@moxxy/sdk 0.44.0 → 0.46.0

package/src/mode/checkpoint-gate.ts

@@ -0,0 +1,198 @@
+import { asPluginId } from '../ids.js';
+import type { MoxxyEvent } from '../events.js';
+import type { ModeContext } from '../mode.js';
+import type { StopReason } from '../provider-utils.js';
+import type { CheckpointResult, TurnCheckpoint } from './checkpoint.js';
+
+/**
+ * The turn-end checkpoint gate and the loop's own lifecycle events, shared by
+ * the ReAct loop and the agent-connection loop.
+ */
+
+const DEFAULT_CHECKPOINT_TIMEOUT_MS = 120_000;
+const CHECKPOINT_EVENT_PLUGIN_ID = asPluginId('react-loop');
+
+/** Gate outcome: end the turn, or loop again (optionally with a volatile nudge). */
+export type GateVerdict = { readonly kind: 'end' } | { readonly kind: 'loop'; readonly volatileText?: string };
+
+export interface GateRound {
+  readonly candidateText: string;
+  readonly stopReason: StopReason;
+  readonly iteration: number;
+  readonly consecutiveIdle: number;
+  readonly injectionsUsed: number;
+  readonly injectionBudget: number;
+  readonly maxInjectChars: number;
+}
+
+export async function* runCheckpointGate(
+  ctx: ModeContext,
+  checkpoints: ReadonlyArray<TurnCheckpoint>,
+  round: GateRound,
+): AsyncGenerator<MoxxyEvent, GateVerdict> {
+  // Natural completions face every checkpoint; truncated/errored candidates
+  // only face the idle-tolerant ones — reviewing a half-sentence as if it
+  // were a completion claim wastes a checker run and confuses the model.
+  const eligible = checkpoints.filter(
+    (cp) =>
+      (round.stopReason === 'end_turn' || (cp.gateOn ?? 'end_turn') === 'idle') && (cp.applies?.(ctx) ?? true),
+  );
+  if (eligible.length === 0) return { kind: 'end' };
+
+  // Budget exhausted → the answer ships as-is, but LOUDLY: silent
+  // degradation would let the user believe a gated answer passed its gates.
+  if (round.injectionsUsed >= round.injectionBudget) {
+    yield await emitError(
+      ctx,
+      'retryable',
+      `checkpoint budget exhausted (${round.injectionBudget} rounds) — ` +
+        `ending the turn with unresolved checkpoint feedback; verify the result manually.`,
+    );
+    return { kind: 'end' };
+  }
+
+  for (const cp of eligible) {
+    // User cancelled mid-gate: end the turn WITHOUT retracting the
+    // already-logged answer — an abort must never un-say what was said.
+    if (ctx.signal.aborted) return { kind: 'end' };
+
+    yield await emitCheckpointEvent(ctx, 'checkpoint_started', {
+      name: cp.name,
+      iteration: round.iteration,
+    });
+
+    const timeoutMs = Math.max(1_000, cp.timeoutMs ?? DEFAULT_CHECKPOINT_TIMEOUT_MS);
+    const timeoutCtl = new AbortController();
+    const timer = setTimeout(() => timeoutCtl.abort(), timeoutMs);
+    timer.unref?.();
+    let result: CheckpointResult;
+    try {
+      result = await cp.run(
+        {
+          candidateText: round.candidateText,
+          stopReason: round.stopReason,
+          iteration: round.iteration,
+          consecutiveIdle: round.consecutiveIdle,
+          injectionsUsed: round.injectionsUsed,
+          injectionBudget: round.injectionBudget,
+          signal: AbortSignal.any([ctx.signal, timeoutCtl.signal]),
+        },
+        ctx,
+      );
+    } catch (err) {
+      if (ctx.signal.aborted) return { kind: 'end' };
+      // Fail OPEN, visibly. A crashed or timed-out checker downgrades the
+      // gate to a warning — it must never wedge the turn (fail-closed is a
+      // turn that can never end) and never crash it (the answer is already
+      // logged).
+      const why = timeoutCtl.signal.aborted
+        ? `timed out after ${timeoutMs}ms`
+        : `failed: ${err instanceof Error ? err.message : String(err)}`;
+      yield await emitError(ctx, 'retryable', `checkpoint "${cp.name}" ${why} — proceeding unchecked`);
+      continue;
+    } finally {
+      clearTimeout(timer);
+    }
+
+    switch (result.action) {
+      case 'pass': {
+        yield await emitCheckpointEvent(ctx, 'checkpoint_passed', { name: cp.name });
+        continue;
+      }
+      case 'stop': {
+        // The checkpoint already emitted its own wrap-up events.
+        yield await emitCheckpointEvent(ctx, 'checkpoint_stopped', { name: cp.name });
+        return { kind: 'end' };
+      }
+      case 'retry': {
+        yield await emitCheckpointEvent(ctx, 'checkpoint_retry', { name: cp.name });
+        return { kind: 'loop' };
+      }
+      case 'inject': {
+        // Guard the guard: an inject with blank text would loop the turn
+        // with no new signal for the model — a checker bug; fail open.
+        const feedback = result.text?.trim();
+        if (!feedback) {
+          yield await emitError(
+            ctx,
+            'retryable',
+            `checkpoint "${cp.name}" injected empty feedback — ignored`,
+          );
+          continue;
+        }
+        const clamped = clampChars(feedback, round.maxInjectChars);
+        if (result.volatile) {
+          yield await emitCheckpointEvent(ctx, 'checkpoint_injected', {
+            name: cp.name,
+            volatile: true,
+          });
+          return { kind: 'loop', volatileText: clamped };
+        }
+        // Persistent: a checkpoint-origin user prompt. Projected as a
+        // user-role message by the existing projection case, marked via the
+        // same `origin` machinery trigger prompts use, cache-safe because it
+        // is an ordinary append at the log tail.
+        yield await ctx.emit({
+          type: 'user_prompt',
+          sessionId: ctx.sessionId,
+          turnId: ctx.turnId,
+          source: 'system',
+          text: clamped,
+          origin: { kind: 'checkpoint', name: cp.name },
+        });
+        yield await emitCheckpointEvent(ctx, 'checkpoint_injected', {
+          name: cp.name,
+          volatile: false,
+        });
+        return { kind: 'loop' };
+      }
+    }
+  }
+  return { kind: 'end' };
+}
+
+function clampChars(text: string, max: number): string {
+  if (text.length <= max) return text;
+  return `${text.slice(0, max)}\n…[checkpoint feedback truncated: ${text.length - max} chars dropped]`;
+}
+
+export async function emitAbort(ctx: ModeContext, reason: string): Promise<MoxxyEvent> {
+  return ctx.emit({
+    type: 'abort',
+    sessionId: ctx.sessionId,
+    turnId: ctx.turnId,
+    source: 'system',
+    reason,
+  });
+}
+
+export async function emitError(
+  ctx: ModeContext,
+  kind: 'retryable' | 'fatal',
+  message: string,
+): Promise<MoxxyEvent> {
+  return ctx.emit({
+    type: 'error',
+    sessionId: ctx.sessionId,
+    turnId: ctx.turnId,
+    source: 'system',
+    kind,
+    message,
+  });
+}
+
+export async function emitCheckpointEvent(
+  ctx: ModeContext,
+  subtype: string,
+  payload: unknown,
+): Promise<MoxxyEvent> {
+  return ctx.emit({
+    type: 'plugin_event',
+    sessionId: ctx.sessionId,
+    turnId: ctx.turnId,
+    source: 'system',
+    pluginId: CHECKPOINT_EVENT_PLUGIN_ID,
+    subtype,
+    payload,
+  });
+}

