@theokit/sdk 2.23.0 → 2.24.0

package/dist/workflow.d.cts

@@ -23,7 +23,8 @@
  * @public
  */
 import type { ZodType } from "zod";
-import type { SDKAgent } from "./types/agent.js";
+import { z } from "zod";
+import type { CustomTool, SDKAgent } from "./types/agent.js";
 import type { MessageOrigin } from "./types/run.js";
 import type { AgentStep, BranchStep, DowhileStep, FnStep, RetryPolicy, Step, StepContext, WorkflowOptions, WorkflowResumeOptions, WorkflowRun, WorkflowRunOptions } from "./types/workflow.js";
 export declare class WorkflowBuilder<TInput = unknown, TOutput = unknown> {
@@ -97,3 +98,48 @@ export declare function agentStep(id: string, agent: SDKAgent, promptTemplate: s
 export { __resetSnapshotStoresForTests } from "./internal/workflow/snapshot-store.js";
 export type * from "./types/workflow.js";
 export { WorkflowAlreadyRunningError, WorkflowCompensateNotImplementedError, WorkflowDuplicateStepIdError, WorkflowMaxIterationsExceededError, WorkflowNotSerializableError, WorkflowParallelError, WorkflowResumeStepNotFoundError, WorkflowSnapshotNotFoundError, } 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 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). */
+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;

package/dist/workflow.d.ts

@@ -23,7 +23,8 @@
  * @public
  */
 import type { ZodType } from "zod";
-import type { SDKAgent } from "./types/agent.js";
+import { z } from "zod";
+import type { CustomTool, SDKAgent } from "./types/agent.js";
 import type { MessageOrigin } from "./types/run.js";
 import type { AgentStep, BranchStep, DowhileStep, FnStep, RetryPolicy, Step, StepContext, WorkflowOptions, WorkflowResumeOptions, WorkflowRun, WorkflowRunOptions } from "./types/workflow.js";
 export declare class WorkflowBuilder<TInput = unknown, TOutput = unknown> {
@@ -97,3 +98,48 @@ export declare function agentStep(id: string, agent: SDKAgent, promptTemplate: s
 export { __resetSnapshotStoresForTests } from "./internal/workflow/snapshot-store.js";
 export type * from "./types/workflow.js";
 export { WorkflowAlreadyRunningError, WorkflowCompensateNotImplementedError, WorkflowDuplicateStepIdError, WorkflowMaxIterationsExceededError, WorkflowNotSerializableError, WorkflowParallelError, WorkflowResumeStepNotFoundError, WorkflowSnapshotNotFoundError, } 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 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). */
+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;

package/dist/workflow.js

@@ -4,7 +4,7 @@ import { join, dirname } from 'path';
 import { createRequire } from 'module';
 import { mkdirSync, readdirSync } from 'fs';
 import { AsyncLocalStorage } from 'async_hooks';
-import { z } from 'zod';
+import { z, toJSONSchema } from 'zod';
 
 var __defProp = Object.defineProperty;
 var __getOwnPropNames = Object.getOwnPropertyNames;
@@ -2241,6 +2241,9 @@ function sanitizeIdentifier(input, options) {
   }
   return input.toLowerCase();
 }
+function toJsonSchema(schema, options = { unrepresentable: "any" }) {
+  return toJSONSchema(schema, options);
+}
 
 // src/workflow.ts
 init_workflow();
@@ -2467,6 +2470,38 @@ function agentStep(id, agent, promptTemplate, opts) {
     ...opts?.origin !== void 0 ? { origin: opts.origin } : {}
   };
 }
+var WorkflowToolError = class extends Error {
+  constructor(toolName, workflowStatus, workflowError) {
+    super(
+      `workflowAsTool("${toolName}"): workflow ${workflowStatus}${workflowError ? `: ${workflowError.message}` : ""}`
+    );
+    this.toolName = toolName;
+    this.workflowStatus = workflowStatus;
+    this.workflowError = workflowError;
+    this.name = "WorkflowToolError";
+  }
+  toolName;
+  workflowStatus;
+  workflowError;
+  code = "workflow_tool_failed";
+};
+function workflowAsTool(workflow, spec) {
+  const inputSchema = toJsonSchema(spec.inputSchema, { unrepresentable: "any" });
+  return {
+    name: spec.name,
+    description: spec.description,
+    inputSchema,
+    handler: async (rawInput) => {
+      const parsed = spec.inputSchema.parse(rawInput);
+      const run = await workflow.run(parsed);
+      if (run.status !== "completed") {
+        throw new WorkflowToolError(spec.name, run.status, run.error);
+      }
+      const output = run.output;
+      return typeof output === "string" ? output : JSON.stringify(output ?? null);
+    }
+  };
+}
 function validateStepId(id) {
   sanitizeIdentifier(id, { maxLen: 64 });
 }
@@ -2492,6 +2527,6 @@ function walkStepsValidating(steps, seen) {
   }
 }
 
-export { Workflow, WorkflowAlreadyRunningError, WorkflowBuilder, WorkflowCompensateNotImplementedError, WorkflowDuplicateStepIdError, WorkflowMaxIterationsExceededError, WorkflowNotSerializableError, WorkflowParallelError, WorkflowResumeStepNotFoundError, WorkflowSnapshotNotFoundError, __resetSnapshotStoresForTests, agentStep, fn };
+export { Workflow, WorkflowAlreadyRunningError, WorkflowBuilder, WorkflowCompensateNotImplementedError, WorkflowDuplicateStepIdError, WorkflowMaxIterationsExceededError, WorkflowNotSerializableError, WorkflowParallelError, WorkflowResumeStepNotFoundError, WorkflowSnapshotNotFoundError, WorkflowToolError, __resetSnapshotStoresForTests, agentStep, fn, workflowAsTool };
 //# sourceMappingURL=workflow.js.map
 //# sourceMappingURL=workflow.js.map