Specification: Agent Runtime

Overview

pi-agent-core is split into a low-level layer (Agent, agentLoop) and a high-level AgentHarness. The low-level layer is transport-agnostic and delegates LLMLarge Language Model. calls to an injectable StreamFn. The harness adds durable session storage, compaction, skills, system prompts, and a rich provider/session hook surface.

Architecture

+---------------------------------------------------+
|                  AgentHarness                     |
|  sessions, compaction, skills, system-prompt,     |
|  provider/session hooks (before_provider_request, |
|  tool_call, session_before_compact, ...)          |
+-------------------------+-------------------------+
                          | owns
                          v
+---------------------------------------------------+
|                    Agent                          |
|  transcript, tools, model/thinking, message       |
|  queues, lifecycle (prompt/continue/abort)        |
+-------------------------+-------------------------+
                          | drives
                          v
+---------------------------------------------------+
|                   agentLoop                       |
|  stream -> extract tools -> execute -> continue   |
+-------------------------+-------------------------+
                          | calls
                          v
                +---------------------+
                |   StreamFn (inject) |  default: pi-ai streamSimple
                +---------------------+  alt: streamProxy (server)

Data Models

AgentState

AgentTool

AgentMessage

A union of pi-ai Message types plus app-injected custom message types via declaration merging. convertToLlm bridges AgentMessage[] to pi-ai Message[] for the stream; transformContext optionally rewrites the AgentMessage[] before conversion.

AgentEvent

API Contracts

Agent.prompt(messages) / Agent.continue()

Request: AgentMessage[] for prompt; none for continue (resumes from current context; last message must be user/toolResult).

Response: an async subscription; results arrive via subscribe() events. Throws if an agent is already running.

StreamFn

Response: an AssistantMessageEventStream. Must never throw; failures are terminal stream events.

Sequences

Agent loop (single turn)

turn_start
  -> transformContext (AgentMessage[])
  -> convertToLlm (-> Message[])
  -> StreamFn(context)
  -> stream deltas -> message_update events
  -> done -> message_end
  -> extract tool calls
  -> beforeToolCall (can block)
  -> execute tools (sequential|parallel) -> tool_execution_* events
  -> afterToolCall (can override/terminate)
  -> append tool results to context
turn_end
  -> drain steering messages? loop
  -> else drain follow-up messages? outer loop
agent_end (after listeners settle)

Failure handling

run executor throws
  -> handleRunFailure: synthesize assistant message (stopReason: aborted|error)
  -> emit message_end, agent_end
  -> finishRun: clear runtime state

Technical Decisions

Risks and Unknowns

1. Overlap between AgentHarness and coding-agent's AgentSession could lead to duplicated session/compaction logic.
2. The declaration-merge extensibility model is powerful but can make type errors hard to localize.
3. Parallel tool execution ordering semantics are subtle; regressions here are hard to detect without targeted tests.

Out of Scope

• LLMLarge Language Model. provider abstraction and streaming protocol (FEAT-0001).
• Terminal rendering (FEAT-0003).
• Interactive TUITerminal User Interface (the interactive mode, and the `pi-tui` library)., slash commands, and the CLICommand-Line Interface (the `pi` binary). product (FEAT-0004).
• Coding-agent-specific session format and branching UI (FEAT-0006).

Vocabulary

Domain Terms

Technical Terms

Acronyms and Abbreviations

Specification: Terminal UI Framework

Overview

pi-tui is an imperative terminal UI framework. Components return arrays of pre-styled strings; the TUITerminal User Interface (the interactive mode, and the `pi-tui` library). manager diffs the new array against the previous frame and emits minimal escape sequences wrapped in synchronized output. There is no virtual DOM; callers mutate components then request a render.

Architecture

+-------------------+   mutate + requestRender
| Application code  |-------------------------+
+-------------------+                         |
        | uses                                 |
        v                                      v
+-------------------+   render(width)   +-------------+
|   Components      |------------------>|    TUITerminal User Interface (the interactive mode, and the `pi-tui` library).      |
| (Editor, Text,    |                   | (manager)   |
|  Markdown, ...)   |                   +------+------+
+-------------------+                          | composites overlays
                                               | diffs vs previousLines
                                               v
                                    +---------------------+
                                    |  differential write |
                                    |  (sync output, ~60fps)|
                                    +----------+----------+
                                               |
                                               v
                                    +---------------------+
                                    | Terminal interface  |
                                    | (ProcessTerminal /  |
                                    |  VirtualTerminal)   |
                                    +---------------------+

