@moxxy/mode-default 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Moxxy (moxxy.ai)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,46 @@
+# @moxxy/mode-default
+
+The **default loop strategy** (mode) for [moxxy](https://moxxy.ai) — a Claude
+Code-style ReAct loop: the agent thinks, optionally calls tools, sees the
+results, and continues until it produces a final answer. It also handles
+retryable provider errors (e.g. 429s) with backoff.
+
+A "mode" is the turn-by-turn brain of a moxxy [`Session`](https://www.npmjs.com/package/@moxxy/core);
+register this one to get sensible default agent behaviour, or author your own
+against `@moxxy/sdk`'s `defineMode`.
+
+## Install
+
+```bash
+npm i @moxxy/core @moxxy/sdk @moxxy/mode-default
+```
+
+## Usage
+
+```ts
+import { Session, collectTurn, autoAllowResolver } from '@moxxy/core';
+import defaultModePlugin from '@moxxy/mode-default';
+import openaiPlugin from '@moxxy/plugin-provider-openai';
+
+const session = new Session({ cwd: process.cwd(), permissionResolver: autoAllowResolver });
+
+session.pluginHost.registerStatic(defaultModePlugin); // ← the loop strategy
+session.pluginHost.registerStatic(openaiPlugin);
+session.providers.setActive('openai', { apiKey: process.env.OPENAI_API_KEY });
+
+const events = await collectTurn(session, 'What is 2+2? Use a tool if you have one.');
+```
+
+The mode is selected automatically once registered (it registers as the default).
+To run a different strategy, register another mode package and switch with
+`session.modes.setActive(name)`.
+
+## Exports
+
+- `default` / `defaultModePlugin` — the moxxy plugin to register.
+- `defaultMode` — the underlying `Mode` (if you compose registries yourself).
+- `DEFAULT_MODE_NAME` — its registered name.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+import { type CollectedToolUse } from '@moxxy/sdk';
+import { DEFAULT_MODE_NAME } from './turn-iterator.js';
+export { DEFAULT_MODE_NAME };
+export type { CollectedToolUse };
+export declare const defaultMode: import("@moxxy/sdk").ModeDef;
+export declare const defaultModePlugin: import("@moxxy/sdk").Plugin;
+export default defaultModePlugin;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,gBAAgB,EACtB,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAkB,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAEvE,OAAO,EAAE,iBAAiB,EAAE,CAAC;AAC7B,YAAY,EAAE,gBAAgB,EAAE,CAAC;AAEjC,eAAO,MAAM,WAAW,8BAItB,CAAC;AAEH,eAAO,MAAM,iBAAiB,6BAI5B,CAAC;AAEH,eAAe,iBAAiB,CAAC"}

package/dist/index.js

@@ -0,0 +1,15 @@
+import { defineMode, definePlugin, } from '@moxxy/sdk';
+import { runDefaultMode, DEFAULT_MODE_NAME } from './turn-iterator.js';
+export { DEFAULT_MODE_NAME };
+export const defaultMode = defineMode({
+    name: DEFAULT_MODE_NAME,
+    description: 'Default ReAct-style loop: model thinks, calls tools, observes results, repeats',
+    run: runDefaultMode,
+});
+export const defaultModePlugin = definePlugin({
+    name: '@moxxy/mode-default',
+    version: '0.0.0',
+    modes: [defaultMode],
+});
+export default defaultModePlugin;
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,UAAU,EACV,YAAY,GAEb,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAEvE,OAAO,EAAE,iBAAiB,EAAE,CAAC;AAG7B,MAAM,CAAC,MAAM,WAAW,GAAG,UAAU,CAAC;IACpC,IAAI,EAAE,iBAAiB;IACvB,WAAW,EAAE,gFAAgF;IAC7F,GAAG,EAAE,cAAc;CACpB,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,iBAAiB,GAAG,YAAY,CAAC;IAC5C,IAAI,EAAE,qBAAqB;IAC3B,OAAO,EAAE,OAAO;IAChB,KAAK,EAAE,CAAC,WAAW,CAAC;CACrB,CAAC,CAAC;AAEH,eAAe,iBAAiB,CAAC"}

package/dist/turn-iterator.d.ts

@@ -0,0 +1,19 @@
+import { type ModeContext, type MoxxyEvent } from '@moxxy/sdk';
+export declare 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 declare const MAX_CONSECUTIVE_RETRIES = 6;
+/** Override the retry back-off sleep (test seam). Returns a restore fn. */
+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

@@ -0,0 +1 @@
+{"version":3,"file":"turn-iterator.d.ts","sourceRoot":"","sources":["../src/turn-iterator.ts"],"names":[],"mappings":"AAAA,OAAO,EAWL,KAAK,WAAW,EAChB,KAAK,UAAU,EAEhB,MAAM,YAAY,CAAC;AAEpB,eAAO,MAAM,iBAAiB,YAAY,CAAC;AAE3C;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,uBAAuB,IAAI,CAAC;AA0BzC,2EAA2E;AAC3E,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,CAqNjF"}

package/dist/turn-iterator.js

@@ -0,0 +1,250 @@
+import { buildSystemPromptWithSkills, collectProviderStream, createStuckLoopDetector, emitRequestsAndDetectStuck, executeToolUses, isContextOverflowError, projectMessages, runCompactionIfNeeded, runElisionIfNeeded, usageEventFields, } 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 schedule, capped — base*2^(attempt-1), attempt is 1-based. */
+function retryBackoffMs(attempt) {
+    const base = 500;
+    const cap = 30_000;
+    return Math.min(cap, base * 2 ** Math.max(0, attempt - 1));
+}
+// Abort-aware sleep, injectable for tests so the back-off path runs instantly
+// and deterministically. Production uses a real timer that clears on abort so a
+// pending back-off never outlives a cancelled turn.
+let sleepImpl = (ms, signal) => new Promise((resolve) => {
+    if (signal.aborted)
+        return resolve();
+    const timer = setTimeout(() => {
+        signal.removeEventListener('abort', onAbort);
+        resolve();
+    }, ms);
+    const onAbort = () => {
+        clearTimeout(timer);
+        resolve();
+    };
+    signal.addEventListener('abort', onAbort, { once: true });
+});
+/** Override the retry back-off sleep (test seam). Returns a restore fn. */
+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.
+    const maxIterations = ctx.maxIterations ?? 500;
+    const detector = createStuckLoopDetector();
+    // 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,
+        });
+        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) {
+                reactiveCompactions += 1;
+                const compacted = await runCompactionIfNeeded(ctx, { force: true });
+                if (compacted) {
+                    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(retryBackoffMs(consecutiveRetries), 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) {
+            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 } : {}) });
+}
+//# sourceMappingURL=turn-iterator.js.map

