@wrongstack/core 0.284.0 → 0.285.0

package/dist/core/context.d.ts

@@ -0,0 +1,269 @@
+import type { TextBlock } from '../types/blocks.js';
+import type { Message } from '../types/messages.js';
+import type { Provider, Usage } from '../types/provider.js';
+import type { SessionWriter } from '../types/session.js';
+import type { ContextEvidenceState } from '../types/context-evidence.js';
+import type { TokenCounter } from '../types/token-counter.js';
+import type { Tool } from '../types/tool.js';
+import { ConversationState } from './conversation-state.js';
+import type { RunEnv } from './run-env.js';
+export interface TodoItem {
+    id: string;
+    content: string;
+    status: 'pending' | 'in_progress' | 'completed';
+    activeForm?: string | undefined;
+    /** When promoted from a plan item, stores the plan item's id. */
+    promotedFromPlan?: string | undefined;
+    /** When promoted from a task, stores the task's id. */
+    promotedFromTask?: string | undefined;
+}
+export interface RunOptions {
+    signal?: AbortSignal | undefined;
+    model?: string | undefined;
+    executionStrategy?: 'parallel' | 'sequential' | 'smart' | undefined;
+    maxIterations?: number | undefined;
+    /**
+     * Enable autonomous continue for this specific run. When true, the agent
+     * loop re-runs on `[continue]`/`[next step]`/`[proceed]` markers or
+     * `continue_to_next_iteration()` tool calls instead of returning.
+     * Overrides `AgentInit.autonomousContinue` for this call only.
+     */
+    autonomousContinue?: boolean | undefined;
+}
+export interface ContextInit {
+    systemPrompt: TextBlock[];
+    provider: Provider;
+    session: SessionWriter;
+    signal: AbortSignal;
+    tokenCounter: TokenCounter;
+    cwd: string;
+    projectRoot: string;
+    /** Mutable working directory. Defaults to `cwd`. Must stay within `projectRoot`. */
+    workingDir?: string | undefined;
+    /**
+     * When false, file tools and `setWorkingDir()` are confined to `projectRoot`.
+     * Defaults to `false` (restrictive) when omitted so directly-constructed
+     * contexts (tests, embedded callers) keep the safe behavior; the runtime
+     * passes the config-derived value (default `true` — permissive) explicitly.
+     */
+    allowOutsideProjectRoot?: boolean | undefined;
+    model: string;
+    tools?: Tool[] | undefined;
+    /** Agent id performing this run (e.g. 'leader', 'executor', 'tech-stack'). */
+    agentId?: string | undefined;
+    /** Human-readable agent name. */
+    agentName?: string | undefined;
+    /**
+     * Session-level trace ID for correlating storage events with agent
+     * iterations in observability pipelines. Stored on the SessionWriter
+     * so that storage operations can emit it in `storage.*` events.
+     * When set, the Context constructor propagates it to
+     * `session.traceId` automatically.
+     */
+    traceId?: string | undefined;
+}
+/**
+ * L1-A: `Context` is the live agent-run object. Its read-only environment
+ * shape is exposed by the `RunEnv` interface (every field below the
+ * conversation state) and its mutable shape by `ConversationState` (the
+ * `state` accessor). New code should declare the narrower type at its
+ * parameter — pass `ctx` for it. Existing tools that accept `Context`
+ * still work because `Context` structurally satisfies both.
+ *
+ * The single source of truth for the project directory is `projectRoot`.
+ * All tools (read/write/bash/exec) resolve paths relative to this.
+ * Sessions, config, memory, and logs are also stored under this root.
+ *
+ * There IS a mutable `workingDir` (separate from `projectRoot`) that can be
+ * changed at runtime via `setWorkingDir()`. It starts as `cwd` and allows
+ * the agent and user to navigate within the project without spawning a new
+ * process. All changes must stay inside `projectRoot`.
+ */
+export declare class Context implements RunEnv {
+    messages: Message[];
+    todos: TodoItem[];
+    /**
+     * Files whose content the **user / model has explicitly seen** via the
+     * `read` tool (or an edit's auto-read, which surfaces the content to the
+     * model). This is the set the permission policy's write-smart-bypass
+     * (step 7) checks — writing a file the model has already read is treated
+     * as "no new content to approve". It must NEVER contain files only touched
+     * by `edit`/`write`, otherwise the model could repeatedly overwrite a file
+     * whose content the user never saw (P1 #1, before-release.md).
+     *
+     * Tool-driven mutations record via `writtenFiles` + `recordRead(..., 'write')`
+     * so mtime tracking still works without widening the bypass.
+     */
+    readFiles: Set<string>;
+    /**
+     * Files written by `edit`/`write` in this session. Tracked for observability
+     * and to keep `readFiles` (the permission-bypass source of truth) clean.
+     * `recordRead(path, mtime, 'write')` adds here instead of `readFiles`.
+     */
+    writtenFiles: Set<string>;
+    fileMtimes: Map<string, number>;
+    /**
+     * sha-256 (hex) of file content at the last recorded read/write, when the
+     * recording tool had the content in hand. Used by `edit` as the authoritative
+     * staleness arbiter: mtime comparison has a 2 s tolerance window on Windows
+     * (FAT/NTFS granularity) during which an external modification is invisible,
+     * and conversely a bare `touch` bumps mtime without changing content. Hash
+     * equality resolves both cases exactly. Entries are dropped whenever a
+     * hash-less `recordRead` observes a *different* mtime (content may have
+     * changed under us — fall back to the mtime heuristic rather than trust a
+     * stale hash).
+     */
+    fileHashes: Map<string, string>;
+    /**
+     * Structured side-effect records accumulated during the current run
+     * (P2 #5). Populated by `recordSideEffect()` — read by /diag for an
+     * in-memory audit trail without parsing the JSONL file. Cleared by
+     * `clearFileTracking()` alongside read/written-file tracking.
+     */
+    sideEffects: import('../types/side-effect.js').SideEffect[];
+    contextEvidence: ContextEvidenceState;
+    systemPrompt: TextBlock[];
+    provider: Provider;
+    session: SessionWriter;
+    signal: AbortSignal;
+    tokenCounter: TokenCounter;
+    cwd: string;
+    projectRoot: string;
+    /** Mutable working directory — starts as `cwd`. Change via `setWorkingDir()`. */
+    workingDir: string;
+    /**
+     * When true, file tools (via `_util.ts`) and `setWorkingDir()` reject paths
+     * outside `projectRoot`. When false, those boundary checks are bypassed so
+     * tools may reach paths outside the project (still gated by permission
+     * tiers). Mutable so `/settings` can toggle it live on the running session.
+     */
+    allowOutsideProjectRoot: boolean;
+    model: string;
+    tools: Tool[];
+    meta: Record<string, unknown>;
+    /** Agent id performing this run (e.g. 'leader', 'executor'). */
+    agentId: string;
+    /** Human-readable agent name. */
+    agentName: string;
+    /**
+     * Session-level trace ID for correlating storage events with agent
+     * iterations. Stored here and also propagated to `session.traceId`
+     * so storage operations can include it in `storage.*` events.
+     */
+    traceId: string | undefined;
+    /** Callbacks fired when `setWorkingDir()` changes the working directory. */
+    private _onWorkingDirChanged;
+    /**
+     * Set to true when the conversation gains new tool_use or tool_result
+     * blocks — the only time repairToolUseAdjacency() can find new issues.
+     * buildAndRunRequestPipeline() checks this flag to skip an O(n) scan
+     * on iterations where no tool content was added (pure text responses).
+     */
+    toolAdjacencyDirty: boolean;
+    /**
+     * H1: pre-computed total-request token estimate from the most recent
+     * `estimateRequestTokens()` call in the agent loop's pre-flight step.
+     * The middleware that decides when to compact, the `emitContextPct`
+     * helper that drives the live context-fill bar, and the pre-flight
+     * itself all need this number; previously each one walked the same
+     * messages/system/tools arrays independently. Stashing it here lets
+     * the three call sites share a single compute per iteration.
+     *
+     * The value is the **uncalibrated** total. Callers that want the
+     * calibrated number apply the per-(provider,model) ratio themselves.
+     */
+    lastRequestTokens: number | undefined;
+    constructor(init: ContextInit);
+    /**
+     * Observable wrapper over the mutable conversation state. Lazy so
+     * subsystems that don't subscribe pay nothing. Mutations made directly
+     * on `ctx.messages` / `ctx.todos` are still visible through this
+     * wrapper's read API (it holds a reference, not a copy) but only
+     * mutations that go through `state.appendMessage()` etc. fire
+     * `onChange`. New code should prefer the wrapper API.
+     */
+    private _state;
+    get state(): ConversationState;
+    /**
+     * Register a teardown hook tied to the current run's abort signal.
+     * Hooks registered before a run starts are stored and fired when the
+     * next run ends; there is no immediate fire when no run is active.
+     *
+     * **Scope:** these hooks fire on the **whole agent run's** abort, not on
+     * an individual tool call. For per-tool teardown of resources owned by
+     * the tool author (child processes, handles), prefer `Tool.cleanup` —
+     * see its JSDoc for the full rule.
+     */
+    private abortHooks;
+    registerAbortHook(fn: () => void | Promise<void>): () => void;
+    drainAbortHooks(): Promise<void>;
+    /**
+     * Record that a file's content was seen / mtime was observed.
+     *
+     * `source` controls which tracking set is populated — and therefore whether
+     * the permission policy's write-smart-bypass (step 7) will auto-approve a
+     * subsequent `write` to this path:
+     *
+     * - `'user'` (default): the model/user saw the content (via `read`, or an
+     *   edit's auto-read that surfaced it). Adds to `readFiles` → bypass applies.
+     * - `'write'`: a tool wrote the file (`edit`/`write`) and is recording the
+     *   new mtime so subsequent edits detect external modification. Adds to
+     *   `writtenFiles` only — the bypass does NOT apply, because the user never
+     *   approved the new content (P1 #1, before-release.md).
+     *
+     * `fileMtimes` is updated in both cases so mtime-based staleness checks work.
+     *
+     * `contentHash` (sha-256 hex of the exact content seen) is optional so
+     * existing callers keep working. When provided it is stored in `fileHashes`
+     * and becomes the authoritative staleness arbiter for later edits. When
+     * omitted, a previously stored hash survives only if the observed mtime is
+     * unchanged — a different mtime with no fresh hash means the content may
+     * have changed, so the stale hash is dropped and staleness checks fall back
+     * to mtime comparison.
+     */
+    recordRead(absPath: string, mtimeMs: number, source?: 'user' | 'write', contentHash?: string): void;
+    /** Clear accumulated file-read metadata after compaction or at boundaries
+     *  where stale read history could cause tools to skip legitimate re-reads.
+     *  The agent re-populates this naturally on the next file access. */
+    clearFileTracking(): void;
+    /**
+     * Record a structured side effect for the audit trail (P2 #5).
+     * Called by tools that perform non-filesystem mutations (bash, install,
+     * fetch) so /diag and session replay can show what the agent did beyond
+     * file edits.
+     *
+     * Unlike recordFileChange(), this does NOT support undo — it is purely
+     * for observability and audit. The event is appended to the session
+     * JSONL fire-and-forget; errors are swallowed so recording never blocks
+     * tool execution.
+     */
+    recordSideEffect(sideEffect: import('../types/side-effect.js').SideEffect): void;
+    /**
+     * True if the model/user has explicitly seen this file's content via `read`
+     * (or an edit auto-read). Tool-only writes (`source: 'write'`) do NOT count
+     * — this is the source of truth for the permission policy's write bypass.
+     */
+    hasRead(absPath: string): boolean;
+    /** True if `edit`/`write` wrote this file in the current session. */
+    hasWritten(absPath: string): boolean;
+    lastReadMtime(absPath: string): number | undefined;
+    /** sha-256 (hex) of the content at the last recorded read/write, if the
+     *  recording tool supplied one. See `fileHashes` for drop semantics. */
+    lastReadHash(absPath: string): string | undefined;
+    /**
+     * Change the working directory for path resolution. Resolves relative paths
+     * against `projectRoot` and validates the result is within the project root.
+     * Fires all registered `onWorkingDirChanged` callbacks.
+     * Returns the resolved absolute path.
+     */
+    setWorkingDir(dir: string): string;
+    /**
+     * Register a callback that fires when the working directory changes.
+     * Returns an unsubscribe function. Callbacks are fired synchronously
+     * inside `setWorkingDir()` — errors in callbacks are swallowed so one
+     * bad listener doesn't prevent others from executing.
+     */
+    onWorkingDirChanged(cb: (newDir: string, oldDir: string) => void): () => void;
+    usage(): Usage;
+}
+//# sourceMappingURL=context.d.ts.map

