@sheetxl/mcp 0.0.0-stage → 0.8.0-beta.15

package/types/src/instances.d.ts

@@ -0,0 +1,104 @@
+import { ToolLogRecord } from '@sheetxl/utils-node';
+export interface InstanceRecord {
+    /** The instance token, matching the one embedded in this process's sandbox ids. */
+    readonly instance: string;
+    readonly pid: number;
+    /** The process that launched this server — the MCP client session. Absent on older records. */
+    readonly ppid?: number;
+    /** ISO 8601. */
+    readonly startedAt: string;
+    readonly workspace: string;
+    /** The tool log this process appends to, when logging is on — where its crashed calls are written. */
+    readonly logPath?: string;
+}
+export interface InstanceCensus {
+    /** The workspace this census was taken for — what {@link liveSiblings} re-asks about. */
+    readonly workspace: string;
+    /**
+     * Other LIVE servers for this workspace AT STARTUP — other client sessions, a duplicate
+     * registration ({@link isSameClient}), or a predecessor still exiting when this one started. A
+     * snapshot: anything reported later asks {@link liveSiblings} instead.
+     */
+    readonly siblings: readonly InstanceRecord[];
+    /** The most recent dead predecessor for this workspace, if it ran recently enough to matter. */
+    readonly replaced: InstanceRecord | null;
+    /** The calls {@link replaced} was running when it died — empty when it was not mid-call. */
+    readonly crashedCalls: readonly ToolLogRecord[];
+}
+/** `12s` / `4m` / `2h` — an age, for a report that must date itself rather than read as timeless. */
+export declare function ago(from: Date): string;
+/**
+ * Record this process and report what it found: live siblings, and the instance it replaced.
+ *
+ * @remarks
+ * **There is deliberately no matching `unregister`.** A record is removed by the NEXT start, not by
+ * its own exit, for two reasons: a killed extension host never runs an exit handler — which is
+ * exactly the abrupt restart worth reporting — and deleting on a graceful shutdown would erase the
+ * evidence that a restart happened at all, making the tidy case the one that reports nothing. Dead
+ * records cost one `kill(pid, 0)` each and are pruned here, with their calls markers: a call still
+ * marked is written to the dead process's tool log as `crashed`, whatever its workspace.
+ *
+ * Synchronous: it runs once, before the transport connects.
+ *
+ * @param logPath The tool log this process appends to, if logging is on.
+ */
+export declare function registerInstance(instance: string, workspace: string, startedAt: Date, logPath?: string | null): InstanceCensus;
+/**
+ * Marks a call as running until the returned function is called — on its answer, or its failure.
+ *
+ * @remarks
+ * Written synchronously, before the call starts, because a server that runs out of memory dies
+ * inside the call: an async write queued at its start is still queued when the process goes. What
+ * a successor finds in the marker is the call that never returned ({@link registerInstance}).
+ *
+ * @param record The call as the tool log would record it, without its outcome.
+ */
+export declare function beginCall(record: ToolLogRecord): () => void;
+/**
+ * The other servers for `workspace` that are alive NOW.
+ *
+ * @remarks
+ * The startup census cannot answer this for long. A server started while its predecessor is still
+ * exiting — the normal shape of a VS Code restart — sees that predecessor as a live sibling, and a
+ * snapshot would go on reporting two servers long after it is gone. A sibling started AFTER this one
+ * is in no snapshot at all. So a report re-reads the directory, the same way startup does.
+ *
+ * Read-only: dead records are left for the next start to prune, because to it they are the evidence
+ * of a restart (see {@link registerInstance}).
+ */
+export declare function liveSiblings(workspace: string): InstanceRecord[];
+/**
+ * Whether a sibling was launched by the same client session as this process — a duplicate
+ * registration rather than a second chat.
+ *
+ * @remarks
+ * Judged by parent pid. A client that launches the server through a wrapper (`npx`, `cmd /c`) gives
+ * each copy its own parent, so a duplicate behind a wrapper reads as two sessions and goes
+ * unreported. That is the cheaper mistake: the alternative warned about every second chat, which is
+ * the common case and needs no fix. A record without a `ppid` predates it and is not judged.
+ */
+export declare function isSameClient(record: InstanceRecord): boolean;
+/**
+ * `census` as it stands NOW: siblings re-read with {@link liveSiblings}, and a startup sibling that
+ * has since exited counted as the instance this one replaced.
+ *
+ * @remarks
+ * A predecessor still exiting when this server started is a sibling to the startup census, not a
+ * replaced instance — startup only reads replacement from a DEAD record. Once it is gone it is
+ * exactly the restart the agent needs to hear about, and dropping it from the siblings alone would
+ * report nothing at all. Matched on `instance`, not pid: a recycled pid is a different server.
+ */
+export declare function recount(census: InstanceCensus): InstanceCensus;
+/**
+ * The one-shot notice for the first tool call of this process, or `null` when there is nothing an
+ * agent needs to un-believe.
+ *
+ * @remarks
+ * Phrased as *what is now false*, not as *what happened*: an agent resuming a conversation across a
+ * restart does not need an event log, it needs to know which of the ids and answers it is holding
+ * have stopped being true. It rides a tool RESULT rather than the handshake because a resumed
+ * conversation replays as [instructions][old turns][now] — a warning in the instructions sits
+ * before the beliefs it is meant to correct, and is read as older than they are.
+ */
+export declare function staleStateNotice(census: InstanceCensus, startedAt: Date): string | null;
+//# sourceMappingURL=instances.d.ts.map

