@theokit/sdk 4.63.4 → 5.0.0-next.2

package/dist/types/run-events.d.ts

@@ -1,4 +1,7 @@
 /**
+ * Owner: `internal/agent-loop/` (3 of 11 importers). Derived from the import graph, not declared —
+ * `tests/lint/types-name-their-owner.test.ts` re-derives it.
+ *
  * SE2 — typed runtime EVENT stream, ADDITIVE to the `SDKMessage` content stream.
  *
  * `Run.stream()` yields `SDKMessage`s (the conversation content). `RunEvent`s are
@@ -16,7 +19,7 @@
  *
  * @public
  */
-export type RunEvent = RunToolProgressEvent | RunRateLimitEvent | RunPermissionDeniedEvent | RunTaskStartedEvent | RunTaskUpdatedEvent | RunTaskCompletedEvent | RunCompactBoundaryEvent | RunCompactionFallbackEvent | RunTripwireEvent | RunCompletionCheckEvent | RunMcpServerFailedEvent | RunMcpServerReadyEvent;
+export type RunEvent = RunToolProgressEvent | RunRateLimitEvent | RunPermissionDeniedEvent | RunTaskStartedEvent | RunTaskUpdatedEvent | RunTaskCompletedEvent | RunCompactBoundaryEvent | RunCompactionFallbackEvent | RunTripwireEvent | RunCompletionCheckEvent | RunMcpServerFailedEvent | RunMcpServerReadyEvent | RunMemoryDegradedEvent;
 /**
  * theokit#188 — an MCP server was configured but its tools could not be listed, so NONE of its
  * tools exist for this run.
@@ -157,14 +160,38 @@ export interface RunCompactionFallbackEvent {
     readonly window: number;
 }
 /**
- * SE2 — the opt-in sink for {@link RunEvent}s. Supplied via `SendOptions.onRunEvent`.
- * Synchronous + best-effort: a throwing sink must never break the run (the emitter
- * try-catches it), so keep it fast (push to a queue, don't await).
+ * A memory stage failed and the run continued without it.
+ *
+ * The same shape of gap {@link RunMcpServerFailedEvent} closed for MCP, in the module next door.
+ * `initLoopContext` had three bare `catch { <field> = <empty> }` blocks: an init failure meant no
+ * memory tool was registered, a `buildTools` failure meant no provider tools, and a `runActivePass`
+ * failure meant no recalled context in the system prompt. The agent then answered without the memory
+ * it was configured with, and nothing recorded it — not stderr, not this sink, not the span in scope.
+ *
+ * Degrading to a working agent is the right BEHAVIOUR. This event exists because the degradation was
+ * unobservable, so a host UI showed a healthy run.
+ *
+ * Emitted once per failing stage per run.
+ *
+ * @public
  */
-export type RunEventSink = (event: RunEvent) => void;
+export interface RunMemoryDegradedEvent {
+    readonly type: "memory_degraded";
+    /** Which stage failed: `init`, `buildTools`, or `activePass`. */
+    readonly stage: string;
+    /** Why it failed, as the provider reported it. */
+    readonly message: string;
+}
 /**
- * SE2 — emit a {@link RunEvent} to an optional sink, swallowing any sink error so
- * observability can never break the run (fail-safe, mirrors the EventBus EC-2
- * contract). No-op when the sink is absent.
+ * Receives every {@link RunEvent} a run emits, in emission order.
+ *
+ * Wired through `onRunEvent` on the run options. The sink is observability, never control flow: it
+ * cannot cancel, alter, or delay the run, and {@link emitRunEvent} swallows anything it throws — a
+ * broken sink degrades what you can see, never what the agent does.
+ *
+ * Synchronous by signature, so a slow sink slows the run. Hand work off rather than awaiting inside
+ * it; returning a promise here would be ignored, not awaited.
+ *
+ * @public
  */
-export declare function emitRunEvent(sink: RunEventSink | undefined, event: RunEvent): void;
+export type RunEventSink = (event: RunEvent) => void;

package/dist/types/run.d.ts

