@yaag/cli 0.1.0

package/assets/types/runtime/checkpoint-dir.d.ts

@@ -0,0 +1,30 @@
+/** A temp file left by an interrupted publication is stale after one day (ADR-0021). */
+export declare const CHECKPOINT_TEMP_MAX_AGE_MS: number;
+/**
+ * Resolves where a stopped Run publishes its checkpoint when `--record` set no
+ * path: `YAAG_CHECKPOINT_DIR`, then an absolute `XDG_STATE_HOME`, then
+ * `$HOME/.local/state`. A relative `XDG_STATE_HOME` is ignored (XDG spec).
+ */
+export declare function resolveCheckpointDirectory(env?: NodeJS.ProcessEnv): string;
+/**
+ * Names one checkpoint file. There is no Run id below the transport seam yet, so
+ * the name is a millisecond timestamp, the process id, and a full random UUID.
+ * The UUID is what makes the name collision-safe: two Runs in one process can
+ * settle inside the same millisecond, and a rename onto an existing name would
+ * destroy the earlier checkpoint (ADR-0021). The UUID keeps all 122 random bits;
+ * a truncated nonce would make that silent overwrite reachable.
+ */
+export declare function checkpointFileName(now?: Date, pid?: number, nonce?: string): string;
+/** Bounds for {@link cleanStaleCheckpointTemp}; both default when omitted. */
+export interface CleanStaleOptions {
+    /** Epoch milliseconds treated as "now"; defaults to `Date.now()`. */
+    readonly now?: number;
+    /** Age above which a temp file is removed; defaults to {@link CHECKPOINT_TEMP_MAX_AGE_MS}. */
+    readonly maxAgeMs?: number;
+}
+/**
+ * Removes publication temp files older than `maxAgeMs`. A missing directory
+ * resolves silently; a `readdir` failure rejects, so the caller owns the
+ * diagnostic. This module never writes to stderr.
+ */
+export declare function cleanStaleCheckpointTemp(directory: string, options?: CleanStaleOptions): Promise<void>;

package/assets/types/runtime/connection.d.ts

@@ -0,0 +1,29 @@
+import type { AgentTransport, Frame } from "./transport.ts";
+/** The useful part of a `response` frame, once narrowed. */
+export interface CommandResponse {
+    readonly success: boolean;
+    readonly error: string | null;
+    readonly data: Record<string, unknown> | null;
+}
+/**
+ * One conversation with an Agent over the transport seam: correlates commands
+ * with their responses by id, cancels dialogs, and hands every other frame to
+ * the Ask in flight.
+ *
+ * Lives above the seam, so it knows nothing about processes.
+ */
+export declare class Connection {
+    #private;
+    constructor(transport: AgentTransport, agent: string);
+    /** True once the Agent's frame stream has ended: the Handle is permanently dead. */
+    get dead(): boolean;
+    /** Resolves when the Agent's frame stream ends. Never rejects. */
+    get closed(): Promise<void>;
+    /** Routes non-response frames to a listener, replacing any previous one. */
+    observe(listener: ((frame: Frame) => void) | null): void;
+    /**
+     * Sends one command and resolves with its id-correlated response.
+     * Rejects with AGENT_DIED if the Agent dies first.
+     */
+    command(frame: Frame): Promise<CommandResponse>;
+}

package/assets/types/runtime/define-agent.d.ts

