lua-cli 3.49.2 → 3.51.0

package/docs/README.md

@@ -1,6 +1,6 @@
-# lua-cli v3.49.2
+# lua-cli v3.51.0
 
-Welcome to the comprehensive API documentation for lua-cli v3.49.2. This guide covers every API, class, and function exported by the package.
+Welcome to the comprehensive API documentation for lua-cli v3.51.0. This guide covers every API, class, and function exported by the package.
 
 ## 📚 Documentation Index
 
@@ -263,7 +263,7 @@ Each API doc includes:
 
 ---
 
-**Version:** 3.49.2
+**Version:** 3.51.0
 **Last Updated:** October 2026
 
 ---

package/docs/api/Agents.md

@@ -38,13 +38,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`, `workflows.get`, `deployed`                                                                                                                                                                                                                                                                                              |
-| `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                                                                                                                                                                                                                                                                                                                                                                                                          |
+| 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`, `deployed`                                                                                                                                                                                                                                                                                                                                                                                      |
+| `observe-content` | Log message bodies in `logs`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `preview`         | `versions.preview`: chat a staged version                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `release`         | `versions.promote`, `persona.activate`, `versions.delete` (a `superseded` version, or a stale `staged` one: never active, over 24 hours old, and not the newest staged version), `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 `[]`.
 
@@ -61,6 +61,9 @@ const keys = await Agents.env('base_agent-tp').keys(); // names only, never valu
 const live = await Agents.deployed('base_agent-tp');
 
 const versions = await Agents.versions('base_agent-tp').list();
+// Page past the newest 50, or filter by status (one or a list): newest first.
+const staged = await Agents.versions('base_agent-tp').list({ status: 'staged', limit: 50 });
+const older = await Agents.versions('base_agent-tp').list({ status: ['staged', 'superseded'], limit: 50, offset: 50 });
 const diff = await Agents.versions('base_agent-tp').diff(7, 8);
 const preview = await Agents.versions('base_agent-tp').preview(8, 'What can you do?'); // no tools unless allowlisted
 
@@ -77,13 +80,14 @@ await Agents.workflows('base_agent-tp').push('wf_123', definition); // the body
 await Agents.workflows('base_agent-tp').deploy('wf_123', '1.4.0', { expectActive: wf.activeVersionId });
 // Optionally name the source commit the version was built from: deploy(wf, v, { expectActive, commitHash? })
 
-// Clean up: only a superseded version can be deleted.
+// Clean up: a superseded version, or a staged one that was never active, is over 24 hours old and is not the newest staged one.
 await Agents.versions('base_agent-tp').delete(5);
 ```
 
 > **Experimental.** `Agents.jobs(agentId).register({ versionId, jobId })` registers job `jobId`, defined in the staged version `versionId`, on the target. It is available in a deployed agent only once the platform serves `jobs.register`, and needs the `supervision:register-job` grant (given per supervisor and target by an org owner or admin, scoped to jobs defined in the staged `versionId`). Without it the call is refused with `supervision_not_granted`. Under `lua test` / `lua dev` it is always refused with `supervision_release_offline_refused`, with no network call. An empty `versionId` or `jobId` is refused with `supervision_bad_args`, and an empty agent id with `supervision_no_target`.
 
 - A workflow deploy also records a new active agent version. Read `versions.list` again before a later `promote`.
+- `versions.list` takes `limit` (1–50, default 20), and optionally `status` (`active`, `staged`, `superseded`, `deleted`, or a list of them) and `offset` (0–10000 rows to skip). A call with only `limit` answers as before. An invalid `status` or `offset` is refused with `supervision_bad_args`. A platform that predates `status` / `offset` ignores them, so check the rows' `status` and versions before relying on them.
 - `commitHash` on `workflows.deploy` is optional and forwarded unchanged. A call without it behaves as before, and the platform may fill it from the Job workspace.
 
 ### Platform switches
@@ -132,7 +136,8 @@ 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_version_not_superseded`, when `versions.delete` targets a version that is not superseded
+- `supervision_version_not_superseded`, when `versions.delete` targets a version that is neither superseded nor staged (the active one, or a deleted one)
+- `supervision_version_staged_was_active`, `supervision_version_staged_too_recent` and `supervision_version_staged_newest`, when `versions.delete` targets a staged version that has promotion history, is under 24 hours old, or is the newest staged version
 - `WORKFLOW_DEPLOY_CONFLICT` and `PROMOTE_CONFLICT`, when `expectActive` is not the live version
 - `supervision_data_not_granted`
 - `supervision_audit_unavailable`
@@ -377,6 +382,43 @@ await Agents.secrets('base_agent-tp').attach([requestId]); // { agentId, attache
   (`secret_attach_existing_disabled`); while it is off, `agentId` in a target is ignored as before. Not available
   offline.
 
