@kabmo-labs/kabmo 0.0.0-stage → 0.0.1

package/src/server/lib/omp/rpc/mode-mirror.test.ts

@@ -0,0 +1,156 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The wrapper's goal mirror.
+ *
+ * `get_state` does not carry goal mode, so this mirror is the only thing the
+ * agent-state route can report a reattaching client. It is fed by omp's own
+ * `goal_updated`, which is authoritative — and the rule that matters is which
+ * STATUSES count as live, because the answer decides whether the composer's
+ * toggle reads as on.
+ */
+
+import { describe, expect, test } from 'bun:test';
+import { ModeMirror } from '@/server/lib/omp/rpc/mode-mirror';
+import type { GoalStatus } from '@/shared/lib/omp/mode/types';
+
+function frame(status: GoalStatus, enabled = true) {
+  return { type: 'goal_updated', goal: { id: 'g1', objective: 'x', status }, state: { enabled, goal: { id: 'g1', objective: 'x', status } } };
+}
+
+function goal(status: GoalStatus) {
+  return { id: 'g1', objective: 'x', status, tokensUsed: 0, timeUsedSeconds: 0, createdAt: 0, updatedAt: 0 };
+}
+
+describe('ModeMirror', () => {
+  test('active and budget-limited are live', () => {
+    const live: GoalStatus[] = ['active', 'budget-limited'];
+    for (const status of live) {
+      const mirror = new ModeMirror();
+      mirror.observe(frame(status));
+      expect(mirror.goalEnabled).toBe(true);
+      expect(mirror.goalStatus).toBe(status);
+    }
+  });
+
+  test('paused, complete and dropped are not live', () => {
+    const closed: GoalStatus[] = ['paused', 'complete', 'dropped'];
+    for (const status of closed) {
+      const mirror = new ModeMirror();
+      mirror.observe(frame(status));
+      expect(mirror.goalEnabled).toBe(false);
+      // The status is still recorded: the card and the modal show what the goal
+      // WAS, which a bare boolean could not.
+      expect(mirror.goalStatus).toBe(status);
+    }
+  });
+
+  test('enabled:false wins even for an active status', () => {
+    const mirror = new ModeMirror();
+    mirror.observe(frame('active', false));
+    expect(mirror.goalEnabled).toBe(false);
+  });
+
+  test('reads the status from the top-level goal when no state is present', () => {
+    const mirror = new ModeMirror();
+    mirror.observe({ type: 'goal_updated', goal: { id: 'g1', objective: 'x', status: 'active' } });
+    expect(mirror.goalEnabled).toBe(false); // no `state.enabled`, so not live
+    expect(mirror.goalStatus).toBe('active');
+  });
+
+  test('a null goal clears the status', () => {
+    const mirror = new ModeMirror();
+    mirror.observe(frame('active'));
+    mirror.observe({ type: 'goal_updated', goal: null });
+    expect(mirror.goalEnabled).toBe(false);
+    expect(mirror.goalStatus).toBeUndefined();
+  });
+});
+
+/**
+ * The marker feed: the extension's own `CHAMBER_*` notices.
+ *
+ * This half exists because a new chat has no transcript for the first
+ * seconds-to-minutes of its life (omp writes the JSONL at the first assistant
+ * message), while the child is already in whatever mode the user picked — and
+ * because PLAN mode has no omp event at all, so the extension's marker is the
+ * only live word on it.
+ */
+describe('ModeMirror.observeMarker', () => {
+  const marker = (name: string, payload: Record<string, unknown>) => ({ marker: name as never, payload });
+
+  test('the pre-rename spelling is still observed', () => {
+    // A transcript replayed from before the rename carries `CHAMBER_*`; the
+    // mirror is what a reattaching client reads the mode from, so ignoring the
+    // old prefix would show a session as having no mode at all.
+    const mirror = new ModeMirror();
+    mirror.observeMarker(marker('CHAMBER_PLAN_STATE:', { enabled: true }));
+    expect(mirror.planEnabled).toBe(true);
+    mirror.observeMarker(marker('CHAMBER_GOAL_STATE:', { goal: goal('active'), enabled: true }));
+    expect(mirror.goalRecord?.id).toBe('g1');
+  });
+
+  test('a plan marker sets the flag in both directions', () => {
+    const mirror = new ModeMirror();
+    expect(mirror.planEnabled).toBeUndefined();
+    mirror.observeMarker(marker('KABMO_PLAN_STATE:', { enabled: true }));
+    expect(mirror.planEnabled).toBe(true);
+    mirror.observeMarker(marker('KABMO_PLAN_STATE:', { enabled: false }));
+    expect(mirror.planEnabled).toBe(false);
+  });
+
+  test('a goal marker records the record and applies the live rule', () => {
+    const mirror = new ModeMirror();
+    mirror.observeMarker(marker('KABMO_GOAL_STATE:', { goal: goal('active'), enabled: true }));
+    expect(mirror.goalRecord?.id).toBe('g1');
+    expect(mirror.goalStatus).toBe('active');
+    expect(mirror.goalEnabled).toBe(true);
+
+    // Paused: the record stays (the composer still shows the goal) but it is
+    // not work in progress.
+    mirror.observeMarker(marker('KABMO_GOAL_STATE:', { goal: goal('paused'), enabled: false }));
+    expect(mirror.goalRecord?.status).toBe('paused');
+    expect(mirror.goalEnabled).toBe(false);
+  });
+
+  test('a continuation verdict and its ceiling ride the goal marker', () => {
+    const mirror = new ModeMirror();
+    mirror.observeMarker(
+      marker('KABMO_GOAL_STATE:', { goal: goal('active'), enabled: true, continuation: { turn: 3, maxTurns: 25 }, maxTurns: 25 }),
+    );
+    expect(mirror.goalContinuation).toEqual({ turn: 3, maxTurns: 25 });
+    expect(mirror.goalMaxTurns).toBe(25);
+
+    // A transition entry with no verdict must not erase the last one.
+    mirror.observeMarker(marker('KABMO_GOAL_STATE:', { goal: goal('active'), enabled: true }));
+    expect(mirror.goalContinuation).toEqual({ turn: 3, maxTurns: 25 });
+  });
+
+  test('a plan marker leaves the goal record alone', () => {
+    const mirror = new ModeMirror();
+    mirror.observeMarker(marker('KABMO_GOAL_STATE:', { goal: goal('active'), enabled: true }));
+    mirror.observeMarker(marker('KABMO_PLAN_STATE:', { enabled: true }));
+    expect(mirror.goalRecord?.id).toBe('g1');
+    expect(mirror.goalEnabled).toBe(true);
+  });
+
+  test('a refusal and a proposal are not a selection', () => {
+    const mirror = new ModeMirror();
+    mirror.observeMarker(marker('CHAMBER_MODE_ERROR:', { scope: 'plan', reason: 'nope' }));
+    mirror.observeMarker(marker('CHAMBER_PLAN_PROPOSAL:', { title: 'x' }));
+    expect(mirror.planEnabled).toBeUndefined();
+    expect(mirror.goalRecord).toBeNull();
+  });
+
+  // A status this build does not know is a version skew, not an open goal: it
+  // is dropped rather than stored, so no downstream `isGoalOpen` has to cast.
+  test('an unknown goal status is not recorded as one', () => {
+    const mirror = new ModeMirror();
+    mirror.observe({ type: 'goal_updated', goal: { status: 'invented' }, state: { enabled: true, goal: { status: 'invented' } } });
+    expect(mirror.goalStatus).toBeUndefined();
+    expect(mirror.goalEnabled).toBe(false);
+  });
+});

