@genesislcap/ai-assistant 15.15.2 → 15.16.0

package/src/main/file-attachments.test.ts

@@ -0,0 +1,215 @@
+import { assert, createLogicSuite } from '@genesislcap/foundation-testing';
+import { FoundationAiAssistant } from './main';
+
+// Hold a reference so the custom-element registration isn't tree-shaken.
+FoundationAiAssistant;
+
+// GENC-1508 — image files become IMAGE attachments, not text.
+//
+// `processFiles` read every accepted file with `readAsText`, so an accepted .png
+// arrived as mojibake the model "read" as prose — an accepted image was worse than a
+// rejected one. The layout-apply flow attaches the picked mockup's PNG beside its
+// spec, which is what forced the branch: images now read as base64 and ship as
+// `{kind:'image'}`, the shape the transports render as real image blocks.
+//
+// Unconnected elements (createElement upgrades but does not connect), same as
+// blocked-state.test.ts — processFiles touches no session state.
+
+const Suite = createLogicSuite('FoundationAiAssistant file attachments');
+
+type ProcessFiles = {
+  processFiles(
+    files: File[],
+    existingBytes?: number,
+  ): Promise<{ attachments: unknown[]; errors: string[] }>;
+};
+
+function element(acceptedFiles: string): ProcessFiles {
+  const el = document.createElement('foundation-ai-assistant') as FoundationAiAssistant;
+  el.chatConfig = { ui: { acceptedFiles } };
+  return el as unknown as ProcessFiles;
+}
+
+/** A tiny valid PNG header is unnecessary — processFiles never parses pixels. */
+const PNG_BYTES = new Uint8Array([137, 80, 78, 71, 13, 10, 26, 10]);
+
+Suite('an accepted image file becomes a kind:image attachment with raw base64', async () => {
+  const el = element('.md,image/*');
+  const { attachments, errors } = await el.processFiles([
+    new File([PNG_BYTES], 'layout-mockup.png', { type: 'image/png' }),
+  ]);
+  assert.equal(errors, []);
+  const [img] = attachments as Array<{
+    kind?: string;
+    name: string;
+    mimeType: string;
+    data?: string;
+  }>;
+  assert.is(img.kind, 'image');
+  assert.is(img.name, 'layout-mockup.png');
+  assert.is(img.mimeType, 'image/png');
+  // RAW base64 — a `data:` prefix left on would be sent to the vendor inside the payload.
+  assert.ok(img.data && !img.data.startsWith('data:'), 'data must be bare base64');
+  assert.is(atob(img.data!).length, PNG_BYTES.length);
+});
+
+Suite('a text file on the same submit stays a text attachment', async () => {
+  const el = element('.md,image/*');
+  const { attachments } = await el.processFiles([
+    new File(['# spec'], 'layout-spec.md', { type: 'text/markdown' }),
+    new File([PNG_BYTES], 'layout-mockup.png', { type: 'image/png' }),
+  ]);
+  const [text, img] = attachments as Array<{ kind?: string; content?: string; data?: string }>;
+  assert.is(text.kind, undefined);
+  assert.is(text.content, '# spec');
+  assert.is(img.kind, 'image');
+});
+
+Suite('an image type the host did not accept is still refused', async () => {
+  const el = element('.md,.txt');
+  const { attachments, errors } = await el.processFiles([
+    new File([PNG_BYTES], 'layout-mockup.png', { type: 'image/png' }),
+  ]);
+  assert.equal(attachments, []);
+  assert.is(errors.length, 1);
+  assert.match(errors[0], /not an accepted file type/);
+});
+
+// A ~70KB image: the base64 loop's chunk size is 32768, so this crosses the boundary twice.
+// The 8-byte fixture above executes the loop body exactly once, which would not notice an
+// off-by-one in the subarray bounds.
+Suite('a multi-chunk image round-trips byte-for-byte across the base64 loop', async () => {
+  const big = new Uint8Array(70_000);
+  // A non-trivial pattern — an all-zero buffer survives most encoding mistakes.
+  for (let i = 0; i < big.length; i += 1) big[i] = (i * 31 + (i >> 8)) & 0xff;
+  const el = element('image/*');
+  const { attachments, errors } = await el.processFiles([
+    new File([big], 'wide.png', { type: 'image/png' }),
+  ]);
+  assert.equal(errors, []);
+  const [img] = attachments as Array<{ data: string }>;
+  const back = atob(img.data);
+  assert.is(back.length, big.length);
+  let mismatch = -1;
+  for (let i = 0; i < big.length; i += 1) {
+    if (back.charCodeAt(i) !== big[i]) {
+      mismatch = i;
+      break;
+    }
+  }
+  assert.is(mismatch, -1, 'every byte must survive the chunked encode');
+});
+
+Suite(
+  'an image over the size cap is refused by NAME and size, not sent to the vendor',
+  async () => {
+    // Refused here rather than at the API: a vendor 400 lands after the user has waited out the
+    // turn, and the encoded blob is persisted meanwhile — one oversized image can blow the storage
+    // quota and silently stop the session autosaving.
+    const el = element('image/*');
+    const { attachments, errors } = await el.processFiles([
+      new File([new Uint8Array(4_000_000)], 'huge.png', { type: 'image/png' }),
+    ]);
+    assert.equal(attachments, []);
+    assert.is(errors.length, 1);
+    assert.match(errors[0], /huge\.png/);
+    assert.match(errors[0], /limited to/);
+  },
+);
+
+Suite(
+  'an image type the vendors do not accept falls back to TEXT, never a failed turn',
+  async () => {
+    // `image/*` covers HEIC, BMP, TIFF, SVG — none of which the APIs take, and sending one fails
+    // the whole turn. SVG especially: it IS text, so the text branch gives the model something it
+    // can actually read.
+    const el = element('image/*');
+    const { attachments, errors } = await el.processFiles([
+      new File(['<svg xmlns="http://www.w3.org/2000/svg"><rect /></svg>'], 'icon.svg', {
+        type: 'image/svg+xml',
+      }),
+      new File([new Uint8Array([0, 1, 2, 3])], 'photo.heic', { type: 'image/heic' }),
+    ]);
+    assert.equal(errors, []);
+    const [svg, heic] = attachments as Array<{ kind?: string; content?: string; mimeType: string }>;
+    assert.is(svg.kind, undefined, 'SVG stays text — a model can read it');
+    assert.match(svg.content!, /<rect/);
+    assert.is(heic.kind, undefined, 'an unsupported binary degrades rather than failing the turn');
+  },
+);
+
+Suite('every supported spelling takes the image branch, including image/jpg', async () => {
+  const el = element('image/*');
+  const { attachments } = await el.processFiles(
+    ['image/png', 'image/jpeg', 'image/jpg', 'image/gif', 'image/webp'].map(
+      (type, i) => new File([PNG_BYTES], `f${i}`, { type }),
+    ),
+  );
+  assert.equal(
+    (attachments as Array<{ kind?: string }>).map((a) => a.kind),
+    ['image', 'image', 'image', 'image', 'image'],
+  );
+});
+
+// The TOTAL, not just each file. `loadSelectedFiles` appends across successive picks and the
+// per-file check is blind to what is already attached, so ten files each just under the per-image
+// ceiling used to be ten passes and one ~34MB request — assembled entirely out of files that each
+// passed. Reviewer catch on #2474.
+
+Suite('the file that crosses the total is refused; the ones that fit are kept', async () => {
+  const el = element('image/*');
+  const mb = (n: number) => new Uint8Array(n * 1_000_000);
+  const { attachments, errors } = await el.processFiles([
+    new File([mb(3)], 'a.png', { type: 'image/png' }),
+    new File([mb(3)], 'b.png', { type: 'image/png' }),
+    new File([mb(3)], 'c.png', { type: 'image/png' }), // 9MB total — past the 8MB ceiling
+  ]);
+  assert.is(attachments.length, 2, 'the two that fit are accepted');
+  assert.is(errors.length, 1);
+  assert.match(errors[0], /c\.png/);
+  assert.match(errors[0], /attachment limit/);
+});
+
+Suite('the budget counts what is ALREADY attached, not just this pick', async () => {
+  // The picker's second pick has to see the first one's bytes, or "under the limit" is measured
+  // against zero every time and the limit means nothing.
+  const el = element('image/*');
+  const fresh = await el.processFiles([
+    new File([new Uint8Array(3_000_000)], 'a.png', { type: 'image/png' }),
+  ]);
+  assert.is(fresh.attachments.length, 1, 'fits on its own');
+
+  const withHistory = await el.processFiles(
+    [new File([new Uint8Array(3_000_000)], 'b.png', { type: 'image/png' })],
+    6_000_000,
+  );
+  assert.is(
+    withHistory.attachments.length,
+    0,
+    'the same file is refused once 6MB is already committed',
+  );
+  assert.match(withHistory.errors[0], /6\.0MB already attached/);
+});
+
+Suite('a refusal skips only the offending file — a later one that still fits is kept', async () => {
+  // Budgeted synchronously off `file.size`, in the user's own pick order, before anything is read
+  // (deciding inside the parallel reads would hand the last slot to whichever finished first).
+  // A file that does not fit is refused and the budget carries on, so a smaller one behind it is
+  // not punished for its neighbour.
+  const el = element('image/*');
+  const mb = (n: number) => new Uint8Array(n * 1_000_000);
+  const { attachments, errors } = await el.processFiles([
+    new File([mb(3)], 'a.png', { type: 'image/png' }), // running 3
+    new File([mb(3)], 'b.png', { type: 'image/png' }), // running 6
+    new File([mb(3)], 'big.png', { type: 'image/png' }), // 9 > 8 — refused
+    new File([mb(1)], 'small.png', { type: 'image/png' }), // 7 — still fits
+  ]);
+  assert.equal(
+    (attachments as Array<{ name: string }>).map((a) => a.name),
+    ['a.png', 'b.png', 'small.png'],
+  );
+  assert.is(errors.length, 1);
+  assert.match(errors[0], /big\.png/);
+});
+
+Suite.run();