package/dist/core/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/core/context.ts"],"names":[],"mappings":"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"}

package/dist/core/continue-intent.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Continue-intent detection + continuation resolution.
+ *
+ * ## Problem
+ *
+ * Users frequently type a bare "continue" (or "devam", "go on", "keep going")
+ * to nudge the agent forward without supplying any new instruction. On its own
+ * that word carries no information about *what* to continue — the model has to
+ * re-derive "what was next" from history, which drifts as the context window is
+ * compacted. Left unanchored, a run of "continue … continue … continue" turns
+ * into an ever-vaguer manual loop: the model repeats work, declares completion
+ * prematurely, or wanders.
+ *
+ * ## Approach
+ *
+ * A bare "continue" is not new information — it points at an *existing* goal.
+ * So instead of asking the model to remember a hidden per-message marker, we
+ * resolve the continuation against the state we already keep:
+ *
+ *   1. **Open todos** — the strongest, most durable anchor. Survives context
+ *      compaction (todos are re-injected each turn) and goal.json persistence.
+ *      "continue" = resume the next open todo.
+ *   2. **Parsed `<nextsteps>` suggestions** — the menu surfaced after the last
+ *      completed turn (already extracted and stored by the surface's
+ *      suggestion store). "continue" = do suggestion #1.
+ *   3. **Open continuation** — no explicit task is queued, but the user still
+ *      wants work to proceed. We inject an instruction that tells the model to
+ *      pick the single most valuable next step itself and carry it out — while
+ *      explicitly forbidding fabricated busywork. This is what keeps "continue"
+ *      from ever dead-ending.
+ *
+ * This module is pure and surface-agnostic: detection takes the raw string,
+ * resolution takes already-collected data (todos + parsed suggestion strings).
+ * The REPL and TUI wire it in at the point where a user message becomes an
+ * agent run, *before* prompt refinement — a bare "continue" has nothing
+ * meaningful to refine, and refining it would only add latency and drift.
+ *
+ * The three triggers of the same continuation machinery — the user typing
+ * "continue", the model emitting the `[continue]` marker (see
+ * {@link parseContinueDirective}), and an autonomy tick — all ultimately want
+ * the same thing: advance the plan. This module is the manual-trigger path.
+ */
+import type { TodoItem } from './context.js';
+/**
+ * True when `raw` is a bare "continue"-style nudge and nothing else.
+ *
+ * Strict by construction: the message must normalize to exactly one of
+ * {@link CONTINUE_PHRASES}. Anything with additional substance ("continue but
+ * skip tests", "go on to the next file and commit") normalizes to a string
+ * outside the set and returns false, so it is handled as an ordinary message.
+ */
+export declare function detectContinueIntent(raw: string): boolean;
+/**
+ * Where the resolved continuation came from:
+ *   - `todo`       — resumed the next open todo (strongest anchor)
+ *   - `suggestion` — took the top parsed `<nextsteps>` suggestion
+ *   - `open`       — no explicit task queued; model self-determines the step
+ */
+export type ContinuationSource = 'todo' | 'suggestion' | 'open';
+export interface ContinuationInput {
+    /** Live todo list (`ctx.todos`). */
+    todos?: readonly TodoItem[] | undefined;
+    /** Already-parsed `<nextsteps>` suggestion strings from the surface store. */
+    suggestions?: readonly string[] | undefined;
+}
+export interface ResolvedContinuation {
+    source: ContinuationSource;
+    /**
+     * The concrete instruction injected as the next user turn in place of the
+     * bare "continue". Written for the model, not the human.
+     */
+    text: string;
+    /**
+     * Short one-line label for the surface to echo (dim) so the human sees what
+     * "continue" resolved to without the full injected paragraph.
+     */
+    label: string;
+}
+/**
+ * Resolve what a bare "continue" should do, given the current run state.
+ *
+ * The ladder — first match wins:
+ *   1. an open todo (in-progress preferred, else the first pending),
+ *   2. the top stored suggestion,
+ *   3. an open continuation that never dead-ends.
+ *
+ * Always returns a usable {@link ResolvedContinuation}; the `open` branch is
+ * the guaranteed fallback so "continue" keeps work moving even with no todos
+ * and no suggestions.
+ */
+export declare function resolveContinuation(input: ContinuationInput): ResolvedContinuation;
+//# sourceMappingURL=continue-intent.d.ts.map