package/types/src/lib/Types.d.ts

@@ -0,0 +1,17 @@
+export interface McpRequestPayload {
+    id: string;
+    /**
+     * The relay command vocabulary (mirrored in the extension's `src/shared/protocol.ts` — edit
+     * both). `tool` executes a `TOOLS` descriptor by name; `rangeSelect` is host-initiated only
+     * (the `vscode://…/select` deep link) — no MCP tool drives it.
+     */
+    cmd: 'tool' | 'rangeSelect' | 'run' | 'revert' | 'restore' | 'listCommits' | 'serialize' | 'highlight' | 'prompt';
+    args?: Record<string, string>;
+    workbookId?: string;
+}
+export interface McpResponsePayload {
+    id: string;
+    result?: unknown;
+    error?: string;
+}
+//# sourceMappingURL=Types.d.ts.map

package/types/src/lib/index.d.ts

@@ -0,0 +1,2 @@
+export * from './Types.ts';
+//# sourceMappingURL=index.d.ts.map

package/types/src/lib/runReport.d.ts

@@ -0,0 +1,158 @@
+import { z } from 'zod';
+import { ScriptingApi } from '@sheetxl/sdk';
+import { RunDelta } from '@sheetxl/query';
+/**
+ * A minimal, valid starting-point macro embedded in the `macro_run` tool description so every agent
+ * has a correct template to copy. Conventions it demonstrates:
+ *  - a NAMED `export default` entry (anonymous trips SXL1002),
+ *  - ONE parameter, the runtime context (`ctx: SheetXL.IScript.ScriptContext`), with the workbook
+ *    reached through `ctx.wb`. This is the portable signature: the identical entry also runs as a
+ *    CLI script, where the runner passes its own context. NB: ScriptContext is nested under IScript,
+ *    so `SheetXL.ScriptContext` is NOT valid.
+ *  - the SheetXL API is ambient (auto-imported `SheetXL` namespace; no `import` needed),
+ *  - read via the workbook API, write output via `ctx.log`.
+ *
+ * The older target-first form (`(workbook: SheetXL.IWorkbook, ctx: …)`) remains valid — a macro may
+ * still ask for the selected sheet or range as its first parameter.
+ *
+ * Covered by a test (`runReport.test.ts`) so this template is guaranteed to compile + run.
+ */
+export declare const EXAMPLE_SCRIPT = "/** Reads A1 and logs its value. */\nexport default function main(ctx: SheetXL.IScript.ScriptContext): void {\n  const value = ctx.wb.getWorksheet().getRange('A1').getValue();\n  ctx.log(`A1 = ${value}`);\n}\n";
+/**
+ * One positioned diagnostic in a {@link runOutputShape} report. Offsets from the compiler are
+ * resolved to 1-based line/column against the submitted source so the agent can pinpoint the fix.
+ */
+export declare const runDiagnosticShape: {
+    severity: z.ZodEnum<{
+        error: "error";
+        warning: "warning";
+    }>;
+    code: z.ZodString;
+    line: z.ZodNumber;
+    column: z.ZodNumber;
+    message: z.ZodString;
+    /** An actionable suggestion the agent can apply to resolve the diagnostic (the MCP "quick fix"). */
+    fix: z.ZodOptional<z.ZodString>;
+};
+/**
+ * Structured result of `run`. This is the agent's primary write path - it is intentionally
+ * machine-parseable AND mirrored in human-readable text. `status` tells the agent how to react:
+ * `compile_error` → fix the source and call again; `runtime_error` → the run threw; `ok` → done
+ * (use `commitId` with `session_revert`), and its `delta` says what the commit changed.
+ */
+export declare const runOutputShape: {
+    status: z.ZodEnum<{
+        ok: "ok";
+        compile_error: "compile_error";
+        runtime_error: "runtime_error";
+        drift: "drift";
+    }>;
+    /** How the source ran — decided by the code itself (default export = script), reported so the inference stays observable. */
+    form: z.ZodOptional<z.ZodEnum<{
+        snippet: "snippet";
+        script: "script";
+    }>>;
+    /** The session the source ran against — echoed so a write to the wrong workbook is visible. */
+    sessionId: z.ZodOptional<z.ZodString>;
+    commitId: z.ZodOptional<z.ZodString>;
+    result: z.ZodOptional<z.ZodUnknown>;
+    /** The result rendered as markdown — the final expression of a snippet, or a script's return value. */
+    resultMarkdown: z.ZodOptional<z.ZodString>;
+    logs: z.ZodOptional<z.ZodString>;
+    diagnostics: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        severity: z.ZodEnum<{
+            error: "error";
+            warning: "warning";
+        }>;
+        code: z.ZodString;
+        line: z.ZodNumber;
+        column: z.ZodNumber;
+        message: z.ZodString;
+        fix: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    error: z.ZodOptional<z.ZodString>;
+    /**
+     * What the run's commit changed: written ranges and what they replaced, formulas with their
+     * results, dependents, errors, and the names, rules and charts over them (`RunDelta` from
+     * `@sheetxl/query`). Present on an `ok` run that wrote cells.
+     */
+    delta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+};
+/** A compiler diagnostic as it arrives on `RunResults.diagnostics` (character offset + length). */
+export interface RawDiagnostic {
+    severity: 'error' | 'warning';
+    code: string;
+    start: number;
+    message: string;
+}
+/** The subset of `IScript.RunResults` this builder consumes. */
+export interface RunResultLike {
+    ok: boolean;
+    result?: unknown;
+    commitId?: string;
+    error?: any;
+    /** The error's `name`, from a session that can only send the error as its message. */
+    errorName?: string;
+    diagnostics?: RawDiagnostic[];
+    /**
+     * The result rendered as markdown, produced WHERE THE RESULT LIVES — the sandbox session
+     * in-process, or the webview for an attended session — because a live SDK object cannot cross a
+     * JSON boundary and render afterwards.
+     */
+    resultMarkdown?: string;
+    /**
+     * What the run's commit changed, read where the workbook lives once the calculation settled,
+     * for the same reason as {@link resultMarkdown}. JSON-safe.
+     */
+    delta?: RunDelta;
+    /** {@link delta} as the report's lines; or, when it could not be read, why. */
+    deltaMarkdown?: string;
+}
+/** Context {@link buildRunReport} needs to attribute a run correctly. */
+export interface RunReportOptions {
+    /** How the source ran; reported in the text so the inference is observable. */
+    form?: 'snippet' | 'script';
+    /**
+     * The session the run targeted, echoed on every outcome. `resolvedFrom` names the token the
+     * caller passed when it was not the id itself.
+     */
+    session?: {
+        id: string;
+        resolvedFrom?: string;
+    };
+    /**
+     * The scripting API index. Given, a member the code used and the API does not have is answered
+     * with the nearest ones, inline — the lookup the agent would make next.
+     */
+    api?: ScriptingApi.Index;
+}
+/** A positioned diagnostic in the report (1-based line/column). */
+export interface RunDiagnostic {
+    severity: 'error' | 'warning';
+    code: string;
+    line: number;
+    column: number;
+    message: string;
+    fix?: string;
+}
+export interface RunReport {
+    content: {
+        type: 'text';
+        text: string;
+    }[];
+    structuredContent: Record<string, unknown>;
+    isError?: boolean;
+    [key: string]: unknown;
+}
+/** Resolves a character offset into 1-based line/column using the source text. */
+export declare function offsetToLineCol(source: string, offset: number): {
+    line: number;
+    column: number;
+};
+/**
+ * Builds the dual (text + structured) `run` report from a {@link RunResultLike} and the
+ * captured logs. The payload order is the contract's: status first, diagnostics and logs in the
+ * middle, the result LAST.
+ */
+export declare function buildRunReport(source: string, result: RunResultLike, logs: string, options?: RunReportOptions): RunReport;
+//# sourceMappingURL=runReport.d.ts.map

