@moxxy/sdk 0.14.2 → 0.14.4

package/src/mode/project-messages.ts

@@ -0,0 +1,461 @@
+import type { ContentBlock, ProviderMessage } from '../provider.js';
+import type { ModeContext } from '../mode.js';
+import type { Skill } from '../skill.js';
+import type { CompactionEvent, MoxxyEvent, UserPromptEvent } from '../events.js';
+import {
+  computeElisionState,
+  conversationalStub,
+  conversationalStubbed,
+  toolResultBytes,
+  toolResultStub,
+  toolResultStubbed,
+  type ElisionState,
+} from '../elision-state.js';
+import { isToolDisplayResult } from '../tool-display.js';
+
+/** Appended to the system prompt while elision is active (see projection). */
+export const ELISION_SYSTEM_NOTE =
+  'Context note: to stay within budget, older turns may appear as stubs like ' +
+  '`[output elided — recall("id") to view]` or `[elided user turn · recall({ seq: N })]`. ' +
+  'These are NOT the real content — call the `recall` tool with the given id/seq to fetch ' +
+  'the full text before relying on any detail from an elided turn. Recent turns are always ' +
+  'shown verbatim.';
+
+/**
+ * Compose a model-facing system prompt that includes any base prompt
+ * plus a COMPACT skill index (name + description + triggers only).
+ *
+ * Lazy-loading design: the body is intentionally NOT inlined. The model
+ * matches user intent against the description/triggers, then calls the
+ * `load_skill` tool to fetch the body of the skill it picked. This keeps
+ * the system prompt small even with many skills installed and avoids
+ * paying for skill bodies the model never actually follows.
+ */
+export function buildSystemPromptWithSkills(
+  baseSystemPrompt: string | undefined,
+  skills: ReadonlyArray<Skill>,
+): string | undefined {
+  if (skills.length === 0) return baseSystemPrompt;
+  const header =
+    `## Available skills\n\n` +
+    `Each line below is a pre-authored playbook for a specific intent. ` +
+    `When the user's request matches one of these (by name, description, ` +
+    `or triggers), call \`load_skill({ name: "<skill-name>" })\` FIRST to ` +
+    `fetch the full instructions, then follow them verbatim. Prefer using ` +
+    `a skill over re-deriving the workflow with ad-hoc tools.\n`;
+  const entries = skills
+    .map((s) => {
+      const fm = s.frontmatter;
+      const triggerHint = fm.triggers?.length
+        ? ` (triggers: ${fm.triggers.map((t) => `"${t}"`).join(', ')})`
+        : '';
+      return `- **${fm.name}** — ${fm.description}${triggerHint}`;
+    })
+    .join('\n');
+  const skillBlock = `${header}\n${entries}`;
+  return baseSystemPrompt ? `${baseSystemPrompt}\n\n${skillBlock}` : skillBlock;
+}
+
+export interface ProjectMessagesOptions {
+  /** Optional system prompt; emitted as the first message when set. */
+  readonly systemPrompt?: string;
+  /** Optional trailing user message — useful for plan-execute's "Focus on this step now: X". */
+  readonly trailingUserText?: string;
+}
+
+interface CompactionRange {
+  readonly from: number;
+  readonly to: number;
+  readonly summary: string;
+}
+
+function activeCompactionRanges(events: ReadonlyArray<MoxxyEvent>): ReadonlyArray<CompactionRange> {
+  return events
+    .filter((event): event is CompactionEvent =>
+      event.type === 'compaction' &&
+      event.tokensSaved > 0 &&
+      event.summary.trim().length > 0 &&
+      event.replacedRange[0] <= event.replacedRange[1],
+    )
+    .map((event) => ({
+      from: event.replacedRange[0],
+      to: event.replacedRange[1],
+      summary: event.summary,
+    }));
+}
+
+function eventInCompactionRange(
+  seq: number,
+  ranges: ReadonlyArray<CompactionRange>,
+): CompactionRange | null {
+  for (const range of ranges) {
+    if (seq >= range.from && seq <= range.to) return range;
+  }
+  return null;
+}
+
+/**
+ * A compaction lookup that answers "which range (if any) contains `seq`" in
+ * O(log ranges) instead of {@link eventInCompactionRange}'s O(ranges) linear
+ * scan per event. Compaction ranges are non-overlapping ascending seq prefixes,
+ * so a seq belongs to at most one range and binary search over the
+ * sorted-by-`from` array returns the SAME range the linear first-match did —
+ * byte-identical projection.
+ *
+ * Defensive fallback: if the ranges are NOT strictly non-overlapping (which the
+ * compaction invariant forbids, but a hand-crafted/corrupt log could violate),
+ * we keep the exact linear first-match semantics so the projection can never
+ * diverge from the old code.
+ */
+function makeCompactionLookup(
+  ranges: ReadonlyArray<CompactionRange>,
+): (seq: number) => CompactionRange | null {
+  if (ranges.length === 0) return () => null;
+  if (ranges.length === 1) {
+    const only = ranges[0]!;
+    return (seq) => (seq >= only.from && seq <= only.to ? only : null);
+  }
+  // Sort a copy by `from` (stable enough — ranges are non-overlapping). Verify
+  // the non-overlap invariant on the sorted copy; only then is binary search
+  // provably equivalent to the linear first-match.
+  const sorted = [...ranges].sort((a, b) => a.from - b.from);
+  let nonOverlapping = true;
+  for (let i = 1; i < sorted.length; i++) {
+    if (sorted[i]!.from <= sorted[i - 1]!.to) {
+      nonOverlapping = false;
+      break;
+    }
+  }
+  if (!nonOverlapping) return (seq) => eventInCompactionRange(seq, ranges);
+  return (seq) => {
+    // Largest `from <= seq`, then a single containment check.
+    let lo = 0;
+    let hi = sorted.length - 1;
+    let cand = -1;
+    while (lo <= hi) {
+      const mid = (lo + hi) >> 1;
+      if (sorted[mid]!.from <= seq) {
+        cand = mid;
+        lo = mid + 1;
+      } else {
+        hi = mid - 1;
+      }
+    }
+    if (cand < 0) return null;
+    const range = sorted[cand]!;
+    return seq <= range.to ? range : null;
+  };
+}
+
+/**
+ * Pure projection of a single `user_prompt` event to its content blocks.
+ *
+ * Extracted from {@link projectMessages} as an independently testable sub-step
+ * (u123-5). Returns either the collapsed stub (when the event is an elided
+ * conversational turn) or the full text + attachment-expanded blocks — exactly
+ * what the inline switch arm produced. Caller decides how to wrap it as a
+ * message / record the stable prefix.
+ */
+export function projectUserPrompt(event: UserPromptEvent, el: ElisionState): ContentBlock[] {
+  // Elided + conversational: collapse to a stub (anchor/tiny kept full).
+  if (conversationalStubbed(event, el)) {
+    return [{ type: 'text', text: conversationalStub('user', event.seq) }];
+  }
+  const blocks: ContentBlock[] = [{ type: 'text', text: event.text }];
+  if (event.attachments) {
+    for (const att of event.attachments) {
+      if (att.kind === 'image') {
+        blocks.push({
+          type: 'image',
+          mediaType: att.mediaType ?? 'image/png',
+          data: att.content,
+        });
+      } else if (att.kind === 'document') {
+        blocks.push({
+          type: 'document',
+          mediaType: att.mediaType ?? 'application/pdf',
+          data: att.content,
+          ...(att.name ? { name: att.name } : {}),
+        });
+      } else {
+        blocks.push({
+          type: 'text',
+          text: `[${att.kind}${att.name ? ` ${att.name}` : ''}]\n${att.content}`,
+        });
+      }
+    }
+  }
+  return blocks;
+}
+
+/**
+ * Precompute the set of callIds that have a matching tool_result (or
+ * tool_call_denied) somewhere in the log. Used to synthesize a fallback
+ * `[interrupted]` tool_result for orphan tool_use blocks when the assistant
+ * message gets flushed.
+ *
+ * Without this fallback the provider rejects the whole conversation with
+ * "assistant message with 'tool_calls' must be followed by tool messages
+ * responding to each 'tool_call_id'". Orphans typically appear after a
+ * cancelled turn, an aborted process, or a tool exception that bypassed the
+ * loop's tool_result emit path.
+ *
+ * Extracted as a pure precompute (u123-5); returns a fresh mutable Set the
+ * projection augments as it synthesizes orphan results (so a repeated orphan
+ * across groups is only emitted once).
+ */
+export function resolvedCallIdSet(events: ReadonlyArray<MoxxyEvent>): Set<string> {
+  const resolvedCallIds = new Set<string>();
+  for (const e of events) {
+    if (e.type === 'tool_result' || e.type === 'tool_call_denied') {
+      resolvedCallIds.add(e.callId);
+    }
+  }
+  return resolvedCallIds;
+}
+
+/**
+ * Project the session's event log to a flat list of ProviderMessages
+ * suitable for handing to `provider.stream`. Used by every loop strategy.
+ *
+ * Handles user_prompt, assistant_message, tool_call_requested (grouped
+ * into a single assistant message of tool_use blocks), and tool_result.
+ * Other event types are passed through as a no-op.
+ *
+ * This is THE projection every loop strategy uses; it honors compaction
+ * events, turn-boundary elision, and the orphan-tool_use fallback. It lives in
+ * the SDK so loop plugins stay independent of core.
+ */
+export interface ProjectedMessages {
+  readonly messages: ProviderMessage[];
+  /**
+   * Index (into `messages`) of the last message belonging to the stable,
+   * byte-identical prefix — i.e. produced entirely from events at or below the
+   * elision high-water mark (which only advances on whole-turn boundaries, so
+   * the cut never splits a message). -1 when no elision is active. The
+   * `stable-prefix` cache strategy places its long-lived cross-turn breakpoint
+   * here; see {@link collectProviderStream}'s `stablePrefixIndex` option.
+   */
+  readonly stablePrefixIndex: number;
+}
+
+export function projectMessagesFromLog(
+  ctx: Pick<ModeContext, 'log'>,
+  opts: ProjectMessagesOptions = {},
+): ProviderMessage[] {
+  return projectMessages(ctx, opts).messages;
+}
+
+/**
+ * Same projection as {@link projectMessagesFromLog} but also reports the
+ * stable-prefix boundary so the active cache strategy can place a cross-turn
+ * breakpoint. Modes that build messages this way should thread the returned
+ * `stablePrefixIndex` into {@link collectProviderStream}.
+ */
+export function projectMessages(
+  ctx: Pick<ModeContext, 'log'>,
+  opts: ProjectMessagesOptions = {},
+): ProjectedMessages {
+  const allEvents = ctx.log.slice();
+  const compactions = activeCompactionRanges(allEvents);
+  const compactionFor = makeCompactionLookup(compactions);
+  const emittedCompactions = new Set<CompactionRange>();
+  const el = computeElisionState(allEvents);
+
+  const messages: ProviderMessage[] = [];
+  // The stable prefix is every message produced from events at/below the
+  // elision HWM. Record the latest such message index as we push.
+  let stablePrefixIndex = -1;
+  const recordStable = (maxSeq: number): void => {
+    if (el.hwm >= 0 && maxSeq >= 0 && maxSeq <= el.hwm) {
+      stablePrefixIndex = messages.length - 1;
+    }
+  };
+  if (opts.systemPrompt) {
+    // When elision is active, tell the model that older turns may be shown as
+    // stubs and how to expand them — so it recalls instead of hallucinating.
+    // Constant text → busts the system cache once (when elision starts), stable
+    // thereafter.
+    const sysText = el.hwm >= 0 ? `${opts.systemPrompt}\n\n${ELISION_SYSTEM_NOTE}` : opts.systemPrompt;
+    messages.push({ role: 'system', content: [{ type: 'text', text: sysText }] });
+  }
+  // Pre-scan: build the set of callIds that have a matching tool_result
+  // (or tool_call_denied) somewhere in the log. Used to synthesize a
+  // fallback `[interrupted]` tool_result for orphan tool_use blocks
+  // when the assistant message gets flushed.
+  const resolvedCallIds = resolvedCallIdSet(allEvents);
+
+  let pendingAssistant: ProviderMessage | null = null;
+  let pendingAssistantMaxSeq = -1;
+  // Reasoning block awaiting attachment to the current assistant turn. Only set
+  // for REPLAYABLE reasoning (Anthropic signature / redacted-or-Codex encrypted
+  // blob) — render-only reasoning is never sent back. Attached as content[0] of
+  // the turn's assistant message (Anthropic requires the signed thinking block
+  // first on an interleaved-thinking tool-use continuation; a missing/unsigned
+  // one is a hard 400). Dropped at any turn/compaction boundary it doesn't reach.
+  let pendingReasoning: Extract<ContentBlock, { type: 'reasoning' }> | null = null;
+  let pendingReasoningSeq = -1;
+  const flush = (): void => {
+    if (!pendingAssistant) return;
+    const flushed = pendingAssistant;
+    const groupMaxSeq = pendingAssistantMaxSeq;
+    pendingAssistant = null;
+    pendingAssistantMaxSeq = -1;
+    messages.push(flushed);
+    recordStable(groupMaxSeq);
+    // Synthesize fallback tool_result messages for any tool_use blocks
+    // whose callId never resolved in the event log. Has to land
+    // immediately after the assistant message (and before any
+    // subsequent user_prompt / assistant_message) so the provider sees
+    // a clean assistant→tool-result chain.
+    for (const block of flushed.content) {
+      if (block.type === 'tool_use' && !resolvedCallIds.has(block.id)) {
+        messages.push({
+          role: 'tool_result',
+          content: [
+            {
+              type: 'tool_result',
+              toolUseId: block.id,
+              content: '[tool call did not return a result — possibly interrupted or cancelled]',
+              isError: true,
+            },
+          ],
+        });
+        recordStable(groupMaxSeq);
+        // Mark synthesized so we don't double-emit if the same orphan
+        // appears in multiple groups (defensive — shouldn't normally
+        // happen since each tool_call_requested has a unique callId).
+        resolvedCallIds.add(block.id);
+      }
+    }
+  };
+
+  for (const e of allEvents) {
+    const compaction = compactionFor(e.seq);
+    if (compaction) {
+      if (!emittedCompactions.has(compaction)) {
+        emittedCompactions.add(compaction);
+        flush();
+        pendingReasoning = null;
+        messages.push({
+          role: 'user',
+          content: [{ type: 'text', text: `[summary of earlier turns]\n${compaction.summary}` }],
+        });
+        recordStable(compaction.to);
+      }
+      continue;
+    }
+
+    switch (e.type) {
+      case 'user_prompt': {
+        flush();
+        pendingReasoning = null;
+        messages.push({ role: 'user', content: projectUserPrompt(e, el) });
+        recordStable(e.seq);
+        break;
+      }
+      case 'reasoning_message': {
+        // Render-only reasoning (no signature/encrypted) is never replayed —
+        // it exists only for the live/scrollback "Thinking" view. Replayable
+        // reasoning is stashed for content[0] of this turn's assistant message.
+        if (e.signature || e.encrypted) {
+          pendingReasoning = {
+            type: 'reasoning',
+            text: e.content,
+            ...(e.signature ? { signature: e.signature } : {}),
+            ...(e.redacted ? { redacted: true } : {}),
+            ...(e.encrypted ? { encrypted: e.encrypted } : {}),
+          };
+          pendingReasoningSeq = e.seq;
+        }
+        break;
+      }
+      case 'assistant_message':
+        flush();
+        if (conversationalStubbed(e, el)) {
+          pendingReasoning = null;
+          messages.push({
+            role: 'assistant',
+            content: [{ type: 'text', text: conversationalStub('assistant', e.seq) }],
+          });
+          recordStable(e.seq);
+          break;
+        }
+        // A tool-only turn can log an assistant_message with empty content
+        // (end_turn + tool calls, no prose). Projecting it as an empty text
+        // block makes some providers (Anthropic) reject the NEXT request and
+        // permanently wedges the session. Skip the block — the turn's
+        // tool_use blocks are projected from tool_call_requested events —
+        // which also un-wedges historical logs that already contain one.
+        if (e.content.trim().length === 0) {
+          pendingReasoning = null;
+          recordStable(e.seq);
+          break;
+        }
+        {
+          const content: Array<ProviderMessage['content'][number]> = [];
+          if (pendingReasoning) {
+            content.push(pendingReasoning);
+            pendingReasoning = null;
+          }
+          content.push({ type: 'text', text: e.content });
+          messages.push({ role: 'assistant', content });
+        }
+        recordStable(e.seq);
+        break;
+      case 'tool_call_requested': {
+        if (!pendingAssistant) {
+          // Seed the assistant turn so the signed reasoning block is content[0],
+          // ahead of every tool_use (Anthropic's interleaved-thinking ordering).
+          pendingAssistant = { role: 'assistant', content: pendingReasoning ? [pendingReasoning] : [] };
+          if (pendingReasoning) {
+            pendingAssistantMaxSeq = Math.max(pendingAssistantMaxSeq, pendingReasoningSeq);
+            pendingReasoning = null;
+          }
+        }
+        pendingAssistantMaxSeq = Math.max(pendingAssistantMaxSeq, e.seq);
+        (pendingAssistant.content as Array<ProviderMessage['content'][number]>).push({
+          type: 'tool_use',
+          id: e.callId,
+          name: e.name,
+          input: e.input,
+        });
+        break;
+      }
+      case 'tool_result': {
+        flush();
+        // Stub bulky old tool output to a recall-able marker (decision shared
+        // with estimateContextTokens via toolResultStubbed).
+        let text: string;
+        if (toolResultStubbed(e, el)) {
+          const recalled = el.recalledCallIds.has(e.callId) || el.recalledSeqs.has(e.seq);
+          text = toolResultStub(e.callId, toolResultBytes(e.output), recalled);
+        } else if (e.error) {
+          text = `[error:${e.error.kind}] ${e.error.message}`;
+        } else if (isToolDisplayResult(e.output)) {
+          // Rich result (e.g. a file diff): the model only needs the short
+          // `forModel` summary — the structured `display` is for channels.
+          text = e.output.forModel;
+        } else {
+          text = typeof e.output === 'string' ? e.output : JSON.stringify(e.output ?? '');
+        }
+        messages.push({
+          role: 'tool_result',
+          content: [{ type: 'tool_result', toolUseId: e.callId, content: text, isError: !e.ok }],
+        });
+        recordStable(e.seq);
+        break;
+      }
+      default:
+        break;
+    }
+  }
+  flush();
+
+  if (opts.trailingUserText) {
+    // The trailing step nudge is volatile (changes per step), never part of
+    // the stable prefix — don't record it.
+    messages.push({ role: 'user', content: [{ type: 'text', text: opts.trailingUserText }] });
+  }
+  return { messages, stablePrefixIndex };
+}

