lua-cli 3.30.0 → 3.32.1

package/dist/api-exports.d.ts

@@ -1,9 +1,24 @@
+import { ArtefactRef } from '@lua/workflow-graph';
 import { CallWarning } from 'ai';
+import { DatasetRef } from '@lua/workflow-graph';
+import { EnvRefBinding } from '@lua/workflow-graph';
 import { FinishReason } from 'ai';
+import { fromKnowledge as fromKnowledge_2 } from '@lua/workflow-graph';
+import { JsonSchema } from '@lua/workflow-graph';
+import { KnowledgeBindingSpec } from '@lua/workflow-graph';
 import { LanguageModelUsage } from 'ai';
+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 { ModelMessage } from 'ai';
+import { PathOrLiteral } from '@lua/workflow-graph';
 import { ReasoningOutput } from 'ai';
+import { SerializedWorkflowGraph } from '@lua/workflow-graph';
+import { TemplateBinding } from '@lua/workflow-graph';
+import { TypedRef } from '@lua/workflow-graph';
 import { UserContent } from 'ai';
+import { WorkflowGraphEntry } from '@lua/workflow-graph';
 import { z } from 'zod';
 import { ZodType } from 'zod';
 
@@ -13,8 +28,11 @@ import { ZodType } from 'zod';
  * not exposed to skill code.
  */
 declare interface AgentInvocationEffects {
-    reviewDraftsCreated: number;
-    storage: 'lua_inbox';
+    reviewDraftsCreated?: number;
+    storage?: 'lua_inbox';
+    /** Set once per run when the agent reported it could not finish. Trusted
+     *  side channel: the run's own account of why, not a regex over its prose. */
+    blocker?: TaskRunBlocker;
 }
 
 /**
@@ -103,22 +121,75 @@ declare interface AgentInvocationInput {
     /** Per-request model override ("provider/model" code). Unknown codes fall back per
      *  approved-models policy server-side. */
     model?: string;
-    /** Task 14 (tasks-redesign) — per-task connector + skill scoping. See `AgentToolScope`. */
-    toolScope?: AgentToolScope;
     /**
-     * PRO-979 (A3) — cooperative mid-run cancellation. Honored where the
-     * transport boundary supports it (the loopback HTTP call is aborted); the
-     * in-flight server-side turn is NOT hard-killed — callers that abort must
-     * treat still-landing side effects as possible and record them (the job
-     * runner's ledger does, via postFence). NOT serialized on the wire — this
-     * field exists only on in-process invocations.
+     * LUA-655 (review M2) — a platform re-ask the customer must not pay for: the workflow executor's
+     * output-repair turns. Honoured server-side ONLY on internally-authenticated turns
+     * (`buildChatRequest` drops a Bearer client's value): it rides `handleBilling` → lua-api's
+     * `deduct-credits` as `skipCredits`, which skips the legacy credit deduction (the seat gate and
+     * the settlement usage event still run, the skill-override posture).
+     */
+    skipCredits?: boolean;
+    /** Task 14 (tasks-redesign) — per-task connector + skill scoping. See `AgentToolScope`. */
+    toolScope?: AgentToolScope_2;
+    /**
+     * PRO-979 (A3) — cooperative mid-run cancellation. Aborting tears down the
+     * loopback HTTP call AND propagates to the server-side turn: the serving
+     * pod's `ActiveChatTurnRegistry` sees the socket close and aborts the turn
+     * signal (`'client_disconnected'`), which flows through
+     * `ChatRequest.clientAbortSignal` into Mastra's
+     * `agent.generate({ abortSignal })` loop, so the in-flight turn stops
+     * generating (the D4 abort chain, pinned by the Phase-0
+     * `chat-generate-abort.contract` spec). Propagation is asynchronous:
+     * callers that abort must still treat side effects already dispatched at
+     * abort time (e.g. an in-flight tool call) as possible and record them (the
+     * job runner's ledger does, via postFence). NOT serialized on the wire —
+     * this field exists only on in-process invocations.
      */
     signal?: AbortSignal;
