lua-cli 3.49.1 → 3.50.0

package/dist/api-exports.d.ts

@@ -30,6 +30,7 @@ import { WorkflowShellFn as WorkflowShell } from '@lua/shared-types/workflow-exe
 import { WorkflowShellValue } from '@lua/shared-types/workflow-exec';
 import { z } from 'zod';
 import { ZodType } from 'zod';
+import type { ZodTypeDef } from 'zod';
 
 /**
  * `auto` (default, today's behaviour): every user-owned connection of the agent's creator auto-mounts on
@@ -707,9 +708,16 @@ export declare interface AgentsApi {
         }): Promise<unknown>;
     };
     versions(agentId: string): {
-        list(opts?: {
-            limit?: number;
-        }): Promise<unknown>;
+        /**
+         * The target's agent versions, newest first (`supervision:observe`). `limit` is 1–50 (default 20). Optional:
+         * `status` keeps only those statuses (one, or a list); `offset` skips that many rows of the (filtered) list, so
+         * `{ limit: 50, offset: 50 }` is the second page. Page until a page is shorter than `limit`.
+         *
+         * Feature-detect: a platform older than these options ignores them and answers the newest `limit` rows of every
+         * status. Check that each row's `status` is one you asked for, and that an `offset` page starts BELOW the
+         * previous page's last `version`; if not, the platform does not support them yet.
+         */
+        list(opts?: SupervisionVersionsListOptions): Promise<unknown>;
         get(version: number): Promise<unknown>;
         diff(from: number, to: number): Promise<unknown>;
         /** Chat staged `version` (`supervision:preview`). No tools run unless `toolScope.skillIds` allowlists them. */
