@moxxy/sdk 0.27.0 → 0.28.1

package/src/mode/stuck-loop.ts

@@ -32,6 +32,13 @@ export interface StuckLoopDetector {
   readonly repeatThreshold: number;
   /** Record the call and report whether the loop guard should trip. */
   record(toolName: string, input: unknown): StuckSignal;
+  /**
+   * Clear both sliding windows. Used by the nudge (steer-don't-stop) stuck
+   * policy: after a trip is surfaced to the model, the detector starts a fresh
+   * episode — otherwise every subsequent call inside the still-full window
+   * would re-trip and re-nudge on each iteration.
+   */
+  reset(): void;
 }
 
 /**
@@ -102,5 +109,9 @@ export function createStuckLoopDetector(opts: LoopGuardSettings = {}): StuckLoop
       }
       return { stuck: false, count: Math.max(exactCount, nearCount), kind: 'exact' };
     },
+    reset(): void {
+      recent.length = 0;
+      recentNear.length = 0;
+    },
   };
 }

package/src/mode-helpers.ts

@@ -9,6 +9,8 @@
  *  - `./mode/single-shot.ts`      — single-shot (no-tools) provider turn
  *  - `./mode/stuck-loop.ts`       — sliding-window stuck-tool-call detector
  *  - `./mode/stable-hash.ts`      — key-order-canonical input hash util
+ *  - `./mode/react-loop.ts`       — the shared ReAct loop core (+ checkpoint gate)
+ *  - `./mode/checkpoint.ts`       — turn-end checkpoint contract
  */
 
 export {
@@ -33,3 +35,17 @@ export {
   type LoopGuardSettings,
 } from './mode/stuck-loop.js';
 export { stableHash } from './mode/stable-hash.js';
+export {
+  runReactLoop,
+  MAX_CONSECUTIVE_RETRIES,
+  __setRetrySleepForTests,
+  type ReactLoopOptions,
+  type ProviderSuccessInfo,
+  type ToolBatchInfo,
+  type StopDirective,
+} from './mode/react-loop.js';
+export type {
+  CheckpointContext,
+  CheckpointResult,
+  TurnCheckpoint,
+} from './mode/checkpoint.js';

package/src/mode.ts

@@ -131,14 +131,33 @@ export interface ModeContext {
    * Absent in synthetic test contexts that don't model a full Session.
    */
   readonly subagents?: SubagentSpawner;
+  /**
+   * True when this context belongs to a spawned child agent (set by the
+   * subagent runtime). The shared ReAct loop disarms turn-end checkpoints in
+   * subagent sessions — the recursion backstop that keeps a checkpoint which
+   * (mistakenly) spawns a child in a checkpoint-bearing mode from gating the
+   * child's turn-end and recursing forever.
+   */
+  readonly isSubagent?: boolean;
   /**
    * Request the session switch its active mode AFTER this turn fully drains.
    * Used by terminal workflow modes (BMAD finishing its last phase) to hand
    * control back to a normal mode so the next message isn't trapped in the
-   * workflow. The switch is applied post-turn by the runner; an unknown /
-   * unregistered mode name is ignored. Absent in synthetic test contexts.
+   * workflow, and by {@link ModeDef.transient} modes (goal) to disarm
+   * themselves once their objective concludes. The switch is applied
+   * post-turn by the runner; an unknown / unregistered mode name is ignored.
+   * Absent in synthetic test contexts.
    */
   readonly requestModeSwitch?: (modeName: string) => void;
+  /**
+   * Name of the mode that was active before the current one (per the mode
+   * registry), when known. Lets a {@link ModeDef.transient} mode hand control
+   * back to whatever the user was in before arming it (`/goal` from research
+   * mode reverts to research, not blindly to default). Absent when the
+   * registry has no history (first mode of the session) or in synthetic test
+   * contexts — callers should fall back to `'default'`.
+   */
+  readonly previousModeName?: string;
   emit(event: EmittedEvent): Promise<MoxxyEvent>;
 }
 
@@ -225,6 +244,21 @@ export interface ModeDef {
    * more later) opt in the same way. See {@link isSelectableMode}.
    */
   readonly special?: ModeSpecial;
+  /**
+   * Marks a mode that arms for a SINGLE objective rather than becoming the
+   * session's standing behavior (goal mode). Uniformly across surfaces:
+   *
+   *   - it is never persisted as the category default (`plugins.mode.default`)
+   *     — `/goal` once must not make every future session boot autonomous;
+   *   - a persisted/config default naming it is refused at boot (the
+   *     protected default stays active instead);
+   *   - the mode itself is expected to hand control back (via
+   *     `ctx.requestModeSwitch`, typically to `ctx.previousModeName`) when
+   *     its objective concludes.
+   *
+   * Switching INTO it (picker, `/goal`, `setMode` RPC) still works normally.
+   */
+  readonly transient?: boolean;
   run(ctx: ModeContext): AsyncIterable<MoxxyEvent>;
 }
 

