@owlmeans/agent 0.1.18-rc.52 → 0.1.18-rc.54

package/README.md

@@ -14,7 +14,7 @@ import { makeAgentModel } from '@owlmeans/agent'
 const agent = makeAgentModel({
   exec,                      // an @owlmeans/llm Execution — its prompt policy is the persona
   tools,                     // { [name]: StructuredToolInterface }
-  context: [projectBrief],   // volatile context; lands in PromptBlock.Context
+  context: [projectBrief],   // run context; lands in PromptBlock.Context, the project message
 })
 
 const result = await agent.invoke('rename the dashboard header')
@@ -45,9 +45,11 @@ with no agent at all, so a pipeline helper writes to the same store an agent rea
 
 ## Things worth knowing before you change it
 
-**Contributed context goes to `PromptBlock.Context` and nowhere else.** That is the only block a
-provider will not put a cache breakpoint on. Volatile material anywhere above it invalidates the
-prefix that every call sharing a persona pays for.
+**Contributed context goes to `PromptBlock.Context` and nowhere else.** It travels in the project
+message after the system, so the system region — role, skills, packages — stays byte-identical for
+every run of a persona. Run material anywhere in the system invalidates the prefix every call
+sharing that persona pays for. Each round caches the opening (`loopCache` of the model's provider
+plugin) and lets the growing conversation be read back from the round before.
 
 **`toolHelper.safeInvokeTool` must never throw.** A rejected LangGraph task aborts the whole superstep: every
 sibling tool call in the same parallel batch dies with it, discarding work they had already
@@ -84,7 +86,7 @@ This package ships embedded agent skills under `agent-meta/`. After installing y
 your project's skill store (`.agents/skills/`):
 
 ```sh
-npx @owlmeans/agent-skills@^0.1.18-rc.54
+npx @owlmeans/agent-skills@^0.1.18-rc.57
 ```
 
 The embedded files are version-matched to this package release. Do not edit them

package/agent-meta/manifest.json

@@ -1,8 +1,8 @@
 {
-  "schemaVersion": 2,
+  "schemaVersion": 3,
   "package": "@owlmeans/agent",
-  "version": "0.1.18-rc.52",
-  "generatedAt": "2026-10-15T10:20:01.303Z",
+  "version": "0.1.18-rc.54",
+  "generatedAt": "2026-10-20T23:19:58.631Z",
   "canonicalRepo": "https://github.com/owlmeans/common",
   "entries": [
     {
@@ -10,7 +10,62 @@
       "name": "agent",
       "category": "package-specific",
       "file": "skills/agent/SKILL.md",
-      "canonicalPath": ".agents/skills/agent/SKILL.md"
+      "canonicalPath": ".agents/skills/agent/SKILL.md",
+      "parts": [
+        {
+          "name": "cumulative-results",
+          "file": "skills/agent/parts/cumulative-results.md",
+          "description": "Cumulative pipeline results — deterministic extractors, the ledger and its rebuild, how a step's view is cut, refresh, model summaries, composed runs and seeds.",
+          "purposes": [
+            "agent",
+            "job"
+          ],
+          "mentions": [
+            "cumulativeResultsPlugin",
+            "CUMULATIVE_RESULTS_PLUGIN",
+            "CumulativeResultStore",
+            "CumulativeResultFact",
+            "DEFAULT_RESULT_SUMMARY_SCHEMA",
+            "ctx.results",
+            "withResults"
+          ]
+        },
+        {
+          "name": "pipelines",
+          "file": "skills/agent/parts/pipelines.md",
+          "description": "Resumable pipelines over a checkpointed StateGraph — steps and edges, the PipelinePlugin seam, and the rules for run rows, step guards, state size, failures and retries.",
+          "purposes": [
+            "agent",
+            "job",
+            "state"
+          ],
+          "mentions": [
+            "makePipeline",
+            "PipelineSpec",
+            "PipelinePlugin",
+            "asStep",
+            "skipWhen",
+            "nonIdempotent",
+            "makeCheckpointSaver",
+            "PipelineRunStore",
+            "CheckpointStore",
+            "maxStateChars",
+            "ctx.mark",
+            "@owlmeans/agent/pipeline"
+          ]
+        },
+        {
+          "name": "testing",
+          "file": "skills/agent/parts/testing.md",
+          "description": "Unit tests of agents and pipelines with a scripted model double and files kept in deps.",
+          "purposes": [
+            "test"
+          ],
+          "mentions": [
+            "FakeStreamingChatModel"
+          ]
+        }
+      ]
     }
   ]
 }

package/agent-meta/skills/agent/SKILL.md

@@ -8,7 +8,7 @@ user-invocable: false
 # @owlmeans/agent
 
 **Layer:** Cross-cutting domain
-**Install:** `"@owlmeans/agent": "^0.1.18-rc.52"` in `dependencies`, plus the `@langchain/core` and
+**Install:** `"@owlmeans/agent": "^0.1.18-rc.54"` in `dependencies`, plus the `@langchain/core` and
 `@langchain/langgraph` **peers**
 
 The agent runtime. Contracts live in `@owlmeans/agent-common`.
@@ -19,7 +19,7 @@ The agent runtime. Contracts live in `@owlmeans/agent-common`.
 |---|---|
 | `makeAgentModel(options)` | An agent over the LangGraph functional API: `invoke`, `use`, `conversation`. |
 | `makePipeline(spec, options)` | A resumable state machine over a checkpointed LangGraph `StateGraph`: `invoke`, `resume`, `snapshot`, `asStep`. `options.plugins` seats `PipelinePlugin`s. |
-| `cumulativeResultsPlugin(options)` · `CUMULATIVE_RESULTS_PLUGIN` · `DEFAULT_RESULT_SUMMARY_SCHEMA` | CUMULATIVE PIPELINE RESULTS — tells every step what its predecessors produced; see below. |
+| `cumulativeResultsPlugin(options)` · `CUMULATIVE_RESULTS_PLUGIN` · `DEFAULT_RESULT_SUMMARY_SCHEMA` | CUMULATIVE PIPELINE RESULTS — tells every step what its predecessors produced; see the `cumulative-results` part. |
 | `PipelinePlugin` and its events, `StepResults`, `PipelineParentRef` | The pipeline plugin seam (types, from `./pipeline`). |
 | `makeCheckpointSaver(store)` | A `BaseCheckpointSaver` over the `CheckpointStore` port. |
 | `makeAgentsService(options?, alias?)` · `appendAgentsService(ctx, options?, alias?)` · `agentServiceApi(options, self)` | The service, and its half without `createService` for composition. |
@@ -36,124 +36,6 @@ The agent runtime. Contracts live in `@owlmeans/agent-common`.
 
 Subpath exports: `./plugins`, `./helpers`, `./stores`, `./pipeline`, `./checkpoint`.
 
