@superjackfruitlabs/salaam 0.0.3 → 0.0.5

package/src/local-edit-helper.ts

@@ -0,0 +1,26 @@
+// Runs as the tools user: applies reviewed local edits that the service has recorded and verified.
+import { closeSync, constants, fsyncSync, openSync, readFileSync, rmSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { applyLocalEdits, localPath, verifyLocalEdits } from './local-edits.js';
+import type { ToolEdit } from './tool-identity.js';
+
+const root = process.argv[2];
+if (!root) throw new Error('usage: local-edit-helper <root>');
+const edits = JSON.parse(readFileSync(0, 'utf8')) as ToolEdit[];
+for (const { remove, ...edit } of edits) {
+  if (remove) {
+    verifyLocalEdits(root, [edit]);
+    const path = localPath(root, edit.path);
+    rmSync(path);
+    const directory = openSync(dirname(path), constants.O_RDONLY);
+    try {
+      fsyncSync(directory);
+    } finally {
+      closeSync(directory);
+    }
+    process.stdout.write('applied ' + JSON.stringify(edit.path) + '\n');
+  } else
+    applyLocalEdits(root, [edit], (path) =>
+      process.stdout.write('applied ' + JSON.stringify(path) + '\n'),
+    );
+}

package/src/local-edits.ts

@@ -106,21 +106,204 @@ export function prepareLocalEdits(root: string, input: unknown): LocalEdit[] {
         'workspace_changed',
         'Read the file first and supply its current sha256; null is only for a new file',
       );
-    if (
-      typeof item.content !== 'string' ||
-      Buffer.byteLength(item.content) > 262144 ||
-      item.content.includes('\0')
-    )
-      throw new ServiceError('invalid_field', 'Provide UTF-8 replacement content up to 256 KiB');
-    return { path, before: original.text, after: item.content, mode: original.mode };
+    // An existing file changes by exact replacements; whole content is for new files (or a
+    // deliberate rewrite). Either way the edit resolves to the exact before and after texts, so
+    // the approval binding, apply, verify and undo paths are unchanged.
+    let after: string;
+    if (item.replacements !== undefined) {
+      if (item.content !== undefined)
+        throw new ServiceError('invalid_field', 'Use replacements or content for a file, not both');
+      if (original.text === null)
+        throw new ServiceError(
+          'invalid_field',
+          'Replacements edit an existing file; give a new file its whole content',
+        );
+      after = applyReplacements(path, original.text, item.replacements);
+    } else after = item.content as string;
+    if (typeof after !== 'string' || Buffer.byteLength(after) > 262144 || after.includes('\0'))
+      throw new ServiceError('invalid_field', 'Provide UTF-8 file content up to 256 KiB');
+    return { path, before: original.text, after, mode: original.mode };
   });
-  if (Buffer.byteLength(JSON.stringify(edits)) > 32768)
+  // What a person reviews is the change, so the change is what is bounded, not the files.
+  if (Buffer.byteLength(reviewLocalEdits(edits, Infinity)) > 32768)
     throw new ServiceError(
       'workspace_limit',
       'Split this edit into smaller reviewable changes (32 KiB per review)',
     );
   return edits;
 }
