@moxxy/mode-default 0.26.0 → 0.28.0

package/dist/turn-iterator.d.ts

@@ -1,25 +1,11 @@
 import { type ModeContext, type MoxxyEvent } from '@moxxy/sdk';
 export declare const DEFAULT_MODE_NAME = "default";
+export { MAX_CONSECUTIVE_RETRIES, __setRetrySleepForTests } from '@moxxy/sdk';
 /**
- * Bounded back-off for a *retryable* provider error (rate-limit/429,
- * overloaded, transient 5xx, ECONNRESET/ETIMEDOUT). Without it, a sustained
- * retryable condition becomes a tight busy-loop: the loop rebuilds the message
- * set and re-hits the provider with zero delay up to `maxIterations` times,
- * burning rate-limit budget and worsening the throttle. We back off
- * exponentially (abort-aware) and give up with a fatal error after
- * {@link MAX_CONSECUTIVE_RETRIES} consecutive failures — the counter resets on
- * any clean provider call, so a long turn can still recover from transient
- * blips. (The context-overflow path keeps its own MAX_REACTIVE_COMPACTIONS
- * budget and is handled before this.)
+ * Default ReAct-style loop: model thinks, calls tools, observes results,
+ * repeats — and returns the moment the model stops calling tools. Pure
+ * delegation to {@link runReactLoop} with no hooks and no checkpoints: the
+ * shared core IS the default behavior; other modes layer policy on top.
  */
-export declare const MAX_CONSECUTIVE_RETRIES = 6;
-/**
- * Override the retry back-off sleep (test seam). Returns a restore fn that
- * callers MUST invoke (in a `finally`) — `sleepImpl` is a module-scoped
- * singleton shared process-wide, so a leaked override bleeds the fake sleep
- * into every other turn/test running in the same worker (parallel subagent
- * fan-out, multiple Sessions in one host). Test-only; never call from prod.
- */
-export declare function __setRetrySleepForTests(fn: (ms: number, signal: AbortSignal) => Promise<void>): () => void;
 export declare function runDefaultMode(ctx: ModeContext): AsyncIterable<MoxxyEvent>;
 //# sourceMappingURL=turn-iterator.d.ts.map

