@moxxy/sdk 0.14.2 → 0.14.3

package/src/mode-helpers.ts

@@ -1,851 +1,33 @@
-import type { ContentBlock, ProviderEvent, ProviderMessage, TokenUsage } from './provider.js';
-import type { ModeContext } from './mode.js';
-import type { StopReason } from './provider-utils.js';
-import type { Skill } from './skill.js';
-import type { CompactionEvent, MoxxyEvent } from './events.js';
-import {
-  computeElisionState,
-  conversationalStub,
-  conversationalStubbed,
-  toolResultBytes,
-  toolResultStub,
-  toolResultStubbed,
-} from './elision-state.js';
-import { isToolDisplayResult } from './tool-display.js';
-import { applyLazyTools } from './tool-gating.js';
-import { runCompactionIfNeeded } from './compactor-helpers.js';
-import { runElisionIfNeeded } from './elision-helpers.js';
-import { usageEventFields } from './token-accounting.js';
-
-/**
- * Shared bits used by every loop strategy: a typed tool-use struct and a
- * common stream-collection helper that runs `onBeforeProviderCall` hooks
- * and reduces a provider stream down to `{text, toolUses, stopReason}`.
- *
- * Lives in core (not in each loop package) so a new loop strategy stays
- * consistent — and so behavioral fixes here propagate. Previously
- * loop-plan-execute had its own copy that skipped the hook (audit bug).
- */
-
-export interface CollectedToolUse {
-  readonly id: string;
-  readonly name: string;
-  readonly input: unknown;
-}
-
-/** 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;
-  };
-}
-
-/**
- * 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.
-  //
-  // 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.
-  const resolvedCallIds = new Set<string>();
-  for (const e of allEvents) {
-    if (e.type === 'tool_result' || e.type === 'tool_call_denied') {
-      resolvedCallIds.add(e.callId);
-    }
-  }
-
-  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;
-        // Elided + conversational: collapse to a stub (anchor/tiny kept full).
-        if (conversationalStubbed(e, el)) {
-          messages.push({
-            role: 'user',
-            content: [{ type: 'text', text: conversationalStub('user', e.seq) }],
-          });
-          recordStable(e.seq);
-          break;
-        }
-        const blocks: ContentBlock[] = [{ type: 'text', text: e.text }];
-        if (e.attachments) {
-          for (const att of e.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}`,
-              });
-            }
-          }
-        }
-        messages.push({ role: 'user', content: blocks });
-        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 };
-}
-
-export interface StreamResult {
-  readonly text: string;
-  readonly toolUses: ReadonlyArray<CollectedToolUse>;
-  readonly stopReason: StopReason;
-  readonly error: { readonly message: string; readonly retryable: boolean } | null;
-  /** Token usage reported by the provider on `message_end`, including cache hits/writes. */
-  readonly usage?: TokenUsage;
-  /**
-   * Reasoning/thinking summary for this provider call, when the model emitted
-   * any. The mode emits it as a `reasoning_message` event (so it persists and
-   * round-trips). `signature`/`encrypted` carry Anthropic's signed thinking
-   * block / redacted blob; `redacted` marks display-suppressed reasoning.
-   */
-  readonly reasoning?: {
-    readonly text: string;
-    readonly signature?: string;
-    readonly redacted?: boolean;
-    readonly encrypted?: string;
-  };
-}
-
-/**
- * Pulls a provider stream, emits `assistant_chunk` events for text deltas,
- * collects tool_use blocks, and returns the final `{text, toolUses, stopReason}`.
- * Runs `onBeforeProviderCall` lifecycle hooks before the call.
- */
-export async function collectProviderStream(
-  ctx: ModeContext,
-  messages: ReadonlyArray<ProviderMessage>,
-  opts: {
-    iteration?: number;
-    includeTools?: boolean;
-    maxTokens?: number;
-    /**
-     * Index (into `messages`) of the last stable-prefix message, from
-     * {@link projectMessages}. Passed to the active cache strategy as
-     * `stablePrefixMessageIndex` so it can place a long-lived cross-turn
-     * breakpoint at the elision boundary. Omit (or -1) when unknown — the
-     * strategy then falls back to its tools/system/tail breakpoints only.
-     */
-    stablePrefixIndex?: number;
-    /**
-     * Number of trailing messages in `messages` that are volatile — injected
-     * for this call only (e.g. goal mode's `trailingUserText` nudge) and
-     * absent from the append-only log, so they won't recur at the same
-     * position next call. Forwarded to the cache strategy as
-     * `volatileTailMessageCount` so it keeps its rolling tail breakpoint
-     * before them instead of paying a guaranteed-wasted cache write.
-     */
-    volatileTailCount?: number;
-  } = {},
-): Promise<StreamResult> {
-  // Lazy tool gating (opt-in): send only always-on + loaded tool schemas, and
-  // index the rest in the system prompt. Runs BEFORE cache planning since it
-  // rewrites the system message and the tool list.
-  let effectiveMessages = messages;
-  let toolList: ReadonlyArray<import('./tool.js').ToolDef> | undefined =
-    opts.includeTools === false ? undefined : ctx.tools.list();
-  if (ctx.lazyTools && toolList) {
-    const gated = applyLazyTools(messages, toolList, ctx.log);
-    effectiveMessages = gated.messages;
-    toolList = gated.tools;
-  }
-
-  // Ask the active cache strategy where to place prompt-cache breakpoints.
-  // The strategy is provider-neutral (returns CacheHints); the provider
-  // translates them (Anthropic → cache_control). Falls back to no hints when
-  // no strategy is registered. The onBeforeProviderCall hook can still adjust.
-  const descriptor = ctx.provider.models.find((m) => m.id === ctx.model);
-  const cacheHints = ctx.cacheStrategy
-    ? ctx.cacheStrategy.plan(effectiveMessages, {
-        model: ctx.model,
-        contextWindow: descriptor?.contextWindow ?? 0,
-        log: ctx.log,
-        ...(opts.stablePrefixIndex != null && opts.stablePrefixIndex >= 0
-          ? { stablePrefixMessageIndex: opts.stablePrefixIndex }
-          : {}),
-        ...(opts.volatileTailCount != null && opts.volatileTailCount > 0
-          ? { volatileTailMessageCount: opts.volatileTailCount }
-          : {}),
-      })
-    : undefined;
-
-  // NOTE: `system` is deliberately NOT prefilled with ctx.systemPrompt — the
-  // composed system prompt already rides as the leading system-role message
-  // (see projectMessages), and providers deliver `req.system` IN ADDITION to
-  // message-derived system text. Prefilling it would duplicate the prompt.
-  // It stays as the side channel `onBeforeProviderCall` hooks use to inject
-  // per-request system text (e.g. the memory consolidation nudge).
-  // Forward the per-provider reasoning preference, but only when THIS model
-  // advertises `supportsReasoning` — providers ignore the knob otherwise, but
-  // gating here keeps requests clean and avoids unsupported-param errors.
-  const reqReasoning = descriptor?.supportsReasoning ? ctx.reasoning : undefined;
-  const req = {
-    model: ctx.model,
-    messages: effectiveMessages,
-    ...(toolList ? { tools: toolList } : {}),
-    ...(cacheHints && cacheHints.length > 0 ? { cacheHints } : {}),
-    ...(opts.maxTokens !== undefined ? { maxTokens: opts.maxTokens } : {}),
-    ...(reqReasoning ? { reasoning: reqReasoning } : {}),
-    signal: ctx.signal,
-  };
-  const transformed = await ctx.hooks.dispatchBeforeProviderCall(req, {
-    sessionId: ctx.sessionId,
-    cwd: '',
-    log: ctx.log,
-    env: {},
-    turnId: ctx.turnId,
-    iteration: opts.iteration ?? 0,
-  });
-
-  let text = '';
-  const toolUses = new Map<string, { name?: string; input?: unknown }>();
-  let stopReason: StopReason = 'end_turn';
-  let error: StreamResult['error'] = null;
-  let usage: TokenUsage | undefined;
-  // Reasoning/thinking accumulation for this single provider call. Emitted as a
-  // finalized `reasoning_message` by the mode (turn-iterator / goal-loop) so it
-  // persists and round-trips; `signature`/`encrypted` carry Anthropic's signed
-  // thinking block / redacted blob for replay.
-  let reasoningText = '';
-  let reasoningSignature: string | undefined;
-  let reasoningRedacted = false;
-  let reasoningEncrypted: string | undefined;
-
-  let stream: AsyncIterable<ProviderEvent>;
-  try {
-    stream = ctx.provider.stream(transformed);
-  } catch (err) {
-    return {
-      text: '',
-      toolUses: [],
-      stopReason: 'error',
-      error: { message: err instanceof Error ? err.message : String(err), retryable: false },
-    };
-  }
-
-  try {
-    for await (const event of stream) {
-      switch (event.type) {
-        case 'text_delta': {
-          text += event.delta;
-          await ctx.emit({
-            type: 'assistant_chunk',
-            sessionId: ctx.sessionId,
-            turnId: ctx.turnId,
-            source: 'model',
-            delta: event.delta,
-          });
-          break;
-        }
-        case 'tool_use_start': {
-          toolUses.set(event.id, { name: event.name });
-          break;
-        }
-        case 'tool_use_end': {
-          const existing = toolUses.get(event.id) ?? {};
-          toolUses.set(event.id, { ...existing, input: event.input });
-          break;
-        }
-        case 'message_end': {
-          stopReason = event.stopReason;
-          if (event.usage) usage = event.usage;
-          break;
-        }
-        case 'error': {
-          error = { message: event.message, retryable: event.retryable };
-          break;
-        }
-        case 'reasoning_delta': {
-          reasoningText += event.delta;
-          // Live preview only — parallels `assistant_chunk`; renderers
-          // accumulate ephemerally and clear on the finalized reasoning_message.
-          await ctx.emit({
-            type: 'reasoning_chunk',
-            sessionId: ctx.sessionId,
-            turnId: ctx.turnId,
-            source: 'model',
-            delta: event.delta,
-          });
-          break;
-        }
-        case 'reasoning_signature': {
-          if (event.signature) reasoningSignature = event.signature;
-          if (event.encrypted) reasoningEncrypted = event.encrypted;
-          if (event.redacted) reasoningRedacted = true;
-          break;
-        }
-        case 'message_start':
-        case 'tool_use_delta':
-        default:
-          break;
-      }
-    }
-  } catch (err) {
-    error = {
-      message: err instanceof Error ? err.message : String(err),
-      retryable: false,
-    };
-  }
-
-  const finalToolUses: CollectedToolUse[] = [];
-  for (const [id, partial] of toolUses) {
-    if (!partial.name) continue;
-    finalToolUses.push({ id, name: partial.name, input: partial.input ?? {} });
-  }
-  // Surface reasoning when there's visible text OR an opaque blob to replay
-  // (a redacted_thinking block has no text but must still round-trip).
-  const reasoning =
-    reasoningText.trim().length > 0 || reasoningEncrypted
-      ? {
-          text: reasoningText,
-          ...(reasoningSignature ? { signature: reasoningSignature } : {}),
-          ...(reasoningRedacted ? { redacted: true } : {}),
-          ...(reasoningEncrypted ? { encrypted: reasoningEncrypted } : {}),
-        }
-      : undefined;
-  return {
-    text,
-    toolUses: finalToolUses,
-    stopReason,
-    error,
-    ...(usage ? { usage } : {}),
-    ...(reasoning ? { reasoning } : {}),
-  };
-}
-
-/**
- * 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;
-}
-
-/**
- * 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' };
-    },
-  };
-}
-
-/**
- * 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(',') + '}';
-}
+ * Barrel for the shared mode/loop helpers. The implementations now live in
+ * focused single-responsibility modules under `./mode/`; this file re-exports
+ * them so every existing `from './mode-helpers.js'` import (and the
+ * `@moxxy/sdk` index barrel) keeps working byte-identically.
+ *
+ *  - `./mode/project-messages.ts` — event-log → ProviderMessage projection
+ *  - `./mode/collect-stream.ts`   — provider-stream collection
+ *  - `./mode/single-shot.ts`      — single-shot (no-tools) provider turn
+ *  - `./mode/stuck-loop.ts`       — sliding-window stuck-tool-call detector
+ *  - `./mode/stable-hash.ts`      — key-order-canonical input hash util
+ */
+
+export {
+  ELISION_SYSTEM_NOTE,
+  buildSystemPromptWithSkills,
+  projectMessagesFromLog,
+  projectMessages,
+  type ProjectMessagesOptions,
+  type ProjectedMessages,
+} from './mode/project-messages.js';
+export {
+  collectProviderStream,
+  type CollectedToolUse,
+  type StreamResult,
+} from './mode/collect-stream.js';
+export { runSingleShotTurn } from './mode/single-shot.js';
+export {
+  createStuckLoopDetector,
+  type StuckLoopDetector,
+  type StuckSignal,
+} from './mode/stuck-loop.js';
+export { stableHash } from './mode/stable-hash.js';