package/types/src/lib.d.ts

@@ -0,0 +1,2 @@
+export * from './lib/index.ts';
+//# sourceMappingURL=lib.d.ts.map

package/types/src/prepareRun.d.ts

@@ -0,0 +1,56 @@
+import { IModule } from '@sheetxl/sdk';
+import { Diagnostic } from '@sheetxl/scripting';
+import { Snippet } from '@sheetxl/runner';
+import { RunResultLike } from './lib/runReport';
+/** The environment variable that sets `run`'s time limit, in seconds; `0` turns the limit off. */
+export declare const RUN_TIMEOUT_ENV = "SHEETXL_RUN_TIMEOUT";
+/** `run`'s time limit in ms from `SHEETXL_RUN_TIMEOUT` (seconds), or `null` when it is off. */
+export declare function resolveRunTimeoutMs(value?: string | undefined): number | null;
+/**
+ * A source prepared for execution: classified, wrapped when it is a snippet, and compiled.
+ *
+ * @remarks
+ * This is the MCP half of the shared snippet contract (`@sheetxl/runner`'s {@link Snippet}): the
+ * CLI hands the same wrapper to its module loader; here it goes through the `ScriptCompiler`,
+ * because both session kinds execute a compiled module — a sandbox in-process, an attended session in
+ * the webview (whose CSP blocks the compiler).
+ */
+export interface PreparedRun {
+    /** How the source ran — decided by the code itself (default export = script), never declared. */
+    form: Snippet.SourceForm;
+    /** The compiled module, or `null` when nothing compiled (see {@link diagnostics}). */
+    module: IModule.JSON | null;
+    /**
+     * This compile's diagnostics, positioned in the SUBMITTED source — the one coordinate system the
+     * caller has. A snippet is compiled inside a generated wrapper whose statements are rewritten,
+     * so its offsets are translated here, once, rather than handed on for every reader to undo.
+     */
+    diagnostics: Diagnostic[];
+    /**
+     * Set only when the snippet ran without implicit await or a result value. Worth surfacing — a
+     * snippet quietly returning `undefined` is worse than one that failed.
+     */
+    warning?: string;
+    /**
+     * The run's stop-check key (see `RunGuard`), or `undefined` when the time limit is off. The
+     * caller aborts with it when the client cancels, and releases it when the run is over.
+     */
+    runKey?: string;
+}
+/**
+ * Classifies, wraps and compiles a `run` source.
+ *
+ * @remarks
+ * A snippet is rewritten exactly once, from its parsed top-level statements: implicit await on each,
+ * final expression as the result. A source that does not parse is wrapped verbatim, so the compiler
+ * reports the syntax error against the user's own code rather than a transform's guess at it. The
+ * compiler is loaded lazily, the first time a run actually happens.
+ */
+export declare function prepareRun(source: string, timeoutMs?: number | null): Promise<PreparedRun>;
+/**
+ * The type-check findings that explain how a run went wrong, positioned in the submitted source:
+ * errors for a run that threw, warnings for a snippet whose answer was `undefined`. Empty for a
+ * run with neither symptom, which is never checked.
+ */
+export declare function diagnoseOutcome(source: string, result: RunResultLike): Promise<Diagnostic[]>;
+//# sourceMappingURL=prepareRun.d.ts.map

