@theokit/sdk 2.28.0 → 2.30.0

package/dist/{cron-BR1NCSk1.d.cts → cron-BNHJywtl.d.ts}

@@ -1,5 +1,6 @@
-import { C as CustomTool, M as ModelSelection, a4 as SDKUserMessage, a6 as SendOptions, b as Run, G as GenerateOptions, j as GenerateRunResult, N as RunToCompletionOptions, Q as RunToCompletionResult, S as SDKMessage, ad as StreamToCompletionResult, a as McpServerConfig, P as Processor } from './run-CdWiihyU.cjs';
 import * as zod from 'zod';
+import { ZodType } from 'zod';
+import { C as CustomTool, M as ModelSelection, a7 as SDKUserMessage, a9 as SendOptions, b as Run, G as GenerateOptions, k as GenerateRunResult, V as RunToCompletionOptions, W as RunToCompletionResult, S as SDKMessage, ag as StreamToCompletionResult, a as McpServerConfig, P as Processor, r as MessageOrigin } from './run-CLXKMRgq.js';
 
 /**
  * Fork primitive public type contracts (T1.2, ADRs D110-D114).
@@ -139,6 +140,13 @@ interface GoalOptions {
     judgeApiKey?: string;
     /** Optional subgoals fed to the judge prompt. */
     subgoals?: string[];
+    /**
+     * SE33 (ADR 0012) — resolve the goal from the durable thread-scoped
+     * objective when `runUntil()` is called with NO explicit goal. Also the
+     * key the loop writes `runsUsed` / `status` progress back to. Ignored when
+     * an explicit goal is passed (that path stays ephemeral).
+     */
+    threadId?: string;
     /**
      * Cancel mid-loop via `AbortController.signal`. The generator yields
      * a `status_change: paused` event and returns at the next turn
@@ -570,6 +578,52 @@ interface BudgetTracker {
     nextIteration?(): void;
 }
 
+/**
+ * SE33 — the durable, thread-scoped objective (Mastra Goals parity, durable half).
+ *
+ * The SDK's `runUntil` goal loop (ADRs D115-D121) is per-call/transient. SE33
+ * persists an objective in conversation storage (via the optional
+ * `getObjectiveRecord`/`setObjectiveRecord` adapter methods) so it survives
+ * reloads, is managed via `Agent` methods, and is read by `runUntil` when no
+ * explicit goal is passed. See ADR 0012.
+ *
+ * @public
+ */
+/** Lifecycle status of a durable objective (ADR 0012 D2). */
+type ObjectiveStatus = "active" | "done" | "paused";
+/**
+ * The per-objective override subset of goal options. Precedence (ADR 0012 D3):
+ * these `record.options` → the agent's standing `goal` config → built-in default.
+ * The `judgeModel` is the activation switch — with no judge resolved, the
+ * standing objective is inert (no scoring, no budget consumed).
+ */
+interface DurableGoalOptions {
+    /** Max judge-gated turns before the loop stops (default 20 — the `runUntil` default). */
+    readonly maxRuns?: number;
+    /** Judge model identifier (e.g. `"openai/gpt-4o-mini"`). Absent ⇒ inherit from agent `goal` config. */
+    readonly judgeModel?: string;
+    /** Optional extra judge instruction appended to the default judge prompt. */
+    readonly prompt?: string;
+}
+/**
+ * A persisted objective record. Stored under the caller's `threadId` (the
+ * conversation key). `_schemaVersion` mirrors {@link import("./workflow.js").WorkflowSnapshot}
+ * for future migration (ADR 0012 D2).
+ */
+interface ObjectiveRecord {
+    readonly _schemaVersion: 1;
+    readonly objective: string;
+    readonly options?: DurableGoalOptions;
+    readonly status: ObjectiveStatus;
+    readonly runsUsed: number;
+}
+/** The standing `goal` config on an agent (ADR 0012 D3). Read when a durable objective is set. */
+interface AgentGoalConfig {
+    readonly judgeModel?: string;
+    readonly maxRuns?: number;
+    readonly prompt?: string;
+}
+
 /**
  * Pluggable persistence for conversation history (Production-Readiness #1, ADRs D303-D306).
  *
@@ -581,6 +635,7 @@ interface BudgetTracker {
  *
  * @public
  */
