ompchamber 0.3.0 → 0.4.0

package/src/server/lib/omp/rpc/subagent-liveness.ts

@@ -0,0 +1,100 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Liveness of a session's subagents, folded from the frames the wrapper already
+ * receives (`set_subagent_subscription` in AgentSessionWrapper.initialize).
+ *
+ * Every other "this session is working" flag on the wrapper (promptRunning /
+ * streaming / compacting / bashRunning) is blind to subagents: a parent turn
+ * can end — or a detached subagent outlive it — while subagents keep working,
+ * and a frame-silent subagent otherwise looks exactly like an idle session to
+ * the idle reaper. Used only for lifecycle decisions (idle reclaim, spawn-mode
+ * reconcile), never for the UI's running set.
+ *
+ * Identity mirrors the UI fold (`SubagentList`): frames carry an id, a
+ * lifecycle may also carry `index`, and progress frames may be id-less and are
+ * then matched by index — hence the index→key alias, so one subagent is never
+ * tracked under two keys (a leftover key would pin the session alive until it
+ * goes stale).
+ */
+
+import { parseSubagentLifecycle, parseSubagentProgress } from '@/shared/lib/omp/subagent/parse';
+import { isRecord } from '@/shared/lib/util/guards';
+import type { SubagentProgress } from '@/shared/types/omp/subagent';
+
+/** Statuses that end a subagent. Mirrors omp's own registry, which deletes an
+ *  entry the moment a non-`started` lifecycle arrives. */
+const TERMINAL_STATUS: Record<string, true> = { completed: true, failed: true, aborted: true };
+
+/** Progress frames arrive AgentProgress-shaped; some wrappers nest the snapshot. */
+function readProgress(payload: unknown): SubagentProgress | undefined {
+  const direct = parseSubagentProgress(payload);
+  if (!isRecord(payload) || !isRecord(payload.progress)) return direct;
+  const nested = parseSubagentProgress(payload.progress);
+  return nested ? { ...nested, id: nested.id ?? direct?.id, index: nested.index ?? direct?.index } : direct;
+}
+
+export class SubagentLiveness {
+  private readonly lastSeen = new Map<string, number>();
+  /** index → key, so an id-less progress frame lands on the entry its lifecycle
+   *  created instead of opening a second one. */
+  private readonly keyByIndex = new Map<number, string>();
+
+  /** Fold one `subagent_lifecycle|subagent_progress|subagent_event` frame. */
+  observe(frame: { type: string; payload?: unknown }, now: number): void {
+    if (frame.type === 'subagent_lifecycle') {
+      const entry = parseSubagentLifecycle(frame.payload);
+      if (!entry) return;
+      if (TERMINAL_STATUS[entry.status] === true) this.forget(entry.id);
+      else this.mark(entry.id, entry.index >= 0 ? entry.index : undefined, now);
+      return;
+    }
+
+    if (frame.type === 'subagent_progress') {
+      const progress = readProgress(frame.payload);
+      if (!progress) return;
+      const index = progress.index !== undefined && progress.index >= 0 ? progress.index : undefined;
+      const key = progress.id ?? (index !== undefined ? this.keyByIndex.get(index) ?? `idx:${index}` : undefined);
+      if (key === undefined) return;
+      if (progress.status !== undefined && TERMINAL_STATUS[progress.status] === true) this.forget(key);
+      else this.mark(key, index, now);
+      return;
+    }
+
+    if (frame.type === 'subagent_event') {
+      // An event proves *some* subagent is working but carries no identity of
+      // its own: refresh what is already tracked, and never invent an entry —
+      // an invented one could never be cleared by a terminal frame.
+      for (const key of this.lastSeen.keys()) this.lastSeen.set(key, now);
+    }
+  }
+
+  /** Live subagents as of `now`. Entries silent past `staleMs` are dropped
+   *  first: a terminal frame lost to a protocol hiccup must not pin a session
+   *  alive forever (the price of the window is at most one idle omp process). */
+  liveCount(now: number, staleMs: number): number {
+    for (const [key, lastSeen] of this.lastSeen) {
+      if (now - lastSeen > staleMs) this.forget(key);
+    }
+    return this.lastSeen.size;
+  }
+
+  private mark(key: string, index: number | undefined, now: number): void {
+    this.lastSeen.set(key, now);
+    if (index === undefined) return;
+    // A lifecycle naming the same index supersedes the synthetic key an earlier
+    // id-less progress frame created for it.
+    if (key !== `idx:${index}`) this.lastSeen.delete(`idx:${index}`);
+    this.keyByIndex.set(index, key);
+  }
+
+  private forget(key: string): void {
+    this.lastSeen.delete(key);
+    for (const [index, alias] of this.keyByIndex) {
+      if (alias === key) this.keyByIndex.delete(index);
+    }
+  }
+}

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

