@juspay/neurolink 12.1.0 → 12.2.0

package/dist/types/backgroundCommand.d.ts

@@ -0,0 +1,174 @@
+/**
+ * Background commands (N4) — run a command detached, bank its output, monitor
+ * it — types.
+ *
+ * A long-running agent has to run real commands: a build, a test suite, a
+ * linter whose output is the evidence for a review finding. Two things make
+ * that safe and useful, and both are in these types.
+ *
+ * 1. **Nothing is discarded.** Both streams go straight to files and the FULL
+ *    files are banked as artifacts when the command settles. What reaches the
+ *    conversation is a bounded `tailPreview` plus a {@link BankedArtifactRef}
+ *    per stream — a pointer, never a replacement. `maxOutputBytes` is the one
+ *    bound, and hitting it is a loud state (`output-limit`), not a silent cut.
+ * 2. **Execution is a contract, not advice.** `argv` arrays only, no shell
+ *    ever; an executable allowlist; a cwd that must resolve, through symlinks,
+ *    inside a declared root; a timeout that actually kills.
+ *
+ * Naming: `cli.ts` already owns `CommandResult` / `CommandDefinition` and
+ * `action.ts` owns `ActionCommand`, so everything here carries the
+ * `BackgroundCommand` prefix (Critical Rule 9).
+ */
+import type { BankedArtifactRef } from "./artifact.js";
+/** Which of a command's two output streams a page or artifact refers to. */
+export type BackgroundCommandStreamName = "stdout" | "stderr";
+/**
+ * Lifecycle of one background command.
+ *
+ * `queued` is the window between the handle being returned and the OS
+ * confirming the child started. The four settled states are deliberately
+ * distinct: "the command failed" and "we killed it because it printed 4 GB"
+ * are different facts about a run, and collapsing them loses the one a
+ * reviewer needs.
+ */
+export type BackgroundCommandState = "queued" | "running" | "exited" | "killed" | "timeout" | "output-limit";
+/** `true` to allow, or a string giving the reason the command was refused. */
+export type BackgroundCommandAllowDecision = true | string;
+/**
+ * What a host permits. There is no default policy: without one every start is
+ * refused, because "run whatever the model asks" is not a defensible default
+ * for a primitive that executes processes.
+ */
+export type BackgroundCommandPolicy = {
+    /**
+     * Executables that may be started, matched EXACTLY against `argv[0]` — no
+     * basename fallback, so allowlisting `git` never permits `/tmp/evil/git`.
+     * Required, and an empty list refuses everything.
+     */
+    allowedExecutables: string[];
+    /**
+     * Final say after the allowlist and the sandbox have passed. Return `true`
+     * to allow, or a string that is handed to the caller as the refusal reason
+     * (so put the recovery step in it).
+     */
+    allowlist?: (argv: string[], cwd: string) => BackgroundCommandAllowDecision;
+    /**
+     * Sandbox root. The resolved REAL cwd (symlinks followed) must be this
+     * directory or inside it.
+     */
+    cwdRoot: string;
+    /** Wall-clock budget when the caller names none. Default 120_000. */
+    defaultTimeoutMs?: number;
+    /** Per-stream byte cap when the caller names none. Default 10_485_760. */
+    maxOutputBytes?: number;
+};
+/**
+ * Per-start options. Only `timeoutMs` and `maxOutputBytes` fall back to the
+ * policy's defaults. The rest have their own omission behaviour: `env`
+ * inherits the parent environment, `label` defaults to `argv[0]`, `sessionId`
+ * resolves from the host's tool context, and `abortSignal` simply has no
+ * fallback.
+ */
+export type BackgroundCommandOptions = {
+    /** Working directory. Must resolve inside `BackgroundCommandPolicy.cwdRoot`. */
+    cwd: string;
+    /** Wall-clock budget in ms; SIGTERM then SIGKILL. */
+    timeoutMs?: number;
+    /** Per-stream byte cap; hitting it kills the command with `output-limit`. */
+    maxOutputBytes?: number;
+    /**
+     * Environment for the child. When given it REPLACES the parent environment
+     * rather than extending it — the command gets exactly these variables and
+     * nothing else. Omit it to inherit the parent environment, which is what a
+     * repository's own checks normally need.
+     */
+    env?: Record<string, string>;
+    /** Short human label for logs and the banked artifacts. Defaults to argv[0]. */
+    label?: string;
+    /** Session the command belongs to; scopes the outstanding counters. */
+    sessionId?: string;
+    /** Parent cancellation — an aborted parent kills the command. */
+    abortSignal?: AbortSignal;
+};
+/** Returned the moment a command is accepted — before it has produced output. */
+export type BackgroundCommandHandle = {
+    taskId: string;
+    argv: string[];
+    startedAt: number;
+};
+/**
+ * Everything known about one command right now.
+ *
+ * `stdout` / `stderr` appear once the command has settled and its streams have
+ * been banked; `tailPreview` is available throughout and is always bounded.
+ * The preview is for orientation — the banked artifacts are the evidence.
+ */
+export type BackgroundCommandStatus = {
+    taskId: string;
+    /** Short human label, e.g. "git log" — which command this is. */
+    label: string;
+    state: BackgroundCommandState;
+    /** Process exit code, once it exited on its own. */
+    exitCode?: number;
+    /** Signal that ended the process, when one did. */
+    signal?: string;
+    durationMs: number;
+    /** Bytes written to each stream's log file so far. */
+    stdoutBytes: number;
+    stderrBytes: number;
+    /** The FULL stdout, banked (N3). Present once settled. */
+    stdout?: BankedArtifactRef;
+    /** The FULL stderr, banked (N3). Present once settled. */
+    stderr?: BankedArtifactRef;
+    /** Tail of the output so far, ≤ 2000 chars. Never a substitute for the files. */
+    tailPreview: string;
+    /** Why the command could not run, or how it was cut short. */
+    error?: string;
+};
+/** One character window of a command's output, read straight from the log file. */
+export type BackgroundCommandOutputPage = {
+    taskId: string;
+    stream: BackgroundCommandStreamName;
+    content: string;
+    offset: number;
+    limit: number;
+    /** Characters in the whole stream, including what this page did not return. */
+    totalSize: number;
+    hasMore: boolean;
+};
+/** Character window for a paginated output read. */
+export type BackgroundCommandPageRequest = {
+    stream: BackgroundCommandStreamName;
+    /** Character offset to start at. Default 0. */
+    offset?: number;
+    /** Maximum characters to return. Default 50_000, hard cap 200_000. */
+    limit?: number;
+};
+/**
+ * Outstanding commands for a session: `running` have not settled yet, and
+ * `finished` have settled without anyone having looked at them since.
+ *
+ * "Not looked at" rather than "ever finished" is what makes the number
+ * actionable — reading a settled command's status or output clears it, so a
+ * non-zero `finished` always means there is something new to read. Nothing is
+ * discarded when it clears: the job, its logs and its artifacts stay exactly
+ * where they were.
+ *
+ * Carried on every command tool result and — via the checklist — on every
+ * `tasks_list`, so the model learns a build finished without polling.
+ */
+export type BackgroundCommandCounts = {
+    running: number;
+    finished: number;
+};
+/** Supplies {@link BackgroundCommandCounts} to the task checklist. */
+export type BackgroundCommandCountsSource = (sessionId: string) => BackgroundCommandCounts;
+/** What `run_command_bg` returns: the handle plus the outstanding counters. */
+export type BackgroundCommandStartToolResult = BackgroundCommandHandle & BackgroundCommandCounts;
+/** What the monitor tools return: a status plus the outstanding counters. */
+export type BackgroundCommandStatusToolResult = BackgroundCommandStatus & BackgroundCommandCounts;
+/** Refusal shape shared with the agent tool registrar: recovery text included. */
+export type BackgroundCommandRefusal = {
+    isError: true;
+    error: string;
+};

