indusagi-coding-agent 0.1.58 → 0.1.60

package/dist/types/capability-deck/builtin-bridge.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Built-in capability bridge — ONE seam to the framework's native tools.
+ *
+ * The framework (`indusagi/agent`, the `actions` surface) already authors its
+ * file, search, shell, web, process, and checklist tools as fully-formed
+ * `AgentTool` objects and ships a `create<Name>Tool(cwd, options)` factory for
+ * each. This module is the single place the deck reaches across that seam: it
+ * pairs every native factory with a deck {@link CapabilityCard.build} closure so
+ * the whole framework tool set is re-exposed as {@link Capability} rows in one
+ * file rather than in a dozen one-line re-export stubs.
+ *
+ * What this buys the rest of the deck:
+ *   - {@link BUILTIN_BRIDGE} — a single record keyed by the wire-facing tool
+ *     name, each value a {@link BridgeBuilder} that mints the live capability for
+ *     a {@link DeckContext}. The manifest derives its catalog rows from this
+ *     record; nothing else hand-maintains a parallel list of built-ins.
+ *   - {@link buildBuiltin} — resolve-and-build one built-in by id, surfacing a
+ *     typed {@link DeckFault} on an unknown id or a builder throw.
+ *   - {@link BUILTIN_PROFILES} — the per-built-in profile membership the
+ *     data-driven provisioner intersects with a requested {@link DeckProfile},
+ *     so the survey (observe-only) set falls out of one table instead of a
+ *     second hand-written tool list.
+ *
+ * Design notes:
+ *   - The builders thread `ctx.cwd` (and, where a factory takes them, the
+ *     framework option bags) into the native factory. They never reimplement the
+ *     tool — the framework owns the read/edit/grep/bash/etc. behavior; the bridge
+ *     only *binds* it to a working context and re-labels it for the catalog.
+ *   - The process and checklist tools are stateful framework singletons exposed
+ *     through their factories; the bridge keeps them framework-backed (wrapping
+ *     the framework, not any third-party package) while presenting them as plain
+ *     capabilities to the deck.
+ *   - All model-facing tool `name` strings are the framework's own wire contract
+ *     (`read`, `bash`, `grep`, …) and are kept verbatim — the model's prompt and
+ *     the conductor key off them. Only the deck-side titles/summaries are the
+ *     deck's own prose.
+ */
+import { type AnyCapability, type Capability, type CapabilityId, type CardProfiles, type DeckContext } from "./contract";
+/**
+ * A closure that mints one framework built-in {@link Capability} for a working
+ * context. The deck's view of a native factory after the bridge has bound the
+ * `cwd` (and any option bag) the factory needs.
+ *
+ * Returns `AnyCapability` because the heterogeneous built-ins carry different
+ * parameter schemas; a typed `AgentTool<TSchema>` widens to this element type,
+ * which is exactly what the deck and the conductor consume.
+ */
+export type BridgeBuilder = (ctx: DeckContext) => AnyCapability;
+/**
+ * One descriptor in the built-in catalog: the wire-facing id, the deck-side
+ * title/summary prose, the profiles the tool participates in, and the
+ * {@link BridgeBuilder} that binds the framework factory to a context.
+ *
+ * The manifest turns each of these into a {@link CapabilityCard}; consumers that
+ * want the raw built-in set read {@link BUILTIN_BRIDGE} directly.
+ */
+export interface BuiltinDescriptor {
+    /** Wire-facing tool name the model invokes (framework contract, verbatim). */
+    readonly id: CapabilityId;
+    /** Short human-facing title for catalogs and help text. */
+    readonly title: string;
+    /** One-line description in the deck's own voice. */
+    readonly summary: string;
+    /** Which deck profiles this built-in belongs to. */
+    readonly profiles: CardProfiles;
+    /** Bind the framework factory to a working context. */
+    readonly build: BridgeBuilder;
+}
+/**
+ * The framework built-ins keyed by their wire-facing {@link CapabilityId} — the
+ * single record the manifest and provisioner read from.
+ *
+ * Derived from {@link BUILTIN_DESCRIPTORS}, so the keyed view and the ordered
+ * list never drift: there is exactly one place a built-in is declared.
+ */
+export declare const BUILTIN_BRIDGE: Readonly<Record<string, BuiltinDescriptor>>;
+/**
+ * The wire-facing ids of every framework built-in, in catalog order. Convenient
+ * for `--tools` style selection and for the manifest's projection.
+ */
+export declare const BUILTIN_IDS: readonly CapabilityId[];
+/**
+ * The profile membership of every built-in, keyed by id — the slice of the
+ * profile table the data-driven provisioner reads to decide which built-ins a
+ * requested {@link DeckProfile} includes.
+ */
+export declare const BUILTIN_PROFILES: Readonly<Record<string, CardProfiles>>;
+/**
+ * The ordered list of built-in descriptors — the manifest projects its catalog
+ * rows from this, preserving order.
+ */
+export declare function builtinDescriptors(): readonly BuiltinDescriptor[];
+/**
+ * Resolve a built-in by id and build its live capability for a context.
+ *
+ * Throws a typed {@link DeckFault}: `unknown_capability` when the id is not a
+ * framework built-in, or `build_failed` when the framework factory throws. This
+ * is the sanctioned entry point so failure shaping stays uniform across the deck.
+ *
+ * @param id   the wire-facing built-in name to build
+ * @param ctx  the working context to bind the factory to
+ */
+export declare function buildBuiltin(id: CapabilityId, ctx: DeckContext): Capability;
+/**
+ * Build every framework built-in eligible for a profile, bound to a context.
+ *
+ * Walks the bridge table once, keeps each built-in whose profile membership
+ * admits the requested profile (`all` admits everything), and binds it. A single
+ * data-driven pass replaces a trio of per-profile build functions.
+ *
+ * @param profile the requested deck profile
+ * @param ctx     the working context to bind each factory to
+ */
+export declare function buildBuiltinsForProfile(profile: "authoring" | "survey" | "all", ctx: DeckContext): AnyCapability[];

