@graphorin/memory 0.6.1 → 0.7.0

package/src/context-engine/annotations.ts

@@ -0,0 +1,161 @@
+/**
+ * Cooperation contract between the {@link ContextEngine} and the
+ * outbound prompt-redaction middleware (D3, see ADR-045 / DEC-157)
+ * + the inbound tool-result sanitization middleware (D4, see
+ * RB-43 / DEC-159).
+ *
+ * Every {@link MessageContent} part assembled by the ContextEngine
+ * carries two **independent** annotations:
+ *
+ * - `graphorin.content.origin` - where the content came from. Used
+ *   by D3 (`withRedaction`) under `scanScope: 'untrusted'` to
+ *   decide whether to re-scan a part that already passed the D2
+ *   sensitivity-tier filter.
+ * - `graphorin.content.inbound.trust` - what trust class the source
+ *   carries. Used by D4 (`withInboundSanitization`) and by Phase 12
+ *   (agent runtime) to gate the per-step preamble injection.
+ *
+ * Both annotations live as **span attributes only** (observability)
+ * - they are never serialized to the wire payload. The wire-stable
+ * `ProviderRequest` shape is unchanged by Phase 10d.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Span-attribute key for the origin axis.
+ *
+ * @stable
+ */
+export const CONTENT_ORIGIN_ATTR = 'graphorin.content.origin' as const;
+
+/**
+ * Span-attribute key for the inbound-trust axis.
+ *
+ * @stable
+ */
+export const INBOUND_TRUST_ATTR = 'graphorin.content.inbound.trust' as const;
+
+/**
+ * Origin discriminator for an assembled message-content part. The
+ * non-ContextEngine origins (`'user:input'`, `'tool:result'`,
+ * `'mcp:response'`, `'tool-call:args'`) are tagged by Phase 12
+ * (agent runtime) when the corresponding payload enters
+ * `session_messages`; the ContextEngine then propagates the tag
+ * through the assembled message list.
+ *
+ * @stable
+ */
+export type ContentOrigin =
+  | 'memory:tier-filtered'
+  | 'system:framework'
+  | 'agent:instructions'
+  | 'skill:content'
+  | 'user:input'
+  | 'tool:result'
+  | 'mcp:response'
+  | 'tool-call:args';
+
+/**
+ * Trust-class discriminator for an assembled message-content part.
+ * Sibling axis to {@link ContentOrigin}; the two are independent.
+ *
+ * - `'trusted'` - built-in framework tools + trusted-skill-bundled
+ *   tools; D4 preamble does NOT fire on steps containing only
+ *   these parts.
+ * - `'user-defined'` - tools registered via `tool({...})` from user
+ *   application code; D4 preamble fires.
+ * - `'untrusted-skill'` - tools bundled by an untrusted skill; D4
+ *   preamble fires; default policy is strip-and-wrap.
+ * - `'mcp'` - every `Tool` produced by `MCPClient.toTools(...)`; D4
+ *   preamble fires; default policy is strip-and-wrap.
+ * - `'web-search'` - built-in `web_search` adapter; D4 preamble
+ *   fires; default policy is strip-and-wrap.
+ * - `'n/a'` - non-tool-result parts for which the inbound-trust
+ *   axis is meaningless (`'user:input'`, `'memory:tier-filtered'`,
+ *   `'system:framework'`, `'agent:instructions'`,
+ *   `'tool-call:args'`).
+ *
+ * @stable
+ */
+export type InboundTrust =
+  | 'trusted'
+  | 'user-defined'
+  | 'untrusted-skill'
+  | 'mcp'
+  | 'web-search'
+  | 'n/a';
+
+/**
+ * Origins for which the inbound-trust axis is meaningless and is
+ * always set to `'n/a'`. Surfaced as a frozen constant so consumers
+ * can introspect the contract without re-implementing the rule.
+ *
+ * @stable
+ */
+export const NON_INBOUND_ORIGINS: ReadonlySet<ContentOrigin> = Object.freeze(
+  new Set<ContentOrigin>([
+    'memory:tier-filtered',
+    'system:framework',
+    'agent:instructions',
+    'user:input',
+    'tool-call:args',
+  ]),
+);
+
+/**
+ * Single typed annotation for an assembled message-content part.
+ *
+ * @stable
+ */
+export interface ContentAnnotation {
+  readonly origin: ContentOrigin;
+  readonly inboundTrust: InboundTrust;
+}
+
+/**
+ * Build an annotation, enforcing the rule that
+ * non-tool-result origins always carry `inboundTrust: 'n/a'`. A
+ * caller that requests a non-`'n/a'` value for a non-inbound origin
+ * is silently corrected (defense-in-depth: the rule is enforced
+ * here so callers cannot accidentally violate it).
+ *
+ * @stable
+ */
+export function annotate(origin: ContentOrigin, inboundTrust: InboundTrust): ContentAnnotation {
+  if (NON_INBOUND_ORIGINS.has(origin)) {
+    return Object.freeze({ origin, inboundTrust: 'n/a' });
+  }
+  return Object.freeze({ origin, inboundTrust });
+}
+
+/**
+ * Convert a {@link ContentAnnotation} to a span-attributes record
+ * suitable for `AISpan.setAttributes(...)`.
+ *
+ * @stable
+ */
+export function toSpanAttributes(annotation: ContentAnnotation): Readonly<Record<string, string>> {
+  return Object.freeze({
+    [CONTENT_ORIGIN_ATTR]: annotation.origin,
+    [INBOUND_TRUST_ATTR]: annotation.inboundTrust,
+  });
+}
+
+/**
+ * Decide whether the per-step inbound-sanitization preamble (D4)
+ * should fire for an assembled message list. The preamble fires
+ * iff at least one part carries an inbound-trust value other than
+ * `'trusted'` and `'n/a'`. Trusted-only steps skip the preamble for
+ * cache-friendliness; preamble is emitted exactly once per step
+ * regardless of how many untrusted parts the step carries.
+ *
+ * @stable
+ */
+export function shouldFireInboundPreamble(annotations: ReadonlyArray<ContentAnnotation>): boolean {
+  for (const annotation of annotations) {
+    const trust = annotation.inboundTrust;
+    if (trust !== 'trusted' && trust !== 'n/a') return true;
+  }
+  return false;
+}