package/src/server/lib/omp/rpc/mode-mirror.ts

@@ -0,0 +1,109 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The wrapper's mirror of omp's plan/goal modes.
+ *
+ * Two facts make a mirror necessary rather than a passthrough:
+ *
+ *  - `get_state` does not carry either mode, so a reattaching client (a reload,
+ *    a second tab) has nothing to read the mode from;
+ *  - and the mode is not a client preference — it decides whether the child is
+ *    running a goal Kabmo must keep feeding, and whether a plan is parked
+ *    waiting for a human.
+ *
+ * The mirror is fed by two frames, and they cover different halves:
+ *
+ *  - omp's own `goal_updated` session event, which is authoritative for the
+ *    goal: whatever Kabmo last asked for, the frame reports what the
+ *    child actually did;
+ *  - Kabmo's mode extension and its `KABMO_*` notice markers, which are the ONLY
+ *    live word on PLAN mode (omp emits no plan event at all) and the only place
+ *    a goal RECORD — objective, status, continuation verdict — is carried.
+ *
+ * The second feed is what makes a session readable before its transcript
+ * exists: omp writes the JSONL at the first assistant message, so for the first
+ * seconds-to-minutes of a new chat the file-based read has nothing while the
+ * child is demonstrably in the mode the user just picked. See
+ * `liveModeSelection`.
+ */
+
+import type { AgentEvent } from '@/server/lib/omp/rpc/constants';
+import {
+  type GoalContinuation,
+  type GoalRecord,
+} from '@/shared/lib/omp/mode/types';
+import { isModeMarker } from '@/shared/lib/omp/mode/constants';
+import { continuationFromMarker, goalEnabledFromMarker, goalRecordFromMarker, type ParsedMarker } from '@/shared/lib/omp/mode/markers';
+import { isGoalStatus } from '@/shared/lib/omp/mode/status';
+import type { GoalStatus } from '@/shared/lib/omp/mode/types';
+
+/** Statuses that mean the goal is still being pursued. `budget-limited` counts:
+ *  it is a resumable state omp returns to `active` when the budget is raised. */
+const LIVE_STATUSES = new Set(['active', 'budget-limited']);
+
+export class ModeMirror {
+  /** True only while a goal is live. A paused or completed goal keeps its
+   *  record in the transcript but is not work in progress. */
+  goalEnabled = false;
+  goalStatus: GoalStatus | undefined;
+  /** The plan flag the extension last reported. `undefined` means no marker has
+   *  been seen — NOT "off", which is what keeps the spawn environment usable as
+   *  the fallback. */
+  planEnabled: boolean | undefined;
+  /** The goal record the last `CHAMBER_GOAL_STATE` carried, for the window in
+   *  which there is no transcript to read it back from. */
+  goalRecord: GoalRecord | null = null;
+  /** The auto-continuation verdict the loop last reported, and the ceiling that
+   *  rode with it. */
+  goalContinuation: GoalContinuation | null = null;
+  goalMaxTurns: number | null = null;
+
+  /** Apply one `goal_updated` frame. */
+  observe(event: AgentEvent): void {
+    const state = event.state as { enabled?: boolean; goal?: { status?: unknown } } | undefined;
+    const goal = event.goal as { status?: unknown } | null | undefined;
+    const status = state?.goal?.status ?? goal?.status;
+    // A status this build does not know is not a status: storing it would make
+    // every downstream `isGoalOpen` call a cast, and an unknown value must read
+    // as "no goal" rather than as an open one.
+    this.goalStatus = isGoalStatus(status) ? status : undefined;
+    this.goalEnabled =
+      state?.enabled === true && this.goalStatus !== undefined && LIVE_STATUSES.has(this.goalStatus);
+  }
+
+  /**
+   * Apply one extension notice marker.
+   *
+   * Markers only, never a `KABMO_MODE_ERROR` or a plan proposal: those are
+   * refusals and review state, not the selection. A marker for the other scope
+   * leaves this one alone — the two toggles are independent, and a plan
+   * transition that blanked the goal record would make a live goal disappear
+   * from a reattaching client.
+   */
+  observeMarker(marker: ParsedMarker): void {
+    if (isModeMarker(marker.marker, 'planStateMarker')) {
+      this.planEnabled = marker.payload.enabled === true;
+      return;
+    }
+    if (!isModeMarker(marker.marker, 'goalStateMarker')) return;
+    const record = goalRecordFromMarker(marker.payload);
+    this.goalRecord = record;
+    this.goalStatus = record && isGoalStatus(record.status) ? record.status : undefined;
+    // The same rule `observe` applies, from the payload that carries the record
+    // rather than from a `goal_updated` frame — so both feeds agree on what
+    // "live" means instead of each having its own spelling.
+    this.goalEnabled =
+      goalEnabledFromMarker(marker.payload) &&
+      this.goalStatus !== undefined &&
+      LIVE_STATUSES.has(this.goalStatus);
+    if ('continuation' in marker.payload) {
+      this.goalContinuation =
+        marker.payload.continuation === null ? null : continuationFromMarker(marker.payload.continuation);
+    }
+    const ceiling = marker.payload.maxTurns;
+    if (typeof ceiling === 'number' && Number.isInteger(ceiling) && ceiling > 0) this.goalMaxTurns = ceiling;
+  }
+}

