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

package/docs/api/Agents.md

@@ -280,6 +280,84 @@ await Agents.notifyOwner('base_agent-tp', {
   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 })`:

package/docs/api/LuaWebhook.md

@@ -52,11 +52,49 @@ interface LuaWebhookConfig {
   /** Optional HMAC-SHA256 signing key (see Request Verification) */
   secret?: string;
 
+  /** Reject schema-violating requests with HTTP 400 (default: log a warning only) */
+  enforceSchemas?: boolean;
+
   /** Function that executes the webhook logic */
   execute: (event: LuaWebhookEvent) => Promise<any>;
 }
 ```
 
+## Schema Enforcement
+
+`querySchema`, `headerSchema` and `bodySchema` are checked before `execute` runs, for webhooks
+compiled with this CLI version or later. Only the schemas you declare are applied. An absent input
+is validated as `{}` (query/headers) or `undefined` (body), so a required `bodySchema` flags a
+request with no body.
+
+**Default: log only.** A violating request still reaches `execute` with the original `event`, and a
+single warning is written to the webhook's logs (also printed by `lua test`):
+
+```
+[lua:webhook-schema] would-reject webhook=<name> parts=query,body issues=3 first=body:n:invalid_type (request still processed; ...)
+```
+
+The line names the webhook, the failing parts, the total issue count and the first issue as
+`<part>:<path>:<code>`. It never includes input values or issue messages. Filter the logs on the
+`[lua:webhook-schema] would-reject` prefix to count would-rejects.
+
+**Opt in to rejection** with `enforceSchemas: true`. A violating request is then rejected before
+`execute` (query is checked first, then headers, then body) with HTTP 400 when deployed, and fails
+`lua test` with the same message:
+
+```json
+{ "statusCode": 400, "code": "VALIDATION", "message": "Invalid body", "part": "body", "issues": [] }
+```
+
+Recommended rollout: deploy, watch the would-reject warnings, fix the schemas or the senders, then
+set `enforceSchemas: true`. Only a strict boolean `true` enforces.
+
+- Validation only: `execute` receives the original `event`. No coercion, defaults or key stripping are applied to `event.query`, `event.headers` or `event.body`.
+- Header names are lowercase, so keys in a `headerSchema` must be lowercase (`'x-probe'`, not `'X-Probe'`). Transport headers are present too, so avoid `z.strictObject` for headers.
+- Webhooks that also subscribe to events receive `body: { eventType, ...payload }`; make sure `bodySchema` allows `eventType`.
+- Event deliveries are checked too, and they arrive with EMPTY `query` and `headers`. A `querySchema` or `headerSchema` with required keys, or a `bodySchema` that rejects `eventType`, logs a warning on every event delivery. Only with `enforceSchemas: true` do those deliveries fail, get logged at ERROR and not retried. Keep these schemas permissive, or declare them only on webhooks that are never event-subscribed.
+- Webhooks deployed from older CLI versions keep the old, unvalidated behaviour until they are re-compiled and re-pushed.
+
 ## Request Verification
 
 A webhook URL is public. Set `secret` and Lua requires every request to carry
@@ -549,7 +587,7 @@ curl -X POST http://localhost:3002/webhook/contact-form \
 
 ### ✅ DO
 
-- Always validate input with schemas (query, headers, body)
+- Always declare schemas (query, headers, body), watch the would-reject warnings, then opt in with `enforceSchemas: true`
 - Verify webhook signatures when available (GitHub, Stripe, etc.)
 - Return meaningful response objects
 - Store webhook events for auditing
@@ -560,7 +598,7 @@ curl -X POST http://localhost:3002/webhook/contact-form \
 
 ### ❌ DON'T
 
-- Don't skip validation - always use schemas
+- Don't skip validation - declare schemas and enable `enforceSchemas` once the warnings are clean
 - Don't expose sensitive data in responses
 - Don't perform long-running operations synchronously
 - Don't trust incoming data without verification

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lua-cli",
-  "version": "3.42.0-beta.2",
+  "version": "3.42.0-beta.3",
   "description": "Build, test, and deploy AI agents with custom tools, webhooks, and scheduled jobs. Features LuaAgent unified configuration, streaming chat, and batch deployment.",
   "readmeFilename": "README.md",
   "main": "dist/api-exports.js",
@@ -115,9 +115,9 @@
     "ts-node": "^10.9.2",
     "tsup": "^8.5.1",
     "@lua/sandbox-runtime": "0.0.1",
-    "@lua/shared-sandbox": "0.0.1",
     "@lua/shared-source-sync": "0.0.1",
     "@lua/shared-types": "0.0.1",
+    "@lua/shared-sandbox": "0.0.1",
     "@lua/workflow-graph": "0.0.1"
   },
   "scripts": {

package/template/package.json

@@ -20,7 +20,7 @@
     "inquirer": "^12.9.6",
     "stripe": "^17.5.0",
     "js-yaml": "^4.1.0",
-    "lua-cli": "^3.42.0-beta.2",
+    "lua-cli": "^3.42.0-beta.3",
     "openai": "^5.23.0",
     "uuid": "^13.0.0",
     "zod": "^3.24.1"