@owlmeans/agent-common 0.1.18-rc.9 → 0.1.18

package/README.md

@@ -1,23 +1,160 @@
 # @owlmeans/agent-common
 
 Serializable contracts for OwlMeans agents and LLM pipelines: conversation identity, the run
-lifecycle flow, and the record shapes an application persists.
+lifecycle flow, the pipeline declaration and run row, the cumulative-results records with their
+deterministic renderers, and the record shapes an application persists. Runtime-free by design — no
+LangChain, no LangGraph, no storage driver — so a backend, a reconciler, an operator console or a
+browser bundle imports it to read what an agent wrote and to say where a pipeline run stands. It does
+not run anything: executing agents and pipelines, binding stores and cutting result views is the
+runtime, [`@owlmeans/agent`](../agent). The package's skill is `agent-common`.
 
-Runtime-free by design — no LangChain, no LangGraph, no storage driver. A backend or a browser
-bundle can import these shapes to read what an agent wrote without pulling the runtime. The
-runtime is [`@owlmeans/agent`](../agent).
+## Installation
 
-## What is here
+```bash
+bun add @owlmeans/agent-common@^0.1.18
+```
+
+## Concepts
+
+- **Conversation** — `ConversationRef` (`{ conversationId, scope }`): the thread a run belongs to and
+  the wider subject its memory is filed under. `conversationFor` derives both from an `LlmPurpose`
+  dedication (`<kind>:<id>`).
+- **Run lifecycle** — `agentRunFlow`, an `@owlmeans/flow` declaration with steps `Received` →
+  `Prepared` → `Working` → `Finalizing` → `Finished`, plus a terminal `Failed`. The steps say how far
+  a run got; nothing resumes one.
+- **Pipeline** — `PipelineSpec`, a declaration of named steps joined by `after` edges. It is the
+  resumable unit; `makePipelineSpecModel(spec)` validates and orders it.
+- **Pipeline run** — `PipelineRun`, the one authority on where a run stands: status, `completed` /
+  `pending` steps, `state` as JSON **text** with `stateChars`, and `heartbeatAt`.
+- **Cumulative results** — `CumulativeResultFact`s a step produced, collected into a
+  `CumulativeResultEntry` per step, rendered full or names-only so later steps reuse the
+  authoritative names.
+- **Port** — a store name (`AGENT_CONVERSATION_STORE`, …) a consumer binds its own storage under. An
+  unbound port is not an error; the plugin that needs it degrades to a no-op.
+
+## Usage
+
+### Derive a conversation and cap text
+
+```typescript
+import { DEFAULT_SUMMARY_CHARS, conversationFor, truncateAt } from '@owlmeans/agent-common'
+
+const ref = conversationFor({ type: 'coder', dedication: `project:${projectId}` })
+// { conversationId: 'project:<id>', scope: '<id>' } — an empty dedication becomes 'anonymous'
+
+const summary = truncateAt(modelAnswer, DEFAULT_SUMMARY_CHARS) // cuts on a paragraph/line/sentence/word, marks with '…'
+```
+
+### Drive the run lifecycle
+
+```typescript
+import { makeFlowModel } from '@owlmeans/flow'
+import { AgentRunStep, AgentRunTransition, agentRunFlow } from '@owlmeans/agent-common'
+
+const model = await makeFlowModel(agentRunFlow)
+model.transit(model.next().transition, true) // Received → Prepared: one automatic edge per step
+model.transit(AgentRunTransition.Work, true)
+
+model.step().step === AgentRunStep.Working
+```
+
+### Declare and validate a pipeline
+
+```typescript
+import { makePipelineSpecModel, PipelineSpecError } from '@owlmeans/agent-common'
+import type { PipelineSpec } from '@owlmeans/agent-common'
+
+export const scaffoldPipeline: PipelineSpec = {
+  alias: 'scaffold',
+  version: 2, // bump on every added, removed or renamed step
+  steps: [
+    { step: 'plan', title: 'Plan the change' },
+    { step: 'types', after: ['plan'] },
+    { step: 'api', after: ['types'] },
+    { step: 'web', after: ['types'] },
+    { step: 'wipe-preview', after: ['api', 'web'], nonIdempotent: true },
+  ],
+}
+
+const spec = makePipelineSpecModel(scaffoldPipeline)
+spec.validate()              // throws PipelineSpecError naming every fault at once
+spec.orderSteps()            // ['plan', 'types', 'api', 'web', 'wipe-preview']
+spec.descendants('types')    // what a resume from 'types' re-runs, 'types' included
+spec.ancestry('wipe-preview') // [{ step: 'plan', depth: 3 }, { step: 'types', depth: 2 }, …]
+```
+
+### Render a step's results
+
+```typescript
+import { CumulativeFactKind, CumulativeResultSource, cumulativeResultsHelper } from '@owlmeans/agent-common'
+
+const { full, compact } = cumulativeResultsHelper.renderResultEntry({
+  label: 'types',
+  source: CumulativeResultSource.Extracted,
+  facts: [
+    { kind: CumulativeFactKind.Type, name: 'User', signature: '{ id: string; email: string }', specifier: '@app/common' },
+    { kind: CumulativeFactKind.Endpoint, name: 'user.create', ref: 'User', attrs: { method: 'POST', path: '/api/users' } },
+  ],
+})
+
+const spec = cumulativeResultsHelper.mergeResultsSpecs(pipelineResults, deploymentOverlay)
+```
+
+## API
+
+### Functions and helpers
 
 | Export | Purpose |
 |---|---|
 | `conversationFor(purpose, override?)` | Derives a `ConversationRef` from an `LlmPurpose` dedication — the thread identity an agent run belongs to |
 | `truncateAt(text, max)` | Boundary-aware truncation; every character cap in the family lands here |
