@theokit/sdk 5.12.0 → 5.13.0

package/dist/sandbox/seccomp-delivery.d.cts

@@ -0,0 +1,49 @@
+import { type SandboxMode } from "./bwrap.js";
+/** The warning both arch guards print, the path route's and this one: one text, two latches. */
+export declare function nonX64SeccompWarning(arch: string): string;
+/**
+ * The restricted-network program for `arch`, or `undefined` where it must not be installed.
+ *
+ * Same ARCH GUARD as `seccompPathForArch`: the program is x86_64 and KILLs every syscall from
+ * another architecture, so on any other arch it is refused with one warning. The latch is this
+ * function's own, so a process that also calls the deprecated path helper warns once from each.
+ */
+export declare function seccompProgramForArch(arch: string, warn: (m: string) => void): Buffer | undefined;
+/** The restricted-network program, built once per process and x64-gated. Never mutated. */
+export declare function restrictedSeccompProgram(warn: (m: string) => void): Buffer | undefined;
+/**
+ * Wrap `command` so bwrap reads `program` on fd 3 from a pipe:
+ *
+ *   exec /bin/sh -c '<PIPE_SCRIPT>' sh <octal> <bwrap...> --seccomp 3 -- /bin/sh -c <cmd>
+ *
+ * The pipeline's grammar is always `/bin/sh`'s, whatever shell runs the outer words.
+ * `bwrapArgv` is the binary and flags, unescaped, without `--seccomp` and the trailing `--`.
+ */
+export declare function wrapWithSeccompProgram(bwrapArgv: readonly string[], command: string, program: Uint8Array): string;
+/**
+ * Remember that `path` was written with `program`, so a wrap naming that file pipes the program
+ * from memory: a sandbox that does not load the filter mounts `/tmp` writable and can replace it.
+ */
+export declare function rememberSeccompFile(path: string, program: Buffer): void;
+/**
+ * Remove `dir` when the process exits or is told to stop. A SIGINT or SIGTERM listener cancels
+ * Node's default termination, so once the directory is gone the signal is raised again when no other
+ * listener remains: the process ends as it would have, and a host's own handler still decides.
+ * The signal listener is prepended (B-648): run first, it still counts a host's `process.once`
+ * handler, which Node unregisters before calling it, whether the host registered before or after.
+ * A host that itself prepends a `once` handler after the filter still runs first and is not counted.
+ */
+export declare function removeDirOnExit(dir: string): void;
+/**
+ * The deprecated path route, with the filter bound read-only on top of every writable bind so the
+ * confined command can neither overwrite it nor rename its directory away (B-600). A path
+ * `seccompPathForArch` wrote is piped from memory instead of read, because another sandbox, one with
+ * no filter, can still replace that file; any other path is read through `3< <path>`.
+ *
+ * `bwrapArgv` is the binary followed by `buildBwrapArgv`'s output, which ends `--chdir <cwd> --`;
+ * the bind goes before `--chdir`, after every writable bind.
+ */
+export declare function wrapWithSeccompPath(bwrapArgv: readonly string[], policy: {
+    mode: SandboxMode;
+    cwd: string;
+}, command: string, seccompPath: string): string;

package/dist/sandbox/seccomp-delivery.d.ts

