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

package/docs/api/Threads.md

@@ -0,0 +1,122 @@
+# Threads
+
+`Threads` lets a job, trigger, webhook or supervision handler reach a person on a conversation your agent owns:
+
+- `Threads.open(userId)` returns the agent's home thread with that person.
+- `Threads.followUp(threadId, …)` either starts a background agent turn on the thread or posts a message as the agent.
+
+```typescript
+import { Threads } from 'lua-cli';
+```
+
+> **Availability.** `Threads` is behind the platform flag `LUA_THREAD_FOLLOW_UP_ENABLED`. While the flag is off, every call throws `thread_follow_up_disabled`. In `lua test` and `lua dev`, both members always throw `thread_follow_up_unavailable`, because they write into a real person's conversation.
+
+## Threads.open
+
+```typescript
+const { threadId, created } = await Threads.open(userId);
+// threadId === `${userId}-${agentId}:home`
+```
+
+- **Idempotent.** It returns the same home thread for this agent and person every time. `created` is `true` only the first time.
+- **Who you can reach.** This is the same rule as `User.Inbox.push`:
+  - the user the run belongs to;
+  - for an agent-level run (a webhook, a user-less job or trigger), a member of the agent's notify list.
+
+  Anyone else throws `thread_user_unreachable`. A supervisor that wants to reach the OWNER of an agent it
+  supervises uses `Agents.notifyOwner(agentId, { message })` instead (the owner opts in on the grant; see
+  [Agents](./Agents.md#messaging-a-supervised-agents-owner)).
+
+## Threads.followUp
+
+```typescript
+// Post the text as the agent, with no model turn.
+await Threads.followUp(threadId, { message: 'Your weekly report is ready.' }); // { status: 'posted' }
+
+// Start a background agent turn on the thread.
+await Threads.followUp(threadId, { prompt: 'Check whether order 1042 shipped and tell the user.' }); // { status: 'queued' }
+```
+
+Pass exactly one of these:
+
+| Field     | Max length  | What happens                                                                                                                                     |
+| --------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `prompt`  | 8,000 chars | A background turn runs on the thread. The prompt is labelled as coming from your own background run, not from the user. The receipt is `queued`. |
+| `message` | 4,000 chars | The text is posted as an agent message. The receipt is `posted`.                                                                                 |
+
+Either way, the person's open conversation refreshes without a reload.
+
+- **Only the agent's own threads.** Allowed: a home thread, or any `{userId}-{agentId}[:suffix]` thread of one of the agent's own turns. Refused with `thread_not_owned_by_agent`: another agent's thread, a room, a task-run thread, or a hidden utility thread.
+- **Rate limited.** The limit is 12 follow-ups per thread per hour and 120 per agent per hour. Over the limit, the call throws `thread_follow_up_rate_limited`. If the limit cannot be checked, the call is refused.
+- **Audited.** Every follow-up writes a `thread_follow_up` row to the agent's logs. The row records the thread, the mode, the site and the outcome, never the text.
+- **Delivery of `queued`.** A queued turn runs in the background. If it fails, the failure is in the agent's logs; the call has already returned.
+
+### Safe retries with `idempotencyKey`
+
+A job, trigger or webhook can run twice for the same event. Add an `idempotencyKey` and a repeat never reaches the
+person twice:
+
+```typescript
+await Threads.followUp(threadId, { message: 'Order 1042 shipped.', idempotencyKey: 'order-1042-shipped' });
+```
+
+- A second call from this agent with the same key, within 24 hours, delivers nothing. It returns the first call's
+  receipt, with the same `followUpId`. It does not count against the rate limit.
+- If a second call arrives while the first is still delivering, it waits briefly and returns the first receipt. If
+  the first is still running after that wait, it throws `thread_follow_up_in_progress`; retry it.
+- If the first call was refused before it wrote anything (rate limit, audit), the key is free again and a retry
+  delivers. If the message write itself failed, the write may still have landed, so the key stays reserved for about
+  two minutes. A retry after that re-posts under the same message id, which replaces the message instead of adding a
+  second one.
+- With `{ prompt }`, the key covers queueing the background turn, not the turn's completion. A retry never queues a
+  second turn, even if the first turn fails later.
+- The key names the delivery, not the text: reusing it with a different message on the same thread still delivers
+  nothing. Reusing it on a different thread, or for the other mode (`prompt` instead of `message`), is refused with
+  `thread_follow_up_input_invalid`. Use one key per delivery, so a loop over users needs a key per user. Keys are
+  1-256 characters with no control characters; an invalid key is `thread_follow_up_input_invalid`.
+- The same key used again after its 24 hours re-posts under the same message id, which replaces the earlier message.
+- Delivery is at most once unless the platform's key store fails in the middle of a delivery. In that case a retry
+  after about two minutes can deliver again, onto the same message id for a message.
+- The key is not split by environment: sandbox and production runs of the same agent share it. Inside a `lua test`
+  session, follow-ups are recorded rather than delivered, and keyed calls are recorded each time (no dedupe).
+- The key is scoped to your agent and to `Threads.followUp`. `Agents.notifyOwner` keys are separate.
+- If the platform cannot check the key, the call is refused with `thread_follow_up_guard_unavailable` and nothing is
+  delivered.
+- Without a key, every call delivers, as before.
+
+## Errors
+
+Refusals throw an error with `name: 'ThreadFollowUpError'` and one of these codes:
+
+| Code                                 | When                                                                                               |
+| ------------------------------------ | -------------------------------------------------------------------------------------------------- |
+| `thread_follow_up_disabled`          | The platform flag is off                                                                           |
+| `thread_follow_up_input_invalid`     | Bad `ownerUserId` or `idempotencyKey`, or not exactly one of `prompt` / `message` within its limit |
+| `thread_not_owned_by_agent`          | The thread is not one of this agent's own threads                                                  |
+| `thread_user_unreachable`            | The person is not one this run may reach                                                           |
+| `thread_follow_up_rate_limited`      | Over the per-thread or per-agent hourly limit                                                      |
+| `thread_follow_up_guard_unavailable` | The rate limit, the audit row or the idempotency key could not be written                          |
+| `thread_follow_up_in_progress`       | A call with the same `idempotencyKey` is still delivering (retryable)                              |
+| `thread_follow_up_room_refused`      | Called from a room turn                                                                            |
+| `thread_follow_up_unavailable`       | `lua test` / `lua dev`, or a runtime without the Threads seam                                      |
+
+```typescript
+try {
+  await Threads.followUp(threadId, { message: 'Done.' });
+} catch (err: any) {
+  if (err.name === 'ThreadFollowUpError' && err.code === 'thread_follow_up_rate_limited') {
+    // try again next hour
+  }
+}
+```
+
+## Approval cards from a job
+
+A workflow run started from a job or a user-bound trigger can point its approval cards at the user's home thread. Pass the thread as `originThreadId`:
+
+```typescript
+const { threadId } = await Threads.open(userId);
+await Workflows.start('refund', input, { originThreadId: threadId, callback: true });
+```
+
+This works only for the run's own user. A user-less, agent-level run cannot target a home thread yet.

package/docs/api/User.md

@@ -216,7 +216,7 @@ Sends messages to the user.
 **Parameters:**
 - `messages` (ChatMessage[]) - Array of messages to send
 
-**Returns:** Promise<boolean>
+**Returns:** Promise<boolean> - `true` only when the platform confirmed delivery, `false` otherwise (including an unconfirmed result). It never throws, so check the result instead of using try/catch.
 
 **Example:**
 ```typescript
@@ -247,7 +247,7 @@ await user.send([
 
 Clears all user data.
 
-**Returns:** Promise<boolean>
+**Returns:** `Promise<{ success: boolean }>` - `{ success: true }` once the data is cleared. Throws if the clear fails.
 
 **Example:**
 ```typescript

package/docs/api/Workflows.md

@@ -36,9 +36,30 @@ Starts a run.
   - `waitSeconds` (number ≤ 55) — server long-poll
   - `initialState` (object ≤ 64 KB) — seeds `ctx.state`
   - `correlationKey` (string), `tags` (string[] ≤ 10)
-  - `replyTo` (`{ channel, threadId }`) — customer-channel continuation
+  - `replyTo` (`{ channel, threadId }`) — customer-channel continuation; `channel` is one of `whatsapp | sms | email | webchat | slack`
+  - `onBehalfOf` (`{ kind: 'customer', externalId }`) — run as an end customer (`principalKind: 'customer'`; never an approver)
+  - `callback` (boolean) — opt-in loopback: when the run completes, fails or times out, the agent takes one background turn on `originThreadId` with the outcome. Throws `CALLBACK_THREAD_REQUIRED` when there is no origin thread
+  - `originThreadId` (string) — the chat thread the run's cards and callback land on. Defaults to `Lua.request.threadId` when called from a chat turn (a tool or pre/postprocessor); an explicit value must be the calling user's own thread on this agent (`ORIGIN_THREAD_INVALID` otherwise)
+  - `notify` (`'emailApp' | 'email' | 'app' | 'off'`)
   - `workflowVersionId` (string) — pin a version (default: the active one)
 
+Inside a deployed agent (tools, jobs, webhooks, triggers, workflow code steps), an option key that is not listed above throws `WorkflowApiError { code: 'VALIDATION_FAILED' }` naming it, as does a malformed `replyTo` / `onBehalfOf` / `callback` / `initialState` / `notify`.
+
+```typescript
+// From a tool: report back in this chat when the run finishes.
+await Workflows.start('refund-review', { orderId }, { callback: true });
+
+// A customer-facing start that replies on WhatsApp.
+await Workflows.start(
+  'order-status',
+  { orderId },
+  {
+    onBehalfOf: { kind: 'customer', externalId: customerId },
+    replyTo: { channel: 'whatsapp', threadId: waThreadId },
+  }
+);
+```
+
 **Returns:** `Promise<{ runId, status: 'queued' | 'gated' | 'running' | 'completed' | 'failed', output? }>`
 
 ```typescript

package/docs/workflows/approvals.md

@@ -46,6 +46,10 @@ Offline, `lua workflows run --approve <id>` completes the node with `decidedBy:
 
 `timeoutHours` runs on **business time** when `businessHours: { tz, calendar }` is set. `onTimeout` is a chain: each `{ escalateTo, timeoutHours }` hop re-prompts the next audience; the terminal `'deny'` (or `'cancel-run'`/`'continue'`) completes the node — e.g. `{approved:false, timedOut:true, escalations:2}`.
 
+## Reminders
+
+`remindAfterHours: 24` re-sends the approval push to the approvers who still have to decide, every 24 hours while the approval is pending: at most **3 reminders** per ask (an escalation hop is a new ask, so its count starts again), and never at or after the deadline. The reminder replaces the earlier notification in place (same collapse key) and reads "Reminder: …". It takes a plain number of hours in `1..720` (no binding); anything else is refused as `remind-after-invalid`, and a value at or above the first deadline pushes with the `remind-after-exceeds-timeout` warning, because it can never fire. The first deadline is the first escalation hop's `timeoutHours` when `onTimeout` starts with a hop, otherwise `timeoutHours` (168 hours when you leave it out). Reminders ride the approval **push**, so they reach the approvers an agent's approval routing names (shared-agent approvers); an approval with no routing gets the inbox row and the channel fallback but no push, and so no reminder. They are sent on the platform's sweep cadence, so a reminder can arrive a few minutes after it is due, and quiet hours and do-not-disturb drop it like any other push.
+
 ## Edited payloads
 
 `editablePaths: ['amount', 'drafts[*].body']` (the `a.b[0].c` / `[*]` grammar) lets the approver patch the payload — a non-empty list implies `editable: true`, so the flag is optional (3.32.6, LUA-825; an explicit `editable: false` beside paths is refused as contradictory). The sequence is **fetch → patch → approve-with-fingerprint**: the approve call echoes the fingerprint of the revision the approver saw, so a concurrent edit forces a re-read. Out-of-grammar paths are refused; `editedPayloadSchema` validates the result.

package/docs/workflows/coding-harness.md

@@ -4,9 +4,35 @@ _Source of truth: workflows-spec 05 §5.17.6 (D27). This page is the developer s
 
 `harness:'claude-code'` runs Claude Code against Anthropic-class models; `harness:'generic'` runs Lua's own agent loop with the **same nine workspace tools** against any provider your org is allowed — the tool ids, the budget, the secret scan and the turn limit are identical.
 
-- Absent `harness`, the platform derives one from the step's model; the local driver prints the derived value so you see what the server will stamp.
+- Absent `harness`, the platform derives one from the step's model (see [Which model a Job step runs on](#which-model-a-job-step-runs-on)); the local driver prints the derived value so you see what the server will stamp.
 - `LUA_WF_JOB_PROVIDERS` gates providers per org; an out-of-list model is `job-tier-provider-unsupported`.
 - **Org BYOK keys go through the sidecar proxy — your key never enters the agent container.**
 - Billing rows carry `model` + `harness` (seat multiplier per provider).
 
 Offline: `--agents live` with `harness:'generic'` runs the generic provider in-process against **your own** key from the environment (`OPENAI_API_KEY` / `GOOGLE_API_KEY` / `ANTHROPIC_API_KEY`) — billing and governance are server-side only.
+
+## Which model a Job step runs on
+
+A Job-tier step picks its model with one fixed rule:
+
+```
+node.model ?? LUA_WF_JOB_DEFAULT_MODEL ?? org default
+```
+
+`node.model` is the step's own `model`, which may be a literal, a run-input placeholder or `class/<c>`. **The agent that owns the step is not in this chain.** A Job step with no `model` does not use the agent's configured model: it runs, and is billed, on the platform default (`LUA_WF_JOB_DEFAULT_MODEL`), or on the org default where the platform default is unset.
+
+Example (approximate, from a production audit; not a guarantee): with the platform default `claude-opus-4-8` (×16.67) a standard-tier Job attempt costs about 3 × 16.67 ≈ 50.01 actions, while an inline step on a ×0.5 model costs 3 × 0.5 = 1.5. A model-less Job step on a cheap agent still bills the first figure.
+
+**Pin `model` on the step** to choose the model and its price.
+
+Where to read the model a Job step actually uses, and what it multiplies by:
+
+- `lua push` / deploy: the `job-model-default` advisory, one per Job step that names no `model`. It is not shown for a pinned step.
+- The compose plan: the Job row.
+- `lua workflows status --steps`: the `⚙` line per Job attempt (model, leg, multiplier).
+- `lua workflows logs`: the `job model →` line.
+- The `step.job_model_resolved` event, appended once per attempt.
+
+The leg is named in plain words: `node.model`, `platform default`, `org default`, `run input`, `placeholder default` or `lease stamp`.
+
+A non-Anthropic pin must pass `LUA_WF_JOB_PROVIDERS`, and `harness:'claude-code'` needs an Anthropic model (otherwise `WORKFLOW_MODEL_HARNESS_MISMATCH`); use `harness:'generic'` for other providers.

package/docs/workflows/workspaces-and-long-steps.md

@@ -8,9 +8,11 @@ _Source of truth: workflows-spec 05 §5.17 (D19-r1/r2). This page is the develop
 
 `workspace` on `createWorkflow` declares the checkout: `{ kind:'git', repo, ref, credentialsRef, sizeGb?, verify? }` or `{ kind:'empty' }`. Steps mount it with `workspace: { mount: 'rw'|'ro', isolation?: 'worktree' }` and read `ctx.workspace = { root, mount, branch, headSha, isolation, baseSha?, arm?, backend? }` — `root` is the absolute directory of the checkout (`/workspace`); `baseSha` is the commit the run's base ref resolved to at provision (`headSha` is where this step's checkout is), `arm` the worktree arm id under `isolation:'worktree'`, `backend` the volume backend — the three are present when the pod hands the run's stamps to the step and absent otherwise (an `empty` workspace, a shared mount). The pre-3.33 name `path` is served by the Job pod as a deprecated alias for one minor (it warns once per step) and then removed; new code reads `root`.
 
+`ttlHours` is how long a released or held volume is kept before it expires: 72 h by default, 24 h for a completed `keepArtefacts` volume. The platform has a **168 h** ceiling on it, a platform setting that applies once the platform enables it: a larger value is then refused at `lua push` with `workspace-ttl-exceeds-cap` (a non-positive or non-numeric one with `workspace-ttl-invalid`) and held volumes are clamped to 168 h. Until then `lua compile` does not check it, so do not rely on a long hold.
+
 `credentialsRef` is a connection id **or a key you declare under `connections: [{ key, integrationType }]`** — declare a key; it resolves against the owner agent's own connections on any agent at run time (see [Git credentials](./git-credentials.md)), so the definition never freezes a production id.
 
-**Suspension does not release the workspace.** When your run waits for a person or a signal, its volume is left exactly as it was — it keeps holding one of the org's `maxWorkspacesPerOrg` slots until a terminal reason releases it, or, for a kept `empty` workspace, `ttlHours` expires. Releasing a workspace at suspension is not implemented yet (tracked as SA-134); until then, commit before a step suspends so your work is durable on the run branch `lua/wf-<lineageId>` independent of the volume.
+**Suspension does not release the workspace.** When your run waits for a person or a signal, its volume is left exactly as it was — it keeps holding one of the org's `maxWorkspacesPerOrg` slots until a terminal reason releases it, or, for a kept `empty` workspace, `ttlHours` expires (168 h at most once the ceiling is enabled). Releasing a workspace at suspension is not implemented yet (tracked as SA-134); until then, commit before a step suspends so your work is durable on the run branch `lua/wf-<lineageId>` independent of the volume.
 
 **Worktree arms:** parallel arms never share a filesystem; each gets its own clone and branch and the `merge` step integrates them — put `verify` on the workspace so an agent-resolved conflict must pass your tests. `onConflict:'agent'` lets one resolver turn fix conflicts.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lua-cli",
-  "version": "3.42.0-beta.1",
+  "version": "3.42.0-beta.2",
   "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,10 +115,10 @@
     "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/workflow-graph": "0.0.1",
-    "@lua/shared-sandbox": "0.0.1"
+    "@lua/workflow-graph": "0.0.1"
   },
   "scripts": {
     "clean": "rm -rf dist temp",