-| `agentRunFlow` / `AgentRunStep` / `AgentRunTransition` | The `@owlmeans/flow` lifecycle a run is driven through |
-| `ConversationEvent` | One finished run, compacted: `summary` (what happened) + `advice` (what to do next) |
-| `AgentRunState` | The data plane of a run — serialized flow plus the execution snapshot |
-| `MemoryNode` / `MemoryEvent` | Agent-authored memory: a subsystem graph node, and an entry in a bounded sequence |
+| `makePipelineSpecModel(spec)` | `PipelineSpecModel`: `validate`, `orderSteps`, `descendants`, `ancestry`, `ancestors`, `stepOf`, `record` |
+| `validatePipelineSpec`, `orderPipelineSteps`, `pipelineDescendants`, `pipelineStep` | Deprecated wrappers over `makePipelineSpecModel` |
+| `cumulativeResultsHelper` (`createCumulativeResultsHelper()`) | `factKey`, `sortFacts`, `renderResultFact`, `renderResultEntry`, `renderResultSummary`, `compareResultOrder`, `rootRunOf`, `resultLabel`, `mergeResultsSpecs` |
+
+### Records and types
+
+| Export | Purpose |
+|---|---|
+| `agentRunFlow` / `agentFlows` / `AgentRunStep` / `AgentRunTransition` | The `@owlmeans/flow` lifecycle a run is driven through |
+| `ConversationEvent` (+ `ConversationEventInput`) | One finished run, compacted: `summary` (what happened) + `advice` (what to do next) |
+| `MemoryNode` / `MemoryEvent` (+ `MemoryEventInput`) | Agent-authored memory: a subsystem graph node, and an entry in a bounded sequence |
 | `AgentRunMessage` | What a transport carries; execution state travels by reference |
+| `PipelineSpec`, `PipelineStepSpec`, `PipelineState` | The declaration and the scalar state passed between steps |
+| `PipelineRun`, `PipelineRunInquiry`, `PipelineProgress` | The persisted run row, the question a `Waiting` run stopped on, runner progress |
+| `PipelineSpecModel`, `PipelineStepDepth` | The spec model and an ancestor with its edge distance |
+| `CumulativeResultFact`, `CumulativeResultEntry`, `RenderableResultEntry`, `RenderedResultEntry`, `ResultRenderCaps` | Cumulative-results records and rendering |
+| `CumulativeResultsSpec`, `StepResultsSpec`, `ResultSummarySpec`, `ResultFactQuery`, `CumulativeResultsHelper` | The JSON-safe declaration, a facts query, the helper interface |
+
+### Constants and enums
+
+| Export | Value / members |
+|---|---|
+| `AGENTS_SERVICE` | `'agents'` — plural, so it never collides with an app's own `agent` service |
+| `AGENT_CONVERSATION_STORE`, `AGENT_MEMORY_GRAPH_STORE`, `AGENT_MEMORY_EVENTS_STORE`, `AGENT_PIPELINE_RUN_STORE`, `AGENT_CHECKPOINT_STORE`, `AGENT_CUMULATIVE_RESULT_STORE` | Port names |
+| `AGENT_RUN_FLOW`, `SCOPE_SEP`, `INQUIRY_ANSWERS_KEY`, `RESULTS_EVERY_STEP` | `'agent-run'`, `':'`, `'answers'`, `'*'` |
+| `DEFAULT_SUMMARY_CHARS` 1200 · `DEFAULT_ADVICE_CHARS` 400 · `DEFAULT_EVENT_WINDOW` 3 · `DEFAULT_MEMORY_NODE_CHARS` 2000 · `DEFAULT_MEMORY_EVENTS_LIMIT` 50 | Run and memory caps |
+| `DEFAULT_MAX_STATE_CHARS` 256 000 · `DEFAULT_STEP_ATTEMPTS` 1 · `DEFAULT_STEP_TIMEOUT` 1 800 000 ms | Pipeline defaults |
+| `DEFAULT_RESULTS_MAX_CHARS` 12 000 · `DEFAULT_RESULT_ENTRY_CHARS` 4 000 · `DEFAULT_RESULT_COMPACT_CHARS` 400 · `DEFAULT_RESULTS_WINDOW` 2 · `DEFAULT_RESULT_SUMMARY_CHARS` 600 | Cumulative-results caps |
+| `AgentRunStatus` | `Ok`, `Failed` |
+| `PipelineRunStatus` | `Running`, `Done`, `Failed`, `Aborted`, `Waiting` |
+| `CumulativeResultSource` | `Extracted`, `Rebuilt`, `Seeded`, `Summarized` |
+| `CumulativeFactKind` | `Type`, `Symbol`, `Endpoint`, `Resource`, `File` |
+| `ResultViewMode` | `Full`, `Compact`, `Omitted` |
+
+### Errors
+
+All extend `AgentCommonError` (a `ResilientError`) and are registered for marshalling.
+
+| Error | Thrown when |
+|---|---|
+| `AgentRunStateError` | a run is asked to advance along a transition its step does not offer |
+| `PipelineSpecError` | a declaration is not runnable — every fault in one message |
+| `PipelineVersionError` | a resume targets a run started under another spec `version` |
+| `PipelineUnknownStepError` | a step name the spec does not declare |
+| `PipelineNotIdempotentError` | a resume would re-enter a completed `nonIdempotent` step without `force` |
+| `PipelineStateTooLargeError` | a step's state exceeds the run row's cap |
+| `PipelineNotResumableError` | a step asks a question with no one to answer and no run store to park in |
 
 ## Conventions worth knowing
 