@@ -740,9 +748,11 @@ export declare interface AgentsApi {
             expectActive: number;
         }): Promise<unknown>;
         /**
-         * Soft-delete `version` (`supervision:release`; only from a named workflow step). Refused
-         * (409 `supervision_version_not_superseded`) unless the version is `superseded` — never the
-         * active version, never the last one.
+         * Soft-delete `version` (`supervision:release`; only from a named workflow step): a `superseded`
+         * version, or a `staged` one that was never active, is over 24 hours old and is not the newest
+         * staged version. Never the active version, never the last one. Refusals (409):
+         * `supervision_version_not_superseded` (active, deleted), `supervision_version_staged_was_active`,
+         * `supervision_version_staged_too_recent`, `supervision_version_staged_newest`.
          */
         delete(version: number): Promise<{
             deleted: true;
@@ -1149,6 +1159,18 @@ export declare interface AgentsApi {
      */
     secrets(agentId: string): {
         attach(requestIds: string[]): Promise<SecretAttachResult>;
+        /**
+         * Write ONE secret row into `agentId`'s own Data, from CODE (a workflow step or a job) so the secret never passes
+         * through a model prompt: the row of `collection` whose `_pk` is `key` is replaced whole by `value` (flat fields:
+         * string, finite number, boolean or null; at most 32 fields, 8 KB a string, 16 KB in all), or created. The agent
+         * reads it with its own `Data.get(collection, { _pk: key })`. Needs `supervision:act` on `agentId` AND the
+         * collection in the grant's `secretWriteCollections` (set only by an org admin; deny by default). The collection is
+         * write-only for you: `Agents.data(agentId)` refuses it. Answers `{ ok, id, fingerprint }` and never the value;
+         * the fingerprint is `sha256:` + the first 16 hex of SHA-256 over the stored row as JSON with sorted keys (`_pk`
+         * included), so a token-free nudge carrying it tells the agent whether it already holds the row. Refused
+         * `supervision_secret_write_not_granted` / `supervision_secret_bad_args`; not available offline.
+         */
+        put(collection: string, key: string, value: Record<string, string | number | boolean | null>): Promise<SupervisedSecretPutResult>;
     };
 }
 
@@ -2032,7 +2054,7 @@ declare const BROWSER_COMMANDS: readonly [{
     readonly description: "Upload local file(s) to a file input. Args: selector, files[].";
 }, {
     readonly name: "find";
-    readonly description: "Act by semantic locator. Args: by(role|text|label|placeholder|alt|title|testid), query, action(click|fill|type|hover|focus|check|uncheck|text), value?, name?, exact?.";
+    readonly description: "Act by semantic locator. Args: by(role|text|label|placeholder|alt|title|testid), query, action(click|fill|hover|check|text), value?, name?, exact?.";
 }, {
     readonly name: "act";
     readonly description: "Act on the page: ref+action (deterministic) or natural-language instruction (engine AI). Args: ref?, action?, value?, instruction?.";
@@ -2041,7 +2063,7 @@ declare const BROWSER_COMMANDS: readonly [{
     readonly description: "Extract data by natural-language instruction (engine AI). Args: instruction.";
 }, {
     readonly name: "wait";
-    readonly description: "Wait for a condition. Provide one of: selector(+state), ms, text, url, load, fn.";
+    readonly description: "Wait for a condition. Provide one of: selector (waits until it is visible), ms, text, url, load, fn.";
 }, {
     readonly name: "tab";
     readonly description: "Manage tabs. Args: action(list|new|switch|close), target?, url?, label?.";
@@ -2065,7 +2087,7 @@ declare const BROWSER_COMMANDS: readonly [{
     readonly description: "Manage web storage. Args: area(local|session), action(get|set|clear), key?, value?.";
 }, {
     readonly name: "set";
-    readonly description: "Configure the browser. Args: setting(viewport|device|geo|headers|credentials|media), args[].";
+    readonly description: "Configure the browser. Args: setting(viewport|device|geo|headers|credentials|media|offline), args[].";
 }, {
     readonly name: "download";
     readonly description: "Download a file (click a selector to trigger, or wait for one). Args: selector?, path?.";
@@ -2095,7 +2117,7 @@ declare const BROWSER_COMMANDS: readonly [{
     readonly description: "Low-level mouse. Args: action(move|down|up|wheel), x?, y?, button?, dy?, dx?.";
 }, {
     readonly name: "keyboard";
-    readonly description: "Low-level keyboard at focus. Args: action(type|inserttext|keydown|keyup), text?, key?.";
+    readonly description: "Low-level keyboard at focus. Args: action(type|inserttext), text. Use press for single keys and chords.";
 }, {
     readonly name: "state";
     readonly description: "Persist/restore storage+auth state to a file. Args: action(save|load|list|clear), path?.";
@@ -2193,7 +2215,7 @@ export declare interface BrowserCommandInputs {
     find: BrowserSessionInput & {
         by: 'role' | 'text' | 'label' | 'placeholder' | 'alt' | 'title' | 'testid';
         query: string;
-        action: 'click' | 'fill' | 'type' | 'hover' | 'focus' | 'check' | 'uncheck' | 'text';
+        action: 'click' | 'fill' | 'hover' | 'check' | 'text';
         value?: string;
         name?: string;
         exact?: boolean;
@@ -2209,7 +2231,7 @@ export declare interface BrowserCommandInputs {
     };
     wait: BrowserSessionInput & {
         selector?: string;
-        state?: 'visible' | 'hidden';
+        state?: 'visible';
         ms?: number;
         text?: string;
         url?: string;
@@ -2287,9 +2309,8 @@ export declare interface BrowserCommandInputs {
         dx?: number;
     };
     keyboard: BrowserSessionInput & {
-        action: 'type' | 'inserttext' | 'keydown' | 'keyup';
-        text?: string;
-        key?: string;
+        action: 'type' | 'inserttext';
+        text: string;
     };
     state: BrowserSessionInput & {
         action: 'save' | 'load' | 'list' | 'clear';
@@ -2926,8 +2947,10 @@ export declare interface ChatHistoryMessage {
      * to render a "Voice call" divider in the thread.
      */
     source?: 'voice' | 'chat';
-    /** Concrete model that served this assistant turn, persisted in content metadata. */
+    /** The model the assistant turn requested (catalog code), persisted in content metadata. */
     model?: string;
+    /** The catalog code of the model that served the turn's final step; differs from `model` when a fallback answered. */
+    servedModel?: string;
     /** True when the turn reached that model through the Auto selector. */
     autoModelRequested?: boolean;
     author?: {
@@ -3280,6 +3303,14 @@ declare interface CustomDataAPI {
      * @returns Promise resolving to delete response
      */
     delete(collectionName: string, entryId: string): Promise<DeleteCustomDataResponse>;
+    /**
+     * An org-shared Data collection (namespace) an org admin created and granted this agent. Returns the same surface
+     * as `Data`, scoped to that namespace: `Data.shared('fleet_map').get('repos', { tier: 1 })`. Readers may call
+     * `collections`, `get`, `getEntry` and `search`; writers may also `create`, `update`, `patch`, `increment` and
+     * `delete`. A call outside the ACL rejects with `code === 'shared_data_forbidden'` (403). Deployed agents only:
+     * local runs reject with `code === 'shared_data_unavailable_offline'`.
+     */
+    shared(name: string): SharedDataAPI;
 }
 
 /** One collection in the agent's Data namespace, from Data.collections(). */
@@ -3500,6 +3531,29 @@ export declare const Data: {
      * @returns Promise resolving when deletion is complete
      */
     delete(collectionName: string, entryId: string): Promise<DeleteCustomDataResponse>;
+    /**
+     * An org-shared Data collection (namespace). An org admin creates it and names which agents of the org may read
+     * and which may write it (`POST /admin/orgs/:orgId/shared-collections`); agents never create one. The handle has
+     * the same methods as `Data`, scoped to the namespace, so a namespace can hold several collections:
+     *
+     * ```typescript
+     * const map = Data.shared('fleet_map');
+     * await map.create('repos', { repo: 'lua-core-services', tier: 1 }, { searchText: 'backend monorepo' }); // writers
+     * const { data } = await map.get('repos', { tier: 1 });                                                    // readers
+     * const hits = await map.search('edges', 'who calls lua-agents', 10);
+     * ```
+     *
+     * - Readers may `collections`, `get`, `getEntry`, `search`; writers may also `create`, `update`, `patch`,
+     *   `increment`, `delete` (a writer can read). Anything else rejects with `code === 'shared_data_forbidden'`
+     *   (403) — also when the name does not exist or belongs to another org.
+     * - Same limits, filters, managed indexes, compare-and-swap and vector search as `Data`. Every write is audited
+     *   (agent, collection, entry id; never the value).
+     * - A test session may read but not write (`shared_data_test_session_write_refused`, 409).
+     * - Deployed agents only: under `lua test` every call rejects with `code === 'shared_data_unavailable_offline'`.
+     *
+     * @param name - The shared collection name the org admin created (1-128 of `[A-Za-z0-9_.-]`)
+     */
+    shared(name: string): SharedDataAPI;
 };
 
 /**
@@ -3583,7 +3637,9 @@ declare const DECISION_ERROR_CODES: {
     readonly CANCELLED: "decision_cancelled";
 };
 
-declare const DECISION_PROVIDERS: readonly ["jev", "openai"];
+declare const DECISION_FALLBACK_PROVIDERS: readonly ["jev", "openai"];
+
+declare const DECISION_PROVIDERS: readonly ["jev", "openai", "openrouter"];
 
 declare const DECISION_ROUTING_RULES: readonly ["pinned", "images", "region", "zero_retention", "default", "fallback"];
 
@@ -3619,13 +3675,15 @@ export declare interface DecisionErrorFields {
     decisionId?: string;
 }
 
-declare type DecisionFallback = DecisionProvider | 'none';
+declare type DecisionFallback = DecisionFallbackProvider | 'none';
 
 declare interface DecisionFallbackInfo {
     from: DecisionProvider;
     reason: string;
 }
 
+declare type DecisionFallbackProvider = (typeof DECISION_FALLBACK_PROVIDERS)[number];
+
 declare interface DecisionImage {
     data: string;
     mimeType: 'image/png' | 'image/jpeg' | 'image/webp' | 'image/gif';
@@ -3824,7 +3882,7 @@ export declare function defineVoice(config: LuaVoiceConfig): LuaVoice;
  *   routes: {
  *     'GET /tickets': route({
  *       query: z.object({ status: z.enum(['open', 'closed']).default('open') }),
- *       handler: async ({ query }) => ({ items: (await Data.get('tickets', { filter: { status: query.status } })).data }),
+ *       handler: async ({ query }) => ({ items: (await Data.get('tickets', { status: query.status })).data }),
  *     }),
  *     'POST /tickets/:id/close': route({
  *       params: z.object({ id: z.string() }),
@@ -5614,6 +5672,10 @@ declare interface LlmContextStep {
     reasoningTokens?: number;
     /** The model id the provider says served the step (a fallback leg names itself here). Cost only. */
     model?: string;
+    /** The catalog code of the leg that served the step. Audit only: settlement never reads it. */
+    servedModel?: string;
+    /** The step was rejected by an output processor and re-run; its reply never reached the user. Audit only. */
+    discarded?: boolean;
 }
 
 declare type LoadState = 'load' | 'domcontentloaded' | 'networkidle';
@@ -9322,6 +9384,29 @@ declare interface RequestOverrides {
     signal?: AbortSignal;
 }
 
+/**
+ * R13 — `ResolveApprovalResult` (§9.5.3; matches shared-types). LUA-759 (#2582 review): the no-op's `decidedBy` is
+ * the spec's `WorkflowActorRef` — lua-api projects lua-core's trimmed `{kind, id, at, via}` record onto it, as it
+ * does R12 / R36 / R37's `recorded.by` — never a string (the old `string` declaration printed `[object Object]`).
+ */
+declare type ResolveApprovalResult = {
+    resolved: true;
+    outcome: 'approved' | 'denied';
+    runStatus: WorkflowRunStatus;
+    stepId?: string;
+} | {
+    resolved: false;
+    outcome: 'noop';
+    reason: 'already_resolved' | 'expired' | 'cancelled' | 'run_gone';
+    decision?: 'approved' | 'denied' | 'expired';
+    /** `approveResultLine` prints it as `<subjectId> via <source>`; an older lua-api's raw lua-core actor falls back to `actorLabel`. */
+    decidedBy?: {
+        subjectType: string;
+        subjectId: string;
+        source: string;
+    };
+};
+
 /**
  * R12 — `ResumeStepResult` (§9.5.3): the loser of a resume race gets the recorded outcome, never a 4xx. LUA-738
  * (desktop #1018): `recorded.by` is the spec's `WorkflowActorRef` — lua-api projects lua-core's `{ kind, id }` onto
@@ -9373,14 +9458,20 @@ export declare interface RouteContext<P = Record<string, string>, Q = Record<str
     request: Request;
 }
 
+/**
+ * The handler sees what a schema OUTPUTS (after `.default()`, `.transform()`, coercion), so only the
+ * output type is inferred; the input type is left open (`unknown`, not `any`). `ZodType<P>` alone would also pin the input
+ * to `P`, and `z.enum([...]).default('open')` (input `T | undefined`) would then make the handler's
+ * value `T | undefined`.
+ */
 export declare interface RouteDefinition<P = Record<string, string>, Q = Record<string, string | string[]>, B = unknown> {
     description?: string;
     /** Zod schema for path parameters; a failure answers 400 `VALIDATION`. */
-    params?: ZodType<P>;
+    params?: ZodType<P, ZodTypeDef, unknown>;
     /** Zod schema for query parameters; a failure answers 400 `VALIDATION`. */
-    query?: ZodType<Q>;
+    query?: ZodType<Q, ZodTypeDef, unknown>;
     /** Zod schema for the request body; a failure answers 400 `VALIDATION`. */
-    body?: ZodType<B>;
+    body?: ZodType<B, ZodTypeDef, unknown>;
     /** Response schemas by status, for the typed client (not enforced at runtime). */
     responses?: Record<number, ZodType>;
     handler: (ctx: RouteContext<P, Q, B>) => Promise<RouteHandlerResult> | RouteHandlerResult;
@@ -9687,6 +9778,16 @@ export declare interface SendTemplateValues {
 
 export { SerializedWorkflowGraph }
 
+/** `Data.shared(name)`: the `Data` surface on an org-shared namespace (it does not nest). */
+export declare type SharedDataAPI = Omit<CustomDataAPI, 'shared'>;
+
+/** Thrown by `Data.shared(name)` outside a deployed agent. `code` is the stable part. */
+export declare class SharedDataError extends Error {
+    readonly code: string;
+    readonly name = "SharedDataError";
+    constructor(code: string, message: string);
+}
+
 /** R14 — 202 `{ accepted:true, signalId, consumed, stepId? }` · 200 `{ accepted:true, duplicate:true }` · 202 `{ accepted:false, reason }`. */
 declare interface SignalRunResult {
     accepted: boolean;
@@ -9801,6 +9902,15 @@ export declare interface SupervisedJobRegisterResult {
     registered: boolean;
 }
 
+/** What `secrets.put` answers: never the value. */
+declare interface SupervisedSecretPutResult {
+    ok: true;
+    /** The Data entry id of the row written (stable across later puts of the same key). */
+    id: string;
+    /** {@link SUPERVISED_SECRET_FINGERPRINT_DOC}. */
+    fingerprint: string;
+}
+
 /** `workflows.get` — metadata only: never the graph, script, code or tools. */
 declare interface SupervisedWorkflow {
     workflowId: string;
@@ -10126,6 +10236,19 @@ declare interface SupervisionRunSummary {
     completedAt?: number;
 }
 
+/** Options of `Agents.versions(id).list` (supervision `versions.list`). */
+export declare interface SupervisionVersionsListOptions {
+    /** Page size, 1–50 (default 20; larger values are clamped to 50). */
+    limit?: number;
+    /** Keep only these statuses (one, or a non-empty list). Omitted = every status, soft-deleted included. */
+    status?: SupervisionVersionStatus | SupervisionVersionStatus[];
+    /** Rows of the (filtered) newest-first list to skip, 0–10000 — `limit: 50, offset: 50` is the second page. */
+    offset?: number;
+}
+
+/** An agent version's lifecycle status, as a supervision `versions.list` filter. */
+export declare type SupervisionVersionStatus = 'active' | 'staged' | 'superseded' | 'deleted';
+
 /**
  * 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
@@ -11971,6 +12094,41 @@ export declare interface WorkflowsApi {
             note?: string;
         }): Promise<Record<string, unknown>>;
     };
+    /**
+     * Act as the SIGNED-IN VIEWER of a web-app route, never as the agent: the decision is authorized and audited
+     * exactly as if that person decided it themselves (agent access, approver / four-eyes / step-up rules,
+     * `decidedBy` = the viewer). Available only inside a `defineWebApp` route handler for a POST, PUT, PATCH or
+     * DELETE call; anywhere else it throws `WorkflowsApiError` code `viewer_unavailable`. Under `lua apps dev` /
+     * `lua test webapp` the route runs as you, so the call is made with your own CLI credentials.
+     *
+     * An approval that demands step-up or a specific surface answers `STEP_UP_REQUIRED` / `APPROVAL_SURFACE_DENIED`:
+     * decide those in the Inbox. Other refusals pass through with their own codes (`NOT_AN_APPROVER`,
+     * `FOUR_EYES_REQUIRED`, `APPROVAL_NOT_FOUND`, `PAYLOAD_MISMATCH`, …).
+     *
+     * @example
+     * ```typescript
+     * 'POST /approvals/:runId/:approvalId': route({
+     *   handler: async ({ params, body }) =>
+     *     json(await Workflows.viewer.decideApproval(params.runId, params.approvalId, { decision: body.decision, note: body.note })),
+     * }),
+     * ```
+     */
+    viewer: {
+        /**
+         * R13 — approve or deny an approval as the viewer. `agentId` names the agent that owns the run (default: the
+         * app's own agent); the viewer must be able to decide on that agent's runs, as in the Inbox.
+         */
+        decideApproval(runId: string, approvalId: string, decision: {
+            decision: 'approve' | 'deny';
+            note?: string;
+            expectedFingerprint?: string;
+            agentId?: string;
+        }): Promise<ResolveApprovalResult>;
+        /** R12 — answer a step waiting for input (`suspend` / ask) as the viewer; `opts.agentId` as for decideApproval. */
+        resume(runId: string, stepId: string, resumeData: unknown, opts?: {
+            agentId?: string;
+        }): Promise<ResumeStepResult>;
+    };
 }
 
 export { WorkflowShell }