+    /**
+     * Workflows D10 (WF-003) — JSON Schema for a typed structured output on
+     * this turn. Honored server-side ONLY on internally-authenticated turns
+     * (`X-Internal-Auth`): `ChatService.buildChatRequest` copies it onto the
+     * `ChatRequest` and `AgentService.generate` forwards it as Mastra
+     * `structuredOutput`, so the result carries a schema-shaped `object`. A
+     * Bearer client's value is dropped before it can reach the model — same
+     * posture as `toolScope`.
+     */
+    outputSchema?: Record<string, unknown>;
+    /**
+     * Workflows D11 (WF-003) — retry-stable billing identity for the turn
+     * (e.g. `wf:<runId>:<stepId>:<billingEpoch>`), letting the credit deduction
+     * be idempotent across step retries. Internal-auth-only, same posture as
+     * `outputSchema`/`toolScope`; a Bearer client's value is dropped.
+     */
+    operationId?: string;
+    /**
+     * Workflows D25 (WF-216, 04 §4.2.7 runtime 3) — the ephemeral specialist's
+     * additive role for THIS turn: `name` (the role name; attribution key
+     * `luaWorkflowRole`), `block` (the rendered `<lua-workflow-role>` block
+     * `PromptService` appends AFTER the owner's own persona/instructions) and
+     * `tools` (the explicit tool-id allowlist `DynamicToolService` intersects
+     * with the owner's toolset). Internal-auth-only, same posture as
+     * `outputSchema`/`toolScope`: a Bearer client's value is dropped. Never a
+     * `systemPrompt` — the persona is the owner's.
+     */
+    workflowRole?: {
+        name: string;
+        block: string;
+        tools: string[];
+    };
 }
 
 declare interface AgentInvocationOutput {
     /** Final response text (post-processor-modified, if applicable). */
     text: string;
+    /**
+     * Workflows D10 (WF-003/WF-108) — the schema-shaped structured result of a
+     * turn that carried `outputSchema`. Present ONLY when the turn ran with
+     * Mastra `structuredOutput` (internal-auth-only, so Bearer callers can never
+     * receive it); absent otherwise — legacy outputs are byte-identical.
+     */
+    object?: unknown;
     /** AI SDK `FinishReason` (or `'preprocessor_blocked'` / `'governance_blocked'`). */
     finishReason?: string;
     /** Token usage summary. */
@@ -226,6 +297,43 @@ export declare interface AgentsApi {
     invoke(targetAgentId: string, input: AgentInvocationInput): Promise<AgentInvocationOutput>;
 }
 
+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;
+    /**
+     * Per-ATTEMPT ceilings for a tier:'job' step (LUA-636): `maxTurns` bounds one harness query; these bound the whole
+     * attempt (every pass and resumed segment). Crossing one checkpoints the workspace and ends the attempt
+     * `attempt_budget_exhausted` — retryable, so the step's `retry` policy continues from that tree with a fresh
+     * session. `maxMessages` counts harness messages (one per content block; 1..5000, default 400),
+     * `maxInputTokens` the attempt's input-side tokens (prompt + cache; 1M..500M, default 30M).
+     */
+    maxMessages?: number;
+    maxInputTokens?: number;
+}
+
+export declare interface AgentToolScope {
+    connectionIds?: string[];
+    skillIds?: string[];
+    toolIds?: string[];
+}
+
 /**
  * Task 14 (tasks-redesign) — per-task connector + skill scoping for a scheduled
  * agent run. Non-empty `connectionIds` restricts the turn's MCP servers to the
@@ -236,7 +344,7 @@ export declare interface AgentsApi {
  * `X-Internal-Auth` agent-invoke path used by the server-side job runner) —
  * lua-core drops it from any client-authenticated `/chat/*` request.
  */
-declare interface AgentToolScope {
+declare interface AgentToolScope_2 {
     /** Allowlisted agent connection ids (UnifiedTo `unifiedId`s). */
     connectionIds?: string[];
     /** Allowlisted skill ids (from the agent's `subAgent.skills`). */
@@ -384,6 +492,8 @@ export declare interface AiGenerateToolResult {
     isError?: boolean;
 }
 
+export declare const and: (...args: LuaPredicate[]) => LuaPredicate;
+
 /**
  * Common Interfaces
  * Shared interfaces used across multiple modules
@@ -419,9 +529,45 @@ declare interface ApiResponse<T = any> {
         error?: string;
         oldAccountLabel?: string;
         newAccountLabel?: string;
+        /** Workflow envelope detail (09 §9.11 `{ statusCode, message, code, ...detail }` is spread top-level). */
+        issues?: Array<{
+            path?: string;
+            message?: string;
+            code?: string;
+        }>;
+        stepId?: string;
+        /** the live step status on 409 NOT_SUSPENDED (LUA-644) */
+        status?: string;
     };
 }
 
+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 }
+
 /**
  * Complete basket entity.
  * Full basket object as stored in the database.
@@ -748,6 +894,28 @@ declare interface BrowserSwitchConfig {
     maxSessionMinutes?: number;
 }
 
+/** 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[];
+    /** `.workflow(id, ref, …, { workspace })` targets; `workspace:'inherit'` marks an inherit child — the compiler defers `workspace-not-declared` for it (03 §3.1). */
+    nestedRefs: Array<{
+        id: string;
+        name: string;
+        workspace?: 'inherit';
+    }>;
+}
+
+/** R11 — `CancelRunVerdict` (PRO-979 vocabulary). */
+declare interface CancelRunVerdict {
+    status: WorkflowRunStatus;
+    nextAction: string;
+    forceAvailableAt?: string;
+}
+
 /**
  * CDN API
  * Upload and retrieve files from the Lua CDN
@@ -1142,6 +1310,9 @@ export declare interface ChatHistoryMessage {
  */
 export declare type ChatMessage = TextMessage | ImageMessage | FileMessage;
 
