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).

Test Plan: Agent Runtime

Scope

Covers pi-agent-core agent loop, tool execution, message queues, abort, events, and the AgentHarness layer including compaction, skills, sessions, and system prompts.

Unit Tests

Test files under packages/agent/test/ cover: - Agent loop and state machine (agent.test.ts, agent-loop.test.ts) - Abort and cancellation flow - Tool execution (sequential/parallel) - Message queue steering and follow-up - AgentHarness session lifecycle (harness/session.test.ts, harness/agent-harness.test.ts, harness/agent-harness-stream.test.ts) - CompactionLossy summarization of older session messages to reclaim context; original JSONL is preserved. (harness/compaction.test.ts) - Skills loading and injection (harness/skills.test.ts) - Prompt templates (harness/prompt-templates.test.ts) - System prompt building (harness/system-prompt.test.ts) - Resource formatting (harness/resource-formatting.test.ts) - Node execution environment (harness/nodejs-env.test.ts) - Storage layer (harness/storage.test.ts) - SessionA persistent, branchable conversation log stored as JSONL (`SessionHeader`, messages, compaction summaries, branch summaries). UUID generation (harness/session-uuid.test.ts) - Truncation utilities (harness/truncate.test.ts) - Repo-level logic (harness/repo.test.ts)

Test Infrastructure

• Injectable StreamFn with controlled behavior (mock stream event sequences)
• In-memory session storage for deterministic testing
• NodeExecutionEnv for filesystem and shell tool testing

Coverage Matrix

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).

Test Plan: Terminal UI Framework

Scope

Covers pi-tui rendering pipeline, components, key handling, terminal abstraction, overlays, and differential rendering.

Unit Tests

Test files under packages/tui/test/ cover: - Differential render engine (tui-render.test.ts, tui-shrink.test.ts, tui-cell-size-input.test.ts, tui-overlay-style-leak.test.ts) - Editor component (editor.test.ts) - Input handling (input.test.ts, keys.test.ts) - Keybindings (keybindings.test.ts) - Markdown rendering (markdown.test.ts) - SelectList component (select-list.test.ts, truncated-text.test.ts) - Overlay system (overlay-options.test.ts, overlay-short-content.test.ts, overlay-non-capturing.test.ts) - Autocomplete (autocomplete.test.ts) - Fuzzy matching (fuzzy.test.ts) - Terminal abstraction (terminal.test.ts, terminal-colors.test.ts, terminal-image.test.ts) - String utilities (truncate-to-width.test.ts, wrap-ansi.test.ts, tab-width.test.ts, word-navigation.test.ts) - Stdin buffer (stdin-buffer.test.ts) - Regression tests (regression-overlay-cjk-boundary.test.ts, regression-regional-indicator-width.test.ts, bug-regression-isimageline-startswith-bug.test.ts)

Integration Tests

Terminal tests run against VirtualTerminal for deterministic render assertions without a real terminal.

Edge Cases and Failure Scenarios

• CJKChinese, Japanese, Korean (terminal width handling for wide characters). character boundary in overlays
• Regional indicator (flag) width
• Tab width handling
• Image protocol capability detection fallback
• Non-capturing overlay focus management
• Short overlay content positioning

Test Infrastructure

• VirtualTerminal for headless render assertions
• Mock terminal color scheme (OSC 11)
• Kitty keyboard protocolTerminal input protocol pi-tui negotiates for richer key reporting. negotiation simulation

Coverage Matrix

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).

Test Plan: Interactive Coding Agent

Scope

Covers the pi-coding-agent CLICommand-Line Interface (the `pi` binary). product: AgentSession, tools, modes (interactive, print, JSON, RPCRemote Procedure Call (the JSONL stdin/stdout protocol mode).), settings, resource loading, project trust, and the SDKSoftware Development Kit (the embeddable programmatic API)..

Unit Tests