@@ -0,0 +1,112 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { afterAll, describe, expect, test } from 'bun:test';
+import fs from 'fs';
+import { join } from 'path';
+
+import { loadSessionMessages } from '@/server/lib/omp/session/messages';
+import { isNoticeRow } from '@/shared/lib/chat/notice-row';
+
+const tempDirs: string[] = [];
+
+/** Write a session JSONL whose lines are exactly the given records, in order. */
+async function writeSession(lines: unknown[]): Promise<string> {
+  const dir = await fs.promises.mkdtemp('omp-messages-');
+  tempDirs.push(dir);
+  const file = join(dir, 'session.jsonl');
+  await Bun.write(file, `${lines.map((line) => JSON.stringify(line)).join('\n')}\n`);
+  return file;
+}
+
+afterAll(() => {
+  for (const dir of tempDirs) fs.rmSync(dir, { recursive: true, force: true });
+});
+
+const at = (second: number) => `2026-09-21T03:00:${String(second).padStart(2, '0')}.000Z`;
+
+/** omp records harness notices as their own `custom_message` entry. */
+const notice = (id: string, text: string, second: number) => ({
+  type: 'custom_message',
+  id,
+  customType: 'ultrathink-notice',
+  timestamp: at(second),
+  content: [{ type: 'text', text: `<system-notice>${text}</system-notice>` }],
+});
+
+const turn = (id: string, role: 'user' | 'assistant', text: string, second: number) => ({
+  type: 'message',
+  id,
+  timestamp: at(second),
+  message: { role, content: [{ type: 'text', text }] },
+});
+
+describe('loadSessionMessages ordering', () => {
+  test('returns entries in file order, leaving a notice before its following user turn', async () => {
+    const file = await writeSession([
+      notice('n1', 'Background job finished.', 0),
+      turn('u1', 'user', 'halo', 1),
+      turn('a1', 'assistant', 'hai', 2),
+    ]);
+
+    const messages = await loadSessionMessages(file);
+
+    expect(messages.map((m) => m.id)).toEqual(['n1', 'u1', 'a1']);
+    expect(messages[0].notice).toBe('Background job finished.');
+    expect(messages[1]).toMatchObject({ role: 'user', content: 'halo' });
+    expect(messages[2]).toMatchObject({ role: 'ai', content: 'hai' });
+  });
+
+  test('preserves a notice that sits between two turns', async () => {
+    const file = await writeSession([
+      turn('u1', 'user', 'satu', 0),
+      turn('a1', 'assistant', 'dua', 1),
+      notice('n1', 'Job done.', 2),
+      turn('u2', 'user', 'tiga', 3),
+      turn('a2', 'assistant', 'empat', 4),
+    ]);
+
+    expect((await loadSessionMessages(file)).map((m) => m.id)).toEqual(['u1', 'a1', 'n1', 'u2', 'a2']);
+  });
+});
+
+describe('loadSessionMessages reminder classification', () => {
+  const blocks = (id: string, texts: string[], second: number) => ({
+    type: 'message',
+    id,
+    timestamp: at(second),
+    message: { role: 'assistant', content: texts.map((text) => ({ type: 'text', text })), usage: { input: 1, output: 2 } },
+  });
+
+  test('prose that quotes the tag stays the answer', async () => {
+    const prose = 'Chip shows the peeled tag (`system-reminder`).\n\nExample: <system-reminder>…</system-reminder> then free text.';
+    const file = await writeSession([blocks('a1', [prose], 0)]);
+
+    const [message] = await loadSessionMessages(file);
+
+    expect(message.notice).toBeUndefined();
+    expect(message.content).toBe(prose);
+    expect(isNoticeRow(message)).toBe(false);
+  });
+
+  test('a text block that IS the reminder envelope becomes a notice', async () => {
+    const file = await writeSession([blocks('a1', ['<system-reminder>\n10 todo items still open.\n</system-reminder>'], 0)]);
+
+    const [message] = await loadSessionMessages(file);
+
+    expect(message.content).toBe('');
+    expect(message.notice).toBe('<system-reminder>\n10 todo items still open.\n</system-reminder>');
+    expect(isNoticeRow(message)).toBe(true);
+  });
+
+  test('an envelope and prose in one turn split between notice and content', async () => {
+    const file = await writeSession([blocks('a1', ['Jawaban akhir.', '<system-reminder>2 items open</system-reminder>'], 0)]);
+
+    const [message] = await loadSessionMessages(file);
+
+    expect(message.content).toBe('Jawaban akhir.');
+    expect(message.notice).toBe('<system-reminder>2 items open</system-reminder>');
+  });
+});

