@owlmeans/agent 0.1.18-rc.47 → 0.1.18-rc.49

package/src/pipeline/results/types.ts

@@ -0,0 +1,152 @@
+import type { CumulativeResultEntry, CumulativeResultFact, PipelineSpec, PipelineState, ResultFactQuery, ResultViewMode, CumulativeResultsSpec, ResultSummarySpec } from '@owlmeans/agent-common'
+import type { CumulativeResults } from '@owlmeans/llm-common'
+import type { CumulativeResultStore } from '../../stores/types.js'
+import type { PipelineEnterMode, PipelineParentRef } from '../runner/types.js'
+
+/** What a step tells the results plugin about itself. Every call adds to the last. */
+export interface ResultRecordInput {
+  /** Files the step wrote or rewrote, relative to the project root. */
+  files?: string[]
+  /** Facts the step already knows. Taken as they are, ahead of anything an extractor finds. */
+  facts?: CumulativeResultFact[]
+}
+
+/** One entry a step can see, and how its view shows it. */
+export interface VisibleResultEntry {
+  entry: CumulativeResultEntry
+  mode: ResultViewMode
+  /** Left out of the prompt for BUDGET — named in `view.omitted` — rather than by declaration. */
+  dropped?: boolean
+}
+
+/**
+ * The results surface of ONE step: the view to put in its prompt, a query over the facts behind
+ * that view for code that wants them, and the way to report what the step produced.
+ */
+export interface StepResults {
+  /** The ledger the step's entries belong to. */
+  ledger: string
+  /** Where the step sits in the ledger — the order key a run composed under it extends. */
+  order: readonly number[]
+  /** Serializable and frozen; `ExecutionService.withResults(exec, results.view)`. */
+  view: CumulativeResults
+  /** Every entry visible to the step, oldest first, with how the view shows it. */
+  entries: () => readonly VisibleResultEntry[]
+  /**
+   * Facts visible to the step, narrowed by kind, name and producing step — including those the
+   * PROMPT left out for space or by declaration: a budget is about what a model reads, and code
+   * asking for a fact is not a model reading a prompt.
+   */
+  facts: (query?: ResultFactQuery) => CumulativeResultFact[]
+  /** Report files touched and facts known. Read once, when the step finishes. */
+  record: (input: ResultRecordInput) => void
+}
+
+/** What a declaration resolver, a seed and a ledger resolver are told about the run. */
+export interface ResultsRunInfo<S extends PipelineState, C> {
+  pipeline: string
+  spec: PipelineSpec
+  runId: string
+  scope: string
+  entityId?: string
+  deps: C
+  state: Readonly<S>
+  mode: PipelineEnterMode
+  parent?: PipelineParentRef
+}
+
+/** What an extractor reads facts from. */
+export interface ResultExtractInput<S extends PipelineState, C> {
+  pipeline: string
+  runId: string
+  step: string
+  /** Durable: the run's state, restored from its row on a resume. */
+  state: Readonly<S>
+  deps: C
+  /** Every file the entry answers for — its durable scope and whatever its step recorded. */
+  files: readonly string[]
+  /** What was recorded as touched on THIS pass — empty on a rebuild. */
+  changed: readonly string[]
+}
+
+export interface ResultScopeInput<S extends PipelineState, C> extends Omit<
+  ResultExtractInput<S, C>, 'files' | 'changed'
+> {}
+
+/**
+ * Facts from files. DETERMINISTIC — the same inputs give the same facts — and never a model
+ * call: an extractor is what makes a fact a fact, and a rebuild after a crash must find exactly
+ * what the first pass found.
+ */
+export interface ResultExtractFn<S extends PipelineState, C> { (input: ResultExtractInput<S, C>): Promise<CumulativeResultFact[]> | CumulativeResultFact[] }
+
+export interface ResultExtractorSpec<S extends PipelineState, C> {
+  /**
+   * The files this extractor answers for, recomputed from DURABLE inputs — the state's keys, the
+   * file tree — and never from what a step happened to report. It is what a rebuild reads when
+   * nothing was recorded, so a step's facts can be found again after the process that ran it died.
+   */
+  scope?: (input: ResultScopeInput<S, C>) => Promise<string[]> | string[]
+  extract: ResultExtractFn<S, C>
+}
+
+// Kept as a type: a union of the bare function and the spec form.
+export type ResultExtractor<S extends PipelineState, C> =
+  ResultExtractFn<S, C> | ResultExtractorSpec<S, C>
+
+/** Facts known before any step of the run ran. Called on every entry of the run; deterministic. */
+export interface ResultSeed<S extends PipelineState, C> { (run: ResultsRunInfo<S, C>): Promise<CumulativeResultFact[]> | CumulativeResultFact[] }
+
+/** Everything a summarize callback needs, including a ready prompt. */
+export interface ResultSummaryRequest<S extends PipelineState, C> extends ResultSummarySpec {
+  schema: Record<string, unknown>
+  maxChars: number
+  pipeline: string
+  runId: string
+  step: string
+  label: string
+  facts: readonly CumulativeResultFact[]
+  files: readonly string[]
+  state: Readonly<S>
+  deps: C
+  signal: AbortSignal
+  /** The instructions, the step's facts and its files, as one deterministic prompt. */
+  prompt: string
+}
+
+/**
+ * Ask a model for a step's summary; return its schema-shaped answer.
+ *
+ * Typically `request => model.invoke(request.prompt, request.schema, { action })` on a model
+ * resolved for `request.role`. A throw is a warning and the entry goes without a summary.
+ */
+export interface ResultSummarizer<S extends PipelineState, C> { (request: ResultSummaryRequest<S, C>): Promise<unknown> }
+
+export interface CumulativeResultsPluginOptions<S extends PipelineState, C> {
+  alias?: string
+  order?: number
+  /**
+   * The declaration, or a function of the run that returns one — or `null`/`false` to leave THIS
+   * run without results. Resolved once, on `enter`.
+   */
+  spec:
+    | CumulativeResultsSpec
+    | ((run: ResultsRunInfo<S, C>) =>
+      CumulativeResultsSpec | null | false | undefined
+      | Promise<CumulativeResultsSpec | null | false | undefined>)
+  /** Named deterministic extractors, referenced by name from `StepResultsSpec.extractors`. */
+  extractors?: Record<string, ResultExtractor<S, C>>
+  /** Named facts available before any step ran. Visible to every step, in name order. */
+  seeds?: Record<string, ResultSeed<S, C>>
+  /**
+   * Where entries live. A composed pipeline must be given the SAME store as the pipeline it is a
+   * step of, or neither sees what the other produced. Default: an in-process memory store of this
+   * plugin instance.
+   */
+  store?: CumulativeResultStore
+  /** Called only for a step whose declaration has a `summary`. */
+  summarize?: ResultSummarizer<S, C>
+  /** The ledger a run's entries belong to. Default: the parent's, else the root run's id. */
+  ledger?: (run: ResultsRunInfo<S, C>) => string
+  trace?: (line: string) => void
+}

