indusagi-coding-agent 0.1.62 → 0.2.0

package/dist/types/boot/contract.d.ts

@@ -123,6 +123,8 @@ export interface Invocation {
     readonly prompt?: string;
     /** Explicit model selector from the command line, if any (`--model` / `-m`). */
     readonly modelId?: string;
+    /** Model to fall back to when the bound model is overloaded mid-turn (`--fallback-model`). */
+    readonly fallbackModelId?: string;
     /** Working directory the run is scoped to; absent means the process cwd (`--cwd`). */
     readonly cwd?: string;
     /** Named credential account to authenticate with (`--account`). */

package/dist/types/boot/runners/addon-wiring.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Boot helper: activate the addon host for a session and fold its tool
+ * interceptors around the deck.
+ *
+ * The {@link createAddonHost addon host} is the product's extension mechanism —
+ * locally-authored modules under `<cwd>/.indus/addons` that graft tools, slash
+ * commands, lifecycle observers, and tool-boundary interceptors onto a running
+ * session. The host itself is fully built and tested, but until this module it
+ * was never *instantiated* outside its own unit tests: nothing in the boot path
+ * discovered, loaded, or wired addons.
+ *
+ * This module closes that gap with two narrow seams the runners call once at
+ * session-assembly time:
+ *
+ *   1. {@link buildAddonHost} — construct a host, swallow its fault stream (a
+ *      broken addon must never sink the session), and {@link AddonHost.loadAll
+ *      load} every addon discovered under the run's `.indus/addons` directory.
+ *      With no such directory the returned {@link AddonSurfaceBundle} is empty —
+ *      no interceptors, no contributed tools — so wiring it is a perfect no-op.
+ *   2. {@link wrapToolsWithAddons} — fold the bundle's
+ *      {@link InterceptorChain} around every tool whose name a stage matches,
+ *      leaving the rest identity-equal. A wrapped tool runs the chain's
+ *      `enter` → real `execute` → `exit` reduce; an `enter` block short-circuits
+ *      to an `isError` result without ever invoking the real tool.
+ *
+ * Scope (v1): only the per-tool interceptor boundary is wired. The richer
+ * lifecycle-event fan-out (`session:start`, `turn:end`, …) needs a conductor
+ * seam that does not exist yet and is deferred. The tool interceptor boundary is
+ * the load-bearing one — it is where the Wave 4 permission gate later registers
+ * as a built-in interceptor rather than a parallel mechanism.
+ */
+import { type AddonSurfaceBundle, type AgentTool, type InterceptorChain } from "../../addons";
+import type { BootContext } from "../contract";
+/**
+ * Build and populate the addon host for a run, returning its wired
+ * {@link AddonSurfaceBundle}.
+ *
+ * Constructs a host with an empty {@link FrameworkHandles} bag (v1 supplies no
+ * `exec` handle — the runner has no shell-exec callback to hand an addon — and
+ * the rest are interactive-only), installs a swallow-everything fault sink so a
+ * broken addon degrades silently instead of crashing the boot, then discovers
+ * and loads every addon under `<cwd>/.indus/addons` (the contract's default
+ * {@link ADDONS_DIR}). With no addons directory the bundle is empty and wiring it
+ * downstream is a no-op.
+ *
+ * @param ctx the boot context whose invocation carries the run cwd
+ * @returns the wired bundle (dispatch, interceptors, contributed commands/tools)
+ */
+export declare function buildAddonHost(ctx: BootContext): Promise<AddonSurfaceBundle>;
+/**
+ * Fold a bundle's {@link InterceptorChain} around every tool a stage matches.
+ *
+ * Each tool whose `name` the chain matches is replaced with a wrapper that runs
+ * the chain around its real `execute`; every other tool is returned *identical*
+ * (same object reference) so an empty bundle leaves the deck untouched. The
+ * contributed `bundle.tools` are NOT appended here — the caller concatenates
+ * them (de-duped against the existing deck) before wrapping, so addon tools are
+ * themselves subject to interception.
+ *
+ * @param tools  the run's tool deck (deck + MCP + already-concatenated addon tools)
+ * @param bundle the loaded addon bundle whose interceptor chain wraps the deck
+ * @returns a new array: matched tools wrapped, unmatched tools identity-equal
+ */
+export declare function wrapToolsWithAddons(tools: AgentTool[], bundle: AddonSurfaceBundle): AgentTool[];
+/**
+ * Wrap one tool so its `execute` runs through the interceptor chain.
+ *
+ * The wrapper spreads the original tool (preserving `name` / `description` /
+ * `parameters` / `label` and any extra fields) and overrides only `execute`. The
+ * override:
+ *
+ *   - closes over the live `toolCallId`, `signal`, and `onUpdate` so streaming
+ *     updates and cancellation still reach the real tool (the chain only threads
+ *     the decoded `args`, so these must be captured here);
+ *   - hands the chain a `(args) => realExecute(args)` closure as the inner
+ *     execution and runs `chain.run({ tool, callId, args }, …)`;
+ *   - maps the resulting {@link InterceptResult} back to an
+ *     {@link AgentToolResult}: a `blocked` enter short-circuits to an `isError`
+ *     result carrying the gate's `reason` (the real tool never ran); otherwise
+ *     the chain's (possibly exit-rewritten) `result` is returned.
+ *
+ * The chain — not this wrapper — owns fault isolation and the throw-on-no-recover
+ * semantics, so a tool error that no exit stage recovers propagates exactly as it
+ * would unwrapped.
+ *
+ * @param tool  the real tool to fold the chain around
+ * @param chain the interceptor chain matching this tool's name
+ */
+export declare function wrapOne(tool: AgentTool, chain: InterceptorChain): AgentTool;
+/**
+ * Concatenate an addon bundle's contributed tools onto an existing deck, dropping
+ * any whose name a deck tool already claims.
+ *
+ * The host de-dupes its OWN tools against each other, but not against the product
+ * deck or MCP tools — so an addon tool named `read` would otherwise shadow (or
+ * be appended alongside) the core read tool. This filter keeps the first
+ * claimant (the existing deck) and admits only addon tools with a fresh name.
+ *
+ * @param deck   the existing tool deck (deck + MCP)
+ * @param bundle the loaded addon bundle whose `tools` are appended
+ * @returns the deck followed by the non-conflicting addon tools
+ */
+export declare function concatAddonTools(deck: AgentTool[], bundle: AddonSurfaceBundle): AgentTool[];

package/dist/types/boot/runners/addon-wiring.test.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Addon wiring — boot-time activation of the addon host (item #19).
+ *
+ * These tests exercise the two seams this module adds to the boot path WITHOUT a
+ * real conductor, real jiti, or disk: a fake {@link ModuleLoader} maps a source
+ * path to a scripted {@link AddonManifest}, the host loads it through
+ * `explicitPaths` (which never touches the filesystem), and the resulting bundle
+ * is folded around a synthetic tool deck.
+ *
+ * Four concerns:
+ *   1. An `enter` block short-circuits the call — the wrapper returns an
+ *      `isError` result carrying the gate reason and the real `execute` NEVER
+ *      runs.
+ *   2. An `exit` rewrite replaces the tool's result.
+ *   3. A tool no interceptor matches is returned IDENTITY-equal (the empty-bundle
+ *      / no-addons path is a perfect no-op).
+ *   4. Contributed addon tools are concatenated, de-duped against the deck.
+ */
+export {};

package/dist/types/boot/runners/checkpoint.d.ts

@@ -0,0 +1,133 @@
+/**
+ * Per-session file-checkpoint store — the product half of rewind (#24).
+ *
+ * The framework's mutating file tools (write/edit) consult a host-injected handle
+ * on `ctx.framework` under the string-literal key {@link CHECKPOINT_HANDLE_KEY}.
+ * Immediately before a file is written — and after the read-before-edit gate has
+ * passed — the framework reads the file's CURRENT on-disk content and hands it to
+ * the handle as `record(absPath, previous)`, where `previous` is the old bytes or
+ * `null` when the file did not yet exist. This module supplies the missing host
+ * piece: a store that files those pre-mutation snapshots against the transcript
+ * node that was active when the mutation happened, so a later rewind to that node
+ * can roll the working tree back to exactly that point.
+ *
+ * Design notes:
+ *   - **Keyed by the ACTIVE transcript node id.** Each snapshot is filed under the
+ *     id the conductor pins as the active node (the head leaf at turn start). All
+ *     of a turn's edits therefore land under ONE node id; navigating back to that
+ *     node and restoring reverts the whole turn's file changes at once.
+ *   - **First-seen wins per path within a node.** If the same file is edited twice
+ *     in one turn, only the FIRST snapshot (the content as it was when the node
+ *     became active) is kept. Overwriting it would lose the true pre-turn state,
+ *     so a second `record` of the same path under the same node is ignored. This
+ *     also makes the framework's pre-write `record` idempotent across the multiple
+ *     mutations one tool call may perform.
+ *   - **`null` previous means "file was absent".** Restoring a node whose snapshot
+ *     marks a file `null` DELETES that file (it did not exist at that point), so a
+ *     rewind that created a file is undone by removing it.
+ *   - **Duck-typed handle.** The store implements exactly the framework's
+ *     `CheckpointHandle` shape (`record(absPath, previous: string | null): void`)
+ *     so the host injector and the framework consumer agree by STRING KEY and
+ *     STRUCTURAL SHAPE — no cross-package type import. `ctx.framework` is an open
+ *     record, so the injection typechecks immediately; the framework consumption
+ *     activates after the framework is rebuilt and the product refreshed.
+ *   - **One instance PER SESSION** (minted in `session.ts`), shared across the
+ *     write/edit cards through the single `ctx.framework` bag, and handed to the
+ *     conductor so the conductor can advance the active node id as the head moves.
+ *
+ * Mirrors the read-edit-gate's `ReadStateStore` conventions (`READ_STATE_HANDLE_KEY`,
+ * `createReadStateStore`); both coexist in the SAME `ctx.framework` open bag.
+ */
+/**
+ * The string-literal key under which the host wires this store onto the deck's
+ * `ctx.framework` bag.
+ *
+ * Mirrors the existing `DELEGATE_HANDLE_KEY = "delegate"`,
+ * `MEMORY_HANDLE_KEY = "memoryStore"`, and `READ_STATE_HANDLE_KEY = "readState"`
+ * conventions. The framework's mutating file tools read
+ * `ctx.framework["checkpoint"]` by the same literal, so the two sides agree by
+ * string rather than by a shared imported symbol.
+ */
+export declare const CHECKPOINT_HANDLE_KEY: "checkpoint";
+/**
+ * One file's pre-mutation snapshot: the path that was mutated and the content it
+ * held immediately before. `previous === null` records that the file did not
+ * exist on disk before the mutation, so restoring this snapshot deletes it.
+ */
+export interface FileSnapshot {
+    readonly path: string;
+    readonly previous: string | null;
+}
+/**
+ * Per-session file-checkpoint store, keyed by transcript node id.
+ *
+ * For each node id it holds a map of normalized absolute path → the FIRST-seen
+ * pre-mutation content for that path under that node. The framework calls
+ * {@link record} (via the duck-typed handle) before every write; the host pins
+ * the active node id with {@link setActiveNodeId} as the conductor's head moves;
+ * and {@link restore} rolls the working tree back to a node's recorded state.
+ */
+export declare class CheckpointStore {
+    /** node id → (normalized abs path → first-seen pre-mutation content). */
+    private readonly byNode;
+    /** The transcript node the next {@link record} files its snapshot under. */
+    private current;
+    /** Normalize an absolute path into the store's canonical per-node key. */
+    private key;
+    /** The node id new snapshots are currently filed under (`null` until pinned). */
+    activeNodeId(): string | null;
+    /**
+     * Pin the transcript node subsequent {@link record} calls file snapshots under.
+     *
+     * The conductor calls this as its head advances (at turn start), so all of a
+     * turn's edits key to the node that was active before the turn ran. Passing the
+     * same id again is harmless.
+     *
+     * @param id the active transcript node id, or `null` to fall back to the root
+     */
+    setActiveNodeId(id: string | null): void;
+    /** The node id snapshots are filed under right now (active id or the root). */
+    private resolveNodeId;
+    /**
+     * Capture the pre-mutation content of `absPath` under the active node.
+     *
+     * The framework's duck-typed `CheckpointHandle` entry point. Called once per
+     * mutated path immediately before the write lands, with the file's OLD on-disk
+     * content (or `null` when the file did not exist). First-seen wins: a later
+     * `record` of the same path under the same node is ignored so the snapshot
+     * reflects the file's state when the node became active, not a mid-turn rewrite.
+     *
+     * @param absPath  absolute path of the file about to be written
+     * @param previous the file's content before this mutation, or `null` if absent
+     */
+    record(absPath: string, previous: string | null): void;
+    /**
+     * The recorded snapshots for a node, or `[]` when nothing was tracked there.
+     *
+     * Each entry pairs the normalized absolute path with the content it held before
+     * the node's first mutation of it (`null` = the file was absent).
+     *
+     * @param nodeId the transcript node to read snapshots for
+     */
+    snapshotFor(nodeId: string): readonly FileSnapshot[];
+    /** Whether a node has ANY recorded file snapshot (the picker's restore gate). */
+    hasSnapshot(nodeId: string): boolean;
+    /**
+     * Roll the working tree back to a node's recorded state.
+     *
+     * For each path the node tracked: when its snapshot is a string, the file is
+     * rewritten with that pre-mutation content (creating parent directories as
+     * needed); when the snapshot is `null` the file is DELETED (it did not exist at
+     * that point). Returns the absolute paths that were restored, in record order.
+     *
+     * A safe no-op when the node has no snapshot — navigating to a node that never
+     * mutated files restores nothing. Per-path failures are swallowed so one
+     * unwritable path never aborts the rest of the restore.
+     *
+     * @param nodeId the transcript node whose file state to restore to
+     * @returns the absolute paths that were written or deleted
+     */
+    restore(nodeId: string): string[];
+}
+/** Mint a fresh, empty per-session checkpoint store. */
+export declare function createCheckpointStore(): CheckpointStore;

package/dist/types/boot/runners/checkpoint.test.d.ts

@@ -0,0 +1,12 @@
+/**
+ * CheckpointStore unit tests — the product half of rewind (#24).
+ *
+ * Cover the store's contract in isolation (no framework tools):
+ *   - per-node FIRST-SEEN snapshot (a path's snapshot within one node is never
+ *     overwritten by a later record);
+ *   - keying follows the active node id (set via `setActiveNodeId`);
+ *   - `restore` writes the recorded old content back AND deletes files whose
+ *     snapshot was `null` (absent at that point);
+ *   - `restore` of an untracked node is a safe no-op.
+ */
+export {};

package/dist/types/boot/runners/delegate-runner.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Boot helper: a live {@link DelegateRunner} that makes the `task` tool real.
+ *
+ * The `task` capability ({@link "../../capability-deck/cards/task-card"}) advertises
+ * sub-agent delegation but only *runs* it when a {@link DelegateRunner} is wired
+ * into the deck context under {@link DELEGATE_HANDLE_KEY}; absent one it degrades
+ * to a typed `STUB_NOTE`. This module supplies that runner.
+ *
+ * Each delegated objective spins a *fresh, isolated* framework {@link Agent} (the
+ * same `facade/bot` Agent the conductor already drives — NOT the swarm `Crew` nor
+ * `runtime/createAgent`) bound to the parent's model id and credential resolver,
+ * given a survey-style system prompt and a deck that DELIBERATELY excludes the
+ * `task` card. That exclusion is the recursion guard: a sub-agent with no `task`
+ * tool cannot spawn its own sub-agents. The runner submits one prompt, lets the
+ * sub-agent run its own tool loop to completion, then extracts the final
+ * assistant turn's text as the single report handed back to the parent.
+ *
+ * The runner never throws out of `run()`: a model that does not resolve, a
+ * sub-agent error, or an empty transcript all map to a `{ ok:false, report }`
+ * result so a delegation failure surfaces to the parent agent as an ordinary
+ * tool error rather than crashing the turn. Cancellation is forwarded: an
+ * already-aborted signal short-circuits, and an abort raised mid-run calls
+ * `agent.abort()`.
+ *
+ * The `spawn`/`tools` options are pure test seams — they let a unit test drive
+ * the runner with an in-memory fake instead of a real network round-trip.
+ */
+import { type AgentMessage } from "../../conductor";
+import { type AgentTool } from "../../capability-deck";
+import type { DelegateRunner } from "../../capability-deck/cards/task-card";
+/**
+ * The minimal sub-agent surface the runner drives.
+ *
+ * A real framework {@link Agent} satisfies this structurally; a test passes a
+ * lightweight fake via {@link DelegateRunnerOptions.spawn}. Only the pieces the
+ * runner touches are named — submit a prompt, abort, and read the resulting
+ * transcript/error afterward.
+ */
+export interface DelegateSubAgent {
+    prompt(input: string): Promise<void>;
+    abort(): void;
+    readonly state: {
+        messages: readonly AgentMessage[];
+        error?: string;
+    };
+}
+/** Configuration for {@link createDelegateRunner}. */
+export interface DelegateRunnerOptions {
+    /** The model id the sub-agent runs under (the parent's resolved model). */
+    readonly modelId: string;
+    /** The working directory the sub-agent's deck is scoped to. */
+    readonly cwd: string;
+    /** The system prompt that shapes the sub-agent's behaviour. */
+    readonly system: string;
+    /**
+     * Per-call credential resolver, forwarded to the framework `Agent` unchanged
+     * (OAuth-only providers, short-lived token rotation). Omitted from the agent
+     * options entirely when undefined so the framework env-var lookup still wins.
+     */
+    readonly getApiKey?: (provider: string) => Promise<string | undefined> | string | undefined;
+    /**
+     * Test seam: build the sub-agent from the objective instead of constructing a
+     * real framework `Agent`. When omitted the runner uses `new Agent`.
+     */
+    readonly spawn?: (objective: string, context?: string) => DelegateSubAgent;
+    /**
+     * Test seam: the tool deck the sub-agent runs with. When omitted the runner
+     * provisions the read-only `'authoring'` profile (which already excludes the
+     * `task` card — the recursion guard).
+     */
+    readonly tools?: () => AgentTool[];
+}
+/**
+ * Build a live {@link DelegateRunner} the host wires into the deck context.
+ *
+ * The model is resolved once up front; if the id resolves to nothing the runner
+ * still builds but every `run()` reports `{ ok:false }` rather than throwing, so
+ * a misconfigured model can never crash the parent's turn.
+ *
+ * @param opts the model id, cwd, system prompt, and optional credential/test seams
+ * @returns a runner satisfying the task card's {@link DelegateRunner} contract
+ */
+export declare function createDelegateRunner(opts: DelegateRunnerOptions): DelegateRunner;

package/dist/types/boot/runners/delegate-runner.test.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Delegate-runner wiring (#10 / fixes #9).
+ *
+ * Proves the chain that makes the advertised `task` tool functional: a live
+ * {@link createDelegateRunner} spins an isolated sub-agent, runs one objective,
+ * and reports back the sub-agent's final assistant text; and the `task` card,
+ * given that runner under {@link DELEGATE_HANDLE_KEY}, delegates for real instead
+ * of returning its `STUB_NOTE`.
+ *
+ * Every test drives the runner through the `opts.spawn` / `opts.tools` seams so
+ * no model is resolved and no network is touched.
+ */
+export {};

package/dist/types/boot/runners/memdir.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Durable cross-session memory — a disk-backed working-memory store and the
+ * project-context document that carries it into each session's system prompt.
+ *
+ * The `memory` capability ({@link "../../capability-deck/cards/memory-card"})
+ * already reads a host-injected store from `ctx.framework[MEMORY_HANDLE_KEY]` and
+ * falls back to an in-process buffer when none is wired. This module supplies the
+ * missing piece: a synchronous {@link DiskMemoryStore} that persists the agent's
+ * note to a per-cwd `MEMORY.md` under the profile directory, so a fact written in
+ * one session is still there the next time the agent runs in the same directory.
+ *
+ * The same file is loaded into the briefing as a {@link ContextDoc} ({@link
+ * loadMemoryDoc}) so the model *sees* its prior memory at the top of a fresh
+ * session, not only when it explicitly calls the `memory` tool. The body is
+ * line-and-byte capped by {@link truncateEntrypointContent} so a runaway memory
+ * file cannot bloat the prompt.
+ *
+ * Design notes:
+ *   - The store is STRICTLY SYNCHRONOUS — the {@link MemoryStore} contract the
+ *     card validates is sync (`read`/`replace`/`append` return `void`/`string`),
+ *     and an async store would silently fail that validation and degrade to the
+ *     in-memory fallback.
+ *   - The memory directory is scoped UNDER `workspace.profileDir`, NOT the cwd, so
+ *     persisting memory never writes files into the user's working tree.
+ *   - The cwd is slugged with the SAME regex as {@link "./session".sessionScopeDir}
+ *     so the per-cwd partitioning lines up with the session layout.
+ *   - Files are written `0o600` (owner-only), matching the auth vault — the memory
+ *     note can hold sensitive project facts.
+ */
+import type { ContextDoc } from "../../briefing";
+import { MEMORY_HANDLE_KEY, type MemoryStore } from "../../capability-deck";
+import type { Workspace } from "../contract";
+/** The on-disk filename the durable memory note is stored under. */
+export declare const MEMORY_ENTRYPOINT = "MEMORY.md";
+/** Maximum number of lines of the memory note inlined into the prompt. */
+export declare const MAX_ENTRYPOINT_LINES = 200;
+/**
+ * Maximum bytes of the memory note inlined into the prompt.
+ *
+ * ~125 chars/line at 200 lines: this catches long-line indexes that slip past
+ * the line cap (a few very long lines can be far larger than 200 short ones).
+ */
+export declare const MAX_ENTRYPOINT_BYTES = 25000;
+/**
+ * Cap the memory note to {@link MAX_ENTRYPOINT_LINES} and
+ * {@link MAX_ENTRYPOINT_BYTES}, appending a warning naming which cap fired.
+ *
+ * Line-truncates first (a natural boundary), then byte-truncates at the last
+ * newline before the cap so a line is never cut mid-way. Content within both
+ * caps is returned trimmed and unchanged.
+ *
+ * @param raw the raw memory-file text
+ * @returns the prompt-safe body (possibly with a trailing truncation warning)
+ */
+export declare function truncateEntrypointContent(raw: string): string;
+/**
+ * The per-cwd memory directory under the profile dir: `<profileDir>/memory/--<slug>--`.
+ *
+ * The cwd is slugged — every non-alphanumeric run collapsed to a single dash —
+ * and wrapped in `--…--` markers, the SAME scheme `sessionScopeDir` uses for the
+ * session transcript layout, so the two partitionings line up. The directory
+ * lives under `workspace.profileDir`, never inside the repo, so persisted memory
+ * never pollutes the user's working tree.
+ *
+ * @param workspace the resolved on-disk layout (supplies the profile dir)
+ * @param cwd       the run's working directory
+ */
+export declare function memoryDirFor(workspace: Workspace, cwd: string): string;
+/**
+ * A synchronous, disk-backed {@link MemoryStore} persisting the working-memory
+ * note to `<memDir>/MEMORY.md`.
+ *
+ * Satisfies the `memory` card's narrow three-method port. STRICTLY synchronous:
+ * the card validates that each of `read`/`replace`/`append` is a function and
+ * calls them inline, so any async variant would break the contract and silently
+ * fall back to the in-memory store. Writes create the directory and use mode
+ * `0o600` (owner-only), matching the auth vault.
+ */
+export declare class DiskMemoryStore implements MemoryStore {
+    private readonly memDir;
+    private readonly file;
+    constructor(memDir: string);
+    /** The current note, or `""` when no file has been written yet. */
+    read(): string;
+    /** Overwrite the note, creating the memory directory as needed (mode 0o600). */
+    replace(content: string): void;
+    /** Add a single line to the end of the note (composed of read + replace). */
+    append(line: string): void;
+}
+/**
+ * Load the per-cwd memory note as a {@link ContextDoc} for the briefing's
+ * `# Project context` section, or `undefined` when there is nothing to show.
+ *
+ * An absent file, an empty/whitespace-only note, or any read error yields
+ * `undefined` (no project-context block); a non-empty note is capped by
+ * {@link truncateEntrypointContent} before inlining. The doc's `path` is the
+ * bare `MEMORY.md` label, not the on-disk location, so the heading reads cleanly.
+ *
+ * @param memDir the per-cwd memory directory from {@link memoryDirFor}
+ */
+export declare function loadMemoryDoc(memDir: string): ContextDoc | undefined;
+/** Re-exported so hosts wiring a store can use one import. */
+export { MEMORY_HANDLE_KEY };

package/dist/types/boot/runners/memdir.test.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Durable cross-session memory (memdir, #27).
+ *
+ * Proves the disk-backed memory chain: {@link memoryDirFor} scopes a per-cwd
+ * directory under the profile (never the cwd); {@link DiskMemoryStore} round-trips
+ * the `memory` card's sync `read`/`replace`/`append` to `<memDir>/MEMORY.md` with
+ * owner-only perms; and {@link loadMemoryDoc} surfaces that file as a briefing
+ * {@link ContextDoc} (capped by {@link truncateEntrypointContent}) — absent or
+ * empty for a fresh cwd. Together they let a fact written in one session reappear
+ * in the next session's prompt.
+ */
+export {};

package/dist/types/boot/runners/read-state.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Per-session read-state store — the product half of the read-before-edit gate
+ * (read-edit-gate, #11).
+ *
+ * The framework's file tools (read/write/edit) consult a host-injected handle on
+ * `ctx.framework` under the string-literal key {@link READ_STATE_HANDLE_KEY} to
+ * decide whether an edit/write may proceed: a file must have been read before it
+ * is mutated, and an edit is refused when the file changed on disk since that
+ * read. This module supplies the missing host piece — an in-memory map of which
+ * files have been read this session and the stat fingerprint at read time — so
+ * the gate has somewhere to record and look up that state.
+ *
+ * Design notes:
+ *   - The store is a thin wrapper over a `Map`, keyed by `path.normalize(absPath)`
+ *     so a write and a later lookup of the SAME file agree on one key regardless
+ *     of how the path was spelled (trailing slashes, `.`/`..` segments).
+ *   - One instance is created PER SESSION (in `session.ts` `selectTools`) and
+ *     shared across the read/write/edit cards through the single `ctx.framework`
+ *     bag, so a read recorded by one tool is visible to the gate in another.
+ *   - The record carries the stat fields the framework gate compares against:
+ *     `mtimeMs` (the file's last-modified time at read), `size`, an optional
+ *     `contentHash` for a content-equality fallback, and `readAt` (when the host
+ *     recorded the read). The framework's own stat result exposes the modified
+ *     time as `modifiedMs`; the host normalizes it into `mtimeMs` on the way in,
+ *     so this record is the single agreed shape.
+ *   - The handle key is a bare string literal (mirroring the deck's
+ *     `DELEGATE_HANDLE_KEY` / `MEMORY_HANDLE_KEY`) so the framework consumer and
+ *     this product injector agree WITHOUT a cross-package type import. `ctx.framework`
+ *     is an open record, so the injection typechecks immediately.
+ */
+/**
+ * The string-literal key under which the host wires this store onto the deck's
+ * `ctx.framework` bag.
+ *
+ * Mirrors the existing `DELEGATE_HANDLE_KEY = "delegate"` and
+ * `MEMORY_HANDLE_KEY = "memoryStore"` conventions. The framework's file tools
+ * read `ctx.framework["readState"]` by the same literal, so the two sides agree
+ * by string rather than by a shared imported symbol.
+ */
+export declare const READ_STATE_HANDLE_KEY: "readState";
+/**
+ * One file's read fingerprint, recorded when the agent reads it this session.
+ *
+ *   - `mtimeMs` — the file's last-modified time (ms) at read. The gate refuses an
+ *     edit when the on-disk mtime has advanced past this. (The framework's stat
+ *     result names this `modifiedMs`; the host maps it to `mtimeMs` here.)
+ *   - `size` — the file's byte length at read, a cheap secondary change signal.
+ *   - `contentHash` — optional digest of the content read, for a content-equality
+ *     fallback when the mtime advanced but the bytes are unchanged.
+ *   - `readAt` — when the host recorded this read (ms since epoch).
+ */
+export interface ReadStateRecord {
+    readonly mtimeMs: number;
+    readonly size: number;
+    readonly contentHash?: string;
+    readonly readAt: number;
+}
+/**
+ * In-memory map of read files for one session, keyed by normalized absolute path.
+ *
+ * The framework gate `set`s a record after every read and after every successful
+ * mutation, and `get`s/`has`-checks it before an edit. Keys are normalized in one
+ * place ({@link ReadStateStore.key}) so writes and lookups of the same file land
+ * on the same entry no matter how the caller spelled the path.
+ */
+export declare class ReadStateStore {
+    private readonly entries;
+    /** Normalize an absolute path into the store's canonical key. */
+    private key;
+    /** The recorded read fingerprint for a path, or `undefined` if never read. */
+    get(absPath: string): ReadStateRecord | undefined;
+    /** Record (or replace) the read fingerprint for a path; returns this store. */
+    set(absPath: string, value: ReadStateRecord): this;
+    /** Whether a path has a recorded read fingerprint this session. */
+    has(absPath: string): boolean;
+    /** Drop a path's recorded read fingerprint; returns whether one existed. */
+    delete(absPath: string): boolean;
+    /** Forget every recorded read for this session. */
+    clear(): void;
+}
+/** Mint a fresh, empty per-session read-state store. */
+export declare function createReadStateStore(): ReadStateStore;

package/dist/types/boot/runners/read-state.test.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Per-session read-state store (read-edit-gate, #11, product half).
+ *
+ * Proves the in-memory map the read-before-edit gate records into: records are
+ * keyed by `path.normalize(absPath)` (so differently-spelled paths to the same
+ * file collapse to one entry), `get`/`set`/`has`/`delete`/`clear` round-trip the
+ * `{ mtimeMs, size, contentHash?, readAt }` record, the handle key matches the
+ * literal the framework consumer reads, and each session gets its own store.
+ */
+export {};

package/dist/types/boot/runners/session.d.ts

@@ -8,8 +8,12 @@
  * {@link ModelMatcher}; the conductor itself is built lazily so no framework agent
  * is constructed until the first turn runs.
  */
-import { type SessionConductor } from "../../conductor";
-import type { BootContext } from "../contract";
+import { type AgentTool, type SessionConductor } from "../../conductor";
+import { type MemoryStore } from "../../capability-deck";
+import { type DelegateRunner } from "../../capability-deck/cards/task-card";
+import { type CheckpointStore } from "./checkpoint";
+import { type ContextDoc, type SkillCard } from "../../briefing";
+import type { BootContext, Invocation } from "../contract";
 /**
  * Resolve the model id for this run.
  *
@@ -21,6 +25,37 @@ import type { BootContext } from "../contract";
  * @returns the canonical model id to bind the session to
  */
 export declare function resolveModelId(ctx: BootContext): string;
+/**
+ * Gather the on-disk skill cards the model may invoke this run: walk the project
+ * and user `.indusagi/skills` roots and drop any card flagged
+ * `disable-model-invocation` (those stay loadable explicitly, but the model is
+ * not told about them). A filesystem walk error degrades to an empty list so a
+ * bad/unreadable skills dir never sinks the session.
+ */
+export declare function gatherModelSkills(cwd: string): SkillCard[];
+/**
+ * Select the tool deck for the run, honouring `--no-tools` (empty) and `--tools`
+ * (allow-list). Tool ids are matched case-insensitively with `_`/`-` stripped, so
+ * a `--tools web_fetch,todo_read` request lines up with the deck's `webfetch` /
+ * `todoread` ids.
+ */
+/**
+ * @param runner an optional live sub-agent {@link DelegateRunner}; when present it
+ *   is injected under {@link DELEGATE_HANDLE_KEY} so the `task` card delegates for
+ *   real instead of returning its `STUB_NOTE`. Omitted by callers that only need
+ *   a deck (the card then degrades gracefully).
+ * @param checkpoint an optional per-session {@link CheckpointStore}; when present
+ *   it is injected under {@link CHECKPOINT_HANDLE_KEY} so the framework's
+ *   write/edit tools snapshot a file's pre-mutation content (rewind, #24). Omitted
+ *   callers get no checkpointing (the tools no-op the snapshot).
+ */
+export declare function selectTools(cwd: string, inv: Invocation, runner?: DelegateRunner, memoryStore?: MemoryStore, checkpoint?: CheckpointStore): AgentTool[];
+/**
+ * Compose the run's system prompt: `--system` replaces the built-in briefing,
+ * `--append-system` adds a trailing block, and both compose (override then
+ * append). With neither, it is the tool-aware built-in briefing.
+ */
+export declare function composeSystem(tools: AgentTool[], inv: Invocation, cwd: string, skills?: readonly SkillCard[], memoryDoc?: ContextDoc): string;
 /**
  * The cwd-scoped session directory under the workspace `sessions/` root.
  *

package/dist/types/boot/runners/session.test.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Skills-surface wiring (#7 / fixes #11).
+ *
+ * Proves the chain that makes on-disk `SKILL.md` cards visible to the model:
+ * `gatherModelSkills` walks `cwd/.indusagi/skills`, drops any card flagged
+ * `disable-model-invocation`, and the survivors render into the briefing's
+ * `<available_skills>` block via `composeSystem`. A `--system` override must NOT
+ * carry the skills block (it replaces the whole prompt).
+ */
+export {};