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

package/docs/API_REFERENCE.md

@@ -396,6 +396,8 @@ Custom data storage with vector search.
 - `Data.getEntry(collection, id)` - Get single entry
 - `Data.search(collection, query)` - Vector search
 - `Data.create(collection, data)` - Create entry
+- `Data.patch(collection, id, { set?, unset? }, { ifVersion? })` - Atomic field set/unset; `ifVersion` = compare-and-swap (409 `data_version_conflict` on a stale version)
+- `Data.increment(collection, id, field, by?, { upsert? })` - Atomic numeric increment, resolves the new value
 - `entry.update(data)` - Update entry
 - `entry.delete()` - Delete entry
 
@@ -717,11 +719,15 @@ if (Lua.request.webhook) {
 
 - `Lua.request.channel` - Channel type (`'whatsapp'`, `'web'`, `'api'`)
 - `Lua.request.webhook` - Webhook info (if running in webhook)
+- `Lua.request.agentId` - The agent handling this turn
+- `Lua.request.orgId` - The agent's organization, on deployed runtimes that know it (absent offline in `lua test`
+  and on older runtimes; read it defensively)
 - `Lua.request.invokedBy` - Present only when **another agent** created this turn through `Agents.invoke`:
   `{ agentId, supervisor, scopes, delegatedUserId? }`. Verified by the platform, never caller-supplied.
   - `supervisor` is true only when an org admin granted the caller `supervision:act` on this agent. Observe, preview and release grants do not set it.
   - `scopes` lists the caller's supervision scopes on this agent. It is `[]` on version-preview turns.
-  - `delegatedUserId` is set when the caller passed `input.userId`.
+  - `delegatedUserId` is set when the caller passed `input.userId`. It is also set when the caller's own turn
+    had such a user, or ran in a Job or workflow run: in those cases the platform did not pick the user.
   - The field is absent on user, channel, job, webhook and self-invoked turns, and offline in `lua test`.
 
 **Gating writes on agent invocation.** Treat a turn with `invokedBy` as agent-initiated. A mutating tool should

package/docs/api/AI.md