package/dist/turn-iterator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"turn-iterator.js","sourceRoot":"","sources":["../src/turn-iterator.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@moxxy/mode-default",
+  "version": "0.1.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",
+    "agent",
+    "mode",
+    "loop",
+    "react",
+    "tool-use"
+  ],
+  "homepage": "https://moxxy.ai",
+  "bugs": {
+    "url": "https://github.com/moxxy-ai/moxxy/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/moxxy-ai/moxxy.git",
+    "directory": "packages/mode-default"
+  },
+  "author": "Michal Makowski <michal.makowski97@gmail.com>",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "moxxy": {
+    "plugin": {
+      "entry": "./dist/index.js",
+      "kind": "mode"
+    }
+  },
+  "dependencies": {
+    "@moxxy/sdk": "0.15.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "typescript": "^5.7.3",
+    "vitest": "^2.1.8",
+    "zod": "^3.24.0",
+    "@moxxy/core": "0.3.0",
+    "@moxxy/testing": "0.0.25",
+    "@moxxy/tsconfig": "0.0.0",
+    "@moxxy/vitest-preset": "0.0.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "clean": "rm -rf dist .turbo"
+  }
+}

package/src/index.test.ts

@@ -0,0 +1,391 @@
+import { describe, expect, it, vi } from 'vitest';
+import { z } from 'zod';
+import { definePlugin, defineTool, type ProviderEvent } from '@moxxy/sdk';
+import { Session, autoAllowResolver, collectTurn, silentLogger } from '@moxxy/core';
+import { FakeProvider, textReply, toolUseReply, createFakeSession } from '@moxxy/testing';
+import { defaultModePlugin } from './index.js';
+import { MAX_CONSECUTIVE_RETRIES, __setRetrySleepForTests } from './turn-iterator.js';
+
+/** A scripted provider reply that surfaces a retryable error (e.g. a 429). */
+const retryableErrorReply = (message = 'rate limited (429)'): ReadonlyArray<ProviderEvent> => [
+  { type: 'message_start', model: 'fake' },
+  { type: 'error', message, retryable: true },
+  { type: 'message_end', stopReason: 'end_turn' },
+];
+
+const sessionWith = (provider: FakeProvider): Session => {
+  const session = createFakeSession({ provider });
+  session.pluginHost.registerStatic(defaultModePlugin);
+  return session;
+};
+
+describe('defaultMode end-to-end', () => {
+  it('runs a plain text turn and emits the expected event sequence', async () => {
+    const provider = new FakeProvider({ script: [textReply('hello there')] });
+    const session = sessionWith(provider);
+
+    const events = await collectTurn(session, 'hi');
+    const types = events.map((e) => e.type);
+
+    expect(types).toEqual([
+      'user_prompt',
+      'mode_iteration',
+      'provider_request',
+      'assistant_chunk',
+      'provider_response',
+      'assistant_message',
+    ]);
+    const last = events[events.length - 1];
+    if (last.type !== 'assistant_message') throw new Error('expected assistant_message last');
+    expect(last.content).toBe('hello there');
+    expect(last.stopReason).toBe('end_turn');
+  });
+
+  it('runs tool_use then continues loop with the result', async () => {
+    const provider = new FakeProvider({
+      script: [toolUseReply('echo', { msg: 'world' }, 'c1'), textReply('done: world')],
+    });
+    const session = sessionWith(provider);
+    session.tools.register(
+      defineTool({
+        name: 'echo',
+        description: 'returns msg',
+        inputSchema: z.object({ msg: z.string() }),
+        handler: (i) => i.msg,
+      }),
+    );
+
+    const events = await collectTurn(session, 'go');
+    const toolResult = events.find((e) => e.type === 'tool_result');
+    if (toolResult?.type !== 'tool_result') throw new Error('expected tool_result');
+    expect(toolResult.ok).toBe(true);
+    expect(toolResult.output).toBe('world');
+
+    const last = events[events.length - 1];
+    if (last.type !== 'assistant_message') throw new Error('expected assistant_message last');
+    expect(last.content).toBe('done: world');
+  });
+
+  it('records denial when permission resolver says no', async () => {
+    const provider = new FakeProvider({
+      script: [toolUseReply('Bash', { command: 'rm -rf /' }, 'c1'), textReply('aborted')],
+    });
+    const session = new Session({
+      cwd: '/tmp',
+      logger: silentLogger,
+      permissionResolver: { name: 'deny', async check() { return { mode: 'deny', reason: 'no shells' }; } },
+    });
+    session.pluginHost.registerStatic({
+      __moxxy: 'plugin' as const,
+      name: 'shim',
+      version: '0.0.0',
+      providers: [
+        {
+          name: provider.name,
+          models: [...provider.models],
+          createClient: () => provider,
+        },
+      ],
+    });
+    session.providers.setActive(provider.name);
+    session.pluginHost.registerStatic(defaultModePlugin);
+    session.tools.register(
+      defineTool({
+        name: 'Bash',
+        description: '',
+        inputSchema: z.object({ command: z.string() }),
+        handler: () => 'should not run',
+      }),
+    );
+
+    const events = await collectTurn(session, 'do it');
+    const denied = events.find((e) => e.type === 'tool_call_denied');
+    expect(denied).toBeDefined();
+    const result = events.find((e) => e.type === 'tool_result');
+    if (result?.type !== 'tool_result') throw new Error('expected tool_result');
+    expect(result.ok).toBe(false);
+    expect(result.error?.kind).toBe('denied');
+  });
+
+  it('handles tool handler throws as failure result', async () => {
+    const provider = new FakeProvider({
+      script: [toolUseReply('boom', {}, 'c1'), textReply('recovered')],
+    });
+    const session = sessionWith(provider);
+    session.tools.register(
+      defineTool({
+        name: 'boom',
+        description: '',
+        inputSchema: z.object({}),
+        handler: () => {
+          throw new Error('explode');
+        },
+      }),
+    );
+
+    const events = await collectTurn(session, 'go');
+    const result = events.find((e) => e.type === 'tool_result');
+    if (result?.type !== 'tool_result') throw new Error('expected tool_result');
+    expect(result.ok).toBe(false);
+    expect(result.error?.kind).toBe('threw');
+    expect(result.error?.message).toContain('explode');
+  });
+
+  it('aborts via stuck-loop detector when the model hammers the same call', async () => {
+    // The detector fires when the same (name, input) pair appears
+    // REPEAT_THRESHOLD times in the last WINDOW calls. A scripted
+    // provider that returns the same toolUse over and over is the
+    // canonical stuck-loop pattern — bail before burning the soft
+    // maxIterations cap.
+    const provider = new FakeProvider({
+      script: Array(20).fill(toolUseReply('loop', {}, 'cN')),
+    });
+    const session = sessionWith(provider);
+    session.tools.register(
+      defineTool({
+        name: 'loop',
+        description: '',
+        inputSchema: z.object({}),
+        handler: () => 'ok',
+      }),
+    );
+    void autoAllowResolver;
+
+    const events = await collectTurn(session, 'spin');
+    const errors = events.filter((e) => e.type === 'error');
+    expect(errors).toHaveLength(1);
+    if (errors[0]?.type !== 'error') throw new Error();
+    expect(errors[0].message).toMatch(/stuck pattern/);
+    // And the safety-net cap is still wired — exercise its message
+    // path by counting outgoing tool calls. The detector should fire
+    // around iteration 3, well below the 500-iteration cap.
+    const toolCalls = events.filter((e) => e.type === 'tool_call_requested');
+    expect(toolCalls.length).toBeLessThan(10);
+    // Regression: a stuck trip must NOT leave an orphan tool_call_requested.
+    // The detector fires AFTER the final request is emitted but the turn ends
+    // before executeToolUses runs it — without synthesizing a result, that
+    // request renders as a tool stuck "running" forever (and the provider
+    // rejects it next turn). Every emitted request must have a paired result.
+    const results = events.filter((e) => e.type === 'tool_result');
+    expect(results.length).toBe(toolCalls.length);
+  });
+
+  it('emits a paired result for every request even when the stuck loop trips', async () => {
+    // Distinct callIds per turn so the assertion is per-call, mirroring how the
+    // desktop fold (pair-events) matches tool_result back to tool_call_requested
+    // by callId. A leftover orphan here is the exact "tool spins forever, flips
+    // to error on the next message" symptom.
+    const provider = new FakeProvider({
+      script: Array.from({ length: 20 }, (_, i) => toolUseReply('loop', {}, `c${i}`)),
+    });
+    const session = sessionWith(provider);
+    session.tools.register(
+      defineTool({
+        name: 'loop',
+        description: '',
+        inputSchema: z.object({}),
+        handler: () => 'ok',
+      }),
+    );
+
+    const events = await collectTurn(session, 'spin');
+    const requestedIds = new Set(
+      events.filter((e) => e.type === 'tool_call_requested').map((e) => e.callId),
+    );
+    const resolvedIds = new Set(
+      events.filter((e) => e.type === 'tool_result').map((e) => e.callId),
+    );
+    // No requested call may be left without a result.
+    const orphans = [...requestedIds].filter((id) => !resolvedIds.has(id));
+    expect(orphans).toEqual([]);
+  });
+
+  it('respects an explicit maxIterations cap when no stuck loop fires', async () => {
+    // To hit the cap without tripping the detector, vary the input
+    // each iteration so the recent-calls window never sees a repeat.
+    const script = Array.from({ length: 60 }, (_, i) =>
+      toolUseReply('vary', { i }, `c${i}`),
+    );
+    const provider = new FakeProvider({ script });
+    const session = sessionWith(provider);
+    session.tools.register(
+      defineTool({
+        name: 'vary',
+        description: '',
+        inputSchema: z.object({ i: z.number() }),
+        handler: () => 'ok',
+      }),
+    );
+    void autoAllowResolver;
+
+    const events = await collectTurn(session, 'spin', { maxIterations: 3 });
+    const errors = events.filter((e) => e.type === 'error');
+    expect(errors).toHaveLength(1);
+    if (errors[0]?.type !== 'error') throw new Error();
+    expect(errors[0].message).toMatch(/maxIterations/);
+  });
+
+  it('executes tools even when provider reports stopReason: end_turn', async () => {
+    // Regression for the codex provider bug where Responses-API turns with
+    // tool calls were reported as `stop_reason: end_turn`. The loop must
+    // execute tools whenever they're requested, regardless of stopReason —
+    // otherwise a single provider mis-mapping leaves orphan
+    // tool_call_requested events and a stuck-looking pending dot.
+    const provider = new FakeProvider({
+      script: [
+        [
+          { type: 'message_start', model: 'fake' },
+          { type: 'tool_use_start', id: 'c1', name: 'echo' },
+          { type: 'tool_use_end', id: 'c1', input: { msg: 'hi' } },
+          // Note: end_turn, NOT tool_use — the bug scenario.
+          { type: 'message_end', stopReason: 'end_turn' },
+        ],
+        textReply('done'),
+      ],
+    });
+    const session = sessionWith(provider);
+    session.tools.register(
+      defineTool({
+        name: 'echo',
+        description: 'returns msg',
+        inputSchema: z.object({ msg: z.string() }),
+        handler: (i) => i.msg,
+      }),
+    );
+
+    const events = await collectTurn(session, 'go');
+    const requested = events.find((e) => e.type === 'tool_call_requested');
+    const result = events.find((e) => e.type === 'tool_result');
+    expect(requested).toBeDefined();
+    expect(result).toBeDefined();
+    if (result?.type !== 'tool_result') throw new Error('expected tool_result');
+    expect(result.ok).toBe(true);
+    expect(result.output).toBe('hi');
+  });
+
+  it('delivers hook-injected req.system to the provider without duplicating the system prompt', async () => {
+    const provider = new FakeProvider({ script: [textReply('ok')] });
+    const session = sessionWith(provider);
+    // The plugin-memory consolidation-nudge pattern: an onBeforeProviderCall
+    // hook appends to req.system. This must reach the provider request —
+    // previously the loop prefilled req.system with the system prompt and
+    // every provider dropped the field, so hook injections vanished.
+    session.pluginHost.registerStatic(
+      definePlugin({
+        name: '@moxxy/test-nudge',
+        version: '0.0.0',
+        hooks: {
+          onBeforeProviderCall: (req) => ({
+            ...req,
+            system: (req.system ?? '') + '[memory note] consider consolidating',
+          }),
+        },
+      }),
+    );
+
+    await collectTurn(session, 'hi', { systemPrompt: 'BASE PROMPT' });
+
+    expect(provider.received).toHaveLength(1);
+    const req = provider.received[0]!;
+    // The hook saw an UNSET req.system (no duplicated prompt) and its
+    // injection arrived verbatim.
+    expect(req.system).toBe('[memory note] consider consolidating');
+    // The composed system prompt still rides as the leading system message.
+    const first = req.messages[0]!;
+    expect(first.role).toBe('system');
+    expect(first.content[0]).toMatchObject({ type: 'text', text: 'BASE PROMPT' });
+  });
+
+  it('leaves req.system unset when no hook injects system text', async () => {
+    const provider = new FakeProvider({ script: [textReply('ok')] });
+    const session = sessionWith(provider);
+    await collectTurn(session, 'hi', { systemPrompt: 'BASE PROMPT' });
+    expect(provider.received[0]!.system).toBeUndefined();
+  });
+
+  it('emits abort event when session is aborted mid-stream', async () => {
+    const provider = new FakeProvider({
+      script: [toolUseReply('slow', {}, 'c1'), textReply('after')],
+    });
+    const session = sessionWith(provider);
+    session.tools.register(
+      defineTool({
+        name: 'slow',
+        description: '',
+        inputSchema: z.object({}),
+        handler: async () => {
+          await new Promise((r) => setTimeout(r, 1000));
+          return 'done';
+        },
+      }),
+    );
+
+    setTimeout(() => session.abort('test abort'), 20);
+    const events = await collectTurn(session, 'go');
+    const aborted = events.find((e) => e.type === 'abort');
+    // Either the abort fires before tool execution completes, or the tool_result has kind 'aborted'
+    const result = events.find((e) => e.type === 'tool_result');
+    if (result?.type === 'tool_result' && !result.ok) {
+      expect(result.error?.kind === 'aborted' || result.error?.kind === 'threw').toBe(true);
+    } else {
+      expect(aborted).toBeDefined();
+    }
+  });
+
+  it('backs off then recovers when a retryable provider error precedes a clean call', async () => {
+    const sleep = vi.fn(async () => {});
+    const restore = __setRetrySleepForTests(sleep);
+    try {
+      const provider = new FakeProvider({
+        script: [retryableErrorReply(), textReply('recovered')],
+      });
+      const session = sessionWith(provider);
+
+      const events = await collectTurn(session, 'hi');
+      // The retryable error was surfaced...
+      const retryable = events.filter((e) => e.type === 'error' && e.kind === 'retryable');
+      expect(retryable).toHaveLength(1);
+      // ...the loop waited before retrying (back-off applied, not a busy-loop)...
+      expect(sleep).toHaveBeenCalledTimes(1);
+      expect(sleep.mock.calls[0]![0]).toBeGreaterThan(0);
+      // ...and the next clean call succeeded.
+      const last = events[events.length - 1];
+      if (last.type !== 'assistant_message') throw new Error('expected assistant_message last');
+      expect(last.content).toBe('recovered');
+    } finally {
+      restore();
+    }
+  });
+
+  it('gives up with a fatal error after the bounded retry count, not maxIterations', async () => {
+    const delays: number[] = [];
+    const restore = __setRetrySleepForTests(async (ms) => {
+      delays.push(ms);
+    });
+    try {
+      // The provider returns a retryable error forever — without a bound this
+      // would busy-loop up to maxIterations (500) times.
+      const provider = new FakeProvider({
+        script: Array.from({ length: 50 }, () => retryableErrorReply()),
+      });
+      const session = sessionWith(provider);
+
+      const events = await collectTurn(session, 'hi');
+      const fatal = events.filter((e) => e.type === 'error' && e.kind === 'fatal');
+      expect(fatal).toHaveLength(1);
+      if (fatal[0]?.type !== 'error') throw new Error();
+      expect(fatal[0].message).toMatch(/giving up/i);
+      // It hit the provider exactly MAX_CONSECUTIVE_RETRIES times (one provider
+      // call per retry), nowhere near the 500-iteration cap.
+      expect(provider.received).toHaveLength(MAX_CONSECUTIVE_RETRIES);
+      // Back-off delays increased (exponential), proving real back-off ran on
+      // each attempt before the final give-up.
+      expect(delays).toHaveLength(MAX_CONSECUTIVE_RETRIES - 1);
+      for (let i = 1; i < delays.length; i++) {
+        expect(delays[i]!).toBeGreaterThan(delays[i - 1]!);
+      }
+    } finally {
+      restore();
+    }
+  });
+});

