@theokit/sdk 2.25.0 → 2.27.0

package/dist/index.js

@@ -4333,7 +4333,7 @@ var init_batch = __esm({
 });
 
 // src/types/workflow.ts
-var WorkflowDuplicateStepIdError, WorkflowAlreadyRunningError, WorkflowSnapshotNotFoundError, WorkflowMaxIterationsExceededError, WorkflowNotSerializableError, WorkflowResumeStepNotFoundError, WorkflowParallelError, WorkflowCompensateNotImplementedError;
+var WorkflowDuplicateStepIdError, WorkflowInputError, WorkflowOutputError, WorkflowStateError, WorkflowAlreadyRunningError, WorkflowSnapshotNotFoundError, WorkflowMaxIterationsExceededError, WorkflowNotSerializableError, WorkflowResumeStepNotFoundError, WorkflowParallelError, WorkflowCompensateNotImplementedError;
 var init_workflow = __esm({
   "src/types/workflow.ts"() {
     WorkflowDuplicateStepIdError = class extends Error {
@@ -4344,6 +4344,36 @@ var init_workflow = __esm({
       stepId;
       name = "WorkflowDuplicateStepIdError";
     };
+    WorkflowInputError = class extends Error {
+      constructor(workflowName, detail) {
+        super(`Workflow "${workflowName}" input failed schema validation: ${detail}`);
+        this.workflowName = workflowName;
+        this.detail = detail;
+      }
+      workflowName;
+      detail;
+      name = "WorkflowInputError";
+    };
+    WorkflowOutputError = class extends Error {
+      constructor(workflowName, detail) {
+        super(`Workflow "${workflowName}" output failed schema validation: ${detail}`);
+        this.workflowName = workflowName;
+        this.detail = detail;
+      }
+      workflowName;
+      detail;
+      name = "WorkflowOutputError";
+    };
+    WorkflowStateError = class extends Error {
+      constructor(workflowName, detail) {
+        super(`Workflow "${workflowName}" state failed schema validation: ${detail}`);
+        this.workflowName = workflowName;
+        this.detail = detail;
+      }
+      workflowName;
+      detail;
+      name = "WorkflowStateError";
+    };
     WorkflowAlreadyRunningError = class extends Error {
       constructor(workflowName, runId) {
         super(`Workflow "${workflowName}" run "${runId}" already in-flight.`);
@@ -4536,7 +4566,7 @@ var init_snapshot_store = __esm({
 });
 
 // src/internal/workflow/ctx.ts
-function makeStepContext(runId, signal) {
+function makeStepContext(runId, signal, state4) {
   return {
     runId,
     signal,
@@ -4547,7 +4577,13 @@ function makeStepContext(runId, signal) {
     },
     suspend: async (payload) => {
       throw new WorkflowSuspendedSentinel(payload);
-    }
+    },
+    // SE29 — read reflects the current shared state; write goes through the
+    // controller (which validates against `stateSchema`).
+    get state() {
+      return state4.getState();
+    },
+    setState: (next) => state4.setState(next)
   };
 }
 function emit(level, runId, msg, attrs) {
@@ -4600,6 +4636,57 @@ var init_error_shape = __esm({
   }
 });
 
+// src/internal/workflow/executor-helpers.ts
+function assembleRun(params) {
+  return {
+    id: params.runId,
+    name: params.name,
+    status: params.status,
+    startedAt: params.startedAt,
+    endedAt: Date.now(),
+    stepResults: params.stepResults,
+    ...params.output !== void 0 ? { output: params.output } : {},
+    ...params.error !== void 0 ? { error: params.error } : {}
+  };
+}
+function abortRun(name, runId, startedAt, stepResults, signal) {
+  return assembleRun({
+    runId,
+    name,
+    status: "cancelled",
+    stepResults,
+    startedAt,
+    error: { name: "AbortError", message: String(signal.reason ?? "Aborted") }
+  });
+}
+function validateWorkflowSchema(schema, value) {
+  if (schema === void 0) return void 0;
+  let parsed;
+  try {
+    parsed = schema.safeParse(value);
+  } catch {
+    return "schema uses async refinements, which whole-workflow validation does not support (use a synchronous Zod schema)";
+  }
+  if (parsed.success) return void 0;
+  return parsed.error.issues.map((issue) => `${issue.path.join(".") || "(root)"}: ${issue.message}`).join("; ");
+}
+function makeStateController(options, initial) {
+  let current = initial;
+  return {
+    getState: () => current,
+    setState: (next) => {
+      const issues = validateWorkflowSchema(options.stateSchema, next);
+      if (issues !== void 0) throw new WorkflowStateError(options.name, issues);
+      current = next;
+    }
+  };
+}
+var init_executor_helpers = __esm({
+  "src/internal/workflow/executor-helpers.ts"() {
+    init_workflow();
+  }
+});
+
 // src/internal/workflow/run-id.ts
 function mintRunId() {
   return `wfr-${globalThis.crypto.randomUUID().replace(/-/g, "").slice(0, 8)}`;
@@ -5266,6 +5353,8 @@ async function handleSuspend(err, ctx) {
       suspendedPayload: err.payload,
       stepResults: ctx.stepResults,
       accumulatedInput: ctx.acc,
+      state: ctx.stepCtx.state,
+      // SE29 — capture the shared state at suspend
       options: ctx.options
     });
   } catch (snapErr) {
@@ -5317,7 +5406,7 @@ async function runOneStep(args) {
     result = await dispatchStep(args.step, args.acc, args.ctx, args.options, args.stepResults);
   } catch (err) {
     if (err instanceof WorkflowSuspendedSentinel) {
-      const outcome = await handleSuspend(err, { ...args, stepSpan });
+      const outcome = await handleSuspend(err, { ...args, stepSpan, stepCtx: args.ctx });
       return { kind: "terminal", run: outcome.run };
     }
     result = {
@@ -5334,22 +5423,42 @@ async function runOneStep(args) {
   stepSpan.end();
   return { kind: "ok", result };
 }
-function abortRun(name, runId, startedAt, stepResults, signal) {
-  return assembleRun({
-    runId,
-    name,
-    status: "cancelled",
-    stepResults,
-    startedAt,
-    error: { name: "AbortError", message: String(signal.reason ?? "Aborted") }
-  });
+function handleStepOutcome(outcome, step, loop, onStepEvent) {
+  if (outcome.kind === "terminal") {
+    if (outcome.run.status === "suspended") {
+      onStepEvent?.({ type: "workflow_suspended", stepId: step.id });
+    }
+    return { terminal: outcome.run };
+  }
+  loop.stepResults.push(outcome.result);
+  if (outcome.result.status === "failed") {
+    onStepEvent?.({
+      type: "step_failed",
+      stepId: step.id,
+      error: outcome.result.error ?? { name: "WorkflowStepError", message: "step failed" }
+    });
+    return {
+      terminal: assembleRun({
+        runId: loop.runId,
+        name: loop.name,
+        status: "failed",
+        stepResults: loop.stepResults,
+        startedAt: loop.startedAt,
+        error: outcome.result.error
+      })
+    };
+  }
+  onStepEvent?.({ type: "step_completed", stepId: step.id, output: outcome.result.output });
+  return { acc: outcome.result.output };
 }
 async function runStepsLoop(params) {
-  const { options, steps, ctx, runId, startedAt, signal } = params;
+  const { options, steps, ctx, runId, startedAt, signal, onStepEvent } = params;
   const stepResults = [...params.initialStepResults ?? []];
+  const loop = { stepResults, runId, name: options.name, startedAt };
   let acc = params.input;
   for (const step of steps) {
     if (signal.aborted) return abortRun(options.name, runId, startedAt, stepResults, signal);
+    onStepEvent?.({ type: "step_started", stepId: step.id });
     const outcome = await runOneStep({
       step,
       acc,
@@ -5360,20 +5469,22 @@ async function runStepsLoop(params) {
       name: options.name,
       startedAt
     });
-    if (outcome.kind === "terminal") return outcome.run;
-    stepResults.push(outcome.result);
-    if (outcome.result.status === "failed") {
-      return assembleRun({
-        runId,
-        name: options.name,
-        status: "failed",
-        stepResults,
-        startedAt,
-        error: outcome.result.error
-      });
-    }
-    acc = outcome.result.output;
+    const handled = handleStepOutcome(outcome, step, loop, onStepEvent);
+    if ("terminal" in handled) return handled.terminal;
+    acc = handled.acc;
+  }
+  const outputIssues = validateWorkflowSchema(options.outputSchema, acc);
+  if (outputIssues !== void 0) {
+    return assembleRun({
+      runId,
+      name: options.name,
+      status: "failed",
+      stepResults,
+      startedAt,
+      error: errToShape(new WorkflowOutputError(options.name, outputIssues))
+    });
   }
+  onStepEvent?.({ type: "workflow_completed" });
   return assembleRun({
     runId,
     name: options.name,
@@ -5396,8 +5507,33 @@ async function executeWorkflow(options, steps, input, runOpts) {
     runSpan.end();
     return abortRun(options.name, runId, startedAt, [], signal);
   }
-  const ctx = makeStepContext(runId, signal);
+  const internal = runOpts;
+  const seededState = internal?.restoredState !== void 0 ? internal.restoredState : options.initialState;
+  const stateController = makeStateController(options, seededState);
+  const ctx = makeStepContext(runId, signal, stateController);
   try {
+    const inputIssues = validateWorkflowSchema(options.inputSchema, input);
+    if (inputIssues !== void 0) {
+      return assembleRun({
+        runId,
+        name: options.name,
+        status: "failed",
+        stepResults: [],
+        startedAt,
+        error: errToShape(new WorkflowInputError(options.name, inputIssues))
+      });
+    }
+    const stateIssues = seededState !== void 0 ? validateWorkflowSchema(options.stateSchema, seededState) : void 0;
+    if (stateIssues !== void 0) {
+      return assembleRun({
+        runId,
+        name: options.name,
+        status: "failed",
+        stepResults: [],
+        startedAt,
+        error: errToShape(new WorkflowStateError(options.name, stateIssues))
+      });
+    }
     return await runStepsLoop({
       options,
       steps,
@@ -5406,7 +5542,8 @@ async function executeWorkflow(options, steps, input, runOpts) {
       runId,
       startedAt,
       signal,
-      ...runOpts?.initialStepResults !== void 0 ? { initialStepResults: runOpts.initialStepResults } : {}
+      ...internal?.initialStepResults !== void 0 ? { initialStepResults: internal.initialStepResults } : {},
+      ...internal?.onStepEvent !== void 0 ? { onStepEvent: internal.onStepEvent } : {}
     });
   } finally {
     runSpan.end();
@@ -5437,28 +5574,17 @@ async function dispatchStep(step, input, ctx, options, prevStepResults) {
     }
   }
 }
-function assembleRun(params) {
-  const endedAt = Date.now();
-  return {
-    id: params.runId,
-    name: params.name,
-    status: params.status,
-    startedAt: params.startedAt,
-    endedAt,
-    stepResults: params.stepResults,
-    ...params.output !== void 0 ? { output: params.output } : {},
-    ...params.error !== void 0 ? { error: params.error } : {}
-  };
-}
 async function saveSnapshot(p) {
   const snapshot = {
-    _schemaVersion: 1,
+    _schemaVersion: 2,
+    // SE29 — carries `state`
     runId: p.runId,
     workflowName: p.workflowName,
     currentStepId: p.currentStepId,
     suspendedPayload: p.suspendedPayload,
     stepResults: p.stepResults,
     accumulatedInput: p.accumulatedInput,
+    ...p.state !== void 0 ? { state: p.state } : {},
     suspendedAt: Date.now()
   };
   const store = getSnapshotStoreFor(p.options);
@@ -5491,7 +5617,10 @@ async function resumeWorkflow(opts) {
     signal: opts.signal,
     runId: opts.runId,
     // M3 #62 — restore prior step outputs so the resumed run is not lossy (internal seam).
-    initialStepResults: snapshot.stepResults
+    initialStepResults: snapshot.stepResults,
+    // SE29 — restore shared state (v2 snapshot). A v1 snapshot has no `state` →
+    // executeWorkflow falls back to `options.initialState`.
+    ...snapshot.state !== void 0 ? { restoredState: snapshot.state } : {}
   });
 }
 var init_executor = __esm({
@@ -5499,6 +5628,7 @@ var init_executor = __esm({
     init_workflow();
     init_ctx();
     init_error_shape();
+    init_executor_helpers();
     init_run_id();
     init_single_flight();
     init_snapshot_store();
@@ -7734,8 +7864,18 @@ function validateCloudToolParity(options) {
   if (options.cloud === void 0) return;
   rejectFunctionSystemPrompt(options);
   rejectFunctionSkills(options);
+  rejectProcessors(options);
   rejectStdioMcpLocalPaths(options);
 }
+function rejectProcessors(options) {
+  const hasProcessors = (options.inputProcessors?.length ?? 0) > 0 || (options.outputProcessors?.length ?? 0) > 0;
+  if (hasProcessors) {
+    throw new ConfigurationError(
+      "Cloud agents can't run guardrail processors \u2014 a Processor carries function handlers that don't survive serialization to PaaS. Run processors on a local agent, or move the guardrail into a server-side gateway in front of TheoCloud.",
+      { code: "cloud_incompatible_function_resolver" }
+    );
+  }
+}
 function rejectFunctionSystemPrompt(options) {
   if (typeof options.systemPrompt === "function") {
     throw new ConfigurationError(
@@ -17674,6 +17814,145 @@ function ponyfillAny(signals) {
   return ctrl.signal;
 }
 
+// src/internal/runtime/processors/run-processors.ts
+var ProcessorAbort = class {
+  constructor(processorId, reason) {
+    this.processorId = processorId;
+    this.reason = reason;
+  }
+  processorId;
+  reason;
+};
+function fireViolation(processor, violation) {
+  try {
+    processor.onViolation?.(violation);
+  } catch {
+  }
+}
+function controlsFor(processor) {
+  return {
+    abort(reason) {
+      throw new ProcessorAbort(processor.id, reason);
+    },
+    warn(message, detail) {
+      fireViolation(processor, {
+        processorId: processor.id,
+        message,
+        ...detail !== void 0 ? { detail } : {}
+      });
+    }
+  };
+}
+function selectHandler(processor, phase) {
+  if (phase === "input") {
+    return processor.processInput ? { kind: "input", fn: processor.processInput } : void 0;
+  }
+  return processor.processOutput ? { kind: "output", fn: processor.processOutput } : void 0;
+}
+function invokeHandler(handler, value, agentId, controls) {
+  return handler.kind === "input" ? handler.fn({ message: value, agentId, ...controls }) : handler.fn({ text: value, agentId, ...controls });
+}
+async function runOneProcessor(processor, value, agentId, phase) {
+  const handler = selectHandler(processor, phase);
+  if (handler === void 0) return { value };
+  try {
+    const out = await invokeHandler(handler, value, agentId, controlsFor(processor));
+    return { value: typeof out === "string" ? out : value };
+  } catch (err) {
+    if (!(err instanceof ProcessorAbort)) throw err;
+    fireViolation(processor, { processorId: err.processorId, message: err.reason });
+    return { tripwire: { reason: err.reason, processorId: err.processorId } };
+  }
+}
+async function runPipeline(processors, initial, agentId, phase) {
+  let value = initial;
+  for (const processor of processors) {
+    const step = await runOneProcessor(processor, value, agentId, phase);
+    if ("tripwire" in step) return { kind: "tripwire", tripwire: step.tripwire };
+    value = step.value;
+  }
+  return { kind: "ok", value };
+}
+function runInputProcessors(processors, message, agentId) {
+  return runPipeline(processors, message, agentId, "input");
+}
+function runOutputProcessors(processors, text, agentId) {
+  return runPipeline(processors, text, agentId, "output");
+}
+
+// src/internal/runtime/processors/tripwire-run.ts
+var SUPPORTED = /* @__PURE__ */ new Set([
+  "stream",
+  "wait",
+  "cancel",
+  "conversation"
+]);
+function emptyStream() {
+  return {
+    next: () => Promise.resolve({ done: true, value: void 0 }),
+    return: () => Promise.resolve({ done: true, value: void 0 }),
+    throw: (err) => Promise.reject(err),
+    [Symbol.asyncIterator]() {
+      return this;
+    }
+  };
+}
+function createTripwireRun(args) {
+  const id = globalThis.crypto.randomUUID();
+  const result = {
+    id,
+    status: "cancelled",
+    tripwire: args.tripwire,
+    ...args.model !== void 0 ? { model: args.model } : {}
+  };
+  const run = {
+    id,
+    agentId: args.agentId,
+    status: "cancelled",
+    ...args.model !== void 0 ? { model: args.model } : {},
+    stream: () => emptyStream(),
+    wait: () => Promise.resolve(result),
+    cancel: () => Promise.resolve(),
+    conversation: () => Promise.resolve([]),
+    supports: (op) => SUPPORTED.has(op),
+    unsupportedReason: (op) => SUPPORTED.has(op) ? void 0 : `operation "${op}" is not available on a tripwire run`,
+    onDidChangeStatus: () => () => {
+    }
+    // already terminal — status never changes
+  };
+  registerRun(run);
+  return run;
+}
+
+// src/internal/runtime/processors/wrap-output-run.ts
+function wrapRunWithOutputProcessors(args) {
+  if (args.processors.length === 0) return args.run;
+  const compute = async () => {
+    const result = await args.run.wait();
+    if (result.status !== "finished" || result.result === void 0) return result;
+    const res = await runOutputProcessors(args.processors, result.result, args.agentId);
+    if (res.kind === "ok") return { ...result, result: res.value };
+    emitRunEvent(args.onRunEvent, {
+      type: "tripwire",
+      reason: res.tripwire.reason,
+      processorId: res.tripwire.processorId
+    });
+    const { result: _suppressed, ...metadata } = result;
+    return { ...metadata, status: "cancelled", tripwire: res.tripwire };
+  };
+  let processed;
+  const wrappedWait = () => {
+    processed ??= compute();
+    return processed;
+  };
+  return new Proxy(args.run, {
+    get(target, prop, receiver) {
+      if (prop === "wait") return wrappedWait;
+      return Reflect.get(target, prop, receiver);
+    }
+  });
+}
+
 // src/internal/runtime/local-agent/local-agent-memory-hooks.ts
 var DEFAULT_MAX_RECALL_BYTES = 16e3;
 async function applyPreUserSendHook(args) {
@@ -17721,11 +18000,38 @@ function wrapRunWithPostReplyHook(args) {
 }
 
 // src/internal/runtime/local-agent/local-agent-send.ts
+async function applyInputProcessors(inputs, message, rawUserText, options, sendModel) {
+  const processors = inputs.options.inputProcessors;
+  if (processors === void 0 || processors.length === 0) {
+    return { userText: rawUserText, effectiveMessage: message };
+  }
+  const res = await runInputProcessors(processors, rawUserText, inputs.agentId);
+  if (res.kind === "tripwire") {
+    emitRunEvent(options.onRunEvent, {
+      type: "tripwire",
+      reason: res.tripwire.reason,
+      processorId: res.tripwire.processorId
+    });
+    return {
+      tripwireRun: createTripwireRun({
+        agentId: inputs.agentId,
+        tripwire: res.tripwire,
+        model: sendModel
+      })
+    };
+  }
+  const effectiveMessage = typeof message === "string" ? res.value : { ...message, text: res.value };
+  return { userText: res.value, effectiveMessage };
+}
 async function executeSendLocked(inputs, message, options) {
   if (inputs.disposed) throw new AgentDisposedError(inputs.agentId);
   await consumePending(inputs.agentId, inputs.invalidationPending, inputs.clearInvalidation, inputs.reload);
-  inputs.applyModelOverride(normalizeModel(options.model));
-  const userText = typeof message === "string" ? message : message.text;
+  const sendModel = normalizeModel(options.model);
+  inputs.applyModelOverride(sendModel);
+  const rawUserText = typeof message === "string" ? message : message.text;
+  const gated = await applyInputProcessors(inputs, message, rawUserText, options, sendModel);
+  if ("tripwireRun" in gated) return gated.tripwireRun;
+  const { userText, effectiveMessage } = gated;
   if (inputs.options.onBeforeSend !== void 0) {
     await inputs.options.onBeforeSend({
       conversationId: inputs.agentId,
@@ -17737,7 +18043,7 @@ async function executeSendLocked(inputs, message, options) {
     pluginManager: inputs.pluginManagerCode,
     agentId: inputs.agentId,
     options: inputs.options,
-    original: message,
+    original: effectiveMessage,
     userText,
     sendOptions: options
   });
@@ -17775,11 +18081,18 @@ async function executeSendLocked(inputs, message, options) {
     memoryTools,
     effectiveMemoryProvider
   );
+  const outputProcessors = inputs.options.outputProcessors;
+  const processedRun = outputProcessors !== void 0 && outputProcessors.length > 0 ? wrapRunWithOutputProcessors({
+    run,
+    processors: outputProcessors,
+    agentId: inputs.agentId,
+    onRunEvent: options.onRunEvent
+  }) : run;
   return wrapRunWithPostReplyHook({
     pluginManager: inputs.pluginManagerCode,
     agentId: inputs.agentId,
     options: inputs.options,
-    run,
+    run: processedRun,
     userText
   });
 }
@@ -19138,6 +19451,48 @@ var Budget = class {
   }
 };
 
+// src/built-in-processors.ts
+var CHARS_PER_TOKEN = 4;
+function estimateTokens(text) {
+  return Math.ceil(text.length / CHARS_PER_TOKEN);
+}
+var CONTROL_CHARS = /[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F-\u009F]/g;
+function createUnicodeNormalizer(opts = {}) {
+  const stripControlChars = opts.stripControlChars ?? false;
+  const collapseWhitespace = opts.collapseWhitespace ?? false;
+  return {
+    id: "unicode-normalizer",
+    processInput(ctx) {
+      let s = ctx.message.normalize("NFC");
+      if (stripControlChars) s = s.replace(CONTROL_CHARS, "");
+      if (collapseWhitespace) {
+        s = s.replace(/[^\S\n]+/g, " ").replace(/ *\n */g, "\n").replace(/\n{3,}/g, "\n\n").trim();
+      }
+      return s;
+    }
+  };
+}
+function createTokenLimiter(opts) {
+  if (!Number.isInteger(opts.limit) || opts.limit <= 0) {
+    throw new Error("createTokenLimiter: `limit` must be a positive integer.");
+  }
+  const limit = opts.limit;
+  const strategy = opts.strategy ?? "truncate";
+  const cap2 = (text, controls) => {
+    const estimated = estimateTokens(text);
+    if (estimated <= limit) return text;
+    if (strategy === "block") {
+      controls.abort(`exceeds token limit ${limit} (~${estimated} estimated)`);
+    }
+    return [...text].slice(0, limit * CHARS_PER_TOKEN).join("");
+  };
+  return {
+    id: "token-limiter",
+    processInput: (ctx) => cap2(ctx.message, ctx),
+    processOutput: (ctx) => cap2(ctx.text, ctx)
+  };
+}
+
 // src/create-skill.ts
 function createSkill(spec) {
   if (!spec.name) throw new Error("createSkill: `name` is required.");
@@ -19819,7 +20174,7 @@ function createCounterBudgetTracker(options = {}) {
 }
 
 // src/internal/runtime/context/replay-history.ts
-var CHARS_PER_TOKEN = 4;
+var CHARS_PER_TOKEN2 = 4;
 var DEFAULT_RESERVE_TOKENS = 8e3;
 function finiteOr(value, fallback) {
   return Number.isFinite(value) ? value : fallback;
@@ -19827,7 +20182,7 @@ function finiteOr(value, fallback) {
 function charBudget(options) {
   const window = finiteOr(options.contextWindowTokens, 0);
   const reserve = finiteOr(options.reserveTokens ?? DEFAULT_RESERVE_TOKENS, DEFAULT_RESERVE_TOKENS);
-  return Math.max(0, window - reserve) * CHARS_PER_TOKEN;
+  return Math.max(0, window - reserve) * CHARS_PER_TOKEN2;
 }
 function assistantText2(event) {
   return event.message.content.filter((block) => block.type === "text").map((block) => block.text).join("");
@@ -20803,6 +21158,45 @@ var PersistenceSchema = z.object({
 
 // src/workflow.ts
 init_path_guard();
+
+// src/internal/workflow/event-stream.ts
+function createEventStream() {
+  const buffer = [];
+  const waiters = [];
+  let ended = false;
+  const stream = {
+    push(event) {
+      if (ended) return;
+      const waiter = waiters.shift();
+      if (waiter !== void 0) waiter({ value: event, done: false });
+      else buffer.push(event);
+    },
+    end() {
+      if (ended) return;
+      ended = true;
+      for (const waiter of waiters.splice(0)) waiter({ value: void 0, done: true });
+    },
+    next() {
+      const buffered = buffer.shift();
+      if (buffered !== void 0) return Promise.resolve({ value: buffered, done: false });
+      if (ended) return Promise.resolve({ value: void 0, done: true });
+      return new Promise((resolve3) => waiters.push(resolve3));
+    },
+    // `for await` calls return() on break/throw — close early so events stop
+    // buffering in memory for a consumer that stopped iterating.
+    return() {
+      stream.end();
+      buffer.length = 0;
+      return Promise.resolve({ value: void 0, done: true });
+    },
+    [Symbol.asyncIterator]() {
+      return stream;
+    }
+  };
+  return stream;
+}
+
+// src/workflow.ts
 init_workflow();
 var RetryPolicySchema = z.object({
   // EC-3 absorbed: maxAttempts MUST be a finite int in [1, 20].
@@ -20814,7 +21208,12 @@ var RetryPolicySchema = z.object({
 });
 var WorkflowOptionsSchema = z.object({
   name: z.string().min(1).max(128),
-  persistence: PersistenceSchema
+  persistence: PersistenceSchema,
+  // SE27 — declared so a future `new WorkflowBuilder(parsed)` refactor cannot
+  // silently drop them (create() passes the ORIGINAL options today, but the
+  // schema is also the documentation of the shape).
+  inputSchema: z.custom().optional(),
+  outputSchema: z.custom().optional()
 });
 var WorkflowBuilder = class {
   /** @internal */
@@ -20991,6 +21390,36 @@ var Workflow = class {
     }
     return result;
   }
+  /**
+   * SE28 — run the workflow and STREAM step-level events as they happen. Returns
+   * an async iterator of {@link WorkflowEvent}s (`step_started` / `step_completed`
+   * / `step_failed` / `workflow_suspended` / `workflow_completed`, top-level
+   * steps) plus a `result` promise resolving to the same terminal
+   * {@link WorkflowRun} `run()` returns. Iterate for progress; await `result` for
+   * the outcome. The stream ends when the run terminates.
+   *
+   * `result` is the AUTHORITATIVE terminal status. Not every terminal state has a
+   * closing event: a step failure emits `step_failed`, but an `outputSchema`
+   * rejection (SE27) or an abort ends the stream WITHOUT `workflow_completed` —
+   * always `await result` to read the final `status`. Consuming order is free:
+   * awaiting `result` without draining, or draining without awaiting `result`,
+   * both work (breaking out of `for await` stops the buffering early).
+   */
+  stream(input, opts) {
+    const queue = createEventStream();
+    const result = (async () => {
+      const { executeWorkflow: executeWorkflow2 } = await Promise.resolve().then(() => (init_executor(), executor_exports));
+      try {
+        return await executeWorkflow2(this._options, this._steps, input, {
+          ...opts,
+          onStepEvent: (event) => queue.push(event)
+        });
+      } finally {
+        queue.end();
+      }
+    })();
+    return Object.assign(queue, { result });
+  }
   /**
    * Resume a suspended workflow from its snapshot. Throws
    * `WorkflowSnapshotNotFoundError` if `runId` is unknown.
@@ -21513,6 +21942,6 @@ function safeStringify2(v) {
   }
 }
 
-export { Agent, AgentBuilder, AgentDisposedError, AgentRunError, AuthenticationError, Budget, BudgetExceededError, ConfigurationError, Cron, EventBus, FileSystemConversationStorage, GenerateObjectError, InMemoryConversationStorage, IntegrationNotConnectedError, InvalidTaskIdError, JobQueue, Memory, MemoryAdapterError, NetworkError, PermissionEngine, RateLimitError, Security, StreamObjectError, Task, TaskNotFoundError, Theokit, TheokitAgentError, ToolError, UnknownAgentError, UnsupportedBudgetOperationError, UnsupportedRunOperationError, UnsupportedTaskOperationError, UsageAccumulator, applyMode, buildReplayHistory, chargeAndCheckThresholds, computeCost, createAgentFactory, createCounterBudgetTracker, createNoopMemoryProvider, createPermissionPlugin, createSessionManager, createSkill, createSquad, definePlugin, defineProvider, defineSkillReadTool, defineTool, emitRunEvent, extractRawId, getPricingEntry, inferApiMode, isTransientError, migrateSqliteToLance2 as migrateSqliteToLance, mkMemoryId, normalizeSchema, normalizeUsage, preflightCheck, scopedConversationId, sessionScopePrefix, toShareGptTrajectory, withCwdMutex };
+export { Agent, AgentBuilder, AgentDisposedError, AgentRunError, AuthenticationError, Budget, BudgetExceededError, ConfigurationError, Cron, EventBus, FileSystemConversationStorage, GenerateObjectError, InMemoryConversationStorage, IntegrationNotConnectedError, InvalidTaskIdError, JobQueue, Memory, MemoryAdapterError, NetworkError, PermissionEngine, RateLimitError, Security, StreamObjectError, Task, TaskNotFoundError, Theokit, TheokitAgentError, ToolError, UnknownAgentError, UnsupportedBudgetOperationError, UnsupportedRunOperationError, UnsupportedTaskOperationError, UsageAccumulator, applyMode, buildReplayHistory, chargeAndCheckThresholds, computeCost, createAgentFactory, createCounterBudgetTracker, createNoopMemoryProvider, createPermissionPlugin, createSessionManager, createSkill, createSquad, createTokenLimiter, createUnicodeNormalizer, definePlugin, defineProvider, defineSkillReadTool, defineTool, emitRunEvent, estimateTokens, extractRawId, getPricingEntry, inferApiMode, isTransientError, migrateSqliteToLance2 as migrateSqliteToLance, mkMemoryId, normalizeSchema, normalizeUsage, preflightCheck, scopedConversationId, sessionScopePrefix, toShareGptTrajectory, withCwdMutex };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map