@moxxy/sdk 0.42.1 → 0.44.0

package/src/mode/project-messages.ts

@@ -2,7 +2,13 @@ import type { ContentBlock, ProviderMessage } from '../provider.js';
 import type { ModeContext } from '../mode.js';
 import type { Skill } from '../skill.js';
 import { toolPatternMatches } from '../skill-mentions.js';
-import type { MoxxyEvent, UserPromptEvent } from '../events.js';
+import type { MoxxyEvent, UserPromptAttachment, UserPromptEvent } from '../events.js';
+import {
+  MODEL_ATTACHMENT_BUDGET_CHARS,
+  attachmentBytes,
+  attachmentKey,
+  restoredAttachmentRef,
+} from '../attachment-payload.js';
 import {
   activeCompactionRanges,
   makeCompactionLookup,
@@ -135,6 +141,96 @@ export interface ProjectMessagesOptions {
   readonly precomputedElisionState?: ElisionState;
 }
 
+function hasModelPayload(att: UserPromptAttachment): boolean {
+  return att.kind === 'image' || att.kind === 'document';
+}
+
+function attachmentLeftOutNote(att: UserPromptAttachment, seq: number, index: number): string {
+  const label = `${att.kind}${att.name ? ` "${att.name}"` : ''}`;
+  const mb = (attachmentBytes(att) / (1024 * 1024)).toFixed(1);
+  return (
+    `[${label} (${mb} MB) was attached earlier in this conversation and is no longer sent ` +
+    `with each request, to keep the request within the model's size limit. ` +
+    `To see it again, call recall({ attachment: "${attachmentKey(seq, index)}" }).]`
+  );
+}
+
+/** The image or document block an attachment the model reads as bytes becomes. */
+function attachmentBlock(att: UserPromptAttachment): ContentBlock {
+  if (att.kind === 'image') {
+    return { type: 'image', mediaType: att.mediaType ?? 'image/png', data: att.content };
+  }
+  return {
+    type: 'document',
+    mediaType: att.mediaType ?? 'application/pdf',
+    data: att.content,
+    ...(att.name ? { name: att.name } : {}),
+  };
+}
+
+/** The prompts that carry attachments, by seq, so a restoring recall finds its original. */
+function attachmentPromptsBySeq(events: ReadonlyArray<MoxxyEvent>): ReadonlyMap<number, UserPromptEvent> {
+  const prompts = new Map<number, UserPromptEvent>();
+  for (const e of events) {
+    if (e.type === 'user_prompt' && e.attachments && e.attachments.length > 0) prompts.set(e.seq, e);
+  }
+  return prompts;
+}
+
+/** The image/document a `recall({ attachment })` result brings back, or null. */
+function restoredAttachment(
+  e: Extract<MoxxyEvent, { type: 'tool_result' }>,
+  prompts: ReadonlyMap<number, UserPromptEvent>,
+): UserPromptAttachment | null {
+  if (!e.ok || e.error) return null;
+  const ref = restoredAttachmentRef(e.output);
+  if (!ref) return null;
+  const prompt = prompts.get(ref.seq);
+  const att = prompt ? prompt.attachments?.[ref.index] : undefined;
+  return att && hasModelPayload(att) && att.omittedBytes === undefined ? att : null;
+}
+
+/** The budget key of what a restoring recall result shows. */
+const restoreKey = (seq: number): string => `r:${seq}`;
+
+/**
+ * Keys of the image/document payloads that go to the model in full: an
+ * attachment's `seq:index`, or `r:seq` for one a recall result restores.
+ * Newest first, while they fit {@link MODEL_ATTACHMENT_BUDGET_CHARS}, so a
+ * restored attachment takes its place among the newest. Deterministic for a
+ * given log, so the prompt cache sees a stable prefix.
+ */
+function attachmentsSentInFull(
+  events: ReadonlyArray<MoxxyEvent>,
+  el: ElisionState,
+  isCompacted: (seq: number) => boolean,
+  prompts: ReadonlyMap<number, UserPromptEvent>,
+): ReadonlySet<string> {
+  const keys = new Set<string>();
+  let room = MODEL_ATTACHMENT_BUDGET_CHARS;
+  const take = (key: string, att: UserPromptAttachment): void => {
+    if (att.content.length > room) return;
+    room -= att.content.length;
+    keys.add(key);
+  };
+  for (let i = events.length - 1; i >= 0; i -= 1) {
+    const e = events[i];
+    if (!e || isCompacted(e.seq)) continue;
+    if (e.type === 'tool_result') {
+      if (toolResultStubbed(e, el)) continue;
+      const att = restoredAttachment(e, prompts);
+      if (att) take(restoreKey(e.seq), att);
+      continue;
+    }
+    if (e.type !== 'user_prompt' || !e.attachments || conversationalStubbed(e, el)) continue;
+    for (const [index, att] of e.attachments.entries()) {
+      if (!hasModelPayload(att) || att.omittedBytes !== undefined) continue;
+      take(attachmentKey(e.seq, index), att);
+    }
+  }
+  return keys;
+}
+
 /**
  * Pure projection of a single `user_prompt` event to its content blocks.
  *
@@ -144,27 +240,23 @@ export interface ProjectMessagesOptions {
  * what the inline switch arm produced. Caller decides how to wrap it as a
  * message / record the stable prefix.
  */
-export function projectUserPrompt(event: UserPromptEvent, el: ElisionState): ContentBlock[] {
+export function projectUserPrompt(
+  event: UserPromptEvent,
+  el: ElisionState,
+  /** Which attachments go to the model in full; the rest become a short note. Default: all. */
+  sendsInFull: (index: number) => boolean = () => true,
+): ContentBlock[] {
   // Elided + conversational: collapse to a stub (anchor/tiny kept full).
   if (conversationalStubbed(event, el)) {
     return [{ type: 'text', text: conversationalStub('user', event.seq) }];
   }
   const blocks: ContentBlock[] = [{ type: 'text', text: event.text }];
   if (event.attachments) {
-    for (const att of event.attachments) {
-      if (att.kind === 'image') {
-        blocks.push({
-          type: 'image',
-          mediaType: att.mediaType ?? 'image/png',
-          data: att.content,
-        });
-      } else if (att.kind === 'document') {
-        blocks.push({
-          type: 'document',
-          mediaType: att.mediaType ?? 'application/pdf',
-          data: att.content,
-          ...(att.name ? { name: att.name } : {}),
-        });
+    for (const [index, att] of event.attachments.entries()) {
+      if (att.omittedBytes !== undefined || (hasModelPayload(att) && !sendsInFull(index))) {
+        blocks.push({ type: 'text', text: attachmentLeftOutNote(att, event.seq, index) });
+      } else if (hasModelPayload(att)) {
+        blocks.push(attachmentBlock(att));
       } else {
         blocks.push({
           type: 'text',
@@ -277,6 +369,8 @@ export function projectMessages(
   // Only VISIBLE results count: one swallowed by a compaction is never sent, so
   // its still-visible tool_use needs the fallback just like a missing one.
   const resolvedCallIds = resolvedCallIdSet(allEvents.filter((e) => !compactionFor(e.seq)));
+  const attachmentPrompts = attachmentPromptsBySeq(allEvents);
+  const sentInFull = attachmentsSentInFull(allEvents, el, (seq) => compactionFor(seq) !== null, attachmentPrompts);
   // callIds whose tool_use block is projected. A tool_result outside this set
   // answers a call a compaction summarized away (the result landed after later
   // turns began); providers reject a result with no matching call.
@@ -347,7 +441,10 @@ export function projectMessages(
       case 'user_prompt': {
         flush();
         pendingReasoning = null;
-        messages.push({ role: 'user', content: projectUserPrompt(e, el) });
+        messages.push({
+          role: 'user',
+          content: projectUserPrompt(e, el, (index) => sentInFull.has(`${e.seq}:${index}`)),
+        });
         recordStable(e.seq);
         break;
       }
@@ -355,13 +452,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;
         }
@@ -430,6 +528,10 @@ export function projectMessages(
         // provider `image` block 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;
+        // 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;
+        const restoredAtt = toolResultStubbed(e, el) ? null : restoredAttachment(e, attachmentPrompts);
         if (toolResultStubbed(e, el)) {
           text = toolResultStubText(e, el);
         } else if (e.error) {
@@ -438,6 +540,16 @@ export function projectMessages(
           // 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]';
+          if (sentInFull.has(restoreKey(e.seq))) {
+            restored = attachmentBlock(restoredAtt);
+          } else {
+            text +=
+              ' [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.
@@ -452,6 +564,7 @@ export function projectMessages(
           { type: 'tool_result', toolUseId: e.callId, content: text, isError: !e.ok },
         ];
         if (image) content.push(image);
+        if (restored) content.push(restored);
         messages.push({ role: 'tool_result', content });
         recordStable(e.seq);
         break;

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;
 }