@ultimat3/ai 25.0.0 → 25.1.0

package/CLAUDE.md

@@ -73,9 +73,9 @@ exposure, the whole input schema (an idempotent action's reserved `idempotencyKe
 | `llm-cache.ts` | the semantic cache half of `llm()`: what a declaration may partition on, and the store it reaches |
 | `llm-fixture.ts` | the harness `llm.test.ts` and `llm-cache.test.ts` share. Not shipped (`!src/**/*-fixture.ts`) |
 | `bounds-fixture.ts` | the one `refusal`/`asyncRefusal` every numeric-bound suite here asserts through. Not shipped, same rule |
-| `agent-bounds.test.ts` | the agent loop's ceilings, split out because `agent.test.ts` is at the 500-line ceiling |
+| `agent-bounds.test.ts` | the agent loop's ceilings (split from `agent.test.ts`, at its line ceiling) |
 | `runtime.ts` | the ambient gateway / embedder / semantic caches an `llm()` reaches |
-| `fix-line.ts` / `fix-line.evals.ts` / `fix-line.v1.baseline.json` / `fix-line.eval.test.ts` | the package's own dogfood eval — the first framework-level `*.eval.test.ts`, proving the `defineEval`/baseline convention actually fails a build |
+| `fix-line-fixture.ts` / `fix-line.evals-fixture.ts` / `fix-line.v1.baseline.json` / `fix-line.eval.test.ts` | the package's dogfood eval — proof the baseline convention fails a build |
 
 ## Invariants — bounds and budget
 
@@ -257,9 +257,11 @@ exposure, the whole input schema (an idempotent action's reserved `idempotencyKe
   unwinds with `X_ABORTED`.
 - **`describeAgents()` / `registeredModels()` are offered, not published** — their only legal consumer
   is `@ultimat3/cli`. The facts are a THUNK; an unnamed agent has no row.
-- **`agentJob()` composes `job()`** (never an imitation handle). `name`, `tenant`, `retry` are
-  REQUIRED; both reads of `target.job()` are LAZY. **Every tool an `agentJob()`'d agent may call must
-  be idempotent** — stated in `AgentJobOptions.idempotencyKey`'s doc and the README, not enforceable.
+- **`agentJob()` composes `job()`** (never an imitation). `name`, `tenant`, `retry` are
+  REQUIRED; both reads of `target.job()` are LAZY. No result is kept: wrap an ACTION that runs the
+  agent and writes, target bound from its input — never a model-aimed write tool; every write
+  idempotent (unenforceable). **`actor`** re-resolves who it acts FOR each attempt (a served worker:
+  ANONYMOUS) via `impersonate`; off-tenant is TERMINAL `X_JOB_TENANT_MISMATCH`.
 
 ## Invariants — evals, retrieval, fix lines
 

package/README.md

@@ -516,6 +516,63 @@ export const summariseBacklog = agentJob(summarisePost, {
 });
 ```
 
+An agent whose policy reads a member — every real app's — names who it runs for. And an agent
+whose result must be KEPT is queued through an action that runs it and makes the write itself.
+
+**Never hand the model a write tool whose target it chooses.** The model's input is text someone
+else wrote — a draft, a ticket, a page — and "now record this for record X" is an instruction a
+model may follow, so a write tool is a write that text can aim. The action binds the target from
+its OWN input, and the agent stays read-only. The reference app's `keepDraftReview` →
+`reviewDraftLater` (`examples/dummy/apps/web/app/posts/actions.ts`, tested on the production
+worker in `review.job.test.ts`) is the worked call:
+
+```ts
+import { action, t } from '@ultimat3/action';
+import { type Actor, userActor } from '@ultimat3/core';
+import { agent, agentJob, definePrompt } from '@ultimat3/ai';
+import { can } from '@ultimat3/policy';
+
+// The app's own reads and its one write, scoped by the job's tenant.
+declare function memberById(id: string): Promise<{ id: string; orgId: string; role: string }>;
+declare function saveReview(postId: string, review: { verdict: string }): Promise<{ verdict: string }>;
+
+// READ-ONLY: no tool here writes, so nothing in the post it reads can aim a write.
+const reviewDraft = agent({
+  input: t.object({ postId: t.uuid, orgId: t.uuid }),
+  output: t.object({ verdict: t.string }),
+  prompt: definePrompt<{ postId: string }>({
+    id: 'review-draft',
+    version: '1.0.0',
+    template: 'Review post {{postId}}.',
+  }),
+  vars: ({ input }) => ({ postId: input.postId }),
+  tools: [],
+  policy: can('post:read'),
+});
+
+// The write, bound to the post id THIS action was given — an upsert, so a replayed run is one row.
+const keepReview = action({
+  input: t.object({ postId: t.uuid, orgId: t.uuid, memberId: t.uuid }),
+  output: t.object({ verdict: t.string }),
+  policy: can('post:publish'),
+  async handle({ input, ctx }) {
+    const review = await reviewDraft.as(ctx.actor, { postId: input.postId, orgId: input.orgId });
+    return saveReview(input.postId, review);
+  },
+});
+
+export const reviewLater = agentJob(keepReview, {
+  name: 'posts.review',
+  tenant: (input) => input.orgId,
+  retry: { attempts: 3, backoff: 'exponential' },
+  // Re-read on every attempt: a member who left, or lost the role, is refused rather than trusted.
+  actor: async ({ input }): Promise<Actor> => {
+    const member = await memberById(input.memberId);
+    return userActor({ id: member.id, orgId: member.orgId, roles: [member.role] });
+  },
+});
+```
+
 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.
@@ -526,7 +583,9 @@ the sweep and `hive()` for the fan-out inside one page.
 | `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 actor is the worker context's, never the model's | the org comes from the job's declared `tenant`; nothing a model emits can reach the identity. In a served app the worker's actor is the **anonymous** one, so a member policy refuses it `X_UNAUTHENTICATED` — declare `actor` |
+| `actor({ input, ctx })` resolves who the run acts FOR, on every attempt | the jobs rule — a job acting for a user takes the user's id in its input and re-authorises it in the body — for a body that is the agent's. Load the member under the job's tenant; the swap is core's `impersonate`, so the worker stays on the record as `onBehalfOf`. An actor in another org than `tenant` is `X_JOB_TENANT_MISMATCH` before the agent starts — terminal, so it dead-letters on attempt 1 |
+| a queued run's return value is **not stored** | `x_jobs` keeps no result column. What the agent produces is kept by the ACTION `agentJob` wraps — it runs the agent, then writes with the ids in its own input — never by a write tool whose target the model picks. That write has to be idempotent (below) |
 
 ### The at-least-once trap, said plainly
 
@@ -535,8 +594,10 @@ one row. One row that a worker claims, half-runs and loses the lease on is claim
 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.
+So every write a run makes has to be idempotent — the wrapping action's, and any tool's: an
+`upsertAll`, an `updateWhere`, a statement whose second run changes nothing. Otherwise a replayed
+attempt issues a second refund. And a write the run needs belongs in the wrapping action, bound to
+its input, rather than in a tool: idempotent is not the same as aimed where you meant.
 
 An action declaring `idempotent: true` offers the model the same optional `idempotencyKey`
 argument `@ultimat3/mcp` advertises, and the key reaches `invoke`: a model retrying an ambiguous

package/package.json

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

package/src/agent-job.ts

@@ -13,8 +13,10 @@
  */
 
 import type { Action, ActionJobHandle } from '@ultimat3/action';
+import type { Actor, Ctx } from '@ultimat3/core';
+import { impersonate, useContext } from '@ultimat3/core';
 import type { JobHandle, JobTenant, RetryPolicy } from '@ultimat3/jobs';
-import { job } from '@ultimat3/jobs';
+import { JobTenantMismatchError, job } from '@ultimat3/jobs';
 import type { InferInput, InferOutput, StandardSchemaV1 } from '@ultimat3/schema';
 
 export interface AgentJobOptions<I> {
@@ -51,6 +53,19 @@ export interface AgentJobOptions<I> {
    * indistinguishable here, and a rule refusing both would be a wrong refusal. See the README.
    */
   idempotencyKey?(input: I): string;
+  /**
+   * Who the run acts FOR, resolved from its own input on EVERY attempt — the jobs rule "a job
+   * acting for a user takes the user's id in its input and re-authorises it in the body", for a
+   * body that is the agent's. Without it the agent, its policy and every tool run as the WORKER,
+   * which in a served app is the anonymous actor: a member rule refuses it `X_UNAUTHENTICATED`.
+   *
+   * Load the member under the job's tenant (the ambient context already carries it) and build the
+   * same actor a request would: a member who left, or lost the role, is refused on the next
+   * attempt rather than trusted from the enqueue. The swap is core's `impersonate`, so the worker
+   * stays on the record as `onBehalfOf`. An actor in another org than `tenant` declared is refused
+   * before the agent starts — `tenant` is the org this run acts under, and nothing moves it.
+   */
+  actor?(args: { readonly input: I; readonly ctx: Ctx }): Promise<Actor> | Actor;
 }
 
 /**
@@ -82,7 +97,31 @@ export function agentJob<TInput extends StandardSchemaV1, TOutput extends Standa
     // 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),
+    run: async ({ input, ctx }) => {
+      if (options.actor === undefined) return bridge().invoke(asInput<TInput>(input), ctx);
+      const actor = await options.actor({ input, ctx });
+      assertSameTenant(options.name, actor, ctx.actor.orgId);
+      return impersonate(actor, `agentJob ${options.name} acts for the actor its input names`, () =>
+        // The CHILD context: the resolved actor, the worker's signal, deadline and services.
+        bridge().invoke(asInput<TInput>(input), useContext()),
+      );
+    },
+  });
+}
+
+/**
+ * The resolver's actor stays inside the org the job declared. Coded and TERMINAL — jobs' own
+ * `X_JOB_TENANT_MISMATCH`, the refusal a webhook delivery naming the wrong org gets — because the
+ * same payload resolves the same foreign actor on every attempt: an unclassified `assert` spent the
+ * whole retry policy re-proving it.
+ */
+function assertSameTenant(name: string, actor: Actor, tenant: string | undefined): void {
+  const orgId = actor.orgId ?? undefined;
+  if (orgId === tenant) return;
+  throw new JobTenantMismatchError({
+    job: name,
+    reason: `resolved an actor in org ${orgId ?? '(none)'} through actor(), but the run is under ${tenant === undefined ? "tenant 'none'" : `org ${tenant}`}, so it would act outside the org it declared`,
+    fix: `actor: ({ input, ctx }) => memberActorIn(ctx.actor.orgId, input) — in agentJob("${name}"), load the member under the job's own tenant, so a member of another org is not found rather than returned`,
   });
 }