lua-cli 3.46.0 → 3.48.0

package/docs/CLI_REFERENCE.md

@@ -258,7 +258,7 @@ lua push [type] [options]
 
 **Arguments:**
 
-- `type` - Primitive type to push: `skill`, `webhook`, `job`, `preprocessor`, `postprocessor`, `mcp`, `device`, `all`
+- `type` - Primitive type to push: `skill`, `agent`, `webhook`, `trigger`, `job`, `preprocessor`, `postprocessor`, `mcp`, `device`, `device-trigger`, `voice`, `decision`, `workflow`, `webapp`, `backup`, `all`
 
 **Options:**
 
@@ -587,6 +587,83 @@ $ lua jobs run daily-cleanup
 
 ---
 
+### `lua decisions`
+
+See, try and roll back the named decisions (`LuaDecision`) on the agent.
+
+**Usage:**
+
+```bash
+lua decisions [command] [name] [version] [options]
+```
+
+**Commands:**
+
+- `list` - List the decisions with their current version and source (default)
+- `versions <name>` - List a decision's versions, newest first; the current one is marked
+- `publish <name> <version>` - Make that version current (rollback); asks first unless `--force` or `--ci`
+- `run <name>` - Run the current version on `--state '<json>'` or `--message '<text>'`
+- `delete <name>` - Deactivate the decision and keep its versions; asks first, and needs `--force` in CI
+
+**Aliases:**
+
+- `ls`, `view` - `list`
+- `history`, `list-versions` - `versions`
+- `rollback`, `deploy` - `publish`
+- `try`, `test` - `run`
+- `rm`, `remove`, `del` - `delete`
+
+**Options:**
+
+- `--json` - Machine-readable output (`list`, `versions`, `run`)
+- `--force` - Skip the confirmation (`publish`, `delete`)
+- `--state <json>` - `run`: the state to decide on
+- `--message <text>` - `run`: sent as `{ message: <text> }`; an empty or blank message is a usage error (exit 2)
+- `--provider <jev|openai|auto>` - `run`: override the version's provider
+- `--min-confidence <n>` - `run`: override the version's `minConfidence` (0 to 1)
+
+**Example:**
+
+```bash
+$ lua decisions
+🧭 triage
+   Routes inbound support messages
+   Current version: 1.0.1
+   Source: from code
+   Created: 10/1/2026, 10:00:00 AM
+
+$ lua decisions run triage --message 'I want my money back'
+refund: odds 0.93
+team: billing (confidence 0.62, uncertain)
+
+Provider: jev
+Rule: default
+Model: jev-latest
+Duration: 184ms
+Tokens: 412
+Fallback: none
+
+$ lua decisions publish triage 1.0.0 --force
+✅ "triage": 1.0.1 → 1.0.0
+   Questions removed: team
+```
+
+The next `lua version promote` sets each decision to the version that agent version included.
+
+`publish` on a deleted decision turns it back on. If another decision has taken its name since, the server answers 409 and the command exits 10.
+
+A failed `run` prints the decision error's own message, so a timeout or a provider outage (both 503) reads as one and exits 11. `lua logs --type decisions` shows the failed call's log row.
+
+**Exit codes:**
+
+- `2` - An unknown decision name or version, a missing argument, or `delete` in CI without `--force`
+- `3` - The server answered 404
+- `9` - The server refused the credential (401)
+- `10` - The server answered 402, 403, 422 or another 4xx
+- `11` - The server answered 503, 504 or another 5xx, or could not be reached
+
+---
+
 ### `lua integrations`
 
 Connect third-party accounts and services.

package/docs/README.md

@@ -1,6 +1,6 @@
-# lua-cli v3.46.0
+# lua-cli v3.47.0
 
-Welcome to the comprehensive API documentation for lua-cli v3.43.0. This guide covers every API, class, and function exported by the package.
+Welcome to the comprehensive API documentation for lua-cli v3.47.0. This guide covers every API, class, and function exported by the package.
 
 ## 📚 Documentation Index
 
@@ -263,8 +263,8 @@ Each API doc includes:
 
 ---
 
-**Version:** 3.29.1
-**Last Updated:** August 2026
+**Version:** 3.47.0
+**Last Updated:** October 2026
 
 ---
 

package/docs/api/Decisions.md