@@ -0,0 +1,48 @@
+import type { AskOptions, ThinkingLevel } from "./types.ts";
+export type { ThinkingLevel } from "./types.ts";
+/** What `defineAgent` is given: the policy of one Agent, never its topology. */
+export interface AgentConfig {
+    /** Stable identity, used in every Lifecycle Event and log line. */
+    readonly name: string;
+    /** System prompt text appended to pi's own, unless `overrideSystemPrompt`. */
+    readonly prompt?: string;
+    /** Replace pi's system prompt with `prompt` instead of appending to it. */
+    readonly overrideSystemPrompt?: boolean;
+    /** Model id handed to `pi --model`. Unset = pi's default. */
+    readonly model?: string;
+    /** Thinking budget for the Agent's turns. */
+    readonly thinking?: ThinkingLevel;
+    /** Allow-list of tool names. Unset = pi's default tool set. */
+    readonly tools?: readonly string[];
+    /** Deny-list of tool names, applied after `tools`. */
+    readonly disallowedTools?: readonly string[];
+    /** Allow-list of skill names. Unset = pi's default skill set. */
+    readonly skills?: readonly string[];
+    /** Deny-list of skill names, applied after `skills`. */
+    readonly disallowedSkills?: readonly string[];
+    /** Ask options applied to every Ask on this Agent unless overridden per call. */
+    readonly askDefaults?: AskOptions;
+}
+/** Not exported, so the config is unreachable outside this module. */
+declare const definition: unique symbol;
+/** Opaque, deep-frozen result of `defineAgent`. */
+export interface AgentDefinition {
+    readonly [definition]: AgentConfig;
+}
+/**
+ * Declares an Agent Definition: reusable policy, independent of where it runs.
+ *
+ * Throws a TypeError when `name` is missing or blank, or when `cwd`/`worktree`
+ * appear — those are topology, chosen at spawn time, not baked into a definition.
+ * The config is defensively copied and deep-frozen, so later mutation of the
+ * caller's arrays cannot change the definition.
+ */
+export declare function defineAgent(config: AgentConfig): AgentDefinition;
+/** True only for values produced by `defineAgent`. */
+export declare function isAgentDefinition(value: unknown): value is AgentDefinition;
+/**
+ * Recovers the config behind an Agent Definition.
+ * Throws a TypeError when the value did not come from `defineAgent`.
+ */
+export declare function agentDefinitionConfig(value: AgentDefinition): AgentConfig;
+export declare function agentDefinitionConfig(value: unknown): AgentConfig;

package/assets/types/runtime/define-run.d.ts

@@ -0,0 +1,40 @@
+import type { Static, TSchema } from "typebox";
+import type { RunContext } from "./run-context.ts";
+/** What `defineRun` is given. */
+export interface ProgramDefinition<Args = unknown, Result = unknown> {
+    readonly name?: string;
+    readonly description?: string;
+    /** Optional Typebox contract for arguments delivered to `run`. */
+    readonly args?: TSchema;
+    readonly run: (ctx: RunContext<Args>) => Result | Promise<Result>;
+}
+type SchemaProgramDefinition<Schema extends TSchema, Result> = Omit<ProgramDefinition<Static<Schema>, Result>, "args"> & {
+    readonly args: Schema;
+};
+type SchemalessProgramDefinition<Args, Result> = ProgramDefinition<Args, Result> & {
+    readonly args?: never;
+};
+/** Not exported, so the definition is unreachable outside this module. */
+declare const definition: unique symbol;
+/** Opaque result of `defineRun`. Must be the module's default export. */
+export interface OrchestrationProgram<Args = unknown, Result = unknown> {
+    readonly [definition]: ProgramDefinition<Args, Result>;
+}
+/**
+ * Declares an Orchestration Program with arguments inferred from its Typebox schema.
+ *
+ * The returned value is opaque: exporting anything else as default is a compile
+ * error rather than a runtime "no program found".
+ */
+export declare function defineRun<Schema extends TSchema, Result>(program: SchemaProgramDefinition<Schema, Result>): OrchestrationProgram<Static<Schema>, Result>;
+/** Declares an Orchestration Program without an argument schema. */
+export declare function defineRun<Args = unknown, Result = unknown>(program: SchemalessProgramDefinition<Args, Result>): OrchestrationProgram<Args, Result>;
+/** True only for values produced by `defineRun`. */
+export declare function isOrchestrationProgram(value: unknown): value is OrchestrationProgram;
+/**
+ * Recovers the definition behind a program.
+ * Throws a TypeError when the value did not come from `defineRun`.
+ */
+export declare function programDefinition<Args, Result>(value: OrchestrationProgram<Args, Result>): ProgramDefinition<Args, Result>;
+export declare function programDefinition(value: unknown): ProgramDefinition;
+export {};

package/assets/types/runtime/errors.d.ts

