Schemas & contracts

lib/agent.js

• get parent() — The creating Agent, or undefined when none was supplied.
• get children() — Snapshot of directly owned workers.
• childCreate(options = {…}) — Construct one direct child through the environment factory.
• get name() — Human-friendly Agent name.
• get description() — Human-friendly Agent description; an empty string is valid.
• can — Live agent-owned capability map.

lib/env/extend.js

Env plugins: how a higher layer installs its Env members (Env.extend)

lib/env/extend.js — Env plugins (private to Env; published as Env.extend). A higher layer (IO, Agent) installs the Env members it owns AFTER the fact, so Env never knows those layers' APIs: - methods and getters land on Env.prototype; - events add Symbol-valued keys to Env.EVENT, and only the installing plugin can emit them (the returned emit). Env events report MEMBERSHIP (what exists); an object's activity is its own events, never an Env copy; - settings add the keys the layer owns to the defaults schema (env.settingsSchema(), init templates, API docs); - modelInfo(env, info, settings) contributes fields to every catalog entry (env.models(); settings = the endpoint's settings; Agent adds maxActive/active/available). Installing a name that already exists throws — a plugin extends Env, never overrides it.

A plugin keeps per-env state under its own Symbol key on the env.

lib/agent/env-plugin.js

Agent's Env plugin: the active-Agent registry, agentCreate, capacity, AGENT_* events

lib/agent/env-plugin.js — Agent's Env plugin (private to Agent).

Env knows nothing about Agents: this plugin installs every Env member that concerns them (Env.extend) when lib/agent.js loads — - the ACTIVE-AGENT registry: agents(), _agentAdd(), _agentRemove(); - the private _toolContextCreate(name, context) handshake for manual Env.toolCall dispatches carrying an Agent; - the factory agentCreate(options) (an Agent over the env it is called on — the safe view yields a safe Agent); - active-Agent capacity: the modelInfo catalog hook adds maxActive / active / available to every env.models() pair (the maxActive settings; a limit changes as a settings write: env.settings.providers[endpoint].models[model].maxActive = n); - the MEMBERSHIP events AGENT_ADDED/AGENT_REMOVED ({agent}) — Env reports which agents exist; what an agent does is its own Agent.onEvent vocabulary (subscribe on AGENT_ADDED); - the schema entries of the settings Agent owns: context and retry (the policy each Agent resolves once — lib/agent/policy.js) and maxActive; - systemPrompt(): the seeded system-prompt texts. Registry state lives under a private Symbol key on the Env (shared by its safe view).

lib/agent/hooks.js

Trusted Agent event hooks: scan roots, lifecycle and observer diagnostics

lib/agent/hooks.js — trusted extension observers of existing Agent events.

Scan only hooks/.js in the package root, installed extension roots, and the user settings folder (in that order, no project layer or extra path setting). Each module exports hooks(env) returning an object whose keys are Symbol Agent.EVENT values and whose values are (payload, agent) => . Example: export const hooks = (env) => ({ [Agent.EVENT.MESSAGE_COMMITTED]: (message, agent) => { / observe message; do not alter the turn \/ } }); Import Agent from lib/agent.js to use the documented Symbol constants. Hooks run in a microtask and are never awaited by a turn. Failures (sync or async) reach the Agent.LOG diagnostic stream once per file/event; they cannot propagate back into the turn. Refresh replaces existing listeners and reimports files with the tool refresh revision. Missing folders do nothing.

lib/env.js

• onEvent(event, callback) — Subscribe to an Env Symbol event.
• offEvent(handle) — Remove the listener registered with {@link onEvent}.
• static EVENT — The Env event vocabulary: Symbol constants for onEvent/offEvent.
• static extend(plugin) — Install a higher layer's Env members after the fact (a plugin): `methods`/`getters` land on Env.prototype and run on the env they were reached through (the safe view included); `events` add Symbol keys to Env.EVENT; `settings` add the layer's settings keys to the defaults schema.
• static get envs() — The registered project Envs by project folder — at most one per canonical folder.
• static open(path, options) — Acquire a fully initialized Env for a project folder.
• get closed() — whether close() has run (the Env left Env.envs).
• get name() — The project name.

lib/agent/policy.js

lib/agent/policy.js — the Agent POLICY (private to Agent): the settings an Agent runs by, resolved when the Agent is built and again only when it selects another model (agent.policy) — a settings edit applies to the next Agent or model selection, never mid-run.

context keys resolve down a TREE, each level overriding the one above per key: the global settings.context, then the endpoint's <endpoint>.context, then the model's <endpoint>.models.<model>.context.

settings.context context policy: cap, turn and autocompact use fractions of the known model window (> 1 means percentage); autocompactMax is an absolute token count: cap the overall ceiling (default 0.9 — always leaves room for /compact); crossing it ends the turn turn the growth ceiling for ONE turn alone (default 0.4) autocompact compact before the next request at 0.4 (40%) by default; false/0/1 disable, true = 0.4 autocompactMax absolute token threshold, default 200,000; 0 disables the absolute threshold; the first threshold reached triggers compaction (lib/agent/compact.js) settings.retry failed provider requests: attempts attempts per turn, the first write included (default 3) base the first retry's delay (default 2s); each next retry waits twice as long max the delay ceiling (default 30s) settings.tools tool dispatch (core schema; folders is Env's): timeout the default per-call timeout (default 120s) timeoutLimit the cap on any call's timeout (default 20m) concurrency the read-only batch size (default 3)