Data Models

Component

OverlayOptions

Key

API Contracts

TUITerminal User Interface (the interactive mode, and the `pi-tui` library)..start() / TUITerminal User Interface (the interactive mode, and the `pi-tui` library)..stop()

Begins/ends raw mode, Kitty keyboard negotiation, and the render loop. requestRender() schedules a throttled render; setFocus, showOverlay/hideOverlay manage composition.

Keybindings

matchesKey(keyData, binding) compares parsed keys against configurable bindings. Defaults live in TUI_KEYBINDINGS; consumers override via setKeybindings.

Sequences

Differential render

application -> component.invalidate() / TUITerminal User Interface (the interactive mode, and the `pi-tui` library)..requestRender()
TUITerminal User Interface (the interactive mode, and the `pi-tui` library). (next tick, if >= MIN_RENDER_INTERVAL_MS):
  render each focused component -> lines[]
  composite overlays into lines[]
  extract cursor marker -> compute hardware cursor position
  if first render:       output all lines (no scrollback clear)
  elif full re-render:   clear screen + home + clear scrollback; delete Kitty images
  else (differential):
    find first/last changed line vs previousLines
    move cursor to first changed line; clear to end
    write only changed range
  wrap all output in synchronized output escapes
  handle appended/deleted lines and viewport scroll

Technical Decisions

Risks and Unknowns

1. Differential renderingpi-tui's technique of diffing a new line array against the previous frame and writing minimal escape sequences. correctness depends on accurate change detection; subtle bugs (Kitty image ranges, overlay compositing above viewport) require regression tests.
2. Terminal compatibility variance (Kitty support, synchronized output, color scheme reporting) means fallback paths must be exercised.
3. The overlay focus-restore state machine has many states ("eligible"/"blocked") and is a likely source of regressions.

Out of Scope

• LLMLarge Language Model. streaming and provider abstraction (FEAT-0001).
• Agent loop and tool execution (FEAT-0002).
• The interactive coding agent product built on top of this framework (FEAT-0004).

Vocabulary

Domain Terms

Technical Terms

Acronyms and Abbreviations

Specification: Interactive Coding Agent

Overview

pi-coding-agent composes the three libraries into a CLICommand-Line Interface (the `pi` binary). product. main() parses args, resolves project trust, builds a SessionManager and AgentSessionRuntime, then dispatches to a run mode. The AgentSession is the central class shared by all modes; InteractiveMode renders events via pi-tui.

Architecture

cli.ts -> main() -------------------------------+
  args parse, migrations, trust resolve         |
  createSessionManager, createAgentSessionRuntime|
        |                                       |
        v                                       |
+-------------------+   owns session +          |
| AgentSession      |   cwd-bound services      |
| Runtime           |   (hot-swap on            |
+---------+---------+   fork/switch/tree)       |
          |                                   |
          v                                   |
+-------------------+   delegates to           |
| AgentSession      |----> pi-agent-core Agent |
| (prompt loop,     |----> ModelRegistry (auth)|
|  compaction, bash,|----> pi-ai streamSimple  |
|  tools, export)   |                          |
+---------+---------+                          |
          | events                             |
          v                                   |
   +------+------+------+                     |
   |             |      |                     |
   v             v      v                     |
Interactive   Print   RPCRemote Procedure Call (the JSONL stdin/stdout protocol mode).  <-- modes dispatch-+
Mode (pi-tui) (text/json)

Data Models

Settings (excerpt)

ResourceLoader sources

Tool sets

API Contracts

SDKSoftware Development Kit (the embeddable programmatic API).: createAgentSession()

Factory building an AgentSession wired with a resource loader, model registry, settings, and extension runner. Exposes prompt, subscribe, state, abort, setModel, setThinkingLevel, compact, fork.

CLICommand-Line Interface (the `pi` binary). flags (excerpt)

Sequences

Interactive prompt