package/src/server/lib/omp/session/messages.ts

@@ -21,7 +21,6 @@
  */
 
 import { parseJsonlLenient } from '@/shared/lib/omp/session/jsonl';
-import { normalizeNoticePositions } from '@/shared/lib/chat/order';
 import { normalizeThinkingLevel } from '@/shared/lib/models/thinking-levels';
 import type { ChatMessageData } from '@/shared/types/chat';
 import { collectToolOutputs, noticeFromCustomMessage, toChatMessage, type SequenceState } from '@/shared/lib/omp/session/messages-map';
@@ -53,9 +52,11 @@ function skillUserMessageFromRecord(record: Record<string, unknown>): ChatMessag
 }
 
 /**
- * Load a session file and return the chat timeline in chronological order.
- * Assistant messages carry thinking accordion + tool calls (with outputs
- * paired from their toolResult entries); tool plumbing rows are folded in.
+ * Load a session file and return the chat timeline in **file order** — the
+ * order omp wrote the entries, which is the session's chronology. The API
+ * response is a faithful projection of the JSONL: nothing here reorders rows,
+ * and no display-side reordering is applied anywhere either (a notice row
+ * renders exactly where omp wrote it).
  */
 export async function loadSessionMessages(filePath: string): Promise<ChatMessageData[]> {
   try {
@@ -120,7 +121,7 @@ export async function loadSessionMessages(filePath: string): Promise<ChatMessage
     }
     state.messages.push(mapped);
   }
-  return normalizeNoticePositions(state.messages);
+  return state.messages;
 }
 
 /** Derive the display title from the JSONL header/title slot (cheap read). */

package/src/server/routes/agent/command.ts

@@ -1,7 +1,7 @@
 import { json } from '@/server/lib/remix-compat';
 import type { ActionFunctionArgs, LoaderFunctionArgs } from '@/server/lib/remix-compat';
 import { resolveSessionPathOr404 } from '@/server/lib/omp/session/locator';
-import { WebRpcError, getRpcSession, resolveSpawnCwd, startRpcSession } from '@/server/lib/omp/rpc/manager';
+import { WebRpcError, getRpcSession, resolveSpawnCwd, startRpcSession, type AgentSessionWrapper } from '@/server/lib/omp/rpc/manager';
 import { getSpawnApprovalMode, reconcileSpawnApprovalMode } from '@/server/lib/omp/rpc/session-registry';
 import { isApprovalMode } from '@/shared/lib/omp/config/access-mode';
 import { loadPersistedAccessMode } from '@/shared/lib/omp/config/access-mode.server';
@@ -53,29 +53,47 @@ export async function sendCommand({ params, request }: ActionFunctionArgs) {
   }
 }
 