package/dist/turn-iterator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"turn-iterator.d.ts","sourceRoot":"","sources":["../src/turn-iterator.ts"],"names":[],"mappings":"AAAA,OAAO,EAaL,KAAK,WAAW,EAChB,KAAK,UAAU,EAEhB,MAAM,YAAY,CAAC;AAEpB,eAAO,MAAM,iBAAiB,YAAY,CAAC;AAE3C;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,uBAAuB,IAAI,CAAC;AAYzC;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CACrC,EAAE,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,GACrD,MAAM,IAAI,CAMZ;AAED,wBAAuB,cAAc,CAAC,GAAG,EAAE,WAAW,GAAG,aAAa,CAAC,UAAU,CAAC,CAkQjF"}
+{"version":3,"file":"turn-iterator.d.ts","sourceRoot":"","sources":["../src/turn-iterator.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,WAAW,EAChB,KAAK,UAAU,EAChB,MAAM,YAAY,CAAC;AAEpB,eAAO,MAAM,iBAAiB,YAAY,CAAC;AAK3C,OAAO,EAAE,uBAAuB,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAE9E;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,WAAW,GAAG,aAAa,CAAC,UAAU,CAAC,CAE1E"}

package/dist/turn-iterator.js

@@ -1,282 +1,16 @@
-import { buildSystemPromptWithSkills, collectProviderStream, createStuckLoopDetector, emitRequestsAndDetectStuck, executeToolUses, isContextOverflowError, nextBackoffMs, projectMessages, runCompactionIfNeeded, runElisionIfNeeded, sleepWithAbort, usageEventFields, } from '@moxxy/sdk';
+import { runReactLoop, } from '@moxxy/sdk';
 export const DEFAULT_MODE_NAME = 'default';
+// The loop plumbing (bounded retry back-off, reactive compaction, elision,
+// stuck detection, abort handling) lives in the SDK's shared ReAct core —
+// re-export its constants/test seam so existing importers keep working.
+export { MAX_CONSECUTIVE_RETRIES, __setRetrySleepForTests } from '@moxxy/sdk';
 /**
- * Bounded back-off for a *retryable* provider error (rate-limit/429,
- * overloaded, transient 5xx, ECONNRESET/ETIMEDOUT). Without it, a sustained
- * retryable condition becomes a tight busy-loop: the loop rebuilds the message
- * set and re-hits the provider with zero delay up to `maxIterations` times,
- * burning rate-limit budget and worsening the throttle. We back off
- * exponentially (abort-aware) and give up with a fatal error after
- * {@link MAX_CONSECUTIVE_RETRIES} consecutive failures — the counter resets on
- * any clean provider call, so a long turn can still recover from transient
- * blips. (The context-overflow path keeps its own MAX_REACTIVE_COMPACTIONS
- * budget and is handled before this.)
+ * Default ReAct-style loop: model thinks, calls tools, observes results,
+ * repeats — and returns the moment the model stops calling tools. Pure
+ * delegation to {@link runReactLoop} with no hooks and no checkpoints: the
+ * shared core IS the default behavior; other modes layer policy on top.
  */
-export const MAX_CONSECUTIVE_RETRIES = 6;
-/** Exponential back-off base/cap for the retry schedule (attempt is 1-based). */
-const RETRY_BACKOFF_BASE_MS = 500;
-const RETRY_BACKOFF_CAP_MS = 30_000;
-// Abort-aware sleep, injectable for tests so the back-off path runs instantly
-// and deterministically. Production delegates to the SDK's sleepWithAbort: a
-// real timer that clears (and drops its abort listener) when the signal fires,
-// so a pending back-off never outlives a cancelled turn.
-let sleepImpl = (ms, signal) => sleepWithAbort(ms, signal);
-/**
- * Override the retry back-off sleep (test seam). Returns a restore fn that
- * callers MUST invoke (in a `finally`) — `sleepImpl` is a module-scoped
- * singleton shared process-wide, so a leaked override bleeds the fake sleep
- * into every other turn/test running in the same worker (parallel subagent
- * fan-out, multiple Sessions in one host). Test-only; never call from prod.
- */
-export function __setRetrySleepForTests(fn) {
-    const prev = sleepImpl;
-    sleepImpl = fn;
-    return () => {
-        sleepImpl = prev;
-    };
-}
-export async function* runDefaultMode(ctx) {
-    // High soft cap as a safety net against truly runaway modes (network
-    // glitch causing an infinite retry, bad prompt, etc.) — primary
-    // termination signal is the stuck-loop detector, which catches the
-    // common "model keeps calling the same tool" case ~10 iterations in.
-    // Coerce a caller/config-supplied bound to a positive integer; a degenerate
-    // value (0, negative, NaN, fractional) would otherwise make the loop never
-    // run and emit a misleading "exceeded maxIterations" fatal. Treat anything
-    // un-coercible (NaN) as the default rather than failing the turn.
-    const requestedMaxIterations = ctx.maxIterations;
-    const maxIterations = typeof requestedMaxIterations === 'number' && Number.isFinite(requestedMaxIterations)
-        ? Math.max(1, Math.floor(requestedMaxIterations))
-        : 500;
-    const detector = createStuckLoopDetector(ctx.loopGuard);
-    // Reactive-compaction budget per overflow episode. If the provider keeps
-    // rejecting for context size even after compacting this many times, give up
-    // (the overflow is in the recent, un-compactable tail). Reset on any clean
-    // provider call so a long turn can recover from multiple overflow episodes.
-    const MAX_REACTIVE_COMPACTIONS = 2;
-    let reactiveCompactions = 0;
-    // Consecutive retryable-error count; reset on any clean provider call. Caps
-    // the busy-loop a sustained retryable condition would otherwise create.
-    let consecutiveRetries = 0;
-    for (let iteration = 1; iteration <= maxIterations; iteration++) {
-        if (ctx.signal.aborted) {
-            yield await ctx.emit({
-                type: 'abort',
-                sessionId: ctx.sessionId,
-                turnId: ctx.turnId,
-                source: 'system',
-                reason: 'signal aborted',
-            });
-            return;
-        }
-        yield await ctx.emit({
-            type: 'mode_iteration',
-            sessionId: ctx.sessionId,
-            turnId: ctx.turnId,
-            source: 'system',
-            strategy: DEFAULT_MODE_NAME,
-            iteration,
-        });
-        // Auto-compact before composing the next provider request. If the
-        // active compactor's `shouldCompact` returns true, this appends a
-        // compaction event onto the log — projectMessagesFromLog (called
-        // by buildMessages) honors it, so the model sees a summarized
-        // prefix instead of overflowing the window mid-loop.
-        await runCompactionIfNeeded(ctx);
-        // Turn-boundary elision (context-on-demand): stub old bulky tool output and
-        // (when enabled) old text turns, recall-able on demand. Composes with
-        // compaction over the same projection.
-        await runElisionIfNeeded(ctx);
-        const { messages, stablePrefixIndex } = buildMessages(ctx);
-        yield await ctx.emit({
-            type: 'provider_request',
-            sessionId: ctx.sessionId,
-            turnId: ctx.turnId,
-            source: 'system',
-            provider: ctx.provider.name,
-            model: ctx.model,
-        });
-        const { text, toolUses, stopReason, error, usage, reasoning } = await collectProviderStream(ctx, messages, {
-            iteration,
-            stablePrefixIndex,
-        });
-        // A user cancellation WHILE the provider stream was being consumed surfaces
-        // as a non-retryable provider `error` ("The operation was aborted") rather
-        // than a clean abort — collectProviderStream catches the fetch AbortError
-        // and classifies it as fatal. Treat it as the cancellation it is so
-        // downstream channels render a 'stopped' turn, not a failed/error turn.
-        if (ctx.signal.aborted) {
-            yield await ctx.emit({
-                type: 'abort',
-                sessionId: ctx.sessionId,
-                turnId: ctx.turnId,
-                source: 'system',
-                reason: 'signal aborted during provider stream',
-            });
-            return;
-        }
-        yield await ctx.emit({
-            type: 'provider_response',
-            sessionId: ctx.sessionId,
-            turnId: ctx.turnId,
-            source: 'system',
-            provider: ctx.provider.name,
-            model: ctx.model,
-            ...usageEventFields(usage),
-        });
-        if (error) {
-            // The request was too big for the model's window: our token estimate
-            // lagged the provider's real tokenizer, so the proactive compactor
-            // didn't fire. Force a compaction and retry rather than dying — this is
-            // the auto-compact-on-overflow path.
-            if (isContextOverflowError(error.message) &&
-                reactiveCompactions < MAX_REACTIVE_COMPACTIONS) {
-                const compacted = await runCompactionIfNeeded(ctx, { force: true });
-                if (compacted) {
-                    // Only count an attempt that actually compacted against the budget —
-                    // a no-op (overflow lives in the un-compactable recent tail) must not
-                    // deny a later, genuinely compactable overflow its retry.
-                    reactiveCompactions += 1;
-                    yield await ctx.emit({
-                        type: 'error',
-                        sessionId: ctx.sessionId,
-                        turnId: ctx.turnId,
-                        source: 'system',
-                        kind: 'retryable',
-                        message: 'context window exceeded — compacted older turns, retrying',
-                    });
-                    continue;
-                }
-            }
-            if (!error.retryable) {
-                yield await ctx.emit({
-                    type: 'error',
-                    sessionId: ctx.sessionId,
-                    turnId: ctx.turnId,
-                    source: 'system',
-                    kind: 'fatal',
-                    message: error.message,
-                });
-                return;
-            }
-            // Retryable: surface it, then back off before retrying. A persistent
-            // retryable condition (sustained 429 / outage) must NOT busy-loop the
-            // provider — give up with a fatal error after the bounded retry count.
-            consecutiveRetries += 1;
-            yield await ctx.emit({
-                type: 'error',
-                sessionId: ctx.sessionId,
-                turnId: ctx.turnId,
-                source: 'system',
-                kind: 'retryable',
-                message: error.message,
-            });
-            if (consecutiveRetries >= MAX_CONSECUTIVE_RETRIES) {
-                yield await ctx.emit({
-                    type: 'error',
-                    sessionId: ctx.sessionId,
-                    turnId: ctx.turnId,
-                    source: 'system',
-                    kind: 'fatal',
-                    message: `provider kept returning a retryable error ${consecutiveRetries} times in a row ` +
-                        `(last: ${error.message}); giving up rather than hammering the provider.`,
-                });
-                return;
-            }
-            await sleepImpl(nextBackoffMs(consecutiveRetries, RETRY_BACKOFF_BASE_MS, RETRY_BACKOFF_CAP_MS), ctx.signal);
-            if (ctx.signal.aborted) {
-                yield await ctx.emit({
-                    type: 'abort',
-                    sessionId: ctx.sessionId,
-                    turnId: ctx.turnId,
-                    source: 'system',
-                    reason: 'signal aborted during retry back-off',
-                });
-                return;
-            }
-            continue;
-        }
-        // Clean provider call — reset the overflow-recovery + retry budgets.
-        reactiveCompactions = 0;
-        consecutiveRetries = 0;
-        // Finalize the reasoning summary for THIS call BEFORE the tool/assistant
-        // emits, so the log order is reasoning → tool_use → text (projection
-        // attaches the signed thinking block as content[0] of the same assistant
-        // turn). collectProviderStream already guards on non-empty text / encrypted.
-        if (reasoning) {
-            yield await ctx.emit({
-                type: 'reasoning_message',
-                sessionId: ctx.sessionId,
-                turnId: ctx.turnId,
-                source: 'model',
-                content: reasoning.text,
-                ...(reasoning.signature ? { signature: reasoning.signature } : {}),
-                ...(reasoning.redacted ? { redacted: true } : {}),
-                ...(reasoning.encrypted ? { encrypted: reasoning.encrypted } : {}),
-            });
-        }
-        const stuck = yield* emitRequestsAndDetectStuck(ctx, toolUses, detector, {
-            abortedResultMessage: 'default mode loop aborted (stuck pattern) before this call ran',
-            nearHint: 'against the same target (only volatile args like maxBytes varied)',
-            fatalMessage: ({ toolName, count, how }) => `default mode loop aborted — detected stuck pattern: tool "${toolName}" called ` +
-                `${count} times ${how}. The model is likely looping on the same call; ` +
-                `reset or rephrase.`,
-        });
-        if (stuck)
-            return;
-        if (text || stopReason === 'end_turn' || toolUses.length === 0) {
-            // A completion with no text, no tool uses, and a non-natural stop (e.g.
-            // 'max_tokens' truncated to nothing) yields a blank assistant bubble that
-            // silently swallows the truncation signal. Surface a retryable note so the
-            // user sees why the turn produced nothing, alongside the (preserved)
-            // empty assistant_message.
-            if (!text && toolUses.length === 0 && stopReason !== 'end_turn') {
-                yield await ctx.emit({
-                    type: 'error',
-                    sessionId: ctx.sessionId,
-                    turnId: ctx.turnId,
-                    source: 'system',
-                    kind: 'retryable',
-                    message: `provider returned an empty completion (stopReason: ${stopReason ?? 'unknown'})`,
-                });
-            }
-            yield await ctx.emit({
-                type: 'assistant_message',
-                sessionId: ctx.sessionId,
-                turnId: ctx.turnId,
-                source: 'model',
-                content: text,
-                stopReason,
-            });
-        }
-        // Execute whenever the model requested tools, regardless of stopReason.
-        // Providers vary in how reliably they report `stopReason: 'tool_use'`
-        // (Codex's Responses API doesn't carry one on `response.completed`, so
-        // the provider has to infer it from emitted events). Trusting only
-        // stopReason here meant a single provider mis-mapping silently dropped
-        // tool calls — `tool_call_requested` would be emitted with no matching
-        // `tool_result`, leaving an orphan pending dot and a stuck-looking UI.
-        if (toolUses.length === 0)
-            return;
-        const exited = yield* executeToolUses(ctx, toolUses, iteration);
-        if (exited)
-            return;
-    }
-    yield await ctx.emit({
-        type: 'error',
-        sessionId: ctx.sessionId,
-        turnId: ctx.turnId,
-        source: 'system',
-        kind: 'fatal',
-        message: `default mode loop exceeded maxIterations (${maxIterations})`,
-    });
-}
-function buildMessages(ctx) {
-    // Compose the system prompt with the skill catalog so the model knows
-    // which playbooks exist; without this skills are invisible to the
-    // model and it falls back to ad-hoc tool calls (the classic
-    // `web_fetch instead of media-digest skill` symptom).
-    const systemPrompt = buildSystemPromptWithSkills(ctx.systemPrompt, ctx.skills.list());
-    return projectMessages(ctx, { ...(systemPrompt ? { systemPrompt } : {}) });
+export function runDefaultMode(ctx) {
+    return runReactLoop(ctx, { strategyName: DEFAULT_MODE_NAME });
 }
 //# sourceMappingURL=turn-iterator.js.map

package/dist/turn-iterator.js.map

@@ -1 +1 @@
-{"version":3,"file":"turn-iterator.js","sourceRoot":"","sources":["../src/turn-iterator.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"turn-iterator.js","sourceRoot":"","sources":["../src/turn-iterator.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,YAAY,GAGb,MAAM,YAAY,CAAC;AAEpB,MAAM,CAAC,MAAM,iBAAiB,GAAG,SAAS,CAAC;AAE3C,2EAA2E;AAC3E,0EAA0E;AAC1E,wEAAwE;AACxE,OAAO,EAAE,uBAAuB,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAE9E;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,GAAgB;IAC7C,OAAO,YAAY,CAAC,GAAG,EAAE,EAAE,YAAY,EAAE,iBAAiB,EAAE,CAAC,CAAC;AAChE,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moxxy/mode-default",
-  "version": "0.26.0",
+  "version": "0.28.0",
   "description": "Default loop strategy (mode) for moxxy — a Claude Code-style ReAct tool-use loop. Register it into an @moxxy/core Session to give your agent its turn-by-turn reasoning + tool-calling behaviour.",
   "keywords": [
     "moxxy",
@@ -44,17 +44,17 @@
     }
   },
   "dependencies": {
-    "@moxxy/sdk": "0.26.0"
+    "@moxxy/sdk": "0.28.0"
   },
   "devDependencies": {
     "@types/node": "^22.10.0",
     "typescript": "^5.7.3",
     "vitest": "^2.1.8",
     "zod": "^3.24.0",
-    "@moxxy/testing": "0.0.44",
     "@moxxy/vitest-preset": "0.0.0",
-    "@moxxy/core": "0.26.0",
-    "@moxxy/tsconfig": "0.0.0"
+    "@moxxy/tsconfig": "0.0.0",
+    "@moxxy/testing": "0.0.46",
+    "@moxxy/core": "0.28.0"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",

package/src/react-loop-gate.test.ts

@@ -0,0 +1,458 @@
+import { describe, expect, it } from 'vitest';
+import { z } from 'zod';
+import {
+  defineMode,
+  definePlugin,
+  defineTool,
+  runReactLoop,
+  type CheckpointContext,
+  type CheckpointResult,
+  type ModeContext,
+  type ProviderEvent,
+  type TurnCheckpoint,
+} from '@moxxy/sdk';
+import { collectTurn, type Session } from '@moxxy/core';
+import { FakeProvider, createFakeSession, textReply, toolUseReply } from '@moxxy/testing';
+
+/**
+ * End-to-end coverage for the shared ReAct loop's turn-end checkpoint gate,
+ * exercised through a real Session + FakeProvider (the same harness the mode
+ * suites use) so every assertion runs against the events channels actually
+ * observe. The plain no-checkpoint path is covered by the mode-default suite
+ * (`index.test.ts`) — this file covers the gate.
+ */
+
+const GATED_MODE = 'gated-test';
+
+/** A text completion truncated by max_tokens — NOT a natural end_turn. */
+const truncatedTextReply = (text: string): ReadonlyArray<ProviderEvent> => [
+  { type: 'message_start', model: 'fake' },
+  { type: 'text_delta', delta: text },
+  { type: 'message_end', stopReason: 'max_tokens' },
+];
+
+/** Build a session whose active mode is runReactLoop + the given checkpoints. */
+function gatedSession(
+  provider: FakeProvider,
+  checkpoints: ReadonlyArray<TurnCheckpoint>,
+  opts: { maxInjections?: number; asSubagent?: boolean } = {},
+): Session {
+  const session = createFakeSession({ provider });
+  session.pluginHost.registerStatic(
+    definePlugin({
+      name: '@moxxy/mode-gated-test',
+      version: '0.0.0',
+      modes: [
+        defineMode({
+          name: GATED_MODE,
+          description: 'runReactLoop with test checkpoints',
+          run: (ctx: ModeContext) =>
+            runReactLoop(opts.asSubagent ? { ...ctx, isSubagent: true } : ctx, {
+              strategyName: GATED_MODE,
+              checkpoints,
+              ...(opts.maxInjections !== undefined ? { maxInjections: opts.maxInjections } : {}),
+            }),
+        }),
+      ],
+    }),
+  );
+  session.modes.setActive(GATED_MODE);
+  return session;
+}
+
+/** The turn's final assistant text (gate lifecycle events may follow it). */
+const lastAssistantText = (events: ReadonlyArray<{ type: string }>): string | undefined => {
+  const msgs = events.filter(
+    (e): e is { type: 'assistant_message'; content: string } => e.type === 'assistant_message',
+  );
+  return msgs[msgs.length - 1]?.content;
+};
+
+const checkpointSubtypes = (events: ReadonlyArray<{ type: string }>): string[] =>
+  events
+    .filter(
+      (e): e is { type: 'plugin_event'; subtype: string } =>
+        e.type === 'plugin_event' && String((e as { pluginId?: unknown }).pluginId) === 'react-loop',
+    )
+    .map((e) => e.subtype);
+
+describe('runReactLoop checkpoint gate', () => {
+  it('persistently injects feedback, loops, and passes on the fixed attempt', async () => {
+    const provider = new FakeProvider({ script: [textReply('draft answer'), textReply('fixed answer')] });
+    let calls = 0;
+    const lintGate: TurnCheckpoint = {
+      name: 'lint',
+      run: async (check) => {
+        calls += 1;
+        expect(check.stopReason).toBe('end_turn');
+        return calls === 1 ? { action: 'inject', text: 'lint failed: unused import' } : { action: 'pass' };
+      },
+    };
+    const session = gatedSession(provider, [lintGate]);
+
+    const events = await collectTurn(session, 'do the thing');
+
+    // The injected feedback is a real, persistent log event with checkpoint provenance…
+    const injected = events.filter(
+      (e) => e.type === 'user_prompt' && e.origin?.kind === 'checkpoint',
+    );
+    expect(injected).toHaveLength(1);
+    if (injected[0]?.type !== 'user_prompt') throw new Error('expected user_prompt');
+    expect(injected[0].text).toBe('lint failed: unused import');
+    expect(injected[0].source).toBe('system');
+    expect(injected[0].origin?.name).toBe('lint');
+
+    // …the loop ran a second provider round and the model saw the feedback…
+    expect(provider.received).toHaveLength(2);
+    const secondCallText = provider.received[1]!.messages
+      .flatMap((m) => m.content)
+      .map((c) => ('text' in c ? c.text : ''))
+      .join('\n');
+    expect(secondCallText).toContain('lint failed: unused import');
+
+    // …and the gate's lifecycle is observable.
+    expect(checkpointSubtypes(events)).toEqual([
+      'checkpoint_started',
+      'checkpoint_injected',
+      'checkpoint_started',
+      'checkpoint_passed',
+    ]);
+    expect(lastAssistantText(events)).toBe('fixed answer');
+  });
+
+  it('volatile injection rides exactly one provider call and never lands in the log', async () => {
+    const provider = new FakeProvider({
+      script: [textReply('first'), textReply('second'), textReply('third')],
+    });
+    let calls = 0;
+    const nudge: TurnCheckpoint = {
+      name: 'nudge',
+      run: async () => {
+        calls += 1;
+        if (calls < 3) return { action: 'inject', text: `keep going (${calls})`, volatile: true };
+        return { action: 'pass' };
+      },
+    };
+    const session = gatedSession(provider, [nudge]);
+
+    const events = await collectTurn(session, 'go');
+
+    // Never persisted…
+    expect(events.some((e) => e.type === 'user_prompt' && e.origin?.kind === 'checkpoint')).toBe(false);
+    // …but each nudge rode exactly its own next call.
+    const callTexts = provider.received.map((req) =>
+      req.messages.flatMap((m) => m.content).map((c) => ('text' in c ? c.text : '')).join('\n'),
+    );
+    expect(callTexts[0]).not.toContain('keep going');
+    expect(callTexts[1]).toContain('keep going (1)');
+    expect(callTexts[1]).not.toContain('keep going (2)');
+    expect(callTexts[2]).toContain('keep going (2)');
+    expect(callTexts[2]).not.toContain('keep going (1)');
+  });
+
+  it('retry loops again without injecting anything', async () => {
+    const provider = new FakeProvider({ script: [textReply('one'), textReply('two')] });
+    let calls = 0;
+    const retryOnce: TurnCheckpoint = {
+      name: 'retry-once',
+      gateOn: 'idle',
+      run: async () => (++calls === 1 ? { action: 'retry' } : { action: 'pass' }),
+    };
+    const session = gatedSession(provider, [retryOnce]);
+
+    const events = await collectTurn(session, 'go');
+
+    expect(provider.received).toHaveLength(2);
+    expect(events.some((e) => e.type === 'user_prompt' && e.origin?.kind === 'checkpoint')).toBe(false);
+    expect(checkpointSubtypes(events)).toEqual([
+      'checkpoint_started',
+      'checkpoint_retry',
+      'checkpoint_started',
+      'checkpoint_passed',
+    ]);
+  });
+
+  it('stop ends the turn immediately and skips remaining checkpoints', async () => {
+    const provider = new FakeProvider({ script: [textReply('answer')] });
+    let laterRan = false;
+    const stopper: TurnCheckpoint = {
+      name: 'stopper',
+      run: async () => ({ action: 'stop' }),
+    };
+    const later: TurnCheckpoint = {
+      name: 'later',
+      run: async () => {
+        laterRan = true;
+        return { action: 'pass' };
+      },
+    };
+    const session = gatedSession(provider, [stopper, later]);
+
+    const events = await collectTurn(session, 'go');
+
+    expect(provider.received).toHaveLength(1);
+    expect(laterRan).toBe(false);
+    expect(checkpointSubtypes(events)).toEqual(['checkpoint_started', 'checkpoint_stopped']);
+  });
+
+  it('exhausts the injection budget LOUDLY and ships the answer as-is', async () => {
+    const provider = new FakeProvider({
+      script: [textReply('v1'), textReply('v2'), textReply('v3')],
+    });
+    const alwaysRed: TurnCheckpoint = {
+      name: 'always-red',
+      run: async () => ({ action: 'inject', text: 'still failing' }),
+    };
+    const session = gatedSession(provider, [alwaysRed], { maxInjections: 2 });
+
+    const events = await collectTurn(session, 'go');
+
+    // Two injections spent, then the third candidate ends the turn with a warning.
+    expect(provider.received).toHaveLength(3);
+    expect(
+      events.filter((e) => e.type === 'user_prompt' && e.origin?.kind === 'checkpoint'),
+    ).toHaveLength(2);
+    const warning = events.find(
+      (e) => e.type === 'error' && e.message.includes('checkpoint budget exhausted'),
+    );
+    expect(warning).toBeDefined();
+    expect(lastAssistantText(events)).toBe('v3');
+  });
+
+  it('the injection budget is per idle-EPISODE: tool work resets it', async () => {
+    // Idle → inject → work → idle → inject → work → idle → inject → done.
+    // Three injections against maxInjections=2 — but never more than one per
+    // episode, so the budget (which exists to stop a no-progress wedge) must
+    // NOT trip. Before the reset, a long run died on its 3rd spread-out idle
+    // with "checkpoint budget exhausted" even though every nudge had worked.
+    const provider = new FakeProvider({
+      script: [
+        textReply('thinking 1'),
+        toolUseReply('work', { step: 1 }, 'w1'),
+        textReply('thinking 2'),
+        toolUseReply('work', { step: 2 }, 'w2'),
+        textReply('thinking 3'),
+        textReply('done'),
+      ],
+    });
+    const nudgeUnlessDone: TurnCheckpoint = {
+      name: 'nudge-unless-done',
+      gateOn: 'idle',
+      run: async (check): Promise<CheckpointResult> =>
+        check.candidateText === 'done'
+          ? { action: 'pass' }
+          : { action: 'inject', text: 'keep going' },
+    };
+    const session = gatedSession(provider, [nudgeUnlessDone], { maxInjections: 2 });
+    session.tools.register(
+      defineTool({
+        name: 'work',
+        description: '',
+        inputSchema: z.object({ step: z.number() }),
+        handler: () => 'ok',
+      }),
+    );
+
+    const events = await collectTurn(session, 'go');
+
+    // All three injections landed (the tool batches reset the budget)…
+    expect(
+      events.filter((e) => e.type === 'user_prompt' && e.origin?.kind === 'checkpoint'),
+    ).toHaveLength(3);
+    // …the run never hit the budget warning and finished naturally.
+    expect(
+      events.some((e) => e.type === 'error' && e.message.includes('checkpoint budget exhausted')),
+    ).toBe(false);
+    expect(lastAssistantText(events)).toBe('done');
+  });
+
+  it('a crashing checkpoint fails OPEN with a visible warning', async () => {
+    const provider = new FakeProvider({ script: [textReply('answer')] });
+    const broken: TurnCheckpoint = {
+      name: 'broken',
+      run: async () => {
+        throw new Error('boom');
+      },
+    };
+    const session = gatedSession(provider, [broken]);
+
+    const events = await collectTurn(session, 'go');
+
+    const warning = events.find(
+      (e) =>
+        e.type === 'error' &&
+        e.kind === 'retryable' &&
+        e.message.includes('checkpoint "broken" failed: boom — proceeding unchecked'),
+    );
+    expect(warning).toBeDefined();
+    expect(lastAssistantText(events)).toBe('answer');
+  });
+
+  it('a hung checkpoint times out and fails OPEN', async () => {
+    const provider = new FakeProvider({ script: [textReply('answer')] });
+    const hung: TurnCheckpoint = {
+      name: 'hung',
+      timeoutMs: 1_000, // the enforced floor — keeps the test fast-ish
+      run: (check: CheckpointContext) =>
+        new Promise<CheckpointResult>((_resolve, reject) => {
+          check.signal.addEventListener('abort', () => reject(new Error('aborted')), { once: true });
+        }),
+    };
+    const session = gatedSession(provider, [hung]);
+
+    const events = await collectTurn(session, 'go');
+
+    const warning = events.find(
+      (e) =>
+        e.type === 'error' &&
+        e.message.includes('checkpoint "hung" timed out after 1000ms — proceeding unchecked'),
+    );
+    expect(warning).toBeDefined();
+    expect(lastAssistantText(events)).toBe('answer');
+  }, 15_000);
+
+  it('empty injected feedback is ignored as a checker bug (fail open)', async () => {
+    const provider = new FakeProvider({ script: [textReply('answer')] });
+    const blank: TurnCheckpoint = {
+      name: 'blank',
+      run: async () => ({ action: 'inject', text: '   ' }),
+    };
+    const session = gatedSession(provider, [blank]);
+
+    const events = await collectTurn(session, 'go');
+
+    expect(provider.received).toHaveLength(1);
+    expect(
+      events.some(
+        (e) => e.type === 'error' && e.message.includes('checkpoint "blank" injected empty feedback'),
+      ),
+    ).toBe(true);
+    expect(events.some((e) => e.type === 'user_prompt' && e.origin?.kind === 'checkpoint')).toBe(false);
+  });
+
+  it('default gateOn skips truncated candidates; gateOn idle sees them', async () => {
+    const provider = new FakeProvider({ script: [truncatedTextReply('partial…')] });
+    let endTurnRan = false;
+    let idleRan = false;
+    let idleStopReason: string | undefined;
+    const endTurnGate: TurnCheckpoint = {
+      name: 'end-turn-only',
+      run: async () => {
+        endTurnRan = true;
+        return { action: 'pass' };
+      },
+    };
+    const idleGate: TurnCheckpoint = {
+      name: 'idle-too',
+      gateOn: 'idle',
+      run: async (check) => {
+        idleRan = true;
+        idleStopReason = check.stopReason;
+        return { action: 'pass' };
+      },
+    };
+    const session = gatedSession(provider, [endTurnGate, idleGate]);
+
+    await collectTurn(session, 'go');
+
+    expect(endTurnRan).toBe(false);
+    expect(idleRan).toBe(true);
+    expect(idleStopReason).toBe('max_tokens');
+  });
+
+  it('consecutiveIdle counts idle rounds and resets after a tool batch', async () => {
+    const provider = new FakeProvider({
+      script: [
+        textReply('idle once'),
+        toolUseReply('echo', { msg: 'work' }, 'c1'),
+        textReply('idle again'),
+      ],
+    });
+    const seen: number[] = [];
+    const recorder: TurnCheckpoint = {
+      name: 'recorder',
+      gateOn: 'idle',
+      run: async (check) => {
+        seen.push(check.consecutiveIdle);
+        return seen.length === 1 ? { action: 'retry' } : { action: 'pass' };
+      },
+    };
+    const session = gatedSession(provider, [recorder]);
+    session.tools.register(
+      defineTool({
+        name: 'echo',
+        description: 'returns msg',
+        inputSchema: z.object({ msg: z.string() }),
+        handler: (i) => i.msg,
+      }),
+    );
+
+    await collectTurn(session, 'go');
+
+    // Round 1 idles (consecutiveIdle 1), the retry round does real tool work
+    // (counter resets), the final idle round starts over at 1.
+    expect(seen).toEqual([1, 1]);
+  });
+
+  it('checkpoints are disarmed inside subagent sessions (recursion backstop)', async () => {
+    const provider = new FakeProvider({ script: [textReply('child answer')] });
+    let ran = false;
+    const recorder: TurnCheckpoint = {
+      name: 'recorder',
+      run: async () => {
+        ran = true;
+        return { action: 'pass' };
+      },
+    };
+    const session = gatedSession(provider, [recorder], { asSubagent: true });
+
+    const events = await collectTurn(session, 'go');
+
+    expect(ran).toBe(false);
+    expect(checkpointSubtypes(events)).toEqual([]);
+    const last = events[events.length - 1];
+    if (last?.type !== 'assistant_message') throw new Error('expected assistant_message last');
+    expect(last.content).toBe('child answer');
+  });
+
+  it('oversized feedback is clamped with an explicit truncation marker', async () => {
+    const provider = new FakeProvider({ script: [textReply('v1'), textReply('v2')] });
+    let calls = 0;
+    const chatty: TurnCheckpoint = {
+      name: 'chatty',
+      run: async () => (++calls === 1 ? { action: 'inject', text: 'x'.repeat(40_000) } : { action: 'pass' }),
+    };
+    const session = gatedSession(provider, [chatty]);
+
+    const events = await collectTurn(session, 'go');
+
+    const injected = events.find((e) => e.type === 'user_prompt' && e.origin?.kind === 'checkpoint');
+    if (injected?.type !== 'user_prompt') throw new Error('expected injected user_prompt');
+    expect(injected.text.length).toBeLessThan(17_000);
+    expect(injected.text).toContain('[checkpoint feedback truncated');
+  });
+
+  it('user abort during a checkpoint ends the turn quietly, keeping the answer', async () => {
+    const provider = new FakeProvider({ script: [textReply('answer')] });
+    const controller = new AbortController();
+    const aborter: TurnCheckpoint = {
+      name: 'aborter',
+      run: async () => {
+        controller.abort();
+        throw new Error('interrupted by user cancel');
+      },
+    };
+    const session = gatedSession(provider, [aborter]);
+
+    const events = await collectTurn(session, 'go', { signal: controller.signal });
+
+    // No "proceeding unchecked" noise — the cancel is not a checker failure…
+    expect(events.some((e) => e.type === 'error' && e.message.includes('proceeding unchecked'))).toBe(
+      false,
+    );
+    // …and the already-produced answer is not retracted.
+    expect(
+      events.some((e) => e.type === 'assistant_message' && e.content === 'answer'),
+    ).toBe(true);
+  });
+});

package/src/turn-iterator.ts

@@ -1,329 +1,22 @@
 import {
-  buildSystemPromptWithSkills,
-  collectProviderStream,
-  createStuckLoopDetector,
-  emitRequestsAndDetectStuck,
-  executeToolUses,
-  isContextOverflowError,
-  nextBackoffMs,
-  projectMessages,
-  runCompactionIfNeeded,
-  runElisionIfNeeded,
-  sleepWithAbort,
-  usageEventFields,
+  runReactLoop,
   type ModeContext,
   type MoxxyEvent,
-  type ProjectedMessages,
 } from '@moxxy/sdk';
 
 export const DEFAULT_MODE_NAME = 'default';
 
-/**
- * Bounded back-off for a *retryable* provider error (rate-limit/429,
- * overloaded, transient 5xx, ECONNRESET/ETIMEDOUT). Without it, a sustained
- * retryable condition becomes a tight busy-loop: the loop rebuilds the message
- * set and re-hits the provider with zero delay up to `maxIterations` times,
- * burning rate-limit budget and worsening the throttle. We back off
- * exponentially (abort-aware) and give up with a fatal error after
- * {@link MAX_CONSECUTIVE_RETRIES} consecutive failures — the counter resets on
- * any clean provider call, so a long turn can still recover from transient
- * blips. (The context-overflow path keeps its own MAX_REACTIVE_COMPACTIONS
- * budget and is handled before this.)
- */
-export const MAX_CONSECUTIVE_RETRIES = 6;
-
-/** Exponential back-off base/cap for the retry schedule (attempt is 1-based). */
-const RETRY_BACKOFF_BASE_MS = 500;
-const RETRY_BACKOFF_CAP_MS = 30_000;
-
-// Abort-aware sleep, injectable for tests so the back-off path runs instantly
-// and deterministically. Production delegates to the SDK's sleepWithAbort: a
-// real timer that clears (and drops its abort listener) when the signal fires,
-// so a pending back-off never outlives a cancelled turn.
-let sleepImpl = (ms: number, signal: AbortSignal): Promise<void> => sleepWithAbort(ms, signal);
+// The loop plumbing (bounded retry back-off, reactive compaction, elision,
+// stuck detection, abort handling) lives in the SDK's shared ReAct core —
+// re-export its constants/test seam so existing importers keep working.
+export { MAX_CONSECUTIVE_RETRIES, __setRetrySleepForTests } from '@moxxy/sdk';
 
 /**
- * Override the retry back-off sleep (test seam). Returns a restore fn that
- * callers MUST invoke (in a `finally`) — `sleepImpl` is a module-scoped
- * singleton shared process-wide, so a leaked override bleeds the fake sleep
- * into every other turn/test running in the same worker (parallel subagent
- * fan-out, multiple Sessions in one host). Test-only; never call from prod.
+ * Default ReAct-style loop: model thinks, calls tools, observes results,
+ * repeats — and returns the moment the model stops calling tools. Pure
+ * delegation to {@link runReactLoop} with no hooks and no checkpoints: the
+ * shared core IS the default behavior; other modes layer policy on top.
  */
-export function __setRetrySleepForTests(
-  fn: (ms: number, signal: AbortSignal) => Promise<void>,
-): () => void {
-  const prev = sleepImpl;
-  sleepImpl = fn;
-  return () => {
-    sleepImpl = prev;
-  };
-}
-
-export async function* runDefaultMode(ctx: ModeContext): AsyncIterable<MoxxyEvent> {
-  // High soft cap as a safety net against truly runaway modes (network
-  // glitch causing an infinite retry, bad prompt, etc.) — primary
-  // termination signal is the stuck-loop detector, which catches the
-  // common "model keeps calling the same tool" case ~10 iterations in.
-  // Coerce a caller/config-supplied bound to a positive integer; a degenerate
-  // value (0, negative, NaN, fractional) would otherwise make the loop never
-  // run and emit a misleading "exceeded maxIterations" fatal. Treat anything
-  // un-coercible (NaN) as the default rather than failing the turn.
-  const requestedMaxIterations = ctx.maxIterations;
-  const maxIterations =
-    typeof requestedMaxIterations === 'number' && Number.isFinite(requestedMaxIterations)
-      ? Math.max(1, Math.floor(requestedMaxIterations))
-      : 500;
-  const detector = createStuckLoopDetector(ctx.loopGuard);
-  // Reactive-compaction budget per overflow episode. If the provider keeps
-  // rejecting for context size even after compacting this many times, give up
-  // (the overflow is in the recent, un-compactable tail). Reset on any clean
-  // provider call so a long turn can recover from multiple overflow episodes.
-  const MAX_REACTIVE_COMPACTIONS = 2;
-  let reactiveCompactions = 0;
-  // Consecutive retryable-error count; reset on any clean provider call. Caps
-  // the busy-loop a sustained retryable condition would otherwise create.
-  let consecutiveRetries = 0;
-
-  for (let iteration = 1; iteration <= maxIterations; iteration++) {
-    if (ctx.signal.aborted) {
-      yield await ctx.emit({
-        type: 'abort',
-        sessionId: ctx.sessionId,
-        turnId: ctx.turnId,
-        source: 'system',
-        reason: 'signal aborted',
-      });
-      return;
-    }
-
-    yield await ctx.emit({
-      type: 'mode_iteration',
-      sessionId: ctx.sessionId,
-      turnId: ctx.turnId,
-      source: 'system',
-      strategy: DEFAULT_MODE_NAME,
-      iteration,
-    });
-
-    // Auto-compact before composing the next provider request. If the
-    // active compactor's `shouldCompact` returns true, this appends a
-    // compaction event onto the log — projectMessagesFromLog (called
-    // by buildMessages) honors it, so the model sees a summarized
-    // prefix instead of overflowing the window mid-loop.
-    await runCompactionIfNeeded(ctx);
-    // Turn-boundary elision (context-on-demand): stub old bulky tool output and
-    // (when enabled) old text turns, recall-able on demand. Composes with
-    // compaction over the same projection.
-    await runElisionIfNeeded(ctx);
-
-    const { messages, stablePrefixIndex } = buildMessages(ctx);
-    yield await ctx.emit({
-      type: 'provider_request',
-      sessionId: ctx.sessionId,
-      turnId: ctx.turnId,
-      source: 'system',
-      provider: ctx.provider.name,
-      model: ctx.model,
-    });
-
-    const { text, toolUses, stopReason, error, usage, reasoning } = await collectProviderStream(
-      ctx,
-      messages,
-      {
-        iteration,
-        stablePrefixIndex,
-      },
-    );
-
-    // A user cancellation WHILE the provider stream was being consumed surfaces
-    // as a non-retryable provider `error` ("The operation was aborted") rather
-    // than a clean abort — collectProviderStream catches the fetch AbortError
-    // and classifies it as fatal. Treat it as the cancellation it is so
-    // downstream channels render a 'stopped' turn, not a failed/error turn.
-    if (ctx.signal.aborted) {
-      yield await ctx.emit({
-        type: 'abort',
-        sessionId: ctx.sessionId,
-        turnId: ctx.turnId,
-        source: 'system',
-        reason: 'signal aborted during provider stream',
-      });
-      return;
-    }
-
-    yield await ctx.emit({
-      type: 'provider_response',
-      sessionId: ctx.sessionId,
-      turnId: ctx.turnId,
-      source: 'system',
-      provider: ctx.provider.name,
-      model: ctx.model,
-      ...usageEventFields(usage),
-    });
-
-    if (error) {
-      // The request was too big for the model's window: our token estimate
-      // lagged the provider's real tokenizer, so the proactive compactor
-      // didn't fire. Force a compaction and retry rather than dying — this is
-      // the auto-compact-on-overflow path.
-      if (
-        isContextOverflowError(error.message) &&
-        reactiveCompactions < MAX_REACTIVE_COMPACTIONS
-      ) {
-        const compacted = await runCompactionIfNeeded(ctx, { force: true });
-        if (compacted) {
-          // Only count an attempt that actually compacted against the budget —
-          // a no-op (overflow lives in the un-compactable recent tail) must not
-          // deny a later, genuinely compactable overflow its retry.
-          reactiveCompactions += 1;
-          yield await ctx.emit({
-            type: 'error',
-            sessionId: ctx.sessionId,
-            turnId: ctx.turnId,
-            source: 'system',
-            kind: 'retryable',
-            message: 'context window exceeded — compacted older turns, retrying',
-          });
-          continue;
-        }
-      }
-      if (!error.retryable) {
-        yield await ctx.emit({
-          type: 'error',
-          sessionId: ctx.sessionId,
-          turnId: ctx.turnId,
-          source: 'system',
-          kind: 'fatal',
-          message: error.message,
-        });
-        return;
-      }
-      // Retryable: surface it, then back off before retrying. A persistent
-      // retryable condition (sustained 429 / outage) must NOT busy-loop the
-      // provider — give up with a fatal error after the bounded retry count.
-      consecutiveRetries += 1;
-      yield await ctx.emit({
-        type: 'error',
-        sessionId: ctx.sessionId,
-        turnId: ctx.turnId,
-        source: 'system',
-        kind: 'retryable',
-        message: error.message,
-      });
-      if (consecutiveRetries >= MAX_CONSECUTIVE_RETRIES) {
-        yield await ctx.emit({
-          type: 'error',
-          sessionId: ctx.sessionId,
-          turnId: ctx.turnId,
-          source: 'system',
-          kind: 'fatal',
-          message:
-            `provider kept returning a retryable error ${consecutiveRetries} times in a row ` +
-            `(last: ${error.message}); giving up rather than hammering the provider.`,
-        });
-        return;
-      }
-      await sleepImpl(
-        nextBackoffMs(consecutiveRetries, RETRY_BACKOFF_BASE_MS, RETRY_BACKOFF_CAP_MS),
-        ctx.signal,
-      );
-      if (ctx.signal.aborted) {
-        yield await ctx.emit({
-          type: 'abort',
-          sessionId: ctx.sessionId,
-          turnId: ctx.turnId,
-          source: 'system',
-          reason: 'signal aborted during retry back-off',
-        });
-        return;
-      }
-      continue;
-    }
-    // Clean provider call — reset the overflow-recovery + retry budgets.
-    reactiveCompactions = 0;
-    consecutiveRetries = 0;
-
-    // Finalize the reasoning summary for THIS call BEFORE the tool/assistant
-    // emits, so the log order is reasoning → tool_use → text (projection
-    // attaches the signed thinking block as content[0] of the same assistant
-    // turn). collectProviderStream already guards on non-empty text / encrypted.
-    if (reasoning) {
-      yield await ctx.emit({
-        type: 'reasoning_message',
-        sessionId: ctx.sessionId,
-        turnId: ctx.turnId,
-        source: 'model',
-        content: reasoning.text,
-        ...(reasoning.signature ? { signature: reasoning.signature } : {}),
-        ...(reasoning.redacted ? { redacted: true } : {}),
-        ...(reasoning.encrypted ? { encrypted: reasoning.encrypted } : {}),
-      });
-    }
-
-    const stuck = yield* emitRequestsAndDetectStuck(ctx, toolUses, detector, {
-      abortedResultMessage: 'default mode loop aborted (stuck pattern) before this call ran',
-      nearHint: 'against the same target (only volatile args like maxBytes varied)',
-      fatalMessage: ({ toolName, count, how }) =>
-        `default mode loop aborted — detected stuck pattern: tool "${toolName}" called ` +
-        `${count} times ${how}. The model is likely looping on the same call; ` +
-        `reset or rephrase.`,
-    });
-    if (stuck) return;
-
-    if (text || stopReason === 'end_turn' || toolUses.length === 0) {
-      // A completion with no text, no tool uses, and a non-natural stop (e.g.
-      // 'max_tokens' truncated to nothing) yields a blank assistant bubble that
-      // silently swallows the truncation signal. Surface a retryable note so the
-      // user sees why the turn produced nothing, alongside the (preserved)
-      // empty assistant_message.
-      if (!text && toolUses.length === 0 && stopReason !== 'end_turn') {
-        yield await ctx.emit({
-          type: 'error',
-          sessionId: ctx.sessionId,
-          turnId: ctx.turnId,
-          source: 'system',
-          kind: 'retryable',
-          message: `provider returned an empty completion (stopReason: ${stopReason ?? 'unknown'})`,
-        });
-      }
-      yield await ctx.emit({
-        type: 'assistant_message',
-        sessionId: ctx.sessionId,
-        turnId: ctx.turnId,
-        source: 'model',
-        content: text,
-        stopReason,
-      });
-    }
-
-    // Execute whenever the model requested tools, regardless of stopReason.
-    // Providers vary in how reliably they report `stopReason: 'tool_use'`
-    // (Codex's Responses API doesn't carry one on `response.completed`, so
-    // the provider has to infer it from emitted events). Trusting only
-    // stopReason here meant a single provider mis-mapping silently dropped
-    // tool calls — `tool_call_requested` would be emitted with no matching
-    // `tool_result`, leaving an orphan pending dot and a stuck-looking UI.
-    if (toolUses.length === 0) return;
-
-    const exited = yield* executeToolUses(ctx, toolUses, iteration);
-    if (exited) return;
-  }
-
-  yield await ctx.emit({
-    type: 'error',
-    sessionId: ctx.sessionId,
-    turnId: ctx.turnId,
-    source: 'system',
-    kind: 'fatal',
-    message: `default mode loop exceeded maxIterations (${maxIterations})`,
-  });
-}
-
-function buildMessages(ctx: ModeContext): ProjectedMessages {
-  // Compose the system prompt with the skill catalog so the model knows
-  // which playbooks exist; without this skills are invisible to the
-  // model and it falls back to ad-hoc tool calls (the classic
-  // `web_fetch instead of media-digest skill` symptom).
-  const systemPrompt = buildSystemPromptWithSkills(ctx.systemPrompt, ctx.skills.list());
-  return projectMessages(ctx, { ...(systemPrompt ? { systemPrompt } : {}) });
+export function runDefaultMode(ctx: ModeContext): AsyncIterable<MoxxyEvent> {
+  return runReactLoop(ctx, { strategyName: DEFAULT_MODE_NAME });
 }