stitchkit 0.91.2 → 0.92.0

package/dist/cli.js

@@ -1,7 +1,10 @@
 import {
   CliArgumentError,
   DEFAULT_EXIT_CODES,
+  cliExitCode,
+  cliInvocationResult,
   createCli,
+  createCliInvoker,
   defineCliCommand,
   emitResult,
   extractCliGlobalOptions,
@@ -11,12 +14,18 @@ import {
   readCapped,
   renderCliView,
   routeCliArgv
-} from "./index-seyy8dvn.js";
+} from "./index-7n145nbe.js";
+import {
+  serializeCanonicalJson
+} from "./index-0j3vcp5m.js";
 import"./index-sbdmyz75.js";
-import"./index-a2nzz56k.js";
-import"./index-4x809vqd.js";
-import"./index-s3dssqxp.js";
-import"./index-vsbzgd7b.js";
+import"./index-2c2bjw3s.js";
+import {
+  argumentsDigest
+} from "./index-a916km3r.js";
+import"./index-mzvgxp0n.js";
+import"./index-yn8remb1.js";
+import"./index-tmwcrptx.js";
 import"./index-f9mb610r.js";
 import"./index-e0znv5gn.js";
 import"./index-0a349c33.js";
@@ -26,8 +35,8 @@ import"./index-zcgf3gqf.js";
 import {
   coerceJsonArgs
 } from "./index-7zbps32p.js";