package/dist/types/capability-deck/capability-deck.test.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Capability-deck — Phase 4 behavioral tests (no network, no real MCP server).
+ *
+ * Three concerns, exercised purely:
+ *   1. {@link provisionDeck} — the data-driven profile assembler: `authoring`
+ *      yields the read-only built-in subset, `all` additionally pulls in the
+ *      app-novel cards, and `box()` hands back an `AgentTool[]` shaped exactly
+ *      the way the conductor's `options.tools` expects.
+ *   2. The {@link BridgeLedger} — event-sourced MCP enrollment: enroll is an
+ *      idempotent upsert, retire is a splice, and every transition yields a new
+ *      immutable snapshot rather than mutating the prior ledger.
+ *   3. The novel cards — the checklist round-trips set/read, and the
+ *      background-process card starts/polls/stops a real short-lived sleeper.
+ *
+ * Everything here binds to a temp/echo context; nothing reaches the network and
+ * no real MCP server is mounted (the ledger is fed synthetic capabilities).
+ */
+export {};

package/dist/types/capability-deck/cards/bg-process-card.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Background-process capability — start, poll, and stop long-lived child
+ * processes that outlive a single tool call.
+ *
+ * App-novel and framework-agnostic: it wraps Node's `child_process.spawn`
+ * directly rather than delegating to any framework process controller, so the
+ * lifecycle is owned entirely by this card. A long-running command (a dev
+ * server, a watcher, a build in `--watch` mode) is launched detached from the
+ * tool turn; the agent later polls its captured output or signals it to stop.
+ *
+ * One tool folds the lifecycle into an `action` discriminant:
+ *   - `start` — spawn `command` in a shell, return the assigned handle id.
+ *   - `poll`  — return the buffered stdout/stderr (and live/exited status) for a
+ *               handle, optionally only the lines appended since the last poll.
+ *   - `stop`  — send SIGTERM (escalating to SIGKILL after a grace window) to a
+ *               handle's process tree.
+ *   - `list`  — enumerate every handle this capability is tracking.
+ *
+ * Output is captured into bounded ring buffers so a chatty process cannot grow
+ * memory without limit; only the most recent lines are retained. The card
+ * produces a {@link Capability} (framework `AgentTool`) the conductor consumes.
+ */
+import { type ChildProcess } from "node:child_process";
+import { type Static } from "@sinclair/typebox";
+import type { Capability, CapabilityCard, DeckContext } from "../contract";
+/** Coarse lifecycle state of a tracked background process. */
+export type DaemonState = "running" | "exited" | "signalled";
+/** A bounded buffer of recent output lines for one stream. */
+interface RingBuffer {
+    lines: string[];
+    /** Index of the next unread line for incremental polling. */
+    cursor: number;
+}
+/** One tracked background process and its captured state. */
+interface DaemonHandle {
+    readonly id: string;
+    readonly command: string;
+    readonly child: ChildProcess;
+    state: DaemonState;
+    exitCode: number | null;
+    signal: NodeJS.Signals | null;
+    readonly startedAt: number;
+    readonly stdout: RingBuffer;
+    readonly stderr: RingBuffer;
+}
+/**
+ * An in-process table of background children, owned by one built capability.
+ *
+ * Each `start` spawns a shell-wrapped child, wires its stdout/stderr into
+ * bounded buffers, and records terminal state on `exit`. `stop` escalates from
+ * SIGTERM to SIGKILL if the process does not exit within a grace window. The
+ * table is per-capability, so one session's daemons are isolated from another's.
+ */
+export declare class DaemonTable {
+    private readonly handles;
+    private nextSeq;
+    private readonly cwd;
+    constructor(cwd: string);
+    start(command: string): DaemonHandle;
+    get(id: string): DaemonHandle | undefined;
+    list(): DaemonHandle[];
+    /**
+     * Signal a handle's process to terminate. Sends SIGTERM immediately and a
+     * SIGKILL after `graceMs` if the child is still alive. Resolves once the
+     * child has exited or the kill has been sent.
+     */
+    stop(handle: DaemonHandle, graceMs?: number): Promise<void>;
+}
+declare const DaemonParams: import("@sinclair/typebox").TObject<{
+    action: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"start">, import("@sinclair/typebox").TLiteral<"poll">, import("@sinclair/typebox").TLiteral<"stop">, import("@sinclair/typebox").TLiteral<"list">]>;
+    command: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    id: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    sinceLast: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
+}>;
+/** Statically-inferred parameter type the capability's `execute` receives. */
+export type DaemonParamsType = Static<typeof DaemonParams>;
+/** Structured detail returned alongside the model-facing content. */
+export interface DaemonDetails {
+    readonly action: "start" | "poll" | "stop" | "list";
+    readonly ok: boolean;
+    readonly id?: string;
+    readonly state?: DaemonState;
+    readonly exitCode?: number | null;
+    readonly processes?: ReadonlyArray<{
+        readonly id: string;
+        readonly command: string;
+        readonly state: DaemonState;
+    }>;
+}
+/**
+ * Build the background-process capability, binding it to a fresh per-session
+ * {@link DaemonTable} scoped to the context's working directory.
+ *
+ * @param ctx the deck context — its `cwd` is where launched processes run.
+ */
+export declare function buildDaemonCapability(ctx: DeckContext): Capability<typeof DaemonParams, DaemonDetails>;
+/** Catalog row for the background-process capability. */
+export declare const daemonCard: CapabilityCard;
+export {};