package/src/server/lib/omp/rpc/peer-proxy.server.test.ts

@@ -0,0 +1,107 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Peer forwarding: relaying a command to the instance that owns a session.
+ *
+ * The load-bearing rules:
+ *   - a relayed request carries the hop header, and a request that already has
+ *     it is never relayed again (two instances that disagree about ownership
+ *     must not bounce a request forever);
+ *   - the method, path and query travel unchanged, and a body the caller has
+ *     already parsed is re-serialized rather than re-read (the body can only be
+ *     consumed once);
+ *   - an unreachable peer answers 502 with a code, never a thrown error, so the
+ *     route can fall back to the ownership refusal.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+
+import { forwardToPeer, isPeerRelayed, PEER_HOP_HEADER, peerRealtimeSocketUrl } from '@/server/lib/omp/rpc/peer-proxy.server';
+
+let originalFetch: typeof globalThis.fetch;
+let captured: { url: string; init: RequestInit } | null;
+
+beforeEach(() => {
+  captured = null;
+  originalFetch = globalThis.fetch;
+});
+
+afterEach(() => {
+  globalThis.fetch = originalFetch;
+});
+
+function stubFetch(responder: (url: string, init: RequestInit) => Response | Promise<Response>): void {
+  globalThis.fetch = (async (input: RequestInfo | URL, init?: RequestInit) => {
+    const url = typeof input === 'string' ? input : input instanceof URL ? input.toString() : input.url;
+    captured = { url, init: init ?? {} };
+    return responder(url, init ?? {});
+  }) as typeof globalThis.fetch;
+}
+
+describe('isPeerRelayed', () => {
+  test('a request carrying the hop header has already been relayed', () => {
+    const relayed = new Request('http://127.0.0.1:3001/api/agent/s1', { headers: { [PEER_HOP_HEADER]: '1' } });
+    expect(isPeerRelayed(relayed)).toBe(true);
+  });
+
+  test('a fresh request has not', () => {
+    expect(isPeerRelayed(new Request('http://127.0.0.1:3001/api/agent/s1'))).toBe(false);
+  });
+});
+
+describe('forwardToPeer', () => {
+  test('preserves method, path and query, and adds the hop header', async () => {
+    stubFetch(() => Response.json({ success: true }));
+    const request = new Request('http://127.0.0.1:3001/api/agent/s1?x=1', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ type: 'prompt', message: 'hi' }),
+    });
+    const response = await forwardToPeer(request, 'http://127.0.0.1:3195', { type: 'prompt', message: 'hi' });
+    expect(captured?.url).toBe('http://127.0.0.1:3195/api/agent/s1?x=1');
+    expect(captured?.init.method).toBe('POST');
+    expect((captured?.init.headers as Headers).get(PEER_HOP_HEADER)).toBe('1');
+    // The caller's parsed body is what travels, not a re-read of the request.
+    expect(captured?.init.body).toBe(JSON.stringify({ type: 'prompt', message: 'hi' }));
+    expect(await response.json()).toEqual({ success: true });
+  });
+
+  test('a GET relays no body', async () => {
+    stubFetch(() => Response.json({ running: true }));
+    await forwardToPeer(new Request('http://127.0.0.1:3001/api/agent/s1'), 'http://127.0.0.1:3195');
+    expect(captured?.init.method).toBe('GET');
+    expect(captured?.init.body).toBeUndefined();
+  });
+
+  test('an unreachable peer answers 502 with a code, never throws', async () => {
+    stubFetch(() => {
+      throw new Error('connect ECONNREFUSED');
+    });
+    const response = await forwardToPeer(new Request('http://127.0.0.1:3001/api/agent/s1'), 'http://127.0.0.1:3195');
+    expect(response.status).toBe(502);
+    const body = (await response.json()) as { code: string };
+    expect(body.code).toBe('peer_unreachable');
+  });
+
+  test("the peer's own error status is passed through unchanged", async () => {
+    stubFetch(() => Response.json({ error: 'nope' }, { status: 409 }));
+    const response = await forwardToPeer(new Request('http://127.0.0.1:3001/api/agent/s1'), 'http://127.0.0.1:3195');
+    expect(response.status).toBe(409);
+  });
+});
+
+describe('peerRealtimeSocketUrl', () => {
+  test('points at the owner unified socket, and carries no session id', () => {
+    // The relay subscribes the session topic ON that socket. The per-session
+    // `/api/agent/<id>/ws` path it used to build was deleted with the realtime
+    // migration, so this pins the path a route actually answers.
+    expect(peerRealtimeSocketUrl('http://127.0.0.1:3195')).toBe('ws://127.0.0.1:3195/api/realtime/ws');
+  });
+
+  test('rewrites https to wss', () => {
+    expect(peerRealtimeSocketUrl('https://127.0.0.1:3195')).toBe('wss://127.0.0.1:3195/api/realtime/ws');
+  });
+});

