@graphorin/agent 0.6.0 → 0.7.0

package/src/runtime/messages.ts

@@ -0,0 +1,309 @@
+/**
+ * Message-buffer shaping and step-accounting helpers for the agent
+ * runtime: reasoning-retention resolution, assistant-message assembly,
+ * the compaction-stable system-prefix scan, per-step request assembly,
+ * tool-error rendering for the model, and usage arithmetic. Extracted
+ * verbatim from `factory.ts` (issue #23).
+ *
+ * @packageDocumentation
+ */
+
+import type {
+  AssistantMessage,
+  Message,
+  MessageContent,
+  Provider,
+  ReasoningContent,
+  ReasoningRetention,
+  RunState,
+  ToolCall,
+  ToolError,
+  Usage,
+  UsageAccumulator,
+} from '@graphorin/core';
+import { COMPACTION_SUMMARY_MARKER } from '@graphorin/memory';
+import { addModelUsage } from '../run-state/index.js';
+import { renderPlanRecitation } from '../tooling/plan.js';
+
+/** Most-recent user-role text in `messages` (for context-engine auto-recall). */
+export function lastUserText(messages: ReadonlyArray<Message>): string | undefined {
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const m = messages[i];
+    if (m?.role !== 'user') continue;
+    if (typeof m.content === 'string') return m.content;
+    const text = m.content
+      .filter((p): p is { readonly type: 'text'; readonly text: string } => p.type === 'text')
+      .map((p) => p.text)
+      .join(' ');
+    return text.length > 0 ? text : undefined;
+  }
+  return undefined;
+}
+
+/**
+ * Resolve the effective {@link ReasoningRetention} for a step. The
+ * agent-level setting wins over the provider-level default; when
+ * neither is supplied, the provider's `reasoningContract`
+ * capability drives the default per RB-42 / suggested DEC-158.
+ */
+export function effectiveReasoningRetention(
+  agentOverride: ReasoningRetention | undefined,
+  provider: Provider,
+): ReasoningRetention {
+  if (agentOverride !== undefined) return agentOverride;
+  const contract = provider.capabilities.reasoningContract;
+  switch (contract) {
+    case 'round-trip-required':
+      return 'pass-through-claude';
+    case 'optional':
+      return 'pass-through-all';
+    case 'hidden':
+      return 'strip';
+    default:
+      return 'strip';
+  }
+}
+
+/**
+ * Build the assistant message that the runtime appends to the
+ * message buffer after a successful provider call. When the
+ * effective {@link ReasoningRetention} is not `'strip'`, the
+ * assembled `reasoning` content parts ride along on `content` so
+ * the next provider call honours the wire-correct round-trip
+ * contract per RB-42.
+ */
+export function buildAssistantMessage(
+  text: string,
+  reasoningParts: ReadonlyArray<ReasoningContent>,
+  toolCalls: ReadonlyArray<ToolCall>,
+  agentId: string,
+  retention: ReasoningRetention,
+): AssistantMessage {
+  const preserveReasoning = retention !== 'strip' && reasoningParts.length > 0;
+  if (preserveReasoning) {
+    const parts: MessageContent[] = [...reasoningParts];
+    if (text.length > 0) parts.push({ type: 'text', text });
+    return {
+      role: 'assistant',
+      content: parts,
+      ...(toolCalls.length > 0 ? { toolCalls } : {}),
+      agentId,
+    };
+  }
+  return {
+    role: 'assistant',
+    content: text,
+    ...(toolCalls.length > 0 ? { toolCalls } : {}),
+    agentId,
+  };
+}
+
+/**
+ * Strip every {@link ReasoningContent} part from each message in
+ * the supplied list. Used at the swap point when `prepareStep`
+ * downgrades the provider's `reasoningContract` mid-run.
+ */
+export function stripReasoningFromMessages(messages: Message[]): { stripped: number } {
+  let stripped = 0;
+  for (let i = 0; i < messages.length; i++) {
+    const msg = messages[i];
+    if (msg === undefined) continue;
+    if (msg.role === 'system' || msg.role === 'tool') continue;
+    if (typeof msg.content === 'string') continue;
+    const filtered = msg.content.filter((p) => p.type !== 'reasoning');
+    if (filtered.length === msg.content.length) continue;
+    stripped += msg.content.length - filtered.length;
+    if (msg.role === 'assistant') {
+      messages[i] = { ...msg, content: filtered };
+    } else {
+      messages[i] = { ...msg, content: filtered };
+    }
+  }
+  return { stripped };
+}
+
+/**
+ * Count the leading contiguous run of `system` messages in the initial
+ * buffer - the trusted, KV-cache-stable instruction prefix. Captured
+ * once at run start (WI-09 / P1-1): auto-compaction summarises only the
+ * messages after this prefix, so the prefix stays byte-identical across
+ * every step (the provider's cache breakpoint is real) and a long run
+ * never re-pays for the system prompt.
+ *
+ * The length is fixed for the run rather than re-derived per compaction
+ * on purpose: each compaction inserts its summary as a `system` message
+ * right after the prefix, so re-scanning the leading run would absorb
+ * that summary into the prefix and shield it from the next compaction -
+ * summaries would stack unbounded. Pinning the original length keeps
+ * each prior summary inside the compactable body, where the next pass
+ * folds it into a fresh summary-of-summary.
+ */
+/**
+ * Marker prefix stamped on every compaction summary. context-engine-05:
+ * the prefix scan must stop at it - after a compact-then-suspend cycle
+ * the summary is a SYSTEM message sitting right after the true prefix,
+ * and counting it in would pin it (and every later summary) outside the
+ * compactable window forever, growing the uncompactable prefix by one
+ * summary per cycle. W-056: the constant is canonical in
+ * `@graphorin/memory` (next to the summary template that stamps it);
+ * re-exported here for the runtime's internal imports.
+ */
+export { COMPACTION_SUMMARY_MARKER };
+
+export function countLeadingSystemMessages(messages: ReadonlyArray<Message>): number {
+  let i = 0;
+  while (i < messages.length) {
+    const msg = messages[i];
+    if (msg?.role !== 'system') break;
+    if (typeof msg.content === 'string' && msg.content.startsWith(COMPACTION_SUMMARY_MARKER)) {
+      break;
+    }
+    i += 1;
+  }
+  return i;
+}
+
+/**
+ * Immutable usage sum. Optional token fields (reasoning + prompt-cache
+ * legs, core-provider-02) appear in the result only when at least one
+ * side carries them, so pre-cache serialized shapes stay byte-identical.
+ */
+/**
+ * D6: assemble the per-step request messages. Trailing, request-only
+ * additions ride the LAST prompt-cache anchor and never touch the shared
+ * `messages` buffer or the persisted RunState: the structured-output
+ * instruction (AG-3) and the attention-recitation plan block are both
+ * appended here, in that order, so the stable prompt prefix is unchanged
+ * and only the small trailing tail is re-sent each step.
+ */
+export function buildStepMessages(
+  messages: ReadonlyArray<Message>,
+  structuredInstruction: string | undefined,
+  todos: ReadonlyArray<import('@graphorin/core').TodoItem> | undefined,
+): Message[] {
+  const out: Message[] = [...messages];
+  if (structuredInstruction !== undefined) {
+    out.push({ role: 'system', content: structuredInstruction });
+  }
+  const recitation = renderPlanRecitation(todos);
+  if (recitation !== null) {
+    out.push({ role: 'system', content: recitation });
+  }
+  return out;
+}
+
+export function addUsage(a: Usage, b: Usage): Usage {
+  const optional = (x: number | undefined, y: number | undefined): number | undefined =>
+    x === undefined && y === undefined ? undefined : (x ?? 0) + (y ?? 0);
+  const reasoningTokens = optional(a.reasoningTokens, b.reasoningTokens);
+  const cachedReadTokens = optional(a.cachedReadTokens, b.cachedReadTokens);
+  const cacheWriteTokens = optional(a.cacheWriteTokens, b.cacheWriteTokens);
+  return {
+    promptTokens: a.promptTokens + b.promptTokens,
+    completionTokens: a.completionTokens + b.completionTokens,
+    totalTokens: a.totalTokens + b.totalTokens,
+    ...(reasoningTokens !== undefined ? { reasoningTokens } : {}),
+    ...(cachedReadTokens !== undefined ? { cachedReadTokens } : {}),
+    ...(cacheWriteTokens !== undefined ? { cacheWriteTokens } : {}),
+  };
+}
+
+/**
+ * C3: render a ToolError for the model. The first line keeps the
+ * long-standing `Error: <message>` shape; a bracketed second line carries
+ * the typed kind + the recovery envelope, which is what actually changes
+ * model behaviour after a failure (retry vs. fix args vs. give up).
+ */
+export function renderToolErrorMessage(error: ToolError): string {
+  const parts: string[] = [`kind: ${error.kind}`];
+  if (error.recoverable !== undefined) {
+    parts.push(error.recoverable ? 'recoverable: yes' : 'recoverable: no');
+  }
+  if (error.recoveryHint !== undefined) parts.push(`suggested action: ${error.recoveryHint}`);
+  if (error.hint !== undefined) parts.push(error.hint);
+  return `Error: ${error.message}\n[${parts.join('; ')}]`;
+}
+
+/** In-place variant of {@link addUsage} for mutable accumulators. */
+export function accumulateUsage(target: Usage, delta: Usage): void {
+  target.promptTokens += delta.promptTokens;
+  target.completionTokens += delta.completionTokens;
+  target.totalTokens += delta.totalTokens;
+  if (delta.reasoningTokens !== undefined) {
+    target.reasoningTokens = (target.reasoningTokens ?? 0) + delta.reasoningTokens;
+  }
+  if (delta.cachedReadTokens !== undefined) {
+    target.cachedReadTokens = (target.cachedReadTokens ?? 0) + delta.cachedReadTokens;
+  }
+  if (delta.cacheWriteTokens !== undefined) {
+    target.cacheWriteTokens = (target.cacheWriteTokens ?? 0) + delta.cacheWriteTokens;
+  }
+}
+
+/**
+ * Fold a completed (or failed - tokens were spent either way) child
+ * run's usage into the parent run's accounting: `state.usage`,
+ * `state.usageByModel` and the run's {@link UsageAccumulator} (W-033).
+ * Children carrying a per-model breakdown fold model-by-model (each
+ * child model entry counts as one attempt on the parent); a child
+ * without `usageByModel` folds its aggregate under the synthetic id
+ * `sub-agent:<name>`, skipped entirely when all-zero so phantom
+ * entries never appear.
+ *
+ * Must be called exactly once per child run at exactly one seam -
+ * a second call double-counts (pinned by test).
+ */
+export function foldChildRunUsage(
+  state: RunState,
+  usageAcc: UsageAccumulator | undefined,
+  childState: RunState,
+  childName: string,
+): void {
+  const byModel = childState.usageByModel;
+  if (byModel !== undefined && Object.keys(byModel).length > 0) {
+    for (const [modelId, usage] of Object.entries(byModel)) {
+      addModelUsage(state, modelId, usage);
+      accumulateUsage(state.usage, usage);
+      usageAcc?.add(modelId, usage);
+    }
+    return;
+  }
+  const aggregate = childState.usage;
+  if (
+    aggregate.promptTokens === 0 &&
+    aggregate.completionTokens === 0 &&
+    aggregate.totalTokens === 0
+  ) {
+    return;
+  }
+  const syntheticId = `sub-agent:${childName}`;
+  addModelUsage(state, syntheticId, aggregate);
+  accumulateUsage(state.usage, aggregate);
+  usageAcc?.add(syntheticId, aggregate);
+}
+
+/**
+ * Resolve the effective reasoning-retention policy for
+ * this step (RB-42). Drop any buffered reasoning when the
+ * contract downgrades to `'strip'`.
+ */
+export function applyReasoningRetention(
+  agentOverride: ReasoningRetention | undefined,
+  provider: Provider,
+  messages: Message[],
+  stateMessages: Message[],
+): ReasoningRetention {
+  const reasoningPolicy = effectiveReasoningRetention(agentOverride, provider);
+  if (reasoningPolicy === 'strip') {
+    const { stripped } = stripReasoningFromMessages(messages);
+    // Mirror the strip into RunState so the persisted state
+    // matches the in-flight buffer.
+    if (stripped > 0) {
+      // The structural drop is bytes-equal across `messages`
+      // and `state.messages` (both arrays carry the same
+      // references); re-strip RunState explicitly to be safe.
+      stripReasoningFromMessages(stateMessages);
+    }
+  }
+  return reasoningPolicy;
+}