@@ -0,0 +1,276 @@
+# Decisions API
+
+The Decisions API asks a fast classifier model short, structured questions about any state and returns typed answers you can branch on.
+
+## Import
+
+```typescript
+import { Decisions, DecisionError } from 'lua-cli';
+```
+
+## Overview
+
+Use Decisions when your code needs a judgment, not prose.
+
+- Ask a yes or no question and get the odds that the answer is yes.
+- Pick one option from a fixed set, such as which team should handle a message.
+- Place something on an ordered scale, such as how frustrated a customer sounds.
+- Ask many questions about the same state in one call.
+
+Each call is billed a flat amount: 0.005 actions when Jev answers and 0.01 actions when OpenAI answers. A cached hit and a failed call cost nothing. A call never goes through the agent chat pipeline.
+
+## Methods
+
+### `Decisions.ask(request)`
+
+Asks every question in `request.questions` about `request.state` and resolves the full result.
+
+```typescript
+const result = await Decisions.ask({
+  state: { message: input.text },
+  questions: {
+    refund: Decisions.odds('Is the customer asking for a refund?'),
+    team: Decisions.choice('Which team should handle this?', {
+      billing: 'Payments, invoices, refunds and charges.',
+      tech: 'Bugs, errors and anything that does not work.',
+      sales: 'Pricing, plans and buying more.',
+    }),
+    frustration: Decisions.score('How frustrated is the customer?', ['calm', 'annoyed', 'angry']),
+  },
+  minConfidence: 0.7,
+});
+
+const { refund, team, frustration } = result.answers;
+if (refund.type === 'odds' && refund.odds > 0.8) {
+  return { route: 'refunds' };
+}
+if (team.type === 'choice' && !team.uncertain) {
+  return { route: team.choice, escalate: frustration.type === 'score' && frustration.level === 'angry' };
+}
+```
+
+`state` can be a string, an array of strings, or a plain object. An empty state (`""`, a blank string, `[]`, `{}`, or an object whose values are all blank strings, such as `{ message: '' }`) throws `decision_invalid`, and the call is never sent or billed. So does a state or question instructions holding a lone UTF-16 surrogate (half of an emoji cut in two), which no provider accepts.
+
+You can pass up to 4 `images` (`{ data, mimeType }`, base64 data) next to the state, each at most 5 MB and at most 6 MB in total. A call over the total throws `decision_invalid` with a message that names the total. A call with images always goes to OpenAI, because Jev does not take images.
+
+A request body over 10 MB is refused with HTTP 413 before any of these checks run. Base64 makes images about a third larger, so the 6 MB image total is the practical limit for one call.
+
+Jev takes about 32,000 tokens of input. With `provider: 'auto'`, a larger state falls back to OpenAI and is charged at OpenAI's price. With `provider: 'jev'`, it fails with `decision_rejected` and Jev's own message.
+
+### `Decisions.ask(state, question, options?)`
+
+Asks a single question and resolves just its answer, not a map.
+
+```typescript
+const refund = await Decisions.ask(input.text, Decisions.odds('Is the customer asking for a refund?'));
+if (refund.type === 'odds' && refund.odds > 0.8) {
+  return { route: 'refunds' };
+}
+```
+
+`options` takes the same fields as the options table below.
+
+### `Decisions.run(name, state, options?)`
+
+Runs a decision declared on the agent with [`LuaDecision`](./LuaDecision.md) and resolves the same result as `Decisions.ask`.
+
+```typescript
+const result = await Decisions.run('triage', { message: input.text });
+const strict = await Decisions.run('triage', { message: input.text }, { minConfidence: 0.9 });
+```
+
+The platform asks the questions of the decision's current version, with its options. Any field in `options` (the options table below, plus `images`) overrides the version's value for this call only.
+
+Each lua-core pod caches the current version. A promote, a publish, a rename or a delete clears that cache at once, so a new version or a rollback reaches running code without a redeploy.
+
+A name the agent does not declare throws a `DecisionError` with code `decision_not_found`. So does a decision that was pushed but never made current.
+
+### `Decisions.odds(instructions, criteria?)`
+
+Builds a yes or no question whose answer is the probability that the answer is yes.
+
+```typescript
+Decisions.odds('Is this message spam?', {
+  yes: 'Unsolicited offers, links to unknown sites, or requests for credentials.',
+  no: 'A real question or request from a customer.',
+});
+```
+
+### `Decisions.choice(instructions, options)`
+
+Builds a question whose answer is exactly one of the option keys, each described in plain words.
+
+The option keys stay literal types, so `answer.choice` is typed as `'billing' | 'tech' | 'sales'` in the example above, once you have checked that `answer.type` is `'choice'`.
+
+### `Decisions.score(instructions, levels)`
+
+Builds a question that places the state on an ordered scale of 2 to 10 levels.
+
+A level is a label, or `{ label, description }` when the label needs explaining.
+
+### Checks before the call
+
+The builders check the question before any network call. They throw `decision_invalid` for empty instructions, instructions over 4,000 characters, fewer than 2 or more than 64 options, fewer than 2 or more than 10 levels, or `criteria` that is not an object.
+
+Question names and option labels are at most 64 characters. Any name works, including `constructor` or `toString`.
+
+## Response shape
+
+```typescript
+interface DecisionResult {
+  decisionId: string;
+  answers: { [questionName: string]: DecisionAnswer };
+  provider: 'jev' | 'openai';
+  model: string;
+  rule: 'pinned' | 'images' | 'region' | 'zero_retention' | 'default' | 'fallback';
+  usage: { inputTokens: number | null };
+  durationMs: number;
+  cached: boolean;
+  fallback?: { from: 'jev' | 'openai'; reason: string };
+}
+```
+
+Each answer has a `type` you check before reading it. Any answer can be `refused`, so `.odds`, `.choice` and `.score` exist only after that check.
+
+| `type`    | Fields                                                       | Meaning                                                   |
+| --------- | ------------------------------------------------------------ | --------------------------------------------------------- |
+| `odds`    | `odds`                                                       | The probability, from 0 to 1, that the answer is yes.     |
+| `choice`  | `choice`, `confidence`, `probabilities`, `uncertain`         | The chosen option key and how sure the model is about it. |
+| `score`   | `score`, `level`, `confidence`, `probabilities`, `uncertain` | The position on the scale and the matching level label.   |
+| `refused` | none                                                         | OpenAI declined to answer this question; Jev never does.  |
+
+`uncertain` is `true` when `confidence` is below `minConfidence`.
+
+A cached hit reports `usage.inputTokens: 0`. Identical cacheable calls made at the same time share one provider call, and every call that joined it comes back with `cached: true`. That sharing happens on each server, so identical calls that reach two servers at once can make two provider calls. Calls that differ in `region` or `zeroRetention` never share an answer.
+
+## Examples
+
+### Pre-processor that routes a message
+
+```typescript
+import { PreProcessor, Decisions } from 'lua-cli';
+
+export const router = new PreProcessor({
+  name: 'support-router',
+  description: 'Routes every message to the team that should handle it.',
+  execute: async (user, messages) => {
+    const text = messages.flatMap((m) => (m.type === 'text' ? [m.text] : [])).join('\n');
+    const { answers } = await Decisions.ask({
+      state: text,
+      questions: {
+        team: Decisions.choice('Which team should handle this message?', {
+          billing: 'Payments, invoices, refunds and charges.',
+          tech: 'Bugs, errors and anything that does not work.',
+          sales: 'Pricing, plans and buying more.',
+        }),
+      },
+    });
+    const team = answers.team.type === 'choice' && !answers.team.uncertain ? answers.team.choice : 'general';
+    return { action: 'proceed', metadata: { team } };
+  },
+});
+```
+
+### Webhook that gates on odds
+
+```typescript
+import { LuaWebhook, Decisions, Data } from 'lua-cli';
+
+export const inbound = new LuaWebhook({
+  name: 'inbound-email',
+  description: 'Saves inbound emails that ask for a refund.',
+  execute: async (event) => {
+    const refund = await Decisions.ask(
+      { subject: event.body.subject, body: event.body.text },
+      Decisions.odds('Is the sender asking for a refund?'),
+      { timeoutMs: 5000 }
+    );
+    if (refund.type !== 'odds' || refund.odds < 0.8) {
+      return { saved: false };
+    }
+    await Data.create('refund-requests', { subject: event.body.subject, odds: refund.odds });
+    return { saved: true };
+  },
+});
+```
+
+## Error handling
+
+A failed call throws a `DecisionError` with the server's message and these fields.
+
+| Field            | Description                                                            |
+| ---------------- | ---------------------------------------------------------------------- |
+| `code`           | One of the codes in the table below.                                   |
+| `provider`       | The provider that failed, when the failure came from a provider.       |
+| `upstreamStatus` | The HTTP status that provider answered, when it answered with one.     |
+| `decisionId`     | The id of the call's log row, so `lua logs --type decisions` finds it. |
+
+```typescript
+try {
+  await Decisions.ask(input.text, Decisions.odds('Is this urgent?'));
+} catch (error) {
+  if (error instanceof DecisionError && error.code === 'decision_timeout') {
+    return { urgent: false };
+  }
+  throw error;
+}
+```
+
+| `code`                          | When it happens                                                                    |
+| ------------------------------- | ---------------------------------------------------------------------------------- |
+| `decision_invalid`              | The request breaks a rule, such as too many questions or an empty state.           |
+| `decision_timeout`              | The provider did not answer before `timeoutMs`.                                    |
+| `decision_rejected`             | The provider refused the request, such as a model it does not know.                |
+| `decision_unavailable`          | No provider could answer, or this runtime cannot make decisions.                   |
+| `decision_disabled`             | The provider has no API key configured on the server.                              |
+| `decision_insufficient_credits` | The organization has no credits left to pay for the call.                          |
+| `decision_not_found`            | `Decisions.run` named a decision the agent does not declare or never made current. |
+
+The SDK sends a decision call once and never retries it. The server tries the other provider once when the first one times out or is unavailable, which includes a provider answering 401, 402, 403 or 429. It does not when you pin `provider`, unless you also set `fallback`.
+
+`timeoutMs` is the budget for the whole call. When the first provider fails and a fallback runs, the fallback gets the time that is left. With under 100 ms left, there is no fallback. A short timeout on your call does not affect other calls.
+
+A wrong `model` for the provider, such as an OpenAI model id OpenAI does not know, fails with `decision_rejected` (HTTP 422), not as an outage.
+
+Under `lua test` and through the HTTP API, `decision_timeout`, `decision_unavailable` and `decision_disabled` (all HTTP 503) arrive with their own code, message and provider, the same as in deployed code.
+
+## Limits
+
+| Limit                       | Value     |
+| --------------------------- | --------- |
+| Questions per call          | 64        |
+| Options per choice question | 2 to 64   |
+| Levels per score question   | 2 to 10   |
+| Characters per instruction  | 4,000     |
+| Characters of state         | 120,000   |
+| Images per call             | 4         |
+| Size per image              | 5 MB      |
+| Total image size per call   | 6 MB      |
+| Characters per name, label  | 64        |
+| Minimum timeout             | 100 ms    |
+| Default timeout             | 3,000 ms  |
+| Maximum timeout             | 15,000 ms |
+| Maximum cache time          | 86,400 s  |
+
+## Options
+
+| Option          | Values                          | Default     | Description                                                                                                                               |
+| --------------- | ------------------------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `provider`      | `'auto'`, `'jev'`, `'openai'`   | `'auto'`    | Which provider answers, where `auto` lets the platform pick.                                                                              |
+| `model`         | a model id of that provider     | provider's  | The exact model to use, which must belong to the chosen provider.                                                                         |
+| `fallback`      | `'jev'`, `'openai'`, `'none'`   | other one   | The provider to try when the first one fails, or `none` to never fall back, and a pinned `provider` never falls back unless you set this. |
+| `region`        | `'eu'`                          | none        | Routes the call to OpenAI's EU endpoint.                                                                                                  |
+| `zeroRetention` | `true`, `false`                 | `false`     | Routes the call to OpenAI only, and no retention flag is sent with the request.                                                           |
+| `minConfidence` | 0 to 1                          | `0.7`       | Below this confidence a choice or score answer carries `uncertain: true`.                                                                 |
+| `timeoutMs`     | 100 to 15000                    | `3000`      | How long the whole call may take, fallback included, before it fails with a timeout, and a value outside the range is clamped to it.      |
+| `cache`         | `{ ttlSeconds }`                | none        | Reuses the answer to an identical request for this many seconds.                                                                          |
+| `logState`      | `'summary'`, `'full'`, `'none'` | `'summary'` | How much of the state is kept in the decision log.                                                                                        |
+
+A pinned `provider` overrides the images, `region` and `zeroRetention` rules.
+
+## Related APIs
+
+- [LuaDecision](./LuaDecision.md) declares a named, versioned decision that `Decisions.run` runs.
+- [AI](./AI.md) generates free text when you need prose instead of a judgment.
+- [PreProcessor](./PreProcessor.md) is a common place to route messages with a decision.
+- [LuaWebhook](./LuaWebhook.md) can gate incoming events on a decision.