package/src/main/interaction-cost.test.ts

@@ -0,0 +1,140 @@
+import { assert, createLogicSuite } from '@genesislcap/foundation-testing';
+import { getSessionStore } from '../state/session-store';
+import { FoundationAiAssistant } from './main';
+
+// Hold a reference so the custom-element registration isn't tree-shaken.
+FoundationAiAssistant;
+
+// GENC-1508 — the host hop of the post-resolve cost channel.
+//
+// The driver method and the orchestrator delegation both have tests; this pins the hop
+// between them, which is the one most likely to break silently: a rename on either side of
+// `handleInteractionCost` is a no-op that every other test still passes, and the "no spinner"
+// guarantee is a design promise stated only in a comment.
+//
+// Unconnected element (createElement upgrades but does not connect), same as
+// blocked-state.test.ts — this handler touches no session state.
+
+const Suite = createLogicSuite('FoundationAiAssistant interaction cost');
+
+type CostHost = {
+  handleInteractionCost(e: Event): void;
+  driver: unknown;
+  startLoadingTimer(): void;
+};
+
+function host(): { el: CostHost; calls: Array<[string, number]>; spinners: number } {
+  const el = document.createElement('foundation-ai-assistant') as unknown as CostHost;
+  const calls: Array<[string, number]> = [];
+  const state = { spinners: 0 };
+  el.driver = {
+    recordExternalCost: (id: string, cost: number) => {
+      calls.push([id, cost]);
+      return true;
+    },
+  };
+  el.startLoadingTimer = () => {
+    state.spinners += 1;
+  };
+  return {
+    el,
+    calls,
+    get spinners() {
+      return state.spinners;
+    },
+  };
+}
+
+const costEvent = (detail: unknown) => new CustomEvent('interaction-cost', { detail });
+
+Suite('a cost report reaches the driver', () => {
+  const h = host();
+  h.el.handleInteractionCost(costEvent({ interactionId: 'abc', costUsd: 0.42 }));
+  assert.equal(h.calls, [['abc', 0.42]]);
+});
+
+Suite('reporting cost NEVER starts the loading spinner', () => {
+  // The whole point of the channel: this is bookkeeping about a turn that already finished, so
+  // it must be invisible. A spinner would tell the user the assistant is working when nothing
+  // is pending — the one thing `handleInteractionCompleted` does that this must not copy.
+  const h = host();
+  h.el.handleInteractionCost(costEvent({ interactionId: 'abc', costUsd: 0.42 }));
+  assert.is(h.spinners, 0);
+});
+
+Suite('an event with no interactionId is ignored', () => {
+  const h = host();
+  h.el.handleInteractionCost(costEvent({ costUsd: 0.42 }));
+  h.el.handleInteractionCost(costEvent(undefined));
+  assert.equal(h.calls, []);
+});
+
+Suite('a driver that does not implement the optional method is not called into', () => {
+  // `recordExternalCost` is optional on `AiDriver`, so a driver predating this — or one that
+  // simply does not track spend — must be ignored rather than throw.
+  const h = host();
+  h.el.driver = {};
+  assert.not.throws(() =>
+    h.el.handleInteractionCost(costEvent({ interactionId: 'a', costUsd: 1 })),
+  );
+  h.el.driver = undefined;
+  assert.not.throws(() =>
+    h.el.handleInteractionCost(costEvent({ interactionId: 'a', costUsd: 1 })),
+  );
+});
+
+Suite('a driver without the method leaves a TRACE, not a silent no-op', () => {
+  // Reviewer catch on #2474: every other hop traces its drops. A driver predating
+  // `recordExternalCost` made this one a silent no-op — money gone, nothing recorded — which is
+  // the invisible gap the whole channel exists to close, reintroduced at the last hop.
+  const h = host();
+  const meta: Array<[string, Record<string, unknown>]> = [];
+  (h.el as unknown as { logMeta(t: string, d: Record<string, unknown>): void }).logMeta = (
+    t,
+    d,
+  ) => {
+    meta.push([t, d]);
+  };
+  h.el.driver = {};
+  h.el.handleInteractionCost(costEvent({ interactionId: 'abc', costUsd: 0.42 }));
+  assert.is(meta.length, 1);
+  assert.is(meta[0][0], 'interaction.external-cost-dropped');
+  assert.is(meta[0][1].costUsd, 0.42);
+  assert.is(meta[0][1].interactionId, 'abc');
+});
+
+// The OUTBOUND half: the driver announced, and the host has to turn that into a moved number.
+// Tested because it is the same shape of hop as the one that already went wrong — the wrapper
+// forward that was missing — and because it deliberately reads the DRIVER's history rather than
+// `this.messages`, which is the part a reader would most likely "simplify" back.
+
+let storeSeq = 0;
+
+/** An element wired to its own real session store, so `sessionUsage` round-trips. */
+function costHost(): FoundationAiAssistant {
+  const el = document.createElement('foundation-ai-assistant') as FoundationAiAssistant;
+  storeSeq += 1;
+  (el as unknown as { _sessionRef: unknown })._sessionRef = getSessionStore(
+    `cost-test-${(storeSeq += 1)}`,
+    false,
+  );
+  return el;
+}
+
+Suite('the recorded spend reaches the session total from the DRIVER history', () => {
+  const el = costHost();
+  const sync = (el as unknown as { syncUsageTotals(m: unknown[]): void }).syncUsageTotals.bind(el);
+
+  sync([{ role: 'assistant', content: 'a', cost: 0.1, model: 'claude-sonnet-5' }]);
+  assert.is(el.sessionCostUsd, 0.1);
+
+  // The post-resolve delta lands on the interaction message as `externalCostUsd`; the total has
+  // to fold it in, or every hop before this one was wasted.
+  sync([
+    { role: 'assistant', content: 'a', cost: 0.1, model: 'claude-sonnet-5' },
+    { role: 'assistant', content: 'b', externalCostUsd: 0.25 },
+  ]);
+  assert.is(el.sessionCostUsd, 0.35);
+});
+
+Suite.run();