+
 /**
  * Persisted message envelope used by {@link ConversationStorageAdapter}.
  *
@@ -712,6 +767,28 @@ interface ConversationStorageAdapter {
      * lazily. Adapters that cannot store side metadata MAY omit this.
      */
     setSessionMeta?(conversationId: string, patch: SessionMetaPatch): Promise<void>;
+    /**
+     * SE33 — optional: read the durable {@link ObjectiveRecord} for a conversation
+     * (the thread-scoped goal). Absent ⇒ the agent's objective methods no-op
+     * (typed degradation, same contract as `getSessionMeta`). ADR 0012 D1.
+     */
+    getObjectiveRecord?(conversationId: string): Promise<ObjectiveRecord | undefined>;
+    /**
+     * SE33 — optional: write (or, with `record: null`, CLEAR) the durable
+     * objective for a conversation. MUST create the record lazily. Adapters that
+     * cannot store side state MAY omit this. ADR 0012 D1.
+     */
+    setObjectiveRecord?(conversationId: string, record: ObjectiveRecord | null): Promise<void>;
+    /**
+     * SE33 — optional: ATOMIC read-modify-write of the durable objective. `mutate`
+     * receives the current record (or `undefined`) and returns the next record, or
+     * `null` to clear, or `undefined` to leave it unchanged. The whole get→mutate→set
+     * MUST run under the adapter's own concurrency guard (the FS adapter holds its
+     * file lock across the read AND the write) so concurrent progress write-backs
+     * on one thread cannot drop turns (TOCTOU). Adapters that omit it fall back to a
+     * non-atomic `getObjectiveRecord` + `setObjectiveRecord` pair. ADR 0012 D1.
+     */
+    updateObjectiveRecord?(conversationId: string, mutate: (current: ObjectiveRecord | undefined) => ObjectiveRecord | null | undefined): Promise<void>;
     /**
      * Optional: dispose underlying handles (close DB pool, etc.).
      * MUST be safe to call multiple times.
@@ -1502,6 +1579,14 @@ interface AgentOptions {
     outputProcessors?: readonly Processor[];
     /** Memory configuration. Persists durable facts; auto-recalled on send. */
     memory?: MemorySettings;
+    /**
+     * SE33 — standing goal config for a DURABLE, thread-scoped objective (Mastra
+     * Goals parity). Read when a durable objective (`setObjective`) is set: the
+     * per-objective values take precedence over this config, which takes
+     * precedence over the built-in defaults. The judge is the activation switch —
+     * with no `judgeModel` resolved, a standing objective is inert. ADR 0012.
+     */
+    goal?: AgentGoalConfig;
     /**
      * Inline custom tools. Local runtime only — cloud agents reject any non-empty
      * `tools` array. Handlers are not persisted; pass them again on resume.
@@ -1801,7 +1886,30 @@ interface SDKAgent {
      *
      * @public
      */