+/** RPC-free view of a busy session. `state` carries only the two flags the
+ *  attach probe reads; the full snapshot resumes once the turn settles. */
+function busySessionPayload(session: AgentSessionWrapper) {
+  return {
+    running: true,
+    busy: true,
+    state: { isStreaming: session.streaming, isPromptRunning: session.promptRunning },
+    pendingUiRequests: session.getPendingUiDialogs(),
+  };
+}
+
 // GET /api/agent/:sessionId — current agent state (running set + live state).
 export async function getAgentState({ params }: LoaderFunctionArgs) {
   const { sessionId } = params;
   if (!sessionId) return json({ error: 'session id is required' }, { status: 400 });
 
+  const session = getRpcSession(sessionId);
+  if (!session || !session.isAlive()) {
+    return json({ running: false });
+  }
+
+  // A busy session answers from local flags: its `get_state` would queue behind
+  // the running turn (omp runs RPC handlers one at a time), and a timeout there
+  // is no reason to reset a session that is demonstrably working — subagents
+  // included. These flags are all the client needs to reattach its stream.
+  if (session.isBusy()) return json(busySessionPayload(session));
+
   try {
-    const session = getRpcSession(sessionId);
-    if (!session || !session.isAlive()) {
-      return json({ running: false });
+    const state = await session.send({ type: 'get_state' });
+    // Dialogs omp is still blocked on: a client that reloaded mid-ask has no
+    // other way to learn the request id it must answer, and omp never
+    // re-emits the frame.
+    return json({ running: true, state, pendingUiRequests: session.getPendingUiDialogs() });
+  } catch (error) {
+    if (error instanceof WebRpcError && error.code === 'session_unresponsive') {
+      return json({ running: false, recovered: true });
     }
-    try {
-      const state = await session.send({ type: 'get_state' });
-      // Dialogs omp is still blocked on: a client that reloaded mid-ask has no
-      // other way to learn the request id it must answer, and omp never
-      // re-emits the frame.
-      return json({ running: true, state, pendingUiRequests: session.getPendingUiDialogs() });
-    } catch (error) {
-      if (error instanceof WebRpcError && error.code === 'session_unresponsive') {
-        return json({ running: false, recovered: true });
-      }
-      throw error;
+    // A turn started between the check above and the RPC: report busy, not dead.
+    if (error instanceof WebRpcError && error.code === 'session_busy') {
+      return json(busySessionPayload(session));
     }
-  } catch (error) {
     return rpcErrorResponse(error);
   }
 }

package/src/server/routes/fs/read.ts

@@ -11,6 +11,7 @@ import fs from 'fs';
 import path from 'path';
 import { isMockMode } from '@/server/mock.server';
 import { getDefaultFsRoot, resolveRoot, resolveWithinRoot } from '@/server/lib/fs/root';
+import { collectIgnoredPaths } from '@/server/lib/fs/git-ignore';
 
 /**
  * GET /api/fs/browse?path=<abs> — list subdirectories of a folder for the
@@ -92,19 +93,26 @@ const NOISE_DIRS: Record<string, true> = { node_modules: true, '.git': true, dis
 // fetch them on demand — directories are NOT recursed here (keeps the initial
 // payload tiny for deep workspaces). Hidden (dot-prefixed) entries are part of
 // the listing: lazy children keep `.github`, `.config`, `.env`, … cheap.
+// Entries git would refuse to track carry `ignored: true` so the panel can dim
+// them; that is one `git check-ignore` per listing, never one per entry.
 async function listEntries(dirPath: string, rootPath: string): Promise<any[]> {
-  const entries = (await fs.promises.readdir(dirPath))
-    .filter(child => !NOISE_DIRS[child]);
+  const listed = (await fs.promises.readdir(dirPath))
+    .filter(child => !NOISE_DIRS[child])
+    .map(child => {
+      const full = path.join(dirPath, child);
+      return { child, full, rel: path.relative(rootPath, full) };
+    });
 
-  const mapped = await Promise.all(entries.map(async child => {
-    const full = path.join(dirPath, child);
+  const ignored = await collectIgnoredPaths(rootPath, listed.map(entry => entry.rel));
+
+  const mapped = await Promise.all(listed.map(async ({ child, full, rel }) => {
     try {
       const st = await Bun.file(full).stat();
-      const rel = path.relative(rootPath, full);
+      const isIgnored = ignored.has(rel);
       if (st.isDirectory()) {
-        return { id: rel, name: child, type: 'folder', path: rel, children: null, is_expanded: 0 };
+        return { id: rel, name: child, type: 'folder', path: rel, children: null, is_expanded: 0, ignored: isIgnored };
       }
-      return { id: rel, name: child, type: 'file', path: rel };
+      return { id: rel, name: child, type: 'file', path: rel, ignored: isIgnored };
     } catch {
       return null; // unreadable entry / broken symlink — skip
     }

package/src/shared/lib/chat/notice-row.test.ts

@@ -0,0 +1,89 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, expect, test } from 'bun:test';
+
+import {
+  isNoticeRow,
+  messageAnswerText,
+  noticeIsAssistantText,
+  reminderPartIndex,
+} from '@/shared/lib/chat/notice-row';
+import type { ChatMessageData } from '@/shared/types';
+
+const row = (over: Partial<ChatMessageData>): ChatMessageData => ({
+  id: 'n1',
+  role: 'ai',
+  content: '',
+  ...over,
+});
+
+const answer = { model: 'deepseek-v4', usage: { totalTokens: 150_640 }, durationMs: 5_574 };
+
+describe('reminderPartIndex', () => {
+  test('finds a text block that is a reminder envelope', () => {
+    expect(reminderPartIndex(['<system-reminder>\n10 todos open\n</system-reminder>'])).toBe(0);
+  });
+
+  test('ignores a tag quoted inside prose', () => {
+    expect(reminderPartIndex(['Chip shows the peeled tag (`system-reminder`).'])).toBeUndefined();
+    expect(reminderPartIndex(['Example: <system-reminder>…</system-reminder> then free text'])).toBeUndefined();
+    expect(
+      reminderPartIndex(['A wrapper is `<a>1</a>`; see <system-reminder> handling below']),
+    ).toBeUndefined();
+  });
+
+  test('ignores an unclosed or mismatched tag pair', () => {
+    expect(reminderPartIndex(['<system-reminder>\nno closing tag'])).toBeUndefined();
+    expect(reminderPartIndex(['<system-reminder><b>10 todos</system-reminder>'])).toBeUndefined();
+  });
+
+  test('picks the envelope out of a multi-block turn', () => {
+    expect(reminderPartIndex(['prose first', '<system-reminder>note</system-reminder>'])).toBe(1);
+  });
+});
+
+describe('notice row classification', () => {
+  test('a bare notice row is a notice card', () => {
+    const notice = row({ notice: 'Late LSP diagnostics arrived after the edit returned.' });
+    expect(noticeIsAssistantText(notice)).toBe(false);
+    expect(isNoticeRow(notice)).toBe(true);
+    expect(messageAnswerText(notice)).toBe('');
+  });
+
+  test('a notice row that kept the turn metadata is the answer', () => {
+    const text = 'Implementasi selesai.\n\n## Aturan';
+    const diverted = row({ notice: text, ...answer });
+    expect(noticeIsAssistantText(diverted)).toBe(true);
+    expect(isNoticeRow(diverted)).toBe(false);
+    expect(messageAnswerText(diverted)).toBe(text);
+  });
+
+  test('a wrapped reminder stays a notice card even with turn metadata', () => {
+    const reminder = row({ notice: '<system-reminder>10 todo items still open.</system-reminder>', ...answer });
+    expect(noticeIsAssistantText(reminder)).toBe(false);
+    expect(isNoticeRow(reminder)).toBe(true);
+  });
+
+  test('a task result stays a notice card', () => {
+    const task = row({ notice: '<task-result id="Job" status="completed">done</task-result>', ...answer });
+    expect(isNoticeRow(task)).toBe(true);
+  });
+
+  test('the live thinking-level stamp alone does not make a notice an answer', () => {
+    expect(isNoticeRow(row({ notice: 'Job done.', thinkingLevel: 'high' }))).toBe(true);
+  });
+
+  test('an ordinary answer row is unaffected', () => {
+    const plain = row({ content: 'Halo', ...answer });
+    expect(isNoticeRow(plain)).toBe(false);
+    expect(messageAnswerText(plain)).toBe('Halo');
+  });
+
+  test('an empty notice is not a notice row', () => {
+    expect(isNoticeRow(row({ notice: '   ' }))).toBe(false);
+    expect(isNoticeRow(row({}))).toBe(false);
+  });
+});

package/src/shared/lib/chat/notice-row.ts

@@ -0,0 +1,78 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * `notice` rows — and the one case where the field carries the ANSWER.
+ *
+ * A real notice row holds nothing but the notice: omp writes harness reminders,
+ * task results and late diagnostics as their own entry, so those rows have no
+ * model, no usage and no thinking. When the assistant's answer itself ends up
+ * in `notice` (omp diverted the turn's text block), the row keeps the turn's
+ * own metadata — model/provider/usage/duration/thinking/toolCalls — and is
+ * therefore an answer that must render as text, never as a System Notice card.
+ *
+ * The decision lives here once so every consumer agrees: the timeline row
+ * (`MessageItem`), the boundary rules of the run footer, and the live-stream
+ * callbacks.
+ */
+
+import type { ChatMessageData } from '@/shared/types';
+import { isReminderTag, unwrapXmlEnvelope } from '@/shared/lib/chat/xml-envelope';
+
+/** Tag that identifies a notice payload rather than prose. A notice keeps its
+ *  wrapper — that tag is the field's identity, and `SystemNotice` reads it to
+ *  pick "System Reminder" / "Task Result" over the generic card. */
+const NOTICE_TAG_RE = /<\/?(?:system-reminder|reminder|system-notice|task-result)\b/i;
+
+/** Fields only a real assistant turn carries. `thinkingLevel` is deliberately
+ *  absent: the live stream stamps it on every non-user frame, notice rows
+ *  included, so it proves nothing about the row being an answer. */
+const TURN_FIELDS = [
+  'model',
+  'provider',
+  'usage',
+  'durationMs',
+  'startedAt',
+  'completedAt',
+  'thinking',
+  'toolCalls',
+] as const;
+
+/**
+ * Index of the text part that IS a reminder envelope — `undefined` when the
+ * turn's prose merely quotes the tag (`see <system-reminder> handling` is
+ * content, not a wrapper). The envelope must open the part and enclose a whole
+ * element, so both statuses of a reminder turn are distinguishable before
+ * anything is moved into `notice`.
+ */
+export function reminderPartIndex(parts: string[]): number | undefined {
+  const index = parts.findIndex((part) => {
+    const envelope = unwrapXmlEnvelope(part);
+    return envelope !== undefined && isReminderTag(envelope.tag);
+  });
+  return index === -1 ? undefined : index;
+}
+
+/** True when the row's `notice` is the assistant answer omp diverted there. */
+export function noticeIsAssistantText(
+  msg: ChatMessageData | null | undefined,
+): msg is ChatMessageData & { notice: string } {
+  if (typeof msg?.notice !== 'string' || !msg.notice.trim()) return false;
+  if (NOTICE_TAG_RE.test(msg.notice)) return false;
+  return TURN_FIELDS.some((field) => msg[field] !== undefined && msg[field] !== null);
+}
+
+/** True when the row renders as a notice card (a real notice, not an answer). */
+export function isNoticeRow(
+  msg: ChatMessageData | null | undefined,
+): msg is ChatMessageData & { notice: string } {
+  return typeof msg?.notice === 'string' && Boolean(msg.notice.trim()) && !noticeIsAssistantText(msg);
+}
+
+/** The row's answer text: `content`, or the notice when the answer landed there. */
+export function messageAnswerText(msg: ChatMessageData | null | undefined): string {
+  if (noticeIsAssistantText(msg)) return msg.notice;
+  return typeof msg?.content === 'string' ? msg.content : '';
+}

package/src/shared/lib/chat/omp/abort.ts

@@ -0,0 +1,41 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Stop-button escalation for a live session.
+ *
+ * `abort` is awaited server-side until the turn actually stops, so a session
+ * wedged on a subagent — or on a child that stopped answering — never replies
+ * to it and the Stop button would hang with it. If the abort request is still
+ * pending after the grace period it is cancelled here and the stop escalates to
+ * `force_reset`, which the server answers by destroying the session's omp child
+ * (and every subagent under it) instead of waiting for a clean stop.
+ */
+
+/** How long a stop may take before the process is reset instead. */
+const ABORT_GRACE_MS = 10_000;
+
+function postCommand(sessionId: string, body: Record<string, unknown>, signal?: AbortSignal): Promise<Response> {
+  return fetch(`/api/agent/${encodeURIComponent(sessionId)}`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(body),
+    ...(signal ? { signal } : {}),
+  });
+}
+
+/** Ask the session to stop, then reset its process if it does not stop in time.
+ *  Failures are swallowed: the event stream is the source of truth for state. */
+export async function stopAgentSession(sessionId: string): Promise<void> {
+  const grace = new AbortController();
+  const timer = setTimeout(() => grace.abort(), ABORT_GRACE_MS);
+  try {
+    const stopped = await postCommand(sessionId, { type: 'abort' }, grace.signal).then(() => true, () => false);
+    if (stopped) return;
+    await postCommand(sessionId, { type: 'force_reset' }).catch(() => null);
+  } finally {
+    clearTimeout(timer);
+  }
+}