@@ -27,8 +164,8 @@ at its own adapter boundary.
 
 **Flow steps are lifecycle stages, not conversational turns.** `FlowPayload` holds flat scalars
 only and a ReAct loop's turn count is unbounded, so the loop lives inside the `Working` step and
-only its counter travels in the payload. What the steps buy is the ability to say where an
-interrupted run resumes.
+only its counter travels in the payload. What the steps buy is the ability to say how far a run got
+when it ended. Resumable work is a pipeline.
 
 **Each working step has exactly one non-explicit outgoing transition**, so `FlowModel.next()` always
 has an unambiguous answer and a driver can advance a run without knowing the vocabulary. `Fail` is
@@ -36,7 +173,31 @@ marked explicit precisely so it never becomes that automatic answer.
 
 **Port names are exported, ports are not bound here.** `AGENT_CONVERSATION_STORE` and friends are
 the keys a consumer registers its own storage under. An unbound port is not an error — the plugin
-that needs it degrades to a no-op.
+that needs it degrades to a no-op. A pipeline without `AGENT_PIPELINE_RUN_STORE` still runs but
+cannot be resumed.
+
+**A rendered result entry is deterministic.** Facts sort by kind (file facts last), name and
+location; nothing that varies (timestamp, run id, revision) is rendered, and over its cap an entry
+drops whole facts and says how many.
+
+## Common pitfalls
+
+- A pipeline state is scalars and keys; a document in it fails the step with
+  `PipelineStateTooLargeError` rather than being truncated — store artifacts elsewhere and pass keys.
+- Forgetting to bump `version` after renaming a step lets a resume skip work silently; a bumped
+  version makes the resume refuse instead.
+- `nonIdempotent: true` with `attempts > 1` is a validation fault.
+- `ancestry`/`ancestors` exclude the named step, `descendants` include it.
+- Caps are applied by truncation after the model answers; restating them in a prompt is not a cap.
+- A `Waiting` run's `heartbeatAt` does not move — do not treat it as stale.
+
+## Related packages
+
+- [`@owlmeans/agent`](../agent) — the runtime that executes runs and pipelines and writes these records
+- [`@owlmeans/llm-common`](../llm-common) — `LlmPurpose` and `Inquiry`
+- [`@owlmeans/flow`](../flow) — the flow model the run lifecycle is declared against
+- [`@owlmeans/resource`](../resource) — `ResourceRecord`, the base of every persisted record
+- [`@owlmeans/error`](../error) — `ResilientError`, the base of the error family
 
 <!-- owlmeans:agent-guidance:start -->
 ## Agent guidance
