Architecture

Kin has one Python harness with several clients. The harness owns model calls, tools, permissions, sessions, and journals. Clients present events and return your input and decisions.

Harness + TUI

The default kin command runs the harness and Textual terminal interface in one process. The interface renders the harness’s typed events; it does not implement a separate permission gate or agent loop.

Other launch forms reuse that harness:

Launch	Process and lifetime
kin	Interactive terminal and harness in one process.
kin -p "task"	One unattended run, with stdout and exit-code contracts.
kin --stdio	One local program hosts an interactive conversation over JSON lines.
kin --serve	A per-user Unix-socket service holds conversations across client windows.
kin --attach	The terminal joins a service conversation as writer or observer.

Local clients use the same trust, journal, and approval machinery. The service accepts same-user local connections; there is no TCP listener. Headless runs can also attach so another client can answer a live human block.

The in-process loop

A model returns text and tool calls. Kin checks each tool’s concrete arguments against the permission policy, executes allowed calls, returns results, and asks the model to continue. This repeats until the turn settles or reaches a limit.

In the terminal, Esc cancels the active worker and starts tool cleanup. Follow-ups enter a bounded FIFO and reach the model at safe boundaries; they do not interrupt tools or start overlapping turns.

The event seam

src/kin/harness/events.py defines the shared event vocabulary: text, reasoning, tool activity, progress, approvals, questions, and lifecycle state. Blocking requests wait for a matching decision. The event reference documents fields; the local-client protocol documents its bounded JSON projection.

How a turn flows

sequenceDiagram
    actor Person
    participant Client
    participant Harness
    participant Model
    participant Tool
    Person->>Client: Submit a request
    Client->>Harness: Start turn
    Harness->>Model: Context and available tools
    Model-->>Harness: Text or tool call
    opt Call needs approval
        Harness-->>Client: Exact approval request
        Client->>Person: Review call
        Person->>Client: Allow or deny
        Client->>Harness: Resolve request
    end
    opt Call allowed
        Harness->>Tool: Execute
        Tool-->>Harness: Result
        Harness->>Model: Continue with result
    end
    Harness-->>Client: Turn settled

Model routes and child agents

Named routes can assign different models to the main conversation, vision, tasks, or specific profiles. Each session receives separate mutable backend state. Capacity permits cover model I/O, so a parent does not hold one while waiting for a child’s tool work.

Vision inspection receives only its question and images, then returns an untrusted observation. A text-only main model can use media references without receiving image bytes on its own wire.

Retry posture — root vs subagent

The root retries transient failures before visible output begins. Children buffer prose and can replace a failed partial attempt before reporting it. Exhausted retries leave an explicit error or retained partial result; they do not prove task completion. See subagents for supervision and sessions for interrupted tool recovery.

Where the deep internals live

Internals links the maintainer maps and decisions. Permissions explains authority; tools describes operations. The environment owns scheduling and any whole-process isolation.