@moxxy/sdk 0.42.1 → 0.43.0

package/src/mode/project-messages.ts

@@ -355,13 +355,14 @@ export function projectMessages(
         // Render-only reasoning (no signature/encrypted) is never replayed —
         // it exists only for the live/scrollback "Thinking" view. Replayable
         // reasoning is stashed for content[0] of this turn's assistant message.
-        if (e.signature || e.encrypted) {
+        if (e.signature || e.encrypted || e.replayItems?.length) {
           pendingReasoning = {
             type: 'reasoning',
             text: e.content,
             ...(e.signature ? { signature: e.signature } : {}),
             ...(e.redacted ? { redacted: true } : {}),
             ...(e.encrypted ? { encrypted: e.encrypted } : {}),
+            ...(e.replayItems ? { replayItems: e.replayItems } : {}),
           };
           pendingReasoningSeq = e.seq;
         }

package/src/mode/react-loop.ts

@@ -391,6 +391,7 @@ export async function* runReactLoop(
         ...(reasoning.signature ? { signature: reasoning.signature } : {}),
         ...(reasoning.redacted ? { redacted: true } : {}),
         ...(reasoning.encrypted ? { encrypted: reasoning.encrypted } : {}),
+        ...(reasoning.replayItems ? { replayItems: reasoning.replayItems } : {}),
       });
     }
 

package/src/mode.ts

