@moxxy/sdk 0.42.1 → 0.44.0

package/src/attachment-payload.ts

@@ -0,0 +1,187 @@
+import type { MoxxyEvent, UserPromptAttachment } from './events.js';
+
+/**
+ * Attachment bytes travel two very different roads. The model needs them in
+ * full; a client that only DRAWS the conversation (desktop, mobile, a channel
+ * bot) does not, and pushing a scanned 30 MB PDF through the client link on
+ * every reconnect is what once wedged a chat in a reconnect loop. So the runner
+ * sends clients {@link eventForClient} — large payloads swapped for their size —
+ * and a client that wants the bytes (an image preview) reads them back in
+ * bounded slices with {@link readAttachmentChunk}. The log itself never changes.
+ */
+
+/**
+ * The most attachment payload (base64 characters) one model request carries.
+ * Every request resends the whole conversation, so without a cap a chat with a
+ * few scanned PDFs outgrows the provider's request limit (Anthropic: 32 MB) and
+ * EVERY later turn fails. The newest attachments go in full; older ones that no
+ * longer fit become a note naming them.
+ */
+export const MODEL_ATTACHMENT_BUDGET_CHARS = 20 * 1024 * 1024;
+
+/** One attachment's payload above this travels to clients by size only. */
+export const CLIENT_INLINE_ATTACHMENT_CHARS = 512 * 1024;
+/** All of one event's inline attachment payloads together stay under this. */
+export const CLIENT_INLINE_EVENT_CHARS = 1024 * 1024;
+/** The largest slice one attachment read returns. */
+export const ATTACHMENT_READ_CHUNK_CHARS = 1024 * 1024;
+
+/** Whether `content` is base64 bytes rather than text. Raw audio carries a media type; a transcript does not. */
+function isBase64Payload(att: UserPromptAttachment): boolean {
+  return att.kind === 'image' || att.kind === 'document' || (att.kind === 'audio' && att.mediaType !== undefined);
+}
+
+/** The attachment's size in bytes — its real size even on a client copy whose bytes were left out. */
+export function attachmentBytes(att: UserPromptAttachment): number {
+  if (att.omittedBytes !== undefined) return att.omittedBytes;
+  if (!isBase64Payload(att)) return att.content.length;
+  const padding = att.content.endsWith('==') ? 2 : att.content.endsWith('=') ? 1 : 0;
+  return Math.max(0, Math.floor((att.content.length * 3) / 4) - padding);
+}
+
+/**
+ * The copy of `event` a client receives: every attachment payload too large for
+ * the client link becomes `content: ''` plus `omittedBytes`. Returns `event`
+ * itself when nothing had to change, so the common case allocates nothing.
+ */
+export function eventForClient(event: MoxxyEvent): MoxxyEvent {
+  if (event.type !== 'user_prompt' || !event.attachments || event.attachments.length === 0) return event;
+  let room = CLIENT_INLINE_EVENT_CHARS;
+  let changed = false;
+  const attachments = event.attachments.map((att) => {
+    const size = att.content.length;
+    if (size <= CLIENT_INLINE_ATTACHMENT_CHARS && size <= room) {
+      room -= size;
+      return att;
+    }
+    changed = true;
+    return { ...att, content: '', omittedBytes: attachmentBytes(att) };
+  });
+  return changed ? { ...event, attachments } : event;
+}
+
+/**
+ * The most one history page may weigh on the wire, in JSON characters. Paging
+ * counts events, and a few hundred events with screenshots or attachments can
+ * add up to tens of megabytes — one frame the client has to swallow whole.
+ */
+export const HISTORY_PAGE_MAX_CHARS = 4 * 1024 * 1024;
+
+/** One newest-first history page: ascending events plus the cursor to the next older page. */
+export interface HistoryPage {
+  readonly events: ReadonlyArray<MoxxyEvent>;
+  readonly prevCursor: number | null;
+}
+
+/**
+ * The page as a client receives it: every event in its client form, and the
+ * oldest events dropped until the page fits {@link HISTORY_PAGE_MAX_CHARS}. The
+ * newest event always stays, so paging always advances; the dropped events
+ * come back on the next older page.
+ */
+export function historyPageForClient(page: HistoryPage): HistoryPage {
+  const events = page.events.map(eventForClient);
+  let room = HISTORY_PAGE_MAX_CHARS;
+  let start = events.length;
+  while (start > 0) {
+    const event = events[start - 1];
+    if (event === undefined) break;
+    const size = JSON.stringify(event).length + 1;
+    if (size > room && start < events.length) break;
+    room -= size;
+    start -= 1;
+  }
+  if (start === 0) return { events, prevCursor: page.prevCursor };
+  const kept = events.slice(start);
+  const oldest = kept[0];
+  return { events: kept, prevCursor: oldest === undefined ? page.prevCursor : oldest.seq };
+}
+
+/** One slice of an attachment's `content`, starting at `offset` (in characters). */
+export interface AttachmentChunk {
+  readonly data: string;
+  /** The full `content` length, so the reader knows when it has everything. */
+  readonly total: number;
+}
+
+/**
+ * Slice attachment `index` of `event`. Slices start on a multiple of four
+ * characters when `offset` does, so base64 slices decode on their own too.
+ */
+export function readAttachmentChunk(event: MoxxyEvent, index: number, offset: number): AttachmentChunk {
+  if (event.type !== 'user_prompt' || !event.attachments) {
+    throw new Error(`event ${event.seq} has no attachments`);
+  }
+  const att = event.attachments[index];
+  if (!att) throw new Error(`event ${event.seq} has no attachment ${index}`);
+  const start = Math.max(0, Math.floor(offset));
+  return { data: att.content.slice(start, start + ATTACHMENT_READ_CHUNK_CHARS), total: att.content.length };
+}
+
+/** How an attachment is named across the conversation: `seq:index` of the prompt that carried it. */
+export function attachmentKey(seq: number, index: number): string {
+  return `${seq}:${index}`;
+}
+
+/** One attachment found in the log, with where it sits. */
+export interface FoundAttachment {
+  readonly seq: number;
+  readonly index: number;
+  readonly attachment: UserPromptAttachment;
+}
+
+function* attachmentsNewestFirst(events: ReadonlyArray<MoxxyEvent>): Generator<FoundAttachment> {
+  for (let i = events.length - 1; i >= 0; i -= 1) {
+    const e = events[i];
+    if (!e || e.type !== 'user_prompt' || !e.attachments) continue;
+    for (let index = e.attachments.length - 1; index >= 0; index -= 1) {
+      const attachment = e.attachments[index];
+      if (attachment) yield { seq: e.seq, index, attachment };
+    }
+  }
+}
+
+/**
+ * The attachment `query` names: its key (`seq:index`) or its file name, the
+ * newest one of that name, whatever the case. Null when none matches.
+ */
+export function findAttachment(events: ReadonlyArray<MoxxyEvent>, query: string): FoundAttachment | null {
+  const wanted = query.trim();
+  const byKey = /^(\d+):(\d+)$/u.exec(wanted);
+  const name = wanted.toLowerCase();
+  for (const found of attachmentsNewestFirst(events)) {
+    if (byKey) {
+      if (found.seq === Number(byKey[1]) && found.index === Number(byKey[2])) return found;
+    } else if (found.attachment.name?.toLowerCase() === name) {
+      return found;
+    }
+  }
+  return null;
+}
+
+/** Every attachment of the conversation, oldest first, as `seq:index name`. */
+export function listAttachments(events: ReadonlyArray<MoxxyEvent>): string[] {
+  return [...attachmentsNewestFirst(events)]
+    .reverse()
+    .map(({ seq, index, attachment }) => `${attachmentKey(seq, index)} ${attachment.name ?? attachment.kind}`);
+}
+
+/**
+ * What `recall({ attachment })` returns for an image or a document: a pointer,
+ * not the bytes, which stay once in the log. The projection puts the
+ * attachment itself beside this result, so the model sees the original again
+ * even after its turn was summarized away.
+ */
+export interface RestoredAttachmentOutput {
+  readonly forModel: string;
+  readonly restoredAttachment: { readonly seq: number; readonly index: number };
+}
+
+/** The attachment a recall result restores, or null for any other output. */
+export function restoredAttachmentRef(output: unknown): { seq: number; index: number } | null {
+  if (typeof output !== 'object' || output === null) return null;
+  const ref = (output as { restoredAttachment?: unknown }).restoredAttachment;
+  if (typeof ref !== 'object' || ref === null) return null;
+  const { seq, index } = ref as { seq?: unknown; index?: unknown };
+  return typeof seq === 'number' && typeof index === 'number' ? { seq, index } : null;
+}