@@ -98,6 +98,8 @@ The full-options response mirrors AI SDK `GenerateTextResult` (serializable fiel
 | `toolCalls?` | `AiGenerateToolCall[]` | Tool calls made during generation |
 | `toolResults?` | `AiGenerateToolResult[]` | Tool results from generation |
 | `warnings?` | `CallWarning[]` | Provider warnings (e.g. unsupported settings) |
+| `model?` | `string` | The model that actually produced `text` (`provider/model`) |
+| `modelFallback?` | `{ requestedModel, servedModel, reason }` | Present only when `model` differs from the model the call resolved to. `reason`: `'not-approved'` (the model is not in the catalogue, so the platform default ran; it takes precedence when both apply) or `'provider-unavailable'` (a fallback model served during a provider outage) |
 
 ## Supported Providers
 
@@ -108,7 +110,7 @@ The full-options response mirrors AI SDK `GenerateTextResult` (serializable fiel
 | OpenAI | `openai/` | `openai/gpt-5.4` |
 | Anthropic | `anthropic/` | `anthropic/claude-sonnet-5` |
 
-Any other code from `lua models list` works too. If the requested model is not available, the request falls back to the platform default (`alibaba/qwen3.8-flash`).
+Any other code from `lua models list` works too. A model that is not available (unknown, misspelled or retired) is never swapped silently: the platform default (`alibaba/qwen3.8-flash`) answers and the response says so in `modelFallback`. A platform switch can turn a model you name into a refusal instead: the call then throws a 400 with `code: 'MODEL_NOT_AVAILABLE'`, a message naming the model, and `availableModels`. Check `model` / `modelFallback`, or catch that code.
 
 Google models automatically get Google Search grounding — search result URLs appear in the `sources` field of the full-options response.
 

package/docs/api/Agents.md

@@ -31,13 +31,13 @@ Supervision lets one agent observe, preview or release another agent in the same
 
 **Nothing in code can grant it.** An org admin creates a grant for each supervisor and target pair, with one or more actions:
 
-| Action            | Allows                                                                                                                                                                                       |
-| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `observe`         | `logs` (without message bodies), `runs`, `data` (only the collections named on the grant), `versions.list/get/diff`, `persona.versions`, `source`, `env.keys`                                |
-| `observe-content` | Log message bodies in `logs`                                                                                                                                                                 |
-| `preview`         | `versions.preview`: chat a staged version                                                                                                                                                    |
-| `release`         | `versions.promote` and `persona.activate`. These always need `expectActive`, and run only from a live workflow step of the supervisor whose workflow the grant names (`releaseWorkflowIds`). |
-| `act`             | The target sees `invokedBy.supervisor === true` when the supervisor invokes it                                                                                                               |
+| Action            | Allows                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `observe`         | `logs` (without message bodies), `runs`, `data` (only the collections named on the grant), `versions.list/get/diff`, `persona.versions`, `source`, `env.keys`, `workflows.get`                                                                                                                                                                                                                                                                                                          |
+| `observe-content` | Log message bodies in `logs`                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `preview`         | `versions.preview`: chat a staged version                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `release`         | `versions.promote`, `persona.activate`, `versions.delete` (a `superseded` version only), `workflows.create` (an inert, inactive workflow with no human author, so it cannot carry a schedule), `workflows.push` (a new, never-activated version of an existing workflow) and `workflows.deploy`. Promote, activate and deploy always need `expectActive`. Every release op runs only from a live workflow step of the supervisor whose workflow the grant names (`releaseWorkflowIds`). |
+| `act`             | The target sees `invokedBy.supervisor === true` when the supervisor invokes it                                                                                                                                                                                                                                                                                                                                                                                                          |
 
 **Discovery.** `Agents.list()` and `Agents.get(id)` return your own organization's agents, and only to an agent that holds at least one supervision grant there. Otherwise `list()` returns `[]`.
 
@@ -56,8 +56,21 @@ const preview = await Agents.versions('base_agent-tp').preview(8, 'What can you
 // Release (from a named workflow step): compare-and-swap, refused (409 PROMOTE_CONFLICT) unless 7 is live.
 await Agents.versions('base_agent-tp').promote(8, { expectActive: 7 });
 await Agents.persona('base_agent-tp').activate(3, { expectActive: 2 });
+
+// Workflows: push an inactive version, then deploy it. The deploy is compare-and-swap on the workflow's
+// live version ID (409 WORKFLOW_DEPLOY_CONFLICT on a mismatch; the message names the live one).
+const wf = await Agents.workflows('base_agent-tp').get('wf_123'); // { activeVersionId, versions: [...] }
+await Agents.workflows('base_agent-tp').push('wf_123', definition); // the body `lua push workflow` sends
+// A workflow the target does not have yet: create it (inert), push, then deploy with expectActive: null.
+// const { workflowId } = await Agents.workflows('base_agent-tp').create('nightly-digest');
+await Agents.workflows('base_agent-tp').deploy('wf_123', '1.4.0', { expectActive: wf.activeVersionId });
+
+// Clean up: only a superseded version can be deleted.
+await Agents.versions('base_agent-tp').delete(5);
 ```
 
+- A workflow deploy also records a new active agent version. Read `versions.list` again before a later `promote`.
+
 ### Platform switches
 
 - **`preview` and `release` are off until enabled per environment.** Set `LUA_SUPERVISION_PREVIEW_ENABLED` and `LUA_SUPERVISION_RELEASE_ENABLED` on lua-core.
@@ -83,13 +96,12 @@ await Agents.persona('base_agent-tp').activate(3, { expectActive: 2 });
   - The write actions (`release`, `act`) are non-transitive: a supervised agent cannot hold one, an agent that holds one cannot be supervised, and two agents cannot supervise each other.
   - These checks and the write are atomic for each org.
 - **Every call is audited on the target.** It writes a `supervisor_access` row to the target's logs (`lua logs --type supervision`). If the audit row cannot be written, the call fails.
-- **Every call is rate-limited.** The defaults are 60 calls a minute per supervisor and 3 releases a day per supervisor and target.
-- **Promotes record the actor.** A supervisor's promote records `promotedBy: service:agent:<supervisorId>` on the version.
+- **Releases record the actor.** A supervisor's promote records `promotedBy: service:agent:<supervisorId>` on the version, and a workflow deploy records it as the creator of the agent version it mints. A version delete is logged with the actor.
 
 ### Offline (`lua test`, `lua dev`)
 
 - **Read members** call the developer API with **your** credential and mirror the projections above: env keys only, and logs without user ids or message bodies.
-- **Refused offline:** `versions.promote`, `persona.activate`, `versions.preview` and `data`. A local test never changes a live agent, and readable collections live on the grant.
+- **Refused offline:** `versions.promote`, `persona.activate`, `versions.delete`, `workflows.create`, `workflows.push`, `workflows.deploy`, `versions.preview` and `data`. A local test never changes a live agent, and readable collections live on the grant.
 - **Not available offline:** `Agents.list`, `Agents.get` and `source.get`.
 
 ### Errors
@@ -101,11 +113,262 @@ Every error is a `SupervisionError` with a `code`:
 - `supervision_self_refused`
 - `supervision_release_binding_required` and `supervision_release_binding_refused`
 - `supervision_expect_active_required`
-- `supervision_rate_limited`
-- `supervision_release_limited`
+- `supervision_version_not_superseded`, when `versions.delete` targets a version that is not superseded
+- `WORKFLOW_DEPLOY_CONFLICT` and `PROMOTE_CONFLICT`, when `expectActive` is not the live version
 - `supervision_data_not_granted`
 - `supervision_audit_unavailable`
 - `supervision_room_refused`
 - `supervision_unavailable`
 - `supervision_release_disabled` and `supervision_preview_disabled`, while the platform switch is off
 - `PROMOTE_CONFLICT` and `PERSONA_ACTIVATE_CONFLICT`, for a stale `expectActive`
+
+## Agent directory and access requests
+
+These need no grant. Each platform switch is off until it is enabled per environment (lua-core and lua-api):
+`LUA_AGENT_DIRECTORY_ENABLED` and `LUA_SUPERVISION_ACCESS_REQUESTS_ENABLED`. While a switch is off, the call fails
+with `agent_directory_disabled` / `supervision_access_requests_disabled`.
+
+**`Agents.list()` versus `Agents.directory()`.** Once your agent holds any supervision grant in the org, `list()`
+returns **every** live org agent's id and name, private ones included. `directory()` shows only what the
+**user of the current turn** may see: a private agent only to its owner or an agent-grant holder.
+
+```typescript
+// Agents the turn's user can see: owner, privacy, build kind, last activity, 30-day volume, your actions.
+const entries = await Agents.directory();
+// [{ agentId, name, ownerUserId, isPrivate, buildKind: 'repo' | 'backup-source' | 'dashboard',
+//    lastActivityAt, volume30d, callerActions: ['observe'] }]
+
+// Ask for access. The owner of a private agent (or the org admins / agent builders of a shared one)
+// gets an inbox card; approving creates the grant, expiring at `expiresAt` when given.
+const req = await Agents.requestAccess('base_agent-tp', {
+  actions: ['observe', 'preview'],
+  reason: 'Triage the failing nightly runs',
+  expiresAt: '2026-12-31T00:00:00Z',
+});
+const mine = await Agents.accessRequests(); // newest first: pending | approved | denied | cancelled | expired | revoked
+await Agents.cancelAccessRequest(req.requestId); // only your own pending request
+```
+
+- `directory()` needs a turn the platform ran for a member of your org. These fail with
+  `agent_directory_requires_user`:
+  - a turn with no such user, for example a channel turn;
+  - a turn whose user was chosen by the agent that invoked it (`Agents.invoke(…, { userId })`);
+  - code in a Job or a workflow run (step, script or job), because the run's user comes from the turn that
+    started it and the platform does not keep where that user came from;
+  - any turn invoked onward from one of these. `volume30d` counts chat exchanges (the nightly rollup, up to yesterday) and
+    workflow runs; job and trigger executions are not counted.
+- One pending request per agent (`supervision_access_request_pending`). A pending request lapses after 7 days.
+- When nobody can approve (the owner of a private agent has left the org, or a shared agent has no org admin or
+  agent builder), the request is refused with `supervision_access_no_approver` and nothing is filed.
+  At most 3 new requests per agent and 20 in all per 24 hours, cancelled ones included
+  (`supervision_access_request_rate_limited`).
+- An approval never overwrites a grant you already hold (`supervision_access_grant_exists`), and the
+  non-transitive rules above still apply. The grant records the approver as its creator. Without the two switches
+  below it carries no `dataCollections`, `releaseWorkflowIds` or `unattendedWorkflowIds` (an org admin can add them).
+- An expired grant is suspended within about a minute of its `expiresAt`, even while the access-request switch
+  is off. A request whose `expiresAt` has passed
+  before anyone approves it cannot be approved; it expires instead.
+- Owners see who supervises their agent with `GET /developer/agents/:agentId/supervisors`, and the owner or an
+  org admin revokes one with `DELETE /developer/agents/:agentId/supervisors/:grantId`. Both routes first need
+  `agents:read` on the agent: on a private agent that is its creator, an agent-grant holder or the org owner, so
+  an org admin who is none of these is refused. The approver decides with
+  `POST /developer/supervision-access-requests/:requestId/decide` (`{ decision: 'approve' | 'deny' }`). Revoke and
+  decide need a signed-in person who is an active member of the org; a typed API key is refused.
+- Not available offline (`supervision_offline_unsupported`).
+
+### Asking for "ship" in chat, and upgrading a grant
+
+Two more switches, each off until enabled on lua-api: `LUA_SUPERVISION_ACCESS_BINDINGS_ENABLED` and
+`LUA_SUPERVISION_ACCESS_UPGRADES_ENABLED`.
+
+```typescript
+// Ask for everything a "watch, suggest and ship" supervisor needs, in one request.
+await Agents.requestAccess('base_agent-tp', {
+  actions: ['observe', 'observe-content', 'preview', 'act', 'release'],
+  reason: 'Stage and release the fixes you approve',
+  releaseWorkflowIds: [svReleaseId, svRollbackId], // YOUR workflows whose code steps may release
+  unattendedWorkflowIds: [svImproveId], // YOUR workflow whose Job-tier steps may stage code unattended
+  dataCollections: ['leads'], // the target's collections you may read
+  notifyOwner: true, // ask the owner to let you message them (see Agents.notifyOwner)
+});
+```
+
+- **Bindings** (`LUA_SUPERVISION_ACCESS_BINDINGS_ENABLED`; otherwise `supervision_access_bindings_disabled`):
+  - Workflow ids must be live workflows of the **requesting** agent (`supervision_access_workflow_not_owned`).
+    Release still happens only inside a code step of one of those workflows.
+  - The grant's own rules apply to the result: `releaseWorkflowIds` needs `release`; `unattendedWorkflowIds` needs
+    `act` or `release`, plus `observe` and `observe-content`; `dataCollections` needs `observe`. At most 10 ids per
+    workflow list and 20 collections; `*` is refused.
+  - An unattended Job step's staging key is owned by the person who approved, and can never do more than they can.
+- **Upgrades** (`LUA_SUPERVISION_ACCESS_UPGRADES_ENABLED`; otherwise approval refuses
+  `supervision_access_grant_exists`, as before). When you already hold an admin (`pap`) or access-request grant on
+  the agent, a new request **adds** to it:
+  - The request records the grant as it is now (`upgradeOf`), and the approver's card lists exactly what approval
+    adds (`adds`), plus what you already have. A request that adds nothing is refused
+    (`supervision_access_nothing_to_add`).
+  - Approval merges: nothing is ever removed, and the grant keeps its source and creator.
+  - If your access changed after you asked (revoked, narrowed, widened), approval is refused
+    (`supervision_access_grant_changed`) and the request stays pending: the approver denies it and you ask again.
+  - An admin grant never expires, so an upgrade of one cannot set `expiresAt`. An access-request grant takes the new
+    expiry when you give one.
+  - Only the grant's creator can approve adding `unattendedWorkflowIds` to it (they own the staging key).
+  - Grants created by agent provisioning are never upgraded.
+
+## Evals on a supervised agent
+
+`Agents.evals(agentId)` runs the target's eval suites (the ones its owner pushed with `lua evals push`) against a
+staged version. Off until the platform enables evals (`LUA_AGENT_EVALS_ENABLED` on lua-core, lua-api and lua-agents);
+`run` also needs `LUA_SUPERVISION_PREVIEW_ENABLED`.
+
+```typescript
+const ev = Agents.evals('base_agent-tp');
+const suites = await ev.suites(); // [{ key, revision, caseCount, minPassRate }]
+const { runId } = await ev.run({ suite: 'release-gate', version: 9 }); // a staged version, or 'active'
+const run = await ev.getRun(runId); // poll until status is completed / failed / cancelled / budget_exhausted
+if (run.status === 'completed' && run.passed === false) {
+  const t = await ev.transcript(runId, run.cases.find((c) => c.status === 'failed')!.caseId); // observe-content
+}
+await ev.cancel(runId); // only runs you started
+```
+
+| Member                                           | Needs                          | Notes                                                                                                                                                                                                                                                                                |
+| ------------------------------------------------ | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `suites()`, `suite(key)`                         | `observe`                      | The suite's cases; its author shows as `user` / `apiKey` / `service:agent`                                                                                                                                                                                                           |
+| `run({ suite, version, maxCredits?, caseIds? })` | `preview` + the preview switch | Runs are attributed to your agent. Bounded by the suite budget, the agent's monthly eval allowance and 10 supervised runs per agent per day (`LUA_SUPERVISION_EVAL_RUNS_PER_DAY`, `supervision_eval_runs_rate_limited`; `supervision_eval_cap_unavailable` when the counter is down) |
+| `runs(opts?)`, `getRun(runId)`                   | `observe`                      | Per-check `detail` and the judge's `reasoning` only with `observe-content`; another principal's runs show a coarse `initiatedBy`                                                                                                                                                     |
+| `transcript(runId, caseId)`                      | `observe` + `observe-content`  | `supervision_content_not_granted` without it; a holdout case is not found                                                                                                                                                                                                            |
+| `cancel(runId)`                                  | `preview`                      | Only runs you started. Works even with evals or preview switched off (stopping work is always safe)                                                                                                                                                                                  |
+
+- Supervisors never write suites: a suite decides which live tools an eval turn may use, which is the owner's call.
+- Eval turns run with built-in tools isolated, and live tools only where the owner opted them in on the suite.
+- Offline (`lua test`): reads use your developer credential; `run` and `cancel` are refused.
+- A Job-tier plugin step can use `lua evals` (reads, start, cancel) on its OWN agent through the `:8092` proxy when
+  `LUA_JOB_STEP_EVALS_ENABLED` is on. On a supervised (foreign) target it gets no eval routes: use `Agents.evals(...)`
+  in a code step, which carries the grant checks, the daily cap and the audit row. Suite writes are always refused.
+
+## Messaging a supervised agent's owner
+
+`Agents.notifyOwner(agentId, { message })` posts a plain message (no model turn) into the **target owner's** home
+thread with your agent, from any run, a schedule or an event trigger included. `Threads.followUp` from those runs
+reaches only your own notify list.
+
+```typescript
+// in an event trigger or a scheduled sweep
+await Agents.notifyOwner('base_agent-tp', {
+  message: 'Lead Desk: the order lookup started failing at 14:05 (12 errors, signed out of Shopify).',
+});
+```
+
+- Needs `observe` on the agent and the **owner's opt-in on your grant**: the owner approved a
+  `requestAccess({ notifyOwner: true })` themselves, or turned it on with
+  `PUT /developer/agents/:agentId/supervisors/:grantId/owner-notify` (`{ enabled }`, the agent's creator only). An org
+  admin approving a shared agent's request cannot opt its owner in.
+- Refused `supervision_owner_notify_not_opted_in` without the opt-in, after the agent changes owner, or once the owner
+  has left the org; `{ prompt }` is refused (`supervision_owner_notify_invalid`): it would start a turn as the owner.
+- Shares `Threads.followUp`'s limits (12 per thread and 120 per agent per hour) and its audit row; the target's logs
+  get a `supervisor_access` row as for every supervision call.
+- The platform does not inspect the text. An owner who opts in should know the supervisor may summarise what it
+  observes on any agent it supervises; replying in that thread talks to the supervisor as the owner.
+- Off until `LUA_SUPERVISION_OWNER_NOTIFY_ENABLED` is on (lua-core and lua-api): `supervision_owner_notify_disabled`.
+  Not available offline.
+- Add an `idempotencyKey` to make retries safe:
+  `Agents.notifyOwner(id, { message, idempotencyKey: 'incident-7' })`. A second call from your agent with the same key
+  within 24 hours posts nothing and returns the first receipt, with the same `followUpId` and `threadId`. A
+  concurrent duplicate waits for the first, or is refused `thread_follow_up_in_progress`; retry it. A first call
+  refused before it wrote anything frees the key; a failed write keeps it reserved for about two minutes, and a later
+  re-post replaces the same message. Delivery is at most once unless the key store fails mid-delivery. The key is 1-256 characters, and an invalid one is `supervision_owner_notify_invalid`, as is
+  a key already used to notify the owner of a different agent. Keys are separate from `Threads.followUp` keys.
+  Without a key, every call posts.
+
+## Handing a supervised agent one of its owner's connections
+
+`Agents.connections(agentId).assign(connectionId, { approval })` mounts one of the agent **owner's own personal
+connections** (their Gmail, their Slack…) on the agent, for example on an agent your Supervisor built for them (a
+provisioned agent gets none of its owner's connections by itself). The owner consents on Lua's own approval card, in
+their signed-in Desktop or inbox session:
+
+```typescript
+// a code step of a workflow the OWNER started from their own turn (the run's creator is the owner)
+const card = {
+  connectionAssignment: { connectionId, agentId, agentName, supervisorName, integration: 'googlemail', account },
+};
+// …previous step returns `card`, then:
+// .approval('giveGmail', { approver: 'creator', title: `Give your googlemail connection to "${agentName}"?` })
+await Agents.connections(agentId).assign(connectionId, { approval: { runId: ctx.runId, stepId: 'giveGmail' } });
+// → { agentId, connectionId, integration, status: 'assigned' }
+```
+
+- The payload is exactly
+  `{ connectionAssignment: { connectionId, agentId, agentName, supervisorName, integration, account } }`: `agentName`
+  is the agent's current name, `supervisorName` your agent's, `integration` the connection's integration type and
+  `account` the label Lua gives the connection (its display name, else the provider's first email). Call `assign` from
+  a code step of the same run that holds the approval (`connection_handover_binding_required` otherwise); the card
+  carries no artefacts. Lua shows these facts on the card (and that your agent can reach the account through the agent it
+  supervises) and checks each against what it stores; an extra key such as `summary` is refused. The step's `title`
+  must be exactly `Give your <integration> connection to "<agentName>"?` (`connectionHandoverApprovalTitle`). A
+  connection with no label, or whose label another of the owner's connections of that kind shares, is refused
+  (`connection_handover_account_unidentified`); so is an agent whose name (or yours) has invisible format characters or
+  that shares its name with another of the owner's agents (`connection_handover_agent_unidentified`). The card shows the
+  agent's name with the last 6 characters of its id.
+- Only the owner's own decision counts: approved in a first-party session with a proved sign-in (not a chat card, a
+  channel reply or an API key), by the person who created the agent and started your run, within 10 minutes, unedited.
+  One assignment per approval. Refusals: `connection_handover_approval_required`, `connection_handover_approval_mismatch`.
+- The connection must be the owner's own user-owned connection (not one delegated to them) and the agent their private
+  agent, else `connection_handover_not_assignable`. Needs `act` on the agent.
+- The owner removes it like any mount (`DELETE /developer/unifiedto/connections/:agentId/:connectionId/attach`).
+- Off until `LUA_SUPERVISED_CONNECTION_HANDOVER_ENABLED` is on (lua-core and lua-api): `connection_handover_disabled`.
+  Not available offline.
+
+## Keys for an agent that already exists
+
+Ask the person for a key for one of THEIR agents; they submit it signed in, Lua tests it, then you attach it:
+
+```typescript
+// in a tool, on the owner's own chat turn
+const { requestId } = await Secrets.request({
+  provider: 'openai',
+  key: 'OPENAI_API_KEY',
+  target: { pendingFor: 'lead-desk', agentId: 'base_agent-tp' },
+  reason: 'Lead Desk summarises new leads',
+});
+// the OWNER checks what they are submitting, then submits it signed in (their session or their own API key):
+//   GET  /developer/secrets/held-requests/<requestId>   → provider, key, env key names, agent, state, expiry
+//   POST /developer/secrets/held-requests/<requestId>/submit  {"values":{"apiKey":"…"}}
+// later, on the owner's turn again:
+await Agents.secrets('base_agent-tp').attach([requestId]); // { agentId, attached, envKeys }
+```
+
+- Asking needs `supervision:act` on the agent, an agent of your org that is not your own, created by the person in the
+  conversation, on that person's **live interactive turn** (a tool in a chat turn; never a scheduled task, Job,
+  workflow step or a user another agent chose). Keys starting `LUA_` or `NODE_` are refused. Otherwise
+  `secret_target_not_allowed` / `secret_key_invalid`.
+- The value is HELD (encrypted), never written to the agent until `attach`. Only the owner can submit it, signed in:
+  the public secret page (and its token) refuses these requests (`secret_submit_requires_owner`).
+- `attach` needs `supervision:act` and the owner's live interactive turn, as above. It takes only requests YOU held
+  for THIS agent that the owner submitted signed in and whose value passed Lua's test (`ok`; never `unverified`), all
+  or none (`secret_pending_not_attachable`), and never replaces a key the agent already has (`secret_key_exists`).
+  The agent's logs get a `supervisor_access` row and an outcome row (request ids and key names, never values).
+- A key held for an existing agent is never attached to a newly provisioned one, and a `{ pendingFor }` key for a new
+  agent is never taken by `attach`. If the agent is archived, or changes owner or org after the hold, the owner can no
+  longer view or submit it.
+- Accepted residuals: (1) "signed in" includes the owner's own API key, so an owner's PERSONAL API key placed in some
+  agent's env could submit as the owner (kept so API-only owners can submit at all); (2) the live-turn marker follows an
+  `Agents.invoke` chain that started on the owner's live turn (a tool the owner's turn invoked counts as that turn).
+- Off until `LUA_SECRET_ATTACH_EXISTING_ENABLED` is on (lua-core and lua-api, with lua-agents on the same build), with `LUA_SECRET_REQUESTS_ENABLED`
+  (`secret_attach_existing_disabled`); while it is off, `agentId` in a target is ignored as before. Not available
+  offline.
+
+## Events about failing tools
+
+Subscribe to two more event kinds with `Agents.events(id).subscribe({ kinds, triggerName })`:
+
+| Kind                   | When                                                                                               | `data`                                                                                            |
+| ---------------------- | -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
+| `tool.auth_failed`     | A tool or integration call of the agent failed with HTTP 401 / 403 or an expired / invalid token   | `toolName`, `logSource`, `reason` (`unauthorized` / `forbidden` / `token_expired`), `windowStart` |
+| `tool.errors_repeated` | The same tool (or job, webhook…) failed 5 times inside 10 minutes                                  | `toolName`, `logSource`, `count`, `windowSeconds`, `windowStart`                                  |
+| `trigger.held`         | A delivery to an inactive or paused trigger was held for replay (at most one per trigger per hour) | `triggerName`, `reason`                                                                           |
+| `agent.paused`         | The agent was paused                                                                               | `reason` (`owner_reason_given` / `none`, never the text), `pausedBy: 'user'`                      |
+
+- `tool.*` events never carry the error text, and fire once per agent, tool and 10-minute window. Test traffic
+  (previews, eval runs, `lua dev`) is not counted. They need `LUA_SUPERVISION_TOOL_FAILURE_EVENTS_ENABLED` on lua-core
+  as well as `LUA_SUPERVISION_EVENTS_ENABLED`.