lua-cli 3.32.6 → 3.34.0

package/dist/api-exports.d.ts

@@ -589,6 +589,20 @@ declare interface ApiResponse<T = any> {
         /** 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;
     };
 }
 
@@ -2073,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;
     };
@@ -3815,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.
@@ -5104,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;
     };
@@ -5674,8 +5704,15 @@ export declare type PreProcessorAction = 'proceed' | 'block';
 export declare type PreProcessorBlockResponse = {
     /** Stop processing immediately */
     action: 'block';
-    /** Message to show to the user */
-    response: string;
+    /**
+     * Message to show to the user.
+     *
+     * Omit it (or leave it empty) to end the turn SILENTLY — nothing is sent on
+     * any channel. That is the supported way to stay quiet, e.g. while a human
+     * agent is handling the conversation. The user's message is still recorded in
+     * the agent's history; only the reply is suppressed.
+     */
+    response?: string;
     /** Optional metadata */
     metadata?: Record<string, any>;
 };
@@ -6594,9 +6631,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 {
@@ -6604,12 +6657,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;
+        };
     };
 }
 
@@ -7289,7 +7351,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';
@@ -7298,6 +7360,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[];
@@ -7316,11 +7399,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;
@@ -7387,6 +7465,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;
     /**