package/dist/types/backgroundCommand.js

@@ -0,0 +1,22 @@
+/**
+ * Background commands (N4) — run a command detached, bank its output, monitor
+ * it — types.
+ *
+ * A long-running agent has to run real commands: a build, a test suite, a
+ * linter whose output is the evidence for a review finding. Two things make
+ * that safe and useful, and both are in these types.
+ *
+ * 1. **Nothing is discarded.** Both streams go straight to files and the FULL
+ *    files are banked as artifacts when the command settles. What reaches the
+ *    conversation is a bounded `tailPreview` plus a {@link BankedArtifactRef}
+ *    per stream — a pointer, never a replacement. `maxOutputBytes` is the one
+ *    bound, and hitting it is a loud state (`output-limit`), not a silent cut.
+ * 2. **Execution is a contract, not advice.** `argv` arrays only, no shell
+ *    ever; an executable allowlist; a cwd that must resolve, through symlinks,
+ *    inside a declared root; a timeout that actually kills.
+ *
+ * Naming: `cli.ts` already owns `CommandResult` / `CommandDefinition` and
+ * `action.ts` owns `ActionCommand`, so everything here carries the
+ * `BackgroundCommand` prefix (Critical Rule 9).
+ */
+export {};

package/dist/types/delegation.d.ts