package/dist/types/capability-deck/cards/index.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Capability cards — the app-novel capabilities the deck builds in-house.
+ *
+ * Each card is a {@link CapabilityCard}: metadata plus a `build(ctx)` factory
+ * that mints a live {@link Capability} (the framework `AgentTool` shape) for a
+ * working context. These are written fresh against the framework contract — not
+ * derived from any prior tooling layer — and stay framework-agnostic where the
+ * behavior is original (todo and bg-process wrap only Node + the deck contract).
+ *
+ * The connector and memory cards expose a thin, clearly-typed adapter seam over
+ * a framework handle injected through {@link DeckContext.framework}; when no
+ * handle is wired they degrade to a typed stub so every card builds and runs in
+ * any environment, including tests.
+ *
+ * {@link APP_NOVEL_CARDS} is the contribution this module makes to the catalog;
+ * the manifest module composes it with the builtin-bridge cards (the framework's
+ * file/shell/search/web tools) to form the single `CAPABILITY_CARDS` source of
+ * truth from which the deck's index and profiles are derived.
+ */
+import type { CapabilityCard } from "../contract";
+export { todoCard, buildTodoCapability, TodoLedger, type TodoItem, type TodoState, type TodoWeight, type TodoParamsType, type TodoDetails, } from "./todo-card";
+export { daemonCard, buildDaemonCapability, DaemonTable, type DaemonState, type DaemonParamsType, type DaemonDetails, } from "./bg-process-card";
+export { taskCard, buildTaskCapability, DELEGATE_HANDLE_KEY, type DelegateRunner, type DelegateRequest, type DelegateResult, type TaskParamsType, type TaskDetails, } from "./task-card";
+export { saasCard, buildSaasCapability, SAAS_GATEWAY_KEY, type SaasGatewayPort, type RemoteToolSummary, type RemoteExecution, type SaasParamsType, type SaasDetails, } from "./saas-card";
+export { memoryCard, buildMemoryCapability, InMemoryStore, MEMORY_HANDLE_KEY, type MemoryStore, type MemoryParamsType, type MemoryDetails, } from "./memory-card";
+/**
+ * The app-novel cards, in catalog order. The manifest module concatenates these
+ * with the builtin-bridge cards to build the full `CAPABILITY_CARDS` array.
+ */
+export declare const APP_NOVEL_CARDS: readonly CapabilityCard[];