@@ -46,7 +207,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
+npx @owlmeans/agent-skills@^0.1.18
 ```
 
 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-common",
-  "version": "0.1.18-rc.8",
-  "generatedAt": "2026-08-27T21:16:47.137Z",
+  "version": "0.1.18",
+  "generatedAt": "2026-10-28T00:31:34.712Z",
   "canonicalRepo": "https://github.com/owlmeans/common",
   "entries": [
     {

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

@@ -1,6 +1,6 @@
 ---
 name: agent-common
-description: How to use @owlmeans/agent-common — runtime-free contracts for OwlMeans agents: conversation identity, the run-lifecycle flow, and the record shapes an application persists (conversation events, run state, memory nodes and events). Auto-invoked when importing agent record types, conversationFor, truncateAt, or the agent run flow.
+description: "How to use @owlmeans/agent-common — runtime-free contracts for OwlMeans agents: conversation identity, the run-lifecycle flow, the PIPELINE declaration (PipelineSpec, PipelineRun, validatePipelineSpec, orderPipelineSteps, pipelineAncestors), the CUMULATIVE PIPELINE RESULTS contracts (facts, entries, declarations, deterministic renderers) and the record shapes an application persists. Auto-invoked when importing agent record types, a pipeline spec or run type, a cumulative-results type or renderer, conversationFor, truncateAt, or the agent run flow."
 user-invocable: false
 ---
 <!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
@@ -8,7 +8,7 @@ user-invocable: false
 # @owlmeans/agent-common
 
 **Layer:** Cross-cutting domain
-**Install:** `"@owlmeans/agent-common": "^0.1.18-rc.8"` in `dependencies`
+**Install:** `"@owlmeans/agent-common": "^0.1.18"` in `dependencies`
 
 Serializable contracts for the agent family. No LangChain, no LangGraph, no storage driver — a
 backend or a browser bundle imports these to read what an agent wrote without pulling the runtime.
@@ -18,18 +18,27 @@ The runtime is `@owlmeans/agent`.
 
 | Export | Description |
 |---|---|
-| `conversationFor(purpose, override?)` | Derives a `ConversationRef` from an `LlmPurpose` dedication. |
+| `ConversationRef` | `{ conversationId, scope }` — the thread a run belongs to, and the wider subject it is about. Two fields, because memory is filed per subject while threads may be finer-grained. |
+| `conversationFor(purpose, override?)` · `SCOPE_SEP` | Derives a `ConversationRef` from an `LlmPurpose` dedication (`<kind>:<id>`, split on `SCOPE_SEP`); either half is overridable. |
 | `truncateAt(text, max)` | Boundary-aware truncation. Every character cap in the family lands here. |
 | `agentRunFlow`, `AgentRunStep`, `AgentRunTransition`, `AGENT_RUN_FLOW` | The `@owlmeans/flow` lifecycle a run is driven through. |
 | `agentFlows` | Every flow this package declares, for a provider to serve. |
 | `ConversationEvent`, `ConversationEventInput` | One finished run, compacted: `summary` + `advice`. |
-| `AgentRunState` | Serialized flow plus the execution snapshot — the data plane of a run. |
 | `MemoryNode`, `MemoryEvent` (+ `MemoryEventInput`) | Agent-authored memory records. |
-| `AgentRunMessage` | What a transport carries; execution state travels by reference. |
+| `AgentRunMessage` | What a transport carries — a POINTER (`runId`, `conversationId`, optional `pipeline`/`step`), never state. |
+| `PipelineStepSpec`, `PipelineSpec` | The declaration: named steps, `after: string[]` edges, `optional`, `nonIdempotent`, `attempts`, `timeout`. |
+| `PipelineRun`, `PipelineRunStatus`, `PipelineProgress` | The persisted run row — `state` is JSON **text** plus `stateChars`; `completed`/`pending`/`warnings`; `heartbeatAt`. |
+| `validatePipelineSpec`, `orderPipelineSteps`, `pipelineDescendants`, `pipelineAncestors`, `pipelineAncestry`, `pipelineStep` | Pure spec helpers — no runtime, no graph engine. |
+| `CumulativeResultFact`, `CumulativeResultEntry`, `CumulativeResultSource`, `CumulativeFactKind`, `ResultViewMode`, `ResultFactQuery` | CUMULATIVE PIPELINE RESULTS records: one authoritative fact, one step's entry in a ledger. |
+| `CumulativeResultsSpec`, `StepResultsSpec`, `ResultSummarySpec`, `mergeResultsSpecs`, `RESULTS_EVERY_STEP` | The JSON-safe declaration — per step: extractors by name, `full`/`omit` consumers, `window`, caps, `refresh`, an optional `summary`. |
+| `renderResultEntry`, `renderResultFact`, `renderResultSummary`, `sortFacts`, `factKey`, `compareResultOrder`, `resultLabel`, `rootRunOf` | Deterministic renderers and ledger helpers. |
 | `AGENTS_SERVICE` | The service alias — **`agents`**, plural. |
 | `AGENT_*_STORE` | Port names a consumer binds its storage under. |
 | `AgentRunStatus` | `ok` / `failed`, written on a conversation event. |
-| `AgentCommonError`, `AgentRunStateError` | The error family. |
+| `AgentCommonError`, `AgentRunStateError`, `PipelineSpecError`, `PipelineVersionError`, `PipelineUnknownStepError`, `PipelineNotIdempotentError`, `PipelineStateTooLargeError` | The error family. |
+| `DEFAULT_SUMMARY_CHARS` (1200) · `DEFAULT_ADVICE_CHARS` (400) · `DEFAULT_EVENT_WINDOW` (3) · `DEFAULT_MEMORY_NODE_CHARS` (2000) · `DEFAULT_MEMORY_EVENTS_LIMIT` (50) | The caps the runtime's plugins default to. Override them per plugin; read them here rather than restating a number. |
+| `DEFAULT_MAX_STATE_CHARS` (256_000) · `DEFAULT_STEP_ATTEMPTS` (1) · `DEFAULT_STEP_TIMEOUT` (30 min) | Pipeline defaults. The state cap is a TRIPWIRE, not a budget. |
+| `DEFAULT_RESULTS_MAX_CHARS` (12_000) · `DEFAULT_RESULT_ENTRY_CHARS` (4_000) · `DEFAULT_RESULT_COMPACT_CHARS` (400) · `DEFAULT_RESULTS_WINDOW` (2) · `DEFAULT_RESULT_SUMMARY_CHARS` (600) · `AGENT_CUMULATIVE_RESULT_STORE` | Cumulative-results caps — they bound what a step is TOLD, never what it may produce — and the store's port name. |
 
 ## Rules
 
@@ -41,26 +50,72 @@ at its own adapter boundary — that is the adapter's job, not the contract's.
 `agent`: a consuming application very often already has a service of its own called that, and a
 context accessor collision is silent — the second registration simply wins.
 
-**Flow steps are lifecycle stages, not conversational turns.** `FlowPayload` holds flat scalars only
-and a ReAct loop's turn count is unbounded, so the loop lives inside the `Working` step and only its
-counter travels in the payload. What the steps buy is knowing where an interrupted run resumes:
-`Working` from the last checkpoint, or `Finalizing` when the loop finished but the compaction never
-committed.
+**Flow steps are lifecycle stages, not conversational turns, and nothing RESUMES one.** `FlowPayload`
+holds flat scalars only and a ReAct loop's turn count is unbounded, so the loop lives inside the
+`Working` step and only its counter travels in the payload. What the steps buy is the ability to say
+how far a run got when it ended, which is what a plugin reads on `onFinish`. Resumable work is a
+PIPELINE — named steps, a state of scalars, side effects guarded per step. A ReAct run is not one:
+its state is an unbounded message list whose tool results are already applied to the world.
+
+**A `PipelineSpec` is a DECLARATION and this package holds no engine.** The steps' bodies, the graph,
+the checkpointer and the stores all live in `@owlmeans/agent`; what is here is what a browser bundle,
+a reconciler or an operator console must read to say where a run stands without importing LangGraph.
+That is also why `PipelineRun.state` is JSON **text** with a `stateChars` beside it rather than a
+subdocument: a run row crosses a `$jsonSchema`, and a state whose keys are dotted paths does not.
+
+**`validatePipelineSpec` names EVERY fault at once** — unknown `after` targets, cycles, duplicate
+step names, `attempts > 1` on a `nonIdempotent` step. A spec is authored once and fixed once, and
+reporting faults one per build turns a five-minute edit into five builds.
+
+**A resume across a `version` change is REFUSED, never adapted.** `completed` names steps by string,
+so a spec that has since renamed, removed or reordered one would let a resumed run skip work it never
+did — silently, because an unknown name in `completed` matches nothing.
 
 **Each working step keeps exactly one non-explicit outgoing transition.** That is what lets
 `FlowModel.next()` give a driver an unambiguous answer without knowing the vocabulary. `Fail` is
 marked `explicit` precisely so it can never become that automatic answer. Adding a second automatic
 edge to any step breaks `next()` for that step.
 
+**Every cap is enforced by truncation after the model answers, never by asking for it.** A cap in a
+prompt is a request; a cap in code is a cap. That is why the defaults live here as numbers rather
+than as prompt text.
+
 **A conversation id degrades to a named default, never to an empty string.** An empty key would
 silently collapse every run of every subject into one thread.
 
+**`pipelineAncestors` mirrors `pipelineDescendants` but excludes the named step.** A re-run re-enters
+the step it names; nothing is its own predecessor. `pipelineAncestry` adds each ancestor's DEPTH —
+the fewest `after` edges between them — which is what a results window counts, so a direct
+predecessor is depth 1 however far apart the two sit in the topological order.
+
+**A rendered entry is deterministic and carries nothing that varies.** Facts sort by kind (file
+facts last — a location is what a budget spares first), name and location with a code-unit compare;
+no timestamp, run id or revision is ever rendered. Over its cap an entry drops WHOLE facts and says
+how many ("they exist: check the files"), never half a signature. An empty non-partial entry renders
+to `''` and costs a view nothing; a summary is always labelled "not verified".
+
+**An entry's `order` is a PATH, not a number.** It is the step's topological index behind the index
+path of every step it was composed under; where one key prefixes another the longer sorts FIRST, so
+a composed run's entries precede the composing step's own. Two pipelines' indexes are not comparable,
+which is why a single sequence number cannot order a ledger.
+
+**Declarations merge like skills.** `mergeResultsSpecs` lets later declarations win field by field
+but ACCUMULATES extractors, `full` and `omit` lists; `'*'` absorbs names.
+
 **Port names are exported; ports are not bound here.** An unbound port is not an error — the plugin
-that needs it degrades to a no-op, the way `ExecutionService.checkpoint` does with no plugin
-registered.
+that needs it degrades to a no-op. `AGENT_PIPELINE_RUN_STORE` is the one exception in spirit: a
+pipeline with no run store still runs, but it is not resumable, because the ROW is what a resume
+reads. `AGENT_CHECKPOINT_STORE` may be absent with no loss of correctness at all.
 
 ## Testing
 
 Category A (unit, no env, no network). This package's own `tests/flow.spec.ts` covers the flow
 round-trip — which is also the standing check that `@owlmeans/flow` still works server-side, since
-every other consumer of that package is client-side.
+every other consumer of that package is client-side. `tests/results.spec.ts` pins the exact bytes an
+entry renders to; a change there changes what every consuming step is told.
+
+## Related
+
+- [[agent]] — the runtime that writes these records
+- [[llm-common]] — `LlmPurpose` and `ExecutionState`, which a run's execution is built from
+- [[flow]] — the flow model the run lifecycle is declared against

package/build/consts.d.ts

@@ -1,3 +1,4 @@
+import type { ShallowFlow } from '@owlmeans/flow';
 /**
  * The agent service alias.
  *
@@ -15,9 +16,50 @@ export declare const AGENTS_SERVICE = "agents";
  * the same way `ExecutionService.checkpoint` does with no plugin registered.
  */
 export declare const AGENT_CONVERSATION_STORE = "agent-conversation-store";
-export declare const AGENT_RUN_STATE_STORE = "agent-run-state-store";
 export declare const AGENT_MEMORY_GRAPH_STORE = "agent-memory-graph-store";
 export declare const AGENT_MEMORY_EVENTS_STORE = "agent-memory-events-store";
+export declare const AGENT_PIPELINE_RUN_STORE = "agent-pipeline-run-store";
+export declare const AGENT_CHECKPOINT_STORE = "agent-checkpoint-store";
+export declare const AGENT_CUMULATIVE_RESULT_STORE = "agent-cumulative-result-store";
+/**
+ * Caps and defaults for cumulative pipeline results.
+ *
+ * Every one of them bounds what a later step is TOLD, never what a step may produce: a fact that
+ * does not fit is left out of one view, and it is still on its entry for the next view and for any
+ * code that queries it. `DEFAULT_RESULTS_WINDOW` is a distance in the step graph — a consumer that
+ * many edges or fewer after a producer gets the producer's full entry; anything further back gets
+ * its names only, unless the producer names the consumer outright.
+ */
+export declare const DEFAULT_RESULTS_MAX_CHARS = 12000;
+export declare const DEFAULT_RESULT_ENTRY_CHARS = 4000;
+export declare const DEFAULT_RESULT_COMPACT_CHARS = 400;
+export declare const DEFAULT_RESULTS_WINDOW = 2;
+export declare const DEFAULT_RESULT_SUMMARY_CHARS = 600;
+/** The consumer wildcard: every later step of the pipeline — and of anything it is composed into. */
+export declare const RESULTS_EVERY_STEP = "*";
+/**
+ * Caps and defaults for a pipeline run.
+ *
+ * `DEFAULT_MAX_STATE_CHARS` is generous by the standard of what a state may legally hold — scalars
+ * and keys — and deliberately so: it is a TRIPWIRE, not a budget. A state approaching it is a state
+ * carrying an artifact, and the step fails so that fact is discovered on the first run rather than
+ * surviving as a row nobody can read back.
+ *
+ * `DEFAULT_STEP_ATTEMPTS` is 1 because retry budgets in this family multiply: an outer retry around
+ * a model's own inner retry is their product, not their sum.
+ */
+export declare const DEFAULT_MAX_STATE_CHARS = 256000;
+export declare const DEFAULT_STEP_ATTEMPTS = 1;
+export declare const DEFAULT_STEP_TIMEOUT = 1800000;
+/**
+ * Where a pipeline's answers live in its state.
+ *
+ * One key, named here rather than per pipeline, because an answer has to survive every hop it can
+ * take: a resume merges answers into it, a composing step forwards it to its child, and a reader
+ * looks a question up by id. Scalars and keys, like everything else a state holds — the answer's
+ * decision travels here and its prose belongs wherever that pipeline keeps its documents.
+ */
+export declare const INQUIRY_ANSWERS_KEY = "answers";
 /** The lifecycle flow every agent run is driven through. */
 export declare const AGENT_RUN_FLOW = "agent-run";
 /**
@@ -26,8 +68,12 @@ export declare const AGENT_RUN_FLOW = "agent-run";
  * These are recoverable LIFECYCLE stages, not conversational turns. A ReAct loop's turn count is
  * unbounded and its messages are not scalars, while `FlowPayload` holds flat scalars only — so the
  * loop lives inside `Working` and only its counter travels in the payload. What the steps buy is
- * the ability to say where a crashed run has to resume: at `Working` from the last checkpoint, or
- * at `Finalizing` when the loop finished but the compaction never committed.
+ * the ability to say how far a run got when it ended, which is what a plugin reads on `onFinish`.
+ *
+ * Nothing RESUMES one of these. 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, so re-entering it
+ * would re-apply them. Resumable work is a PIPELINE — see `pipeline.ts` — whose steps are named,
+ * whose state is scalars, and whose side effects are guarded per step.
  */
 export declare enum AgentRunStep {
     Received = "received",
@@ -43,8 +89,7 @@ export declare enum AgentRunTransition {
     Work = "work",
     Finalize = "finalize",
     Finish = "finish",
-    Fail = "fail",
-    Resume = "resume"
+    Fail = "fail"
 }
 /** How a run ended. Written on the conversation event so a reader can weigh the advice. */
 export declare enum AgentRunStatus {
@@ -64,4 +109,72 @@ export declare const DEFAULT_MEMORY_NODE_CHARS = 2000;
 export declare const DEFAULT_MEMORY_EVENTS_LIMIT = 50;
 /** Separator between a dedication's kind and its target — `project:<id>`. */
 export declare const SCOPE_SEP = ":";
+/** How a run ended, or that it has not. */
+export declare enum PipelineRunStatus {
+    Running = "running",
+    Done = "done",
+    Failed = "failed",
+    /** Stopped on purpose with work left — a budget expired, or the caller asked. Resumable. */
+    Aborted = "aborted",
+    /**
+     * Stopped on purpose, waiting for an answer to {@link PipelineRun.inquiry}.
+     *
+     * Resumable, and NOT stale: a waiting run has no process behind it and its `heartbeatAt` will not
+     * move again until somebody answers. A reconciler that reads staleness alone would take this for
+     * a crashed run and repair what is merely waiting.
+     */
+    Waiting = "waiting"
+}
+/** Where the facts of an entry came from. */
+export declare enum CumulativeResultSource {
+    /** Read by code from what the step left behind, when the step finished. */
+    Extracted = "extracted",
+    /**
+     * Read by code from the step's DURABLE inputs, after the fact — on a resume that found no stored
+     * entry, or for a step whose guard skipped it. The same facts an extraction would have found.
+     */
+    Rebuilt = "rebuilt",
+    /** Supplied before any step of the run ran — the caller already knew them. */
+    Seeded = "seeded",
+    /** No facts at all; only a model's summary, which nothing has checked. */
+    Summarized = "summarized"
+}
+/** How one entry appears in a view cut for a given step. */
+export declare enum ResultViewMode {
+    Full = "full",
+    /** Names only, grouped by kind. */
+    Compact = "compact",
+    /** Not in the prompt. Still answered by a programmatic facts query. */
+    Omitted = "omitted"
+}
+/**
+ * Kinds an extractor is encouraged to use. `CumulativeResultFact.kind` is an open string — declare
+ * your own — but two extractors naming the same thing differently split one fact into two.
+ */
+export declare enum CumulativeFactKind {
+    Type = "type",
+    Symbol = "symbol",
+    Endpoint = "endpoint",
+    Resource = "resource",
+    File = "file"
+}
+/**
+ * The lifecycle of one agent run.
+ *
+ * Read it as "how far did this run get", not "what did it say". Everything conversational happens
+ * inside `Working`; the steps exist so a plugin reading `onFinish` can say where a run ended.
+ * `Fail` is reachable from every working step and is TERMINAL — see the note on that step.
+ *
+ * `service` is left as the flow name on every step. A flow step normally binds to a service or an
+ * entrypoint, but an agent run is driven by whoever holds the model — there is no second party to
+ * hand control to, and inventing one would put a name in the serialized state that nothing
+ * resolves.
+ *
+ * Each working step keeps exactly ONE non-explicit outgoing transition, so `FlowModel.next()`
+ * always has an unambiguous answer: that is what lets a driver advance the run without knowing the
+ * vocabulary. `Fail` is marked explicit precisely so it never becomes that automatic answer.
+ */
+export declare const agentRunFlow: ShallowFlow;
+/** Every flow this package declares, for a provider to serve. */
+export declare const agentFlows: ShallowFlow[];
 //# sourceMappingURL=consts.d.ts.map

package/build/consts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"consts.d.ts","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc,WAAW,CAAA;AAEtC;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB,6BAA6B,CAAA;AAClE,eAAO,MAAM,qBAAqB,0BAA0B,CAAA;AAC5D,eAAO,MAAM,wBAAwB,6BAA6B,CAAA;AAClE,eAAO,MAAM,yBAAyB,8BAA8B,CAAA;AAEpE,4DAA4D;AAC5D,eAAO,MAAM,cAAc,cAAc,CAAA;AAEzC;;;;;;;;GAQG;AACH,oBAAY,YAAY;IACtB,QAAQ,aAAa;IACrB,QAAQ,aAAa;IACrB,OAAO,YAAY;IACnB,UAAU,eAAe;IACzB,QAAQ,aAAa;IACrB,MAAM,WAAW;CAClB;AAED,iDAAiD;AACjD,oBAAY,kBAAkB;IAC5B,OAAO,YAAY;IACnB,IAAI,SAAS;IACb,QAAQ,aAAa;IACrB,MAAM,WAAW;IACjB,IAAI,SAAS;IACb,MAAM,WAAW;CAClB;AAED,2FAA2F;AAC3F,oBAAY,cAAc;IACxB,EAAE,OAAO;IACT,MAAM,WAAW;CAClB;AAED;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,OAAO,CAAA;AACzC,eAAO,MAAM,oBAAoB,MAAM,CAAA;AACvC,eAAO,MAAM,oBAAoB,IAAI,CAAA;AACrC,eAAO,MAAM,yBAAyB,OAAO,CAAA;AAC7C,eAAO,MAAM,2BAA2B,KAAK,CAAA;AAE7C,6EAA6E;AAC7E,eAAO,MAAM,SAAS,MAAM,CAAA"}
+{"version":3,"file":"consts.d.ts","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAA;AAEjD;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc,WAAW,CAAA;AAEtC;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB,6BAA6B,CAAA;AAClE,eAAO,MAAM,wBAAwB,6BAA6B,CAAA;AAClE,eAAO,MAAM,yBAAyB,8BAA8B,CAAA;AACpE,eAAO,MAAM,wBAAwB,6BAA6B,CAAA;AAClE,eAAO,MAAM,sBAAsB,2BAA2B,CAAA;AAC9D,eAAO,MAAM,6BAA6B,kCAAkC,CAAA;AAE5E;;;;;;;;GAQG;AACH,eAAO,MAAM,yBAAyB,QAAS,CAAA;AAC/C,eAAO,MAAM,0BAA0B,OAAQ,CAAA;AAC/C,eAAO,MAAM,4BAA4B,MAAM,CAAA;AAC/C,eAAO,MAAM,sBAAsB,IAAI,CAAA;AACvC,eAAO,MAAM,4BAA4B,MAAM,CAAA;AAE/C,qGAAqG;AACrG,eAAO,MAAM,kBAAkB,MAAM,CAAA;AAErC;;;;;;;;;;GAUG;AACH,eAAO,MAAM,uBAAuB,SAAU,CAAA;AAC9C,eAAO,MAAM,qBAAqB,IAAI,CAAA;AACtC,eAAO,MAAM,oBAAoB,UAAY,CAAA;AAE7C;;;;;;;GAOG;AACH,eAAO,MAAM,mBAAmB,YAAY,CAAA;AAE5C,4DAA4D;AAC5D,eAAO,MAAM,cAAc,cAAc,CAAA;AAEzC;;;;;;;;;;;;GAYG;AACH,oBAAY,YAAY;IACtB,QAAQ,aAAa;IACrB,QAAQ,aAAa;IACrB,OAAO,YAAY;IACnB,UAAU,eAAe;IACzB,QAAQ,aAAa;IACrB,MAAM,WAAW;CAClB;AAED,iDAAiD;AACjD,oBAAY,kBAAkB;IAC5B,OAAO,YAAY;IACnB,IAAI,SAAS;IACb,QAAQ,aAAa;IACrB,MAAM,WAAW;IACjB,IAAI,SAAS;CACd;AAED,2FAA2F;AAC3F,oBAAY,cAAc;IACxB,EAAE,OAAO;IACT,MAAM,WAAW;CAClB;AAED;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,OAAO,CAAA;AACzC,eAAO,MAAM,oBAAoB,MAAM,CAAA;AACvC,eAAO,MAAM,oBAAoB,IAAI,CAAA;AACrC,eAAO,MAAM,yBAAyB,OAAO,CAAA;AAC7C,eAAO,MAAM,2BAA2B,KAAK,CAAA;AAE7C,6EAA6E;AAC7E,eAAO,MAAM,SAAS,MAAM,CAAA;AAE5B,2CAA2C;AAC3C,oBAAY,iBAAiB;IAC3B,OAAO,YAAY;IACnB,IAAI,SAAS;IACb,MAAM,WAAW;IACjB,4FAA4F;IAC5F,OAAO,YAAY;IACnB;;;;;;OAMG;IACH,OAAO,YAAY;CACpB;AAED,6CAA6C;AAC7C,oBAAY,sBAAsB;IAChC,2EAA2E;IAC3E,SAAS,cAAc;IACvB;;;OAGG;IACH,OAAO,YAAY;IACnB,8EAA8E;IAC9E,MAAM,WAAW;IACjB,0EAA0E;IAC1E,UAAU,eAAe;CAC1B;AAED,4DAA4D;AAC5D,oBAAY,cAAc;IACxB,IAAI,SAAS;IACb,mCAAmC;IACnC,OAAO,YAAY;IACnB,uEAAuE;IACvE,OAAO,YAAY;CACpB;AAED;;;GAGG;AACH,oBAAY,kBAAkB;IAC5B,IAAI,SAAS;IACb,MAAM,WAAW;IACjB,QAAQ,aAAa;IACrB,QAAQ,aAAa;IACrB,IAAI,SAAS;CACd;AAED;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,YAAY,EAAE,WA0F1B,CAAA;AAED,iEAAiE;AACjE,eAAO,MAAM,UAAU,EAAE,WAAW,EAAmB,CAAA"}