+## Writing a secret row into an agent's Data
+
+Hand a supervised agent a credential without it ever passing through a model prompt: from CODE (a workflow step or a
+job), write it straight into the agent's own Data, then nudge the agent with the fingerprint only.
+
+```typescript
+// in a workflow code step or a job of the SUPERVISOR — mint and write in the same step, return only the receipt
+const token = await mintTokenFor('ticket-pilot'); // your own code; never a tool argument, never a prompt
+const receipt = await Agents.secrets('base_agent-tp').put('pilot_linear_app_token', 'access', {
+  grant: 'brokered',
+  accessToken: token.accessToken,
+  expiresAt: token.expiresAtMs,
+  refreshToken: null,
+});
+// { ok: true, id: '<entry id>', fingerprint: 'sha256:<16 hex>' } — never the value
+return { fingerprint: receipt.fingerprint };
+
+// the agent reads it with its own Data access:
+//   await Data.get('pilot_linear_app_token', { _pk: 'access' }) — newest row first
+```
+
+- Writes the row of `collection` whose `_pk` is `key`, replacing its WHOLE `data` (no stale field survives), or creates
+  it. `value` is flat: string, finite number, boolean or null fields (at most 32; a string at most 8 KB; 16 KB in all);
+  `_pk` is set to `key`. No search text is set, so the value is never embedded.
+- Needs `supervision:act` on the agent AND the collection in the grant's `secretWriteCollections` (written only by an org
+  admin; absent = no secret write anywhere). Otherwise `supervision_not_granted` / `supervision_secret_write_not_granted`;
+  a malformed call is `supervision_secret_bad_args` (the message names the field, never its value).
+- The collection is write-only for you: `Agents.data(id).get/query` refuses it (`supervision_secret_collection_write_only`),
+  and the admin cannot also list it in `dataCollections`.
+- The agent's logs get a `supervisor_access` row and an outcome row (`secret_written`: collection, entry id and
+  fingerprint), never the value. A refusal after the grant check gets a `denied` row with its code only.
+- Fingerprint: `sha256:` + the first 16 hex of SHA-256 over the stored row as JSON with its keys sorted (`_pk`
+  included). If the agent caches the secret in memory, a token-free message carrying the fingerprint is how you tell it
+  to reload.
+- Keep the value out of your step's RESULT and memory: mint and `put` inside one step and return the receipt only.
+- Never on yourself, never by a watchdog grant, never inside a test session; not available offline.
+
 ## Events about failing tools
 
 Subscribe to two more event kinds with `Agents.events(id).subscribe({ kinds, triggerName })`:

package/docs/api/Data.md

