@theokit/sdk 5.12.1 → 5.13.0

package/dist/workflow.d.ts

@@ -459,8 +459,9 @@ declare function __resetSnapshotStoresForTests(): void;
  */
 
 /**
- * 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
@@ -487,6 +488,22 @@ 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}. */
+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
@@ -494,7 +511,8 @@ 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.
@@ -504,6 +522,22 @@ interface WorkflowAsToolSpec<T extends ZodType> {
 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
+ */
+declare function workflowResumeTool(workflow: WorkflowResumeOptions["workflow"], spec: WorkflowResumeToolSpec): CustomTool;
 
 /**
  * The workflow error hierarchy — runtime classes, deliberately NOT in `types/`.
@@ -643,6 +677,22 @@ 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.
+ */
+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.
  *
@@ -908,4 +958,4 @@ declare function cloneWorkflow<TI = unknown, TO = unknown>(wf: Workflow<TI, TO>,
     id: string;
 }): Workflow<TI, TO>;
 
-export { type AgentStep, type BranchStep, type DowhileStep, type FnStep, type ForeachStep, type ParallelStep, type RetryPolicy, type SleepStep, type Step, type StepContext, type StepResult, type SuspendStep, Workflow, WorkflowAlreadyRunningError, type WorkflowAsToolSpec, WorkflowBuilder, WorkflowCompensateNotImplementedError, type WorkflowDescription, WorkflowDuplicateStepIdError, type WorkflowEvent, WorkflowInputError, WorkflowMaxIterationsExceededError, WorkflowNestedError, WorkflowNotSerializableError, type WorkflowOptions, WorkflowOutputError, WorkflowParallelError, type WorkflowPersistenceOptions, type WorkflowResumeOptions, WorkflowResumeStepNotFoundError, type WorkflowRun, type WorkflowRunOptions, type WorkflowSnapshot, WorkflowSnapshotNotFoundError, WorkflowStateError, type WorkflowStepDescription, type WorkflowStream, WorkflowToolError, __resetSnapshotStoresForTests, agentStep, cloneWorkflow, fn, workflowAsTool, workflowStep };
+export { type AgentStep, type BranchStep, type DowhileStep, type FnStep, type ForeachStep, type ParallelStep, type RetryPolicy, type SleepStep, type Step, type StepContext, type StepResult, type SuspendStep, Workflow, WorkflowAlreadyRunningError, type WorkflowAsToolSpec, WorkflowBuilder, WorkflowCompensateNotImplementedError, type WorkflowDescription, WorkflowDuplicateStepIdError, type WorkflowEvent, WorkflowInputError, WorkflowMaxIterationsExceededError, WorkflowNestedError, WorkflowNotSerializableError, type WorkflowOptions, WorkflowOutputError, WorkflowParallelError, type WorkflowPersistenceOptions, type WorkflowResumeOptions, WorkflowResumeStepNotFoundError, type WorkflowResumeToolSpec, WorkflowResumeWorkflowMismatchError, type WorkflowRun, type WorkflowRunOptions, type WorkflowSnapshot, WorkflowSnapshotNotFoundError, WorkflowStateError, type WorkflowStepDescription, type WorkflowStream, WorkflowToolError, __resetSnapshotStoresForTests, agentStep, cloneWorkflow, fn, workflowAsTool, workflowResumeTool, workflowStep };

package/dist/workflow.js

@@ -1,5 +1,5 @@
-export { Workflow, WorkflowBuilder, WorkflowToolError, agentStep, cloneWorkflow, fn, workflowAsTool, workflowStep } from './chunk-ZLFFDPXC.js';
-export { WorkflowAlreadyRunningError, WorkflowCompensateNotImplementedError, WorkflowDuplicateStepIdError, WorkflowInputError, WorkflowMaxIterationsExceededError, WorkflowNestedError, WorkflowNotSerializableError, WorkflowOutputError, WorkflowParallelError, WorkflowResumeStepNotFoundError, WorkflowSnapshotNotFoundError, WorkflowStateError, __resetSnapshotStoresForTests } from './chunk-BO3PV3OP.js';
+export { Workflow, WorkflowBuilder, WorkflowToolError, agentStep, cloneWorkflow, fn, workflowAsTool, workflowResumeTool, workflowStep } from './chunk-73IITAF7.js';
+export { WorkflowAlreadyRunningError, WorkflowCompensateNotImplementedError, WorkflowDuplicateStepIdError, WorkflowInputError, WorkflowMaxIterationsExceededError, WorkflowNestedError, WorkflowNotSerializableError, WorkflowOutputError, WorkflowParallelError, WorkflowResumeStepNotFoundError, WorkflowResumeWorkflowMismatchError, WorkflowSnapshotNotFoundError, WorkflowStateError, __resetSnapshotStoresForTests } from './chunk-TDED5XES.js';
 import './chunk-HY66GLM6.js';
 import './chunk-7I5Z3UBJ.js';
 import './chunk-PKRPV3R7.js';

package/docs/error-codes.md