@@ -0,0 +1,50 @@
+/** Which soft Ask budget was exhausted. */
+export type AskLimitKind = "turns" | "toolCalls" | "durationMs";
+/** The recorded result when yaag aborts an Ask after a soft budget is exhausted. */
+export interface AskLimitOutcome {
+    readonly kind: AskLimitKind;
+    readonly count: number;
+}
+/** The recorded result when yaag rejects an Ask because no frame arrived within `idleMs`. */
+export interface AskStalledOutcome {
+    /** The configured silence threshold that tripped. */
+    readonly idleMs: number;
+    /** True when abort failed to settle the Agent and yaag killed the process. */
+    readonly destructive: boolean;
+}
+/** Recoverable result when all structured-output correction efforts are exhausted. */
+export interface AskInvalidOutputOutcome {
+    /** Corrective steers sent before aborting this Ask. */
+    readonly steeringEfforts: number;
+    /** Final extraction or TypeBox diagnostics, localized to JSON paths. */
+    readonly errors: readonly string[];
+}
+/** Why an Ask, spawn, or Run failed. Programs may branch on this; most won't. */
+export type YaagErrorCode = "AGENT_FAILED" | "AGENT_DIED" | "AGENT_BUSY" | "ASK_TIMEOUT" | "ASK_LIMIT" | "ASK_STALLED" | "ASK_INVALID_OUTPUT" | "ARGS_INVALID" | "OPTIONS_CONFLICT" | "REPLAY_DIVERGED" | "RESUME_REFUSED" | "RUN_CLOSED" | "RUN_STOPPED" | "WORKTREE_REFUSED" | "SPAWN_FAILED";
+/** The single error class of the runtime (ADR-0003). */
+export declare class YaagError extends Error {
+    readonly code: YaagErrorCode;
+    /** Agent name, when the error concerns one. */
+    readonly agent?: string;
+    /** Exhausted soft Ask budget, present only for `ASK_LIMIT`. */
+    readonly limit?: AskLimitKind;
+    /** Count observed when the soft Ask budget first tripped. */
+    readonly count?: number;
+    /** Silence threshold that tripped, present only for `ASK_STALLED`. */
+    readonly idleMs?: number;
+    /** True when an `ASK_STALLED` escalation had to kill the Agent. */
+    readonly destructive?: boolean;
+    /** Number of corrective output steers sent, present only for `ASK_INVALID_OUTPUT`. */
+    readonly steeringEfforts?: number;
+    /** Localized extraction or schema errors, present only for `ASK_INVALID_OUTPUT`. */
+    readonly errors?: readonly string[];
+    constructor(code: YaagErrorCode, message: string, agent?: string, options?: AskLimitOutcome | AskStalledOutcome | AskInvalidOutputOutcome);
+}
+/** Builds the runtime's uniform agent-scoped error message. */
+export declare function agentError(agent: string, code: YaagErrorCode, message: string): YaagError;
+/** The ASK_LIMIT rejection for one exhausted soft budget. */
+export declare function askLimitError(agent: string, outcome: AskLimitOutcome): YaagError;
+/** The ASK_STALLED rejection for one tripped idle watch. */
+export declare function askStalledError(agent: string, outcome: AskStalledOutcome): YaagError;
+/** Narrows an unknown rejection reason to a YaagError. */
+export declare function isYaagError(value: unknown): value is YaagError;

package/assets/types/runtime/events.d.ts

