@theokit/sdk 1.6.2 → 1.8.0

package/dist/workflow.d.cts

@@ -0,0 +1,97 @@
+/**
+ * Public `Workflow` class — declarative multi-step orchestration over
+ * `Agent.send`, `Handoff`, `Agent.batch` and friends (Adoption Roadmap #5;
+ * ADRs D230-D248).
+ *
+ * Usage:
+ *
+ *   import { Agent } from "@theokit/sdk";
+ *   import { Workflow, fn, agentStep } from "@theokit/sdk/workflow";
+ *
+ *   const classifier = await Agent.create({ ... });
+ *   const wf = Workflow.create({ name: "demo" })
+ *     .then(fn("validate", (input: { id: string }) => {
+ *       if (!input.id) throw new Error("missing id");
+ *       return input;
+ *     }))
+ *     .then(agentStep("classify", classifier, (i) => `Classify: ${JSON.stringify(i)}`))
+ *     .commit();
+ *
+ *   const run = await wf.run({ id: "x" });
+ *   console.log(run.status, run.output);
+ *
+ * @public
+ */
+import type { ZodType } from "zod";
+import type { SDKAgent } from "./types/agent.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> {
+    private readonly options;
+    private readonly _steps;
+    private _committed;
+    then<TO = unknown>(step: Step): WorkflowBuilder<TInput, TO>;
+    parallel(branches: ReadonlyArray<ReadonlyArray<Step>>, opts?: {
+        id?: string;
+        concurrency?: number;
+        errorPolicy?: "fail-fast" | "collect";
+    }): WorkflowBuilder<TInput, unknown[]>;
+    branch(predicates: BranchStep["predicates"], opts?: {
+        id?: string;
+        fallback?: ReadonlyArray<Step>;
+    }): WorkflowBuilder<TInput, unknown>;
+    foreach(iterableFrom: string, step: Step, opts?: {
+        id?: string;
+        concurrency?: number;
+    }): WorkflowBuilder<TInput, unknown[]>;
+    dowhile(step: Step, condFn: DowhileStep["condFn"], opts?: {
+        id?: string;
+        maxIterations?: number;
+    }): WorkflowBuilder<TInput, unknown>;
+    sleep(durationMs: number, id?: string): WorkflowBuilder<TInput, TOutput>;
+    suspend(opts?: {
+        id?: string;
+        payloadSchema?: ZodType;
+    }): WorkflowBuilder<TInput, unknown>;
+    commit(): Workflow<TInput, TOutput>;
+    private validateUniqueIds;
+    private assertNotCommitted;
+}
+export declare class Workflow<TInput = unknown, TOutput = unknown> {
+    private readonly _options;
+    private readonly _steps;
+    /**
+     * Construct a workflow builder. Validate options via Zod and return a
+     * `WorkflowBuilder` for fluent chaining. Call `.commit()` to obtain the
+     * immutable `Workflow`.
+     */
+    static create<TI = unknown, TO = unknown>(options: WorkflowOptions): WorkflowBuilder<TI, TO>;
+    /**
+     * Run this workflow with the given input. Returns a populated
+     * `WorkflowRun`. Errors inside a step DO NOT throw — they propagate via
+     * `run.status === "failed"`.
+     */
+    run(input: TInput, opts?: WorkflowRunOptions): Promise<WorkflowRun<TOutput>>;
+    /**
+     * Resume a suspended workflow from its snapshot. Throws
+     * `WorkflowSnapshotNotFoundError` if `runId` is unknown.
+     */
+    static resume<TO = unknown>(opts: WorkflowResumeOptions): Promise<WorkflowRun<TO>>;
+}
+/**
+ * Build a `FnStep`. `id` must match `^[a-z0-9][a-z0-9_-]*$`.
+ */
+export declare function fn<I = unknown, O = unknown>(id: string, step: (input: I, ctx: StepContext) => Promise<O> | O, opts?: {
+    inputSchema?: ZodType;
+    outputSchema?: ZodType;
+    retry?: RetryPolicy;
+}): FnStep;
+/**
+ * Build an `AgentStep`. The `promptTemplate` can be a static string or a
+ * function that receives the input and returns the prompt.
+ */
+export declare function agentStep(id: string, agent: SDKAgent, promptTemplate: string | ((input: unknown) => string), opts?: {
+    retry?: RetryPolicy;
+}): AgentStep;
+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";