package/src/server/lib/omp/rpc/peer-proxy.server.ts

@@ -0,0 +1,150 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Peer forwarding: when a session is owned by ANOTHER Kabmo instance, serve
+ * the request from that instance instead of starting a second omp writer.
+ *
+ * ## Why forward instead of redirect
+ *
+ * The ownership guard (ownership.server.ts) refuses to resume a session another
+ * process owns, because omp moves the second writer to a sibling file
+ * (`open-elsewhere`) — the duplicate sidebar rows and split conversations this
+ * whole change exists to prevent. Redirecting the tab to the owner works, but
+ * it moves the user to a different port mid-conversation.
+ *
+ * Forwarding keeps the client on whichever instance it opened: every
+ * `/api/agent/:sessionId*` request for a peer-owned session is relayed to the
+ * owning instance, which runs it against the ONE omp child it already has. Both
+ * instances share a database and an agent dir, so the owner is authoritative
+ * and no state needs reconciling.
+ *
+ * ## Loop safety
+ *
+ * A relayed request carries {@link PEER_HOP_HEADER}. A request that already has
+ * it is never forwarded again: if two instances disagree about ownership (a
+ * stale record, a lease released between the two checks), the second hop
+ * answers with the ownership refusal instead of bouncing the request forever.
+ *
+ * ## Failure
+ *
+ * An unreachable peer (crashed, port reused) is not an error the user should
+ * see as a hang: the caller falls back to the ownership refusal, and the client
+ * still has the redirect path.
+ */
+
+import { resolveSessionOwnership } from '@/server/lib/omp/session/ownership.server';
+
+/** Marks a request already relayed once, so a peer never forwards it again. */
+export const PEER_HOP_HEADER = 'x-kabmo-peer-hop';
+
+/** How long a relayed command may take before it is treated as unreachable. */
+const PEER_TIMEOUT_MS = 120_000;
+
+/**
+ * Base URL of the instance owning `sessionId`, or null when it is free, owned
+ * by this process, or owned by something Kabmo cannot place (an `omp` CLI
+ * run has no instance record and therefore no port to relay to).
+ *
+ * The record's `host` is the bind address (`0.0.0.0` for a default install),
+ * which is not dialable: a peer on this machine is always reached over
+ * loopback, and the port is what distinguishes instances.
+ */
+export async function peerOriginForSession(sessionId: string): Promise<string | null> {
+  const owner = (await resolveSessionOwnership(sessionId))?.owner ?? null;
+  if (!owner) return null;
+  return `http://127.0.0.1:${owner.port}`;
+}
+
+/**
+ * Relay a request to the owning instance and return its response unchanged.
+ *
+ * The method, path and body travel as-is; only the hop header is added. A
+ * response is returned even when the peer answers an error — that error is the
+ * owner's own answer and is more truthful than anything this instance could
+ * invent.
+ *
+ * `parsedBody` is supplied when the caller has ALREADY consumed the request
+ * body (the command route parses it before deciding to relay). Reading the body
+ * twice is impossible, so the parsed value is re-serialized rather than cloned
+ * up front — the common path never pays for a clone it does not use.
+ */
+export async function forwardToPeer(
+  request: Request,
+  origin: string,
+  parsedBody?: unknown,
+): Promise<Response> {
+  const incoming = new URL(request.url);
+  const target = new URL(incoming.pathname + incoming.search, origin);
+  const headers = new Headers(request.headers);
+  headers.set(PEER_HOP_HEADER, '1');
+  const hasBody = request.method !== 'GET' && request.method !== 'HEAD';
+  let payload: BodyInit | undefined;
+  if (hasBody) {
+    if (parsedBody !== undefined) {
+      headers.set('content-type', 'application/json');
+      payload = JSON.stringify(parsedBody);
+    } else {
+      payload = await request.arrayBuffer();
+    }
+  }
+  try {
+    return await fetch(target, {
+      method: request.method,
+      headers,
+      body: payload,
+      signal: AbortSignal.timeout(PEER_TIMEOUT_MS),
+    });
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    return Response.json(
+      { error: `The instance running this session is not reachable (${reason}).`, code: 'peer_unreachable' },
+      { status: 502 },
+    );
+  }
+}
+
+/** True when this request was already relayed once and must not hop again. */
+export function isPeerRelayed(request: Request): boolean {
+  return request.headers.get(PEER_HOP_HEADER) === '1';
+}
+
+/**
+ * The owning instance's unified realtime socket — where a session's frames are
+ * relayed from.
+ *
+ * There is deliberately no per-session socket any more: the per-session agent
+ * WS/SSE routes were deleted with the realtime migration, and a relay pointed
+ * at `/api/agent/<id>/ws` dials a path no route answers, so it fails with no
+ * frame ever arriving. A session's frames now live on the `session:<id>` TOPIC
+ * of the owner's one socket, so the relay subscribes that topic there.
+ */
+export function peerRealtimeSocketUrl(origin: string): string {
+  return `${origin.replace(/^http/, 'ws')}/api/realtime/ws`;
+}
+
+/**
+ * The owner's own view of a session, for an instance that does not hold the
+ * child — the same payload `GET /api/agent/:id` answers with there.
+ *
+ * `null` when the owner cannot be reached or answers a non-JSON body: the caller
+ * keeps its local answer rather than blanking a subscriber's panel over a
+ * transient peer failure. The payload is otherwise UNVALIDATED — the caller
+ * narrows it, because this module must not depend on the route module that
+ * owns the shape.
+ */
+export async function fetchPeerSessionSnapshot(sessionId: string, origin: string): Promise<unknown> {
+  try {
+    const response = await fetch(new URL(`/api/agent/${encodeURIComponent(sessionId)}`, origin), {
+      headers: { [PEER_HOP_HEADER]: '1' },
+      signal: AbortSignal.timeout(PEER_TIMEOUT_MS),
+    });
+    if (!response.ok) return null;
+    return (await response.json()) as unknown;
+  } catch {
+    // Unreachable, timed out, or a body that is not JSON: a soft miss.
+    return null;
+  }
+}

