lua-cli 3.32.5 → 3.33.0

package/dist/api-exports.d.ts

@@ -582,6 +582,27 @@ declare interface ApiResponse<T = any> {
         stepId?: string;
         /** the live step status on 409 NOT_SUSPENDED (LUA-644) */
         status?: string;
+        /** LUA-810 — 503 UPSTREAM_UNAVAILABLE: the internal Lua service behind the API that answered a fault or did
+         *  not answer (`lua-agents`, `lua-core`, …), and the id on the server's matching error log line. */
+        upstream?: string;
+        requestId?: string;
+        /** LUA-812 — 503 VENDOR_UNAVAILABLE: the third-party vendor behind the API that failed (`unified` | `github` |
+         *  `pusher` | `google`); `retryAfterSeconds` above is present only when a blind retry is safe. */
+        vendor?: string;
+        /** The vendor's own HTTP status when it answered (LUA-812); absent when nothing came back. */
+        vendorStatus?: number;
+        /** LUA-826 — on a 503 VENDOR_UNAVAILABLE from the GitHub token mint / the Unified.to passthrough: the code the
+         *  site served before it moved to the shared one (`PROVIDER_ERROR` | `passthrough_upstream_error`) and its former
+         *  line. One release, then gone — branch on `code`; these are for a script that still greps the old string. */
+        legacyCode?: string;
+        legacyMessage?: string;
+        /** LUA-820 — 424 PROVIDER_REJECTED: the model provider behind the agent refused the request (lua-core `provider-outcome.ts`):
+         *  the provider's own status, the refusal reason (`invalid_api_key` | `forbidden` | `model_not_found` | `content_refused` |
+         *  `quota_exhausted` | `bad_request`) and whose key it refused; `transient` is `false` — the mirror of a 503's `true`. */
+        providerStatus?: number;
+        reason?: string;
+        keyOwner?: 'platform' | 'byok';
+        transient?: boolean;
     };
 }
 