package/src/index.ts

@@ -0,0 +1,24 @@
+import {
+  defineMode,
+  definePlugin,
+  type CollectedToolUse,
+} from '@moxxy/sdk';
+
+import { runDefaultMode, DEFAULT_MODE_NAME } from './turn-iterator.js';
+
+export { DEFAULT_MODE_NAME };
+export type { CollectedToolUse };
+
+export const defaultMode = defineMode({
+  name: DEFAULT_MODE_NAME,
+  description: 'Default ReAct-style loop: model thinks, calls tools, observes results, repeats',
+  run: runDefaultMode,
+});
+
+export const defaultModePlugin = definePlugin({
+  name: '@moxxy/mode-default',
+  version: '0.0.0',
+  modes: [defaultMode],
+});
+
+export default defaultModePlugin;

package/src/turn-iterator.ts

@@ -0,0 +1,290 @@
+import {
+  buildSystemPromptWithSkills,
+  collectProviderStream,
+  createStuckLoopDetector,
+  emitRequestsAndDetectStuck,
+  executeToolUses,
+  isContextOverflowError,
+  projectMessages,
+  runCompactionIfNeeded,
+  runElisionIfNeeded,
+  usageEventFields,
+  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 schedule, capped — base*2^(attempt-1), attempt is 1-based. */
+function retryBackoffMs(attempt: number): number {
+  const base = 500;
+  const cap = 30_000;
+  return Math.min(cap, base * 2 ** Math.max(0, attempt - 1));
+}
+
+// Abort-aware sleep, injectable for tests so the back-off path runs instantly
+// and deterministically. Production uses a real timer that clears on abort so a
+// pending back-off never outlives a cancelled turn.
+let sleepImpl = (ms: number, signal: AbortSignal): Promise<void> =>
+  new Promise<void>((resolve) => {
+    if (signal.aborted) return resolve();
+    const timer = setTimeout(() => {
+      signal.removeEventListener('abort', onAbort);
+      resolve();
+    }, ms);
+    const onAbort = (): void => {
+      clearTimeout(timer);
+      resolve();
+    };
+    signal.addEventListener('abort', onAbort, { once: true });
+  });
+
+/** Override the retry back-off sleep (test seam). Returns a restore fn. */
+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.
+  const maxIterations = ctx.maxIterations ?? 500;
+  const detector = createStuckLoopDetector();
+  // 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,
+      },
+    );
+
+    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
+      ) {
+        reactiveCompactions += 1;
+        const compacted = await runCompactionIfNeeded(ctx, { force: true });
+        if (compacted) {
+          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(retryBackoffMs(consecutiveRetries), 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) {
+      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 } : {}) });
+}