-## Pipelines
-
-A pipeline is a **state machine over named steps** whose position is persisted at every step
-boundary, so a run killed anywhere continues from the step it stopped at rather than from zero.
-
-```ts
-const spec: PipelineSpec = {
-  alias: 'vib:story:design', version: 1,
-  steps: [
-    { step: 'screens' },
-    { step: 'ux', after: ['screens'] },
-    { step: 'data', after: ['screens'] },          // runs BESIDE `ux`
-    { step: 'persist', after: ['ux', 'data'] },    // joins BOTH
-  ],
-}
-
-const pipeline = makePipeline<State, Deps>(spec, { steps, runs, checkpointer, fatal })
-await pipeline.invoke(seed, { runId, deps, scope: projectId })
-await pipeline.resume(runId, { deps, from: 'data' })
-```
-
-**`StateGraph`, not the functional API.** A resume must be able to name the step it starts at, and
-only a graph has named nodes; `entrypoint`/`task` identifies a task by its positional call ordinal,
-which renumbers on any edit to the function — under a file watcher that is the common case, not the
-corner case. The functional API stays exactly where it is, inside `makeAgentModel`'s ReAct loop.
-
-**Edges are `after: string[]`.** Several steps naming one predecessor fan out; one step naming
-several joins them, and the join waits for ALL of them (the array form of `addEdge`, which is a
-barrier — separate single edges would fire on the first). Branching is `skipWhen`, never a
-conditional edge: a branch expressed as an edge is invisible to a resume, while a branch expressed
-as a guard is the same mechanism that makes a resume correct.
-
-**The graph is compiled per run and the steps close over their dependencies.** Passing collaborators
-through the engine's config would make a run depend on which config keys a given LangGraph minor
-propagates into a node body. A closure cannot be lost.
-
-## Pipeline plugins
-
-```ts
-interface PipelinePlugin<S, C> {
-  alias: string; order?: number                     // seated by alias, run by ascending order
-  enter?: (event) => void        // once per invoke/resume: mode fresh|continue|restart, inherited steps, parent
-  beforeStep?: (event) => { results?: StepResults } | void   // the step WILL run; may hand it ctx.results
-  afterStep?: (event) => void    // patch merged into state, BEFORE the row commit marks the step done
-  passStep?: (event) => void     // reason: 'skipped' (guard) | 'failed' (optional step, run goes on)
-  exit?: (event) => void         // once, with the result the caller is about to receive
-}
-```
-
-**A plugin watches a run; it never writes the state and never decides where the run stands.**
-Whatever it keeps, it keeps in a store of its own. `afterStep` runs before the commit so a plugin's
-own write lands before the step is durably done — a crash between the two re-runs the step rather
-than leaving a done step with nothing recorded about it.
-
-**A plugin that throws costs a warning, never the run** — unless `options.fatal` calls the error
-fatal: then it takes the exact path a fatal step error takes, the row written `Failed` first and the
-error rethrown (from `enter`, `passStep` and `exit` too). The runner's stop signal passes through.
-
-**Seating nothing changes nothing.** Every hook site is guarded, so a pipeline without plugins awaits
-nothing it did not await before — its parallel steps interleave identically and its step context
-has no `results` key. `tests/pipeline-compat.spec.ts` pins this with golden rows, trace lines and
-progress events recorded from the runner before the seam existed; it must stay green unedited.
-
-`asStep` passes the composing step to the child as `PipelineInvokeArgs.parent` (read-only:
-pipeline, run id, step, and the parent step's `results`); the child's plugins see it on `enter`.
-
-## Cumulative pipeline results
-
-After each step, code reads what the step produced into FACTS (`CumulativeResultFact`: a type's
-shape and import specifier, an endpoint's method/path/guard, a resource's table, a file) and every
-later step is told them — so it uses the authoritative names instead of re-deriving them.
-
-```ts
-const pipeline = makePipeline<State, Deps>(spec, {
-  steps, runs,
-  plugins: [cumulativeResultsPlugin<State, Deps>({
-    spec: { steps: { types: { extractors: ['ts-types'], full: ['endpoints'] } } }, // or run => spec | null
-    extractors: { 'ts-types': { scope: ({ deps }) => deps.glob('src/types/**'), extract: readTypes } },
-    store,                                    // CumulativeResultStore; share it with composed pipelines
-  })],
-})
-// inside a step:
-const exec = executions().withResults(taskExec, ctx.results?.view)   // every model built from it composes the view
-ctx.results?.record({ files: written })                             // what the step touched
-ctx.results?.facts({ kind: 'type', name: 'User' })                  // typed query for code
-```
-
-- **Extractors are deterministic code, never a model call.** A rebuild after a crash must find
-  exactly what the first pass found. `scope` recomputes the files an extractor answers for from
-  DURABLE inputs (state keys, the file tree), never from what a step reported — it is what a rebuild
-  reads. Declarations name extractors; the plugin holds the code.
-- **The ledger is an optimization, never the authority.** A fresh start or restart clears the run's
-  own entries (and those of runs composed under it); a continuation loads them and silently
-  REBUILDS any missing entry of a finished step from its durable scope. Resume correctness never
-  depends on the store; a failing store is a warning. A step's `record({ facts })`-only facts with
-  no extractor cannot be rebuilt.
-- **A view is cut once per step**: predecessors only (siblings may not have run), full within
-  `window` edges (default 2) or when the producer names the step in `full` (`'*'` for every step),
-  names only beyond, never shown when named in `omit`. Over `maxChars` the OLDEST entries not naming
-  the step go to names only, then out (listed in `view.omitted`); named ones last; an entry's own
-  text is never cut. `facts()` answers from every visible entry regardless of the prompt budget.
-- **A fact belongs to the first entry that produced it** — the step's predecessors and the runs
-  composed under the step itself. A later re-extraction never duplicates it.
-- **A later step that rewrites an earlier entry's files refreshes it**: re-extracted from its own
-  sources, revision bumped, facts about untouched files kept (`refresh: false` opts out). Entries of
-  other pipelines are never refreshed — their extractors live elsewhere.
-- **A skipped step** keeps a stored entry, or gets one rebuilt from its files; **a failed optional
-  step** gets a `partial` entry from what it left behind.
-- **Model summaries are OFF unless a step declares `summary`** and the plugin has `summarize`.
-  The request carries a ready prompt and schema; the answer is rendered deterministically, capped
-  in code, always labelled "not verified", and a failure is a warning without the summary.
-- **A composed run shares its parent's ledger** (parent's, else the root run id); its steps see the
-  parent's view for the composing step, and the parent's later steps see the child's entries,
-  labelled `<composingStep>/<childStep>` and ordered inside the composing step. Both pipelines must
-  be given the SAME store.
-- **Seeds** are facts known before any step ran, visible to every step. A declaration resolved to
-  `null`/`false` leaves that run without `ctx.results` at all.
-
 ## The agent plugin seam
 
 ```ts
@@ -173,10 +55,27 @@ itself does not know those features exist.
 
 ## Rules
 
-**Contributed context goes to `PromptBlock.Context` and nowhere else.** It is the only block a
-provider will not put a cache breakpoint on — the Anthropic plugin explicitly refuses to mark a
-trailing `Context`. Volatile material anywhere above it invalidates the `Role` + `Skills` prefix
-that every call sharing a persona pays for.
+**Contributed context goes to `PromptBlock.Context` and nowhere else.** `AgentOptions.context`,
+`invoke`'s `args.context` and every plugin's `context()` land there — in the project message, the
+user turn right after the system — below the system's cached `Role` + `Skills` and `Packages`
+prefix that every run of a persona shares. The project message is stable for one run and is cached
+for its rounds; volatile material anywhere above it would cost every run sharing the persona a
+cache write.
+
+**The loop's prompt is composed once and marked per round.** The run sends
+`[system, project message, opening, …rounds]`: the system as real text in a `SystemMessage` (never a
+`JSON.stringify`d block array), and the composed Tail on a COPY of the opening, so the transcript
+keeps the caller's message. Each round hands the wire to the provider plugin's
+`loopCache(wire, agentModel, hints)` — it strips and re-marks copies, the opening at its boundaries
+and the growing conversation read back round after round — and streams with the call options it
+returns. The plugin is `AgentOptions.provider ?? llmPluginRegistry.resolveFor(agentModel)`, resolved
+on the unbound model. `cacheSystem: false` on the persona sends no markers. Detail:
+[[llm-prompt-caching]].
+
+**`spectate` gets the turn and the answering model.** `AgentSpectateHook(input, message, action,
+retries, startedAt?, model?)` is called once per round with the turn number as `retries` and the
+agent model's id as `model`, after `cacheHelper.withCacheTiers` has carried a 1-hour cache write
+into the usage.
 
 **A run that exceeds `maxTurns` throws `AgentLoopExhaustedError`.** The ceiling counts tool rounds
 (`DEFAULT_MAX_TURNS` is 64, `AgentOptions.maxTurns` overrides it), and it is reached only when the
@@ -237,41 +136,6 @@ forgetting, which is not a decision one caller has the standing to take. A node
 the context window on knowledge the run cannot tell apart from what it needs; the agent pulls what it
 wants by name.
 
-**The run ROW is the authority on where a run stands — never the LangGraph checkpoint.** The
-checkpoint is size-guarded and expires, so a design that reads a run's position out of it has a
-silent hole exactly where a crashed run needs an answer. Every reader of a position — a resume, a
-reconciler, an operator, a status endpoint — reads the row. With no checkpointer bound at all, a
-resume is still correct; the checkpointer buys replay, never correctness.
-
-**Every step is guarded twice.** The runner refuses to re-enter a step its row calls complete, and
-the application's `skipWhen` reads a durable marker the step itself wrote. The first covers a clean
-crash; the second covers a crash BETWEEN the side effect and the row write, which the first cannot
-see. A step that does N undoable things in a loop marks a cursor with `ctx.mark`.
-
-**A pipeline state is scalars and KEYS.** Ids, revisions, markers, lists of codes — never an
-artifact. The state is serialized into the row at every step boundary, so a field carrying a
-document writes one copy of it per step. Over `maxStateChars` the step FAILS: refused, never
-truncated, because a resume replaying from a cut-down state replays from a state that never existed.
-
-**A step failure is an OUTCOME, not a throw.** `invoke`/`resume` return
-`{ status: Failed, failedAt, error }`, because every caller has a status, a warning or a record to
-write before it decides anything, and a throwing runner puts that in a `catch` where it gets
-forgotten. The one exception is `options.fatal`: those are written to the row Failed FIRST and then
-rethrown, so an exhausted budget cannot become a result a caller carries on from.
-
-**No default retry.** `attempts` defaults to 1, because retry budgets in this family MULTIPLY — an
-outer retry around a model's own inner retry is their product. `attempts > 1` on a `nonIdempotent`
-step is refused at build time: an automatic retry is exactly what that flag says must not happen.
-
-**`nonIdempotent` marks a step whose side effect cannot be undone** — a wipe, a purge, a claim
-against a rate-limited authority, a model call whose output is already on disk. `resume({ from })`
-refuses to re-enter a completed one without `force`.
-
-**A ReAct run is not a resumable unit, and that is why `makeAgentModel` still builds its
-`entrypoint` inside `invoke()`.** Its state is an unbounded message list whose tool results are side
-effects already applied to the world: re-entering a turn re-applies them. What IS resumable is a
-pipeline — and an agent run belongs inside one of its steps.
-
 **`toolHelper.safeInvokeTool(tools, call, fatal?)` takes a fatal predicate.** Containment is right for a bad
 argument and wrong for an exhausted budget: a tool may be a whole pipeline behind one call, and
 handing the model a readable "out of tokens" is an invitation to pick another tool and spend again.
@@ -280,19 +144,18 @@ handing the model a readable "out of tokens" is an invitation to pick another to
 name first and only re-reads it as a serialized token once the provider throws — returning null
 would break every restore.
 
-## Testing
-
-Category A (unit, no env, no network). The model is doubled with a small scripted object in
-`tests/_tools/model.ts` because `@langchain/core`'s own `FakeStreamingChatModel` always replays its
-first response and so cannot drive a tool loop. That double stands in for the MODEL, an external
-boundary — never for an `@owlmeans/*` package. The cumulative-results specs keep the project as a
-`Map` of files in `deps` — the durable input extractors read — so a "new process" is a new plugin
-over the same files.
-
 ## Related
 
 - [[agent-common]] — the serializable records and the run lifecycle flow
 - [[llm]] — `Execution`, the model contract and the `advise`-only `ExecutionPlugin`
 - [[agent-checkpoint]] — the durable Mongo implementation of both storage ports (internal)
 - [[llm-prompt-caching]] — which block contributed context lands in, and why
-- [[agent-skills]] — `projectSkillsAgentPlugin` and the `read_skill` tool
+- [[agent-skills]] — `owlmeansPackagesPlugin`, the prompt plugin that loads package skills on agent runs too
+
+## Parts
+
+| Part | Load it when |
+|---|---|
+| [pipelines](parts/pipelines.md) | declaring or running a pipeline, writing a pipeline plugin, or resuming a run |
+| [cumulative-results](parts/cumulative-results.md) | telling a pipeline's later steps what earlier steps produced, or writing an extractor |
+| [testing](parts/testing.md) | writing tests that drive an agent loop or a pipeline |

package/agent-meta/skills/agent/parts/cumulative-results.md

@@ -0,0 +1,62 @@
+---
+name: cumulative-results
+description: Cumulative pipeline results — deterministic extractors, the ledger and its rebuild, how a step's view is cut, refresh, model summaries, composed runs and seeds.
+metadata:
+  purposes: agent, job
+  mentions: cumulativeResultsPlugin, CUMULATIVE_RESULTS_PLUGIN, CumulativeResultStore, CumulativeResultFact, DEFAULT_RESULT_SUMMARY_SCHEMA, ctx.results, withResults
+---
+<!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
+
+# @owlmeans/agent — Cumulative pipeline results
+
+## Cumulative pipeline results
+
+After each step, code reads what the step produced into FACTS (`CumulativeResultFact`: a type's
+shape and import specifier, an endpoint's method/path/guard, a resource's table, a file) and every
+later step is told them — so it uses the authoritative names instead of re-deriving them.
+
+```ts
+const pipeline = makePipeline<State, Deps>(spec, {
+  steps, runs,
+  plugins: [cumulativeResultsPlugin<State, Deps>({
+    spec: { steps: { types: { extractors: ['ts-types'], full: ['endpoints'] } } }, // or run => spec | null
+    extractors: { 'ts-types': { scope: ({ deps }) => deps.glob('src/types/**'), extract: readTypes } },
+    store,                                    // CumulativeResultStore; share it with composed pipelines
+  })],
+})
+// inside a step:
+const exec = executions().withResults(taskExec, ctx.results?.view)   // every model built from it composes the view
+ctx.results?.record({ files: written })                             // what the step touched
+ctx.results?.facts({ kind: 'type', name: 'User' })                  // typed query for code
+```
+
+- **Extractors are deterministic code, never a model call.** A rebuild after a crash must find
+  exactly what the first pass found. `scope` recomputes the files an extractor answers for from
+  DURABLE inputs (state keys, the file tree), never from what a step reported — it is what a rebuild
+  reads. Declarations name extractors; the plugin holds the code.
+- **The ledger is an optimization, never the authority.** A fresh start or restart clears the run's
+  own entries (and those of runs composed under it); a continuation loads them and silently
+  REBUILDS any missing entry of a finished step from its durable scope. Resume correctness never
+  depends on the store; a failing store is a warning. A step's `record({ facts })`-only facts with
+  no extractor cannot be rebuilt.
+- **A view is cut once per step**: predecessors only (siblings may not have run), full within
+  `window` edges (default 2) or when the producer names the step in `full` (`'*'` for every step),
+  names only beyond, never shown when named in `omit`. Over `maxChars` the OLDEST entries not naming
+  the step go to names only, then out (listed in `view.omitted`); named ones last; an entry's own
+  text is never cut. `facts()` answers from every visible entry regardless of the prompt budget.
+- **A fact belongs to the first entry that produced it** — the step's predecessors and the runs
+  composed under the step itself. A later re-extraction never duplicates it.
+- **A later step that rewrites an earlier entry's files refreshes it**: re-extracted from its own
+  sources, revision bumped, facts about untouched files kept (`refresh: false` opts out). Entries of
+  other pipelines are never refreshed — their extractors live elsewhere.
+- **A skipped step** keeps a stored entry, or gets one rebuilt from its files; **a failed optional
+  step** gets a `partial` entry from what it left behind.
+- **Model summaries are OFF unless a step declares `summary`** and the plugin has `summarize`.
+  The request carries a ready prompt and schema; the answer is rendered deterministically, capped
+  in code, always labelled "not verified", and a failure is a warning without the summary.
+- **A composed run shares its parent's ledger** (parent's, else the root run id); its steps see the
+  parent's view for the composing step, and the parent's later steps see the child's entries,
+  labelled `<composingStep>/<childStep>` and ordered inside the composing step. Both pipelines must
+  be given the SAME store.
+- **Seeds** are facts known before any step ran, visible to every step. A declaration resolved to
+  `null`/`false` leaves that run without `ctx.results` at all.

package/agent-meta/skills/agent/parts/pipelines.md

@@ -0,0 +1,113 @@
+---
+name: pipelines
+description: Resumable pipelines over a checkpointed StateGraph — steps and edges, the PipelinePlugin seam, and the rules for run rows, step guards, state size, failures and retries.
+metadata:
+  purposes: agent, job, state
+  mentions: makePipeline, PipelineSpec, PipelinePlugin, asStep, skipWhen, nonIdempotent, makeCheckpointSaver, PipelineRunStore, CheckpointStore, maxStateChars, ctx.mark, @owlmeans/agent/pipeline
+---
+<!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
+
+# @owlmeans/agent — Pipelines
+
+## Pipelines
+
+A pipeline is a **state machine over named steps** whose position is persisted at every step
+boundary, so a run killed anywhere continues from the step it stopped at rather than from zero.
+
+```ts
+const spec: PipelineSpec = {
+  alias: 'vib:story:design', version: 1,
+  steps: [
+    { step: 'screens' },
+    { step: 'ux', after: ['screens'] },
+    { step: 'data', after: ['screens'] },          // runs BESIDE `ux`
+    { step: 'persist', after: ['ux', 'data'] },    // joins BOTH
+  ],
+}
+
+const pipeline = makePipeline<State, Deps>(spec, { steps, runs, checkpointer, fatal })
+await pipeline.invoke(seed, { runId, deps, scope: projectId })
+await pipeline.resume(runId, { deps, from: 'data' })
+```
+
+**`StateGraph`, not the functional API.** A resume must be able to name the step it starts at, and
+only a graph has named nodes; `entrypoint`/`task` identifies a task by its positional call ordinal,
+which renumbers on any edit to the function — under a file watcher that is the common case, not the
+corner case. The functional API stays exactly where it is, inside `makeAgentModel`'s ReAct loop.
+
+**Edges are `after: string[]`.** Several steps naming one predecessor fan out; one step naming
+several joins them, and the join waits for ALL of them (the array form of `addEdge`, which is a
+barrier — separate single edges would fire on the first). Branching is `skipWhen`, never a
+conditional edge: a branch expressed as an edge is invisible to a resume, while a branch expressed
+as a guard is the same mechanism that makes a resume correct.
+
+**The graph is compiled per run and the steps close over their dependencies.** Passing collaborators
+through the engine's config would make a run depend on which config keys a given LangGraph minor
+propagates into a node body. A closure cannot be lost.
+
+## Pipeline plugins
+
+```ts
+interface PipelinePlugin<S, C> {
+  alias: string; order?: number                     // seated by alias, run by ascending order
+  enter?: (event) => void        // once per invoke/resume: mode fresh|continue|restart, inherited steps, parent
+  beforeStep?: (event) => { results?: StepResults } | void   // the step WILL run; may hand it ctx.results
+  afterStep?: (event) => void    // patch merged into state, BEFORE the row commit marks the step done
+  passStep?: (event) => void     // reason: 'skipped' (guard) | 'failed' (optional step, run goes on)
+  exit?: (event) => void         // once, with the result the caller is about to receive
+}
+```
+
+**A plugin watches a run; it never writes the state and never decides where the run stands.**
+Whatever it keeps, it keeps in a store of its own. `afterStep` runs before the commit so a plugin's
+own write lands before the step is durably done — a crash between the two re-runs the step rather
+than leaving a done step with nothing recorded about it.
+
+**A plugin that throws costs a warning, never the run** — unless `options.fatal` calls the error
+fatal: then it takes the exact path a fatal step error takes, the row written `Failed` first and the
+error rethrown (from `enter`, `passStep` and `exit` too). The runner's stop signal passes through.
+
+**Seating nothing changes nothing.** Every hook site is guarded, so a pipeline without plugins awaits
+nothing it did not await before — its parallel steps interleave identically and its step context
+has no `results` key. `tests/pipeline-compat.spec.ts` pins this with golden rows, trace lines and
+progress events recorded from the runner before the seam existed; it must stay green unedited.
+
+`asStep` passes the composing step to the child as `PipelineInvokeArgs.parent` (read-only:
+pipeline, run id, step, and the parent step's `results`); the child's plugins see it on `enter`.
+
+## Rules
+
+**The run ROW is the authority on where a run stands — never the LangGraph checkpoint.** The
+checkpoint is size-guarded and expires, so a design that reads a run's position out of it has a
+silent hole exactly where a crashed run needs an answer. Every reader of a position — a resume, a
+reconciler, an operator, a status endpoint — reads the row. With no checkpointer bound at all, a
+resume is still correct; the checkpointer buys replay, never correctness.
+
+**Every step is guarded twice.** The runner refuses to re-enter a step its row calls complete, and
+the application's `skipWhen` reads a durable marker the step itself wrote. The first covers a clean
+crash; the second covers a crash BETWEEN the side effect and the row write, which the first cannot
+see. A step that does N undoable things in a loop marks a cursor with `ctx.mark`.
+
+**A pipeline state is scalars and KEYS.** Ids, revisions, markers, lists of codes — never an
+artifact. The state is serialized into the row at every step boundary, so a field carrying a
+document writes one copy of it per step. Over `maxStateChars` the step FAILS: refused, never
+truncated, because a resume replaying from a cut-down state replays from a state that never existed.
+
+**A step failure is an OUTCOME, not a throw.** `invoke`/`resume` return
+`{ status: Failed, failedAt, error }`, because every caller has a status, a warning or a record to
+write before it decides anything, and a throwing runner puts that in a `catch` where it gets
+forgotten. The one exception is `options.fatal`: those are written to the row Failed FIRST and then
+rethrown, so an exhausted budget cannot become a result a caller carries on from.
+
+**No default retry.** `attempts` defaults to 1, because retry budgets in this family MULTIPLY — an
+outer retry around a model's own inner retry is their product. `attempts > 1` on a `nonIdempotent`
+step is refused at build time: an automatic retry is exactly what that flag says must not happen.
+
+**`nonIdempotent` marks a step whose side effect cannot be undone** — a wipe, a purge, a claim
+against a rate-limited authority, a model call whose output is already on disk. `resume({ from })`
+refuses to re-enter a completed one without `force`.
+
+**A ReAct run is not a resumable unit, and that is why `makeAgentModel` still builds its
+`entrypoint` inside `invoke()`.** Its state is an unbounded message list whose tool results are side
+effects already applied to the world: re-entering a turn re-applies them. What IS resumable is a
+pipeline — and an agent run belongs inside one of its steps.

package/agent-meta/skills/agent/parts/testing.md

@@ -0,0 +1,19 @@
+---
+name: testing
+description: Unit tests of agents and pipelines with a scripted model double and files kept in deps.
+metadata:
+  purposes: test
+  mentions: FakeStreamingChatModel
+---
+<!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
+
+# @owlmeans/agent — Testing
+
+## Testing
+
+Category A (unit, no env, no network). The model is doubled with a small scripted object in
+`tests/_tools/model.ts` because `@langchain/core`'s own `FakeStreamingChatModel` always replays its
+first response and so cannot drive a tool loop. That double stands in for the MODEL, an external
+boundary — never for an `@owlmeans/*` package. The cumulative-results specs keep the project as a
+`Map` of files in `deps` — the durable input extractors read — so a "new process" is a new plugin
+over the same files.

package/build/model.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"model.d.ts","sourceRoot":"","sources":["../src/model.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EACV,UAAU,EAAE,YAAY,EACzB,MAAM,YAAY,CAAA;AAKnB;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,cAAc,YAAa,YAAY,KAAG,UAgQtD,CAAA"}
+{"version":3,"file":"model.d.ts","sourceRoot":"","sources":["../src/model.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EACV,UAAU,EAAE,YAAY,EACzB,MAAM,YAAY,CAAA;AA6BnB;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,cAAc,YAAa,YAAY,KAAG,UAmRtD,CAAA"}

package/build/model.js

@@ -2,13 +2,35 @@ import { AIMessage, HumanMessage, SystemMessage, ToolMessage } from '@langchain/
 import { addMessages, entrypoint, task } from '@langchain/langgraph';
 import { createIdOfLength } from '@owlmeans/basic-ids';
 import { makeFlowModel } from '@owlmeans/flow';
-import { llmPluginRegistry } from '@owlmeans/llm';
+import { PromptRegion } from '@owlmeans/llm-common';
+import { cacheHelper, llmPluginRegistry } from '@owlmeans/llm';
 import { logger } from '@owlmeans/log';
 import { AgentRunStatus, AgentRunTransition, agentRunFlow, conversationFor, } from '@owlmeans/agent-common';
 import { DEFAULT_ACTION, DEFAULT_ENTRYPOINT, DEFAULT_MAX_TURNS, DEFAULT_PLUGIN_ORDER } from './consts.js';
 import { AgentLoopExhaustedError, AgentMissconfiguredError } from './errors.js';
 import { toolHelper } from './helpers/tools.js';
 const log = logger('agent');
+/**
+ * A copy of the opening with the per-call tail after its payload — a string stays a string. The
+ * opening itself stays in the transcript untouched; only the wire carries the tail.
+ */
+const withTail = (opening, tail) => {
+    if (opening.getType() !== 'human') {
+        return [opening, new HumanMessage({ content: tail })];
+    }
+    const content = typeof opening.content === 'string'
+        ? `${opening.content}\n\n${tail}`
+        : [...opening.content, { type: 'text', text: tail }];
+    return [new HumanMessage({
+            content, id: opening.id, name: opening.name, additional_kwargs: opening.additional_kwargs,
+        })];
+};
+/** The provider's id of the model a run talks to, for billing — the config's, else the client's own. */
+const modelIdOf = (model) => {
+    const typed = model;
+    const id = typed.metadata?.config?.model ?? typed.model ?? typed.modelName;
+    return typeof id === 'string' ? id : undefined;
+};
 /**
  * An OwlMeans agent over the LangGraph functional API.
  *
@@ -34,7 +56,8 @@ export const makeAgentModel = (options) => {
     }
     const conversation = options.conversation ?? conversationFor(exec.purpose);
     const prompts = options.prompts ?? exec.prompts;
-    const provider = options.provider ?? llmPluginRegistry.pluginFor(agentModel);
+    const provider = options.provider ?? llmPluginRegistry.resolveFor(agentModel);
+    const modelId = modelIdOf(agentModel);
     const purpose = exec.purpose;
     const registry = [];
     const ordered = () => [...registry].sort((a, b) => (a.order ?? DEFAULT_PLUGIN_ORDER) - (b.order ?? DEFAULT_PLUGIN_ORDER));
@@ -107,26 +130,45 @@ export const makeAgentModel = (options) => {
                     results: exec.results,
                 })
                 : null;
-            const system = composed?.system?.content
-                ?? (context.length > 0 ? context.join('\n\n') : '');
-            const systemMessage = new SystemMessage(typeof system === 'string' ? system : JSON.stringify(system));
+            // The opening of every round: the system (a persona, stable across runs), the project
+            // message (this run's facts), and the caller's opening carrying the per-call tail. The system
+            // goes out as real text — its cache blocks are the provider plugin's, never a stringified array.
+            const system = composed != null ? composed.system ?? '' : context.join('\n\n');
+            const head = [
+                ...(system !== '' ? [new SystemMessage(system)] : []),
+                ...(composed?.project != null ? [new HumanMessage(composed.project)] : []),
+            ];
+            const hints = {
+                system: composed?.blocks.filter(block => block.region === PromptRegion.System),
+                ...(composed?.project != null ? { project: head.length - 1 } : {}),
+                ...(composed != null ? { ttl: composed.cache.ttl } : {}),
+            };
+            const cached = composed?.cache.enabled !== false;
             const tooled = agentModel.bindTools?.(Object.values(toolSet)) ?? agentModel;
-            const ask = task('call-llm', async (messages) => {
+            const ask = task('call-llm', async ({ messages, turn }) => {
                 const startedAt = Date.now();
-                const stream = await tooled.stream([systemMessage, ...messages], { runName: action, metadata: { purpose } });
+                const [first, ...rest] = messages;
+                const opening = composed?.tail != null && first != null ? withTail(first, composed.tail) : [first];
+                const wire = [...head, ...opening, ...rest].filter(message => message != null);
+                // Each round strips and re-marks copies: the system and project message once, and the
+                // growing conversation read back from the round before.
+                const patch = cached
+                    ? provider?.loopCache?.(wire, agentModel, hints)
+                    : undefined;
+                const stream = await tooled.stream((patch?.messages ?? wire), { ...patch?.options, runName: action, metadata: { purpose } });
                 let final;
                 for await (const chunk of stream) {
                     final = final != null ? final.concat(chunk) : chunk;
                 }
-                const result = new AIMessage(final);
-                await spectate?.(messages, result, action, 0, startedAt);
+                const result = new AIMessage(cacheHelper.withCacheTiers(final));
+                await spectate?.(messages, result, action, turn, startedAt, modelId);
                 return result;
             });
             // A rejected task aborts the whole superstep, killing every sibling call in the same batch —
             // `safeInvokeTool` is what keeps a bad argument from costing the work the others finished.
             const call = task('call-tool', async (toolCall) => toolHelper.safeInvokeTool(toolSet, toolCall, options.fatal));
             const agent = entrypoint(entrypointName, async (messages) => {
-                let response = await ask(messages);
+                let response = await ask({ messages, turn: 0 });
                 let turn = 0;
                 while (true) {
                     messages = addMessages(messages, [response]);
@@ -163,7 +205,7 @@ export const makeAgentModel = (options) => {
                         });
                     }));
                     messages = addMessages(messages, results);
-                    response = await ask(messages);
+                    response = await ask({ messages, turn });
                 }
                 return messages;
             });

package/build/model.js.map

@@ -1 +1 @@
-{"version":3,"file":"model.js","sourceRoot":"","sources":["../src/model.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"model.js","sourceRoot":"","sources":["../src/model.ts"],"names":[],"mappings":"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"}

package/build/plugins/summarize.d.ts

@@ -10,7 +10,7 @@ import type { SummarizeOptions } from './types.js';
  *
  * What it contributes is rendered as clearly delimited, explicitly untrusted material. These are
  * model words derived from user input, stored and replayed into a later prompt: they belong in the
- * volatile context block, described as a record of what happened, never as instructions.
+ * context block of the project message, described as a record of what happened, never as instructions.
  */
 export declare const summarizePlugin: (options?: SummarizeOptions) => AgentPlugin;
 //# sourceMappingURL=summarize.d.ts.map