@@ -1,4 +1,9 @@
-import type { CustomTool, ModelSelection } from "./agent-prims.js";
+/**
+ * Owner: `internal/local-agent/` (8 of 34 importers). Derived from the import graph, not
+ * declared — `tests/lint/types-name-their-owner.test.ts` re-derives it.
+ *
+ */
+import type { CustomTool, ModelSelection, PermissionMode } from "./agent-prims.js";
 import type { ConversationStep, ConversationTurn } from "./conversation.js";
 import type { McpServerConfig } from "./mcp.js";
 import type { SDKMessage } from "./messages.js";
@@ -308,6 +313,28 @@ export interface SDKUserMessage {
 /**
  * Per-send overrides and callbacks.
  *
+ * ## Which options do I need?
+ *
+ * Twenty-one optional fields with genuinely different audiences, so most callers read all of them to
+ * find their two. This table is the fix that was chosen; the alternative — nesting the groups under
+ * `observe?` and `toolPolicy?` and carrying the flat keys as deprecated aliases for one major — would
+ * have added surface to remove surface, and the harm here is the READING cost, not a representable
+ * illegal state. There is no measured defect behind this grouping and no consumer census; the fields
+ * and the audiences are what was measured.
+ *
+ * | If you are… | you want |
+ * |---|---|
+ * | rendering a live UI | `onDelta`, `onStep`, `onRunEvent` |
+ * | applying a policy | `permissionMode`, `activeTools`, `toolChoice`, `toolResultGuard`, `perToolTimeoutMs` |
+ * | running an eval or a harness | `maxIterations`, `completionCheck`, `doomLoop`, `signal` |
+ * | orchestrating agents | `origin`, `task`, `context` |
+ * | overriding this one send | `model`, `systemPrompt`, `tools`, `mcpServers`, `contextPaths`, `local` |
+ *
+ * Every field appears in exactly one row, and
+ * `tests/lint/send-options-audience-table.test.ts` fails when one is added without a row — a table
+ * that silently stops covering the type is worse than none, because a reader trusts it and stops
+ * looking.
+ *
  * @public
  */
 export interface SendOptions {
@@ -374,7 +401,7 @@ export interface SendOptions {
      * ask rules), `bypass` / `bypassPermissions` (allow all except an explicit deny).
      * Absent ⇒ the plugin's own construction-time mode applies. Local runtime.
      */
-    permissionMode?: import("../permission-engine.js").PermissionMode;
+    permissionMode?: PermissionMode;
     onStep?: (args: {
         step: ConversationStep;
     }) => void | Promise<void>;

package/dist/types/sdk-agent.d.ts

@@ -1,3 +1,8 @@
+/**
+ * Owner: `internal/local-agent/` (1 of 2 importers). Derived from the import graph, not declared —
+ * `tests/lint/types-name-their-owner.test.ts` re-derives it.
+ *
+ */
 import type { ModelSelection } from "./agent-prims.js";
 import type { SDKContextManager } from "./context.js";
 import type { SDKProvidersManager } from "./providers.js";
@@ -12,10 +17,27 @@ import type { Run, SDKUserMessage, SendOptions } from "./run.js";
 export interface SystemPromptSkillRef {
     name: string;
     description: string;
+    /**
+     * Where this skill came from: the absolute path to its `SKILL.md` for a skill read from disk,
+     * or the synthetic `inline://<name>` marker `createSkill` stamps on a code-defined one (see
+     * `create-skill.ts`) — there is no third case, so this is populated for every skill `list()`
+     * returns.
+     *
+     * It is the ORIGIN and NOT the body: `list()` stays lean by contract, and a skill's instructions
+     * are reachable only through {@link SDKAgentSkills.get}. What this adds is the answer to
+     * usetheokit/theokit-sdk#524's visibility question — which root a skill came from, so a listing
+     * can show that one arrived from `.claude/skills/` rather than the project's own directory, or
+     * that it was never on disk at all.
+     *
+     * Typed optional rather than required because {@link SystemPromptSkillRef} is the shape any
+     * future skill producer returns, and this SDK should not assert every one of them can name an
+     * origin.
+     */
+    source?: string;
 }
 /**
  * A skill resolved WITH its body, returned by {@link SDKAgentSkills.get}. Unlike
- * {@link SystemPromptSkillRef} (name + description only), this carries the full
+ * {@link SystemPromptSkillRef}, which carries metadata only, this carries the full
  * `instructions` — read from the SKILL.md for filesystem skills or the inline
  * `createSkill` body. @public
  */
@@ -59,6 +81,16 @@ export interface SDKAgentSkills {
 export interface SDKPluginMetadata {
     name: string;
     description?: string;
+    /**
+     * Absolute path the plugin manifest was read from.
+     *
+     * The runtime has ALWAYS returned this — `agent.plugins.list()` hands back the internal
+     * `PluginMetadata`, whose own docblock says it carries provenance "so callers can audit where the
+     * plugin came from". This type simply did not declare it, so the caller received the field and
+     * the compiler denied it existed. Declaring it is what makes the audit usetheokit/theokit-sdk#524
+     * asks for reachable in typed code.
+     */
+    source?: string;
 }
 /**
  * Public plugin listing handle exposed as `agent.plugins`. Populated when
@@ -80,6 +112,16 @@ export interface SDKArtifact {
     sizeBytes: number;
     updatedAt: string;
 }
+/**
+ * An operation a consumer may ask an {@link SDKAgent} about via `supports()`.
+ *
+ * Deliberately the members whose availability DIFFERS between runtimes, plus the core ones a caller
+ * may want to assert positively. A union rather than `string` so a typo is a compile error instead
+ * of a silent `false`.
+ *
+ * @public
+ */
+export type AgentOperation = "send" | "generate" | "listArtifacts" | "downloadArtifact" | "runUntil" | "fork" | "runToCompletion" | "streamToCompletion" | "usePersonality" | "invalidateCache";
 /**
  * Handle returned by `Agent.create()` and `Agent.resume()`.
  *
@@ -133,6 +175,34 @@ export interface SDKAgent {
      * idempotent across both surfaces.
      */
     [Symbol.asyncDispose](): Promise<void>;
+    /**
+     * Which operations this agent's runtime actually performs.
+     *
+     * `SDKAgent` is one handle over two runtimes that do not offer the same operations, and the type
+     * does not model the difference: `downloadArtifact` is a REQUIRED member that rejects for every
+     * input on a local agent, and five optional members are present-but-throwing on a cloud one, so
+     * `typeof agent.fork === "function"` is true and calling it throws. Neither requiredness nor
+     * optionality expresses "exists here, not there".
+     *
+     * Ask before calling. Mirrors `Run.supports(op)` / `Run.unsupportedReason(op)`, which solved the
+     * same problem one layer down over the `RunOperation` union.
+     *
+     * This is a MITIGATION. The structural fix is to split this interface into a common core plus
+     * `LocalCapableAgent` / `CloudCapableAgent`, so the compiler refuses the call instead of the
+     * runtime and a consumer narrows once instead of asking per call. That is breaking on a published
+     * surface and is deliberately not done here.
+     *
+     * @public
+     */
+    supports(operation: AgentOperation): boolean;
+    /**
+     * Human-readable reason `supports(operation)` returned `false`, or `undefined` when it returned
+     * `true`. The message names the runtime, so an operator reading a log knows which half of the
+     * union they are holding.
+     *
+     * @public
+     */
+    unsupportedReason(operation: AgentOperation): string | undefined;
     /** Cloud-only. Local returns an empty array. */
     listArtifacts(): Promise<SDKArtifact[]>;
     /** Cloud-only. Local throws `UnsupportedRunOperationError`. */

package/dist/types/session-message.d.ts

@@ -1,4 +1,7 @@
 /**
+ * Owner: `src/` (1 of 2 importers). Derived from the import graph, not
+ * declared — `tests/lint/types-name-their-owner.test.ts` re-derives it.
+ *
  * The shape of a persisted session turn, as a HOST reads it.
  *
  * Lives in `types/` because it is public contract — `Agent.transcript()` returns it (theokit#146).

package/dist/types/session-record.d.ts

@@ -1,4 +1,7 @@
 /**
+ * Owner: `src/` (1 of 2 importers). Derived from the import graph, not
+ * declared — `tests/lint/types-name-their-owner.test.ts` re-derives it.
+ *
  * `SessionRecord` — the native on-disk transcript record shape (SE40).
  *
  * The theokit session format IS the Claude Code record shape: a

package/dist/types/session-store.d.ts

@@ -1,4 +1,7 @@
 /**
+ * Owner: `internal/session/` (4 of 8 importers). Derived from the import graph, not declared —
+ * `tests/lint/types-name-their-owner.test.ts` re-derives it.
+ *
  * SE41 — the pluggable `SessionStore` seam over the NATIVE session transcript.
  *
  * A minimal, two-method port so an external store (Postgres / Redis / KV /
@@ -14,6 +17,19 @@
  * `local.sessionStore` yields byte-identical current behavior (back-compat, zero
  * consumer change). Injected via `local.sessionStore` for external stores.
  *
+ * THIS SEAM DOES NOT HIDE THE STORAGE, AND IS NOT MEANT TO. A Repository
+ * abstracts a persistence model away; this one is defined in terms of the
+ * native one — the port speaks {@link SessionRecord}, "the exact SessionRecord
+ * the SDK writes", and the on-disk layout's path helpers (`encodeProjectDir`,
+ * `transcriptPath`, `transcriptRoot`) are published on purpose at
+ * `@theokit/sdk/persistence` so a consumer can locate a transcript file.
+ *
+ * That is the whole design and the reason the seam is two methods rather than
+ * ten: the format is the contract, and a store implements read/append over it.
+ * A consumer supplying `local.sessionStore` is NOT bound by those paths — they
+ * describe where the DEFAULT `FsSessionStore` puts files, not where an external
+ * store must.
+ *
  * Consistency contract: `appendRecords` is append-only and ordering-preserving.
  * The FS default serializes appends per agent with a cross-process file lock;
  * external implementations own (and MUST document) their own concurrency
@@ -56,4 +72,33 @@ export interface SessionStore {
      * which MUST throw on failure (a resume cannot proceed on a silent partial history).
      */
     appendRecords(agentId: string, records: readonly SessionRecord[]): Promise<void>;
+    /**
+     * Claim the single-writer lease for `agentId`, if this store has one. OPTIONAL.
+     *
+     * The SDK calls it when an agent starts and skips it when absent, so a two-method store keeps
+     * working unchanged — declaring it here does not require it, which is the whole reason it is
+     * optional. What declaring it DOES is make the capability discoverable: the SDK probed for this
+     * method through an `as unknown` cast against an interface that never mentioned it, so a
+     * third-party store author — the serverless / multi-pod case this port exists to serve — read a
+     * two-method interface, implemented two methods, and never learned the hook was there.
+     *
+     * CONTRACT, and the half that matters: a rejection whose `name` is `"SessionBusyError"` PROPAGATES
+     * to the caller, because another process holding the session is a decision the caller has to make
+     * (`exec` forks to a new id). Any other rejection is treated as "no lease available here" —
+     * logged, and the turn proceeds without single-writer protection, since the write is best-effort
+     * by contract anyway.
+     */
+    acquire?(agentId: string): Promise<void>;
+    /**
+     * Release the lease `acquire` claimed, if this store has one. OPTIONAL.
+     *
+     * Called on agent disposal. A rejection is not handled specially.
+     */
+    release?(agentId: string): Promise<void>;
+    /**
+     * Release store-level resources — a connection pool, a file handle. OPTIONAL.
+     *
+     * Called once, on agent disposal, after {@link SessionStore.release}.
+     */
+    dispose?(): Promise<void>;
 }

package/dist/types/task.d.ts

@@ -1,4 +1,7 @@
 /**
+ * Owner: `internal/task/` (4 of 5 importers). Derived from the import graph, not declared —
+ * `tests/lint/types-name-their-owner.test.ts` re-derives it.
+ *
  * Public type contract for the Task observability registry (ADRs D361-D374).
  *
  * Tasks are an opt-in observability layer over async work in the SDK
@@ -141,14 +144,3 @@ export interface TaskCancelResult {
     readonly cancelled: boolean;
     readonly alreadyTerminal: boolean;
 }
-/**
- * Validates a task ID against the public grammar + reserved prefixes.
- * Throws `InvalidTaskIdError` from `../errors.js` on rejection.
- *
- * Adapter callers (workflow/batch/cron) MUST set `allowReserved: true`
- * to register their own IDs; user-facing surfaces (`Task.submit`,
- * `agent.send({ task: { id } })`) leave it false.
- */
-export declare function isValidTaskId(id: string, allowReserved: boolean): boolean;
-/** Re-exported for adapter implementations + tests. */
-export declare const TASK_RESERVED_PREFIXES: readonly string[];

package/dist/types/theokit.d.ts

@@ -1,4 +1,7 @@
 /**
+ * Owner: `internal/catalog/` (2 of 3 importers). Derived from the import graph, not declared —
+ * `tests/lint/types-name-their-owner.test.ts` re-derives it.
+ *
  * Account-level user info returned by `Theokit.me()`.
  *
  * @public

package/dist/types/trajectory.d.ts

@@ -1,4 +1,7 @@
 /**
+ * Owner: `src/` (1 of 1 importers). Derived from the import graph, not declared —
+ * `tests/lint/types-name-their-owner.test.ts` re-derives it.
+ *
  * Public types for ShareGPT trajectory export (ADR D139).
  *
  * Output format for fine-tuning datasets — consumed by HuggingFace, Axolotl,

package/dist/types/updates.d.ts

@@ -1,3 +1,8 @@
+/**
+ * Owner: `internal/agent-loop/` (1 of 1 importers). Derived from the import graph, not declared —
+ * `tests/lint/types-name-their-owner.test.ts` re-derives it.
+ *
+ */
 import type { UserMessage } from "./messages-base.js";
 /**
  * Single tool call event. The internal `args` and `result` shapes are NOT stable.

package/dist/types/usage.d.ts

@@ -1,4 +1,7 @@
 /**
+ * Owner: `internal/budget/` (3 of 8 importers). Derived from the import graph, not declared —
+ * `tests/lint/types-name-their-owner.test.ts` re-derives it.
+ *
  * Public type contract for token usage + cost tracking (ADRs D376-D379).
  *
  * Surfaces via `RunResult.usage` + `RunResult.cost` after every Run.
@@ -41,7 +44,7 @@ export type CostSource = "openrouter_api" | "litellm_snapshot" | "user_override"
 /**
  * Cost breakdown attached to `RunResult.cost`. When `status === "unknown"`,
  * `amountUsd` is `undefined` — DO NOT default to 0 (a lie). The UI shows
- * `n/a` para unknown, `~$1.23` para estimated, `$1.23` para actual.
+ * `n/a` for unknown, `~$1.23` for estimated, `$1.23` for actual.
  */
 export interface CostBreakdown {
     readonly amountUsd: number | undefined;

package/dist/types/workflow.d.ts

@@ -1,4 +1,7 @@
 /**
+ * Owner: `internal/workflow/` (15 of 19 importers). Derived from the import graph, not declared —
+ * `tests/lint/types-name-their-owner.test.ts` re-derives it.
+ *
  * Public type contract for `Workflow.create / .run / .resume` (Adoption
  * Roadmap #5; ADRs D230-D248).
  *
@@ -34,7 +37,16 @@ export interface FnStep {
     readonly inputSchema?: ZodType;
     readonly outputSchema?: ZodType;
     readonly retry?: RetryPolicy;
-    /** D238 — slot reserved; runtime throws if engine not yet implemented. */
+    /**
+     * @deprecated NOT IMPLEMENTED. Setting this does not enable saga rollback — it arms
+     * `WorkflowCompensateNotImplementedError`, so the step FAILS at run time and the message tells you
+     * to remove it. A field whose only effect is to make the step fail is worse than an absent field,
+     * because the type invites it and the cost is discovered in production.
+     *
+     * Kept rather than removed because `FnStep` is published and dropping a member is a major-version
+     * decision. The deprecation is the part that reaches a caller at the point of use: an editor
+     * strikes it through, which the D238 comment that stood here ("slot reserved") did not.
+     */
     readonly compensate?: (input: unknown, output: unknown, error: Error) => Promise<void> | void;
 }
 /** An agent.send-driven step. */
@@ -412,137 +424,3 @@ export interface WorkflowResumeOptions<TI = unknown> {
     readonly payload?: unknown;
     readonly signal?: AbortSignal;
 }
-/**
- * Thrown by `.commit()` when one step id appears twice anywhere in the workflow — including inside a
- * parallel branch, a branch predicate, the fallback, and the inner step of a `foreach` or `dowhile`.
- *
- * Ids address steps in snapshots and on resume, so this is refused at build time rather than
- * discovered mid-run. Workflows nested with `workflowStep()` are exempt: the child runs in its own
- * executor with its own id-space, so its ids cannot collide with the parent's.
- */
-export declare class WorkflowDuplicateStepIdError extends Error {
-    readonly stepId: string;
-    readonly name = "WorkflowDuplicateStepIdError";
-    constructor(stepId: string);
-}
-/**
- * SE27 — the whole-workflow `inputSchema` rejected `run(input)` (before step 1).
- * `detail` is a pre-formatted issues summary (a string, NOT Zod's `ZodIssue[]`).
- */
-export declare class WorkflowInputError extends Error {
-    readonly workflowName: string;
-    readonly detail: string;
-    readonly name = "WorkflowInputError";
-    constructor(workflowName: string, detail: string);
-}
-/**
- * SE27 — the whole-workflow `outputSchema` rejected the final output (on `completed`).
- * `detail` is a pre-formatted issues summary (a string, NOT Zod's `ZodIssue[]`).
- */
-export declare class WorkflowOutputError extends Error {
-    readonly workflowName: string;
-    readonly detail: string;
-    readonly name = "WorkflowOutputError";
-    constructor(workflowName: string, detail: string);
-}
-/**
- * SE29 — `WorkflowOptions.stateSchema` rejected an `initialState` or a
- * `setState(next)` call. `detail` is a pre-formatted issues summary.
- */
-export declare class WorkflowStateError extends Error {
-    readonly workflowName: string;
-    readonly detail: string;
-    readonly name = "WorkflowStateError";
-    constructor(workflowName: string, detail: string);
-}
-/**
- * SE30 — a nested workflow (via `workflowStep`) did not `complete`. A nested
- * `suspended` is NOT resumable in v1 (resume continues AFTER the step, so the
- * child would be skipped) — restructure with a top-level suspend. A nested
- * `failed`/`cancelled` fails the parent step with the child's error attached.
- */
-export declare class WorkflowNestedError extends Error {
-    readonly stepId: string;
-    readonly childName: string;
-    readonly childStatus: Exclude<WorkflowRun["status"], "completed">;
-    readonly childError?: {
-        name: string;
-        message: string;
-    } | undefined;
-    readonly name = "WorkflowNestedError";
-    constructor(stepId: string, childName: string, childStatus: Exclude<WorkflowRun["status"], "completed">, childError?: {
-        name: string;
-        message: string;
-    } | undefined);
-}
-/**
- * Thrown out of `Workflow.run()` — one of the few workflow failures that rejects instead of arriving
- * as `run.status === "failed"` — when the committed workflow already has a run in flight under the
- * same run id.
- *
- * The lock key pairs the id minted at `.commit()` with the run id, not `WorkflowOptions.name`, so
- * two workflows sharing a name are independent and concurrent runs with distinct minted ids never
- * collide. In practice this only fires when a caller pins `WorkflowRunOptions.runId`, or resumes a
- * run id that is still executing. The registry is an in-process map: a crash releases every lock, and
- * it says nothing about runs in other processes.
- */
-export declare class WorkflowAlreadyRunningError extends Error {
-    readonly workflowName: string;
-    readonly runId: string;
-    readonly name = "WorkflowAlreadyRunningError";
-    constructor(workflowName: string, runId: string);
-}
-/**
- * Thrown by `Workflow.resume()` when no snapshot exists for the given run id.
- *
- * The message suggests configuring persistence, which is the common cause but not the only one. The
- * run may never have suspended; it may have suspended under the default memory backend in a process
- * that has since exited; or the snapshot may already have been consumed, since resume deletes it
- * before re-entering the executor and a second resume of the same run id lands here.
- */
-export declare class WorkflowSnapshotNotFoundError extends Error {
-    readonly runId: string;
-    readonly name = "WorkflowSnapshotNotFoundError";
-    constructor(runId: string);
-}
-/**
- * Raised when a `dowhile` step's condition kept returning true past `maxIterations` (default 100).
- *
- * It does not escape `run()`: the step fails, the run ends `status: "failed"`, and the error reaches
- * the caller flattened as `run.error` with `name: "WorkflowMaxIterationsExceededError"` — match on
- * the name, the instance does not survive. The guard is evaluated before each iteration, so the inner
- * step runs at most `maxIterations` times; raising the ceiling is a `maxIterations` on the step, and
- * there is no global default to change.
- */
-export declare class WorkflowMaxIterationsExceededError extends Error {
-    readonly stepId: string;
-    readonly maxIterations: number;
-    readonly name = "WorkflowMaxIterationsExceededError";
-    constructor(stepId: string, maxIterations: number);
-}
-/** EC-4 absorbed — JSON.stringify failed on snapshot payload. */
-export declare class WorkflowNotSerializableError extends Error {
-    readonly stepId: string;
-    readonly underlying: Error;
-    readonly name = "WorkflowNotSerializableError";
-    constructor(stepId: string, underlying: Error);
-}
-/** EC-8 absorbed — `currentStepId` from snapshot not found in resumed workflow. */
-export declare class WorkflowResumeStepNotFoundError extends Error {
-    readonly stepId: string;
-    readonly workflowName: string;
-    readonly name = "WorkflowResumeStepNotFoundError";
-    constructor(stepId: string, workflowName: string);
-}
-/** Aggregate failure from parallel branches. */
-export declare class WorkflowParallelError extends AggregateError {
-    readonly stepId: string;
-    readonly name = "WorkflowParallelError";
-    constructor(errors: ReadonlyArray<Error>, stepId: string);
-}
-/** D238 — saga engine not yet implemented. */
-export declare class WorkflowCompensateNotImplementedError extends Error {
-    readonly stepId: string;
-    readonly name = "WorkflowCompensateNotImplementedError";
-    constructor(stepId: string);
-}

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

@@ -0,0 +1,66 @@
+/**
+ * SE19 — expose a {@link Workflow} as an agent tool.
+ *
+ * Split out of `workflow.ts` because it answers a different question: that file is about BUILDING a
+ * workflow; this one is about handing a built workflow to an agent as a callable. The file-size gate
+ * is what surfaced the seam, and the seam is real — nothing here runs while steps are composed.
+ *
+ * Re-exported from `workflow.ts`, so `@theokit/sdk/workflow` is unchanged.
+ *
+ * NOTE ON THE MODULE TAG: this header deliberately carries no internal-visibility tag, and does not
+ * even name one — TypeScript attaches a file-leading docblock to the FIRST declaration below it, and
+ * `stripInternal: true` (tsconfig.base) then deletes that declaration from the emitted `.d.ts`.
+ * `tsc --noEmit` stays clean and the declaration rollup fails with `"X" is not exported by "..."`.
+ * 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 { TheokitAgentError } from "./errors.js";
+import type { CustomTool } from "./types/agent.js";
+import type { 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).
+ * The dispatch converts it to a `tool_result(isError)`.
+ *
+ * @public
+ */
+export declare class WorkflowToolError extends TheokitAgentError {
+    readonly toolName: string;
+    readonly workflowStatus: string;
+    readonly workflowError?: {
+        name: string;
+        message: string;
+    } | undefined;
+    readonly name = "WorkflowToolError";
+    readonly code: "workflow_tool_failed";
+    constructor(toolName: string, workflowStatus: string, workflowError?: {
+        name: string;
+        message: string;
+    } | undefined);
+}
+/** Spec for {@link workflowAsTool}. `inputSchema` is the workflow's input shape (Zod). */
+export interface WorkflowAsToolSpec<T extends ZodType> {
+    /** Tool name surfaced to the LLM. Same constraints as a `CustomTool.name`. */
+    name: string;
+    /** Description surfaced to the LLM — when the agent should trigger the workflow. */
+    description: string;
+    /** Zod schema for the workflow's input (a `Workflow` carries no top-level schema). */
+    inputSchema: T;
+}
+/**
+ * SE19 — expose a {@link Workflow} as an agent {@link CustomTool}, completing the
+ * "X as tools" trio (tools; agents-as-tools via `defineSubAgent`; workflows-as-tools).
+ * 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"`).
+ *
+ * Accepts any `{ run }`-shaped workflow (structural), so it never imports the
+ * `Workflow` class directly.
+ *
+ * @public
+ */
+export declare function workflowAsTool<T extends ZodType, TOutput = unknown>(workflow: {
+    run: (input: z.infer<T>) => Promise<WorkflowRun<TOutput>>;
+}, spec: WorkflowAsToolSpec<T>): CustomTool;