+/** A container arm: a `StepRef`, or (B14 — lands with WF-509) the two-element chain `[mapConfig, stepRef]`. */
+export declare type ContainerArm = StepRef | [LuaMapConfig, StepRef];
+
 /**
  * Options for creating a custom data entry.
  */
@@ -1196,6 +1367,10 @@ declare interface CreateOrderRequest {
     };
 }
 
+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;
+
 /**
  * Custom Data API contract.
  * Defines operations for managing custom data collections with vector search.
@@ -1459,6 +1634,8 @@ export declare class DataEntryInstance {
     save(searchText?: string): Promise<boolean>;
 }
 
+export { DatasetRef }
+
 /**
  * Define a device that an agent can communicate with.
  *
@@ -1556,6 +1733,8 @@ export declare function defineTrigger<T = any>(config: LuaTriggerConfig<T>): Lua
  */
 export declare function defineVoice(config: LuaVoiceConfig): LuaVoice;
 
+export declare function defineWorkflow(cfg: LuaWorkflowConfig, build: (wf: LuaWorkflowBuilder) => LuaWorkflow): LuaWorkflow;
+
 /**
  * Response from deleting custom data entry.
  */
@@ -1672,6 +1851,8 @@ export declare interface DeliveryView {
     failedAt?: string;
 }
 