package/build/plugins/summarize.js

@@ -12,7 +12,7 @@ import { compactionHelper } from '../helpers/compaction.js';
  *
  * What it contributes is rendered as clearly delimited, explicitly untrusted material. These are
  * model words derived from user input, stored and replayed into a later prompt: they belong in the
- * volatile context block, described as a record of what happened, never as instructions.
+ * context block of the project message, described as a record of what happened, never as instructions.
  */
 export const summarizePlugin = (options = {}) => {
     const { store, model, maxSummaryChars = DEFAULT_SUMMARY_CHARS, maxAdviceChars = DEFAULT_ADVICE_CHARS, window = DEFAULT_EVENT_WINDOW, action = 'agent-compaction', onEvent, } = options;

package/build/types.d.ts

@@ -17,10 +17,11 @@ export interface AgentToolSet {
  * What the caller gets told about each model call.
  *
  * Shaped to match `spectate(spectator, callType)` from `@owlmeans/llm` exactly, so an application
- * that already has a spectator passes the curried function straight in.
+ * that already has a spectator passes the curried function straight in. `retries` carries the
+ * loop's turn number, and `model` the id of the model that answered.
  */
 export interface AgentSpectateHook {
-    (input: ModelInputItem[], message: AIMessage, action: string, retries: number, startedAt?: number): Promise<unknown>;
+    (input: ModelInputItem[], message: AIMessage, action: string, retries: number, startedAt?: number, model?: string): Promise<unknown>;
 }
 export interface AgentOptions {
     /** The execution the run belongs to. Its `prompt` policy is the agent's persona. */
@@ -28,7 +29,10 @@ export interface AgentOptions {
     /** Overrides the model resolved from the execution. */
     agentModel?: BaseChatModel;
     tools: AgentToolSet;
-    /** Static volatile context. Lands in `PromptBlock.Context`, never in the cached prefix. */
+    /**
+     * Static context. Lands in `PromptBlock.Context` — the project message, behind the cached
+     * system region — never in the system message other runs share.
+     */
     context?: string[];
     conversation?: ConversationRef;
     /** LangGraph entrypoint name; shows up in traces. */
@@ -41,7 +45,10 @@ export interface AgentOptions {
      * by default: the agent holds an execution, not the service that knows its policy.
      */
     utility?: () => BaseChatModel | undefined;
-    /** Provider plugin used for cache placement. Resolved from the model when omitted. */
+    /**
+     * Provider plugin used for cache placement. Resolved from the model when omitted
+     * (`llmPluginRegistry.resolveFor`, so a model the service built gets its own provider's).
+     */
     provider?: LlmPlugin;
     maxTurns?: number;
     /**
@@ -65,7 +72,7 @@ export interface AgentOptions {
 export interface AgentInvokeArgs {
     /** LangChain `runName` for the model calls of this run. */
     action?: string;
-    /** Extra volatile context for this call only. */
+    /** Extra context for this run only — it joins the project message. */
     context?: string[];
 }
 export interface AgentRunOutcome {

package/build/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owlmeans/agent",
-  "version": "0.1.18-rc.52",
+  "version": "0.1.18-rc.54",
   "license": "MIT",
   "type": "module",
   "scripts": {
@@ -68,14 +68,14 @@
     "@langchain/langgraph-checkpoint": "^1.1.5"
   },
   "dependencies": {
-    "@owlmeans/agent-common": "^0.1.18-rc.49",
-    "@owlmeans/basic-ids": "^0.1.18-rc.40",
-    "@owlmeans/context": "^0.1.18-rc.34",
-    "@owlmeans/error": "^0.1.18-rc.38",
-    "@owlmeans/flow": "^0.1.18-rc.45",
-    "@owlmeans/llm": "^0.1.18-rc.50",
-    "@owlmeans/llm-common": "^0.1.18-rc.39",
-    "@owlmeans/log": "^0.1.18-rc.3",
+    "@owlmeans/agent-common": "^0.1.18-rc.50",
+    "@owlmeans/basic-ids": "^0.1.18-rc.41",
+    "@owlmeans/context": "^0.1.18-rc.35",
+    "@owlmeans/error": "^0.1.18-rc.39",
+    "@owlmeans/flow": "^0.1.18-rc.46",
+    "@owlmeans/llm": "^0.1.18-rc.52",
+    "@owlmeans/llm-common": "^0.1.18-rc.40",
+    "@owlmeans/log": "^0.1.18-rc.4",
     "ajv": "^8.20.0"
   },
   "publishConfig": {

package/src/model.ts

@@ -1,11 +1,12 @@
 import { AIMessage, HumanMessage, SystemMessage, ToolMessage } from '@langchain/core/messages'
-import type { AIMessageChunk, BaseMessage, BaseMessageLike, ToolCall } from '@langchain/core/messages'
+import type { AIMessageChunk, BaseMessage, BaseMessageLike, MessageFieldWithRole, ToolCall } from '@langchain/core/messages'
 import { addMessages, entrypoint, task } from '@langchain/langgraph'
 import { createIdOfLength } from '@owlmeans/basic-ids'
 import { makeFlowModel } from '@owlmeans/flow'
 import type { FlowModel } from '@owlmeans/flow'
-import { llmPluginRegistry } from '@owlmeans/llm'
-import type { HelperExecution, ModelInputItem } from '@owlmeans/llm'
+import { PromptRegion } from '@owlmeans/llm-common'
+import { cacheHelper, llmPluginRegistry } from '@owlmeans/llm'
+import type { HelperExecution, LlmLoopCacheHints, ModelInputItem } from '@owlmeans/llm'
 import { logger } from '@owlmeans/log'
 import {
   AgentRunStatus, AgentRunTransition, agentRunFlow, conversationFor,
@@ -19,6 +20,30 @@ import { toolHelper } from './helpers/tools.js'
 
 const log = logger('agent')
 
+/**
+ * A copy of the opening with the per-call tail after its payload — a string stays a string. The
+ * opening itself stays in the transcript untouched; only the wire carries the tail.
+ */
+const withTail = (opening: BaseMessage, tail: string): BaseMessage[] => {
+  if (opening.getType() !== 'human') {
+    return [opening, new HumanMessage({ content: tail })]
+  }
+  const content = typeof opening.content === 'string'
+    ? `${opening.content}\n\n${tail}`
+    : [...opening.content, { type: 'text', text: tail }]
+
+  return [new HumanMessage({
+    content, id: opening.id, name: opening.name, additional_kwargs: opening.additional_kwargs,
+  } as ConstructorParameters<typeof HumanMessage>[0])]
+}
+
+/** The provider's id of the model a run talks to, for billing — the config's, else the client's own. */
+const modelIdOf = (model: unknown): string | undefined => {
+  const typed = model as { metadata?: { config?: { model?: string } }, model?: unknown, modelName?: unknown }
+  const id = typed.metadata?.config?.model ?? typed.model ?? typed.modelName
+  return typeof id === 'string' ? id : undefined
+}
+
 /**
  * An OwlMeans agent over the LangGraph functional API.
  *
@@ -49,7 +74,8 @@ export const makeAgentModel = (options: AgentOptions): AgentModel => {
 
   const conversation = options.conversation ?? conversationFor(exec.purpose)
   const prompts = options.prompts ?? exec.prompts
-  const provider = options.provider ?? llmPluginRegistry.pluginFor(agentModel)
+  const provider = options.provider ?? llmPluginRegistry.resolveFor(agentModel)
+  const modelId = modelIdOf(agentModel)
   const purpose = exec.purpose
 
   const registry: AgentPlugin[] = []
@@ -136,20 +162,38 @@ export const makeAgentModel = (options: AgentOptions): AgentModel => {
           },
         )
         : null
-      const system = composed?.system?.content
-        ?? (context.length > 0 ? context.join('\n\n') : '')
-      const systemMessage = new SystemMessage(
-        typeof system === 'string' ? system : JSON.stringify(system),
-      )
+      // The opening of every round: the system (a persona, stable across runs), the project
+      // message (this run's facts), and the caller's opening carrying the per-call tail. The system
+      // goes out as real text — its cache blocks are the provider plugin's, never a stringified array.
+      const system = composed != null ? composed.system ?? '' : context.join('\n\n')
+      const head: BaseMessage[] = [
+        ...(system !== '' ? [new SystemMessage(system)] : []),
+        ...(composed?.project != null ? [new HumanMessage(composed.project)] : []),
+      ]
+      const hints: LlmLoopCacheHints = {
+        system: composed?.blocks.filter(block => block.region === PromptRegion.System),
+        ...(composed?.project != null ? { project: head.length - 1 } : {}),
+        ...(composed != null ? { ttl: composed.cache.ttl } : {}),
+      }
+      const cached = composed?.cache.enabled !== false
 
       const tooled = agentModel.bindTools?.(Object.values(toolSet)) ?? agentModel
 
-      const ask = task('call-llm', async (messages: BaseMessageLike[]) => {
+      const ask = task('call-llm', async ({ messages, turn }: { messages: BaseMessageLike[], turn: number }) => {
         const startedAt = Date.now()
 
+        const [first, ...rest] = messages as BaseMessage[]
+        const opening = composed?.tail != null && first != null ? withTail(first, composed.tail) : [first]
+        const wire = [...head, ...opening, ...rest].filter(message => message != null)
+        // Each round strips and re-marks copies: the system and project message once, and the
+        // growing conversation read back from the round before.
+        const patch = cached
+          ? provider?.loopCache?.(wire as unknown as MessageFieldWithRole[], agentModel, hints)
+          : undefined
+
         const stream = await tooled.stream(
-          [systemMessage, ...messages],
-          { runName: action, metadata: { purpose } },
+          (patch?.messages ?? wire) as BaseMessageLike[],
+          { ...patch?.options, runName: action, metadata: { purpose } } as Parameters<typeof tooled.stream>[1],
         )
 
         let final: AIMessageChunk | undefined
@@ -157,8 +201,8 @@ export const makeAgentModel = (options: AgentOptions): AgentModel => {
           final = final != null ? final.concat(chunk) : chunk
         }
 
-        const result = new AIMessage(final!)
-        await spectate?.(messages as ModelInputItem[], result, action, 0, startedAt)
+        const result = new AIMessage(cacheHelper.withCacheTiers(final!))
+        await spectate?.(messages as ModelInputItem[], result, action, turn, startedAt, modelId)
 
         return result
       })
@@ -171,7 +215,7 @@ export const makeAgentModel = (options: AgentOptions): AgentModel => {
       )
 
       const agent = entrypoint(entrypointName, async (messages: BaseMessageLike[]) => {
-        let response = await ask(messages)
+        let response = await ask({ messages, turn: 0 })
         let turn = 0
 
         while (true) {
@@ -214,7 +258,7 @@ export const makeAgentModel = (options: AgentOptions): AgentModel => {
           }))
 
           messages = addMessages(messages, results)
-          response = await ask(messages)
+          response = await ask({ messages, turn })
         }
 
         return messages

package/src/plugins/summarize.ts

@@ -18,7 +18,7 @@ import { compactionHelper } from '../helpers/compaction.js'
  *
  * What it contributes is rendered as clearly delimited, explicitly untrusted material. These are
  * model words derived from user input, stored and replayed into a later prompt: they belong in the
- * volatile context block, described as a record of what happened, never as instructions.
+ * context block of the project message, described as a record of what happened, never as instructions.
  */
 export const summarizePlugin = (options: SummarizeOptions = {}): AgentPlugin => {
   const {

package/src/types.ts

@@ -17,11 +17,13 @@ export interface AgentToolSet { [key: string]: StructuredToolInterface }
  * What the caller gets told about each model call.
  *
  * Shaped to match `spectate(spectator, callType)` from `@owlmeans/llm` exactly, so an application
- * that already has a spectator passes the curried function straight in.
+ * that already has a spectator passes the curried function straight in. `retries` carries the
+ * loop's turn number, and `model` the id of the model that answered.
  */
 export interface AgentSpectateHook {
   (
     input: ModelInputItem[], message: AIMessage, action: string, retries: number, startedAt?: number,
+    model?: string,
   ): Promise<unknown>
 }
 
@@ -31,7 +33,10 @@ export interface AgentOptions {
   /** Overrides the model resolved from the execution. */
   agentModel?: BaseChatModel
   tools: AgentToolSet
-  /** Static volatile context. Lands in `PromptBlock.Context`, never in the cached prefix. */
+  /**
+   * Static context. Lands in `PromptBlock.Context` — the project message, behind the cached
+   * system region — never in the system message other runs share.
+   */
   context?: string[]
   conversation?: ConversationRef
   /** LangGraph entrypoint name; shows up in traces. */
@@ -44,7 +49,10 @@ export interface AgentOptions {
    * by default: the agent holds an execution, not the service that knows its policy.
    */
   utility?: () => BaseChatModel | undefined
-  /** Provider plugin used for cache placement. Resolved from the model when omitted. */
+  /**
+   * Provider plugin used for cache placement. Resolved from the model when omitted
+   * (`llmPluginRegistry.resolveFor`, so a model the service built gets its own provider's).
+   */
   provider?: LlmPlugin
   maxTurns?: number
   /**
@@ -69,7 +77,7 @@ export interface AgentOptions {
 export interface AgentInvokeArgs {
   /** LangChain `runName` for the model calls of this run. */
   action?: string
-  /** Extra volatile context for this call only. */
+  /** Extra context for this run only — it joins the project message. */
   context?: string[]
 }
 

package/tests/_tools/model.ts

@@ -22,16 +22,25 @@ export interface ScriptedModel {
   turns: () => number
   /** The message lists it was asked with, in order. */
   asked: () => unknown[][]
+  /** The call options of each ask, in order. */
+  options: () => Array<Record<string, unknown>>
 }
 
-export const scriptedModel = (script: ScriptedTurn[]): ScriptedModel => {
+/**
+ * `extra` puts identity on the double — a `modelName`, the `metadata.config` a service-built model
+ * carries — so a provider plugin can recognise and size it.
+ */
+export const scriptedModel = (script: ScriptedTurn[], extra: Record<string, unknown> = {}): ScriptedModel => {
   let at = 0
   const asked: unknown[][] = []
+  const options: Array<Record<string, unknown>> = []
 
   const model = {
+    ...extra,
     bindTools: () => model,
-    stream: async (messages: unknown[]) => {
+    stream: async (messages: unknown[], callOptions: Record<string, unknown> = {}) => {
       asked.push(messages)
+      options.push(callOptions)
       const turn = script[Math.min(at, script.length - 1)]
       at += 1
 
@@ -46,5 +55,5 @@ export const scriptedModel = (script: ScriptedTurn[]): ScriptedModel => {
     },
   }
 
-  return { model: model as unknown as BaseChatModel, turns: () => at, asked: () => asked }
+  return { model: model as unknown as BaseChatModel, turns: () => at, asked: () => asked, options: () => options }
 }

package/tests/agent.spec.ts

@@ -1,9 +1,10 @@
 import { describe, expect, test } from 'bun:test'
 import { tool } from '@langchain/core/tools'
+import type { BaseChatModel } from '@langchain/core/language_models/chat_models'
 import * as z from 'zod'
-import { ExecutionLevel, PromptBlock } from '@owlmeans/llm-common'
-import { makePromptService } from '@owlmeans/llm'
-import type { Execution, PromptService } from '@owlmeans/llm'
+import { ExecutionLevel, ModelProvider, PromptBlock } from '@owlmeans/llm-common'
+import { anthropicPlugin, makePromptService, openAiPlugin } from '@owlmeans/llm'
+import type { Execution, ModelConfig, PromptService } from '@owlmeans/llm'
 import { AgentRunStatus } from '@owlmeans/agent-common'
 import { makeAgentModel } from '../src/index.js'
 import type { AgentPlugin, AgentToolSet } from '../src/index.js'
@@ -115,9 +116,9 @@ describe('agent — plugins', () => {
     expect((finished[0] as { status: string }).status).toBe(AgentRunStatus.Ok)
   })
 
-  test('contributed context lands in the volatile block, never in the cached prefix', async () => {
-    // The Context block is the only one a provider will not put a cache breakpoint on. Volatile
-    // material anywhere above it invalidates the prefix every call that shares the persona pays for.
+  test('contributed context lands in the project message, never in the cached system', async () => {
+    // The system region is what every run of the persona shares. Run-specific material anywhere in
+    // it invalidates the prefix every call that shares the persona pays for.
     const prompts = promptService()
     const composed = await prompts.compose(
       { role: 'You are a test agent.', context: ['REMEMBERED CONTEXT'] },
@@ -233,8 +234,85 @@ describe('agent — finalization', () => {
 
     await agent.invoke('go')
 
-    const system = String(scripted.asked()[0][0].content)
-    expect(system).toContain('the agent version')
-    expect(system).not.toContain('the service version')
+    // The project message, right after the system, carries what the plugins contributed.
+    const project = String((scripted.asked()[0][1] as { content: unknown }).content)
+    expect(project).toContain('the agent version')
+    expect(project).not.toContain('the service version')
+  })
+})
+
+describe('agent — the prompt on the wire', () => {
+  const content = (message: unknown): unknown => (message as { content: unknown }).content
+  const marks = (message: unknown, key: string): number => Array.isArray(content(message))
+    ? (content(message) as Array<Record<string, unknown>>).filter(block => block[key] != null).length
+    : 0
+  const long = 'x'.repeat(400)
+  const anthropicExec = (prompts: () => PromptService): Execution => ({
+    ...execution(prompts), prompt: { role: `You are a test agent. ${long}`, skills: [] },
+  } as unknown as Execution)
+
+  // The system was stringified once — a JSON dump of content blocks sent as the persona.
+  test('the system goes out as text blocks, the project message second, the tail on a copy of the opening', async () => {
+    const scripted = scriptedModel([
+      { toolCalls: [{ name: 'echo', args: { value: 'hi' } }] },
+      { content: 'done' },
+    ], { modelName: 'claude-haiku-4-5', metadata: { config: { model: 'claude-haiku-4-5', cacheMinTokens: 1 } } })
+    const prompts = promptService()
+    prompts.register({ alias: 'percall', body: 'per-call skill' })
+    const agent = makeAgentModel({
+      exec: anthropicExec(() => prompts), agentModel: scripted.model, tools: { echo }, provider: anthropicPlugin,
+      context: ['RUN FACTS'],
+    })
+
+    const result = await agent.invoke('use the tool')
+
+    const [first, second] = scripted.asked()
+    expect(content(first![0])).toEqual([
+      { type: 'text', text: `You are a test agent. ${long}`, cache_control: { type: 'ephemeral' } },
+    ])
+    expect(JSON.stringify(content(first![1]))).toContain('RUN FACTS')
+    expect(marks(first![1], 'cache_control')).toBe(1)
+    // Three explicit markers at most, never on the final message; the automatic one moves forward.
+    for (const round of [first!, second!]) {
+      const explicit = round.reduce<number>((sum, message) => sum + marks(message, 'cache_control'), 0)
+      expect(explicit).toBeLessThanOrEqual(3)
+      expect(marks(round[round.length - 1], 'cache_control')).toBe(0)
+    }
+    expect(scripted.options()[1]!.cache_control).toEqual({ type: 'ephemeral' })
+    expect(second!.length).toBe(first!.length + 2)
+    // The transcript keeps the opening as the caller sent it.
+    expect(result.messages[0]!.content).toBe('use the tool')
+  })
+
+  test('the tail rides a copy of the opening, after the payload', async () => {
+    const scripted = scriptedModel([{ content: 'ok' }])
+    const prompts = makePromptService({}, `agent-spec-prompts-${++seq}`)
+    prompts.use({ alias: 'late', compose: ctx => ctx.add(PromptBlock.Tail, 'LATE PACKAGE') })
+    const agent = makeAgentModel({ exec: execution(() => prompts), agentModel: scripted.model, tools: {} })
+
+    const result = await agent.invoke('go')
+
+    const asked = scripted.asked()[0]!
+    expect(content(asked[asked.length - 1])).toBe('go\n\nLATE PACKAGE')
+    expect(result.messages[0]!.content).toBe('go')
+  })
+
+  // By instance alone every ChatOpenAI is the compatible plugin's, which caches nothing; the agent
+  // resolves the provider the service built the model with.
+  test('a service-built ChatOpenAI is cached through the OpenAI plugin', async () => {
+    const scripted = scriptedModel([{ content: 'ok' }])
+    const chat = openAiPlugin.build({
+      alias: 'spec', secret: 'sk-test', callbacks: [],
+      config: { alias: 'spec', provider: ModelProvider.OpenAI, model: 'gpt-6-sol', cacheMinTokens: 1 } as ModelConfig,
+    })
+    ;(chat as unknown as { bindTools: () => BaseChatModel }).bindTools = () => scripted.model
+    const agent = makeAgentModel({
+      exec: anthropicExec(promptService), agentModel: chat, tools: {}, context: ['RUN FACTS'],
+    })
+
+    await agent.invoke('go')
+
+    expect(JSON.stringify(scripted.asked()[0])).toContain('prompt_cache_breakpoint')
+    expect(scripted.options()[0]!.promptCacheOptions).toEqual({ mode: 'explicit' })
   })
 })