package/src/mode/single-shot.ts

@@ -0,0 +1,63 @@
+import type { ProviderMessage } from '../provider.js';
+import type { ModeContext } from '../mode.js';
+import { runCompactionIfNeeded } from '../compactor-helpers.js';
+import { runElisionIfNeeded } from '../elision-helpers.js';
+import { usageEventFields } from '../token-accounting.js';
+import { collectProviderStream } from './collect-stream.js';
+
+/**
+ * Run a single-shot (no-tools) provider turn — the shape every planner /
+ * synthesis phase shares. Runs context management (compaction + elision),
+ * emits the `provider_request` bookend, streams the response with tools
+ * disabled, then emits either an `error` event (returning `null`) or the
+ * `provider_response` bookend (returning the collected text).
+ *
+ * Replaces the ~40-line block each mode phase used to inline; centralizing it
+ * keeps event emission uniform and means a fix here (e.g. always running
+ * elision) lands for every loop strategy at once.
+ */
+export async function runSingleShotTurn(
+  ctx: ModeContext,
+  messages: ReadonlyArray<ProviderMessage>,
+  opts: { maxTokens?: number } = {},
+): Promise<string | null> {
+  await runCompactionIfNeeded(ctx);
+  await runElisionIfNeeded(ctx);
+
+  await ctx.emit({
+    type: 'provider_request',
+    sessionId: ctx.sessionId,
+    turnId: ctx.turnId,
+    source: 'system',
+    provider: ctx.provider.name,
+    model: ctx.model,
+  });
+
+  const { text, usage, error } = await collectProviderStream(ctx, messages, {
+    includeTools: false,
+    ...(opts.maxTokens !== undefined ? { maxTokens: opts.maxTokens } : {}),
+  });
+  if (error) {
+    await ctx.emit({
+      type: 'error',
+      sessionId: ctx.sessionId,
+      turnId: ctx.turnId,
+      source: 'system',
+      kind: error.retryable ? 'retryable' : 'fatal',
+      message: error.message,
+    });
+    return null;
+  }
+
+  await ctx.emit({
+    type: 'provider_response',
+    sessionId: ctx.sessionId,
+    turnId: ctx.turnId,
+    source: 'system',
+    provider: ctx.provider.name,
+    model: ctx.model,
+    ...usageEventFields(usage),
+  });
+
+  return text;
+}