package/src/pipeline/results.ts

@@ -1,12 +1,13 @@
-import { CumulativeResultSource, DEFAULT_RESULT_SUMMARY_CHARS, DEFAULT_RESULTS_MAX_CHARS, DEFAULT_RESULTS_WINDOW, RESULTS_EVERY_STEP, ResultViewMode, compareResultOrder, factKey, orderPipelineSteps, pipelineAncestry, renderResultEntry, renderResultFact, renderResultSummary, resultLabel, rootRunOf, sortFacts, type CumulativeResultEntry, type CumulativeResultFact, type PipelineState, type ResultSummarySpec, type StepResultsSpec } from '@owlmeans/agent-common'
-import { prefixHash } from '@owlmeans/llm'
+import { CumulativeResultSource, DEFAULT_RESULT_SUMMARY_CHARS, DEFAULT_RESULTS_MAX_CHARS, DEFAULT_RESULTS_WINDOW, RESULTS_EVERY_STEP, ResultViewMode, cumulativeResultsHelper, makePipelineSpecModel, type CumulativeResultEntry, type CumulativeResultFact, type PipelineState, type ResultSummarySpec, type StepResultsSpec } from '@owlmeans/agent-common'
+import { promptRenderHelper } from '@owlmeans/llm'
 import { logger } from '@owlmeans/log'
 import type { CumulativeResults } from '@owlmeans/llm-common'
 import { createMemoryCumulativeResultStore } from '../stores/memory.js'
-import type { PipelinePlugin, PipelineRunContext, StepResults, VisibleResultEntry, CumulativeResultsPluginOptions, ResultExtractFn, ResultExtractor, ResultsRunInfo } from './types.js'
+import type { PipelinePlugin, PipelineRunContext } from './runner/types.js'
+import type { StepResults, VisibleResultEntry, CumulativeResultsPluginOptions, ResultExtractFn, ResultExtractor, ResultsRunInfo } from './results/types.js'
 import { SEPARATOR } from './consts.local.js'
 import { CUMULATIVE_RESULTS_PLUGIN, DEFAULT_RESULT_SUMMARY_SCHEMA } from './consts.js'