package/src/server/lib/omp/rpc/pending-ui-dialogs.ts

@@ -0,0 +1,59 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Ask/approval dialogs an omp process is currently BLOCKED on.
+ *
+ * Every `extension_ui_request` with an answerable method (`select`, `confirm`,
+ * `input`, `editor`) parks its tool call until the matching
+ * `extension_ui_response` arrives, and omp never re-delivers the frame. A
+ * browser that reloads mid-dialog therefore has no way to learn the request id
+ * it must answer: the modal disappears, the agent stays blocked, and the run
+ * looks hung until the user stops it. Remembering the requests here — on the
+ * server, which outlives the client — lets a reattaching client replay them.
+ *
+ * Split from the session wrapper so rpc-manager.ts stays under the repo's
+ * per-file size ceiling.
+ */
+
+import { ANSWERABLE_UI_METHODS } from '@/server/lib/omp/rpc/constants';
+import type { RpcFrame } from '@/server/lib/omp/rpc/process';
+
+export class PendingUiDialogs {
+  // Insertion order is omp's arrival order, which is the order the user should
+  // answer them in — a Map preserves it.
+  private readonly requests = new Map<string, RpcFrame>();
+
+  /** Record an answerable request, or forget one omp withdrew (`cancel`).
+   *  Returns whether the pending set changed — a caller that republishes state
+   *  on every frame would otherwise republish for `notify`/`open_url` too. */
+  track(frame: RpcFrame): boolean {
+    if (frame.method === 'cancel') {
+      const targetId = typeof frame.targetId === 'string' ? frame.targetId : '';
+      return targetId ? this.requests.delete(targetId) : false;
+    }
+    const id = typeof frame.id === 'string' ? frame.id : '';
+    if (!id || typeof frame.method !== 'string' || ANSWERABLE_UI_METHODS[frame.method] !== true) return false;
+    // A repeat of the same id is not a change.
+    if (this.requests.has(id)) return false;
+    this.requests.set(id, frame);
+    return true;
+  }
+
+  /** Forget a request once its response is on the wire — omp will not raise it
+   *  again, so replaying it to a later client would only show a dead modal. */
+  resolve(id: string): boolean {
+    return this.requests.delete(id);
+  }
+
+  /** Still-blocking requests, oldest first. */
+  list(): RpcFrame[] {
+    return [...this.requests.values()];
+  }
+
+  clear(): void {
+    this.requests.clear();
+  }
+}

