@kabmo-labs/kabmo 0.0.0-stage → 0.1.0

package/src/server/lib/omp/mode/live-selection.ts

@@ -0,0 +1,90 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The plan/goal selection of a session that is ALIVE but has no transcript yet.
+ *
+ * omp writes the session JSONL at its first ASSISTANT message, not at spawn, so
+ * a new chat spends its first seconds-to-minutes with a live child and no file.
+ * During that window the file-based read has nothing to answer from, and the
+ * console's hydration (`useChatTimelineModes`) treats the resulting 404 as
+ * "no modes" — which resets the very toggles the user just pressed. Measured on
+ * a real spawn: the file appeared 40 s after the id was adopted, so a Plan
+ * toggle made in between was undone in the composer while the child was
+ * demonstrably in plan mode.
+ *
+ * Two sources answer for the child, and neither can drift from it:
+ *
+ *  - the wrapper's `ModeMirror`, fed by the extension's own `KABMO_*` markers
+ *    and by omp's `goal_updated`;
+ *  - the spawn environment (`KABMO_MODES`), which is the selection the child
+ *    was started with and which its extension re-applies at session start.
+ *
+ * `spoken` says whether the child itself has reported a mode. It is what the
+ * caller uses to decide between these and a transcript that already exists:
+ * the child's word is newer than any entry the file holds (a toggle moves the
+ * child, and the append that records it lands a moment later), while an
+ * unreported child is described better by the file than by the environment it
+ * happened to be spawned with.
+ */
+
+import { getRpcSession, getSpawnModeEnv } from '@/server/lib/omp/rpc/manager';
+import { selectionFromModeEnvValue } from '@/server/lib/omp/mode/request';
+import type { PersistedModes } from '@/server/lib/omp/session/modes';
+import { isGoalOpen, isGoalStatus } from '@/shared/lib/omp/mode/status';
+
+export interface LiveModeSelection {
+  modes: PersistedModes;
+  /** True once the child has reported a mode itself (a marker, or a
+   *  `goal_updated` frame) — as opposed to the selection it was spawned with. */
+  spoken: boolean;
+}
+
+/**
+ * The mode selection of the live child running `sessionId`, or null when this
+ * process holds no live child for it.
+ */
+export function liveModeSelection(sessionId: string): LiveModeSelection | null {
+  const session = getRpcSession(sessionId);
+  if (!session || !session.isAlive()) return null;
+
+  const mirror = session.modeMirror;
+  // Both env spellings: this build exports `KABMO_MODES`, and a child spawned
+  // by an older one carries `CHAMBER_MODES`.
+  const env = getSpawnModeEnv(session);
+  const spawned = selectionFromModeEnvValue(env.KABMO_MODES ?? env.CHAMBER_MODES);
+  // The child has spoken if EITHER feed produced anything: a `KABMO_*` marker
+  // (plan, or a goal record) or omp's own `goal_updated` (a goal status).
+  const spoken =
+    mirror.planEnabled !== undefined || mirror.goalRecord !== null || mirror.goalStatus !== undefined;
+  const plan = mirror.planEnabled ?? spawned.plan;
+  const record = mirror.goalRecord;
+  // A goal this chat no longer owns (`complete`/`dropped`) is reported as OFF
+  // even while its record travels: the composer's strip and button gate on the
+  // same question (`isGoalOpen`), and a closed goal must not re-open them. With
+  // no record at all, the child's own `goal_updated` status decides — and a
+  // status this build does not know reads as OFF rather than as an open goal.
+  const goal = record
+    ? isGoalOpen(record.status)
+    : isGoalStatus(mirror.goalStatus)
+      ? isGoalOpen(mirror.goalStatus)
+      : spawned.goal;
+
+  return {
+    spoken,
+    modes: {
+      plan,
+      goal,
+      // The file reader's rule, applied to the mirror: only an ENABLED goal is
+      // being pursued, and only `active` is a goal actually working (paused and
+      // budget-limited stay open but idle, which is what arms the continuation
+      // loop).
+      goalLive: mirror.goalEnabled && record?.status === 'active',
+      goalRecord: record,
+      goalContinuation: mirror.goalContinuation,
+      goalMaxTurns: mirror.goalMaxTurns,
+    },
+  };
+}

package/src/server/lib/omp/mode/request.test.ts

