@ultimat3/ai 2.0.0 → 3.0.0

package/CLAUDE.md

@@ -4,7 +4,12 @@ Tier 4. May import tier 0–3: `core schema i18n money time cache seo entity pol
 query jobs realtime`. **Never** `mcp manifest render pwa ui admin testing cli`.
 
 Declared today: `action` (the primitive `llm()` returns), `cache` (semantic cache), `core`,
-`db` (pgvector), `money`, `policy`, `schema`, `time`.
+`db` (pgvector), `jobs` (`agentJob()`), `money`, `policy`, `schema`, `time`.
+
+**`jobs` was declared 2026-08, for `agentJob()`.** `packages/action/src/job-handle.ts`'s header
+already named this package as the home: `isJobHandle` needs `kind === 'job'` plus membership of a
+WeakMap only `job()` writes, and `action` and `jobs` are both tier 3, so the bridge has to live at
+tier 4+. Downward edge, nothing new in the tier table.
 
 `mcp` is the same tier, so the LLM-tool projection is restated structurally in `tools.ts`
 rather than imported. Same contract, two wire formats — and the same *decision*: `toLlmTools` and
@@ -44,10 +49,16 @@ until 2026-08, naming a tool no catalog contained (`llm.test.ts`, `agent.test.ts
 | `pg-vector-sql.ts` | every pgvector statement: DDL, upsert, cosine, FTS, RRF fusion |
 | `pg-vector.ts` | `PgVectorStore` — the production store |
 | `rag.ts` | chunker, retriever, reranker, budgeted context assembler |
-| `tools.ts` | action → LLM tool definition; `runLlmToolCall` |
+| `tools.ts` | action → LLM tool definition; the `AgentTool` union and `asProjectableAction`; `runLlmToolCall` |
 | `llm.ts` | `llm()` — the model call, declared as an `action`; and what a streamed answer must satisfy |
 | `llm-stream.ts` | `.stream()`'s plumbing: the sink, the ambient mark, the one-turn drive |
 | `agent.ts` | `agent()` — the tool loop, declared as an `action` |
+| `agent-transcript.ts` | what one turn leaves in the transcript: the assistant replay, the tool results, the correction |
+| `agent-facts.ts` | `describeAgents()` — the agent registry and the row a manifest publishes |
+| `agent-job.ts` | `agentJob()` — an agent as a real `JobHandle`, composed from `job()` |
+| `hive.ts` | `hive()` — one action fanned out over many inputs, declared as an `action` |
+| `hive-result.ts` | `HiveMember` / `HiveResult`, and the SCHEMA built from the member's own `output` |
+| `hive-errors.ts` | the `X_HIVE_*` class; its code and title stay in `errors.ts` |
 | `redaction.ts` | the one gate between `vars()` and the provider: a `Secret` never reaches a prompt |
 | `eval-errors.ts` | the five `X_EVAL_*` classes; their codes and titles stay in `errors.ts` |
 | `runtime.ts` | the ambient gateway / embedder / semantic caches an `llm()` reaches |
@@ -92,6 +103,12 @@ until 2026-08, naming a tool no catalog contained (`llm.test.ts`, `agent.test.ts
   zero leaks the ceiling upward on every release.
 - Cost is `Money` (integer minor units), rounded **up**. Never a float, never a division
   that loses a fraction.
+- **The gateway's two reads of a provider's throw are total.** A `Provider` is the APP's object, so
+  the value it rejects with is one the framework did not build: `isRetryable` indexes it (a getter,
+  or a `Proxy` trap) and fails closed if the read raises, and the failure line goes through core's
+  `renderThrowable` rather than `error.message` / `String(error)` — a renderer that throws replaces
+  `X_AI_PROVIDER_UNAVAILABLE` with a bare `TypeError` nothing catches by code, and it bounds a
+  provider's 1MB body out of the `cause`.
 - Every non-2xx and every in-band `error` frame becomes `AiTransportError`, which carries a real
   `status` field — that field IS the gateway's retry rule. A body parsed as a message would read
   as an empty, successful answer, which is the one outcome nothing downstream can detect.
@@ -261,15 +278,156 @@ until 2026-08, naming a tool no catalog contained (`llm.test.ts`, `agent.test.ts
   (`X_AGENT_MAX_TURNS`, never a partial answer), by `budget.tokensPerRun` (the ledger's `request`
   scope, which accumulates across turns) and by `maxToolResultChars` — the transcript IS the
   request, so an untruncated tool result is re-billed once per remaining turn.
+  - **`tools` takes the real `action()`, adapted at this package's edge — decided 2026-08 (issue
+    #124).** It took `ProjectableAction` alone, which no `action()` structurally satisfies (an
+    action is `as`/`tool`/`openapi`/`job`/`contract` and the callable, never `run`), so the shape
+    the README documents was a `TS2741` and every test here hand-built a stand-in — which is why
+    the suite was green over an API that did not compile. `AgentTool = AnyAction |
+    ProjectableAction` and `asProjectableAction` are the fix, the same union `@ultimat3/mcp`'s
+    `ListedPrimitive` already accepted. **Not** a `run` member on the action facade, which was the
+    obvious alternative and is wrong three times over: it duplicates `.as()` (axiom 1), it would
+    offer a tool named `''` for an action `registerActions` has not named yet, and it would NOT
+    collapse `mcp`'s adapter, whose `toWireSchema` narrows to the subset that server's arg
+    validator can enforce while this one publishes the Messages API's (`packages/mcp/src/
+    from-action.ts` header). Two wire formats, two projections, one `invoke`.
+  - Projection happens on the FIRST RUN, memoised — never at declaration. `agent()` is evaluated at
+    module scope and `registerAction` stamps a name at boot, so `actionName()` at declaration would
+    make the ordinary `export const publishPost = action(...)` beside it `X_ACTION_UNREGISTERED`.
+  - **An `agent()` is a tool of another `agent()`** — it returns an action, and an action is what a
+    tool is. That is the supervisor/sub-agent shape, with no `hive()` and no ninth primitive; the
+    sub-agent runs under the same actor, through its own policy.
   - A tool listed in `agent({ tools })` that is not `mcp: { expose: true }` is
     `X_AGENT_TOOL_UNEXPOSED` **at declaration**, not filtered at the call: a silently dropped tool
     reads as offered and is not. `isMcpExposed` is the one predicate, so an in-app agent and an
-    external MCP client see the same catalogue.
+    external MCP client see the same catalogue. Asked of the DECLARATION, not of the projection,
+    because exposure needs no name and the name does not exist yet.
+  - **`ctx.signal` is read, at three points.** `throwIfAborted` at the top of every turn and before
+    every tool batch, and `GenerateRequest.signal` forwarded into `fetch` by both providers. The
+    transcript IS the request, so a loop that keeps going after the caller disconnects re-sends it
+    once per remaining turn, runs every remaining tool's side effect and discards the answer —
+    eight provider calls for an answer nothing reads. `X_ABORTED` is core's, already shipped; no
+    new code. `signal` is deliberately absent from `cacheKeyFor` and from every estimate: it says
+    whether a call was ABANDONED, never what it asked for.
+  - **The tools of ONE turn run concurrently**, unbounded within the turn, results paired by index
+    so a fast tool cannot be matched to a slow tool's `tool_use` id. Serial cost 5x wall clock for a
+    turn that asked for five tools and nothing in the types or the docs said so. No second ceiling
+    here: the batch is what one model turn asked for, each entry is an action with its own `policy`
+    and `rateLimit`, and a tool that calls a model still queues on the ledger's root turnstile.
+    Guarantee is "no tool STARTS after the abort" — a tool already in flight unwinds through its
+    own handler's reading of `ctx.signal`, which is the action's to make.
+  - **`onTurn` is the per-turn observation, and `.stream()` on `agent()` is deliberately not shipped
+    yet.** A 90-second multi-turn run emitted nothing until it returned. `onTurn` reports facts
+    only — turn, model, tool names, stop reason, usage, that turn's cost — never the transcript and
+    never the actor, and the same facts land on the span as an `agent.turn` event so a run
+    declaring no hook is still readable in a trace. A throw from it FAILS the run: an observer that
+    quietly stopped working reads exactly like one that is fine. Tokens on a screen is a different
+    contract from turns in a loop, and half-shipping it would be the second path axiom 1 refuses.
   - **No semantic cache on `agent()`.** Similar prompts do not have similar answers once the answer
     depends on what `lookupOrder` returned this second.
+  - **Every `tool_use` block the transcript replays is answered by a `tool_result` in the very next
+    message** — the Messages API's own rule, and `agent-transcript.ts` owns both halves of it for
+    that reason. Two paths broke it, both through `respond`, which is filtered out of the calls
+    that RUN and replayed like any other block: a turn emitting a tool call AND `respond` together
+    (ordinary parallel tool use), and a `respond` whose input failed the output schema, followed by
+    a plain user message. Both were a 400 (`tool_use ids were found without tool_result blocks`),
+    i.e. `X_AI_PROVIDER_UNAVAILABLE` in place of a completed run, and `agent.test.ts` never mixed
+    the two so neither shipped visible. An unaccepted `respond` now comes back as its own
+    `tool_result`, `is_error`, saying why — the answer is SUPERSEDED, not wrong: it was written
+    before the results of the tools the same turn asked for existed, so the loop continues and the
+    model answers again with them in hand. Discarding the block instead would have been the other
+    legal fix and loses the record; USING the speculative answer would skip the tool results the
+    model itself asked for, after those tools already ran.
+  - **A tool result is rendered totally.** `runLlmToolCall` returns `content: string` and the loop
+    TRUNCATES it, so `JSON.stringify`'s other two answers both have to be handled: `undefined` for
+    an action that returns nothing (`'null'`), and a throw on a bigint, a cycle or a `toJSON` of
+    the value's own — reported as "the tool ran and its result is not JSON", never as a failure,
+    because a model told the tool failed calls it again and buys its side effects twice. The throw
+    it catches is read with `stringField`, never `typeof error.code === 'string'`: the value is an
+    app's, so the probe is a getter call or a `Proxy` trap inside the catch block.
   - `AiMessage.content` widened to `string | readonly AiContentBlock[]` for this: a `tool_result`
     has to name the `tool_use` it answers and a string has nowhere to put the id. The block field
     names are the Messages API's, so `body()` passes them through untouched.
+- **`hive()` is a fan-out, and the FOURTH instance of the factory rule** (after `llm()`,
+  `backfill()` and `agent()`) — it returns an `action`, never a ninth primitive. It exists because
+  the alternative is a hand-rolled `Promise.all` over `agent()` calls, and that loop gets four
+  things wrong every time: the actor, the order, the difference between ran-and-failed and
+  never-ran, and the ceiling.
+  - **`HiveResult` is a SCHEMA, not an interface**, built from the member action's own `output` and
+    embedded in the `ok` arm. That is what makes a hive project to OpenAPI, the typed client, the
+    MCP `outputSchema` and the manifest like any other action; a hand-written interface would have
+    given the type and none of the six projections, which is the whole reason it is a factory.
+  - **Three arms — `ok` / `failed` / `skipped` — never two.** A member that ran and threw and a
+    member that never ran are different facts, and an aborted sibling is the second. Two arms make
+    "the hive stopped early" indistinguishable from "every remaining item is bad data", which is
+    the difference between retrying the tail and fixing the source. `skipped` gets its own counter
+    beside `ok` and `failed` for the same reason: three arms and two counters means every caller
+    writes `members.length - ok - failed` once, and writes it wrong once.
+  - **`members` is in SPLIT order, always**, filled by index rather than pushed on settle, with
+    `index` on every arm so a caller can join a result back to its row without depending on array
+    position surviving a filter.
+  - **The hive never names an actor.** `split` derives member inputs from `input` and `ctx` and
+    from nothing a model emitted; each member runs through its own callable, so `invoke` applies
+    the member's own `policy` with `ctx.actor` untouched. There is no `as(actor)` in the factory —
+    the same boundary `agent()` holds, and the reason both belong in the framework.
+  - **No hive-specific budget code, deliberately.** One derived ledger for the run, `withBudget`
+    around the pool, each member's `agent()` deriving again — and the ceiling holds under
+    parallelism because `reserve` DEBITS on the root's turnstile before the call. Three members
+    against a ceiling only one fits leave exactly one `ok`; that is asserted through the hive
+    rather than asserted about the ledger, because the ledger already promised it.
+  - **A member's throw is RECORDED, whatever it is.** `failureOf` reads it with `isThrownError` and
+    `stringField` from core, never `error instanceof Error` and `.message`: a member is an app's
+    action, so a `Proxy` makes `instanceof` run a `getPrototypeOf` trap, and a throw there takes
+    down the whole hive — the one outcome the three arms exist to prevent. `skipped` has two
+    reasons, because they are two facts: `SKIPPED_ABORTED` (a sibling failed under `'abort'`) and
+    `SKIPPED_NO_INPUT` (the split produced nothing at that index). One string for both sent a
+    caller to retry a tail that was never cut.
+  - **`onMemberError` is required.** `'abort'` stops and leaves the rest `skipped`; `'collect'`
+    harvests. Both are right for somebody, so neither may be inherited silently.
+  - `concurrency` defaults to 4 and `minMembers` to 2, and neither number is measured off any run —
+    the framework cannot know a provider's concurrency allowance. A below-floor split still runs
+    every input it produced, serially: dropping one would be silent data loss.
+  - An empty split is `X_HIVE_EMPTY`, never a successful run of zero members — "0 ok, 0 failed"
+    cannot be told apart from a query that returned no rows and nobody noticed.
+  - An aborted `ctx` unwinds the whole hive with `X_ABORTED`, which is a DIFFERENT event from
+    `onMemberError: 'abort'`: the latter is a completed run with a partial harvest worth returning,
+    the former has nobody left to hand it to.
+- **`describeAgents()` publishes what an `ActionDescriptor` cannot.** An agent projects to the same
+  descriptor as any other action, and that descriptor knows nothing about turns, tools, models or
+  prompt hashes — so "how far can this loop and what may it call" had no answer outside the source.
+  Same shape as `describePrompts()` / `describeEvals()`, and deliberately NOT a new
+  `ActionDescriptor` field: `@ultimat3/action` is tier 3 and knows nothing about models.
+  The facts are a THUNK, resolved when asked: `agent()` runs at module scope beside the actions it
+  lists, and every name in a row is stamped by `registerAction` at boot. An agent still carrying no
+  name has no row — not a silent drop, but the absence of a capability: an action with no name
+  reaches no route, no tool catalogue and no queue. `named()` builds a TWIN where registration
+  names in place, so an agent renamed that way is absent for the same reason; register it instead.
+- **`agentJob()` closes #125 for the agent case, by COMPOSING `job()`** — the returned value is one
+  `job()` seated in that package's own registry, so `.enqueue()`, the outbox, the worker's
+  cancellation, the dead-letter path, `x jobs show` and its manifest row arrive without a line here.
+  Never an imitation handle: `isJobHandle` needs `kind === 'job'` plus membership of a WeakMap only
+  `job()` writes, which is exactly what stops a second execution path existing.
+  - `name`, `tenant` and `retry` are REQUIRED, no defaults. `name` because a job name is the durable
+    queue key that queued, retrying and dead-lettered rows already carry — deriving it from the
+    export name would move delivery when somebody renames a variable. `tenant` and `retry` because
+    `jobs` states that every candidate default for `tenant` is a cross-tenant read waiting for the
+    first job that takes an org id in its input. Both are `TS2741` when omitted AND have runtime
+    backstops (`X_JOB_TENANT_REQUIRED`, the `retry.attempts` assert), for generated and JS callers.
+  - **Both reads of `target.job()` are LAZY**, and that is load-bearing: `actionName()` throws
+    `X_ACTION_UNREGISTERED` until boot stamps the export name, and `agentJob()` is evaluated at
+    module scope right beside the `agent()` it wraps. Same rule as `agent()`'s tool projection and
+    `describeAgents()`' thunk — third instance in this package.
+  - **The at-least-once trap is DOCUMENTED, not enforced, and that is a decision with evidence.**
+    `idempotencyKey` dedupes the ENQUEUE, never the ATTEMPT: a lost lease re-runs the agent from the
+    top, as does every page `backfill()` replays. So every tool an `agentJob()`'d agent may call has
+    to be idempotent. The framework cannot check it: `mutates` is not a fact an `action()` declares
+    — it exists only in `@ultimat3/mcp`, whose `projectable.ts` sets it to `true` for EVERY action —
+    so a read-only `lookupOrder` and a destructive `issueRefund` are indistinguishable, and
+    `ActionFacade`'s `Pick<>` carries no `idempotent` either (only `describe()` does, and that needs
+    a name). `isMutator` IS legible without a name, but `mutator()` is the local-first write
+    primitive: refusing only those would catch almost none of the risk while reading as if it caught
+    all of it. A wrong refusal is worse than a stated obligation, so the obligation is stated — in
+    `AgentJobOptions.idempotencyKey`'s doc comment and in the README, both naming the second refund.
+
 - **`configureAi({ redact })` is the one seam between `vars()` and the provider.** `vars()` is the
   one declared place a model call loads data, so it is the one place a redactor can see the row
   before it leaves the process; the redactor sees the whole RENDERED prompt and the system prompt,

package/README.md

@@ -300,23 +300,161 @@ export const support = agent({
   output: t.object({ answer: t.string }),
   prompt: supportPrompt,
   vars:   ({ input }) => ({ orderId: input.orderId }),
-  tools:  [lookupOrder, issueRefund],          // actions, each mcp.expose
+  tools:  [lookupOrder, issueRefund],          // real actions, each mcp.expose
   maxTurns: 6,
   maxToolResultChars: 4_000,
   budget: { tokensPerRun: 200_000, costPerCall: { minor: 50, currency: 'USD' } },
   policy: can('order:support'),
+  onTurn: ({ turn, toolCalls, cost }) => progress.push({ turn, toolCalls, cost }),
 });
 ```
 
+`tools` takes the `action()` an app already wrote — `[lookupOrder, issueRefund]`, the imports
+themselves. `As of 2026-08`: it took a hand-shaped `ProjectableAction` until then, so the line
+above was a `TS2741` against every real action (issue #124) and the only thing that satisfied it
+was a stand-in written for a test.
+
+An `agent()` returns an action, so **an agent is a tool of another agent** — a supervisor lists a
+sub-agent in its own `tools` and the sub-agent runs under the same actor, through the same policy.
+No `hive()`, no supervisor primitive: it falls out of the factory rule.
+
 | Rule | Why |
 |---|---|
 | the actor is **`ctx.actor`**, read once, never from the model | this is the mistake a hand-rolled loop ships, and the reason the loop belongs in the framework |
+| an aborted `ctx` unwinds the run — at the top of every turn, before every tool batch, and on the socket | the transcript IS the request, so a loop that keeps going after the caller disconnects re-sends it once per remaining turn, runs every remaining side effect and discards the answer. `ctx.signal` rides on `GenerateRequest` too, so a call already in flight is cut rather than paid for |
+| the tools of **one turn** run concurrently, results paired by `tool_use` id | a turn asking for five tools cost 5x wall clock and nothing said so. Order is positional, never by completion; the batch is bounded by what one turn asked for, and each tool is an action with its own `policy` and `rateLimit`, so a second ceiling here would be a throttle competing with those |
+| `onTurn` reports each completed turn as it happens (and an `agent.turn` span event, always) | a 90-second run emitted nothing until it returned. Observation only — it cannot steer the loop, see the transcript or reach the actor — and a throw from it fails the run rather than being swallowed |
 | a tool that is not `mcp: { expose: true }` is `X_AGENT_TOOL_UNEXPOSED` **at declaration** | a silently dropped tool reads as offered and is not; `isMcpExposed` is the one predicate, so an in-app agent and an external MCP client see the same catalogue |
 | running out of turns is `X_AGENT_MAX_TURNS`, never a partial answer | a half-finished transcript returned as a result is working notes presented as a decision |
 | `budget.tokensPerRun` caps the **whole run** | a single call is bounded by `maxTokens`; a loop is bounded by nothing until this is set |
 | a tool result is truncated, and says so | the transcript IS the request, so an untruncated result is re-billed once per remaining turn |
 | **no semantic cache** | similar prompts do not have similar answers once the answer depends on what `lookupOrder` returned this second |
 
+## `hive()` — many members, one action
+
+Fan an action out over many inputs. The fourth factory over a primitive, after `llm()`,
+`backfill()` and `agent()`: a fan-out is still one server-authoritative operation with an input
+schema, an output schema and a policy.
+
+```ts
+import { action, t } from '@ultimat3/action';
+import { hive } from '@ultimat3/ai';
+import { allow } from '@ultimat3/policy';
+
+const summarisePost = action({
+  input: t.object({ postId: t.uuid }),
+  output: t.object({ summary: t.string }),
+  policy: allow(),
+  mcp: { expose: true },
+  handle: ({ input }) => ({ summary: input.postId }),
+});
+
+export const summariseBacklog = hive({
+  input: t.object({ postIds: t.array(t.uuid) }),
+  member: summarisePost,
+  split: ({ input }) => input.postIds.map((postId) => ({ postId })),
+  concurrency: 8,
+  minMembers: 2,
+  onMemberError: 'collect',
+  budget: { tokensPerRun: 500_000 },
+  policy: allow(),
+});
+```
+
+`member` is any action — most usefully an `agent()`, which makes a hive a **supervisor over
+sub-agents** with no supervisor primitive anywhere.
+
+| Rule | Why |
+|---|---|
+| `members` comes back in **split order**, with `index` on every arm | a hand-rolled `Promise.all` reports in completion order, so joining a result back to the row it came from silently depends on nothing having failed |
+| three arms — `ok`, `failed`, `skipped` — never two | *ran and threw* and *never ran* are different facts, and an aborted sibling is the second. Collapsing them makes "the hive stopped early" read as "every remaining item is bad data" |
+| `onMemberError` is **required** | `'abort'` stops and leaves the rest `skipped`; `'collect'` harvests the rest. Both are right for somebody, so neither is a default |
+| the hive **never names an actor** | `split` derives member inputs from `input` and `ctx` and from nothing a model emitted; each member runs through its own callable, so `invoke` applies the member's own policy with `ctx.actor` untouched |
+| `concurrency` bounds the fan-out; one derived ledger bounds the spend | the ceiling holds under parallelism because the budget's root turnstile debits before the call, so three members against a ceiling only one fits leave exactly one `ok` — no hive-specific budget code exists |
+| an empty split is `X_HIVE_EMPTY` | "0 ok, 0 failed" cannot be told apart from a query that returned no rows and nobody noticed |
+| `minMembers` (default 2) stops fanning out, and **drops nothing** | a member's fixed cost dominates trivial work; below the floor every input still runs, serially |
+| an aborted `ctx` unwinds the whole hive with `X_ABORTED` | distinct from `onMemberError: 'abort'`, which is a completed run with a partial harvest worth returning — here there is nobody left to hand it to |
+
+## `agentJob()` — an agent as durable background work
+
+Run an agent over a million rows as resumable, retried, budgeted queue work. `As of 2026-08` this
+is the only way an agent reaches a queue at all: `.job()` hands back `kind: 'action-job'`, and
+`isJobHandle` needs `kind === 'job'` plus membership of a `WeakMap` only `job()` writes, so nothing
+externally shaped has ever reached the registry, the worker or the dead-letter path (issue #125).
+
+```ts
+import { t } from '@ultimat3/action';
+import { agent, agentJob, definePrompt } from '@ultimat3/ai';
+import { allow } from '@ultimat3/policy';
+
+const summarisePost = agent({
+  input: t.object({ postId: t.uuid, orgId: t.uuid }),
+  output: t.object({ summary: t.string }),
+  prompt: definePrompt<{ postId: string }>({
+    id: 'summarise-post',
+    version: '1.0.0',
+    template: 'Summarise post {{postId}}.',
+  }),
+  vars: ({ input }) => ({ postId: input.postId }),
+  tools: [],
+  policy: allow(),
+});
+
+export const summariseBacklog = agentJob(summarisePost, {
+  name: 'summarise-backlog',
+  tenant: (input) => input.orgId,
+  retry: { attempts: 3, backoff: 'exponential' },
+});
+```
+
+It composes `job()` rather than imitating a handle, so `.enqueue()`, the outbox, the worker's
+cancellation, `x jobs show` and its manifest row all arrive for free. Pair it with `backfill()` for
+the sweep and `hive()` for the fan-out inside one page.
+
+| Rule | Why |
+|---|---|
+| `name` is required, and is the queue key | a job name is what queued, retrying and dead-lettered rows already carry, so renaming an export must not move where they are delivered |
+| `tenant` and `retry` are required, no default | `jobs` states it: every candidate default for `tenant` is a cross-tenant read waiting for the first job that takes an org id in its input. `tenant: 'none'` is the explicit statement that it touches no scoped table |
+| the action projection is read **lazily** | `agentJob()` runs at module scope beside the `agent()` it wraps, and names are stamped by `registerAction` at boot — reading `.job()` eagerly makes that ordinary file `X_ACTION_UNREGISTERED` |
+| one execution path, and it is the action's | `run` is `invoke(agent, input, { surface: 'job', ctx })`, so the agent's policy, input parse, budget scope and span all apply — and the `ctx` is the worker's, so an attempt timing out aborts the agent's turn loop |
+| the actor is the worker context's, never the model's | the job body runs with system authority and the org comes from the job's declared `tenant`; nothing a model emits can reach either |
+
+### The at-least-once trap, said plainly
+
+**`idempotencyKey` dedupes the ENQUEUE, never the ATTEMPT.** Two enqueues with the same payload are
+one row. One row that a worker claims, half-runs and loses the lease on is claimed again, and **the
+agent runs a second time from the top** — as does every page a `backfill()` replays, since its
+`handle` is at-least-once by construction.
+
+So every tool the agent may call has to be idempotent: an `upsertAll`, an `updateWhere`, a statement
+whose second run changes nothing. Otherwise a replayed attempt issues a second refund.
+
+**The framework does not check this, and the reason is worth knowing.** `mutates` is not a fact an
+`action()` declares — it exists only in `@ultimat3/mcp`, which sets it to `true` for *every* action
+it projects — so a read-only `lookupOrder` and a destructive `issueRefund` are indistinguishable
+here. A rule refusing every tool that has not declared `idempotent: true` would refuse the reads
+too, and a wrong refusal is worse than a stated obligation. `isMutator` is legible, but `mutator()`
+is the local-first write primitive and catches almost none of the risk while reading as if it
+caught all of it. This is a contract you keep, not one the compiler keeps for you.
+
+## `describeAgents()` — what the manifest can say
+
+```ts
+import { describeAgents } from '@ultimat3/ai';
+
+describeAgents();
+// [{ name: 'supportAgent', prompt: 'support@1.0.0', promptHash: '…', model: 'claude-opus-5',
+//    maxTurns: 6, maxToolResultChars: 4000, tools: ['issueRefund', 'lookupOrder'],
+//    budget: { tokensIn: null, tokensPerRun: 200000, costPerCall: { minor: 50, currency: 'USD' } },
+//    mcp: true }]
+```
+
+An agent projects to an `ActionDescriptor` like any other action, and that descriptor knows nothing
+about turns or tools — so "how far can this loop, and what may it call" had no answer outside the
+source. Names are read when you ask, not when the agent was declared: `registerAction` stamps them
+at boot, long after `agent()` ran at module scope. An agent nothing registered has no row, because
+an action with no name reaches no route, no tool catalogue and no queue.
+
 ## Redaction: one declared seam
 
 `vars()` is the one place a model call loads data, so it is the one place anything can sit between

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/ai",
-  "version": "2.0.0",
+  "version": "3.0.0",
   "description": "LLM gateway, versioned prompts, evals as tests, embeddings, hybrid vector search, RAG",
   "license": "MIT",
   "type": "module",
@@ -31,13 +31,14 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/action": "2.0.0",
-    "@ultimat3/cache": "2.0.0",
-    "@ultimat3/core": "2.0.0",
-    "@ultimat3/db": "2.0.0",
-    "@ultimat3/money": "2.0.0",
-    "@ultimat3/policy": "2.0.0",
-    "@ultimat3/schema": "2.0.0",
-    "@ultimat3/time": "2.0.0"
+    "@ultimat3/action": "3.0.0",
+    "@ultimat3/cache": "3.0.0",
+    "@ultimat3/core": "3.0.0",
+    "@ultimat3/db": "3.0.0",
+    "@ultimat3/jobs": "3.0.0",
+    "@ultimat3/money": "3.0.0",
+    "@ultimat3/policy": "3.0.0",
+    "@ultimat3/schema": "3.0.0",
+    "@ultimat3/time": "3.0.0"
   }
 }

package/src/agent-facts.ts

@@ -0,0 +1,70 @@
+// What an `agent()` IS, published for the manifest — turns, tools, budget, model, prompt hash.
+//
+// Nothing agent-shaped was visible anywhere before this: an agent projects to `ActionDescriptor`
+// like every other action, and that descriptor deliberately knows nothing about turns or tools,
+// so "which agents does this app have, how far can each one loop, and what may it call" had no
+// answer outside reading the source. Same shape as `describePrompts()` / `describeEvals()`, and
+// deliberately NOT a new `ActionDescriptor` field: @ultimat3/action is tier 3 and knows nothing
+// about models.
+
+import type { AnyAction } from '@ultimat3/action';
+import type { Money } from '@ultimat3/money';
+
+/** The declared ceilings, flattened so a manifest row is plain JSON. `null` is "not declared". */
+export interface AgentBudgetFact {
+  readonly tokensIn: number | null;
+  readonly tokensPerRun: number | null;
+  readonly costPerCall: Money | null;
+}
+
+export interface AgentFact {
+  /** The export name registration stamped — the same name `.tool()` and `tools/call` answer to. */
+  readonly name: string;
+  readonly prompt: string;
+  readonly promptId: string;
+  /**
+   * The prompt's content hash. An agent's behaviour is its prompt, so a row without one records
+   * which agent ran and not which agent it was — the same reason every eval result carries it.
+   */
+  readonly promptHash: string;
+  readonly model: string;
+  readonly maxTurns: number;
+  readonly maxToolResultChars: number;
+  /** Tool names, sorted — the catalogue this agent may call, which is its blast radius. */
+  readonly tools: readonly string[];
+  readonly budget: AgentBudgetFact;
+  /** Whether the agent itself is offered as a tool, so a supervisor could call it. */
+  readonly mcp: boolean;
+}
+
+/**
+ * Keyed by the action, and the facts are a THUNK: every name in a row — the agent's and its
+ * tools' — is stamped by `registerAction` at boot, long after `agent()` ran at module scope.
+ * Reading them here rather than at declaration is what makes a row name what an app can call.
+ */
+const registry = new Map<AnyAction, () => Omit<AgentFact, 'name'>>();
+
+export function registerAgentFact(target: AnyAction, facts: () => Omit<AgentFact, 'name'>): void {
+  registry.set(target, facts);
+}
+
+/**
+ * Every registered agent, by name.
+ *
+ * An agent still carrying no name is left out, and that is not a silent drop: a name is stamped by
+ * `registerAction`, an action without one reaches no route, no tool catalogue and no queue, so
+ * there is no capability for a row to describe. `named()` builds a TWIN rather than naming in
+ * place — registration names in place — so an agent renamed that way is absent for the same
+ * reason. Register it instead: `registerAction('supportAgent', support)`.
+ */
+export function describeAgents(): readonly AgentFact[] {
+  return [...registry.entries()]
+    .filter(([target]) => target.name !== '')
+    .map(([target, facts]) => ({ name: target.name, ...facts() }))
+    .sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+}
+
+/** Test-only reset. A module-level registry otherwise leaks between test files. */
+export function resetAgents(): void {
+  registry.clear();
+}

package/src/agent-job.ts

@@ -0,0 +1,97 @@
+/**
+ * `agentJob()` — an agent as durable, resumable, budgeted background work.
+ *
+ * The bridge `packages/action/src/job-handle.ts` names in its own header and could not build:
+ * `isJobHandle` needs `kind === 'job'` PLUS membership of a WeakMap only `job()` writes, so no
+ * externally-shaped object reaches the registry, the queue or the worker — and `action` and `jobs`
+ * are both tier 3, so neither may import the other. This package is tier 4 and may import both,
+ * which is exactly where that header says the adapter belongs.
+ *
+ * It composes `job()` rather than re-implementing a handle: the returned value IS one `job()`
+ * seated, so `.enqueue()`, the outbox, the worker's cancellation, the dead-letter path,
+ * `x jobs show` and its manifest row all arrive without a line here.
+ */
+
+import type { Action, ActionJobHandle } from '@ultimat3/action';
+import type { JobHandle, JobTenant, RetryPolicy } from '@ultimat3/jobs';
+import { job } from '@ultimat3/jobs';
+import type { InferInput, InferOutput, StandardSchemaV1 } from '@ultimat3/schema';
+
+export interface AgentJobOptions<I> {
+  /**
+   * The durable queue key. REQUIRED and never derived from the agent's export name: a job name is
+   * what queued, retrying and dead-lettered rows already carry, so renaming an export must not
+   * move where they are delivered.
+   */
+  readonly name: string;
+  /**
+   * REQUIRED, no default, and the org this run's body acts under. `jobs` states why: every
+   * candidate default is a cross-tenant read waiting for the first job that takes an org id in its
+   * input. `tenant: 'none'` is the explicit statement that this agent touches no tenant-scoped
+   * table, and then every scoped read inside it fails closed.
+   */
+  readonly tenant: JobTenant<I>;
+  /** REQUIRED, no default. A model call fails transiently; how many times is nobody else's guess. */
+  readonly retry: RetryPolicy;
+  readonly queue?: string;
+  /**
+   * Defaults to the action projection's own key — `action:<name>:<fingerprint of input>` — which
+   * is stable across retries and derived from the payload alone.
+   *
+   * **It dedupes the ENQUEUE, never the ATTEMPT.** Two `enqueue` calls with the same payload are
+   * one row; one row that a worker claims, half-runs and loses the lease on is claimed again, and
+   * the agent runs a second time from the top. Combined with `backfill()`, whose `handle` is at
+   * least once by construction, a replayed page re-runs every agent on it.
+   *
+   * What that means for `tools`: **every tool the agent may call has to be idempotent** — an
+   * `upsertAll`, an `updateWhere`, a statement whose second run changes nothing — because a
+   * replayed attempt issues a second `issueRefund` otherwise. The framework does NOT check this and
+   * cannot: `mutates` is not a fact an `action()` declares (`@ultimat3/mcp` sets it to `true` for
+   * every action it projects), so a read-only `lookupOrder` and a destructive `issueRefund` are
+   * indistinguishable here, and a rule refusing both would be a wrong refusal. See the README.
+   */
+  idempotencyKey?(input: I): string;
+}
+
+/**
+ * Wrap an `agent()` — or any action — as a real job handle.
+ *
+ * Both reads of the underlying projection are LAZY, and that is load-bearing: `target.job()` calls
+ * `actionName()`, which throws `X_ACTION_UNREGISTERED` until `registerAction` stamps the export
+ * name at boot — and `agentJob()` is evaluated at module scope, right beside the `agent()` it
+ * wraps. The queue key comes from `options.name` for the same reason it is required.
+ */
+export function agentJob<TInput extends StandardSchemaV1, TOutput extends StandardSchemaV1>(
+  target: Action<TInput, TOutput>,
+  options: AgentJobOptions<InferOutput<TInput>>,
+): JobHandle<InferOutput<TInput>> {
+  let projected: ActionJobHandle<TInput, TOutput> | undefined;
+  const bridge = (): ActionJobHandle<TInput, TOutput> => {
+    if (projected === undefined) projected = target.job();
+    return projected;
+  };
+  return job<InferOutput<TInput>>({
+    name: options.name,
+    input: target.input as StandardSchemaV1<unknown, InferOutput<TInput>>,
+    tenant: options.tenant,
+    retry: options.retry,
+    ...(options.queue === undefined ? {} : { queue: options.queue }),
+    idempotencyKey: (input) =>
+      options.idempotencyKey?.(input) ?? bridge().idempotencyKey(asInput<TInput>(input)),
+    // ONE execution path, and it is the action's. `ActionJobHandle.invoke` is `invoke(target,
+    // input, { surface: 'job', ctx })`, so the agent's policy, its input parse, its budget scope
+    // and its span all apply — and `ctx` is the WORKER's, so `ctx.signal` aborting at the attempt
+    // timeout reaches the agent's turn loop.
+    run: ({ input, ctx }) => bridge().invoke(asInput<TInput>(input), ctx),
+  });
+}
+
+/**
+ * The job parsed with the action's OWN schema, so what it hands back is a value that schema
+ * accepts — `invoke` re-parses it regardless, which is what makes this safe rather than merely
+ * convenient. The cast exists because `InferOutput` and `InferInput` are different types wherever a
+ * field has a default, and nothing at this seam can prove they meet.
+ */
+function asInput<TInput extends StandardSchemaV1>(value: InferOutput<TInput>): InferInput<TInput> {
+  return value as InferInput<TInput>;
+}