+declare type Depth = [never, 0, 1, 2, 3, 4];
+
 /** Configuration for a single device command (agent → device) */
 export declare interface DeviceCommandConfig {
     /** Description of what this command does */
@@ -1735,6 +1916,11 @@ export declare interface DirectoryTarget {
     validated: boolean;
 }
 
+/** 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;
+
 /** A single email attachment, referenced by URL — lua-email fetches the bytes
  * server-side and attaches them, keeping large files off the SDK→API hops. */
 declare interface EmailAttachmentInput {
@@ -1781,21 +1967,31 @@ export declare interface EmailSendInput {
 }
 
 /**
- * Safe environment variable access function.
- * Gets injected at runtime with skill-specific environment variables.
- *
- * Checks process environment variables (.env file)
+ * Read a sub-agent env key.
  *
- * @param key - The environment variable key to retrieve
- * @returns The environment variable value or undefined if not found
- *
- * @example
- * ```typescript
- * const baseUrl = env('BASE_URL');
- * const apiKey = env('API_KEY');
- * ```
- */
-export declare const env: (key: string) => string | undefined;
+ * Workflows (03 §3.1, WF-201): at MODULE TOP LEVEL of a workflow file the
+ * compiler's tier-1 sandbox replaces this with a stub that returns `''` and
+ * records the key into `ManifestWorkflow.envKeys[]`; inside `execute` it is
+ * `ctx.env[key]`. `env.template(KEY)` (Cluster K — B33) returns the
+ * `{ __envRef: KEY }` placeholder legal wherever a `template(...)` binding is —
+ * never a value at construction time — and `lua push` resolves it from the
+ * TARGET agent env into the version's `envOverlay`.
+ */
+export declare const env: ((key: string, opts?: {
+    manifest?: boolean;
+}) => string | undefined) & {
+    template: (key: string) => {
+        __envRef: string;
+    };
+};
+
+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 FileMessage {
     type: 'file';
@@ -1809,6 +2005,37 @@ declare type FileMessage_2 = {
     mediaType: string;
 };
 
+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;
+
 /**
  * Response from getting custom data entries.
  * Includes pagination information.
@@ -1887,6 +2114,10 @@ declare interface GovernanceConfig {
     serverUrl?: string;
 }
 
+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;
+
 /**
  * Function type for resolving headers at runtime.
  * Use env() inside to access agent environment variables.
@@ -1920,6 +2151,13 @@ declare abstract class HttpClient {
      * @private
      */
     private request;
+    /**
+     * Non-2xx classification shared by `request` and `httpStream` (WF-204): 401s become
+     * `AuthenticationError` (ownership vs credential), 403s throw, everything else returns the
+     * `{ success:false, error }` envelope with the server body spread in.
+     * @private
+     */
+    private classifyErrorResponse;
     /**
      * Checks if an HTTP status code is retryable
      * @param statusCode - The HTTP status code (0 for network errors)
@@ -1961,7 +2199,7 @@ declare abstract class HttpClient {
      * @returns Promise resolving to an ApiResponse with typed data
      * @protected
      */
-    protected httpPost<T>(url: string, data?: any, headers?: Record<string, string>): Promise<ApiResponse<T>>;
+    protected httpPost<T>(url: string, data?: any, headers?: Record<string, string>, overrides?: RequestOverrides): Promise<ApiResponse<T>>;
     /**
      * Performs one HTTP POST attempt.
      *
@@ -1996,6 +2234,25 @@ declare abstract class HttpClient {
      * @protected
      */
     protected httpPatch<T>(url: string, data?: any, headers?: Record<string, string>): Promise<ApiResponse<T>>;
+    /**
+     * Opens a Server-Sent Events stream (WF-204 — 03 §3.10 `watch`; 09 §9.10 `watchEvents`).
+     *
+     * The ONLY deliberately timeout-free request in the client: an SSE tail lives as long as
+     * the run (the server heartbeats every 15 s). Cancellation is the caller's `signal`.
+     * Non-2xx responses go through the same 401/403 classification as `request` — a 401 is
+     * an `AuthenticationError`, a 403 throws — and every other status resolves the returned
+     * `ApiResponse` with `success:false` (no retry: the caller decides whether to reconnect,
+     * passing `Last-Event-ID` for a resume).
+     *
+     * @param url - relative URL path (appended to baseUrl)
+     * @param headers - headers (auth); `Last-Event-ID` when resuming
+     * @param opts.signal - abort to close the stream
+     * @returns `{ success:true, data: AsyncIterable<SseFrame> }` or the error envelope
+     * @protected
+     */
+    protected httpStream(url: string, headers?: Record<string, string>, opts?: {
+        signal?: AbortSignal;
+    }): Promise<ApiResponse<AsyncIterable<SseFrame>>>;
 }
 
 /**
@@ -2094,6 +2351,10 @@ declare interface InboxPushReceipt {
     reason?: string;
 }
 
+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;
+
 /** HTTP methods the passthrough relay accepts. */
 declare const INTEGRATION_PASSTHROUGH_METHODS: readonly ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD"];
 
@@ -2656,12 +2917,31 @@ declare interface JobVersion {
     metadata?: Record<string, any>;
 }
 
+export { JsonSchema }
+
+export { KnowledgeBindingSpec }
+
 export declare interface ListTemplatesOptions {
     page?: number;
     limit?: number;
     search?: string;
 }
 
+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;
+
 /**
  * Lua Runtime API
  * Access request-level runtime information in your tools, conditions, and processors.
@@ -2723,6 +3003,7 @@ export declare class LuaAgent {
     private readonly webhooks;
     private readonly triggers;
     private readonly jobs;
+    private readonly workflows;
     private readonly preProcessors;
     private readonly postProcessors;
     private readonly mcpServers;
@@ -2761,6 +3042,7 @@ export declare class LuaAgent {
     getWebhooks(): LuaWebhook[];
     getTriggers(): LuaTrigger[];
     getJobs(): LuaJob[];
+    getWorkflows(): LuaWorkflow[];
     getPreProcessors(): PreProcessor[];
     getPostProcessors(): PostProcessor[];
     getMCPServers(): LuaMCPServer[];
@@ -2803,6 +3085,8 @@ export declare interface LuaAgentConfig {
     triggers?: LuaTrigger[];
     /** Array of scheduled jobs */
     jobs?: LuaJob[];
+    /** Array of workflows (createWorkflow / defineWorkflow) — 03 §3.1; resolved by the compiler traverser, dropped from the agent bundle */
+    workflows?: LuaWorkflow[];
     /** Array of preprocessors (run before messages reach the agent) */
     preProcessors?: PreProcessor[];
     /** Array of postprocessors (run after agent generates responses) */
@@ -3127,6 +3411,8 @@ export declare interface LuaJobConfig {
     metadata?: Record<string, any>;
 }
 
+export { LuaMapConfig }
+
 /**
  * LuaMCPServer class.
  * Defines an MCP (Model Context Protocol) server connection.
@@ -3184,6 +3470,8 @@ export declare class LuaMCPServer {
  */
 export declare type LuaMCPServerConfig = MCPSSEServerConfig | MCPStreamableHttpServerConfig;
 
+export { LuaPredicate }
+
 /**
  * The entity-independent, bounded Mongo-style filter accepted by Lua APIs.
  * Root `$and`/`$or` branches and nested data fields share this recursive shape;
@@ -3414,7 +3702,7 @@ export declare class LuaTrigger<T = any> {
     readonly inputSchema?: ZodType;
     readonly verify?: (ctx: TriggerContext<T>) => boolean | Promise<boolean>;
     readonly filter?: (ctx: TriggerContext<T>) => boolean | Promise<boolean>;
-    readonly transform?: (ctx: TriggerContext<T>) => string | AgentInvocationInput | Promise<string | AgentInvocationInput>;
+    readonly transform?: (ctx: TriggerContext<T>) => string | AgentInvocationInput | TriggerStartWorkflow | Promise<string | AgentInvocationInput | TriggerStartWorkflow>;
     readonly tool?: {
         name: string;
         input?: (ctx: TriggerContext<T>) => Record<string, unknown> | Promise<Record<string, unknown>>;
@@ -3457,7 +3745,7 @@ export declare interface LuaTriggerConfig<T = any> {
      * whose payload is capped at ~50k chars (like a no-code trigger); return a
      * transform to forward larger or hand-picked fields as the message.
      */
-    transform?: (ctx: TriggerContext<T>) => string | AgentInvocationInput | Promise<string | AgentInvocationInput>;
+    transform?: (ctx: TriggerContext<T>) => string | AgentInvocationInput | TriggerStartWorkflow | Promise<string | AgentInvocationInput | TriggerStartWorkflow>;
     /**
      * Direct tool binding: after `verify`/`filter` pass, the platform executes
      * this named skill tool DIRECTLY — no chat turn, no LLM, no visible
@@ -3984,7 +4272,7 @@ declare const LuaVoiceConfigSchema: z.ZodEffects<z.ZodObject<{
         prefixPaddingDuration?: number;
         activationThreshold?: number;
     };
-    turnDetection?: "multilingual" | "english" | "vad" | "stt" | "manual";
+    turnDetection?: "manual" | "multilingual" | "english" | "vad" | "stt";
     greeting?: string;
     maxToolSteps?: number;
     userAwayTimeout?: number;
@@ -4078,7 +4366,7 @@ declare const LuaVoiceConfigSchema: z.ZodEffects<z.ZodObject<{
         prefixPaddingDuration?: number;
         activationThreshold?: number;
     };
-    turnDetection?: "multilingual" | "english" | "vad" | "stt" | "manual";
+    turnDetection?: "manual" | "multilingual" | "english" | "vad" | "stt";
     greeting?: string;
     maxToolSteps?: number;
     userAwayTimeout?: number;
@@ -4172,7 +4460,7 @@ declare const LuaVoiceConfigSchema: z.ZodEffects<z.ZodObject<{
         prefixPaddingDuration?: number;
         activationThreshold?: number;
     };
-    turnDetection?: "multilingual" | "english" | "vad" | "stt" | "manual";
+    turnDetection?: "manual" | "multilingual" | "english" | "vad" | "stt";
     greeting?: string;
     maxToolSteps?: number;
     userAwayTimeout?: number;
@@ -4266,7 +4554,7 @@ declare const LuaVoiceConfigSchema: z.ZodEffects<z.ZodObject<{
         prefixPaddingDuration?: number;
         activationThreshold?: number;
     };
-    turnDetection?: "multilingual" | "english" | "vad" | "stt" | "manual";
+    turnDetection?: "manual" | "multilingual" | "english" | "vad" | "stt";
     greeting?: string;
     maxToolSteps?: number;
     userAwayTimeout?: number;
@@ -4621,6 +4909,158 @@ declare interface LuaWebhookEvent {
     timestamp: string;
 }
 
+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`; `workspace:'inherit'` marks the inherit children the compiler defers `workspace-not-declared` for. */
+    getNestedWorkflowRefs(): Array<{
+        id: string;
+        name: string;
+        workspace?: 'inherit';
+    }>;
+    /** 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'
+/**
+* @deprecated LUA-635 — the builder no longer throws it: a mount with no envelope `workspace` is the SHARED validator's
+* verdict (deferred for an inherit child, 03 §3.1 table). Kept for one minor so a consumer switching on the union still
+* compiles; removed in the next.
+*/
+| '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 — declares `id`, so a container may place it by string ref (03 §3.2.0) */
+    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;
+    /**
+     * Declared connection keys. `workspace.credentialsRef` and a step's `requiredConnections` may name a
+     * `key` instead of a connection id; the engine resolves it against the owner agent's own connections
+     * at run time (agent-scoped first, then org-scoped — never a user's), so the same definition runs on
+     * a template install, a hand-built agent and a duplicate without a frozen id.
+     */
+    connections?: WorkflowConnectionDeclaration[];
+}
+
+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 }
+
 /**
  * Base configuration for all MCP servers.
  */
