@kabmo-labs/kabmo 0.0.0-stage → 0.1.0

package/extensions/kabmo-modes/parked.test.ts

@@ -0,0 +1,112 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The parked-proposal slot: what fills it, what empties it, and the rule that
+ * nothing empties it on a clock.
+ *
+ * The slot is module-level state (omp permits one `xd://propose` at a time per
+ * session), so every test here takes it through the module's own API and leaves
+ * it empty — a leaked slot would make the NEXT test's `peek` lie.
+ */
+
+import { beforeEach, describe, expect, test } from 'bun:test';
+import {
+  awaitParkedProposal,
+  parkProposal,
+  peekParkedProposal,
+  releaseForRefinement,
+  releaseParkedProposal,
+  takeParkedProposal,
+} from './parked';
+
+interface Resolved {
+  content: Array<{ type: string; text: string }>;
+  details: { planFilePath: string; title: string; planExists: boolean };
+}
+
+/** Park a proposal and hand back a recorder for how it was resolved. */
+function park(title = 'migrate-importer'): { resolved: Resolved[] } {
+  const resolved: Resolved[] = [];
+  parkProposal({
+    title,
+    planFilePath: `local://${title}-plan.md`,
+    planContent: '# Plan',
+    resolve: (result) => resolved.push(result as Resolved),
+  });
+  return { resolved };
+}
+
+beforeEach(() => {
+  // Drain anything a previous test left behind.
+  takeParkedProposal();
+});
+
+describe('the parked proposal slot', () => {
+  test('peek reports the slot without consuming it', () => {
+    park('peeked');
+    expect(peekParkedProposal()?.title).toBe('peeked');
+    // Still there: `republish` peeks on every attach and must not steal the
+    // proposal from the decision that follows.
+    expect(peekParkedProposal()?.title).toBe('peeked');
+    expect(takeParkedProposal()?.title).toBe('peeked');
+    expect(peekParkedProposal()).toBeNull();
+  });
+
+  test('only one caller can resolve a proposal', () => {
+    park();
+    expect(takeParkedProposal()).not.toBeNull();
+    // A second decision must be refused, not answered against a plan that was
+    // already handed to the model.
+    expect(takeParkedProposal()).toBeNull();
+  });
+
+  test('awaitParkedProposal resolves immediately when one is already parked', async () => {
+    park();
+    await awaitParkedProposal();
+    expect(peekParkedProposal()?.title).toBe('migrate-importer');
+  });
+
+  test('awaitParkedProposal resolves when a proposal parks, not on its own', async () => {
+    let done = false;
+    const pending = awaitParkedProposal();
+    void pending.then(() => { done = true; });
+
+    // A microtask boundary: a promise that had resolved eagerly — on a timer, or
+    // by pre-resolving — would report `true` here.
+    await Promise.resolve();
+    expect(done).toBe(false);
+
+    park('late');
+    await pending;
+    expect(done).toBe(true);
+    expect(peekParkedProposal()?.title).toBe('late');
+  });
+});
+
+describe('releases that are not a decision', () => {
+  test('a refinement release hands the model a reason and keeps the plan path', () => {
+    const { resolved } = park();
+    releaseForRefinement('The run was interrupted.');
+    expect(resolved).toHaveLength(1);
+    expect(resolved[0]?.content[0]?.text).toContain('The run was interrupted.');
+    // The model is told to re-propose, which is what keeps plan mode useful:
+    // the path it should rewrite is carried back.
+    expect(resolved[0]?.content[0]?.text).toContain('xd://propose');
+    expect(resolved[0]?.details.planFilePath).toBe('local://migrate-importer-plan.md');
+    expect(peekParkedProposal()).toBeNull();
+  });
+
+  test('a teardown release says it was dismissed', () => {
+    const { resolved } = park();
+    releaseParkedProposal();
+    expect(resolved[0]?.content[0]?.text).toContain('dismissed');
+  });
+
+  test('releasing an empty slot is a no-op, not a crash', () => {
+    expect(() => releaseForRefinement('nothing here')).not.toThrow();
+    expect(() => releaseParkedProposal()).not.toThrow();
+  });
+});

