@owlmeans/agent 0.1.18-rc.16 → 0.1.18-rc.17

package/README.md

@@ -39,6 +39,7 @@ const agent = context.agents().agent({ exec, tools })
 | `summarizePlugin` | Compacts each finished run into `summary` + `advice`, and replays the last few on the way in |
 | `memoryGraphPlugin` | Durable notes filed by subsystem, with links — index injected, content pulled by tool |
 | `memoryEventsPlugin` | A bounded, ordered record of what happened |
+| `inquiryPlugin` | The `ask_user` tool — offered only when a channel to a person is wired |
 
 Both memory plugins also export a plain API (`memoryGraph`, `memoryEvents`) usable with no agent at
 all, so a pipeline helper writes to the same store an agent reads.
@@ -72,9 +73,22 @@ implements. An unbound port is not an error — the plugin that needs it becomes
 purpose is streamed to the client, so without it the summary of a run types itself out in the
 user's view of that run, right after it finished.
 
-**No LangGraph checkpointer.** Recoverability lives in the OwlMeans execution and flow layers, which
-already own a serializable state model; `makeAgentExecutionPlugin` is the first real implementation
-of `@owlmeans/llm`'s `ExecutionPlugin` seam.
+**An agent run is not resumable; a PIPELINE is.** A turn's tool calls are effects already applied
+to the world, so re-entering one re-applies them — `makeAgentModel` therefore keeps no checkpoint,
+and `makeAgentExecutionPlugin` is the first real implementation of `@owlmeans/llm`'s
+`ExecutionPlugin` seam. What resumes is `makePipeline`, a state machine over named steps whose
+position is written to a run row at every boundary; an agent run belongs inside one of its steps.
+The row is the authority on where a run stands — never the LangGraph checkpoint, which is
+size-guarded and expires. A checkpointer is optional and buys replay, never correctness.
+
+**A step asks a person with `ctx.ask(inquiry)`, and a run nobody can answer parks `Waiting`.** An
+answer already in the state comes straight back, so a question is never asked twice; that only
+holds if `Inquiry.id` is DERIVED from the step and the thing being decided rather than minted per
+call. Answers are merged by the runner, in `invoke` and in `resume({ answers })`, never by a
+caller's mapping. An agent that installs `inquiryPlugin` must pass
+`fatal: e => isFatalError(e) != null` into its tool invocation: the tool rethrows
+`InquiryUnavailable` alone — a channel that has gone is terminal, and without the predicate the
+loop spends its whole turn budget on it.
 
 <!-- owlmeans:agent-guidance:start -->
 ## Agent guidance
@@ -84,7 +98,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.12
+npx @owlmeans/agent-skills@^0.1.18-rc.13
 ```
 
 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,
   "package": "@owlmeans/agent",
-  "version": "0.1.18-rc.16",
-  "generatedAt": "2026-09-04T22:43:25.447Z",
+  "version": "0.1.18-rc.17",
+  "generatedAt": "2026-09-10T18:54:42.500Z",
   "canonicalRepo": "https://github.com/owlmeans/common",
   "entries": [
     {

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

@@ -1,6 +1,6 @@
 ---
 name: agent
-description: How to use @owlmeans/agent — context-aware LLM agents and pipelines over the LangGraph functional API, with the AgentPlugin seam, conversation-summarization and memory plugins, storage-independent ports, and the ExecutionPlugin checkpoint implementation. Auto-invoked when importing makeAgentModel, appendAgentsService, an agent plugin, safeInvokeTool, or an agent store.
+description: How to use @owlmeans/agent — context-aware LLM agents over the LangGraph functional API, and resumable PIPELINES over a checkpointed StateGraph, with the AgentPlugin seam, conversation-summarization and memory plugins, and storage-independent ports. Auto-invoked when importing makeAgentModel, makePipeline, makeCheckpointSaver, appendAgentsService, an agent plugin, safeInvokeTool, or an agent store.
 user-invocable: false
 ---
 <!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
@@ -8,7 +8,7 @@ user-invocable: false
 # @owlmeans/agent
 
 **Layer:** Cross-cutting domain
-**Install:** `"@owlmeans/agent": "^0.1.18-rc.16"` in `dependencies`, plus the `@langchain/core` and
+**Install:** `"@owlmeans/agent": "^0.1.18-rc.17"` in `dependencies`, plus the `@langchain/core` and
 `@langchain/langgraph` **peers**
 
 The agent runtime. Contracts live in `@owlmeans/agent-common`.
@@ -18,20 +18,58 @@ The agent runtime. Contracts live in `@owlmeans/agent-common`.
 | Export | Description |
 |---|---|
 | `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`. |
+| `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. |
 | `summarizePlugin(options?)` | Compacts each finished run into `summary` + `advice`; replays the last few. |
 | `memoryGraphPlugin(options?)` · `memoryGraph(store, options?)` | Durable notes filed by subsystem, with links. Plugin **and** plain API. |
 | `memoryEventsPlugin(options?)` · `memoryEvents(store, options?)` | A bounded, ordered record of what happened. |