@@ -0,0 +1,138 @@
+/**
+ * Lifecycle Events (ADR-0006): a closed set of flat records, emitted above the
+ * transport seam. Live-only frame observers may add richer events than a
+ * Cassette replay produces; replay intentionally omits that observation data.
+ * Playback Asks still emit normal start/end events, but intentionally omit live
+ * activity, output, and usage observations. v0 renders them as stderr lines; the
+ * dedicated fd arrives with the extension.
+ */
+import type { TokenBreakdown, WorktreeResolution } from "./transport.ts";
+/** A settled Run's terminal outcome (ADR-0022). `paused` arrives with the pause slice. */
+export type RunOutcome = "completed" | "failed" | "stopped" | "paused";
+/** The current, Ask-scoped observer projection derived from Agent frames. */
+export type AgentActivity = {
+    readonly type: "thinking";
+} | {
+    readonly type: "writing";
+} | {
+    readonly type: "tool";
+    readonly name: string;
+    readonly argsGist: string;
+} | {
+    readonly type: "compacting";
+} | {
+    readonly type: "retrying";
+    readonly attempt: number;
+    readonly max: number;
+};
+/** The assistant stream channel carried by an additive `ask_output` event. */
+export type AskOutputChannel = "text" | "thinking";
+/** The lifecycle state of one Nested Node, as decoded from its parent's frames. */
+export type NodeState = "running" | "exited" | "failed";
+/** Accounting a nesting tool reports for one Nested Node; both fields are optional facts. */
+export interface NodeUsage {
+    readonly tokens?: TokenBreakdown;
+    readonly cost?: number;
+}
+export type LifecycleEventBody = {
+    readonly type: "run_start";
+    readonly program: string;
+} | {
+    readonly type: "agent_spawn";
+    readonly agent: string;
+    readonly model: string;
+    readonly cwd: string;
+    /** Present only when the Agent was spawned into a worktree. */
+    readonly branch?: string;
+    /**
+     * pi's persisted session file for this Agent, when the startup handshake
+     * reported one. A path is not a prompt payload, so it may ride the wire
+     * (ticket 09); a Peek reads this file to render the transcript. Absent for
+     * Cassette-playback Agents and events from older CLIs.
+     */
+    readonly sessionFile?: string;
+} | {
+    readonly type: "ask_start";
+    readonly agent: string;
+    readonly index: number;
+    /** First non-blank prompt line, whitespace-collapsed, ≤ PROMPT_GIST_MAX_CHARS. */
+    readonly promptGist: string;
+    /** Full prompt length; the prompt itself never rides the wire (ticket 09). */
+    readonly promptChars: number;
+    /** Present only when this individual Ask was served from Cassette playback. */
+    readonly replayed?: true;
+} | {
+    readonly type: "ask_activity";
+    readonly agent: string;
+    readonly index: number;
+    readonly activity: AgentActivity;
+} | {
+    readonly type: "ask_output";
+    readonly agent: string;
+    readonly index: number;
+    readonly channel: AskOutputChannel;
+    readonly text: string;
+} | {
+    /**
+     * A bounded snapshot of one Nested Node. It is the only nested-node event:
+     * there is no per-node spawn/ask/exit mirroring (spec §3). Unlike
+     * `ask_activity` and `ask_output`, it is re-derived on Cassette replay,
+     * because it decodes recorded Agent frames only (ADR-0006, ADR-0013).
+     */
+    readonly type: "node_update";
+    readonly agent: string;
+    /** Node identity in the grammar `name(:askIndex(/childName…))`. */
+    readonly path: string;
+    readonly state: NodeState;
+    /** One line, ≤ NODE_GIST_MAX_CHARS; never a prompt (ticket 09). */
+    readonly activityGist?: string;
+    readonly usage?: NodeUsage;
+} | {
+    readonly type: "ask_end";
+    readonly agent: string;
+    readonly index: number;
+    readonly durationMs: number;
+    readonly ok: boolean;
+    /** Largest inter-frame silence during this Ask; absent during Cassette playback. */
+    readonly maxFrameGapMs?: number;
+} | {
+    readonly type: "agent_usage";
+    readonly agent: string;
+    /** Cumulative assistant-completion usage observed so far. */
+    readonly tokens: TokenBreakdown;
+    /** Cumulative assistant-completion cost observed so far. */
+    readonly cost: number;
+} | {
+    readonly type: "agent_exit";
+    readonly agent: string;
+    readonly tokens: TokenBreakdown | null;
+    readonly cost: number | null;
+    /** Cost is a floor, not a total: the Agent was killed mid-Ask (ADR-0012). */
+    readonly incomplete: boolean;
+    /** Surviving worktree identity, present only for worktree Agents. */
+    readonly worktree?: WorktreeResolution;
+} | {
+    readonly type: "run_end";
+    readonly ok: boolean;
+    /** Terminal outcome (ADR-0022); the invariant is `ok === (outcome === "completed")`. */
+    readonly outcome: RunOutcome;
+    readonly durationMs: number;
+    readonly cost: number;
+    /** Summed component-wise; null when any Agent's usage was unknown. */
+    readonly tokens: TokenBreakdown | null;
+    /** At least one Agent's cost was an undercount. */
+    readonly incomplete: boolean;
+    /** Largest inter-frame silence across every Ask; 0 when nothing was measured. */
+    readonly worstFrameGapMs: number;
+};
+/**
+ * A Lifecycle Event as observers see it: the body plus `at` — epoch-ms wall
+ * clock, stamped once in the Orchestrator's sink wrapper, never per emitter.
+ */
+export type LifecycleEvent = LifecycleEventBody & {
+    readonly at: number;
+};
+/** Where emitters inside a Run report Lifecycle Event bodies, pre-stamp. */
+export type EventSink = (event: LifecycleEventBody) => void;
+/** Where a Run reports its stamped Lifecycle Events. */
+export type StampedEventSink = (event: LifecycleEvent) => void;