package/src/runtime/provider-events.ts

@@ -0,0 +1,175 @@
+/**
+ * Provider stream bridging for the agent runtime: the per-step
+ * accumulation of `ProviderEvent`s into agent-visible events / final
+ * tool calls, thrown-provider-error classification for the fallback
+ * chain, and the `ModelSpec` -> `Provider` projection. Extracted
+ * verbatim from `factory.ts` (issue #23).
+ *
+ * @packageDocumentation
+ */
+
+import type {
+  AgentEvent,
+  ModelSpec,
+  Provider,
+  ProviderError,
+  ProviderErrorKind,
+  ProviderEvent,
+  ReasoningContent,
+  ToolCall,
+  Usage,
+} from '@graphorin/core';
+
+/**
+ * AG-21: classify a **thrown** provider error into a {@link ProviderErrorKind}
+ * so the fallback chain can act on it, instead of flattening every exception to
+ * `'unknown'` (which is always fallback-ineligible). Structural - reads the
+ * `kind` carried by `@graphorin/provider`'s `GraphorinProviderError` subclasses
+ * without importing them, keeping the agent decoupled from the provider package.
+ */
+/** Canonical `ProviderErrorKind` values honoured off a thrown error's `errorKind`. */
+const CANONICAL_PROVIDER_ERROR_KINDS: ReadonlySet<string> = new Set([
+  'rate-limit',
+  'capacity',
+  'context-length',
+  'transient',
+  'invalid-request',
+  'unauthorized',
+  'content-filter',
+]);
+
+export function classifyThrownProviderErrorKind(cause: unknown): ProviderErrorKind {
+  if (typeof cause === 'object' && cause !== null) {
+    // B1: `ProviderHttpError` carries the canonical mapped kind on
+    // `errorKind` (its `kind` stays the stable 'provider-http'
+    // discriminant) - honour it so a thrown 429 / context overflow is
+    // classified like the structured-event equivalent.
+    const errorKind = (cause as { readonly errorKind?: unknown }).errorKind;
+    if (typeof errorKind === 'string' && CANONICAL_PROVIDER_ERROR_KINDS.has(errorKind)) {
+      return errorKind as ProviderErrorKind;
+    }
+    switch ((cause as { readonly kind?: unknown }).kind) {
+      case 'rate-limit-exceeded':
+        return 'rate-limit';
+    }
+  }
+  return 'unknown';
+}
+
+export function specToProvider(spec: ModelSpec): Provider {
+  if ('provider' in spec) return spec.provider as Provider;
+  return spec as Provider;
+}
+
+export interface ToolCallAccumulator {
+  readonly toolCallId: string;
+  toolName: string;
+  argsBuffer: string;
+}
+
+export interface ProviderEventOutcome {
+  readonly emit?: AgentEvent;
+  readonly providerError?: ProviderError;
+  readonly usage?: Usage;
+  readonly finished?: boolean;
+}
+
+export interface ProviderEventCollector {
+  textBuffer: string;
+  reasoningBuffer: string;
+  reasoningParts: ReasoningContent[];
+  calls: Map<string, ToolCallAccumulator>;
+  finalCalls: ToolCall[];
+}
+
+export function handleProviderEvent(
+  ev: ProviderEvent,
+  state: ProviderEventCollector,
+): ProviderEventOutcome {
+  switch (ev.type) {
+    case 'stream-start':
+      return {};
+    case 'reasoning-delta':
+      state.reasoningBuffer += ev.delta;
+      return { emit: { type: 'reasoning.delta', delta: ev.delta } };
+    case 'reasoning-end': {
+      // W-024: close the current reasoning block - flush the buffered
+      // deltas into a per-block ReasoningContent carrying the adapter's
+      // opaque round-trip meta (Anthropic thinking signature / redacted
+      // data). A redacted block has no deltas: its part is meta-only
+      // with empty text, which the retention pipeline still round-trips.
+      const text = state.reasoningBuffer;
+      state.reasoningBuffer = '';
+      state.reasoningParts.push({
+        type: 'reasoning',
+        text,
+        ...(ev.meta !== undefined ? { meta: ev.meta } : {}),
+      });
+      return {};
+    }
+    case 'text-delta':
+      state.textBuffer += ev.delta;
+      return { emit: { type: 'text.delta', delta: ev.delta } };
+    case 'tool-call-start':
+      state.calls.set(ev.toolCallId, {
+        toolCallId: ev.toolCallId,
+        toolName: ev.toolName,
+        argsBuffer: '',
+      });
+      return {
+        emit: {
+          type: 'tool.call.start',
+          toolCallId: ev.toolCallId,
+          toolName: ev.toolName,
+          args: undefined,
+        },
+      };
+    case 'tool-call-input-delta': {
+      const acc = state.calls.get(ev.toolCallId);
+      if (acc !== undefined) acc.argsBuffer += ev.argsDelta;
+      return {
+        emit: { type: 'tool.call.delta', toolCallId: ev.toolCallId, argsDelta: ev.argsDelta },
+      };
+    }
+    case 'tool-call-end': {
+      const acc = state.calls.get(ev.toolCallId);
+      if (acc === undefined) {
+        // AG-26: an end without a matching start has no tool name - the
+        // old path dispatched it as the unknown tool ''. Drop it loudly.
+        process.stderr.write(
+          `[graphorin/agent] dropped tool-call-end '${ev.toolCallId}' with no matching tool-call-start.\n`,
+        );
+        return {};
+      }
+      state.finalCalls.push({
+        toolCallId: ev.toolCallId,
+        toolName: acc.toolName,
+        args: ev.finalArgs,
+      });
+      return {
+        emit: { type: 'tool.call.end', toolCallId: ev.toolCallId, finalArgs: ev.finalArgs },
+      };
+    }
+    // AG-26: provider-generated files / citations are consumer-observable
+    // events instead of silently vanishing.
+    case 'file':
+      return { emit: { type: 'file.generated', mimeType: ev.mimeType, data: ev.data } };
+    case 'source':
+      return {
+        emit: {
+          type: 'source.cited',
+          uri: ev.uri,
+          ...(ev.title !== undefined ? { title: ev.title } : {}),
+        },
+      };
+    case 'finish':
+      return { usage: ev.usage, finished: true };
+    case 'error':
+      return { providerError: ev.error };
+    default: {
+      const _exhaustive: never = ev;
+      void _exhaustive;
+      return {};
+    }
+  }
+}