package/types/src/relay.d.ts

@@ -0,0 +1,102 @@
+import { IWorkbook, IModule } from '@sheetxl/sdk';
+import { ToolLogRecord } from '@sheetxl/utils-node';
+import { CommitEntry, ListCommitsOptions, SessionInfo, RunOutcome, Highlight, HighlightResult, PromptSpec, PromptResult } from './SessionRegistry.ts';
+/**
+ * Finds the relay server, or null when no client UI is running → sandboxes only.
+ *
+ * @remarks
+ * Lock discovery itself lives in `@sheetxl/utils-node` (`discoverRelay`), because presence is not an
+ * MCP fact: `sheetxl info` reads the same locks to answer attended/unattended without a server
+ * in the picture. Two copies of the lock protocol would drift, and the surface that drifted
+ * would report "nobody is watching" while somebody was. What stays here is the protocol layered
+ * over the endpoint — macros, presence, prompts.
+ */
+export declare function findRelay(): Promise<RelayClient | null>;
+/**
+ * A prompt that ended because the editor went away, not because the user answered or dismissed it.
+ * Its message is written for the agent: what happened and what to do next.
+ */
+export declare class EditorClosedError extends Error {
+    readonly name = "EditorClosedError";
+}
+/**
+ * Whether `err` is the relay being unreachable — Node's `fetch` rejects with a bare `TypeError:
+ * fetch failed` and puts the socket error on `cause`.
+ */
+export declare function isUnreachable(err: unknown): boolean;
+/**
+ * HTTP client for the relay running inside a client UI (the VS Code extension host). The MCP child
+ * process has no direct access to UI state, so attended-session operations are forwarded over HTTP to
+ * the relay, which owns the webview registry and routes by `workbookId` (or its active workbook).
+ */
+export declare class RelayClient {
+    private readonly port;
+    private readonly token;
+    constructor(port: number, token: string);
+    /** The endpoint fields, for the discovery helpers in `@sheetxl/utils-node`. */
+    private get endpoint();
+    /**
+     * Execute a `TOOLS` descriptor (grep, …) in the webview that owns the workbook — the only place
+     * an attended session's live `IWorkbook` exists. `args` is JSON-encoded because the relay's args
+     * are string→string; the webview parses it back and resolves the descriptor by name.
+     */
+    tool(name: string, args: Record<string, unknown>, workbookId?: string): Promise<string>;
+    /**
+     * Executes an **already-compiled** macro against an attended workbook. The MCP server compiles on Node
+     * (the webview's CSP blocks the compiler) and ships the {@link IModule.JSON} artifact; the webview
+     * loads it via a `data:` URL and runs the entry as one transaction.
+     */
+    run(compiled: IModule.JSON, opts: {
+        description?: string;
+        originalCommitId?: string;
+        args?: Record<string, any>;
+    }, workbookId?: string): Promise<RunOutcome>;
+    /**
+     * Mark ranges in the webview's grid. Declarative — replaces the prior highlight; an empty
+     * `ranges` clears it. `ranges` is JSON-encoded because the relay's `args` are string→string.
+     *
+     * @remarks
+     * The webview RESOLVES each address against the live workbook before marking anything, so an
+     * unparseable range rejects here (the dispatch throws) instead of failing silently at render
+     * time. What comes back is what the grid resolved — sheet-qualified and normalized — and that,
+     * not the request, is what the caller is told.
+     */
+    highlight(highlight: Highlight, workbookId?: string): Promise<HighlightResult>;
+    /**
+     * Show a grid prompt and resolve when the user answers — the MCP `prompt` task's internal channel.
+     * "Show" is a quick acked request (NOT held); the answer is then **polled** from the relay's
+     * answer-store. No held connection ⇒ no ~5-min fetch ceiling, so a wait of minutes/hours is fine.
+     * The agent meanwhile polls `tasks/get` and the LLM is idle. Terminates on answer, on the workbook
+     * closing (`gone`), or a 1h safety cap.
+     */
+    prompt(spec: PromptSpec, workbookId?: string, opts?: {
+        signal?: AbortSignal;
+    }): Promise<PromptResult>;
+    revert(commitId: string, workbookId?: string): Promise<void>;
+    /** The attended session's commit log (newest first), read from the webview's live store. */
+    listCommits(opts: ListCommitsOptions, workbookId?: string): Promise<CommitEntry[]>;
+    restore(commitId: string, workbookId?: string): Promise<void>;
+    /** Asks the webview to serialize its live workbook to JSON (the fork-from-attended path). */
+    serialize(workbookId?: string): Promise<IWorkbook.JSON>;
+    /**
+     * The attended sessions currently open in the client UI, as {@link SessionInfo} for the registry.
+     * Attended sessions are owned by a webview (they have a live view) and are opened-from-file today.
+     */
+    listAttendedSessions(): Promise<SessionInfo[]>;
+    /**
+     * Mirror one tool-call record into the client UI's live log (VS Code's SheetXL output channel).
+     * The record is the same one the JSONL sink would write — see `setToolLogMirror` in
+     * `@sheetxl/utils-node`; the UI decides how much of it to show.
+     *
+     * @remarks
+     * Fire-and-forget in both directions: it is not awaited (the call it describes has already
+     * finished — tracing must not add latency to it), and a failure is dropped rather than raised. A
+     * dead endpoint is normal here: the UI restarts, and this is the one channel that must not care.
+     *
+     * This is also why the trace covers **sandbox** sessions, which never otherwise touch the relay —
+     * a headless session's work was invisible in the UI even while the user watched it happen.
+     */
+    trace(record: ToolLogRecord): void;
+    private dispatch;
+}
+//# sourceMappingURL=relay.d.ts.map