package/dist/types/capability-deck/cards/memory-card.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Working-memory capability — read and update a persistent scratch note the
+ * agent carries across turns.
+ *
+ * Status: minimal in-memory implementation + clearly-typed seam for the
+ * framework memory subsystem.
+ *
+ * The framework's `indusagi/memory` facade is not yet populated with a public
+ * working-memory store, so this card ships a self-contained, framework-agnostic
+ * implementation: a single mutable text buffer the agent overwrites or appends
+ * to, scoped to one built capability (one session). When the framework exposes a
+ * persistent memory store, swap the {@link MemoryStore} default for an adapter
+ * over it via {@link DeckContext.framework} — the {@link Capability} surface and
+ * the tool's wire contract do not change.
+ *
+ * TODO(framework-memory): adapt `indusagi/memory` once it exports a public
+ * working-memory store; read it from `ctx.framework[MEMORY_HANDLE_KEY]`.
+ *
+ * The single tool keys behavior on an `action` discriminant:
+ *   - `read`    — return the current working-memory note.
+ *   - `replace` — overwrite the note with the supplied `content`.
+ *   - `append`  — add a line to the end of the note.
+ */
+import { type Static } from "@sinclair/typebox";
+import type { Capability, CapabilityCard, DeckContext } from "../contract";
+/** Key under which a host may wire a framework-backed memory store in later. */
+export declare const MEMORY_HANDLE_KEY: "memoryStore";
+/**
+ * The narrow port the memory capability binds to.
+ *
+ * The in-memory default below satisfies it; a future framework-backed store can
+ * be adapted to the same three methods and injected through the context.
+ */
+export interface MemoryStore {
+    read(): string;
+    replace(content: string): void;
+    append(line: string): void;
+}
+/** A trivial in-process working-memory buffer, one per built capability. */
+export declare class InMemoryStore implements MemoryStore {
+    private buffer;
+    read(): string;
+    replace(content: string): void;
+    append(line: string): void;
+}
+declare const MemoryParams: import("@sinclair/typebox").TObject<{
+    action: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"read">, import("@sinclair/typebox").TLiteral<"replace">, import("@sinclair/typebox").TLiteral<"append">]>;
+    content: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+}>;
+/** Statically-inferred parameter type the capability's `execute` receives. */
+export type MemoryParamsType = Static<typeof MemoryParams>;
+/** Structured detail returned alongside the model-facing content. */
+export interface MemoryDetails {
+    readonly action: "read" | "replace" | "append";
+    readonly ok: boolean;
+    /** Length of the note after the call, for quick status. */
+    readonly length: number;
+}
+/**
+ * Build the working-memory capability, binding it to an injected store when one
+ * is wired into the context, or a fresh in-memory store otherwise.
+ *
+ * @param ctx the deck context; an optional store is read from
+ *            `ctx.framework[MEMORY_HANDLE_KEY]`.
+ */
+export declare function buildMemoryCapability(ctx: DeckContext): Capability<typeof MemoryParams, MemoryDetails>;
+/** Catalog row for the working-memory capability. */
+export declare const memoryCard: CapabilityCard;
+export {};