package/src/mode/stable-hash.ts

@@ -0,0 +1,20 @@
+/**
+ * Stable, key-order-canonical hash of a tool call's input, so `{a:1,b:2}` and
+ * `{b:2,a:1}` produce the same key. Use for any "have I seen this call before"
+ * comparison — a raw `JSON.stringify` is NOT order-stable.
+ */
+export function stableHash(input: unknown): string {
+  return canonicalize(input);
+}
+
+function canonicalize(value: unknown): string {
+  if (value === null || value === undefined) return 'null';
+  if (typeof value !== 'object') return JSON.stringify(value);
+  if (Array.isArray(value)) {
+    return '[' + value.map(canonicalize).join(',') + ']';
+  }
+  const entries = Object.entries(value as Record<string, unknown>).sort(
+    ([a], [b]) => (a < b ? -1 : a > b ? 1 : 0),
+  );
+  return '{' + entries.map(([k, v]) => JSON.stringify(k) + ':' + canonicalize(v)).join(',') + '}';
+}

package/src/mode/stuck-loop.ts

@@ -0,0 +1,89 @@
+import { stableHash } from './stable-hash.js';
+
+/**
+ * Sliding-window detector for "model keeps making the same tool call".
+ *
+ * When the same `(toolName, input)` pair appears `repeatThreshold` times in
+ * the last `windowSize` calls, the model is almost certainly stuck — polling a
+ * tool that returns the same thing, mis-handling an error, etc. Bail early
+ * instead of burning through the iteration cap.
+ *
+ * Shared across every loop strategy so detection is uniform — previously each
+ * mode re-rolled this, and one copy used a non-canonical `JSON.stringify`
+ * signature that silently missed key-reordered repeats.
+ */
+export interface StuckSignal {
+  /** True when the loop guard should trip. */
+  readonly stuck: boolean;
+  /** Repeat count behind the trip — for the error message. */
+  readonly count: number;
+  /**
+   * `exact` = the same (tool, full-input) repeated `repeatThreshold` times.
+   * `near`  = the same (tool, identity arg — url / file_path / command / …)
+   *           repeated `nearThreshold` times while only volatile args (maxBytes,
+   *           timeoutMs) varied. Catches the "refetch the same URL with a bigger
+   *           maxBytes over and over" loop the exact check sails past.
+   */
+  readonly kind: 'exact' | 'near';
+}
+
+export interface StuckLoopDetector {
+  readonly windowSize: number;
+  readonly repeatThreshold: number;
+  /** Record the call and report whether the loop guard should trip. */
+  record(toolName: string, input: unknown): StuckSignal;
+}
+
+/** Identity arguments that pin "the same target" across volatile-arg variation,
+ *  best-first. The first present string field wins. */
+const IDENTITY_ARG_KEYS = ['url', 'file_path', 'path', 'command', 'cmd', 'query', 'pattern'];
+
+function identityArg(input: unknown): string | null {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) return null;
+  const o = input as Record<string, unknown>;
+  for (const k of IDENTITY_ARG_KEYS) {
+    const v = o[k];
+    if (typeof v === 'string' && v.trim().length > 0) return `${k}=${v}`;
+  }
+  return null;
+}
+
+export function createStuckLoopDetector(
+  opts: {
+    windowSize?: number;
+    repeatThreshold?: number;
+    nearWindowSize?: number;
+    nearThreshold?: number;
+  } = {},
+): StuckLoopDetector {
+  const windowSize = opts.windowSize ?? 8;
+  const repeatThreshold = opts.repeatThreshold ?? 3;
+  // Near-dups need a higher count + a wider window (they're spread out across a
+  // burst of other calls), and tolerate a couple of legit "bigger refetch" tries.
+  const nearWindowSize = opts.nearWindowSize ?? Math.max(windowSize * 2, 16);
+  const nearThreshold = opts.nearThreshold ?? Math.max(repeatThreshold + 2, 5);
+  const recent: string[] = [];
+  const recentNear: string[] = [];
+  return {
+    windowSize,
+    repeatThreshold,
+    record(toolName, input): StuckSignal {
+      const key = `${toolName}|${stableHash(input)}`;
+      recent.push(key);
+      if (recent.length > windowSize) recent.shift();
+      const exactCount = recent.filter((k) => k === key).length;
+      if (exactCount >= repeatThreshold) return { stuck: true, count: exactCount, kind: 'exact' };
+
+      let nearCount = 0;
+      const id = identityArg(input);
+      if (id !== null) {
+        const nearKey = `${toolName}|${id}`;
+        recentNear.push(nearKey);
+        if (recentNear.length > nearWindowSize) recentNear.shift();
+        nearCount = recentNear.filter((k) => k === nearKey).length;
+        if (nearCount >= nearThreshold) return { stuck: true, count: nearCount, kind: 'near' };
+      }
+      return { stuck: false, count: Math.max(exactCount, nearCount), kind: 'exact' };
+    },
+  };
+}