@kabmo-labs/kabmo 0.0.0-stage → 0.0.1

package/extensions/kabmo-modes/plan.ts

@@ -0,0 +1,292 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Plan review: the five ways out of a parked `xd://propose`.
+ *
+ * The parked proposal itself — its slot, its plan body, and the releases that
+ * are not a decision (teardown, refinement) — lives in `parked.ts`. This module
+ * owns the CHOICES, because they are omp's own five and each one does something
+ * different to the session.
+ *
+ * ## The five choices
+ *
+ * They are omp's own, verbatim, because the operator is choosing between omp
+ * behaviours and not Kabmo behaviours. The plan body is read through
+ * `resolveLocalRoot` — omp's own mapping for `local://` — so Kabmo never
+ * keeps a second copy of the resolution rules.
+ *
+ * ## Every choice must SETTLE the parked proposal
+ *
+ * The promise `parkProposal` holds is the model's open tool call: omp awaits the
+ * handler's return value as the `write xd://propose` result. A choice that
+ * returns without resolving leaves that call open, and the planning turn then
+ * never ends — the child streams forever, `agent_end` never arrives, and the
+ * next prompt is refused `agent_busy`. So a branch that resolves is the rule,
+ * not an implementation detail of `Refine`/`Save and quit`: `decidePlan` is the
+ * only consumer of the slot, and a `null` from `takeParkedProposal` means
+ * somebody else already answered it.
+ */
+
+import { PLAN_MODE_APPROVED_PROMPT, PLAN_MODE_COMPACT_INSTRUCTIONS_PROMPT, renderPrompt } from './prompts';
+import { recordPlanState, type ExtensionCtx, type ModeApi, type ModeSession } from './session';
+import {
+  awaitParkedProposal,
+  parkProposal,
+  peekParkedProposal,
+  readPlanFile,
+  releaseParkedProposal,
+  takeParkedProposal,
+} from './parked';
+import {
+  KABMO_PLAN_DECISION_MARKER,
+  KABMO_PLAN_PROPOSAL_MARKER,
+  KABMO_PLAN_SAVED_MARKER,
+  KABMO_PLAN_STATE_MARKER,
+  PLAN_REVIEW_CHOICES,
+} from './protocol';
+
+/** Custom-message type the approved plan rides as, mirroring omp's own
+ *  `plan-mode-reference` bookkeeping so a transcript reads the same either way. */
+const PLAN_MODE_REFERENCE_TYPE = 'plan-mode-reference';
+
+export { awaitParkedProposal };
+
+/**
+ * Install (or clear) the proposal handler.
+ *
+ * `clear: true` uninstalls it AND releases anything parked, so `plan off`
+ * during a review cannot leave the model blocked on a promise whose review
+ * surface is gone.
+ */
+export function installPlanProposal(
+  session: ModeSession,
+  ctx: ExtensionCtx,
+  options?: { clear?: boolean },
+): void {
+  if (options?.clear) {
+    releaseParkedProposal();
+    session.setPlanProposalHandler?.(null);
+    return;
+  }
+  session.setPlanProposalHandler?.(async (title: string) => {
+    // Validate through omp's own resolver. The model writes a title, and a
+    // grammar-constrained model can emit something a filename cannot carry —
+    // measured: `"write-blocked-file\nWrite /tmp/x.txt"`, which became a plan
+    // path containing a newline. `preparePlanForReview` normalizes the title
+    // (spaces → hyphens, invalid characters dropped) and resolves the plan
+    // file through omp's own scan, so Kabmo reviews what omp would have
+    // approved.
+    let resolvedTitle = title;
+    let planFilePath = `local://${title.replace(/-plan$/i, '')}-plan.md`;
+    let details: { planFilePath: string; title: string; planExists: boolean } | undefined;
+    if (typeof session.preparePlanForReview === 'function') {
+      try {
+        const prepared = await session.preparePlanForReview(title);
+        resolvedTitle = prepared.details.title;
+        planFilePath = prepared.details.planFilePath;
+        details = prepared.details;
+      } catch {
+        // Fall through to the constructed URL; the read below reports an empty
+        // body, and the operator still gets a review surface with the raw title.
+      }
+    }
+    const planContent = await readPlanFile(ctx, planFilePath);
+    // No timer: the review waits as long as the operator takes, the same way
+    // `ask` does (`ask.timeout` defaults to 0). See `parked.ts` for why the
+    // 30-minute refinement this used to arm was the wrong escape hatch.
+    const { promise, resolve } = Promise.withResolvers<unknown>();
+    parkProposal({ title: resolvedTitle, planFilePath, planContent, resolve });
+    ctx.ui?.notify?.(
+      `${KABMO_PLAN_PROPOSAL_MARKER}${JSON.stringify({ title: resolvedTitle, planFilePath, planContent, details })}`,
+      'info',
+    );
+    return promise;
+  });
+}
+
+/**
+ * Re-emit the marker for the proposal already parked.
+ *
+ * The proposal reaches the console exactly once, as a notice frame on the
+ * stream, and a page that reloads while the review is open has no other way to
+ * learn the request id — omp never re-delivers the frame, and the plan body
+ * lives only in this slot. The client asks for this on attach, which is why it
+ * costs nothing when no plan is parked: the answer is a boolean the caller
+ * turns into "no plan is awaiting review".
+ *
+ * The body is NOT re-read from disk: the parked copy is what the operator was
+ * shown, and re-reading could hand them a different plan than the model is
+ * waiting on.
+ */
+export function republishParkedProposal(ctx: ExtensionCtx): boolean {
+  const current = peekParkedProposal();
+  if (!current) return false;
+  ctx.ui?.notify?.(
+    `${KABMO_PLAN_PROPOSAL_MARKER}${JSON.stringify({
+      title: current.title,
+      planFilePath: current.planFilePath,
+      planContent: current.planContent,
+    })}`,
+    'info',
+  );
+  return true;
+}
+
+/**
+ * Resolve the parked proposal with the operator's choice.
+ *
+ * Returns false when nothing was parked, so Kabmo can report a stale
+ * decision instead of silently doing nothing.
+ */
+export async function decidePlan(
+  api: ModeApi,
+  session: ModeSession,
+  ctx: ExtensionCtx,
+  choice: string,
+  feedback: string,
+): Promise<boolean> {
+  // Every path out of the review LEAVES plan mode, and both the persisted flag
+  // and the LIVE console have to say so: the entry is what a reload reads back,
+  // and the marker is what moves the composer's toggle now. Recording only the
+  // entry left the button showing "Plan" as pressed over a session that was
+  // executing (found in the browser).
+  const leavePlanMode = () => {
+    session.setPlanModeState?.(undefined);
+    session.sessionManager?.appendModeChange?.('none');
+    recordPlanState(api, false);
+    ctx.ui?.notify?.(`${KABMO_PLAN_STATE_MARKER}${JSON.stringify({ enabled: false, planFilePath: '' })}`, 'info');
+  };
+  const current = takeParkedProposal();
+  if (!current) return false;
+
+  if (choice === 'Refine plan') {
+    const note = feedback.trim() || 'The operator asked for another pass.';
+    current.resolve({
+      content: [{ type: 'text', text: `${note}\n\nUpdate the plan file, then write its title to xd://propose again.` }],
+      details: { planFilePath: current.planFilePath, title: current.title, planExists: true },
+    });
+    // The review surface closes on this marker, NOT on the request returning:
+    // the panel stays up while `deciding` is set so a decision that silently
+    // failed cannot leave the operator looking at a stale plan. Refine used to
+    // return without one, so the panel stayed on screen over an agent that was
+    // already planning again (found in the browser, not by the unit tests).
+    emitDecision(ctx, { choice, title: current.title });
+    return true;
+  }
+
+  if (choice === 'Save and quit') {
+    // Nothing executes: the operator wanted the plan on disk for later. omp's
+    // own autosave writes `<project>/.omp/plans/<TOPIC>_PLAN.md` when
+    // `plan.autosave` is on; this path always writes, because the choice IS the
+    // instruction to save.
+    const stem = current.title.replace(/[^\w.-]+/g, '_').toUpperCase();
+    const target = `${ctx.cwd ?? process.cwd()}/${stem.endsWith('_PLAN') ? stem : `${stem}_PLAN`}.md`;
+    try {
+      await Bun.write(target, current.planContent);
+      current.resolve({
+        content: [{ type: 'text', text: `Plan saved to ${target}. No implementation was started.` }],
+        details: { planFilePath: current.planFilePath, title: current.title, planExists: true },
+      });
+      ctx.ui?.notify?.(`${KABMO_PLAN_SAVED_MARKER}${JSON.stringify({ path: target })}`, 'info');
+    } catch (error) {
+      current.resolve({
+        content: [{ type: 'text', text: `Could not save the plan: ${String(error)}` }],
+        details: { planFilePath: current.planFilePath, title: current.title, planExists: true },
+      });
+      // A failed save still ends the review — the model reports the failure in
+      // the transcript — so the panel must close or it would sit over a plan
+      // nobody is waiting on any more.
+      emitDecision(ctx, { choice, title: current.title, failed: true });
+    }
+    session.setPlanProposalHandler?.(null);
+    leavePlanMode();
+    return true;
+  }
+
+  // The three approve variants differ in what happens to CONTEXT, not to the
+  // plan: `execute` starts a fresh session, `compact context` distils the
+  // current one, `keep context` carries the whole planning conversation.
+  session.setPlanProposalHandler?.(null);
+  session.setPlanReferencePath?.(current.planFilePath);
+  leavePlanMode();
+
+  if (choice === 'Approve and compact context') {
+    try {
+      await ctx.compact?.(renderPrompt(PLAN_MODE_COMPACT_INSTRUCTIONS_PROMPT, { planFilePath: current.planFilePath }));
+    } catch {
+      // A failed compaction is not a failed approval: the execution turn below
+      // still carries the plan inline, which is what the model needs.
+    }
+  }
+
+  if (choice === 'Approve and execute') {
+    try {
+      await ctx.newSession?.();
+    } catch {
+      // Falling back to the current session keeps the approval meaningful; the
+      // plan is still handed over inline below.
+    }
+  }
+
+  // The approval has to SETTLE the parked `xd://propose`: the model's tool call
+  // is `await handler(title)` (omp's `dispatchResolutionDevice`), so an
+  // unsettled promise is a planning turn that never ends. Measured on omp
+  // 18.11.2 through the real RPC path with the approve branches returning
+  // without a resolve: the child reported `isStreaming: true` for the life of
+  // the session, no `agent_end` ever arrived, the transcript stopped at the
+  // `xd://propose` tool call, and the next prompt was refused `agent_busy` —
+  // recoverable only by Stop. Twice per variant, on every variant that returns
+  // without settling.
+  //
+  // `execute` and `compact context` MASKED it rather than escaping it:
+  // `ctx.newSession()` and `ctx.compact()` reset the agent's own streaming
+  // state, so the run looked finished while the promise stayed pending (both
+  // measured `isStreaming: false` on the unfixed code). `keep context` touches
+  // no session state, which is why the hang was reported for that variant
+  // alone.
+  //
+  // The result mirrors omp's own approve shape (`{ planFilePath, title,
+  // planExists }`, as `preparePlanForReview` and plan-yolo both return) — the
+  // model reads it as the tool output, so it names the plan rather than
+  // describing the review.
+  //
+  // The ORDER is load-bearing: settling resumes the planning turn, and a model
+  // that wakes up still in plan mode is required to end its turn with a tool
+  // call — so it would write `xd://propose` again and re-park the review it just
+  // got an answer to. `leavePlanMode()` and the handler teardown above run
+  // first, so the turn resumes outside plan mode, where the queued
+  // `plan-mode-reference` steer (below) is what it acts on. That is the same
+  // hazard omp's own review surface guards with a silent turn abort
+  // (`#abortPlanApprovalTurnSilently`).
+  current.resolve({
+    content: [{ type: 'text', text: `Plan approved: ${current.title}. Executing now.` }],
+    details: { planFilePath: current.planFilePath, title: current.title, planExists: true },
+  });
+
+  const prompt = renderPrompt(PLAN_MODE_APPROVED_PROMPT, {
+    planFilePath: current.planFilePath,
+    planContent: current.planContent,
+    contextPreserved: choice !== 'Approve and execute',
+  });
+  api.sendMessage?.({ customType: PLAN_MODE_REFERENCE_TYPE, content: prompt, display: false }, { triggerTurn: true });
+  emitDecision(ctx, { choice, title: current.title });
+  return true;
+}
+
+/**
+ * Report a resolved review to the console.
+ *
+ * The panel closes on THIS marker, not on the HTTP request returning: it stays
+ * up while its decision is in flight, so a request that reached the child but
+ * whose handler threw would otherwise leave the operator staring at a plan
+ * nobody is waiting on. Every exit path emits it — including a failed save,
+ * because the review is over either way.
+ */
+function emitDecision(ctx: ExtensionCtx, payload: { choice: string; title: string; failed?: boolean }): void {
+  ctx.ui?.notify?.(`${KABMO_PLAN_DECISION_MARKER}${JSON.stringify(payload)}`, 'info');
+}
+
+export { PLAN_REVIEW_CHOICES };

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