@@ -110,6 +110,11 @@ export interface ModeContext {
   readonly reasoning?: { readonly effort?: ReasoningEffort } | boolean;
   /** Ask for the provider's faster tier; forwarded only to a model with `supportsFast`. */
   readonly fast?: boolean;
+  /**
+   * The reminder at the end of a turn that ended on a step that did not get
+   * done (config `context.unfinishedStepCheck`). Unset means on.
+   */
+  readonly unfinishedStepCheck?: boolean;
   readonly permissions: PermissionResolver;
   /**
    * Optional generic "ask the user a question" gate. Any loop strategy can

package/src/provider.ts

@@ -1,4 +1,5 @@
 import type { HostedTool, ToolDef } from './tool.js';
+import type { ReasoningReplayItem } from './events.js';
 
 export interface ProviderMessage {
   readonly role: 'system' | 'user' | 'assistant' | 'tool_result';
@@ -36,6 +37,7 @@ export type ContentBlock =
       readonly signature?: string;
       readonly redacted?: boolean;
       readonly encrypted?: string;
+      readonly replayItems?: ReadonlyArray<ReasoningReplayItem>;
     };
 
 /**
@@ -110,7 +112,7 @@ export type ProviderEvent =
    * Codex reasoning encrypted_content) that must be replayed verbatim;
    * `redacted` marks reasoning that must never be displayed.
    */
-  | { readonly type: 'reasoning_signature'; readonly signature?: string; readonly redacted?: boolean; readonly encrypted?: string };
+  | { readonly type: 'reasoning_signature'; readonly signature?: string; readonly redacted?: boolean; readonly encrypted?: string; readonly replayItem?: ReasoningReplayItem };
 
 export interface TokenUsage {
   /** Non-cached prompt tokens. Providers whose raw usage includes cached

package/src/session-like.ts

@@ -167,6 +167,11 @@ export interface SessionInfo {
   readonly reasoningEffort?: ReasoningEffort | 'default' | null;
   /** Whether turns ask for the provider's faster tier. Absent from older runners. */
   readonly fast?: boolean;
+  /**
+   * The model a turn runs on when it names none: the one the conversation last ran on, else the one set as the
+   * active provider's default, else the first that provider lists. Absent without an active provider, and from older runners.
+   */
+  readonly defaultModel?: string;
   /** Turns running now, whichever client (or in-process channel) started them.
    *  Reported by a runner to its clients; absent from runners that predate it. */
   readonly runningTurns?: ReadonlyArray<string>;

package/src/shortfall.test.ts

@@ -0,0 +1,93 @@
+import { describe, expect, it } from 'vitest';
+import { asEventId, asSessionId, asTurnId } from './ids.js';
+import type { MoxxyEvent } from './events.js';
+import { openShortfall, shortfallNudge, shortfallOf } from './shortfall.js';
+
+/**
+ * A tool that carries out steps can stop short of them and still answer
+ * without an error: `browser_run` says "0 of 1 steps done". In a form trial
+ * the agent pressed Send, the page answered "503, try again", and the agent
+ * ended the turn there. A result that names what it did not get done
+ * (`shortfall.what`) lets the loop see that the turn ended on such a step.
+ */
+const sid = asSessionId('s1');
+const t1 = asTurnId('t1');
+
+function event(seq: number, partial: Omit<MoxxyEvent, 'id' | 'seq' | 'ts' | 'sessionId'>): MoxxyEvent {
+  return { id: asEventId(`e${seq}`), seq, ts: seq, sessionId: sid, ...partial } as MoxxyEvent;
+}
+
+function step(seq: number, callId: string, output: unknown, error?: { message: string; kind: 'aborted' | 'threw' | 'denied' | 'timeout' }): MoxxyEvent[] {
+  return [
+    event(seq, { type: 'tool_call_requested', turnId: t1, source: 'model', callId, name: 'run', input: {} }),
+    event(seq + 1, { type: 'tool_result', turnId: t1, source: 'tool', callId, ok: error === undefined, ...(error ? { error } : { output }) }),
+  ];
+}
+
+const SHORT = { text: '0 of 1 steps done', shortfall: { what: 'step 1, click "Send": the page answered 503' } };
+
+describe('shortfallOf', () => {
+  it('reads what a result says it did not get done, and whether the step was delivered unseen', () => {
+    expect(shortfallOf(SHORT)).toEqual({ what: 'step 1, click "Send": the page answered 503' });
+    expect(shortfallOf({ shortfall: { what: 'step 2: not seen', unverified: true } })).toEqual({ what: 'step 2: not seen', unverified: true });
+  });
+
+  it('is null for a result that says nothing of it', () => {
+    expect(shortfallOf('plain text')).toBeNull();
+    expect(shortfallOf({ text: '3 of 3 steps done' })).toBeNull();
+    expect(shortfallOf({ shortfall: { unverified: true } })).toBeNull();
+    expect(shortfallOf({ shortfall: { what: '   ' } })).toBeNull();
+  });
+});
+
+describe('openShortfall', () => {
+  it('is the step the turn ended on, when that step did not get done', () => {
+    expect(openShortfall([...step(0, 'c1', { text: 'ok' }), ...step(2, 'c2', SHORT)])).toEqual(SHORT.shortfall);
+  });
+
+  it('is settled by any step after it: another route that worked, a hand-over, a look', () => {
+    expect(openShortfall([...step(0, 'c1', SHORT), ...step(2, 'c2', { text: 'sent through the other form' })])).toBeNull();
+    expect(openShortfall([...step(0, 'c1', SHORT), ...step(2, 'c2', { completed: false })])).toBeNull();
+  });
+
+  it('is not an error, a refusal or a cancel — those say nothing of a step left to finish', () => {
+    for (const kind of ['threw', 'denied', 'aborted', 'timeout'] as const) {
+      expect(openShortfall([...step(0, 'c1', SHORT), ...step(2, 'c2', undefined, { message: 'no', kind })])).toBeNull();
+    }
+  });
+
+  it('is null in a turn that called no tool', () => {
+    expect(openShortfall([event(0, { type: 'assistant_message', turnId: t1, source: 'model', content: 'hello', stopReason: 'end_turn' })])).toBeNull();
+  });
+});
+
+describe('shortfallNudge', () => {
+  it('does not assert delivery when the helper did not answer', () => {
+    const text = shortfallNudge({ what: 'Save: helper timed out', unverified: true });
+    expect(text).not.toContain('It was delivered');
+    expect(text).toContain('read the page or window to see whether it took effect');
+    expect(text).toContain('do not repeat it blind');
+  });
+  it('names the step, offers another way and leaves room to say what blocks', () => {
+    const text = shortfallNudge({ what: 'step 1, click "Send": the page answered 503' });
+
+    expect(text).toContain('step 1, click "Send": the page answered 503');
+    expect(text).toMatch(/another way/);
+    expect(text).toMatch(/say plainly what stops you/);
+    expect(text).toMatch(/do not work around a refusal/);
+  });
+
+  it('tells to check the effect first when the step was delivered, never to send it again blind', () => {
+    const text = shortfallNudge({ what: 'step 1, click "Pay": delivered, but "paid" was not seen', unverified: true });
+
+    expect(text).toMatch(/read the page or window to see whether it took effect/);
+    expect(text).toMatch(/do not repeat it blind/);
+  });
+
+  it('says to do the step again when the page shows it did not take: an error that says "try again" is not a risk of a duplicate', () => {
+    // In a form trial the agent was reminded, read "503, try again" on the page and still asked whether to resend.
+    const text = shortfallNudge({ what: 'step 1, click "Send": delivered, but "a ticket number" was not seen', unverified: true });
+
+    expect(text).toMatch(/If it shows that it did not — an error, a "try again" — do the step again/);
+  });
+});

package/src/shortfall.ts

@@ -0,0 +1,87 @@
+import type { MoxxyEvent } from './events.js';
+import type { ModeContext } from './mode.js';
+import type { TurnCheckpoint } from './mode/checkpoint.js';
+
+/**
+ * What a tool result says it was asked to do and did not get done: `what`
+ * names the step and why, `unverified` marks an action whose effect is unknown,
+ * including delivery without confirmation and a helper that did not answer.
+ * A result that got everything done leaves `shortfall` out, and so does one
+ * stopped by a refusal — that is the user's
+ * answer, not a step left to finish.
+ */
+export interface Shortfall {
+  readonly what: string;
+  readonly unverified?: boolean;
+}
+
+export function shortfallOf(output: unknown): Shortfall | null {
+  if (typeof output !== 'object' || output === null) return null;
+  const shortfall = (output as { shortfall?: unknown }).shortfall;
+  if (typeof shortfall !== 'object' || shortfall === null) return null;
+  const { what, unverified } = shortfall as { what?: unknown; unverified?: unknown };
+  if (typeof what !== 'string' || what.trim() === '') return null;
+  return { what, ...(unverified === true ? { unverified: true } : {}) };
+}
+
+/**
+ * The step `events` ended on, when it did not get done. Any step after it
+ * settles it — another route that worked, a hand-over to the user, a look at
+ * the result — and an error, a refusal or a cancel is not one: those say
+ * nothing of a step left to finish.
+ */
+export function openShortfall(events: ReadonlyArray<MoxxyEvent>): Shortfall | null {
+  const last = events.findLast((e) => e.type === 'tool_result');
+  if (last?.type !== 'tool_result' || !last.ok) return null;
+  return shortfallOf(last.output);
+}
+
+export function shortfallNudge(shortfall: Shortfall): string {
+  const next = shortfall.unverified
+    ? 'Its effect is unconfirmed, so first read the page or window to see whether it took effect. ' +
+      'If it shows that it did not — an error, a "try again" — do the step again. ' +
+      'If it may have gone through (a send, a payment, a tick), do not repeat it blind. '
+    : 'Try it again where the error or the page invites that, or go another way: a different element, tool or route. ';
+  return (
+    `Before you report: your last step did not get done — ${shortfall.what}. ` +
+    'If what the user asked for is not done yet and there is still a way to get there, take it now. ' +
+    next +
+    'If the user has to do something themselves (sign in, solve a CAPTCHA, decide, grant access), or nothing is left to try, ' +
+    'say plainly what stops you — and do not work around a refusal.'
+  );
+}
+
+const NAME = 'unfinished-step';
+
+/** Whether this turn was already reminded: read from its log, so a resumed turn is not asked twice. */
+const reminded = (events: ReadonlyArray<MoxxyEvent>): boolean =>
+  events.some(
+    (e) =>
+      e.type === 'plugin_event' &&
+      e.subtype === 'checkpoint_injected' &&
+      (e.payload as { name?: unknown } | null)?.name === NAME,
+  );
+
+/**
+ * At the end of a turn, one reminder when the turn ended on a step that did
+ * not get done. In a form trial the agent pressed Send, the page answered
+ * "503, try again", and the agent reported that it could not send. Asked once
+ * per turn: the agent may be right that nothing is left to try, and it is told
+ * how to say so. Off with `unfinishedStepCheck: false`.
+ */
+export function unfinishedStepCheckpoint(): TurnCheckpoint {
+  const due = (ctx: ModeContext): Shortfall | null => {
+    if (ctx.unfinishedStepCheck === false) return null;
+    const events = ctx.log.byTurn(ctx.turnId);
+    return reminded(events) ? null : openShortfall(events);
+  };
+  return {
+    name: NAME,
+    applies: (ctx: ModeContext) => due(ctx) !== null,
+    async run(check, ctx: ModeContext) {
+      const shortfall = check.signal.aborted ? null : due(ctx);
+      if (!shortfall) return { action: 'pass' };
+      return { action: 'inject', text: shortfallNudge(shortfall), volatile: true };
+    },
+  };
+}

package/src/tool-dispatch.ts

@@ -63,7 +63,13 @@ export async function* dispatchToolCall(
       { sessionId: String(ctx.sessionId), turnId: String(ctx.turnId), toolDescription: ctx.tools.get(t.name)?.description },
     );
     if (decision.mode === 'deny') {
-      yield* emitDenied(ctx, t, decision.reason ?? 'denied by resolver', 'resolver');
+      // The session's resolver consults standing rules before asking anyone;
+      // name such a refusal as policy, so 'resolver' means the answer given.
+      const standing = await ctx.permissions.policyCheck?.(
+        { callId: asToolCallId(t.id), name: t.name, input: actualInput },
+        { sessionId: String(ctx.sessionId), turnId: String(ctx.turnId) },
+      );
+      yield* emitDenied(ctx, t, decision.reason ?? 'denied by resolver', standing?.mode === 'deny' ? 'policy' : 'resolver');
       return;
     }
     // A deferred approval may outlive its turn, or policy may change while
@@ -183,8 +189,9 @@ async function* emitDenied(
  * Run a batch of tool uses in order, handling mid-batch abort. On
  * `ctx.signal.aborted` it synthesizes a failed `tool_result` for every
  * not-yet-run call (so the log never ends on an orphan `tool_call_requested`),
- * emits an `abort`, and returns `true` to tell the caller to stop. Returns
- * `false` after a clean batch. Shared by every loop strategy so the
+ * emits an `abort`, and returns `true` to tell the caller to stop. The user's
+ * refusal of a tool with `refusalEndsTurn` stops the turn the same way, ending
+ * it with that tool's text. Returns `false` after a clean batch. Shared by every loop strategy so the
  * orphan-on-abort guarantee lives in one place.
  */
 export async function* executeToolUses(
@@ -219,11 +226,41 @@ export async function* executeToolUses(
       });
       return true;
     }
+    const endsTurn = ctx.tools.get(t.name)?.refusalEndsTurn;
+    let refused = false;
     try {
-      yield* dispatchToolCall(ctx, t, iteration);
+      for await (const event of dispatchToolCall(ctx, t, iteration)) {
+        // Only the person's answer ends the turn; a rule or a hook is a failed step to route around.
+        if (event.type === 'tool_call_denied' && event.decidedBy === 'resolver') refused = true;
+        yield event;
+      }
     } finally {
       unresolved.delete(t.id);
     }
+    // For such a tool a refusal is a terminal boundary, not a failed task step.
+    // Drain pending requests without invoking hooks, permissions or handlers.
+    if (refused && endsTurn !== undefined) {
+      for (const orphanId of unresolved) {
+        yield await ctx.emit({
+          type: 'tool_result',
+          sessionId: ctx.sessionId,
+          turnId: ctx.turnId,
+          source: 'system',
+          callId: asToolCallId(orphanId),
+          ok: false,
+          error: { kind: 'denied', message: `${t.name} was refused, so the rest of this turn was cancelled` },
+        });
+      }
+      yield await ctx.emit({
+        type: 'assistant_message',
+        sessionId: ctx.sessionId,
+        turnId: ctx.turnId,
+        source: 'system',
+        stopReason: 'end_turn',
+        content: endsTurn,
+      });
+      return true;
+    }
   }
   return false;
 }

package/src/tool.ts

@@ -230,4 +230,12 @@ export interface ToolDef {
    * a task in a mode that never asked for it. See `toolsForMode`.
    */
   readonly modes?: ReadonlyArray<string>;
+  /**
+   * The user's refusal of this tool ends the turn, with this text as its last
+   * message, instead of letting the model try another way round it. For tools
+   * whose refusal means "not like this, not now" (Computer Use). A standing
+   * rule or a hook refusing it stays a failed step. The rest of the batch is
+   * cancelled unrun; the next user turn asks again.
+   */
+  readonly refusalEndsTurn?: string;
 }