package/dist/types/capability-deck/cards/saas-card.d.ts

@@ -0,0 +1,78 @@
+/**
+ * SaaS-action capability — a thin wrapper over the framework's connector gateway
+ * (Composio-style remote tool execution).
+ *
+ * The heavy lifting (authenticating to a vendor, resolving toolkit scopes,
+ * executing a remote tool slug) lives in the framework's `connectors-saas`
+ * layer. This card does NOT re-implement any of it; it adapts an injected
+ * gateway handle to the deck's {@link Capability} shape so the agent can invoke
+ * remote SaaS actions by slug. When no gateway is wired into the context the card
+ * still builds and returns a typed stub, so the deck assembles in every
+ * environment.
+ *
+ * The single tool keys behavior on an `action` discriminant:
+ *   - `discover` — list executable remote tool slugs (optionally filtered).
+ *   - `execute`  — run one remote tool slug with arguments.
+ *
+ * Vendor-defined identifiers (uppercase tool slugs like `GITHUB_CREATE_ISSUE`)
+ * are passed through verbatim — they are part of the connector's wire contract.
+ */
+import { type Static } from "@sinclair/typebox";
+import type { Capability, CapabilityCard, DeckContext } from "../contract";
+/** Key under which a host wires a live SaaS gateway into the deck context. */
+export declare const SAAS_GATEWAY_KEY: "saasGateway";
+/** One executable remote tool advertised by the connector. */
+export interface RemoteToolSummary {
+    /** Vendor-defined slug, passed through verbatim (e.g. `GITHUB_CREATE_ISSUE`). */
+    readonly slug: string;
+    /** Human-readable description from the connector, if any. */
+    readonly description?: string;
+}
+/** The outcome of executing one remote tool slug. */
+export interface RemoteExecution {
+    readonly ok: boolean;
+    /** Connector payload, surfaced to the model as serialized text. */
+    readonly data: unknown;
+}
+/**
+ * The slice of a framework SaaS gateway this card adapts.
+ *
+ * Deliberately narrow — the deck only needs to list and execute remote tools.
+ * The framework's full gateway (connection lifecycle, scope planning, status
+ * reporting) is a superset; a host adapts it to this shape when wiring it in.
+ */
+export interface SaasGatewayPort {
+    /** List executable remote tools, optionally filtered by toolkit or query. */
+    discover(filter?: {
+        toolkits?: string[];
+        query?: string;
+    }): Promise<RemoteToolSummary[]>;
+    /** Execute one remote tool slug with arguments. */
+    execute(slug: string, args: Record<string, unknown>): Promise<RemoteExecution>;
+}
+declare const SaasParams: import("@sinclair/typebox").TObject<{
+    action: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"discover">, import("@sinclair/typebox").TLiteral<"execute">]>;
+    slug: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    arguments: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, import("@sinclair/typebox").TUnknown>>;
+    toolkits: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>>;
+    query: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+}>;
+/** Statically-inferred parameter type the capability's `execute` receives. */
+export type SaasParamsType = Static<typeof SaasParams>;
+/** Structured detail returned alongside the model-facing content. */
+export interface SaasDetails {
+    readonly action: "discover" | "execute";
+    readonly ok: boolean;
+    readonly slug?: string;
+    readonly count?: number;
+}
+/**
+ * Build the SaaS-action capability, adapting an injected gateway when present.
+ *
+ * @param ctx the deck context; an optional gateway is read from
+ *            `ctx.framework[SAAS_GATEWAY_KEY]`.
+ */
+export declare function buildSaasCapability(ctx: DeckContext): Capability<typeof SaasParams, SaasDetails>;
+/** Catalog row for the SaaS-action capability. */
+export declare const saasCard: CapabilityCard;
+export {};