package/docs/api/Jobs.md

@@ -465,6 +465,22 @@ execute: async (job) => {
 }
 ```
 
+### The thread a job was created in
+
+A job created by `Jobs.create` during a chat turn records that turn's full thread id, readable as `job.data.originThreadId` (a string: `base` or `base:suffix`). It is informational and read-only; you never pass it to `Jobs.create`.
+
+It is absent for jobs created outside a chat turn (deploy-time `LuaJob`s, webhooks without a chat thread) and for jobs created before it was recorded, so read it as `job.data.originThreadId ?? undefined`.
+
+**`user.send()` does not use it.** A message sent from a job still goes to the user's last-interaction channel, and for a webchat-only user it lands on the base `${userId}-${agentId}` thread, not on the conversation thread the job was created in. See [`user.send`](./User.md#usersendmessages).
+
+**Example:**
+```typescript
+execute: async (job) => {
+  const threadId: string | undefined = job.data.originThreadId;
+  console.log('Created in thread', threadId ?? 'none');
+}
+```
+
 ## Retry Configuration
 
 ```typescript

package/docs/api/LuaDecision.md

@@ -0,0 +1,121 @@
+# LuaDecision
+
+`LuaDecision` declares a named decision on the agent: a fixed set of questions and the options to ask them with. Code runs it by name with `Decisions.run`, each `lua push` stages a new version of it, and `lua version promote` makes that version current.
+
+## Import
+
+```typescript
+import { LuaDecision, defineDecision, Decisions } from 'lua-cli';
+```
+
+## Overview
+
+Declare a decision when several places in your code ask the same questions, or when you want to change the questions or thresholds without redeploying the code that asks them.
+
+- The questions live in one place and are checked when you compile.
+- `Decisions.run('triage', state)` always asks the current version's questions.
+- You can write a new version from the dashboard, and publishing an older version rolls back.
+- Every log row and usage row of a run names the decision and its version.
+
+## Configuration
+
+```typescript
+type LuaDecisionConfig = {
+  name: string;
+  description?: string;
+  questions: Record<string, OddsQuestion | ChoiceQuestion | ScoreQuestion>;
+  provider?: 'auto' | 'jev' | 'openai';
+  model?: string;
+  fallback?: 'jev' | 'openai' | 'none';
+  region?: 'eu';
+  zeroRetention?: boolean;
+  minConfidence?: number;
+  timeoutMs?: number;
+  cache?: { ttlSeconds: number };
+  logState?: 'summary' | 'full' | 'none';
+};
+```
+
+| Field         | Description                                                                                         |
+| ------------- | --------------------------------------------------------------------------------------------------- |
+| `name`        | 1 to 64 letters, digits, underscores or hyphens. Unique on the agent; `Decisions.run` uses it.      |
+| `description` | What the decision is for, shown on the dashboard.                                                   |
+| `questions`   | 1 to 64 named questions, each built with `Decisions.odds`, `Decisions.choice` or `Decisions.score`. |
+| options       | The same options as `Decisions.ask`; see the options table in [Decisions](./Decisions.md#options).  |
+
+Write each question as a `Decisions.odds(...)`, `Decisions.choice(...)` or `Decisions.score(...)` call. The compiler reads them from your source, so their arguments must be values it can see: literals or constants.
+
+## Example
+
+```typescript
+import { LuaAgent, LuaDecision, Decisions } from 'lua-cli';
+
+export const triage = new LuaDecision({
+  name: 'triage',
+  description: 'Route an inbound message to the right team',
+  questions: {
+    refund: Decisions.odds('Is the customer asking for a refund?'),
+    team: Decisions.choice('Which team should handle this?', {
+      billing: 'Payments, invoices, refunds and charges.',
+      tech: 'Bugs, errors and anything that does not work.',
+      sales: 'Pricing, plans and buying more.',
+    }),
+  },
+  minConfidence: 0.7,
+});
+
+export const agent = new LuaAgent({
+  name: 'support',
+  persona: 'You help customers.',
+  decisions: [triage],
+});
+```
+
+Then, from any tool, job, webhook or processor of the agent:
+
+```typescript
+const result = await Decisions.run('triage', { message: text });
+const team = result.answers.team;
+if (team.type === 'choice' && !team.uncertain) {
+  await routeTo(team.choice);
+}
+```
+
+`defineDecision({...})` takes the same config and is detected the same way.
+
+## Versions
+
+`lua push` stages a new version of every decision listed in `decisions`; it does not change what `Decisions.run` asks. `lua push decision --name triage` stages one decision. A staged version becomes current only through `lua version promote` or `lua decisions publish`. Until a decision has a current version, `Decisions.run` throws `decision_not_found` for it.
+
+A staged version goes live with the agent version that includes it: run `lua version create`, then `lua version promote <version>`. Promoting an older agent version brings back the decision versions it included, which is how you roll back a pushed decision.
+
+A version saved from the dashboard goes live when you publish it, and publishing an older version there rolls back too.
+
+Each lua-core pod caches the current version. A promote, a publish, a rename or a delete clears that cache at once, so the change reaches running code without a redeploy.
+
+## From the terminal
+
+`lua decisions` lists the named decisions on the agent with their current version. `lua decisions versions triage` shows each version newest first, with its questions, provider and `minConfidence`.
+
+`lua decisions run triage --message 'I want a refund'` runs the current version and prints one line per answer, then the provider, rule, model, duration, tokens and fallback. Pass `--state '<json>'` to decide on structured state instead, and `--provider` or `--min-confidence` to override the version's options for that run.
+
+`lua decisions publish triage 1.0.1` makes 1.0.1 the current version straight away, which is the quickest rollback. The next `lua version promote` sets it back to the version that agent version included.
+
+`lua decisions delete triage` deactivates the decision after asking and keeps its versions. From then on `Decisions.run('triage', ...)` throws `decision_not_found`. Publishing a version of a deleted decision turns it back on.
+
+`lua version status` lists each decision with the version the active agent version runs and the version in `lua.skill.yaml`.
+
+## Errors
+
+The constructor throws a `DecisionError` with code `decision_invalid` when the name is not valid, there are no questions, or a question was not built with a builder.
+
+The builders refuse a malformed question with `decision_invalid` before anything is sent. [Decisions](./Decisions.md#checks-before-the-call) lists the checks.
+
+`Decisions.run` throws a `DecisionError` with code `decision_not_found` when the agent does not declare the name, when the decision was deleted, or when it was pushed but never made current. Like every decision error, it carries `decisionId`, the id of the call's log row.
+
+Writing a definition answers HTTP 409 on a conflict. That happens when another active decision on the agent already uses the name, on create or rename, and when the version number was already written for that decision. Publishing a deleted decision whose name another decision has taken since also answers 409.
+
+## Related APIs
+
+- [Decisions](./Decisions.md) asks questions directly and runs named decisions.
+- [LuaAgent](./LuaAgent.md) lists the decisions in `decisions`.

package/docs/api/User.md

@@ -226,7 +226,7 @@ await user.update({
 
 Sends messages to the user.
 
-**Where it lands:** `user.send()` targets the user's last-interaction channel (WhatsApp, Teams, SMS and so on). For a user who only chats on webchat, it writes the message to the user's base conversation thread (the `${userId}-${agentId}` root thread) and pushes it live to the webchat widget. It does **not** target a specific workspace conversation; there is no conversation or thread option.
+**Where it lands:** `user.send()` targets the user's last-interaction channel (WhatsApp, Teams, SMS and so on). For a user who only chats on webchat, it writes the message to the user's base conversation thread (the `${userId}-${agentId}` root thread) and pushes it live to the webchat widget. It does **not** target a specific workspace conversation; there is no conversation or thread option. A job's creating thread is readable as `job.data.originThreadId` (see [Jobs.md](./Jobs.md#the-thread-a-job-was-created-in)), but `user.send()` does not target it.
 
 **Parameters:**
 
@@ -266,7 +266,7 @@ await user.send([
 
 #### `user.clear()`
 
-Clears all user data.
+Clears all user data, including the user's My work list.
 
 **Returns:** `Promise<{ success: boolean }>` - `{ success: true }` once the data is cleared. Throws if the clear fails.
 
@@ -277,6 +277,57 @@ const user = await User.get();
 await user.clear();
 ```
 
+#### `user.setWorkItems(items)`
+
+Publishes this user's **My work** list: the open work an agent lists for them (a ticket they raised or hold, an approval waiting on them). Their client shows it beside the conversation, for example Frontline's "My work" tab. Each call replaces the whole list.
+
+**Parameters:** `items: WorkItem[]`, at most 100.
+
+| Field         | Type             | Notes                                                                   |
+| ------------- | ---------------- | ----------------------------------------------------------------------- |
+| `id`          | `string`         | Unique in the list, ≤ 200 chars (e.g. a ticket number)                  |
+| `title`       | `string`         | One line the user recognises, ≤ 120 chars                               |
+| `group`       | `string`         | Display group you choose, ≤ 40 chars ("Waiting on you", "Your tickets") |
+| `needsAction` | `boolean?`       | The user's own action is needed; listed first and highlighted           |
+| `status`      | `string?`        | Short label, ≤ 40 chars ("In progress")                                 |
+| `updatedAt`   | `string \| Date` | When this work last changed                                             |
+| `action`      | `string`         | Message the client sends when the item is tapped, ≤ 200 chars           |
+
+**Returns:** `Promise<void>`. Throws an error naming the first invalid item before anything is written, or `Failed to set work items` if the write fails.
+
+**Rules:**
+
+- **`action` is a show/open request, never a decision.** Use "Show MNT-00123", not "Approve MNT-00123". A tap must not act on a list that may be minutes old; ask for decisions in the conversation instead.
+- **Publish whenever the work changes, for everyone it affects.** That means the raiser, the assignee and the next approver. Use `User.get({ phone })` or `User.get(userId)` to address each of them.
+- **Add a scheduled job (every ~30 min)** that rebuilds the lists of recently active users. It catches any write that failed.
+- **Leave closed or cancelled work out.** An empty list (`[]`) means "nothing waiting".
+- **The list is kept out of `user.data`.** `update()`, `save()` and `patch()` never write it, so a stale read can't overwrite a newer list. `user.clear()` removes it.
+
+**Example:**
+
+```typescript
+import { User } from 'lua-cli';
+
+// After assigning MNT-00123 to a technician:
+const technician = await User.get({ phone: '+254700000000' });
+await technician?.setWorkItems([
+  {
+    id: 'MNT-00123',
+    title: 'MNT-00123 · Fryer not heating',
+    group: 'Assigned to you',
+    status: 'In progress',
+    updatedAt: new Date(),
+    action: 'Show MNT-00123',
+  },
+]);
+```
+
+#### `user.clearWorkItems()`
+
+Removes this user's My work list. Their client then shows no list from this agent.
+
+**Returns:** `Promise<void>`
+
 #### `user.save()`
 
 Saves current user data state.

package/docs/api/Workflows.md

@@ -20,6 +20,18 @@ Inside a sandbox (tools, jobs, webhooks, workflow code steps) `Workflows` is als
 - `get` / `list` honour output visibility: a restricted run comes back with `restricted: true` and no `output` — never an error.
 - From a workflow code step, `Workflows.start` creates a **detached** run (no parent link). Use the `.workflow(...)` builder node when the parent should wait.
 
+## Concurrency per correlation key
+
+`concurrencyPolicy: 'forbid'` alone is workflow-wide: one in-flight run blocks every other start of that workflow. Adding `concurrencyKey: 'correlationKey'` (set on the push API request next to `concurrencyPolicy`; the CLI / SDK declaration follows) narrows the guard to runs that share a `correlationKey`:
+
+- A start is refused only while a **non-terminal** run (`queued`, `running`, `cancellation_requested`, `gated`, `suspended`, `waiting`) of the same workflow carries the **same** `correlationKey`. `completed`, `failed`, `cancelled`, `abandoned` and `timed_out` runs free the key.
+- 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.
+- `concurrencyKey` requires `concurrencyPolicy: 'forbid'`; otherwise the push is a 400 `VALIDATION_FAILED` (`concurrency-key-requires-forbid`).
+- The refusal is a 409 `RUNS_IN_FLIGHT` whose body carries `blockingRunId`, `blockingStatus`, `concurrencyKey` and the colliding `correlationKey` (absent for the null bucket).
+- A scheduled fire that collides on its rendered `correlationKeyTemplate` key records `skipped_overlap`; a fire with a different key dispatches.
+
 ## Methods
 
 ### `Workflows.start(nameOrId, input?, opts?)`

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). 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. 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.46.0",
+  "version": "3.48.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.46.0",
+    "lua-cli": "^3.48.0",
     "openai": "^5.23.0",
     "uuid": "^13.0.0",
     "zod": "^3.24.1"