-import type { EntryParts, Item, Recorded, RunLedger } from './types.local.js'
+import type { EntryParts, Item, Recorded, RunLedger } from './results/types.local.js'
 
 const log = logger('agent:pipeline:results')
 
@@ -28,7 +29,7 @@ const dedupe = (facts: readonly CumulativeResultFact[]): CumulativeResultFact[]
   const seen = new Set<string>()
 
   return facts.filter(fact => {
-    const key = factKey(fact)
+    const key = cumulativeResultsHelper.factKey(fact)
     if (seen.has(key)) {
       return false
     }
@@ -71,7 +72,7 @@ const summaryPrompt = (
   `The step "${label}" has just finished. For the later steps of the same work, summarize what it `
   + 'decided or produced that the facts below do not already say. Do not repeat the facts and do not '
   + `guess at anything not shown. At most ${maxChars} characters.`,
-  `# Facts read from the files after the step finished\n${facts.map(renderResultFact).join('\n') || '(none)'}`,
+  `# Facts read from the files after the step finished\n${facts.map(cumulativeResultsHelper.renderResultFact).join('\n') || '(none)'}`,
   `# Files the step answers for\n${files.map(file => `- ${file}`).join('\n') || '(none)'}`,
 ].join(SEPARATOR)
 
@@ -187,7 +188,7 @@ export const cumulativeResultsPlugin = <S extends PipelineState, C>(
    * necessarily run, so what it says cannot be what a step relies on.
    */
   const visibleTo = (run: RunLedger<C>, step: string): Item[] => {
-    const depths = new Map(pipelineAncestry(run.spec, step).map(({ step: name, depth }) => [name, depth]))
+    const depths = new Map(makePipelineSpecModel(run.spec).ancestry(step).map(({ step: name, depth }) => [name, depth]))
     const items: Item[] = [
       ...run.upstream.map(visible => ({
         entry: visible.entry, mode: visible.mode, explicit: false, dropped: visible.dropped === true,
@@ -203,7 +204,7 @@ export const cumulativeResultsPlugin = <S extends PipelineState, C>(
     }
 
     return items.sort((a, b) =>
-      compareResultOrder(a.entry.order, b.entry.order) || compare(a.entry.label, b.entry.label))
+      cumulativeResultsHelper.compareResultOrder(a.entry.order, b.entry.order) || compare(a.entry.label, b.entry.label))
   }
 
   const textOf = (item: Item): string =>
@@ -250,11 +251,11 @@ export const cumulativeResultsPlugin = <S extends PipelineState, C>(
       .map(item => item.entry.label)
     const joined = sections.map(section => section.text).join(SEPARATOR)
     const view: CumulativeResults = Object.freeze({
-      step: resultLabel(run.ledger, run.runId, step),
+      step: cumulativeResultsHelper.resultLabel(run.ledger, run.runId, step),
       sections: Object.freeze(sections) as CumulativeResults['sections'],
       omitted: Object.freeze(omitted) as string[],
       chars: joined.length,
-      digest: prefixHash(`${joined}\u0000${omitted.join('\u0000')}`),
+      digest: promptRenderHelper.prefixHash(`${joined}\u0000${omitted.join('\u0000')}`),
     })
     const visible: readonly VisibleResultEntry[] = Object.freeze(items.map(item => Object.freeze({
       entry: item.entry, mode: item.mode, ...(item.dropped ? { dropped: true } : {}),
@@ -347,18 +348,18 @@ export const cumulativeResultsPlugin = <S extends PipelineState, C>(
     const owned = new Set<string>()
     for (const item of visibleTo(run, step)) {
       for (const fact of item.entry.facts) {
-        owned.add(factKey(fact))
+        owned.add(cumulativeResultsHelper.factKey(fact))
       }
     }
     for (const entry of run.entries.values()) {
       if (entry.runId.startsWith(`${run.runId}/${step}`) && anchorOf(run, entry) === step) {
         for (const fact of entry.facts) {
-          owned.add(factKey(fact))
+          owned.add(cumulativeResultsHelper.factKey(fact))
         }
       }
     }
 
-    return facts.filter(fact => !owned.has(factKey(fact)))
+    return facts.filter(fact => !owned.has(cumulativeResultsHelper.factKey(fact)))
   }
 
   /** A step's facts and files, from its durable scope, what it recorded, and its extractors. */
@@ -374,12 +375,12 @@ export const cumulativeResultsPlugin = <S extends PipelineState, C>(
 
   const compose = (run: RunLedger<C>, step: string, parts: EntryParts): CumulativeResultEntry => {
     const previous = run.entries.get(keyOf(run.runId, step))
-    const label = resultLabel(run.ledger, run.runId, step)
+    const label = cumulativeResultsHelper.resultLabel(run.ledger, run.runId, step)
     const source = parts.facts.length === 0 && parts.summary != null
       ? CumulativeResultSource.Summarized
       : parts.source
-    const facts = sortFacts(parts.facts)
-    const rendered = renderResultEntry(
+    const facts = cumulativeResultsHelper.sortFacts(parts.facts)
+    const rendered = cumulativeResultsHelper.renderResultEntry(
       { label, source, facts, ...(parts.partial === true ? { partial: true } : {}), ...(parts.summary != null ? { summary: parts.summary } : {}) },
       {
         maxChars: parts.spec?.maxChars ?? run.results.maxEntryChars,
@@ -424,8 +425,8 @@ export const cumulativeResultsPlugin = <S extends PipelineState, C>(
     const mine = orderOf(run, step)
     const earlier = [...run.entries.values()]
       .filter(entry => entry.runId === run.runId && entry.step !== step
-        && compareResultOrder(entry.order, mine) < 0)
-      .sort((a, b) => compareResultOrder(a.order, b.order))
+        && cumulativeResultsHelper.compareResultOrder(entry.order, mine) < 0)
+      .sort((a, b) => cumulativeResultsHelper.compareResultOrder(a.order, b.order))
 
     for (const entry of earlier) {
       const spec = run.results.steps?.[entry.step]
@@ -437,8 +438,8 @@ export const cumulativeResultsPlugin = <S extends PipelineState, C>(
         continue
       }
       const fresh = await extract(run, entry.step, state, entry.files, overlap)
-      const freshKeys = new Set(fresh.map(factKey))
-      const kept = entry.facts.filter(fact => !freshKeys.has(factKey(fact))
+      const freshKeys = new Set(fresh.map(cumulativeResultsHelper.factKey))
+      const kept = entry.facts.filter(fact => !freshKeys.has(cumulativeResultsHelper.factKey(fact))
         && (fact.path == null || !overlap.includes(normalizePath(fact.path))))
       const facts = unowned(run, entry.step, dedupe([...fresh, ...kept]))
       const refreshed = compose(run, entry.step, {
@@ -466,7 +467,7 @@ export const cumulativeResultsPlugin = <S extends PipelineState, C>(
       return undefined
     }
     const maxChars = spec.maxChars ?? DEFAULT_RESULT_SUMMARY_CHARS
-    const label = resultLabel(run.ledger, run.runId, step)
+    const label = cumulativeResultsHelper.resultLabel(run.ledger, run.runId, step)
     try {
       const answer = await options.summarize({
         ...spec,
@@ -483,7 +484,7 @@ export const cumulativeResultsPlugin = <S extends PipelineState, C>(
         signal: ctx.signal,
         prompt: summaryPrompt(spec, label, facts, files, maxChars),
       })
-      const text = renderResultSummary(answer, maxChars)
+      const text = cumulativeResultsHelper.renderResultSummary(answer, maxChars)
 
       return text !== '' ? text : undefined
     } catch (e) {
@@ -516,14 +517,14 @@ export const cumulativeResultsPlugin = <S extends PipelineState, C>(
       }
 
       const parent = event.parent?.results
-      const ledger = options.ledger?.(info) ?? parent?.ledger ?? rootRunOf(event.runId)
+      const ledger = options.ledger?.(info) ?? parent?.ledger ?? cumulativeResultsHelper.rootRunOf(event.runId)
       const run: RunLedger<C> = {
         results: declared,
         spec: event.spec,
         runId: event.runId,
         ledger,
         trail: parent != null ? [...parent.order] : [],
-        index: new Map(orderPipelineSteps(event.spec).map((step, at) => [step, at + 1])),
+        index: new Map(makePipelineSpecModel(event.spec).orderSteps().map((step, at) => [step, at + 1])),
         entries: new Map(),
         upstream: parent != null ? parent.entries() : [],
         seeds: [],

package/src/pipeline/runner/types.local.ts

@@ -0,0 +1,21 @@
+import type { BaseCheckpointSaver } from '@langchain/langgraph'
+
+/**
+ * The graph builder, seen loosely.
+ *
+ * `StateGraph`'s node names are a generic parameter that only a literal-typed builder chain can
+ * satisfy, and a pipeline's nodes come from data. The precision belongs at THIS package's public
+ * boundary — `PipelineSpec`, `PipelineStep`, `PipelineModel` are all exact — not in the three lines
+ * that hand LangGraph a name it will look up in a map either way.
+ */
+export interface LooseGraph {
+  addNode: (
+    name: string,
+    fn: (state: unknown) => Promise<Record<string, unknown>>,
+    options?: Record<string, unknown>,
+  ) => LooseGraph
+  addEdge: (start: string | string[], end: string) => LooseGraph
+  compile: (options?: { checkpointer?: BaseCheckpointSaver }) => {
+    invoke: (input: unknown, config?: Record<string, unknown>) => Promise<unknown>
+  }
+}

package/src/pipeline/{types.ts → runner/types.ts}

@@ -1,7 +1,8 @@
 import type { BaseCheckpointSaver } from '@langchain/langgraph'
-import type { CumulativeResultEntry, CumulativeResultFact, PipelineProgress, PipelineRun, PipelineRunInquiry, PipelineRunStatus, PipelineSpec, PipelineState, ResultFactQuery, ResultViewMode, CumulativeResultsSpec, ResultSummarySpec } from '@owlmeans/agent-common'
-import type { CumulativeResults, Inquiry, InquiryAnswer } from '@owlmeans/llm-common'
-import type { PipelineRunStore, CumulativeResultStore } from '../stores/types.js'
+import type { PipelineProgress, PipelineRun, PipelineRunInquiry, PipelineRunStatus, PipelineSpec, PipelineState } from '@owlmeans/agent-common'
+import type { Inquiry, InquiryAnswer } from '@owlmeans/llm-common'
+import type { PipelineRunStore } from '../../stores/types.js'
+import type { StepResults } from '../results/types.js'
 
 /**
  * What a step is handed while it runs.
@@ -72,45 +73,6 @@ export interface PipelineRunContext<S extends PipelineState, C> {
   results?: StepResults
 }
 
-/** What a step tells the results plugin about itself. Every call adds to the last. */
-export interface ResultRecordInput {
-  /** Files the step wrote or rewrote, relative to the project root. */
-  files?: string[]
-  /** Facts the step already knows. Taken as they are, ahead of anything an extractor finds. */
-  facts?: CumulativeResultFact[]
-}
-
-/** One entry a step can see, and how its view shows it. */
-export interface VisibleResultEntry {
-  entry: CumulativeResultEntry
-  mode: ResultViewMode
-  /** Left out of the prompt for BUDGET — named in `view.omitted` — rather than by declaration. */
-  dropped?: boolean
-}
-
-/**
- * The results surface of ONE step: the view to put in its prompt, a query over the facts behind
- * that view for code that wants them, and the way to report what the step produced.
- */
-export interface StepResults {
-  /** The ledger the step's entries belong to. */
-  ledger: string
-  /** Where the step sits in the ledger — the order key a run composed under it extends. */
-  order: readonly number[]
-  /** Serializable and frozen; `ExecutionService.withResults(exec, results.view)`. */
-  view: CumulativeResults
-  /** Every entry visible to the step, oldest first, with how the view shows it. */
-  entries: () => readonly VisibleResultEntry[]
-  /**
-   * Facts visible to the step, narrowed by kind, name and producing step — including those the
-   * PROMPT left out for space or by declaration: a budget is about what a model reads, and code
-   * asking for a fact is not a model reading a prompt.
-   */
-  facts: (query?: ResultFactQuery) => CumulativeResultFact[]
-  /** Report files touched and facts known. Read once, when the step finishes. */
-  record: (input: ResultRecordInput) => void
-}
-
 /**
  * The composing step of a parent pipeline, as a run composed under it (`asStep`) sees it —
  * read-only by construction: a composed run may learn where it sits, never write its parent.
@@ -350,117 +312,3 @@ export interface PipelineModel<S extends PipelineState, C> {
     step: string, mapping: PipelineStepMapping<S, PS>
   ) => PipelineStep<PS, C>
 }
-
-/** What a declaration resolver, a seed and a ledger resolver are told about the run. */
-export interface ResultsRunInfo<S extends PipelineState, C> {
-  pipeline: string
-  spec: PipelineSpec
-  runId: string
-  scope: string
-  entityId?: string
-  deps: C
-  state: Readonly<S>
-  mode: PipelineEnterMode
-  parent?: PipelineParentRef
-}
-
-/** What an extractor reads facts from. */
-export interface ResultExtractInput<S extends PipelineState, C> {
-  pipeline: string
-  runId: string
-  step: string
-  /** Durable: the run's state, restored from its row on a resume. */
-  state: Readonly<S>
-  deps: C
-  /** Every file the entry answers for — its durable scope and whatever its step recorded. */
-  files: readonly string[]
-  /** What was recorded as touched on THIS pass — empty on a rebuild. */
-  changed: readonly string[]
-}
-
-export type ResultScopeInput<S extends PipelineState, C> = Omit<
-  ResultExtractInput<S, C>, 'files' | 'changed'
->
-
-/**
- * Facts from files. DETERMINISTIC — the same inputs give the same facts — and never a model
- * call: an extractor is what makes a fact a fact, and a rebuild after a crash must find exactly
- * what the first pass found.
- */
-export type ResultExtractFn<S extends PipelineState, C> = (
-  input: ResultExtractInput<S, C>,
-) => Promise<CumulativeResultFact[]> | CumulativeResultFact[]
-
-export interface ResultExtractorSpec<S extends PipelineState, C> {
-  /**
-   * The files this extractor answers for, recomputed from DURABLE inputs — the state's keys, the
-   * file tree — and never from what a step happened to report. It is what a rebuild reads when
-   * nothing was recorded, so a step's facts can be found again after the process that ran it died.
-   */
-  scope?: (input: ResultScopeInput<S, C>) => Promise<string[]> | string[]
-  extract: ResultExtractFn<S, C>
-}
-
-export type ResultExtractor<S extends PipelineState, C> =
-  ResultExtractFn<S, C> | ResultExtractorSpec<S, C>
-
-/** Facts known before any step of the run ran. Called on every entry of the run; deterministic. */
-export type ResultSeed<S extends PipelineState, C> = (
-  run: ResultsRunInfo<S, C>,
-) => Promise<CumulativeResultFact[]> | CumulativeResultFact[]
-
-/** Everything a summarize callback needs, including a ready prompt. */
-export interface ResultSummaryRequest<S extends PipelineState, C> extends ResultSummarySpec {
-  schema: Record<string, unknown>
-  maxChars: number
-  pipeline: string
-  runId: string
-  step: string
-  label: string
-  facts: readonly CumulativeResultFact[]
-  files: readonly string[]
-  state: Readonly<S>
-  deps: C
-  signal: AbortSignal
-  /** The instructions, the step's facts and its files, as one deterministic prompt. */
-  prompt: string
-}
-
-/**
- * Ask a model for a step's summary; return its schema-shaped answer.
- *
- * Typically `request => model.invoke(request.prompt, request.schema, { action })` on a model
- * resolved for `request.role`. A throw is a warning and the entry goes without a summary.
- */
-export type ResultSummarizer<S extends PipelineState, C> = (
-  request: ResultSummaryRequest<S, C>,
-) => Promise<unknown>
-
-export interface CumulativeResultsPluginOptions<S extends PipelineState, C> {
-  alias?: string
-  order?: number
-  /**
-   * The declaration, or a function of the run that returns one — or `null`/`false` to leave THIS
-   * run without results. Resolved once, on `enter`.
-   */
-  spec:
-    | CumulativeResultsSpec
-    | ((run: ResultsRunInfo<S, C>) =>
-      CumulativeResultsSpec | null | false | undefined
-      | Promise<CumulativeResultsSpec | null | false | undefined>)
-  /** Named deterministic extractors, referenced by name from `StepResultsSpec.extractors`. */
-  extractors?: Record<string, ResultExtractor<S, C>>
-  /** Named facts available before any step ran. Visible to every step, in name order. */
-  seeds?: Record<string, ResultSeed<S, C>>
-  /**
-   * Where entries live. A composed pipeline must be given the SAME store as the pipeline it is a
-   * step of, or neither sees what the other produced. Default: an in-process memory store of this
-   * plugin instance.
-   */
-  store?: CumulativeResultStore
-  /** Called only for a step whose declaration has a `summary`. */
-  summarize?: ResultSummarizer<S, C>
-  /** The ledger a run's entries belong to. Default: the parent's, else the root run's id. */
-  ledger?: (run: ResultsRunInfo<S, C>) => string
-  trace?: (line: string) => void
-}

package/src/pipeline/runner.ts

@@ -1,14 +1,15 @@
 import { Annotation, END, START, StateGraph } from '@langchain/langgraph'
-import { AgentRunStateError, DEFAULT_MAX_STATE_CHARS, INQUIRY_ANSWERS_KEY, PipelineNotIdempotentError, PipelineNotResumableError, PipelineRunStatus, PipelineSpecError, PipelineStateTooLargeError, PipelineVersionError, orderPipelineSteps, pipelineDescendants, pipelineStep, validatePipelineSpec, type PipelineProgress, type PipelineRun, type PipelineRunInquiry, type PipelineSpec, type PipelineState, type PipelineStepSpec } from '@owlmeans/agent-common'
-import { DEFAULT_INQUIRY_ANSWER_CHARS, capAnswer, stateAnswerOf, type InquiryAnswer } from '@owlmeans/llm-common'
+import { AgentRunStateError, DEFAULT_MAX_STATE_CHARS, INQUIRY_ANSWERS_KEY, PipelineNotIdempotentError, PipelineNotResumableError, PipelineRunStatus, PipelineSpecError, PipelineStateTooLargeError, PipelineVersionError, type PipelineProgress, type PipelineRun, type PipelineRunInquiry, type PipelineSpec, type PipelineState, type PipelineStepSpec, makePipelineSpecModel } from '@owlmeans/agent-common'
+import { DEFAULT_INQUIRY_ANSWER_CHARS, type InquiryAnswer, inquiryHelper } from '@owlmeans/llm-common'
 import { logger } from '@owlmeans/log'
 import type {
   PipelineEnterMode, PipelineInvokeArgs, PipelineModel, PipelineOptions, PipelineParentRef,
   PipelinePlugin, PipelineResult, PipelineRunContext, PipelineStep, PipelineStepContribution,
-  PipelineStepMapping, StepResults,
-} from './types.js'
+  PipelineStepMapping,
+} from './runner/types.js'
+import type { StepResults } from './results/types.js'
 import { DEFAULT_PIPELINE_PLUGIN_ORDER, MAX_INQUIRY_ROUNDS } from './consts.local.js'
-import type { LooseGraph } from './types.local.js'
+import type { LooseGraph } from './runner/types.local.js'
 
 const log = logger('agent:pipeline')
 
@@ -78,7 +79,8 @@ const answersIn = (state: unknown, key: string): Record<string, InquiryAnswer> =
 export const makePipeline = <S extends PipelineState, C>(
   spec: PipelineSpec, options: PipelineOptions<S, C>,
 ): PipelineModel<S, C> => {
-  validatePipelineSpec(spec)
+  const specModel = makePipelineSpecModel(spec)
+  specModel.validate()
 
   const handlers = new Map<string, PipelineStep<S, C>>()
   const faults: string[] = []
@@ -100,7 +102,7 @@ export const makePipeline = <S extends PipelineState, C>(
     throw new PipelineSpecError(`${spec.alias}: ${faults.join('; ')}`)
   }
 
-  const order = orderPipelineSteps(spec)
+  const order = specModel.orderSteps()
   const total = order.length
   const runs = options.runs
   const maxStateChars = options.maxStateChars ?? DEFAULT_MAX_STATE_CHARS
@@ -145,7 +147,7 @@ export const makePipeline = <S extends PipelineState, C>(
 
   /** The copy of an answer this pipeline's STATE is allowed to hold. */
   const forState = (answer: InquiryAnswer): InquiryAnswer =>
-    stateAnswerOf(capAnswer(answer, maxAnswerChars))
+    inquiryHelper.stateAnswerOf(inquiryHelper.capAnswer(answer, maxAnswerChars))
 
   /**
    * Fold every source of answers into the live state, later sources winning per id.
@@ -321,7 +323,7 @@ export const makePipeline = <S extends PipelineState, C>(
             : null
 
           if (answer != null) {
-            const capped = capAnswer({ ...answer, inquiryId: inquiry.id }, maxAnswerChars)
+            const capped = inquiryHelper.capAnswer({ ...answer, inquiryId: inquiry.id }, maxAnswerChars)
             // The state keeps the DECISION and a short excerpt of any prose; the step is handed the
             // whole answer. A state is scalars and keys, and two long answers would spend a
             // pipeline's whole state budget on text nothing replays from.
@@ -333,7 +335,7 @@ export const makePipeline = <S extends PipelineState, C>(
             // person has already answered to be asked again on the next entry.
             await ctx.mark({
               [answersKey]: {
-                ...answersIn(live, answersKey), [inquiry.id]: stateAnswerOf(capped),
+                ...answersIn(live, answersKey), [inquiry.id]: inquiryHelper.stateAnswerOf(capped),
               },
             } as Partial<S>)
 
@@ -765,9 +767,9 @@ export const makePipeline = <S extends PipelineState, C>(
 
       let completed = [...existing.completed]
       if (args.from != null) {
-        const rerun = pipelineDescendants(spec, args.from)
+        const rerun = specModel.descendants(args.from)
         const blocked = rerun.filter(step =>
-          completed.includes(step) && pipelineStep(spec, step)?.nonIdempotent === true)
+          completed.includes(step) && specModel.stepOf(step)?.nonIdempotent === true)
         if (blocked.length > 0 && args.force !== true) {
           throw new PipelineNotIdempotentError(`${runId}:${blocked.join(',')}`)
         }

package/src/plugins/export.ts

@@ -4,11 +4,11 @@ export { summarizePlugin } from './summarize.js'
 export { SUMMARIZE_PLUGIN } from './consts.js'
 export type { SummarizeOptions } from './types.js'
 
-export { memoryGraph, memoryGraphPlugin } from './memory-graph.js'
+export { makeMemoryGraphApi, memoryGraph, memoryGraphPlugin } from './memory-graph.js'
 export { DEFAULT_FOLLOW, MEMORY_GRAPH_PLUGIN } from './consts.js'
 export type { MemoryGraphApi, MemoryGraphOptions } from './types.js'
 
-export { memoryEvents, memoryEventsPlugin } from './memory-events.js'
+export { makeMemoryEventsApi, memoryEvents, memoryEventsPlugin } from './memory-events.js'
 export { DEFAULT_MEMORY_EVENT_CHARS, MEMORY_EVENTS_PLUGIN } from './consts.js'
 export type { MemoryEventsApi, MemoryEventsOptions } from './types.js'
 

package/src/plugins/inquiry.ts

@@ -1,12 +1,12 @@
 import { tool } from '@langchain/core/tools'
 import { IdStyle, createIdOfLength } from '@owlmeans/basic-ids'
-import { DEFAULT_INQUIRY_OPTIONS, InquiryKind, capAnswer, type Inquiry } from '@owlmeans/llm-common'
+import { DEFAULT_INQUIRY_OPTIONS, InquiryKind, type Inquiry, inquiryHelper } from '@owlmeans/llm-common'
 import { InquiryDeclined, InquiryUnavailable } from '@owlmeans/llm'
-import { toErrorResponse } from '../helpers/tools.js'
 import type { AgentPlugin, AgentToolSet } from '../types.js'
 import { ASK_USER_TOOL, INQUIRY_PLUGIN } from './consts.js'
 import type { AskUserArgs } from './types.local.js'
 import type { InquiryPluginOptions } from './types.js'
+import { toolHelper } from '../helpers/tools.js'
 
 
 /**
@@ -78,7 +78,7 @@ export const inquiryPlugin = (options: InquiryPluginOptions = {}): AgentPlugin =
                 }
               }
 
-              return JSON.stringify(capAnswer(answer, options.maxAnswerChars))
+              return JSON.stringify(inquiryHelper.capAnswer(answer, options.maxAnswerChars))
             } catch (e) {
               if (e instanceof InquiryUnavailable) {
                 // The one throw. A channel that has gone cannot be argued with, and containing it
@@ -91,7 +91,7 @@ export const inquiryPlugin = (options: InquiryPluginOptions = {}): AgentPlugin =
                 }
               }
 
-              return toErrorResponse(e)
+              return toolHelper.toErrorResponse(e)
             }
           },
           {

package/src/plugins/memory-events.ts

@@ -16,7 +16,7 @@ import type { MemoryEventsApi, MemoryEventsOptions } from './types.js'
  * The bound is per scope, and pruning is per scope, so a busy subject cannot evict a quiet one's
  * whole history.
  */
-export const memoryEvents = (
+export const makeMemoryEventsApi = (
   store: MemoryEventStore,
   options: Pick<MemoryEventsOptions, 'limit' | 'maxEventChars'> = {},
 ): MemoryEventsApi => {
@@ -35,7 +35,7 @@ export const memoryEvents = (
 export const memoryEventsPlugin = (options: MemoryEventsOptions = {}): AgentPlugin => {
   const { store, window = DEFAULT_EVENT_WINDOW, tools: withTools = true } = options
   const scopeOf = (run: AgentRun): string => options.scope?.(run) ?? run.conversation.scope
-  const api = (): MemoryEventsApi | null => store == null ? null : memoryEvents(store, options)
+  const api = (): MemoryEventsApi | null => store == null ? null : makeMemoryEventsApi(store, options)
 
   return {
     alias: MEMORY_EVENTS_PLUGIN,
@@ -105,3 +105,9 @@ export const memoryEventsPlugin = (options: MemoryEventsOptions = {}): AgentPlug
     },
   }
 }
+
+/** @deprecated compat:factory-refactor — use `makeMemoryEventsApi(…)` */
+export const memoryEvents = (
+  store: MemoryEventStore,
+  options: Pick<MemoryEventsOptions, 'limit' | 'maxEventChars'> = {},
+): MemoryEventsApi => makeMemoryEventsApi(store, options)