@@ -0,0 +1,178 @@
+/**
+ * Async delegation (N2) — spawn a background worker, collect it later, in any
+ * order — types.
+ *
+ * Delegation today is a synchronous tool call: the supervising agent blocks
+ * until the worker is done, so four investigations take four times as long as
+ * one and the supervisor cannot do anything useful while it waits. These types
+ * describe the background form — `spawn` hands back a `DelegateHandle`
+ * immediately, `collect` returns whichever worker finished FIRST regardless of
+ * which was started first, and each outcome carries a bounded summary plus a
+ * {@link BankedArtifactRef} to the worker's full report, which is banked to a
+ * file rather than pushed into the conversation.
+ *
+ * Naming: `agentNetwork.ts` already owns `DelegationRule` / `DelegationCondition`
+ * and `isolatedAgent.ts` owns `AgentDelegationTurnState`, so everything here
+ * carries the `Delegate` prefix (Critical Rule 9).
+ */
+import type { BankedArtifactRef } from "./artifact.js";
+import type { AgentRunStatus } from "./isolatedAgent.js";
+/** What a supervisor hands down when it spawns a background worker. */
+export type DelegateSpawnOptions = {
+    /** The task, in the supervisor's own words. Required and non-empty. */
+    task: string;
+    /** What the worker may look at — files, directories, systems. */
+    scope?: string;
+    /** Brief slice of context handed down (never the whole rulebook). */
+    context?: string;
+    /** Model override for this worker. */
+    model?: string;
+    /** Provider override for this worker. */
+    provider?: string;
+    /** Read-only tool allowlist for the worker (tool names). */
+    tools?: string[];
+    /**
+     * Caller's session. Collection is scoped to it, and it is the key the task
+     * checklist's `delegatesPending` / `delegatesReady` counters are read by.
+     * Defaults to the session the host's tool context declares.
+     */
+    sessionId?: string;
+    /** Caller's delegation depth; the worker runs one level deeper. */
+    depth?: number;
+    /** Short human label used in logs and in the banked report's name. */
+    label?: string;
+    /** Parent cancellation — an aborted parent cancels this worker. */
+    abortSignal?: AbortSignal;
+    /** Max agentic steps for the worker's research pass. */
+    maxSteps?: number;
+    /** Wall-clock budget for the worker's research pass (ms). */
+    budgetMs?: number;
+};
+/**
+ * Returned the moment a worker is spawned — before it has run anything.
+ * `queued` is true when the process-wide delegation pool was full and the
+ * worker is waiting for a slot.
+ */
+export type DelegateHandle = {
+    workerId: string;
+    spawnedAt: number;
+    queued: boolean;
+};
+/**
+ * A settled worker, claimed exactly once.
+ *
+ * `summary` is bounded; `report` points at the COMPLETE report on disk. The
+ * two are not alternatives — the summary is what the conversation carries, the
+ * report is what the evidence lives in.
+ */
+export type DelegateOutcome = {
+    workerId: string;
+    /** Human label the spawn was given (defaults to the worker id). */
+    label: string;
+    /** Reused from the isolated-agent runner — no parallel taxonomy. */
+    status: AgentRunStatus;
+    /** True for `completed` and `partial`: the worker produced usable evidence. */
+    ok: boolean;
+    /** Bounded narrative for the conversation. Never the whole report. */
+    summary: string;
+    /** The FULL report, always banked to a file. */
+    report: BankedArtifactRef;
+    durationMs: number;
+    toolCallsUsed: number;
+    /** Mechanical waste signatures the runner tripped, if any. */
+    wasteSignals?: string[];
+    /** `continueAgent()` handle when the worker was cut short mid-investigation. */
+    handle?: string;
+    /** Why the worker failed, when it did. */
+    error?: string;
+};
+/** `any` returns the first worker to finish; `all` waits for every one. */
+export type DelegateCollectMode = "any" | "all";
+/**
+ * What to collect. `waitMs` of 0 polls (return what is ready right now);
+ * omitting it uses the runtime default.
+ */
+export type DelegateCollectRequest = {
+    mode: DelegateCollectMode;
+    waitMs?: number;
+    sessionId?: string;
+} | {
+    workerId: string;
+    waitMs?: number;
+    sessionId?: string;
+};
+/**
+ * Outcomes claimed by one collect call, in COMPLETION order — the order
+ * workers finished in, which has nothing to do with the order they were
+ * spawned in.
+ */
+export type DelegateCollectResult = {
+    /** Claimed exactly once: these outcomes are gone from the registry. */
+    completed: DelegateOutcome[];
+    /** Still running or waiting for a pool slot. */
+    pending: number;
+    /** Finished but not yet claimed. */
+    ready: number;
+    /**
+     * True when the wait expired before this call claimed what it asked for:
+     * for a named worker, that worker's outcome; for `any`, any outcome while
+     * work was still pending; for `all`, pending work remained when the wait
+     * ran out. A collect that claimed something reports `false` even if other
+     * work is still outstanding — `pending`/`ready` carry that.
+     */
+    timedOut: boolean;
+};
+/** Lifecycle of one background job. `claimed` jobs are dropped immediately. */
+export type DelegateJobPhase = "queued" | "running" | "ready" | "claimed";
+/**
+ * Provider/model a model-invoked `delegate_task` spawn falls back to. The spawn
+ * schema deliberately exposes no `provider` — a model cannot name a provider it
+ * cannot see — so without a default the worker instance falls back to provider
+ * auto-selection, which on a host with stray credentials puts a worker on a
+ * provider nobody configured — observed live as workers walking several
+ * unconfigured providers before reaching the configured one. The model's own
+ * `model` argument still wins over `model` here.
+ */
+export type DelegateSpawnDefaults = {
+    provider?: string;
+    model?: string;
+};
+/** Per-host delegation policy, resolved from registration options. */
+export type DelegateRuntimeSettings = {
+    /** Caller depth at which `delegate_task` refuses rather than spawning. */
+    maxDepth: number;
+    /** How long a spawned worker waits for a pool slot before giving up (ms). */
+    poolQueueTimeoutMs: number;
+    /** Default `waitMs` for a collect that does not name one (ms). */
+    defaultCollectWaitMs: number;
+    /** Defaults merged under every model-invoked `delegate_task` spawn. */
+    spawnDefaults?: DelegateSpawnDefaults;
+};
+/** Options for `NeuroLink.registerDelegationTools()`. */
+export type DelegateRegistrationOptions = {
+    /**
+     * Caller depth at which further delegation is refused. Default 1: a
+     * background worker does not spawn background workers, because nothing
+     * would ever collect them.
+     */
+    maxDepth?: number;
+    /**
+     * Raise the process-wide delegation pool to at least this many concurrent
+     * workers. The pool is shared with `registerAgentTool` and only ever rises.
+     */
+    maxConcurrent?: number;
+    /** Queue wait before a spawned worker gives up on a pool slot (ms). */
+    poolQueueTimeoutMs?: number;
+    /** Provider/model for model-invoked spawns — see {@link DelegateSpawnDefaults}. */
+    spawnDefaults?: DelegateSpawnDefaults;
+};
+/** What `delegate_task` returns: the handle plus the outstanding counters. */
+export type DelegateSpawnToolResult = DelegateHandle & {
+    pending: number;
+    ready: number;
+};
+/** Refusal shape shared with the agent tool registrar: recovery text included. */
+export type DelegateRefusal = {
+    isError: true;
+    error: string;
+};