@@ -0,0 +1,73 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The mode command's wire format.
+ *
+ * The prompt it produces is what the extension parses, so the two ends must
+ * agree on one thing above all: the payload travels as ONE line. An objective
+ * is free-form text with newlines in it, and a newline inside the JSON would
+ * end the prompt's argument region instead of the string it belongs to.
+ */
+
+import { describe, expect, test } from 'bun:test';
+import { modeCommandPrompt, modeEnvValue, parseModeRequest, parseModeSelection } from '@/server/lib/omp/mode/request';
+
+describe('parseModeRequest', () => {
+  test('accepts a well-formed request', () => {
+    expect(parseModeRequest({ scope: 'plan', action: 'on' })).toEqual({ scope: 'plan', action: 'on', payload: undefined });
+    expect(parseModeRequest({ scope: 'goal', action: 'create', payload: { objective: 'x' } })?.payload).toEqual({ objective: 'x' });
+  });
+
+  test('refuses an unknown scope or an empty action', () => {
+    expect(parseModeRequest({ scope: 'vibe', action: 'on' })).toBeNull();
+    expect(parseModeRequest({ scope: 'plan', action: '  ' })).toBeNull();
+    expect(parseModeRequest({ scope: 'plan' })).toBeNull();
+  });
+
+  test('drops a payload that is not an object', () => {
+    expect(parseModeRequest({ scope: 'plan', action: 'on', payload: 'x' })?.payload).toBeUndefined();
+    expect(parseModeRequest({ scope: 'plan', action: 'on', payload: ['x'] })?.payload).toBeUndefined();
+  });
+});
+
+describe('modeCommandPrompt', () => {
+  test('renders one line for a payload with newlines', () => {
+    const prompt = modeCommandPrompt({
+      scope: 'goal',
+      action: 'create',
+      payload: { objective: 'line one\nline two' },
+    });
+    expect(prompt.includes('\n')).toBe(false);
+    expect(prompt.startsWith('/kabmo-mode goal create ')).toBe(true);
+    // Round-trips: the extension parses the same JSON back out.
+    const json = prompt.slice('/kabmo-mode goal create '.length);
+    expect(JSON.parse(json).objective).toBe('line one\nline two');
+  });
+
+  test('omits an empty payload', () => {
+    expect(modeCommandPrompt({ scope: 'plan', action: 'off' })).toBe('/kabmo-mode plan off');
+  });
+});
+
+describe('parseModeSelection', () => {
+  test('absent flags mean off', () => {
+    expect(parseModeSelection({})).toEqual({ plan: false, goal: false });
+    expect(parseModeSelection({ plan: true })).toEqual({ plan: true, goal: false });
+  });
+
+  test('only a literal true turns a mode on', () => {
+    expect(parseModeSelection({ plan: 'true', goal: 1 })).toEqual({ plan: false, goal: false });
+  });
+});
+
+describe('modeEnvValue', () => {
+  test('names only the modes that are on', () => {
+    expect(modeEnvValue({ plan: true, goal: false })).toBe('plan');
+    expect(modeEnvValue({ plan: false, goal: true })).toBe('goal');
+    expect(modeEnvValue({ plan: true, goal: true })).toBe('plan,goal');
+    expect(modeEnvValue({ plan: false, goal: false })).toBe('');
+  });
+});

package/src/server/lib/omp/mode/request.ts