+
+/** Applies exact replacements in order. Each `old` must occur exactly once in the text as it is
+ * at that point; the message tells the model how to fix a miss. */
+function applyReplacements(path: string, text: string, input: unknown): string {
+  if (!Array.isArray(input) || !input.length || input.length > 20)
+    throw new ServiceError('invalid_field', 'Provide one to twenty replacements');
+  input.forEach((raw, i) => {
+    const r = object(raw),
+      n = `Replacement ${i + 1} in ${path}`;
+    if (typeof r.old !== 'string' || typeof r.new !== 'string')
+      throw new ServiceError('invalid_field', `${n}: give old and new as text`);
+    if (!r.old)
+      throw new ServiceError(
+        'invalid_field',
+        `${n}: old is empty; quote the exact lines to change`,
+      );
+    let count = 0;
+    for (let at = text.indexOf(r.old); at !== -1; at = text.indexOf(r.old, at + r.old.length))
+      count++;
+    if (count === 0)
+      throw new ServiceError(
+        'edit_mismatch',
+        `${n}: old text not found. Read the file again and copy the exact lines, including whitespace`,
+      );
+    if (count > 1)
+      throw new ServiceError(
+        'edit_mismatch',
+        `${n}: old text occurs ${count} times. Include more surrounding lines so it matches exactly once`,
+      );
+    if (r.old === r.new) throw new ServiceError('invalid_field', `${n}: changes nothing`);
+    text = text.replace(r.old, () => r.new as string);
+  });
+  return text;
+}
+
+const CONTEXT = 3,
+  REVIEW_LINES = 200;
+
+/** A unified diff of each file's change with a few lines of context: what an approval shows.
+ * Long reviews stop at `limit` lines and say how much they left out; the approval still binds
+ * the exact full change. */
+export function reviewLocalEdits(edits: LocalEdit[], limit = REVIEW_LINES): string {
+  const out: string[] = [];
+  let hidden = 0;
+  for (const edit of edits) {
+    const lines =
+      edit.before === null
+        ? [`+++ ${edit.path} (new file)`, ...split(edit.after).map((l) => '+' + l)]
+        : [`--- ${edit.path}`, `+++ ${edit.path}`, ...hunks(split(edit.before), split(edit.after))];
+    for (const line of lines) {
+      if (out.length < limit) out.push(line);
+      else if (/^[+-]/.test(line) && !/^(\+\+\+|---) /.test(line)) hidden++;
+    }
+  }
+  if (hidden)
+    out.push(`… ${hidden} more changed lines not shown; the approval covers the exact full change`);
+  return out.join('\n');
+}
+function split(text: string): string[] {
+  const lines = text.split('\n');
+  if (lines.at(-1) === '') lines.pop();
+  return lines;
+}
+/** Unified-diff hunks from a line-level Myers diff (prefix and suffix trimmed first, so a small
+ * change to a big file stays cheap). A diff too large to compute in budget is shown whole. */
+function hunks(a: string[], b: string[]): string[] {
+  let pre = 0;
+  while (pre < a.length && pre < b.length && a[pre] === b[pre]) pre++;
+  let suf = 0;
+  while (
+    suf < a.length - pre &&
+    suf < b.length - pre &&
+    a[a.length - 1 - suf] === b[b.length - 1 - suf]
+  )
+    suf++;
+  const ops = myers(a.slice(pre, a.length - suf), b.slice(pre, b.length - suf));
+  // Full op list over the whole file: equal prefix, the diffed middle, equal suffix.
+  const all: { t: ' ' | '-' | '+'; s: string; ai: number; bi: number }[] = [];
+  for (let i = 0; i < pre; i++) all.push({ t: ' ', s: a[i]!, ai: i, bi: i });
+  let ai = pre,
+    bi = pre;
+  for (const o of ops) {
+    all.push({ ...o, ai, bi });
+    if (o.t !== '+') ai++;
+    if (o.t !== '-') bi++;
+  }
+  for (let i = 0; i < suf; i++) all.push({ t: ' ', s: a[ai + i]!, ai: ai + i, bi: bi + i });
+  const out: string[] = [];
+  let i = 0;
+  while (i < all.length) {
+    if (all[i]!.t === ' ') {
+      i++;
+      continue;
+    }
+    let start = Math.max(0, i - CONTEXT),
+      end = i;
+    // Extend while the next change is within 2*CONTEXT equal lines.
+    for (;;) {
+      while (end < all.length && all[end]!.t !== ' ') end++;
+      let gap = end;
+      while (gap < all.length && all[gap]!.t === ' ' && gap - end < 2 * CONTEXT) gap++;
+      if (gap < all.length && all[gap]!.t !== ' ' && gap - end < 2 * CONTEXT) end = gap;
+      else break;
+    }
+    const stop = Math.min(all.length, end + CONTEXT),
+      part = all.slice(start, stop),
+      aStart = part.find((o) => o.t !== '+')?.ai ?? part[0]!.ai,
+      bStart = part.find((o) => o.t !== '-')?.bi ?? part[0]!.bi,
+      aLen = part.filter((o) => o.t !== '+').length,
+      bLen = part.filter((o) => o.t !== '-').length;
+    out.push(`@@ -${aStart + 1},${aLen} +${bStart + 1},${bLen} @@`, ...part.map((o) => o.t + o.s));
+    i = stop;
+  }
+  return out;
+}
+function myers(a: string[], b: string[]): { t: ' ' | '-' | '+'; s: string }[] {
+  const n = a.length,
+    m = b.length,
+    max = n + m;
+  if (max > 20000)
+    return [...a.map((s) => ({ t: '-' as const, s })), ...b.map((s) => ({ t: '+' as const, s }))];
+  const v = new Map<number, number>([[1, 0]]),
+    trace: Map<number, number>[] = [];
+  for (let d = 0; d <= max; d++) {
+    trace.push(new Map(v));
+    for (let k = -d; k <= d; k += 2) {
+      let x =
+        k === -d || (k !== d && (v.get(k - 1) ?? -1) < (v.get(k + 1) ?? -1))
+          ? v.get(k + 1)!
+          : v.get(k - 1)! + 1;
+      let y = x - k;
+      while (x < n && y < m && a[x] === b[y]) {
+        x++;
+        y++;
+      }
+      v.set(k, x);
+      if (x >= n && y >= m) return backtrack(a, b, trace, n, m);
+    }
+    if (d > 2000) break;
+  }
+  return [...a.map((s) => ({ t: '-' as const, s })), ...b.map((s) => ({ t: '+' as const, s }))];
+}
+function backtrack(
+  a: string[],
+  b: string[],
+  trace: Map<number, number>[],
+  n: number,
+  m: number,
+): { t: ' ' | '-' | '+'; s: string }[] {
+  const ops: { t: ' ' | '-' | '+'; s: string }[] = [];
+  let x = n,
+    y = m;
+  for (let d = trace.length - 1; d >= 0; d--) {
+    const v = trace[d]!,
+      k = x - y,
+      prevK = k === -d || (k !== d && (v.get(k - 1) ?? -1) < (v.get(k + 1) ?? -1)) ? k + 1 : k - 1,
+      prevX = v.get(prevK) ?? 0,
+      prevY = prevX - prevK;
+    while (x > prevX && y > prevY) {
+      ops.push({ t: ' ', s: a[x - 1]! });
+      x--;
+      y--;
+    }
+    if (d > 0) {
+      if (x === prevX) ops.push({ t: '+', s: b[y - 1]! });
+      else ops.push({ t: '-', s: a[x - 1]! });
+    }
+    x = prevX;
+    y = prevY;
+  }
+  return ops.reverse();
+}
 export function verifyLocalEdits(root: string, edits: LocalEdit[]): void {
   for (const edit of edits) {
     const actual = contents(localPath(root, edit.path));

package/src/local-undo.ts

@@ -3,6 +3,7 @@ import { rmSync, openSync, closeSync, fsyncSync, constants } from 'node:fs';
 import { assertPermissionBinding } from './autonomy.js';
 import type { Store } from './store.js';
 import { digest, ServiceError, type Controller } from './protocol.js';
+import { applyEditsAsTools, type ToolIdentity } from './tool-identity.js';
 import { applyLocalEdits, localPath, verifyLocalEdits, type LocalEdit } from './local-edits.js';
 
 export interface UndoReview {
@@ -53,6 +54,7 @@ export function applyUndo(
   reviewed: string,
   controller: Controller,
   idle: () => void,
+  tools?: ToolIdentity,
 ) {
   const input = { kind: 'local-undo', id, reviewed };
   const saved = store.cachedRequest<{ state: string }>('local-operator', request, input);
@@ -79,20 +81,33 @@ export function applyUndo(
     return { state: 'outcome_unknown', ...review };
   });
   // Intent is durable before touching files. A lost process never repeats this mutation.
-  for (const edit of work.edits) {
-    const inverse = { ...edit, before: edit.after, after: edit.before ?? '' };
-    if (edit.before === null) {
-      verifyLocalEdits(root, [inverse]);
-      const path = localPath(root, edit.path);
-      rmSync(path);
-      const directory = openSync(dirname(path), constants.O_RDONLY);
-      try {
-        fsyncSync(directory);
-      } finally {
-        closeSync(directory);
-      }
-    } else applyLocalEdits(root, [inverse], () => {});
-  }
+  if (tools?.mode === 'tools-user')
+    applyEditsAsTools(
+      tools,
+      root,
+      work.edits.map((edit: LocalEdit) => ({
+        ...edit,
+        before: edit.after,
+        after: edit.before ?? '',
+        ...(edit.before === null ? { remove: true } : {}),
+      })),
+      () => {},
+    );
+  else
+    for (const edit of work.edits) {
+      const inverse = { ...edit, before: edit.after, after: edit.before ?? '' };
+      if (edit.before === null) {
+        verifyLocalEdits(root, [inverse]);
+        const path = localPath(root, edit.path);
+        rmSync(path);
+        const directory = openSync(dirname(path), constants.O_RDONLY);
+        try {
+          fsyncSync(directory);
+        } finally {
+          closeSync(directory);
+        }
+      } else applyLocalEdits(root, [inverse], () => {});
+    }
   verifyLocalEdits(root, work.edits);
   return store.transaction(() => {
     const result = { state: 'completed', call_id: work.call_id };

package/src/managed.ts

@@ -503,7 +503,7 @@ export class ManagedWork {
     revision: number,
     binding: string,
     decision: 'approve' | 'deny',
-    scoped?: { receipt: Record<string, unknown>; authorize: () => void },
+    scoped?: { receipt: Record<string, unknown>; authorize: () => void; decidedBy?: string },
   ): Approval {
     const requestWork = this.store.db.isTransaction
       ? this.store.requestInTransaction.bind(this.store)
@@ -553,7 +553,7 @@ export class ManagedWork {
           .prepare(
             "UPDATE approvals SET state='decided',decision=?,decided_by=?,revision=revision+1 WHERE id=?",
           )
-          .run(decision, scoped ? 'scoped-policy' : 'local-operator', id);
+          .run(decision, scoped ? (scoped.decidedBy ?? 'scoped-policy') : 'local-operator', id);
         if (decision === 'deny')
           this.transition(op, 'cancelled_before_dispatch', 'Denied by operator');
         this.store.event(

package/src/mentions.ts

@@ -0,0 +1,304 @@
+import { createHash } from 'node:crypto';
+import { execFileSync } from 'node:child_process';
+import { lstatSync, readdirSync, readFileSync, realpathSync } from 'node:fs';
+import { basename, isAbsolute, relative, resolve, sep } from 'node:path';
+import type { DatabaseSync } from 'node:sqlite';
+import { ServiceError } from './protocol.js';
+
+/** `@path` mentions attach workspace files to a desk prompt (Phase 3b). */
+export const MENTION_LIMITS = {
+  perFile: 64 * 1024,
+  total: 256 * 1024,
+  image: 512 * 1024,
+  listing: 5000,
+  entries: 200,
+} as const;
+
+export interface Attachment {
+  path: string;
+  kind: 'text' | 'binary' | 'image' | 'listing' | 'missing' | 'refused' | 'skipped';
+  content?: string;
+  data?: string;
+  mime?: string;
+  sha256?: string;
+  bytes?: number;
+  truncated?: boolean;
+  sensitive?: boolean;
+  reason?: string;
+}
+
+const SENSITIVE = [
+  /(^|\/)\.env(\..+)?$/,
+  /\.(pem|key|p12|pfx|keystore|jks)$/i,
+  /(^|\/)id_(rsa|dsa|ecdsa|ed25519)(\.pub)?$/,
+  /(^|\/)\.(netrc|npmrc|pypirc)$/,
+  /(^|\/)(credentials|secrets?)(\.[a-z]+)?$/i,
+];
+
+export function isSensitivePath(path: string): boolean {
+  return SENSITIVE.some((pattern) => pattern.test(path));
+}
+
+/** `@token` at a word start; `@"a b"` may hold spaces; trailing punctuation is dropped. */
+export function extractMentions(text: string): string[] {
+  const found: string[] = [];
+  const pattern = /(^|[\s([{])@(?:"([^"]+)"|([^\s"]+))/g;
+  for (const match of text.matchAll(pattern)) {
+    const value = match[2] ?? match[3]!.replace(/[.,;:!?)\]}]+$/, '');
+    if (value && !value.startsWith('@') && !found.includes(value)) found.push(value);
+  }
+  return found;
+}
+
+function inside(root: string, path: string): boolean {
+  const rel = relative(root, path);
+  return rel === '' || (!rel.startsWith('..') && !isAbsolute(rel));
+}
+
+/** Tracked and untracked-but-not-ignored files; a symlink is listed only if it stays inside. */
+export function listWorkspaceFiles(root: string): string[] {
+  let names: string[];
+  try {
+    names = execFileSync('git', ['ls-files', '--cached', '--others', '--exclude-standard', '-z'], {
+      cwd: root,
+      maxBuffer: 32 * 1024 * 1024,
+      stdio: ['ignore', 'pipe', 'ignore'],
+    })
+      .toString('utf8')
+      .split('\0')
+      .filter(Boolean);
+  } catch {
+    names = walk(root, root);
+  }
+  const real = realpathSync(root);
+  const kept: string[] = [];
+  for (const name of names) {
+    if (kept.length >= MENTION_LIMITS.listing) break;
+    try {
+      if (
+        lstatSync(resolve(root, name)).isSymbolicLink() &&
+        !inside(real, realpathSync(resolve(root, name)))
+      )
+        continue;
+    } catch {
+      continue;
+    }
+    kept.push(name);
+  }
+  return kept;
+}
+
+function walk(root: string, dir: string, out: string[] = []): string[] {
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (out.length >= MENTION_LIMITS.listing) break;
+    if (entry.name === '.git' || entry.name === 'node_modules') continue;
+    const full = resolve(dir, entry.name);
+    if (entry.isDirectory()) walk(root, full, out);
+    else out.push(relative(root, full).split(sep).join('/'));
+  }
+  return out;
+}
+
+/** Basename hits first, then path substrings, then in-order subsequences. */
+export function rankFiles(files: string[], query: string): string[] {
+  if (!query) return files;
+  const q = query.toLowerCase();
+  const score = (file: string) => {
+    const f = file.toLowerCase();
+    const base = basename(f);
+    if (base.startsWith(q)) return 4;
+    if (base.includes(q)) return 3;
+    if (f.includes(q)) return 2;
+    let i = 0;
+    for (const ch of f) if (ch === q[i]) i++;
+    return i === q.length ? 1 : 0;
+  };
+  return files
+    .map((file) => ({ file, s: score(file) }))
+    .filter((x) => x.s > 0)
+    .sort((a, b) => b.s - a.s || a.file.length - b.file.length || a.file.localeCompare(b.file))
+    .map((x) => x.file);
+}
+
+function imageMime(bytes: Buffer): string | undefined {
+  if (bytes.subarray(0, 8).equals(Buffer.from('89504e470d0a1a0a', 'hex'))) return 'image/png';
+  if (bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff) return 'image/jpeg';
+  if (bytes.subarray(0, 4).toString('latin1') === 'GIF8') return 'image/gif';
+  if (
+    bytes.subarray(0, 4).toString('latin1') === 'RIFF' &&
+    bytes.subarray(8, 12).toString('latin1') === 'WEBP'
+  )
+    return 'image/webp';
+  return undefined;
+}
+
+function truncate(text: string, limit: number): string {
+  const buf = Buffer.from(text, 'utf8');
+  if (buf.length <= limit) return text;
+  // Cut on a character boundary so the byte bound holds.
+  return buf.subarray(0, limit).toString('utf8').replace(/�$/, '');
+}
+
+/** Read each mention under the workspace; nothing outside it, through a symlink or not. */
+export function resolveMentions(root: string, mentions: string[]): Attachment[] {
+  const real = realpathSync(root);
+  let budget: number = MENTION_LIMITS.total;
+  return mentions.map((path): Attachment => {
+    const target = resolve(real, path);
+    if (isAbsolute(path) || !inside(real, target))
+      return { path, kind: 'refused', reason: 'outside the workspace' };
+    let resolved: string;
+    try {
+      resolved = realpathSync(target);
+    } catch {
+      return { path, kind: 'missing' };
+    }
+    if (!inside(real, resolved))
+      return { path, kind: 'refused', reason: 'links outside the workspace' };
+    const sensitive = isSensitivePath(path) || undefined;
+    const stat = lstatSync(resolved);
+    if (stat.isDirectory()) {
+      const names = readdirSync(resolved, { withFileTypes: true })
+        .filter((e) => e.name !== '.git')
+        .slice(0, MENTION_LIMITS.entries)
+        .map((e) => (e.isDirectory() ? `${e.name}/` : e.name));
+      const content = truncate(names.join('\n'), Math.min(MENTION_LIMITS.perFile, budget));
+      budget -= Buffer.byteLength(content);
+      return { path, kind: 'listing', content };
+    }
+    if (!stat.isFile()) return { path, kind: 'refused', reason: 'not a regular file' };
+    const bytes = readFileSync(resolved);
+    const sha256 = createHash('sha256').update(bytes).digest('hex');
+    const mime = imageMime(bytes);
+    if (mime) {
+      if (bytes.length > MENTION_LIMITS.image)
+        return {
+          path,
+          kind: 'skipped',
+          reason: 'image larger than 512 KiB',
+          bytes: bytes.length,
+          sha256,
+        };
+      return {
+        path,
+        kind: 'image',
+        mime,
+        data: bytes.toString('base64'),
+        sha256,
+        bytes: bytes.length,
+        sensitive,
+      };
+    }
+    if (bytes.subarray(0, 8192).includes(0))
+      return { path, kind: 'binary', sha256, bytes: bytes.length, sensitive };
+    if (budget <= 0)
+      return {
+        path,
+        kind: 'skipped',
+        reason: 'attachment budget used up',
+        sha256,
+        bytes: bytes.length,
+        sensitive,
+      };
+    const limit = Math.min(MENTION_LIMITS.perFile, budget);
+    const content = truncate(bytes.toString('utf8'), limit);
+    budget -= Buffer.byteLength(content);
+    return {
+      path,
+      kind: 'text',
+      content,
+      sha256,
+      bytes: bytes.length,
+      ...(Buffer.byteLength(content) < bytes.length ? { truncated: true } : {}),
+      ...(sensitive ? { sensitive } : {}),
+    };
+  });
+}
+
+/** The text the model reads; image bytes travel separately as image content. */
+export function attachmentContext(attachments: Attachment[]): string {
+  if (!attachments.length) return '';
+  const parts = attachments.map((a) => {
+    const digest = a.sha256 ? `, sha256 ${a.sha256.slice(0, 12)}` : '';
+    switch (a.kind) {
+      case 'text':
+        return `@${a.path} (${a.bytes} bytes${digest}${a.truncated ? ', truncated' : ''})\n\`\`\`\n${a.content}\n\`\`\``;
+      case 'listing':
+        return `@${a.path} (directory)\n\`\`\`\n${a.content}\n\`\`\``;
+      case 'image':
+        return `@${a.path} (image, attached)${digest ? ` [${digest.slice(2)}]` : ''}`;
+      case 'binary':
+        return `@${a.path} (binary, ${a.bytes} bytes${digest}; not attached)`;
+      default:
+        return `@${a.path} (${a.kind}${a.reason ? `: ${a.reason}` : ''})`;
+    }
+  });
+  return `<attached-files>\n${parts.join('\n\n')}\n</attached-files>`;
+}
+
+export interface PromptImage {
+  type: 'image';
+  data: string;
+  mimeType: string;
+}
+
+export const MAX_IMAGES = 4;
+
+/**
+ * Expand a desk prompt's mentions. A secret-looking file is attached only after the user
+ * confirms it; the refusal names the files so the client can ask.
+ */
+export function expandPrompt(
+  root: string,
+  text: string,
+  confirmSensitive: boolean,
+): { text: string; images: PromptImage[]; attachments: Attachment[] } {
+  const mentions = extractMentions(text);
+  if (!mentions.length) return { text, images: [], attachments: [] };
+  const attachments = resolveMentions(root, mentions);
+  const sensitive = attachments
+    .filter((a) => a.sensitive && a.kind !== 'binary')
+    .map((a) => a.path);
+  if (sensitive.length && !confirmSensitive)
+    throw new ServiceError(
+      'sensitive_attachment',
+      `Confirm attaching secret-looking files: ${sensitive.join(', ')}`,
+      409,
+    );
+  const images: PromptImage[] = [];
+  for (const a of attachments) {
+    if (a.kind !== 'image') continue;
+    if (images.length >= MAX_IMAGES) {
+      a.kind = 'skipped';
+      a.reason = `more than ${MAX_IMAGES} images`;
+      delete a.data;
+      continue;
+    }
+    images.push({ type: 'image', data: a.data!, mimeType: a.mime! });
+  }
+  return { text: `${text}\n\n${attachmentContext(attachments)}`, images, attachments };
+}
+
+function imageTable(db: DatabaseSync): void {
+  db.exec(
+    'CREATE TABLE IF NOT EXISTS submission_images(submission_id TEXT NOT NULL,position INTEGER NOT NULL,mime TEXT NOT NULL,data TEXT NOT NULL,PRIMARY KEY(submission_id,position))',
+  );
+}
+
+export function storeImages(db: DatabaseSync, submissionId: string, images: PromptImage[]): void {
+  if (!images.length) return;
+  imageTable(db);
+  const insert = db.prepare('INSERT INTO submission_images VALUES (?,?,?,?)');
+  images.forEach((image, i) => insert.run(submissionId, i, image.mimeType, image.data));
+}
+
+/** Images ride with their submission once; they are dropped after dispatch. */
+export function takeImages(db: DatabaseSync, submissionId: string): PromptImage[] {
+  imageTable(db);
+  const rows = db
+    .prepare('SELECT mime,data FROM submission_images WHERE submission_id=? ORDER BY position')
+    .all(submissionId) as { mime: string; data: string }[];
+  if (rows.length)
+    db.prepare('DELETE FROM submission_images WHERE submission_id=?').run(submissionId);
+  return rows.map((r) => ({ type: 'image', data: r.data, mimeType: r.mime }));
+}