@@ -0,0 +1,49 @@
+import { type SandboxMode } from "./bwrap.js";
+/** The warning both arch guards print, the path route's and this one: one text, two latches. */
+export declare function nonX64SeccompWarning(arch: string): string;
+/**
+ * The restricted-network program for `arch`, or `undefined` where it must not be installed.
+ *
+ * Same ARCH GUARD as `seccompPathForArch`: the program is x86_64 and KILLs every syscall from
+ * another architecture, so on any other arch it is refused with one warning. The latch is this
+ * function's own, so a process that also calls the deprecated path helper warns once from each.
+ */
+export declare function seccompProgramForArch(arch: string, warn: (m: string) => void): Buffer | undefined;
+/** The restricted-network program, built once per process and x64-gated. Never mutated. */
+export declare function restrictedSeccompProgram(warn: (m: string) => void): Buffer | undefined;
+/**
+ * Wrap `command` so bwrap reads `program` on fd 3 from a pipe:
+ *
+ *   exec /bin/sh -c '<PIPE_SCRIPT>' sh <octal> <bwrap...> --seccomp 3 -- /bin/sh -c <cmd>
+ *
+ * The pipeline's grammar is always `/bin/sh`'s, whatever shell runs the outer words.
+ * `bwrapArgv` is the binary and flags, unescaped, without `--seccomp` and the trailing `--`.
+ */
+export declare function wrapWithSeccompProgram(bwrapArgv: readonly string[], command: string, program: Uint8Array): string;
+/**
+ * Remember that `path` was written with `program`, so a wrap naming that file pipes the program
+ * from memory: a sandbox that does not load the filter mounts `/tmp` writable and can replace it.
+ */
+export declare function rememberSeccompFile(path: string, program: Buffer): void;
+/**
+ * Remove `dir` when the process exits or is told to stop. A SIGINT or SIGTERM listener cancels
+ * Node's default termination, so once the directory is gone the signal is raised again when no other
+ * listener remains: the process ends as it would have, and a host's own handler still decides.
+ * The signal listener is prepended (B-648): run first, it still counts a host's `process.once`
+ * handler, which Node unregisters before calling it, whether the host registered before or after.
+ * A host that itself prepends a `once` handler after the filter still runs first and is not counted.
+ */
+export declare function removeDirOnExit(dir: string): void;
+/**
+ * The deprecated path route, with the filter bound read-only on top of every writable bind so the
+ * confined command can neither overwrite it nor rename its directory away (B-600). A path
+ * `seccompPathForArch` wrote is piped from memory instead of read, because another sandbox, one with
+ * no filter, can still replace that file; any other path is read through `3< <path>`.
+ *
+ * `bwrapArgv` is the binary followed by `buildBwrapArgv`'s output, which ends `--chdir <cwd> --`;
+ * the bind goes before `--chdir`, after every writable bind.
+ */
+export declare function wrapWithSeccompPath(bwrapArgv: readonly string[], policy: {
+    mode: SandboxMode;
+    cwd: string;
+}, command: string, seccompPath: string): string;

package/dist/sandbox/shell-escape.d.cts

@@ -2,7 +2,19 @@
  * POSIX shell escaping for values interpolated into a `SandboxBackend.execute`
  * command string. `execute` runs via `/bin/sh -c`, so any untrusted value
  * (repo URL, ref, path) MUST be quoted to prevent command injection.
+ */
+/**
+ * Quotes `arg` as one word for POSIX `sh`, for a command line you build yourself and hand to
+ * `SandboxBackend.execute`. A value from outside cannot end the word and start another command,
+ * whatever it holds: quotes, `$()`, backticks, newlines, backslashes. An empty string comes back as
+ * `''`. Quoting does not stop the program you call from reading a leading dash as an option, so put
+ * `--` before the value for one that parses options. The derived helpers and `provisionRepo` use this
+ * same quoter.
  *
- * @internal
+ * Wrap `arg` in single quotes, escaping embedded single quotes (`'\''`). A backslash before a quote,
+ * a backslash or the end is written outside the quotes too (`'\\'`), so the word parses the same
+ * under fish, which reads `\'` and `\\` inside single quotes as escapes, as under sh (B-600): the PTY
+ * runs the sandbox wrap under the user's `$SHELL`. After the first pass an original quote reads
+ * `'\''`, whose own backslash is always followed by `''`, so the second pass never matches it.
  */
-export {};
+export declare function shellEscapePosix(arg: string): string;

package/dist/sandbox/shell-escape.d.ts

@@ -2,7 +2,19 @@
  * POSIX shell escaping for values interpolated into a `SandboxBackend.execute`
  * command string. `execute` runs via `/bin/sh -c`, so any untrusted value
  * (repo URL, ref, path) MUST be quoted to prevent command injection.
+ */
+/**
+ * Quotes `arg` as one word for POSIX `sh`, for a command line you build yourself and hand to
+ * `SandboxBackend.execute`. A value from outside cannot end the word and start another command,
+ * whatever it holds: quotes, `$()`, backticks, newlines, backslashes. An empty string comes back as
+ * `''`. Quoting does not stop the program you call from reading a leading dash as an option, so put
+ * `--` before the value for one that parses options. The derived helpers and `provisionRepo` use this
+ * same quoter.
  *
- * @internal
+ * Wrap `arg` in single quotes, escaping embedded single quotes (`'\''`). A backslash before a quote,
+ * a backslash or the end is written outside the quotes too (`'\\'`), so the word parses the same
+ * under fish, which reads `\'` and `\\` inside single quotes as escapes, as under sh (B-600): the PTY
+ * runs the sandbox wrap under the user's `$SHELL`. After the first pass an original quote reads
+ * `'\''`, whose own backslash is always followed by `''`, so the second pass never matches it.
  */