package/src/tool-dispatch.test.ts

@@ -9,7 +9,10 @@ import {
   dispatchToolCall,
   executeToolUses,
   emitRequestsAndDetectStuck,
+  emitRequestsAndNudgeOnStuck,
   type StuckLoopReport,
+  type StuckNudgeReport,
+  type StuckTripInfo,
 } from './tool-dispatch.js';
 
 /**
@@ -213,3 +216,77 @@ describe('emitRequestsAndDetectStuck — stuck trip', () => {
     expect(events.filter((e) => e.type === 'tool_result')).toHaveLength(0);
   });
 });
+
+describe('emitRequestsAndNudgeOnStuck — steer, never stop', () => {
+  const nudgeReport: StuckNudgeReport = {
+    nearHint: 'with nearly identical input',
+    warnMessage: ({ toolName, count }) => `repetitive: ${toolName} x${count}`,
+    extraOnStuck: ({ toolName }) => [
+      {
+        type: 'plugin_event',
+        sessionId: asSessionId('s1'),
+        turnId: asTurnId('t1'),
+        source: 'plugin',
+        pluginId: 'test' as never,
+        subtype: 'test_stuck',
+        payload: { toolName },
+      },
+    ],
+  };
+
+  function nudgeDetector(trip: StuckSignal): StuckLoopDetector & { resets: number } {
+    const d = {
+      resets: 0,
+      record: () => trip,
+      reset: () => {
+        d.resets += 1;
+      },
+    };
+    return d as unknown as StuckLoopDetector & { resets: number };
+  }
+
+  it('on a trip: warns (retryable, not fatal), emits extra events, resets the detector, and does NOT synthesize results', async () => {
+    const { ctx, events } = makeCtx();
+    const det = nudgeDetector({ stuck: true, kind: 'exact', count: 8 });
+    const trip = (await drain(
+      emitRequestsAndNudgeOnStuck(ctx, [tool], det, nudgeReport),
+    )) as StuckTripInfo | null;
+
+    // Trip info is returned for the loop's volatile nudge…
+    expect(trip).toEqual({ toolName: 'Read', count: 8, kind: 'exact', how: 'with identical input' });
+    // …the detector started a fresh episode…
+    expect(det.resets).toBe(1);
+    // …the request stands (the batch will execute — no synthesized results)…
+    expect(events.some((e) => e.type === 'tool_call_requested')).toBe(true);
+    expect(events.filter((e) => e.type === 'tool_result')).toHaveLength(0);
+    // …the warning is visible but NON-fatal, with the extra event before it.
+    const err = events.find((e) => e.type === 'error') as
+      | { kind: string; message: string }
+      | undefined;
+    expect(err?.kind).toBe('retryable');
+    expect(err?.message).toBe('repetitive: Read x8');
+    expect(events.some((e) => e.type === 'plugin_event' && e.subtype === 'test_stuck')).toBe(true);
+  });
+
+  it('a near trip uses the report nearHint wording', async () => {
+    const { ctx } = makeCtx();
+    const trip = (await drain(
+      emitRequestsAndNudgeOnStuck(
+        ctx,
+        [tool],
+        nudgeDetector({ stuck: true, kind: 'near', count: 5 }),
+        nudgeReport,
+      ),
+    )) as StuckTripInfo | null;
+    expect(trip?.how).toBe('with nearly identical input');
+  });
+
+  it('returns null and stays quiet when the detector does not trip', async () => {
+    const { ctx, events } = makeCtx();
+    const det = nudgeDetector({ stuck: false, kind: 'exact', count: 0 });
+    const trip = await drain(emitRequestsAndNudgeOnStuck(ctx, [tool], det, nudgeReport));
+    expect(trip).toBeNull();
+    expect(det.resets).toBe(0);
+    expect(events.filter((e) => e.type !== 'tool_call_requested')).toHaveLength(0);
+  });
+});

package/src/tool-dispatch.ts

@@ -2,7 +2,11 @@ import { asToolCallId } from './ids.js';
 import type { EmittedEvent, MoxxyEvent } from './events.js';
 import type { ModeContext } from './mode.js';
 import type { ToolCallVerdict } from './hooks.js';
-import type { CollectedToolUse, StuckLoopDetector, StuckSignal } from './mode-helpers.js';
+// Import the concrete modules, not the './mode-helpers.js' barrel: the barrel
+// re-exports the ReAct loop core, which imports THIS file — going through the
+// barrel here closes that loop into a real import cycle.
+import type { CollectedToolUse } from './mode/collect-stream.js';
+import type { StuckLoopDetector, StuckSignal } from './mode/stuck-loop.js';
 
 /**
  * Execute a single tool-use end-to-end: dispatch `dispatchToolCall` hooks, run
@@ -282,3 +286,80 @@ export async function* emitRequestsAndDetectStuck(
   }
   return false;
 }
+
+/** A stuck-detector trip, as surfaced to the nudge policy. */
+export interface StuckTripInfo {
+  readonly toolName: string;
+  readonly count: number;
+  readonly kind: StuckSignal['kind'];
+  /** Human phrasing of HOW it repeated ("with identical input" / the near hint). */
+  readonly how: string;
+}
+
+/** Wording + extra events for {@link emitRequestsAndNudgeOnStuck}. */
+export interface StuckNudgeReport {
+  /** Explanation for a `near` match (an `exact` match always reads
+   *  "with identical input"). */
+  readonly nearHint: string;
+  /** Build the visible (non-fatal) warning surfaced to the user on a trip. */
+  readonly warnMessage: (info: StuckTripInfo) => string;
+  /** Extra events to emit right before the warning — goal mode surfaces a
+   *  `goal_stuck` plugin_event here. */
+  readonly extraOnStuck?: StuckLoopReport['extraOnStuck'];
+}
+
+/**
+ * The steer-don't-stop counterpart of {@link emitRequestsAndDetectStuck}: emit
+ * a `tool_call_requested` per call and feed the detector, but a trip NEVER
+ * aborts the turn — the batch still executes (the repeated calls are usually
+ * legitimate work, e.g. re-running a failing build between edits). Instead the
+ * trip is surfaced as a visible warning + the report's extra events, the
+ * detector is reset (fresh episode — no re-trip on every subsequent call while
+ * the window is still full), and the trip info is returned so the loop can
+ * steer the model with a volatile nudge on its next provider call.
+ *
+ * Used by modes that must never kill an unattended run on a repetition
+ * heuristic (goal mode). Returns the first trip of the batch, or null.
+ */
+export async function* emitRequestsAndNudgeOnStuck(
+  ctx: ModeContext,
+  toolUses: ReadonlyArray<CollectedToolUse>,
+  detector: StuckLoopDetector,
+  report: StuckNudgeReport,
+): AsyncGenerator<MoxxyEvent, StuckTripInfo | null, unknown> {
+  let trip: StuckTripInfo | null = null;
+  for (const t of toolUses) {
+    yield await ctx.emit({
+      type: 'tool_call_requested',
+      sessionId: ctx.sessionId,
+      turnId: ctx.turnId,
+      source: 'model',
+      callId: asToolCallId(t.id),
+      name: t.name,
+      input: t.input,
+    });
+    const sig = detector.record(t.name, t.input);
+    if (!sig.stuck || trip) continue;
+    trip = {
+      toolName: t.name,
+      count: sig.count,
+      kind: sig.kind,
+      how: sig.kind === 'near' ? report.nearHint : 'with identical input',
+    };
+    detector.reset();
+    if (report.extraOnStuck) {
+      for (const e of report.extraOnStuck({ toolName: t.name, count: sig.count, kind: sig.kind })) {
+        yield await ctx.emit(e);
+      }
+    }
+    yield await ctx.emit({
+      type: 'error',
+      sessionId: ctx.sessionId,
+      turnId: ctx.turnId,
+      source: 'system',
+      kind: 'retryable',
+      message: report.warnMessage(trip),
+    });
+  }
+  return trip;
+}