Durations accept milliseconds or unit strings ("30s", "5m").

lib/agent/run.js

lib/agent/tool-timeout-settings.js

lib/agent/tool-timeout-settings.js — Agent's tool-timeout constants (private): the defaults behind settings.tools.timeout/timeoutLimit (resolved per Agent in lib/agent/policy.js) and the onTimeout grace.

The Agent owns enforcement. Tools may DECLARE timeout, but the Agent extracts it before invocation; tools never race a second timer against the harness. A tool's optional Agent-facing onTimeout callback gets one bounded cleanup/final-response grace period.

lib/agent/tool-timeout.js

Agent-owned deadlines and cancellation for each dispatch. Tool-declared timeout is extracted before invocation. onTimeout is a bounded final-result hook, not a process-cleanup policy; dispatch always tears down its sandbox.

lib/context/types.js

lib/context/types.js — context/message/content types (concrete JSDoc).

Own schema, no external dependency. A context is an ordered array of messages. Every message has a numeric type and a content array; all other fields are optional metadata, tolerated by readers (unknown fields never invalidate a value).

Addressing is array/block based — messages have no local ids: message = context[i]; block = context[i].content[j] Provider response/cache/block identifiers may ride as optional metadata and are dropped by Context when an edit makes them stale.

lib/agent.js

the headless core entry point: callbacks replace stdio/process.exit/terminal APIs

lib/agent.js — Agent: owns context, provider/model selection, the tool loop, and persistence. Headless: no stdio, no process.exit, no TUI.

PUBLIC CORE ENTRY POINT. Agent coordinates the JSONL session store, crash-safe finish hooks, the forked tool sandbox, the tool loop, tool-call execution, status readouts, and thinking level. One Agent owns one conversation for its lifetime; create another Agent to start or resume a conversation, or use Agent.fork to branch one. App owns view replacement. It composes Context ← Env ← IO ← Agent and publishes that core tree as Agent.Context, Agent.Env, and Agent.IO. It does not import CLI, Markdown, or application/UI layers.

