@theokit/sdk 4.63.4 → 5.0.0-next.2

package/dist/workflow.d.ts

@@ -1,8 +1,12 @@
 import { ZodType, z } from 'zod';
-import { u as MessageOrigin, C as CustomTool } from './run-BYSHf58D.js';
-import { S as SDKAgent } from './sdk-agent-D8qJVkuV.js';
+import { S as SDKAgent } from './sdk-agent-D4a_BR_6.js';
+import { t as MessageOrigin, C as CustomTool } from './run-CTAdRU3U.js';
+import { T as TheokitAgentError } from './errors-base-B5g01neU.js';
 
 /**
+ * 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).
  *
@@ -36,7 +40,16 @@ 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. */
@@ -414,6 +427,100 @@ interface WorkflowResumeOptions<TI = unknown> {
     readonly payload?: unknown;
     readonly signal?: AbortSignal;
 }
+
+/**
+ * Snapshot store interface + InMemory and JsonFile backends (ADR D235).
+ *
+ * EC-4 absorbed: serialization happens here. `JSON.stringify` failure raises
+ * `WorkflowNotSerializableError` instead of letting the underlying `TypeError`
+ * leak.
+ *
+ * @internal
+ */
+
+/** Test seam — clear in-memory store between tests. */
+declare function __resetSnapshotStoresForTests(): void;
+
+/**
+ * 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.
+ */
+
+/**
+ * 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
+ */
+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). */
+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
+ */
+declare function workflowAsTool<T extends ZodType, TOutput = unknown>(workflow: {
+    run: (input: z.infer<T>) => Promise<WorkflowRun<TOutput>>;
+}, spec: WorkflowAsToolSpec<T>): CustomTool;
+
+/**
+ * The workflow error hierarchy — runtime classes, deliberately NOT in `types/`.
+ *
+ * `types/index.ts` calls itself "the canonical public contract" and re-exports every sibling with
+ * `export type *`, which cannot carry a value; `.dependency-cruiser.cjs` restates the same rule as
+ * "src/types/* are pure type definitions". These twelve classes lived in `types/workflow.ts` anyway
+ * and reached consumers only because the DTS rollup hoists a declaration the runtime bundle never
+ * emitted — the shape that shipped #279 for `isValidTaskId`. `tests/lint/types-are-types-only.test.ts`
+ * is what stops it recurring.
+ *
+ * The home mirrors `task-errors.ts`: errors for one public surface, next to it, at the src root.
+ * Re-exported by name from `workflow.ts`, so `@theokit/sdk/workflow` is unchanged.
+ *
+ * @public
+ */
+
 /**
  * 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`.
@@ -422,7 +529,7 @@ interface WorkflowResumeOptions<TI = unknown> {
  * 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.
  */