package/types/src/screenshot.d.ts

@@ -0,0 +1,23 @@
+import { IWorkbook } from '@sheetxl/sdk';
+import { ScreenshotOptions, ScreenshotResult } from '@sheetxl/screenshot';
+/**
+ * One headless browser per server, started on the first screenshot and closed after a minute
+ * without one. A browser that exited is replaced on the next call.
+ */
+export declare class ScreenshotService {
+    private _screenshotter;
+    private _idle;
+    private _active;
+    /**
+     * Render a range of a workbook snapshot.
+     *
+     * @throws {@link ScreenshotUnavailableError} when this machine has no usable browser.
+     */
+    capture(json: IWorkbook.JSON, options: ScreenshotOptions): Promise<ScreenshotResult>;
+    /** Close the browser, if one is running. */
+    close(): Promise<void>;
+    private _acquire;
+    private _armIdle;
+    private _clearIdle;
+}
+//# sourceMappingURL=screenshot.d.ts.map

package/types/src/server.d.ts

@@ -0,0 +1,37 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { InstanceCensus } from './instances.ts';
+import { PromptResult, PromptSpec, SessionRegistry } from './SessionRegistry.ts';
+/**
+ * Normalize the `prompt` tool's two shapes — one question (`message`/`options`/`range`) or several
+ * (`questions`) — into one list of questions. Throws, with what to change, when the call is neither
+ * or both, or repeats a question id.
+ */
+export declare function toPromptSpec(args: {
+    message?: string;
+    options?: {
+        id: string;
+        label: string;
+        description?: string;
+    }[];
+    range?: string;
+    questions?: {
+        id: string;
+        header?: string;
+        message: string;
+        options?: {
+            id: string;
+            label: string;
+            description?: string;
+        }[];
+        range?: string;
+    }[];
+}): PromptSpec;
+/** The agent-facing text for a prompt's outcome. A single `message` question reads as it always has. */
+export declare function describePromptResult(spec: PromptSpec, result: PromptResult, single: boolean): string;
+/**
+ * The single MCP server. There is no connected-vs-direct mode: the server owns sandbox sessions
+ * in-process and surfaces attended sessions from the relay (via the {@link SessionRegistry}).
+ * Every tool routes by `session_id`.
+ */
+export declare function createServer(registry: SessionRegistry, census?: InstanceCensus): McpServer;
+//# sourceMappingURL=server.d.ts.map