@@ -0,0 +1,94 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The Kabmo's plan/goal control channel.
+ *
+ * Every mode action is an ordinary `/kabmo-mode <scope> <action> [json]`
+ * prompt sent to the live child, where Kabmo-owned extension executes it
+ * locally. Three properties make that the right transport, and all three are
+ * measured rather than assumed:
+ *
+ *  - it reaches the live `AgentSession`, which no RPC verb does for either
+ *    mode;
+ *  - it costs no transcript: the command answers `agentInvoked: false` and
+ *    writes no user message, so toggling Plan five times leaves no bubbles;
+ *  - it needs no respawn. The extension re-applies both flags in-process, so a
+ *    live session is re-targeted instantly — unlike `--approval-mode`, which is
+ *    a spawn-time flag and forces the destroy-and-respawn dance.
+ *
+ * The payload is JSON because an objective is free-form text: spaces,
+ * punctuation and newlines all have to survive one line of prompt.
+ */
+
+import { isRecord } from '@/shared/lib/util/guards';
+import { KABMO_MODE_COMMAND, type KabmoModeSelection } from '@/shared/lib/omp/mode/types';
+
+export type ModeScope = 'plan' | 'goal';
+
+export interface ModeRequest {
+  scope: ModeScope;
+  action: string;
+  payload?: Record<string, unknown>;
+}
+
+/** The command type a mode request travels as.
+ *
+ *  `kabmo_mode` is what this build sends; `chamber_mode` is the pre-rename
+ *  spelling and is still ACCEPTED, because a tab that loaded before a restart
+ *  keeps posting the old name until it reloads, and a rejected request there
+ *  reads as a dead Plan/Goal button. */
+export const MODE_COMMAND_TYPE = 'kabmo_mode';
+
+/** @deprecated Use `MODE_COMMAND_TYPE`. Accepted on the read side. */
+export const LEGACY_MODE_COMMAND_TYPE = 'chamber_mode';
+
+/** Whether a command body's `type` names a mode request, under either spelling. */
+export function isModeCommandType(type: unknown): boolean {
+  return type === MODE_COMMAND_TYPE || type === LEGACY_MODE_COMMAND_TYPE;
+}
+
+/** Parse a mode request body. Returns null when the shape is wrong,
+ *  so the route answers a 400 instead of forwarding a command the extension
+ *  would reject with a notice. */
+export function parseModeRequest(body: Record<string, unknown>): ModeRequest | null {
+  const scope = body.scope;
+  const action = body.action;
+  if (scope !== 'plan' && scope !== 'goal') return null;
+  if (typeof action !== 'string' || !action.trim()) return null;
+  const payload = isRecord(body.payload) ? body.payload : undefined;
+  return { scope, action: action.trim(), payload };
+}
+
+/** Render the prompt that carries a mode request to the extension.
+ *
+ *  One line, always: the command token ends at the first whitespace run, and a
+ *  newline inside the JSON would end the prompt's argument region instead of
+ *  the string it belongs to. `JSON.stringify` escapes newlines, which is the
+ *  whole reason the payload is JSON rather than `key=value` pairs. */
+export function modeCommandPrompt(request: ModeRequest): string {
+  const payload = request.payload && Object.keys(request.payload).length > 0 ? ` ${JSON.stringify(request.payload)}` : '';
+  return `/${KABMO_MODE_COMMAND} ${request.scope} ${request.action}${payload}`;
+}
+
+/** A selection parsed from a client request body. Absent flags mean "off", so
+ *  a partial body can never silently leave a mode on. */
+export function parseModeSelection(body: Record<string, unknown>): KabmoModeSelection {
+  return { plan: body.plan === true, goal: body.goal === true };
+}
+
+/** The extension's mode-selection env value for a selection. */
+export function modeEnvValue(selection: KabmoModeSelection): string {
+  return [selection.plan ? 'plan' : '', selection.goal ? 'goal' : ''].filter(Boolean).join(',');
+}
+
+/** The selection a mode-selection env value describes — the inverse of
+ *  `modeEnvValue`, kept beside it so the two spellings of the format cannot
+ *  drift. An absent or empty value is the empty selection, which is what a
+ *  prewarmed child carries. */
+export function selectionFromModeEnvValue(value: string | undefined): KabmoModeSelection {
+  const parts = (value ?? '').split(',');
+  return { plan: parts.includes('plan'), goal: parts.includes('goal') };
+}

package/src/server/lib/omp/rpc/agent-start-watchdog.ts

