@kabmo-labs/kabmo 0.0.0-stage → 0.0.1

package/src/server/lib/omp/session/auto-title.server.test.ts

@@ -0,0 +1,270 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, expect, test } from 'bun:test';
+
+import {
+  consumeAutoTitleOutput,
+  markTitleRequestSent,
+  triggerAutoSessionTitle,
+  type AutoTitleHost,
+} from '@/server/lib/omp/session/auto-title.server';
+
+/**
+ * The safety property of auto-titling, and the one thing that must never
+ * regress: Kabmo fires omp's own `/rename` (which persists through
+ * `setSessionName(title, "user")`) in the background, and that write has no
+ * "don't overwrite" guard of its own — omp only refuses an `"auto"` write over
+ * a `"user"` title. So the decision to skip a NAMED session is ours, and a bug
+ * here silently destroys a name the operator typed.
+ *
+ * These tests drive the guard directly: a fake `get_state` reports a name, and
+ * the assertion is that no `/rename` reaches the wire.
+ */
+
+interface FakeProc {
+  commands: Array<Record<string, unknown>>;
+  sendCommand<T>(command: { type: string; [key: string]: unknown }): Promise<T>;
+}
+
+function makeHost(options: {
+  sessionName?: string;
+  sessionId?: string;
+  inFlight?: boolean;
+  pending?: boolean;
+  requested?: boolean;
+  windowUntil?: number;
+  /** Called with the host the moment a `/rename` prompt reaches the wire, so a
+   *  test can observe the window state the frame handler would see. */
+  onPrompt?: (host: AutoTitleHost) => void;
+  /** Make the `/rename` send reject, for the rollback path. */
+  failPrompt?: boolean;
+}): { host: AutoTitleHost; proc: FakeProc } {
+  const host: AutoTitleHost = {
+    sessionId: 'sess-1',
+    autoTitleInFlight: options.inFlight ?? false,
+    autoTitleWindowUntil: options.windowUntil ?? 0,
+    autoTitlePending: options.pending ?? true,
+    autoTitleRequested: options.requested ?? false,
+    proc: undefined as unknown as AutoTitleHost['proc'],
+  };
+  const proc: FakeProc = {
+    commands: [],
+    async sendCommand<T>(command: { type: string; [key: string]: unknown }): Promise<T> {
+      proc.commands.push(command);
+      if (command.type === 'get_state') {
+        return {
+          sessionId: options.sessionId ?? 'sess-1',
+          sessionName: options.sessionName,
+        } as T;
+      }
+      options.onPrompt?.(host);
+      if (options.failPrompt) throw new Error('send failed');
+      return undefined as T;
+    },
+  };
+  host.proc = proc as unknown as AutoTitleHost['proc'];
+  return { host, proc };
+}
+
+/** Commands other than the `get_state` probe the guard always performs. */
+function sentRenames(proc: FakeProc): Array<Record<string, unknown>> {
+  return proc.commands.filter((command) => command.type === 'prompt');
+}
+
+describe('triggerAutoSessionTitle', () => {
+  test('names an unnamed session through omp own /rename', async () => {
+    const { host, proc } = makeHost({});
+    await triggerAutoSessionTitle(host, 'opening');
+
+    const renames = sentRenames(proc);
+    expect(renames).toHaveLength(1);
+    expect(renames[0].message).toBe('/rename');
+    // The request window opens BEFORE the command is sent, so the
+    // `prompt_result {agentInvoked:false}` omp answers within the same tick is
+    // already attributable to us when it arrives.
+    expect(host.autoTitleWindowUntil).toBeGreaterThan(Date.now());
+  });
+
+  test('the request window is armed BEFORE the /rename is sent', async () => {
+    // The regression: omp answers the `/rename` prompt with
+    // `prompt_result {agentInvoked:false}` in the same tick (measured 3 ms),
+    // while the operator's turn is still streaming. The frame fold suppresses
+    // that frame only while the window is armed — arming it after the ack left
+    // the frame to reach the client, which settled the optimistic turn, blanked
+    // the generating indicator and cleared the sidebar's live `stream` row
+    // while the answer kept arriving (measured: indicator on for ~1.2 s of a
+    // 20 s run).
+    let windowAtSend = -1;
+    const { host, proc } = makeHost({ onPrompt: (h) => { windowAtSend = h.autoTitleWindowUntil; } });
+    await triggerAutoSessionTitle(host, 'opening');
+
+    expect(sentRenames(proc)).toHaveLength(1);
+    expect(windowAtSend).toBeGreaterThan(Date.now());
+  });
+
+  test('rolls the window back when the /rename never reached omp', async () => {
+    // An armed window with no request behind it would swallow the next
+    // operator frame inside its 60 s span — and block the settle-stage
+    // fallback, which stands down while a generation is "in flight".
+    const { host, proc } = makeHost({ failPrompt: true });
+    await triggerAutoSessionTitle(host, 'opening');
+
+    expect(sentRenames(proc)).toHaveLength(1);
+    expect(host.autoTitleWindowUntil).toBe(0);
+  });
+
+  test('never overwrites a name the operator set', async () => {
+    // At either stage: the name is re-read from omp, so a rename made in
+    // another tab survives both the early attempt and the fallback.
+    for (const stage of ['opening', 'settle'] as const) {
+      const { host, proc } = makeHost({ sessionName: 'My Deliberate Name' });
+      await triggerAutoSessionTitle(host, stage);
+
+      expect(sentRenames(proc)).toHaveLength(0);
+      // No request was sent, so nothing may claim the output window either.
+      expect(host.autoTitleWindowUntil).toBe(0);
+    }
+  });
+
+  test('treats a whitespace-only name as unnamed', async () => {
+    const { host, proc } = makeHost({ sessionName: '   ' });
+    await triggerAutoSessionTitle(host, 'opening');
+
+    expect(sentRenames(proc)).toHaveLength(1);
+  });
+
+  test('skips when the session changed under the read', async () => {
+    // `get_state` answered for a different conversation (a reset or switch
+    // between the trigger and the read) — titling this session would name the
+    // wrong one.
+    const { host, proc } = makeHost({ sessionId: 'someone-else' });
+    await triggerAutoSessionTitle(host, 'opening');
+
+    expect(sentRenames(proc)).toHaveLength(0);
+  });
+
+  test('does not stack a second request while one is in flight', async () => {
+    const { host, proc } = makeHost({ inFlight: true });
+    await triggerAutoSessionTitle(host, 'opening');
+
+    expect(sentRenames(proc)).toHaveLength(0);
+    expect(proc.commands).toHaveLength(0);
+  });
+
+  test('the early attempt does not consume the eligibility latch', async () => {
+    // The fallback exists precisely because the early attempt can come back
+    // empty. If `opening` consumed the latch, a provider error at the first
+    // user message would leave the session unnamed for good.
+    const { host } = makeHost({});
+    await triggerAutoSessionTitle(host, 'opening');
+
+    expect(host.autoTitlePending).toBe(true);
+    expect(host.autoTitleRequested).toBe(true);
+  });
+
+  test('the fallback retries once the early attempt came back empty', async () => {
+    // The real sequence: the early `/rename` is accepted, omp answers
+    // `command_output` (consuming the window) with no title, and the run then
+    // ends — the fallback is what names the session.
+    const { host, proc } = makeHost({});
+    await triggerAutoSessionTitle(host, 'opening');
+    expect(consumeAutoTitleOutput(host)).toBe(true);
+
+    await triggerAutoSessionTitle(host, 'settle');
+
+    expect(sentRenames(proc)).toHaveLength(2);
+    expect(host.autoTitlePending).toBe(false);
+  });
+
+  test('the fallback stands down while the early generation is in flight', async () => {
+    // A short run can end before the tiny model answers (~4s). Re-asking there
+    // would reserve a new title revision and cancel the generation already in
+    // flight, for a title derived from the same opening turn.
+    const { host, proc } = makeHost({});
+    await triggerAutoSessionTitle(host, 'opening');
+    expect(host.autoTitleWindowUntil).toBeGreaterThan(Date.now());
+
+    await triggerAutoSessionTitle(host, 'settle');
+
+    expect(sentRenames(proc)).toHaveLength(1);
+    // The latch is still consumed: the attempt in flight owns this
+    // conversation's title from here.
+    expect(host.autoTitlePending).toBe(false);
+  });
+
+  test('fires the early attempt once per run', async () => {
+    // A queued steer message also settles as a user message inside the same
+    // run; re-asking on it would cancel the first generation for no gain.
+    const { host, proc } = makeHost({});
+    await triggerAutoSessionTitle(host, 'opening');
+    await triggerAutoSessionTitle(host, 'opening');
+
+    expect(sentRenames(proc)).toHaveLength(1);
+  });
+
+  test('titles from the first run only', async () => {
+    // The regression this latch exists for: a second turn used to fire its own
+    // `/rename`, and omp derives that title from the NEWEST turns — so the
+    // session ended up named after message two.
+    const { host, proc } = makeHost({});
+    await triggerAutoSessionTitle(host, 'opening');
+    await triggerAutoSessionTitle(host, 'settle');
+    expect(sentRenames(proc)).toHaveLength(1);
+
+    // A later run reaches neither stage with the latch consumed.
+    await triggerAutoSessionTitle(host, 'opening');
+    await triggerAutoSessionTitle(host, 'settle');
+
+    expect(sentRenames(proc)).toHaveLength(1);
+  });
+
+  test('skips a conversation that already has a first turn behind it', async () => {
+    // A child resumed for an existing session (`--resume` after the idle
+    // reclaim) reports a non-zero message count, so its next turn must not
+    // name it — the session is either titled already or deliberately unnamed.
+    const { host, proc } = makeHost({ pending: false });
+    await triggerAutoSessionTitle(host, 'opening');
+    await triggerAutoSessionTitle(host, 'settle');
+
+    expect(sentRenames(proc)).toHaveLength(0);
+    expect(host.autoTitleWindowUntil).toBe(0);
+  });
+
+  test('consumes the latch even when generation is skipped', async () => {
+    // A declined generation must not leave the door open for the next turn:
+    // otherwise a first turn whose title the provider refused gets re-asked
+    // after every later message, which is the same bug one step later.
+    const { host } = makeHost({});
+    await triggerAutoSessionTitle(host, 'settle');
+
+    expect(host.autoTitlePending).toBe(false);
+  });
+});
+
+describe('auto-title output window', () => {
+  test('claims exactly one frame per request', () => {
+    const { host } = makeHost({});
+    markTitleRequestSent(host);
+
+    expect(consumeAutoTitleOutput(host)).toBe(true);
+    // omp emits a single command_output per /rename; a second frame inside the
+    // window belongs to something the operator typed and must reach the UI.
+    expect(consumeAutoTitleOutput(host)).toBe(false);
+  });
+
+  test('claims nothing when no request is outstanding', () => {
+    const { host } = makeHost({});
+    expect(consumeAutoTitleOutput(host)).toBe(false);
+  });
+
+  test('expires so a stale window cannot swallow an operator command', () => {
+    const { host } = makeHost({});
+    markTitleRequestSent(host);
+    host.autoTitleWindowUntil = Date.now() - 1;
+
+    expect(consumeAutoTitleOutput(host)).toBe(false);
+  });
+});