package/src/server/lib/omp/rpc/process-helpers.ts

@@ -0,0 +1,70 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type { resolveOmpBin } from '@/server/lib/omp/core/cli';
+
+export interface RpcResponseFrame {
+  type: 'response';
+  id?: string;
+  command: string;
+  success: boolean;
+  data?: unknown;
+  error?: string;
+  code?: string;
+}
+
+export type RpcFrame = { type: string; [key: string]: unknown };
+
+export class RpcCommandError extends Error {
+  readonly command: string;
+  readonly code?: string;
+
+  constructor(command: string, message: string, code?: string) {
+    super(message);
+    this.name = 'RpcCommandError';
+    this.command = command;
+    this.code = code;
+  }
+}
+export class RpcCommandTimeoutError extends Error {
+  readonly command: string;
+  readonly timeoutMs: number;
+
+  constructor(command: string, timeoutMs: number, message?: string) {
+    super(message ?? `RPC command ${command} timed out after ${timeoutMs}ms`);
+    this.name = 'RpcCommandTimeoutError';
+    this.command = command;
+    this.timeoutMs = timeoutMs;
+  }
+}
+
+export interface PendingCommand {
+  command: string;
+  resolve: (data: unknown) => void;
+  reject: (error: Error) => void;
+  timer?: NodeJS.Timeout;
+}
+
+export interface RpcProcessOptions {
+  /** Working directory for the agent (also passed as --cwd). */
+  cwd: string;
+  /** Extra CLI args appended after the base `--mode rpc-ui --cwd <cwd>`. */
+  extraArgs?: string[];
+  /** Environment overrides merged over Bun.env. Used by Kabmo's mode
+   *  extension (`KABMO_MODES`), which reads the persisted selection at
+   *  session start — the only channel available before the child's first
+   *  command. */
+  env?: Record<string, string>;
+  /** Called for every non-response frame (events, extension UI, subagent frames). */
+  onFrame?: (frame: RpcFrame) => void;
+  /** Called once when the child exits, after pending commands are rejected. */
+  onExit?: (info: { code: number | null; signal: NodeJS.Signals | null; stderrTail: string }) => void;
+  /** Injectable binary resolver for deterministic transport tests. */
+  dependencies?: {
+    resolveOmpBin?: typeof resolveOmpBin;
+  };
+}
+
+export const STDERR_TAIL_LIMIT = 8 * 1024;