Ownership: - Agent alone owns the ordered in-memory context, provider/model selection per request, the tool loop, and persistence. - IO receives the COMPLETE current context on every request; one IO instance is reused per qualified model and reconstructed after close() leaves it permanently closed. It reports usage PER TURN (the terminal event's usage envelope, see lib/context/usage.js) — nothing above it. - The CONTEXT is a Context object (lib/context.js): Agent names it from a session id (--session/--resume), or adopts a ready one unchanged; its identity never changes. Context owns edits and persistence to env.settings.sessions when saving is on. - Agent alone owns the CUMULATIVE usage total (the usage getter): it sums every terminal's canonical counters in memory as run() sees them. Never persisted (no usage.json) — a fresh Agent starts at zero; bindings that show it (the TUI footer, a one-shot CLI's final line) read it fresh rather than tracking their own copy.

Agent's implementation is split across helper modules in lib/agent/; this file provides the public façade: - run.js the tool loop and its runaway guards; - tool-exec.js tool-call eventDispatch/execution, the result contract; - readouts.js cumulative usage/context-window/connection readouts; - context-lifecycle.js constructor session settings and seeded system prompt; - thinking.js the thinking level.

Model identity is one qualified <endpoint>/<model> string throughout construction, property assignment, child creation and context persistence. Assigning model validates and records a whole state change. run() has no model override. Split endpoint options are rejected; presentation layers derive display fields.

Core rules (see run.js/tool-exec.js for the full contracts): every tool call in the LIVE response executes — identical repeats included; calls execute ONLY in real time, never from history. Tool-call ids belong to AGENT, never to the model (generated when missing, regenerated on collision). Tool-execution lifecycle is observable: TOOL_EXECUTE fires just before a call runs and TOOL_RESULT after each result is appended.

Tool-call SANDBOX (options.toolCall): file-scanned tools execute in a FORKED child process by default (fork: true); built-ins, programmatic tools, and INTERACTIVE tools stay in-process. Options: - fork: false disables the sandbox (in-process execution) - timeout: explicit HOST override of settings.tools.timeout (duration) Read-only (tool schema safe:true) calls overlap in contiguous groups; mutations run in order. Every call is Agent-timed (including in-process). A schema-declared timeout argument is extracted and capped at settings.tools.timeoutLimit; schema.onTimeout gets at most 60s for cleanup or a final result.

WRITE CAPABILITY (options.can.write; assign agent.can.write at runtime): always publish the full available catalog, but execute ONLY read-only tools (schemas with safe: true) while write is denied. Agent passes the effective tool-context safe to Env.toolCall. A child inherits its parent's write restriction. Write denial is FORCED when no supported OS sandbox is available — there is NO opt-out: mutation tools run only under an active OS sandbox, so on a mechanism-less platform the agent is read-only.

SYSTEM PAYLOADS: a tool returning { result, system } answers briefly via its tool result while system (string or string[]) appends as System messages after the complete tool-call batch and any queued user input. DISPLAY PAYLOADS: { result, display } — display rides the outcome to TOOL_RESULT subscribers and is shown to the user WITHOUT ever joining the context: a tool can display data without sending it to the model (the edit tool's git-style diff).

bin/scripts/agent

the reference consumer: a one-shot stdin-to-stdout tool loop, as a CLI

agent — headless tool-loop CLI (thin binding over lib/agent.js).

Usage: <prefix>-agent [--model <endpoint>/<model>] [--url <url>] [--token <key>] [--timeout <dur>] [--tools <list>] [--session <id> | --resume <id>] [--login] [--logout <endpoint>] [--help]

Contract: - Reads stdin to EOF (shared grammar: whole JSON context first, otherwise JSON-per-line with non-JSON lines as user messages). - Runs the Agent tool loop: provider request → tool calls executed in-process → results appended → next request, until done/error. - stdout: normalized response events, one JSON object per line (every request's events stream in order; the last done carries the final assembled message). stderr: diagnostics only. - --session <id> persists the context to a JSONL session log; --resume <id> replays it first. Session wiring lives in Agent. - SIGINT/SIGTERM cancels the in-flight request: the terminal partial is persisted, exit 130.

Exit codes: 0 success · 1 usage/other · 2 auth · 3 network · 4 provider error · 5 malformed input · 130 cancelled

lib/jobs.js

Portable, folder-only project Jobs. ai-jobs enables, ai-jobs-disabled disables. Operations are best effort: there are no locks, daemon identity records, or cross-process coordination. Concurrent scans/mutations may duplicate work, lose updates, or race archives. Atomic single-file replacement remains used.

PUBLIC MODULE (owner of lib/jobs/). The façade publishes the operations a host or tool needs; task parsing, occurrence state, attempts, and archives stay private to lib/jobs/.

lib/jobs/tasks.js

Pure Markdown/frontmatter parsing with wholesale fallback and task-local rejection.

lib/jobs/operations.js

lib/jobs/dispatcher.js

lib/jobs/agent-execution.js

In-process job Agent execution: one fresh, headless Agent per task against a wake-shared Env. An explicit cancel interrupts it; Jobs has no whole-job deadline and a wake never force-kills a running job.

bin/scripts/jobs

Thin operator CLI: maps argv to the Jobs façade and prints short notes. Problems are logged by the library in ai-jobs/errors/, not printed here.

lib/env/models.js

lib/env/models.js — the published MODEL CATALOG (private to Env): env.models(secret) — a Map keyed endpoint/model whose ModelInfo values hold everything already computed from current state — and env.connection(selector), IO's handle on one pair.

ModelInfo = { endpoint, model, label, listed, secret, disabled, loginRequired, lastUsed, projectLastUsed, caps: { contextWindow, thinking, tools, streaming, input? }, ...plugin fields (Agent: maxActive, active, available) } - listed: the endpoint's catalog publishes the model; an endpoint with no catalog yet (collection pending) still answers its last-used pairs, unlisted; - secret: the endpoint's filter / secret: true, the model's own secret hides it (models() omits it; models(true) includes it, flagged); - disabled: the endpoint's disabled: true (a user switch, e.g. a depleted token budget): models() omits the pair, models(true) includes it flagged, and connection() refuses it; - lastUsed: the global last-model memory's ISO timestamp (or null); projectLastUsed: the pinned project's own timestamp (or null); - caps.thinking: the model entry's native modes, else the provider's; - caps.tools: the provider's built-in tools minus settings opt-outs, first explicit boolean wins: <ep>.models.<m>.tools.<name>, then <ep>.tools.<name>, then providers.tools.<name>. Plugins add fields through Env.extend({modelInfo(env, info)}).

The catalog is collected in the BACKGROUND (collect(): context-window registry, live model lists, bounded retries); every change emits Env.EVENT.MODELS_CHANGED (coalesced per tick) and consumers re-read.

lib/env.js

• models(secret = false) — The model catalog: every known endpoint/model pair with its state already computed (lib/env/models.js ModelInfo — caps, secret, loginRequired, lastUsed, plugin capacity fields).
• connection(selector, { remember = true } = {…}) — IO's handle on one pair: {endpoint, model, Protocol, url, settings, authSet(data), authReload(current)} (lib/env/models.js).

settings.json

{
  "providers": {
    "test": {
      "provider": "test",
      "url": "test://script",
      "secret": true
    }
  }
}

lib/env/provider.js

CATALOG side — Env completes the statics

lib/env/provider.js — static-side provider completion (private to Env). A provider plugin default-exports one class and imports only lib/context.js. Env registers it with its CATALOG side completed:

static provider — {label, capabilities: {streaming, thinking, tools}} normalized: thinking = native modes (least -> max, [] = none); tools = false | true | map of built-in tools {name: {description?, schema?, function}} static detectEnvironment(...) — optional process-environment-only discovery; Env runs this once per registered protocol per Env. static detect(...) — live endpoint auto-detection (default: nothing); continues each pass for probes and custom detectors. static detectEnvironmentOnly — true when detect merely delegates to detectEnvironment, avoiding a duplicate scan. static models(...) — the endpoint's model map (default: OpenAI- compatible /models, lib/env/openai-models.js) static testConnection — strict login verification (default: same) static login(input) — credentials -> auth record (default: api key)

The instance (wire) side is IO's concern (lib/io/provider.js).

static methods completed when the class lacks them: detect models testConnection login

lib/io/provider.js

WIRE side — IO completes the instance

lib/io/provider.js — instance-side provider completion (private to IO). A provider class Env registered carries its static catalog side; IO completes the wire side before constructing a connection:

- missing context2msg / msg2events / read / close / reportPlanUsage come from the OpenAI Responses defaults (lib/io/openai.js); - send(msg, base): a provider's own send receives base, the plain HTTP transport, to wrap (missing: the OpenAI default send); - classifyError(err, base) / depletionError(classified, base): base is the shared verdict a provider may refine.

One completed class per provider class (cached).

lib/io/provider-error.js

Errors — providers throw plain errors with `kind` or `status`

lib/io/provider-error.js — the stable provider failure taxonomy (private to IO): auth / network / provider / malformed. Providers throw plain errors carrying kind or status; IO classifies them here, and a provider's own classifyError(err, base) may refine the default verdict.

lib/io/thinking.js

Thinking — native modes; IO maps library levels

lib/io/thinking.js — the library thinking vocabulary and its mapping to a model's NATIVE modes (private to IO).

The harness speaks one vocabulary (THINKING_LEVELS). A provider publishes its native modes (capabilities.thinking, least -> max, an off mode such as none first when it has one); a model entry may narrow them (thinking: [...], [] = no thinking control); a model entry or the provider's capabilities may name a default (thinkingDefault). IO maps the think setting to one native mode before a provider reads it, so providers never translate.

providers/ollama.js reference implementation

providers/ollama.js — Ollama connector: the reference implementation of the provider contract (metadata, models(), login(), the context2msg()/msg2events() translators, and endpoint detection), canonical for other provider plugins to follow.

Direct HTTP to the Ollama local server (never the ollama CLI): POST {url}/api/chat — NDJSON streaming chat GET {url}/api/tags — local model listing

Uses the default HTTP backend wholesale (connect/send/read/close) — Ollama's NDJSON stream is line-delimited JSON, which the default blocking-await read already speaks. Only the two translators plus the pi-pattern metadata surface live here.

Wire mapping (context format -> /api/chat): system/user -> {role, content} (text blocks joined) assistant -> {role:"assistant", content, tool_calls?} — thinking blocks are local-only and never hit the wire tool result -> {role:"tool", name, content} — name resolved from the message's name, else the matching toolCall block image and generic binary blocks ride Ollama's sole documented images channel (base64) on user messages; tool-result attachments follow all tool messages in a labeled user message. Ollama exposes no generic-file field in /api/chat. Tools: Env catalog entries -> {type:"function", function:{name, description, parameters}}; omitted when the catalog is empty.

Wire mapping (/api/chat NDJSON -> response events): content strings stream as text_start/text_delta/text_end at contentIndex 0; tool_calls become tool_call_start/tool_call_end pairs (Ollama supplies no call ids — local ollama-N ids are generated for context linkage); the done:true frame maps prompt_eval_count/eval_count into the usage envelope. Native frames ride along as event metadata where useful.

Errors: HTTP statuses and stream-level {error} frames surface through IO's auth/network/provider/malformed taxonomy; login() is a trivial no-auth procedure; models() refreshes the cached list in the provider namespace on every access and falls back to the cache offline.

lib/agent/reliability.js

lib/agent/reliability.js — which failed provider requests an Agent retries (private to Agent). Only failure classes that can plausibly succeed on a later attempt retry (RETRYABLE_KINDS): transport failures and provider-side statuses — a depleted token budget surfaces as one of those and its refill IS time. A malformed context never heals by waiting; a cancellation is the user's own word. How often and how long is the Agent's policy (lib/agent/policy.js, settings.retry).

lib/io/provider-error.js

lib/env/settings.js

lib/env/settings.js — plain-object predicate and JSON source discovery shared by Env's source graph and trusted extension selection. The graph owns precedence and merge semantics; arrays replace rather than concatenate. Theme files are scanned only when requested from a trusted themes/ folder.

GUIDE.md

lib/env/settings-store.js

SettingsStore — a project-agnostic settings aggregator (public as Env.SettingsStore).

A store is a flat, ordered list of nodes. Reads merge objects by key, with later nodes overriding earlier nodes; arrays and scalars replace lower values. A node holds data from one file or memory, mounted at a key path (at). A parent store is the lowest layer: reads merge over it and writes no local node takes fall through to it.

Reads return the current state immediately, even while files are loading. Writes scan nodes from last to first: the first writable node that owns the exact key or accepts it as a catch-all takes the write and marks changed file nodes dirty. Construction and attach may stat a path to identify a directory, but do not load file content; poll loads it. Loading, saving and change notices are asynchronous, grouped per round:

loaded — a poll round finished reading every changed file saved — a storage round finished writing every dirty file updated — settings data changed (after a storage or poll round)

import { Env } from "./lib/env.js";
const store = new Env.SettingsStore({ sources: [
  { source: "./config.json", catchAll: true },
  { at: ["session"], catchAll: true, data: {} },
] });
await store.poll();
store.write(["theme"], "dark");
store.write(["session", "active"], true); // memory only
await store.save();
await store.close();

import { Env } from "./lib/env.js";
const store = new Env.SettingsStore();
store.read(["missing"]); // undefined
store.write(["missing"], 1); // false: no writable owner or catch-all
try { store.write([], 1); } catch (error) {
  console.log(error instanceof TypeError); // true: root writes are unsupported
}
await store.close();

import { Env } from "./lib/env.js";
const shared = new Env.SettingsStore({ sources: [{ catchAll: true, data: {} }] });
const project = new Env.SettingsStore({ parent: shared,
  sources: [{ at: ["project"], catchAll: true, data: {} }] });
project.write(["shared"], 1); // falls through to shared
project.write(["project", "name"], "demo"); // local only
await project.save(); // also saves shared by default
await project.close(); // shared remains open
await shared.close();

lib/env.js

• skills() — Effective skills, read fresh from package/settings/configured/environment/ project layers.

tools/skill.js

tools/resource.js

lib/env/tools.js

PUBLISHES — the module shape a tool file must export

lib/env/tools.js — tool-folder scanning (private to Env).

The scan is NOT recursive: only a root's TOP-LEVEL .js files are tool modules. Sub-folders are private to the tools — a well-designed tool is a thin wrapper (tools/read.js) whose helpers/libraries live beside it (tools/read/engine.js, tools/read/query.js, ...) and are never imported or published by the scan.

Module contract: a module's toolDescription(env) — or describe(env) when toolDescription is undefined (the fallback name) — returns an object keyed by exported function name, each value an MCP-like {description, inputSchema} (plus optional harness metadata: safe/trusted/ sandbox/onTimeout/secret/fn — never published). onTimeout is an Agent-facing callback, not a model-facing schema member. secret: true hides the tool from the PUBLISHED catalog (never sent to the model) while it stays callable directly (bin/scripts/tool, the TUI's /<tool> and Tools menu). A described function is normally published only when the module exports a callable of that name; an entry may instead carry its own fn (a closure built at scan time) for names that have no static export. The scan-time env argument lets a module read live settings to decide which such entries to contribute; it is REBUILT on every refresh, so settings edits take effect on the next tool-refresh. Modules without any of the three functions are omitted from the catalog (their import side effects still run). Duplicate names are diagnosed (throw), never resolved arbitrarily.

Every scan imports modules with a cache-busting ?v=<revision> (bumped on every refresh), so wrappers re-run and re-import their helpers (stamped with Env.toolRevision()). Bun IGNORES query strings on file:// URL imports — plain absolute paths only.

A module may also export settingsSchema() (zero-arg, sync, same scan cadence as toolDescription): { [settingKey]: {default, description} }, merged into the DEFAULTS SCHEMA (see lib/env/settings-schema.js, env.settingsSchema()) — a tool's own self-documentation for the setting(s) it reads (tools/read.js contributes read this way). Purely discovery metadata: an unknown settings key is never rejected either way.

lib/env/tool-registry.js

PUBLISHES — registration and the catalog (Env.tools(safe, selector) -> ToolInfo; provider tools shadow)

tools/read.js

PUBLISHES — a worked example: the minimal wrapper shape (read-only, no ctx)

/**
 * tools/read.js — the `read` tool: a cwd-rooted file access tool,
 * read-only unless `target` saves the result. Thin WRAPPER publishing the callable
 * implemented under tools/read/. The tool scan is NOT recursive:
 * sub-folders are never scanned. read/ owns query normalization,
 * guarded execution and serialization; `target` saves through write/save.js.
 * Shared contracts stay explicit. No helper is independently published as a tool.
 *
 * One exception BY DESIGN: tools/guard/ is the shared guard layer
 * EVERY tool imports (read, write, edit, bash) — the deterministic
 * path resolver (guard/resolve.js) and the fast-path content
 * trip-wire (guard/paths.js); path traversal policy is global,
 * never per-tool (see those files).
 *
 * Helper imports are stamped with the shared refresh revision
 * (toolRevision() — lib/tool-runtime.js, the tiny dependency-free
 * runtime the tool scan publishes it through): every refreshTools()
 * bumps it, the wrapper re-runs, and the helpers re-import fresh —
 * editing any read/* module applies on refresh without touching this
 * wrapper.
 */

import { toolRevision } from "../lib/tool-runtime.js"; // the tool-runtime leaf: one instance across cache-busted imports — no whole-library load for a timestamp

const timestamp = toolRevision(); // shared tool-registry revision
const { read, readDescription, readSettingsSchema } = await import(`./read/read.js?now=${timestamp}`);

export { read };

export function toolDescription() {
  return { read: readDescription() };
}

/** This tool's own contribution to env.settingsSchema(). */
export function settingsSchema() {
  return readSettingsSchema();
}

tools/write.js

PUBLISHES — a worked example: sandboxed (`sandbox: true`, forked, write-jailed)

/** Mutating text writer. Saving read results lives in read.target; both share tools/write/save.js. */
import { toolRevision } from "../lib/tool-runtime.js";
const { saveTarget, savePayload } = await import(`./write/save.js?revision=${toolRevision()}`);

/** Atomically create or overwrite a text file; the destination changes only after guarded checks pass. */
export async function write(args = {}, context) {
  if (context?.safe === true) throw new Error("write is unavailable in safe mode");
  if (!args || typeof args !== "object" || Array.isArray(args)) throw new TypeError("write arguments must be an object");
  for (const key of Object.keys(args)) if (!["path", "content", "ask"].includes(key)) throw new Error(`Unknown write field: ${key}`);
  if (typeof args.content !== "string") throw new TypeError("write.content must be a string");
  if (![undefined, null, "", 0, -1].includes(args.ask) && typeof args.ask !== "boolean") throw new TypeError("write.ask must be a boolean");
  const target = await saveTarget(args.path, context);
  return savePayload(target, { payload: Buffer.from(args.content) }, context, { ask: args.ask === true });
}

export function toolDescription() {
  return { write: { trusted: true,
    description: "Create or overwrite a text file in the Agent folder. Use edit for targeted changes; use read with target to copy files or save read results.",
    inputSchema: { type: "object", additionalProperties: false, required: ["path", "content"], properties: {
      path: { type: "string", description: "Destination path inside the Agent folder, relative to it or an absolute contained path." },
      content: { type: "string", description: "Full file text; an empty string creates or clears the file." },
      ask: { type: "boolean", description: "Ask permission if the text references an existing outside path or an existing absolute project path; without permission, the write is refused." },
    } },
  } };
}

tools/process.js

PUBLISHES — Agent-owned background commands: bash(background) and process-list/output/stop

lib/agent.js

PUBLISHES — Agent's current filtered model-facing descriptors

• get tools() — Current model-facing tools: `const tools = await agent.tools`; `tools.get(name)` returns a provider-neutral descriptor with its schema.

lib/agent/tool-context.js

REQUIRES — internal dispatch constructs every in-process call's (args, ctx); tools receive capabilities, hosts do not construct them

lib/agent/tool-exec.js

REQUIRES — dispatch: which tools fork (sandboxed worker, REDUCED ctx) vs stay in-process (full ctx)

tools/question.js

REQUIRES — a worked example: an interactive tool (`interactive: true`) using ctx.question.ask

tools/question.js — the question tool: ask the user one or more structured questions mid-task (pi question-tool semantics): 1–4 questions, each with a ≤16-character header chip, 2–16 options (label ≤60 characters + description, optional preview), and an optional multiSelect flag. The engine appends its own free-text affordance (pi's "Type something." row) — it is NOT an option here.

DISENTANGLED from the rendering engine: the tool owns argument validation and answer normalization; the harness's QUESTION BRIDGE (context.question.ask — provided by the Agent, which received it from the TUI/HTML/WebSocket binding) owns rendering the questions and previews and collecting the answers. The bridge is the INTERNAL second argument, never part of the published schema. Bridge answer shape, one per question: { labels: string[] } — the chosen option label(s) { text: string } — a custom typed answer { abandoned: true } — the user pressed Esc Without a bridge the tool REFUSES (throws): a session with no one to ask cannot ask — CLI bindings wire the bridge ONLY into the ACTIVE agent (the one being displayed), so a session running headless execution has no question handler and every question is refused. The refusal text tells the model to proceed with its best judgment instead.

Read-only (safe: true): asking the user mutates nothing — safe-mode Agents may ask questions. The forked, OS-sandboxed worker uses the Agent's typed fd-3/fd-4 JSONL ask/answer bridge; no host callback crosses the sandbox.

lib/agent/tool-worker.js

REQUIRES — forked worker's serializable ctx: env, sandbox, deadline, onData, agent.folder; question bridge when enabled; no live Agent or IO

lib/agent/tool-worker.js — the child-process side of lib/agent/tool-sandbox.js.

Spawned as <runtime> lib/agent/tool-worker.js: reads ONE JSON line from stdin — {dir, settings, roots, name, args, cwd, projectCwd, file?, questionBridge?, detached?} — rebuilds an Env from it, loads the ONE tool module the parent's registry named (file; never a root rescan), invokes the tool, and writes ONE JSON result line to stdout: {ok: true, value} or {ok: false, error}. All ordinary failures are reported on stdout with exit 0; a nonzero exit (or silence) means the tool destroyed the process (e.g. process.exit) and the parent reports that instead — which is the entire point of the sandbox.

THE RESULT LINE IS THE LAST THING WRITTEN — and it must survive everything a tool printed at IMPORT (a script without an import.meta.main guard can dump megabytes onto stdout while the tool scan loads it): the process exits only after the writable side FLUSHED. process.exit() right after write() discards user-space pipe buffers — the truncated-result race the parent reports as "worker exited without a result (code 0)".

This file is executed, not imported, and must stay runtime-agnostic (no Bun-only APIs).

lib/agent/tool-exec.js

RETURNS — every shape a tool's return value may take

lib/app/tui/input-controller.js

lib/app/tui/input-controller.js — the draft input box's MODEL-OWNED state: value/caret/selection (mirrored from GTUI's input control — see lib/app/gtui/controls.js's controlled-input contract: the control computes edits from the LAST rendered value/caret/selection, so the app must hold and re-supply them) plus completions, which are pure tui-app policy (completion.js's computeCompletions) that GTUI's input node only ever displays.

Tab/Shift+Tab/Down/Up/Enter double as completion-list navigation ONLY while completions are showing — the app declares them via GTUI's bindings(model) so those keys bypass the input control entirely and move, accept, or dismiss the completion list instead.

lib/app/gtui/controls/manager.js

lib/app/gtui/terminal-input.js

lib/app/tui/questionnaire-view.js

lib/app/tui/questionnaire-view.js — the open question (agent-adapter.js's question bridge + questionnaire.js's pure state) into GTUI nodes: the options render through the SAME controlled menu used everywhere else (arrow/enter/escape are native), plus a real input control for a custom typed answer, not just a display label.

Enter and Space both select/toggle the focused row. On a single-select answer Enter also moves the highlight to the Submit row for confirmation (the input's Enter does the same jump). Only selecting the final submit row commits the answer. The question text, option labels, and option DESCRIPTIONS all SOFT-WRAP (labels through the menu's own word-wrap; descriptions as their own wrapped text nodes), so nothing clips at the overlay edge. A description/preview belongs to the option: it shows ONLY while that option is the HIGHLIGHTED menu row (tui-app tracks menu.change into question.highlight), so extra information never floods the overlay. A code preview renders through the shared markdown pipeline (fenced block) — the same highlighting the transcript uses. Crossing the input's top row with ↑ (or its bottom with ↓) returns focus to the menu (tui-app's key policy on GTUI's bubbled boundary move). GTUI still owns only generic menu navigation/selection and never sees questionnaire state.