@yaag/cli 0.9.0 → 0.11.0

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

@@ -0,0 +1,29 @@
+import type { EventSink } from "../events.ts";
+import type { AgentTransport, CompactionResult, Connection } from "../transport/index.ts";
+import type { AgentUsage } from "./agent-usage.ts";
+/** One compaction of one Agent's context (ADR-0043). */
+export interface CompactionExchange {
+    readonly agent: string;
+    readonly connection: Connection;
+    readonly transport: AgentTransport;
+    /** Monotonic per Agent, from 0. */
+    readonly index: number;
+    /** Settled Asks of this Agent at the compaction point. */
+    readonly afterAsks: number;
+    /** pi `customInstructions`; the text never rides the wire (ticket 09). */
+    readonly instructions?: string;
+    readonly emit: EventSink;
+    readonly usage: AgentUsage;
+}
+/**
+ * Compacts one Agent's context and reports what the summary call cost.
+ *
+ * Playback answers from the Cassette and emits the same event, but folds no
+ * usage: a replayed Run never reports live accounting.
+ */
+export declare function compactAgent(exchange: CompactionExchange): Promise<CompactionResult>;
+/**
+ * Identity of one compaction: where it sits in the Agent's conversation, and
+ * whether the program steered it. The instruction text is hashed, never stored.
+ */
+export declare function compactionHash(afterAsks: number, instructions: string | undefined): string;

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

@@ -13,4 +13,12 @@ export declare class AgentUsage {
     constructor(report: (snapshot: AgentUsageSnapshot) => void);
     /** Observes one raw Agent frame and reports after each valid assistant completion. */
     observe(frame: Frame): void;
+    /**
+     * Folds one completion yaag observed outside the frame stream, and reports.
+     *
+     * A compaction's summary call is the only such completion today: pi answers
+     * it on the `compact` response instead of an assistant `message_end`, so the
+     * live accounting would lose that spend (ADR-0043).
+     */
+    add(usage: AgentUsageSnapshot): void;
 }

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

@@ -1,8 +1,9 @@
 import type { Static, TSchema } from "typebox";
 import type { EventSink } from "../events.ts";
 import type { ModelErrorHistory, ModelResolution } from "../model/index.ts";