+| `inquiryPlugin(options?)` · `INQUIRY_PLUGIN` · `ASK_USER_TOOL` | The `ask_user` tool and its one Context paragraph — offered only when a channel is wired. |
 | `safeInvokeTool`, `toErrorResponse`, `isToolError` | The never-throwing tool contract. |
 | `composeCompaction`, `composeRollingSummary`, `renderTranscript`, `messageText` | Summary primitives; both composers are total. |
-| `makeAgentExecutionPlugin(options)` | The first real implementation of `@owlmeans/llm`'s `ExecutionPlugin`. |
 | `makeStaticFlowProvider(flows)` | The server-side `FlowProvider` `@owlmeans/flow` does not ship. |
 | `inProcessTransport()`, `AgentTransport` | The scaling seam; default carries messages by direct call. |
-| `createMemory*Store()` | In-memory reference implementations of every port. |
+| `createMemory*Store()` | In-memory reference implementations of every port, including `createMemoryPipelineRunStore` and `createMemoryCheckpointStore`. |
 | `AgentError` · `AgentMissconfiguredError` · `AgentLoopExhaustedError` | The `ResilientError` family. `AgentMissconfiguredError` is a model or tool set the agent was built without; `AgentLoopExhaustedError` is the tool loop hitting its ceiling. |
 | `DEFAULT_MAX_TURNS` (64) · `DEFAULT_PLUGIN_ORDER` · `DEFAULT_ACTION` · `DEFAULT_ENTRYPOINT` | The loop and plugin defaults. |
 
-Subpath exports: `./plugins`, `./helpers`, `./stores`.
+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.
 
 ## The plugin seam
 