user input -> AgentSession.prompt()
  -> slash command? extension command or builtin
  -> emit input event (extensions may transform/intercept)
  -> expand skill/template
  -> streaming? queue steer/follow-up
  -> validate model + auth
  -> check pre-prompt compaction
  -> before_agent_start (extensions modify system prompt / inject messages)
  -> Agent.prompt() -> agentLoop -> streamFn -> pi-ai
  -> stream deltas, execute tools, emit events
  -> _handlePostAgentRun: retry/compact/queued messages loop
  -> append entries to SessionManager JSONL
InteractiveMode renders events incrementally via pi-tui

Run mode dispatch

main() -> resolveAppMode(args)
  interactive -> AgentSessionRuntime + InteractiveMode (TUITerminal User Interface (the interactive mode, and the `pi-tui` library).)
  print       -> runPrintMode (text or json)
  rpc         -> runRpcMode (JSONL stdin/stdout)
  (SDKSoftware Development Kit (the embeddable programmatic API).)       -> createAgentSession() used programmatically

Technical Decisions

Risks and Unknowns

1. InteractiveMode is a very large module (~193KB); changes there are high-churn and hard to review.
2. Project trustA per-folder decision (`~/.pi/agent/trust.json`) gating whether project settings, resources, and extensions execute. is a security-critical path; regressions could execute untrusted code.
3. The package manager and resource discovery span many source locations; collision and precedence rules must stay consistent.

Out of Scope

• ProviderThe runtime unit owning a model catalog, auth, and stream behavior (e.g. `anthropic`, `openai`). abstraction internals (FEAT-0001).
• Agent loop internals (FEAT-0002).
• TUITerminal User Interface (the interactive mode, and the `pi-tui` library). rendering internals (FEAT-0003).
• ExtensionA TypeScript module with a default export `function (pi: ExtensionAPI)` that augments the agent with tools, commands, events, UI, or providers./skills API surface (FEAT-0005).
• SessionA persistent, branchable conversation log stored as JSONL (`SessionHeader`, messages, compaction summaries, branch summaries). format and branching internals (FEAT-0006).

Vocabulary

Domain Terms

Technical Terms

Acronyms and Abbreviations

Specification: ExtensionA TypeScript module with a default export `function (pi: ExtensionAPI)` that augments the agent with tools, commands, events, UI, or providers. and Skills Platform

Overview

Three resource types extend pi: extensions (TypeScript modules), skills (SKILL.md packages), and prompt templates ({{var}} Markdown). DefaultResourceLoader discovers them from global/project/package sources with trust gating; ExtensionRunner dispatches lifecycle and event hooks; skills and templates are injected into the system prompt on demand.

Architecture

DefaultResourceLoader
  discover: global (~/.pi/agent, ~/.agents)
            project (.pi, .agents, AGENTS.mdProject-specific rules file for humans and agents, read automatically from the repo root./CLAUDE.md) -- trust gated
            packages (installed)
        |
        v
+--------------------+   cached, lazy (jiti)
| ExtensionA TypeScript module with a default export `function (pi: ExtensionAPI)` that augments the agent with tools, commands, events, UI, or providers. loader   |----> default export (pi: ExtensionAPI)
+---------+----------+
          |
          v
+--------------------+
| ExtensionRunner    |   lifecycle + event dispatch
| (on/emit hooks)    |   (input, tool_call, tool_result,
+--------------------+    message_*, session_*, provider_*, ...)
        |
        v
   AgentSession / InteractiveMode  (consume hooks, expose UI context)

Skills & Prompt Templates
  loaded on demand (/skill:name, /templatename)
  -> injected into system prompt or expanded into user message

Data Models

ExtensionAPI (excerpt)

Event surface (categories)

SkillAn on-demand capability package following the Agent Skills standard (`SKILL.md` + optional frontmatter), invoked as `/skill:name`.

API Contracts

/skill:name

Injects the skill's SKILL.md body into the system prompt context for the session.

/templatename

Expands {{variable}} placeholders in the Markdown template into a user message.

pi.install(name) / pi.remove(name) / pi.update(name)

Package manager operations over npm or git sources, resolving to resource directories (extensions, skills, prompts, themes, models).

Sequences

Tool call through extension hooks

agent -> tool_call event
  -> beforeToolCall (extension can {block: true})
  -> if not blocked: tool.execute(args)
     -> tool_execution_update events (extensions observe)
  -> afterToolCall (extension can override content/details/isError/terminate)
  -> tool_result event

Resource discovery (trust-gated)