package/assets/types/runtime/extension-package.d.ts

@@ -0,0 +1,17 @@
+import type { ExtensionSource } from "./extension-source.ts";
+/** Roots searched for an already-installed pi package, project before user. */
+export interface ExtensionInstallRoots {
+    /** Agent working directory holding `.pi/npm` and `.pi/git`; defaults to `process.cwd()`. */
+    readonly projectRoot?: string;
+    /** pi user config directory; defaults to `~/.pi/agent`. */
+    readonly userConfigDir?: string;
+}
+/**
+ * Expands an installed pi package into its declared extension entry files.
+ *
+ * Resolves the project install before the user install, then reads the package
+ * manifest's `pi.extensions` array in declaration order. Returns `undefined`
+ * when the package is not installed, so the caller can hand the raw specifier
+ * to pi and let it temp-install (docs/packages.md).
+ */
+export declare function resolveInstalledExtension(source: ExtensionSource, roots?: ExtensionInstallRoots): Promise<readonly string[] | undefined>;

package/assets/types/runtime/extension-paths.d.ts

@@ -0,0 +1,16 @@
+import { type ExtensionInstallRoots } from "./extension-package.ts";
+/** Inputs that decide how a declaration becomes a launch-ready `-e` argument. */
+export interface ExtensionResolutionOptions extends ExtensionInstallRoots {
+    /** Orchestration Program source path, required by relative declarations. */
+    readonly programFile?: string;
+}
+/**
+ * Resolves declared extensions into launch-ready `pi -e` arguments before transport opening.
+ *
+ * Filesystem declarations are resolved against the Orchestration Program directory and
+ * checked for existence. `npm:`/`git:` specifiers expand to the entry points of the
+ * already-installed package (project install shadows the user install); an uninstalled
+ * specifier passes through verbatim so pi temp-installs it. Results retain declaration
+ * order. Rejects missing paths and a relative declaration without `programFile`.
+ */
+export declare function resolveExtensionPaths(declarations: readonly string[], options?: ExtensionResolutionOptions): Promise<readonly string[]>;

package/assets/types/runtime/extension-source.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Parses pi package specifiers (`npm:`, `git:`) used as extension declarations.
+ *
+ * A declaration that carries neither prefix is a filesystem path and is reported
+ * as `{ kind: "path" }` so the caller keeps its existing resolution behaviour.
+ */
+export type ExtensionSource = {
+    readonly kind: "path";
+} | {
+    readonly kind: "npm";
+    readonly packageName: string;
+} | {
+    readonly kind: "git";
+    readonly host: string;
+    readonly owner: string;
+    readonly repo: string;
+};
+/** An extension declared as a pi package specifier rather than a filesystem path. */
+export type InstalledExtensionSource = Exclude<ExtensionSource, {
+    kind: "path";
+}>;
+/**
+ * Classifies one extension declaration.
+ *
+ * Throws when an `npm:`/`git:` prefix is present but the remainder is not a
+ * package name or a `<host>/<owner>/<repo>` triple.
+ */
+export declare function parseExtensionSource(declaration: string): ExtensionSource;

package/assets/types/runtime/fake-transport.d.ts