package/src/context-engine/auto-recall.ts

@@ -0,0 +1,92 @@
+/**
+ * Auto-recall heuristic - opt-in regex-based pre-call that injects
+ * the top-K facts into Layer 6 when the last user message matches one
+ * of the configured trigger phrases. (Episode auto-recall is not
+ * implemented; episodes are reachable via the `recall_episodes` tool.)
+ *
+ * The framework ships English defaults; per-locale trigger
+ * phrases extend the default via {@link defineContextLocalePack}.
+ * Application code can also register a fully-custom strategy via
+ * {@link defineAutoRecallStrategy}.
+ *
+ * @packageDocumentation
+ */
+
+import type { ContextLocalePack } from './locale-packs/index.js';
+
+/**
+ * Per-call scope passed to a custom strategy.
+ *
+ * @stable
+ */
+export interface AutoRecallStrategyContext {
+  readonly locale: string;
+  readonly lastUserMessage: string;
+}
+
+/**
+ * Outcome of a strategy invocation.
+ *
+ * @stable
+ */
+export interface AutoRecallTriggerResult {
+  readonly factsTriggered: boolean;
+  /** Optional reason surfaced in spans / metadata. */
+  readonly reason?: string;
+}
+
+/**
+ * Pluggable strategy signature.
+ *
+ * @stable
+ */
+export type AutoRecallStrategy = (ctx: AutoRecallStrategyContext) => AutoRecallTriggerResult;
+
+/**
+ * Build a locale-driven heuristic strategy. The default for every
+ * configured locale.
+ *
+ * @stable
+ */
+export function defaultLocaleHeuristicStrategy(pack: ContextLocalePack): AutoRecallStrategy {
+  const factTriggers = pack.autoRecallTriggers.factTriggers;
+  return (ctx) => {
+    const text = ctx.lastUserMessage ?? '';
+    if (text.length === 0) {
+      return { factsTriggered: false };
+    }
+    const factsTriggered = factTriggers.some((re) => re.test(text));
+    if (factsTriggered) {
+      return { factsTriggered, reason: 'locale-heuristic-trigger-matched' };
+    }
+    return { factsTriggered: false };
+  };
+}
+
+/**
+ * Builder for application-supplied custom strategies. Accepts a
+ * raw function and returns a tagged version so the engine can
+ * surface the strategy name on spans.
+ *
+ * @stable
+ */
+export function defineAutoRecallStrategy(opts: {
+  readonly id: string;
+  readonly evaluate: AutoRecallStrategy;
+}): AutoRecallStrategy & { readonly id: string } {
+  if (typeof opts.id !== 'string' || opts.id.length === 0) {
+    throw new TypeError(
+      '[graphorin/memory] defineAutoRecallStrategy: `id` must be a non-empty string.',
+    );
+  }
+  if (typeof opts.evaluate !== 'function') {
+    throw new TypeError(
+      '[graphorin/memory] defineAutoRecallStrategy: `evaluate` must be a function.',
+    );
+  }
+  const wrapped = ((ctx: AutoRecallStrategyContext) => opts.evaluate(ctx)) as AutoRecallStrategy & {
+    readonly id: string;
+  };
+  Object.defineProperty(wrapped, 'id', { value: opts.id, enumerable: true });
+  return wrapped;
+}