package/dist/core/continue-intent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"continue-intent.d.ts","sourceRoot":"","sources":["../../src/core/continue-intent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAGH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AA8H7C;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CASzD;AAID;;;;;GAKG;AACH,MAAM,MAAM,kBAAkB,GAAG,MAAM,GAAG,YAAY,GAAG,MAAM,CAAC;AAEhE,MAAM,WAAW,iBAAiB;IAChC,oCAAoC;IACpC,KAAK,CAAC,EAAE,SAAS,QAAQ,EAAE,GAAG,SAAS,CAAC;IACxC,8EAA8E;IAC9E,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;CAC7C;AAED,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,kBAAkB,CAAC;IAC3B;;;OAGG;IACH,IAAI,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAC;CACf;AAQD;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,iBAAiB,GAAG,oBAAoB,CAgDlF"}

package/dist/core/continue-to-next-iteration.d.ts

@@ -0,0 +1,96 @@
+/**
+ * L1-E: Autonomous continue — model-driven self-iteration continuation.
+ *
+ * In autonomous mode the model can signal "keep going without waiting for
+ * user input" by either:
+ *
+ *  1. **Tool call** — call `continue_to_next_iteration()` with no args.
+ *     The tool returns `{ continue: true }` and sets
+ *     `ctx.meta._autonomousContinue = true`. The agent loop detects this
+ *     flag and re-runs the iteration instead of returning.
+ *
+ *  2. **Text marker** — include one of the below markers on its own line
+ *     in the final text output (no tool call required):
+ *
+ *     - `[continue]`          — same as calling the tool; next iteration
+ *     - `[next step]`        — synonym for `[continue]`
+ *     - `[proceed]`          — synonym for `[continue]`
+ *     - `[done]`             — stop iterating; return to caller
+ *
+ *     The parser matches `^\s*(?:\[continue\]|\[next step\]|\[proceed\]|\[done\])\s*$`
+ *     so the marker must occupy its own line (possibly indented).
+ *
+ * Text markers are checked in `processResponse()` BEFORE the loop exit
+ * condition, so the model can emit `[continue]` as part of its final text
+ * block and the loop re-runs seamlessly.
+ *
+ * The `_autonomousContinue` flag lives in `ctx.meta` — it is cleared at
+ * the start of each iteration so a stale flag from a prior run cannot
+ * cause spurious continuation.
+ *
+ * @example
+ * ```typescript
+ * // Enable autonomous continuation on the Agent
+ * const agent = new Agent({
+ *   // ... other options
+ *   autonomousContinue: true,   // enable text-marker parsing
+ * });
+ *
+ * // The model can now end a response with:
+ * //   [continue]
+ * // and the agent will immediately start the next iteration without
+ * // returning to the caller.
+ * ```
+ */
+import type { Context } from './context.js';
+import type { Tool } from '../types/tool.js';
+/**
+ * Directive emitted by the model to control the autonomous loop.
+ *
+ * `continue`  — halt the current agent.run() and signal to the outer
+ *                runner (e.g. AutonomousRunner) that it should re-invoke
+ *                agent.run() immediately with a fresh continuation prompt.
+ *
+ * `stop`      — halt and signal the outer runner to NOT continue.
+ *                The agent.run() returns `{ status: 'done' }` as normal.
+ *
+ * `none`      — no directive present; outer runner uses its own
+ *                `doneCondition` to decide.
+ */
+export type ContinueDirective = 'continue' | 'stop' | 'none';
+/**
+ * Parse a `ContinueDirective` from raw assistant text.
+ *
+ * Matches markers on their own line (with optional leading/trailing
+ * whitespace). Case-insensitive. Returns `'none'` when no marker found.
+ *
+ * The marker must be on its own line to avoid false positives — e.g.
+ * "remember to use [continue] in your next email" does NOT trigger it.
+ */
+export declare function parseContinueDirective(text: string): ContinueDirective;
+/**
+ * Set the autonomous continue flag in the context.
+ * Called by `makeContinueToNextIterationTool` when the model invokes it.
+ */
+export declare function setAutonomousContinue(ctx: Context): void;
+/**
+ * Clear the autonomous continue flag at the start of each iteration.
+ * Called from `Agent.run()` before the loop body.
+ */
+export declare function clearAutonomousContinue(ctx: Context): void;
+/**
+ * Read and clear the autonomous continue flag in one call.
+ * Returns `true` if the flag was set; `false` otherwise.
+ */
+export declare function consumeAutonomousContinue(ctx: Context): boolean;
+/**
+ * Built-in tool that lets the model explicitly request the next iteration.
+ *
+ * When called, the agent loop detects the flag and re-runs instead of
+ * returning to the caller. This is the explicit counterpart to the
+ * `[continue]` text marker.
+ *
+ * The tool has no side effects and returns `{ continue: true }`.
+ */
+export declare function makeContinueToNextIterationTool(): Tool;
+//# sourceMappingURL=continue-to-next-iteration.d.ts.map