@@ -0,0 +1,78 @@
+import type { AgentStats, AgentTransport, AskMarker, Frame } from "./transport.ts";
+/**
+ * Scripted frame playback for one prompt sent through a FakeTransport.
+ *
+ * Abort frames play only after that prompt's abort command.
+ */
+export interface FakePromptScript {
+    /** Frames the Agent emits in response to this prompt, in recorded order. */
+    readonly frames?: readonly Frame[];
+    /** Scripts selected in order by correction follow-up `prompt` commands. */
+    readonly corrections?: readonly FakePromptScript[];
+    /** Script selected by the configured or default soft-limit wrap-up steer, when provided. */
+    readonly wrapUp?: FakePromptScript;
+    /** Prompt that selects `wrapUp`; falls back to the runtime default when omitted. */
+    readonly wrapUpPrompt?: string;
+    /** Frames emitted after yaag sends an abort command. */
+    readonly abortFrames?: readonly Frame[];
+    /** Delay before each scripted frame, for clock-driven tests. */
+    readonly frameDelayMs?: number;
+    /** Delay before each abort-specific frame, for abort-settlement tests. */
+    readonly abortFrameDelayMs?: number;
+    /** Payload of `get_last_assistant_text`; null means the `{}` pi returns on failure. */
+    readonly lastText?: string | null;
+    /** Makes this script's prompt RPC response fail, before any frame playback. */
+    readonly promptError?: string;
+}
+/**
+ * Configures a FakeTransport with one shorthand script or ordered per-prompt scripts.
+ *
+ * Control-command failures apply across the configured playback.
+ */
+export interface FakeTransportOptions extends FakePromptScript {
+    /** One script per Ask's initial prompt, used in order; preserves the single-script shorthand above. */
+    readonly scripts?: readonly FakePromptScript[];
+    /** Makes a steer RPC response fail without embedding a limit decision in playback. */
+    readonly steerError?: string;
+    /** Makes an abort RPC response fail without embedding a limit decision in playback. */
+    readonly abortError?: string;
+    readonly stats?: AgentStats;
+    /** pi can answer a command after `agent_settled` — it is last among events only. */
+    readonly promptResponse?: "immediate" | "after-settle";
+    /** Ends the frame stream once playback finishes, as a dying process would. */
+    readonly dieAfterFrames?: boolean;
+}
+/**
+ * Test implementation of the transport seam that plays scripted recorded or synthetic frames.
+ *
+ * It encodes real pi (0.84.1) post-settlement semantics: an Ask's initial prompt
+ * selects the next top-level script, each later prompt within the same Ask selects
+ * the next correction script, and a non-wrap-up steer is acknowledged but only
+ * queued (`queue_update`) — it never plays frames or settles.
+ * It never spawns or closes a real Agent process.
+ */
+export declare class FakeTransport implements AgentTransport {
+    #private;
+    readonly model = "test/model";
+    /** Everything the runtime wrote, in order. */
+    readonly sent: Frame[];
+    readonly asks: AskMarker[];
+    constructor(options?: FakeTransportOptions);
+    send(frame: Frame): void;
+    frames(): AsyncIterable<Frame>;
+    beginAsk(marker: AskMarker): undefined;
+    finishAsk(): void;
+    /** True once the runtime shut this Agent down. */
+    get closed(): boolean;
+    /** Number of times this fake actually began close work. */
+    get closeCalls(): number;
+    close(): Promise<AgentStats>;
+    /** Simulates the process dying: the frame stream just ends. */
+    die(): void;
+}
+/**
+ * Loads and parses a named JSONL frame fixture from the runtime fixtures directory.
+ *
+ * Rejects when the fixture cannot be read or contains an invalid frame.
+ */
+export declare function recordedFrames(name: string): Promise<Frame[]>;

package/assets/types/runtime/frame-gap.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Per-Ask frame-gap telemetry: the largest silence between two consecutive
+ * Agent frames (ADR-0020 — measure before enforcing idle thresholds).
+ *
+ * The first gap is measured from prompt send (`start()`) to the first frame;
+ * later gaps are inter-arrival. Live-only: Cassette playback creates no tracker,
+ * because replayed frames arrive instantly and their gaps mean nothing.
+ */
+export interface FrameGapOptions {
+    /** Injectable clock, so tests need no real timers. Defaults to `Date.now`. */
+    readonly now?: () => number;
+}
+/** Tracks the maximum inter-frame gap of one Ask. No per-frame allocation. */
+export declare class FrameGapTracker {
+    #private;
+    constructor(options?: FrameGapOptions);
+    /** Marks prompt send. Call once, before the prompt command. */
+    start(): void;
+    /** Records one frame arrival, widening the maximum gap if this one is larger. */
+    observe(): void;
+    /** The largest gap observed so far, in milliseconds; 0 when no frame arrived. */
+    get maxGapMs(): number;
+}

package/assets/types/runtime/frame-queue.d.ts

@@ -0,0 +1,15 @@
+import type { Frame } from "./transport.ts";
+/**
+ * A single-consumer queue turning pushed frames into an async iterable.
+ *
+ * The live transport reads its child's stdout once — intercepting the responses
+ * to its own commands — and republishes the rest here, so the layer above sees
+ * one ordered stream regardless of when it starts iterating.
+ */
+export declare class FrameQueue {
+    #private;
+    push(frame: Frame): void;
+    /** Ends the stream; the consumer's iteration finishes once drained. */
+    end(): void;
+    frames(): AsyncGenerator<Frame>;
+}