-declare class WorkflowDuplicateStepIdError extends Error {
+declare class WorkflowDuplicateStepIdError extends TheokitAgentError {
     readonly stepId: string;
     readonly name = "WorkflowDuplicateStepIdError";
     constructor(stepId: string);
@@ -431,7 +538,7 @@ declare class WorkflowDuplicateStepIdError extends Error {
  * SE27 — the whole-workflow `inputSchema` rejected `run(input)` (before step 1).
  * `detail` is a pre-formatted issues summary (a string, NOT Zod's `ZodIssue[]`).
  */
-declare class WorkflowInputError extends Error {
+declare class WorkflowInputError extends TheokitAgentError {
     readonly workflowName: string;
     readonly detail: string;
     readonly name = "WorkflowInputError";
@@ -441,7 +548,7 @@ declare class WorkflowInputError extends Error {
  * SE27 — the whole-workflow `outputSchema` rejected the final output (on `completed`).
  * `detail` is a pre-formatted issues summary (a string, NOT Zod's `ZodIssue[]`).
  */
-declare class WorkflowOutputError extends Error {
+declare class WorkflowOutputError extends TheokitAgentError {
     readonly workflowName: string;
     readonly detail: string;
     readonly name = "WorkflowOutputError";
@@ -451,7 +558,7 @@ declare class WorkflowOutputError extends Error {
  * SE29 — `WorkflowOptions.stateSchema` rejected an `initialState` or a
  * `setState(next)` call. `detail` is a pre-formatted issues summary.
  */
-declare class WorkflowStateError extends Error {
+declare class WorkflowStateError extends TheokitAgentError {
     readonly workflowName: string;
     readonly detail: string;
     readonly name = "WorkflowStateError";
@@ -463,7 +570,7 @@ declare class WorkflowStateError extends Error {
  * child would be skipped) — restructure with a top-level suspend. A nested
  * `failed`/`cancelled` fails the parent step with the child's error attached.
  */
-declare class WorkflowNestedError extends Error {
+declare class WorkflowNestedError extends TheokitAgentError {
     readonly stepId: string;
     readonly childName: string;
     readonly childStatus: Exclude<WorkflowRun["status"], "completed">;
@@ -488,7 +595,7 @@ declare class WorkflowNestedError extends Error {
  * 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.
  */
-declare class WorkflowAlreadyRunningError extends Error {
+declare class WorkflowAlreadyRunningError extends TheokitAgentError {
     readonly workflowName: string;
     readonly runId: string;
     readonly name = "WorkflowAlreadyRunningError";
@@ -502,7 +609,7 @@ declare class WorkflowAlreadyRunningError extends Error {
  * 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.
  */
-declare class WorkflowSnapshotNotFoundError extends Error {
+declare class WorkflowSnapshotNotFoundError extends TheokitAgentError {
     readonly runId: string;
     readonly name = "WorkflowSnapshotNotFoundError";
     constructor(runId: string);
@@ -516,52 +623,52 @@ declare class WorkflowSnapshotNotFoundError extends Error {
  * step runs at most `maxIterations` times; raising the ceiling is a `maxIterations` on the step, and
  * there is no global default to change.
  */
-declare class WorkflowMaxIterationsExceededError extends Error {
+declare class WorkflowMaxIterationsExceededError extends TheokitAgentError {
     readonly stepId: string;
     readonly maxIterations: number;
     readonly name = "WorkflowMaxIterationsExceededError";
     constructor(stepId: string, maxIterations: number);
 }
 /** EC-4 absorbed — JSON.stringify failed on snapshot payload. */
-declare class WorkflowNotSerializableError extends Error {
+declare class WorkflowNotSerializableError extends TheokitAgentError {
     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. */
-declare class WorkflowResumeStepNotFoundError extends Error {
+declare class WorkflowResumeStepNotFoundError extends TheokitAgentError {
     readonly stepId: string;
     readonly workflowName: string;
     readonly name = "WorkflowResumeStepNotFoundError";
     constructor(stepId: string, workflowName: string);
 }
-/** Aggregate failure from parallel branches. */
+/**
+ * Aggregate failure from parallel branches.
+ *
+ * THE ONE PUBLIC WORKFLOW ERROR STILL OUTSIDE THE SDK HIERARCHY, deliberately. Its ten siblings were
+ * reparented onto `TheokitAgentError` so `isTransientError` — and therefore `Retry.create`'s default
+ * predicate — can see them at all. This one cannot follow without ceasing to be an `AggregateError`,
+ * and `instanceof AggregateError` plus the standard `errors` array is the whole reason a caller
+ * catches it: they want the branch failures, not a single message.
+ *
+ * The cost is stated rather than hidden: `isTransientError(err)` is `false` for this class, so a
+ * parallel step whose branches failed transiently is not retried by the SDK's own helper. Inspect
+ * `err.errors` and decide per branch — which is what an aggregate asks of a caller anyway, since
+ * "should this be retried" has no single answer when the branches failed for different reasons.
+ */
 declare class WorkflowParallelError extends AggregateError {
     readonly stepId: string;
     readonly name = "WorkflowParallelError";
     constructor(errors: ReadonlyArray<Error>, stepId: string);
 }
 /** D238 — saga engine not yet implemented. */
-declare class WorkflowCompensateNotImplementedError extends Error {
+declare class WorkflowCompensateNotImplementedError extends TheokitAgentError {
     readonly stepId: string;
     readonly name = "WorkflowCompensateNotImplementedError";
     constructor(stepId: string);
 }
 
-/**
- * Snapshot store interface + InMemory and JsonFile backends (ADR D235).
- *
- * EC-4 absorbed: serialization happens here. `JSON.stringify` failure raises
- * `WorkflowNotSerializableError` instead of letting the underlying `TypeError`
- * leak.
- *
- * @internal
- */
-
-/** Test seam — clear in-memory store between tests. */
-declare function __resetSnapshotStoresForTests(): void;
-
 /**
  * Public `Workflow` class — declarative multi-step orchestration over
  * `Agent.send`, `Handoff`, `Agent.batch` and friends (Adoption Roadmap #5;
@@ -801,50 +908,4 @@ declare function cloneWorkflow<TI = unknown, TO = unknown>(wf: Workflow<TI, TO>,
     id: string;
 }): Workflow<TI, TO>;
 
-/**
- * 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
- */
-declare class WorkflowToolError extends Error {
-    readonly toolName: string;
-    readonly workflowStatus: string;
-    readonly workflowError?: {
-        name: string;
-        message: string;
-    } | undefined;
-    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). */
-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
- */
-declare function workflowAsTool<T extends ZodType, TOutput = unknown>(workflow: {
-    run: (input: z.infer<T>) => Promise<WorkflowRun<TOutput>>;
-}, spec: WorkflowAsToolSpec<T>): CustomTool;
-
 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 };

package/dist/workflow.js

@@ -1,12 +1,11 @@
-export { Workflow, WorkflowBuilder, WorkflowToolError, agentStep, cloneWorkflow, fn, workflowAsTool, workflowStep } from './chunk-OSEG74VJ.js';
-export { WorkflowAlreadyRunningError, WorkflowCompensateNotImplementedError, WorkflowDuplicateStepIdError, WorkflowInputError, WorkflowMaxIterationsExceededError, WorkflowNestedError, WorkflowNotSerializableError, WorkflowOutputError, WorkflowParallelError, WorkflowResumeStepNotFoundError, WorkflowSnapshotNotFoundError, WorkflowStateError, __resetSnapshotStoresForTests } from './chunk-BZRFXJHA.js';
+export { Workflow, WorkflowBuilder, WorkflowToolError, agentStep, cloneWorkflow, fn, workflowAsTool, workflowStep } from './chunk-HFEJE7AC.js';
+export { WorkflowAlreadyRunningError, WorkflowCompensateNotImplementedError, WorkflowDuplicateStepIdError, WorkflowInputError, WorkflowMaxIterationsExceededError, WorkflowNestedError, WorkflowNotSerializableError, WorkflowOutputError, WorkflowParallelError, WorkflowResumeStepNotFoundError, WorkflowSnapshotNotFoundError, WorkflowStateError, __resetSnapshotStoresForTests } from './chunk-GBCVPKHE.js';
 import './chunk-HY66GLM6.js';
-import './chunk-4VPXM6UU.js';
-import './chunk-HS7AVXTF.js';
-import './chunk-RIAM53CP.js';
-import './chunk-2GUYQR5P.js';
-import './chunk-ZZMZWBR6.js';
-import './chunk-D4CUGAKZ.js';
-import './chunk-XEQ3TM66.js';
+import './chunk-7I5Z3UBJ.js';
+import './chunk-EH6XD3FY.js';
+import './chunk-UKMBRMGT.js';
+import './chunk-3JHIFQ4I.js';
+import './chunk-ALUN2B4W.js';
+import './chunk-CZJ6Q7CW.js';
 //# sourceMappingURL=workflow.js.map
 //# sourceMappingURL=workflow.js.map