@kabmo-labs/kabmo 0.0.0-stage → 0.1.0

package/src/shared/lib/omp/session/wait.test.ts

@@ -0,0 +1,167 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * `wait` result normalization and the clock it reports.
+ *
+ * The fixtures are the shapes omp actually sends (measured on 443 results in
+ * the author's session store): a blocking snapshot with running jobs, a
+ * settled snapshot with a completion, an interrupted wait with no jobs, a peer
+ * message that woke it, and the 30-minute cap's empty result. The empty result
+ * is the load-bearing one — it is a real ANSWER ("Wait limit reached"), and a
+ * reader that treated "no jobs" as "not a wait" drew the most interesting wait
+ * of all as a generic card.
+ *
+ * Pure, no mounting.
+ */
+
+import { describe, expect, test } from 'bun:test';
+import {
+  formatWaitClock,
+  WAIT_MAX_MS,
+  waitHitLimit,
+  waitCounts,
+  waitJobSpanMs,
+  waitSummaryLine,
+  waitViewOf,
+} from '@/shared/lib/omp/session/wait';
+
+const BLOCKING = {
+  op: 'wait',
+  meta: { source: { type: 'report', value: 'background jobs snapshot' } },
+  jobs: [
+    { id: 'bg_1', type: 'bash', status: 'running', label: 'bun run e2e.ts', durationMs: 41_500 },
+    { id: 'bg_2', type: 'task', status: 'running', label: 'audit', durationMs: 12_000, completionPercent: 40, resolvedModel: 'deepseek-v4-1-flash' },
+  ],
+};
+
+const SETTLED = {
+  op: 'wait',
+  jobs: [
+    { id: 'bg_8', type: 'bash', status: 'completed', label: 'restart loop', durationMs: 126_589, exitCode: 0 },
+  ],
+};
+
+describe('waitViewOf', () => {
+  test('reads a blocking snapshot with its jobs', () => {
+    const view = waitViewOf({ details: BLOCKING });
+    expect(view?.op).toBe('wait');
+    expect(view?.jobs).toHaveLength(2);
+    expect(view?.jobs[0]).toMatchObject({ id: 'bg_1', status: 'running', durationMs: 41_500 });
+    expect(view?.jobs[1]).toMatchObject({ completionPercent: 40, resolvedModel: 'deepseek-v4-1-flash' });
+  });
+
+  test('an empty job list is an answer, not an absence', () => {
+    // `{op:'wait', jobs:[]}` is what omp returns when the 30-minute cap elapses
+    // and when a SERVICE rather than a job woke the call.
+    const view = waitViewOf({ details: { op: 'wait', jobs: [] } });
+    expect(view?.jobs).toEqual([]);
+    expect(view?.interrupted).toBe(false);
+  });
+
+  test('reads an interrupted wait', () => {
+    const view = waitViewOf({ details: { op: 'wait', jobs: [], interrupted: true } });
+    expect(view?.interrupted).toBe(true);
+  });
+
+  test('reads the peer message that ended the wait', () => {
+    const view = waitViewOf({
+      details: { op: 'wait', from: 'main', waited: { from: 'Sleeper', to: 'main', body: 'done', ts: 1_791_000_000_000 } },
+    });
+    expect(view?.waited).toMatchObject({ from: 'Sleeper', body: 'done' });
+  });
+
+  test('does not claim a proc:// or hub listing', () => {
+    // Both carry `jobs`, and `procViewOf` already owns them. Reading them here
+    // would draw a process listing as a wait.
+    expect(waitViewOf({ details: { op: 'list', jobs: [{ id: 'bg_1' }] } })).toBeUndefined();
+    expect(waitViewOf({ details: { jobs: [{ id: 'bg_1' }] } })).toBeUndefined();
+    expect(waitViewOf({ details: { proc: { jobs: [{ id: 'bg_1' }] } } })).toBeUndefined();
+    expect(waitViewOf({})).toBeUndefined();
+  });
+});
+
+describe('waitJobSpanMs', () => {
+  test('reports the longest span a watched job reports', () => {
+    expect(waitJobSpanMs(waitViewOf({ details: BLOCKING })!)).toBe(41_500);
+  });
+
+  test('is undefined when no job reports a span', () => {
+    expect(waitJobSpanMs(waitViewOf({ details: { op: 'wait', jobs: [] } })!)).toBeUndefined();
+  });
+
+  test('is NOT the wait’s own clock — a job can predate the wait', () => {
+    // Measured on a real result: `bg_8` had run 126 s while the `wait` call that
+    // watched it took 20 s. The call's span is `tool.durationMs`; this helper
+    // only reports what the JOB says, and every caller prefers the call's own.
+    const view = waitViewOf({ details: { op: 'wait', jobs: [{ id: 'bg_8', status: 'completed', durationMs: 126_589 }] } })!;
+    expect(waitJobSpanMs(view)).toBe(126_589);
+  });
+});
+
+describe('waitCounts and the summary line', () => {
+  test('counts running, failed and cancelled separately', () => {
+    const view = waitViewOf({
+      details: {
+        op: 'wait',
+        jobs: [
+          { status: 'running' },
+          { status: 'failed' },
+          { status: 'cancelled' },
+          { status: 'completed' },
+        ],
+      },
+    })!;
+    expect(waitCounts(view)).toEqual({ total: 4, running: 1, failed: 1, cancelled: 1 });
+    expect(waitSummaryLine(view)).toBe('4 jobs · 1 running · 1 failed · 1 cancelled');
+  });
+
+  test('names a single job in the singular, and says when it was interrupted', () => {
+    expect(waitSummaryLine(waitViewOf({ details: SETTLED })!)).toBe('1 job');
+    expect(waitSummaryLine(waitViewOf({ details: { op: 'wait', jobs: [], interrupted: true } })!))
+      .toBe('interrupted');
+  });
+
+  test('an empty result has an empty line, not a fabricated count', () => {
+    expect(waitSummaryLine(waitViewOf({ details: { op: 'wait', jobs: [] } })!)).toBe('');
+  });
+});
+
+describe('the 30-minute cap', () => {
+  test('is the runtime’s own ceiling, not a client guess', () => {
+    // omp 18.12.0: `WAIT_MAX_MS = 30 * 60_000`, and the tool's schema is
+    // `type({})` — a caller cannot ask for a longer wait.
+    expect(WAIT_MAX_MS).toBe(1_800_000);
+    expect(formatWaitClock(WAIT_MAX_MS)).toBe('30:00');
+  });
+
+  test('the limit-reached result is recognised from its prose', () => {
+    // The result carries NO flag for this: `{op:'wait', jobs:[]}` is also what a
+    // service wake answers, so the sentence is the only discriminator.
+    const view = waitViewOf({ details: { op: 'wait', jobs: [] } })!;
+    expect(waitHitLimit(view, 'Wait limit reached; background work may still be running. Read proc:// for status.')).toBe(true);
+  });
+
+  test('a service wake and a normal settle are not the cap', () => {
+    const empty = waitViewOf({ details: { op: 'wait', jobs: [] } })!;
+    expect(waitHitLimit(empty, 'A service finished. Read proc:// for its status and output.')).toBe(false);
+    expect(waitHitLimit(empty, undefined)).toBe(false);
+    const settled = waitViewOf({ details: { op: 'wait', jobs: [{ id: 'bg_1', status: 'completed' }] } })!;
+    expect(waitHitLimit(settled, 'Wait limit reached')).toBe(false);
+  });
+});
+
+describe('formatWaitClock', () => {
+  test('keeps a fixed width per scale so the digits do not re-flow', () => {
+    expect(formatWaitClock(7_000)).toBe('0:07');
+    expect(formatWaitClock(83_000)).toBe('1:23');
+    expect(formatWaitClock(3_723_000)).toBe('1:02:03');
+  });
+
+  test('clamps a missing or negative span to zero', () => {
+    expect(formatWaitClock(-5)).toBe('0:00');
+    expect(formatWaitClock(Number.NaN)).toBe('0:00');
+  });
+});

package/src/shared/lib/omp/session/wait.ts

@@ -0,0 +1,267 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * oh-my-pi's `wait` tool — the call that BLOCKS until a background job or a
+ * project service the agent started settles.
+ *
+ * Its result is `CoordinationDetails` (measured on 443 real results across the
+ * author's session store):
+ *
+ *   { op:'wait', meta:{source:{type:'report',value:'background jobs snapshot'}},
+ *     jobs:[{id,type,status,label,durationMs,exitCode?,completionPercent?,
+ *            resolvedModel?,resolvedThinkingLevel?,resultText?,errorText?,
+ *            agentUrlId?}] }
+ *   { op:'wait', jobs:[], interrupted:true }            // cut short by a message
+ *   { op:'wait', from:<sender>, waited:{from,to,body,ts} }  // a peer message woke it
+ *   { op:'cancel', jobs:[...], cancelled:[{id,status}] }
+ *
+ * While the call is still blocking omp re-emits the SAME snapshot every 500 ms
+ * (`PROGRESS_INTERVAL_MS`) with a fresh `durationMs`, so the elapsed clock is
+ * the runtime's own measurement rather than a client-side guess.
+ *
+ * Pure and DOM-free: the live fold, the JSONL reload path, the card's fact
+ * chips and the panel all read the call through this one function.
+ */
+
+import { isRecord } from '@/shared/lib/util/guards';
+
+/** The operations that report through `CoordinationDetails`. */
+export type WaitOp = 'wait' | 'send' | 'cancel' | 'jobs';
+
+/** One background job (or subagent task) the wait watched. */
+export interface WaitJob {
+  id?: string;
+  /** `bash` | `task` | `eval`. */
+  type?: string;
+  status?: string;
+  label?: string;
+  /** Elapsed time AT SNAPSHOT TIME — omp computes `now - startTime` while the
+   *  job runs, so a live snapshot's value is the real elapsed clock. */
+  durationMs?: number;
+  exitCode?: number;
+  /** Self-estimated completion of a subagent task (0–100). */
+  completionPercent?: number;
+  resolvedModel?: string;
+  resolvedThinkingLevel?: string;
+  advisor?: boolean;
+  resultText?: string;
+  errorText?: string;
+  /** `agent://<id>` handle backing this job's artifacts. */
+  agentUrlId?: string;
+}
+
+/** A live subagent the session registered outside its job rows. */
+export interface WaitAgent {
+  id?: string;
+  parentId?: string;
+  activity?: string;
+  ageMs?: number;
+  live?: boolean;
+  acceptedAt?: number;
+}
+
+/** A peer (IRC) message that ended the wait. */
+export interface WaitMessage {
+  from?: string;
+  to?: string;
+  body?: string;
+  ts?: number;
+  replyTo?: string;
+}
+
+/** Everything one `wait` result says, in one shape. */
+export interface WaitView {
+  op: string;
+  jobs: WaitJob[];
+  agents: WaitAgent[];
+  /** The wait was cut short by steering, a peer message or a completion notice. */
+  interrupted: boolean;
+  cancelled: { id?: string; status?: string }[];
+  waited?: WaitMessage;
+  /** The message a `send` delivered to, for the `send` op. */
+  from?: string;
+  to?: string;
+}
+
+function asString(value: unknown): string | undefined {
+  return typeof value === 'string' && value.trim() ? value : undefined;
+}
+
+function asNumber(value: unknown): number | undefined {
+  return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+
+function asBoolean(value: unknown): boolean | undefined {
+  return typeof value === 'boolean' ? value : undefined;
+}
+
+function jobOf(value: unknown): WaitJob | undefined {
+  if (!isRecord(value)) return undefined;
+  return {
+    id: asString(value.id),
+    type: asString(value.type),
+    status: asString(value.status),
+    label: asString(value.label),
+    durationMs: asNumber(value.durationMs),
+    exitCode: asNumber(value.exitCode),
+    completionPercent: asNumber(value.completionPercent),
+    resolvedModel: asString(value.resolvedModel),
+    resolvedThinkingLevel: asString(value.resolvedThinkingLevel),
+    advisor: asBoolean(value.advisor),
+    resultText: asString(value.resultText),
+    errorText: asString(value.errorText),
+    agentUrlId: asString(value.agentUrlId),
+  };
+}
+
+function agentOf(value: unknown): WaitAgent | undefined {
+  if (!isRecord(value)) return undefined;
+  return {
+    id: asString(value.id),
+    parentId: asString(value.parentId),
+    activity: asString(value.activity),
+    ageMs: asNumber(value.ageMs),
+    live: asBoolean(value.live),
+    acceptedAt: asNumber(value.acceptedAt),
+  };
+}
+
+function messageOf(value: unknown): WaitMessage | undefined {
+  if (!isRecord(value)) return undefined;
+  return {
+    from: asString(value.from),
+    to: asString(value.to),
+    body: asString(value.body),
+    ts: asNumber(value.ts),
+    replyTo: asString(value.replyTo),
+  };
+}
+
+const WAIT_OPS: Record<string, true> = { wait: true, send: true };
+
+/**
+ * Normalize a `wait` result into `WaitView`, or undefined when the call is not
+ * one of the coordination operations.
+ *
+ * The `op` is what decides, and it is the ONLY reliable discriminator: `hub` and
+ * `proc://` results carry `jobs` too, and reading those here would draw a
+ * process listing as a wait. Only `wait` and `send` are claimed — `cancel` and
+ * `jobs` belong to `proc://` and are already read by `procViewOf`.
+ *
+ * An EMPTY job list is a real answer, not an absence: omp returns
+ * `{op:'wait', jobs:[]}` when the 30-minute cap elapses ("Wait limit reached;
+ * background work may still be running") and when a service rather than a job
+ * woke the call. Rejecting it drew the most interesting wait of all as a
+ * generic card.
+ */
+export function waitViewOf(tool: { details?: Record<string, unknown> }): WaitView | undefined {
+  const details = isRecord(tool.details) ? tool.details : undefined;
+  if (!details) return undefined;
+  const op = asString(details.op);
+  if (!op || !WAIT_OPS[op]) return undefined;
+
+  return {
+    op,
+    jobs: Array.isArray(details.jobs) ? (details.jobs.map(jobOf).filter(Boolean) as WaitJob[]) : [],
+    agents: Array.isArray(details.agents)
+      ? (details.agents.map(agentOf).filter(Boolean) as WaitAgent[])
+      : [],
+    interrupted: details.interrupted === true,
+    cancelled: Array.isArray(details.cancelled)
+      ? details.cancelled.filter(isRecord).map((row) => ({ id: asString(row.id), status: asString(row.status) }))
+      : [],
+    waited: messageOf(details.waited),
+    from: asString(details.from),
+    to: asString(details.to),
+  };
+}
+
+/**
+ * The longest span any WATCHED JOB reports — how long the job itself has run.
+ *
+ * This is NOT how long the wait has blocked: a job started before the wait did
+ * (measured on a real result: `bg_8` reported 126 s while the `wait` call that
+ * watched it took 20 s). It is only a fallback for a call whose own span is
+ * unknown, and the panel and the fact chips both prefer `tool.durationMs`.
+ */
+export function waitJobSpanMs(view: WaitView): number | undefined {
+  let longest: number | undefined;
+  for (const job of view.jobs) {
+    if (typeof job.durationMs !== 'number') continue;
+    if (longest === undefined || job.durationMs > longest) longest = job.durationMs;
+  }
+  return longest;
+}
+
+/** Running / settled counts, in the order a reader asks for them. */
+export function waitCounts(view: WaitView): { total: number; running: number; failed: number; cancelled: number } {
+  const counts = { total: view.jobs.length, running: 0, failed: 0, cancelled: 0 };
+  for (const job of view.jobs) {
+    if (job.status === 'running') counts.running++;
+    else if (job.status === 'failed') counts.failed++;
+    else if (job.status === 'cancelled') counts.cancelled++;
+  }
+  return counts;
+}
+
+/** `2 jobs · 1 running` — the line under the elapsed clock. */
+export function waitSummaryLine(view: WaitView): string {
+  const counts = waitCounts(view);
+  const noun = counts.total === 1 ? 'job' : 'jobs';
+  const parts: string[] = [];
+  if (counts.total > 0) parts.push(`${counts.total} ${noun}`);
+  if (counts.running > 0) parts.push(`${counts.running} running`);
+  if (counts.failed > 0) parts.push(`${counts.failed} failed`);
+  if (counts.cancelled > 0) parts.push(`${counts.cancelled} cancelled`);
+  if (view.agents.length > 0) {
+    parts.push(`${view.agents.length} agent${view.agents.length === 1 ? '' : 's'}`);
+  }
+  if (view.interrupted) parts.push('interrupted');
+  return parts.join(' · ');
+}
+
+/** `0:07` / `1:23` / `1:02:03` — a stopwatch, not a duration phrase.
+ *  A blocking call is watched second by second, so the digits must not
+ *  re-flow between ticks: the format keeps a fixed width per scale. */
+export function formatWaitClock(ms: number): string {
+  if (!Number.isFinite(ms) || ms < 0) return '0:00';
+  const totalSeconds = Math.floor(ms / 1000);
+  const seconds = String(totalSeconds % 60).padStart(2, '0');
+  const minutes = Math.floor(totalSeconds / 60) % 60;
+  const hours = Math.floor(totalSeconds / 3600);
+  return hours > 0 ? `${hours}:${String(minutes).padStart(2, '0')}:${seconds}` : `${minutes}:${seconds}`;
+}
+
+/**
+ * How long a single `wait` call may block, as omp enforces it.
+ *
+ * Hardcoded in omp's own tool (`WAIT_MAX_MS = 30 * 60_000`, verified on 18.12.0)
+ * and NOT a parameter: its schema is `type({})`, so the model cannot ask for
+ * more. When the timer wins the race, omp returns `{op:'wait', jobs:[]}` and the
+ * sentence "Wait limit reached; background work may still be running."
+ *
+ * The panel shows this because a blocking call is watched for minutes, and
+ * without the ceiling a reader has no way to tell "still waiting" from "waiting
+ * for something that can never arrive".
+ */
+export const WAIT_MAX_MS = 30 * 60_000;
+
+/** The sentence omp returns when its own cap fired. Matched on the text because
+ *  the result carries no flag for it — `jobs: []` is also what a service wake
+ *  answers, and those two must not be reported as the same event. */
+const WAIT_LIMIT_TEXT = /wait limit reached/i;
+
+/**
+ * Whether this result is the cap firing rather than a normal settle.
+ *
+ * Text is the only signal: measured across 443 real `wait` results, the
+ * limit-reached answer and a service wake both carry `{op:'wait', jobs:[]}`,
+ * and only the prose distinguishes them.
+ */
+export function waitHitLimit(view: WaitView, output: string | undefined): boolean {
+  if (view.jobs.length > 0) return false;
+  return WAIT_LIMIT_TEXT.test(output ?? '');
+}

package/src/shared/lib/omp/subagent/control.ts

@@ -0,0 +1,46 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Client calls for controlling ONE running subagent.
+ *
+ * The endpoints act on the session's live child, so a session this server does
+ * not manage answers 409 (`session_not_running`) — the roster row and the
+ * transcript banner both disable their buttons while the subagent is not
+ * running, so the refusal is a guard against a stale click rather than a normal
+ * outcome.
+ */
+
+/** Hard-kill one running subagent. Resolves false when it was not running. */
+export async function cancelSubagent(sessionId: string, subagentId: string): Promise<boolean> {
+  try {
+    const res = await fetch(
+      `/api/sessions/${encodeURIComponent(sessionId)}/subagents/${encodeURIComponent(subagentId)}/cancel`,
+      { method: 'POST' },
+    );
+    if (!res.ok) return false;
+    const body = (await res.json().catch(() => null)) as { data?: { cancelled?: unknown } } | null;
+    return body?.data?.cancelled === true;
+  } catch {
+    return false;
+  }
+}
+
+/** Send a message to one running subagent as its user. */
+export async function steerSubagent(sessionId: string, subagentId: string, message: string): Promise<boolean> {
+  try {
+    const res = await fetch(
+      `/api/sessions/${encodeURIComponent(sessionId)}/subagents/${encodeURIComponent(subagentId)}/steer`,
+      {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ message }),
+      },
+    );
+    return res.ok;
+  } catch {
+    return false;
+  }
+}

package/src/shared/lib/omp/subagent/history/client.ts

@@ -0,0 +1,76 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Client helpers for the on-disk subagent history route
+ * (`GET /api/sessions/:id/subagents`): wire normalization, history → roster
+ * mapping, and the compact row formatters.
+ */
+
+import { isRecord } from '@/shared/lib/util/guards';
+import type { SubagentHistoryEntry, SubagentInfo, SubagentProgress } from '@/shared/types/omp/subagent';
+
+/** Minimal wire guard — a malformed element must not become a roster row. */
+function isHistoryEntry(value: unknown): value is SubagentHistoryEntry {
+  return isRecord(value)
+    && typeof value.id === 'string' && value.id.length > 0
+    && typeof value.agent === 'string' && value.agent.length > 0
+    && typeof value.status === 'string'
+    && typeof value.index === 'number';
+}
+
+/** Fetch the recovered roster for a session. `null` = unavailable/failed. */
+export async function fetchSubagentHistory(sessionId: string): Promise<SubagentHistoryEntry[] | null> {
+  try {
+    const res = await fetch(`/api/sessions/${encodeURIComponent(sessionId)}/subagents`);
+    if (!res.ok) return null;
+    const body: unknown = await res.json().catch(() => null);
+    if (!isRecord(body)) return null;
+    const payload = isRecord(body.data) ? body.data : body;
+    if (!Array.isArray(payload.subagents)) return null;
+    return payload.subagents.filter(isHistoryEntry);
+  } catch {
+    return null;
+  }
+}
+
+/** Convert a recovered on-disk history entry into roster form. `lastUpdate: 0`
+ *  marks it infinitely old, so any live frame wins in `mergeSubagentRoster`. */
+export function historyEntryToSubagentInfo(entry: SubagentHistoryEntry): SubagentInfo {
+  const info: SubagentInfo = { ...entry, source: 'history', lastUpdate: 0 };
+  const progress: SubagentProgress = {};
+  if (entry.lastIntent !== undefined) progress.lastIntent = entry.lastIntent;
+  if (entry.toolCount !== undefined) progress.toolCount = entry.toolCount;
+  if (entry.requests !== undefined) progress.requests = entry.requests;
+  if (entry.tokens !== undefined) progress.tokens = entry.tokens;
+  if (entry.contextTokens !== undefined) progress.contextTokens = entry.contextTokens;
+  if (entry.contextWindow !== undefined) progress.contextWindow = entry.contextWindow;
+  if (entry.cost !== undefined) progress.cost = entry.cost;
+  if (entry.durationMs !== undefined) progress.durationMs = entry.durationMs;
+  if (entry.resolvedModel !== undefined) progress.resolvedModel = entry.resolvedModel;
+  if (Object.keys(progress).length > 0) info.progress = progress;
+  return info;
+}
+
+/** ms → `17.8s` / `1m 4s`; empty for absent/negative values. */
+export function formatSubagentDuration(ms: number | undefined): string {
+  if (typeof ms !== 'number' || !Number.isFinite(ms) || ms < 0) return '';
+  if (ms < 60_000) return `${(ms / 1000).toFixed(1)}s`;
+  const totalSeconds = Math.round(ms / 1000);
+  return `${Math.floor(totalSeconds / 60)}m ${totalSeconds % 60}s`;
+}
+
+/** `$0.003` compact cost; empty for absent/zero values. */
+export function formatSubagentCost(cost: number | undefined): string {
+  if (typeof cost !== 'number' || !Number.isFinite(cost) || cost <= 0) return '';
+  return `$${cost.toFixed(3)}`;
+}
+
+/** Combined `duration · cost` row suffix, sourced from the roster progress. */
+export function formatSubagentMeta(subagent: SubagentInfo): string {
+  const duration = formatSubagentDuration(subagent.progress?.durationMs);
+  const cost = formatSubagentCost(subagent.progress?.cost);
+  return [duration, cost].filter(Boolean).join(' · ');
+}