package/assets/types/runtime/git-facts.d.ts

@@ -0,0 +1,7 @@
+import type { CassetteGit } from "./cassette.ts";
+/**
+ * Observes the branch and commit at a cwd without changing repository state.
+ *
+ * Returns undefined when Git cannot describe a checked-out work tree.
+ */
+export declare function readGitFacts(cwd: string): Promise<CassetteGit | undefined>;

package/assets/types/runtime/idle-watch.d.ts

@@ -0,0 +1,44 @@
+import type { AskStalledOutcome } from "./errors.ts";
+import type { Frame } from "./transport.ts";
+/** Fixed time allowed for `agent_settled` to arrive after the idle abort. */
+export declare const IDLE_ABORT_SETTLE_MS = 5000;
+export interface IdleWatchOptions {
+    /** Maximum silence, in milliseconds, before escalation starts. */
+    readonly idleMs: number;
+    readonly command: (frame: Frame) => Promise<boolean>;
+    /** Bounded wait for `agent_settled` after the abort; defaults to 5s. */
+    readonly abortSettleMs?: number;
+}
+/** Rejection carried by {@link IdleWatch.killed} when abort produced nothing. */
+export declare class IdleKillSignal extends Error {
+    readonly outcome: AskStalledOutcome;
+    constructor(outcome: AskStalledOutcome);
+}
+/**
+ * Per-Ask silence watchdog, a sibling of `AskLimit` (ADR-0020).
+ *
+ * The timer starts at prompt send and resets on every frame. On expiry it
+ * sends `abort` and nothing else — a queued `steer` would be delivered as a new
+ * turn the instant abort ends the hung one, and `agent_settled` would never
+ * arrive.
+ */
+export declare class IdleWatch {
+    #private;
+    constructor(options: IdleWatchOptions);
+    /** Arms the idle timer immediately before the prompt command is sent. */
+    start(): void;
+    /** Resets the silence timer; after escalation, watches for `agent_settled`. */
+    observe(frame: Frame): void;
+    /** Cancels the watch once the Ask settles. Idempotent. */
+    settled(): void;
+    /** Cancels timers on every other Ask exit path. Idempotent. */
+    cleanup(): void;
+    /** True once the silence budget expired and escalation began. */
+    get tripped(): boolean;
+    /** The stalled outcome, once escalation resolved either way. */
+    get result(): AskStalledOutcome | null;
+    /** Rejects when the abort RPC is refused, mirroring `AskLimit.failed`. */
+    get failed(): Promise<never>;
+    /** Rejects with an {@link IdleKillSignal} only on the destructive path. */
+    get killed(): Promise<never>;
+}

package/assets/types/runtime/index.d.ts