package/src/server/lib/omp/session/auto-title.server.ts

@@ -0,0 +1,250 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Auto session titles for Kabmo.
+ *
+ * Kabmo spawns omp with `--mode rpc-ui`, and that mode force-sets
+ * `PI_NO_TITLE=1` (omp's main.ts). The flag gates only the two AUTOMATIC title
+ * paths — `AgentSession.maybeStartTitleGeneration` (first user message) and
+ * `#scheduleReplanTitleRefresh` (todo replan) — so a Kabmo session is never
+ * named on its own and the sidebar keeps the `New Session - <timestamp>`
+ * placeholder for its whole life.
+ *
+ * The generate path itself is NOT gated: `/rename` with no args reaches
+ * `session.generateTitle()` through `executeAcpBuiltinSlashCommand`, which
+ * rpc-mode dispatches for a `prompt` frame BEFORE that frame is forwarded as a
+ * turn — so the request can be sent at any point in a run and never becomes
+ * part of the conversation. Verified against omp 18.3.0 — the ack returns
+ * `{agentInvoked:false}` immediately, the generation lands ~3-4s later as
+ * `session_info_update` + `command_output`, and no entry is written to the
+ * transcript.
+ *
+ * WHY THE NAME MUST BE EMPTY FIRST: `/rename` persists through
+ * `setSessionName(title, "user")`. omp's own guard only refuses an `"auto"`
+ * write over a `"user"` title, so a `/rename` fired against an already-named
+ * session would overwrite the operator's own name. The unnamed check below is
+ * therefore a safety property, not a nicety — it is re-read from `get_state`
+ * on every attempt rather than cached, so a rename made in another tab is
+ * respected.
+ *
+ * ONE ATTEMPT PER CONVERSATION, RETRIED ONCE INSIDE THE FIRST RUN. The title
+ * is derived from the FIRST run and never re-asked after it. omp's `/rename`
+ * derives its title from the newest turns (and `generateRenameTitle` reserves a
+ * fresh title revision, which cancels any generation still in flight), so a
+ * second attempt after turn two would name the session after whatever the
+ * conversation had become by then — and could even discard a slow first
+ * generation.
+ *
+ * There are exactly two triggers, both inside that first run:
+ *
+ *   1. the first settled USER message — the earliest point at which the
+ *      transcript carries the conversation's opening intent. (`agent_start` is
+ *      too early to be usable: omp pushes it before the turn opens, so the
+ *      transcript is still empty there and the title context comes back blank.
+ *      See the `message_end` branch of frame-fold.)
+ *   2. the terminal `agent_end`, as a fallback when the early attempt produced
+ *      no title — a provider error, a timeout, a child that went away, or the
+ *      tiny model declining.
+ *
+ * The eligibility latch `autoTitlePending` is consumed by the fallback, so that
+ * is the last chance this conversation gets and a later run can never title it.
+ * `autoTitleRequested` is what keeps the early trigger from firing again on a
+ * queued steer message. A session that a skill invocation opened has no
+ * user-role message at all (omp delivers it as a `custom` message), so the
+ * early trigger never fires there and the fallback is what names it.
+ *
+ * A first message that omp's low-signal filter rejects ("hi") therefore leaves
+ * the session unnamed for good, which is the honest outcome: the fallback does
+ * re-ask, and omp declines a second time (measured on omp 18.3.0 — the
+ * rejection is a property of the opening message, not of when it is asked).
+ */
+
+import { readSettingsJson } from '@/server/lib/db/settings-store';
+import { getDb } from '@/server/db.server';
+import { GET_STATE_TIMEOUT_MS, PROMPT_ACK_TIMEOUT_MS, type RpcSessionState } from '@/server/lib/omp/rpc/constants';
+
+/** Settings blob key; mirrors the other blob keys (see `shared/lib/settings/keys`). */
+const SETTINGS_BLOB_KEY = 'kabmo_settings';
+
+/** Auto-titling is opt-in per Kabmo install. Default ON: an unnamed session
+ *  renders as `New Session - <timestamp>` forever, which is the visible defect,
+ *  and the cost is one tiny-model call per session. */
+const AUTO_SESSION_TITLE_DEFAULT = true;
+
+/** omp's builtin that generates a title from the conversation. Sent with no
+ *  args so omp derives it through its own `generateRenameTitle`. */
+const GENERATE_TITLE_COMMAND = '/rename';
+
+/**
+ * How long Kabmo's own `/rename` may keep emitting its diagnostic frames.
+ *
+ * The command answers on the prompt path with an immediate ack and then streams
+ * `session_info_update` + `command_output` once the tiny model returns
+ * (measured ~4s). Both carry NO correlation id, so the only way to attribute
+ * them to our background request is this window. It is deliberately generous —
+ * a slow provider must not leak the message — because the cost of over-holding
+ * it is only that a slash command typed in the same few seconds loses its
+ * output row.
+ */
+const AUTO_TITLE_OUTPUT_WINDOW_MS = 60_000;
+
+/** Wrapper state this module reads and writes. The in-flight flag, the
+ *  output window and the one-shot latch are owned by the caller because they
+ *  are per-session runtime state, not policy. */
+export interface AutoTitleHost {
+  sessionId: string;
+  autoTitleInFlight: boolean;
+  /** Epoch ms until which frames belong to our own background rename; 0 when
+   *  no request is outstanding. */
+  autoTitleWindowUntil: number;
+  /** True only while this conversation is still eligible for a title at all.
+   *  Seeded from omp's own message count when the child is spawned, so it
+   *  survives an idle reclaim (a `--resume` child reports the messages it
+   *  restored) and is consumed by the first run's terminal `agent_end` — the
+   *  fallback's last chance. */
+  autoTitlePending: boolean;
+  /** True once the early attempt (the first settled user message) has been
+   *  made, so a queued steer message cannot re-ask inside the same run. */
+  autoTitleRequested: boolean;
+  proc: {
+    sendCommand<T = unknown>(command: { type: string; [key: string]: unknown }, timeoutMs?: number): Promise<T>;
+  };
+}
+
+/**
+ * Claim the frames our own `/rename` is about to emit, so the wrapper can keep
+ * its diagnostics out of the timeline — and, more importantly, so the
+ * `prompt_result {agentInvoked:false}` this background command answers with is
+ * not read as "the operator's prompt opened no turn".
+ *
+ * Called BEFORE the request is sent, never after its ack. omp answers the ack
+ * and emits the `prompt_result` in the same tick (measured: 3 ms apart on
+ * 18.7.0), while the operator's turn is still streaming — so a window opened
+ * after the await is already too late. The `prompt_result` then reached the
+ * client, which folds it as "the run settled": the generating indicator blanked
+ * and the sidebar's live `stream` row was cleared while the answer kept
+ * arriving. `frame-fold` only suppresses the frame when the window is armed, so
+ * arming late is exactly the hole this ordering closes.
+ *
+ * On a send that never reached omp the claim is dropped (see the caller), so a
+ * window can never belong to nothing and block the settle-stage fallback.
+ */
+export function markTitleRequestSent(host: AutoTitleHost): void {
+  host.autoTitleWindowUntil = Date.now() + AUTO_TITLE_OUTPUT_WINDOW_MS;
+}
+
+/**
+ * True when this frame is the tail of our own background rename, consuming the
+ * window. One frame per request: omp emits exactly one `command_output` for it,
+ * on both the success and the "could not generate" path.
+ */
+export function consumeAutoTitleOutput(host: AutoTitleHost): boolean {
+  if (host.autoTitleWindowUntil === 0 || Date.now() > host.autoTitleWindowUntil) return false;
+  host.autoTitleWindowUntil = 0;
+  return true;
+}
+
+/**
+ * Read the `autoSessionTitle` flag from Kabmo settings blob. Absent or
+ * malformed → the default. Never throws: a settings read must not be able to
+ * break a turn's settle path.
+ */
+async function isAutoTitleEnabled(): Promise<boolean> {
+  try {
+    const db = await getDb();
+    const blob = await readSettingsJson<Record<string, unknown> | null>(db, SETTINGS_BLOB_KEY, null);
+    const value = blob?.autoSessionTitle;
+    return typeof value === 'boolean' ? value : AUTO_SESSION_TITLE_DEFAULT;
+  } catch {
+    return AUTO_SESSION_TITLE_DEFAULT;
+  }
+}
+
+/**
+ * Which of the two attempts inside the first run is asking.
+ *
+ * - `opening` — the first settled USER message. Earliest usable point, and it
+ *   does NOT consume the eligibility latch, so `settle` can still retry.
+ * - `settle` — the terminal `agent_end`. The fallback, and the attempt that
+ *   consumes the latch: after it, this conversation is never titled again.
+ */
+export type AutoTitleStage = 'opening' | 'settle';
+
+/**
+ * Ask omp to name this session from its opening turns.
+ *
+ * Called twice at most, both inside the conversation's first run: once when the
+ * first user message settles (`opening`), and once at the terminal `agent_end`
+ * as a fallback (`settle`). A second run never gets either — see the module
+ * doc for why a title derived from a later turn is the bug this gate prevents.
+ *
+ * Every bail-out is deliberate: a named session is never renamed by this path
+ * (the name is re-read from omp, so a rename made in another tab is respected),
+ * a generation already in flight is never duplicated, and failures are
+ * swallowed — an auto-title is a convenience, and a session whose opening
+ * message was low-signal ("hi") simply keeps its placeholder.
+ */
+export async function triggerAutoSessionTitle(host: AutoTitleHost, stage: AutoTitleStage): Promise<void> {
+  if (!host.autoTitlePending) return;
+  if (stage === 'opening') {
+    // One early attempt per run. A queued steer message also settles as a user
+    // message inside the same run, and re-asking on it would cancel the first
+    // generation for no gain — the context is the same turn either way.
+    if (host.autoTitleRequested) return;
+    // Consumed before the first await: two user messages settling in the same
+    // tick must not both pass the gate.
+    host.autoTitleRequested = true;
+  } else {
+    // Consumed before the first await: the fallback is this conversation's last
+    // chance, and two settles must never both pass the gate.
+    host.autoTitlePending = false;
+    // The early attempt is still generating. Its `command_output` has not
+    // arrived, so omp is mid-generation and a second `/rename` now would
+    // reserve a new title revision and cancel it — same title context, wasted
+    // model call. Leave the early attempt to finish.
+    if (host.autoTitleWindowUntil > Date.now()) return;
+  }
+  if (host.autoTitleInFlight || !host.sessionId) return;
+  if (!(await isAutoTitleEnabled())) return;
+
+  host.autoTitleInFlight = true;
+  try {
+    // Re-read the name from omp rather than trusting a cached value: a rename
+    // made in another tab (or by omp's own TUI on the same session file) would
+    // otherwise be overwritten by the `"user"` write `/rename` performs. This is
+    // also what makes the fallback a no-op when the early attempt already
+    // landed — the name is simply there by then.
+    const state = await host.proc.sendCommand<RpcSessionState>({ type: 'get_state' }, GET_STATE_TIMEOUT_MS);
+    if (state.sessionName?.trim()) return;
+    // The session changed under us (a reset, or a `switch_session`): the name
+    // we just read belongs to a different conversation.
+    if (state.sessionId !== host.sessionId) return;
+
+    // Direct `proc` write, NOT Kabmo's prompt dispatch: this is
+    // background work, so it must not mark the session streaming or claim the
+    // sidebar's run row. omp's ack is immediate (`agentInvoked:false`); the
+    // generation itself streams back later as ordinary frames.
+    //
+    // The claim is armed BEFORE the send, not after its ack: omp emits the
+    // `prompt_result {agentInvoked:false}` that answers this command within
+    // milliseconds, and the fold can only suppress it while the window is open
+    // (see `markTitleRequestSent`). An armed window is rolled back if the send
+    // never reached omp, so it cannot outlive a request that did not happen.
+    markTitleRequestSent(host);
+    try {
+      await host.proc.sendCommand({ type: 'prompt', message: GENERATE_TITLE_COMMAND }, PROMPT_ACK_TIMEOUT_MS);
+    } catch (error) {
+      host.autoTitleWindowUntil = 0;
+      throw error;
+    }
+  } catch {
+    // Provider error, timeout, or a child that went away — leave the session
+    // unnamed; the settle attempt (or the next run, for an aborted turn) tries
+    // again.
+  } finally {
+    host.autoTitleInFlight = false;
+  }
+}

