@theokit/sdk 2.29.0 → 3.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +20 -0
- package/dist/a2a/index.cjs +8 -1
- package/dist/a2a/index.cjs.map +1 -1
- package/dist/a2a/index.d.cts +1 -1
- package/dist/a2a/index.d.ts +1 -1
- package/dist/a2a/index.js +8 -1
- package/dist/a2a/index.js.map +1 -1
- package/dist/a2a/subagent.d.cts +5 -1
- package/dist/a2a/subagent.d.ts +5 -1
- package/dist/agent-factory.d.ts +5 -20
- package/dist/concurrency.cjs +10 -1
- package/dist/concurrency.cjs.map +1 -1
- package/dist/concurrency.d.cts +7 -1
- package/dist/concurrency.d.ts +7 -1
- package/dist/concurrency.js +10 -1
- package/dist/concurrency.js.map +1 -1
- package/dist/create-skill.d.ts +7 -7
- package/dist/{cron-COSAehOL.d.ts → cron-BLRe166v.d.ts} +392 -31
- package/dist/{cron-yJoNUZxe.d.cts → cron-C2jWAvlQ.d.cts} +392 -31
- package/dist/cron.cjs +89 -44
- package/dist/cron.cjs.map +1 -1
- package/dist/cron.d.cts +2 -2
- package/dist/cron.d.ts +2 -2
- package/dist/cron.js +89 -44
- package/dist/cron.js.map +1 -1
- package/dist/define-tool.d.ts +12 -1
- package/dist/{errors-tP-8O-hR.d.cts → errors-DZpCGlYv.d.cts} +1 -1
- package/dist/{errors-BxMIlgLP.d.ts → errors-D_Bfo30u.d.ts} +1 -1
- package/dist/errors.d.cts +2 -2
- package/dist/index.cjs +179 -56
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +64 -246
- package/dist/index.d.ts +64 -246
- package/dist/index.js +168 -45
- package/dist/index.js.map +1 -1
- package/dist/internal/plugins/index.d.cts +1 -1
- package/dist/internal/plugins/index.d.ts +1 -1
- package/dist/internal/plugins/types.d.cts +4 -0
- package/dist/internal/plugins/types.d.ts +4 -0
- package/dist/retry.cjs +10 -1
- package/dist/retry.cjs.map +1 -1
- package/dist/retry.d.cts +12 -1
- package/dist/retry.d.ts +12 -1
- package/dist/retry.js +10 -1
- package/dist/retry.js.map +1 -1
- package/dist/{run-q_P0vHlY.d.cts → run-CLXKMRgq.d.cts} +1 -1
- package/dist/{run-q_P0vHlY.d.ts → run-CLXKMRgq.d.ts} +1 -1
- package/dist/server/auth/index.cjs +8 -1
- package/dist/server/auth/index.cjs.map +1 -1
- package/dist/server/auth/index.d.cts +1 -1
- package/dist/server/auth/index.d.ts +1 -1
- package/dist/server/auth/index.js +8 -1
- package/dist/server/auth/index.js.map +1 -1
- package/dist/server/auth/orchestrator.d.cts +5 -1
- package/dist/server/auth/orchestrator.d.ts +5 -1
- package/dist/subscription/define-subscription.d.cts +5 -0
- package/dist/subscription/define-subscription.d.ts +5 -0
- package/dist/subscription/index.cjs +8 -1
- package/dist/subscription/index.cjs.map +1 -1
- package/dist/subscription/index.d.cts +1 -1
- package/dist/subscription/index.d.ts +1 -1
- package/dist/subscription/index.js +8 -1
- package/dist/subscription/index.js.map +1 -1
- package/dist/types/cron.d.ts +30 -13
- package/package.json +1 -1
|
@@ -1,5 +1,6 @@
|
|
|
1
|
-
import { C as CustomTool, M as ModelSelection, a7 as SDKUserMessage, a9 as SendOptions, b as Run, G as GenerateOptions, l as GenerateRunResult, V as RunToCompletionOptions, W as RunToCompletionResult, S as SDKMessage, ag as StreamToCompletionResult, a as McpServerConfig, P as Processor } from './run-q_P0vHlY.cjs';
|
|
2
1
|
import * as zod from 'zod';
|
|
2
|
+
import { ZodType } from 'zod';
|
|
3
|
+
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.cjs';
|
|
3
4
|
|
|
4
5
|
/**
|
|
5
6
|
* Fork primitive public type contracts (T1.2, ADRs D110-D114).
|
|
@@ -803,7 +804,7 @@ interface ConversationStorageAdapter {
|
|
|
803
804
|
*
|
|
804
805
|
* @public
|
|
805
806
|
*/
|
|
806
|
-
interface Skill {
|
|
807
|
+
interface Skill$1 {
|
|
807
808
|
name: string;
|
|
808
809
|
description: string;
|
|
809
810
|
/** Absolute path to the discovered `SKILL.md`. */
|
|
@@ -824,7 +825,7 @@ interface Skill {
|
|
|
824
825
|
*/
|
|
825
826
|
|
|
826
827
|
/** A code-defined skill (from {@link createSkill}) — a {@link Skill} plus its inline body. */
|
|
827
|
-
interface InlineSkill extends Skill {
|
|
828
|
+
interface InlineSkill extends Skill$1 {
|
|
828
829
|
/** The skill body/instructions (inline skills carry it here instead of a SKILL.md file). */
|
|
829
830
|
instructions: string;
|
|
830
831
|
/**
|
|
@@ -844,11 +845,11 @@ interface CreateSkillSpec {
|
|
|
844
845
|
/** SE21 — supporting documents (filename → content), like a filesystem skill's `references/`. */
|
|
845
846
|
references?: Record<string, string>;
|
|
846
847
|
}
|
|
847
|
-
/**
|
|
848
|
-
|
|
849
|
-
|
|
850
|
-
|
|
851
|
-
|
|
848
|
+
/** SE36 — `Skill.create` replaces `createSkill` (ADR 0015). @public */
|
|
849
|
+
declare class Skill {
|
|
850
|
+
private constructor();
|
|
851
|
+
static create(spec: CreateSkillSpec): InlineSkill;
|
|
852
|
+
}
|
|
852
853
|
|
|
853
854
|
/**
|
|
854
855
|
* Context manager backend.
|
|
@@ -1161,6 +1162,13 @@ interface BasePlugin {
|
|
|
1161
1162
|
name: string;
|
|
1162
1163
|
version: string;
|
|
1163
1164
|
}
|
|
1165
|
+
/**
|
|
1166
|
+
* Identity helper for plugin authors. TS-only convenience — preserves
|
|
1167
|
+
* inferred type without forcing manual `Plugin` annotation.
|
|
1168
|
+
*
|
|
1169
|
+
* @public
|
|
1170
|
+
*/
|
|
1171
|
+
declare function definePlugin<P extends Plugin>(p: P): P;
|
|
1164
1172
|
type Plugin = (BasePlugin & {
|
|
1165
1173
|
kind: "general";
|
|
1166
1174
|
register: (ctx: PluginContext) => void | Promise<void>;
|
|
@@ -1171,13 +1179,10 @@ type Plugin = (BasePlugin & {
|
|
|
1171
1179
|
kind: "memory";
|
|
1172
1180
|
createProvider: MemoryProviderFactory;
|
|
1173
1181
|
});
|
|
1174
|
-
/**
|
|
1175
|
-
|
|
1176
|
-
|
|
1177
|
-
|
|
1178
|
-
* @public
|
|
1179
|
-
*/
|
|
1180
|
-
declare function definePlugin<P extends Plugin>(p: P): P;
|
|
1182
|
+
/** SE36 — `Plugin.create` replaces `definePlugin` (ADR 0015). Const-companion (the `Plugin` type alias blocks a class of the same name); `create` is the generic `definePlugin`. @public */
|
|
1183
|
+
declare const Plugin: {
|
|
1184
|
+
create: typeof definePlugin;
|
|
1185
|
+
};
|
|
1181
1186
|
|
|
1182
1187
|
/**
|
|
1183
1188
|
* Which on-disk settings layers a local agent loads.
|
|
@@ -2108,6 +2113,345 @@ interface ListResult<T> {
|
|
|
2108
2113
|
nextCursor?: string;
|
|
2109
2114
|
}
|
|
2110
2115
|
|
|
2116
|
+
/**
|
|
2117
|
+
* Public type contract for `Workflow.create / .run / .resume` (Adoption
|
|
2118
|
+
* Roadmap #5; ADRs D230-D248).
|
|
2119
|
+
*
|
|
2120
|
+
* Step types form a discriminated union by `kind`. Helper factory functions
|
|
2121
|
+
* (`fn()`, `agentStep()`) live in `workflow.ts` and hide the discriminator
|
|
2122
|
+
* from end users.
|
|
2123
|
+
*
|
|
2124
|
+
* @public
|
|
2125
|
+
*/
|
|
2126
|
+
|
|
2127
|
+
type Step = FnStep | AgentStep | ParallelStep | BranchStep | ForeachStep | DowhileStep | SleepStep | SuspendStep;
|
|
2128
|
+
/** A pure function step. */
|
|
2129
|
+
interface FnStep {
|
|
2130
|
+
readonly kind: "fn";
|
|
2131
|
+
readonly id: string;
|
|
2132
|
+
readonly fn: (input: unknown, ctx: StepContext) => Promise<unknown> | unknown;
|
|
2133
|
+
readonly inputSchema?: ZodType;
|
|
2134
|
+
readonly outputSchema?: ZodType;
|
|
2135
|
+
readonly retry?: RetryPolicy;
|
|
2136
|
+
/** D238 — slot reserved; runtime throws if engine not yet implemented. */
|
|
2137
|
+
readonly compensate?: (input: unknown, output: unknown, error: Error) => Promise<void> | void;
|
|
2138
|
+
}
|
|
2139
|
+
/** An agent.send-driven step. */
|
|
2140
|
+
interface AgentStep {
|
|
2141
|
+
readonly kind: "agent";
|
|
2142
|
+
readonly id: string;
|
|
2143
|
+
readonly agent: SDKAgent;
|
|
2144
|
+
readonly promptTemplate: string | ((input: unknown) => string);
|
|
2145
|
+
readonly retry?: RetryPolicy;
|
|
2146
|
+
/**
|
|
2147
|
+
* SE3 — provenance stamped onto this step's `agent.send()` (forwarded to
|
|
2148
|
+
* `RunResult.origin`). Squad sets `{ kind: "peer", from: "agent-<i-1>" }` on
|
|
2149
|
+
* every step after the first so a peer-driven turn is attributable.
|
|
2150
|
+
*/
|
|
2151
|
+
readonly origin?: MessageOrigin;
|
|
2152
|
+
}
|
|
2153
|
+
/** N concurrent branches, each its own mini-step-list. */
|
|
2154
|
+
interface ParallelStep {
|
|
2155
|
+
readonly kind: "parallel";
|
|
2156
|
+
readonly id: string;
|
|
2157
|
+
readonly branches: ReadonlyArray<ReadonlyArray<Step>>;
|
|
2158
|
+
readonly concurrency?: number;
|
|
2159
|
+
readonly errorPolicy?: "fail-fast" | "collect";
|
|
2160
|
+
}
|
|
2161
|
+
/** First-match-wins predicates + optional fallback. */
|
|
2162
|
+
interface BranchStep {
|
|
2163
|
+
readonly kind: "branch";
|
|
2164
|
+
readonly id: string;
|
|
2165
|
+
readonly predicates: ReadonlyArray<readonly [(input: unknown) => boolean | Promise<boolean>, ReadonlyArray<Step>]>;
|
|
2166
|
+
readonly fallback?: ReadonlyArray<Step>;
|
|
2167
|
+
}
|
|
2168
|
+
/** Map a step over an upstream array output. */
|
|
2169
|
+
interface ForeachStep {
|
|
2170
|
+
readonly kind: "foreach";
|
|
2171
|
+
readonly id: string;
|
|
2172
|
+
/** ID of an upstream top-level step whose output is iterable. */
|
|
2173
|
+
readonly iterableFrom: string;
|
|
2174
|
+
readonly step: Step;
|
|
2175
|
+
readonly concurrency?: number;
|
|
2176
|
+
}
|
|
2177
|
+
/** Loop a step until condFn returns false. */
|
|
2178
|
+
interface DowhileStep {
|
|
2179
|
+
readonly kind: "dowhile";
|
|
2180
|
+
readonly id: string;
|
|
2181
|
+
readonly step: Step;
|
|
2182
|
+
readonly condFn: (output: unknown, iteration: number) => boolean | Promise<boolean>;
|
|
2183
|
+
readonly maxIterations?: number;
|
|
2184
|
+
}
|
|
2185
|
+
/** Pause for a fixed duration. */
|
|
2186
|
+
interface SleepStep {
|
|
2187
|
+
readonly kind: "sleep";
|
|
2188
|
+
readonly id: string;
|
|
2189
|
+
readonly durationMs: number;
|
|
2190
|
+
}
|
|
2191
|
+
/** Standalone explicit suspend point. */
|
|
2192
|
+
interface SuspendStep {
|
|
2193
|
+
readonly kind: "suspend";
|
|
2194
|
+
readonly id: string;
|
|
2195
|
+
readonly payloadSchema?: ZodType;
|
|
2196
|
+
}
|
|
2197
|
+
/** D237 — retry policy applied per fn/agent step. */
|
|
2198
|
+
interface RetryPolicy {
|
|
2199
|
+
/** Total attempts (MIN 1, MAX 20). `1` = no retry. */
|
|
2200
|
+
readonly maxAttempts: number;
|
|
2201
|
+
readonly initialBackoffMs?: number;
|
|
2202
|
+
readonly backoffCoefficient?: number;
|
|
2203
|
+
readonly maximumBackoffMs?: number;
|
|
2204
|
+
readonly nonRetryableErrors?: ReadonlyArray<string>;
|
|
2205
|
+
}
|
|
2206
|
+
/** D247 — context handed to every step.fn. */
|
|
2207
|
+
interface StepContext {
|
|
2208
|
+
readonly runId: string;
|
|
2209
|
+
readonly signal: AbortSignal;
|
|
2210
|
+
readonly log: {
|
|
2211
|
+
debug: (msg: string, attrs?: Record<string, unknown>) => void;
|
|
2212
|
+
info: (msg: string, attrs?: Record<string, unknown>) => void;
|
|
2213
|
+
warn: (msg: string, attrs?: Record<string, unknown>) => void;
|
|
2214
|
+
};
|
|
2215
|
+
/** Pause the workflow; resume via `Workflow.resume({...})`. */
|
|
2216
|
+
readonly suspend: (payload?: unknown) => Promise<never>;
|
|
2217
|
+
/**
|
|
2218
|
+
* SE29 — the workflow's shared state (from `WorkflowOptions.initialState`,
|
|
2219
|
+
* mutated by {@link setState}), visible to every subsequent step in the run.
|
|
2220
|
+
* `undefined` when no `initialState`/`setState` has run. Persisted across
|
|
2221
|
+
* suspend/resume.
|
|
2222
|
+
*/
|
|
2223
|
+
readonly state: unknown;
|
|
2224
|
+
/**
|
|
2225
|
+
* SE29 — update the shared state for subsequent steps. Validated against
|
|
2226
|
+
* `WorkflowOptions.stateSchema` when set (a mismatch throws
|
|
2227
|
+
* {@link WorkflowStateError}, which fails the step/run — Rule 8).
|
|
2228
|
+
*/
|
|
2229
|
+
readonly setState: (next: unknown) => void;
|
|
2230
|
+
}
|
|
2231
|
+
interface StepResult {
|
|
2232
|
+
readonly stepId: string;
|
|
2233
|
+
readonly kind: Step["kind"];
|
|
2234
|
+
readonly status: "completed" | "failed" | "skipped" | "suspended";
|
|
2235
|
+
readonly attempts: number;
|
|
2236
|
+
readonly durationMs: number;
|
|
2237
|
+
readonly output?: unknown;
|
|
2238
|
+
readonly error?: {
|
|
2239
|
+
name: string;
|
|
2240
|
+
message: string;
|
|
2241
|
+
};
|
|
2242
|
+
}
|
|
2243
|
+
interface WorkflowRun<TOutput = unknown> {
|
|
2244
|
+
readonly id: string;
|
|
2245
|
+
readonly name: string;
|
|
2246
|
+
readonly status: "running" | "completed" | "failed" | "suspended" | "cancelled";
|
|
2247
|
+
readonly output?: TOutput;
|
|
2248
|
+
readonly error?: {
|
|
2249
|
+
name: string;
|
|
2250
|
+
message: string;
|
|
2251
|
+
};
|
|
2252
|
+
readonly startedAt: number;
|
|
2253
|
+
readonly endedAt?: number;
|
|
2254
|
+
readonly stepResults: ReadonlyArray<StepResult>;
|
|
2255
|
+
}
|
|
2256
|
+
/**
|
|
2257
|
+
* SE28 — a step-level workflow event emitted by `Workflow.stream()` as top-level
|
|
2258
|
+
* steps run. Coarse-grained (one event per top-level step; nested
|
|
2259
|
+
* parallel/branch/foreach emit as their single wrapping step), distinct from the
|
|
2260
|
+
* token-delta agent stream. Discriminate on `type`.
|
|
2261
|
+
*
|
|
2262
|
+
* @public
|
|
2263
|
+
*/
|
|
2264
|
+
type WorkflowEvent = {
|
|
2265
|
+
readonly type: "step_started";
|
|
2266
|
+
readonly stepId: string;
|
|
2267
|
+
} | {
|
|
2268
|
+
readonly type: "step_completed";
|
|
2269
|
+
readonly stepId: string;
|
|
2270
|
+
readonly output: unknown;
|
|
2271
|
+
} | {
|
|
2272
|
+
readonly type: "step_failed";
|
|
2273
|
+
readonly stepId: string;
|
|
2274
|
+
readonly error: {
|
|
2275
|
+
readonly name: string;
|
|
2276
|
+
readonly message: string;
|
|
2277
|
+
};
|
|
2278
|
+
} | {
|
|
2279
|
+
readonly type: "workflow_suspended";
|
|
2280
|
+
readonly stepId: string;
|
|
2281
|
+
} | {
|
|
2282
|
+
readonly type: "workflow_completed";
|
|
2283
|
+
};
|
|
2284
|
+
/**
|
|
2285
|
+
* SE28 — the async iterator returned by `Workflow.stream()`. Yields
|
|
2286
|
+
* {@link WorkflowEvent}s in execution order; `result` resolves to the same
|
|
2287
|
+
* terminal {@link WorkflowRun} the `run()` path returns (the authoritative
|
|
2288
|
+
* outcome — the stream ends when the run terminates).
|
|
2289
|
+
*
|
|
2290
|
+
* @public
|
|
2291
|
+
*/
|
|
2292
|
+
type WorkflowStream<TOutput = unknown> = AsyncIterableIterator<WorkflowEvent> & {
|
|
2293
|
+
readonly result: Promise<WorkflowRun<TOutput>>;
|
|
2294
|
+
};
|
|
2295
|
+
interface WorkflowPersistenceOptions {
|
|
2296
|
+
readonly backend: "memory" | "json";
|
|
2297
|
+
/** Required for `backend: "json"`. */
|
|
2298
|
+
readonly dir?: string;
|
|
2299
|
+
}
|
|
2300
|
+
interface WorkflowOptions {
|
|
2301
|
+
readonly name: string;
|
|
2302
|
+
readonly persistence?: WorkflowPersistenceOptions;
|
|
2303
|
+
/**
|
|
2304
|
+
* SE27 — Zod schema for the WHOLE workflow's input. When set, `run(input)`
|
|
2305
|
+
* validates `input` BEFORE step 1; a mismatch yields `status: "failed"` with a
|
|
2306
|
+
* typed {@link WorkflowInputError} in `error` (fail-fast, no step runs, no
|
|
2307
|
+
* silent coerce). Absent ⇒ no whole-workflow input validation (unchanged).
|
|
2308
|
+
*/
|
|
2309
|
+
readonly inputSchema?: ZodType;
|
|
2310
|
+
/**
|
|
2311
|
+
* SE27 — Zod schema for the workflow's final output. When set, the terminal
|
|
2312
|
+
* `completed` output is validated before `WorkflowRun.output` is populated; a
|
|
2313
|
+
* mismatch yields `status: "failed"` with a typed {@link WorkflowOutputError}.
|
|
2314
|
+
* Only validated on the `completed` path (suspended/failed runs skip it).
|
|
2315
|
+
*/
|
|
2316
|
+
readonly outputSchema?: ZodType;
|
|
2317
|
+
/**
|
|
2318
|
+
* SE29 — Zod schema for the workflow's shared state (see `StepContext.state` /
|
|
2319
|
+
* `setState`). When set, `initialState` and every `setState(next)` are
|
|
2320
|
+
* validated against it (a mismatch throws {@link WorkflowStateError}). When
|
|
2321
|
+
* `initialState` is absent, `state` starts as `undefined` and validation fires
|
|
2322
|
+
* on the first `setState` call.
|
|
2323
|
+
*/
|
|
2324
|
+
readonly stateSchema?: ZodType;
|
|
2325
|
+
/**
|
|
2326
|
+
* SE29 — the initial shared state, seeded onto `StepContext.state` before
|
|
2327
|
+
* step 1. Validated against `stateSchema` when both are set. Persisted across
|
|
2328
|
+
* suspend/resume.
|
|
2329
|
+
*/
|
|
2330
|
+
readonly initialState?: unknown;
|
|
2331
|
+
/** Internal — minted at `.commit()`. Not user-facing. */
|
|
2332
|
+
readonly workflowId?: string;
|
|
2333
|
+
}
|
|
2334
|
+
interface WorkflowRunOptions {
|
|
2335
|
+
readonly signal?: AbortSignal;
|
|
2336
|
+
/** Override run ID for deterministic resume (advanced; default = mintRunId). */
|
|
2337
|
+
readonly runId?: string;
|
|
2338
|
+
/**
|
|
2339
|
+
* Opt-in Task wrapping (ADRs D363, D374). Registers the workflow run
|
|
2340
|
+
* as a `Task` (kind="workflow") with a `wf-` namespaced id (D368,
|
|
2341
|
+
* EC-5). The task transitions terminal when `Workflow.run` resolves.
|
|
2342
|
+
*
|
|
2343
|
+
* Auto-id: `wf-{runId}`.
|
|
2344
|
+
*
|
|
2345
|
+
* @public
|
|
2346
|
+
*/
|
|
2347
|
+
readonly task?: true | {
|
|
2348
|
+
id?: string;
|
|
2349
|
+
meta?: Record<string, unknown>;
|
|
2350
|
+
};
|
|
2351
|
+
}
|
|
2352
|
+
interface WorkflowResumeOptions<TI = unknown> {
|
|
2353
|
+
readonly runId: string;
|
|
2354
|
+
readonly workflow: {
|
|
2355
|
+
run: (input: TI, opts?: WorkflowRunOptions) => Promise<WorkflowRun>;
|
|
2356
|
+
};
|
|
2357
|
+
readonly payload?: unknown;
|
|
2358
|
+
readonly signal?: AbortSignal;
|
|
2359
|
+
}
|
|
2360
|
+
|
|
2361
|
+
/**
|
|
2362
|
+
* Public `Workflow` class — declarative multi-step orchestration over
|
|
2363
|
+
* `Agent.send`, `Handoff`, `Agent.batch` and friends (Adoption Roadmap #5;
|
|
2364
|
+
* ADRs D230-D248).
|
|
2365
|
+
*
|
|
2366
|
+
* Usage:
|
|
2367
|
+
*
|
|
2368
|
+
* import { Agent } from "@theokit/sdk";
|
|
2369
|
+
* import { Workflow, fn, agentStep } from "@theokit/sdk/workflow";
|
|
2370
|
+
*
|
|
2371
|
+
* const classifier = await Agent.create({ ... });
|
|
2372
|
+
* const wf = Workflow.create({ name: "demo" })
|
|
2373
|
+
* .then(fn("validate", (input: { id: string }) => {
|
|
2374
|
+
* if (!input.id) throw new Error("missing id");
|
|
2375
|
+
* return input;
|
|
2376
|
+
* }))
|
|
2377
|
+
* .then(agentStep("classify", classifier, (i) => `Classify: ${JSON.stringify(i)}`))
|
|
2378
|
+
* .commit();
|
|
2379
|
+
*
|
|
2380
|
+
* const run = await wf.run({ id: "x" });
|
|
2381
|
+
* console.log(run.status, run.output);
|
|
2382
|
+
*
|
|
2383
|
+
* @public
|
|
2384
|
+
*/
|
|
2385
|
+
|
|
2386
|
+
declare class WorkflowBuilder<TInput = unknown, TOutput = unknown> {
|
|
2387
|
+
private readonly options;
|
|
2388
|
+
private readonly _steps;
|
|
2389
|
+
private _committed;
|
|
2390
|
+
then<TO = unknown>(step: Step): WorkflowBuilder<TInput, TO>;
|
|
2391
|
+
parallel(branches: ReadonlyArray<ReadonlyArray<Step>>, opts?: {
|
|
2392
|
+
id?: string;
|
|
2393
|
+
concurrency?: number;
|
|
2394
|
+
errorPolicy?: "fail-fast" | "collect";
|
|
2395
|
+
}): WorkflowBuilder<TInput, unknown[]>;
|
|
2396
|
+
branch(predicates: BranchStep["predicates"], opts?: {
|
|
2397
|
+
id?: string;
|
|
2398
|
+
fallback?: ReadonlyArray<Step>;
|
|
2399
|
+
}): WorkflowBuilder<TInput, unknown>;
|
|
2400
|
+
foreach(iterableFrom: string, step: Step, opts?: {
|
|
2401
|
+
id?: string;
|
|
2402
|
+
concurrency?: number;
|
|
2403
|
+
}): WorkflowBuilder<TInput, unknown[]>;
|
|
2404
|
+
dowhile(step: Step, condFn: DowhileStep["condFn"], opts?: {
|
|
2405
|
+
id?: string;
|
|
2406
|
+
maxIterations?: number;
|
|
2407
|
+
}): WorkflowBuilder<TInput, unknown>;
|
|
2408
|
+
sleep(durationMs: number, id?: string): WorkflowBuilder<TInput, TOutput>;
|
|
2409
|
+
suspend(opts?: {
|
|
2410
|
+
id?: string;
|
|
2411
|
+
payloadSchema?: ZodType;
|
|
2412
|
+
}): WorkflowBuilder<TInput, unknown>;
|
|
2413
|
+
commit(): Workflow<TInput, TOutput>;
|
|
2414
|
+
private validateUniqueIds;
|
|
2415
|
+
private assertNotCommitted;
|
|
2416
|
+
}
|
|
2417
|
+
declare class Workflow<TInput = unknown, TOutput = unknown> {
|
|
2418
|
+
private readonly _options;
|
|
2419
|
+
private readonly _steps;
|
|
2420
|
+
/**
|
|
2421
|
+
* Construct a workflow builder. Validate options via Zod and return a
|
|
2422
|
+
* `WorkflowBuilder` for fluent chaining. Call `.commit()` to obtain the
|
|
2423
|
+
* immutable `Workflow`.
|
|
2424
|
+
*/
|
|
2425
|
+
static create<TI = unknown, TO = unknown>(options: WorkflowOptions): WorkflowBuilder<TI, TO>;
|
|
2426
|
+
/**
|
|
2427
|
+
* Run this workflow with the given input. Returns a populated
|
|
2428
|
+
* `WorkflowRun`. Errors inside a step DO NOT throw — they propagate via
|
|
2429
|
+
* `run.status === "failed"`.
|
|
2430
|
+
*/
|
|
2431
|
+
run(input: TInput, opts?: WorkflowRunOptions): Promise<WorkflowRun<TOutput>>;
|
|
2432
|
+
/**
|
|
2433
|
+
* SE28 — run the workflow and STREAM step-level events as they happen. Returns
|
|
2434
|
+
* an async iterator of {@link WorkflowEvent}s (`step_started` / `step_completed`
|
|
2435
|
+
* / `step_failed` / `workflow_suspended` / `workflow_completed`, top-level
|
|
2436
|
+
* steps) plus a `result` promise resolving to the same terminal
|
|
2437
|
+
* {@link WorkflowRun} `run()` returns. Iterate for progress; await `result` for
|
|
2438
|
+
* the outcome. The stream ends when the run terminates.
|
|
2439
|
+
*
|
|
2440
|
+
* `result` is the AUTHORITATIVE terminal status. Not every terminal state has a
|
|
2441
|
+
* closing event: a step failure emits `step_failed`, but an `outputSchema`
|
|
2442
|
+
* rejection (SE27) or an abort ends the stream WITHOUT `workflow_completed` —
|
|
2443
|
+
* always `await result` to read the final `status`. Consuming order is free:
|
|
2444
|
+
* awaiting `result` without draining, or draining without awaiting `result`,
|
|
2445
|
+
* both work (breaking out of `for await` stops the buffering early).
|
|
2446
|
+
*/
|
|
2447
|
+
stream(input: TInput, opts?: WorkflowRunOptions): WorkflowStream<TOutput>;
|
|
2448
|
+
/**
|
|
2449
|
+
* Resume a suspended workflow from its snapshot. Throws
|
|
2450
|
+
* `WorkflowSnapshotNotFoundError` if `runId` is unknown.
|
|
2451
|
+
*/
|
|
2452
|
+
static resume<TO = unknown>(opts: WorkflowResumeOptions): Promise<WorkflowRun<TO>>;
|
|
2453
|
+
}
|
|
2454
|
+
|
|
2111
2455
|
/**
|
|
2112
2456
|
* Runtime hosting a cron job. Mirrors the agent runtime split.
|
|
2113
2457
|
*
|
|
@@ -2126,11 +2470,12 @@ type CronRuntime = "local" | "cloud";
|
|
|
2126
2470
|
*/
|
|
2127
2471
|
type CronJobStatus = "scheduled" | "running" | "paused" | "errored";
|
|
2128
2472
|
/**
|
|
2129
|
-
* Persistent cron-scheduled invocation of the Theo agent.
|
|
2473
|
+
* Persistent cron-scheduled invocation of the Theo agent or a workflow.
|
|
2130
2474
|
*
|
|
2131
|
-
* Exactly one
|
|
2132
|
-
*
|
|
2133
|
-
* continuity)
|
|
2475
|
+
* Exactly one target is set: {@link CronJob.agent} (ephemeral agent created on
|
|
2476
|
+
* each fire), {@link CronJob.agentId} (bound to an existing agent for context
|
|
2477
|
+
* continuity), or {@link CronJob.workflow} (a committed workflow run per fire;
|
|
2478
|
+
* SE35). Agent targets carry a `message`; a workflow target carries `inputData`.
|
|
2134
2479
|
*
|
|
2135
2480
|
* @public
|
|
2136
2481
|
*/
|
|
@@ -2141,17 +2486,25 @@ interface CronJob {
|
|
|
2141
2486
|
cron: string;
|
|
2142
2487
|
/** IANA timezone identifier. Defaults to `"UTC"`. */
|
|
2143
2488
|
timezone?: string;
|
|
2144
|
-
/** Message sent to the agent on each fire. */
|
|
2145
|
-
message
|
|
2146
|
-
/** Ephemeral agent options. Mutually exclusive with `agentId`. */
|
|
2489
|
+
/** Message sent to the agent on each fire. Present for agent targets; absent for a workflow target. */
|
|
2490
|
+
message?: string | SDKUserMessage;
|
|
2491
|
+
/** Ephemeral agent options. Mutually exclusive with `agentId`/`workflow`. */
|
|
2147
2492
|
agent?: AgentOptions;
|
|
2148
|
-
/** ID of an existing agent to reuse for context continuity. Mutually exclusive with `agent`. */
|
|
2493
|
+
/** ID of an existing agent to reuse for context continuity. Mutually exclusive with `agent`/`workflow`. */
|
|
2149
2494
|
agentId?: string;
|
|
2495
|
+
/**
|
|
2496
|
+
* SE35 — a committed {@link Workflow} run on each fire (`workflow.run(inputData)`).
|
|
2497
|
+
* Mutually exclusive with `agent`/`agentId`. Held in-memory (local runtime only —
|
|
2498
|
+
* a workflow instance cannot cross the cloud process boundary). ADR 0014.
|
|
2499
|
+
*/
|
|
2500
|
+
workflow?: Workflow;
|
|
2501
|
+
/** SE35 — input passed to `workflow.run(inputData)` on each fire. Workflow targets only. */
|
|
2502
|
+
inputData?: unknown;
|
|
2150
2503
|
/** Whether the scheduler will fire this job on schedule. */
|
|
2151
2504
|
enabled: boolean;
|
|
2152
2505
|
/** Current status. */
|
|
2153
2506
|
status: CronJobStatus;
|
|
2154
|
-
/** Runtime that hosts this job. Inferred from `agent`/`agentId` at create time. */
|
|
2507
|
+
/** Runtime that hosts this job. Inferred from `agent`/`agentId`/`workflow` at create time (a `workflow` target is always `local`). */
|
|
2155
2508
|
runtime: CronRuntime;
|
|
2156
2509
|
/** Unix ms of the last successful fire, if any. */
|
|
2157
2510
|
lastRunAt?: number;
|
|
@@ -2163,17 +2516,24 @@ interface CronJob {
|
|
|
2163
2516
|
/**
|
|
2164
2517
|
* Options for `Cron.create()`.
|
|
2165
2518
|
*
|
|
2166
|
-
* Pass `agent`
|
|
2167
|
-
*
|
|
2168
|
-
*
|
|
2519
|
+
* Pass exactly ONE target: `agent` (ephemeral agent fresh per fire), `agentId`
|
|
2520
|
+
* (reuse an existing agent — preserves conversation context), or `workflow`
|
|
2521
|
+
* (SE35 — run a committed workflow per fire). Agent targets REQUIRE `message`;
|
|
2522
|
+
* a workflow target takes `inputData` and MUST NOT set `message`. Violations are
|
|
2523
|
+
* a `ConfigurationError`.
|
|
2169
2524
|
*
|
|
2170
2525
|
* @public
|
|
2171
2526
|
*/
|
|
2172
2527
|
interface CronCreateOptions {
|
|
2173
2528
|
cron: string;
|
|
2174
|
-
|
|
2529
|
+
/** Message for an agent target. Required with `agent`/`agentId`; forbidden with `workflow`. */
|
|
2530
|
+
message?: string | SDKUserMessage;
|
|
2175
2531
|
agent?: AgentOptions;
|
|
2176
2532
|
agentId?: string;
|
|
2533
|
+
/** SE35 — a committed {@link Workflow} to run per fire. Mutually exclusive with `agent`/`agentId`. */
|
|
2534
|
+
workflow?: Workflow;
|
|
2535
|
+
/** SE35 — input for `workflow.run(inputData)`. Workflow targets only. */
|
|
2536
|
+
inputData?: unknown;
|
|
2177
2537
|
name?: string;
|
|
2178
2538
|
timezone?: string;
|
|
2179
2539
|
/** Defaults to `true`. */
|
|
@@ -2301,11 +2661,12 @@ declare class Cron {
|
|
|
2301
2661
|
*/
|
|
2302
2662
|
static disable(jobId: string, _options?: CronOperationOptions): Promise<CronJob>;
|
|
2303
2663
|
/**
|
|
2304
|
-
* Manually trigger a cron job off-schedule. Returns the resulting `Run
|
|
2664
|
+
* Manually trigger a cron job off-schedule. Returns the resulting `Run`
|
|
2665
|
+
* (agent target) or `WorkflowRun` (workflow target — SE35).
|
|
2305
2666
|
*
|
|
2306
2667
|
* @public
|
|
2307
2668
|
*/
|
|
2308
|
-
static run(jobId: string, _options?: CronRunOptions): Promise<Run>;
|
|
2669
|
+
static run(jobId: string, _options?: CronRunOptions): Promise<Run | WorkflowRun>;
|
|
2309
2670
|
/**
|
|
2310
2671
|
* Activate the in-process scheduler for local cron jobs.
|
|
2311
2672
|
*
|
|
@@ -2326,4 +2687,4 @@ declare class Cron {
|
|
|
2326
2687
|
static status(_options?: CronStartOptions): Promise<CronSchedulerStatus>;
|
|
2327
2688
|
}
|
|
2328
2689
|
|
|
2329
|
-
export { type
|
|
2690
|
+
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, Skill as aD, type SkillsResolver as aE, type SkillsResolverContext as aF, type SystemPromptContext as aG, type SystemPromptMemoryFact as aH, type SystemPromptSkillRef as aI, type TelemetrySettings as aJ, 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, 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 };
|