package/dist/core/continue-to-next-iteration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"continue-to-next-iteration.d.ts","sourceRoot":"","sources":["../../src/core/continue-to-next-iteration.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAE5C,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAE7C;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,iBAAiB,GAAG,UAAU,GAAG,MAAM,GAAG,MAAM,CAAC;AAE7D;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,iBAAiB,CAqCtE;AAaD;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,OAAO,GAAG,IAAI,CAExD;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,OAAO,GAAG,IAAI,CAE1D;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAI/D;AAED;;;;;;;;GAQG;AACH,wBAAgB,+BAA+B,IAAI,IAAI,CAqBtD"}

package/dist/core/conversation-state.d.ts

@@ -0,0 +1,96 @@
+import type { ContentBlock } from '../types/blocks.js';
+import type { Message } from '../types/messages.js';
+import type { Context, TodoItem } from './context.js';
+/**
+ * Observable wrapper for mutable conversation state. Production code should
+ * mutate messages, todos, and meta through this API so subscribers see a
+ * deterministic change stream. The underlying Context arrays are still
+ * exposed for read compatibility and legacy tests.
+ *
+ * L1-A invariant: direct mutations of `ctx.messages` / `ctx.todos` bypass
+ * the observer layer. Prefer `ctx.state.appendMessage()` etc. to keep
+ * subscribers in sync. The compatibility arrays exist so existing code
+ * that reads `ctx.messages` directly still works — they are NOT safe for
+ * external writes.
+ */
+export type StateChange = {
+    kind: 'message_appended';
+    message: Message;
+} | {
+    kind: 'messages_replaced';
+    messages: readonly Message[];
+} | {
+    kind: 'message_updated';
+    index: number;
+    message: Message;
+} | {
+    kind: 'todos_replaced';
+    todos: readonly TodoItem[];
+} | {
+    kind: 'meta_set';
+    key: string;
+    value: unknown;
+} | {
+    kind: 'meta_deleted';
+    key: string;
+} | {
+    kind: 'meta_cleared';
+};
+export type StateChangeHandler = (change: StateChange, state: ConversationState) => void;
+export interface ReadonlyConversationState {
+    readonly messages: readonly Message[];
+    readonly todos: readonly TodoItem[];
+    readonly meta: Readonly<Record<string, unknown>>;
+}
+export declare class ConversationState {
+    private readonly ctx;
+    private readonly listeners;
+    private _revision;
+    constructor(ctx: Context);
+    get messages(): readonly Message[];
+    get todos(): readonly TodoItem[];
+    get meta(): Readonly<Record<string, unknown>>;
+    /** Monotonic mutation counter for consumers that need to detect rewrites. */
+    get revision(): number;
+    /**
+     * Cheap immutable snapshot. Useful for tests and for compaction passes
+     * that need a stable view across an async boundary.
+     *
+     * Uses shallow-freeze instead of deep-freeze: only the wrapper object
+     * and the three content arrays are frozen. Individual message/todo
+     * objects are NOT recursively frozen — they are reconstructed via
+     * spread copies and are immutable by convention. This cuts the freeze
+     * count from O(n·m·d) (n=messages, m=content blocks, d=depth) to O(1).
+     */
+    snapshot(): ReadonlyConversationState;
+    appendMessage(message: Message): void;
+    /**
+     * Append a content block to the trailing user message's content array.
+     * Mutates only that one message (a single indexed assignment) — avoids
+     * the O(n) array copy + token-cache re-walk that `replaceMessages()`
+     * would do for a single-message edit. Used by the agent loop to fold
+     * btw-notes / queued-mailbox blocks into the conversation.
+     *
+     * The block is folded only into a *user* message (preserves
+     * user/assistant alternation between tool batches). Returns false when
+     * there is no trailing user message to fold into — callers should
+     * `appendMessage({ role: 'user', content: [block] })` instead.
+     */
+    appendBlockToLastUserMessage(block: ContentBlock): boolean;
+    replaceMessages(messages: Message[]): void;
+    replaceTodos(todos: TodoItem[]): void;
+    setMeta(key: string, value: unknown): void;
+    deleteMeta(key: string): void;
+    clearMeta(): void;
+    /**
+     * Subscribe to mutations that go through this wrapper. Direct mutations of
+     * the compatibility arrays are intentionally not observed.
+     */
+    onChange(listener: StateChangeHandler): () => void;
+    private emit;
+}
+/**
+ * Convenience constructor. The wrapper holds a reference, not a copy.
+ */
+export declare function wrapAsState(ctx: Context): ConversationState;
+//# sourceMappingURL=conversation-state.d.ts.map