@@ -0,0 +1,88 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Watchdog for a dispatch whose turn never opened.
+ *
+ * The command dispatcher marks `stream` and arms `awaitingAgentStartDeadline`
+ * the moment a prompt is sent, because omp may accept it and open no turn at
+ * all — a builtin it runs itself, or a prompt it drops. It then relies on a
+ * frame to settle that state: `agent_start` for a real run, `prompt_result` for
+ * one that never started. When NO such frame ever arrives nothing settles it:
+ *
+ *   - `promptRunning` stays true, so `isRunning()` stays true, so the idle
+ *     reaper refuses to reclaim the child and `GET /api/agent/:id` reports
+ *     `busy` forever;
+ *   - the `stream` row is owned by a LIVE process, so
+ *     `healStaleStreamStatuses` cannot reach it either — the sidebar spinner
+ *     turns until the process restarts.
+ *
+ * Measured shape: Kabmo's own `/kabmo-mode` extension (the composer's
+ * Plan/Goal toggles) acks a bare `{success:true}`, which reads as a run.
+ *
+ * The deadline is the only thing that can tell this apart from a slow start,
+ * and nothing was watching it. This watches it.
+ *
+ * The decision is a callback because "did it actually settle?" is a question
+ * only the wrapper can answer — the same split as `IdleReaper`, and for the
+ * same reason: this object owns only the clock.
+ */
+
+export interface AgentStartWatchdogHost {
+  /** Armed by the dispatcher; cleared by any frame that settles the dispatch. */
+  awaitingAgentStart: boolean;
+  awaitingAgentStartDeadline: number;
+  /** A real run is under way, which outranks a stale deadline. */
+  streaming: boolean;
+  sessionId: string;
+}
+
+export class AgentStartWatchdog {
+  #timer: ReturnType<typeof setTimeout> | null = null;
+  readonly #host: AgentStartWatchdogHost;
+  readonly #onExpired: () => void;
+
+  constructor(host: AgentStartWatchdogHost, onExpired: () => void) {
+    this.#host = host;
+    this.#onExpired = onExpired;
+  }
+
+  /**
+   * (Re-)arm for the pending deadline. A no-op when no dispatch is awaiting a
+   * turn, so it is safe to call unconditionally after a prompt ack.
+   */
+  arm(): void {
+    this.stop();
+    if (!this.#host.awaitingAgentStart || !this.#host.sessionId) return;
+    const delayMs = Math.max(0, this.#host.awaitingAgentStartDeadline - Date.now());
+    this.#timer = setTimeout(() => {
+      this.#timer = null;
+      // A frame settled the dispatch while we waited — the deadline is no
+      // longer the truth about it, and a live turn always outranks it.
+      if (!this.#host.awaitingAgentStart || this.#host.streaming) return;
+      this.#onExpired();
+    }, delayMs);
+    // Must never keep the event loop alive on its own.
+    this.#timer.unref?.();
+  }
+
+  /**
+   * Cancel when a frame settled the dispatch (`agent_start` cleared the
+   * awaiting flag and streams; `prompt_result` cleared it too). Cancelling here
+   * rather than letting the timer fire keeps a stale callback from re-reading
+   * flags a LATER dispatch has since re-armed.
+   */
+  settleIfDone(): void {
+    if (this.#timer === null) return;
+    if (!this.#host.awaitingAgentStart || this.#host.streaming) this.stop();
+  }
+
+  /** Cancel without firing (teardown, an explicit destroy). */
+  stop(): void {
+    // The guard narrows `null` for `clearTimeout`; it also mirrors IdleReaper.
+    if (this.#timer) clearTimeout(this.#timer);
+    this.#timer = null;
+  }
+}

package/src/server/lib/omp/rpc/child-config.ts

@@ -0,0 +1,48 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The commands a freshly-spawned child is configured with, before any prompt.
+ *
+ * Split out of `manager.ts` (which is at the repo's per-file ceiling) so the
+ * attach sequence reads as one list rather than being interleaved with the
+ * wrapper's own state. Each entry is BEST-EFFORT: an older omp answers
+ * `Unknown command` and the run continues on that build's defaults, which is
+ * why none of them may throw.
+ *
+ * `set_event_filter` keeps the FULL accumulated message on every `message_update`
+ * frame — the projection omp calls `"full"` and the one it uses by default.
+ * Delta mode (`messageUpdates: "delta"`) was measured ~101x smaller on the wire
+ * (108 KB / 486 frames against 10.9 MB / 2217 on a 300-word prompt), but it
+ * drops the identity a streaming tool call needs: `toolcall_delta` carries ONLY
+ * `{contentIndex, delta}`, and `toolcall_start` carries no block at all. The
+ * name and id live on the seed block, and `message_start`'s snapshot does not
+ * reliably contain it — measured on omp 18.10.3, the same model produced a seed
+ * of `[text, toolCall]` on one run and `[thinking]` on the next, so a card
+ * rendered a bare **Tool** for the whole argument stream and only snapped to
+ * `Write — <path>` at `toolcall_end` (which also remounted it, dropping the
+ * reader's expand state). `full` makes the name and id readable from the first
+ * delta, at the cost of the accumulated snapshot per frame.
+ *
+ * Nothing else changes: the terminal frames (`message_start`, `message_end`,
+ * `turn_end`, `agent_end`) carry the full message either way.
+ */
+
+import type { RpcProcess } from '@/server/lib/omp/rpc/process';
+
+/** Apply the attach-time configuration to a child that just became ready. */
+export async function configureChild(proc: RpcProcess): Promise<void> {
+  // Subagent lifecycle/progress/event frames, so the UI can show a live roster.
+  await proc.sendCommand({ type: 'set_subagent_subscription', level: 'events' }).catch(() => {});
+  // Full accumulated `message_update` frames (see the module doc): the streaming
+  // tool call's name/id live on the seed block, which delta mode drops.
+  await proc.sendCommand({ type: 'set_event_filter', events: null, messageUpdates: 'full' }).catch(() => {});
+  // Grouped `ask` dialogs: every question of one `ask` tool call in a SINGLE
+  // `extension_ui_request` (`method:"ask"`, with `multi`/`recommended`), answered
+  // by one `answers` response. Without this omp loops one `select` per question,
+  // which is what the ask card's per-question bookkeeping exists to reassemble.
+  // Verified on 18.8.3: two questions (one `multi`) arrived in one request.
+  await proc.sendCommand({ type: 'set_ask_dialog', enabled: true }).catch(() => {});
+}

package/src/server/lib/omp/rpc/constants.test.ts

@@ -0,0 +1,229 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The RPC command/constant contract shared with the omp CLI and with the
+ * session dispatcher.
+ *
+ * These tests exist because every value here is load-bearing in a way that is
+ * invisible at the call site: the timeout windows decide whether a wedged child
+ * is reclaimed or a live turn is destroyed, the command sets decide whether a
+ * command is forwarded verbatim or refused, the image limits are the only
+ * server-side bound on what a client may POST, and the argv builders are the
+ * literal contract with the omp binary (`--resume`, `--approval-mode`, `-e`).
+ * A silent change to any of them is a behavior change, so the exact values and
+ * the argument ORDER are pinned.
+ */
+
+import { afterEach, describe, expect, test } from 'bun:test';
+import { existsSync, mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, isAbsolute } from 'node:path';
+import { titleModelOverlayPath } from '@/server/lib/omp/session/title-model-overlay.server';
+
+import {
+  AWAITING_AGENT_START_TIMEOUT_MS,
+  ANSWERABLE_UI_METHODS,
+  CONVERSATION_MOVING_COMMANDS,
+  GET_STATE_TIMEOUT_MS,
+  IDLE_REAP_MS,
+  IMAGE_BEARING_COMMANDS,
+  MAX_AGGREGATE_IMAGE_BYTES,
+  MAX_ATTACHED_IMAGE_BYTES,
+  MAX_ATTACHED_IMAGES,
+  NON_TERMINAL_CONTINUATION_GRACE_MS,
+  OBSERVER_ONLY_COMMANDS,
+  PASSTHROUGH_COMMANDS,
+  PROMPT_ACK_TIMEOUT_MS,
+  READY_TIMEOUT_MS,
+  RELOAD_PLUGINS_TIMEOUT_MS,
+  RESTARTING_MESSAGE,
+  SESSION_BUSY_MESSAGE,
+  SUBAGENT_STALE_MS,
+  buildSessionSpawnArgs,
+  resolveSpawnCwd,
+  toImageContents,
+  validateAgentImages,
+} from '@/server/lib/omp/rpc/constants';
+import { kabmoExtensionArgs } from '@/server/lib/omp/extensions/locator';
+
+const tempDirs: string[] = [];
+
+afterEach(() => {
+  for (const dir of tempDirs.splice(0)) rmSync(dir, { recursive: true, force: true });
+});
+
+function tempDir(): string {
+  const dir = mkdtempSync(join(tmpdir(), 'kabmo-test-'));
+  tempDirs.push(dir);
+  return dir;
+}
+
+describe('timeout windows and messages', () => {
+  test('reclaim windows keep their measured values', () => {
+    expect(IDLE_REAP_MS).toBe(600_000);
+    expect(SUBAGENT_STALE_MS).toBe(1_800_000);
+  });
+
+  test('command timeouts keep their values', () => {
+    expect(READY_TIMEOUT_MS).toBe(120_000);
+    expect(GET_STATE_TIMEOUT_MS).toBe(5_000);
+    expect(PROMPT_ACK_TIMEOUT_MS).toBe(30_000);
+    expect(RELOAD_PLUGINS_TIMEOUT_MS).toBe(10_000);
+    expect(NON_TERMINAL_CONTINUATION_GRACE_MS).toBe(2_000);
+    expect(AWAITING_AGENT_START_TIMEOUT_MS).toBe(10_000);
+  });
+
+  test('user-facing messages are verbatim', () => {
+    expect(RESTARTING_MESSAGE).toBe('This session is restarting — retry in a moment.');
+    expect(SESSION_BUSY_MESSAGE).toBe('The OMP session is busy with the running turn; retry once it settles.');
+  });
+});
+
+describe('command classification sets', () => {
+  test('passthrough commands are the exact verbatim-forward set', () => {
+    expect(PASSTHROUGH_COMMANDS.size).toBe(25);
+    for (const command of ['abort', 'steer', 'follow_up', 'set_thinking_level', 'set_todos', 'get_login_providers', 'login', 'cancel_subagent', 'steer_subagent']) {
+      expect(PASSTHROUGH_COMMANDS.has(command)).toBe(true);
+    }
+    // Commands the dispatcher handles itself must NOT be passthrough, or their
+    // argument handling would be bypassed by the verbatim forward.
+    for (const command of ['prompt', 'get_state', 'set_model', 'set_fast_mode', 'compact', 'bash', 'get_commands']) {
+      expect(PASSTHROUGH_COMMANDS.has(command)).toBe(false);
+    }
+  });
+
+  test('observer-only commands are a subset of passthrough', () => {
+    expect([...OBSERVER_ONLY_COMMANDS].sort()).toEqual(['get_subagent_messages', 'get_subagents']);
+    for (const command of OBSERVER_ONLY_COMMANDS) expect(PASSTHROUGH_COMMANDS.has(command)).toBe(true);
+  });
+
+  test('conversation-moving commands are dispatched, never forwarded verbatim', () => {
+    expect([...CONVERSATION_MOVING_COMMANDS].sort()).toEqual(['branch', 'handoff', 'new_session', 'switch_session']);
+    for (const command of CONVERSATION_MOVING_COMMANDS) expect(PASSTHROUGH_COMMANDS.has(command)).toBe(false);
+  });
+
+  test('image-bearing commands and answerable UI methods', () => {
+    expect([...IMAGE_BEARING_COMMANDS].sort()).toEqual(['abort_and_prompt', 'follow_up', 'prompt', 'steer']);
+    // `ask` is the grouped dialog `configureChild` opts into with
+    // `set_ask_dialog`: omp parks the tool call on it exactly as it does on a
+    // `select`, so a list without it leaves the frame unremembered and the
+    // question unanswerable after a reload.
+    expect(Object.keys(ANSWERABLE_UI_METHODS).sort()).toEqual(['ask', 'confirm', 'editor', 'input', 'select']);
+    // Fire-and-forget methods must never block a turn waiting for a response.
+    expect(ANSWERABLE_UI_METHODS.notify).toBeUndefined();
+    expect(ANSWERABLE_UI_METHODS.cancel).toBeUndefined();
+  });
+});
+
+describe('validateAgentImages', () => {
+  test('absent images are allowed, non-arrays are not', () => {
+    expect(validateAgentImages(undefined)).toBeNull();
+    expect(validateAgentImages('nope')).toBe('images must be an array');
+    expect(validateAgentImages({ data: 'x', mimeType: 'image/png' })).toBe('images must be an array');
+  });
+
+  test('more than the maximum count is refused by count alone', () => {
+    expect(MAX_ATTACHED_IMAGES).toBe(20);
+    const images = Array.from({ length: MAX_ATTACHED_IMAGES + 1 }, () => ({ data: 'AAAA', mimeType: 'image/png' }));
+    expect(validateAgentImages(images)).toBe(`Maximum of ${MAX_ATTACHED_IMAGES} attached images reached.`);
+  });
+
+  test('malformed entries are refused', () => {
+    expect(validateAgentImages([null])).toBe('invalid image entry');
+    expect(validateAgentImages([{ data: 1, mimeType: 'image/png' }])).toBe('invalid image entry');
+    expect(validateAgentImages([{ data: 'AAAA' }])).toBe('invalid image entry');
+  });
+
+  test('a valid single image passes and its size is measured from the base64 body', () => {
+    expect(MAX_ATTACHED_IMAGE_BYTES).toBe(20 * 1024 * 1024);
+    expect(validateAgentImages([{ data: 'AAAA', mimeType: 'image/png' }])).toBeNull();
+  });
+
+  test('a single image over the per-image limit is refused', () => {
+    // 21 MiB of decoded bytes: over the 20 MB cap, still a legal base64 body.
+    const data = 'A'.repeat(4 * Math.ceil((21 * 1024 * 1024) / 3));
+    expect(validateAgentImages([{ data, mimeType: 'image/png' }])).toBe('Images up to 20 MB are supported.');
+  });
+
+  test('the aggregate limit is checked across individually-legal images', () => {
+    expect(MAX_AGGREGATE_IMAGE_BYTES).toBe(40 * 1024 * 1024);
+    // Three ~14 MiB images: each is under the per-image cap, the sum is not.
+    const data = 'A'.repeat(4 * Math.ceil((14 * 1024 * 1024) / 3));
+    const images = Array.from({ length: 3 }, () => ({ data, mimeType: 'image/png' }));
+    expect(validateAgentImages(images)).toBe('Total image size exceeds the supported limit.');
+  });
+});
+
+describe('toImageContents', () => {
+  test('omits an empty or absent list so the wire payload carries no images key', () => {
+    expect(toImageContents(undefined)).toBeUndefined();
+    expect(toImageContents([])).toBeUndefined();
+  });
+
+  test('passes a non-empty list through by reference', () => {
+    const images = [{ type: 'image' as const, data: 'AAAA', mimeType: 'image/png' }];
+    expect(toImageContents(images)).toBe(images);
+  });
+});
+
+describe('resolveSpawnCwd', () => {
+  test('a recorded cwd that still exists is used verbatim', async () => {
+    const dir = tempDir();
+    expect(await resolveSpawnCwd(dir)).toBe(dir);
+  });
+
+  test('a deleted recorded cwd falls back to the server cwd', async () => {
+    const dir = tempDir();
+    rmSync(dir, { recursive: true, force: true });
+    expect(await resolveSpawnCwd(dir)).toBe(process.cwd());
+    expect(await resolveSpawnCwd(null)).toBe(process.cwd());
+    expect(await resolveSpawnCwd(undefined)).toBe(process.cwd());
+  });
+});
+
+describe('buildSessionSpawnArgs', () => {
+  test('the title-model overlay, then the resume file, approval mode and extension load', () => {
+    expect(buildSessionSpawnArgs('/tmp/session.jsonl', 'yolo')).toEqual([
+      '--config',
+      titleModelOverlayPath(),
+      '--resume',
+      '/tmp/session.jsonl',
+      '--approval-mode',
+      'yolo',
+      ...kabmoExtensionArgs(),
+    ]);
+  });
+
+  test('an approval mode is passed without a resume file', () => {
+    expect(buildSessionSpawnArgs('', 'write')).toEqual([
+      '--config',
+      titleModelOverlayPath(),
+      '--approval-mode',
+      'write',
+      ...kabmoExtensionArgs(),
+    ]);
+  });
+
+  test('a new session still gets the overlay and the extension load', () => {
+    expect(buildSessionSpawnArgs('')).toEqual(['--config', titleModelOverlayPath(), ...kabmoExtensionArgs()]);
+  });
+
+  test('the overlay file EXISTS by the time the argv names it', () => {
+    // omp's `--config` loader is strict: a missing file is a hard error, so the
+    // file has to be there before the spawn reads the argv.
+    const args = buildSessionSpawnArgs('');
+    const path = args[args.indexOf('--config') + 1];
+    expect(path).toBe(titleModelOverlayPath());
+    expect(existsSync(path)).toBe(true);
+  });
+
+  test('the extension load is the `-e <existing absolute file>` pair', () => {
+    const args = kabmoExtensionArgs();
+    expect(args.length === 0 || args[0] === '-e').toBe(true);
+    // `isAbsolute`, not `startsWith('/')`: a Windows checkout names it `C:\…`.
+    if (args.length > 0) expect(isAbsolute(args[1])).toBe(true);
+  });
+});