package/dist/types/delegation.js

@@ -0,0 +1,18 @@
+/**
+ * Async delegation (N2) — spawn a background worker, collect it later, in any
+ * order — types.
+ *
+ * Delegation today is a synchronous tool call: the supervising agent blocks
+ * until the worker is done, so four investigations take four times as long as
+ * one and the supervisor cannot do anything useful while it waits. These types
+ * describe the background form — `spawn` hands back a `DelegateHandle`
+ * immediately, `collect` returns whichever worker finished FIRST regardless of
+ * which was started first, and each outcome carries a bounded summary plus a
+ * {@link BankedArtifactRef} to the worker's full report, which is banked to a
+ * file rather than pushed into the conversation.
+ *
+ * Naming: `agentNetwork.ts` already owns `DelegationRule` / `DelegationCondition`
+ * and `isolatedAgent.ts` owns `AgentDelegationTurnState`, so everything here
+ * carries the `Delegate` prefix (Critical Rule 9).
+ */
+export {};

package/dist/types/gitTools.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Read-only git toolset (N4.4) — types.
+ *
+ * A reviewing agent needs git constantly: what changed, who wrote it, what the
+ * merge base was. Handing it a shell to run `git` in is the wrong shape twice
+ * over — it can then run anything, and git itself has write-capable options
+ * (`--output=<file>`, `diff.external`) that a free-form argument string would
+ * carry straight through.
+ *
+ * So these tools are BOUNDED: the model supplies validated values (a ref, a
+ * path, a line range), never flags, and each tool assembles a fixed argv from
+ * them. The whole surface is six read-only subcommands. Execution goes through
+ * the same hardened runner as {@link BackgroundCommandPolicy} — argv arrays,
+ * no shell, a cwd sandboxed to the repository, a timeout, a byte cap — and the
+ * full output is banked, so a 40 MB diff costs a bounded preview plus a
+ * pointer.
+ *
+ * Naming: nothing else in the types folder claims `Git`, and `tools.ts` owns
+ * the unprefixed `Tool*` names, so these carry the `GitTool` prefix
+ * (Critical Rule 9).
+ */
+import type { BankedArtifactRef } from "./artifact.js";
+import type { BackgroundCommandState } from "./backgroundCommand.js";
+/** How `git log` should render each commit. Presets only — never a raw format. */
+export type GitToolLogFormat = "oneline" | "full" | "stat" | "name-only";
+/** Options for `NeuroLink.registerGitTools()`. */
+export type GitToolsetOptions = {
+    /**
+     * Repository root. Every git tool runs here, and every path argument must
+     * resolve inside it.
+     */
+    repoRoot: string;
+    /** Wall-clock budget per git invocation (ms). Default 60_000. */
+    timeoutMs?: number;
+    /** Byte cap per stream. Default 33_554_432 (a big diff is still a diff). */
+    maxOutputBytes?: number;
+    /** Characters of output returned inline. Default 2000, hard cap 4000. */
+    previewChars?: number;
+    /** Executable to run. Default "git"; name an absolute path to pin it. */
+    gitExecutable?: string;
+};
+/**
+ * What every git tool returns.
+ *
+ * `preview` is a bounded head slice for the conversation; `output` points at
+ * the COMPLETE stdout on disk. They are not alternatives — a `git diff` whose
+ * preview looks empty may still have banked megabytes.
+ */
+export type GitToolResult = {
+    /** The exact argv that ran, so the result is reproducible by hand. */
+    command: string[];
+    /** True when git exited 0. */
+    ok: boolean;
+    exitCode?: number;
+    state: BackgroundCommandState;
+    /** Bounded head slice of stdout. */
+    preview: string;
+    /** The FULL stdout, banked (N3). */
+    output: BankedArtifactRef;
+    /** Literal `retrieve_context` call that reads the rest of stdout. */
+    readBackHint: string;
+    /** Bounded head slice of stderr, present only when git wrote something there. */
+    stderrPreview?: string;
+};
+/** Refusal shape shared with the agent tool registrar: recovery text included. */
+export type GitToolRefusal = {
+    isError: true;
+    error: string;
+};