-    runUntil?(goal: string, options?: GoalOptions): RunUntilIterator;
+    runUntil?(goal?: string, options?: GoalOptions): RunUntilIterator;
+    /**
+     * SE33 — set a DURABLE, thread-scoped objective persisted via the
+     * conversation storage (survives reload). Read by `runUntil()` when no
+     * explicit goal is passed. `threadId` is REQUIRED (the durability key); the
+     * call no-ops when the run is not memory-backed (the storage adapter omits the
+     * optional objective methods). Throws `ConfigurationError` on `maxRuns <= 0`.
+     * ADR 0012.
+     */
+    setObjective?(objective: string, opts: {
+        threadId: string;
+    } & DurableGoalOptions): Promise<void>;
+    /** SE33 — read the durable objective record for a thread (or `undefined`). */
+    getObjective?(opts: {
+        threadId: string;
+    }): Promise<ObjectiveRecord | undefined>;
+    /** SE33 — merge options into the active objective (only provided fields change; no-op if unset). */
+    updateObjectiveOptions?(opts: {
+        threadId: string;
+    } & DurableGoalOptions): Promise<void>;
+    /** SE33 — drop the durable objective for a thread. */
+    clearObjective?(opts: {
+        threadId: string;
+    }): Promise<void>;
     /**
      * Fork a short-lived sub-agent with parent's credentials + system
      * prompt byte-identical (ADR D112 — cache hit) and a restricted tool
@@ -2001,6 +2109,345 @@ interface ListResult<T> {
     nextCursor?: string;
 }
 
+/**
+ * Public type contract for `Workflow.create / .run / .resume` (Adoption
+ * Roadmap #5; ADRs D230-D248).
+ *
+ * Step types form a discriminated union by `kind`. Helper factory functions
+ * (`fn()`, `agentStep()`) live in `workflow.ts` and hide the discriminator
+ * from end users.
+ *
+ * @public
+ */
+
+type Step = FnStep | AgentStep | ParallelStep | BranchStep | ForeachStep | DowhileStep | SleepStep | SuspendStep;
+/** A pure function step. */
+interface FnStep {
+    readonly kind: "fn";
+    readonly id: string;
+    readonly fn: (input: unknown, ctx: StepContext) => Promise<unknown> | unknown;
+    readonly inputSchema?: ZodType;
+    readonly outputSchema?: ZodType;
+    readonly retry?: RetryPolicy;
+    /** D238 — slot reserved; runtime throws if engine not yet implemented. */
+    readonly compensate?: (input: unknown, output: unknown, error: Error) => Promise<void> | void;
+}
+/** An agent.send-driven step. */
+interface AgentStep {
+    readonly kind: "agent";
+    readonly id: string;
+    readonly agent: SDKAgent;
+    readonly promptTemplate: string | ((input: unknown) => string);
+    readonly retry?: RetryPolicy;
+    /**
+     * SE3 — provenance stamped onto this step's `agent.send()` (forwarded to
+     * `RunResult.origin`). Squad sets `{ kind: "peer", from: "agent-<i-1>" }` on
+     * every step after the first so a peer-driven turn is attributable.
+     */
+    readonly origin?: MessageOrigin;
+}
+/** N concurrent branches, each its own mini-step-list. */
+interface ParallelStep {
+    readonly kind: "parallel";
+    readonly id: string;
+    readonly branches: ReadonlyArray<ReadonlyArray<Step>>;
+    readonly concurrency?: number;
+    readonly errorPolicy?: "fail-fast" | "collect";
+}
+/** First-match-wins predicates + optional fallback. */
+interface BranchStep {
+    readonly kind: "branch";
+    readonly id: string;
+    readonly predicates: ReadonlyArray<readonly [(input: unknown) => boolean | Promise<boolean>, ReadonlyArray<Step>]>;
+    readonly fallback?: ReadonlyArray<Step>;
+}
+/** Map a step over an upstream array output. */
+interface ForeachStep {
+    readonly kind: "foreach";
+    readonly id: string;
+    /** ID of an upstream top-level step whose output is iterable. */
+    readonly iterableFrom: string;
+    readonly step: Step;
+    readonly concurrency?: number;
+}
+/** Loop a step until condFn returns false. */
+interface DowhileStep {
+    readonly kind: "dowhile";
+    readonly id: string;
+    readonly step: Step;
+    readonly condFn: (output: unknown, iteration: number) => boolean | Promise<boolean>;
+    readonly maxIterations?: number;
+}
+/** Pause for a fixed duration. */
+interface SleepStep {
+    readonly kind: "sleep";
+    readonly id: string;
+    readonly durationMs: number;
+}
+/** Standalone explicit suspend point. */
+interface SuspendStep {
+    readonly kind: "suspend";
+    readonly id: string;
+    readonly payloadSchema?: ZodType;
+}
+/** D237 — retry policy applied per fn/agent step. */
+interface RetryPolicy {
+    /** Total attempts (MIN 1, MAX 20). `1` = no retry. */
+    readonly maxAttempts: number;
+    readonly initialBackoffMs?: number;
+    readonly backoffCoefficient?: number;
+    readonly maximumBackoffMs?: number;
+    readonly nonRetryableErrors?: ReadonlyArray<string>;
+}
+/** D247 — context handed to every step.fn. */
+interface StepContext {
+    readonly runId: string;
+    readonly signal: AbortSignal;
+    readonly log: {
+        debug: (msg: string, attrs?: Record<string, unknown>) => void;
+        info: (msg: string, attrs?: Record<string, unknown>) => void;
+        warn: (msg: string, attrs?: Record<string, unknown>) => void;
+    };
+    /** Pause the workflow; resume via `Workflow.resume({...})`. */
+    readonly suspend: (payload?: unknown) => Promise<never>;
+    /**
+     * SE29 — the workflow's shared state (from `WorkflowOptions.initialState`,
+     * mutated by {@link setState}), visible to every subsequent step in the run.
+     * `undefined` when no `initialState`/`setState` has run. Persisted across
+     * suspend/resume.
+     */
+    readonly state: unknown;
+    /**
+     * SE29 — update the shared state for subsequent steps. Validated against
+     * `WorkflowOptions.stateSchema` when set (a mismatch throws
+     * {@link WorkflowStateError}, which fails the step/run — Rule 8).
+     */
+    readonly setState: (next: unknown) => void;
+}
+interface StepResult {
+    readonly stepId: string;
+    readonly kind: Step["kind"];
+    readonly status: "completed" | "failed" | "skipped" | "suspended";
+    readonly attempts: number;
+    readonly durationMs: number;
+    readonly output?: unknown;
+    readonly error?: {
+        name: string;
+        message: string;
+    };
+}
+interface WorkflowRun<TOutput = unknown> {
+    readonly id: string;
+    readonly name: string;
+    readonly status: "running" | "completed" | "failed" | "suspended" | "cancelled";
+    readonly output?: TOutput;
+    readonly error?: {
+        name: string;
+        message: string;
+    };
+    readonly startedAt: number;
+    readonly endedAt?: number;
+    readonly stepResults: ReadonlyArray<StepResult>;
+}
+/**
+ * SE28 — a step-level workflow event emitted by `Workflow.stream()` as top-level
+ * steps run. Coarse-grained (one event per top-level step; nested
+ * parallel/branch/foreach emit as their single wrapping step), distinct from the
+ * token-delta agent stream. Discriminate on `type`.
+ *
+ * @public
+ */
+type WorkflowEvent = {
+    readonly type: "step_started";
+    readonly stepId: string;
+} | {
+    readonly type: "step_completed";
+    readonly stepId: string;
+    readonly output: unknown;
+} | {
+    readonly type: "step_failed";
+    readonly stepId: string;
+    readonly error: {
+        readonly name: string;
+        readonly message: string;
+    };
+} | {
+    readonly type: "workflow_suspended";
+    readonly stepId: string;
+} | {
+    readonly type: "workflow_completed";
+};
+/**
+ * SE28 — the async iterator returned by `Workflow.stream()`. Yields
+ * {@link WorkflowEvent}s in execution order; `result` resolves to the same
+ * terminal {@link WorkflowRun} the `run()` path returns (the authoritative
+ * outcome — the stream ends when the run terminates).
+ *
+ * @public
+ */
+type WorkflowStream<TOutput = unknown> = AsyncIterableIterator<WorkflowEvent> & {
+    readonly result: Promise<WorkflowRun<TOutput>>;
+};
+interface WorkflowPersistenceOptions {
+    readonly backend: "memory" | "json";
+    /** Required for `backend: "json"`. */
+    readonly dir?: string;
+}
+interface WorkflowOptions {
+    readonly name: string;
+    readonly persistence?: WorkflowPersistenceOptions;
+    /**
+     * SE27 — Zod schema for the WHOLE workflow's input. When set, `run(input)`
+     * validates `input` BEFORE step 1; a mismatch yields `status: "failed"` with a
+     * typed {@link WorkflowInputError} in `error` (fail-fast, no step runs, no
+     * silent coerce). Absent ⇒ no whole-workflow input validation (unchanged).
+     */
+    readonly inputSchema?: ZodType;
+    /**
+     * SE27 — Zod schema for the workflow's final output. When set, the terminal
+     * `completed` output is validated before `WorkflowRun.output` is populated; a
+     * mismatch yields `status: "failed"` with a typed {@link WorkflowOutputError}.
+     * Only validated on the `completed` path (suspended/failed runs skip it).
+     */
+    readonly outputSchema?: ZodType;
+    /**
+     * SE29 — Zod schema for the workflow's shared state (see `StepContext.state` /
+     * `setState`). When set, `initialState` and every `setState(next)` are
+     * validated against it (a mismatch throws {@link WorkflowStateError}). When
+     * `initialState` is absent, `state` starts as `undefined` and validation fires
+     * on the first `setState` call.
+     */
+    readonly stateSchema?: ZodType;
+    /**
+     * SE29 — the initial shared state, seeded onto `StepContext.state` before
+     * step 1. Validated against `stateSchema` when both are set. Persisted across
+     * suspend/resume.
+     */
+    readonly initialState?: unknown;
+    /** Internal — minted at `.commit()`. Not user-facing. */
+    readonly workflowId?: string;
+}
+interface WorkflowRunOptions {
+    readonly signal?: AbortSignal;
+    /** Override run ID for deterministic resume (advanced; default = mintRunId). */
+    readonly runId?: string;
+    /**
+     * Opt-in Task wrapping (ADRs D363, D374). Registers the workflow run
+     * as a `Task` (kind="workflow") with a `wf-` namespaced id (D368,
+     * EC-5). The task transitions terminal when `Workflow.run` resolves.
+     *
+     * Auto-id: `wf-{runId}`.
+     *
+     * @public
+     */
+    readonly task?: true | {
+        id?: string;
+        meta?: Record<string, unknown>;
+    };
+}
+interface WorkflowResumeOptions<TI = unknown> {
+    readonly runId: string;
+    readonly workflow: {
+        run: (input: TI, opts?: WorkflowRunOptions) => Promise<WorkflowRun>;
+    };
+    readonly payload?: unknown;
+    readonly signal?: AbortSignal;
+}
+
+/**
+ * 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
+ */
+
+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;
+}
+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>>;
+    /**
+     * 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: TInput, opts?: WorkflowRunOptions): WorkflowStream<TOutput>;
+    /**
+     * Resume a suspended workflow from its snapshot. Throws
+     * `WorkflowSnapshotNotFoundError` if `runId` is unknown.
+     */
+    static resume<TO = unknown>(opts: WorkflowResumeOptions): Promise<WorkflowRun<TO>>;
+}
+
 /**
  * Runtime hosting a cron job. Mirrors the agent runtime split.
  *
@@ -2019,11 +2466,12 @@ type CronRuntime = "local" | "cloud";
  */
 type CronJobStatus = "scheduled" | "running" | "paused" | "errored";
 /**
- * Persistent cron-scheduled invocation of the Theo agent.
+ * Persistent cron-scheduled invocation of the Theo agent or a workflow.
  *
- * Exactly one of {@link CronJob.agent} (ephemeral agent created on each fire)
- * or {@link CronJob.agentId} (bound to an existing agent for context
- * continuity) is set.
+ * Exactly one target is set: {@link CronJob.agent} (ephemeral agent created on
+ * each fire), {@link CronJob.agentId} (bound to an existing agent for context
+ * continuity), or {@link CronJob.workflow} (a committed workflow run per fire;
+ * SE35). Agent targets carry a `message`; a workflow target carries `inputData`.
  *
  * @public
  */