-import"./index-8z9we758.js";
-import"./index-fenaekmk.js";
+import"./index-vjpvjqpn.js";
+import"./index-h9etkkyk.js";
 import"./index-cby4ar3v.js";
 import {
   AppError
@@ -35,7 +44,61 @@ import {
 import {
   safeJsonParse
 } from "./index-kzfs85xp.js";
-import"./index-77fekveh.js";
+import {
+  isRecord
+} from "./index-77fekveh.js";
+// src/tools/cli-checkpoint.ts
+import { existsSync, readFileSync } from "node:fs";
+
+// src/internal/atomic-file.ts
+import { randomBytes } from "node:crypto";
+import { closeSync, fchmodSync, fsyncSync, openSync, renameSync, writeSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+function writeFileAtomic(target, bytes, mode) {
+  const staged = join(dirname(target), `.${basename(target)}.${randomBytes(12).toString("hex")}.tmp`);
+  const handle = openSync(staged, "wx", mode);
+  try {
+    writeSync(handle, bytes);
+    fchmodSync(handle, mode);
+    fsyncSync(handle);
+  } finally {
+    closeSync(handle);
+  }
+  renameSync(staged, target);
+}
+
+// src/tools/cli-checkpoint.ts
+function emptyCheckpoint(entries) {
+  return {
+    entries,
+    digestOf: (line) => argumentsDigest({ command: line.command, args: line.args }),
+    record(id, digest, answer) {
+      entries[id] = { digest, answer };
+    }
+  };
+}
+function readCliCheckpoint(path) {
+  if (!existsSync(path))
+    return emptyCheckpoint({});
+  try {
+    const parsed = safeJsonParse(readFileSync(path, "utf8"));
+    const entries = {};
+    if (isRecord(parsed) && isRecord(parsed.entries)) {
+      for (const [id, value] of Object.entries(parsed.entries)) {
+        if (isRecord(value) && typeof value.digest === "string") {
+          entries[id] = { digest: value.digest, answer: value.answer };
+        }
+      }
+    }
+    return emptyCheckpoint(entries);
+  } catch {
+    return emptyCheckpoint({});
+  }
+}
+function writeCliCheckpoint(path, checkpoint) {
+  writeFileAtomic(path, Buffer.from(`${JSON.stringify({ entries: checkpoint.entries }, null, 2)}
+`, "utf8"), 384);
+}
 // src/tools/cli-installer.ts
 function shellQuote(value) {
   return `'${value.replaceAll("'", `'"'"'`)}'`;
@@ -155,28 +218,98 @@ ${cases}
 esac`;
 }
 // src/tools/cli-manifest.ts
+import { z as z2 } from "zod";
+
+// src/tools/cli-signature.ts
+import {
+  createPrivateKey,
+  createPublicKey,
+  sign as cryptoSign,
+  verify as cryptoVerify
+} from "node:crypto";
 import { z } from "zod";
-var CliBuildTargetSchema = z.object({
-  platform: z.string().min(1),
-  arch: z.string().min(1)
+var CliBuildSignatureSchema = z.object({
+  algorithm: z.literal("ed25519"),
+  keyId: z.string().min(1),
+  signature: z.string().min(1)
+});
+function cliManifestSigningPayload(manifest) {
+  return serializeCanonicalJson({
+    name: manifest.name,
+    version: manifest.version,
+    commit: manifest.commit,
+    builtAt: manifest.builtAt,
+    assets: manifest.assets.map((asset) => ({
+      platform: asset.platform,
+      arch: asset.arch,
+      compression: asset.compression,
+      size: asset.size,
+      sha256: asset.sha256
+    }))
+  });
+}
+function publicKeyOf(material) {
+  const trimmed = material.trim();
+  if (trimmed.includes("BEGIN PUBLIC KEY"))
+    return createPublicKey(trimmed);
+  const raw = Buffer.from(trimmed, "base64");
+  if (raw.length !== 32) {
+    throw new Error("[stitchkit] an Ed25519 public key is 32 bytes or SPKI PEM");
+  }
+  const spki = Buffer.concat([Buffer.from("302a300506032b6570032100", "hex"), raw]);
+  return createPublicKey({ key: spki, format: "der", type: "spki" });
+}
+function signCliManifest(manifest, options) {
+  const signature = cryptoSign(null, Buffer.from(cliManifestSigningPayload(manifest), "utf8"), createPrivateKey(typeof options.privateKey === "string" ? options.privateKey : { key: Buffer.from(options.privateKey), format: "der", type: "pkcs8" }));
+  return {
+    algorithm: "ed25519",
+    keyId: options.keyId,
+    signature: signature.toString("base64")
+  };
+}
+function verifyCliManifest(manifest, signature, trust) {
+  const keys = trust?.keys;
+  if (!keys || Object.keys(keys).length === 0)
+    return "unenforced";
+  if (!signature)
+    return "missing";
+  const material = Object.hasOwn(keys, signature.keyId) ? keys[signature.keyId] : undefined;
+  if (material === undefined)
+    return "unknown-key";
+  try {
+    const ok = cryptoVerify(null, Buffer.from(cliManifestSigningPayload(manifest), "utf8"), publicKeyOf(material), Buffer.from(signature.signature, "base64"));
+    return ok ? "valid" : "invalid";
+  } catch {
+    return "invalid";
+  }
+}
+function cliSignatureAccepted(verdict) {
+  return verdict === "valid" || verdict === "unenforced";
+}
+
+// src/tools/cli-manifest.ts
+var CliBuildTargetSchema = z2.object({
+  platform: z2.string().min(1),
+  arch: z2.string().min(1)
 });
 var CliBuildAssetSchema = CliBuildTargetSchema.extend({
-  url: z.url(),
-  compression: z.enum(["gzip", "none"]).default("none"),
-  size: z.int().positive(),
-  sha256: z.string().regex(/^[0-9a-f]{64}$/, "sha256 must be 64 lowercase hex characters")
+  url: z2.url(),
+  compression: z2.enum(["gzip", "none"]).default("none"),
+  size: z2.int().positive(),
+  sha256: z2.string().regex(/^[0-9a-f]{64}$/, "sha256 must be 64 lowercase hex characters")
 });
-var CliBuildManifestSchema = z.object({
-  name: z.string().min(1),
-  version: z.string().min(1),
-  commit: z.string().min(1),
-  builtAt: z.iso.datetime(),
-  assets: z.array(CliBuildAssetSchema)
+var CliBuildManifestSchema = z2.object({
+  name: z2.string().min(1),
+  version: z2.string().min(1),
+  commit: z2.string().min(1),
+  builtAt: z2.iso.datetime(),
+  assets: z2.array(CliBuildAssetSchema),
+  signature: CliBuildSignatureSchema.optional()
 });
-var CliBuildStampSchema = z.object({
-  version: z.string().min(1),
-  commit: z.string().min(1),
-  builtAt: z.iso.datetime()
+var CliBuildStampSchema = z2.object({
+  version: z2.string().min(1),
+  commit: z2.string().min(1),
+  builtAt: z2.iso.datetime()
 });
 function formatCliBuildStamp(stamp, name) {
   const prefix = name ? `${name} ` : "";
@@ -188,26 +321,30 @@ function currentCliBuildTarget() {
 function selectCliBuildAsset(manifest, target = currentCliBuildTarget()) {
   return manifest.assets.find((asset) => asset.platform === target.platform && asset.arch === target.arch);
 }
+function isManifestList(value) {
+  return Array.isArray(value);
+}
 function assertCliPublishable(previous, next) {
-  if (!previous)
-    return;
-  if (previous.version !== next.version)
-    return;
-  if (previous.commit === next.commit)
-    return;
-  throw new Error(`[stitchkit] ${next.name} ${next.version} was already published from commit ${previous.commit}; ` + `refusing to republish it from ${next.commit} — bump the version instead`);
+  const published = previous === undefined ? [] : isManifestList(previous) ? previous : [previous];
+  for (const candidate of published) {
+    if (candidate.version !== next.version)
+      continue;
+    if (candidate.commit === next.commit)
+      continue;
+    throw new Error(`[stitchkit] ${next.name} ${next.version} was already published from commit ${candidate.commit}; ` + `refusing to republish it from ${next.commit} — bump the version instead`);
+  }
 }
 // src/tools/cli-profile.ts
 import {
   chmodSync,
-  existsSync,
+  existsSync as existsSync2,
   mkdirSync,
   readdirSync,
-  readFileSync,
+  readFileSync as readFileSync2,
   statSync,
   writeFileSync
 } from "node:fs";
-import { join } from "node:path";
+import { join as join2 } from "node:path";
 var PROFILE_SUFFIX = ".json";
 var FILE_MODE = 384;
 var DIRECTORY_MODE = 448;
@@ -228,23 +365,23 @@ function createCliProfileStore(config) {
 `));
   const pathFor = (name) => {
     assertProfileName(name);
-    return join(config.directory, `${name}${PROFILE_SUFFIX}`);
+    return join2(config.directory, `${name}${PROFILE_SUFFIX}`);
   };
   const list = () => {
-    if (!existsSync(config.directory))
+    if (!existsSync2(config.directory))
       return [];
     return readdirSync(config.directory).filter((entry) => entry.endsWith(PROFILE_SUFFIX)).map((entry) => entry.slice(0, -PROFILE_SUFFIX.length)).sort();
   };
   const read = (name) => {
     const path = pathFor(name);
-    if (!existsSync(path)) {
+    if (!existsSync2(path)) {
       throw new CliProfileError(missingMessage(name, path, config));
     }
     const mode = statSync(path).mode & 63;
     if (mode !== 0) {
       throw new CliProfileError(`profile "${name}" is readable by other users — run: chmod 600 ${path}`, "FORBIDDEN");
     }
-    const parsed = safeJsonParse(readFileSync(path, "utf8"));
+    const parsed = safeJsonParse(readFileSync2(path, "utf8"));
     const result = config.schema.safeParse(parsed);
     if (!result.success) {
       const issue = result.error.issues[0];
@@ -279,7 +416,7 @@ function createCliProfileStore(config) {
         return { name: only, path, value: read(only), substituted: true };
       }
       if (configured.length === 0) {
-        const example = join(config.directory, `<name>${PROFILE_SUFFIX}`);
+        const example = join2(config.directory, `<name>${PROFILE_SUFFIX}`);
         throw new CliProfileError(`no profile is configured in ${config.directory}${config.createHint ? ` — ${config.createHint("<name>", example)}` : ""}`);
       }
       throw new CliProfileError(`several profiles are configured (${configured.join(", ")}) — name one`, "BAD_REQUEST");
@@ -290,10 +427,140 @@ function missingMessage(name, path, config) {
   const hint = config.createHint ? ` — ${config.createHint(name, path)}` : "";
   return `profile "${name}" is not configured; expected ${path}${hint}`;
 }
+// src/tools/cli-stream.ts
+import { z as z3 } from "zod";
+var LineSchema = z3.object({
+  id: z3.string().min(1),
+  command: z3.string().min(1),
+  args: z3.record(z3.string(), z3.unknown()).default({})
+});
+async function* readStdinLines(source = process.stdin) {
+  const decoder = new TextDecoder;
+  let pending = "";
+  for await (const chunk of source) {
+    pending += typeof chunk === "string" ? chunk : decoder.decode(chunk, { stream: true });
+    let newline = pending.indexOf(`
+`);
+    while (newline !== -1) {
+      const line = pending.slice(0, newline);
+      pending = pending.slice(newline + 1);
+      yield line.endsWith("\r") ? line.slice(0, -1) : line;
+      newline = pending.indexOf(`
+`);
+    }
+  }
+  if (pending !== "")
+    yield pending.endsWith("\r") ? pending.slice(0, -1) : pending;
+}
+function parseLine(line) {
+  let parsed;
+  try {
+    parsed = safeJsonParse(line);
+  } catch {
+    return { ok: false, answer: malformed("the line is not JSON") };
+  }
+  const result = LineSchema.safeParse(parsed);
+  if (!result.success) {
+    const id = isRecord(parsed) && typeof parsed.id === "string" ? parsed.id : undefined;
+    return {
+      ok: false,
+      answer: {
+        ...malformed("the line needs `id` and `command`"),
+        ...id !== undefined && { id }
+      }
+    };
+  }
+  return { ok: true, value: result.data };
+}
+function malformed(message) {
+  return {
+    id: "",
+    ok: false,
+    exitCode: 2,
+    error: { code: "BAD_REQUEST", message }
+  };
+}
+async function runCliStream(invoker, lines, onAnswer, hooks = {}) {
+  for await (const line of lines) {
+    if (line.trim() === "")
+      continue;
+    const parsed = parseLine(line);
+    if (!parsed.ok) {
+      onAnswer(parsed.answer);
+      continue;
+    }
+    const { id, command, args } = parsed.value;
+    const answered = hooks.before?.(id, { command, args });
+    if (answered) {
+      onAnswer(answered);
+      continue;
+    }
+    const outcome = await invoker.invoke(command, args);
+    hooks.after?.(id, { command, args }, outcome);
+    onAnswer({ id, ...outcome });
+  }
+}
+function defineCliStreamCommand(config) {
+  return defineCliCommand({
+    name: config.name ?? "stream",
+    description: config.description ?? "Run one operation per JSON line of stdin, answering each",
+    input: z3.object({}),
+    handler: async (context) => {
+      const invoker = typeof config.invoker === "function" ? await config.invoker() : config.invoker;
+      await runCliStream(invoker, (config.readLines ?? readStdinLines)(), (answer) => {
+        context.stdout(`${JSON.stringify(answer)}
+`);
+      });
+    }
+  });
+}
+function defineCliBatchCommand(config) {
+  return defineCliCommand({
+    name: config.name ?? "batch",
+    description: config.description ?? "Run one operation per JSON line of stdin, resuming from a checkpoint",
+    input: z3.object({
+      checkpoint: z3.string().optional()
+    }),
+    handler: async (context) => {
+      const invoker = typeof config.invoker === "function" ? await config.invoker() : config.invoker;
+      const path = context.input.checkpoint ?? config.checkpointPath ?? ".stitchkit-batch.json";
+      const checkpoint = readCliCheckpoint(path);
+      await runCliStream(invoker, (config.readLines ?? readStdinLines)(), (answer) => {
+        context.stdout(`${JSON.stringify(answer)}
+`);
+      }, {
+        before: (id, line) => {
+          const digest = checkpoint.digestOf(line);
+          const recorded = checkpoint.entries[id];
+          if (!recorded)
+            return;
+          if (recorded.digest !== digest) {
+            return {
+              id,
+              ok: false,
+              exitCode: 2,
+              error: {
+                code: "CONFLICT",
+                message: "this id was already run with different content — change the id or start a new checkpoint"
+              }
+            };
+          }
+          const replay = isRecord(recorded.answer) ? recorded.answer : {};
+          return { ...replay, id, replayed: true };
+        },
+        after: (id, line, outcome) => {
+          if (!outcome.ok)
+            return;
+          checkpoint.record(id, checkpoint.digestOf(line), outcome);
+          writeCliCheckpoint(path, checkpoint);
+        }
+      });
+    }
+  });
+}
 // src/tools/cli-update.ts
 import { createHash } from "node:crypto";
-import { chmodSync as chmodSync2, renameSync, writeFileSync as writeFileSync2 } from "node:fs";
-import { basename, dirname, join as join2 } from "node:path";
+import { existsSync as existsSync3, readFileSync as readFileSync3, statSync as statSync2 } from "node:fs";
 import { gunzipSync } from "node:zlib";
 var DEFAULT_CHECK_TIMEOUT_MS = 2000;
 var DEFAULT_CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
@@ -354,14 +621,19 @@ async function checkCliUpdate(config) {
         reason: `cannot compare ${config.currentVersion} with ${manifest.version}`
       };
     }
+    const verdict = verifyCliManifest(manifest, manifest.signature, config.trust);
     if (order >= 0)
-      return { status: "current", version: manifest.version };
+      return { status: "current", version: manifest.version, signature: verdict };
+    if (!cliSignatureAccepted(verdict)) {
+      return { status: "unknown", reason: `manifest signature: ${verdict}` };
+    }
     const asset = selectCliBuildAsset(manifest, config.target ?? currentCliBuildTarget());
     return {
       status: "outdated",
       version: manifest.version,
       manifest,
-      ...asset && { asset }
+      ...asset && { asset },
+      signature: verdict
     };
   } catch (error) {
     return {
@@ -372,6 +644,18 @@ async function checkCliUpdate(config) {
 }
 async function applyCliUpdate(config) {
   const target = config.targetPath ?? process.execPath;
+  if (config.trust) {
+    if (!config.manifest) {
+      throw new Error("[stitchkit] update: a trust root needs the manifest the asset came from");
+    }
+    const verdict = verifyCliManifest(config.manifest, config.manifest.signature, config.trust);
+    if (!cliSignatureAccepted(verdict)) {
+      throw new Error(`[stitchkit] update: refusing to install — manifest signature ${verdict}`);
+    }
+    if (!config.manifest.assets.some((asset) => asset.sha256 === config.asset.sha256)) {
+      throw new Error("[stitchkit] update: the asset is not one the signed manifest names");
+    }
+  }
   const response = await fetchGuarded(new URL(config.asset.url), config.allowPrivateHosts ?? false, {
     timeoutMs: config.timeoutMs ?? DEFAULT_DOWNLOAD_TIMEOUT_MS,
     bodyTimeoutMs: config.timeoutMs ?? DEFAULT_DOWNLOAD_TIMEOUT_MS
@@ -382,7 +666,7 @@ async function applyCliUpdate(config) {
   const transferred = await readCapped(response, config.maxBytes ?? DEFAULT_MAX_ASSET_BYTES);
   if (!transferred)
     throw new Error("[stitchkit] update download exceeded the size ceiling");
-  const bytes = config.asset.compression === "gzip" ? gunzipSync(transferred) : transferred;
+  const bytes = config.asset.compression === "gzip" ? gunzipSync(transferred, { maxOutputLength: config.asset.size }) : transferred;
   if (bytes.length !== config.asset.size) {
     throw new Error(`[stitchkit] update is ${bytes.length} bytes, manifest says ${config.asset.size} — refusing to install it`);
   }
@@ -390,28 +674,64 @@ async function applyCliUpdate(config) {
   if (sha256 !== config.asset.sha256) {
     throw new Error(`[stitchkit] update digest ${sha256} does not match the manifest — refusing to install it`);
   }
-  const staged = join2(dirname(target), `.${basename(target)}.${process.pid}.${Date.now()}`);
-  writeFileSync2(staged, bytes, { mode: 493 });
-  chmodSync2(staged, 493);
-  renameSync(staged, target);
+  const backup = config.backupPath ? keepReplacedBinary(target, config.backupPath) : undefined;
+  writeFileAtomic(target, bytes, 493);
+  return {
+    path: target,
+    bytes: bytes.length,
+    sha256,
+    ...backup && { backupPath: backup.path, backupSha256: backup.sha256 }
+  };
+}
+function keepReplacedBinary(target, backupPath) {
+  if (!existsSync3(target))
+    return;
+  const previous = readFileSync3(target);
+  writeFileAtomic(backupPath, previous, statSync2(target).mode & 511);
+  return { path: backupPath, sha256: createHash("sha256").update(previous).digest("hex") };
+}
+function rollbackCliUpdate(config) {
+  const target = config.targetPath ?? process.execPath;
+  if (!existsSync3(config.backupPath)) {
+    throw new Error(`[stitchkit] rollback: no backup at ${config.backupPath}`);
+  }
+  const bytes = readFileSync3(config.backupPath);
+  const sha256 = createHash("sha256").update(bytes).digest("hex");
+  if (sha256 !== config.expectedSha256) {
+    throw new Error(`[stitchkit] rollback: backup digest ${sha256} does not match the expected ${config.expectedSha256} — refusing to restore it`);
+  }
+  writeFileAtomic(target, bytes, statSync2(config.backupPath).mode & 511);
   return { path: target, bytes: bytes.length, sha256 };
 }
 export {
+  writeCliCheckpoint,
+  verifyCliManifest,
+  signCliManifest,
   selectCliBuildAsset,
+  runCliStream,
   routeCliArgv,
+  rollbackCliUpdate,
   renderCliView,
   renderCliInstaller,
+  readCliCheckpoint,
   pollUntilDone,
   parseCliArgs,
   formatCliBuildStamp,
   extractCliGlobalOptions,
   emitResult,
+  defineCliStreamCommand,
   defineCliCommand,
+  defineCliBatchCommand,
   currentCliBuildTarget,
   createCliProfileStore,
+  createCliInvoker,
   createCli,
   compareCliVersions,
   coerceJsonArgs,
+  cliSignatureAccepted,
+  cliManifestSigningPayload,
+  cliInvocationResult,
+  cliExitCode,
   checkCliUpdate,
   assertCliPublishable,
   applyCliUpdate,
@@ -419,6 +739,7 @@ export {
   CliProfileError,
   CliBuildTargetSchema,
   CliBuildStampSchema,
+  CliBuildSignatureSchema,
   CliBuildManifestSchema,
   CliBuildAssetSchema,
   CliArgumentError

package/dist/contract/define.d.ts

@@ -183,10 +183,42 @@ export interface EndpointMcpInputRequired<TKey extends string = string, TSchema
     /** Flat primitive object schema accepted from the host. */
     schema: TSchema;
 }
+/**
+ * What the tool call looks like when the questions are chosen — the same
+ * `params` / `input` the handler would receive, parsed by the contract's own
+ * schemas.
+ */
+export interface McpInputRequiredCall {
+    params: unknown;
+    input: unknown;
+}
+/**
+ * Choose this call's elicitation rounds from its arguments.
+ *
+ * The static list is declared before any call exists, which is enough when the
+ * questions are a property of the operation. It is not enough when they are a
+ * property of the ARGUMENTS — one model takes `aspect_ratio`, another takes
+ * `duration`, a third needs an input image — and there the declared list can
+ * only be empty, so the tool description ends up teaching the model to work
+ * around a mechanism the protocol already has.
+ *
+ * Returning an empty list is a legitimate answer: this call needs nothing, run
+ * it. Everything else about the mechanism is unchanged — the state is still
+ * signed, still bound to the principal, the operation and the argument digest,
+ * and still counted against `maxRounds`.
+ *
+ * The resolved list is fingerprinted into the signed state and re-checked on
+ * every round, so a resolver that answers differently mid-conversation is
+ * refused rather than silently asking round 2's question under round 1's key.
+ */
+export type McpInputRequiredResolver<TRequests extends readonly EndpointMcpInputRequired[] = readonly EndpointMcpInputRequired[]> = (call: McpInputRequiredCall) => TRequests | Promise<TRequests>;
 /** MCP-only execution policy attached to a contract or runtime tool. */
 export interface EndpointMcpPolicy<TRequests extends readonly EndpointMcpInputRequired[] = readonly EndpointMcpInputRequired[]> {
-    /** Ordered elicitation rounds. Every key must be unique. */
-    inputRequired: TRequests;
+    /**
+     * Ordered elicitation rounds — a fixed list, or a function of the parsed
+     * arguments. Every key must be unique, in either form.
+     */
+    inputRequired: TRequests | McpInputRequiredResolver<TRequests>;
 }
 interface HttpOnlyEndpointDef extends EndpointDefBase {
     expose: readonly ['HTTP'];
@@ -417,7 +449,45 @@ export interface McpCallContext {
     clientInfo?: McpClientInfo;
     outcome?: McpRoundOutcome;
     round?: number;
+    /**
+     * The host's progress token for this call, when it asked for progress.
+     *
+     * Declarative, like everything else on this type: it says the host is
+     * listening. Reporting is `ctx.reportProgress`, which is a function and
+     * therefore deliberately NOT here — this type is also the type of
+     * `RequestEvent.mcp`, and an audit row's shape must not claim to carry
+     * behaviour.
+     */
+    progressToken?: string | number;
+}
+/**
+ * One progress update a tool handler sends to the host mid-call.
+ *
+ * `progress` is a number the protocol requires. It is optional here because a
+ * handler often has a stage to name and no scale to name it on — "uploading",
+ * "rendering frame 12" — and the honest answer to "how far along" is then the
+ * ordinal of the update itself, which is what gets sent. That is a fact about
+ * what happened, not a percentage nobody measured; `total` stays absent, so a
+ * host renders it as an unbounded counter rather than a bar at 3%.
+ */
+export interface McpProgressUpdate {
+    /** Human-facing stage, shown by the host while the call is still running. */
+    message?: string;
+    /** How far along, on whatever scale `total` implies. */
+    progress?: number;
+    /** The scale, when the operation knows it. */
+    total?: number;
 }
+/**
+ * Send one progress update for the call in flight.
+ *
+ * Present on every tool call and a no-op unless the host asked for progress by
+ * sending a token, so a handler never branches on transport. It never throws
+ * and never rejects: a message about work must not be able to kill the work it
+ * describes. Fire-and-forget — the returned promise settles when the
+ * notification has been handed to the transport, and ignoring it is correct.
+ */
+export type McpReportProgress = (update: McpProgressUpdate) => Promise<void>;
 export interface RuntimeContext {
     params: unknown;
     input: unknown;
@@ -444,6 +514,16 @@ export interface RuntimeContext {
     signal?: AbortSignal;
     /** Validated metadata for an MCP call; absent on every other transport. */
     mcp?: McpCallContext;
+    /**
+     * Report progress on the call in flight.
+     *
+     * Present on every TOOL call — MCP, agent and CLI — and a no-op wherever
+     * nobody is listening, so a handler never branches on transport to say what
+     * it is doing. Absent on the HTTP transport, which has no channel for it;
+     * that is why the field is optional and a handler that also serves HTTP
+     * writes `ctx.reportProgress?.(…)`.
+     */
+    reportProgress?: McpReportProgress;
     [key: string]: unknown;
 }
 export interface HandlerContext<TParams = undefined, TInput = undefined> {
@@ -464,6 +544,8 @@ export interface HandlerContext<TParams = undefined, TInput = undefined> {
     userAgent?: string;
     /** Validated metadata for an MCP call; absent on every other transport. */
     mcp?: McpCallContext;
+    /** Report progress on the call in flight — a no-op when none was asked for. */
+    reportProgress?: McpReportProgress;
     [key: string]: unknown;
 }
 type Prop<T, K extends string> = K extends keyof T ? T[K] : undefined;