Test files under packages/coding-agent/test/ cover: - AgentSession core (agent-session-.test.ts files for retry, concurrent, stats, dynamic-provider, dynamic-tools, runtime-events, auto-compaction-queue) - Bash execution (bash-close-hang-windows.test.ts, bash-execution-width.test.ts) - Built-in tools (tools.test.ts, edit-tool-legacy-input.test.ts, edit-tool-no-full-redraw.test.ts) - CLICommand-Line Interface (the `pi` binary). args (args.test.ts) - Config/settings (config.test.ts, settings-manager.test.ts, settings-manager-bug.test.ts, config-value-migration.test.ts) - Resource loader (resource-loader.test.ts) - System prompt building (system-prompt.test.ts) - Run modes (print-mode.test.ts, rpc.test.ts, rpc-jsonl.test.ts, rpc-client-clone.test.ts, rpc-client-process-exit.test.ts, rpc-prompt-response-semantics.test.ts) - SDKSoftware Development Kit (the embeddable programmatic API). (sdk-session-manager.test.ts, sdk-skills.test.ts, sdk-stream-options.test.ts, sdk-openrouter-attribution.test.ts) - Trust manager (trust-manager.test.ts, trust-selector.test.ts) - Theme handling (theme-detection.test.ts, theme-export.test.ts, theme-picker.test.ts, export-html-xss.test.ts) - Interactive mode (interactive-mode-anthropic-warning.test.ts, interactive-mode-clone-command.test.ts, interactive-mode-compaction.test.ts, interactive-mode-import-command.test.ts, interactive-mode-startup-input.test.ts, interactive-mode-status.test.ts, interactive-mode-suspend.test.ts) - Image processing (image-process.test.ts, image-processing.test.ts, image-resize-callers.test.ts) - Clipboard handling (clipboard.test.ts, clipboard-native.test.ts, clipboard-image.test.ts, clipboard-image-bmp-conversion.test.ts) - Version check (version-check.test.ts, pi-user-agent.test.ts) - Suite tests (suite/agent-session-.test.ts) using the harness + faux provider

Integration Tests

• Suite tests under test/suite/ use the coding-agent test harness with a faux provider for full prompt-loop testing without real API calls
• Issue regression tests under test/suite/regressions/ cover specific bugs and edge cases

Test Infrastructure

• HarnessThe coding agent runtime that wires the agent loop, tools, sessions, and UI together. (test/suite/harness.ts) provides a managed AgentSession + faux provider
• In-memory session manager for deterministic testing
• Controlled bash process lifecycle

Coverage Matrix

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).

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

Scope

Covers extension loading, hook dispatch, skills, prompt templates, package manager, and the ExtensionAPI surface.

Unit Tests

Test files under packages/coding-agent/test/ cover: - ExtensionA TypeScript module with a default export `function (pi: ExtensionAPI)` that augments the agent with tools, commands, events, UI, or providers. runner (extensions-runner.test.ts, compaction-extensions.test.ts, compaction-extensions-example.test.ts) - ExtensionA TypeScript module with a default export `function (pi: ExtensionAPI)` that augments the agent with tools, commands, events, UI, or providers. discovery (extensions-discovery.test.ts) - ExtensionA TypeScript module with a default export `function (pi: ExtensionAPI)` that augments the agent with tools, commands, events, UI, or providers. input events (extensions-input-event.test.ts) - Skills (skills.test.ts, sdk-skills.test.ts) - Prompt templates (prompt-templates.test.ts) - Package manager (package-manager.test.ts, package-manager-ssh.test.ts, package-command-paths.test.ts) - Git integration (git-update.test.ts, git-ssh-url.test.ts, git-merge-and-resolve-extension.test.ts) - Plan mode extension (plan-mode-extension.test.ts, plan-mode-utils.test.ts) - Trigger compact extension (trigger-compact-extension.test.ts) - Suite regressions (extension-factory-cache.test.ts, 6162-extension-active-tools-next-turn.test.ts, 6260-inline-extension-naming.test.ts, 5433-extension-oauth-prompt-input.test.ts, 2835-tools-allowlist-filters-extension-tools.test.ts, 5080-signal-shutdown-extension-cleanup.test.ts)

Test Infrastructure

• In-memory extension module loading with mock default exports
• Fake ExtensionAPI and ExtensionUIContext for dispatch testing
• Test extension files in examples/extensions/

Coverage Matrix

Vocabulary

Domain Terms