package/src/context-engine/compaction/clear-tool-results.ts

@@ -0,0 +1,232 @@
+/**
+ * SOTA-1: zero-LLM tool-result clearing - the cheapest pre-compaction tier.
+ *
+ * Mirrors Anthropic context editing (`clear_tool_uses_20250919`): when the
+ * buffer crosses the compaction threshold, replace the oldest tool results with
+ * a compact placeholder BEFORE paying for a summarizer LLM call. The most recent
+ * `keepToolUses` results stay verbatim, `excludeTools` are never touched, and
+ * clearing is skipped entirely when it would reclaim fewer than `clearAtLeast`
+ * tokens (not worth the context churn). Pure + deterministic - no provider call.
+ *
+ * @packageDocumentation
+ */
+
+import type { Message, ToolMessage } from '@graphorin/core';
+import {
+  type ContextTokenCounter,
+  countMessageTokens,
+  renderMessageText,
+} from '../token-counter.js';
+
+/** Placeholder prefix on a cleared tool result - makes clearing idempotent. */
+export const CLEARED_TOOL_RESULT_MARKER = '[cleared tool result';
+
+/** Default count of most-recent tool results kept verbatim. */
+export const DEFAULT_KEEP_TOOL_USES = 3;
+
+/** Knobs for {@link clearOldToolResults} (mirrors the strategy variant). */
+export interface ClearToolResultsOptions {
+  /** Most-recent tool results kept verbatim (default `DEFAULT_KEEP_TOOL_USES`). */
+  readonly keepToolUses?: number;
+  /** Only clear if at least this many tokens are reclaimable; else leave untouched (default 0). */
+  readonly clearAtLeast?: number;
+  /** Tool names whose results are never cleared. */
+  readonly excludeTools?: ReadonlyArray<string>;
+  /** Placeholder builder; defaults to a one-line `[cleared tool result …]` marker. */
+  readonly placeholder?: (info: {
+    readonly toolCallId: string;
+    readonly toolName?: string;
+    readonly clearedTokens: number;
+  }) => string;
+  /**
+   * A6 / SOTA-2 - recoverable clearing. When provided, the original tool-result
+   * text of each cleared message is handed to this callback (wire it to a spill
+   * store / the `read_result` handle registry) and the placeholder references the
+   * returned handle id + preview, so the model can re-fetch the full result via
+   * `read_result` rather than losing it. Invoked only for clears that actually
+   * commit (after the `clearAtLeast` floor), so a rejected clearing never spills.
+   * Omitted ⇒ the bare `placeholder` (irrecoverable, byte-identical default).
+   */
+  readonly externalize?: (
+    content: string,
+    info: {
+      readonly toolCallId: string;
+      readonly toolName?: string;
+      readonly clearedTokens: number;
+    },
+  ) => Promise<{ readonly handleId: string; readonly preview?: string }>;
+  /**
+   * C4 (context-engine-11): the tool the externalized-handle placeholder
+   * advertises. The memory package cannot know whether the agent
+   * registered `read_result` (that depends on spill wiring), so callers
+   * whose runtime does NOT expose it pass `null` and the placeholder
+   * degrades to a tool-neutral phrasing instead of promising a tool the
+   * model cannot call. Default `'read_result'` (the agent built-in).
+   */
+  readonly readResultToolName?: string | null;
+  /**
+   * C4 (clear_tool_uses_20250919 parity): additionally blank the PAIRED
+   * assistant message's tool-call arguments for every cleared result,
+   * reclaiming the input side of verbose calls too. Default `false`.
+   */
+  readonly clearToolInputs?: boolean;
+}
+
+/** Result of a clearing pass. `clearedIndices` empty ⇒ nothing changed. */
+export interface ClearToolResultsOutcome {
+  readonly messages: ReadonlyArray<Message>;
+  readonly clearedIndices: ReadonlyArray<number>;
+  readonly reclaimedTokens: number;
+}
+
+function defaultPlaceholder(info: { toolName?: string; clearedTokens: number }): string {
+  return `${CLEARED_TOOL_RESULT_MARKER} · ${info.toolName ?? 'tool'} · ${info.clearedTokens} tokens elided · re-run the tool if needed]`;
+}
+
+/** A6: a placeholder that points at the externalized handle (recoverable via read_result). */
+function handlePlaceholder(info: {
+  toolName?: string;
+  clearedTokens: number;
+  handleId: string;
+  preview?: string;
+  readToolName?: string | null;
+}): string {
+  const preview = info.preview !== undefined && info.preview.length > 0 ? ` · ${info.preview}` : '';
+  // C4 (context-engine-11): only advertise a retrieval tool the caller
+  // vouches exists; `null` degrades to a tool-neutral phrasing.
+  const retrieval =
+    info.readToolName === null
+      ? `full result externalized to handle: ${info.handleId}`
+      : `full result via ${info.readToolName ?? 'read_result'} handle: ${info.handleId}`;
+  return `${CLEARED_TOOL_RESULT_MARKER} · ${info.toolName ?? 'tool'} · ${info.clearedTokens} tokens · ${retrieval}${preview}]`;
+}
+
+function isAlreadyCleared(content: Message['content']): boolean {
+  return typeof content === 'string' && content.startsWith(CLEARED_TOOL_RESULT_MARKER);
+}
+
+/**
+ * Replace the oldest clearable tool results with placeholders. Returns the new
+ * buffer (same length - content is replaced in place, never removed) plus the
+ * cleared indices and reclaimed token count. Idempotent: already-cleared
+ * placeholders are skipped on a second pass.
+ */
+export async function clearOldToolResults(
+  messages: ReadonlyArray<Message>,
+  options: ClearToolResultsOptions,
+  counter: ContextTokenCounter,
+): Promise<ClearToolResultsOutcome> {
+  const keep = options.keepToolUses ?? DEFAULT_KEEP_TOOL_USES;
+  const exclude = new Set(options.excludeTools ?? []);
+  const placeholder = options.placeholder ?? defaultPlaceholder;
+
+  // toolCallId → toolName from every assistant tool-call in the buffer.
+  const toolNameById = new Map<string, string>();
+  for (const m of messages) {
+    if (m.role === 'assistant' && m.toolCalls) {
+      for (const tc of m.toolCalls) toolNameById.set(tc.toolCallId, tc.toolName);
+    }
+  }
+
+  // Indices of all not-yet-cleared tool-result messages, oldest first.
+  const toolIdx: number[] = [];
+  for (let i = 0; i < messages.length; i++) {
+    const m = messages[i];
+    if (m?.role === 'tool' && !isAlreadyCleared(m.content)) toolIdx.push(i);
+  }
+
+  // Keep the most-recent `keep`; older ones are candidates unless excluded.
+  const keptCutoff = toolIdx.length - Math.max(0, keep);
+  const replacements = new Map<number, ToolMessage>();
+  const clearedTokensByIdx = new Map<number, number>();
+  let reclaimable = 0;
+  for (let j = 0; j < toolIdx.length && j < keptCutoff; j++) {
+    const idx = toolIdx[j];
+    if (idx === undefined) continue;
+    const tm = messages[idx] as ToolMessage;
+    const name = toolNameById.get(tm.toolCallId);
+    if (name !== undefined && exclude.has(name)) continue;
+    const originalTokens = await countMessageTokens([tm], counter);
+    const replaced: ToolMessage = {
+      role: 'tool',
+      toolCallId: tm.toolCallId,
+      content: placeholder({
+        toolCallId: tm.toolCallId,
+        ...(name !== undefined ? { toolName: name } : {}),
+        clearedTokens: originalTokens,
+      }),
+    };
+    const placeholderTokens = await countMessageTokens([replaced], counter);
+    reclaimable += Math.max(0, originalTokens - placeholderTokens);
+    replacements.set(idx, replaced);
+    clearedTokensByIdx.set(idx, originalTokens);
+  }
+
+  const clearAtLeast = options.clearAtLeast ?? 0;
+  if (replacements.size === 0 || reclaimable < clearAtLeast) {
+    return { messages, clearedIndices: [], reclaimedTokens: 0 };
+  }
+
+  // A6: only now that the clearing commits, externalize each cleared result to a
+  // recoverable handle and rewrite its placeholder to reference it. Skipped
+  // clears (above) never reach here, so the spill never fires for nothing.
+  const externalize = options.externalize;
+  if (externalize !== undefined) {
+    for (const idx of replacements.keys()) {
+      const tm = messages[idx] as ToolMessage;
+      const name = toolNameById.get(tm.toolCallId);
+      const clearedTokens = clearedTokensByIdx.get(idx) ?? 0;
+      const content = typeof tm.content === 'string' ? tm.content : renderMessageText(tm);
+      const handle = await externalize(content, {
+        toolCallId: tm.toolCallId,
+        ...(name !== undefined ? { toolName: name } : {}),
+        clearedTokens,
+      });
+      replacements.set(idx, {
+        role: 'tool',
+        toolCallId: tm.toolCallId,
+        content: handlePlaceholder({
+          ...(name !== undefined ? { toolName: name } : {}),
+          clearedTokens,
+          handleId: handle.handleId,
+          ...(handle.preview !== undefined ? { preview: handle.preview } : {}),
+          ...(options.readResultToolName !== undefined
+            ? { readToolName: options.readResultToolName }
+            : {}),
+        }),
+      });
+    }
+  }
+
+  let out: Message[] = messages.map((m, i) => replacements.get(i) ?? m);
+
+  // C4 (clear_tool_uses parity): blank the paired assistant tool-call
+  // ARGUMENTS for every cleared result. The call's name and id survive
+  // (the transcript stays well-formed); only the argument payload is
+  // replaced with a marker object.
+  if (options.clearToolInputs === true && replacements.size > 0) {
+    const clearedCallIds = new Set<string>();
+    for (const idx of replacements.keys()) {
+      const tm = messages[idx] as ToolMessage;
+      clearedCallIds.add(tm.toolCallId);
+    }
+    out = out.map((m) => {
+      if (m.role !== 'assistant' || m.toolCalls === undefined) return m;
+      if (!m.toolCalls.some((tc) => clearedCallIds.has(tc.toolCallId))) return m;
+      return {
+        ...m,
+        toolCalls: m.toolCalls.map((tc) =>
+          clearedCallIds.has(tc.toolCallId)
+            ? { ...tc, args: { cleared: '[tool input elided by context clearing]' } }
+            : tc,
+        ),
+      };
+    });
+  }
+
+  return {
+    messages: out,
+    clearedIndices: [...replacements.keys()],
+    reclaimedTokens: reclaimable,
+  };
+}