package/src/mode/checkpoint.ts

@@ -101,6 +101,12 @@ export interface TurnCheckpoint {
    * (goal/collab-style stall handling wants these too).
    */
   readonly gateOn?: 'end_turn' | 'idle';
+  /**
+   * Also gate turns done by a vendor's agent (an agent connection). Off by
+   * default: the agent decides when its turn is done, as in its own tool, so
+   * Moxxy's end-of-turn reminders stay out of it.
+   */
+  readonly agentConnections?: boolean;
   /**
    * A cheap test of whether this turn needs the checkpoint at all. When it
    * says no, the checkpoint is skipped without a trace — no lifecycle events —

package/src/mode/collect-stream.ts

@@ -22,7 +22,7 @@ export interface CollectedToolUse {
 }
 
 /** Sum two usage frames so multi-`message_end` responses don't undercount. */
-function addUsage(a: TokenUsage, b: TokenUsage): TokenUsage {
+export function addUsage(a: TokenUsage, b: TokenUsage): TokenUsage {
   const cacheRead =
     a.cacheReadTokens !== undefined || b.cacheReadTokens !== undefined
       ? (a.cacheReadTokens ?? 0) + (b.cacheReadTokens ?? 0)

package/src/mode/project-messages.test.ts

@@ -187,6 +187,17 @@ describe('projectMessagesFromLog tool_result stringify hardening', () => {
   it('passes a string output through verbatim', () => {
     expect(toolResultText(logWith('plain text'))).toBe('plain text');
   });
+
+  it('shows the model every image a result carries, after its text', () => {
+    const output = { forModel: 'Two windows', mediaType: 'image/png', base64: 'AAA', moreImages: [{ mediaType: 'image/jpeg', base64: 'BBB' }] };
+    const msgs = projectMessagesFromLog({ log: reader(logWith(output)) });
+
+    expect(msgs.find((m) => m.role === 'tool_result')?.content).toEqual([
+      { type: 'tool_result', toolUseId: 'c1', content: 'Two windows', isError: false },
+      { type: 'image', mediaType: 'image/png', data: 'AAA' },
+      { type: 'image', mediaType: 'image/jpeg', data: 'BBB' },
+    ]);
+  });
 });
 
 describe('skillsWithinReach', () => {

package/src/mode/project-messages.ts

@@ -22,51 +22,7 @@ import {
   toolResultStubbed,
   type ElisionState,
 } from '../elision-state.js';
-import { isToolDisplayResult } from '../tool-display.js';
-
-/**
- * Stringify an arbitrary tool output for the model-facing tool_result text.
- * `tool_result.output` is `unknown` and comes straight from whatever a tool
- * returned, so it can be circular or contain a BigInt — either of which makes
- * `JSON.stringify` THROW. Because projection runs on every request over the
- * append-only log, an unguarded throw here permanently wedges the session
- * (every subsequent re-projection re-throws). Mirrors the try/catch guard the
- * sibling sizing paths (`safeJsonLen`, `toolResultBytes`) already use.
- */
-function safeStringifyOutput(output: unknown): string {
-  if (typeof output === 'string') return output;
-  try {
-    return JSON.stringify(output ?? '');
-  } catch {
-    try {
-      return String(output ?? '');
-    } catch {
-      return '[unserializable tool output]';
-    }
-  }
-}
-
-/**
- * An image ContentBlock extracted from an image-shaped tool output. A tool can
- * return either `{ mediaType, base64 }` (the desktop screenshot/clipboard shape)
- * or the provider-native `{ type:'image', mediaType, data }` — both normalize to
- * the same provider `image` block so the model SEES the pixels instead of a
- * stringified blob of base64.
- */
-function imageBlockFromOutput(output: unknown): Extract<ContentBlock, { type: 'image' }> | null {
-  if (typeof output !== 'object' || output === null) return null;
-  const o = output as { type?: unknown; mediaType?: unknown; base64?: unknown; data?: unknown };
-  if (typeof o.mediaType !== 'string') return null;
-  // `{ mediaType, base64 }` (raw shape) or `{ type:'image', mediaType, data }`.
-  const data =
-    typeof o.base64 === 'string'
-      ? o.base64
-      : o.type === 'image' && typeof o.data === 'string'
-        ? o.data
-        : null;
-  if (data === null) return null;
-  return { type: 'image', mediaType: o.mediaType, data };
-}
+import { toolOutputForModel, type ToolImageBlock } from '../tool-output.js';
 
 /** Appended to the system prompt while elision is active (see projection). */
 export const ELISION_SYSTEM_NOTE =
@@ -524,10 +480,10 @@ export function projectMessages(
         // Stub bulky old tool output to a recall-able marker (decision shared
         // with estimateContextTokens via toolResultStubbed).
         let text: string;
-        // An image-shaped output (a screenshot/clipboard grab) is carried as a
-        // provider `image` block so the model SEES the pixels — only when the
+        // An image-shaped output (a screenshot/clipboard grab) is carried as
+        // provider `image` blocks so the model SEES the pixels — only when the
         // result isn't stubbed (elided) or an error and the call succeeded.
-        let image: Extract<ContentBlock, { type: 'image' }> | null = null;
+        let images: ReadonlyArray<ToolImageBlock> = [];
         // A `recall({ attachment })` result: the original image/document goes
         // beside it, from the prompt that carried it, while the budget allows.
         let restored: ContentBlock | null = null;
@@ -536,10 +492,6 @@ export function projectMessages(
           text = toolResultStubText(e, el);
         } else if (e.error) {
           text = `[error:${e.error.kind}] ${e.error.message}`;
-        } else if (isToolDisplayResult(e.output)) {
-          // Rich result (e.g. a file diff): the model only needs the short
-          // `forModel` summary — the structured `display` is for channels.
-          text = e.output.forModel;
         } else if (restoredAtt) {
           const description = (e.output as { forModel?: unknown }).forModel;
           text = typeof description === 'string' ? description : '[attachment restored — see below]';
@@ -550,20 +502,15 @@ export function projectMessages(
               ' [It could not be shown again: newer attachments already fill what one request may carry.' +
               ' Ask the person to attach it again if you need it now.]';
           }
-        } else if (e.ok && (image = imageBlockFromOutput(e.output))) {
-          // Short marker satisfies the tool_use→tool_result pairing; the image
-          // block (appended below) carries the actual pixels.
-          const description = (e.output as { forModel?: unknown }).forModel;
-          text = typeof description === 'string'
-            ? description
-            : '[image returned by tool — see attached image]';
         } else {
-          text = safeStringifyOutput(e.output);
+          const forModel = toolOutputForModel(e.output);
+          text = forModel.text;
+          if (e.ok) images = forModel.images;
         }
         const content: ContentBlock[] = [
           { type: 'tool_result', toolUseId: e.callId, content: text, isError: !e.ok },
+          ...images,
         ];
-        if (image) content.push(image);
         if (restored) content.push(restored);
         messages.push({ role: 'tool_result', content });
         recordStable(e.seq);

package/src/mode/react-loop-options.ts

@@ -0,0 +1,124 @@
+import type { ModeContext } from '../mode.js';
+import type { AgentGoalStatus, TokenUsage } from '../provider.js';
+import type { StopReason } from '../provider-utils.js';
+import type { StuckLoopReport, StuckTripInfo } from '../tool-dispatch.js';
+import type { TurnCheckpoint } from './checkpoint.js';
+import type { CollectedToolUse } from './collect-stream.js';
+
+/** What a clean provider call produced — input to {@link ReactLoopOptions.onProviderSuccess}. */
+export interface ProviderSuccessInfo {
+  readonly text: string;
+  readonly stopReason: StopReason;
+  readonly toolUses: ReadonlyArray<CollectedToolUse>;
+  readonly usage?: TokenUsage;
+  readonly iteration: number;
+}
+
+/** A completed tool batch — input to {@link ReactLoopOptions.onToolBatchEnd}. */
+export interface ToolBatchInfo {
+  readonly toolUses: ReadonlyArray<CollectedToolUse>;
+  readonly iteration: number;
+}
+
+/** Hooks return this to end the turn; the hook emits its own wrap-up events first. */
+export interface StopDirective {
+  readonly action: 'stop';
+}
+
+export interface ReactLoopOptions {
+  /** Name stamped on `mode_iteration` events (e.g. `'default'`, `'goal'`). */
+  readonly strategyName: string;
+  /**
+   * Iteration cap when the context doesn't supply one. Default 500. May be
+   * `Number.POSITIVE_INFINITY` for an uncapped loop (goal mode): the run then
+   * ends only via a terminal signal (checkpoint/hook stop, abort, fatal
+   * error) — an explicit `ctx.maxIterations` still takes precedence.
+   */
+  readonly defaultMaxIterations?: number;
+  /** Prefix for provider-error messages (goal mode uses `'goal: '`). */
+  readonly errorPrefix?: string;
+  /**
+   * When set, an already-aborted signal is reported (with this reason) BEFORE
+   * the first iteration — goal/collab preflight. When omitted the first
+   * iteration's own abort check covers it with the generic reason.
+   */
+  readonly preflightAbortReason?: string;
+  /** Turn-end gates, run in declared order. Omit/empty → plain ReAct loop. */
+  readonly checkpoints?: ReadonlyArray<TurnCheckpoint>;
+  /**
+   * Hard cap on checkpoint `inject`/`retry` rounds per idle EPISODE — i.e.
+   * consecutive gate rounds with no tool work between them; the count resets
+   * whenever a tool batch executes (default 3). When exhausted the turn ends
+   * with the model's answer as-is plus a visible warning — a
+   * permanently-failing gate degrades loudly instead of looping forever.
+   */
+  readonly maxInjections?: number;
+  /** Clamp on injected feedback length in characters (default 16_384). */
+  readonly maxInjectChars?: number;
+  /**
+   * Stuck-loop policy + wording overrides; sensible defaults from
+   * `strategyName`. `action` picks what a detector trip does:
+   *
+   *   - `'abort'` (default): fail the batch and end the turn with a fatal
+   *     error — the historical behavior, right for attended modes where the
+   *     user is present to redirect.
+   *   - `'nudge'`: never stop. The batch still executes (repeated calls are
+   *     usually legitimate work — re-running a failing build between edits),
+   *     a visible warning + `extraOnStuck` events are emitted, the detector
+   *     resets, and `nudgeText` (or a default) rides the next provider call
+   *     as a volatile steer. For unattended modes (goal) where a heuristic
+   *     must never kill the run.
+   */
+  readonly stuck?: Partial<StuckLoopReport> & {
+    readonly action?: 'abort' | 'nudge';
+    /** Volatile steer for `'nudge'` trips; default wording when omitted. */
+    readonly nudgeText?: (info: StuckTripInfo) => string;
+  };
+  /**
+   * Runs after compaction/elision, before the provider call. May return a
+   * volatile user message to ride ONLY the next call (collab's inbox/pause
+   * awareness) — never appended to the log; the cache strategy is told via
+   * `volatileTailCount` so its tail breakpoint stays ahead of it.
+   */
+  readonly onIterationStart?: (
+    ctx: ModeContext,
+    iteration: number,
+  ) => Promise<{ readonly volatileUserText?: string } | undefined>;
+  /**
+   * Runs after every clean provider call (reasoning already logged, tools not
+   * yet executed). Return `{action: 'stop'}` to end the turn — the hook emits
+   * its own wrap-up events first (goal mode's token-budget backstop).
+   */
+  readonly onProviderSuccess?: (
+    ctx: ModeContext,
+    info: ProviderSuccessInfo,
+  ) => Promise<StopDirective | undefined>;
+  /**
+   * Runs after a tool batch executes cleanly. Return `{action: 'stop'}` to
+   * end the turn (goal/collab terminal-tool detection: `goal_complete`,
+   * `collab_done`); the hook emits its own completion events first.
+   */
+  readonly onToolBatchEnd?: (
+    ctx: ModeContext,
+    info: ToolBatchInfo,
+  ) => Promise<StopDirective | undefined>;
+  /**
+   * Runs after an agent connection's turn that reported the state of the
+   * agent's own goal. Return `{action: 'stop'}` to end the turn (goal mode
+   * wraps up a met goal); the hook emits its own completion events first.
+   */
+  readonly onAgentGoal?: (ctx: ModeContext, status: AgentGoalStatus) => Promise<StopDirective | undefined>;
+  /**
+   * Agent connections only: the agent finished its own plan (Markdown). Plan
+   * mode shows it as its plan card and ends the turn; without this hook the
+   * plan is shown as the agent's message.
+   */
+  readonly onAgentPlan?: (ctx: ModeContext, plan: string) => Promise<StopDirective | undefined>;
+  /**
+   * Replaces the default "exceeded maxIterations" fatal error — the hook
+   * emits its own cap-reached events (goal mode adds a plugin event and its
+   * own wording). The loop returns right after.
+   */
+  readonly onMaxIterations?: (ctx: ModeContext, maxIterations: number) => Promise<void>;
+}
+