package/src/server/lib/omp/session/blobs.server.test.ts

@@ -0,0 +1,129 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Blob-reference resolution for persisted session images.
+ *
+ * omp externalizes a large attached image out of the session JSONL: the entry
+ * keeps a content-addressed ref (`blob:sha256:<hash>`) and the bytes live in the
+ * blob store. Nothing else resolves them, so a reloaded session used to render
+ * `data:image/png;base64,blob:sha256:…` — a data URL whose payload is the ref
+ * string, which the browser cannot decode.
+ *
+ * The ref suffix feeds a `path.join` against the blob directory, so the
+ * canonical-hash guard is the security boundary and is tested as such.
+ *
+ * The agent dir is read per call (not at import time), so pointing
+ * `PI_CODING_AGENT_DIR` at a temp directory is enough to redirect the store.
+ */
+
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
+import * as fsp from 'node:fs/promises';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { getBlobStoreDir, isBlobRef, readBlob, readBlobImage, readBlobRef } from '@/server/lib/omp/session/blobs.server';
+import { extractUserImageAttachments, isBlobImageRef } from '@/shared/lib/omp/session/parse-message-blocks';
+
+/** A minimal but structurally valid PNG, so the assertion is about real bytes. */
+const PNG_BYTES = Buffer.from('89504e470d0a1a0a0000000d49484452', 'hex');
+const HASH = 'a'.repeat(64);
+
+let agentDir = '';
+
+beforeAll(async () => {
+  agentDir = await fsp.mkdtemp(path.join(os.tmpdir(), 'omp-blob-test-'));
+  process.env.PI_CODING_AGENT_DIR = agentDir;
+  await fsp.mkdir(getBlobStoreDir(), { recursive: true });
+  await fsp.writeFile(path.join(getBlobStoreDir(), HASH), PNG_BYTES);
+});
+
+afterAll(async () => {
+  delete process.env.PI_CODING_AGENT_DIR;
+  await fsp.rm(agentDir, { recursive: true, force: true });
+});
+
+describe('blob store reads', () => {
+  test('reads the bytes a hash points at', async () => {
+    expect(await readBlob(HASH)).toEqual(PNG_BYTES);
+  });
+
+  test('reads through a blob reference', async () => {
+    expect(await readBlobRef(`blob:sha256:${HASH}`)).toEqual(PNG_BYTES);
+  });
+
+  test('a missing blob yields null instead of throwing', async () => {
+    expect(await readBlob('b'.repeat(64))).toBeNull();
+  });
+
+  test('a non-reference string yields null', async () => {
+    expect(await readBlobRef('iVBORw0KGgo=')).toBeNull();
+  });
+
+  // The hash is interpolated into a path, so anything but a canonical digest
+  // must be refused before the filesystem is touched.
+  test('rejects refs that would escape the blob directory', async () => {
+    for (const bad of ['../../../../etc/passwd', '..%2f..%2fetc%2fpasswd', `${'a'.repeat(63)}/`, 'A'.repeat(64), 'abc', '']) {
+      expect(await readBlob(bad)).toBeNull();
+      expect(await readBlobRef(`blob:sha256:${bad}`)).toBeNull();
+    }
+  });
+
+  test('recognises the reference prefix', () => {
+    expect(isBlobRef(`blob:sha256:${HASH}`)).toBe(true);
+    expect(isBlobRef('data:image/png;base64,AAAA')).toBe(false);
+  });
+});
+
+describe('image block extraction', () => {
+  test('an externalized block carries the ref instead of a fake data URL', () => {
+    const ref = `blob:sha256:${HASH}`;
+    const [attachment] = extractUserImageAttachments([{ type: 'image', data: ref, mimeType: 'image/png' }]);
+    expect(attachment.blobRef).toBe(ref);
+    // The bug: `data:image/png;base64,blob:sha256:…` is not decodable.
+    expect(attachment.preview).toBe('');
+    expect(attachment.preview).not.toContain('base64,blob:');
+    expect(attachment.type).toBe('image/png');
+  });
+
+  test('an inlined block still becomes a data URL', () => {
+    const [attachment] = extractUserImageAttachments([{ type: 'image', data: 'iVBORw0KGgo=', mimeType: 'image/png' }]);
+    expect(attachment.preview).toBe('data:image/png;base64,iVBORw0KGgo=');
+    expect(attachment.blobRef).toBeUndefined();
+  });
+
+  test('distinguishes the two payload shapes', () => {
+    expect(isBlobImageRef(`blob:sha256:${HASH}`)).toBe(true);
+    expect(isBlobImageRef('iVBORw0KGgo=')).toBe(false);
+  });
+});
+
+describe('readBlobImage', () => {
+  /** A store entry with NO extension link beside it — what a pruned store or a
+   *  copied session leaves behind, and the case the extension cannot answer. */
+  const LONE_HASH = 'c'.repeat(64);
+  const JPEG_BYTES = Buffer.from([0xff, 0xd8, 0xff, 0xe0, 0x00, 0x10, 0x4a, 0x46]);
+
+  beforeAll(async () => {
+    await fsp.writeFile(path.join(getBlobStoreDir(), LONE_HASH), JPEG_BYTES);
+  });
+
+  test('names the content type from the bytes when no extension link exists', async () => {
+    // Measured on this install: a `read` of a 96×96 PNG came back as a JPEG
+    // blob, so the bytes are the honest source and the sibling link only the
+    // fallback.
+    const image = await readBlobImage(LONE_HASH);
+    expect(image?.mimeType).toBe('image/jpeg');
+    expect(image?.bytes).toEqual(JPEG_BYTES);
+  });
+
+  test('a missing blob yields null', async () => {
+    expect(await readBlobImage('d'.repeat(64))).toBeNull();
+  });
+
+  test('a malformed hash never reaches the filesystem', async () => {
+    expect(await readBlobImage('../../etc/passwd')).toBeNull();
+    expect(await readBlobImage('not-a-hash')).toBeNull();
+  });
+});