package/dist/types/gitTools.js

@@ -0,0 +1,22 @@
+/**
+ * Read-only git toolset (N4.4) — types.
+ *
+ * A reviewing agent needs git constantly: what changed, who wrote it, what the
+ * merge base was. Handing it a shell to run `git` in is the wrong shape twice
+ * over — it can then run anything, and git itself has write-capable options
+ * (`--output=<file>`, `diff.external`) that a free-form argument string would
+ * carry straight through.
+ *
+ * So these tools are BOUNDED: the model supplies validated values (a ref, a
+ * path, a line range), never flags, and each tool assembles a fixed argv from
+ * them. The whole surface is six read-only subcommands. Execution goes through
+ * the same hardened runner as {@link BackgroundCommandPolicy} — argv arrays,
+ * no shell, a cwd sandboxed to the repository, a timeout, a byte cap — and the
+ * full output is banked, so a 40 MB diff costs a bounded preview plus a
+ * pointer.
+ *
+ * Naming: nothing else in the types folder claims `Git`, and `tools.ts` owns
+ * the unprefixed `Tool*` names, so these carry the `GitTool` prefix
+ * (Critical Rule 9).
+ */
+export {};

package/dist/types/index.d.ts

@@ -18,6 +18,10 @@ export * from "./config.js";
 export * from "./context.js";
 export * from "./conversation.js";
 export * from "./conversationMemoryInterface.js";