@@ -2034,17 +2482,25 @@ interface CronJob {
     cron: string;
     /** IANA timezone identifier. Defaults to `"UTC"`. */
     timezone?: string;
-    /** Message sent to the agent on each fire. */
-    message: string | SDKUserMessage;
-    /** Ephemeral agent options. Mutually exclusive with `agentId`. */
+    /** Message sent to the agent on each fire. Present for agent targets; absent for a workflow target. */
+    message?: string | SDKUserMessage;
+    /** Ephemeral agent options. Mutually exclusive with `agentId`/`workflow`. */
     agent?: AgentOptions;
-    /** ID of an existing agent to reuse for context continuity. Mutually exclusive with `agent`. */
+    /** ID of an existing agent to reuse for context continuity. Mutually exclusive with `agent`/`workflow`. */
     agentId?: string;
+    /**
+     * SE35 — a committed {@link Workflow} run on each fire (`workflow.run(inputData)`).
+     * Mutually exclusive with `agent`/`agentId`. Held in-memory (local runtime only —
+     * a workflow instance cannot cross the cloud process boundary). ADR 0014.
+     */
+    workflow?: Workflow;
+    /** SE35 — input passed to `workflow.run(inputData)` on each fire. Workflow targets only. */
+    inputData?: unknown;
     /** Whether the scheduler will fire this job on schedule. */
     enabled: boolean;
     /** Current status. */
     status: CronJobStatus;
-    /** Runtime that hosts this job. Inferred from `agent`/`agentId` at create time. */
+    /** Runtime that hosts this job. Inferred from `agent`/`agentId`/`workflow` at create time (a `workflow` target is always `local`). */
     runtime: CronRuntime;
     /** Unix ms of the last successful fire, if any. */
     lastRunAt?: number;
@@ -2056,17 +2512,24 @@ interface CronJob {
 /**
  * Options for `Cron.create()`.
  *
- * Pass `agent` for an ephemeral agent created fresh on each fire, OR
- * `agentId` to reuse an existing agent (preserves conversation context across
- * fires). Setting both is a `ConfigurationError`.
+ * Pass exactly ONE target: `agent` (ephemeral agent fresh per fire), `agentId`
+ * (reuse an existing agent — preserves conversation context), or `workflow`
+ * (SE35 — run a committed workflow per fire). Agent targets REQUIRE `message`;
+ * a workflow target takes `inputData` and MUST NOT set `message`. Violations are
+ * a `ConfigurationError`.
  *
  * @public
  */
 interface CronCreateOptions {
     cron: string;
-    message: string | SDKUserMessage;
+    /** Message for an agent target. Required with `agent`/`agentId`; forbidden with `workflow`. */
+    message?: string | SDKUserMessage;
     agent?: AgentOptions;
     agentId?: string;
+    /** SE35 — a committed {@link Workflow} to run per fire. Mutually exclusive with `agent`/`agentId`. */
+    workflow?: Workflow;
+    /** SE35 — input for `workflow.run(inputData)`. Workflow targets only. */
+    inputData?: unknown;
     name?: string;
     timezone?: string;
     /** Defaults to `true`. */
@@ -2194,11 +2657,12 @@ declare class Cron {
      */
     static disable(jobId: string, _options?: CronOperationOptions): Promise<CronJob>;
     /**
-     * Manually trigger a cron job off-schedule. Returns the resulting `Run`.
+     * Manually trigger a cron job off-schedule. Returns the resulting `Run`
+     * (agent target) or `WorkflowRun` (workflow target — SE35).
      *
      * @public
      */
-    static run(jobId: string, _options?: CronRunOptions): Promise<Run>;
+    static run(jobId: string, _options?: CronRunOptions): Promise<Run | WorkflowRun>;
     /**
      * Activate the in-process scheduler for local cron jobs.
      *
@@ -2219,4 +2683,4 @@ declare class Cron {
     static status(_options?: CronStartOptions): Promise<CronSchedulerStatus>;
 }
 
-export { type CronSchedulerStatus as $, type AgentOptions as A, type BudgetTracker as B, type CloudOptions as C, type BudgetUsageEvent as D, type CloudEnv as E, type CloudRepo as F, type GetAgentOptions as G, type ContextBudget as H, type InlineSkill as I, type ContextManagerKind as J, type ContextSnapshot as K, type LocalOptions as L, type MemorySettings as M, type ContextSource as N, type ContextSourceStatus as O, type ProviderRoutingSettings as P, type CreateSkillSpec as Q, Cron as R, type SystemPromptResolver as S, type CronCreateOptions as T, type CronGetOptions as U, type CronJob as V, type CronJobStatus as W, type CronListOptions as X, type CronOperationOptions as Y, type CronRunOptions as Z, type CronRuntime as _, type AgentDefinition as a, type CronStartOptions as a0, type GoalEvent as a1, type GoalOptions as a2, type GoalResult as a3, type HookName as a4, type InvalidateCacheOptions as a5, type MemoryAdapter as a6, type MemoryAdapterCapabilities as a7, type MemoryContext as a8, type MemoryFact as a9, type SystemPromptContext as aA, type SystemPromptMemoryFact as aB, type SystemPromptSkillRef as aC, type TelemetrySettings as aD, createSkill as aE, definePlugin as aF, type MemoryProviderHandle as aa, type MemoryProviderInitOptions as ab, type MemoryRevision as ac, type MemoryToolSchema as ad, type MemoryTurnMessage as ae, type PersonalityPreset as af, type PluginContext as ag, type PostAssistantReplyContext as ah, type PreToolCallContext as ai, type PreUserSendContext as aj, type PreUserSendResult as ak, type ProviderCapability as al, type ProviderRoute as am, type RecordSessionSummaryArgs as an, type ResolvedProviderRoute as ao, type RunUntilIterator as ap, type SDKAgentPlugins as aq, type SDKAgentSkillDetail as ar, type SDKAgentSkills as as, type SDKArtifact as at, type SDKContextManager as au, type SDKPluginMetadata as av, type SDKProvidersManager as aw, type SettingSource as ax, type SkillsResolver as ay, type SkillsResolverContext as az, type ContextSettings as b, type PluginsSettings as c, type SkillsSettings as d, type SDKAgent as e, type ListAgentsOptions as f, type ListResult as g, type SDKAgentInfo as h, type ListRunsOptions as i, type GetRunOptions as j, type AgentOperationOptions as k, type ProviderProfile as l, type Plugin as m, type ConversationStorageAdapter as n, type StoredMessage as o, type SessionMeta as p, type SessionMetaPatch as q, type MemoryProvider as r, type MemoryId as s, type PreToolCallDecision as t, type SDKProvider as u, type ActiveMemoryPassArgs as v, type ActiveMemoryPassResult as w, type AgentMemory as x, type BudgetCheck as y, type BudgetTotal as z };
+export { type CronOperationOptions as $, type AgentOptions as A, type BudgetTracker as B, type CloudOptions as C, type BudgetCheck as D, type BudgetTotal as E, type BudgetUsageEvent as F, type GetAgentOptions as G, type CloudEnv as H, type InlineSkill as I, type CloudRepo as J, type ContextBudget as K, type LocalOptions as L, type MemorySettings as M, type ContextManagerKind as N, type ObjectiveRecord as O, type ProviderRoutingSettings as P, type ContextSnapshot as Q, type ContextSource as R, type SystemPromptResolver as S, type ContextSourceStatus as T, type CreateSkillSpec as U, Cron as V, type CronCreateOptions as W, type CronGetOptions as X, type CronJob as Y, type CronJobStatus as Z, type CronListOptions as _, type AgentDefinition as a, type CronRunOptions as a0, type CronRuntime as a1, type CronSchedulerStatus as a2, type CronStartOptions as a3, type DurableGoalOptions as a4, type GoalEvent as a5, type GoalOptions as a6, type GoalResult as a7, type HookName as a8, type InvalidateCacheOptions as a9, type SDKPluginMetadata as aA, type SDKProvidersManager as aB, type SettingSource as aC, type SkillsResolver as aD, type SkillsResolverContext as aE, type SystemPromptContext as aF, type SystemPromptMemoryFact as aG, type SystemPromptSkillRef as aH, type TelemetrySettings as aI, createSkill as aJ, definePlugin as aK, type MemoryAdapter as aa, type MemoryAdapterCapabilities as ab, type MemoryContext as ac, type MemoryFact as ad, type MemoryProviderHandle as ae, type MemoryProviderInitOptions as af, type MemoryRevision as ag, type MemoryToolSchema as ah, type MemoryTurnMessage as ai, type ObjectiveStatus as aj, type PersonalityPreset as ak, type PluginContext as al, type PostAssistantReplyContext as am, type PreToolCallContext as an, type PreUserSendContext as ao, type PreUserSendResult as ap, type ProviderCapability as aq, type ProviderRoute as ar, type RecordSessionSummaryArgs as as, type ResolvedProviderRoute as at, type RunUntilIterator as au, type SDKAgentPlugins as av, type SDKAgentSkillDetail as aw, type SDKAgentSkills as ax, type SDKArtifact as ay, type SDKContextManager as az, type ContextSettings as b, type PluginsSettings as c, type SkillsSettings as d, type SDKAgent as e, type ListAgentsOptions as f, type ListResult as g, type SDKAgentInfo as h, type ListRunsOptions as i, type GetRunOptions as j, type AgentOperationOptions as k, type ProviderProfile as l, type Plugin as m, type ConversationStorageAdapter as n, type StoredMessage as o, type SessionMeta as p, type SessionMetaPatch as q, type MemoryProvider as r, type MemoryId as s, type PreToolCallDecision as t, type StepResult as u, type SDKProvider as v, type ActiveMemoryPassArgs as w, type ActiveMemoryPassResult as x, type AgentGoalConfig as y, type AgentMemory as z };