@@ -599,6 +620,11 @@ export declare interface ApprovalOptions {
     /** default 'continue' (denial is data unless 'fail') */
     onDeny?: WorkflowApprovalOnDeny;
     businessHours?: WorkflowBusinessHours;
+    /**
+     * Optional — inferred `true` from a non-empty `editablePaths` (LUA-808 / LUA-825: the validator's `approvalEditable`
+     * rule, applied by the builder too); an explicit `false` beside paths is refused as contradictory. Absent with no
+     * paths ⇒ `false` (the approver decides, never edits).
+     */
     editable?: boolean;
     /** grammar: `drafts`, `drafts[*]`, `drafts[*].body`, `drafts[3].body`, `summary.title` */
     editablePaths?: string[];
@@ -2061,11 +2087,16 @@ declare type FileMessage_2 = {
 };
 
 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;
-    } | {
+    /**
+     * Cluster G (B34): PURE builder lowering — emits `{ type:'mapping', id:'<foreachId>_items', mapConfig:{'': items} }`
+     * before the foreach entry. The lowering carries a typed path ref (`init('rows')` / `step(x).path('list')`), an
+     * `initData` descriptor (`fromInit('rows')`; `path` optional = the whole input) or a single-step descriptor
+     * (`fromStep(x, 'list')`). The slot admits the whole `MapDescriptor` union because that is what every descriptor
+     * factory is declared to return (LUA-864) — the members the lowering does not carry (`value` / `template` /
+     * `fromRequest` / `rows` / `fromKnowledge`, a fan-in `fromStep([…])`) are `invalid-envelope` at build:
+     * `.map({ '': … }, { id })` before the foreach instead.
+     */
+    items?: TypedRef<unknown[]> | MapDescriptor | {
         initData: true;
         path?: string;
     };
@@ -2229,6 +2260,15 @@ declare abstract class HttpClient {
      * @private
      */
     private calculateBackoff;
+    /**
+     * The wait before the next attempt: the client's jittered exponential backoff, floored by the server's
+     * `retryAfterSeconds` on a 429 (the limiter's word is final) and on an idempotent read (GET / HEAD). LUA-810: a
+     * POST / PUT / PATCH / DELETE that met a 5xx keeps the client's own backoff — every 503 body carries
+     * `retryAfterSeconds: 5` (`CONTROL_UNAVAILABLE`, `UPSTREAM_UNAVAILABLE`), which floored all three waits at 5 s:
+     * a ≥15 s stall on a write that may already have landed, and retrying an ambiguous write harder does not make
+     * it less ambiguous. The client's own schedule is ≤1 s + ≤2 s + ≤4 s.
+     */
+    private retryDelayMs;
     /**
      * Wraps request with retry logic for transient failures
      * @param url - The full URL to request
@@ -3794,8 +3834,11 @@ export declare interface LuaTriggerConfig<T = any> {
     /** Skip invocation (HTTP 200, no agent run) when this returns false. */
     filter?: (ctx: TriggerContext<T>) => boolean | Promise<boolean>;
     /**
-     * Shape the agent input. Return a `string` (the message) or a full
-     * `AgentInvocationInput` (you own the turn). Returning null/undefined is an
+     * Shape the agent input. Return a `string` (the message), a full
+     * `AgentInvocationInput` (you own the turn), or `{ startWorkflow: { name, … } }`
+     * to start a workflow run instead of a chat turn (`TriggerStartWorkflow` — the
+     * run is created in the delivery request, `trigger: 'webhook'`, and the
+     * execution log row carries its `runId`). Returning null/undefined is an
      * error — use `filter` to skip. Omit to use the default `body → message`,
      * 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.
@@ -5083,8 +5126,16 @@ export declare interface LuaWorkflowConfig {
      * for how many attempts the run may make.
      */
     budget?: Pick<WorkflowDefinitionBudget, 'maxCredits' | 'maxSteps' | 'maxDurationSeconds'>;
-    /** verbatim LuaJob union (D12) → Job{kind:'workflow'} on publish */
-    schedule?: JobSchedule;
+    /**
+     * verbatim LuaJob union (D12) → Job{kind:'workflow'} on publish. `runAs` (LUA-779) governs the copy a
+     * marketplace template freezes from this schedule: `'installer'` (the default when absent — every install's
+     * fires run as the person who installed, who gets the run card in their inbox) or `'system'` (the frozen copy
+     * runs user-less and unwatched — no inbox card for its runs; the install response says so). On this agent the
+     * schedule runs as you either way.
+     */
+    schedule?: JobSchedule & {
+        runAs?: 'installer' | 'system';
+    };
     backfillOnEnable?: {
         maxOccurrences?: number;
     };
@@ -6573,9 +6624,25 @@ export declare interface TriggerContext<T = any> {
  * `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
+ * `transform` may start a workflow run instead of a chat turn (03 §3.7 / 07 §7.2.1 — WF-205, LUA-875):
+ * `{ startWorkflow: { name, input?, idempotencyKey?, notify?, correlationKey?, tags?, initialState?, replyTo?, onBehalfOf? } }`.
+ *
+ * The contract, the same on an HTTP trigger (`POST /trigger/:agentId/:token`) and a device trigger:
+ * - the run is created synchronously in the delivery request — `200 { status: 'accepted', executionId, runId }` —
+ *   as the system principal (`trigger: 'webhook'`, the trigger's id on `run.triggerId`; no user connections are
+ *   mounted), and NO chat turn fires. A `prompt` / `messages` beside `startWorkflow` is ignored: the presence of
+ *   `startWorkflow` decides. A declared `tool` still wins over the whole transform (the both-declared rule).
+ * - `idempotencyKey` is the ONE uniqueness key: a redelivery with the same key returns the SAME run (the
+ *   execution log row is `started_workflow` with that run's id). A webhook delivery has no key of its own —
+ *   set it from the vendor's delivery id (`linear:${issue.identifier}:ready-for-agent`, Stripe `event.id`,
+ *   GitHub `X-GitHub-Delivery`); without one every delivery starts a run.
+ * - `notify` defaults to `'off'` (a system-principal run has no creator to notify); `replyTo` / `onBehalfOf`
+ *   make the run `principalKind: 'customer'`; `initialState` seeds the run's state (≤ 64 KB).
+ * - a missing `name`, an unknown workflow, an input failing the workflow's `inputSchema`, or a
+ *   `concurrencyPolicy: 'forbid'` overlap is a typed row in `lua triggers logs` (`failed` / `skipped_overlap`)
+ *   on a `200` — the sender is never asked to retry a configuration error.
+ * `name` is the agent-local workflow name (or its id — an id-or-name lookup, exactly what
+ * `lua workflows describe <ref>` resolves); `correlationKey` accepts a literal or a
  * `'${input.<field>}'` template the trigger fills.
  */
 declare interface TriggerStartWorkflow {
@@ -6583,12 +6650,21 @@ declare interface TriggerStartWorkflow {
         name: string;
         input?: unknown;
         idempotencyKey?: string;
+        /** receipt delivery; default `'off'` — a trigger start runs as the system principal. */
+        notify?: 'emailApp' | 'email' | 'app' | 'off';
         correlationKey?: string;
         tags?: string[];
+        /** seeds the run's state (≤ 64 KB) instead of `{}`. */
+        initialState?: Record<string, unknown>;
         replyTo?: {
             channel: string;
             threadId: string;
         };
+        /** a customer principal without a reply channel. */
+        onBehalfOf?: {
+            kind: 'customer';
+            externalId: string;
+        };
     };
 }
 
@@ -7268,7 +7344,7 @@ declare type WorkflowJobHarness_2 = (typeof WORKFLOW_JOB_HARNESSES)[number];
 
 declare type WorkflowJobResources = (typeof WORKFLOW_JOB_RESOURCES)[number];
 
-export declare type WorkflowJobToolId = 'shell' | 'read' | 'write' | 'edit' | 'glob' | 'grep' | 'git' | 'gh' | 'fetch';
+export declare type WorkflowJobToolId = 'shell' | 'read' | 'write' | 'edit' | 'glob' | 'grep' | 'git' | 'gh' | 'fetch' | 'ripwire';
 
 export declare interface WorkflowMergePolicy {
     strategy: 'rebase' | 'merge';
@@ -7277,6 +7353,27 @@ export declare interface WorkflowMergePolicy {
 
 declare type WorkflowOnError = (typeof WORKFLOW_ON_ERROR)[number];
 
+/**
+ * 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").
+ */
+/**
+ * LUA-877 — R4 `fields:'full'` / R5 `outputRef`: how to dereference an offloaded `{__cdnRef}` / `{__datasetRef}`
+ * `output`. `GET url` is R32: a `cdn` ref answers a presigned download of the canonical JSON (+ `sha256`); a
+ * `dataset` ref answers the presigned NDJSON plus the first page of rows (`?offset&limit`). Needs
+ * `workflows:read-outputs` on the run. Absent beside an inline output and without the grant.
+ */
+declare interface WorkflowOutputRefDto {
+    kind: 'cdn' | 'dataset';
+    artefactId: string;
+    url: string;
+    size?: number;
+    sha256?: string;
+    rowCount?: number;
+    contentType: string;
+}
+
 export declare interface WorkflowOutputVisibility {
     roles: string[];
     users?: string[];
@@ -7295,11 +7392,6 @@ declare interface WorkflowRetryPolicy {
     maxBackoffSeconds?: number;
 }
 
-/**
- * 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;
@@ -7366,6 +7458,8 @@ declare interface WorkflowRun {
     output?: unknown;
     /** LUA-643: ≤ 2 KB preview beside an offloaded `output`. */
     outputPreview?: string;
+    /** LUA-877: the R32 route that dereferences an offloaded `output` (beside the ref; absent on an inline output). */
+    outputRef?: WorkflowOutputRefDto;
     /** LUA-643: every shape says whether a result exists; `--steps` (`fields:'full'`) serves it. */
     hasOutput?: boolean;
     /**