package/dist/types/capability-deck/cards/task-card.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Task capability — delegate a self-contained piece of work to a sub-agent.
+ *
+ * App-novel wiring. The `task` tool lets the primary agent hand off a bounded
+ * objective (e.g. "find every call site of `foo` and summarize them") to a fresh
+ * sub-agent that runs its own tool loop and reports back a single result, keeping
+ * the parent's context window clean.
+ *
+ * The actual sub-agent runner is NOT owned by this card — it is a framework /
+ * swarm concern injected through {@link DeckContext.framework} under the
+ * {@link DELEGATE_HANDLE_KEY} key. When that handle is present the capability
+ * delegates to it; when it is absent (tests, headless tooling, a host that has
+ * not wired the swarm) the capability degrades gracefully to a clearly-typed
+ * stub that reports delegation is unavailable rather than throwing. Either way
+ * the card builds a valid {@link Capability} and the deck typechecks and runs.
+ *
+ * The card produces a framework `AgentTool`; parameters are a TypeBox schema and
+ * the prose is original to this deck.
+ */
+import { type Static } from "@sinclair/typebox";
+import type { Capability, CapabilityCard, DeckContext } from "../contract";
+/** Key under which a host wires a live delegate runner into the deck context. */
+export declare const DELEGATE_HANDLE_KEY: "delegate";
+/** A single delegated objective handed to the sub-agent runner. */
+export interface DelegateRequest {
+    /** Optional named agent profile to run as (e.g. "explorer", "reviewer"). */
+    readonly agent?: string;
+    /** The self-contained objective the sub-agent should accomplish. */
+    readonly objective: string;
+    /** Optional extra context the parent wants the sub-agent to start with. */
+    readonly context?: string;
+}
+/** The single result a sub-agent reports back to the parent. */
+export interface DelegateResult {
+    /** Whether the sub-agent considers the objective met. */
+    readonly ok: boolean;
+    /** The sub-agent's final report, surfaced to the parent agent verbatim. */
+    readonly report: string;
+}
+/**
+ * The contract a host's sub-agent runner must satisfy to be wired in.
+ *
+ * Intentionally minimal: the deck only needs a way to run one objective under
+ * cancellation and get one report back. How the runner spawns the sub-agent
+ * (in-process loop, worktree, separate process) is entirely the host's concern.
+ */
+export interface DelegateRunner {
+    /** Optional roster of named agent profiles, surfaced in the tool description. */
+    listAgents?(): readonly string[];
+    /** Run one delegated objective and resolve with the sub-agent's report. */
+    run(request: DelegateRequest, signal?: AbortSignal): Promise<DelegateResult>;
+}
+declare const TaskParams: import("@sinclair/typebox").TObject<{
+    objective: import("@sinclair/typebox").TString;
+    agent: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    context: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+}>;
+/** Statically-inferred parameter type the capability's `execute` receives. */
+export type TaskParamsType = Static<typeof TaskParams>;
+/** Structured detail returned alongside the model-facing content. */
+export interface TaskDetails {
+    /** True when a delegate runner handled the objective. */
+    readonly delegated: boolean;
+    /** True when the sub-agent (or stub) considers the objective met. */
+    readonly ok: boolean;
+    /** The agent profile that ran, if one was named. */
+    readonly agent?: string;
+}
+/**
+ * Build the task/delegate capability.
+ *
+ * If a {@link DelegateRunner} is present on the context it is bound and the tool
+ * truly delegates; otherwise the tool builds anyway and returns a typed,
+ * non-throwing stub result so the deck stays assemblable in every environment.
+ *
+ * @param ctx the deck context; an optional delegate runner is read from
+ *            `ctx.framework[DELEGATE_HANDLE_KEY]`.
+ */
+export declare function buildTaskCapability(ctx: DeckContext): Capability<typeof TaskParams, TaskDetails>;
+/** Catalog row for the task/delegate capability. */
+export declare const taskCard: CapabilityCard;
+export {};