DefaultResourceLoader.discover()
  for each source (global, project, package):
    if project source and not trusted: skip
    collect extensions, skills, prompts, themes, context files
  -> resources_discover event (extensions may augment)
  -> registry populated

Technical Decisions

Risks and Unknowns

1. The ExtensionAPI is large and evolving; breaking changes affect the ecosystem.
2. Event handler ordering and interaction effects across multiple extensions can be hard to predict.
3. Project trustA per-folder decision (`~/.pi/agent/trust.json`) gating whether project settings, resources, and extensions execute. bypass (e.g. via a malicious package source) is a security risk to monitor.

Out of Scope

• The core built-in tools and agent loop (FEAT-0002, FEAT-0004).
• SessionA persistent, branchable conversation log stored as JSONL (`SessionHeader`, messages, compaction summaries, branch summaries). persistence and branching (FEAT-0006).
• LLMLarge Language Model. provider auth internals (FEAT-0001).

Vocabulary

Domain Terms

Technical Terms

Acronyms and Abbreviations

Specification: SessionA persistent, branchable conversation log stored as JSONL (`SessionHeader`, messages, compaction summaries, branch summaries). Persistence and BranchingTree-structured session forking (`/fork`, `/clone`, `/tree`) where each entry has `id`/`parentId`.

Overview

Sessions are JSONL files with a tree-structured entry stream. SessionManager owns append/read/migration; AgentSessionRuntime hot-swaps the active session and its cwd-bound services on fork/switch/tree navigation; compaction runs in AgentSession with hooks for extensions.

Architecture

AgentSession
  prompt loop appends entries ------+
  compaction summarizes             |
  branch summarization              |
        |                           v
        |                  +-------------------+
        +----------------->|   SessionManager  |
                           | JSONL append/read |
                           | tree traversal    |
                           | migration (v1->N) |
                           +---------+---------+
                                     | hot-swap
                                     v
                        +------------------------+
                        | AgentSessionRuntime    |
                        | owns active session +  |
                        | cwd-bound services     |
                        | fork()/switch()/       |
                        | navigate()             |
                        +------------------------+

Data Models

SessionA persistent, branchable conversation log stored as JSONL (`SessionHeader`, messages, compaction summaries, branch summaries). JSONL entry (union, tree-structured)

SessionHeader

CompactionLossy summarization of older session messages to reclaim context; original JSONL is preserved. summary entry

API Contracts

SessionManager.append(entry) / read()

Append appends a JSONL line; read loads and indexes the tree for traversal, listing, and migration.

Runtime: fork() / switch(id) / navigate(direction)

Each tears down the current runtime, emits the corresponding session_before_* event, and recreates services bound to the target session/cwd.

/compact [prompt]

Triggers compaction: emits session_before_compact, summarizes older messages, retains recent ones, appends a compaction summary, emits session_compact.

Sequences

CompactionLossy summarization of older session messages to reclaim context; original JSONL is preserved. flow

threshold exceeded OR /compact
  -> session_before_compact event (extensions may modify/inject)
  -> findCutPoint (token estimation)
  -> summarize messages before cut
  -> keep recent messages
  -> append compaction summary entry to JSONL
  -> post-token estimate
  -> session_compact event (with reason, willRetry)
  -> if willRetry: agent.continue()

BranchingTree-structured session forking (`/fork`, `/clone`, `/tree`) where each entry has `id`/`parentId`. flow

/fork <message-id>
  -> session_before_fork event
  -> create new session file from entries up to message-id
  -> runtime.switch() to new session
  -> session_fork event
(original session file unchanged)

Technical Decisions

Risks and Unknowns

1. Large session files (multi-MB) affect resume and read performance; pruning policy is undefined.
2. Migration logic must handle every prior version; a missed step corrupts old sessions.
3. CompactionLossy summarization of older session messages to reclaim context; original JSONL is preserved. quality (what gets summarized) directly affects agent performance and is hard to evaluate automatically.

Out of Scope

• The interactive TUITerminal User Interface (the interactive mode, and the `pi-tui` library). rendering of sessions (FEAT-0004).
• The agent loop and tool execution (FEAT-0002).
• ExtensionA TypeScript module with a default export `function (pi: ExtensionAPI)` that augments the agent with tools, commands, events, UI, or providers. API internals beyond session hooks (FEAT-0005).

Vocabulary

Domain Terms

Technical Terms

Acronyms and Abbreviations