@@ -278,6 +278,57 @@ if (result.status === 'success') {
 }
 ```
 
+## Org-shared collections: `Data.shared(name)`
+
+`Data` is private to the agent. To share reference data between agents of one organization (for example an
+architecture map one agent maintains and every other agent reads), an org admin creates a **shared collection** and
+names which agents may read it and which may write it. Agents never create or grant one themselves.
+
+```typescript
+import { Data } from 'lua-cli';
+
+const map = Data.shared('fleet_map');
+
+// A writer:
+const card = await map.create('repos', { repo: 'lua-core-services', tier: 1 }, { searchText: 'backend monorepo' });
+await map.patch('repos', card.id, { set: { tier: 2 } }, { ifVersion: card._version });
+
+// Any reader (a writer can read too):
+const { data } = await map.get('repos', { tier: 1 });
+const edges = await map.search('edges', 'what calls lua-agents', 10);
+const names = await map.collections();
+```
+
+- **Same surface as `Data`.** `Data.shared(name)` returns `collections`, `create`, `get`, `getEntry`, `update`,
+  `patch`, `increment`, `search` and `delete` with the same signatures, limits, filters, managed indexes,
+  compare-and-swap and vector search. The shared collection is a namespace: it can hold several collections
+  (`'repos'`, `'edges'`). An entry it returns writes back to the shared namespace (`entry.update()`, `entry.delete()`).
+- **Access.** Readers may call `collections`, `get`, `getEntry` and `search`. Writers may also call `create`,
+  `update`, `patch`, `increment` and `delete`. Any other call rejects with `code === 'shared_data_forbidden'`
+  (status 403). The same answer is given when the name does not exist or belongs to another organization: an agent
+  can only ever reach its own organization's shared collections.
+- **Audit.** Every write records the agent, the collection and the entry id (never the value) in the
+  organization's audit log.
+- **Test sessions** may read a shared collection but not write it (`shared_data_test_session_write_refused`, 409).
+- **Local runs** (`lua test`) have no org ACL to consult: every call rejects with
+  `code === 'shared_data_unavailable_offline'`.
+- Do not store end-customer personal data in a shared collection: it is organization reference data, and the
+  per-agent end-customer erasure does not cover it.
+
+### Managing shared collections (org admins)
+
+Created and managed through the admin API (`members:manage` to list, `members:assign-role` to change). Every id in
+`readers` / `writers` must be a live agent of the organization; explicit ids only, never `*`.
+
+```http
+GET    /admin/orgs/:orgId/shared-collections
+POST   /admin/orgs/:orgId/shared-collections        { "name": "fleet_map", "readers": ["agent_a"], "writers": ["agent_b"] }
+PUT    /admin/orgs/:orgId/shared-collections/:name  { "readers": [...], "writers": [...] }   (replaces both lists)
+DELETE /admin/orgs/:orgId/shared-collections/:name  (access ends at once; entries are purged; irreversible)
+```
+
+A change applies to the next `Data.shared` call. Re-creating a deleted name starts an empty collection.
+
 ## DataEntryInstance
 
 Data entries have convenient methods:

package/docs/api/Workflows.md

@@ -28,6 +28,7 @@ Inside a sandbox (tools, jobs, webhooks, workflow code steps) `Workflows` is als
 - Starts with **different** keys run in parallel (for example one release per agent).
 - Starts with **no** `correlationKey` share one null bucket: a second keyless start is refused while a keyless run is in flight. A keyless start and a keyed start never block each other.
 - Without `concurrencyKey` nothing changes: the guard stays workflow-wide.
+- The key rides the push DTO and compiled manifest, not the graph body, so declaring it never changes the `graphHash`.
 - `concurrencyKey` requires `concurrencyPolicy: 'forbid'`; otherwise `lua compile` / `lua push` fail with `concurrency-key-requires-forbid`, and a push that reaches the server is a 400 `VALIDATION_FAILED` (`concurrency-key-requires-forbid`). Any value other than `'correlationKey'` also fails the compile.
 - The refusal is a 409 `RUNS_IN_FLIGHT` whose body carries `blockingRunId`, `blockingStatus`, `concurrencyKey` and the colliding `correlationKey` (absent for the null bucket).
 - `lua workflows start` names the colliding `correlationKey` in its error line (and says so when the in-flight run is the keyless one); the body is unchanged under `--json`.

package/docs/workflows/schedules.md

@@ -2,7 +2,7 @@
 
 _Source of truth: workflows-spec 07 §7.1. This page is the developer summary; the spec is normative._
 
-`schedule: { type:'cron', expression: '0 9 * * 1', timezone: 'Europe/London' }` on `createWorkflow` fires runs on the cron grid; `scheduleInput` is the run input. `concurrencyPolicy:'forbid'` skips a fire while a run is in flight (the skip is recorded, never queued). With `concurrencyKey:'correlationKey'` a fire is skipped only when a run with the same rendered `correlationKeyTemplate` key is in flight; a fire with no key shares one null bucket. Manage with `lua workflows activate` / `deactivate`, or create and drive a schedule from the CLI without a `schedule:` block — `lua workflows schedules create|pause|resume|patch|delete` below; a re-enable with `--backfill-now` starts the missed occurrences (deduplicated on `backfill:<workflowId>:<occurrenceIso>`).
+`schedule: { type:'cron', expression: '0 9 * * 1', timezone: 'Europe/London' }` on `createWorkflow` fires runs on the cron grid; `scheduleInput` is the run input. `concurrencyPolicy:'forbid'` skips a fire while a run is in flight (the skip is recorded, never queued). With `concurrencyKey:'correlationKey'` a fire is skipped only when a run with the same rendered `correlationKeyTemplate` key is in flight; a fire with no key shares one null bucket (see [Concurrency](../api/LuaWorkflow.md#concurrency)). Manage with `lua workflows activate` / `deactivate`, or create and drive a schedule from the CLI without a `schedule:` block — `lua workflows schedules create|pause|resume|patch|delete` below; a re-enable with `--backfill-now` starts the missed occurrences (deduplicated on `backfill:<workflowId>:<occurrenceIso>`).
 
 ## Schedule health
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lua-cli",
-  "version": "3.49.2",
+  "version": "3.51.0",
   "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",

package/template/package.json

@@ -20,7 +20,7 @@
     "inquirer": "^12.9.6",
     "stripe": "^17.5.0",
     "js-yaml": "^4.1.0",
-    "lua-cli": "^3.49.2",
+    "lua-cli": "^3.51.0",
     "openai": "^5.23.0",
     "uuid": "^13.0.0",
     "zod": "^3.24.1"