package/extensions/kabmo-modes/parked.ts

@@ -0,0 +1,161 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The parked `xd://propose`: the slot it lives in, the plan body it carries,
+ * and the ways it can be released.
+ *
+ * Split from `plan.ts` so the review surface owns only the DECISION (which of
+ * omp's five choices, and what each one does to the session). This half knows
+ * nothing about choices — it is the state a decision is made against.
+ *
+ * ## The parking contract
+ *
+ * Plan mode's approval path is a `write` to `xd://propose`, which omp dispatches
+ * to whatever `setPlanProposalHandler` installed. The TUI's handler opens the
+ * full-screen review overlay and resolves when the operator picks; the model's
+ * tool call stays open the whole time. That is exactly what Kabmo needs —
+ * the operator reviews in the web console, and the decision travels back — so
+ * the handler parks the promise the same way.
+ *
+ * Parking is safe: measured on omp 18.4.4 with a proposal held for 45 s, the RPC
+ * loop stays responsive (`get_state` answers, a second command runs) because the
+ * handler blocks only the tool call, not the reader.
+ *
+ * ## Why it waits INDEFINITELY
+ *
+ * The review has no deadline, exactly like the `ask` tool: `ask.timeout`
+ * defaults to 0 — "wait forever" — because a question that expires under the
+ * operator is worse than one that waits. A plan review is the same kind of
+ * gate, and this used to be the exception: a 30-minute timer resolved the
+ * proposal as a REFINEMENT, which kept plan mode active and told the model to
+ * plan again. So an operator who left a review open over lunch came back to a
+ * different plan, with no notice that theirs had been discarded, while the panel
+ * still showed the plan the child had already abandoned. omp itself has no such
+ * timer (`peekPlanProposalHandler` is awaited with no deadline), so Kabmo
+ * was inventing one.
+ *
+ * What keeps a parked proposal from becoming a hung run is therefore an
+ * EXPLICIT exit, not a clock:
+ *
+ *  - the operator decides (five choices, or Dismiss, which refines);
+ *  - `plan off` releases it as a refinement before tearing plan mode down, so
+ *    turning the toggle off mid-review cannot strand the turn;
+ *  - Stop/abort ends the turn the tool call belongs to — the same escape an
+ *    unanswered `ask` has;
+ *  - switching sessions or reloading does NOT touch it: the child keeps the call
+ *    open and the review is re-published to whichever client attaches.
+ */
+
+import type { ExtensionCtx } from './session';
+
+export interface ParkedProposal {
+  title: string;
+  planFilePath: string;
+  planContent: string;
+  resolve: (result: unknown) => void;
+}
+
+/** The single parked proposal for this process. omp permits one `xd://propose`
+ *  at a time per session (the handler is replaced, never stacked), so a slot
+ *  rather than a map is the honest shape. */
+let parked: ParkedProposal | null = null;
+
+/** Resolvers waiting for the next proposal to park. See `awaitParkedProposal`. */
+let parkedWaiters: Array<() => void> = [];
+
+/**
+ * Resolve once a proposal is parked (immediately when one already is).
+ *
+ * A seam for the test suite, and honest about why it has to exist: parking
+ * happens AFTER the plan file is read, so a caller cannot know from the return
+ * of `installPlanProposal` whether the handler has reached its parked state —
+ * and a test that guessed with a delay would be racing the read rather than
+ * waiting for it.
+ */
+export function awaitParkedProposal(): Promise<void> {
+  if (parked) return Promise.resolve();
+  const { promise, resolve } = Promise.withResolvers<void>();
+  parkedWaiters.push(resolve);
+  return promise;
+}
+
+/** The parked proposal, if any. Read-only: a caller that intends to resolve it
+ *  takes it through `takeParkedProposal` instead. */
+export function peekParkedProposal(): ParkedProposal | null {
+  return parked;
+}
+
+/** Fill the slot and wake whoever is waiting on `awaitParkedProposal`. */
+export function parkProposal(proposal: ParkedProposal): void {
+  parked = proposal;
+  const waiters = parkedWaiters;
+  parkedWaiters = [];
+  for (const waiter of waiters) waiter();
+}
+
+/** Consume the slot. Exactly one caller may resolve a given proposal, which is
+ *  what makes `null` here mean "somebody already answered it". */
+export function takeParkedProposal(): ParkedProposal | null {
+  const current = parked;
+  parked = null;
+  return current;
+}
+
+/**
+ * omp's `local://` root resolver, loaded ON DEMAND.
+ *
+ * Dynamic on purpose: the module lives in the omp package, which is installed
+ * in the machine's global prefix and is NOT a Kabmo dependency — a static
+ * import would make this file unresolvable outside a child process (measured:
+ * `bun test` on this very file failed with "Cannot find module
+ * '@oh-my-pi/pi-coding-agent/internal-urls'"). Inside the child the specifier
+ * resolves, and the load is cached after the first call.
+ */
+async function localRootResolver(): Promise<((options: unknown) => string) | null> {
+  try {
+    const mod: unknown = await import('@oh-my-pi/pi-coding-agent/internal-urls');
+    if (mod && typeof mod === 'object' && 'resolveLocalRoot' in mod) {
+      const resolver = mod.resolveLocalRoot;
+      return typeof resolver === 'function' ? (resolver as (options: unknown) => string) : null;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/** Read a `local://` artifact through omp's own root mapping. */
+export async function readPlanFile(ctx: ExtensionCtx, planFilePath: string): Promise<string> {
+  try {
+    const resolveLocalRoot = await localRootResolver();
+    if (!resolveLocalRoot) return '';
+    const root = resolveLocalRoot(ctx.localProtocolOptions);
+    const relative = planFilePath.replace(/^local:\/+/i, '');
+    const file = Bun.file(`${root}/${relative}`);
+    if (!(await file.exists())) return '';
+    return await file.text();
+  } catch {
+    // A plan that cannot be read is reported as an empty body; the approval
+    // itself still works, because omp re-reads the file its own way.
+    return '';
+  }
+}
+
+/** Resolve a parked proposal with a refinement request, which keeps plan mode
+ *  active and hands the model a reason instead of a decision. */
+export function releaseForRefinement(reason: string): void {
+  const current = takeParkedProposal();
+  if (!current) return;
+  current.resolve({
+    content: [{ type: 'text', text: `${reason} Update the plan file, then write its title to xd://propose again.` }],
+    details: { planFilePath: current.planFilePath, title: current.title, planExists: true },
+  });
+}
+
+/** Release the parked proposal because plan mode is being torn down. */
+export function releaseParkedProposal(): void {
+  releaseForRefinement('Plan review was dismissed.');
+}

package/extensions/kabmo-modes/plan.test.ts

@@ -0,0 +1,283 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The plan-review decision, end to end inside the extension.
+ *
+ * Every exit path must report itself. The panel closes on the child's
+ * `KABMO_PLAN_DECISION` marker and NOT on the HTTP request returning — it
+ * stays up while the decision is in flight, deliberately, so a decision that
+ * silently failed cannot leave the operator looking at a plan nobody is waiting
+ * on.
+ *
+ * That contract was broken for `Refine plan`: the branch resolved the parked
+ * promise (so the agent started planning again) but returned without a marker,
+ * and the panel sat on screen over a live agent. It was found in the browser,
+ * not by a unit test — hence this file.
+ */
+
+import { beforeEach, describe, expect, test } from 'bun:test';
+import { awaitParkedProposal, decidePlan, installPlanProposal } from './plan';
+import {
+  KABMO_PLAN_DECISION_MARKER,
+  KABMO_PLAN_PROPOSAL_MARKER,
+  KABMO_PLAN_STATE_MARKER,
+} from './protocol';
+import type { ExtensionCtx, ModeApi, ModeSession } from './session';
+
+/** The handler the extension installs, exposed so a test can drive it. */
+interface HandlerHost {
+  handler?: (title: string) => Promise<unknown>;
+}
+
+interface Harness {
+  api: ModeApi;
+  session: ModeSession;
+  ctx: ExtensionCtx;
+  notices: string[];
+  appended: Array<{ customType: string; data: unknown }>;
+  sent: Array<{ customType: string; content: string }>;
+  /** Delays any timer the extension armed would have fired at. */
+  timerArms: number[];
+  planEnabled: () => boolean;
+  /** The promise omp awaits as the `write xd://propose` tool result. Set by
+   *  `propose`, and the thing every choice must settle. */
+  toolCall: Promise<unknown> | null;
+}
+
+function harness(): Harness {
+  const notices: string[] = [];
+  const appended: Harness['appended'] = [];
+  const sent: Harness['sent'] = [];
+  let planState: { enabled: boolean; planFilePath: string } | undefined = {
+    enabled: true,
+    planFilePath: 'local://PLAN.md',
+  };
+
+  const host: HandlerHost = {};
+  const session: ModeSession = {
+    getPlanModeState: () => planState,
+    setPlanModeState: (state) => {
+      planState = state;
+    },
+    setPlanProposalHandler: (handler) => {
+      host.handler = handler ?? undefined;
+    },
+    preparePlanForReview: async (title: string) => ({
+      details: { planFilePath: `local://${title}-plan.md`, title, planExists: true },
+    }),
+    setPlanReferencePath: () => {},
+    sessionManager: { appendModeChange: () => 'id', getSessionId: () => 's1' },
+  };
+
+  const api: ModeApi = {
+    appendEntry: (customType, data) => appended.push({ customType, data }),
+    sendMessage: (message) => sent.push({ customType: message.customType, content: message.content }),
+  };
+
+  // The review must arm NO timer: omp's own handler is awaited with no
+  // deadline, and `ask.timeout` defaults to 0 for the same reason. Spying on
+  // the ctx hooks is what makes a re-added deadline a test failure rather than
+  // a silent behaviour change — the shape is widened locally so the spy does
+  // not put the hooks back on the production interface.
+  const timerArms: number[] = [];
+  const timerHost = {
+    setTimeout: (_callback: (...args: unknown[]) => void, ms?: number) => {
+      timerArms.push(ms ?? 0);
+      return 1;
+    },
+    clearTimer: () => {},
+  };
+  const ctx: ExtensionCtx = {
+    cwd: '/tmp/plan-review-test',
+    ui: { notify: (message) => notices.push(message) },
+    ...timerHost,
+  };
+
+  // Expose the installed handler through the session object the harness owns, so
+  // the test never re-derives it from a cast at the call site.
+  (session as unknown as HandlerHost).handler = undefined;
+  const exposed: Harness & HandlerHost = {
+    api,
+    session,
+    ctx,
+    notices,
+    appended,
+    sent,
+    timerArms,
+    planEnabled: () => planState?.enabled === true,
+    toolCall: null,
+  };
+  Object.defineProperty(exposed, 'handler', {
+    get: () => host.handler,
+  });
+  return exposed;
+}
+
+/** Install the handler and park a proposal through it.
+ *
+ *  Awaits the parked state rather than a duration: the handler reads the plan
+ *  file first, so the return of `installPlanProposal` says nothing about when
+ *  the slot is filled. The handler's promise is kept on the harness because it
+ *  IS the model's open tool call — the thing every choice has to settle. */
+async function propose(h: Harness): Promise<void> {
+  installPlanProposal(h.session, h.ctx);
+  const handler = (h as Harness & HandlerHost).handler;
+  if (!handler) throw new Error('proposal handler was not installed');
+  h.toolCall = handler('migrate-importer');
+  await awaitParkedProposal();
+}
+
+/**
+ * The parked proposal is module-level state (omp permits one `xd://propose` at
+ * a time per session), so a test that proposes and does not decide would leave
+ * its proposal parked for the next one. Cleared through the extension's own
+ * public teardown — the same call `plan off` makes.
+ */
+beforeEach(() => {
+  const h = harness();
+  installPlanProposal(h.session, h.ctx, { clear: true });
+});
+
+function markers(h: Harness): string[] {
+  return h.notices.filter((n) => n.startsWith('KABMO_'));
+}
+
+function decisionOf(h: Harness): Record<string, unknown> | undefined {
+  const marker = markers(h).find((m) => m.startsWith(KABMO_PLAN_DECISION_MARKER));
+  if (!marker) return undefined;
+  const parsed: unknown = JSON.parse(marker.slice(KABMO_PLAN_DECISION_MARKER.length));
+  return parsed && typeof parsed === 'object' ? (parsed as Record<string, unknown>) : undefined;
+}
+
+/** The `details` bag of a settled `xd://propose` result, narrowed rather than
+ *  asserted: the promise's value is `unknown`, so the read is checked. */
+function planDetailsOf(result: unknown): { planFilePath?: string; title?: string } | undefined {
+  if (!result || typeof result !== 'object' || !('details' in result)) return undefined;
+  const { details } = result;
+  if (!details || typeof details !== 'object') return undefined;
+  const planFilePath = 'planFilePath' in details && typeof details.planFilePath === 'string' ? details.planFilePath : undefined;
+  const title = 'title' in details && typeof details.title === 'string' ? details.title : undefined;
+  return { planFilePath, title };
+}
+
+describe('decidePlan', () => {
+  test('a proposal is announced to the console', async () => {
+    const h = harness();
+    await propose(h);
+    const proposal = markers(h).find((m) => m.startsWith(KABMO_PLAN_PROPOSAL_MARKER));
+    expect(proposal).toBeDefined();
+    const payload = JSON.parse((proposal as string).slice(KABMO_PLAN_PROPOSAL_MARKER.length)) as { title?: string };
+    expect(payload.title).toBe('migrate-importer');
+  });
+
+  test('Refine reports the decision and keeps plan mode on', async () => {
+    const h = harness();
+    await propose(h);
+    expect(await decidePlan(h.api, h.session, h.ctx, 'Refine plan', 'shorter')).toBe(true);
+    // The marker is what closes the panel; without it the review surface stayed
+    // up over an agent that was already planning again.
+    expect(decisionOf(h)?.choice).toBe('Refine plan');
+    // Refine keeps plan mode ON: the model is expected to revise and re-propose.
+    expect(h.planEnabled()).toBe(true);
+  });
+
+  test('each approve variant reports the decision and leaves plan mode', async () => {
+    for (const choice of [
+      'Approve and execute',
+      'Approve and compact context',
+      'Approve and keep context',
+    ]) {
+      const h = harness();
+      await propose(h);
+      expect(await decidePlan(h.api, h.session, h.ctx, choice, '')).toBe(true);
+      expect(decisionOf(h)?.choice).toBe(choice);
+      expect(h.planEnabled()).toBe(false);
+      // The execution turn rides a hidden message, so the transcript carries the
+      // plan without a visible "Plan approved." bubble.
+      expect(h.sent).toHaveLength(1);
+      expect(h.sent[0]?.content).toContain('Plan approved');
+    }
+  });
+
+  /**
+   * The invariant the approve branches were missing.
+   *
+   * The parked promise IS the model's open `write xd://propose` tool call —
+   * omp awaits the handler's return value as that call's result. A choice that
+   * returns without resolving leaves the call open, so the planning turn never
+   * ends: the child streams forever, `agent_end` never arrives, and the next
+   * prompt is refused. Measured on omp 18.11.2 through the real RPC path before
+   * this was fixed: `Approve and keep context` left the session
+   * `isStreaming: true` indefinitely (transcript stopped at the tool call, a
+   * follow-up prompt refused), while `Approve and execute` and
+   * `Approve and compact context` only MASKED it — their `newSession` /
+   * `compact` reset the agent's streaming state, so the run looked finished
+   * with the promise still pending.
+   *
+   * The race is what makes an unsettled promise observable: `toolCall` resolves
+   * before this runs when the choice settled it, so its reaction is queued
+   * first and wins against an already-resolved sentinel — and the sentinel wins
+   * when it never settles.
+   */
+  test('every choice SETTLES the parked tool call', async () => {
+    const NOT_SETTLED = Symbol('not-settled');
+    for (const [choice, feedback] of [
+      ['Approve and execute', ''],
+      ['Approve and compact context', ''],
+      ['Approve and keep context', ''],
+      ['Refine plan', 'shorter'],
+      ['Save and quit', ''],
+    ] as const) {
+      const h = harness();
+      await propose(h);
+      const toolCall = h.toolCall;
+      if (!toolCall) throw new Error('propose did not expose the tool call');
+      expect(await decidePlan(h.api, h.session, h.ctx, choice, feedback)).toBe(true);
+      const result: unknown = await Promise.race([toolCall, Promise.resolve(NOT_SETTLED)]);
+      expect(result).not.toBe(NOT_SETTLED);
+      // The result is the tool output the model reads, so it must name the plan
+      // the way omp's own `preparePlanForReview` does.
+      const details = planDetailsOf(result);
+      expect(details?.title).toBe('migrate-importer');
+      expect(details?.planFilePath).toContain('migrate-importer');
+    }
+  });
+
+  test('leaving plan mode is both PERSISTED and broadcast', async () => {
+    const h = harness();
+    await propose(h);
+    await decidePlan(h.api, h.session, h.ctx, 'Approve and keep context', '');
+    // The entry is what a reload reads back, and the marker is what moves the
+    // composer's toggle right now. Writing only the entry left the Plan button
+    // showing as pressed over a session that was already executing — found in
+    // the browser, which is why both halves are asserted here.
+    const planEntries = h.appended.filter((e) => e.customType === 'kabmo-plan-state');
+    expect(planEntries.at(-1)?.data).toEqual({ enabled: false });
+    const planState = markers(h).filter((m) => m.startsWith(KABMO_PLAN_STATE_MARKER));
+    const last = JSON.parse((planState.at(-1) as string).slice(KABMO_PLAN_STATE_MARKER.length)) as { enabled?: boolean };
+    expect(last.enabled).toBe(false);
+  });
+
+  test('a decision with nothing parked is refused, not silently dropped', async () => {
+    const h = harness();
+    expect(await decidePlan(h.api, h.session, h.ctx, 'Approve and keep context', '')).toBe(false);
+  });
+
+  test('the review waits with NO deadline, like the ask tool', async () => {
+    const h = harness();
+    await propose(h);
+    // A parked review must not expire under the operator. The 30-minute timer
+    // this used to arm resolved the proposal as a REFINEMENT, so a review left
+    // open came back as a different plan with the panel still showing the
+    // abandoned one. `ask.timeout` defaults to 0 — "wait forever" — and this is
+    // the same kind of gate, so nothing may be armed at all.
+    expect(h.timerArms).toEqual([]);
+
+    // And the proposal really is still pending: a decision is what resolves it.
+    expect(await decidePlan(h.api, h.session, h.ctx, 'Approve and keep context', '')).toBe(true);
+    expect(decisionOf(h)?.choice).toBe('Approve and keep context');
+  });
+});