+export * from "./delegation.js";
+export * from "./backgroundCommand.js";
+export * from "./gitTools.js";
+export * from "./pathSandbox.js";
 export * from "./domain.js";
 export * from "./errors.js";
 export * from "./evaluation.js";
@@ -58,6 +62,7 @@ export * from "./streaming.js";
 export * from "./subscription.js";
 export * from "./task.js";
 export * from "./taskClassification.js";
+export * from "./tasks.js";
 export * from "./toolDedup.js";
 export * from "./toolResolution.js";
 export * from "./toolRouting.js";

package/dist/types/index.js

@@ -19,6 +19,13 @@ export * from "./config.js";
 export * from "./context.js";
 export * from "./conversation.js";
 export * from "./conversationMemoryInterface.js";
+export * from "./delegation.js";
+// Background commands (N4) — detached execution, banked output, monitors
+export * from "./backgroundCommand.js";
+// Read-only git toolset (N4.4) built on the background-command runner
+export * from "./gitTools.js";
+// Path containment guard shared by the sandboxed execution paths
+export * from "./pathSandbox.js";
 export * from "./domain.js";
 export * from "./errors.js";
 export * from "./evaluation.js";
@@ -59,6 +66,7 @@ export * from "./streaming.js";
 export * from "./subscription.js";
 export * from "./task.js";
 export * from "./taskClassification.js";
+export * from "./tasks.js";
 export * from "./toolDedup.js";
 export * from "./toolResolution.js";
 export * from "./toolRouting.js";

package/dist/types/pathSandbox.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Path sandboxing — types.
+ *
+ * One shape, used by every guard that has to answer "may this path be
+ * touched?": the resolved real path, or the reason it was refused. A
+ * discriminated result rather than a thrown error, because a refusal is an
+ * ordinary answer a tool turns into recovery text, not an exceptional one.
+ *
+ * Naming: `file.ts` already owns `FilePath*`, so this carries the
+ * `PathSandbox` prefix (Critical Rule 9).
+ */
+/**
+ * Outcome of a containment check. Exactly one branch is present, so a caller
+ * that forgets to check `error` cannot accidentally read a path that was
+ * refused.
+ */
+export type PathSandboxResult = {
+    path: string;
+    error?: undefined;
+} | {
+    path?: undefined;
+    error: string;
+};

package/dist/types/pathSandbox.js

@@ -0,0 +1,12 @@
+/**
+ * Path sandboxing — types.
+ *
+ * One shape, used by every guard that has to answer "may this path be
+ * touched?": the resolved real path, or the reason it was refused. A
+ * discriminated result rather than a thrown error, because a refusal is an
+ * ordinary answer a tool turns into recovery text, not an exceptional one.
+ *
+ * Naming: `file.ts` already owns `FilePath*`, so this carries the
+ * `PathSandbox` prefix (Critical Rule 9).
+ */
+export {};