@@ -6,7 +6,7 @@ Branch on `code`, never on the message: messages carry context (an id, a path, a
 
 **Transport codes vs the rest.** `ErrorCode` in `errors.ts` is the small canonical union a provider failure maps onto — the codes marked *transport* below. Everything else is raised by a specific subsystem at a specific place, and a `catch` that only handles the union will meet them anyway.
 
-251 distinct code(s).
+254 distinct code(s).
 
 | Code | Kind | Raised by | Sites |
 |---|---|---|---|
@@ -40,7 +40,7 @@ Branch on `code`, never on the message: messages carry context (an id, a path, a
 | `cloud_custom_tools_rejected` | domain | ConfigurationError | `packages/sdk/src/internal/cloud-agent/cloud-agent.ts:154` +1 |
 | `cloud_incompatible_function_resolver` | domain | ConfigurationError | `packages/sdk/src/internal/cloud-agent/cloud-tool-parity.ts:43` +2 |
 | `cloud_incompatible_mcp_stdio_local` | domain | ConfigurationError | `packages/sdk/src/internal/cloud-agent/cloud-tool-parity.ts:74` |
-| `cloud_plugin_path_rejected` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/plugin-loader/plugins-manager.ts:159` +1 |
+| `cloud_plugin_path_rejected` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/plugin-loader/plugins-manager.ts:195` +1 |
 | `cloud_run_http_error` | domain | NetworkError | `packages/sdk/src/internal/cloud-agent/real-cloud-run.ts:156` |
 | `cloud_run_unknown_status` | domain | NetworkError | `packages/sdk/src/internal/cloud-agent/real-cloud-run.ts:285` +1 |
 | `cloud_runtime_pre_release` | domain | ConfigurationError | `packages/sdk/src/agent.ts:419` +2 |
@@ -80,7 +80,7 @@ Branch on `code`, never on the message: messages carry context (an id, a path, a
 | `handoff_target_invalid` | domain | ConfigurationError | `packages/sdk-handoff/src/handoff.ts:116` |
 | `handoff_target_required` | domain | ConfigurationError | `packages/sdk-handoff/src/handoff.ts:111` |
 | `hitl_timeout` | domain | HitlTimeoutError | `packages/sdk/src/internal/runtime/tools/hitl-middleware.ts:42` +1 |
-| `hook_denied` | domain | ConfigurationError | `packages/sdk/src/internal/local-agent/local-agent.ts:455` |
+| `hook_denied` | domain | ConfigurationError | `packages/sdk/src/internal/local-agent/local-agent.ts:467` |
 | `hooks_invalid_command` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/hooks/hooks-source.ts:415` |
 | `hooks_json_invalid` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/hooks/hooks-source.ts:252` +2 |
 | `hooks_read_error` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/hooks/hooks-source.ts:243` |
@@ -172,12 +172,14 @@ Branch on `code`, never on the message: messages carry context (an id, a path, a
 | `personality_not_found` | domain | ConfigurationError | `packages/sdk/src/internal/personality/switch.ts:60` |
 | `personality_reserved_name` | domain | ConfigurationError | `packages/sdk/src/internal/personality/registry.ts:110` |
 | `pipeline_duplicate_provider` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/system-prompt/pipeline.ts:33` |
-| `plugin_entry_missing` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/plugin-loader/plugins-manager.ts:134` |
+| `plugin_entry_import_failed` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/plugin-loader/manifest-entry-import.ts:78` |
+| `plugin_entry_missing` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/plugin-loader/plugins-manager.ts:170` |
+| `plugin_entry_shape` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/plugin-loader/manifest-entry-import.ts:85` |
 | `plugin_frontmatter_invalid` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/plugin-loader/plugin-frontmatter.ts:39` |
 | `plugin_late_register_kind` | domain | ConfigurationError | `packages/sdk/src/internal/plugins/manager.ts:103` |
-| `plugin_manifest_invalid` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/plugin-loader/plugins-manager.ts:185` |
-| `plugin_manifest_shape` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/plugin-loader/plugins-manager.ts:191` |
-| `plugin_missing_manifest` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/plugin-loader/plugins-manager.ts:176` +2 |
+| `plugin_manifest_invalid` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/plugin-loader/plugins-manager.ts:221` |
+| `plugin_manifest_shape` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/plugin-loader/plugins-manager.ts:227` |
+| `plugin_missing_manifest` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/plugin-loader/plugins-manager.ts:212` +2 |
 | `programmatic_hooks_rejected` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/validation/validate-agent-options.ts:99` |
 | `provider_unresolved` | domain | ConfigurationError | `packages/sdk/src/internal/llm/router.ts:107` +2 |
 | `quota_exceeded` | domain | — | `packages/sdk/src/internal/error-mappers/openai-compatible.ts:148` |
@@ -189,9 +191,9 @@ Branch on `code`, never on the message: messages carry context (an id, a path, a
 | `run_cancelled` | domain | — | `packages/sdk/src/errors.ts:656` |
 | `run_not_found` | domain | UnknownAgentError | `packages/sdk/src/agent.ts:426` |
 | `runtime_exclusive` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/validation/validate-agent-options.ts:90` |
-| `sandbox_derived_helper_failed` | domain | ConfigurationError | `packages/sdk/src/sandbox/types.ts:185` +1 |
-| `sandbox_not_available` | domain | SandboxNotAvailableError | `packages/sdk/src/sandbox/types.ts:92` +1 |
-| `sandbox_security` | domain | SandboxSecurityError | `packages/sdk/src/sandbox/types.ts:73` +1 |
+| `sandbox_derived_helper_failed` | domain | ConfigurationError | `packages/sdk/src/sandbox/types.ts:223` +1 |
+| `sandbox_not_available` | domain | SandboxNotAvailableError | `packages/sdk/src/sandbox/types.ts:108` +1 |
+| `sandbox_security` | domain | SandboxSecurityError | `packages/sdk/src/sandbox/types.ts:89` +1 |
 | `schema_invalid` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/skills/skill-frontmatter.ts:99` +5 |
 | `server_error` | domain | buildErrorMetadata | `packages/sdk/src/internal/error-mappers/ollama.ts:92` +1 |
 | `session_busy` | domain | — | `packages/sdk/src/internal/persistence/session-writer.ts:56` +1 |
@@ -246,7 +248,7 @@ Branch on `code`, never on the message: messages carry context (an id, a path, a
 | `work_threw` | domain | — | `packages/sdk/src/internal/task/registry.ts:295` |
 | `workflow_already_committed` | domain | ConfigurationError | `packages/sdk/src/workflow.ts:269` |
 | `workflow_already_running` | domain | — | `packages/sdk/src/workflow-errors.ts:141` |
-| `workflow_compensate_not_implemented` | domain | — | `packages/sdk/src/workflow-errors.ts:246` +1 |
+| `workflow_compensate_not_implemented` | domain | — | `packages/sdk/src/workflow-errors.ts:270` +1 |
 | `workflow_duplicate_step_id` | domain | — | `packages/sdk/src/workflow-errors.ts:31` |
 | `workflow_input_invalid` | domain | — | `packages/sdk/src/workflow-errors.ts:48` |
 | `workflow_max_iterations_exceeded` | domain | — | `packages/sdk/src/workflow-errors.ts:181` |
@@ -254,11 +256,12 @@ Branch on `code`, never on the message: messages carry context (an id, a path, a
 | `workflow_not_serializable` | domain | — | `packages/sdk/src/workflow-errors.ts:195` +1 |
 | `workflow_output_invalid` | domain | — | `packages/sdk/src/workflow-errors.ts:65` |
 | `workflow_resume_step_not_found` | domain | — | `packages/sdk/src/workflow-errors.ts:210` +1 |
+| `workflow_resume_workflow_mismatch` | domain | — | `packages/sdk/src/workflow-errors.ts:234` +1 |
 | `workflow_snapshot_not_found` | domain | — | `packages/sdk/src/workflow-errors.ts:159` |
 | `workflow_state_invalid` | domain | — | `packages/sdk/src/workflow-errors.ts:82` |
-| `workflow_tool_failed` | domain | WorkflowToolError | `packages/sdk/src/workflow-as-tool.ts:40` +2 |
+| `workflow_tool_failed` | domain | WorkflowToolError | `packages/sdk/src/workflow-as-tool.ts:41` +2 |
 | `ws_global_missing` | domain | SubscriptionError | `packages/sdk/src/subscription/theokit-subscribe.ts:184` |
 | `ws_peer_missing` | domain | SubscriptionError | `packages/sdk/src/subscription/internal/ws-adapter-node.ts:48` |
 | `ws_transport_mismatch` | domain | SubscriptionError | `packages/sdk/src/subscription/internal/server-integration.ts:351` |
-| `zod_not_installed` | domain | ConfigurationError | `packages/sdk/src/internal/structured-output-helpers.ts:33` +1 |
+| `zod_not_installed` | domain | ConfigurationError | `packages/sdk/src/internal/structured-output-helpers.ts:40` +1 |
 

package/docs/harness-capability-map.md

@@ -4,7 +4,7 @@ Every public symbol the TheoKit workspace publishes, and the exact specifier to
 
 A symbol listed under two specifiers is reachable from both, but that does NOT make the two interchangeable: a class emitted separately into a subpath entry is a distinct nominal type from the one in the root bundle, so passing one where the other is expected fails on a private field. When a symbol appears twice, import it and everything it is passed to from the SAME specifier.
 
-1233 export(s) across 46 entry point(s).
+1259 export(s) across 50 entry point(s).
 
 ## `@theokit/acp`
 
@@ -771,6 +771,8 @@ A symbol listed under two specifiers is reachable from both, but that does NOT m
 | `createSessionArtifactStore` | function | Create a generic artifact store rooted at `dir`.  |
 | `createShellTool` | function | Build the `shell_exec` tool: run a command through `/bin/sh -c` with `projectRoot` as the working directory.  |
 | `CreateShellToolOptions` | interface | `shell_exec` — built-in tool for coding agents.  |
+| `createTextToSpeechTool` | function | Build the `text_to_speech` tool over a caller-supplied provider.  |
+| `CreateTextToSpeechToolOptions` | interface | Options for {@link createTextToSpeechTool } .  |
 | `createTodolistTool` | function | Build the `todolist` tool: an in-memory checklist the agent keeps across the turns of one session.  |
 | `createUpdatePlanTool` | function | `update_plan` — built-in tool for coding agents.  |
 | `createViewImageTool` | function | Read an image from the project so the model can look at it. |
@@ -782,7 +784,9 @@ A symbol listed under two specifiers is reachable from both, but that does NOT m
 | `createWriteFileTool` | function | Build the `write_file` tool.  |
 | `CreateWriteFileToolOptions` | interface | Options for {@link createWriteFileTool } .  |
 | `createWriteStdinTool` | function | Write to a live interactive session's stdin and read the output it produces. |
+| `DEFAULT_MAX_AUDIO_BYTES` | const | Default ceiling on the clip written to disk: 10 MiB, by analogy with `DEFAULT_MAX_IMAGE_BYTES`. |
 | `DEFAULT_MAX_IMAGE_BYTES` | const | Default ceiling: 5 MB on disk.  |
+| `DEFAULT_MAX_TEXT_CHARS` | const | Default ceiling on the text sent to the provider, in UTF-16 code units.  |
 | `DEFAULT_TOOL_GUIDANCE` | const | Curated hints for the common cross-tool error codes.  |
 | `denyCatastrophicCommands` | function | A policy that denies catastrophic commands by composing the M3-2 guardrail. |
 | `EnvContextOptions` | interface | Options for {@link buildEnvContext } .  |
@@ -812,6 +816,9 @@ A symbol listed under two specifiers is reachable from both, but that does NOT m
 | `SessionArtifactStore` | interface | A generic, id-keyed, atomic artifact store.  |
 | `SessionArtifactStoreOptions` | interface | Options for {@link createSessionArtifactStore } . |
 | `SsrfBlockedError` | class | Thrown when a host/redirect resolves to a blocked (private/reserved) address. |
+| `SynthesizedAudio` | interface | What the provider returns: the encoded clip and its mime type. |
+| `TextToSpeechCallback` | type | The speech provider {@link createTextToSpeechTool } calls.  |
+| `TextToSpeechResult` | type | The tool's result, before it is serialised to the JSON string the handler returns. |
 | `TodoItem` | interface | `todolist` — in-session task tracking for multi-step work.  |
 | `todoItemsToPlanNodes` | function | Convert structured todo items (from a `todolist` tool result's `items`, M4-5) into versioned `PlanNode`s for rendering.  |
 | `TodolistTool` | interface | The `todolist` tool object.  |
@@ -829,6 +836,40 @@ A symbol listed under two specifiers is reachable from both, but that does NOT m
 | `withShellExitGuidance` | function | Wrap `shell_exec` so a SOFT failure — `{ ok: true, exit_code != 0 }` (the TOOL ran, the COMMAND failed) — gains a `guidance` hint.  |
 | `withToolResultGuidance` | function | Wrap a `CustomTool` so its failed results gain a `guidance` hint from `guidance`.  |
 
+## `@theokit/sdk-tools/extract-document`
+
+| Symbol | Kind | Summary |
+|---|---|---|
+| `createExtractDocumentTool` | function | Extract the text of a `.docx` inside the project root. |
+| `CreateExtractDocumentToolOptions` | interface | Options for {@link createExtractDocumentTool } . |
+
+## `@theokit/sdk-tools/github-link-preview`
+
+| Symbol | Kind | Summary |
+|---|---|---|
+| `createGithubLinkPreviewTool` | function | Build the `github_link_preview` tool.  |
+| `CreateGithubLinkPreviewToolOptions` | interface | Options for {@link createGithubLinkPreviewTool } ; every one is optional. |
+| `GithubLinkKind` | type | What a previewed GitHub URL points at, taken from its path. |
+| `GithubLinkPreviewResult` | type | The JSON the `github_link_preview` tool returns: a preview, or a typed failure. |
+
+## `@theokit/sdk-tools/read-pdf`
+
+| Symbol | Kind | Summary |
+|---|---|---|
+| `createReadPdfTool` | function | Read the text of a PDF inside the project root. |
+| `CreateReadPdfToolOptions` | interface | Options for {@link createReadPdfTool } . |
+
+## `@theokit/sdk-tools/screenshot-logbook`
+
+| Symbol | Kind | Summary |
+|---|---|---|
+| `createScreenshotLogbookTool` | function | Build the `screenshot_logbook` tool over a log under `projectRoot`.  |
+| `CreateScreenshotLogbookToolOptions` | interface | Options for {@link createScreenshotLogbookTool } .  |
+| `DEFAULT_MAX_CAPTION_CHARS` | const | Default ceiling on a caption, in UTF-16 code units.  |
+| `DEFAULT_MAX_ENTRIES` | const | Default ceiling on the entries one log holds; it bounds the cost of each rewrite.  |
+| `LogbookEntry` | type | One line of the log.  |
+| `ScreenshotLogbookResult` | type | The tool's result, before it is serialised to the JSON string the handler returns. |
+
 ## `@theokit/sdk/a2a`
 
 | Symbol | Kind | Summary |
@@ -1293,7 +1334,7 @@ A symbol listed under two specifiers is reachable from both, but that does NOT m
 | `buildBwrapArgv` | function | Pure argv builder.  |
 | `buildSeccompFilter` | function | Build the cBPF seccomp program as a `Buffer` (each `sock_filter` = 8 bytes).  |
 | `BwrapArgvOptions` | interface | Everything {@link buildBwrapArgv } needs besides the {@link SandboxMode } .  |
-| `BwrapDetection` | type | Result of {@link detectBwrap } / {@link detectBwrapMemoized } , discriminated on `ok`: `{ ok: true, bin }` carries the absolute path of the validated `bwrap`, `{ ok: false, reason }` a human-readab... |
+| `BwrapDetection` | type | Result of probing for bubblewrap.  |
 | `BwrapProbes` | interface | Injectable probes — each mirrors one Codex availability check. |
 | `createSandboxBackend` | function | Honest factory: bwrap available + mode wants confinement → `LinuxSandbox` (kernel enforcement, running the VALIDATED absolute bin); `danger-full-access` → plain `LocalSandbox` silently (explicit op... |
 | `CreateSandboxBackendOptions` | interface | Options for `createSandboxBackend`, which probes for bubblewrap and returns a {@link LinuxSandbox } when confinement is genuinely available or a `LocalSandbox` when it is not — warning once when th... |
@@ -1317,13 +1358,15 @@ A symbol listed under two specifiers is reachable from both, but that does NOT m
 | `restrictedSeccompPath` | function | M57 — the memoized x64-gated seccomp program, written once per process to a temp file. |
 | `SandboxBackend` | class | The execution capability handed to an agent tool, and the extension point for new environments.  |
 | `SandboxConfig` | interface | Construction-time settings shared by every {@link SandboxBackend } .  |
-| `SandboxMode` | type | Codex's three canonical modes.  |
+| `SandboxMode` | type | Codex's three canonical sandbox modes; lives in this leaf module so bwrap.ts and deny-read.ts need not import each other. |
+| `SandboxNetworkPolicy` | interface | What a {@link SandboxBackend } states about its outbound network.  |
 | `SandboxNotAvailableError` | class | A backend cannot be used at all: its runtime is missing or unusable.  |
 | `SandboxPosture` | interface | Durable sandbox posture for the UI — the honest answer to "am I kernel-enforced right now?". |
 | `SandboxProvider` | type | A backend OR a per-request resolver of one — mirrors `FilesystemProvider` / `InteractiveProvider`.  |
 | `SandboxSecurityError` | class | A backend refused a command on policy grounds — the environment works, and it said no.  |
 | `SeccompOptions` | interface | Input to {@link buildSeccompFilter } — the one axis the generated cBPF program varies on.  |
 | `seccompPathForArch` | function | M63 — the restricted-network seccomp program is DETERMINISTIC, so write it ONCE per process and reuse the path across every LinuxSandbox (no per-instance temp accumulation).  |
+| `shellEscapePosix` | function | Quotes `arg` as one word for POSIX `sh`, for a command line you build yourself and hand to `SandboxBackend.execute`.  |
 | `wrapCommandForSandbox` | function | M57 — the single source of truth for the sandbox command wrap.  |
 | `writableRootsFor` | function | U-6 — the roots a mode may write to, answerable WITHOUT spawning anything.  |
 
@@ -1459,6 +1502,9 @@ A symbol listed under two specifiers is reachable from both, but that does NOT m
 | `WorkflowPersistenceOptions` | interface | Where suspend snapshots are kept.  |
 | `WorkflowResumeOptions` | interface | Arguments for `Workflow.resume()`.  |
 | `WorkflowResumeStepNotFoundError` | class | EC-8 absorbed — `currentStepId` from snapshot not found in resumed workflow. |
+| `workflowResumeTool` | function | 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.  |
+| `WorkflowResumeToolSpec` | interface | Spec for {@link workflowResumeTool } . |
+| `WorkflowResumeWorkflowMismatchError` | class | 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.  |
 | `WorkflowRun` | interface | The terminal record of one run — what `Workflow.run()` resolves to, what `Workflow.resume()` returns, and what the `result` promise of `Workflow.stream()` settles with.  |
 | `WorkflowRunOptions` | interface | Per-run options for `Workflow.run()` and `Workflow.stream()`.  |
 | `WorkflowSnapshot` | interface | The persisted state of a suspended run: written when a step calls `StepContext.suspend()`, read back by `Workflow.resume()`.  |
@@ -1467,5 +1513,5 @@ A symbol listed under two specifiers is reachable from both, but that does NOT m
 | `workflowStep` | function | SE30 — use a committed {@link Workflow } as a step inside another workflow.  |
 | `WorkflowStepDescription` | interface | theokit#161 — one step of a workflow, as a reflection surface sees it.  |
 | `WorkflowStream` | type | SE28 — the async iterator returned by `Workflow.stream()`.  |
-| `WorkflowToolError` | class | Raised by a {@link workflowAsTool } tool when the wrapped workflow run does not reach `status: "completed"` (a step failed, the run was cancelled/suspended).  |
+| `WorkflowToolError` | class | 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 `reportSuspe... |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theokit/sdk",
-  "version": "5.12.1",
+  "version": "5.13.0",
   "description": "TypeScript SDK for the Theo agent harness — same surface, local or cloud.",
   "license": "Apache-2.0",
   "homepage": "https://github.com/usetheokit/theokit-sdk#readme",

package/dist/chunk-4YD2WI57.cjs.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/generate-object.ts"],"names":["StructuredOutputError","disposeAndDeleteTransient","setupStructuredOutput","makeOutputTool","buildTransientAgentOptions","buildToolPrompt","extractUsage","STRUCTURED_OUTPUT_MESSAGES"],"mappings":"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","file":"chunk-4YD2WI57.cjs","sourcesContent":["import type { z as ZodNamespace, ZodType } from \"zod\";\nimport { StructuredOutputError } from \"./errors.js\";\nimport {\n  buildToolPrompt,\n  buildTransientAgentOptions,\n  disposeAndDeleteTransient,\n  extractUsage,\n  makeOutputTool,\n  STRUCTURED_OUTPUT_MESSAGES,\n  setupStructuredOutput,\n} from \"./internal/structured-output-helpers.js\";\nimport type { AgentOptions, LocalOptions, ModelSelection, SDKAgent } from \"./types/agent.js\";\nimport type { ProviderRoutingSettings } from \"./types/providers.js\";\n\n/**\n * Options accepted by {@link Agent.generateObject}. Returns a typed object\n * matching the supplied Zod schema. See ADR D33.\n *\n * @public\n */\nexport interface GenerateObjectOptions<T extends ZodType> {\n  /** Zod schema describing the expected object shape. */\n  schema: T;\n  /** User prompt — the model is asked to fill the schema given this prompt. */\n  prompt: string;\n  /** Optional system prompt steering the model. */\n  systemPrompt?: string;\n  /** Model selection. Required (transient agents need a model). SE8 — accepts a\n   *  bare-string id shorthand (`\"openai/gpt-4o-mini\"`) or a {@link ModelSelection}. */\n  model: string | ModelSelection;\n  /**\n   * M21 — optional separate model for the STRUCTURING step. When set, `model` first produces a\n   * free-text reasoned answer to the prompt (phase 1), then `structuringModel` extracts the\n   * schema-matched object by calling the `output` tool over that answer (phase 2). Lets a large\n   * model reason while a cheap fast model does the extraction. Absent ⇒ today's single-model flow.\n   */\n  structuringModel?: string | ModelSelection;\n  /** API key. Falls back to env (THEOKIT_API_KEY etc). */\n  apiKey?: string;\n  /** Local runtime config (cwd, sandbox). Required to keep the transient agent local-only. */\n  local: LocalOptions;\n  /**\n   * Retry budget on parse failures. Default 1 (initial attempt + 1 retry).\n   * The transient agent is REUSED across retries so the registry sees a\n   * single entry (EC-3).\n   */\n  maxRetries?: number;\n  /**\n   * Optional provider routing forwarded to the transient agent. Required when\n   * `model.id` uses a prefix (e.g. `openai/gpt-4o-mini`) but the credential is\n   * for a unified gateway (e.g. OpenRouter). Without this, the SDK infers\n   * provider from the prefix and may fail with `provider_unresolved` even\n   * when the right env key is set under a different provider name.\n   */\n  providers?: ProviderRoutingSettings;\n  /**\n   * What to do when the model's output fails schema validation after all\n   * retries are exhausted (M14):\n   * - `'throw'` (default) — throw {@link GenerateObjectError} `parse_failed`.\n   * - `'return-raw'` — resolve with the raw, UNVALIDATED input the model sent\n   *   (`object` may not match the schema; inspect `raw` too).\n   * - `'return-partial'` — for object schemas, resolve with only the fields that\n   *   individually validate (best-effort salvage); non-object schemas fall back\n   *   to raw.\n   */\n  errorStrategy?: \"throw\" | \"return-partial\" | \"return-raw\";\n}\n\n/**\n * Successful return from {@link Agent.generateObject}.\n *\n * @public\n */\nexport interface GenerateObjectResult<T> {\n  /** Typed object parsed via the Zod schema. */\n  object: T;\n  /** Raw input the model passed to the synthetic tool, before Zod parse. */\n  raw: unknown;\n  /** Token usage of the LLM call(s) that produced the result. */\n  usage: { inputTokens: number; outputTokens: number };\n  /** Stop reason of the underlying agent run. */\n  finishReason: \"tool_use\" | \"error\";\n}\n\n/**\n * Typed error thrown by {@link Agent.generateObject} when the model refuses\n * to call the synthetic `output` tool or when retries are exhausted.\n *\n * @public\n */\nexport class GenerateObjectError extends StructuredOutputError {\n  override readonly name = \"GenerateObjectError\";\n}\n\ninterface GenerateObjectDeps {\n  create: (options: AgentOptions) => Promise<SDKAgent>;\n  /** Hard-delete the transient agent from the registry after dispose. */\n  delete: (agentId: string) => Promise<void>;\n}\n\n/**\n * M14 — best-effort partial salvage for `errorStrategy: 'return-partial'`. For an object schema,\n * keep only the fields that individually validate; anything else (non-object schema or non-object\n * raw) falls back to the raw value. Works across Zod v3/v4 via the `.shape` record both expose.\n */\nfunction salvagePartial<T extends ZodType>(schema: T, raw: unknown): unknown {\n  if (typeof raw !== \"object\" || raw === null) return raw;\n  const shape = (schema as { shape?: Record<string, ZodType> }).shape;\n  if (shape === undefined || typeof shape !== \"object\") return raw;\n  const rawObj = raw as Record<string, unknown>;\n  const out: Record<string, unknown> = {};\n  for (const [key, fieldSchema] of Object.entries(shape)) {\n    if (typeof fieldSchema?.safeParse !== \"function\") continue;\n    const parsed = fieldSchema.safeParse(rawObj[key]);\n    if (parsed.success) out[key] = parsed.data;\n  }\n  return out;\n}\n\n/**\n * M21 — phase 1: run `options.model` as a plain reasoning agent (no output tool) and return its\n * free-text answer, which phase 2's structuring model then extracts. The transient reasoning agent\n * is disposed + hard-deleted so the registry count stays stable (EC-3, mirrors the phase-2 finally).\n */\nasync function runReasoningPhase<T extends ZodType>(\n  options: GenerateObjectOptions<T>,\n  deps: GenerateObjectDeps,\n): Promise<string> {\n  const reasoningOptions: AgentOptions = {\n    model: options.model,\n    local: options.local,\n    ...(options.systemPrompt !== undefined ? { systemPrompt: options.systemPrompt } : {}),\n    ...(options.apiKey !== undefined ? { apiKey: options.apiKey } : {}),\n    ...(options.providers !== undefined ? { providers: options.providers } : {}),\n  };\n  const reasoningAgent = await deps.create(reasoningOptions);\n  try {\n    const run = await reasoningAgent.send(options.prompt);\n    const result = await run.wait();\n    const text = (result as { result?: unknown }).result;\n    return typeof text === \"string\" ? text : options.prompt;\n  } finally {\n    await disposeAndDeleteTransient(reasoningAgent, deps.delete);\n  }\n}\n\n/**\n * Implementation of `Agent.generateObject`. Receives the `Agent.create`\n * factory as a callback to keep the dependency graph acyclic (mirrors the\n * AgentBuilder pattern in D25 / agent.ts injection).\n *\n * Algorithm:\n *   1. Convert the consumer's Zod schema to JSON Schema.\n *   2. Build a single synthetic `output` CustomTool whose handler captures\n *      the raw input and short-circuits the agent loop. The handler\n *      THROWS a sentinel so the loop terminates immediately without a\n *      second LLM round-trip.\n *   3. Create ONE transient agent (per the entire generateObject call,\n *      not per retry — EC-3). Each retry re-sends through the same agent,\n *      driving fresh LLM rounds.\n *   4. On each attempt, send a wrapper prompt instructing the model to\n *      call the `output` tool. Capture the raw input via the sentinel.\n *   5. Parse the raw input via schema.parse. On success, return typed.\n *      On failure, retry until the budget is exhausted.\n *   6. Always dispose the transient agent in `finally`.\n */\n// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: retry loop + capture sentinel + dispose-and-delete is a single transaction; splitting harms locality and the finally block.\nexport async function generateObjectImpl<T extends ZodType>(\n  options: GenerateObjectOptions<T>,\n  deps: GenerateObjectDeps,\n): Promise<GenerateObjectResult<ZodNamespace.infer<T>>> {\n  const { jsonSchema, maxRetries, initialUsage } = setupStructuredOutput(\n    options.schema,\n    options.maxRetries,\n  );\n  let capturedRaw: unknown;\n  let lastUsage = initialUsage;\n  const sentinel = Symbol(\"generate-object-sentinel\");\n  class CaptureSentinel extends Error {\n    readonly [sentinel] = true;\n    constructor(public readonly captured: unknown) {\n      super(\"generate-object-capture\");\n    }\n  }\n\n  const outputTool = makeOutputTool(jsonSchema, (input) => {\n    // EC-D10 (parallel tool use): first capture wins. Subsequent calls\n    // in the same response are ignored.\n    if (capturedRaw === undefined) {\n      capturedRaw = input;\n    }\n    throw new CaptureSentinel(input);\n  });\n\n  // M21 — when a separate structuring model is set, `model` first reasons in free text (phase 1),\n  // and `structuringModel` extracts the object over that text (phase 2). Absent ⇒ single-model flow.\n  const reasoningText =\n    options.structuringModel !== undefined ? await runReasoningPhase(options, deps) : undefined;\n  const structuringModel = options.structuringModel ?? options.model;\n  const structuringPrompt = reasoningText ?? options.prompt;\n\n  const agentOptions: AgentOptions = buildTransientAgentOptions({\n    model: structuringModel,\n    local: options.local,\n    outputTool,\n    ...(options.systemPrompt !== undefined ? { systemPrompt: options.systemPrompt } : {}),\n    ...(options.apiKey !== undefined ? { apiKey: options.apiKey } : {}),\n    ...(options.providers !== undefined ? { providers: options.providers } : {}),\n  });\n  const agent = await deps.create(agentOptions);\n\n  try {\n    const userMessage = buildToolPrompt(structuringPrompt);\n    let lastParseError: unknown;\n\n    for (let attempt = 0; attempt <= maxRetries; attempt += 1) {\n      capturedRaw = undefined;\n      const run = await agent.send(userMessage);\n      const result = await run.wait();\n      lastUsage = extractUsage(result);\n\n      if (capturedRaw === undefined) {\n        // EC: when the underlying run errored (e.g. provider_unresolved),\n        // surface the original cause instead of the misleading \"model\n        // returned text\" message — there was no model call at all.\n        if (result.status === \"error\" && result.error !== undefined) {\n          throw new GenerateObjectError(\n            \"no_tool_call\",\n            STRUCTURED_OUTPUT_MESSAGES.runFailed(result.error.message, result.error.code),\n            result.error,\n          );\n        }\n        // Model didn't call the output tool.\n        if (attempt === maxRetries) {\n          throw new GenerateObjectError(\"no_tool_call\", STRUCTURED_OUTPUT_MESSAGES.noToolCall);\n        }\n        continue;\n      }\n\n      const parsed = options.schema.safeParse(capturedRaw);\n      if (parsed.success) {\n        return {\n          object: parsed.data,\n          raw: capturedRaw,\n          usage: lastUsage,\n          finishReason: \"tool_use\",\n        };\n      }\n      lastParseError = parsed.error;\n    }\n\n    // M14 — all retries exhausted with a parse failure. `errorStrategy` decides the outcome; the\n    // tool WAS called (capturedRaw is set), so `finishReason` stays `tool_use`.\n    if (options.errorStrategy === \"return-raw\") {\n      return {\n        object: capturedRaw as ZodNamespace.infer<T>,\n        raw: capturedRaw,\n        usage: lastUsage,\n        finishReason: \"tool_use\",\n      };\n    }\n    if (options.errorStrategy === \"return-partial\") {\n      return {\n        object: salvagePartial(options.schema, capturedRaw) as ZodNamespace.infer<T>,\n        raw: capturedRaw,\n        usage: lastUsage,\n        finishReason: \"tool_use\",\n      };\n    }\n    throw new GenerateObjectError(\n      \"parse_failed\",\n      STRUCTURED_OUTPUT_MESSAGES.parseFailed,\n      lastParseError,\n    );\n  } finally {\n    // EC-3: dispose AND hard-delete the transient agent so registry count\n    // stays stable across retries.\n    await disposeAndDeleteTransient(agent, deps.delete);\n  }\n}\n"]}

package/dist/chunk-AQW54OWQ.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/internal/structured-output-helpers.ts"],"names":[],"mappings":"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","file":"chunk-AQW54OWQ.js","sourcesContent":["import { createRequire } from \"node:module\";\nimport type { z as ZodNamespace, ZodType } from \"zod\";\nimport { ConfigurationError } from \"../errors.js\";\nimport type { AgentOptions, CustomTool, LocalOptions, ModelSelection } from \"../types/agent.js\";\nimport type { ProviderRoutingSettings } from \"../types/providers.js\";\nimport { toJsonSchema } from \"./zod-to-json-schema.js\";\n\n/**\n * Shared helpers for `Agent.generateObject` (ADR D33) and\n * `Agent.streamObject` (ADR D39). Both build a transient agent with a\n * single synthetic `output` tool whose handler captures the model's\n * structured response.\n *\n * Extracted from inline duplicates to keep jscpd quiet AND to keep the\n * two public APIs in lockstep.\n *\n * @internal\n */\n\nlet cachedZ: typeof ZodNamespace | undefined;\n\n/**\n * Load Zod via createRequire (it's an optional peer dep). Throws a typed\n * ConfigurationError if Zod isn't installed.\n */\nexport function requireZod(): typeof ZodNamespace {\n  if (cachedZ !== undefined) return cachedZ;\n  const r = createRequire(import.meta.url);\n  let mod: { z?: typeof ZodNamespace } & typeof ZodNamespace;\n  try {\n    mod = r(\"zod\") as typeof mod;\n  } catch (cause) {\n    throw new ConfigurationError(\n      \"Structured output requires the optional peer dependency `zod`. \" +\n        'Add `\"zod\": \"^3.25.0 || ^4.0.0\"` to your package.json and reinstall.',\n      { code: \"zod_not_installed\", cause },\n    );\n  }\n  cachedZ = (mod.z ?? mod) as typeof ZodNamespace;\n  return cachedZ;\n}\n\n/**\n * Build the synthetic `output` tool used by both `generateObject` and\n * `streamObject`. The handler captures the raw input on first call only\n * (EC-D10 / EC-6: parallel tool use in Claude 3.5+ may invoke `output`\n * twice; later calls are ignored).\n */\nexport function makeOutputTool(\n  jsonSchema: Record<string, unknown>,\n  onCapture: (input: unknown) => string | Promise<string> | undefined,\n): CustomTool {\n  return {\n    name: \"output\",\n    description: \"Call this tool with your final structured answer. Match the JSON schema exactly.\",\n    inputSchema: jsonSchema,\n    handler: (input) => {\n      const out = onCapture(input);\n      // Some callers throw a sentinel (generate-object) and never return.\n      // Others return a string (stream-object). Anything else → empty string.\n      if (typeof out === \"string\") return out;\n      if (out instanceof Promise) return out;\n      return \"\";\n    },\n  };\n}\n\n/**\n * Assemble the AgentOptions for the transient agent. Shared shape:\n * model + local + tools[output] + systemPrompt + apiKey.\n */\nexport function buildTransientAgentOptions(params: {\n  // SE8 — accepts the bare-string shorthand; forwarded to AgentOptions.model\n  // (normalized at Agent.create).\n  model: string | ModelSelection;\n  local: LocalOptions;\n  outputTool: CustomTool;\n  systemPrompt?: string;\n  apiKey?: string;\n  providers?: ProviderRoutingSettings;\n}): AgentOptions {\n  return {\n    model: params.model,\n    local: params.local,\n    tools: [params.outputTool],\n    systemPrompt:\n      params.systemPrompt ??\n      \"You produce structured output by calling the `output` tool exactly once. Match the JSON schema.\",\n    ...(params.apiKey !== undefined ? { apiKey: params.apiKey } : {}),\n    ...(params.providers !== undefined ? { providers: params.providers } : {}),\n  };\n}\n\n/**\n * Best-effort extraction of token usage from a run result. Local runtimes\n * may not expose it; default to zeros.\n */\nexport function extractUsage(result: unknown): { inputTokens: number; outputTokens: number } {\n  const u = (result as { usage?: { inputTokens?: number; outputTokens?: number } }).usage;\n  if (u === undefined) return { inputTokens: 0, outputTokens: 0 };\n  return { inputTokens: u.inputTokens ?? 0, outputTokens: u.outputTokens ?? 0 };\n}\n\n/**\n * Build the user-message prompt that instructs the model to call the\n * `output` tool with a schema-matched structured answer.\n */\nexport function buildToolPrompt(prompt: string): string {\n  return `${prompt}\\n\\nRespond by calling the \\`output\\` tool with the structured answer that matches the schema.`;\n}\n\n/**\n * One-shot setup shared by both `generateObject` and `streamObject`. Loads\n * Zod, computes the JSON schema, primes the captured-raw / usage / retry\n * state. Returns the values needed by the caller's loop.\n */\nexport function setupStructuredOutput<T extends ZodType>(\n  schema: T,\n  maxRetries: number | undefined,\n) {\n  const z = requireZod();\n  // Universal Zod 3+4 conversion (feature-detects native v4, falls back to lib on v3).\n  const jsonSchema = toJsonSchema(schema, { unrepresentable: \"any\" });\n  return {\n    z,\n    jsonSchema,\n    maxRetries: maxRetries ?? 1,\n    initialUsage: { inputTokens: 0, outputTokens: 0 },\n  };\n}\n\n/**\n * Cleanup the transient agent after generateObject/streamObject finish.\n * Disposes AND hard-deletes from the registry so the count stays stable.\n *\n * @internal\n */\nexport async function disposeAndDeleteTransient(\n  agent: { dispose: () => Promise<void>; agentId: string },\n  deletor: (agentId: string) => Promise<void>,\n): Promise<void> {\n  await agent.dispose();\n  try {\n    await deletor(agent.agentId);\n  } catch {\n    // Best-effort cleanup.\n  }\n}\n\n/**\n * The three failure messages, verbatim from what both entry points already emit.\n *\n * Identical strings in two files is how two APIs start describing the same failure differently: the\n * first person to improve one of them improves half the product.\n *\n * @internal\n */\nexport const STRUCTURED_OUTPUT_MESSAGES = {\n  runFailed: (message: string | undefined, code: string | undefined): string =>\n    `Agent run failed before the model could reply: ${message ?? \"unknown error\"} [${code ?? \"?\"}]`,\n  noToolCall: \"The model returned text instead of calling the `output` tool.\",\n  parseFailed: \"Schema parse failed after all retries.\",\n} as const;\n"]}