lua-cli 3.42.0-beta.1 → 3.42.0-beta.3

package/dist/api-exports.d.ts

@@ -31,6 +31,163 @@ import { WorkflowShellValue } from '@lua/shared-types/workflow-exec';
 import { z } from 'zod';
 import { ZodType } from 'zod';
 
+/**
+ * `auto` (default, today's behaviour): every user-owned connection of the agent's creator auto-mounts on
+ * the creator's exclusive agents. `explicit`: NO user connection auto-mounts; a mount needs a confirmed
+ * assignment (c). Stored as `SubAgent.connectionPolicy` (absent ⇒ `auto`).
+ */
+declare const AGENT_CONNECTION_POLICIES: readonly ["auto", "explicit"];
+
+declare const AGENT_OBJECTIVE_STATUSES: readonly ["proposed", "active", "paused", "retired", "rejected"];
+
+/** `lease.get` / the dashboard field / lua-cli status: the lease (if live) and the human-activity signal. */
+declare interface AgentChangeActivity {
+    lease: AgentChangeLease | null;
+    /** ISO of the latest version create / promote or backup push whose actor is `human`. */
+    lastHumanChangeAt?: string;
+    /** ISO of the latest such change by an `agent:<id>` actor. */
+    lastAgentChangeAt?: string;
+}
+
+/** The ONE active lease of an agent (agents DB `agentChangeLeases`, one row per agent, `_id = agentId`). */
+declare interface AgentChangeLease {
+    leaseId: string;
+    agentId: string;
+    holderAgentId: string;
+    reason: string;
+    /** ISO. */
+    acquiredAt: string;
+    expiresAt: string;
+}
+
+/** `Agents.config(id).set(...)` (`act`). `env` holds NON-secret keys only. */
+declare interface AgentConfigSetInput {
+    model?: string;
+    name?: string;
+    env?: Record<string, string>;
+}
+
+/** What `config.set` wrote. Env VALUES are never echoed back. */
+declare interface AgentConfigSetResult {
+    agentId: string;
+    updated: Array<'model' | 'name' | 'env'>;
+    /** The env keys written (merged into the agent's env; other keys are untouched). */
+    envKeys: string[];
+}
+
+declare type AgentConnectionPolicy = (typeof AGENT_CONNECTION_POLICIES)[number];
+
+/**
+ * The member's consent given through a workflow `approval` step of the CALLER's own run (an alternative to
+ * `consentId`). `runId` is the code step's `ctx.runId`; name the approval by `stepId` (the approval node's id, what
+ * a code step knows) or by `approvalId` (`wfa_…`, from the run's approvals). Exactly one of `stepId` / `approvalId`.
+ * Only the ids are read: lua-api derives everything else (decision, decider, payload) from the stored rows.
+ */
+declare type AgentCreateApprovalRef = {
+    runId: string;
+    approvalId: string;
+} | {
+    runId: string;
+    stepId: string;
+};
+
+/** `Agents.create` first argument. */
+declare interface AgentCreateInput {
+    name: string;
+    model: string;
+    persona?: string;
+    /** The member's user-owned connection ids to mount (explicit policy: these are confirmed by the consent). */
+    connections?: string[];
+    /** The provisioner's supervision actions on the new agent (bounded by the policy). */
+    supervise?: ProvisionedSupervisionAction[];
+    /**
+     * The PROVISIONER's own workflow ids written on its grant (the supervision PAP's fields, not the new agent's
+     * workflows): `releaseWorkflowIds` names which of its workflows may run the `release` the member consented to
+     * (they only narrow it: a grant naming none cannot release at all).
+     */
+    releaseWorkflowIds?: string[];
+    /**
+     * Refused (non-empty) on provisioning for now: unattended staging keys are minted with the member as owner,
+     * and the member's consent does not cover them.
+     */
+    unattendedWorkflowIds?: string[];
+    /**
+     * U9 — `{ pendingFor }` secret requests to attach to the new agent (U9's `attachPending`). Only while
+     * `LUA_SECRET_REQUESTS_ENABLED` is on; each must be a stored, `ok`-tested request THIS provisioner made for
+     * the member in this org, and the member's consent must name the same ids.
+     */
+    pendingSecretRequestIds?: string[];
+}
+
+/** `Agents.create` second argument: exactly one of `consentId` or `approval`. */
+declare interface AgentCreateOptions {
+    /** The member the agent is created for; must be a member of the caller's org. */
+    onBehalfOf: string;
+    /** Minted by that member's chat confirmation (`POST /developer/agent-provisioning/consents`). */
+    consentId?: string;
+    /**
+     * …or the member's decision on a workflow `approval` step whose payload carries
+     * `{ [AGENT_PROVISIONING_APPROVAL_PAYLOAD_KEY]: AgentProvisioningApprovalPayload }` describing this create.
+     */
+    approval?: AgentCreateApprovalRef;
+}
+
+declare interface AgentCreateResult {
+    agentId: string;
+    name: string;
+    isPrivate: true;
+    createdBy: string;
+    connectionPolicy: AgentConnectionPolicy;
+    /** The scaffold backup version seeded at create (always 1). */
+    backupVersion: 1;
+    mountedConnectionIds: string[];
+    /** The provisioner's grant on the new agent (absent when `supervise` was empty). */
+    grant?: {
+        grantId: string;
+        actions: ProvisionedSupervisionAction[];
+    };
+    /** U9 — env keys attached from pending secret requests (never values). */
+    attachedSecretKeys?: string[];
+}
+
+/** `Agents.lifecycle(id).delete({ confirmName })` — must equal the agent's current name exactly. */
+declare interface AgentDeleteInput {
+    confirmName: string;
+}
+
+/** How the agent is built: from a source backup, in the dashboard, or from a repo (a `commitHash` on its versions). */
+declare type AgentDirectoryBuildKind = 'backup-source' | 'dashboard' | 'repo';
+
+/**
+ * One agent the turn's DELEGATED user can see (same visibility as the user's own agent list: private
+ * agents only for their creator / agent-grant holders; PDP-checked). Metadata only.
+ */
+declare interface AgentDirectoryEntry {
+    agentId: string;
+    name?: string;
+    /** The creator's user id (never their email). */
+    ownerUserId?: string;
+    isPrivate: boolean;
+    buildKind: AgentDirectoryBuildKind;
+    /**
+     * ISO — the latest counted activity: the newest persisted chat turn or workflow run. Job / trigger / webhook
+     * executions are not counted (U29 v1). When the live chat read fails the directory falls back to the nightly
+     * evidence rollup, and the chat half is then the UTC day of the latest exchanges.
+     */
+    lastActivityAt?: string;
+    /**
+     * Chat turns + workflow runs over the last 30 days, read live. A chat turn is a row in `chats.messages`: one
+     * per user turn the platform persisted, on ANY channel — production and sandbox (`lua chat -e sandbox`, the
+     * `dev` channel) alike. Not counted: version previews and test-session / test-traffic turns (never persisted),
+     * and job / trigger / webhook executions (U29 v1). A sub-agent's turns count on its own entry. `lua logs`
+     * counts differently (one log row per user message AND per agent response, plus tool / runtime rows), so a
+     * log count is typically about twice this number.
+     */
+    volume30d: number;
+    /** The supervision actions the CALLER already holds on it. */
+    callerActions: string[];
+}
+
 /**
  * Narrowed, wire-safe output for `Agents.invoke`. A slice of the internal
  * `FullOutput` shape — raw Mastra steps / tripwire payloads are intentionally
@@ -44,7 +201,7 @@ declare interface AgentInvocationEffects {
     blocker?: TaskRunBlocker;
 }
 
-declare interface AgentInvocationInput {
+export declare interface AgentInvocationInput {
     /** Shortcut: plain-text prompt. Mutually exclusive with `messages`. */
     prompt?: string;
     /** AI SDK `UserContent` (text/image/file parts). Mutually exclusive with `prompt`. */
@@ -271,6 +428,79 @@ declare interface AgentInvocationOutput {
     threadId?: string;
 }
 
+/**
+ * U4b (wave 2) — archive / delete with confirmation, the owner-departure policy, and non-secret config
+ * writes. Owner: U4b (the ONE owner-departure hook: pause agents, suspend grants, notify org admins; U1
+ * only suspends grants when a provisioning policy is revoked). Contract: docs/agent-builder/wave2-contracts.md §U4b.
+ */
+/**
+ * What archive and delete do (U4b spec): unmount connections (never revoke them at the provider), delete
+ * the agent's secrets, cancel its runs, revoke grants on it, and keep external records.
+ */
+declare interface AgentLifecycleResult {
+    agentId: string;
+    action: 'archive' | 'delete';
+    unmountedConnectionIds: string[];
+    deletedSecretKeys: number;
+    cancelledRunIds: string[];
+    /** The supervision grants revoked: every one ON the agent and every one it held on other agents. */
+    revokedGrantIds: string[];
+    /** Member access grants (roster and org-wide) the archive revoked or suspended; counted, not listed. */
+    memberGrantsRevoked?: number;
+    /** ISO. When the agent was archived (a re-archive keeps the first date). */
+    archivedAt?: string;
+    /**
+     * ISO. When the purge sweep may hard-delete the agent's Lua-held data. `archive` keeps the 30-day grace
+     * (`restore` works until then); `delete` sets it to now, so the agent cannot be restored.
+     */
+    purgeAfter?: string;
+    /** True when the agent was already archived (a race with another archive) and this call re-ran the teardown. */
+    resumed?: boolean;
+    /**
+     * Best-effort steps that did not complete (channel teardown, a run cancel, an unmount…). The call also revokes the
+     * caller's own grant on the agent, so a supervisor cannot re-run it: finishing a partial teardown (or deleting an
+     * already-archived agent) is a staff action.
+     */
+    warnings?: string[];
+}
+
+/** `Agents.metrics(id).query(...)` and the owners' REST twin. */
+export declare interface AgentMetricQueryInput {
+    /** A recorded metric name, or … */
+    name?: string;
+    /** … an objective (its metric definition is resolved server-side). */
+    objectiveId?: string;
+    /** ISO. */
+    from: string;
+    /** ISO. */
+    to: string;
+    interval: '1h' | '1d';
+    /**
+     * How each bucket reduces (added by U30): default `sum` for a name, the objective's own aggregation for an
+     * `objectiveId`. Buckets show the mean for `p50` / `p95` (percentiles are window-level, see the evaluator).
+     */
+    aggregation?: AgentObjectiveAggregation;
+}
+
+export declare interface AgentMetricQueryResult {
+    name: string;
+    interval: '1h' | '1d';
+    series: Array<{
+        tags: Record<string, string>;
+        points: Array<{
+            t: string;
+            value: number;
+            count: number;
+        }>;
+    }>;
+}
+
+export declare interface AgentMetricRecordReceipt {
+    accepted: boolean;
+    /** Present when `accepted: false`. */
+    code?: string;
+}
+
 /**
  * Per-agent LLM call settings PLUS normalized reasoning config. The
  * `CallSettings` leafs (`temperature`, `topP`, …) map directly onto Mastra's
@@ -320,6 +550,90 @@ export declare interface AgentModelSettings {
     };
 }
 
+/** One objective (agents DB `agentObjectives`). Only `active` objectives are evaluated and can breach. */
+export declare interface AgentObjective {
+    id: string;
+    agentId: string;
+    statement: string;
+    metric: AgentObjectiveMetric;
+    baseline?: number;
+    target?: number;
+    guardrails: AgentObjectiveGuardrail[];
+    confidence: 'low' | 'medium' | 'high';
+    status: AgentObjectiveStatus;
+    /** `user:<id>` or `service:agent:<id>` (a supervisor's proposal). */
+    proposedBy: string;
+    /** The OWNER who confirmed it (absent while `proposed`). */
+    confirmedBy?: string;
+    confirmedAt?: string;
+    lastEvaluatedAt?: string;
+    lastValue?: number;
+    /**
+     * A supervisor's `update` / `retire` proposal (U30): a separate `proposed` row that names the objective it
+     * would change. The target objective is untouched until the owner confirms this row; confirming applies
+     * `patch` (or retires the target) and marks this row `retired`. Absent on `create` proposals and owner rows.
+     */
+    pendingChange?: AgentObjectivePendingChange;
+    createdAt: string;
+    updatedAt: string;
+}
+
+/**
+ * How a window's points reduce to one value. `rate` is the mean of the recorded values (for 0/1 outcome
+ * metrics: the success rate); `p50` / `p95` are over at most the newest 10,000 points in the window.
+ */
+declare type AgentObjectiveAggregation = 'count' | 'sum' | 'avg' | 'rate' | 'p50' | 'p95' | 'min' | 'max';
+
+export declare interface AgentObjectiveGuardrail {
+    id: string;
+    metric: AgentObjectiveMetric;
+    op: 'lt' | 'lte' | 'gt' | 'gte';
+    value: number;
+}
+
+/**
+ * What an objective measures. `definition` is source-specific and validated server-side: `custom` = a
+ * `Metrics.record` name; `runs` = `{ workflowId?, status? }`; `logs` = `{ level?, logSource? }`; `evals` =
+ * `{ suiteKey | monitorKey }`; `data` = `{ collection, filter }` (read through the owner's Data).
+ */
+export declare interface AgentObjectiveMetric {
+    source: AgentObjectiveMetricSource;
+    definition: Record<string, unknown> | string;
+    aggregation: AgentObjectiveAggregation;
+    window: AgentObjectiveWindow;
+}
+
+declare type AgentObjectiveMetricSource = 'logs' | 'runs' | 'evals' | 'data' | 'custom';
+
+/** The fields an owner `PATCH` (or a confirmed `update` proposal) may change. */
+declare type AgentObjectivePatch = Partial<Pick<AgentObjective, 'statement' | 'metric' | 'baseline' | 'target' | 'guardrails' | 'confidence'>>;
+
+declare type AgentObjectivePendingChange = {
+    op: 'update';
+    objectiveId: string;
+    patch: AgentObjectivePatch;
+} | {
+    op: 'retire';
+    objectiveId: string;
+};
+
+/** `objectives.propose` (supervisor, `act`): never effective until the owner confirms. */
+export declare type AgentObjectiveProposal = {
+    op: 'create';
+    objective: Omit<AgentObjective, 'id' | 'agentId' | 'status' | 'proposedBy' | 'createdAt' | 'updatedAt'>;
+} | {
+    op: 'update';
+    objectiveId: string;
+    patch: AgentObjectivePatch;
+} | {
+    op: 'retire';
+    objectiveId: string;
+};
+
+export declare type AgentObjectiveStatus = (typeof AGENT_OBJECTIVE_STATUSES)[number];
+
+declare type AgentObjectiveWindow = '1d' | '7d' | '30d';
+
 export declare const Agents: AgentsApi;
 
 /**
@@ -406,6 +720,79 @@ export declare interface AgentsApi {
         promote(version: number, opts: {
             expectActive: number | null;
         }): 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.
+         */
+        delete(version: number): Promise<{
+            deleted: true;
+            version: number;
+        }>;
+        /**
+         * Open a TEST SESSION on staged `opts.version` (`supervision:preview`, U11 / DOC2 §6.1): multi-turn chat and
+         * fire against the staged version with side effects recorded instead of executed. A supervisor session runs
+         * with no tools (the preview posture) and never gets `egress: 'live'`.
+         */
+        session(opts: TestSessionOpenInput): Promise<{
+            sessionId: string;
+            version: number;
+            session: TestSessionRecord;
+            chat(input: string | {
+                prompt?: string;
+                messages?: unknown[];
+                threadId?: string;
+            }): Promise<{
+                sessionId: string;
+                threadId: string;
+                version: number;
+                text: string;
+                toolsUsed: string[];
+            }>;
+            fire(input: TestSessionFireInput): Promise<unknown>;
+            effects(): Promise<{
+                effects: TestSessionEffect[];
+            }>;
+            close(): Promise<{
+                id: string;
+                status: 'closed';
+                shadowPurged: boolean;
+            }>;
+        }>;
+    };
+    /** A workflow of the target: read it (`supervision:observe`), create and release it (`supervision:release`). */
+    workflows(agentId: string): {
+        /**
+         * The workflow's live `activeVersionId` (the value `deploy` takes as `expectActive`; null = none live) and
+         * its newest 20 versions — metadata only (`supervision:observe`).
+         */
+        get(workflowId: string): Promise<SupervisedWorkflow>;
+        /**
+         * Create workflow `name` on the target, or answer the one a previous `create` made (`created: false`), so a
+         * retried release step converges; a person's or a chat-composed workflow of that name is a 409
+         * `WORKFLOW_NAME_TAKEN`. INERT: inactive, no version; `push` then adds an inactive version and `deploy`
+         * (with `expectActive: null`) publishes it. It has no human author (what you write never runs as a person),
+         * so a SCHEDULED version on it is refused at deploy (`WORKFLOW_SCHEDULE_OWNER_UNKNOWN`); start it from a
+         * trigger or `Workflows.start` instead. Release-bound like `push` / `deploy` (`supervision:release`).
+         */
+        create(name: string, opts?: {
+            description?: string;
+            form?: 'graph' | 'script';
+        }): Promise<SupervisedWorkflowCreated>;
+        /**
+         * Push a new version of workflow `workflowId` (the same body `lua push workflow` sends). The version is
+         * NEVER activated: `activate` is forced to `false`. Deploy it with `deploy`.
+         */
+        push(workflowId: string, definition: Record<string, unknown>): Promise<unknown>;
+        /**
+         * Publish workflow `version` (a semver). Compare-and-swap: refused (409 `WORKFLOW_DEPLOY_CONFLICT`, the
+         * message names the live version) unless `expectActive` is the workflow's live version ID (null = none live).
+         * A deploy also records a new active agent version, so a later `versions.promote` needs a fresh
+         * `expectActive`.
+         */
+        deploy(workflowId: string, version: string, opts: {
+            expectActive: string | null;
+        }): Promise<unknown>;
     };
     persona(agentId: string): {
         versions(): Promise<unknown>;
@@ -433,6 +820,286 @@ export declare interface AgentsApi {
             keys: string[];
         }>;
     };