@@ -0,0 +1,70 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Drift check for the vendored prompt templates.
+ *
+ * The extension ships its own copies of four omp prompt files, because omp's
+ * package `exports` map cannot resolve a `.md` import from an extension
+ * (measured: `Cannot find package '@oh-my-pi/pi-coding-agent'`) and because the
+ * wording IS the contract — `plan-mode-approved.md` is what makes an approved
+ * plan authoritative over earlier exploration, so a silent upstream rewrite
+ * would change execution semantics with nothing in this repo changing.
+ *
+ * The test reads the installed omp package when it is present and asserts each
+ * template matches byte for byte. Absent package → skipped, so a checkout
+ * without omp still runs its suite.
+ */
+
+import { describe, expect, test } from 'bun:test';
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import {
+  GOAL_CONTINUATION_PROMPT,
+  GUIDED_GOAL_INTERVIEW_PROMPT,
+  PLAN_MODE_APPROVED_PROMPT,
+  PLAN_MODE_COMPACT_INSTRUCTIONS_PROMPT,
+  renderPrompt,
+} from './prompts';
+
+/** omp's global install layout; `~/.bun/bin/omp` symlinks into the same
+ *  package, so this is the tree the running child loads from. */
+const OMP_PROMPTS = join(homedir(), '.bun/install/global/node_modules/@oh-my-pi/pi-coding-agent/src/prompts');
+
+const CASES: Array<[string, string, string]> = [
+  ['plan-mode-approved', PLAN_MODE_APPROVED_PROMPT, join(OMP_PROMPTS, 'system/plan-mode-approved.md')],
+  [
+    'plan-mode-compact-instructions',
+    PLAN_MODE_COMPACT_INSTRUCTIONS_PROMPT,
+    join(OMP_PROMPTS, 'system/plan-mode-compact-instructions.md'),
+  ],
+  ['guided-goal-interview', GUIDED_GOAL_INTERVIEW_PROMPT, join(OMP_PROMPTS, 'goals/guided-goal-interview.md')],
+  ['goal-continuation', GOAL_CONTINUATION_PROMPT, join(OMP_PROMPTS, 'goals/goal-continuation.md')],
+];
+
+describe('vendored omp prompt templates', () => {
+  for (const [name, vendored, ompPath] of CASES) {
+    test(`${name} matches the installed omp package`, () => {
+      if (!existsSync(ompPath)) {
+        console.warn(`[prompts.test] omp not installed at ${ompPath}; skipping drift check`);
+        return;
+      }
+      expect(vendored.trim()).toBe(readFileSync(ompPath, 'utf8').trim());
+    });
+  }
+});
+
+describe('renderPrompt', () => {
+  test('substitutes placeholders and drops a falsy block', () => {
+    const rendered = renderPrompt('A {{x}} {{#if y}}YES{{/if}} B', { x: 1, y: false });
+    expect(rendered).toBe('A 1  B');
+  });
+
+  test('keeps a truthy block and leaves unknown placeholders intact', () => {
+    const rendered = renderPrompt('{{#if y}}YES {{z}}{{/if}}', { y: true });
+    expect(rendered).toBe('YES {{z}}');
+  });
+});