@@ -101,8 +139,8 @@ a prompt is a request. Both composers (`composeCompaction`, `composeRollingSumma
 no model, a failing model or an empty answer they fall back deterministically, so a caller can record
 history unconditionally. A failed fold costs detail, never the event.
 
-**Ports, not resources.** `ConversationStore`, `MemoryGraphStore`, `MemoryEventStore` and
-`AgentRunStateStore` are narrow interfaces a consumer implements. A port names exactly what the
+**Ports, not resources.** `ConversationStore`, `MemoryGraphStore`, `MemoryEventStore`,
+`PipelineRunStore` and `CheckpointStore` are narrow interfaces a consumer implements. A port names exactly what the
 plugin needs, which is a far smaller surface than CRUD, and anything can satisfy it — a `Resource`,
 or a file on disk, which is what the project-history equivalent is. An unbound port is a no-op, not
 an error.
@@ -115,13 +153,67 @@ 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.
 
-**Checkpoints are size-guarded.** A project-level execution carries the whole project specification;
-writing that on every checkpoint is a storage problem that surfaces much later and much worse than a
-skipped write.
-
-**No LangGraph checkpointer, and the `entrypoint` is created inside `invoke()`.** Recoverability
-lives in the OwlMeans execution and flow layers, which already own a serializable state model;
-adopting a second one would leave two half-truths about where a crashed run stands.
+**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.
+
+**A step asks with `ctx.ask(inquiry)`, and a run nobody can answer parks `Waiting`.** Three
+outcomes in order: an answer already in the state comes straight back (a question is never asked
+twice); a live `options.inquiry.ask` answer is RECORDED in the state — `stateAnswerOf(capAnswer(…))`
+under `state[INQUIRY_ANSWERS_KEY][id]`, the decision whole and the prose cut — and the FULL answer
+returned to the step; otherwise the run stops `Waiting` with the inquiry on its row, and with no run
+store it throws `PipelineNotResumableError` instead. A throwing channel is not a park: it fails the
+step as an ordinary outcome, because the asking failed rather than the answer being no. `Inquiry.id`
+is the only thing an answer is matched by, so DERIVE it from the step and the thing being decided —
+an id minted per call never matches the state, and the run re-asks and parks forever.
+
+**Answers are merged by the RUNNER, in `invoke` and in `resume({ answers })`, never by a mapping.**
+`invoke` builds `{ ...restored, ...seed }`, so a mapping that forwarded the answers map would
+replace the child's own recorded answers wholesale — and write `undefined` over them when the parent
+had none, which re-asks question 1 on every resume. When a composed child parks, `asStep` relays its
+question to the parent's `ctx.ask` and re-invokes the child with the answer (bounded at 8 questions
+per composing step); the parent parks only when its own `ask` parks, and never throws a plain error
+in that path.
+
+**An agent that installs `inquiryPlugin` must pass `fatal: e => isFatalError(e) != null`.** The tool
+rethrows `InquiryUnavailable` alone — no channel is an answerable situation, a channel that has GONE
+is terminal — and `safeInvokeTool` contains everything else by default, so without that predicate
+the loop spends its whole turn budget on a dead channel. See [[inquiry]] for the whole primitive.
+
+**`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.
 
 **`makeStaticFlowProvider` must throw on an unknown flow.** `makeFlowModel` reads a string as a flow
 name first and only re-reads it as a serialized token once the provider throws — returning null
@@ -136,7 +228,9 @@ boundary — never for an `@owlmeans/*` package.
 
 ## Related
 
+- [[inquiry]] — the human-in-the-loop primitive `ctx.ask`, `Waiting` and `ask_user` belong to
 - [[agent-common]] — the serializable records and the run lifecycle flow
-- [[llm]] — `Execution`, the model contract and `ExecutionPlugin`
+- [[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

package/build/checkpoint/index.d.ts

@@ -0,0 +1,2 @@
+export * from './saver.js';
+//# sourceMappingURL=index.d.ts.map

package/build/checkpoint/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/checkpoint/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAA"}

package/build/checkpoint/index.js

@@ -0,0 +1,2 @@
+export * from './saver.js';
+//# sourceMappingURL=index.js.map

package/build/checkpoint/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/checkpoint/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAA"}

package/build/checkpoint/saver.d.ts

@@ -0,0 +1,7 @@
+import { BaseCheckpointSaver } from '@langchain/langgraph';
+import type { SerializerProtocol } from '@langchain/langgraph-checkpoint';
+import type { CheckpointStore } from '../stores/types.js';
+export declare const makeCheckpointSaver: (store: CheckpointStore, options?: {
+    serde?: SerializerProtocol;
+}) => BaseCheckpointSaver;
+//# sourceMappingURL=saver.d.ts.map

package/build/checkpoint/saver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"saver.d.ts","sourceRoot":"","sources":["../../src/checkpoint/saver.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAA;AAE1D,OAAO,KAAK,EAEqB,kBAAkB,EAClD,MAAM,iCAAiC,CAAA;AAExC,OAAO,KAAK,EAAE,eAAe,EAAyB,MAAM,oBAAoB,CAAA;AAwKhF,eAAO,MAAM,mBAAmB,UACvB,eAAe,YAAW;IAAE,KAAK,CAAC,EAAE,kBAAkB,CAAA;CAAE,KAC9D,mBAAoE,CAAA"}

package/build/checkpoint/saver.js

@@ -0,0 +1,135 @@
+import { BaseCheckpointSaver } from '@langchain/langgraph';
+import { WRITES_IDX_MAP } from '@langchain/langgraph-checkpoint';
+/**
+ * Where each half of LangGraph's checkpoint API comes from, and why it is two imports.
+ *
+ * The CLASS is imported from `@langchain/langgraph`'s root, because a checkpointer crosses a
+ * package boundary and a class with protected members is nominally distinct per installed copy —
+ * two copies and `entrypoint({ checkpointer })` stops type-checking, or worse, stops recognising
+ * what it was handed. The protocol VALUES (`WRITES_IDX_MAP`, and the types beside it) are not in
+ * langgraph's root export list at all, so they come from `@langchain/langgraph-checkpoint` — which
+ * is a hard dependency of langgraph, so there is exactly one of it either way.
+ */
+const encode = (data) => Buffer.from(data).toString('base64');
+const decode = (data) => new Uint8Array(Buffer.from(data, 'base64'));
+const threadOf = (config) => ({
+    thread: String(config.configurable?.thread_id ?? ''),
+    ns: String(config.configurable?.checkpoint_ns ?? ''),
+    id: config.configurable?.checkpoint_id != null
+        ? String(config.configurable.checkpoint_id)
+        : undefined,
+});
+const configFor = (thread, ns, id) => ({
+    configurable: { thread_id: thread, checkpoint_ns: ns, checkpoint_id: id },
+});
+/**
+ * A {@link BaseCheckpointSaver} over the package's storage-agnostic {@link CheckpointStore} port.
+ *
+ * Everything protocol-shaped lives here; everything storage-shaped lives behind the port. That
+ * split is what lets an application bind Mongo, Redis or nothing at all without this file — or
+ * LangGraph's version of it — being a consideration.
+ *
+ * Payloads are base64 of whatever the serde produced. Never `JSON.stringify`: the checkpoint holds
+ * `BaseMessage` instances, and a plain-object round trip returns something no `instanceof` in a
+ * provider adapter recognises again — a resumed run would silently drop its tool calls.
+ */
+class PortCheckpointSaver extends BaseCheckpointSaver {
+    store;
+    constructor(store, serde) {
+        super(serde);
+        this.store = store;
+    }
+    async toTuple(thread, ns, record) {
+        const checkpoint = await this.serde.loadsTyped(record.type, decode(record.checkpoint));
+        const metadata = await this.serde.loadsTyped(record.type, decode(record.metadata));
+        const writes = await this.store.writesFor(thread, ns, [record.checkpointId]);
+        const pendingWrites = await Promise.all([...writes].sort((a, b) => a.idx - b.idx).map(async (write) => [
+            write.taskId, write.channel, await this.serde.loadsTyped(write.type, decode(write.value)),
+        ]));
+        return {
+            config: configFor(thread, ns, record.checkpointId),
+            checkpoint,
+            metadata,
+            ...(record.parentCheckpointId != null
+                ? { parentConfig: configFor(thread, ns, record.parentCheckpointId) }
+                : {}),
+            pendingWrites,
+        };
+    }
+    async getTuple(config) {
+        const { thread, ns, id } = threadOf(config);
+        if (thread === '') {
+            return undefined;
+        }
+        const record = await this.store.one(thread, ns, id);
+        return record != null ? await this.toTuple(thread, ns, record) : undefined;
+    }
+    async *list(config, options) {
+        const { thread, ns } = threadOf(config);
+        if (thread === '') {
+            return;
+        }
+        const before = options?.before?.configurable?.checkpoint_id;
+        // `limit` is applied by the STORE, not after decoding: a caller asking for the last three
+        // checkpoints must not pay for deserializing a thread's whole history to get them.
+        const records = await this.store.page({
+            threadId: thread,
+            ...(config.configurable?.checkpoint_ns != null ? { ns } : {}),
+            ...(before != null ? { beforeId: String(before) } : {}),
+            ...(options?.limit != null ? { limit: options.limit } : {}),
+        });
+        for (const record of records) {
+            yield await this.toTuple(thread, record.ns, record);
+        }
+    }
+    async put(config, checkpoint, metadata, _newVersions) {
+        const { thread, ns, id } = threadOf(config);
+        const [type, serialized] = await this.serde.dumpsTyped(checkpoint);
+        const [metadataType, serializedMetadata] = await this.serde.dumpsTyped(metadata);
+        if (type !== metadataType) {
+            throw new Error(`Mismatched checkpoint serialization types: ${type} vs ${metadataType}`);
+        }
+        await this.store.put({
+            threadId: thread,
+            ns,
+            checkpointId: checkpoint.id,
+            ...(id != null ? { parentCheckpointId: id } : {}),
+            type,
+            checkpoint: encode(serialized),
+            metadata: encode(serializedMetadata),
+            createdAt: new Date().toISOString(),
+        });
+        return configFor(thread, ns, checkpoint.id);
+    }
+    async putWrites(config, writes, taskId) {
+        const { thread, ns, id } = threadOf(config);
+        if (id == null) {
+            return;
+        }
+        const taskPath = config.configurable?.checkpoint_task_path;
+        const records = await Promise.all(writes.map(async ([channel, value], position) => {
+            const [type, serialized] = await this.serde.dumpsTyped(value);
+            return {
+                threadId: thread,
+                ns,
+                checkpointId: id,
+                taskId,
+                // A control channel has a well-known NEGATIVE index; a task's own output keeps its
+                // position. The sign is the write rule, and the store reads it: positive is first-wins,
+                // so a retried task cannot overwrite the answer its first attempt committed; negative is
+                // last-wins, because that is what an error or an interrupt is.
+                idx: WRITES_IDX_MAP[channel] ?? position,
+                channel,
+                type,
+                value: encode(serialized),
+                ...(taskPath != null ? { taskPath: String(taskPath) } : {}),
+            };
+        }));
+        await this.store.putWrites(records);
+    }
+    async deleteThread(threadId) {
+        await this.store.dropThread(threadId);
+    }
+}
+export const makeCheckpointSaver = (store, options = {}) => new PortCheckpointSaver(store, options.serde);
+//# sourceMappingURL=saver.js.map

package/build/checkpoint/saver.js.map

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

package/build/helpers/tools.d.ts

@@ -24,6 +24,12 @@ export declare const isToolError: (result: unknown) => result is ToolErrorRespon
  * that is what the model calls — a map keyed by a local variable silently loses any tool whose two
  * names drifted apart, leaving it advertised, callable, and permanently "not found". The key stays
  * as a fallback so a caller may still address a tool by it.
+ *
+ * `fatal` is the ONE exception to "never throws", and it exists because containment has a cost the
+ * containment itself cannot see. A tool may be a whole pipeline behind a single call; when the
+ * thing that stopped it is an exhausted budget or a refusal, handing the model a readable error
+ * message is an invitation to pick another tool and spend again. A caller that knows which errors
+ * mean "stop" says so here, and those alone travel out.
  */
-export declare const safeInvokeTool: (tools: AgentToolSet, toolCall: ToolCall) => Promise<unknown>;
+export declare const safeInvokeTool: (tools: AgentToolSet, toolCall: ToolCall, fatal?: (e: unknown) => boolean) => Promise<unknown>;
 //# sourceMappingURL=tools.d.ts.map

package/build/helpers/tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../src/helpers/tools.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAA;AACxD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAE/C,oGAAoG;AACpG,MAAM,WAAW,iBAAiB;IAAG,KAAK,EAAE,MAAM,CAAA;CAAE;AAEpD,eAAO,MAAM,eAAe,MAAO,OAAO,KAAG,iBAC2C,CAAA;AAExF,eAAO,MAAM,WAAW,WAAY,OAAO,KAAG,MAAM,IAAI,iBACW,CAAA;AAEnE;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,cAAc,UAAiB,YAAY,YAAY,QAAQ,KAAG,OAAO,CAAC,OAAO,CAc7F,CAAA"}
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../src/helpers/tools.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAA;AACxD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAE/C,oGAAoG;AACpG,MAAM,WAAW,iBAAiB;IAAG,KAAK,EAAE,MAAM,CAAA;CAAE;AAEpD,eAAO,MAAM,eAAe,MAAO,OAAO,KAAG,iBAC2C,CAAA;AAExF,eAAO,MAAM,WAAW,WAAY,OAAO,KAAG,MAAM,IAAI,iBACW,CAAA;AAEnE;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,cAAc,UAClB,YAAY,YAAY,QAAQ,UAAU,CAAC,CAAC,EAAE,OAAO,KAAK,OAAO,KACvE,OAAO,CAAC,OAAO,CAiBjB,CAAA"}

package/build/helpers/tools.js

@@ -18,8 +18,14 @@ export const isToolError = (result) => typeof result === 'object' && result != n
  * that is what the model calls — a map keyed by a local variable silently loses any tool whose two
  * names drifted apart, leaving it advertised, callable, and permanently "not found". The key stays
  * as a fallback so a caller may still address a tool by it.
+ *
+ * `fatal` is the ONE exception to "never throws", and it exists because containment has a cost the
+ * containment itself cannot see. A tool may be a whole pipeline behind a single call; when the
+ * thing that stopped it is an exhausted budget or a refusal, handing the model a readable error
+ * message is an invitation to pick another tool and spend again. A caller that knows which errors
+ * mean "stop" says so here, and those alone travel out.
  */
-export const safeInvokeTool = async (tools, toolCall) => {
+export const safeInvokeTool = async (tools, toolCall, fatal) => {
     const tool = tools[toolCall.name]
         ?? Object.values(tools).find(entry => entry.name === toolCall.name);
     if (tool == null) {
@@ -29,6 +35,9 @@ export const safeInvokeTool = async (tools, toolCall) => {
         return await tool.invoke(toolCall.args);
     }
     catch (e) {
+        if (fatal?.(e) === true) {
+            throw e;
+        }
         console.warn(`Error during tool call ${toolCall.name}:`, e);
         return toErrorResponse(e);
     }

package/build/helpers/tools.js.map

@@ -1 +1 @@
-{"version":3,"file":"tools.js","sourceRoot":"","sources":["../../src/helpers/tools.ts"],"names":[],"mappings":"AAMA,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,CAAU,EAAqB,EAAE,CAC/D,CAAC,EAAE,KAAK,EAAE,2BAA2B,CAAC,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAA;AAExF,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,MAAe,EAA+B,EAAE,CAC1E,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,IAAI,IAAI,IAAI,OAAO,IAAI,MAAM,CAAA;AAEnE;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,KAAK,EAAE,KAAmB,EAAE,QAAkB,EAAoB,EAAE;IAChG,MAAM,IAAI,GAAG,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC;WAC5B,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,CAAC,IAAI,KAAK,QAAQ,CAAC,IAAI,CAAC,CAAA;IAErE,IAAI,IAAI,IAAI,IAAI,EAAE,CAAC;QACjB,OAAO,eAAe,CAAC,IAAI,KAAK,CAAC,QAAQ,QAAQ,CAAC,IAAI,YAAY,CAAC,CAAC,CAAA;IACtE,CAAC;IAED,IAAI,CAAC;QACH,OAAO,MAAM,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAA;IACzC,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,OAAO,CAAC,IAAI,CAAC,0BAA0B,QAAQ,CAAC,IAAI,GAAG,EAAE,CAAC,CAAC,CAAA;QAC3D,OAAO,eAAe,CAAC,CAAC,CAAC,CAAA;IAC3B,CAAC;AACH,CAAC,CAAA"}
+{"version":3,"file":"tools.js","sourceRoot":"","sources":["../../src/helpers/tools.ts"],"names":[],"mappings":"AAMA,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,CAAU,EAAqB,EAAE,CAC/D,CAAC,EAAE,KAAK,EAAE,2BAA2B,CAAC,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAA;AAExF,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,MAAe,EAA+B,EAAE,CAC1E,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,IAAI,IAAI,IAAI,OAAO,IAAI,MAAM,CAAA;AAEnE;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,KAAK,EACjC,KAAmB,EAAE,QAAkB,EAAE,KAA+B,EACtD,EAAE;IACpB,MAAM,IAAI,GAAG,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC;WAC5B,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,CAAC,IAAI,KAAK,QAAQ,CAAC,IAAI,CAAC,CAAA;IAErE,IAAI,IAAI,IAAI,IAAI,EAAE,CAAC;QACjB,OAAO,eAAe,CAAC,IAAI,KAAK,CAAC,QAAQ,QAAQ,CAAC,IAAI,YAAY,CAAC,CAAC,CAAA;IACtE,CAAC;IAED,IAAI,CAAC;QACH,OAAO,MAAM,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAA;IACzC,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC;YACxB,MAAM,CAAC,CAAA;QACT,CAAC;QACD,OAAO,CAAC,IAAI,CAAC,0BAA0B,QAAQ,CAAC,IAAI,GAAG,EAAE,CAAC,CAAC,CAAA;QAC3D,OAAO,eAAe,CAAC,CAAC,CAAC,CAAA;IAC3B,CAAC;AACH,CAAC,CAAA"}

package/build/index.d.ts

@@ -5,8 +5,9 @@ export * from './model.js';
 export * from './service.js';
 export * from './helpers/index.js';
 export * from './stores/index.js';
+export * from './pipeline/index.js';
+export * from './checkpoint/index.js';
 export * from './runtime/provider.js';
 export * from './runtime/transport.js';
-export * from './runtime/checkpoint.js';
 export * from './plugins/export.js';
 //# sourceMappingURL=index.d.ts.map

package/build/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,mBAAmB,YAAY,CAAA;AAC/B,cAAc,YAAY,CAAA;AAC1B,cAAc,cAAc,CAAA;AAC5B,cAAc,oBAAoB,CAAA;AAClC,cAAc,mBAAmB,CAAA;AACjC,cAAc,uBAAuB,CAAA;AACrC,cAAc,wBAAwB,CAAA;AACtC,cAAc,yBAAyB,CAAA;AACvC,cAAc,qBAAqB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,mBAAmB,YAAY,CAAA;AAC/B,cAAc,YAAY,CAAA;AAC1B,cAAc,cAAc,CAAA;AAC5B,cAAc,oBAAoB,CAAA;AAClC,cAAc,mBAAmB,CAAA;AACjC,cAAc,qBAAqB,CAAA;AACnC,cAAc,uBAAuB,CAAA;AACrC,cAAc,uBAAuB,CAAA;AACrC,cAAc,wBAAwB,CAAA;AACtC,cAAc,qBAAqB,CAAA"}

package/build/index.js

@@ -4,8 +4,9 @@ export * from './model.js';
 export * from './service.js';
 export * from './helpers/index.js';
 export * from './stores/index.js';
+export * from './pipeline/index.js';
+export * from './checkpoint/index.js';
 export * from './runtime/provider.js';
 export * from './runtime/transport.js';
-export * from './runtime/checkpoint.js';
 export * from './plugins/export.js';
 //# sourceMappingURL=index.js.map

package/build/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAE3B,cAAc,YAAY,CAAA;AAC1B,cAAc,cAAc,CAAA;AAC5B,cAAc,oBAAoB,CAAA;AAClC,cAAc,mBAAmB,CAAA;AACjC,cAAc,uBAAuB,CAAA;AACrC,cAAc,wBAAwB,CAAA;AACtC,cAAc,yBAAyB,CAAA;AACvC,cAAc,qBAAqB,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAE3B,cAAc,YAAY,CAAA;AAC1B,cAAc,cAAc,CAAA;AAC5B,cAAc,oBAAoB,CAAA;AAClC,cAAc,mBAAmB,CAAA;AACjC,cAAc,qBAAqB,CAAA;AACnC,cAAc,uBAAuB,CAAA;AACrC,cAAc,uBAAuB,CAAA;AACrC,cAAc,wBAAwB,CAAA;AACtC,cAAc,qBAAqB,CAAA"}

package/build/model.d.ts

@@ -3,13 +3,18 @@ import type { AgentModel, AgentOptions } from './types.js';
  * An OwlMeans agent over the LangGraph functional API.
  *
  * The loop is deliberately the plain one: ask the model, run whatever tools it asked for, feed the
- * results back, repeat until it stops asking. No `StateGraph`, and no LangGraph checkpointer — this
- * family's recoverability lives in the OwlMeans execution and flow layers, which already own a
- * serializable state model, and adopting a second one would leave two half-truths about where a
- * crashed run stands.
+ * results back, repeat until it stops asking.
  *
- * The `entrypoint` is created INSIDE `invoke()`, so nothing survives a call. What continuity a
- * conversation has comes from plugins putting it back into the prompt, not from the graph.
+ * The `entrypoint` is created INSIDE `invoke()` and takes no checkpointer, and that is not for want
+ * of one — `makePipeline` in this same package is a checkpointed `StateGraph`. **A ReAct run is not
+ * a resumable unit.** 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, and the identity a functional
+ * replay would key on is the positional call ordinal, which renumbers on any edit to the loop. What
+ * IS resumable is a pipeline, whose steps are named, whose state is scalars, and whose side effects
+ * are guarded per step — and an agent run belongs INSIDE one of those steps.
+ *
+ * So nothing survives a call here. What continuity a conversation has comes from plugins putting it
+ * back into the prompt, not from the graph.
  */
 export declare const makeAgentModel: (options: AgentOptions) => AgentModel;
 //# sourceMappingURL=model.d.ts.map

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;AAEnB;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,cAAc,YAAa,YAAY,KAAG,UA8OtD,CAAA"}
+{"version":3,"file":"model.d.ts","sourceRoot":"","sources":["../src/model.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EACV,UAAU,EAAE,YAAY,EACzB,MAAM,YAAY,CAAA;AAEnB;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,cAAc,YAAa,YAAY,KAAG,UA6PtD,CAAA"}

package/build/model.js

@@ -11,13 +11,18 @@ import { safeInvokeTool } from './helpers/tools.js';
  * An OwlMeans agent over the LangGraph functional API.
  *
  * The loop is deliberately the plain one: ask the model, run whatever tools it asked for, feed the
- * results back, repeat until it stops asking. No `StateGraph`, and no LangGraph checkpointer — this
- * family's recoverability lives in the OwlMeans execution and flow layers, which already own a
- * serializable state model, and adopting a second one would leave two half-truths about where a
- * crashed run stands.
+ * results back, repeat until it stops asking.
  *
- * The `entrypoint` is created INSIDE `invoke()`, so nothing survives a call. What continuity a
- * conversation has comes from plugins putting it back into the prompt, not from the graph.
+ * The `entrypoint` is created INSIDE `invoke()` and takes no checkpointer, and that is not for want
+ * of one — `makePipeline` in this same package is a checkpointed `StateGraph`. **A ReAct run is not
+ * a resumable unit.** 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, and the identity a functional
+ * replay would key on is the positional call ordinal, which renumbers on any edit to the loop. What
+ * IS resumable is a pipeline, whose steps are named, whose state is scalars, and whose side effects
+ * are guarded per step — and an agent run belongs INSIDE one of those steps.
+ *
+ * So nothing survives a call here. What continuity a conversation has comes from plugins putting it
+ * back into the prompt, not from the graph.
  */
 export const makeAgentModel = (options) => {
     const { exec, tools, entrypoint: entrypointName = DEFAULT_ENTRYPOINT, maxTurns = DEFAULT_MAX_TURNS, autoFinish = true, spectate, } = options;
@@ -29,22 +34,32 @@ export const makeAgentModel = (options) => {
     const prompts = options.prompts ?? exec.prompts;
     const provider = options.provider ?? pluginFor(agentModel);
     const purpose = exec.purpose;
-    const registry = [...(options.plugins ?? [])];
+    const registry = [];
     const ordered = () => [...registry].sort((a, b) => (a.order ?? DEFAULT_PLUGIN_ORDER) - (b.order ?? DEFAULT_PLUGIN_ORDER));
+    /**
+     * Seat by alias, keeping the original position.
+     *
+     * Registering the same plugin twice is a wiring accident, and the failure it causes — every
+     * context block emitted twice — is silent and expensive rather than loud. The options list goes
+     * through this same path, which is the whole point: a service composes its plugins ahead of an
+     * agent's own precisely so the agent's can REPLACE one by alias, and a constructor that simply
+     * spread the array made "replace" mean "run both".
+     */
+    const seat = (plugin) => {
+        const at = registry.findIndex(entry => entry.alias === plugin.alias);
+        if (at < 0) {
+            registry.push(plugin);
+        }
+        else {
+            registry[at] = plugin;
+        }
+    };
+    for (const plugin of options.plugins ?? []) {
+        seat(plugin);
+    }
     const model = {
         conversation: () => conversation,
-        use: plugin => {
-            // Seat by alias, keeping the original position: registering the same plugin twice is a wiring
-            // accident, and the failure it would otherwise cause — every context block emitted twice — is
-            // silent and expensive rather than loud.
-            const at = registry.findIndex(entry => entry.alias === plugin.alias);
-            if (at < 0) {
-                registry.push(plugin);
-            }
-            else {
-                registry[at] = plugin;
-            }
-        },
+        use: seat,
         invoke: async (input, args = {}) => {
             const action = args.action ?? DEFAULT_ACTION;
             const opening = typeof input === 'string' ? new HumanMessage({ content: input }) : input;
@@ -104,7 +119,7 @@ export const makeAgentModel = (options) => {
             });
             // 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) => safeInvokeTool(toolSet, toolCall));
+            const call = task('call-tool', async (toolCall) => safeInvokeTool(toolSet, toolCall, options.fatal));
             const agent = entrypoint(entrypointName, async (messages) => {
                 let response = await ask(messages);
                 let turn = 0;