package/dist/workflow.js

@@ -1,9 +1,9 @@
-import { readFile, unlink, mkdir, open, rename, readdir } from 'fs/promises';
+import { randomUUID, randomBytes } from 'crypto';
+import { readFile, unlink, mkdir, open, rename, statfs, readdir } from 'fs/promises';
 import { join, dirname } from 'path';
 import { createRequire } from 'module';
 import { mkdirSync, readdirSync } from 'fs';
 import { AsyncLocalStorage } from 'async_hooks';
-import { randomUUID } from 'crypto';
 import { z } from 'zod';
 
 var __defProp = Object.defineProperty;
@@ -16,6 +16,136 @@ var __export = (target, all) => {
     __defProp(target, name, { get: all[name], enumerable: true });
 };
 
+// src/internal/security/redact.ts
+function readEnvOnce() {
+  const raw = process.env.THEOKIT_REDACT_SECRETS;
+  if (raw === void 0) return true;
+  return ["1", "true", "yes", "on"].includes(raw.toLowerCase());
+}
+function maskToken(token) {
+  if (token.length < 18) return "***";
+  return `${token.slice(0, 6)}...${token.slice(-4)}`;
+}
+function coerceToString(value) {
+  if (typeof value === "string") return value;
+  if (value === null || value === void 0) return null;
+  if (typeof value === "object") {
+    try {
+      const s = JSON.stringify(value);
+      return s === void 0 ? null : s;
+    } catch {
+      return "[unredactable: circular]";
+    }
+  }
+  return String(value);
+}
+function redactSecrets(text, opts) {
+  const coerced = coerceToString(text);
+  if (coerced === null) return "";
+  if (!REDACT_ENABLED) return coerced;
+  let s = coerced;
+  for (const re of BUILTIN_PATTERNS) {
+    s = s.replace(re, (m) => maskToken(m));
+  }
+  for (const re of _extraPatterns) {
+    s = s.replace(re, (m) => maskToken(m));
+  }
+  {
+    s = s.replace(BEARER_PATTERN, (_, prefix) => `${prefix}***`);
+    s = s.replace(PARAM_PATTERN, (whole, prefix, value) => {
+      if (value.includes("...")) return whole;
+      return `${prefix}***`;
+    });
+  }
+  return s;
+}
+var REDACT_ENABLED, warnedOptOut, BUILTIN_PATTERNS, BEARER_PATTERN, PARAM_PATTERN, _extraPatterns;
+var init_redact = __esm({
+  "src/internal/security/redact.ts"() {
+    REDACT_ENABLED = readEnvOnce();
+    warnedOptOut = false;
+    if (!REDACT_ENABLED && !warnedOptOut) {
+      process.stderr.write(
+        "[theokit-sdk] Secret redaction is DISABLED via THEOKIT_REDACT_SECRETS. Credentials may leak into errors, telemetry, logs, transcripts.\n"
+      );
+      warnedOptOut = true;
+    }
+    BUILTIN_PATTERNS = [
+      // T5.4: 30+ vendor prefixes (was 12 pre-T5.4). Order matters — more
+      // specific prefixes precede generic ones (e.g., sk-ant-admin01 before
+      // sk-ant-, sk-proj- before sk-). PEM block deliberately first so its
+      // multi-line span runs before any per-line patterns can fire.
+      /-----BEGIN[ ]+(?:RSA |EC |DSA |OPENSSH |ENCRYPTED |)PRIVATE KEY-----[\s\S]+?-----END[ ]+(?:RSA |EC |DSA |OPENSSH |ENCRYPTED |)PRIVATE KEY-----/g,
+      // JWT — exact 3-segment base64url. Dotted; the body floor of 4 chars per
+      // segment matches the minimum legal payload while skipping `a.b.c` noise.
+      /eyJ[A-Za-z0-9_-]{4,}\.eyJ[A-Za-z0-9_-]{4,}\.[A-Za-z0-9_-]{4,}/g,
+      // Azure Storage SAS — match the sig= component (URL-encoded base64).
+      /(?<=[?&]sig=)[A-Za-z0-9%+/]{20,}/g,
+      // Anthropic
+      /sk-ant-admin01-[A-Za-z0-9_-]{10,}/g,
+      //   Anthropic admin keys (must precede sk-ant-)
+      /sk-ant-[A-Za-z0-9_-]{10,}/g,
+      //           Anthropic regular
+      // OpenAI family + clones (sk- generic must come AFTER all sk-foo- variants)
+      /sk-proj-[A-Za-z0-9_-]{10,}/g,
+      //  OpenAI project key (must precede sk- generic)
+      /sk-[A-Za-z0-9_-]{10,}/g,
+      //       OpenAI / OpenRouter / DeepInfra / Together / DeepSeek
+      // Provider prefixes (alphabetized for maintainability)
+      /AIza[A-Za-z0-9_-]{35}/g,
+      //       Google API key
+      /AKIA[A-Z0-9]{16}/g,
+      //            AWS access key
+      /fw_[A-Za-z0-9]{20,}/g,
+      //         Fireworks
+      /glpat-[A-Za-z0-9_-]{20}/g,
+      //     GitLab PAT
+      /ghp_[A-Za-z0-9]{36}/g,
+      //         GitHub PAT classic
+      /github_pat_[A-Za-z0-9_]{82}/g,
+      // GitHub PAT fine-grained
+      /gsk_[A-Za-z0-9]{20,}/g,
+      //        Groq
+      /hf_[A-Za-z0-9]{20,}/g,
+      //         HuggingFace
+      /\bpa-[A-Za-z0-9_-]{20,}/g,
+      //     Voyage AI (word-boundary to skip CSS / kebab IDs)
+      /pcsk_[A-Za-z0-9_-]{20,}/g,
+      //     Pinecone
+      /pplx-[A-Za-z0-9_-]{20,}/g,
+      //     Perplexity
+      /r8_[A-Za-z0-9_-]{20,}/g,
+      //       Replicate
+      /rk_live_[A-Za-z0-9]{20,}/g,
+      //    Stripe restricted
+      /sk_live_[A-Za-z0-9]{20,}/g,
+      //    Stripe secret
+      /sntrys_[A-Za-z0-9]{40,}/g,
+      //     Sentry user auth
+      /xai-[A-Za-z0-9_-]{20,}/g,
+      //      xAI (Grok)
+      /xox[bpasr]-[A-Za-z0-9-]{10,}/g,
+      //Slack tokens
+      // Additional unique-prefix tokens with low false-positive risk
+      /npm_[A-Za-z0-9]{36}/g,
+      //         npm access token
+      /SG\.[A-Za-z0-9_-]{22}\.[A-Za-z0-9_-]{43}/g,
+      // SendGrid
+      /\bSK[A-Za-z0-9]{32}\b/g,
+      //       Twilio API SID (word-boundary to skip CSS class noise)
+      /\bkey-[a-f0-9]{32}\b/g,
+      //        Mailgun (hex-only narrows false positives)
+      /MT[A-Za-z0-9_-]{23}\.[A-Za-z0-9_-]{6}\.[A-Za-z0-9_-]{27}/g,
+      // Discord bot
+      /\b(?:sdk|mob)-[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}\b/g
+      // LaunchDarkly
+    ];
+    BEARER_PATTERN = /\b(Bearer\s+)([A-Za-z0-9_\-.+/=]{8,})/g;
+    PARAM_PATTERN = /(\b(?:access_token|api_key|api-key|client_secret|credential|credentials|id_token|jwt|password|private_key|refresh_token|secret|service_account|session_token|token|x-api-key)\b["']?\s*[:=]\s*["']?)([A-Za-z0-9_\-.+/]+)/gi;
+    _extraPatterns = [];
+  }
+});
+
 // src/errors.ts
 var TheokitAgentError, ConfigurationError, UnsupportedRunOperationError, InvalidTaskIdError, TaskNotFoundError;
 var init_errors = __esm({
@@ -163,9 +293,29 @@ var init_workflow = __esm({
     };
   }
 });
+function detectNetworkFsName(typeMagic) {
+  return NETWORK_FS_MAGIC.get(typeMagic) ?? null;
+}
+async function warnOnNetworkFsOnce(dirPath, label) {
+  const key2 = `${dirPath}\0${label}`;
+  if (warnedNfsDirs.has(key2)) return;
+  warnedNfsDirs.add(key2);
+  try {
+    const info = await statfs(dirPath);
+    const fsName = detectNetworkFsName(info.type);
+    if (fsName === null) return;
+    process.stderr.write(
+      `[theokit-sdk] ${label}: detected network fs (${fsName}) at ${dirPath} \u2014 rename() atomicity guarantees may be weaker than expected.
+`
+    );
+  } catch {
+  }
+}
 async function replaceFileAtomic(filePath, content) {
-  const tmp = `${filePath}.${process.pid}.${Math.random().toString(36).slice(2, 10)}.tmp`;
-  const handle = await open(tmp, "w");
+  await warnOnNetworkFsOnce(dirname(filePath), "atomic-write");
+  const suffix = randomBytes(8).toString("hex");
+  const tmp = `${filePath}.${process.pid}.${suffix}.tmp`;
+  const handle = await open(tmp, "w", 384);
   try {
     await handle.writeFile(content, "utf8");
     await handle.sync();
@@ -183,8 +333,16 @@ async function atomicWriteText(filePath, content) {
   await mkdir(dirname(filePath), { recursive: true });
   await replaceFileAtomic(filePath, content);
 }
+var NETWORK_FS_MAGIC, warnedNfsDirs;
 var init_atomic_write = __esm({
   "src/internal/persistence/atomic-write.ts"() {
+    NETWORK_FS_MAGIC = /* @__PURE__ */ new Map([
+      [26985, "nfs"],
+      [20859, "smb"],
+      [4283649346, "cifs"],
+      [1702057286, "fuse"]
+    ]);
+    warnedNfsDirs = /* @__PURE__ */ new Set();
   }
 });
 function getSnapshotStoreFor(options) {
@@ -561,91 +719,6 @@ var init_step_agent = __esm({
   }
 });
 
-// src/internal/security/redact.ts
-function readEnvOnce() {
-  const raw = process.env.THEOKIT_REDACT_SECRETS;
-  if (raw === void 0) return true;
-  return ["1", "true", "yes", "on"].includes(raw.toLowerCase());
-}
-function maskToken(token) {
-  if (token.length < 18) return "***";
-  return `${token.slice(0, 6)}...${token.slice(-4)}`;
-}
-function coerceToString(value) {
-  if (typeof value === "string") return value;
-  if (value === null || value === void 0) return null;
-  if (typeof value === "object") {
-    try {
-      const s = JSON.stringify(value);
-      return s === void 0 ? null : s;
-    } catch {
-      return "[unredactable: circular]";
-    }
-  }
-  return String(value);
-}
-function redactSecrets(text, opts) {
-  const coerced = coerceToString(text);
-  if (coerced === null) return "";
-  if (!REDACT_ENABLED) return coerced;
-  let s = coerced;
-  for (const re of BUILTIN_PATTERNS) {
-    s = s.replace(re, (m) => maskToken(m));
-  }
-  for (const re of _extraPatterns) {
-    s = s.replace(re, (m) => maskToken(m));
-  }
-  {
-    s = s.replace(BEARER_PATTERN, (_, prefix) => `${prefix}***`);
-    s = s.replace(PARAM_PATTERN, (_, prefix) => `${prefix}***`);
-  }
-  return s;
-}
-var REDACT_ENABLED, warnedOptOut, BUILTIN_PATTERNS, BEARER_PATTERN, PARAM_PATTERN, _extraPatterns;
-var init_redact = __esm({
-  "src/internal/security/redact.ts"() {
-    REDACT_ENABLED = readEnvOnce();
-    warnedOptOut = false;
-    if (!REDACT_ENABLED && !warnedOptOut) {
-      process.stderr.write(
-        "[theokit-sdk] Secret redaction is DISABLED via THEOKIT_REDACT_SECRETS. Credentials may leak into errors, telemetry, logs, transcripts.\n"
-      );
-      warnedOptOut = true;
-    }
-    BUILTIN_PATTERNS = [
-      /sk-ant-[A-Za-z0-9_-]{10,}/g,
-      //   Anthropic
-      /sk-proj-[A-Za-z0-9_-]{10,}/g,
-      //  OpenAI project key (must precede sk- generic)
-      /sk-[A-Za-z0-9_-]{10,}/g,
-      //       OpenAI / OpenRouter / DeepInfra. {10,} body floor —
-      //   real keys are 40+ chars; 10-char floor still skips `sk-test` (4) and
-      //   `sk-test-key` (8). codeFile mode protects placeholders/examples.
-      /ghp_[A-Za-z0-9]{36}/g,
-      //         GitHub PAT classic (exact length)
-      /github_pat_[A-Za-z0-9_]{82}/g,
-      // GitHub PAT fine-grained
-      /glpat-[A-Za-z0-9_-]{20}/g,
-      //     GitLab PAT
-      /AKIA[A-Z0-9]{16}/g,
-      //            AWS access key
-      /AIza[A-Za-z0-9_-]{35}/g,
-      //       Google API key
-      /xox[bpasr]-[A-Za-z0-9-]{10,}/g,
-      //Slack tokens
-      /sntrys_[A-Za-z0-9]{40,}/g,
-      //     Sentry user auth
-      /sk_live_[A-Za-z0-9]{20,}/g,
-      //    Stripe secret
-      /rk_live_[A-Za-z0-9]{20,}/g
-      //    Stripe restricted
-    ];
-    BEARER_PATTERN = /\b(Bearer\s+)([A-Za-z0-9_\-.+/=]{8,})/g;
-    PARAM_PATTERN = /(\b(?:access_token|api_key|api-key|password|secret|x-api-key)\b["']?\s*[:=]\s*["']?)([A-Za-z0-9_\-.+/]+)/gi;
-    _extraPatterns = [];
-  }
-});
-
 // src/internal/workflow/step-branch.ts
 async function runBranchStep(step, input, ctx, options, prevStepResults, dispatch) {
   const startedAt = Date.now();
@@ -2129,6 +2202,23 @@ var PersistenceSchema = z.object({
 
 // src/internal/security/path-guard.ts
 init_errors();
+var PathTraversalError = class extends ConfigurationError {
+  name = "PathTraversalError";
+  constructor(input, resolvedPath) {
+    super(`Path traversal attempt: ${input} \u2192 ${resolvedPath}`, {
+      code: "path_traversal"
+    });
+  }
+};
+function rejectNulAndControlChars(input, role) {
+  for (let i = 0; i < input.length; i++) {
+    const code = input.charCodeAt(i);
+    if (code === 0 || code >= 1 && code <= 31 || code === 127) {
+      const label = code === 0 ? "<nul-byte>" : `<control-char-0x${code.toString(16)}>`;
+      throw new PathTraversalError(`${role}: ${input}`, label);
+    }
+  }
+}
 var IDENTIFIER_PATTERN = /^[a-z0-9][a-z0-9\-_]*$/i;
 function sanitizeIdentifier(input, options) {
   const maxLen = options?.maxLen;
@@ -2137,6 +2227,7 @@ function sanitizeIdentifier(input, options) {
       code: "invalid_identifier"
     });
   }
+  rejectNulAndControlChars(input, "identifier");
   if (!IDENTIFIER_PATTERN.test(input)) {
     throw new ConfigurationError(`Identifier contains invalid characters: "${input}"`, {
       code: "invalid_identifier"