package/dist/types/capability-deck/cards/todo-card.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Todo capability — an in-memory checklist the agent set/reads during a run.
+ *
+ * App-novel and framework-agnostic: the store is a plain in-process array of
+ * items, owned by the card and closed over by the built capability. No file
+ * persistence, no session-branch reconstruction, no framework store — just a
+ * mutable list the agent rewrites wholesale (the model is expected to send the
+ * complete desired list on every `set`, the same convention coding agents use so
+ * the plan stays a single coherent snapshot rather than a diff stream).
+ *
+ * Two operations are folded into one tool keyed by an `action` discriminant:
+ *   - `read` — return the current checklist as model-facing prose.
+ *   - `set`  — replace the checklist with the supplied items (the authoritative
+ *              new plan), then echo it back.
+ *
+ * The card produces a {@link Capability} (the framework `AgentTool` shape) so the
+ * conductor consumes it verbatim as one of `options.tools`. Parameters are a
+ * TypeBox schema; the prose below is original to this deck.
+ */
+import { type Static } from "@sinclair/typebox";
+import type { Capability, CapabilityCard, DeckContext } from "../contract";
+/** Lifecycle state of one checklist item. */
+export type TodoState = "pending" | "active" | "done" | "dropped";
+/** Relative importance of one checklist item. */
+export type TodoWeight = "low" | "normal" | "high";
+/** One row of the in-memory checklist. */
+export interface TodoItem {
+    /** The work to be done, phrased as a short imperative. */
+    readonly task: string;
+    /** Where the item stands right now. */
+    readonly state: TodoState;
+    /** How much it matters relative to the rest of the list. */
+    readonly weight: TodoWeight;
+}
+/**
+ * A minimal in-process checklist store.
+ *
+ * Deliberately tiny and synchronous: the whole list lives in one field, `set`
+ * swaps it atomically, and `read` hands back a frozen copy so a caller cannot
+ * mutate the store's backing array. One store is created per built capability,
+ * so two sessions never share a checklist.
+ */
+export declare class TodoLedger {
+    private items;
+    /** Replace the entire checklist with `next`; returns the stored snapshot. */
+    set(next: readonly TodoItem[]): readonly TodoItem[];
+    /** Return the current checklist as a frozen, read-only snapshot. */
+    read(): readonly TodoItem[];
+}
+declare const TodoParams: import("@sinclair/typebox").TObject<{
+    action: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"read">, import("@sinclair/typebox").TLiteral<"set">]>;
+    items: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
+        task: import("@sinclair/typebox").TString;
+        state: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"pending">, import("@sinclair/typebox").TLiteral<"active">, import("@sinclair/typebox").TLiteral<"done">, import("@sinclair/typebox").TLiteral<"dropped">]>;
+        weight: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"low">, import("@sinclair/typebox").TLiteral<"normal">, import("@sinclair/typebox").TLiteral<"high">]>;
+    }>>>;
+}>;
+/** Statically-inferred parameter type the capability's `execute` receives. */
+export type TodoParamsType = Static<typeof TodoParams>;
+/** Structured detail returned alongside the model-facing content. */
+export interface TodoDetails {
+    /** The action that was performed. */
+    readonly action: "read" | "set";
+    /** The checklist as it stands after the call. */
+    readonly items: readonly TodoItem[];
+}
+/**
+ * Build the todo capability, binding it to a freshly created in-memory ledger.
+ *
+ * The ledger is closed over by `execute`, so the checklist persists for the life
+ * of this capability instance (i.e. the session) without any external store.
+ *
+ * @param _ctx the deck context (unused — the todo card needs no cwd/backends)
+ */
+export declare function buildTodoCapability(_ctx: DeckContext): Capability<typeof TodoParams, TodoDetails>;
+/** Catalog row for the todo capability — registered in `CAPABILITY_CARDS`. */
+export declare const todoCard: CapabilityCard;
+export {};