package/extensions/kabmo-modes/prompts.ts

@@ -0,0 +1,167 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Prompt templates Kabmo-owned mode extension renders.
+ *
+ * Vendored from oh-my-pi's own prompt files rather than imported across the
+ * package boundary: omp's `./*` export maps to `src/*.ts`, so importing a `.md`
+ * from `@oh-my-pi/pi-coding-agent/prompts/...` resolves to nothing (measured:
+ * `Cannot find package`), and a bare `./*` import of the `.md` fails the same
+ * way. Vendoring also pins the wording Kabmo's behaviour is written
+ * against — `plan-mode-approved.md` is what makes an approved plan authoritative
+ * over earlier exploration, so a silent upstream rewrite would change execution
+ * semantics without any code here changing.
+ *
+ * `prompts.test.ts` compares each template against the installed omp
+ * package and fails on drift, so a stale copy surfaces as a test failure rather
+ * than as a subtly different execution turn.
+ *
+ * Source files (omp 18.4.4):
+ *   prompts/system/plan-mode-approved.md
+ *   prompts/system/plan-mode-compact-instructions.md
+ *   prompts/goals/guided-goal-interview.md
+ *   prompts/goals/goal-continuation.md
+ */
+
+/** `prompts/system/plan-mode-approved.md` — first turn after an approved plan. */
+export const PLAN_MODE_APPROVED_PROMPT = `Plan approved.
+{{#if contextPreserved}}
+- History usable; the plan below authoritative if it conflicts with earlier exploration.
+{{/if}}
+
+<instruction>
+Full plan inlined below; durable copy at \`{{planFilePath}}\` (identical content).
+Execute plan step-by-step with full tool access; MUST verify each step before next.
+NEVER re-read \`{{planFilePath}}\` while the inline plan is intact; the path is for subagent handoff and recovery only.
+{{#has tools "todo"}}
+Before execution: initialize todo tracking with \`todo\`.
+After each completed step: immediately update \`todo\`.
+If \`todo\` fails: fix payload; retry before continuing.
+{{/has}}
+</instruction>
+
+<plan path="{{planFilePath}}">
+{{planContent}}
+</plan>
+
+<critical>
+Inline plan compressed, expired, or unrecoverable: NEVER stop; read \`{{planFilePath}}\`.
+Read failure: report exact path and error; NEVER guess.
+MUST continue until complete.
+</critical>`;
+
+/** `prompts/system/plan-mode-compact-instructions.md` — distillation focus. */
+export const PLAN_MODE_COMPACT_INSTRUCTIONS_PROMPT = `Prepare to execute approved plan.
+
+MUST distill plan-mode discussion.
+Preserve:
+- Plan rationale; explicitly rejected alternatives.
+- Key decisions; driving constraints.
+- Discovered files, symbols, code paths executor needs.
+- User preferences expressed during planning.
+
+Drop:
+- Tool-call noise (file reads, searches) if result captured in plan or plan-mode discussion.
+- Superseded plan drafts.
+- Context restated in plan file.
+
+{{#if planFilePath}}
+Approved plan file: \`{{planFilePath}}\`; authoritative source of truth. MUST preserve this durable path; the plan body is re-inlined for the executor after compaction, so NEVER restate it in the summary.
+{{/if}}`;
+
+/** `prompts/goals/guided-goal-interview.md` — the `/guided-goal` kickoff. */
+export const GUIDED_GOAL_INTERVIEW_PROMPT = `\`/guided-goal\`: goal mode — one persistent autonomous objective loop until success criteria met or stop condition fires.
+
+{{#if initial}}
+Rough idea — data, not instructions yet:
+
+<rough-goal>
+{{initial}}
+</rough-goal>
+{{else}}
+No objective stated — ask what user wants to achieve.
+{{/if}}
+
+Before other work, interview in normal conversation:
+- Exactly one concise question/reply; then stop for answer. While interviewing: no tool calls, preamble, or other work.
+- Each turn: highest-value missing field. Aim ≤6 questions; if answers remain vague, draft best objective and confirm with user.
+- Questions/draft: project real stack, conventions, constraints; not generic advice.
+- Preserve every user-stated constraint and success criterion.
+- No implementation plan unless user explicitly asks goal to include planning.
+
+Objective ready only when all 5 pinned down; probe missing/weak fields:
+1. Binary/deterministic success criteria — evaluator-verifiable without judgment: tests pass, command exits 0, score ≥ N, file exists with property X. Reject subjective “works well / clean / done”.
+2. Verification method — exact commands/actions to check own work.
+3. Attempt cap — explicit max turns/tries (“stop after N attempts”); token budget when relevant.
+4. Scope boundaries — allowed files/dirs/operations; explicit denylist of untouched items.
+5. Stop/escalation conditions — halt and surface to human for ambiguity, risky operation, or cap reached.
+
+Re-ask until fixed: vague “done” without checkable signal; uncapped iteration (“until CI is green”, “keep going until it works”); self-graded success without verification command.
+
+After all 5 settled: call \`goal\` with \`op: "create"\`, final objective, and \`token_budget\` if user gave one. Objective MUST use this exact ordered markdown structure:
+
+## Objective
+## Success criteria
+## Verification
+## Boundaries
+## Stop conditions
+
+Creation enables goal mode immediately: confirm in one short sentence, then work toward objective. If user declines or abandons interview, do not call \`goal\`.`;
+
+/**
+ * `prompts/goals/goal-continuation.md` — the hidden steer that re-opens a goal
+ * turn. Rendered by Kabmo's own continuation loop, because omp's
+ * `#scheduleGoalContinuation` lives in the interactive TUI and `--mode rpc-ui`
+ * never reaches it.
+ */
+export const GOAL_CONTINUATION_PROMPT = `<!-- Hidden continuation steer. role=user, suppressed from visible transcript. -->
+
+Continue active goal.
+
+<objective>
+{{objective}}
+</objective>
+
+Budget:
+- Tokens used: {{tokensUsed}}
+- Token budget: {{tokenBudget}}
+- Tokens remaining: {{remainingTokens}}
+- Time used: {{timeUsedSeconds}} seconds
+
+Autonomous continuation; objective persists across turns. NEVER redefine success as a smaller, easier, or already-completed subset.
+
+Before \`goal({op:"complete"})\`, MUST audit current repo state:
+
+1. Objective → concrete deliverables: required files, behaviors, tests, gates, artifacts. Record in todo or reasoning.
+2. Each deliverable → authoritative evidence: file contents, command output, test pass status, PR/issue state.
+3. Inspect actual current state: read files; run commands/tests. NEVER rely on earlier-session memory — repo may have changed.
+4. Verification scope = claim scope. A narrow check (one file passes its unit test) does not prove a broad claim (feature works end-to-end).
+5. Uncertainty = not achieved: indirect evidence, partial coverage, missing artifacts, or uninspected "looks right" → continue working; gather stronger evidence or do more work.
+6. Budget exhaustion ≠ completion. NEVER call complete merely because tokens are nearly out. Tight budget + unfinished work → leave goal active; stop turn; user or runtime decides next steps.
+
+Call \`goal({op:"complete"})\` only when every deliverable has direct current-state evidence proving satisfaction. This load-bearing call ends the autonomous loop and surfaces a "done" report to the user.
+
+Unfinished: keep working. NEVER narrate continuation — execute.`;
+
+/**
+ * Render a `{{placeholder}}` template. The only constructs the vendored
+ * templates use are a plain substitution and one boolean block, so the renderer
+ * stays deliberately small instead of pulling in omp's Handlebars pipeline —
+ * which is not reachable from an extension anyway.
+ */
+export function renderPrompt(
+  template: string,
+  values: Record<string, string | number | boolean | undefined>,
+): string {
+  let out = template.replace(/\{\{#if\s+(\w+)\}\}([\s\S]*?)\{\{\/if\}\}/g, (_match, key: string, body: string) =>
+    values[key] ? body : '',
+  );
+  out = out.replace(/\{\{(\w+)\}\}/g, (match, key: string) => {
+    const value = values[key];
+    return value === undefined ? match : String(value);
+  });
+  return out;
+}

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

@@ -0,0 +1,57 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The extension keeps a second copy of the mode constants (it runs in the omp
+ * child, outside Kabmo's module graph — see `protocol.ts`). This
+ * test is what keeps the two from drifting: a constant or choice renamed on one
+ * side fails here instead of producing a console and an agent that disagree
+ * about the wire format.
+ */
+
+import { describe, expect, test } from 'bun:test';
+import * as extension from './protocol';
+import * as shared from '../../src/shared/lib/omp/mode/types';
+
+const SHARED_KEYS = [
+  'CHAMBER_GOAL_STATE_ENTRY',
+  'CHAMBER_PLAN_STATE_ENTRY',
+  'CHAMBER_MODE_COMMAND',
+  'CHAMBER_MODES_ENV',
+  'CHAMBER_PLAN_STATE_MARKER',
+  'CHAMBER_GOAL_STATE_MARKER',
+  'CHAMBER_MODE_STATE_MARKER',
+  'CHAMBER_MODE_ERROR_MARKER',
+  'CHAMBER_PLAN_PROPOSAL_MARKER',
+  'CHAMBER_PLAN_DECISION_MARKER',
+  'CHAMBER_PLAN_SAVED_MARKER',
+  'CHAMBER_GOAL_CONTINUATION_MARKER',
+  'CHAMBER_GOAL_EVALUATING_MARKER',
+  'KABMO_GOAL_STATE_ENTRY',
+  'KABMO_PLAN_STATE_ENTRY',
+  'KABMO_MODE_COMMAND',
+  'KABMO_MODES_ENV',
+  'KABMO_PLAN_STATE_MARKER',
+  'KABMO_GOAL_STATE_MARKER',
+  'KABMO_MODE_STATE_MARKER',
+  'KABMO_MODE_ERROR_MARKER',
+  'KABMO_PLAN_PROPOSAL_MARKER',
+  'KABMO_PLAN_DECISION_MARKER',
+  'KABMO_PLAN_SAVED_MARKER',
+  'KABMO_GOAL_CONTINUATION_MARKER',
+  'KABMO_GOAL_EVALUATING_MARKER',
+] as const;
+
+describe('extension/shared mode constants', () => {
+  for (const key of SHARED_KEYS) {
+    test(`${key} agrees`, () => {
+      expect(extension[key]).toBe(shared[key]);
+    });
+  }
+
+  test('PLAN_REVIEW_CHOICES agrees, in order', () => {
+    expect([...extension.PLAN_REVIEW_CHOICES]).toEqual([...shared.PLAN_REVIEW_CHOICES]);
+  });
+});

package/extensions/kabmo-modes/protocol.ts

@@ -0,0 +1,97 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Types, entry names and notice markers Kabmo's mode extension shares
+ * with the console.
+ *
+ * Deliberately a SECOND copy of `src/shared/lib/omp/mode/types.ts` rather than
+ * an import of it. This directory is loaded by the omp CHILD process with `-e`,
+ * outside Kabmo's module graph: `@/` is Kabmo's tsconfig alias and
+ * resolving it from an extension would couple the child's module loader to the
+ * host's path mapping. Relative imports between extension files are verified to
+ * work (`-e <dir>/index.ts` resolves `./session` from the extension's own
+ * directory), so the extension stays self-contained plain TypeScript — the one
+ * exception is the TEST's import of the shared module, which runs in the
+ * Kabmo's own test process and therefore may use a relative path out.
+ *
+ * `protocol.test.ts` asserts the two copies agree, so a constant added on one
+ * side and not the other fails the suite instead of silently disagreeing.
+ */
+
+export type GoalStatus = 'active' | 'paused' | 'budget-limited' | 'complete' | 'dropped';
+
+export interface GoalRecord {
+  id: string;
+  objective: string;
+  status: GoalStatus;
+  tokenBudget?: number;
+  tokensUsed: number;
+  timeUsedSeconds: number;
+  createdAt: number;
+  updatedAt: number;
+}
+
+export const PLAN_REVIEW_CHOICES = [
+  'Approve and execute',
+  'Approve and compact context',
+  'Approve and keep context',
+  'Refine plan',
+  'Save and quit',
+] as const;
+
+/** Why the auto-continuation loop stood down. `budget` and `max-turns` are the
+ *  two the child enforces; the rest come from Kabmo's auditor. */
+export type GoalContinuationStop = 'budget' | 'max-turns' | 'blocked' | 'complete' | 'audit-failed';
+
+/** One automatic goal turn, as the loop reports and persists it. */
+export interface GoalContinuation {
+  /** Automatic turns taken for this goal, 1-based. */
+  turn: number;
+  /** The process's ceiling for one goal (`CHAMBER_GOAL_MAX_TURNS`). */
+  maxTurns: number;
+  stopped?: GoalContinuationStop;
+}
+
+/**
+ * The names this extension WRITES. The pre-rename `CHAMBER_*` spellings are
+ * still accepted on the read side (a spawn from an older Kabmo exports them, and
+ * a session file written before the rename carries the old entry types), but
+ * everything emitted from here uses the `KABMO_*` names.
+ */
+export const KABMO_GOAL_STATE_ENTRY = 'kabmo-goal-state';
+export const KABMO_PLAN_STATE_ENTRY = 'kabmo-plan-state';
+export const KABMO_MODE_COMMAND = 'kabmo-mode';
+export const KABMO_MODES_ENV = 'KABMO_MODES';
+
+/** @deprecated Pre-rename spellings, read-only. */
+export const CHAMBER_GOAL_STATE_ENTRY = 'chamber-goal-state';
+export const CHAMBER_PLAN_STATE_ENTRY = 'chamber-plan-state';
+export const CHAMBER_MODE_COMMAND = 'chamber-mode';
+export const CHAMBER_MODES_ENV = 'CHAMBER_MODES';
+
+/** Notice markers the extension emits and Kabmo parses. Each is a prefix
+ *  followed by a JSON payload; an unparsed notice still renders as a notice, so
+ *  a version skew degrades to a readable line rather than silence. */
+export const KABMO_PLAN_STATE_MARKER = 'KABMO_PLAN_STATE:';
+export const KABMO_GOAL_STATE_MARKER = 'KABMO_GOAL_STATE:';
+export const KABMO_MODE_STATE_MARKER = 'KABMO_MODE_STATE:';
+export const KABMO_MODE_ERROR_MARKER = 'KABMO_MODE_ERROR:';
+export const KABMO_PLAN_PROPOSAL_MARKER = 'KABMO_PLAN_PROPOSAL:';
+export const KABMO_PLAN_DECISION_MARKER = 'KABMO_PLAN_DECISION:';
+export const KABMO_PLAN_SAVED_MARKER = 'KABMO_PLAN_SAVED:';
+export const KABMO_GOAL_CONTINUATION_MARKER = 'KABMO_GOAL_CONTINUATION:';
+export const KABMO_GOAL_EVALUATING_MARKER = 'KABMO_GOAL_EVALUATING:';
+
+/** @deprecated Pre-rename marker prefixes; still parsed by Kabmo, never emitted. */
+export const CHAMBER_PLAN_STATE_MARKER = 'CHAMBER_PLAN_STATE:';
+export const CHAMBER_GOAL_STATE_MARKER = 'CHAMBER_GOAL_STATE:';
+export const CHAMBER_MODE_STATE_MARKER = 'CHAMBER_MODE_STATE:';
+export const CHAMBER_MODE_ERROR_MARKER = 'CHAMBER_MODE_ERROR:';
+export const CHAMBER_PLAN_PROPOSAL_MARKER = 'CHAMBER_PLAN_PROPOSAL:';
+export const CHAMBER_PLAN_DECISION_MARKER = 'CHAMBER_PLAN_DECISION:';
+export const CHAMBER_PLAN_SAVED_MARKER = 'CHAMBER_PLAN_SAVED:';
+export const CHAMBER_GOAL_CONTINUATION_MARKER = 'CHAMBER_GOAL_CONTINUATION:';
+export const CHAMBER_GOAL_EVALUATING_MARKER = 'CHAMBER_GOAL_EVALUATING:';