-export {};
+export declare function shellEscapePosix(arg: string): string;

package/dist/sandbox/types.d.cts

@@ -52,6 +52,21 @@ export interface SandboxConfig {
      */
     env?: EnvPolicy;
 }
+/**
+ * What a {@link SandboxBackend} states about its outbound network. It is a statement the backend
+ * makes about itself, for a caller that wants to ask before it trusts: this package enforces nothing
+ * from it, and a custom backend is responsible for the claim being true.
+ *
+ * `"unrestricted"` means a command can reach whatever the host can. `"none"` means it cannot reach
+ * the network at all. `"allowlist"` means it can reach only the destinations in `allow`, written as
+ * the backend's own firewall spells them (usually domain names); the field is meaningful only with
+ * that mode. A backend that says nothing leaves `networkPolicy` undefined, which is not the same as
+ * `"unrestricted"`: it means the backend makes no claim either way.
+ */
+export interface SandboxNetworkPolicy {
+    readonly mode: "unrestricted" | "allowlist" | "none";
+    readonly allow?: readonly string[];
+}
 /**
  * A backend refused a command on policy grounds — the environment works, and it said no. Carries a
  * stable `code: "sandbox_security"` for callers that prefer not to match on the class.
@@ -98,16 +113,36 @@ export declare class SandboxNotAvailableError extends TheokitAgentError {
  * a reason to pin one. For genuinely untrusted code you want a container or VM backend, which this
  * package does not ship — write it against these two methods.
  *
+ * Two optional members let a backend say more about itself. {@link SandboxBackend.networkPolicy}
+ * states its egress: `LocalSandbox` declares `"unrestricted"`, `LinuxSandbox` declares `"none"` when
+ * bubblewrap unshares the network, and a backend that does not override it states nothing. Nothing in
+ * this package enforces an allowlist, so `"allowlist"` is only ever a claim a custom backend makes
+ * for itself. {@link SandboxBackend.dispose} releases what the backend holds, and the owner of the
+ * backend calls it.
+ *
  * Because the derived helpers assemble shell command lines (arguments escaped for POSIX `sh`), a
  * backend whose `execute` is not a POSIX shell must override them as well.
  */
 export declare abstract class SandboxBackend {
     protected config: SandboxConfig;
+    /**
+     * What this backend states about its outbound network, or `undefined` when it states nothing.
+     * Read it to check an isolation claim before trusting a backend; do not read `undefined` as
+     * "unrestricted". A subclass sets it as a field, and it is a statement only: the backend must
+     * enforce it itself.
+     */
+    readonly networkPolicy?: SandboxNetworkPolicy;
     constructor(config?: SandboxConfig);
     abstract execute(command: string, opts?: {
         timeoutMs?: number;
     }): Promise<ExecuteResult>;
     abstract uploadFile(path: string, content: string | Buffer): Promise<void>;
+    /**
+     * Releases whatever the backend holds, such as a VM or a container. The default does nothing,
+     * which is correct for a backend that holds nothing, so existing subclasses need no change. Safe
+     * to call more than once. The owner of the backend calls it; nothing in this package does.
+     */
+    dispose(): Promise<void>;
     readFile(path: string): Promise<string>;
     writeFile(path: string, content: string): Promise<void>;
     glob(pattern: string, cwd?: string): Promise<string[]>;
@@ -141,3 +176,13 @@ export declare abstract class SandboxBackend {
 export type SandboxProvider<Ctx = unknown> = SandboxBackend | ((ctx: Ctx) => SandboxBackend | Promise<SandboxBackend>);
 /** Resolve a {@link SandboxProvider} to a concrete backend for `ctx`. */
 export declare function resolveSandbox<Ctx>(provider: SandboxProvider<Ctx>, ctx: Ctx): Promise<SandboxBackend>;
+/** Codex's three canonical sandbox modes; lives in this leaf module so bwrap.ts and deny-read.ts need not import each other. */
+export type SandboxMode = "read-only" | "workspace-write" | "danger-full-access";
+/** Result of probing for bubblewrap. Detection never throws. */
+export type BwrapDetection = {
+    ok: true;
+    bin: string;
+} | {
+    ok: false;
+    reason: string;
+};

package/dist/sandbox/types.d.ts

@@ -52,6 +52,21 @@ export interface SandboxConfig {
      */
     env?: EnvPolicy;
 }
+/**
+ * What a {@link SandboxBackend} states about its outbound network. It is a statement the backend
+ * makes about itself, for a caller that wants to ask before it trusts: this package enforces nothing
+ * from it, and a custom backend is responsible for the claim being true.
+ *
+ * `"unrestricted"` means a command can reach whatever the host can. `"none"` means it cannot reach
+ * the network at all. `"allowlist"` means it can reach only the destinations in `allow`, written as
+ * the backend's own firewall spells them (usually domain names); the field is meaningful only with
+ * that mode. A backend that says nothing leaves `networkPolicy` undefined, which is not the same as
+ * `"unrestricted"`: it means the backend makes no claim either way.
+ */
+export interface SandboxNetworkPolicy {
+    readonly mode: "unrestricted" | "allowlist" | "none";
+    readonly allow?: readonly string[];
+}
 /**
  * A backend refused a command on policy grounds — the environment works, and it said no. Carries a
  * stable `code: "sandbox_security"` for callers that prefer not to match on the class.
@@ -98,16 +113,36 @@ export declare class SandboxNotAvailableError extends TheokitAgentError {
  * a reason to pin one. For genuinely untrusted code you want a container or VM backend, which this
  * package does not ship — write it against these two methods.
  *
+ * Two optional members let a backend say more about itself. {@link SandboxBackend.networkPolicy}
+ * states its egress: `LocalSandbox` declares `"unrestricted"`, `LinuxSandbox` declares `"none"` when
+ * bubblewrap unshares the network, and a backend that does not override it states nothing. Nothing in
+ * this package enforces an allowlist, so `"allowlist"` is only ever a claim a custom backend makes
+ * for itself. {@link SandboxBackend.dispose} releases what the backend holds, and the owner of the
+ * backend calls it.
+ *
  * Because the derived helpers assemble shell command lines (arguments escaped for POSIX `sh`), a
  * backend whose `execute` is not a POSIX shell must override them as well.
  */
 export declare abstract class SandboxBackend {
     protected config: SandboxConfig;
+    /**
+     * What this backend states about its outbound network, or `undefined` when it states nothing.
+     * Read it to check an isolation claim before trusting a backend; do not read `undefined` as
+     * "unrestricted". A subclass sets it as a field, and it is a statement only: the backend must
+     * enforce it itself.
+     */
+    readonly networkPolicy?: SandboxNetworkPolicy;
     constructor(config?: SandboxConfig);
     abstract execute(command: string, opts?: {
         timeoutMs?: number;
     }): Promise<ExecuteResult>;
     abstract uploadFile(path: string, content: string | Buffer): Promise<void>;
+    /**
+     * Releases whatever the backend holds, such as a VM or a container. The default does nothing,
+     * which is correct for a backend that holds nothing, so existing subclasses need no change. Safe
+     * to call more than once. The owner of the backend calls it; nothing in this package does.
+     */
+    dispose(): Promise<void>;
     readFile(path: string): Promise<string>;
     writeFile(path: string, content: string): Promise<void>;
     glob(pattern: string, cwd?: string): Promise<string[]>;
@@ -141,3 +176,13 @@ export declare abstract class SandboxBackend {
 export type SandboxProvider<Ctx = unknown> = SandboxBackend | ((ctx: Ctx) => SandboxBackend | Promise<SandboxBackend>);
 /** Resolve a {@link SandboxProvider} to a concrete backend for `ctx`. */
 export declare function resolveSandbox<Ctx>(provider: SandboxProvider<Ctx>, ctx: Ctx): Promise<SandboxBackend>;
+/** Codex's three canonical sandbox modes; lives in this leaf module so bwrap.ts and deny-read.ts need not import each other. */
+export type SandboxMode = "read-only" | "workspace-write" | "danger-full-access";
+/** Result of probing for bubblewrap. Detection never throws. */
+export type BwrapDetection = {
+    ok: true;
+    bin: string;
+} | {
+    ok: false;
+    reason: string;
+};

package/dist/stream-object-AS4YYM4B.cjs

@@ -0,0 +1,20 @@
+'use strict';
+
+var chunk2XWAYCFM_cjs = require('./chunk-2XWAYCFM.cjs');
+require('./chunk-PDOXYXWX.cjs');
+require('./chunk-AA27GEYS.cjs');
+require('./chunk-CEGU5AVD.cjs');
+require('./chunk-RNXXYF22.cjs');
+
+
+
+Object.defineProperty(exports, "StreamObjectError", {
+  enumerable: true,
+  get: function () { return chunk2XWAYCFM_cjs.StreamObjectError; }
+});
+Object.defineProperty(exports, "streamObjectImpl", {
+  enumerable: true,
+  get: function () { return chunk2XWAYCFM_cjs.streamObjectImpl; }
+});
+//# sourceMappingURL=stream-object-AS4YYM4B.cjs.map
+//# sourceMappingURL=stream-object-AS4YYM4B.cjs.map

package/dist/{stream-object-TEEK3CAX.cjs.map → stream-object-AS4YYM4B.cjs.map}

@@ -1 +1 @@
-{"version":3,"sources":[],"names":[],"mappings":"","file":"stream-object-TEEK3CAX.cjs"}
+{"version":3,"sources":[],"names":[],"mappings":"","file":"stream-object-AS4YYM4B.cjs"}

package/dist/stream-object-EKM4WGTI.js

@@ -0,0 +1,7 @@
+export { StreamObjectError, streamObjectImpl } from './chunk-CYWOJA6B.js';
+import './chunk-DFBWYETS.js';
+import './chunk-7I5Z3UBJ.js';
+import './chunk-TNFOU6SB.js';
+import './chunk-3OY6H3I7.js';
+//# sourceMappingURL=stream-object-EKM4WGTI.js.map
+//# sourceMappingURL=stream-object-EKM4WGTI.js.map

package/dist/{stream-object-R6SMYV4R.js.map → stream-object-EKM4WGTI.js.map}

@@ -1 +1 @@
-{"version":3,"sources":[],"names":[],"mappings":"","file":"stream-object-R6SMYV4R.js"}
+{"version":3,"sources":[],"names":[],"mappings":"","file":"stream-object-EKM4WGTI.js"}

package/dist/stream-object.d.ts

@@ -1,6 +1,6 @@
 import type { ZodType } from "zod";
 import { StructuredOutputError } from "./errors.js";
-import type { LocalOptions, ModelSelection } from "./types/agent.js";
+import type { BuiltinToolName, LocalOptions, MemorySettings, ModelSelection } from "./types/agent.js";
 import type { ProviderRoutingSettings } from "./types/providers.js";
 /**
  * Options accepted by {@link Agent.streamObject}. Same shape as
@@ -26,6 +26,19 @@ export interface StreamObjectOptions<T extends ZodType> {
      * when the right env key is set under a different provider name.
      */
     providers?: ProviderRoutingSettings;
+    /**
+     * Builtin tools removed from the transient agent's catalogue, forwarded to
+     * {@link AgentOptions.withheldBuiltinTools}. Absent ⇒ unchanged default: the agent holds
+     * `shell`. Pass `["shell"]` for a step that must only produce JSON. The `output` tool is
+     * never withheld.
+     */
+    withheldBuiltinTools?: readonly BuiltinToolName[];
+    /**
+     * Memory settings for the transient agent, forwarded to {@link AgentOptions.memory}.
+     * Absent ⇒ unchanged default (a session transcript is written). Pass `{ enabled: false }`
+     * for a step that must leave no transcript.
+     */
+    memory?: MemorySettings;
 }
 /**
  * Recursive partial — `T` where every nested field becomes optional.

package/dist/subagents-loader.d.cts

@@ -1,4 +1,4 @@
-import { a as AgentDefinition } from './agent-Cn0sphpA.cjs';
+import { a as AgentDefinition } from './agent-iW5kPpfT.cjs';
 import './sdk-agent-4-dXI2GS.cjs';
 import './agent-prims-CZyxfCmS.cjs';
 import 'zod';

package/dist/subagents-loader.d.ts

@@ -1,4 +1,4 @@
-import { a as AgentDefinition } from './agent-CVzDy_Oj.js';
+import { a as AgentDefinition } from './agent-DSMuwADp.js';
 import './sdk-agent-CTOJlWA_.js';
 import './agent-prims-CZyxfCmS.js';
 import 'zod';

package/dist/types/agent.d.ts

@@ -581,7 +581,14 @@ export interface AgentOptions {
      *
      * - **Named-enable settings** — `{ enabled: ["name", ...] }`. Selects which
      *   file-discovered plugin providers (under `.theokit/plugins/`) are active.
-     *   Plugin sources must also be active via `local.settingSources`.
+     *   Plugin sources must also be active via `local.settingSources`. A folder
+     *   under `<cwd>/.theokit/plugins/` whose `PLUGIN.md` names an `entry` has
+     *   that entry imported and its default export (a `kind: "general"` plugin)
+     *   registered, but only when the folder's absolute realpath is listed in
+     *   `~/.theokit/plugins/trusted-workspace-plugins.json` (a JSON array, read on
+     *   each `Agent.create`). The provider trust list never authorizes a workspace
+     *   folder. An untrusted folder is listed and never imported; foreign roots
+     *   are never imported.
      * - **Code `Plugin` objects** — an array of `Plugin` instances, e.g.
      *   `plugins: [Handoff.asPlugin({ ... })]`. These are registered directly by
      *   the runtime (`extractCodePlugins`); no `settingSources` entry is needed.

package/dist/workflow-as-tool.d.ts

@@ -14,13 +14,14 @@
  * Measured twice on this file on 2026-09-01: once with the tag, and again when the comment
  * EXPLAINING the trap quoted the tag verbatim and re-armed it.
  */
-import type { ZodType, z } from "zod";
+import { type ZodType, z } from "zod";
 import { TheokitAgentError } from "./errors.js";
 import type { CustomTool } from "./types/agent.js";
-import type { WorkflowRun } from "./types/workflow.js";
+import type { WorkflowResumeOptions, WorkflowRun } from "./types/workflow.js";
 /**
- * Raised by a {@link workflowAsTool} tool when the wrapped workflow run does not
- * reach `status: "completed"` (a step failed, the run was cancelled/suspended).
+ * Raised by a {@link workflowAsTool} or {@link workflowResumeTool} tool when the
+ * run does not reach `status: "completed"` (a step failed, the run was cancelled,
+ * or it suspended without `reportSuspended`, which returns a report instead).
  * The dispatch converts it to a `tool_result(isError)`.
  *
  * @public
@@ -47,6 +48,22 @@ export interface WorkflowAsToolSpec<T extends ZodType> {
     description: string;
     /** Zod schema for the workflow's input (a `Workflow` carries no top-level schema). */
     inputSchema: T;
+    /**
+     * When `true`, a run that suspends returns `{"status":"suspended","runId":…,"stepId":…}` instead of
+     * raising {@link WorkflowToolError}, so the model can hand the run id to a
+     * {@link workflowResumeTool}. The report carries ids only, never the suspended payload; `stepId` is
+     * `null` for a run that carries no step result. Default `false`.
+     */
+    reportSuspended?: boolean;
+}
+/** Spec for {@link workflowResumeTool}. */
+export interface WorkflowResumeToolSpec {
+    /** Tool name surfaced to the LLM. Same constraints as a `CustomTool.name`. */
+    name: string;
+    /** Description surfaced to the LLM — when the agent should resume a suspended run. */
+    description: string;
+    /** Report a run that suspends again instead of raising, as in {@link WorkflowAsToolSpec}. */
+    reportSuspended?: boolean;
 }
 /**
  * SE19 — expose a {@link Workflow} as an agent {@link CustomTool}, completing the
@@ -54,7 +71,8 @@ export interface WorkflowAsToolSpec<T extends ZodType> {
  * The handler validates the model's args against `spec.inputSchema`, runs the
  * workflow, and returns its output (a string as-is, else JSON). A run that does not
  * reach `status: "completed"` raises a typed {@link WorkflowToolError} (workflow
- * step errors do NOT throw — they surface via `run.status === "failed"`).
+ * step errors do NOT throw — they surface via `run.status === "failed"`), except a
+ * suspended run with `spec.reportSuspended`, which returns the suspended report.
  *
  * Accepts any `{ run }`-shaped workflow (structural), so it never imports the
  * `Workflow` class directly.
@@ -64,3 +82,19 @@ export interface WorkflowAsToolSpec<T extends ZodType> {
 export declare function workflowAsTool<T extends ZodType, TOutput = unknown>(workflow: {
     run: (input: z.infer<T>) => Promise<WorkflowRun<TOutput>>;
 }, spec: WorkflowAsToolSpec<T>): CustomTool;
+/**
+ * B-677 — a {@link CustomTool} that resumes a suspended run of `workflow` by its run id, with an
+ * optional payload validated against the suspend step's schema. It returns the run's output like
+ * {@link workflowAsTool}; a run that suspends again keeps the same run id and is reported or raised
+ * per `spec.reportSuspended`. Snapshot errors (`WorkflowSnapshotNotFoundError` for an unknown or
+ * already-resumed id, `WorkflowResumeWorkflowMismatchError` for a run another workflow suspended,
+ * `WorkflowResumeStepNotFoundError` when `workflow` lacks the suspended step) and payload validation
+ * errors propagate to the dispatch.
+ *
+ * `workflow` must be the committed instance from `Workflow.create().commit()`. The default snapshot
+ * store is in memory and process-local: a host that resumes across processes configures a persistent
+ * backend. This tool resumes any run id it is given; deciding who may approve a run is the host's job.
+ *
+ * @public
+ */
+export declare function workflowResumeTool(workflow: WorkflowResumeOptions["workflow"], spec: WorkflowResumeToolSpec): CustomTool;

package/dist/workflow-errors.d.ts

@@ -137,6 +137,22 @@ export declare class WorkflowResumeStepNotFoundError extends TheokitAgentError {
     readonly name = "WorkflowResumeStepNotFoundError";
     constructor(stepId: string, workflowName: string);
 }
+/**
+ * Thrown by `Workflow.resume()` (and so by a `workflowResumeTool` tool) when the snapshot for the run
+ * id was written by a workflow of another name. The snapshot is left in the store, so the workflow
+ * that suspended the run can still resume it.
+ *
+ * Without this check the default store, one process-global memory store, would let workflow B run
+ * its own tail on workflow A's accumulated input whenever both declare a step with the suspended id.
+ * `name` is a label, not an identity: two workflows that share a name are not told apart here.
+ */
+export declare class WorkflowResumeWorkflowMismatchError extends TheokitAgentError {
+    readonly runId: string;
+    readonly snapshotWorkflowName: string;
+    readonly workflowName: string;
+    readonly name = "WorkflowResumeWorkflowMismatchError";
+    constructor(runId: string, snapshotWorkflowName: string, workflowName: string);
+}
 /**
  * Aggregate failure from parallel branches.
  *

package/dist/workflow.cjs

@@ -1,7 +1,7 @@
 'use strict';
 
-var chunkZWLFHSON_cjs = require('./chunk-ZWLFHSON.cjs');
-var chunkTLVI2OQK_cjs = require('./chunk-TLVI2OQK.cjs');
+var chunkR35ZJAYT_cjs = require('./chunk-R35ZJAYT.cjs');
+var chunkSETHRLQS_cjs = require('./chunk-SETHRLQS.cjs');
 require('./chunk-VTYY7XL5.cjs');
 require('./chunk-AA27GEYS.cjs');
 require('./chunk-3KIUY67P.cjs');
@@ -14,87 +14,95 @@ require('./chunk-RNXXYF22.cjs');
 
 Object.defineProperty(exports, "Workflow", {
   enumerable: true,
-  get: function () { return chunkZWLFHSON_cjs.Workflow; }
+  get: function () { return chunkR35ZJAYT_cjs.Workflow; }
 });
 Object.defineProperty(exports, "WorkflowBuilder", {
   enumerable: true,
-  get: function () { return chunkZWLFHSON_cjs.WorkflowBuilder; }
+  get: function () { return chunkR35ZJAYT_cjs.WorkflowBuilder; }
 });
 Object.defineProperty(exports, "WorkflowToolError", {
   enumerable: true,
-  get: function () { return chunkZWLFHSON_cjs.WorkflowToolError; }
+  get: function () { return chunkR35ZJAYT_cjs.WorkflowToolError; }
 });
 Object.defineProperty(exports, "agentStep", {
   enumerable: true,
-  get: function () { return chunkZWLFHSON_cjs.agentStep; }
+  get: function () { return chunkR35ZJAYT_cjs.agentStep; }
 });
 Object.defineProperty(exports, "cloneWorkflow", {
   enumerable: true,
-  get: function () { return chunkZWLFHSON_cjs.cloneWorkflow; }
+  get: function () { return chunkR35ZJAYT_cjs.cloneWorkflow; }
 });
 Object.defineProperty(exports, "fn", {
   enumerable: true,
-  get: function () { return chunkZWLFHSON_cjs.fn; }
+  get: function () { return chunkR35ZJAYT_cjs.fn; }
 });
 Object.defineProperty(exports, "workflowAsTool", {
   enumerable: true,
-  get: function () { return chunkZWLFHSON_cjs.workflowAsTool; }
+  get: function () { return chunkR35ZJAYT_cjs.workflowAsTool; }
+});
+Object.defineProperty(exports, "workflowResumeTool", {
+  enumerable: true,
+  get: function () { return chunkR35ZJAYT_cjs.workflowResumeTool; }
 });
 Object.defineProperty(exports, "workflowStep", {
   enumerable: true,
-  get: function () { return chunkZWLFHSON_cjs.workflowStep; }
+  get: function () { return chunkR35ZJAYT_cjs.workflowStep; }
 });
 Object.defineProperty(exports, "WorkflowAlreadyRunningError", {
   enumerable: true,
-  get: function () { return chunkTLVI2OQK_cjs.WorkflowAlreadyRunningError; }
+  get: function () { return chunkSETHRLQS_cjs.WorkflowAlreadyRunningError; }
 });
 Object.defineProperty(exports, "WorkflowCompensateNotImplementedError", {
   enumerable: true,
-  get: function () { return chunkTLVI2OQK_cjs.WorkflowCompensateNotImplementedError; }
+  get: function () { return chunkSETHRLQS_cjs.WorkflowCompensateNotImplementedError; }
 });
 Object.defineProperty(exports, "WorkflowDuplicateStepIdError", {
   enumerable: true,
-  get: function () { return chunkTLVI2OQK_cjs.WorkflowDuplicateStepIdError; }
+  get: function () { return chunkSETHRLQS_cjs.WorkflowDuplicateStepIdError; }
 });
 Object.defineProperty(exports, "WorkflowInputError", {
   enumerable: true,
-  get: function () { return chunkTLVI2OQK_cjs.WorkflowInputError; }
+  get: function () { return chunkSETHRLQS_cjs.WorkflowInputError; }
 });
 Object.defineProperty(exports, "WorkflowMaxIterationsExceededError", {
   enumerable: true,
-  get: function () { return chunkTLVI2OQK_cjs.WorkflowMaxIterationsExceededError; }
+  get: function () { return chunkSETHRLQS_cjs.WorkflowMaxIterationsExceededError; }
 });
 Object.defineProperty(exports, "WorkflowNestedError", {
   enumerable: true,
-  get: function () { return chunkTLVI2OQK_cjs.WorkflowNestedError; }
+  get: function () { return chunkSETHRLQS_cjs.WorkflowNestedError; }
 });
 Object.defineProperty(exports, "WorkflowNotSerializableError", {
   enumerable: true,
-  get: function () { return chunkTLVI2OQK_cjs.WorkflowNotSerializableError; }
+  get: function () { return chunkSETHRLQS_cjs.WorkflowNotSerializableError; }
 });
 Object.defineProperty(exports, "WorkflowOutputError", {
   enumerable: true,
-  get: function () { return chunkTLVI2OQK_cjs.WorkflowOutputError; }
+  get: function () { return chunkSETHRLQS_cjs.WorkflowOutputError; }
 });
 Object.defineProperty(exports, "WorkflowParallelError", {
   enumerable: true,
-  get: function () { return chunkTLVI2OQK_cjs.WorkflowParallelError; }
+  get: function () { return chunkSETHRLQS_cjs.WorkflowParallelError; }
 });
 Object.defineProperty(exports, "WorkflowResumeStepNotFoundError", {
   enumerable: true,
-  get: function () { return chunkTLVI2OQK_cjs.WorkflowResumeStepNotFoundError; }
+  get: function () { return chunkSETHRLQS_cjs.WorkflowResumeStepNotFoundError; }
+});
+Object.defineProperty(exports, "WorkflowResumeWorkflowMismatchError", {
+  enumerable: true,
+  get: function () { return chunkSETHRLQS_cjs.WorkflowResumeWorkflowMismatchError; }
 });
 Object.defineProperty(exports, "WorkflowSnapshotNotFoundError", {
   enumerable: true,
-  get: function () { return chunkTLVI2OQK_cjs.WorkflowSnapshotNotFoundError; }
+  get: function () { return chunkSETHRLQS_cjs.WorkflowSnapshotNotFoundError; }
 });
 Object.defineProperty(exports, "WorkflowStateError", {
   enumerable: true,
-  get: function () { return chunkTLVI2OQK_cjs.WorkflowStateError; }
+  get: function () { return chunkSETHRLQS_cjs.WorkflowStateError; }
 });
 Object.defineProperty(exports, "__resetSnapshotStoresForTests", {
   enumerable: true,
-  get: function () { return chunkTLVI2OQK_cjs.__resetSnapshotStoresForTests; }
+  get: function () { return chunkSETHRLQS_cjs.__resetSnapshotStoresForTests; }
 });
 //# sourceMappingURL=workflow.cjs.map
 //# sourceMappingURL=workflow.cjs.map