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

package/src/results.ts

@@ -1,315 +1,270 @@
 import { DEFAULT_RESULT_COMPACT_CHARS, DEFAULT_RESULT_ENTRY_CHARS, DEFAULT_RESULT_SUMMARY_CHARS, RESULTS_EVERY_STEP, CumulativeFactKind, CumulativeResultSource } from './consts.js'
-import { truncateAt } from './helpers/conversation.js'
+import { truncateAt } from './helpers/truncate.js'
 import { NAMES_ONLY, NOT_VERIFIED, PARTIAL_EMPTY, PARTIAL_WITH_FACTS, SEEDED, SUMMARY_ALONE, SUMMARY_LEFT_OUT, SUMMARY_WITH_FACTS } from './consts.local.js'
-import type { CumulativeResultFact, CumulativeResultsSpec, RenderableResultEntry, ResultRenderCaps, StepResultsSpec } from './types.js'
-
-/**
- * CUMULATIVE PIPELINE RESULTS — the contracts.
- *
- * After a step of a pipeline finishes, code reads what it produced — a type's shape, a file, an
- * endpoint's method, path and parameters, a resource's table — into a small list of FACTS, and the
- * later steps are told those facts instead of re-deriving them from the files. A later step that is
- * handed the authoritative names does not invent a second spelling of them, and that is the whole
- * point: it removes the class of errors that live BETWEEN steps.
- *
- * Everything here is data and pure functions. The runtime that extracts, stores and cuts the views
- * is `@owlmeans/agent`'s `cumulativeResultsPlugin`; the prompt block it lands in is
- * `@owlmeans/llm`'s. A backend or a browser bundle reads an entry without either.
- */
-
-const compare = (a: string, b: string): number => a < b ? -1 : a > b ? 1 : 0
-
-const oneLine = (text: string): string => text.replace(/\s+/g, ' ').trim()
-
-/**
- * The identity of a fact inside a ledger: what it is, what it is called and where it comes from.
- * Two facts with one key are one fact, owned by whichever entry produced it first.
- */
-export const factKey = (fact: CumulativeResultFact): string =>
-  `${fact.kind}\u0000${fact.name}\u0000${fact.specifier ?? fact.path ?? ''}`
-
-/** File facts last — a location is the first thing a budget can spare, a shape the last. */
-const kindRank = (kind: string): number => kind === CumulativeFactKind.File ? 1 : 0
-
-/**
- * Facts in the one order they are ever rendered in: by kind (file facts last), name and location,
- * with a code-unit comparison so every host sorts them alike.
- */
-export const sortFacts = (facts: readonly CumulativeResultFact[]): CumulativeResultFact[] =>
-  [...facts].sort((a, b) =>
-    kindRank(a.kind) - kindRank(b.kind)
-    || compare(a.kind, b.kind)
-    || compare(a.name, b.name)
-    || compare(a.specifier ?? a.path ?? '', b.specifier ?? b.path ?? ''))
-
-/** One fact as one prompt line: kind and name, shape, scalars, pointer, and where it comes from. */
-export const renderResultFact = (fact: CumulativeResultFact): string => {
-  let line = `- ${fact.kind} \`${oneLine(fact.name)}\``
-  const shape = fact.signature != null && fact.signature.trim() !== ''
-    ? oneLine(fact.signature)
-    : fact.members != null && fact.members.length > 0
-      ? `{ ${fact.members.map(oneLine).join(', ')} }`
-      : ''
-  if (shape !== '') {
-    line += `: ${shape}`
-  }
-  const attrs = Object.keys(fact.attrs ?? {}).sort(compare)
-    .map(key => `${key}: ${oneLine(fact.attrs![key]!)}`)
-  if (attrs.length > 0) {
-    line += ` (${attrs.join(', ')})`
-  }
-  if (fact.ref != null && fact.ref !== '') {
-    line += ` → \`${oneLine(fact.ref)}\``
-  }
-  if (fact.specifier != null && fact.specifier !== '') {
-    line += ` — import from \`${fact.specifier}\``
-  }
-  if (fact.path != null && fact.path !== '' && fact.path !== fact.name) {
-    line += fact.specifier != null && fact.specifier !== ''
-      ? ` (file \`${fact.path}\`)`
-      : ` — file \`${fact.path}\``
-  }
-
-  return line
-}
-
+import type {
+  CumulativeResultFact, CumulativeResultsHelper, CumulativeResultsSpec, RenderableResultEntry, RenderedResultEntry,
+  ResultRenderCaps, StepResultsSpec,
+} from './results/types.js'
+
+export const createCumulativeResultsHelper = (): CumulativeResultsHelper => {
+  const compare = (a: string, b: string): number => a < b ? -1 : a > b ? 1 : 0
+
+  const oneLine = (text: string): string => text.replace(/\s+/g, ' ').trim()
+
+  const factKey = (fact: CumulativeResultFact): string =>
+    `${fact.kind}\u0000${fact.name}\u0000${fact.specifier ?? fact.path ?? ''}`
+
+  /** File facts last — a location is the first thing a budget can spare, a shape the last. */
+  const kindRank = (kind: string): number => kind === CumulativeFactKind.File ? 1 : 0
+
+  const sortFacts = (facts: readonly CumulativeResultFact[]): CumulativeResultFact[] =>
+    [...facts].sort((a, b) =>
+      kindRank(a.kind) - kindRank(b.kind)
+      || compare(a.kind, b.kind)
+      || compare(a.name, b.name)
+      || compare(a.specifier ?? a.path ?? '', b.specifier ?? b.path ?? ''))
+
+  const renderResultFact = (fact: CumulativeResultFact): string => {
+    let line = `- ${fact.kind} \`${oneLine(fact.name)}\``
+    const shape = fact.signature != null && fact.signature.trim() !== ''
+      ? oneLine(fact.signature)
+      : fact.members != null && fact.members.length > 0
+        ? `{ ${fact.members.map(oneLine).join(', ')} }`
+        : ''
+    if (shape !== '') {
+      line += `: ${shape}`
+    }
+    const attrs = Object.keys(fact.attrs ?? {}).sort(compare)
+      .map(key => `${key}: ${oneLine(fact.attrs![key]!)}`)
+    if (attrs.length > 0) {
+      line += ` (${attrs.join(', ')})`
+    }
+    if (fact.ref != null && fact.ref !== '') {
+      line += ` → \`${oneLine(fact.ref)}\``
+    }
+    if (fact.specifier != null && fact.specifier !== '') {
+      line += ` — import from \`${fact.specifier}\``
+    }
+    if (fact.path != null && fact.path !== '' && fact.path !== fact.name) {
+      line += fact.specifier != null && fact.specifier !== ''
+        ? ` (file \`${fact.path}\`)`
+        : ` — file \`${fact.path}\``
+    }
 
-const moreFacts = (count: number): string =>
-  `- … and ${count} more not listed here for space. They exist: check the files before creating anything similar.`
+    return line
+  }
 
-const moreNames = (count: number): string => `- … and ${count} more`
+  const moreFacts = (count: number): string =>
+    `- … and ${count} more not listed here for space. They exist: check the files before creating anything similar.`
 
-const heading = (entry: RenderableResultEntry, compact: boolean): string => {
-  const notes: string[] = []
-  const hasFacts = entry.facts.length > 0
-  if (entry.partial === true) {
-    notes.push(hasFacts ? PARTIAL_WITH_FACTS : PARTIAL_EMPTY)
-  }
-  if (entry.source === CumulativeResultSource.Seeded) {
-    notes.push(SEEDED)
-  }
-  if (!hasFacts && entry.summary != null) {
-    notes.push(NOT_VERIFIED)
-  }
-  if (compact && (hasFacts || entry.summary != null)) {
-    notes.push(hasFacts ? NAMES_ONLY : SUMMARY_LEFT_OUT)
-  }
+  const moreNames = (count: number): string => `- … and ${count} more`
 
-  return `### ${entry.label}${notes.length > 0 ? ` (${notes.join('; ')})` : ''}`
-}
+  const heading = (entry: RenderableResultEntry, compact: boolean): string => {
+    const notes: string[] = []
+    const hasFacts = entry.facts.length > 0
+    if (entry.partial === true) {
+      notes.push(hasFacts ? PARTIAL_WITH_FACTS : PARTIAL_EMPTY)
+    }
+    if (entry.source === CumulativeResultSource.Seeded) {
+      notes.push(SEEDED)
+    }
+    if (!hasFacts && entry.summary != null) {
+      notes.push(NOT_VERIFIED)
+    }
+    if (compact && (hasFacts || entry.summary != null)) {
+      notes.push(hasFacts ? NAMES_ONLY : SUMMARY_LEFT_OUT)
+    }
 
-/** Lines under `head`, as many as fit in `max`, with `more(n)` saying how many did not. */
-const fit = (
-  head: string[], lines: string[], tail: string[], max: number, more: (count: number) => string,
-): string => {
-  const total = (parts: string[]): number => parts.join('\n').length
-  if (total([...head, ...lines, ...tail]) <= max) {
-    return [...head, ...lines, ...tail].join('\n')
+    return `### ${entry.label}${notes.length > 0 ? ` (${notes.join('; ')})` : ''}`
   }
 
-  // Room for the "more" line is reserved at its widest, so adding it can never break the cap.
-  const reserve = more(lines.length).length + 1
-  const kept: string[] = []
-  for (const line of lines) {
-    if (total([...head, ...kept, line, ...tail]) + reserve > max) {
-      break
+  /** Lines under `head`, as many as fit in `max`, with `more(n)` saying how many did not. */
+  const fit = (
+    head: string[], lines: string[], tail: string[], max: number, more: (count: number) => string,
+  ): string => {
+    const total = (parts: string[]): number => parts.join('\n').length
+    if (total([...head, ...lines, ...tail]) <= max) {
+      return [...head, ...lines, ...tail].join('\n')
     }
-    kept.push(line)
-  }
 
-  return [...head, ...kept, more(lines.length - kept.length), ...tail].join('\n')
-}
+    // Room for the "more" line is reserved at its widest, so adding it can never break the cap.
+    const reserve = more(lines.length).length + 1
+    const kept: string[] = []
+    for (const line of lines) {
+      if (total([...head, ...kept, line, ...tail]) + reserve > max) {
+        break
+      }
+      kept.push(line)
+    }
 
-/**
- * An entry's two renderings — in full, and as names only — or two empty strings when it has
- * nothing to say.
- *
- * Deterministic and free of anything that varies between two renderings of the same facts: no
- * timestamp, no run id, no revision. Over its cap an entry DROPS whole facts, in render order, and
- * says how many it dropped; it never cuts one fact's line, because half a signature is a wrong
- * signature. An empty entry that is not partial renders to nothing, so it costs a view nothing.
- */
-export const renderResultEntry = (
-  entry: RenderableResultEntry, caps: ResultRenderCaps = {},
-): { full: string, compact: string } => {
-  const maxChars = caps.maxChars ?? DEFAULT_RESULT_ENTRY_CHARS
-  const maxCompactChars = caps.maxCompactChars ?? DEFAULT_RESULT_COMPACT_CHARS
-  const facts = sortFacts(entry.facts)
-  if (facts.length === 0 && entry.summary == null && entry.partial !== true) {
-    return { full: '', compact: '' }
+    return [...head, ...kept, more(lines.length - kept.length), ...tail].join('\n')
   }
 
-  const summary = entry.summary != null && entry.summary.trim() !== ''
-    ? [`${facts.length > 0 ? SUMMARY_WITH_FACTS : SUMMARY_ALONE} ${oneLine(entry.summary)}`]
-    : []
-  const full = fit([heading(entry, false)], facts.map(renderResultFact), summary, maxChars, moreFacts)
+  const renderResultEntry = (
+    entry: RenderableResultEntry, caps: ResultRenderCaps = {},
+  ): RenderedResultEntry => {
+    const maxChars = caps.maxChars ?? DEFAULT_RESULT_ENTRY_CHARS
+    const maxCompactChars = caps.maxCompactChars ?? DEFAULT_RESULT_COMPACT_CHARS
+    const facts = sortFacts(entry.facts)
+    if (facts.length === 0 && entry.summary == null && entry.partial !== true) {
+      return { full: '', compact: '' }
+    }
+
+    const summary = entry.summary != null && entry.summary.trim() !== ''
+      ? [`${facts.length > 0 ? SUMMARY_WITH_FACTS : SUMMARY_ALONE} ${oneLine(entry.summary)}`]
+      : []
+    const full = fit([heading(entry, false)], facts.map(renderResultFact), summary, maxChars, moreFacts)
 
-  const byKind = new Map<string, string[]>()
-  for (const fact of facts) {
-    const names = byKind.get(fact.kind) ?? []
-    if (!names.includes(fact.name)) {
-      names.push(fact.name)
+    const byKind = new Map<string, string[]>()
+    for (const fact of facts) {
+      const names = byKind.get(fact.kind) ?? []
+      if (!names.includes(fact.name)) {
+        names.push(fact.name)
+      }
+      byKind.set(fact.kind, names)
     }
-    byKind.set(fact.kind, names)
-  }
-  // One line per kind while the names fit; the rest are counted, never cut.
-  const compactHead = heading(entry, true)
-  const namesWithin = (reserve: number): { lines: string[], left: number } => {
-    const lines: string[] = []
-    let left = 0
-    for (const [kind, names] of byKind) {
-      let line = `- ${kind}:`
-      let taken = 0
-      for (const name of names) {
-        const next = `${line}${taken > 0 ? ',' : ''} \`${oneLine(name)}\``
-        if (left > 0 || [compactHead, ...lines, next].join('\n').length + reserve > maxCompactChars) {
-          left += 1
-          continue
+    // One line per kind while the names fit; the rest are counted, never cut.
+    const compactHead = heading(entry, true)
+    const namesWithin = (reserve: number): { lines: string[], left: number } => {
+      const lines: string[] = []
+      let left = 0
+      for (const [kind, names] of byKind) {
+        let line = `- ${kind}:`
+        let taken = 0
+        for (const name of names) {
+          const next = `${line}${taken > 0 ? ',' : ''} \`${oneLine(name)}\``
+          if (left > 0 || [compactHead, ...lines, next].join('\n').length + reserve > maxCompactChars) {
+            left += 1
+            continue
+          }
+          line = next
+          taken += 1
+        }
+        if (taken > 0) {
+          lines.push(line)
         }
-        line = next
-        taken += 1
-      }
-      if (taken > 0) {
-        lines.push(line)
       }
+
+      return { lines, left }
+    }
+    let names = namesWithin(0)
+    if (names.left > 0) {
+      // Room for the "more" line is reserved at its widest, so adding it can never break the cap.
+      names = namesWithin(moreNames(facts.length).length + 1)
     }
+    const compact = [
+      compactHead, ...names.lines, ...(names.left > 0 ? [moreNames(names.left)] : []),
+    ].join('\n')
 
-    return { lines, left }
+    return { full, compact }
   }
-  let names = namesWithin(0)
-  if (names.left > 0) {
-    // Room for the "more" line is reserved at its widest, so adding it can never break the cap.
-    names = namesWithin(moreNames(facts.length).length + 1)
-  }
-  const compact = [
-    compactHead, ...names.lines, ...(names.left > 0 ? [moreNames(names.left)] : []),
-  ].join('\n')
 
-  return { full, compact }
-}
-
-/**
- * Ledger order: element by element, and where one key is a prefix of the other, the LONGER one
- * first — an entry of a run composed under a step sorts ahead of that step's own entry, which is
- * written only once the composed run has finished.
- */
-export const compareResultOrder = (a: readonly number[], b: readonly number[]): number => {
-  for (let i = 0; i < Math.min(a.length, b.length); ++i) {
-    if (a[i] !== b[i]) {
-      return a[i]! - b[i]!
+  const compareResultOrder = (a: readonly number[], b: readonly number[]): number => {
+    for (let i = 0; i < Math.min(a.length, b.length); ++i) {
+      if (a[i] !== b[i]) {
+        return a[i]! - b[i]!
+      }
     }
-  }
 
-  return b.length - a.length
-}
+    return b.length - a.length
+  }
 
-/** The root run of a composition — what a composed run's id (`<parent>/<step>`) starts with. */
-export const rootRunOf = (runId: string): string => {
-  const at = runId.indexOf('/')
+  const rootRunOf = (runId: string): string => {
+    const at = runId.indexOf('/')
 
-  return at < 0 ? runId : runId.slice(0, at)
-}
+    return at < 0 ? runId : runId.slice(0, at)
+  }
 
-/**
- * How an entry is headed: the step, behind the path of composing steps between the ledger's root
- * run and the run that produced it. A root-run step is headed by its bare name.
- */
-export const resultLabel = (ledger: string, runId: string, step: string): string => {
-  const path = runId === ledger
-    ? ''
-    : runId.startsWith(`${ledger}/`)
-      ? runId.slice(ledger.length + 1)
-      : runId.slice(rootRunOf(runId).length + 1)
-
-  return path !== '' ? `${path}/${step}` : step
-}
+  const resultLabel = (ledger: string, runId: string, step: string): string => {
+    const path = runId === ledger
+      ? ''
+      : runId.startsWith(`${ledger}/`)
+        ? runId.slice(ledger.length + 1)
+        : runId.slice(rootRunOf(runId).length + 1)
 
-const flatten = (value: unknown): string => {
-  if (value == null) {
-    return ''
-  }
-  if (typeof value === 'string') {
-    return oneLine(value)
-  }
-  if (typeof value === 'number' || typeof value === 'boolean') {
-    return String(value)
+    return path !== '' ? `${path}/${step}` : step
   }
-  if (Array.isArray(value)) {
-    return value.map(flatten).filter(part => part !== '').join(', ')
-  }
-  if (typeof value === 'object') {
-    return Object.keys(value).sort(compare)
-      .map(key => [key, flatten((value as Record<string, unknown>)[key])] as const)
-      .filter(([, text]) => text !== '')
-      .map(([key, text]) => `${key}: ${text}`)
-      .join('; ')
-  }
-
-  return ''
-}
 
-/**
- * A model's schema-shaped summary as one capped line, the same bytes for the same answer.
- *
- * An object renders as `key: value` pairs in key order; one with a single key renders as that
- * value alone, so the default `{ summary }` answer reads as prose. The cap is applied here, after
- * the model answered — a cap in a prompt is a request.
- */
-export const renderResultSummary = (
-  answer: unknown, maxChars: number = DEFAULT_RESULT_SUMMARY_CHARS,
-): string => {
-  const single = typeof answer === 'object' && answer != null && !Array.isArray(answer)
-    && Object.keys(answer).length === 1
-    ? (answer as Record<string, unknown>)[Object.keys(answer)[0]!]
-    : answer
-
-  return truncateAt(flatten(single), maxChars)
-}
+  const flatten = (value: unknown): string => {
+    if (value == null) {
+      return ''
+    }
+    if (typeof value === 'string') {
+      return oneLine(value)
+    }
+    if (typeof value === 'number' || typeof value === 'boolean') {
+      return String(value)
+    }
+    if (Array.isArray(value)) {
+      return value.map(flatten).filter(part => part !== '').join(', ')
+    }
+    if (typeof value === 'object') {
+      return Object.keys(value).sort(compare)
+        .map(key => [key, flatten((value as Record<string, unknown>)[key])] as const)
+        .filter(([, text]) => text !== '')
+        .map(([key, text]) => `${key}: ${text}`)
+        .join('; ')
+    }
 
-const union = (left: readonly string[] | undefined, right: readonly string[] | undefined): string[] | undefined =>
-  left == null && right == null ? undefined : [...new Set([...(left ?? []), ...(right ?? [])])]
+    return ''
+  }
 
-const mergeStep = (base: StepResultsSpec | undefined, patch: StepResultsSpec): StepResultsSpec => {
-  const extractors = union(base?.extractors, patch.extractors)
-  const omit = union(base?.omit, patch.omit)
-  const full = base?.full === RESULTS_EVERY_STEP || patch.full === RESULTS_EVERY_STEP
-    ? RESULTS_EVERY_STEP
-    : union(base?.full as string[] | undefined, patch.full as string[] | undefined)
+  const renderResultSummary = (
+    answer: unknown, maxChars: number = DEFAULT_RESULT_SUMMARY_CHARS,
+  ): string => {
+    const single = typeof answer === 'object' && answer != null && !Array.isArray(answer)
+      && Object.keys(answer).length === 1
+      ? (answer as Record<string, unknown>)[Object.keys(answer)[0]!]
+      : answer
 
-  return {
-    ...base,
-    ...patch,
-    ...(extractors != null ? { extractors } : {}),
-    ...(omit != null ? { omit } : {}),
-    ...(full != null ? { full } : {}),
+    return truncateAt(flatten(single), maxChars)
   }
-}
 
-/**
- * Several declarations as one — a pipeline's own, then any overlay (a variant, a deployment).
- *
- * Later declarations win field by field, except the lists: extractors, `full` consumers and `omit`
- * consumers ACCUMULATE, the way skills do down an execution chain, because an overlay that adds an
- * extractor is not asking to lose the ones the pipeline declared. `'*'` in `full` absorbs names.
- */
-export const mergeResultsSpecs = (
-  ...specs: Array<CumulativeResultsSpec | null | undefined>
-): CumulativeResultsSpec => {
-  const merged: CumulativeResultsSpec = {}
-  for (const spec of specs) {
-    if (spec == null) {
-      continue
+  const union = (left: readonly string[] | undefined, right: readonly string[] | undefined): string[] | undefined =>
+    left == null && right == null ? undefined : [...new Set([...(left ?? []), ...(right ?? [])])]
+
+  const mergeStep = (base: StepResultsSpec | undefined, patch: StepResultsSpec): StepResultsSpec => {
+    const extractors = union(base?.extractors, patch.extractors)
+    const omit = union(base?.omit, patch.omit)
+    const full = base?.full === RESULTS_EVERY_STEP || patch.full === RESULTS_EVERY_STEP
+      ? RESULTS_EVERY_STEP
+      : union(base?.full as string[] | undefined, patch.full as string[] | undefined)
+
+    return {
+      ...base,
+      ...patch,
+      ...(extractors != null ? { extractors } : {}),
+      ...(omit != null ? { omit } : {}),
+      ...(full != null ? { full } : {}),
     }
-    const { steps, ...scalars } = spec
-    Object.assign(merged, scalars)
-    if (steps != null) {
-      const into: Record<string, StepResultsSpec> = { ...merged.steps }
-      for (const name of Object.keys(steps)) {
-        into[name] = mergeStep(into[name], steps[name]!)
+  }
+
+  const mergeResultsSpecs = (
+    ...specs: Array<CumulativeResultsSpec | null | undefined>
+  ): CumulativeResultsSpec => {
+    const merged: CumulativeResultsSpec = {}
+    for (const spec of specs) {
+      if (spec == null) {
+        continue
+      }
+      const { steps, ...scalars } = spec
+      Object.assign(merged, scalars)
+      if (steps != null) {
+        const into: Record<string, StepResultsSpec> = { ...merged.steps }
+        for (const name of Object.keys(steps)) {
+          into[name] = mergeStep(into[name], steps[name]!)
+        }
+        merged.steps = into
       }
-      merged.steps = into
     }
+
+    return merged
   }
 
-  return merged
+  return {
+    factKey, sortFacts, renderResultFact, renderResultEntry, compareResultOrder, rootRunOf, resultLabel,
+    renderResultSummary, mergeResultsSpecs,
+  }
 }
+
+export const cumulativeResultsHelper = createCumulativeResultsHelper()