package/src/conduct.test.ts

@@ -1,8 +1,9 @@
 /**
  * How Moxxy conducts herself, whatever surface or mode the conversation is on.
  * Each rule answers a fault seen in a live session: live facts stated without
- * checking, a choice the user settled lost on a redo, and the voice and the
- * agent speaking of themselves in different grammatical genders in one chat.
+ * checking, a choice the user settled lost on a redo, the voice and the
+ * agent speaking of themselves in different grammatical genders in one chat,
+ * and a turn ended at the first failed step with an offer to continue.
  */
 import { describe, expect, it } from 'vitest';
 import type { ProviderRequest } from './provider.js';
@@ -38,6 +39,38 @@ describe('AGENT_CONDUCT', () => {
   it('holds the self-reference rule the voice uses too', () => {
     expect(AGENT_CONDUCT).toContain(SELF_REFERENCE_NOTE);
   });
+
+  it('works until the request is done and tries another route when a step fails', () => {
+    expect(AGENT_CONDUCT).toMatch(/Work until the user's request is done/);
+    expect(AGENT_CONDUCT).toMatch(/When a step fails, try another route yourself before ending the turn/);
+  });
+
+  it('takes the next step instead of announcing it, and does not ask again for what is settled', () => {
+    expect(AGENT_CONDUCT).toMatch(/Never end your reply by announcing or offering the next step — take it/);
+    expect(AGENT_CONDUCT).toMatch(/What the user already told you is settled; do not ask for it again/);
+  });
+
+  it('asks for no permission in chat for a step that can be undone and stays within the request', () => {
+    expect(AGENT_CONDUCT).toMatch(/can be undone, stays within what the user asked for/);
+    expect(AGENT_CONDUCT).toMatch(/breaks no limit the user or an approval rule set/);
+    expect(AGENT_CONDUCT).toMatch(/needs no new permission in chat/);
+  });
+
+  it('asks for what only the user has and before anything that cannot be undone', () => {
+    expect(AGENT_CONDUCT).toMatch(/something only they have \(a password or token/);
+    expect(AGENT_CONDUCT).toMatch(/before anything that cannot be undone or reaches beyond the request/);
+  });
+
+  it('does not work around a refusal or a look-only request, and waits after Stop', () => {
+    expect(AGENT_CONDUCT).toMatch(/a tool reports a missing permission/);
+    expect(AGENT_CONDUCT).toMatch(/only look and not change anything, do not work around it/);
+    expect(AGENT_CONDUCT).toMatch(/After the user presses Stop, stop and wait to be resumed/);
+  });
+
+  it('ends a turn unfinished only at a real block, naming what was tried', () => {
+    expect(AGENT_CONDUCT).toMatch(/End the turn unfinished only at a real block/);
+    expect(AGENT_CONDUCT).toMatch(/name what you tried\.$/);
+  });
 });
 
 describe('withAgentConduct', () => {

package/src/conduct.ts

@@ -11,6 +11,23 @@ export const SELF_REFERENCE_NOTE =
   '(Polish: "sprawdziłam", "ustawiłam", "jestem gotowa"; never "sprawdziłem"), in every reply, ' +
   'whatever earlier messages in the chat used.';
 
+/**
+ * A turn ends when the model answers without calling a tool, so a model that
+ * reports the first failed step and offers to go on leaves the user typing
+ * "continue". This names when ending early is right and when it is not.
+ */
+const PERSISTENCE_NOTE =
+  "Work until the user's request is done. When a step fails, try another route yourself before ending " +
+  'the turn. A step that can be undone, stays within what the user asked for and breaks no limit the ' +
+  'user or an approval rule set needs no new permission in chat — take it and say afterwards what you ' +
+  'did. Never end your reply by announcing or offering the next step — take it. What the user already ' +
+  'told you is settled; do not ask for it again. Ask the user when you need something only they have ' +
+  '(a password or token, a choice between results that really differ) and before anything that cannot ' +
+  'be undone or reaches beyond the request. When a tool reports a missing permission, or the user said ' +
+  'to only look and not change anything, do not work around it. After the user presses Stop, stop and ' +
+  'wait to be resumed. End the turn unfinished only at a real block — one of the above, or no route ' +
+  'left after several different ones failed — and name what you tried.';
+
 const MARKER = '## How Moxxy works';
 
 /** Appended to every agent request, in every mode and on every surface. */
@@ -25,6 +42,7 @@ export const AGENT_CONDUCT = [
     'choice the user already settled — dates, one-way or return, sizes, names, filters — unless the user ' +
     'changed it, and check that the result shows them before you report.',
   SELF_REFERENCE_NOTE,
+  PERSISTENCE_NOTE,
 ].join('\n');
 
 /**

package/src/define.ts

@@ -52,6 +52,7 @@ export function defineTool<S extends z.ZodTypeAny, O = unknown>(spec: {
   liveState?: boolean;
   alwaysLoaded?: boolean;
   modes?: ReadonlyArray<string>;
+  refusalEndsTurn?: string;
 }): ToolDef {
   return Object.freeze({
     name: spec.name,
@@ -67,6 +68,7 @@ export function defineTool<S extends z.ZodTypeAny, O = unknown>(spec: {
     isolation: spec.isolation,
     ...(spec.liveState ? { liveState: true } : {}),
     ...(spec.alwaysLoaded ? { alwaysLoaded: true } : {}),
+    ...(spec.refusalEndsTurn !== undefined ? { refusalEndsTurn: spec.refusalEndsTurn } : {}),
     ...(spec.modes ? { modes: Object.freeze([...spec.modes]) } : {}),
   });
 }

package/src/events.ts

@@ -48,6 +48,12 @@ export interface UserPromptAttachment {
   readonly name?: string;
   /** MIME type — required for `image`, `document`, and raw `audio` so providers translate correctly. */
   readonly mediaType?: string;
+  /**
+   * Set only on a client's copy of the event: the payload was too large to send
+   * to clients, so `content` is empty and this is the real size in bytes. The
+   * bytes stay in the runner's log; `session.readAttachment` reads them back.
+   */
+  readonly omittedBytes?: number;
 }
 
 /**
@@ -107,6 +113,12 @@ export interface ReasoningChunkEvent extends EventBase {
   readonly delta: string;
 }
 
+/** Provider-owned reasoning state, kept opaque and replayed only to its origin. */
+export interface ReasoningReplayItem {
+  readonly provider: string;
+  readonly item: Readonly<Record<string, unknown>>;
+}
+
 /**
  * A finalized reasoning summary for ONE provider call. Parallels
  * {@link AssistantMessageEvent}: it is persisted + replayed, and because
@@ -126,6 +138,7 @@ export interface ReasoningMessageEvent extends EventBase {
   readonly redacted?: boolean;
   /** Opaque provider blob (Anthropic redacted_thinking data / Codex encrypted_content) replayed as-is. */
   readonly encrypted?: string;
+  readonly replayItems?: ReadonlyArray<ReasoningReplayItem>;
 }
 
 export interface ToolCallRequestedEvent extends EventBase {

package/src/index.ts

@@ -22,6 +22,7 @@ export type {
   AssistantMessageEvent,
   ReasoningChunkEvent,
   ReasoningMessageEvent,
+  ReasoningReplayItem,
   ToolCallRequestedEvent,
   ToolCallApprovedEvent,
   ToolCallDeniedEvent,
@@ -311,6 +312,25 @@ export {
   type JsonFileStoreOptions,
 } from './json-file-store.js';
 export { assertDefined, assertNever, invariant } from './assert.js';
+export {
+  ATTACHMENT_READ_CHUNK_CHARS,
+  CLIENT_INLINE_ATTACHMENT_CHARS,
+  CLIENT_INLINE_EVENT_CHARS,
+  HISTORY_PAGE_MAX_CHARS,
+  MODEL_ATTACHMENT_BUDGET_CHARS,
+  attachmentBytes,
+  attachmentKey,
+  eventForClient,
+  findAttachment,
+  historyPageForClient,
+  listAttachments,
+  readAttachmentChunk,
+  restoredAttachmentRef,
+  type AttachmentChunk,
+  type FoundAttachment,
+  type HistoryPage,
+  type RestoredAttachmentOutput,
+} from './attachment-payload.js';
 export { compareSemver, parseSemverCore } from './semver.js';
 // readRequestBody/bearerTokenMatches (http-utils) and the channel-auth value
 // helpers live on the './server' subpath — they reach node:http/crypto/fs/path.
@@ -423,6 +443,7 @@ export {
   unfinishedWorkNudge,
   type Progress,
 } from './progress.js';
+export { openShortfall, shortfallNudge, shortfallOf, unfinishedStepCheckpoint, type Shortfall } from './shortfall.js';
 export { AGENT_CONDUCT, SELF_REFERENCE_NOTE, withAgentConduct } from './conduct.js';
 export {
   applyLazyTools,

package/src/mode/collect-stream.ts

@@ -2,7 +2,7 @@ import type { ProviderEvent, ProviderMessage, TokenUsage } from '../provider.js'
 import type { ModeContext } from '../mode.js';
 import type { StopReason } from '../provider-utils.js';
 import { applyLazyTools, shouldGateTools } from '../tool-gating.js';
-import type { ProviderCallTiming } from '../events.js';
+import type { ProviderCallTiming, ReasoningReplayItem } from '../events.js';
 import { providerTiming } from './provider-timing.js';
 
 /**
@@ -58,6 +58,7 @@ export interface StreamResult {
     readonly signature?: string;
     readonly redacted?: boolean;
     readonly encrypted?: string;
+    readonly replayItems?: ReadonlyArray<ReasoningReplayItem>;
   };
 }
 
@@ -185,6 +186,7 @@ export async function collectProviderStream(
   let reasoningSignature: string | undefined;
   let reasoningRedacted = false;
   let reasoningEncrypted: string | undefined;
+  const reasoningReplayItems: ReasoningReplayItem[] = [];
 
   let stream: AsyncIterable<ProviderEvent>;
   try {
@@ -255,6 +257,7 @@ export async function collectProviderStream(
           if (event.signature) reasoningSignature = event.signature;
           if (event.encrypted) reasoningEncrypted = event.encrypted;
           if (event.redacted) reasoningRedacted = true;
+          if (event.replayItem) reasoningReplayItems.push(event.replayItem);
           break;
         }
         case 'message_start':
@@ -286,12 +289,13 @@ export async function collectProviderStream(
   // Surface reasoning when there's visible text OR an opaque blob to replay
   // (a redacted_thinking block has no text but must still round-trip).
   const reasoning =
-    reasoningText.trim().length > 0 || reasoningEncrypted
+    reasoningText.trim().length > 0 || reasoningEncrypted || reasoningReplayItems.length > 0
       ? {
           text: reasoningText,
           ...(reasoningSignature ? { signature: reasoningSignature } : {}),
           ...(reasoningRedacted ? { redacted: true } : {}),
           ...(reasoningEncrypted ? { encrypted: reasoningEncrypted } : {}),
+          ...(reasoningReplayItems.length > 0 ? { replayItems: reasoningReplayItems } : {}),
         }
       : undefined;
   return {

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

@@ -1,5 +1,11 @@
 import { describe, expect, it } from 'vitest';
-import { projectMessagesFromLog, projectUserPrompt, resolvedCallIdSet, skillsWithinReach } from './project-messages.js';
+import { MODEL_ATTACHMENT_BUDGET_CHARS } from '../attachment-payload.js';
+import {
+  projectMessagesFromLog,
+  projectUserPrompt,
+  resolvedCallIdSet,
+  skillsWithinReach,
+} from './project-messages.js';
 import type { Skill } from '../skill.js';
 import { computeElisionState } from '../elision-state.js';
 import { asEventId, asSessionId, asTurnId } from '../ids.js';
@@ -252,3 +258,103 @@ describe('projectMessagesFromLog tool pairing across a compaction boundary', ()
     });
   });
 });
+
+describe('projectMessagesFromLog attachment budget', () => {
+  const pdf = (name: string, chars: number) => ({
+    kind: 'document' as const,
+    content: 'A'.repeat(chars),
+    mediaType: 'application/pdf',
+    name,
+  });
+  const blocksOf = (events: ReadonlyArray<MoxxyEvent>) =>
+    projectMessagesFromLog({ log: reader(events) }).flatMap((m) => m.content);
+
+  it('sends the newest attachments in full and names the older ones that no longer fit', () => {
+    const half = Math.floor(MODEL_ATTACHMENT_BUDGET_CHARS * 0.6);
+    const blocks = blocksOf([
+      userPrompt(0, { text: 'first scan', attachments: [pdf('old-scan.pdf', half)] }),
+      userPrompt(1, { text: 'second scan', attachments: [pdf('new-scan.pdf', half)] }),
+    ]);
+    const documents = blocks.filter((b) => b.type === 'document');
+    expect(documents).toHaveLength(1);
+    expect(documents[0]).toMatchObject({ name: 'new-scan.pdf' });
+    const note = blocks.find((b) => b.type === 'text' && b.text.includes('old-scan.pdf'));
+    expect(note).toBeDefined();
+    const sent = blocks.reduce((n, b) => n + (b.type === 'document' ? b.data.length : 0), 0);
+    expect(sent).toBeLessThanOrEqual(MODEL_ATTACHMENT_BUDGET_CHARS);
+  });
+
+  it('tells the model how to bring a left-out attachment back', () => {
+    const half = Math.floor(MODEL_ATTACHMENT_BUDGET_CHARS * 0.6);
+    const blocks = blocksOf([
+      userPrompt(0, { text: 'first scan', attachments: [pdf('old-scan.pdf', half)] }),
+      userPrompt(1, { text: 'second scan', attachments: [pdf('new-scan.pdf', half)] }),
+    ]);
+    const note = blocks.find((b) => b.type === 'text' && b.text.includes('old-scan.pdf'));
+    expect(note).toMatchObject({ text: expect.stringContaining('recall({ attachment: "0:0" })') });
+  });
+
+  const restore = (seq: number, callId: string, ref: { seq: number; index: number }): MoxxyEvent[] => [
+    event(seq, { type: 'tool_call_requested', turnId: t1, source: 'model', callId, name: 'recall', input: { attachment: `${ref.seq}:${ref.index}` } }),
+    event(seq + 1, {
+      type: 'tool_result',
+      turnId: t1,
+      source: 'tool',
+      callId,
+      ok: true,
+      output: { forModel: 'restored old-scan.pdf', restoredAttachment: ref },
+    }),
+  ];
+
+  it('shows a restored attachment again beside the recall result, within the same budget', () => {
+    const half = Math.floor(MODEL_ATTACHMENT_BUDGET_CHARS * 0.6);
+    const messages = projectMessagesFromLog({
+      log: reader([
+        userPrompt(0, { text: 'first scan', attachments: [pdf('old-scan.pdf', half)] }),
+        userPrompt(1, { text: 'second scan', attachments: [pdf('new-scan.pdf', half)] }),
+        userPrompt(2, { text: 'back to the first one' }),
+        ...restore(3, 'r1', { seq: 0, index: 0 }),
+      ]),
+    });
+    const result = messages.find((m) => m.role === 'tool_result');
+    expect(result?.content).toEqual([
+      { type: 'tool_result', toolUseId: 'r1', content: 'restored old-scan.pdf', isError: false },
+      { type: 'document', mediaType: 'application/pdf', data: 'A'.repeat(half), name: 'old-scan.pdf' },
+    ]);
+    const blocks = messages.flatMap((m) => m.content);
+    expect(blocks.filter((b) => b.type === 'document')).toHaveLength(1);
+    expect(blocks.some((b) => b.type === 'text' && b.text.includes('new-scan.pdf'))).toBe(true);
+  });
+
+  it('restores an attachment whose turn a compaction summarized away', () => {
+    const messages = projectMessagesFromLog({
+      log: reader([
+        userPrompt(0, { text: 'the contract', attachments: [pdf('umowa.pdf', 100)] }),
+        event(1, {
+          type: 'compaction',
+          turnId: t1,
+          source: 'compactor',
+          compactor: 'segments',
+          replacedRange: [0, 0],
+          summary: 'the person shared umowa.pdf',
+          tokensSaved: 10,
+        }),
+        userPrompt(2, { text: 'what was in point 7?' }),
+        ...restore(3, 'r1', { seq: 0, index: 0 }),
+      ]),
+    });
+    const documents = messages.flatMap((m) => m.content).filter((b) => b.type === 'document');
+    expect(documents).toEqual([{ type: 'document', mediaType: 'application/pdf', data: 'A'.repeat(100), name: 'umowa.pdf' }]);
+  });
+
+  it('never sends an empty payload for an attachment whose bytes were left out', () => {
+    const blocks = projectUserPrompt(
+      userPrompt(0, {
+        attachments: [{ kind: 'image', content: '', mediaType: 'image/png', name: 'shot.png', omittedBytes: 2048 }],
+      }),
+      noElision,
+    );
+    expect(blocks.some((b) => b.type === 'image')).toBe(false);
+    expect(blocks.some((b) => b.type === 'text' && b.text.includes('shot.png'))).toBe(true);
+  });
+});