package/dist/core/conversation-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conversation-state.d.ts","sourceRoot":"","sources":["../../src/core/conversation-state.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAEpD,OAAO,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAEtD;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,WAAW,GACnB;IAAE,IAAI,EAAE,kBAAkB,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,GAC9C;IAAE,IAAI,EAAE,mBAAmB,CAAC;IAAC,QAAQ,EAAE,SAAS,OAAO,EAAE,CAAA;CAAE,GAC3D;IAAE,IAAI,EAAE,iBAAiB,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,GAC5D;IAAE,IAAI,EAAE,gBAAgB,CAAC;IAAC,KAAK,EAAE,SAAS,QAAQ,EAAE,CAAA;CAAE,GACtD;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,GACjD;IAAE,IAAI,EAAE,cAAc,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GACrC;IAAE,IAAI,EAAE,cAAc,CAAA;CAAE,CAAC;AAE7B,MAAM,MAAM,kBAAkB,GAAG,CAAC,MAAM,EAAE,WAAW,EAAE,KAAK,EAAE,iBAAiB,KAAK,IAAI,CAAC;AAEzF,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,QAAQ,EAAE,SAAS,OAAO,EAAE,CAAC;IACtC,QAAQ,CAAC,KAAK,EAAE,SAAS,QAAQ,EAAE,CAAC;IACpC,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CAClD;AAED,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAU;IAC9B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAiC;IAC3D,OAAO,CAAC,SAAS,CAAK;IAEtB,YAAY,GAAG,EAAE,OAAO,EAEvB;IAED,IAAI,QAAQ,IAAI,SAAS,OAAO,EAAE,CAEjC;IAED,IAAI,KAAK,IAAI,SAAS,QAAQ,EAAE,CAE/B;IAED,IAAI,IAAI,IAAI,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAE5C;IAED,6EAA6E;IAC7E,IAAI,QAAQ,IAAI,MAAM,CAErB;IAED;;;;;;;;;OASG;IACH,QAAQ,IAAI,yBAAyB,CAUpC;IAED,aAAa,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CASpC;IAED;;;;;;;;;;;OAWG;IACH,4BAA4B,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAiBzD;IAED,eAAe,CAAC,QAAQ,EAAE,OAAO,EAAE,GAAG,IAAI,CAiDzC;IAED,YAAY,CAAC,KAAK,EAAE,QAAQ,EAAE,GAAG,IAAI,CAUpC;IAED,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAGzC;IAED,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAI5B;IAED,SAAS,IAAI,IAAI,CAKhB;IAED;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,kBAAkB,GAAG,MAAM,IAAI,CAGjD;IAED,OAAO,CAAC,IAAI;CAWb;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,OAAO,GAAG,iBAAiB,CAE3D"}