package/dist/types/tasks.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Task-checklist primitive (TodoWrite-style) — types.
+ *
+ * A long-running agent needs a durable, model-visible list of what this run
+ * must finish. The checklist lives on the SESSION, outside the message list,
+ * so summarization/compaction can rewrite the conversation without touching
+ * it, and every tool call returns the whole list so the model re-anchors for
+ * free after a compaction.
+ *
+ * Naming: the scheduler in `task.ts` already owns `Task`, `TaskStatus`,
+ * `TaskDefinition`, `TaskStore`, `TaskRunResult` and `TasksFile`, so every
+ * type here carries the `Checklist` prefix (Critical Rule 9).
+ */
+/** Lifecycle of one checklist item. `closed` means "not done, and here is why". */
+export type ChecklistItemStatus = "pending" | "in_progress" | "done" | "closed";
+export type ChecklistItem = {
+    /** "t1", "t2", … — assigned by the engine, never by the model. */
+    id: string;
+    title: string;
+    status: ChecklistItemStatus;
+    /** Result note, or the REASON an item was closed unfinished. */
+    note?: string;
+    createdAt: number;
+    updatedAt: number;
+};
+/** Everything one session's checklist holds. Never stored in messages. */
+export type ChecklistState = {
+    sessionId: string;
+    items: ChecklistItem[];
+    updatedAt: number;
+};
+export type ChecklistCreateInput = {
+    titles: string[];
+};
+export type ChecklistUpdateInput = {
+    id: string;
+    status: ChecklistItemStatus;
+    note?: string;
+};
+/**
+ * Background delegates outstanding for a session. Populated by the async
+ * delegation primitive; zero while that primitive is unused.
+ */
+export type ChecklistDelegateCounts = {
+    pending: number;
+    ready: number;
+};
+/** Supplies {@link ChecklistDelegateCounts} to every checklist tool result. */
+export type ChecklistDelegateCountsSource = (sessionId: string) => ChecklistDelegateCounts;
+/**
+ * Background commands outstanding for a session. Populated by the
+ * background-command primitive; zero while that primitive is unused.
+ */
+export type ChecklistCommandCounts = {
+    running: number;
+    finished: number;
+};
+/** Supplies {@link ChecklistCommandCounts} to every checklist tool result. */
+export type ChecklistCommandCountsSource = (sessionId: string) => ChecklistCommandCounts;
+/**
+ * Every `tasks_*` tool returns this — the model re-anchors on the full list
+ * on each call, which is what makes the checklist survive compaction with no
+ * re-injection machinery.
+ */
+export type ChecklistToolResult = {
+    items: ChecklistItem[];
+    counts: Record<ChecklistItemStatus, number>;
+    /** Background delegates not yet collected (0 when delegation is unused). */
+    delegatesPending: number;
+    delegatesReady: number;
+    /**
+     * Background commands still running (0 when the command primitive is
+     * unused). Carried here for the same reason the delegate counters are: the
+     * model learns "the build finished" from any `tasks_list`, with no polling
+     * and no change to the core loop.
+     */
+    commandsRunning: number;
+    /** Background commands that have settled and can be read. */
+    commandsFinished: number;
+};
+/** Refusal shape shared with the agent tool registrar: recovery text included. */
+export type ChecklistRefusal = {
+    isError: true;
+    error: string;
+};

package/dist/types/tasks.js

@@ -0,0 +1,14 @@
+/**
+ * Task-checklist primitive (TodoWrite-style) — types.
+ *
+ * A long-running agent needs a durable, model-visible list of what this run
+ * must finish. The checklist lives on the SESSION, outside the message list,
+ * so summarization/compaction can rewrite the conversation without touching
+ * it, and every tool call returns the whole list so the model re-anchors for
+ * free after a compaction.
+ *
+ * Naming: the scheduler in `task.ts` already owns `Task`, `TaskStatus`,
+ * `TaskDefinition`, `TaskStore`, `TaskRunResult` and `TasksFile`, so every
+ * type here carries the `Checklist` prefix (Critical Rule 9).
+ */
+export {};