-import type { AgentStats, AgentTransport } from "../transport/index.ts";
-import type { AskOptions, Handle, ResolvedSpawnOptions, StructuredAskOptions } from "../types.ts";
+import type { AgentStats, AgentTransport, CompactionResult } from "../transport/index.ts";
+import type { AskOptions, ForkOptions, Handle, ResolvedSpawnOptions, StructuredAskOptions } from "../types.ts";
+import type { ForkSpawner } from "./fork.ts";
 /** The mid-Ask Model Resolution one Agent's spawn handed it (ADR-0038). */
 export interface AgentModelFallback {
     readonly resolution: ModelResolution;
@@ -24,6 +25,10 @@ export interface AgentOptions {
      * Absent when the spawn named no candidate: there is nothing to fall back from.
      */
     readonly modelFallback?: AgentModelFallback;
+    /** pi's session file for this Agent; a fork copies it. Absent during playback. */
+    readonly sessionFile?: string;
+    /** Opens a fork of this Agent through the Run's spawn gate (ADR-0044). */
+    readonly fork?: ForkSpawner;
     /** Definition-owned defaults merged below explicit per-Ask options. */
     readonly askDefaults?: AskOptions;
     /** Definition identity recorded on its Asks, outside replay identity. */
@@ -46,6 +51,10 @@ export declare class Agent implements Handle {
     get model(): string;
     ask<Schema extends TSchema>(prompt: string, options: StructuredAskOptions<Schema>): Promise<Static<Schema>>;
     ask(prompt: string, options?: AskOptions): Promise<string>;
+    /** Replaces this Agent's context with a summary of it (ADR-0043). */
+    compact(instructions?: string): Promise<CompactionResult>;
+    /** Spawns a new Agent from a copy of this Agent's session (ADR-0044). */
+    fork(overrides?: ForkOptions): Promise<Handle>;
     /** True when the Agent was killed mid-Ask, so its cost is a floor (ADR-0012). */
     get incomplete(): boolean;
     /** Shuts the Agent down and reports its cost. Idempotent. */

package/assets/types/runtime/agent/fork.d.ts

@@ -0,0 +1,43 @@
+import type { WorktreeResolution } from "../transport/index.ts";
+import type { ForkOptions, Handle, ResolvedSpawnOptions, SpawnOptions } from "../types.ts";
+/** What one Agent hands the spawn gate when it is forked (ADR-0044). */
+export interface ForkSource {
+    readonly name: string;
+    /** The options the source settled on; the verbatim inheritance base. */
+    readonly spawnOptions: ResolvedSpawnOptions;
+    /** pi's session file for the source; a fork without one is refused. */
+    readonly sessionFile: string | undefined;
+    readonly worktree: WorktreeResolution | undefined;
+    /** Settled Asks of the source at the fork point. */
+    readonly settledAsks: number;
+    /** The source Handle itself, which becomes the fork's default Parent Link. */
+    readonly handle: Handle;
+}
+/** Opens one fork. The spawn gate owns it, so a fork walks the normal spawn path. */
+export type ForkSpawner = (source: ForkSource, overrides?: ForkOptions) => Promise<Handle>;
+/** Spawn identity and launch facts that only a fork carries. */
+export interface ForkIdentity {
+    readonly forkOf: string;
+    readonly forkAsks: number;
+    /** The session pi copies with `--fork`; machine-specific, never identity. */
+    readonly forkSession: string;
+    readonly worktreeFrom?: WorktreeResolution;
+}
+/** One fork request: what to spawn, whose child it is, and whether to compact it. */
+export interface ForkRequest {
+    /** Inherited options with the overrides applied; never carries `name`. */
+    readonly spawnOptions: SpawnOptions;
+    /** The raw Parent Link, defaulting to the fork source. */
+    readonly parent: unknown;
+    readonly fork: ForkIdentity;
+    readonly compact: boolean | string | undefined;
+}
+/**
+ * Merges a fork source with explicit overrides into one spawn request.
+ *
+ * Inheritance is verbatim, with two deliberate exceptions: `name` is dropped,
+ * so the child gets a fresh auto-name unless the overrides give it one, and
+ * `compact` never reaches the spawn options, because it is a fork verb rather
+ * than a property of the Agent.
+ */
+export declare function forkRequest(source: ForkSource, overrides?: ForkOptions): ForkRequest;

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

@@ -4,4 +4,5 @@
  */
 export { Agent } from "./agent.ts";
 export { type AgentConfig, type AgentDefinition, agentDefinitionConfig, defineAgent, isAgentDefinition, } from "./define-agent.ts";
+export { type ForkSource, type ForkSpawner, forkRequest } from "./fork.ts";
 export { makeSpawn } from "./spawn.ts";

package/assets/types/runtime/agent/spawn-open.d.ts

@@ -0,0 +1,31 @@
+import type { AskOptions, Handle, SpawnOptions } from "../types.ts";
+import type { ForkIdentity, ForkSpawner } from "./fork.ts";
+import type { SpawnDependencies } from "./spawn.ts";
+/** One request the open path serves: a plain spawn, or a fork of another Agent. */
+export interface OpenAgentRequest {
+    /** Never carries `parent`: a Handle must not reach the recorded options. */
+    readonly spawnOptions: SpawnOptions;
+    /** The raw Parent Link option, validated by `resolveParent`. */
+    readonly parent: unknown;
+    readonly askDefaults: AskOptions | undefined;
+    /** Definition identity stays separate from a topology-overridden Agent name. */
+    readonly definitionName: string | undefined;
+    /** Present only for a fork; adds `origin: "fork"` and the `--fork` source. */
+    readonly fork?: ForkIdentity;
+}
+/** What the open path needs beyond the Run's spawn dependencies. */
+export interface OpenAgentContext extends SpawnDependencies {
+    /** Agent names already allocated in this Run. */
+    readonly taken: Set<string>;
+    /** How an opened Agent forks itself later. */
+    readonly forkSpawner: ForkSpawner;
+}
+/**
+ * Opens one Agent: resolves extensions and a model, starts its transport, and
+ * emits `agent_spawn`.
+ *
+ * A fork walks this very path, so the Tool Contract probe, Model Resolution,
+ * the worktree wrapper and the Cassette identity cannot drift between a spawn
+ * and a fork (ADR-0044).
+ */
+export declare function openAgent(deps: OpenAgentContext, request: OpenAgentRequest): Promise<Handle>;

package/assets/types/runtime/agent/spawn-parent.d.ts

@@ -0,0 +1,11 @@
+import type { Agent } from "./agent.ts";
+/**
+ * Resolves a Parent Link to the parent Agent's name.
+ *
+ * Only a Handle this Run already spawned is accepted, which is what makes a
+ * lineage cycle impossible by construction: a Handle exists only after its own
+ * spawn resolved. Liveness is deliberately not checked — a cleanly exited Agent
+ * remains a valid parent, because the link states tree position, not a
+ * dependency on a live process.
+ */
+export declare function resolveParent(parent: unknown, agents: readonly Agent[]): string | undefined;

package/assets/types/runtime/agent/spawn-request.d.ts

@@ -1,5 +1,5 @@
 import type { ModelSelection } from "../model/index.ts";
-import type { OpenOptions } from "../transport/index.ts";
+import type { OpenOptions, WorktreeResolution } from "../transport/index.ts";
 import type { ResolvedSpawnOptions, SpawnOptions } from "../types.ts";
 /** Everything one spawn needs to build its open request, before a model settles. */
 export interface OpenRequestOptions {
@@ -8,6 +8,14 @@ export interface OpenRequestOptions {
     readonly spawnOptions: SpawnOptions;
     readonly resolvedExtensionPaths?: readonly string[];
     readonly declaredExtensions?: readonly string[];
+    /** Resolved parent Agent name (Parent Link); spawn identity only, never argv. */
+    readonly parent?: string;
+    /** Fork facts (ADR-0044); the first three are spawn identity, the rest are not. */
+    readonly origin?: "fork";
+    readonly forkOf?: string;
+    readonly forkAsks?: number;
+    readonly forkSession?: string;
+    readonly worktreeFrom?: WorktreeResolution;
     readonly sessionDir: string | undefined;
 }
 /**

package/assets/types/runtime/agent/spawn.d.ts

@@ -2,7 +2,7 @@ import type { ConfigExtension } from "../config/index.ts";
 import type { EventSink } from "../events.ts";
 import type { RunContext } from "../run/index.ts";
 import type { TransportFactory } from "../transport/index.ts";
-import { Agent } from "./agent.ts";
+import type { Agent } from "./agent.ts";
 /** Dependencies for one Run's Agent-spawn gate. */
 export interface SpawnDependencies {
     readonly factory: TransportFactory;

package/assets/types/runtime/cassette/cassette-replay.d.ts

@@ -1,4 +1,4 @@
-import type { AgentStats, AskMarker, AskPlayback, Frame } from "../transport/index.ts";
+import type { AgentStats, AskMarker, AskPlayback, CompactionMarker, CompactionPlayback, Frame } from "../transport/index.ts";
 import type { CassetteAgent } from "./cassette.ts";
 /**
  * Replays one Cassette Agent's frame streams at the transport seam.
@@ -19,6 +19,14 @@ export declare class CassetteReplay {
     frames(): AsyncIterable<Frame>;
     /** Moves playback to an Ask that its caller has already identity-checked. */
     beginAsk(marker: AskMarker): AskPlayback;
+    /**
+     * Moves playback to a compaction its caller has already identity-checked.
+     *
+     * A compaction lives between two Asks, and `beginAsk` never switches the
+     * cursors back to the Agent-level streams, so the recorded compaction owns
+     * its own streams (ADR-0043).
+     */
+    beginCompaction(marker: CompactionMarker): CompactionPlayback;
     /** Ends the stream cleanly, allowing a caller to switch to another source. */
     finish(): void;
 }

package/assets/types/runtime/cassette/cassette-schema.d.ts

@@ -31,6 +31,10 @@ export declare const CassetteSchema: Type.TObject<{
             cwd: Type.TString;
             worktree: Type.TOptional<Type.TLiteral<true>>;
             declaredExtensions: Type.TOptional<Type.TArray<Type.TString>>;
+            parent: Type.TOptional<Type.TString>;
+            origin: Type.TOptional<Type.TLiteral<"fork">>;
+            forkOf: Type.TOptional<Type.TString>;
+            forkAsks: Type.TOptional<Type.TNumber>;
         }>;
         model: Type.TString;
         sessionFile: Type.TOptional<Type.TString>;
@@ -99,6 +103,25 @@ export declare const CassetteSchema: Type.TObject<{
             }>>;
             recovered: Type.TOptional<Type.TLiteral<true>>;
         }>>;
+        compactions: Type.TOptional<Type.TArray<Type.TObject<{
+            index: Type.TNumber;
+            hash: Type.TString;
+            afterAsks: Type.TNumber;
+            result: Type.TOptional<Type.TObject<{
+                tokensBefore: Type.TUnion<[Type.TNull, Type.TNumber]>;
+                tokensAfter: Type.TUnion<[Type.TNull, Type.TNumber]>;
+                tokens: Type.TUnion<[Type.TNull, Type.TObject<{
+                    input: Type.TNumber;
+                    output: Type.TNumber;
+                    cacheRead: Type.TNumber;
+                    cacheWrite: Type.TNumber;
+                    total: Type.TNumber;
+                }>]>;
+                cost: Type.TUnion<[Type.TNull, Type.TNumber]>;
+            }>>;
+            sentFrames: Type.TArray<Type.TUnsafe<Frame>>;
+            receivedFrames: Type.TArray<Type.TUnsafe<Frame>>;
+        }>>>;
         stats: Type.TObject<{
             tokens: Type.TUnion<[Type.TNull, Type.TObject<{
                 input: Type.TNumber;

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

@@ -1,7 +1,7 @@
 import type { CanonicalJsonObject } from "../ask-contract/index.ts";
 import type { AskLimitOutcome, AskStalledOutcome } from "../errors.ts";
 import type { RunOutcome } from "../events.ts";
-import type { AgentStats, AskCompletion, AskInvalidOutputPlayback, AskMarker, AskMarkerContext, Frame, OpenOptions, WorktreeResolution } from "../transport/index.ts";
+import type { AgentStats, AskCompletion, AskInvalidOutputPlayback, AskMarker, AskMarkerContext, CompactionMarker, CompactionResult, Frame, OpenOptions, WorktreeResolution } from "../transport/index.ts";
 import type { ThinkingLevel } from "../types.ts";
 /** The Cassette format this runtime writes; the loader also reads version 1. */
 export declare const CASSETTE_VERSION: 2;
@@ -45,8 +45,21 @@ export interface CassetteAgent {
     readonly sentFrames: readonly Frame[];
     readonly receivedFrames: readonly Frame[];
     readonly asks: readonly CassetteAsk[];
+    /** Compactions between this Agent's Asks; absent for an Agent that compacted none. */
+    readonly compactions?: readonly CassetteCompaction[];
     readonly stats: AgentStats;
 }
+/** The frames attributed to one compaction marker (ADR-0043). */
+export interface CassetteCompaction {
+    readonly index: number;
+    readonly hash: string;
+    /** Settled Asks of this Agent at the compaction point. */
+    readonly afterAsks: number;
+    /** What the recorded compaction reported; absent when the exchange failed. */
+    readonly result?: CompactionResult;
+    readonly sentFrames: readonly Frame[];
+    readonly receivedFrames: readonly Frame[];
+}
 /** Behavioural identity supplied when opening a recorded Agent. */
 export interface CassetteSpawn {
     readonly name: string;
@@ -72,6 +85,17 @@ export interface CassetteSpawn {
      * across machines (ADR-0040). Absent when the Agent ran no extension.
      */
     readonly declaredExtensions?: readonly string[];
+    /**
+     * Resolved name of the Agent named as this Agent's parent (Parent Link).
+     * Part of spawn identity; absent for a root Agent and for older Cassettes.
+     */
+    readonly parent?: string;
+    /** How the Agent came to be; absent means an ordinary spawn. Spawn identity. */
+    readonly origin?: "fork";
+    /** Name of the Agent this one was forked from. Spawn identity. */
+    readonly forkOf?: string;
+    /** Settled Asks of the fork source at the fork point. Spawn identity. */
+    readonly forkAsks?: number;
 }
 /** The frames attributed to one Ask marker. */
 export interface CassetteAsk {
@@ -117,6 +141,8 @@ export interface CassetteRecorder {
     received(frame: Frame): void;
     beginAsk(marker: AskMarker): void;
     finishAsk(completion: AskCompletion): void;
+    beginCompaction(marker: CompactionMarker): void;
+    finishCompaction(result: CompactionResult | undefined): void;
     closed(stats: AgentStats): void;
 }
 /** Collects a Cassette in memory; `executeRun` serializes it at Run settlement. */

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

@@ -2,7 +2,7 @@
  * Public surface of the `cassette/` module: record, replay, checkpoint, and resume.
  * Files inside this directory import each other directly.
  */
-export { CASSETTE_VERSION, type Cassette, type CassetteAgent, type CassetteArtifact, type CassetteAsk, CassetteCollector, type CassetteGit, type CassetteRun, type CassetteSink, type CassetteSpawn, } from "./cassette.ts";
+export { CASSETTE_VERSION, type Cassette, type CassetteAgent, type CassetteArtifact, type CassetteAsk, CassetteCollector, type CassetteCompaction, type CassetteGit, type CassetteRun, type CassetteSink, type CassetteSpawn, } from "./cassette.ts";
 export { assertReplayable, interruptedResumeWarning, loadCassette } from "./cassette-loader.ts";
 export { publishCassette } from "./cassette-publish.ts";
 export { checkpointFileName, cleanStaleCheckpointTemp, resolveCheckpointDirectory, } from "./checkpoint-dir.ts";

package/assets/types/runtime/cassette/replay-divergence.d.ts

@@ -1,8 +1,8 @@
-import type { AskMarker, OpenOptions, RecordedSpawnSelection } from "../transport/index.ts";
+import type { AskMarker, CompactionMarker, OpenOptions, RecordedSpawnSelection } from "../transport/index.ts";
 import type { CassetteAgent, CassetteSpawn } from "./cassette.ts";
 /** A pure description of the first strict replay identity mismatch. */
 export interface ReplayMismatch {
-    readonly kind: "unexpected-spawn" | "spawn-options" | "changed-ask" | "extra-ask";
+    readonly kind: "unexpected-spawn" | "spawn-options" | "changed-ask" | "extra-ask" | "changed-compaction" | "extra-compaction";
     readonly agent: string;
     readonly index?: number;
     readonly expectedHash: string;
@@ -14,6 +14,7 @@ export interface ReplayMismatch {
 export declare const replayMismatch: {
     spawn(expected: CassetteAgent | null, actual: OpenOptions): ReplayMismatch | null;
     ask(agent: CassetteAgent, cursor: number, actual: AskMarker): ReplayMismatch | null;
+    compaction(agent: CassetteAgent, cursor: number, actual: CompactionMarker): ReplayMismatch | null;
 };
 /** Converts a detected mismatch into strict replay's public failure. */
 export declare function strictReplay(mismatch: ReplayMismatch): never;

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

@@ -30,7 +30,7 @@ export interface ModelResolutionOutcome {
     readonly modelErrors: readonly ModelError[];
 }
 /** 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" | "CONFIG_INVALID" | "OPTIONS_CONFLICT" | "RECORD_PATH_UNUSABLE" | "REPLAY_DIVERGED" | "RESUME_REFUSED" | "RUN_CLOSED" | "RUN_STOPPED" | "WORKTREE_REFUSED" | "MODEL_RESOLUTION_FAILED" | "SPAWN_FAILED";
+export type YaagErrorCode = "AGENT_FAILED" | "AGENT_DIED" | "AGENT_BUSY" | "ASK_TIMEOUT" | "ASK_LIMIT" | "ASK_STALLED" | "COMPACT_DURING_ASK" | "COMPACT_FAILED" | "FORK_DURING_ASK" | "FORK_REFUSED" | "ASK_INVALID_OUTPUT" | "ARGS_INVALID" | "CONFIG_INVALID" | "OPTIONS_CONFLICT" | "RECORD_PATH_UNUSABLE" | "REPLAY_DIVERGED" | "RESUME_REFUSED" | "RUN_CLOSED" | "RUN_STOPPED" | "WORKTREE_REFUSED" | "MODEL_RESOLUTION_FAILED" | "SPAWN_FAILED";
 /** The single error class of the runtime (ADR-0003). */
 export declare class YaagError extends Error {
     readonly code: YaagErrorCode;

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

@@ -17,6 +17,11 @@ export type { ModelErrorReason } from "./model/index.ts";
  * settled Run never writes it (ADR-0031).
  */
 export type RunOutcome = "completed" | "failed" | "stopped" | "paused" | "interrupted";
+/**
+ * How an Agent came to be. An absent value on an event means "spawn"; "fork"
+ * marks an Agent created from a copy of another Agent's session (ADR-0044).
+ */
+export type SpawnOrigin = "spawn" | "fork";
 /** The current, Ask-scoped observer projection derived from Agent frames. */
 export type AgentActivity = {
     readonly type: "thinking";
@@ -65,6 +70,10 @@ export type LifecycleEventBody = {
      * Cassette-playback Agents and events from older CLIs.
      */
     readonly sessionFile?: string;
+    /** Resolved name of the Agent named as this Agent's parent (Parent Link). */
+    readonly parent?: string;
+    /** How the Agent came to be; absent means "spawn". */
+    readonly origin?: SpawnOrigin;
 } | {
     readonly type: "ask_start";
     readonly agent: string;
@@ -150,6 +159,30 @@ export type LifecycleEventBody = {
     readonly tokens: TokenBreakdown;
     /** Cumulative assistant-completion cost observed so far. */
     readonly cost: number;
+} | {
+    /**
+     * One compaction of an Agent's context (ADR-0043).
+     *
+     * It carries the summary call's own spend, so a Run Summary does not
+     * silently lose it. `agent_exit` stays authoritative for the Agent's
+     * total: pi's `get_session_stats` already includes compaction spend.
+     * The custom instructions never ride the wire (ticket 09); only the
+     * `custom` flag says that the program supplied some.
+     */
+    readonly type: "agent_compaction";
+    readonly agent: string;
+    /** Monotonic per Agent, from 0. */
+    readonly index: number;
+    /** Context tokens before the summary replaced the transcript; null when unknown. */
+    readonly tokensBefore: number | null;
+    /** Estimated context tokens after the summary; null when unknown. */
+    readonly tokensAfter: number | null;
+    /** The summary call's own token breakdown; null when unknown. */
+    readonly tokens: TokenBreakdown | null;
+    /** The summary call's own cost; null when unknown. */
+    readonly cost: number | null;
+    /** The program supplied custom compaction instructions. */
+    readonly custom: boolean;
 } | {
     readonly type: "agent_exit";
     readonly agent: string;

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

@@ -1,21 +1,21 @@
 export type { AgentConfig, AgentDefinition } from "./agent/index.ts";
 export { agentDefinitionConfig, defineAgent, isAgentDefinition } from "./agent/index.ts";
-export type { Cassette, CassetteAgent, CassetteArtifact, CassetteAsk, CassetteGit, CassetteRun, CassetteSink, CassetteSpawn, } from "./cassette/index.ts";
+export type { Cassette, CassetteAgent, CassetteArtifact, CassetteAsk, CassetteCompaction, CassetteGit, CassetteRun, CassetteSink, CassetteSpawn, } from "./cassette/index.ts";
 export { assertReplayable, CASSETTE_VERSION, loadCassette, recordingTransport, replayTransport, resumeTransport, } from "./cassette/index.ts";
 export type { ConfigEnvironment, ConfigExtension, ConfigLayerName, EffectiveConfig, EffectiveConfigRequest, } from "./config/index.ts";
 export { EMPTY_EFFECTIVE_CONFIG, loadEffectiveConfig, PROJECT_CONFIG_DIR, } from "./config/index.ts";
 export type { AskInvalidOutputOutcome, AskLimitKind, AskLimitOutcome, AskStalledOutcome, ModelResolutionOutcome, 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 { AgentActivity, AskOutputChannel, EventSink, LifecycleEvent, LifecycleEventBody, NodeState, NodeUsage, SpawnOrigin, StampedEventSink, } from "./events.ts";
 export type { ModelError, ModelErrorReason, ModelResolver, ModelSelection, ModelSpec, ThinkingResolver, ThinkingSpec, } from "./model/index.ts";
 export type { DecodedNode, NodeDecoder, NodePath, NodeSnapshot } from "./node/index.ts";
 export { agentAskPath, childPath, DEFAULT_NODE_DECODERS, NodeTracker, sanitizeNodeName, } from "./node/index.ts";
 export { prompt, promptGist } from "./prompt/index.ts";
 export type { OrchestrationProgram, ProgramDefinition, RunContext, RunOptions, } from "./run/index.ts";
 export { defineRun, executeRun, isOrchestrationProgram, programDefinition } from "./run/index.ts";
-export type { AgentInfo, AgentState, AskingAgentInfo, EndedRunSummary, ExitedAgentInfo, IdleAgentInfo, ModelFallbackInfo, NodeInfo, RunningRunSummary, RunOutcome, RunState, RunSummary, } from "./summary/index.ts";
+export type { AgentInfo, AgentState, AskingAgentInfo, CompactionInfo, EndedRunSummary, ExitedAgentInfo, IdleAgentInfo, ModelFallbackInfo, NodeInfo, RunningRunSummary, RunOutcome, RunState, RunSummary, } from "./summary/index.ts";
 export { applyEvent, initialSummary } from "./summary/index.ts";
-export type { AgentStats, AgentTransport, AskMarker, AskMarkerContext, AskPlayback, DiscoveredSkill, Frame, ReapPath, ReapTarget, SkillProbeFactory, TokenBreakdown, TransportFactory, TransportStartup, TransportStartupObserver, WorktreeResolution, } from "./transport/index.ts";
+export type { AgentStats, AgentTransport, AskMarker, AskMarkerContext, AskPlayback, CompactionMarker, CompactionPlayback, CompactionResult, DiscoveredSkill, Frame, ReapPath, ReapTarget, SkillProbeFactory, TokenBreakdown, TransportFactory, TransportStartup, TransportStartupObserver, WorktreeResolution, } from "./transport/index.ts";
 export { readSystemPromptSidecar, reap, worktreeTransport } from "./transport/index.ts";
-export type { AskOptions, Handle, ResolvedSpawnOptions, SpawnOptions, SpawnOverrides, StructuredAskOptions, ThinkingLevel, } from "./types.ts";
+export type { AskOptions, ForkOptions, Handle, ResolvedSpawnOptions, 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";

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

@@ -3,4 +3,4 @@
  * Files inside this directory import each other directly.
  */
 export { applyEvent, type EndedRunSummary, initialSummary, type RunningRunSummary, type RunOutcome, type RunState, type RunSummary, } from "./summary.ts";
-export type { AgentInfo, AgentState, AskingAgentInfo, ExitedAgentInfo, IdleAgentInfo, ModelFallbackInfo, NodeInfo, } from "./summary-agent.ts";
+export type { AgentInfo, AgentState, AskingAgentInfo, CompactionInfo, ExitedAgentInfo, IdleAgentInfo, ModelFallbackInfo, NodeInfo, SpawnOrigin, } from "./summary-agent.ts";

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

@@ -1,10 +1,18 @@
-import type { AgentActivity } from "../events.ts";
+import type { AgentActivity, SpawnOrigin } from "../events.ts";
 import type { TokenBreakdown, WorktreeResolution } from "../transport/index.ts";
 import type { ModelFallbackInfo } from "./summary-fallbacks.ts";
 import type { NodeInfo } from "./summary-nodes.ts";
-export type { AgentActivity } from "../events.ts";
+export type { AgentActivity, SpawnOrigin } from "../events.ts";
 export type { ModelFallbackInfo } from "./summary-fallbacks.ts";
 export type { NodeInfo } from "./summary-nodes.ts";
+/** What one compaction of an Agent's context reported (ADR-0043). */
+export interface CompactionInfo {
+    readonly tokensBefore: number | null;
+    readonly tokensAfter: number | null;
+    /** The summary call's own cost, already included in `agent_exit` accounting. */
+    readonly cost: number | null;
+    readonly at: number | null;
+}
 /** The observer-facing lifecycle state of an Agent. */
 export type AgentState = "idle" | "asking" | "exited";
 /** Identity and accounting facts that apply in every observer Agent state. */
@@ -19,6 +27,10 @@ interface AgentInfoBase {
     readonly branch: string | null;
     /** pi's session file for this Agent, when the spawn reported one; a Peek reads it. */
     readonly sessionFile: string | null;
+    /** The Agent named as this one's parent (Parent Link), or null for a root Agent. */
+    readonly parent: string | null;
+    /** How the Agent came to be; "spawn" until forking ships. */
+    readonly origin: SpawnOrigin;
     readonly activity: AgentActivity | null;
     readonly tokens: TokenBreakdown | null;
     readonly cost: number | null;
@@ -27,6 +39,10 @@ interface AgentInfoBase {
     /** Timestamp ordering only cumulative live accounting, never lifecycle state. */
     readonly usageUpdatedAt: number | null;
     readonly askStartedAt: number | null;
+    /** Compactions of this Agent's context so far (ADR-0043). */
+    readonly compactions: number;
+    /** What the newest compaction reported, or null when the Agent compacted none. */
+    readonly lastCompaction: CompactionInfo | null;
     /** This Agent's bounded Nested Node table, in first-seen order (spec §3). */
     readonly nodes: readonly NodeInfo[];
     /** Exited Nested Nodes dropped to keep the table bounded. */
@@ -90,6 +106,8 @@ export declare function spawnAgent(current: AgentRecord | undefined, identity: {
     readonly cwd: string;
     readonly branch?: string;
     readonly sessionFile?: string;
+    readonly parent?: string;
+    readonly origin?: SpawnOrigin;
 }, at: number | null): AgentRecord;
 /**
  * Folds an Ask start into the asking arm when it is not older than the folded
@@ -123,6 +141,15 @@ export declare function endAsk(current: AgentRecord | undefined, settlement: Ask
  * stream order while older stamped observations are ignored.
  */
 export declare function setUsage(current: AgentRecord | undefined, observation: AgentUsageObservation, at: number | null): AgentRecord;
+/**
+ * Counts one compaction and keeps what it reported.
+ *
+ * It folds no cost: the summary call's spend reaches the Summary through
+ * `agent_usage`, and `agent_exit` stays authoritative (ADR-0043). A terminal
+ * Agent still counts a late compaction, because the count is a fact about the
+ * conversation rather than a lifecycle state.
+ */
+export declare function compactAgent(current: AgentRecord | undefined, observation: CompactionInfo, at: number | null): AgentRecord;
 /**
  * Folds authoritative shutdown accounting into the terminal Agent state.
  *

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

@@ -2,7 +2,7 @@ import type { LifecycleEvent, LifecycleEventBody, RunOutcome } from "../events.t
 import type { TokenBreakdown } from "../transport/index.ts";
 import type { AgentInfo } from "./summary-agent.ts";
 export type { NodeState, NodeUsage, RunOutcome } from "../events.ts";
-export type { AgentActivity, AgentInfo, AgentState, AskingAgentInfo, ExitedAgentInfo, IdleAgentInfo, ModelFallbackInfo, NodeInfo, } from "./summary-agent.ts";
+export type { AgentActivity, AgentInfo, AgentState, AskingAgentInfo, CompactionInfo, ExitedAgentInfo, IdleAgentInfo, ModelFallbackInfo, NodeInfo, SpawnOrigin, } from "./summary-agent.ts";
 /** The observer-facing lifecycle state of a Run. */
 export type RunState = "running" | "ended";
 /** Accounting and identity facts shared by all Run observer states. */
@@ -24,6 +24,8 @@ interface RunSummaryBase {
     readonly worstFrameGapMs: number;
     /** Run-wide Model Resolution fallbacks, pruned per-Agent entries included. */
     readonly modelFallbacks: number;
+    /** Compactions across every Agent of this Run (ADR-0043). */
+    readonly compactions: number;
 }
 /** A Run that has not settled; it has neither outcome nor compatibility result. */
 export interface RunningRunSummary extends RunSummaryBase {

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

@@ -1,5 +1,5 @@
 import type { AvailableModel } from "../model/index.ts";
-import type { AgentStats, AgentTransport, AskMarker, Frame } from "./transport.ts";
+import type { AgentStats, AgentTransport, AskMarker, CompactionMarker, Frame } from "./transport.ts";
 /**
  * Scripted frame playback for one prompt sent through a FakeTransport.
  *
@@ -41,6 +41,10 @@ export interface FakeTransportOptions extends FakePromptScript {
     readonly steerError?: string;
     /** Makes an abort RPC response fail without embedding a limit decision in playback. */
     readonly abortError?: string;
+    /** Payload of a `compact` command response; omission answers a bare success. */
+    readonly compaction?: Record<string, unknown>;
+    /** Makes a `compact` command response fail, as pi does when it cannot summarize. */
+    readonly compactError?: string;
     /** Makes the private report_result schema command fail. */
     readonly schemaCommandError?: string;
     /** The snapshot answered to `get_available_models`; defaults to this fake's own model. */
@@ -73,11 +77,14 @@ export declare class FakeTransport implements AgentTransport {
     /** Everything the runtime wrote, in order. */
     readonly sent: Frame[];
     readonly asks: AskMarker[];
+    readonly compactions: CompactionMarker[];
     constructor(options?: FakeTransportOptions);
     send(frame: Frame): void;
     frames(): AsyncIterable<Frame>;
     beginAsk(marker: AskMarker): undefined;
     finishAsk(): void;
+    beginCompaction(marker: CompactionMarker): undefined;
+    finishCompaction(): void;
     /** True once the runtime shut this Agent down. */
     get closed(): boolean;
     /** Number of times this fake actually began close work. */

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

@@ -9,11 +9,11 @@ export { FrameGapTracker } from "./frame-gap.ts";
 export { FrameQueue } from "./frame-queue.ts";
 export { decodeFrames } from "./jsonl.ts";
 export { liveTransport } from "./live-transport.ts";
-export { type AgentProgress, piCommand, readAgentProgress } from "./pi-state.ts";
+export { type AgentProgress, piCommand, readAgentProgress, readCompaction, } from "./pi-state.ts";
 export { type ReapPath, type ReapTarget, reap } from "./reap.ts";
 export { type DiscoveredSkill, liveSkillProbe, type SkillProbeFactory } from "./skill-probe.ts";
 export { skillRestrictionTransport } from "./skill-restriction-transport.ts";
 export { readSystemPromptSidecar } from "./system-prompt-recorder.ts";
 export { SYSTEM_PROMPT_SIDECAR_SUFFIX, systemPromptSidecarPath, } from "./system-prompt-recorder-extension.ts";
-export type { AgentStats, AgentTransport, AskCompletion, AskInvalidOutputPlayback, AskMarker, AskMarkerContext, AskPlayback, Frame, OpenOptions, TokenBreakdown, TransportFactory, TransportStartup, TransportStartupObserver, WorktreeResolution, } from "./transport.ts";
+export type { AgentStats, AgentTransport, AskCompletion, AskInvalidOutputPlayback, AskMarker, AskMarkerContext, AskPlayback, CompactionMarker, CompactionPlayback, CompactionResult, Frame, OpenOptions, TokenBreakdown, TransportFactory, TransportStartup, TransportStartupObserver, WorktreeResolution, } from "./transport.ts";
 export { worktreeTransport } from "./worktree-transport.ts";

package/assets/types/runtime/transport/pi-state.d.ts

@@ -1,4 +1,4 @@
-import type { AgentStats, Frame, OpenOptions } from "./transport.ts";
+import type { AgentStats, CompactionResult, Frame, OpenOptions } from "./transport.ts";
 /** What the Agent reported about its own work, read from a `get_state` probe. */
 export interface AgentProgress {
     /** True while pi streams a completion, compacts its context, or holds a queued prompt. */
@@ -49,3 +49,10 @@ export declare function readSessionFile(response: Frame): string | null;
  * distinguishable (ADR-0012); a partial breakdown is treated as unknown.
  */
 export declare function readStats(response: Frame): AgentStats;
+/**
+ * What a `compact` response reports (ADR-0043).
+ *
+ * A missing field becomes null rather than 0, so "unknown" and "free" stay
+ * distinguishable: a custom compaction handler may answer without usage.
+ */
+export declare function readCompaction(response: Frame): CompactionResult;

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

@@ -29,6 +29,22 @@ export interface AgentStats {
     readonly tokens: TokenBreakdown | null;
     readonly cost: number | null;
 }
+/**
+ * What one compaction of an Agent's context reported (ADR-0043).
+ *
+ * Every field is null when pi reported nothing for it: a custom compaction
+ * handler may answer without usage, and "unknown" must stay distinct from 0.
+ */
+export interface CompactionResult {
+    /** Context tokens before the summary replaced the transcript. */
+    readonly tokensBefore: number | null;
+    /** Estimated context tokens after the summary replaced the transcript. */
+    readonly tokensAfter: number | null;
+    /** Token breakdown of the summary call itself. */
+    readonly tokens: TokenBreakdown | null;
+    /** Cost of the summary call itself. */
+    readonly cost: number | null;
+}
 /** Recorded inputs used to explain an Ask-hash mismatch without changing identity. */
 export interface AskMarkerContext {
     readonly prompt: string;
@@ -72,6 +88,25 @@ export interface AskCompletion {
     /** The Stall Watchdog settled this Ask from observed state (ADR-0029). */
     readonly recovered?: true;
 }
+/**
+ * Opaque marker naming one compaction of an Agent's context.
+ *
+ * A compaction sits between two Asks, so it cannot ride the Agent-level frame
+ * streams: a Cassette replay switches those cursors to an Ask and never
+ * switches back. The marker gives the exchange its own recorded streams.
+ */
+export interface CompactionMarker {
+    /** Monotonic per Agent, from 0. */
+    readonly index: number;
+    /** sha256 of the settled-Ask count and the custom instructions, when given. */
+    readonly hash: string;
+    /** Settled Asks of this Agent at the compaction point. */
+    readonly afterAsks: number;
+}
+/** Presence identifies Cassette playback of one compaction. */
+export interface CompactionPlayback {
+    readonly result: CompactionResult;
+}
 /** Presence identifies Cassette playback, including recorded successful Asks. */
 export interface AskPlayback {
     /** Limit outcome recorded for this Ask, if it rejected with ASK_LIMIT. */
@@ -116,6 +151,13 @@ export interface AgentTransport {
     beginAsk(marker: AskMarker): AskPlayback | undefined;
     /** Reports surfaced live outcomes; replay ignores completion. */
     finishAsk(completion: AskCompletion): void;
+    /**
+     * Begins one compaction. Live transports return undefined; replay transports
+     * return the recorded result.
+     */
+    beginCompaction(marker: CompactionMarker): CompactionPlayback | undefined;
+    /** Ends the compaction exchange, so later frames belong to the Agent again. */
+    finishCompaction(result: CompactionResult | undefined): void;
     /**
      * The extraction policy recorded for the Ask at `index`, when a Cassette
      * backs it. An Ask recorded under an older policy keeps that policy, so its
@@ -162,10 +204,31 @@ export interface OpenOptions {
      * Spawn identity only: it never becomes argv, and it is absent when empty.
      */
     readonly declaredExtensions?: readonly string[];
+    /**
+     * Resolved name of the Agent named as this Agent's parent (Parent Link).
+     * Spawn identity only: it never becomes argv.
+     */
+    readonly parent?: string;
     /** Session storage directory. Used by the e2e suite to stay out of ~/.pi (ticket 06). */
     readonly sessionDir?: string;
     /** Resumes an existing pi session, translated to `--session <path>`. */
     readonly sessionFile?: string;
+    /** How the Agent came to be; absent means an ordinary spawn. Spawn identity. */
+    readonly origin?: "fork";
+    /** Name of the Agent this one was forked from. Spawn identity; never argv. */
+    readonly forkOf?: string;
+    /** Settled Asks of the fork source at the fork point. Spawn identity. */
+    readonly forkAsks?: number;
+    /**
+     * The fork source's session file, translated to `pi --fork <path>`.
+     * Never spawn identity: the path is machine-specific.
+     */
+    readonly forkSession?: string;
+    /**
+     * The fork source's worktree, so the fork branches from it instead of from a
+     * clean base tree. Never spawn identity.
+     */
+    readonly worktreeFrom?: WorktreeResolution;
 }
 /** Nondeterministic worktree identity resolved below the transport seam. */
 export interface WorktreeResolution {

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

@@ -1,6 +1,8 @@
 import type { Static, TSchema } from "typebox";
 import type { ModelSpec, ThinkingLevel, ThinkingSpec } from "./model/index.ts";
+import type { CompactionResult } from "./transport/index.ts";
 export type { ThinkingLevel } from "./model/index.ts";
+export type { CompactionResult } from "./transport/index.ts";
 /** Options for spawning one Agent (ADR-0001, ADR-0009, ADR-0026). */
 export interface SpawnOptions {
     /** Working directory. Defaults to the Orchestrator's cwd. */
@@ -64,17 +66,44 @@ export interface SpawnOptions {
     readonly name?: string;
     /** Request a fresh Git worktree. The requested cwd remains the base until spawn resolves. */
     readonly worktree?: boolean;
+    /**
+     * Names this Agent's parent in the Run tree (Parent Link). Data only: it is
+     * no conversation channel and no lifetime rule.
+     */
+    readonly parent?: Handle;
 }
 /**
  * Spawn options after Model Resolution has settled one model and thinking level.
  *
  * This is the settled shape, and it is what the Cassette identity hashes
  * (ADR-0039).
+ *
+ * `parent` is omitted on purpose: a Handle must never reach this shape, because
+ * an Ask records these options into the Cassette. Spawn resolves the Parent
+ * Link to a name, which travels in `OpenOptions` and stays out of Ask identity.
  */
-export interface ResolvedSpawnOptions extends Omit<SpawnOptions, "model" | "thinking"> {
+export interface ResolvedSpawnOptions extends Omit<SpawnOptions, "model" | "thinking" | "parent"> {
     readonly model?: string;
     readonly thinking?: ThinkingLevel;
 }
+/**
+ * What a fork may change about the Agent it copies (ADR-0044).
+ *
+ * A fork inherits the source's resolved spawn options verbatim: model,
+ * thinking, tools, skills, system prompt, extensions and Ask defaults. `name`
+ * is the exception — the child always gets a fresh auto-name unless this object
+ * names one. The fork source becomes the child's default `parent`.
+ *
+ * The inherited model is the concrete one the source settled on, so the child
+ * never re-runs the source's fallback list; `fork({ model })` is the way out.
+ * A fork of a Worktree Agent gets its own fresh worktree, branched from the
+ * source's branch, so only committed state transfers. The child re-runs the
+ * ADR-0026 Tool Contract probe against its own effective options.
+ */
+export interface ForkOptions extends SpawnOptions {
+    /** true = pi's default compaction; a string = pi custom instructions. */
+    readonly compact?: boolean | string;
+}
 /** Topology-only fields that may change when spawning an Agent Definition. */
 export interface SpawnOverrides {
     /** Log and event label. Defaults to the definition's name; duplicates are suffixed. */
@@ -83,6 +112,8 @@ export interface SpawnOverrides {
     readonly cwd?: string;
     /** Request a fresh Git worktree. */
     readonly worktree?: boolean;
+    /** Names this Agent's parent in the Run tree (Parent Link). Data only. */
+    readonly parent?: Handle;
 }
 /**
  * Options for one Ask (ADR-0003).
@@ -179,4 +210,23 @@ export interface Handle {
      */
     ask<Schema extends TSchema>(prompt: string, options: StructuredAskOptions<Schema>): Promise<Static<Schema>>;
     ask(prompt: string, options?: AskOptions): Promise<string>;
+    /**
+     * Spawns a new Agent from a copy of this Agent's session (ADR-0044).
+     *
+     * The fork point is a settled Ask boundary: a call while an Ask is in flight
+     * rejects with `FORK_DURING_ASK`. An Agent that died mid-Ask, or that holds
+     * no session file, rejects with `FORK_REFUSED`. An Agent that exited cleanly
+     * stays forkable, so a program can build context, let the Agent exit, then
+     * fork its final state many times.
+     */
+    fork(overrides?: ForkOptions): Promise<Handle>;
+    /**
+     * Replaces this Agent's context with a summary of it (ADR-0043).
+     *
+     * `instructions` becomes pi's `customInstructions`. A call while an Ask is in
+     * flight rejects with `COMPACT_DURING_ASK`; a refusal from pi rejects with
+     * `COMPACT_FAILED`. The result reports what the summary call cost; each field
+     * is null when pi reported nothing for it.
+     */
+    compact(instructions?: string): Promise<CompactionResult>;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yaag/cli",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "publishConfig": {
     "access": "public"
   },
@@ -21,8 +21,8 @@
   },
   "dependencies": {
     "@earendil-works/pi-tui": "^0.84.0",
-    "@yaag/runtime": "0.9.0",
-    "@yaag/tui": "0.9.0",
+    "@yaag/runtime": "0.11.0",
+    "@yaag/tui": "0.11.0",
     "typebox": "1.3.7"
   }
 }

package/src/terminal/render.ts

@@ -24,7 +24,7 @@ function renderPlainEvent(event: LifecycleEventBody, mode: PlainRenderMode): str
     case "run_start":
       return `[yaag] run ${event.program}`;
     case "agent_spawn":
-      return `[${event.agent}] spawned ${event.model} in ${event.cwd}`;
+      return `[${event.agent}] ${event.origin === "fork" ? "forked" : "spawned"} ${event.model} in ${event.cwd}${event.parent === undefined ? "" : ` under ${event.parent}`}`;
     case "ask_start":
       return `[${event.agent}] ask #${event.index + 1}${event.replayed === true ? " (replayed)" : ""}${event.promptGist === "" ? "" : ` — ${event.promptGist}`}`;
     case "ask_activity":
@@ -43,6 +43,8 @@ function renderPlainEvent(event: LifecycleEventBody, mode: PlainRenderMode): str
       return `[${event.agent}] model ${event.failedModel} ${event.reason} — falling back to ${event.resolvedModel}`;
     case "agent_model":
       return `[${event.agent}] model \u2014 now running ${event.model}`;
+    case "agent_compaction":
+      return `[${event.agent}] compacted ${contextTokens(event.tokensBefore)} → ${contextTokens(event.tokensAfter)}${event.custom ? " (custom)" : ""} ${cost(event.cost)}`;
     case "agent_exit":
       return `[${event.agent}] exit ${tokens(event.tokens)} ${cost(event.cost)}${event.incomplete ? " (killed mid-ask, cost incomplete)" : ""}`;
     case "run_end": {
@@ -64,6 +66,7 @@ function minimalEvent(type: LifecycleEventBody["type"]): boolean {
     type === "ask_end" ||
     type === "model_fallback" ||
     type === "agent_model" ||
+    type === "agent_compaction" ||
     type === "agent_exit" ||
     type === "run_end"
   );
@@ -97,6 +100,11 @@ function tokens(value: TokenBreakdown | null): string {
   return value === null ? "tokens unknown" : `${value.total} tokens`;
 }
 
+/** Context size at one end of a compaction; a compaction may report neither. */
+function contextTokens(value: number | null): string {
+  return value === null ? "?" : `${value} tokens`;
+}
+
 function cost(value: number | null): string {
   return value === null ? "cost unknown" : `$${value.toFixed(4)}`;
 }