+    /**
+     * Supervision events of the target (`supervision:observe`). Each event of a subscribed kind
+     * (`governance.blocked`, `workflow.run_failed`, `workflow.run_gated`, `connection.unhealthy`, …)
+     * starts one of YOUR agent's triggers, `triggerName`, with a
+     * `SupervisionEventEnvelope` body (`source: 'supervision'`). The grant is re-checked on every
+     * delivery: a revoked grant stops the events. Not available offline.
+     */
+    events(agentId: string): {
+        /** Upsert by `triggerName` (one of your own triggers); at most 10 per supervised agent. */
+        subscribe(opts: {
+            kinds: SupervisionEventKind[];
+            triggerName: string;
+        }): Promise<SupervisionEventSubscription>;
+        unsubscribe(triggerName: string): Promise<{
+            removed: boolean;
+        }>;
+        /** Your own subscriptions on this agent. */
+        list(): Promise<SupervisionEventSubscription[]>;
+    };
+    /**
+     * Create a PRIVATE agent for a member of your organization (`onBehalfOf`), owned by them. Needs the org's
+     * agent-provisioning policy to name your agent, and the member's consent — exactly one of:
+     *  - `consentId`: from their chat confirmation (single use, 10 minutes);
+     *  - `approval: { runId, stepId }`: the member approved an `approval` step of YOUR workflow run. The step before
+     *    the approval outputs EXACTLY `{ agentProvisioning: { name, model, supervise, connections, releaseWorkflowIds,
+     *    pendingSecretRequestIds } }` (the approval's payload; no other key — the platform renders the card from it),
+     *    the approval is `approver: 'creator'` and is not editable, and a later code step calls `Agents.create` with
+     *    exactly that input, `runId: ctx.runId` and `stepId` = the approval step's id as stored (`confirm`; inside a
+     *    loop / foreach `confirm#n` / `confirm[i]`), or `approvalId` when you hold the `wfa_…` id. The run must have
+     *    been started by the member and still be running, and the member must have approved in their own signed-in
+     *    session (Lua Desktop / the inbox — not a chat card, a channel reply or an API key) within the last 10
+     *    minutes; each approval creates one agent. Set no `details` on the approval, or details equal in shape to the
+     *    payload. Call it from a regular code step (not `tier: 'job'`); graph workflows only.
+     * The policy bounds the model, how many agents a member may hold and the supervision actions (`supervise`) your
+     * agent gets on the new one. Refused offline (`supervision_offline_unsupported`) and while the platform has
+     * provisioning disabled (`agent_provisioning_disabled`).
+     *
+     * @example
+     * ```typescript
+     * const created = await Agents.create(
+     *   { name: 'Inbox helper', model: 'google/gemini-2.5-flash', supervise: ['observe'] },
+     *   { onBehalfOf: userId, consentId }
+     * );
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // A workflow the member starts (e.g. from chat): plan → confirm (the member approves) → create.
+     * const plan = { name: 'Inbox helper', model: 'google/gemini-2.5-flash', supervise: ['observe' as const] };
+     * const propose = createStep({
+     *   id: 'propose', inputSchema: z.object({ memberId: z.string() }), outputSchema: z.any(),
+     *   execute: async () => ({ agentProvisioning: plan }), // the approval's payload: what the member sees
+     * });
+     * const create = createStep({
+     *   id: 'create', inputSchema: z.any(), outputSchema: z.any(),
+     *   execute: async (ctx) => {
+     *     if (!ctx.inputData.approved) return { created: false };
+     *     return Agents.create(plan, {
+     *       onBehalfOf: ctx.getInitData<{ memberId: string }>().memberId, // must be the run's creator
+     *       approval: { runId: ctx.runId, stepId: 'confirm' },
+     *     });
+     *   },
+     * });
+     * createWorkflow({ ... })
+     *   .then(propose)
+     *   .approval('confirm', { title: 'Create “Inbox helper” for you?', approver: 'creator' })
+     *   .then(create)
+     *   .commit();
+     * ```
+     */
+    create(input: AgentCreateInput, opts: AgentCreateOptions): Promise<AgentCreateResult>;
+    /**
+     * The supervised agent's connections (`supervision:observe`): what `Integrations.list()` shows, without
+     * any person's identity (no owner user ids; no account identity on personal connections), and READ
+     * catalogue checks only — a check that writes is refused.
+     */
+    integrations(agentId: string): {
+        list(): Promise<IntegrationConnectionSummary[]>;
+        check(connectionId: string, check: ConnectionCheckName): Promise<ConnectionCheckOutcome>;
+    };
+    /**
+     * Metrics the target recorded with `Metrics.record` (`supervision:observe`): one `name` (or the metric of one
+     * `objectiveId`), bucketed by `1h` (≤ 7 days) or `1d` (≤ 400 days).
+     */
+    metrics(agentId: string): {
+        query(q: AgentMetricQueryInput): Promise<AgentMetricQueryResult>;
+    };
+    /**
+     * The target's objectives. `list` (`supervision:observe`) shows confirmed and proposed ones; `propose`
+     * (`supervision:act`) adds a `proposed` create / update / retire that takes effect ONLY when the agent's owner
+     * confirms it. Offline, `list` reads with your developer credential and `propose` is refused.
+     */
+    objectives(agentId: string): {
+        list(opts?: {
+            status?: AgentObjectiveStatus;
+        }): Promise<AgentObjective[]>;
+        propose(proposal: AgentObjectiveProposal): Promise<AgentObjective>;
+    };
+    /**
+     * The target's advisory change lease. A lease never blocks anyone's push: the agent's humans see it
+     * (`lua push` / `lua status` print a warning, and the dashboard shows it) and another supervisor cannot take
+     * it while it is live. Use it to say "I am working on this agent until …".
+     *
+     * @example
+     * ```typescript
+     * const { lease, lastHumanChangeAt } = await Agents.lease(agentId).get();
+     * // Back off while a person changed the agent in the last hour.
+     * if (lastHumanChangeAt && Date.now() - Date.parse(lastHumanChangeAt) < 3_600_000) return;
+     * await Agents.lease(agentId).acquire({ ttlMinutes: 30, reason: 'Tuning the refund skill' });
+     * // ... change the agent ...
+     * await Agents.lease(agentId).release();
+     * ```
+     */
+    lease(agentId: string): {
+        /**
+         * The live lease (null when none, or expired) and when a human (`lastHumanChangeAt`) or a supervisor agent
+         * (`lastAgentChangeAt`) last created or promoted a version or pushed the source (`supervision:observe`).
+         */
+        get(): Promise<AgentChangeActivity>;
+        /**
+         * Take the lease for YOUR agent, or renew the one you hold (`supervision:act`). `ttlMinutes` is 1-240,
+         * `reason` (at most 300 characters) is shown to the agent's humans. Refused (409 `change_lease_held`) while
+         * another agent's lease is live. Not available offline.
+         */
+        acquire(opts: {
+            ttlMinutes: number;
+            reason: string;
+        }): Promise<AgentChangeLease>;
+        /** Drop the lease you hold (`supervision:act`); `released: false` when you hold none. Not available offline. */
+        release(): Promise<{
+            released: boolean;
+        }>;
+    };
+    /**
+     * Archive or delete a supervised agent (`supervision:act`, on a grant written by an org owner or by the agent's
+     * creator). Both remove its connections from the agent without revoking them at the provider, delete its
+     * secrets (env), cancel its workflow runs and revoke every grant on it, yours included (so you cannot call it twice
+     * on the same agent: archive OR delete, and `warnings` lists anything staff must finish); records outside Lua are
+     * kept. Archive is reversible by staff for 30 days; `delete` needs the agent's exact current name and cannot be
+     * undone.
+     * Refused offline and while the platform has it disabled (`supervised_lifecycle_disabled`).
+     *
+     * @example
+     * ```typescript
+     * await Agents.lifecycle(agentId).delete({ confirmName: 'Old intake bot' });
+     * ```
+     */
+    lifecycle(agentId: string): {
+        archive(): Promise<AgentLifecycleResult>;
+        delete(opts: AgentDeleteInput): Promise<AgentLifecycleResult>;
+    };
+    /**
+     * Change a supervised agent's settings (`supervision:act`): its model, its name, or NON-secret env keys (merged;
+     * other keys untouched). A key ending SECRET, TOKEN, KEY or PASSWORD refuses the whole call
+     * (`agent_config_secret_key_refused`): secrets are set by the agent's owner. Refused offline.
+     */
+    config(agentId: string): {
+        set(input: AgentConfigSetInput): Promise<AgentConfigSetResult>;
+    };
+    /**
+     * Agents the DELEGATED user of the current turn can see (private agents only for their owner or agent-grant
+     * holders), with owner, privacy, build kind, last activity, 30-day volume and the actions you hold on each.
+     * Refused with `agent_directory_requires_user` on a turn with no user (or a user outside your org), a turn
+     * whose user an invoking agent chose, code in a Job or workflow run, and any turn invoked onward from those.
+     */
+    directory(): Promise<AgentDirectoryEntry[]>;
+    /**
+     * Ask for supervision actions on `agentId`. The request goes to the owner of a private agent, or to the org
+     * admins / agent builders of a shared one, as an inbox card; approving creates the grant (expiring at
+     * `expiresAt`, when given). One pending request per agent; a pending request lapses after 7 days. Refused
+     * with `supervision_access_no_approver` when nobody can approve (a departed owner, no admin / builder).
+     *
+     * Where the platform enables them, a request may also name `releaseWorkflowIds` / `unattendedWorkflowIds` (YOUR
+     * own workflows: release only ever happens in those workflows' code steps) and `dataCollections`
+     * (`supervision_access_bindings_disabled` otherwise), and `notifyOwner: true` (the owner opts in to `notifyOwner` by
+     * approving it). When you already hold a grant on the agent, the request UPGRADES it: the approver sees exactly
+     * what is added (`adds`), nothing is ever removed, and approval is refused (`supervision_access_grant_changed`) if
+     * your access changed after you asked (`supervision_access_upgrades_disabled` / `_grant_exists` where off).
+     */
+    requestAccess(agentId: string, opts: SupervisionAccessRequestInput): Promise<SupervisionAccessRequest>;
+    /** Your own access requests, newest first (at most 50). */
+    accessRequests(): Promise<SupervisionAccessRequest[]>;
+    /** Withdraw one of your own pending requests. */
+    cancelAccessRequest(requestId: string): Promise<SupervisionAccessRequest>;
+    /**
+     * Eval suites of a supervised agent (U12). Reads need `supervision:observe`; `run` and `cancel` need
+     * `supervision:preview`. `run` executes a STAGED (unpromoted) version — or `'active'` — against a suite the agent's
+     * owner defined, isolated from live tools unless the owner opted some in. Bounded by the suite budget, the agent's
+     * monthly eval allowance and a per-day cap of supervised runs per agent (`supervision_eval_runs_rate_limited`).
+     * Per-check `detail`, the judge's `reasoning` and transcripts need `observe-content`. `cancel` stops only runs you
+     * started, and works even after the platform turns evals or preview off. Suites are written by the owner
+     * (`lua evals push`), never by a supervisor. Off until the platform enables evals (`agent_evals_disabled`).
+     * Offline (`lua test`): reads use your developer credential; `run` / `cancel` are refused.
+     *
+     * @example
+     * ```typescript
+     * const { runId } = await Agents.evals(agentId).run({ suite: 'release-gate', version: staged });
+     * const run = await Agents.evals(agentId).getRun(runId); // poll (or wait in a workflow step) until it finishes
+     * if (run.passed === false) { ... }
+     * ```
+     */
+    evals(agentId: string): {
+        suites(): Promise<Array<{
+            key: string;
+            revision: number;
+            caseCount: number;
+            minPassRate: number;
+            updatedAt?: string;
+        }>>;
+        suite(key: string): Promise<EvalSuite>;
+        run(opts: {
+            suite: string;
+            version: number | 'active';
+            maxCredits?: number;
+            caseIds?: string[];
+        }): Promise<EvalRunReceipt>;
+        runs(opts?: {
+            suite?: string;
+            version?: number;
+            status?: string;
+            limit?: number;
+            before?: string;
+        }): Promise<EvalSuiteRunSummary[]>;
+        getRun(runId: string): Promise<EvalSuiteRunSummary>;
+        transcript(runId: string, caseId: string): Promise<EvalCaseTranscript>;
+        cancel(runId: string): Promise<EvalSuiteRunSummary>;
+    };
+    /**
+     * Message the OWNER of a supervised agent: a plain message (no model turn) in their home thread with YOUR agent,
+     * from any run — a schedule or an event trigger included, not only your own notify list. Needs `supervision:observe`
+     * and the owner's opt-in on your grant (they approved a `requestAccess({ notifyOwner: true })` themselves, or turned
+     * it on from the agent's supervisors list). Refused `supervision_owner_notify_not_opted_in` otherwise, and when the
+     * agent changed owner or the owner left. Shares `Threads.followUp`'s rate limits. Off until the platform enables it
+     * (`supervision_owner_notify_disabled`); not available offline.
+     *
+     * Pass an optional `idempotencyKey` (1-256 characters) to make retries safe: a second call from your agent with the
+     * same key within 24 hours posts nothing and resolves the FIRST call's receipt (same `followUpId` and `threadId`).
+     * A duplicate sent while the first is still posting waits for it, or is refused `thread_follow_up_in_progress`
+     * (retry it). A key already used for ANOTHER target agent is refused `supervision_owner_notify_invalid`. At most
+     * once unless the platform's key store fails mid-delivery. Without a key every call posts.
+     *
+     * @example
+     * ```typescript
+     * await Agents.notifyOwner(targetId, { message: 'Lead Desk is failing', idempotencyKey: `incident-${incidentId}` });
+     * ```
+     */
+    notifyOwner(agentId: string, input: SupervisionOwnerNotifyInput): Promise<SupervisionOwnerNotifyReceipt>;
+    /**
+     * Hand one of the agent OWNER's own personal connections to the agent (`supervision:act`), with the owner's consent
+     * on Lua's own approval card, decided in their signed-in Desktop or inbox session (a chat-card, channel-reply or
+     * API-key decision does not count). From a run the owner started, suspend on
+     * `.approval(step, { approver: 'creator', title })` with the payload exactly
+     * `{ connectionAssignment: { connectionId, agentId, agentName, supervisorName, integration, account } }` — the
+     * agent's and YOUR agent's current names, the connection's integration type and its label (display name, else first
+     * email), each checked against what Lua stores — and `title` exactly
+     * `Give your <integration> connection to "<agentName>"?` (`connectionHandoverApprovalTitle`); no artefacts. Then call
+     * `assign(connectionId, { approval: { runId, stepId } })` from a code step of THAT run within 10 minutes. One
+     * assignment per approval. Refused `connection_handover_account_unidentified` / `connection_handover_agent_unidentified`
+     * when the card could not say which account / agent (no label, a duplicate label or name, invisible characters). Refused `connection_handover_not_assignable` unless the connection is the owner's own and the agent is
+     * their private agent. Off until the platform enables it (`connection_handover_disabled`); not available offline.
+     */
+    connections(agentId: string): {
+        assign(connectionId: string, opts: {
+            approval: AgentCreateApprovalRef;
+        }): Promise<ConnectionHandoverResult>;
+    };
+    /**
+     * Keys for an agent that already exists. On the owner's live chat turn, ask with `Secrets.request({ provider, key,
+     * target: { pendingFor, agentId } })` (needs `supervision:act` on `agentId`, an agent of your org created by the
+     * person you are talking to; never a `LUA_` / `NODE_` key). The OWNER submits it signed in
+     * (`POST /developer/secrets/held-requests/:requestId/submit`; the public secret page refuses these), Lua tests it and
+     * holds it encrypted; then attach it with `Agents.secrets(agentId).attach([requestId])`, again on the owner's live
+     * chat turn (never a scheduled task, Job, workflow step or a user another agent chose). Only `ok`-tested requests you
+     * held and the owner submitted are taken, all or none, and a key the agent already has is never replaced
+     * (`secret_key_exists`). Off until `LUA_SECRET_ATTACH_EXISTING_ENABLED` is on (`secret_attach_existing_disabled`);
+     * not available offline.
+     */
+    secrets(agentId: string): {
+        attach(requestIds: string[]): Promise<SecretAttachResult>;
+    };
 }
 
 export declare interface AgentStepOptions {
@@ -557,16 +1224,30 @@ export declare interface AiApi {
     generate(prompt: string, content?: UserContent): Promise<string>;
     /**
      * Generate text with full options — a serializable subset of `generateText`
-     * (`model`, `system`, `prompt`, `messages`, `temperature`, `maxOutputTokens`).
+     * (`model`, `system`, `prompt`, `messages`, `temperature`, `maxOutputTokens`,
+     * `structuredOutput`, `reasoning`).
      * Returns the full AI SDK–aligned result including `text`, `finishReason`, `usage`,
      * `sources` (Google Search grounding), `reasoning`, `warnings`, and more.
      *
+     * `reasoning` takes the same `{ effort?, show? }` as an agent's `modelSettings.reasoning`:
+     * `effort` (`'off' | 'minimal' | 'low' | 'medium' | 'high' | 'max'`) is translated for the
+     * model's provider and clamped to the levels that model supports; `show: false` omits
+     * `reasoning` / `reasoningText` from the result (the count stays on `usage.reasoningTokens`).
+     * The call's `reasoning` outranks the model's catalog default. The agent's own
+     * `modelSettings.reasoning` is not applied to `AI.generate`.
+     *
      * @example
      * ```typescript
      * const { text, finishReason, usage, sources } = await AI.generate({
      *   system: 'You are concise.',
      *   prompt: 'Say hi.',
      * });
+     *
+     * // Think harder, but keep the trace out of the result.
+     * const { text: plan } = await AI.generate({
+     *   prompt: 'Plan the migration in five steps.',
+     *   reasoning: { effort: 'high', show: false },
+     * });
      * ```
      */
     generate(options: AiGenerateInput): Promise<AiGenerateOutput>;
@@ -584,6 +1265,11 @@ export declare interface AiGenerateInput {
     messages?: ModelMessage[];
     temperature?: number;
     maxOutputTokens?: number;
+    /**
+     * Reasoning effort / visibility — the same shape and semantics as an agent's
+     * `modelSettings.reasoning` (see {@link AiGenerateReasoningOptions}).
+     */
+    reasoning?: AiGenerateReasoningOptions;
     /**
      * When set, constrains the response to match the JSON Schema. The parsed result
      * lands on `AiGenerateOutput.output`. Mirrors AI SDK `Output.object({ schema })`.
@@ -599,6 +1285,19 @@ export declare interface AiGenerateInput {
  */
 export declare type AiGenerateJsonSchema = Record<string, unknown>;
 
+/**
+ * Why the served model differs from the requested one:
+ *  - `not-approved`: the resolved model (the agent's own pin, when the call named none) is not in the model
+ *    catalogue, so the platform default ran. A model the CALLER names is never swapped this way on
+ *    `AI.generate` — it is refused with a 400 `MODEL_NOT_AVAILABLE` instead.
+ *  - `provider-unavailable`: the requested model's provider failed transiently and a fallback leg served.
+ */
+declare interface AiGenerateModelFallback {
+    requestedModel: string;
+    servedModel: string;
+    reason: 'not-approved' | 'provider-unavailable';
+}
+
 /**
  * Wire-format output from `AI.generate` / `POST .../generate`.
  * Fields mirror AI SDK `GenerateTextResult` — uses AI SDK types where exported.
@@ -627,8 +1326,29 @@ export declare interface AiGenerateOutput {
     output?: unknown;
     /** Provider warnings (e.g. unsupported settings) — AI SDK `CallWarning[]` */
     warnings?: CallWarning[];
+    /**
+     * The model that actually produced `text` (`provider/model`). Present on every response from builds that
+     * report it; absent only from older servers.
+     */
+    model?: string;
+    /** Present only when `model` is NOT the model the call resolved to — see {@link AiGenerateModelFallback}. */
+    modelFallback?: AiGenerateModelFallback;
 }
 
+/**
+ * Reasoning options for `AI.generate` — the same shape and semantics as an agent's
+ * `modelSettings.reasoning` (and the chat request's `options.reasoning`):
+ *
+ * - `effort` — `'off' | 'minimal' | 'low' | 'medium' | 'high' | 'max'`, translated per
+ *   provider (Anthropic `thinking`, OpenAI `reasoningEffort`, Gemini `thinkingConfig`, …)
+ *   and clamped to the levels the served model supports, exactly as on an agent turn.
+ *   Unset = the model's catalog default.
+ * - `show` — whether the reasoning trace is returned. `false` asks the provider to omit
+ *   its summaries AND drops `reasoning` / `reasoningText` from the response (the token
+ *   count stays on `usage.reasoningTokens`). Default `true`.
+ */
+export declare type AiGenerateReasoningOptions = ModelReasoningOptions;
+
 /**
  * URL source from Google Search grounding.
  * Mirrors `LanguageModelV2Source` (AI SDK `Source` type — not exported from `ai` as of v5).
@@ -751,6 +1471,14 @@ export declare interface ApprovalOptions {
     fourEyes?: WorkflowFourEyes;
     /** default 168; a binding is resolved at suspend time and must yield 1..720 */
     timeoutHours?: number | TemplateBinding;
+    /**
+     * Re-send the approval push to the approvers who have not decided yet, every `remindAfterHours` hours while the
+     * approval is pending — at most 3 reminders per ask (an escalation hop starts a new ask), and never after the
+     * deadline. A plain number in 1..720 (no binding); a value at or above a numeric `timeoutHours` never fires (a
+     * push warning). Absent ⇒ no reminder. Reminders ride the approval push, so they reach the approvers an agent's
+     * approval routing names (Settings → Approvals); they are sent on the platform's sweep cadence.
+     */
+    remindAfterHours?: number;
     /** 'deny' (default) | 'cancel-run' | 'fail' | a chain of ≤ 3 hops ending in one terminal member */
     onTimeout?: WorkflowSuspendTimeoutChain;
     /** default 'continue' (denial is data unless 'fail') */
@@ -1060,7 +1788,7 @@ export declare enum BasketStatus {
  * Per-agent message batching/debounce configuration.
  * Overrides platform-wide env var defaults for this specific agent.
  */
-declare interface BatchingConfig {
+export declare interface BatchingConfig {
     /** Hold first message N ms before processing, to allow rapid follow-ups to batch together. 0 = disabled. */
     firstMessageDelayMs?: number;
     /** Window to collect subsequent messages while one is in-flight (ms). 0 = batching disabled. */
@@ -1089,7 +1817,7 @@ declare interface BatchingConfig {
  * local browser (desktop) or the Browser-Use cloud fallback. The object form
  * adds optional policy.
  */
-declare interface BrowserSwitchConfig {
+export declare interface BrowserSwitchConfig {
     /** Preferred engine; 'auto' lets the platform pick local (desktop) vs cloud. */
     engine?: 'auto' | 'browser-use' | 'agent-browser';
     /** Egress allowlist — domains the browser may navigate/sub-request. */
@@ -1175,10 +1903,6 @@ export declare const CDN: {
     get(fileId: string): Promise<File>;
 };
 
-/**
- * Lua Runtime Interfaces
- * Request-level runtime information available in the execution sandbox
- */
 /**
  * Channel type.
  * Represents the communication channel through which a request originated.
@@ -1310,6 +2034,25 @@ export declare interface ChannelsApi {
          * ```
          */
         sendReaction(input: WhatsAppReactionSendInput): Promise<ChannelSendOutput>;
+        /**
+         * Ask a WhatsApp user to share their phone number. WhatsApp shows `text`
+         * with a share button. If they tap it, their own number is saved on their
+         * profile (when it has none) and is in `user._luaProfile.mobileNumbers`
+         * on that same turn. Users who hide their number behind a WhatsApp
+         * username otherwise reach you without one.
+         *
+         * Needs an open 24h window (the user wrote in the last 24 hours); a
+         * closed window throws. Declining sends nothing back.
+         *
+         * @example
+         * ```typescript
+         * await Channels.whatsapp.requestPhoneNumber({
+         *   to: { userId: user._luaProfile.userId },
+         *   text: 'Please share your phone number so we can confirm you are registered.',
+         * });
+         * ```
+         */
+        requestPhoneNumber(input: WhatsAppPhoneRequestInput): Promise<ChannelSendOutput>;
     };
     /** Email-specific send operations. */
     email: {
@@ -1369,6 +2112,11 @@ export declare interface ChannelSendInput {
 export declare interface ChannelSendOptions {
     /** Pin a specific channel config (must belong to the sending agent). */
     channelIdentifier?: string;
+    /**
+     * Send even while a staff member holds the conversation. By default a held
+     * conversation refuses proactive sends with 409 `CONVERSATION_HELD`.
+     */
+    ignoreHold?: boolean;
     /** WhatsApp-specific send options. */
     whatsapp?: {
         /**
@@ -1432,12 +2180,16 @@ export declare interface ChannelSendOutput {
  * - slack: `Lua.request.conversation.externalId` (`T…:A…:C…[:threadTs]`), a
  *   channel id (`C…`, top level), `C…:threadTs` (a reply in that thread), a
  *   member id (`U…`, their DM with the bot) or 2–8 member ids (`U…,U…`, a group
- *   DM). The bot must be in the channel. */
+ *   DM). The bot must be in the channel.
+ *
+ * `identity` names one of the agent's users by a channel id, as `Lua.request.sender`
+ * gives it: a `whatsapp_bsuid` on whatsapp, a `slack_user` on slack. */
 export declare interface ChannelSendTarget {
     userId?: string;
     phoneNumber?: string;
     email?: string;
     conversationId?: string;
+    identity?: UserIdentityRef;
 }
 
 /**
@@ -1542,6 +2294,105 @@ export declare interface ChatHistoryMessage {
  */
 export declare type ChatMessage = TextMessage | ImageMessage | FileMessage;
 
+/** wave 2 U33 — the typed refusal `Integrations.checkAsUser` raises outside a live chat turn. */
+export declare function checkAsUserRequiresUser(): Error;
+
+/**
+ * U6 (wave 2) — connection inspection, account pinning and capability checks; U33 — the same checks run
+ * with the CONVERSATION USER's principal. Owner: U6 (catalogue, list, pin, check, cleanup); U33 owns only
+ * `checkAsUser`. Contract: docs/agent-builder/wave2-contracts.md §U6, §U33.
+ *
+ * The check catalogue is SERVER-OWNED (lua-api `services/connection-checks/`): a caller can only NAME a
+ * check; the probe, its request and its interpretation live on the server. Results are a fixed enum
+ * plus SAFE metadata (account identity, counts) — never a provider body.
+ */
+declare const CONNECTION_CHECK_RESULTS: readonly ["ok", "unauthorized", "insufficient_scope", "not_found", "unreachable", "unsupported"];
+
+/** u21 doc §5.1 — the request row's state machine (transition table in §6.3). */
+declare const CONNECTION_REQUEST_STATES: readonly ["pending", "opened", "authorizing", "remote_created", "finalizing", "connected", "identity_mismatch", "declined", "expired", "cancelled", "exhausted", "manual_review"];
+
+/**
+ * A check id. `identity` exists for every catalogued integration; the rest are per integration
+ * ({@link CONNECTION_CHECK_CATALOGUE_V1}). An uncatalogued pair answers `unsupported`, never an error.
+ */
+declare type ConnectionCheckName = 'identity' | (string & {});
+
+declare interface ConnectionCheckOptions {
+    /** Required (`true`) for a `reversible-write` catalogue entry; refused otherwise. */
+    allowWrite?: boolean;
+}
+
+declare interface ConnectionCheckOutcome {
+    connectionId: string;
+    integrationType: string;
+    check: ConnectionCheckName;
+    result: ConnectionCheckResult;
+    /** ISO. */
+    checkedAt: string;
+    metadata?: ConnectionCheckSafeMetadata;
+    /** Present only for a `reversible-write` check: `pending` ⇒ a leftover is queued for cleanup retry. */
+    cleanup?: 'done' | 'pending';
+}
+
+declare type ConnectionCheckResult = (typeof CONNECTION_CHECK_RESULTS)[number];
+
+/** The ONLY metadata a check may return (allow-listed fields; no provider body, ever). */
+declare interface ConnectionCheckSafeMetadata {
+    accountEmail?: string;
+    accountId?: string;
+    accountName?: string;
+    /** Small named counts, e.g. `{ teams: 3 }`. */
+    counts?: Record<string, number>;
+    /** Unified scope names the probe found missing (`insufficient_scope`). */
+    missingScopes?: string[];
+}
+
+declare interface ConnectionHandoverResult {
+    agentId: string;
+    connectionId: string;
+    integration: string;
+    status: 'assigned';
+}
+
+/** `Integrations.requestConnection(...)` (u21 doc §15.2). The agent id comes from the runtime credential. */
+export declare interface ConnectionRequestCreateInput {
+    integrationType: string;
+    invitee: {
+        email: string;
+    };
+    scopes?: string[];
+    /** Default false. */
+    unattended?: boolean;
+    /** Default 72, max 168. */
+    expiresInHours?: number;
+}
+
+declare type ConnectionRequestHolderClass = 'member' | 'nonmember';
+
+declare type ConnectionRequestKind = 'connect' | 'reconnect';
+
+export declare type ConnectionRequestState = (typeof CONNECTION_REQUEST_STATES)[number];
+
+/** What the requester (SDK, CLI, Desktop card) may read — never the token, never the hosted URL. */
+export declare interface ConnectionRequestStatus {
+    requestId: string;
+    kind: ConnectionRequestKind;
+    agentId: string;
+    integrationType: string;
+    state: ConnectionRequestState;
+    /** A display label for the invitee (name, else the email's local part). */
+    inviteeLabel: string;
+    holderClass: ConnectionRequestHolderClass;
+    unattended: boolean;
+    /** ISO. */
+    expiresAt: string;
+    /** Present once `connected`. */
+    connectionId?: string;
+    /** Present once `connected`: the remote identity the holder signed in with. */
+    connectedAs?: string;
+    lastErrorCode?: string;
+}
+
 /**
  * A container arm: a `StepRef` — a `createStep` object, or a string naming an entry declared elsewhere in the chain
  * (`agentStep` / `specialistStep` / `toolStep` / `workflow`, and since LUA-684 `approval` / `waitForSignal`, so an
@@ -1713,12 +2564,25 @@ declare interface CustomDataAPI {
      * @returns Promise resolving to update response
      */
     update(collectionName: string, entryId: string, data: Record<string, any>, optionsOrSearchText?: string | CreateCustomDataOptions): Promise<UpdateCustomDataResponse>;
-    /** Atomically sets and removes top-level entry fields and optionally changes search text. */
+    /**
+     * Atomically sets and removes top-level entry fields and optionally changes search text.
+     * `options.ifVersion` makes it a compare-and-swap: a stale version rejects with
+     * `code === 'data_version_conflict'` (409) and writes nothing.
+     */
     patch(collectionName: string, entryId: string, mutation: {
         set?: Record<string, any>;
         unset?: string[];
         searchText?: string | null;
+    }, options?: {
+        ifVersion?: number;
     }): Promise<UpdateCustomDataResponse>;
+    /**
+     * Atomically adds `by` (default 1) to a top-level numeric field and resolves the new value.
+     * A missing field starts at 0; `options.upsert` creates a missing entry under `entryId`.
+     */
+    increment(collectionName: string, entryId: string, field: string, by?: number, options?: {
+        upsert?: boolean;
+    }): Promise<number>;
     /**
      * Performs vector search on a collection.
      * @param collectionName - Collection name
@@ -1758,6 +2622,12 @@ declare interface CustomDataEntry extends IdentifiedEntity, TimestampedEntity {
     createdAt: number;
     updatedAt: number;
     searchText?: string;
+    /**
+     * Write counter for compare-and-swap (LUA-963): pass it back as
+     * `Data.patch(c, id, mutation, { ifVersion })`. Every write bumps it;
+     * entries not written since versioning was introduced report 0.
+     */
+    version?: number;
 }
 
 /**
@@ -1863,6 +2733,74 @@ export declare const Data: {
      * @returns Promise resolving to update response
      */
     update(collectionName: string, entryId: string, data: Record<string, any>, optionsOrSearchText?: string | CreateCustomDataOptions): Promise<UpdateCustomDataResponse>;
+    /**
+     * Atomically sets and removes top-level fields of an entry in ONE write (no
+     * read-merge), optionally changing its search text.
+     *
+     * Compare-and-swap: pass `{ ifVersion }` to apply the patch only if nobody
+     * wrote the entry since you read it. Every entry carries a `version`
+     * (`entry.version` from `Data.get`, `entry._version` on the instance from
+     * `Data.getEntry` / `Data.create`) that every write bumps. On a mismatch
+     * nothing is written and the call rejects with an error whose
+     * `code === 'data_version_conflict'` (`status` 409, plus `currentVersion`
+     * and `expectedVersion`): re-read and retry. A present `ifVersion` that is
+     * not a non-negative integer (even `undefined`) throws a TypeError and
+     * sends nothing; omit the key for an unconditional patch. A CAS patch is
+     * sent once (not retried), so after a network error re-read the entry to
+     * see whether it landed.
+     *
+     * ```typescript
+     * const entry = await Data.getEntry('seats', seatId);
+     * if (entry.data.heldBy) return 'taken';
+     * try {
+     *   await Data.patch('seats', seatId, { set: { heldBy: userId } }, { ifVersion: entry._version });
+     * } catch (error: any) {
+     *   if (error?.code === 'data_version_conflict') return 'taken'; // someone else won
+     *   throw error;
+     * }
+     * ```
+     *
+     * @param collectionName - Name of the collection
+     * @param entryId - ID of the entry
+     * @param mutation - `{ set?, unset?, searchText? }` (`searchText: null` clears it)
+     * @param options - `{ ifVersion? }` for compare-and-swap
+     * @returns Promise resolving to `{ status, message, version }` (`version` = the entry's new version)
+     */
+    patch(collectionName: string, entryId: string, mutation: {
+        set?: Record<string, any>;
+        unset?: string[];
+        searchText?: string | null;
+    }, options?: PatchCustomDataOptions): Promise<UpdateCustomDataResponse>;
+    /**
+     * Atomically adds `by` (default 1; negative and fractional amounts allowed)
+     * to a top-level numeric field and resolves the field's NEW value. Safe
+     * under concurrency: unlike `get` + `update`, simultaneous increments
+     * never lose a count. A missing field starts at 0.
+     *
+     * ```typescript
+     * const views = await Data.increment('stats', 'homepage', 'views');
+     * await Data.increment('stock', sku, 'available', -1);
+     * // Daily counter: one long-lived entry, one field per day (a missing field starts at 0).
+     * await Data.increment('stats', 'calls', `day-${today}`);
+     * ```
+     *
+     * Errors: 404 when the entry does not exist (unless `upsert`), 400 when the
+     * field holds a non-number. `upsert` is NOT safe for an entry many
+     * conversations may create at once: concurrent first-time upserts of the
+     * same new id can create duplicate entries, and the count in one of them is
+     * lost. Do not upsert a fresh id per day or per event under load; create the
+     * entry once from a non-concurrent path, then increment it.
+     * The SDK sends the request once and does not retry it, so a network
+     * failure means the increment may or may not have been applied.
+     *
+     * @param collectionName - Name of the collection
+     * @param entryId - ID of the entry (the id to create under when upserting)
+     * @param field - Top-level field name (no dots, no `$` prefix)
+     * @param by - Amount to add (default 1)
+     * @param options - `{ upsert? }`
+     * @returns Promise resolving to the field's value after the increment
+     */
+    increment(collectionName: string, entryId: string, field: string, by?: number, options?: IncrementCustomDataOptions): Promise<number>;
     /**
      * Performs vector search on a collection.
      *
@@ -1893,6 +2831,12 @@ export declare class DataEntryInstance {
     id: string;
     collectionName: string;
     score?: number;
+    /**
+     * The entry's write version for compare-and-swap (LUA-963):
+     * `entry.patch(m, { ifVersion: entry._version })`. Underscored so it never
+     * shadows a user `data.version` field through the property proxy.
+     */
+    _version: number;
     private customDataAPI;
     [key: string]: any;
     /**
@@ -1916,10 +2860,18 @@ export declare class DataEntryInstance {
      * @throws Error if the update fails
      */
     update(data: Record<string, any>, searchText?: string): Promise<Record<string, any>>;
+    /**
+     * Atomically sets/unsets fields. `options.ifVersion` makes it a
+     * compare-and-swap (pass `entry._version`); a stale version rejects with
+     * `code === 'data_version_conflict'` (status 409) and leaves the entry (and
+     * this instance) unchanged.
+     */
     patch(mutation: {
         set?: Record<string, any>;
         unset?: string[];
         searchText?: string | null;
+    }, options?: {
+        ifVersion?: number;
     }): Promise<Record<string, any>>;
     unset(...fields: string[]): Promise<Record<string, any>>;
     /**
@@ -2325,6 +3277,219 @@ export { EnvRefBinding }
 
 export declare const eq: <T>(l: TypedRef<T>, r: TypedRef<T> | Literal<T>) => LuaPredicate;
 
+/** DOC3 §4.3 — deterministic check kinds (`side_effect` / `no_side_effect` / `no_log_errors` are Phase 2). */
+declare const EVAL_CHECK_KINDS: readonly ["contains", "regex", "not_contains", "not_regex", "tool_called", "tool_not_called", "tool_args", "max_latency_ms", "no_log_errors", "side_effect", "no_side_effect", "finish_reason"];
+
+declare const EVAL_SUITE_RUN_STATUSES: readonly ["queued", "running", "completed", "failed", "cancelled", "budget_exhausted"];
+
+declare type EvalCase = EvalConversationCase | EvalEventCase;
+
+declare interface EvalCaseResult {
+    caseId: string;
+    status: EvalCaseStatus;
+    checks: Array<{
+        kind: string;
+        passed: boolean;
+        detail?: string;
+    }>;
+    judge?: {
+        score: number;
+        passed: boolean;
+        reasoning?: string;
+    };
+    turns: number;
+    durationMs?: number;
+    credits?: number;
+    holdout?: boolean;
+}
+
+declare type EvalCaseStatus = 'pending' | 'passed' | 'failed' | 'error' | 'skipped';
+
+/** `evalCaseTranscripts` (agents DB, 30-day TTL) — what the transcript route returns. */
+declare interface EvalCaseTranscript {
+    runId: string;
+    caseId: string;
+    agentId: string;
+    turns: EvalTranscriptTurn[];
+    judge?: {
+        score: number;
+        passed: boolean;
+        reasoning?: string;
+    };
+    error?: string;
+    holdout?: boolean;
+    /** Always true until the U19 scrubber lands: bodies are stored through `redactTranscript` (DOC3 §4.6). */
+    redacted: boolean;
+}
+
+/** One check. Fields beyond `kind` are per kind (DOC3 §4.2 examples); the parser validates them. */
+declare interface EvalCheck {
+    kind: EvalCheckKind;
+    [field: string]: unknown;
+}
+
+declare type EvalCheckKind = (typeof EVAL_CHECK_KINDS)[number];
+
+declare interface EvalConversationCase {
+    id: string;
+    kind: 'conversation';
+    turns?: Array<{
+        role: 'user' | 'assistant';
+        content: string;
+    }>;
+    simulatedUser?: {
+        persona: string;
+        goal: string;
+        stopWhen: string;
+        maxTurns: number;
+    };
+    checks: EvalCheck[];
+    rubric?: EvalRubric;
+    toolDoubles?: EvalToolDouble[];
+    tags?: string[];
+}
+
+declare interface EvalEventCase {
+    id: string;
+    kind: 'event';
+    fire: {
+        trigger: string;
+    } | {
+        job: string;
+    } | {
+        workflow: string;
+    } | {
+        webhook: string;
+    };
+    payload: unknown;
+    checks: EvalCheck[];
+    rubric?: EvalRubric;
+    toolDoubles?: EvalToolDouble[];
+}
+
+declare interface EvalRubric {
+    text: string;
+    /** 0..1; default the suite's judge threshold (default 0.7). */
+    threshold?: number;
+}
+
+declare interface EvalRunReceipt {
+    runId: string;
+    estimate: {
+        credits: number;
+        cases: number;
+    };
+}
+
+/** `evalSuites` (agents DB), one per `(agentId, key)`. Only the OWNER writes the `live*` lists. */
+declare interface EvalSuite {
+    id: string;
+    agentId: string;
+    key: string;
+    revision: number;
+    source: EvalSuiteSource;
+    minPassRate: number;
+    judge: {
+        model?: string;
+        threshold: number;
+    };
+    budget: {
+        maxCredits: number;
+        maxTurnsPerCase: number;
+        maxCases: number;
+    };
+    toolDoubles: EvalToolDouble[];
+    liveSkills: string[];
+    liveBuiltins: string[];
+    liveAgentTools: string[];
+    monitors: EvalSuiteMonitor[];
+    cases: EvalCase[];
+    updatedBy: string;
+}
+
+/** DOC3 §4.9 — a suite monitor (template `EvalSetMonitor` + `appliesTo` / `threshold`). */
+declare interface EvalSuiteMonitor {
+    key: string;
+    title: string;
+    rubric: string;
+    samplingRate: number;
+    appliesTo: Array<'chat' | 'workflow' | 'trigger' | 'job'>;
+    threshold: number;
+}
+
+declare type EvalSuiteRunStatus = (typeof EVAL_SUITE_RUN_STATUSES)[number];
+
+/** `evalSuiteRuns` (agents DB) — what `Evals.runs(id).get` returns (no transcripts). */
+declare interface EvalSuiteRunSummary {
+    id: string;
+    agentId: string;
+    suiteKey: string;
+    suiteRevision: number;
+    version: number;
+    sourceDigest?: string;
+    /** U11 session, when the run used one. */
+    testSessionId?: string;
+    /** `user:<id>` | `apiKey:<id>` | `service:agent:<id>`. */
+    initiatedBy: string;
+    status: EvalSuiteRunStatus;
+    budget: {
+        maxCredits: number;
+        reserved: number;
+        spent: {
+            credits: number;
+            agentCredits: number;
+            judgeCredits: number;
+            simulatorCredits: number;
+        };
+    };
+    cases: EvalCaseResult[];
+    passRate?: number;
+    passed?: boolean;
+    /**
+     * Why a run stopped early when it was not the run budget: `EVAL_MONTHLY_CAP_REACHED` (the agent's
+     * monthly allowance ran out mid-run) or `EVAL_CAP_UNAVAILABLE` (the cap store was down; fail closed).
+     * Absent for plain per-run `budget_exhausted`.
+     */
+    error?: string;
+    startedAt?: string;
+    finishedAt?: string;
+}
+
+declare type EvalSuiteSource = {
+    kind: 'agent';
+} | {
+    kind: 'template';
+    templateId: string;
+    evalSetRevision: number;
+} | {
+    kind: 'builder';
+    projectId: string;
+};
+
+/** Shape of `agent-template.eval-set.schema.ts` `EvalSetToolDouble` (reused, not redefined). */
+declare interface EvalToolDouble {
+    tool: string;
+    server?: string;
+    kind?: 'mcp' | 'skill' | 'builtin';
+    result: unknown;
+    /** When set, the double returns an isError result with this text (template `EvalSetToolDouble.error`). */
+    error?: string;
+}
+
+/** One recorded turn of a case transcript. */
+declare interface EvalTranscriptTurn {
+    role: 'user' | 'assistant';
+    content: string;
+    /** `script` for a scripted turn, `simulator` for a simulated-user message, `agent` for a reply. */
+    source: 'script' | 'simulator' | 'agent';
+    toolCalls?: Array<{
+        name: string;
+        input?: string;
+    }>;
+    latencyMs?: number;
+    finishReason?: string;
+}
+
 export declare const exists: (ref: TypedRef<unknown>) => LuaPredicate;
 
 export declare const falsy: (ref: TypedRef<unknown>) => LuaPredicate;
@@ -2410,7 +3575,7 @@ declare interface GetJobsResponseData {
  * platform resolves it from the `GOVERNANCE_API_KEY` env var. This
  * keeps secrets out of MongoDB, support logs, and backups.
  */
-declare interface GovernanceConfig {
+export declare interface GovernanceConfig {
     mode: 'sdk' | 'api';
     /**
      * SDK mode — a named governance-sdk preset composed as the base rule set. The platform builder
@@ -2584,6 +3749,15 @@ declare abstract class HttpClient {
      * @protected
      */
     protected httpPatch<T>(url: string, data?: any, headers?: Record<string, string>): Promise<ApiResponse<T>>;
+    /**
+     * Performs one HTTP PATCH attempt (no client retry).
+     *
+     * For a conditional write whose retry is not safe: a compare-and-swap PATCH
+     * (`Data.patch(..., { ifVersion })`, LUA-963) that landed but lost its
+     * response would, on retry, find the version already bumped and report a
+     * false conflict. An ambiguous failure surfaces instead.
+     */
+    protected httpPatchOnce<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`).
      *
@@ -2633,6 +3807,8 @@ declare interface ImmutableUserProfile {
     fullName: string;
     mobileNumbers: string[];
     emailAddresses: string[];
+    /** The person's channel ids (WhatsApp, Slack, ...). Absent when they could not be loaded. */
+    identities?: UserIdentity[];
 }
 
 /**
@@ -2701,6 +3877,12 @@ declare interface InboxPushReceipt {
     reason?: string;
 }
 
+/** Options for `Data.increment` (LUA-963). */
+export declare interface IncrementCustomDataOptions {
+    /** Create the entry (`data: { [field]: by }`) under the given id if it does not exist. Default false. */
+    upsert?: boolean;
+}
+
 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;
@@ -2708,8 +3890,91 @@ export declare const inSet: <T extends string | number | boolean | null>(v: Type
 /** HTTP methods the passthrough relay accepts. */
 declare const INTEGRATION_PASSTHROUGH_METHODS: readonly ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD"];
 
+declare type IntegrationConnectionStatus = 'active' | 'paused' | 'unhealthy' | 'needs_reconnect';
+
+/** One row of `Integrations.list()` / `Agents.integrations(id).list()`: a connection VISIBLE to the agent. */
+declare interface IntegrationConnectionSummary {
+    connectionId: string;
+    integrationType: string;
+    displayName?: string;
+    /** Remote account identity as captured at finalize or by the last `identity` check. */
+    account?: {
+        email?: string;
+        id?: string;
+        name?: string;
+    };
+    /** Provider-granted unified scopes (`grantedScopes`), else the requested filter. */
+    scopes: string[];
+    status: IntegrationConnectionStatus;
+    owner: {
+        type: 'agent' | 'user' | 'org';
+        userId?: string;
+    };
+    /** Agents the connection is mounted on that the CALLER may know about (same org). */
+    agentIds: string[];
+    /** U2 (d): `check-only` mounts are listed but not usable as tools. */
+    mount?: 'tools' | 'check-only';
+}
+
+/**
+ * LUA-860 — the typed members `IntegrationPassthroughError` carries beside `message`: the fields lua-api serves on a
+ * route-level refusal of `Integrations.passthrough` (`ApiResponse.error`), copied APPEND-ONLY — a member absent on the
+ * wire is absent on the error, never `undefined`-valued — so skill code branches on `code` (and, for one release,
+ * `legacyCode`) on the in-process path (`lua test`, `lua dev`, the api-exports `Integrations` namespace) exactly as it
+ * does on the production runtime. Parity is complete (LUA-862, #2737, commit 90f05540b — in the lua-cli@3.33.0 tree;
+ * this comment corrected under BAC-551): every production hop relays the same members append-only — lua-core's
+ * `callInternalUnifiedPassthrough` (`unified-passthrough.tool.ts`, via `pickVendorFaultRelayFields` in
+ * `vendor-fault-relay.ts`), the seam envelope (`InternalSandboxSeamController.run` on the fast / worker planes and
+ * `sandbox-passthrough.controller.ts` on the Job tier), the remote-runner bridge (`lua-sandbox-runner/src/executor/
+ * bridge-deps.ts`, the `seamFetch` rebuild) and the Job pod (`lua-workflow-job/src/protocol-client.ts` +
+ * `code-step-ipc.ts`) — so `retryAfterSeconds` / `vendor` / `vendorStatus` / `requestId` are identical on the
+ * in-process path and the production routing, and "absent on the wire ⇒ absent on the error" holds at every hop (a
+ * withheld `retryAfterSeconds` is lua-api's unsafe-to-retry marker, never defaulted). The class is not on the public
+ * `lua-cli` surface — skill code duck-types on `name === 'IntegrationPassthroughError'` and `code`. Before this, the
+ * in-process path threw a bare `Error(message)`: no `code` could reach skill code, so a shipped 3.32.x client could
+ * only be steered server-side through the message text (the LUA-826 `(503 Service Unavailable)` suffix — the shim
+ * this replaces).
+ */
+export declare interface IntegrationPassthroughErrorFields {
+    /**
+     * The server's discriminator — `VENDOR_UNAVAILABLE` (503, the vendor behind the relay failed: transient) ·
+     * `VENDOR_REJECTED` (422, the vendor refused the request as sent: deterministic) · `passthrough_disabled` ·
+     * `passthrough_no_connection` · `passthrough_rate_limited` · `passthrough_invalid_request` · … Absent when the
+     * server served none, or the request never reached it.
+     */
+    code?: string;
+    /** lua-api's own HTTP status; `0` for a transport failure (no answer / timeout). Never the vendor's: that is `vendorStatus`. */
+    statusCode?: number;
+    /** Alias of `statusCode` — the member lua-core's production `IntegrationPassthroughError` exposes under that name. */
+    status?: number;
+    /**
+     * LUA-826, ONE release: the code a vendor-fault site served before it moved to `VENDOR_UNAVAILABLE`
+     * (`passthrough_upstream_error`) and the line it served under it. Branch on `code`; these exist for skill code that
+     * still greps the old string, and go away the release after.
+     */
+    legacyCode?: string;
+    legacyMessage?: string;
+    /**
+     * Seconds to wait before retrying. On a 503 `VENDOR_UNAVAILABLE`: present ONLY when the server says a blind retry is
+     * safe — a read, or a write whose duplicate is inert. On a 429 `passthrough_rate_limited` (LUA-968): always present —
+     * the seconds left in the caller's shared per-minute window (also served as the `Retry-After` header).
+     */
+    retryAfterSeconds?: number;
+    /** The third-party vendor behind the fault (`unified` | `github` | `google` | …) and its own status when it answered. */
+    vendor?: string;
+    vendorStatus?: number;
+    /** The id on the server's matching error log line — the one to quote. */
+    requestId?: string;
+}
+
 export declare type IntegrationPassthroughMethod = (typeof INTEGRATION_PASSTHROUGH_METHODS)[number];
 
+/** `Integrations.passthrough(type, request, options)` — the third argument (U6 pin). */
+declare interface IntegrationPassthroughPinOptions {
+    /** Use exactly this connection (it must be visible to the agent); the server pin in `pickConnection`. */
+    connectionId?: string;
+}
+
 /**
  * One raw provider API call, relative to the provider's API base URL
  * (e.g. `repos/{owner}/{repo}/pulls/42/files` against GitHub).
@@ -2786,7 +4051,86 @@ export declare interface IntegrationsApi {
      * });
      * ```
      */
-    passthrough(integrationType: string, request: IntegrationPassthroughRequest): Promise<IntegrationPassthroughResponse>;
+    passthrough(integrationType: string, request: IntegrationPassthroughRequest, 
+    /**
+     * `{ connectionId }` pins one connection (from {@link IntegrationsApi.list}) when the agent has several of
+     * the same type. The pin must be a connection this agent may use: it narrows the choice, never widens it.
+     */
+    options?: IntegrationPassthroughPinOptions): Promise<IntegrationPassthroughResponse>;
+    /**
+     * The connections visible to this agent: integration type, remote account identity, scopes, status,
+     * owner and the agents (of your organization) each one is mounted on. A personal connection is listed
+     * only for the person it belongs to.
+     *
+     * @example
+     * ```typescript
+     * const gmail = (await Integrations.list()).filter((c) => c.integrationType === 'googlemail');
+     * ```
+     */
+    list(): Promise<IntegrationConnectionSummary[]>;
+    /**
+     * Run one platform-owned check on a visible connection: `identity` exists for every catalogued
+     * integration; others are per integration (`mail.list`, `teams.list`, `issue.create-permission`,
+     * `refund.calculate`, …). The answer is a fixed `result` (`ok` | `unauthorized` | `insufficient_scope`
+     * | `not_found` | `unreachable` | `unsupported`) plus safe metadata (account email/id, counts) — never a
+     * provider body. A check that writes and then undoes (`mail.draft-create-delete`) runs only with
+     * `{ allowWrite: true }`.
+     *
+     * @example
+     * ```typescript
+     * const { result, metadata } = await Integrations.check(gmail.connectionId, 'identity');
+     * ```
+     */
+    check(connectionId: string, check: ConnectionCheckName, options?: ConnectionCheckOptions): Promise<ConnectionCheckOutcome>;
+    /**
+     * Run one server-owned catalogue check (`identity`, `mail.list`, …) on a connection the CONVERSATION USER
+     * owns, with that user as the principal. The answer is a fixed result enum (`ok`, `unauthorized`,
+     * `insufficient_scope`, `not_found`, `unreachable`, `unsupported`) plus safe metadata — never a provider body.
+     *
+     * Only during a chat turn with a live user: jobs, triggers, webhooks, workflows and background turns throw
+     * `connection_check_requires_user`; a connection the user does not own throws `connection_check_not_owner`.
+     * Read checks only. Every call is audited on the agent's logs. Off unless the platform enables
+     * `LUA_CONNECTION_CHECK_AS_USER_ENABLED` (`connection_checks_disabled`).
+     *
+     * Offline (`lua test`) there is no live user, so it always throws `connection_check_requires_user`.
+     *
+     * @example
+     * ```typescript
+     * const outcome = await Integrations.checkAsUser(connectionId, 'identity');
+     * if (outcome.result !== 'ok') return `Your connection needs attention: ${outcome.result}`;
+     * ```
+     */
+    checkAsUser(connectionId: string, check: string): Promise<ConnectionCheckOutcome>;
+    /**
+     * Ask someone else to connect their account to THIS agent. The invitee gets the link from Lua (never from
+     * your code): this returns the request's id, state and expiry only — never a token or URL. Refused off a
+     * user's own turn (a job, webhook, trigger, workflow or `Agents.invoke` call) with `REQUESTER_UNAUTHORIZED`.
+     * Failures throw an `Error` with `name === 'ConnectionRequestError'` and the server's `code`.
+     *
+     * @example
+     * ```typescript
+     * const { requestId } = await Integrations.requestConnection({
+     *   integrationType: 'googlemail',
+     *   invitee: { email: 'ceo@acme.io' },
+     *   expiresInHours: 72, // 1..168, default 72
+     * });
+     * ```
+     */
+    requestConnection(input: ConnectionRequestCreateInput): Promise<{
+        requestId: string;
+        state: ConnectionRequestState;
+        expiresAt: string;
+    }>;
+    /** Ask the holder of a delegated connection to reconnect it (e.g. after its token was revoked). */
+    requestReconnect(connectionId: string): Promise<{
+        requestId: string;
+        state: ConnectionRequestState;
+        expiresAt: string;
+    }>;
+    /** Read one of this agent's connection requests. Never carries a token or URL. */
+    connectionRequest(requestId: string): Promise<ConnectionRequestStatus>;
+    /** Cancel a pending connection request. */
+    cancelConnectionRequest(requestId: string): Promise<void>;
 }
 
 /**
@@ -2805,7 +4149,10 @@ export declare interface InvokedBy {
     supervisor: boolean;
     /** The caller's supervision scopes on this agent (e.g. `supervision:act`); `[]` on preview turns. */
     scopes: string[];
-    /** Set when the caller passed `input.userId` to `Agents.invoke` (a delegated turn). */
+    /**
+     * Set when the caller passed `input.userId` to `Agents.invoke` (a delegated turn), and when the caller's own
+     * turn had such a user or ran in a Job / workflow run (the platform did not pick the user).
+     */
     delegatedUserId?: string;
 }
 
@@ -3043,6 +4390,17 @@ export declare class JobInstance {
     /** The active version of the job (if one exists) */
     readonly activeVersion?: JobVersion;
     metadata: Record<string, any>;
+    /**
+     * Per-run execution identity, set by the platform when the job runs. `occurrenceId` is the stable
+     * dedupe key across retries of the same fire; `scheduledTime` is set on scheduled fires only.
+     * Undefined when the platform did not supply it, so read it as `job.execution?.occurrenceId`.
+     */
+    execution?: {
+        executionId: string;
+        attempt: number;
+        occurrenceId: string;
+        scheduledTime?: string;
+    };
     private userApi?;
     constructor(jobApi: JobApi, jobData: Job);
     /**
@@ -4009,6 +5367,11 @@ export declare interface LuaRequest {
     userId?: string;
     /** The id of the agent handling this turn. */
     agentId?: string;
+    /**
+     * The organization the agent belongs to. Present on deployed runtimes that know it (absent offline in `lua test`
+     * and on older runtimes) — read it defensively.
+     */
+    orgId?: string;
     /**
      * The group conversation this turn belongs to, with its participants and the
      * current speaker. Undefined on 1:1 turns and on non-chat executions.
@@ -4020,6 +5383,12 @@ export declare interface LuaRequest {
      * `lua test`). Read it defensively — older runtimes do not set it.
      */
     invokedBy?: InvokedBy;
+    /**
+     * The channel identity that sent this message, e.g. `{ kind: 'whatsapp_bsuid', scope, value }` or a
+     * `slack_user`. Present only when Lua confirmed it belongs to this turn's user on this channel;
+     * absent on other channels, voice, jobs and webhooks. Match it against `user._luaProfile.identities`.
+     */
+    sender?: UserIdentityRef;
 }
 
 /**
@@ -4122,7 +5491,7 @@ export declare class LuaSkill {
  * Lua Skill configuration.
  * Used to initialize a new LuaSkill instance.
  */
-declare interface LuaSkillConfig {
+export declare interface LuaSkillConfig {
     /** Skill name (required; used as the server-side identifier). */
     name: string;
     /** Short description of the skill (1-2 sentences) */
@@ -4179,7 +5548,7 @@ export declare interface LuaTool<TInput extends ZodType = ZodType> {
  * voice: { say } }`. Tools that want to act differently inside a voice
  * call check for `ctx?.voice` and use the typed surface.
  */
-declare interface LuaToolCtx {
+export declare interface LuaToolCtx {
     /** LiveKit's tool-call id (voice only). */
     toolCallId?: string;
     /** Voice-runtime delegates. Only set when the tool runs over voice. */
@@ -4411,13 +5780,13 @@ declare const LuaVoiceConfigSchema: z.ZodEffects<z.ZodObject<{
     }, "strip", z.ZodTypeAny, {
         voice?: string;
         kind?: "inference";
-        options?: Record<string, unknown>;
         model?: string;
+        options?: Record<string, unknown>;
     }, {
         voice?: string;
         kind?: "inference";
-        options?: Record<string, unknown>;
         model?: string;
+        options?: Record<string, unknown>;
     }>, z.ZodObject<{
         kind: z.ZodLiteral<"plugin">;
         provider: z.ZodEnum<["deepgram", "elevenlabs"]>;
@@ -4431,13 +5800,13 @@ declare const LuaVoiceConfigSchema: z.ZodEffects<z.ZodObject<{
         options: z.ZodRecord<z.ZodString, z.ZodUnknown>;
     }, "strip", z.ZodTypeAny, {
         class?: "LLM" | "STT" | "STTv2" | "TTS";
-        provider?: "deepgram" | "elevenlabs";
         kind?: "plugin";
+        provider?: "deepgram" | "elevenlabs";
         options?: Record<string, unknown>;
     }, {
         class?: "LLM" | "STT" | "STTv2" | "TTS";
-        provider?: "deepgram" | "elevenlabs";
         kind?: "plugin";
+        provider?: "deepgram" | "elevenlabs";
         options?: Record<string, unknown>;
     }>, z.ZodObject<{
         kind: z.ZodLiteral<"realtime">;
@@ -4450,12 +5819,12 @@ declare const LuaVoiceConfigSchema: z.ZodEffects<z.ZodObject<{
          */
         options: z.ZodRecord<z.ZodString, z.ZodUnknown>;
     }, "strip", z.ZodTypeAny, {
-        provider?: "google" | "xai" | "openai";
         kind?: "realtime";
+        provider?: "openai" | "google" | "xai";
         options?: Record<string, unknown>;
     }, {
-        provider?: "google" | "xai" | "openai";
         kind?: "realtime";
+        provider?: "openai" | "google" | "xai";
         options?: Record<string, unknown>;
     }>]>;
     stt: z.ZodOptional<z.ZodDiscriminatedUnion<"kind", [z.ZodObject<{
@@ -4477,13 +5846,13 @@ declare const LuaVoiceConfigSchema: z.ZodEffects<z.ZodObject<{
     }, "strip", z.ZodTypeAny, {
         voice?: string;
         kind?: "inference";
-        options?: Record<string, unknown>;
         model?: string;
+        options?: Record<string, unknown>;
     }, {
         voice?: string;
         kind?: "inference";
-        options?: Record<string, unknown>;
         model?: string;
+        options?: Record<string, unknown>;
     }>, z.ZodObject<{
         kind: z.ZodLiteral<"plugin">;
         provider: z.ZodEnum<["deepgram", "elevenlabs"]>;
@@ -4497,13 +5866,13 @@ declare const LuaVoiceConfigSchema: z.ZodEffects<z.ZodObject<{
         options: z.ZodRecord<z.ZodString, z.ZodUnknown>;
     }, "strip", z.ZodTypeAny, {
         class?: "LLM" | "STT" | "STTv2" | "TTS";
-        provider?: "deepgram" | "elevenlabs";
         kind?: "plugin";
+        provider?: "deepgram" | "elevenlabs";
         options?: Record<string, unknown>;
     }, {
         class?: "LLM" | "STT" | "STTv2" | "TTS";
-        provider?: "deepgram" | "elevenlabs";
         kind?: "plugin";
+        provider?: "deepgram" | "elevenlabs";
         options?: Record<string, unknown>;
     }>, z.ZodObject<{
         kind: z.ZodLiteral<"realtime">;
@@ -4516,12 +5885,12 @@ declare const LuaVoiceConfigSchema: z.ZodEffects<z.ZodObject<{
          */
         options: z.ZodRecord<z.ZodString, z.ZodUnknown>;
     }, "strip", z.ZodTypeAny, {
-        provider?: "google" | "xai" | "openai";
         kind?: "realtime";
+        provider?: "openai" | "google" | "xai";
         options?: Record<string, unknown>;
     }, {
-        provider?: "google" | "xai" | "openai";
         kind?: "realtime";
+        provider?: "openai" | "google" | "xai";
         options?: Record<string, unknown>;
     }>]>>;
     tts: z.ZodOptional<z.ZodDiscriminatedUnion<"kind", [z.ZodObject<{
@@ -4543,13 +5912,13 @@ declare const LuaVoiceConfigSchema: z.ZodEffects<z.ZodObject<{
     }, "strip", z.ZodTypeAny, {
         voice?: string;
         kind?: "inference";
-        options?: Record<string, unknown>;
         model?: string;
+        options?: Record<string, unknown>;
     }, {
         voice?: string;
         kind?: "inference";
-        options?: Record<string, unknown>;
         model?: string;
+        options?: Record<string, unknown>;
     }>, z.ZodObject<{
         kind: z.ZodLiteral<"plugin">;
         provider: z.ZodEnum<["deepgram", "elevenlabs"]>;
@@ -4563,13 +5932,13 @@ declare const LuaVoiceConfigSchema: z.ZodEffects<z.ZodObject<{
         options: z.ZodRecord<z.ZodString, z.ZodUnknown>;
     }, "strip", z.ZodTypeAny, {
         class?: "LLM" | "STT" | "STTv2" | "TTS";
-        provider?: "deepgram" | "elevenlabs";
         kind?: "plugin";
+        provider?: "deepgram" | "elevenlabs";
         options?: Record<string, unknown>;
     }, {
         class?: "LLM" | "STT" | "STTv2" | "TTS";
-        provider?: "deepgram" | "elevenlabs";
         kind?: "plugin";
+        provider?: "deepgram" | "elevenlabs";
         options?: Record<string, unknown>;
     }>, z.ZodObject<{
         kind: z.ZodLiteral<"realtime">;
@@ -4582,12 +5951,12 @@ declare const LuaVoiceConfigSchema: z.ZodEffects<z.ZodObject<{
          */
         options: z.ZodRecord<z.ZodString, z.ZodUnknown>;
     }, "strip", z.ZodTypeAny, {
-        provider?: "google" | "xai" | "openai";
         kind?: "realtime";
+        provider?: "openai" | "google" | "xai";
         options?: Record<string, unknown>;
     }, {
-        provider?: "google" | "xai" | "openai";
         kind?: "realtime";
+        provider?: "openai" | "google" | "xai";
         options?: Record<string, unknown>;
     }>]>>;
     vad: z.ZodOptional<z.ZodString>;
@@ -4751,47 +6120,47 @@ declare const LuaVoiceConfigSchema: z.ZodEffects<z.ZodObject<{
     stt?: {
         voice?: string;
         kind?: "inference";
-        options?: Record<string, unknown>;
         model?: string;
+        options?: Record<string, unknown>;
     } | {
         class?: "LLM" | "STT" | "STTv2" | "TTS";
-        provider?: "deepgram" | "elevenlabs";
         kind?: "plugin";
+        provider?: "deepgram" | "elevenlabs";
         options?: Record<string, unknown>;
     } | {
-        provider?: "google" | "xai" | "openai";
         kind?: "realtime";
+        provider?: "openai" | "google" | "xai";
         options?: Record<string, unknown>;
     };
     volume?: number;
     llm?: {
         voice?: string;
         kind?: "inference";
-        options?: Record<string, unknown>;
         model?: string;
+        options?: Record<string, unknown>;
     } | {
         class?: "LLM" | "STT" | "STTv2" | "TTS";
-        provider?: "deepgram" | "elevenlabs";
         kind?: "plugin";
+        provider?: "deepgram" | "elevenlabs";
         options?: Record<string, unknown>;
     } | {
-        provider?: "google" | "xai" | "openai";
         kind?: "realtime";
+        provider?: "openai" | "google" | "xai";
         options?: Record<string, unknown>;
     };
     tts?: {
         voice?: string;
         kind?: "inference";
-        options?: Record<string, unknown>;
         model?: string;
+        options?: Record<string, unknown>;
     } | {
         class?: "LLM" | "STT" | "STTv2" | "TTS";
-        provider?: "deepgram" | "elevenlabs";
         kind?: "plugin";
+        provider?: "deepgram" | "elevenlabs";
         options?: Record<string, unknown>;
     } | {
-        provider?: "google" | "xai" | "openai";
         kind?: "realtime";
+        provider?: "openai" | "google" | "xai";
         options?: Record<string, unknown>;
     };
     vadOptions?: {
@@ -4845,47 +6214,47 @@ declare const LuaVoiceConfigSchema: z.ZodEffects<z.ZodObject<{
     stt?: {
         voice?: string;
         kind?: "inference";
-        options?: Record<string, unknown>;
         model?: string;
+        options?: Record<string, unknown>;
     } | {
         class?: "LLM" | "STT" | "STTv2" | "TTS";
-        provider?: "deepgram" | "elevenlabs";
         kind?: "plugin";
+        provider?: "deepgram" | "elevenlabs";
         options?: Record<string, unknown>;
     } | {
-        provider?: "google" | "xai" | "openai";
         kind?: "realtime";
+        provider?: "openai" | "google" | "xai";
         options?: Record<string, unknown>;
     };
     volume?: number;
     llm?: {
         voice?: string;
         kind?: "inference";
-        options?: Record<string, unknown>;
         model?: string;
+        options?: Record<string, unknown>;
     } | {
         class?: "LLM" | "STT" | "STTv2" | "TTS";
-        provider?: "deepgram" | "elevenlabs";
         kind?: "plugin";
+        provider?: "deepgram" | "elevenlabs";
         options?: Record<string, unknown>;
     } | {
-        provider?: "google" | "xai" | "openai";
         kind?: "realtime";
+        provider?: "openai" | "google" | "xai";
         options?: Record<string, unknown>;
     };
     tts?: {
         voice?: string;
         kind?: "inference";
-        options?: Record<string, unknown>;
         model?: string;
+        options?: Record<string, unknown>;
     } | {
         class?: "LLM" | "STT" | "STTv2" | "TTS";
-        provider?: "deepgram" | "elevenlabs";
         kind?: "plugin";
+        provider?: "deepgram" | "elevenlabs";
         options?: Record<string, unknown>;
     } | {
-        provider?: "google" | "xai" | "openai";
         kind?: "realtime";
+        provider?: "openai" | "google" | "xai";
         options?: Record<string, unknown>;
     };
     vadOptions?: {
@@ -4939,47 +6308,47 @@ declare const LuaVoiceConfigSchema: z.ZodEffects<z.ZodObject<{
     stt?: {
         voice?: string;
         kind?: "inference";
-        options?: Record<string, unknown>;
         model?: string;
+        options?: Record<string, unknown>;
     } | {
         class?: "LLM" | "STT" | "STTv2" | "TTS";
-        provider?: "deepgram" | "elevenlabs";
         kind?: "plugin";
+        provider?: "deepgram" | "elevenlabs";
         options?: Record<string, unknown>;
     } | {
-        provider?: "google" | "xai" | "openai";
         kind?: "realtime";
+        provider?: "openai" | "google" | "xai";
         options?: Record<string, unknown>;
     };
     volume?: number;
     llm?: {
         voice?: string;
         kind?: "inference";
-        options?: Record<string, unknown>;
         model?: string;
+        options?: Record<string, unknown>;
     } | {
         class?: "LLM" | "STT" | "STTv2" | "TTS";
-        provider?: "deepgram" | "elevenlabs";
         kind?: "plugin";
+        provider?: "deepgram" | "elevenlabs";
         options?: Record<string, unknown>;
     } | {
-        provider?: "google" | "xai" | "openai";
         kind?: "realtime";
+        provider?: "openai" | "google" | "xai";
         options?: Record<string, unknown>;
     };
     tts?: {
         voice?: string;
         kind?: "inference";
-        options?: Record<string, unknown>;
         model?: string;
+        options?: Record<string, unknown>;
     } | {
         class?: "LLM" | "STT" | "STTv2" | "TTS";
-        provider?: "deepgram" | "elevenlabs";
         kind?: "plugin";
+        provider?: "deepgram" | "elevenlabs";
         options?: Record<string, unknown>;
     } | {
-        provider?: "google" | "xai" | "openai";
         kind?: "realtime";
+        provider?: "openai" | "google" | "xai";
         options?: Record<string, unknown>;
     };
     vadOptions?: {
@@ -5033,47 +6402,47 @@ declare const LuaVoiceConfigSchema: z.ZodEffects<z.ZodObject<{
     stt?: {
         voice?: string;
         kind?: "inference";
-        options?: Record<string, unknown>;
         model?: string;
+        options?: Record<string, unknown>;
     } | {
         class?: "LLM" | "STT" | "STTv2" | "TTS";
-        provider?: "deepgram" | "elevenlabs";
         kind?: "plugin";
+        provider?: "deepgram" | "elevenlabs";
         options?: Record<string, unknown>;
     } | {
-        provider?: "google" | "xai" | "openai";
         kind?: "realtime";
+        provider?: "openai" | "google" | "xai";
         options?: Record<string, unknown>;
     };
     volume?: number;
     llm?: {
         voice?: string;
         kind?: "inference";
-        options?: Record<string, unknown>;
         model?: string;
+        options?: Record<string, unknown>;
     } | {
         class?: "LLM" | "STT" | "STTv2" | "TTS";
-        provider?: "deepgram" | "elevenlabs";
         kind?: "plugin";
+        provider?: "deepgram" | "elevenlabs";
         options?: Record<string, unknown>;
     } | {
-        provider?: "google" | "xai" | "openai";
         kind?: "realtime";
+        provider?: "openai" | "google" | "xai";
         options?: Record<string, unknown>;
     };
     tts?: {
         voice?: string;
         kind?: "inference";
-        options?: Record<string, unknown>;
         model?: string;
+        options?: Record<string, unknown>;
     } | {
         class?: "LLM" | "STT" | "STTv2" | "TTS";
-        provider?: "deepgram" | "elevenlabs";
         kind?: "plugin";
+        provider?: "deepgram" | "elevenlabs";
         options?: Record<string, unknown>;
     } | {
-        provider?: "google" | "xai" | "openai";
         kind?: "realtime";
+        provider?: "openai" | "google" | "xai";
         options?: Record<string, unknown>;
     };
     vadOptions?: {
@@ -5160,7 +6529,7 @@ export declare interface LuaVoiceHookContext {
  * The constructor below stores the raw input as-is — the runtime classes
  * never execute as part of the push pipeline.
  */
-declare type LuaVoiceModelInput = string | object;
+export declare type LuaVoiceModelInput = string | object;
 
 export declare class LuaVoiceTool<TInput extends ZodType = ZodType> implements LuaTool<TInput> {
     readonly name: string;
@@ -5378,6 +6747,7 @@ export declare class LuaWebhook {
     private readonly headerSchema?;
     private readonly bodySchema?;
     private readonly secret?;
+    private readonly enforceSchemas?;
     private readonly executeFunction;
     /**
      * Creates a new LuaWebhook instance.
@@ -5388,6 +6758,7 @@ export declare class LuaWebhook {
      * @param config.querySchema - Optional Zod schema for query parameter validation
      * @param config.headerSchema - Optional Zod schema for header validation
      * @param config.bodySchema - Optional Zod schema for body validation
+     * @param config.enforceSchemas - Reject schema-violating requests with HTTP 400 (default: log a warning only)
      * @param config.execute - Function that processes the webhook request
      */
     constructor(config: LuaWebhookConfig);
@@ -5412,6 +6783,7 @@ export declare class LuaWebhook {
      * @param query - Query parameters object
      * @param headers - Headers object
      * @param body - Request body
+     * @param rawBody - Exact request bytes (utf8), delivered as `event.rawBody` when given
      * @returns Promise resolving to webhook execution result
      * @throws Error if validation fails for any input
      *
@@ -5424,7 +6796,7 @@ export declare class LuaWebhook {
      * );
      * ```
      */
-    execute(query?: Record<string, any>, headers?: Record<string, any>, body?: any): Promise<any>;
+    execute(query?: Record<string, any>, headers?: Record<string, any>, body?: any, rawBody?: string): Promise<any>;
 }
 
 /**
@@ -5450,6 +6822,13 @@ export declare interface LuaWebhookConfig {
      * it and re-deploying.
      */
     secret?: string;
+    /**
+     * Opt in to rejecting requests that violate `querySchema` / `headerSchema` /
+     * `bodySchema`. Default (`false`): violations are logged as a
+     * `[lua:webhook-schema] would-reject` warning and `execute` still runs.
+     * `true`: a violating request is rejected with HTTP 400 before `execute`.
+     */
+    enforceSchemas?: boolean;
     /** Function that executes the webhook logic */
     execute: (event: LuaWebhookEvent) => Promise<any>;
 }
@@ -5457,13 +6836,23 @@ export declare interface LuaWebhookConfig {
 /**
  * Event payload delivered to webhook execute functions.
  */
-declare interface LuaWebhookEvent {
+export declare interface LuaWebhookEvent {
     /** Parsed query parameters */
     query?: Record<string, any>;
     /** Request headers */
     headers?: Record<string, any>;
     /** Request body (JSON or raw data) */
     body?: any;
+    /**
+     * The EXACT unparsed request bytes, as a utf8 string. Use it to verify a
+     * vendor's own signature scheme (Stripe `t=…,v1=…`, GitHub `sha256=…`, Slack
+     * `v0:…`) in `execute` — those HMACs cover the wire bytes, which
+     * `JSON.stringify(body)` does not reproduce. Present for JSON requests
+     * (`''` for an empty body); absent for form-encoded / text bodies and for
+     * webhooks fired by platform events. Header keys arrive lowercased, e.g.
+     * `event.headers['x-hub-signature-256']`.
+     */
+    rawBody?: string;
     /** ISO timestamp when the webhook was received */
     timestamp: string;
 }
@@ -5503,7 +6892,9 @@ export declare type LuaWorkflowBuildCode = 'duplicate-step-id' | 'unknown-step-r
 * chain — the code is `node-type-unsupported-in-container`. Kept for one minor so a consumer switching on the
 * union still compiles; removed in the next.
 */
-| 'approval-inside-container' | 'node-type-unsupported-in-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';
+| 'approval-inside-container' | 'node-type-unsupported-in-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'
+/** LUA-973: `remindAfterHours` is not a number of hours in 1..720 (`validateApprovalReminder`). */
+| 'remind-after-invalid' | '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;
@@ -5685,6 +7076,12 @@ export declare interface MCPServerBaseConfig {
     description?: string;
     /** Optional timeout in milliseconds (default: 60000) */
     timeout?: number;
+    /**
+     * Optional tool allow/deny list, applied by the platform when it discovers
+     * this server's tools. Use it to expose only the tools the agent needs.
+     * See {@link MCPToolFilter}.
+     */
+    tools?: MCPToolFilter;
 }
 
 /**
@@ -5776,6 +7173,29 @@ export declare interface MCPStreamableHttpServerConfig extends MCPServerBaseConf
     headers?: Record<string, string> | HeadersResolverFunction;
 }
 
+/**
+ * Per-server tool allow/deny list for an MCP server.
+ *
+ * Entries are the server's own (raw) tool names — not the namespaced
+ * `${serverName}_${tool}` id the agent sees — matched exactly, or as a prefix
+ * when the entry ends in `*` (e.g. `'read_*'`).
+ *
+ * - `deny` always wins over `allow`.
+ * - `allow` omitted ⇒ every tool the server lists (minus `deny`).
+ * - `allow: []` ⇒ no tools from this server.
+ *
+ * @example
+ * ```typescript
+ * tools: { allow: ['search', 'read_*'], deny: ['read_secrets'] }
+ * ```
+ */
+export declare interface MCPToolFilter {
+    /** Only these tools are exposed to the agent. */
+    allow?: string[];
+    /** These tools are never exposed to the agent (wins over `allow`). */
+    deny?: string[];
+}
+
 /**
  * MCP Server transport type - determines how to connect to the server.
  *
@@ -5788,6 +7208,35 @@ export declare type MCPTransport = 'sse' | 'streamable-http';
 
 declare type Message = TextMessage_2 | ImageMessage_2 | FileMessage_2;
 
+export declare const Metrics: MetricsApi;
+
+/**
+ * Record a number your agent cares about (orders completed, a latency, a 0/1 outcome) so its owner's objectives
+ * — and supervisor agents holding `supervision:observe` — can track it.
+ */
+export declare interface MetricsApi {
+    /**
+     * Record one point. `name`: lower-case, dotted / underscored, ≤ 64 chars. `tags`: at most 4 short string pairs
+     * (each distinct tag set is a series; an agent keeps at most 200 live series). Rate-limited per agent.
+     *
+     * Never throws: the receipt says whether the point was stored (`accepted`) or why not (`code`, e.g.
+     * `agent_metrics_disabled`, `agent_metric_rate_limited`). In `lua test` / `lua dev` the point is checked but
+     * recorded nowhere (`agent_metrics_offline`).
+     *
+     * @example
+     * ```typescript
+     * await Metrics.record('orders.completed', 1, { channel: Lua.request.channel });
+     * ```
+     */
+    record(name: string, value: number, tags?: Record<string, string>): Promise<AgentMetricRecordReceipt>;
+}
+
+declare interface ModelReasoningOptions {
+    effort?: ReasoningEffort;
+    /** Whether to surface the reasoning trace to the caller. Default true. */
+    show?: boolean;
+}
+
 export declare const ne: <T>(l: TypedRef<T>, r: TypedRef<T> | Literal<T>) => LuaPredicate;
 
 /** `.workflow(id, ref, input?, opts?)` — a nested run (a `subrun` row). */
@@ -5861,7 +7310,7 @@ declare class OrderApi extends HttpClient implements OrderAPI {
     create(orderData: CreateOrderRequest): Promise<OrderInstance>;
     /**
      * Updates the status of an existing order
-     * @param status - The new order status (e.g., 'pending', 'processing', 'shipped', 'delivered', 'cancelled')
+     * @param status - The new order status (e.g., 'pending', 'confirmed', 'fulfilled', 'cancelled'). `OrderStatus.FULFILLED` is sent as the platform value `fullfilled`.
      * @param orderId - The unique identifier of the order to update
      * @returns Promise resolving to the updated OrderResponse
      * @throws Error if the order is not found or the status update fails
@@ -5877,7 +7326,7 @@ declare class OrderApi extends HttpClient implements OrderAPI {
     updateData(data: Record<string, any>, orderId: string): Promise<OrderResponse>;
     /**
      * Retrieves all user orders with optional status filtering
-     * @param status - Optional order status to filter by (e.g., 'pending', 'processing', 'shipped', 'delivered', 'cancelled')
+     * @param status - Optional order status to filter by (e.g., 'pending', 'confirmed', 'fulfilled', 'cancelled'). `OrderStatus.FULFILLED` is sent as the platform value `fullfilled`.
      * @returns Promise resolving to an array of OrderInstance objects
      * @throws Error if the request fails or orders cannot be retrieved
      */
@@ -5896,7 +7345,8 @@ declare class OrderApi extends HttpClient implements OrderAPI {
  * Calculated/derived properties maintained by the system.
  */
 declare interface OrderCommon {
-    status: 'pending' | 'confirmed' | 'fulfilled' | 'cancelled';
+    /** The platform stores and returns the misspelt 'fullfilled'. */
+    status: 'pending' | 'confirmed' | 'fulfilled' | 'fullfilled' | 'cancelled';
     totalAmount: string | number;
     currency: string;
     itemCount: number;
@@ -6062,6 +7512,17 @@ declare interface Pagination {
     prevPage: number | null;
 }
 
+/** Options for `Data.patch` (LUA-963). */
+export declare interface PatchCustomDataOptions {
+    /**
+     * Compare-and-swap: apply the patch only if the entry is still at this
+     * version (`entry.version` from `Data.get`, `entry._version` on a
+     * `DataEntryInstance`). A mismatch writes nothing and rejects with
+     * `code === 'data_version_conflict'`.
+     */
+    ifVersion?: number;
+}
+
 export { PathOrLiteral }
 
 /** P split on '.' walked into T; `unknown` past depth 4 or through an index. */
@@ -6316,9 +7777,10 @@ declare interface ProductAPI {
     /**
      * Searches products.
      * @param query - Search query
+     * @param limit - Max products to return (default 5)
      * @returns Promise resolving to search results
      */
-    search(query: string): Promise<any>;
+    search(query: string, limit?: number): Promise<any>;
 }
 
 /**
@@ -6533,9 +7995,10 @@ export declare const Products: {
      * Searches products by query string.
      *
      * @param query - Search query
+     * @param limit - Max products to return (default 5)
      * @returns Promise resolving to search results
      */
-    search(query: string): Promise<ProductSearchInstance>;
+    search(query: string, limit?: number): Promise<ProductSearchInstance>;
     /**
      * Retrieves a specific product by ID.
      *
@@ -6656,6 +8119,87 @@ export declare interface ProfileResponse {
     };
 }
 
+/**
+ * Progress API — show live progress for a long-running tool in the chat that called it.
+ *
+ * Each call updates ONE progress card for the current tool call; the card closes on its own when the tool
+ * returns. It is best-effort: it never throws, and resolves `{ emitted: false }` when the chat surface cannot
+ * show it (no live stream, a text-only channel, or offline in `lua test`).
+ *
+ * @example
+ * ```typescript
+ * import { Progress } from 'lua-cli';
+ *
+ * for (let i = 0; i < files.length; i++) {
+ *   await Progress.update({ label: 'Importing files', fraction: i / files.length, phase: files[i].name });
+ *   await importFile(files[i]);
+ * }
+ * ```
+ */
+export declare const Progress: ProgressApi;
+
+/**
+ * wave 2 U15 — `Progress.update(...)` outside a deployed agent.
+ *
+ * In a deployed agent the `lua-cli` import is stripped at compile time and the sandbox's own `Progress` global
+ * serves the call, putting a live progress card on the chat turn. Offline (`lua test`, `lua dev`, or a plain
+ * Node import) there is no live chat stream to show it on, so every call is a no-op answering
+ * `{ emitted: false }`. It never throws.
+ */
+export declare interface ProgressApi {
+    /**
+     * Show or update this tool's progress card in the chat that called it.
+     *
+     * - `label`: card title; the first call's label (or the tool's name) is kept when you leave it out.
+     * - `fraction`: 0..1 (clamped); leave it out for an indeterminate bar.
+     * - `phase`: what the tool is doing now, e.g. "Reading sources (3/12)".
+     *
+     * Resolves `{ emitted: true }` when the card was (or, for a burst of calls, will be) shown, and
+     * `{ emitted: false }` when there is nothing to show it on. It never throws.
+     */
+    update(input?: ProgressUpdateInput): Promise<ProgressUpdateReceipt>;
+}
+
+/**
+ * U15 (wave 2) — run cards for SDK-started runs and `Progress.update`. Owner: U15.
+ * Contract: docs/agent-builder/wave2-contracts.md §U15.
+ *
+ *  - An SDK-started workflow run (`Workflows.start`) carrying `originThreadId` emits the EXISTING
+ *    `data-lua-workflow-run` parts into that thread (lua-core `workflow-part-emitter.ts`), so Desktop shows
+ *    the live run card. No new part type.
+ *  - `Progress.update(...)` from a long custom tool emits the EXISTING `data-lua-job-progress` part
+ *    (`LuaJobProgressData`, `source: 'sdk-job'`) through lua-core `job-progress-emitter.ts` — only when a
+ *    live stream writer exists and the surface declared the `jobs` client capability; otherwise a no-op.
+ */
+/** `Progress.update(input)`. */
+export declare interface ProgressUpdateInput {
+    /** Card label; the first call's label (or the tool's name) is kept when absent. */
+    label?: string;
+    /** Determinate progress 0..1 (clamped); absent ⇒ indeterminate. */
+    fraction?: number;
+    /** Current phase text, e.g. "Reading sources (3/12)". */
+    phase?: string;
+}
+
+export declare interface ProgressUpdateReceipt {
+    /** `false` when there is no live stream to show it on (a no-op, never an error). */
+    emitted: boolean;
+}
+
+/**
+ * U1 (wave 2) — provision agents for a user: `Agents.create(input, { onBehalfOf, consentId })` under an
+ * org provisioning policy. Owner: U1. Consumers: U17 (one-per-member instances), U9 (pending secrets
+ * attach on create), U4b (suspension reasons). Contract: docs/agent-builder/wave2-contracts.md §U1.
+ *
+ * What a create does (U1 spec): a PRIVATE agent with `createdBy = onBehalfOf` (an org member), an empty
+ * scaffold backup v1 (shared-source-sync) so restore works, `connectionPolicy: 'explicit'` (U2), and a
+ * supervision grant for the CALLING agent on the new agent with `createdByUserId = onBehalfOf`,
+ * `source: 'provisioning'`, `consentId`, its actions bounded by the policy.
+ */
+
+/** Supervision actions a provisioning grant may carry (`@lua/authz` `SUPERVISION_ACTIONS`). */
+declare type ProvisionedSupervisionAction = 'observe' | 'observe-content' | 'preview' | 'release' | 'act';
+
 declare interface PushJobVersionDTO {
     name: string;
     version: string;
@@ -6792,39 +8336,226 @@ export declare const rows: (s: LuaWorkflowStep<any, any, any> | string, path: st
 /** Where an incident notice goes beyond the inbox card (which always lands). */
 declare const SCHEDULE_HEALTH_NOTIFY_CHANNELS: readonly ["app", "email", "emailApp"];
 
-/** The declaration an author writes. At least one threshold is required. */
-declare interface ScheduleHealthConfig {
-    /** Alert when no scheduled run has completed successfully for this many minutes (5..43200). */
-    maxSilenceMinutes?: number;
+/** The declaration an author writes. At least one threshold is required. */
+declare interface ScheduleHealthConfig {
+    /** Alert when no scheduled run has completed successfully for this many minutes (5..43200). */
+    maxSilenceMinutes?: number;
+    /**
+     * Alert when this many scheduled runs in a row failed. Workflows and agent tasks are parked by the
+     * platform after 3 consecutive failures, so for them the value is 1..3; code jobs accept 1..50.
+     */
+    alertAfterConsecutiveFailures?: number;
+    /** Out-of-inbox routing for the notice: 'app' (push), 'email', or 'emailApp' (both). Default 'emailApp'. */
+    notify?: ScheduleHealthNotify;
+}
+
+declare type ScheduleHealthNotify = (typeof SCHEDULE_HEALTH_NOTIFY_CHANNELS)[number];
+
+/**
+ * Additive field on primitive publish responses. When the agent is under
+ * versioning the server performs a scoped promote and returns the newly
+ * minted + promoted agent version here; absent when the agent has no versions.
+ */
+declare interface ScopedPromoteFields {
+    agentVersion?: number;
+}
+
+/**
+ * Response from product search.
+ */
+declare interface SearchProductsResponse {
+    success: boolean;
+    message: string;
+    data: Product[];
+}
+
+/** Datadog's validate host is per region; the caller picks only from this enum. */
+declare const SECRET_DATADOG_REGIONS: readonly ["us1", "eu1"];
+
+declare const SECRET_REQUEST_STATES: readonly ["pending", "submitted", "stored", "attached", "expired", "cancelled"];
+
+/**
+ * U9 (wave 2) — secret requests tested on the server. Owner: U9 (SDK `Secrets.*`, lua-api secrets service,
+ * provider test catalogue, hosted-page token routes, the lua-core `requestSecret` echo tool). Consumers:
+ * U9D (lua-desktop masked card), U1 (calls U9's attach for pending secrets at provisioning).
+ * Contract: docs/agent-builder/wave2-contracts.md §U9.
+ *
+ * Values are stored through the EXISTING agent env path (lua-agents `agentenvs`). That path stores `data` as
+ * plain text in the document, so an agent-target value is encrypted at rest only by the storage layer (the
+ * database's own encryption), not by the application; a pending-target value is a KMS envelope until it is
+ * attached. Values are never returned by any route, SDK call, log or outcome turn. The provider test catalogue is
+ * SERVER-OWNED: a caller can only name a provider; the request, host and interpretation are fixed.
+ */
+declare const SECRET_TEST_RESULTS: readonly ["ok", "unauthorized", "wrong_key_type", "insufficient_permission", "unreachable", "unverified"];
+
+/**
+ * `Agents.secrets(agentId).attach(requestIds)` (supervision op `secrets.attach`): the env keys set on the agent.
+ * Never a value.
+ */
+declare interface SecretAttachResult {
+    agentId: string;
+    attached: string[];
+    envKeys: string[];
+}
+
+declare type SecretDatadogRegion = (typeof SECRET_DATADOG_REGIONS)[number];
+
+/**
+ * `Secrets.request(...)` input. `key` is the env key a single-field secret is stored under; a bundle
+ * stores each field under `fields[i].envKey`. Env keys match {@link SECRET_ENV_KEY_PATTERN}.
+ */
+export declare interface SecretRequestInput {
+    provider: string;
+    key: string;
+    target?: SecretRequestTarget;
+    fields?: Array<{
+        name: string;
+        envKey: string;
+        label?: string;
+    }>;
+    region?: SecretDatadogRegion;
+    /** One line shown on the card / hosted page. */
+    reason?: string;
+}
+
+export declare interface SecretRequestReceipt {
+    requestId: string;
+    key: string;
+    state: SecretRequestState;
+    /** ISO. */
+    expiresAt: string;
     /**
-     * Alert when this many scheduled runs in a row failed. Workflows and agent tasks are parked by the
-     * platform after 3 consecutive failures, so for them the value is 1..3; code jobs accept 1..50.
+     * The one-time hosted-page token (`/secret-requests/:token`). Returned ONCE, to the creator only, at
+     * creation; the server stores only its sha256 and stops resolving it once the request is done (stored,
+     * cancelled, or out of attempts). Absent on every later read.
+     *
+     * It is a bearer CREDENTIAL: whoever holds it can write a value into the target agent's env. Hand it only
+     * to the person who should enter the secret (as the hosted-page link); never return it to the model as a
+     * tool result, put it in chat history, or log it.
      */
-    alertAfterConsecutiveFailures?: number;
-    /** Out-of-inbox routing for the notice: 'app' (push), 'email', or 'emailApp' (both). Default 'emailApp'. */
-    notify?: ScheduleHealthNotify;
+    pageToken?: string;
 }
 
-declare type ScheduleHealthNotify = (typeof SCHEDULE_HEALTH_NOTIFY_CHANNELS)[number];
+declare type SecretRequestState = (typeof SECRET_REQUEST_STATES)[number];
 
 /**
- * Additive field on primitive publish responses. When the agent is under
- * versioning the server performs a scoped promote and returns the newly
- * minted + promoted agent version here; absent when the agent has no versions.
+ * `Secrets.requestStatus(requestId)` — one request THIS agent created (including a `{ pendingFor }` request for
+ * an agent that does not exist yet), in the caller's org. Any other id answers `secret_request_not_found`.
+ * Never the value, the hosted-page token, or the person it was for.
  */
-declare interface ScopedPromoteFields {
-    agentVersion?: number;
+export declare interface SecretRequestStatus {
+    requestId: string;
+    key: string;
+    provider: string;
+    /** `expired` once a `pending` / `submitted` request is past `expiresAt`. A failed test leaves it `pending`. */
+    state: SecretRequestState;
+    /** The last server-side test of a submitted value (absent until the person submits). */
+    lastTest?: {
+        result: SecretTestResult; /** ISO. */
+        at: string;
+    };
+    /** ISO. */
+    expiresAt: string;
+    /**
+     * The agent a `{ pendingFor }` request's value was attached to (U1 provisioning), once `attached`. Omitted (with
+     * `state` still `attached`) when that agent is not in the caller's org.
+     */
+    attachedAgentId?: string;
 }
 
 /**
- * Response from product search.
+ * Where the secret goes. `'self'` = the calling agent; a string = that agent id (must be one the caller
+ * may configure); `{ pendingFor }` = a not-yet-created agent: the value is held (encrypted) on the
+ * request row and attached when U1 provisioning creates the agent with that request id.
+ *
+ * `{ pendingFor, agentId }` (held for an EXISTING agent, `LUA_SECRET_ATTACH_EXISTING_ENABLED`): the value is held
+ * (encrypted) the same way, named for `agentId` — an agent of the caller's org, not the caller, created by the
+ * conversation's person — and is attached only by the supervision op `secrets.attach` on that agent
+ * (`Agents.secrets(agentId).attach([requestId])`, `act` grant, on the owner's own turn). Never by U1.
  */
-declare interface SearchProductsResponse {
-    success: boolean;
-    message: string;
-    data: Product[];
+export declare type SecretRequestTarget = 'self' | string | {
+    pendingFor: string;
+    agentId?: string;
+};
+
+export declare const Secrets: SecretsApi;
+
+/**
+ * Secrets API — ask a person for a credential this agent needs, tested by Lua on the server before it is
+ * stored in the agent's env. Values never pass through your code: they are entered on the masked Desktop
+ * card or the hosted secret page, and no call here ever returns one.
+ *
+ * Off unless the platform enables secret requests (`secret_requests_disabled` otherwise).
+ */
+export declare interface SecretsApi {
+    /**
+     * Open a request for a provider credential. `target` defaults to this agent (`'self'`); `{ pendingFor }`
+     * holds the value for an agent that is provisioned later on the requesting person's behalf;
+     * `{ pendingFor, agentId }` holds it for an EXISTING agent the person created (attach it with
+     * `Agents.secrets(agentId).attach`).
+     * The receipt's `pageToken` (returned once) opens the hosted secret page.
+     *
+     * **`pageToken` is a credential**: anyone holding it can write a value into this agent's env until the
+     * request is done. Send it only to the person who should enter the secret (as the hosted-page link). Never
+     * return the receipt (or the token) from a tool as-is, put it in a message to the model, or log it; return
+     * `requestId` / `key` / `state` instead.
+     *
+     * @example
+     * ```typescript
+     * const { requestId, key, state } = await Secrets.request({
+     *   provider: 'stripe',
+     *   key: 'STRIPE_SECRET_KEY',
+     *   reason: 'Issue refunds for support tickets',
+     * });
+     * return { requestId, key, state }; // never the pageToken
+     * ```
+     */
+    request(input: SecretRequestInput): Promise<SecretRequestReceipt>;
+    /** Whether `key` is set, its provider, the last test result and any open request — never the value. */
+    status(key: string): Promise<SecretStatus>;
+    /** Re-test the stored value against the provider's fixed probe. `result` is a fixed enum. */
+    test(key: string): Promise<SecretTestOutcome>;
+    /**
+     * The state of ONE request this agent created — notably a `{ pendingFor }` request for an agent that does not
+     * exist yet, which `status(key)` cannot see. Answers `{ requestId, key, provider, state, lastTest?: { result, at },
+     * expiresAt, attachedAgentId? }`: `state` `stored` means the person submitted and the server test passed
+     * (`lastTest.result` `ok`, or `unverified` for an uncatalogued provider); a failed test leaves it `pending` with
+     * `lastTest` set; `attached` (with `attachedAgentId`) once provisioning attached it. Never the value or the token.
+     * A request another agent created, or from another org, answers `secret_request_not_found` like an unknown id.
+     * Platform only: refused offline (`secrets_unavailable`).
+     *
+     * @example
+     * ```typescript
+     * const s = await Secrets.requestStatus(requestId);
+     * if (s.state === 'stored' && s.lastTest?.result === 'ok') { ... }
+     * ```
+     */
+    requestStatus(requestId: string): Promise<SecretRequestStatus>;
+}
+
+/** `Secrets.status(key)` — never the value. */
+export declare interface SecretStatus {
+    key: string;
+    present: boolean;
+    provider?: string;
+    lastTest?: {
+        result: SecretTestResult;
+        testedAt: string;
+    };
+    pendingRequestId?: string;
+}
+
+/** `Secrets.test(key)`. */
+export declare interface SecretTestOutcome {
+    key: string;
+    provider: string;
+    result: SecretTestResult;
+    /** ISO. */
+    testedAt: string;
 }
 
+export declare type SecretTestResult = (typeof SECRET_TEST_RESULTS)[number];
+
 declare interface SendTemplateButtonValue {
     sub_type: WhatsAppTemplateButtonType;
     index: string;
@@ -6838,12 +8569,19 @@ export declare interface SendTemplateData {
 }
 
 export declare interface SendTemplateResponse {
-    results: any[];
+    results: SendTemplateResult[];
     errors: any[];
     totalProcessed: number;
     totalErrors: number;
 }
 
+export declare interface SendTemplateResult {
+    phoneNumber: string;
+    ok: boolean;
+    messageId?: string;
+    error?: string;
+}
+
 export declare interface SendTemplateValues {
     header?: Record<string, string> & {
         image_url?: string;
@@ -6875,7 +8613,7 @@ declare interface SignalRunResult {
  * and agent `persona` play different semantic roles. Sharing the structural
  * shape today keeps the runtime lean; future divergence is a one-line change.
  */
-declare type SkillContextText = string | {
+export declare type SkillContextText = string | {
     base?: string;
     voice?: string;
     text?: string;
@@ -6954,6 +8692,275 @@ declare interface SupervisedAgentSummary {
     actions: string[];
 }
 
+/** `workflows.get` — metadata only: never the graph, script, code or tools. */
+declare interface SupervisedWorkflow {
+    workflowId: string;
+    name?: string;
+    /** The value `workflows.deploy` takes as `expectActive` (null = nothing live). */
+    activeVersionId: string | null;
+    /** Newest first, at most {@link SUPERVISED_WORKFLOW_VERSIONS_MAX}. */
+    versions: SupervisedWorkflowVersion[];
+}
+
+/** `workflows.create` — the workflow `push` / `deploy` take as `workflowId`. `created: false` = it already existed. */
+declare interface SupervisedWorkflowCreated {
+    workflowId: string;
+    name: string;
+    created: boolean;
+}
+
+declare interface SupervisedWorkflowVersion {
+    versionId: string;
+    version: string;
+    /** `active` = the workflow's `activeVersionId`; `sandbox` = a mutable `-sandbox` version; else `inactive`. */
+    status: 'active' | 'inactive' | 'sandbox';
+    createdAt?: string;
+}
+
+declare const SUPERVISION_ACCESS_REQUEST_STATES: readonly ["pending", "approved", "denied", "cancelled", "expired", "revoked"];
+
+/**
+ * U25 (LUA-959) — the supervision event kinds. An emitter writes one outbox row
+ * per event of a target agent that some supervisor subscribed to; lua-core then
+ * starts each subscribed supervisor's trigger, re-checking the `supervision:observe`
+ * grant at delivery time.
+ *
+ * `trigger.held` and `agent.paused` were typed extension points; SV (supervisor platform) gave them their
+ * emitters: lua-core's trigger dispatch emits `trigger.held` when a delivery to an inactive or paused trigger
+ * is held (one per trigger per hour), lua-api's agent pause emits `agent.paused`.
+ *
+ * Wave 2 adds three more extension points the same way (no emitter until the owning item lands):
+ * `objective.breached` (U30), `judge.score_below_threshold` (U25c, DOC3 §4.9) and
+ * `never_rule.violated` (U25c). Only the owning item writes an emitter for its kind.
+ */
+declare const SUPERVISION_EVENT_KINDS: readonly ["governance.blocked", "workflow.run_failed", "workflow.run_gated", "connection.unhealthy", "trigger.held", "agent.paused", "objective.breached", "judge.score_below_threshold", "never_rule.violated", "tool.auth_failed", "tool.errors_repeated"];
+
+/**
+ * The approver: the OWNER (creator) for a private agent; org admins / agent builders (holders of
+ * `members:assign-role` or `agents:manage` on the agent) for a shared one.
+ */
+declare type SupervisionAccessApproverKind = 'owner' | 'org_admin';
+
+/** What approving the request adds (empty lists omitted). `expiry` says how the grant's expiry changes. */
+declare interface SupervisionAccessGrantDelta {
+    actions?: string[];
+    releaseWorkflowIds?: string[];
+    unattendedWorkflowIds?: string[];
+    dataCollections?: string[];
+    /** Upgrade of an expiring `access_request` grant: `'kept'` (no new expiry asked), `'set'` (the new one applies). */
+    expiry?: 'kept' | 'set';
+    /** The approval also records the owner's opt-in to supervisor follow-ups (`notifyOwner`). */
+    ownerNotify?: boolean;
+}
+
+/** The supervision-grant fields an access request can add to. */
+declare interface SupervisionAccessGrantFields {
+    actions: string[];
+    releaseWorkflowIds?: string[];
+    unattendedWorkflowIds?: string[];
+    dataCollections?: string[];
+}
+
+/** The live grant an upgrade request was filed against (stored on the request; never user ids). */
+declare interface SupervisionAccessGrantSnapshot extends SupervisionAccessGrantFields {
+    grantId: string;
+    source: 'pap' | 'access_request';
+    /** ISO; only an `access_request` grant expires. */
+    expiresAt?: string;
+}
+
+/** lua `supervision_access_requests` row (owner U29). */
+declare interface SupervisionAccessRequest {
+    requestId: string;
+    orgId: string;
+    requesterAgentId: string;
+    targetAgentId: string;
+    actions: ProvisionedSupervisionAction[];
+    reason: string;
+    approverKind: SupervisionAccessApproverKind;
+    state: SupervisionAccessRequestState;
+    /** The inbox `input_request` item the approver acts on. */
+    inboxItemId?: string;
+    /** Set on approval: the grant created with `createdByUserId = decidedByUserId`, `source: 'access_request'`. */
+    grantId?: string;
+    decidedByUserId?: string;
+    /** ISO. */
+    createdAt: string;
+    expiresAt: string;
+    grantExpiresAt?: string;
+    decidedAt?: string;
+    /** SV — bindings the request asked for (see {@link SupervisionAccessRequestInput}). */
+    releaseWorkflowIds?: string[];
+    unattendedWorkflowIds?: string[];
+    dataCollections?: string[];
+    notifyOwner?: boolean;
+    /** SV — set when the request UPGRADES a live grant: that grant as it was when the request was filed. */
+    upgradeOf?: SupervisionAccessGrantSnapshot;
+    /** SV — exactly what approval adds to the supervisor's access (the approver's card lists this). */
+    adds?: SupervisionAccessGrantDelta;
+}
+
+/** `Agents.requestAccess(agentId, opts)`. */
+declare interface SupervisionAccessRequestInput {
+    actions: ProvisionedSupervisionAction[];
+    /** Shown to the approver; ≤ {@link SUPERVISION_ACCESS_REASON_MAX}. */
+    reason: string;
+    /** ISO; the GRANT's expiry once approved (absent ⇒ until revoked). */
+    expiresAt?: string;
+    /**
+     * SV — the requester's OWN workflows whose code steps may release on the target (needs `release`).
+     * `LUA_SUPERVISION_ACCESS_BINDINGS_ENABLED`; see `supervision-access-upgrade.types.ts`.
+     */
+    releaseWorkflowIds?: string[];
+    /** SV — the requester's OWN workflows that may run unattended Job-tier plugin steps on the target. */
+    unattendedWorkflowIds?: string[];
+    /** SV — the target's custom-data collections the supervisor may read (needs `observe`). */
+    dataCollections?: string[];
+    /**
+     * SV — ask the target's OWNER to opt in to follow-ups from this supervisor (`Agents.notifyOwner`). Recorded only
+     * when the approver IS the target's owner (creator); an org admin approving a shared agent cannot opt its owner in.
+     */
+    notifyOwner?: boolean;
+}
+
+declare type SupervisionAccessRequestState = (typeof SUPERVISION_ACCESS_REQUEST_STATES)[number];
+
+/** Per-kind payloads — metadata only: never message bodies, user ids, run inputs or outputs. */
+export declare interface SupervisionEventDataByKind {
+    'governance.blocked': {
+        stage: 'preprocess' | 'tool_call' | 'postprocess';
+        /** `workflow` = a workflow agent step's owner-governance preflight (gate 2). */
+        surface?: 'chat' | 'voice' | 'delegation' | 'workflow';
+        ruleId?: string;
+        reason?: string;
+        channel?: string;
+    };
+    'workflow.run_failed': {
+        runId: string;
+        workflowId?: string;
+        reason?: string;
+        stepId?: string;
+    };
+    'workflow.run_gated': {
+        runId: string;
+        workflowId?: string;
+        gate: 'billing' | 'quota';
+        code?: string;
+        stepId?: string;
+    };
+    'connection.unhealthy': {
+        connectionId: string;
+        integrationType?: string;
+        lastUnhealthyCode?: string;
+    };
+    /** A delivery was held for replay (`reason`: `inactive` / `paused`); one per trigger per hour (SV emitter). */
+    'trigger.held': {
+        triggerName: string;
+        reason?: string;
+    };
+    /** The agent was paused (SV emitter, lua-api). `pausedBy` is a coarse marker (`user`), never a user id. */
+    'agent.paused': {
+        reason?: string;
+        pausedBy?: string;
+    };
+    /**
+     * Wave 2 extension point (U30): an owner-confirmed objective broke one of its guardrails
+     * (`breach: 'guardrail'`) or drifted below its baseline (`breach: 'baseline'`). Metric values only.
+     */
+    'objective.breached': {
+        objectiveId: string;
+        metric: string;
+        breach: 'guardrail' | 'baseline';
+        value: number;
+        threshold: number;
+        /** The evaluated window, e.g. `7d`. */
+        window?: string;
+        guardrailId?: string;
+    };
+    /**
+     * Wave 2 extension point (U25c, DOC3 §4.9): a sampled completed run scored below its monitor's
+     * threshold. `reasoning` respects the org's judge redaction tier and is absent when the tier strips it.
+     * Flat on purpose: the outbox keeps only flat scalars (`sanitizeSupervisionEventData`), so DOC3's
+     * `subject: { kind, id }` travels as `subjectKind` + `subjectId`.
+     */
+    'judge.score_below_threshold': {
+        monitorKey: string;
+        subjectKind: 'workflow-run' | 'trigger' | 'job';
+        subjectId: string;
+        score: number;
+        threshold: number;
+        reasoning?: string;
+    };
+    /**
+     * SV — a tool / integration call of the target failed with an AUTH error: HTTP 401 / 403, or an expired /
+     * invalid token. Deduped per (target, tool) per window (`windowStart`, ISO). Metadata only: never the error text.
+     */
+    'tool.auth_failed': {
+        toolName: string;
+        /** Where it ran: `skill`, `mcp`, `job`, `webhook`, … (the log row's `logSource`). */
+        logSource?: string;
+        primitiveName?: string;
+        /** `unauthorized` (401), `forbidden` (403), `token_expired` (expired / invalid token or grant). */
+        reason: 'unauthorized' | 'forbidden' | 'token_expired';
+        windowStart: string;
+    };
+    /**
+     * SV — the same tool / primitive of the target failed `count` times inside one window (`windowSeconds`), counted
+     * across pods. Emitted once per (target, tool, window), when the count reaches the threshold.
+     */
+    'tool.errors_repeated': {
+        toolName: string;
+        logSource?: string;
+        primitiveName?: string;
+        count: number;
+        windowSeconds: number;
+        windowStart: string;
+    };
+    /** Wave 2 extension point (U25c): a stored never-rule refused (or, log-only, would have refused) a call. */
+    'never_rule.violated': {
+        ruleId: string;
+        surface: 'passthrough' | 'mcp' | 'workflow-step' | 'tool';
+        toolName?: string;
+        operation?: string;
+        /** `false` while `LUA_NEVER_RULES_ENFORCED` is off: the call was allowed and only recorded. */
+        enforced: boolean;
+        severity: 'severe';
+    };
+}
+
+/**
+ * The trigger body a subscribed supervisor receives (`source: 'supervision'`). It is
+ * delivered through the supervisor's own trigger, so that trigger's verify / filter /
+ * transform slots run as for any other dispatch.
+ */
+export declare interface SupervisionEventEnvelope {
+    source: 'supervision';
+    eventId: string;
+    kind: SupervisionEventKind;
+    targetAgentId: string;
+    occurredAt: string;
+    data: Record<string, unknown>;
+}
+
+export declare type SupervisionEventKind = (typeof SUPERVISION_EVENT_KINDS)[number];
+
+/**
+ * `supervisorAgentId`'s trigger `triggerName` fires on `kinds` of `targetAgentId`.
+ *
+ * A subscription lives only as long as the grant behind it: when a delivery finds the
+ * supervisor no longer holds `supervision:observe` on the target (revoked, or the two
+ * agents are no longer in one org), the platform deletes the subscription, and a
+ * re-granted supervisor subscribes again. Archiving either agent purges it too.
+ */
+export declare interface SupervisionEventSubscription {
+    supervisorAgentId: string;
+    targetAgentId: string;
+    kinds: SupervisionEventKind[];
+    triggerName: string;
+    createdAt?: string;
+    updatedAt?: string;
+}
+
 declare interface SupervisionLogRow {
     timestamp: string | number | Date;
     level?: string;
@@ -6962,6 +8969,32 @@ declare interface SupervisionLogRow {
     logSource?: string;
     primitiveName?: string;
     toolName?: string;
+    /**
+     * A non-identifying conversation key: the same value for every row of one conversation (thread) on this target,
+     * never the thread id itself (which embeds the end user's id), and different on another target. Present on rows
+     * written with a thread (a turn's `user_message` and `agent_response` rows, tool runtime logs, STT), so a
+     * conversation's user turns and replies group under one key; absent otherwise.
+     */
+    threadKey?: string;
+}
+
+declare interface SupervisionOwnerNotifyInput {
+    message: string;
+    /**
+     * Optional dedupe key (1-256 characters, no control characters). A retried `notifyOwner` with the same key from
+     * the same supervisor within 24 hours never posts twice: it answers the FIRST call's receipt (same `followUpId`,
+     * same `threadId`). A concurrent duplicate still in flight is refused `thread_follow_up_in_progress` (retryable).
+     * Scoped to `notifyOwner` — the same key on `Threads.followUp` is a different key. A key already used for another
+     * target agent is refused `supervision_owner_notify_invalid`. Without a key every call posts.
+     */
+    idempotencyKey?: string;
+}
+
+declare interface SupervisionOwnerNotifyReceipt {
+    followUpId: string;
+    /** The owner's home thread with the supervisor. */
+    threadId: string;
+    status: 'posted';
 }
 
 declare interface SupervisionRunSummary {
@@ -7111,6 +9144,90 @@ export declare const Templates: {
     };
 };
 
+/** Recorded effect kinds (DOC2 §7 seam table; `fetch` is sandbox egress record mode, §9.1). */
+declare const TEST_EFFECT_KINDS: readonly ["channel.send", "whatsapp.template", "whatsapp.reaction", "whatsapp.phone_request", "email.send", "inbox.push", "voice.call", "passthrough", "mcp.tool", "supervision.write", "user.update_name", "browser.action", "jobs.create", "fetch", "refused", "metrics.record", "threads.open", "threads.follow_up", "secrets.request", "connection_request.create", "connection_request.reconnect", "connection_request.cancel", "ai.generate"];
+
+declare type TestEffectKind = (typeof TEST_EFFECT_KINDS)[number];
+
+/** DOC2 §6.3 — Data: `shadow` (copy-on-write over live, default) or `isolated` (empty shadow only). */
+declare type TestSessionDataMode = 'shadow' | 'isolated';
+
+/** One row of `lua.test_session_effects` (unique `{testSessionId, seq}`; TTL = the session's `expiresAt`). */
+declare interface TestSessionEffect {
+    testSessionId: string;
+    seq: number;
+    kind: TestEffectKind;
+    /** The execution site (`tool`, `job`, `trigger`, `workflow-step`, …). */
+    site: string;
+    primitiveId?: string;
+    /** Redacted: secret-keyed values `[REDACTED]`, `Authorization` / `Cookie` / `X-Api-Key` dropped, body ≤ 16 KB. */
+    request: unknown;
+    syntheticResponse?: unknown;
+    /** ISO. */
+    at: string;
+}
+
+/** DOC2 §6.1 — sandbox egress: `record` (default) or `live` (explicit OWNER opt-in; never for supervisors). */
+declare type TestSessionEgressMode = 'record' | 'live';
+
+declare type TestSessionFireInput = TestSessionFireTarget & {
+    payload?: unknown;
+};
+
+declare type TestSessionFireTarget = {
+    trigger: string;
+} | {
+    job: string;
+} | {
+    workflow: string;
+} | {
+    webhook: string;
+};
+
+/** DOC2 §6.1 — MCP mode: `doubles-only` (T13 default) or `read-live` (session default). */
+declare type TestSessionMcpMode = 'doubles-only' | 'read-live';
+
+/** `Agents.versions(id).session(opts)` (DOC2 §6.1). `testTraffic: true` is a required literal. */
+declare interface TestSessionOpenInput {
+    version: number;
+    testTraffic: true;
+    toolDoubles?: TestSessionToolDouble[];
+    mcp?: TestSessionMcpMode;
+    data?: TestSessionDataMode;
+    egress?: TestSessionEgressMode;
+    /** Hours; default {@link TEST_SESSION_TTL_HOURS_DEFAULT}, max {@link TEST_SESSION_TTL_HOURS_MAX}. */
+    ttlHours?: number;
+}
+
+/** The session record (`lua.test_sessions`). */
+declare interface TestSessionRecord {
+    id: string;
+    agentId: string;
+    orgId: string;
+    version: number;
+    /** `user:<id>` / `apiKey:<id>` / `system:<agentId>` for a supervisor. */
+    createdBy: string;
+    mcp: TestSessionMcpMode;
+    data: TestSessionDataMode;
+    egress: TestSessionEgressMode;
+    toolDoubles: TestSessionToolDouble[];
+    status: TestSessionStatus;
+    /** Turns plus fires so far (cap {@link TEST_SESSION_OPS_MAX}). */
+    ops: number;
+    /** ISO. */
+    createdAt: string;
+    expiresAt: string;
+}
+
+declare type TestSessionStatus = 'open' | 'closed' | 'expired';
+
+/** Same shape as `ChatRequest.toolDoubles` (lua-core `request.type.ts`). */
+declare interface TestSessionToolDouble {
+    server?: string;
+    tool: string;
+    result: unknown;
+}
+
 export declare interface TextMessage {
     type: 'text';
     text: string;
@@ -7121,6 +9238,88 @@ declare type TextMessage_2 = {
     text: string;
 };
 
+/**
+ * `Threads.followUp(threadId, input)`: exactly one of `prompt` (a BACKGROUND agent turn on the thread,
+ * like the workflow callback loopback) or `message` (post the text as the agent, no model turn).
+ * Only the agent's OWN threads (its home threads and the threads of its turns).
+ */
+export declare type ThreadFollowUpInput = ({
+    prompt: string;
+    message?: never;
+} | {
+    message: string;
+    prompt?: never;
+}) & {
+    /**
+     * Optional dedupe key (1-256 characters, no control characters). A retried call with the same key on the same
+     * agent — within 24 hours (`FOLLOW_UP_IDEMPOTENCY_TTL_SECONDS`) — never delivers twice: it answers the FIRST call's
+     * receipt (same `followUpId`) and posts / queues nothing. The key belongs to its first thread: reusing it on
+     * another thread is refused `INPUT_INVALID`. Without a key every call delivers.
+     */
+    idempotencyKey?: string;
+};
+
+export declare interface ThreadFollowUpReceipt {
+    followUpId: string;
+    mode: 'turn' | 'message';
+    /** A turn is queued and delivered by the loopback; a message is posted immediately. */
+    status: 'queued' | 'posted';
+}
+
+/** `Threads.open(ownerUserId)`. The user must be one the agent may reach (same rules as `User.Inbox.push`). */
+export declare interface ThreadOpenResult {
+    threadId: string;
+    /** `true` the first time; the thread is otherwise reused. */
+    created: boolean;
+}
+
+export declare const Threads: ThreadsApi;
+
+/**
+ * Threads API — reach a person on a conversation your agent owns, from a job, trigger, webhook or supervision
+ * handler. The platform decides every call: the feature flag, that the thread is this agent's own, that the person
+ * is reachable (the run's own user, or — for an agent-level run — a member of the agent's notify list), a rate
+ * limit (12 per thread and 120 per agent per hour) and an audit row on the agent's logs (never the text).
+ *
+ * Refusals throw an error with `name: 'ThreadFollowUpError'` and a `code` from `THREAD_FOLLOW_UP_ERRORS`
+ * (`thread_follow_up_disabled`, `thread_not_owned_by_agent`, `thread_user_unreachable`,
+ * `thread_follow_up_rate_limited`, `thread_follow_up_input_invalid`, `thread_follow_up_unavailable`, …).
+ * `lua test` / `lua dev` never post into a real conversation: both members throw `thread_follow_up_unavailable`.
+ *
+ * @example
+ * ```typescript
+ * // In a job: open the user's home thread with this agent, then follow up there.
+ * const { threadId } = await Threads.open(userId);
+ * await Threads.followUp(threadId, { message: 'Your weekly report is ready.' }); // posted as the agent
+ * await Threads.followUp(threadId, { prompt: 'Check whether order 1042 shipped and tell the user.' }); // a background turn
+ *
+ * // Safe to retry: the same idempotencyKey never delivers twice (the retry resolves the first receipt).
+ * await Threads.followUp(threadId, { message: 'Order 1042 shipped.', idempotencyKey: 'order-1042-shipped' });
+ * ```
+ */
+export declare interface ThreadsApi {
+    /**
+     * The agent's HOME thread with `ownerUserId` (`{userId}-{agentId}:home`) — the same thread every time;
+     * `created` is `true` only the first time.
+     */
+    open(ownerUserId: string): Promise<ThreadOpenResult>;
+    /**
+     * Follow up on one of the agent's own threads with EXACTLY one of:
+     * - `{ prompt }` (≤ 8,000 chars) — start a background agent turn on the thread; the receipt is `queued`;
+     * - `{ message }` (≤ 4,000 chars) — post the text as the agent with no model turn; the receipt is `posted`.
+     *
+     * Optional `idempotencyKey` (1-256 characters, no control characters): a retried call with the same key from this
+     * agent within 24 hours delivers nothing and resolves the FIRST call's receipt (same `followUpId`) — use it when a
+     * job, trigger or webhook may run twice. A duplicate sent while the first is still delivering waits for it, or is
+     * refused `thread_follow_up_in_progress` (retry it). The key identifies the delivery: reusing it with different text
+     * on the same thread still delivers nothing, and reusing it on ANOTHER thread is refused
+     * `thread_follow_up_input_invalid` (as is reusing it for the other mode) — use one key per delivery. For
+     * `{ prompt }` the key covers QUEUEING the turn, not its completion. At most once unless the platform's key store
+     * fails mid-delivery. Without a key every call delivers.
+     */
+    followUp(threadId: string, input: ThreadFollowUpInput): Promise<ThreadFollowUpReceipt>;
+}
+
 /**
  * Base interface for entities with timestamps.
  * Most database entities include these fields.
@@ -7215,7 +9414,7 @@ export declare interface TriggerContext<T = any> {
 /**
  * Context delivered to a trigger's verify / filter / transform slots.
  *
- * Unlike a webhook event, `rawBody` carries the EXACT unparsed request bytes
+ * As on 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.
@@ -7243,7 +9442,7 @@ export declare interface TriggerContext<T = any> {
  * `lua workflows describe <ref>` resolves); `correlationKey` accepts a literal or a
  * `'${input.<field>}'` template the trigger fills.
  */
-declare interface TriggerStartWorkflow {
+export declare interface TriggerStartWorkflow {
     startWorkflow: {
         name: string;
         input?: unknown;
@@ -7276,6 +9475,8 @@ export { TypedRef }
 declare interface UpdateCustomDataResponse {
     status: string;
     message: string;
+    /** Entry version after the write (LUA-963). */
+    version?: number;
 }
 
 /**
@@ -7462,10 +9663,12 @@ export declare class UserDataInstance {
     unset(...fields: string[]): Promise<any>;
     /**
      * Clears all user data for the current user
-     * @returns Promise resolving to true if clearing was successful
+     * @returns Promise resolving to `{ success: true }` if clearing was successful
      * @throws Error if the clear operation fails
      */
-    clear(): Promise<boolean>;
+    clear(): Promise<{
+        success: boolean;
+    }>;
     /**
      * Saves the user's data
      * @returns Promise resolving to true if saving was successful
@@ -7475,21 +9678,41 @@ export declare class UserDataInstance {
     /**
      * Sends a message to a specific user conversation for the agent
      * @param messages - An array of messages to send (can be text, image, or file types)
-     * @returns Promise resolving to the response data from the server
-     * @throws Error if the message sending fails or the request is unsuccessful
+     * @returns Promise resolving to true only when the platform confirmed delivery, false on a failure or an unconfirmed result. Never throws.
      */
-    send(messages: Message[]): Promise<any>;
+    send(messages: Message[]): Promise<boolean>;
     getChatHistory(): Promise<ChatHistoryMessage[]>;
 }
 
+/** One channel id of a person, as that channel issued it. */
+declare interface UserIdentity {
+    /** `whatsapp_bsuid`, `slack_user`, `slack_bot` or `teams_user`; more kinds arrive as channels move over. */
+    kind: string;
+    /** Who issued the value: the WhatsApp business portfolio, the Slack team or enterprise, or the Microsoft tenant. */
+    scope: string;
+    value: string;
+    verifiedBy?: UserIdentityVerifiedBy;
+    /** What the channel shows for the person. Never use it to identify them. */
+    displayName?: string;
+    username?: string;
+}
+
+/** Which identity a message came from, as `Lua.request.sender` gives it. */
+declare type UserIdentityRef = Pick<UserIdentity, 'kind' | 'scope' | 'value'>;
+
+/** How an identity was established. */
+declare type UserIdentityVerifiedBy = 'otp' | 'oauth' | 'receipt' | 'provider' | 'observed' | 'none';
+
 /**
- * Options for looking up a user by email or phone
+ * Options for looking up a user by email, phone or channel identity
  */
 export declare interface UserLookupOptions {
     /** Email address to look up */
     email?: string;
     /** Phone number to look up (with or without + prefix) */
     phone?: string;
+    /** A channel identity, e.g. `Lua.request.sender` or an entry of `_luaProfile.identities` */
+    identity?: UserIdentityRef;
 }
 
 export declare const value: (v: unknown) => MapDescriptor;
@@ -7781,11 +10004,29 @@ declare interface WebRouteAuth {
 
 declare type WebRouteMethod = (typeof WEB_ROUTE_METHODS)[number];
 
+/**
+ * Body of POST /developer/agents/:agentId/channels/whatsapp/phone-request.
+ * Sends WhatsApp's "share your phone number" button. A user who taps it shares
+ * their own number, which is saved on their Lua profile before their next turn
+ * runs. Needs an open 24h customer-service window.
+ */
+declare interface WhatsAppPhoneRequestInput {
+    to: {
+        userId?: string;
+        phoneNumber?: string;
+        identity?: UserIdentityRef;
+    };
+    /** Message shown above the button (max 1024 characters). */
+    text: string;
+    options?: ChannelSendOptions;
+}
+
 /** Body of POST /developer/agents/:agentId/channels/whatsapp/reaction */
 export declare interface WhatsAppReactionSendInput {
     to: {
         userId?: string;
         phoneNumber?: string;
+        identity?: UserIdentityRef;
     };
     /** Vendor id (`wamid...`) of the message to react to — e.g. an inbound
      * message's id from the conversation history, ≤30 days old per Meta. */
@@ -7876,6 +10117,7 @@ export declare interface WhatsAppTemplateSendInput {
     to: {
         userId?: string;
         phoneNumber?: string;
+        identity?: UserIdentityRef;
     };
     templateName: string;
     languageCode?: string;
@@ -8182,7 +10424,16 @@ declare interface WorkflowRun {
     parentRunId?: string;
     correlationKey?: string;
     tags?: string[];
-    /** R4 `gate` (02 §2.4). LUA-788: a `kind:'billing'` gate names the wallet's refusal (`code`), the held step and its expiry. */
+    /**
+     * R3/R4 `gate` (02 §2.4) — what a `gated` run (and a gate-parked `suspended` one) waits on. LUA-788: a
+     * `kind:'billing'` gate names the wallet's refusal (`code`), the held step and its expiry. A `kind:'budget'` gate
+     * carries the run cap it met (`dimension`, `spent`, `cap`) and — item 10, newer servers — the refused step's
+     * estimate (`reserve`). A `kind:'start-consent'` gate carries — item 10, newer servers — WHY the start asked a
+     * person (`exceeded`: each crossed threshold and the estimate judged against it, e.g. credits 34 > maxAutoCredits
+     * 20) and `rateLimited` when the autonomy envelope's hourly meter sent it back. Every member past `kind` is
+     * optional: an older server sends none of the item-10 members, and the CLI then words the reason from the members
+     * it does send.
+     */
     gate?: {
         kind: string;
         reason?: string;
@@ -8190,7 +10441,21 @@ declare interface WorkflowRun {
         code?: string;
         stepId?: string;
         expiresAt?: number;
+        dimension?: 'credits' | 'actions' | 'steps' | 'jobSeconds' | (string & {});
+        spent?: number;
+        cap?: number;
+        reserve?: number;
+        exceeded?: WorkflowStartConsentExceededDto[];
+        rateLimited?: boolean;
     };
+    /**
+     * WHY a `suspended` / `waiting` run is parked (R3 list rows and R4; `WorkflowRunSuspendedFor` on the server) —
+     * stamped by the engine at every park, dropped on every wake and terminal. Servers since LUA-816 send it for
+     * approval / input / signal / billing parks; item-10 servers add budget and the waiting kinds. Absent on a run that
+     * is not parked and on a run parked before its park site stamped one: read `gate` / `status` then.
+     * `lua workflows status` renders it on the header line (`suspensionReason`).
+     */
+    suspendedFor?: WorkflowRunSuspendedForDto;
     /**
      * Server-decided (09 §9.6): `raise_budget` on a budget gate (LUA-665), `top_up` on a billing gate (LUA-788 — the
      * wallet clears it; the engine re-checks and resumes on its own), `cancel_again` / `force` under a pending cancel,
@@ -8339,9 +10604,52 @@ declare interface WorkflowRunModelUsageRow {
     fallbacks?: number;
 }
 
-/** §02 §2.4 run statuses (one union across every section). */
+/**
+ * §02 §2.4 run statuses (one union across every section). The three PARKED statuses hold no worker and say why on
+ * the run: `gated` (read `gate` — consent, quota, billing, an archived workspace, a paused agent), `suspended`
+ * (read `suspendedFor` — an approval / input / signal, the run's budget, a payment; `gate` for a step awaiting a
+ * decision),
+ * `waiting` (read `suspendedFor` — a sleep, a retry backoff, a child run). See `WorkflowRunSuspendedForDto`.
+ */
 declare type WorkflowRunStatus = 'queued' | 'running' | 'cancellation_requested' | 'gated' | 'suspended' | 'waiting' | 'completed' | 'failed' | 'cancelled' | 'abandoned' | 'timed_out';
 
+/**
+ * Item 10 — `WorkflowRun.suspendedFor`: what the engine parked the run FOR.
+ *
+ * `kind` is OPEN (an unknown kind from a newer server must render generically, never crash). A step parked for a
+ * decision (an exception park) is read off `gate` (`kind:'exception'`, `stepId`, `code`), not this stamp.
+ *  - `approval` | `input` | `signal` — a person or a signal decides (`stepId`; `approvalId` / `escalatedHop` on an
+ *    approval; `signalName` on a signal wait; `deadlineAt` when the wait times out);
+ *  - `budget` — the run met its own cap before step `stepId` (`dimension`, `spent`, `cap`, the step's estimate
+ *    `reserve`, the gate's `expiresAt`) — `lua workflows raise-budget` resumes it;
+ *  - `billing` — the wallet refused (`code`: `insufficient_credits` | `out_of_actions`) — a top-up resumes it;
+ *  - `model_policy` | `gate` — a platform policy holds step `stepId`;
+ *  - `sleep` | `retry_backoff` — a `waiting` run the engine wakes at `wakeAt` on its own;
+ *  - `subrun` — a `waiting` run waits on child run `childRunId`.
+ */
+declare interface WorkflowRunSuspendedForDto {
+    kind: 'approval' | 'input' | 'signal' | 'budget' | 'billing' | 'model_policy' | 'gate' | 'sleep' | 'retry_backoff' | 'subrun' | (string & {});
+    stepId?: string;
+    attempt?: number;
+    /** When the park began (epoch ms). */
+    since?: number;
+    code?: string;
+    expiresAt?: number;
+    operationId?: string;
+    approvalId?: string;
+    escalatedHop?: number;
+    signalName?: string;
+    /** HITL waits: when the wait times out (epoch ms). */
+    deadlineAt?: number;
+    /** `sleep` / `retry_backoff`: when the engine wakes the run (epoch ms). */
+    wakeAt?: number;
+    childRunId?: string;
+    dimension?: 'credits' | 'actions' | 'steps' | 'jobSeconds' | (string & {});
+    spent?: number;
+    cap?: number;
+    reserve?: number;
+}
+
 /**
  * [WJB-B5] (BAC-671) — the four token figures the server sums per run and per step (`WorkflowRunTokens` in
  * `@lua/shared-types`). Every member optional: the CLI is a reader of whatever the server sends, and a figure
@@ -8381,6 +10689,9 @@ export declare const Workflows: WorkflowsApi;
  * - `get`/`list` honour output ACLs: a restricted run comes back with `restricted:true`
  *   and no `output` — never an error.
  *
+ * - `start` options are checked: an option key it does not know throws
+ *   `WorkflowApiError{ code:'VALIDATION_FAILED' }` naming it — never silently dropped.
+ *
  * `startBatch`, `signalByKey`, `raiseBudget`, `setGoal` and `goals.*` are part of the
  * frozen member list and throw `WORKFLOWS_API_UNAVAILABLE` until their routes ship.
  */
@@ -8396,16 +10707,39 @@ export declare interface WorkflowsApi {
         initialState?: Record<string, unknown>;
         correlationKey?: string;
         tags?: string[];
+        /** Deliver the terminal summary back on this channel thread (07 §7.4.5). */
         replyTo?: {
             channel: string;
             threadId: string;
         };
+        /** Run on behalf of an end customer: `principalKind:'customer'` (reduced scope; never an approver). */
         onBehalfOf?: {
-            userId: string;
+            kind: 'customer';
+            externalId: string;
         };
+        /**
+         * Opt-in `workflow-callback`: on the terminal (completed | failed | timed_out) the agent takes one
+         * background turn on `originThreadId` with the outcome. Needs an origin thread — from a tool it defaults
+         * to the current chat thread; elsewhere a start without one throws `CALLBACK_THREAD_REQUIRED`.
+         */
+        callback?: boolean;
+        /**
+         * The chat thread the run's cards and callback land on. Defaults to `Lua.request.threadId` when called
+         * from a chat turn (a tool / processor); must be the calling user's own thread on this agent
+         * (`ORIGIN_THREAD_INVALID` otherwise).
+         */
+        originThreadId?: string;
+        notify?: 'emailApp' | 'email' | 'app' | 'off';
         workflowVersionId?: string;
     }): Promise<StartWorkflowRunResult>;
+    /**
+     * One run (R4). A parked run says WHY: `status` is `gated` | `suspended` | `waiting`, `gate` carries a gated run's
+     * reason (consent — with the crossed thresholds on newer servers —, quota, billing, budget …) and `suspendedFor`
+     * a suspended / waiting run's (`approval` | `input` | `signal` | `budget` | `billing` | `sleep` |
+     * `retry_backoff` | `subrun` …, with the step and the figures). Both are optional — absent on older servers.
+     */
     get(runId: string): Promise<WorkflowRun>;
+    /** Runs of this agent (R3); each row carries `gate` / `suspendedFor` exactly as `get` does. */
     list(opts?: {
         limit?: number;
         status?: WorkflowRunStatus | string;
@@ -8501,6 +10835,16 @@ export declare interface WorkflowSpecialistRole {
     tools: string[];
 }
 
+/** Item 10 — one crossed consent threshold on a `start-consent` gate (`WorkflowRun.gate.exceeded`). */
+declare interface WorkflowStartConsentExceededDto {
+    /** `steps` | `credits` | `duration` (seconds) | `actions`. */
+    dimension: 'steps' | 'credits' | 'duration' | 'actions' | (string & {});
+    /** The threshold crossed — `maxAutoSteps` / `maxAutoCredits` / `maxAutoDurationSeconds` / the envelope's `maxActions`. */
+    limit: number;
+    /** The start's estimate on that dimension. */
+    estimate: number;
+}
+
 export declare interface WorkflowStepContext<TIn = unknown, TResume = unknown, TState = Record<string, unknown>> {
     runId: string;
     workflowId: string;
@@ -8705,6 +11049,7 @@ export declare type WorkspaceSpec = {
     ref?: string | TemplateBinding;
     credentialsRef?: string;
     sizeGb?: number;
+    /** Hours a released or held volume is kept before expiry — default 72 h (24 h for a completed `keepArtefacts` volume), platform ceiling 168 h; once the platform enables `LUA_WF_WORKSPACE_TTL_CEILING_ENFORCE` a larger value is refused at push with `workspace-ttl-exceeds-cap` or clamped at run time. */
     ttlHours?: number;
     verify?: string;
     keepArtefacts?: boolean;
@@ -8712,9 +11057,10 @@ export declare type WorkspaceSpec = {
 } | {
     kind: 'empty';
     sizeGb?: number;
+    /** Hours a released or held volume is kept before expiry — default 72 h (24 h for a completed `keepArtefacts` volume), platform ceiling 168 h; once the platform enables `LUA_WF_WORKSPACE_TTL_CEILING_ENFORCE` a larger value is refused at push with `workspace-ttl-exceeds-cap` or clamped at run time. */
     ttlHours?: number;
     /**
-     * Keep the volume after the run completes: held until `ttlHours` (24 h when undeclared), then expired. A kept
+     * Keep the volume after the run completes: held until `ttlHours` (24 h when undeclared; the platform ceiling is 168 h once enforced), then expired. A kept
      * volume holds one of the organisation's workspace slots (`maxWorkspacesPerOrg`, 10 by default) until then.
      */
     keepArtefacts?: boolean;