@@ -0,0 +1,33 @@
+export type { Cassette, CassetteAgent, CassetteArtifact, CassetteAsk, CassetteGit, CassetteRun, CassetteSink, CassetteSpawn, } from "./cassette.ts";
+export { CASSETTE_VERSION } from "./cassette.ts";
+export { loadCassette } from "./cassette-loader.ts";
+export type { AgentConfig, AgentDefinition } from "./define-agent.ts";
+export { agentDefinitionConfig, defineAgent, isAgentDefinition } from "./define-agent.ts";
+export type { OrchestrationProgram, ProgramDefinition } from "./define-run.ts";
+export { defineRun, isOrchestrationProgram, programDefinition } from "./define-run.ts";
+export type { AskInvalidOutputOutcome, AskLimitKind, AskLimitOutcome, AskStalledOutcome, YaagErrorCode, } from "./errors.ts";
+export { isYaagError, YaagError } from "./errors.ts";
+export type { AgentActivity, AskOutputChannel, EventSink, LifecycleEvent, LifecycleEventBody, NodeState, NodeUsage, StampedEventSink, } from "./events.ts";
+export type { DecodedNode, NodeDecoder } from "./node-decoder.ts";
+export { DEFAULT_NODE_DECODERS } from "./node-decoders.ts";
+export type { NodePath } from "./node-path.ts";
+export { agentAskPath, childPath, sanitizeNodeName } from "./node-path.ts";
+export type { NodeSnapshot } from "./node-tracker.ts";
+export { NodeTracker } from "./node-tracker.ts";
+export { prompt } from "./prompt.ts";
+export { promptGist } from "./prompt-gist.ts";
+export type { ReapPath, ReapTarget } from "./reap.ts";
+export { reap } from "./reap.ts";
+export { recordingTransport } from "./recording-transport.ts";
+export { replayTransport } from "./replay-transport.ts";
+export { resumeTransport } from "./resume-transport.ts";
+export type { RunOptions } from "./run.ts";
+export { executeRun } from "./run.ts";
+export type { RunContext } from "./run-context.ts";
+export type { DiscoveredSkill, SkillProbeFactory } from "./skill-probe.ts";
+export type { AgentInfo, AgentState, AskingAgentInfo, EndedRunSummary, ExitedAgentInfo, IdleAgentInfo, NodeInfo, RunningRunSummary, RunOutcome, RunState, RunSummary, } from "./summary.ts";
+export { applyEvent, initialSummary } from "./summary.ts";
+export type { AgentStats, AgentTransport, AskMarker, AskMarkerContext, AskPlayback, Frame, TokenBreakdown, TransportFactory, TransportStartup, TransportStartupObserver, WorktreeResolution, } from "./transport.ts";
+export type { AskOptions, Handle, SpawnOptions, SpawnOverrides, StructuredAskOptions, ThinkingLevel, } from "./types.ts";
+export { AGENT_NODE_TABLE_MAX, ASK_OUTPUT_FLUSH_INTERVAL_MS, ASK_OUTPUT_MAX_BYTES, ASK_OUTPUT_TRUNCATION_MARKER, NODE_GIST_MAX_CHARS, PROMPT_GIST_MAX_CHARS, TOOL_ARGS_GIST_MAX_CHARS, } from "./wire-constants.ts";
+export { worktreeTransport } from "./worktree-transport.ts";

package/assets/types/runtime/jsonl.d.ts

@@ -0,0 +1,13 @@
+import type { Frame } from "./transport.ts";
+/**
+ * Decodes a byte stream into frames using pi's strict JSONL framing: split on
+ * `\n` only, strip a trailing `\r`. A generic line reader is not
+ * protocol-compliant, because U+2028/U+2029 are valid inside JSON strings
+ * (pi `docs/rpc.md`, framing note).
+ *
+ * Non-JSON lines and JSON that is not a frame object are skipped rather than
+ * thrown on: pi emits undocumented frame types and occasional noise (ticket 01).
+ */
+export declare function decodeFrames(chunks: AsyncIterable<Uint8Array>): AsyncGenerator<Frame>;
+/** Returns null for anything that is not a JSON object with a string `type`. */
+export declare function parseFrame(line: string): Frame | null;

package/assets/types/runtime/live-transport.d.ts

@@ -0,0 +1,3 @@
+import type { TransportFactory } from "./transport.ts";
+/** Agents are real `pi --mode rpc` child processes (ADR-0001). */
+export declare const liveTransport: TransportFactory;

package/assets/types/runtime/node-decoder-subagent.d.ts

@@ -0,0 +1,7 @@
+import type { NodeDecoder } from "./node-decoder.ts";
+/**
+ * Decodes the reference `subagent` tool's `SubagentDetails`: one Nested Node per
+ * `results[]` entry, in the order the tool reports them. `exitCode === -1` means
+ * "still running" in that tool, so it stays a running node.
+ */
+export declare const subagentNodeDecoder: NodeDecoder;

package/assets/types/runtime/node-decoder-workflow.d.ts

@@ -0,0 +1,12 @@
+import type { NodeDecoder } from "./node-decoder.ts";
+/**
+ * Decodes pi-extensible-workflows' progress shape: `details.run.agents[]`, each
+ * an `AgentRecord` with a state, an optional structural path, activity and
+ * accounting.
+ *
+ * Tool-name matching is best-effort (spec §3): a workflow tool may register
+ * under `workflow` or a `workflow_`-prefixed name, and a tool that matches but
+ * reports another shape still yields no nodes. A backgrounded run
+ * carries no `run`, so it yields no nodes — its facts leave the RPC stream.
+ */
+export declare const workflowNodeDecoder: NodeDecoder;