package/types/src/taskStore.d.ts

@@ -0,0 +1,28 @@
+import { InMemoryTaskStore } from '@modelcontextprotocol/sdk/experimental/tasks';
+import { Result, Task } from '@modelcontextprotocol/sdk/types.js';
+/**
+ * An {@link InMemoryTaskStore} that surfaces a **failed** task's reason in `statusMessage`.
+ *
+ * The base store records the error only in the task *result*, so the `Task` object — and thus
+ * `tasks/get` and `notifications/tasks/status` — carries no `statusMessage`. Clients then see
+ * "failed" with "No additional information". Here we copy the failed result's text into
+ * `statusMessage` so the reason for **any** failure (not just one specific path) is legible without
+ * a separate `tasks/result` fetch.
+ *
+ * Implementation note: a terminal task can't be mutated via `updateTaskStatus` (it rejects terminal
+ * transitions), and `getTask` returns a copy — so we set the message while the task is still
+ * `working` (a no-op status change that records `statusMessage`), then let `super.storeTaskResult`
+ * move it to `failed`. `storeTaskResult` does not clear `statusMessage`, so it persists.
+ */
+export declare class StatusMessageTaskStore extends InMemoryTaskStore {
+    /** Per-task cancellation controllers, fired when a task transitions to `cancelled`. */
+    private readonly cancels;
+    /**
+     * An `AbortSignal` that fires when this task is cancelled (e.g. via `tasks/cancel`). The prompt
+     * task's background work waits on it to stop polling and clear the grid. Idempotent per task.
+     */
+    cancelSignal(taskId: string): AbortSignal;
+    storeTaskResult(taskId: string, status: 'completed' | 'failed', result: Result, sessionId?: string): Promise<void>;
+    updateTaskStatus(taskId: string, status: Task['status'], statusMessage?: string, sessionId?: string): Promise<void>;
+}
+//# sourceMappingURL=taskStore.d.ts.map