lua-cli 3.29.1 → 3.31.0

package/dist/workflow-builder.d.ts

@@ -0,0 +1,766 @@
+import { ArtefactRef } from '@lua/workflow-graph';
+import { DatasetRef } from '@lua/workflow-graph';
+import { EnvRefBinding } from '@lua/workflow-graph';
+import { fromKnowledge as fromKnowledge_2 } from '@lua/workflow-graph';
+import { JsonSchema } from '@lua/workflow-graph';
+import { KnowledgeBindingSpec } from '@lua/workflow-graph';
+import { Literal } from '@lua/workflow-graph';
+import { LuaMapConfig } from '@lua/workflow-graph';
+import { LuaPredicate } from '@lua/workflow-graph';
+import { MapDescriptor } from '@lua/workflow-graph';
+import { PathOrLiteral } from '@lua/workflow-graph';
+import { SerializedWorkflowGraph } from '@lua/workflow-graph';
+import { TemplateBinding } from '@lua/workflow-graph';
+import { TypedRef } from '@lua/workflow-graph';
+import { WorkflowGraphEntry } from '@lua/workflow-graph';
+import type { z } from 'zod';
+import { ZodType } from 'zod';
+
+export declare interface AgentStepOptions {
+    agentId: string | EnvRefBinding;
+    prompt: TemplateLike;
+    outputSchema?: ZodType;
+    model?: string;
+    toolScope?: AgentToolScope & {
+        jobTools?: WorkflowJobToolId[];
+    };
+    timeoutSeconds?: number;
+    retry?: RetryPolicy;
+    onError?: 'fail' | 'continue' | 'park';
+    requiredConnections?: string[];
+    /** static-only persona override (§11 S3) */
+    systemPrompt?: string;
+    tier?: 'job';
+    workspace?: WorkflowStepWorkspace;
+    jobResources?: 'small' | 'medium' | 'large';
+    harness?: WorkflowJobHarness;
+    /** Coding-turn cap for a tier:'job' step (1..500); absent ⇒ the platform default. A monorepo change needs more than the default. */
+    maxTurns?: number;
+}
+
+export declare interface AgentToolScope {
+    connectionIds?: string[];
+    skillIds?: string[];
+    toolIds?: string[];
+}
+
+export declare const and: (...args: LuaPredicate[]) => LuaPredicate;
+
+export declare interface ApprovalOptions {
+    title: string;
+    details?: TemplateBinding;
+    /** default 'creator' */
+    approver?: WorkflowApproverSpec;
+    excludeInitiator?: boolean;
+    fourEyes?: WorkflowFourEyes;
+    /** default 168; a binding is resolved at suspend time and must yield 1..720 */
+    timeoutHours?: number | TemplateBinding;
+    /** 'deny' (default) | 'cancel-run' | 'fail' | a chain of ≤ 3 hops ending in one terminal member */
+    onTimeout?: WorkflowSuspendTimeoutChain;
+    /** default 'continue' (denial is data unless 'fail') */
+    onDeny?: 'fail' | 'continue';
+    businessHours?: WorkflowBusinessHours;
+    editable?: boolean;
+    /** grammar: `drafts`, `drafts[*]`, `drafts[*].body`, `drafts[3].body`, `summary.title` */
+    editablePaths?: string[];
+    editedPayloadSchema?: ZodType;
+    itemsPath?: string;
+    itemApprover?: WorkflowApproverSpec | {
+        fromItem: string;
+    };
+    itemTimeout?: WorkflowSuspendOnTimeout;
+}
+
+export { ArtefactRef }
+
+/** What `.commit()` hands to `LuaWorkflow` — internal; never `new LuaWorkflow({...})` by users. */
+declare interface BuiltWorkflow {
+    config: LuaWorkflowConfig;
+    graph: WorkflowGraphEntry[];
+    steps: Record<string, LuaWorkflowStep<any, any, any>>;
+    warnings: LuaWorkflowBuildWarning[];
+    envTemplateKeys: string[];
+    nestedRefs: Array<{
+        id: string;
+        name: string;
+    }>;
+}
+
+/** A container arm: a `StepRef`, or (B14 — lands with WF-509) the two-element chain `[mapConfig, stepRef]`. */
+export declare type ContainerArm = StepRef | [LuaMapConfig, StepRef];
+
+export declare function createStep<TIn extends ZodType, TOut extends ZodType, TResume extends ZodType = ZodType>(s: LuaWorkflowStep<TIn, TOut, TResume>): LuaWorkflowStep<TIn, TOut, TResume>;
+
+export declare function createWorkflow(cfg: LuaWorkflowConfig): LuaWorkflowBuilder;
+
+export { DatasetRef }
+
+export declare function defineWorkflow(cfg: LuaWorkflowConfig, build: (wf: LuaWorkflowBuilder) => LuaWorkflow): LuaWorkflow;
+
+declare type Depth = [never, 0, 1, 2, 3, 4];
+
+/** Template-literal walk of T's object keys, depth ≤ 4 (P1-21). */
+export declare type DotPath<T, D extends number = 4> = [D] extends [never] ? never : T extends readonly unknown[] ? never : T extends object ? {
+    [K in keyof T & string]: NonNullable<T[K]> extends object ? K | `${K}.${DotPath<NonNullable<T[K]>, Depth[D]>}` : K;
+}[keyof T & string] : never;
+
+export { EnvRefBinding }
+
+export declare const eq: <T>(l: TypedRef<T>, r: TypedRef<T> | Literal<T>) => LuaPredicate;
+
+export declare const exists: (ref: TypedRef<unknown>) => LuaPredicate;
+
+export declare const falsy: (ref: TypedRef<unknown>) => LuaPredicate;
+
+export declare interface ForeachOptions {
+    /** Cluster G (B34): PURE builder lowering — emits `{ type:'mapping', id:'<foreachId>_items', mapConfig:{'': items} }` before the foreach entry. */
+    items?: TypedRef<unknown[]> | {
+        step: string;
+        path: string;
+    } | {
+        initData: true;
+        path?: string;
+    };
+    /** default 4, max 16 */
+    concurrency?: number;
+    /** default 256 — a FAIL-FAST bound at runtime, never a truncation (P0-6). */
+    maxItems?: number;
+    chunk?: {
+        size: number;
+    };
+    rateLimit?: {
+        perSecond?: number;
+        perMinute?: number;
+    };
+}
+
+export declare const fromInit: (path: string) => MapDescriptor;
+
+export declare const fromKnowledge: typeof fromKnowledge_2;
+
+export declare const fromRequest: (path: string) => MapDescriptor;
+
+/** path default '' = whole output */
+export declare const fromStep: (s: LuaWorkflowStep<any, any, any> | string | Array<LuaWorkflowStep<any, any, any> | string>, path?: string) => MapDescriptor;
+
+export declare const gt: (l: TypedRef<number> | number, r: TypedRef<number> | Literal<number> | number) => LuaPredicate;
+
+export declare const gte: (l: TypedRef<number> | number, r: TypedRef<number> | Literal<number> | number) => LuaPredicate;
+
+export declare const init: <T = unknown>(path: string) => TypedRef<T>;
+
+export declare const inSet: <T extends string | number | boolean | null>(v: TypedRef<T>, set: T[]) => LuaPredicate;
+
+/**
+ * Job schedule configuration
+ * Supports either cron-style recurring schedules or one-time execution
+ */
+declare type JobSchedule = {
+    type: 'cron';
+    expression: string;
+    timezone?: string;
+} | {
+    type: 'once';
+    executeAt: Date | string;
+} | {
+    type: 'interval';
+    seconds: number;
+};
+
+export { JsonSchema }
+
+export { KnowledgeBindingSpec }
+
+export declare const lit: <const V extends string | number | boolean | null>(v: V) => Literal<V>;
+
+export { Literal }
+
+export declare interface LoopOptions {
+    /** default 100 */
+    maxIterations?: number;
+    /** engine timer between iterations, 1..86 400 (B24) */
+    intervalSeconds?: number;
+}
+
+export declare const lt: (l: TypedRef<number> | number, r: TypedRef<number> | Literal<number> | number) => LuaPredicate;
+
+export declare const lte: (l: TypedRef<number> | number, r: TypedRef<number> | Literal<number> | number) => LuaPredicate;
+
+export { LuaMapConfig }
+
+export { LuaPredicate }
+
+declare interface LuaTool<TInput extends ZodType = ZodType> {
+    /** Unique tool name (alphanumeric, hyphens, underscores only) */
+    name: string;
+    /** Description of what the tool does */
+    description: string;
+    /** Zod schema for input validation */
+    inputSchema: TInput;
+    /**
+     * Async function that executes the tool logic.
+     *
+     * `ctx` is `undefined` when the tool runs from the chat path (lua-core's
+     * vm-execution doesn't pass a second arg today). When the tool runs
+     * inside a voice session, `ctx` carries the voice runtime's delegates
+     * (`ctx.voice.say(...)` to emit a spoken acknowledgement, plus the
+     * `toolCallId` LiveKit assigned). Tools that want to bridge both modes
+     * read `ctx?.voice` and branch.
+     */
+    execute: (input: any, ctx?: LuaToolCtx) => Promise<any>;
+    /** Optional async function that determines if the tool should be available */
+    condition?: () => Promise<boolean>;
+    /**
+     * Optional voice-only metadata. When present, the lua-livekit worker
+     * applies these flags to the wrapped LiveKit `llm.tool()` registration.
+     * Tools without this field work in chat and voice unchanged.
+     */
+    voice?: {
+        flags?: ToolFlag[];
+    };
+}
+
+/**
+ * Per-call context passed to a `LuaTool.execute` running inside a voice
+ * session. Imported here (rather than in `voice.ts`) to break a circular
+ * import — `LuaVoiceTool` extends `LuaTool` and would otherwise loop.
+ *
+ * The chat path (lua-core's vm-execution) doesn't pass a second arg, so
+ * `ctx` is `undefined` for chat. The voice path passes `{ toolCallId,
+ * voice: { say } }`. Tools that want to act differently inside a voice
+ * call check for `ctx?.voice` and use the typed surface.
+ */
+declare interface LuaToolCtx {
+    /** LiveKit's tool-call id (voice only). */
+    toolCallId?: string;
+    /** Voice-runtime delegates. Only set when the tool runs over voice. */
+    voice?: {
+        say(text: string): Promise<void>;
+    };
+}
+
+export declare class LuaWorkflow {
+    private readonly built;
+    constructor(built: BuiltWorkflow);
+    getName(): string;
+    getConfig(): LuaWorkflowConfig;
+    getSteps(): Record<string, LuaWorkflowStep<any, any, any>>;
+    /** Builder warnings (`map-id-required`, `hitl-duration-defaulted`, `schedule-input-*`) — the compiler prints them. */
+    getBuildWarnings(): LuaWorkflowBuildWarning[];
+    /** Every `env.template(KEY)` placeholder key the graph carries (sorted, deduped) — `ManifestWorkflow.envTemplateKeys`. */
+    getEnvTemplateKeys(): string[];
+    /** `.workflow(id, ref)` targets by name — `ManifestWorkflow.workflowRefs`. */
+    getNestedWorkflowRefs(): Array<{
+        id: string;
+        name: string;
+    }>;
+    /** Pure: no I/O, no env, no time. Called by the compiler in the VM tier and by `lua test`. */
+    __serializeGraph(): SerializedWorkflowGraph;
+}
+
+export declare type LuaWorkflowBuildCode = 'duplicate-step-id' | 'unknown-step-ref' | 'map-id-required' | 'closure-predicate' | 'closure-binding' | 'timeout-out-of-range' | 'timeout-exceeds-tier' | 'job-timeout-exceeds-cap' | 'long-job-requires-workspace' | 'workspace-requires-job-tier' | 'workspace-not-declared' | 'workspace-inherit-without-parent-workspace' | 'workspace-inherit-conflict' | 'harness-requires-job-tier' | 'max-turns-requires-job-tier' | 'max-turns-invalid' | 'cap-exceeded' | 'chunk-size-invalid' | 'rate-limit-invalid' | 'backoff-invalid' | 'loop-interval-out-of-range' | 'mapping-placement' | 'container-arm-empty' | 'approval-inside-container' | 'empty-graph' | 'ephemeral-role-too-long' | 'role-ref-and-inline' | 'approver-excludes-only-candidate' | 'four-eyes-requires-editable' | 'escalation-chain-not-terminal' | 'escalation-chain-too-long' | 'editable-path-invalid' | 'env-template-secret-key' | 'invalid-envelope' | 'invalid-step' | 'invalid-step-id' | 'invalid-workflow-name' | 'schedule-input-required' | 'schedule-input-invalid' | 'hitl-duration-defaulted' | 'WORKFLOW_UNPLACED_STEP';
+
+export declare interface LuaWorkflowBuilder {
+    then(step: StepRef): this;
+    /** 2..16 arms; output = { [stepId]: output } */
+    parallel(steps: ContainerArm[], opts?: {
+        merge?: WorkflowMergePolicy;
+    }): this;
+    /** all-true arms run (Mastra); exclusive:true ≡ switch() */
+    branch(arms: Array<[LuaPredicate, StepRef]>, opts?: {
+        exclusive?: boolean;
+    }): this;
+    /** first true arm only ⇒ conditional{ exclusive:true, otherwise } */
+    switch(arms: Array<[LuaPredicate, StepRef]>, otherwise?: StepRef): this;
+    foreach(step: ContainerArm, opts?: ForeachOptions): this;
+    dowhile(step: ContainerArm, predicate: LuaPredicate, opts?: LoopOptions): this;
+    dountil(step: ContainerArm, predicate: LuaPredicate, opts?: LoopOptions): this;
+    /** top-level only. `id` is REQUIRED once the workflow has ≥ 2 maps (`map-id-required`). */
+    map(mapping: LuaMapConfig, opts?: {
+        id?: string;
+    }): this;
+    /** literal only; engine-side wait, no lease */
+    sleep(ms: number, opts?: {
+        id?: string;
+        businessHours?: WorkflowBusinessHours;
+    }): this;
+    /** a TemplateBinding lowers to `<id>_at` mapping + `sleepUntil{dateFrom}` (D6-r1) */
+    sleepUntil(iso: string | TemplateBinding, opts?: {
+        id?: string;
+        businessHours?: WorkflowBusinessHours;
+        round?: 'next-open' | 'next-close';
+    }): this;
+    agentStep(id: string, opts: AgentStepOptions): this;
+    /** D25 ephemeral specialist: runs AS THE OWNING AGENT (`agentId:'$self'`) with an additive role block. */
+    specialistStep(id: string, opts: SpecialistStepOptions): this;
+    toolStep(id: string, tool: LuaTool<any>, opts?: ToolStepOptions): this;
+    approval(id: string, opts: ApprovalOptions): this;
+    waitForSignal(id: string, opts: WaitForSignalOptions): this;
+    /** nested run; depth ≤ 3 */
+    workflow(id: string, ref: LuaWorkflow | string, input?: LuaMapConfig, opts?: {
+        workspace?: 'inherit';
+    }): this;
+    commit(): LuaWorkflow;
+}
+
+export declare class LuaWorkflowBuildError extends Error {
+    readonly code: LuaWorkflowBuildCode;
+    readonly hint?: string | undefined;
+    constructor(code: LuaWorkflowBuildCode, message: string, hint?: string | undefined);
+}
+
+export declare interface LuaWorkflowBuildWarning {
+    code: LuaWorkflowBuildCode;
+    message: string;
+    stepId?: string;
+}
+
+export declare interface LuaWorkflowConfig {
+    /** /^[a-z][a-z0-9-_]*$/ — server identifier */
+    name: string;
+    description?: string;
+    inputSchema: ZodType;
+    outputSchema?: ZodType;
+    /** types `ctx.state`; ≤ 64KB at runtime */
+    stateSchema?: ZodType;
+    /** 'forbid' = jobs-style overlap guard per workflow (D21-r1) — every start path gets 409 `RUNS_IN_FLIGHT`. */
+    concurrencyPolicy?: 'allow' | 'forbid';
+    /** Who may READ this workflow's run outputs beyond `workflows:read-outputs` holders (B44). Envelope member outside `graphHash`. */
+    outputVisibility?: WorkflowOutputVisibility;
+    /** `maxDurationSeconds` default 604 800; 2 592 000 when the graph contains an approval / waitForSignal / suspend-capable step (P1-4). */
+    budget?: {
+        maxCredits?: number;
+        maxSteps?: number;
+        maxDurationSeconds?: number;
+    };
+    /** verbatim LuaJob union (D12) → Job{kind:'workflow'} on publish */
+    schedule?: JobSchedule;
+    backfillOnEnable?: {
+        maxOccurrences?: number;
+    };
+    /** Literal JSON passed as run input on every scheduled fire; must validate against `inputSchema` (P0-5e). */
+    scheduleInput?: Record<string, unknown>;
+    goal?: WorkflowGoalEnvelope;
+    /** NEVER set by hand — the compiler derives it from the source file. */
+    form?: 'graph' | 'script';
+    workspace?: WorkspaceSpec;
+}
+
+export declare interface LuaWorkflowStep<TIn extends ZodType = ZodType, TOut extends ZodType = ZodType, TResume extends ZodType = ZodType> {
+    /** /^[a-z][a-zA-Z0-9_-]{0,63}$/ — unique per workflow; `[`, `#`, `.`, `:` reserved. */
+    id: string;
+    description?: string;
+    inputSchema: TIn;
+    outputSchema: TOut;
+    suspendSchema?: ZodType;
+    resumeSchema?: TResume;
+    execute: (ctx: WorkflowStepContext<z.infer<TIn>, z.infer<TResume>>) => Promise<z.infer<TOut>>;
+    /** 1..600 (D19); default 300 — on `tier:'job'` 1..86 400, default 3600. */
+    timeoutSeconds?: number;
+    /** Run this step as a k8s Job (hours tier). Implied by `workspace`. */
+    tier?: 'job';
+    workspace?: WorkflowStepWorkspace;
+    jobResources?: 'small' | 'medium' | 'large';
+    jobTools?: WorkflowJobToolId[];
+    /** default { maxAttempts: 1 } */
+    retry?: RetryPolicy;
+    /** default 'none'; 'external' ⇒ park on platform-fault reclaim. */
+    sideEffects?: 'none' | 'external';
+    /** What the FINAL failure of this step does to the run (default 'fail'). */
+    onError?: 'fail' | 'continue' | 'park';
+    requiredConnections?: string[];
+    /** Deadline for a `ctx.suspend()` suspension; default 168, max 720. */
+    resumeTimeoutHours?: number;
+    businessHours?: WorkflowBusinessHours;
+    onSuspendTimeout?: 'fail' | 'cancel-run';
+}
+
+export { MapDescriptor }
+
+export declare const ne: <T>(l: TypedRef<T>, r: TypedRef<T> | Literal<T>) => LuaPredicate;
+
+export declare const not: (arg: LuaPredicate) => LuaPredicate;
+
+export declare const notExists: (ref: TypedRef<unknown>) => LuaPredicate;
+
+export declare const notIn: <T extends string | number | boolean | null>(v: TypedRef<T>, set: T[]) => LuaPredicate;
+
+export declare const or: (...args: LuaPredicate[]) => LuaPredicate;
+
+export { PathOrLiteral }
+
+/** P split on '.' walked into T; `unknown` past depth 4 or through an index. */
+export declare type PathValue<T, P extends string> = P extends `${infer H}.${infer R}` ? H extends keyof T ? PathValue<NonNullable<T[H]>, R> : unknown : P extends keyof T ? T[P] : unknown;
+
+export declare type ReplyChannel = 'whatsapp' | 'sms' | 'email' | 'webchat' | 'slack';
+
+export declare interface RetryPolicy {
+    maxAttempts: number;
+    /** delay before attempt 2 (default 0 = immediate) */
+    backoffSeconds?: number;
+    /** 'fixed' (default) | 'exponential' — an engine timer, never a sleep inside the step VM (P1-10). */
+    backoff?: 'fixed' | 'exponential';
+    /** default 3600; only meaningful with 'exponential' (`backoff-invalid` otherwise). */
+    maxBackoffSeconds?: number;
+}
+
+export declare const rows: (s: LuaWorkflowStep<any, any, any> | string, path: string, page: {
+    offset: number;
+    limit: number;
+}) => MapDescriptor;
+
+export { SerializedWorkflowGraph }
+
+export declare interface SpecialistStepOptions {
+    role: WorkflowSpecialistRole | {
+        ref: string;
+    };
+    prompt: TemplateLike;
+    outputSchema?: ZodType;
+    model?: string;
+    toolScope?: AgentToolScope;
+    timeoutSeconds?: number;
+    retry?: RetryPolicy;
+    onError?: 'fail' | 'continue' | 'park';
+    requiredConnections?: string[];
+}
+
+export declare const state: <T = unknown>(path: string) => TypedRef<T>;
+
+/** `step(x).path('confidence')` is `TypedRef<number>` when `x.outputSchema` says so; a string id yields `TypedRef<unknown>`. */
+export declare function step<TOut extends ZodType>(s: LuaWorkflowStep<any, TOut, any>): StepPathRef<z.infer<TOut>>;
+
+export declare function step(id: string): {
+    path(p: string): TypedRef<unknown>;
+};
+
+/** Typed string ref for `agentStep`/`toolStep` ids: `stepOf<typeof angle>('techAngle').path('confidence')`. */
+export declare function stepOf<TOut extends ZodType>(id: string): StepPathRef<z.infer<TOut>>;
+
+export declare interface StepPathRef<TOut> {
+    path<P extends DotPath<TOut>>(p: P): TypedRef<PathValue<TOut, P>>;
+}
+
+/** An inline step object, or a string naming an entry declared by an `agentStep`/`specialistStep`/`toolStep`/`map` call in the same chain (03 §3.2.0). */
+export declare type StepRef = LuaWorkflowStep<any, any, any> | string;
+
+/** placeholders: ${initData.*} ${stepResults.<id>.*} ${state.*} */
+export declare const template: (s: string) => TemplateBinding;
+
+export { TemplateBinding }
+
+/** A prompt / literal slot: a string, a `template(...)` binding, or an `env.template(KEY)` placeholder (B33). */
+export declare type TemplateLike = string | TemplateBinding | EnvRefBinding;
+
+/**
+ * Lua Tool interface.
+ * Defines the structure of a tool that can be added to a LuaSkill.
+ *
+ * @template TInput - Zod schema type for input validation
+ *
+ * @example
+ * ```typescript
+ * import { z } from 'zod';
+ * import { LuaTool } from 'lua-cli';
+ *
+ * const weatherTool: LuaTool = {
+ *   name: 'get_weather',
+ *   description: 'Gets current weather for a city',
+ *   inputSchema: z.object({
+ *     city: z.string(),
+ *     units: z.enum(['metric', 'imperial']).optional()
+ *   }),
+ *   execute: async (input) => {
+ *     // Fetch weather data...
+ *     return { temperature: 72, condition: 'sunny' };
+ *   }
+ * };
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Tool with condition - only available to premium users
+ * class PremiumSearchTool implements LuaTool {
+ *   name = "premium_search";
+ *   description = "Advanced search for premium users";
+ *   inputSchema = z.object({ query: z.string() });
+ *
+ *   // Condition runs before tool is offered to LLM
+ *   condition = async () => {
+ *     const user = await User.get();
+ *     return user.data?.isPremium === true;
+ *   };
+ *
+ *   execute = async (input) => { ... };
+ * }
+ * ```
+ */
+/**
+ * Tool-level flags mirrored from LiveKit's `ToolFlag`. Used by `LuaTool.voice.flags`
+ * to control tool availability + interruption semantics during a voice session.
+ * Defined here (not voice.ts) so LuaTool's voice metadata stays self-contained
+ * with no risk of circular imports.
+ */
+declare enum ToolFlag {
+    NONE = "none",
+    /** Tool is hidden from the LLM during the first turn after onEnter. */
+    IGNORE_ON_ENTER = "ignore_on_enter",
+    /** User speech does not interrupt the agent while this tool is executing. */
+    DISALLOW_INTERRUPTION = "disallow_interruption"
+}
+
+export declare interface ToolStepOptions {
+    input?: LuaMapConfig;
+    timeoutSeconds?: number;
+    retry?: RetryPolicy;
+    sideEffects?: 'none' | 'external';
+    onError?: 'fail' | 'continue' | 'park';
+    requiredConnections?: string[];
+}
+
+export declare const truthy: (ref: TypedRef<unknown>) => LuaPredicate;
+
+export { TypedRef }
+
+export declare const value: (v: unknown) => MapDescriptor;
+
+export declare interface WaitForSignalOptions {
+    signal: string;
+    schema?: ZodType;
+    timeoutHours?: number | TemplateBinding;
+    /** default 'fail'; 'continue' ⇒ output {received:false,timedOut:true} */
+    onTimeout?: 'fail' | 'continue';
+    businessHours?: WorkflowBusinessHours;
+    /** default ['webhook','api','user'] */
+    acceptedSources?: Array<'webhook' | 'api' | 'user' | 'agent'>;
+}
+
+export declare const WORKFLOW_DEFAULT_MAX_DURATION_SECONDS = 604800;
+
+export declare const WORKFLOW_HITL_MAX_DURATION_SECONDS = 2592000;
+
+export declare type WorkflowApproverSpec = 'creator' | 'org-admins' | {
+    users: string[] | TemplateBinding;
+} | {
+    role: string | TemplateBinding | MapDescriptor;
+} | {
+    group: string | TemplateBinding;
+} | {
+    governance: {
+        policyId: string;
+    };
+};
+
+export declare interface WorkflowArtefactMeta {
+    artefactId: string;
+    name: string;
+    contentType: string;
+    bytes: number;
+    kind: 'file' | 'dataset' | 'image' | 'document';
+    datasetSchema?: JsonSchema;
+    rowCount?: number;
+    producer: {
+        stepId: string;
+        attempt: number;
+        source: 'turn' | 'ctx' | 'input';
+    };
+    previewCdnRef?: string;
+    title?: string;
+    source?: {
+        kind: 'step' | 'input' | 'url' | 'connection' | 'upload';
+        ref?: string;
+    };
+}
+
+export declare interface WorkflowBusinessHours {
+    tz: string;
+    calendar?: 'mon-fri' | {
+        days: number[];
+        start: string;
+        end: string;
+        holidays?: string[];
+    };
+}
+
+export declare interface WorkflowFourEyes {
+    edit: WorkflowApproverSpec;
+    approve: WorkflowApproverSpec;
+}
+
+export declare interface WorkflowGoalEnvelope {
+    objective: string;
+    judge: {
+        agentId: string | '$self';
+        role?: WorkflowSpecialistRole;
+        schema: ZodType;
+    };
+    cadence: JobSchedule[];
+    maxRuns: number;
+    budget?: LuaWorkflowConfig['budget'];
+    maxTotalCredits?: number;
+    initialState?: Record<string, unknown>;
+}
+
+export declare type WorkflowJobHarness = 'claude-code' | 'generic';
+
+export declare type WorkflowJobToolId = 'shell' | 'read' | 'write' | 'edit' | 'glob' | 'grep' | 'git' | 'gh' | 'fetch';
+
+export declare interface WorkflowMergePolicy {
+    strategy: 'rebase' | 'merge';
+    onConflict: 'fail' | 'agent';
+}
+
+export declare interface WorkflowOutputVisibility {
+    roles: string[];
+    users?: string[];
+    ownerBypass?: boolean;
+}
+
+export declare type WorkflowRunTrigger = 'chat' | 'sdk' | 'api' | 'schedule' | 'webhook' | 'template' | 'workflow' | 'device';
+
+export declare interface WorkflowSpecialistRole {
+    name: string;
+    instructions: string;
+    tools: string[];
+}
+
+export declare interface WorkflowStepContext<TIn = unknown, TResume = unknown, TState = Record<string, unknown>> {
+    runId: string;
+    workflowId: string;
+    workflowVersionId: string;
+    stepId: string;
+    attempt: number;
+    /** `${lineageId}:${stepId}` — stable across retries, resumes, `retry-step` AND repair runs. THE key for side-effect dedup. */
+    occurrenceId: string;
+    /** The run's recovery lineage: the first run's id in a repair chain; `=== runId` for a non-repair run. */
+    lineageId: string;
+    /** Resolved bindings snapshot (mapping descriptors applied by the advancer). Plain JSON. */
+    inputData: TIn;
+    /** Present only when re-invoked after resume. `execute` RE-RUNS FROM THE TOP (Mastra semantics). */
+    resumeData?: TResume;
+    /** What the prior invocation passed to `suspend()`. */
+    suspendData?: unknown;
+    getInitData<T = unknown>(): T;
+    /** Output of an UPSTREAM step. Throws `WorkflowStepResultError{ code:'STEP_RESULT_NOT_ANCESTOR' }` for a non-ancestor. */
+    getStepResult<T = unknown>(stepId: string): T;
+    /** Run-scoped KV, ledger-backed, ≤ 64KB total. `set` is durable when the step terminalizes. */
+    state: {
+        get<K extends keyof TState>(k: K): TState[K] | undefined;
+        set<K extends keyof TState>(k: K, v: TState[K]): Promise<void>;
+    };
+    /** Terminal for this invocation → step `suspended` kind:'input'. Never returns. */
+    suspend(payload: unknown): Promise<never>;
+    /** Early successful exit with `result` as the step output. Never returns. */
+    bail<T>(result: T): never;
+    /** Early successful exit for the WHOLE RUN (Cluster G, B8). Never returns. */
+    bailRun<T>(output: T): never;
+    /** → `step.progress` event (≤ 1000 per attempt; 1KB each). */
+    log(message: string): void;
+    /** Aborts on run cancel and on the sandbox wall. */
+    signal: AbortSignal;
+    /** Sub-agent env, exactly as jobs receive it. */
+    env: Record<string, string>;
+    /** EXACTLY-ONCE effect keyed on `{occurrenceId, key}` (P1-18). Claim → run `fn` → settle. */
+    once<T>(key: string, fn: () => Promise<T>): Promise<T>;
+    /** Job-tier steps only: the mounted run workspace. */
+    workspace?: {
+        path: string;
+        mount: 'rw' | 'ro';
+        branch?: string;
+        baseSha?: string;
+        arm?: string;
+        backend?: WorkflowWorkspaceBackend;
+    };
+    /** The run artefact store (P1-8). */
+    artefacts: {
+        put(name: string, data: Uint8Array | string | ReadableStream, opts: {
+            contentType: string;
+            kind?: 'file' | 'dataset' | 'image' | 'document';
+            datasetSchema?: JsonSchema;
+            title?: string;
+            source?: {
+                kind: 'step' | 'input' | 'url' | 'connection' | 'upload';
+                ref?: string;
+            };
+        }): Promise<{
+            artefactId: string;
+        }>;
+        get(artefactId: string): Promise<{
+            url: string;
+            meta: WorkflowArtefactMeta;
+            stream(opts?: {
+                range?: {
+                    start: number;
+                    end?: number;
+                };
+            }): Promise<ReadableStream>;
+            rows(page: {
+                offset: number;
+                limit: number;
+            }): Promise<{
+                rows: unknown[];
+                rowCount: number;
+                nextOffset?: number;
+            }>;
+        }>;
+        list(): Promise<WorkflowArtefactMeta[]>;
+    };
+    /** Stamped by the executor for observability; read-only. */
+    runtime: {
+        trigger: WorkflowRunTrigger;
+        parentRunId?: string;
+        agentVersion?: number;
+        traceparent?: string;
+        correlationKey?: string;
+        tags?: string[];
+        principalKind: 'user' | 'service' | 'customer';
+        replyTo?: {
+            channel: ReplyChannel;
+            threadId: string;
+        };
+    };
+}
+
+/** Thrown by `ctx.getStepResult` for a non-ancestor / unknown id — never `undefined` (03 §3.1). */
+export declare interface WorkflowStepResultError extends Error {
+    code: 'STEP_RESULT_NOT_ANCESTOR';
+    stepId: string;
+}
+
+export declare interface WorkflowStepWorkspace {
+    mount: 'rw' | 'ro';
+    isolation?: 'shared' | 'worktree';
+}
+
+export declare interface WorkflowSuspendOnTimeout {
+    timeoutHours: number | TemplateBinding;
+}
+
+export declare type WorkflowSuspendTimeoutChain = WorkflowSuspendTimeoutChainMember | WorkflowSuspendTimeoutChainMember[];
+
+export declare type WorkflowSuspendTimeoutChainMember = 'deny' | 'cancel-run' | 'fail' | 'continue' | {
+    escalateTo: WorkflowApproverSpec;
+    timeoutHours: number;
+};
+
+export declare type WorkflowWorkspaceBackend = 'ebs' | 'efs' | 's3';
+
+export declare type WorkspaceSpec = {
+    kind: 'git';
+    repo: string | TemplateBinding;
+    ref?: string | TemplateBinding;
+    credentialsRef?: string;
+    sizeGb?: number;
+    ttlHours?: number;
+    verify?: string;
+    keepArtefacts?: boolean;
+    backend?: WorkflowWorkspaceBackend;
+} | {
+    kind: 'empty';
+    sizeGb?: number;
+    ttlHours?: number;
+    keepArtefacts?: boolean;
+    backend?: WorkflowWorkspaceBackend;
+};
+
+export { }