@@ -4732,6 +5172,16 @@ export declare type MCPTransport = 'sse' | 'streamable-http';
 
 declare type Message = TextMessage_2 | ImageMessage_2 | FileMessage_2;
 
+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;
+
 /**
  * Order API contract.
  * Defines operations for managing orders.
@@ -4984,6 +5434,11 @@ declare interface Pagination {
     prevPage: number | null;
 }
 
+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;
+
 /**
  * Polymorphic shape used by `LuaAgent.persona`. String form is the legacy
  * single-channel persona; object form lets the customer split prose per
@@ -5593,6 +6048,8 @@ declare const REASONING_EFFORT_VALUES: readonly ["off", "minimal", "low", "mediu
 
 declare type ReasoningEffort = (typeof REASONING_EFFORT_VALUES)[number];
 
+export declare type ReplyChannel = 'whatsapp' | 'sms' | 'email' | 'webchat' | 'slack';
+
 declare interface RequestCredential {
     readonly descriptor: RequestCredentialDescriptor;
     bearer(): Promise<string>;
@@ -5609,6 +6066,47 @@ declare type RequestCredentialDescriptor = {
 
 declare type RequestCredentialInput = string | RequestCredential;
 
+/**
+ * Optional per-request overrides (WF-202, 03 §3.7 client-deadline rule). Today only
+ * `timeoutMs`: `WorkflowApi.startRun` long-polls with `waitSeconds ≤ 55` and raises
+ * its deadline to `(waitSeconds + 10) s` so the 30 s default abort never races the
+ * server. Every other call site is untouched (undefined ⇒ the 30 s default).
+ */
+declare interface RequestOverrides {
+    timeoutMs?: number;
+}
+
+declare type ResumeStepResult = {
+    resumed: true;
+    runStatus: WorkflowRunStatus;
+} | {
+    resumed: false;
+    reason: 'already_resumed';
+    recorded: {
+        at: number;
+        by?: {
+            kind: string;
+            id?: string;
+        };
+    };
+    runStatus: WorkflowRunStatus;
+};
+
+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;
+
 /**
  * Additive field on primitive publish responses. When the agent is under
  * versioning the server performs a scoped promote and returns the newly
@@ -5660,6 +6158,18 @@ export declare interface SendTemplateValues {
     buttons?: SendTemplateButtonValue[];
 }
 
+export { SerializedWorkflowGraph }
+
+/** R14 — 202 `{ accepted:true, signalId, consumed, stepId? }` · 200 `{ accepted:true, duplicate:true }` · 202 `{ accepted:false, reason }`. */
+declare interface SignalRunResult {
+    accepted: boolean;
+    signalId?: string;
+    consumed?: boolean;
+    stepId?: string;
+    duplicate?: boolean;
+    reason?: string;
+}
+
 /**
  * Same shape as `PersonaText`, exported separately because skill `context`
  * and agent `persona` play different semantic roles. Sharing the structural
@@ -5671,6 +6181,77 @@ declare type SkillContextText = string | {
     text?: string;
 };
 
+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[];
+}
+
+/** One parsed SSE frame (`id:` / `event:` / `data:` — `data` JSON-parsed when it parses, else the raw string). */
+declare interface SseFrame {
+    id?: string;
+    event: string;
+    data: unknown;
+}
+
+/** R8 — 202 `{ runId, status:'queued'|'gated', watchHint, idempotentReplay? }`, or 200 the run detail when `waitSeconds` elapsed on a terminal/suspended run. */
+declare interface StartWorkflowRunResult {
+    runId: string;
+    status: WorkflowRunStatus;
+    watchHint?: string;
+    idempotentReplay?: boolean;
+    output?: unknown;
+}
+
+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;
+
+/**
+ * Why an unattended run could not finish, reported by the agent itself instead
+ * of being guessed from its prose. The platform — not the agent — writes every
+ * user-facing string from this; `whatWouldUnblock` and `detail` are agent text
+ * and never reach a headline, preview, push body or email subject.
+ */
+declare const TASK_RUN_BLOCKER_KINDS: readonly ["missing_connection", "resource_not_found", "needs_input", "permission_denied", "other"];
+
+declare interface TaskRunBlocker {
+    kind: TaskRunBlockerKind;
+    /** Catalog slug when known ('googlemail', 'asana'). Never a guess. */
+    integrationType?: string;
+    /** What it was reaching for, in the user's words ('the agent-all-west repo'). */
+    resourceLabel?: string;
+    /** One sentence, the agent's own: what would make this run work next time. */
+    whatWouldUnblock: string;
+    /** Longer technical account. Expandable detail only — never a headline. */
+    detail?: string;
+}
+
+declare type TaskRunBlockerKind = (typeof TASK_RUN_BLOCKER_KINDS)[number];
+
 export declare const Team: TeamApi;
 
 /**
@@ -5698,6 +6279,14 @@ export declare interface TeamApi {
     findMember(name: string): Promise<DirectoryResolveResult>;
 }
 
+/** 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;
+
 /**
  * Templates API
  *
@@ -5853,15 +6442,15 @@ export declare enum ToolFlag {
     DISALLOW_INTERRUPTION = "disallow_interruption"
 }
 
-/**
- * Context delivered to a trigger's verify / filter / transform slots.
- *
- * Unlike a webhook event, `rawBody` carries the EXACT unparsed request bytes
- * (utf8) — HMAC signature schemes (Stripe `t=…,v1=…`, GitHub `sha256=…`, Slack
- * `v0:…`) are computed over the wire bytes, which `JSON.stringify(body)` does
- * not reproduce. `headers` keys arrive lowercased (Express), e.g.
- * `ctx.headers['x-hub-signature-256']`.
- */
+export declare interface ToolStepOptions {
+    input?: LuaMapConfig;
+    timeoutSeconds?: number;
+    retry?: RetryPolicy;
+    sideEffects?: 'none' | 'external';
+    onError?: 'fail' | 'continue' | 'park';
+    requiredConnections?: string[];
+}
+
 export declare interface TriggerContext<T = any> {
     /** Parsed request body (typed by `inputSchema` when provided). */
     body: T;
@@ -5877,6 +6466,39 @@ export declare interface TriggerContext<T = any> {
     source: string;
 }
 
+/**
+ * Context delivered to a trigger's verify / filter / transform slots.
+ *
+ * Unlike a webhook event, `rawBody` carries the EXACT unparsed request bytes
+ * (utf8) — HMAC signature schemes (Stripe `t=…,v1=…`, GitHub `sha256=…`, Slack
+ * `v0:…`) are computed over the wire bytes, which `JSON.stringify(body)` does
+ * not reproduce. `headers` keys arrive lowercased (Express), e.g.
+ * `ctx.headers['x-hub-signature-256']`.
+ */
+/**
+ * `transform` may start a workflow run instead of a chat turn (03 §3.7 / 07 — WF-205):
+ * `{ startWorkflow: { name, input?, idempotencyKey?, correlationKey?, tags? } }`.
+ * `name` is the agent-local workflow name; `correlationKey` accepts a literal or a
+ * `'${input.<field>}'` template the trigger fills.
+ */
+declare interface TriggerStartWorkflow {
+    startWorkflow: {
+        name: string;
+        input?: unknown;
+        idempotencyKey?: string;
+        correlationKey?: string;
+        tags?: string[];
+        replyTo?: {
+            channel: string;
+            threadId: string;
+        };
+    };
+}
+
+export declare const truthy: (ref: TypedRef<unknown>) => LuaPredicate;
+
+export { TypedRef }
+
 /**
  * Response from updating custom data entry.
  */
@@ -6096,6 +6718,8 @@ export declare interface UserLookupOptions {
     phone?: string;
 }
 
+export declare const value: (v: unknown) => MapDescriptor;
+
 export declare const Voice: VoiceApi;
 
 /**
@@ -6274,6 +6898,17 @@ declare interface VoiceSessionOutput {
     agentName: string;
 }
 
+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'>;
+}
+
 /**
  * Webhook request information from channel integrations.
  * Contains the raw webhook payload from the channel provider.
@@ -6397,4 +7032,424 @@ declare interface WhatsAppTemplateUrlButton {
     example?: string | string[];
 }
 
+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[];
+    };
+}
+
+declare interface WorkflowConnectionDeclaration {
+    /** /^[a-z][a-z0-9_-]{0,63}$/ — unique per workflow. */
+    key: string;
+    /** Catalog integration type (`'github'`, `'linear'`, …). */
+    integrationType: string;
+    required?: boolean;
+    description?: 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;
+}
+
+/**
+ * Matches WorkflowRunDto (R4 `fields:'summary'` — outputs are never inlined here).
+ * The wire names the run `runId` (shared-types `WorkflowRunSummary`); `id` is the pre-R4 spelling some
+ * envelopes still carry — read through `runIdOf()` (LUA-668: `status` printed "Run undefined").
+ */
+declare interface WorkflowRun {
+    id?: string;
+    runId?: string;
+    workflowId: string;
+    workflowVersionId: string;
+    agentId: string;
+    orgId: string;
+    status: WorkflowRunStatus;
+    trigger: 'chat' | 'sdk' | 'api' | 'schedule' | 'webhook' | 'template' | 'workflow' | 'device';
+    graphHash: string;
+    lineageId?: string;
+    parentRunId?: string;
+    correlationKey?: string;
+    tags?: string[];
+    gate?: {
+        kind: string;
+        reason?: string;
+        since?: string;
+    };
+    failureReason?: string;
+    restricted?: boolean;
+    /** LUA-623: the keys the run's version declares, and what each resolved to on its agent (`connection.resolved` rows). */
+    connections?: {
+        declared: Array<{
+            key: string;
+            integrationType: string;
+            required?: boolean;
+        }>;
+        resolved: Array<{
+            key: string;
+            connectionId: string;
+            integrationType: string;
+            scope: 'agent' | 'org';
+            at: number;
+        }>;
+    };
+    /** R4 `fields:'full'` only: the payload inline, else the `{__cdnRef}` it was offloaded under (LUA-643). */
+    output?: unknown;
+    /** LUA-643: ≤ 2 KB preview beside an offloaded `output`. */
+    outputPreview?: string;
+    /** LUA-643: every shape says whether a result exists; `--steps` (`fields:'full'`) serves it. */
+    hasOutput?: boolean;
+    createdAt: string;
+    startedAt?: string;
+    completedAt?: string;
+    updatedAt: string;
+}
+
+/** §02 §2.4 run statuses (one union across every section). */
+declare type WorkflowRunStatus = 'queued' | 'running' | 'cancellation_requested' | 'gated' | 'suspended' | 'waiting' | 'completed' | 'failed' | 'cancelled' | 'abandoned' | 'timed_out';
+
+export declare type WorkflowRunTrigger = 'chat' | 'sdk' | 'api' | 'schedule' | 'webhook' | 'template' | 'workflow' | 'device';
+
+/**
+ * @example
+ * ```typescript
+ * const { runId, status } = await Workflows.start('outreach', { leads }, { idempotencyKey: `outreach:${batchId}` });
+ * const run = await Workflows.get(runId);
+ * await Workflows.signal(runId, 'review', { approved: true });
+ * ```
+ */
+export declare const Workflows: WorkflowsApi;
+
+/**
+ * Workflows API — start, inspect and steer workflow runs from tools, jobs, webhooks,
+ * triggers, other workflows' code steps and scripts.
+ *
+ * - `start` is ALWAYS fire-and-return: it never awaits execution. `waitSeconds` (≤ 55) is
+ *   a server long-poll that returns early terminal state when the run finishes inside the
+ *   window — it changes the response, never the execution model. From a code step,
+ *   `start` creates a DETACHED run; use the `workflow()` node to wait on a nested run.
+ * - A `concurrencyPolicy:'forbid'` workflow with a run in flight throws
+ *   `WorkflowApiError{ code:'RUNS_IN_FLIGHT', blockingRunId }` — never a 429, never a gate.
+ * - `status:'gated'` from `start` means the run holds no org slot (quota/billing/consent).
+ * - `nameOrId` resolves the agent-local `workflow.name` first, then a workflow id.
+ * - `get`/`list` honour output ACLs: a restricted run comes back with `restricted:true`
+ *   and no `output` — never an error.
+ *
+ * `startBatch`, `signalByKey`, `raiseBudget`, `setGoal` and `goals.*` are part of the
+ * frozen member list and throw `WORKFLOWS_API_UNAVAILABLE` until their routes ship.
+ */
+export declare interface WorkflowsApi {
+    start(nameOrId: string, input?: unknown, opts?: {
+        idempotencyKey?: string;
+        budget?: {
+            maxCredits?: number;
+            maxSteps?: number;
+            maxDurationSeconds?: number;
+        };
+        waitSeconds?: number;
+        initialState?: Record<string, unknown>;
+        correlationKey?: string;
+        tags?: string[];
+        replyTo?: {
+            channel: string;
+            threadId: string;
+        };
+        onBehalfOf?: {
+            userId: string;
+        };
+        workflowVersionId?: string;
+    }): Promise<StartWorkflowRunResult>;
+    get(runId: string): Promise<WorkflowRun>;
+    list(opts?: {
+        limit?: number;
+        status?: WorkflowRunStatus | string;
+        workflow?: string;
+        correlationKey?: string;
+        tags?: string[];
+        sort?: string;
+    }): Promise<WorkflowRun[]>;
+    cancel(runId: string, opts?: {
+        mode?: 'request' | 'force';
+        reason?: string;
+    }): Promise<CancelRunVerdict>;
+    resume(runId: string, stepId: string, resumeData: unknown): Promise<ResumeStepResult>;
+    signal(runId: string, name: string, payload?: unknown, opts?: {
+        dedupeKey?: string;
+    }): Promise<SignalRunResult>;
+    signalByKey(nameOrId: string, correlationKey: string, name: string, payload?: unknown, opts?: {
+        dedupeKey?: string;
+        allowMultiple?: boolean;
+    }): Promise<{
+        runIds: string[];
+        delivered: number;
+    }>;
+    startBatch(nameOrId: string, items: Array<{
+        input: unknown;
+        idempotencyKey: string;
+        budget?: {
+            maxCredits?: number;
+            maxSteps?: number;
+            maxDurationSeconds?: number;
+        };
+        tags?: string[];
+        correlationKey?: string;
+        initialState?: Record<string, unknown>;
+    }>, opts?: {
+        mode?: 'reject' | 'gate';
+        budget?: {
+            maxCredits?: number;
+            maxSteps?: number;
+            maxDurationSeconds?: number;
+        };
+    }): Promise<{
+        batchId: string;
+        accepted: number;
+        items: Array<{
+            idempotencyKey: string;
+            runId?: string;
+            status: 'queued' | 'gated' | 'replayed' | 'rejected';
+            code?: string;
+        }>;
+    }>;
+    raiseBudget(runId: string, patch: {
+        maxCredits?: number;
+        maxSteps?: number;
+        maxJobSeconds?: number;
+        maxDurationSeconds?: number;
+        note?: string;
+    }): Promise<{
+        raised: true;
+        budget: Record<string, number>;
+        runStatus: WorkflowRunStatus;
+        resumed: boolean;
+    } | {
+        raised: false;
+        reason: 'already_raised';
+    }>;
+    setGoal(agentId: string, goal: Record<string, unknown>): Promise<Record<string, unknown>>;
+    goals: {
+        list(agentId: string, opts?: {
+            status?: 'active' | 'paused' | 'done' | 'closed';
+            workflowId?: string;
+        }): Promise<Record<string, unknown>[]>;
+        get(agentId: string, goalId: string): Promise<Record<string, unknown>>;
+        pause(agentId: string, goalId: string): Promise<Record<string, unknown>>;
+        resume(agentId: string, goalId: string): Promise<Record<string, unknown>>;
+        close(agentId: string, goalId: string, opts?: {
+            note?: string;
+        }): Promise<Record<string, unknown>>;
+    };
+}
+
+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 { }