package/src/main/main.template.ts

@@ -624,6 +624,7 @@ ${(tc) => (tc.foldPath?.length ? `${tc.foldPath.join(' › ')} › ` : '')}<stro
                     :interactionId=${(m) => m.interaction!.interactionId}
                     :resolved=${(m) => m.interaction!.resolved}
                     @interaction-completed=${(m, c) => c.parent.handleInteractionCompleted(c.event)}
+                    @interaction-cost=${(m, c) => c.parent.handleInteractionCost(c.event)}
                   ></ai-chat-interaction-wrapper>
                 `,
               )}

package/src/main/main.ts

@@ -220,6 +220,67 @@ const SESSION_MENU_CLOSE_MS = 200;
  */
 const LEDGER_FLUSH_DEBOUNCE_MS = 2000;
 
+/**
+ * The image types BOTH vendors accept, and therefore the only ones sent as image blocks.
+ *
+ * A host's `acceptedFiles` may well say `image/*`, which covers HEIC, BMP, TIFF, AVIF and SVG —
+ * none of which the APIs take. Sending one fails the whole turn the user is waiting on, so
+ * anything outside this set falls through to the text branch instead: harmless for a binary, and
+ * genuinely useful for SVG, which is text a model can read.
+ *
+ * `image/jpg` is absent on purpose — `normalizeImageMime` rewrites it to `image/jpeg` at the
+ * transport, but a file arriving with that spelling is still a real JPEG, so it is accepted here.
+ */
+const VENDOR_IMAGE_MIME_TYPES = new Set([
+  'image/jpeg',
+  'image/jpg',
+  'image/png',
+  'image/gif',
+  'image/webp',
+]);
+
+/**
+ * Ceiling on ONE image attachment, under Anthropic's ~5MB-per-image limit with room for the ~33%
+ * base64 overhead. Refused here, with the size named, rather than at the vendor: a 400 arrives
+ * only after the user has waited out the turn.
+ *
+ * A VENDOR guard, and only that. An earlier version of this comment also claimed it protected the
+ * session's storage quota — it does not, and the arithmetic says so: one file at this ceiling is
+ * ~4.7MB of base64, which alone can exceed a 5MB `localStorage` budget before the transcript is
+ * counted. Attachments riding into persisted storage is a real and separate problem; it is not
+ * this constant's to solve, and saying otherwise hid it.
+ */
+const MAX_IMAGE_ATTACHMENT_BYTES = 3_500_000;
+
+/**
+ * Ceiling on ALL attachments carried by one message, across every type and every successive pick.
+ *
+ * The per-file check above is blind to the total: the picker APPENDS (`loadSelectedFiles`), so ten
+ * files each just under the per-image limit are ten passes and one ~34MB request. Sized against
+ * the vendors' request ceilings — comfortably inside the smaller of them with room for the
+ * transcript itself — so a turn that would be rejected wholesale is refused here, where the user
+ * can still act on it, naming the file that crossed the line.
+ *
+ * Like its sibling, this does NOT make attachments safe to persist — 8MB of attachments is still
+ * ~10.7MB of base64. What a persisted session should keep of its images is GENC-1531; note the
+ * transports also REPLAY history attachments on every later call, so it is a recurring cost as
+ * well as a storage one.
+ */
+const MAX_ATTACHMENTS_TOTAL_BYTES = 8_000_000;
+
+/** Base64 carries 3 bytes in every 4 characters, so decoded size is 3/4 of the encoded length. */
+const BASE64_DECODED_RATIO = 0.75;
+
+/** A rough byte size for an already-accepted attachment, for budgeting against the total cap. */
+function attachmentBytes(a: ChatAttachment): number {
+  return a.kind === 'image'
+    ? Math.ceil((a.data?.length ?? 0) * BASE64_DECODED_RATIO)
+    : (a.content?.length ?? 0);
+}
+
+/** Bytes per megabyte, for the size the refusal message quotes back to the user. */
+const BYTES_PER_MB = 1_000_000;
+
 /**
  * Reporter id for this element's OWN session persister in `brokenSources` (GENC-1511).
  *
@@ -2711,6 +2772,22 @@ export class FoundationAiAssistant extends GenesisElement {
     };
     driver.addEventListener('history-updated', onHistoryUpdated);
 
+    // Post-resolve external cost. Deliberately does NOT reassign `messages`: that would rebuild
+    // the trailing interaction row (a `recycle: false` repeat) and blank the widget that just
+    // reported — see `recordExternalCost`. The totals come off the DRIVER's history because the
+    // host's copy holds the pre-update message objects, and the persister already reads the
+    // driver first, so the save picks the field up with no help from here.
+    const onExternalCostRecorded = () => {
+      if (driver.getRawHistory) this.syncUsageTotals(driver.getRawHistory());
+      this.persister()?.scheduleSave();
+      // Diagnostics too, for the same reason `onHistoryUpdated` schedules both: the forward-append
+      // is what carries `interaction.external-cost` (and its `-dropped` sibling) into the persisted
+      // stream. Without it the trace this change adds sits in memory waiting for activity that,
+      // in this flow, never comes — the interaction is the last thing in the session.
+      this.persister()?.scheduleDiagnostics();
+    };
+    driver.addEventListener('external-cost-recorded', onExternalCostRecorded);
+
     // Re-seed the rendered list from the driver's current history. `wireDriver`
     // runs on (re)connect, popin, and when adopting a sibling's driver
     // (GENC-1388); in those cases `messages` would otherwise stay stale until the
@@ -2791,6 +2868,7 @@ export class FoundationAiAssistant extends GenesisElement {
 
     const cleanups: (() => void)[] = [
       () => driver.removeEventListener('history-updated', onHistoryUpdated),
+      () => driver.removeEventListener('external-cost-recorded', onExternalCostRecorded),
       () => driver.removeEventListener('sub-agent-history-updated', onSubAgentHistoryUpdated),
       () => driver.removeEventListener('sub-agent-start', onSubAgentStart),
       () => driver.removeEventListener('sub-agent-stop', onSubAgentStop),
@@ -3281,6 +3359,39 @@ export class FoundationAiAssistant extends GenesisElement {
     this.showingSplash = !!this.chatConfig.ui?.showSplash && this.messages.length === 0;
   }
 
+  /**
+   * Recompute the session's cost and token buckets from a transcript.
+   *
+   * Takes the list rather than reading `this.messages`, because it has two callers with
+   * different sources: the `messages` setter passes the rendered list, and post-resolve external
+   * cost passes the DRIVER's history — spend recorded there must reach the total WITHOUT
+   * reassigning `messages`, which would re-render the live interaction row. See
+   * `onExternalCostRecorded`.
+   *
+   * Recomputing (rather than incrementing on append) keeps the totals correct under any mutation
+   * of the message list — clear-chat, re-render, restore. `sumUsage` recurses into
+   * `toolCall.subAgentTrace`, so work a sub-agent did (possibly on another provider at other
+   * rates) counts, and it reads the usage a compaction banked onto its summary, so shrinking
+   * history no longer shrinks the totals.
+   */
+  private syncUsageTotals(messages: readonly ChatMessage[]): void {
+    const running = sumUsage(messages);
+    const current = this.sessionUsage;
+    if (
+      running.costUsd !== current.costUsd ||
+      running.uncachedInputTokens !== current.uncachedInputTokens ||
+      running.cacheReadTokens !== current.cacheReadTokens ||
+      running.cacheWriteTokens !== current.cacheWriteTokens ||
+      running.outputTokens !== current.outputTokens
+    ) {
+      this.sessionUsage = running;
+      // Keep this project's history row current as spend accrues, which is what lets
+      // the Usage tab total be the sum of the rows alone. Idempotent (an upsert keyed
+      // by the session key), so calling it per change is safe.
+      this.finalizeCostSession();
+    }
+  }
+
   /**
    * Runs side effects that were previously in `messagesChanged()`.
    * Called from the `messages` setter after dispatching to the store.
@@ -3317,21 +3428,7 @@ export class FoundationAiAssistant extends GenesisElement {
     // recurses into `toolCall.subAgentTrace`, so work a sub-agent did (possibly on
     // another provider at other rates) counts, and it reads the usage a compaction
     // banked onto its summary, so shrinking history no longer shrinks the totals.
-    const running = sumUsage(this.messages);
-    const current = this.sessionUsage;
-    if (
-      running.costUsd !== current.costUsd ||
-      running.uncachedInputTokens !== current.uncachedInputTokens ||
-      running.cacheReadTokens !== current.cacheReadTokens ||
-      running.cacheWriteTokens !== current.cacheWriteTokens ||
-      running.outputTokens !== current.outputTokens
-    ) {
-      this.sessionUsage = running;
-      // Keep this project's history row current as spend accrues, which is what lets
-      // the Usage tab total be the sum of the rows alone. Idempotent (an upsert keyed
-      // by the session key), so calling it per change is safe.
-      this.finalizeCostSession();
-    }
+    this.syncUsageTotals(this.messages);
     // Record a context.updated meta event when the token count changes (≈once
     // per LLM call, as a new usage-bearing message arrives), plus a one-shot
     // threshold-crossed event the first time usage passes 80%.
@@ -4661,25 +4758,82 @@ export class FoundationAiAssistant extends GenesisElement {
     );
   }
 
+  // Blob's own promise APIs, not FileReader: UTF-8 only (a `charset` parameter on the blob's
+  // type is ignored, where FileReader would honour it), and they exist in the node test runtime
+  // too — FileReader does not, so neither reader was testable before.
   private readFileAsText(file: File): Promise<string> {
-    return new Promise((resolve, reject) => {
-      const reader = new FileReader();
-      reader.onload = () => resolve(reader.result as string);
-      reader.onerror = () => reject(new Error(`Failed to read file: ${file.name}`));
-      reader.readAsText(file);
-    });
+    return file.text();
+  }
+
+  /** The base64 payload of a file, without any `data:` prefix — the raw form
+   *  `ChatImageAttachment.data` specifies (transports add their own framing). */
+  private async readFileAsBase64(file: File): Promise<string> {
+    const bytes = new Uint8Array(await file.arrayBuffer());
+    let binary = '';
+    const CHUNK = 0x8000;
+    for (let i = 0; i < bytes.length; i += CHUNK) {
+      binary += String.fromCharCode(...bytes.subarray(i, i + CHUNK));
+    }
+    return btoa(binary);
   }
 
   private async processFiles(
     files: File[],
+    existingBytes = 0,
   ): Promise<{ attachments: ChatAttachment[]; errors: string[] }> {
     type FileResult = { ok: true; attachment: ChatAttachment } | { ok: false; message: string };
+    // Budget the batch BEFORE reading any of it. `file.size` needs no I/O, so the verdict is
+    // deterministic and in the user's own pick order; deciding inside the parallel map below would
+    // hand the last slot to whichever read happened to finish first. `existingBytes` is what the
+    // caller has already committed to — the picker appends to a running list, so its files have to
+    // count against what is already attached rather than starting from zero each time.
+    let running = existingBytes;
+    const overBudget = new Map<File, string>();
+    for (const file of files) {
+      if (running + file.size > MAX_ATTACHMENTS_TOTAL_BYTES) {
+        overBudget.set(
+          file,
+          `"${file.name}" would take this message past the ` +
+            `${MAX_ATTACHMENTS_TOTAL_BYTES / BYTES_PER_MB}MB attachment limit ` +
+            `(${(running / BYTES_PER_MB).toFixed(1)}MB already attached).`,
+        );
+        continue;
+      }
+      running += file.size;
+    }
     const results = await Promise.all(
       files.map(async (file): Promise<FileResult> => {
         if (!this.isAcceptedFile(file)) {
           return { ok: false, message: `"${file.name}" is not an accepted file type.` };
         }
+        const tooMuch = overBudget.get(file);
+        if (tooMuch) return { ok: false, message: tooMuch };
         try {
+          // An image file becomes a real image attachment — the transports render those as
+          // image blocks the model SEES. Reading it as text (the only path that existed)
+          // produced mojibake the model "read" as prose: an accepted .png was worse than a
+          // rejected one. Text stays the default for everything else.
+          //
+          // Only the types the vendors actually accept take this branch. `image/*` covers far
+          // more than that, and sending one an API rejects fails the whole turn the user is
+          // waiting on — where the text branch merely degrades. It also keeps SVG working:
+          // SVG *is* text, and reading it as such gives the model something it can genuinely
+          // read, which a base64 image block of it would not.
+          if (VENDOR_IMAGE_MIME_TYPES.has(file.type.toLowerCase())) {
+            if (file.size > MAX_IMAGE_ATTACHMENT_BYTES) {
+              return {
+                ok: false,
+                message:
+                  `"${file.name}" is ${Math.ceil(file.size / BYTES_PER_MB)}MB; images are limited to ` +
+                  `${MAX_IMAGE_ATTACHMENT_BYTES / BYTES_PER_MB}MB.`,
+              };
+            }
+            const data = await this.readFileAsBase64(file);
+            return {
+              ok: true,
+              attachment: { kind: 'image', name: file.name, mimeType: file.type, data },
+            };
+          }
           const content = await this.readFileAsText(file);
           return {
             ok: true,
@@ -4710,7 +4864,10 @@ export class FoundationAiAssistant extends GenesisElement {
     const input = e.target as HTMLInputElement;
     const files = Array.from(input.files ?? []);
     input.value = '';
-    const { attachments, errors } = await this.processFiles(files);
+    const { attachments, errors } = await this.processFiles(
+      files,
+      this.attachments.reduce((n, a) => n + attachmentBytes(a), 0),
+    );
     if (attachments.length) {
       this.attachments = [...this.attachments, ...attachments];
       this.logMeta('attachment.added', {
@@ -4976,6 +5133,31 @@ export class FoundationAiAssistant extends GenesisElement {
     }
   }
 
+  /**
+   * A widget reporting spend it incurred AFTER resolving.
+   *
+   * Note what this deliberately does NOT do: no `startLoadingTimer()`. This is bookkeeping about a
+   * turn that already finished, so it must be invisible — showing a spinner would tell the user the
+   * assistant is working when nothing is pending.
+   */
+  handleInteractionCost(e: Event) {
+    const detail = (e as CustomEvent).detail;
+    if (!detail?.interactionId) return;
+    // Optional on `AiDriver`, so call it optionally — a driver that predates this, or one that
+    // simply doesn't track spend, should ignore the report rather than throw on it. TRACED,
+    // because the spend is real and already billed: an untraced no-op here is the same invisible
+    // gap this whole channel exists to close, reintroduced at the last hop. Reviewer catch.
+    if (!this.driver?.recordExternalCost) {
+      this.logMeta('interaction.external-cost-dropped', {
+        interactionId: detail.interactionId,
+        costUsd: detail.costUsd,
+        reason: 'driver does not implement recordExternalCost',
+      });
+      return;
+    }
+    this.driver.recordExternalCost(detail.interactionId, detail.costUsd);
+  }
+
   /**
    * The live {@link InteractionContext} for a pending interaction (GENC-1390).
    * `AiChatInteractionWrapper` pierces this across the shadow boundary to build the