@kabmo-labs/kabmo 0.0.0-stage → 0.1.0

package/extensions/kabmo-modes/goal.ts

@@ -0,0 +1,335 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Goal-mode actuation and the auto-continuation loop, inside the omp child.
+ *
+ * ## Why the loop lives here and not in Kabmo server
+ *
+ * The TUI's `#scheduleGoalContinuation` (`interactive-mode.ts`) is
+ * interactive-only, so `--mode rpc-ui` never re-opens a goal turn on its own —
+ * without this, Goal mode runs exactly one turn and stops, which is not the
+ * "keeps working across turns" the feature is for.
+ *
+ * The obvious server-side implementation does not work: the RPC command union
+ * has `prompt`/`steer`/`follow_up` and nothing else, so a Kabmo-sent
+ * continuation arrives as a VISIBLE USER MESSAGE and every automatic turn would
+ * leave a "Continue active goal." bubble in the transcript. The extension can
+ * send a hidden custom message (`display: false`), which is exactly what the
+ * TUI does — and it also sees `agent_end.willContinue`, the one signal that
+ * says omp has already scheduled its own continuation.
+ *
+ * The Kabmo still owns the on/off decision (the composer toggle) and Pause:
+ * the loop only fires while `status === 'active'`, and Pause flips that.
+ */
+
+import { GOAL_CONTINUATION_PROMPT, GUIDED_GOAL_INTERVIEW_PROMPT, renderPrompt } from './prompts';
+import type { ExtensionCtx, ModeApi, ModeSession } from './session';
+import {
+  KABMO_GOAL_CONTINUATION_MARKER,
+  KABMO_GOAL_EVALUATING_MARKER,
+  KABMO_GOAL_STATE_ENTRY,
+  type GoalContinuation,
+  type GoalContinuationStop,
+  type GoalRecord,
+} from './protocol';
+
+/**
+ * Ask the loop to forget how many automatic turns it has taken.
+ *
+ * The counter is per goal and per session, and the ceiling is what stops the
+ * loop — so without this a goal that hit `max-turns` cannot be resumed: the
+ * next decision recomputes `turns >= ceiling` from the same counter and stands
+ * down again, leaving Resume a button that appears to do nothing until the
+ * child restarts. Applied on the next decision, which is the first moment the
+ * counter is read.
+ */
+let continuationTurnsReset = false;
+
+export function resetGoalContinuationTurns(): void {
+  continuationTurnsReset = true;
+}
+
+/**
+ * Write the loop's verdict onto the session branch, beside the mode record the
+ * console already reads for the composer's toggles.
+ *
+ * It has to be persisted, not only reported: the turn count lives in THIS
+ * process's memory, so without the entry a reload (or a second tab) would show
+ * a goal as active with nothing left to run it, and no way to tell that
+ * automatic continuation had already stood down. The payload carries the whole
+ * mode record — `readPersistedModes` takes the newest `kabmo-goal-state` as
+ * the state, so a verdict-only entry would wipe the goal it describes.
+ *
+ * `null` clears it (Resume restarts the count, so the old verdict is a lie).
+ */
+export function persistContinuation(
+  api: ModeApi,
+  session: ModeSession,
+  continuation: GoalContinuation | null,
+  maxTurns?: number,
+): void {
+  api.appendEntry?.(KABMO_GOAL_STATE_ENTRY, {
+    ...goalStateRecord(session),
+    continuation,
+    // The goal's own ceiling rides the same entry: the verdict is cleared on
+    // Resume while the ceiling must survive, and this file is the only place
+    // that outlives the process.
+    ...(maxTurns === undefined ? {} : { maxTurns }),
+  });
+}
+
+/** Hard ceiling on automatic turns for one goal. The token budget is the
+ *  primary guard, but a goal with `budget off` has none — and an agent that
+ *  keeps finding work would otherwise run until the process is killed.
+ *
+ * Both spellings are read: the current one is what this build's spawn path
+ * exports, and the pre-rename one is what an older Kabmo (or a hand-written
+ * environment) still carries. */
+const MAX_TURNS_ENV = 'KABMO_GOAL_MAX_TURNS';
+const LEGACY_MAX_TURNS_ENV = 'CHAMBER_GOAL_MAX_TURNS';
+const DEFAULT_MAX_TURNS = 25;
+
+/** Per-goal ceilings, keyed by goal id. A goal's own `maxTurns` beats the
+ *  install default for its whole life, including after a Resume. */
+const goalCeilings = new Map<string, number>();
+
+function ceilingFor(goalId: string): number {
+  const raw = process.env?.[MAX_TURNS_ENV] ?? process.env?.[LEGACY_MAX_TURNS_ENV] ?? '';
+  const configured = Number.parseInt(raw, 10);
+  const fallback = Number.isInteger(configured) && configured > 0 ? configured : DEFAULT_MAX_TURNS;
+  return goalCeilings.get(goalId) ?? fallback;
+}
+
+/** Custom-message types, matching the TUI's own naming so a transcript written
+ *  by either surface reads the same. */
+const GOAL_CONTINUATION_TYPE = 'goal-continuation';
+const GUIDED_GOAL_TYPE = 'guided-goal-interview';
+/** The opening turn of a goal. Distinct from `goal-continuation` because the
+ *  transcript should read as one started objective, not as a continuation. */
+const GOAL_START_TYPE = 'goal-start';
+
+interface GoalArgs {
+  objective?: string;
+  tokenBudget?: number;
+  guided?: string;
+  /** Automatic-turn ceiling for THIS goal; overrides the install default. */
+  maxTurns?: number;
+  /** The auditor's terminal reason, carried by the `done` action. */
+  stopped?: GoalContinuationStop;
+}
+
+/** Parse the JSON payload a Kabmo command carries.
+ *
+ *  The payload is JSON rather than `key=value` pairs because an objective is
+ *  free-form text: it holds spaces, punctuation and newlines, and JSON encodes
+ *  every one of them onto a single line — which matters because the whole
+ *  command travels as one prompt line. */
+export function parseGoalArgs(rest: string): GoalArgs {
+  const trimmed = rest.trim();
+  if (!trimmed) return {};
+  let payload: Record<string, unknown>;
+  try {
+    const parsed: unknown = JSON.parse(trimmed);
+    payload =
+      parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? (parsed as Record<string, unknown>) : {};
+  } catch {
+    // Not JSON: treat the raw text as the objective, so a hand-typed
+    // `/kabmo-mode goal create fix the build` still does something sane.
+    payload = { objective: trimmed };
+  }
+  const objective = typeof payload.objective === 'string' ? payload.objective.trim() : undefined;
+  const guided = typeof payload.guided === 'string' ? payload.guided : undefined;
+  // The Kabmo's auditor reports its terminal verdict through `done`; the
+  // reason travels so the strip can name it (and so a reload can too).
+  const stopped = payload.stopped === 'budget' || payload.stopped === 'max-turns' || payload.stopped === 'blocked' || payload.stopped === 'complete' || payload.stopped === 'audit-failed'
+    ? payload.stopped
+    : undefined;
+  const rawBudget = payload.tokenBudget;
+  const tokenBudget =
+    typeof rawBudget === 'number' && Number.isInteger(rawBudget) && rawBudget > 0 ? rawBudget : undefined;
+  // A per-goal ceiling: the install default is fine until someone wants a
+  // short leash on one objective, and then the number belongs to the goal.
+  const rawMaxTurns = payload.maxTurns;
+  const maxTurns =
+    typeof rawMaxTurns === 'number' && Number.isInteger(rawMaxTurns) && rawMaxTurns > 0 ? rawMaxTurns : undefined;
+  return { objective, tokenBudget, guided, maxTurns, stopped };
+}
+
+/** The record Kabmo mirrors. `enabled` is what decides whether the
+ *  composer's toggle reads as on; a paused goal keeps its record. */
+export function goalStateRecord(session: ModeSession): { goal: GoalRecord | null; enabled: boolean } {
+  const state = session.getGoalModeState?.();
+  if (!state?.goal) return { goal: null, enabled: false };
+  return { goal: state.goal as GoalRecord, enabled: state.enabled };
+}
+
+/**
+ * Create a goal, or resume the paused one.
+ *
+ * `createGoal` refuses a session that already carries a goal — omp throws
+ * "cannot create a new goal because this session already has a goal" for any
+ * status but `dropped`/`complete`. The composer's Goal toggle is a single
+ * button, so pressing it on a paused session must resume rather than fail.
+ */
+export async function createGoalFromSelection(
+  session: ModeSession,
+  input: { objective: string; tokenBudget?: number; maxTurns?: number },
+): Promise<void> {
+  const runtime = session.goalRuntime;
+  if (!runtime) throw new Error('goal runtime unavailable');
+  const existing = session.getGoalModeState?.();
+  if (existing?.goal && existing.goal.status === 'paused') {
+    await runtime.resumeGoal();
+    if (input.maxTurns !== undefined) goalCeilings.set(existing.goal.id, input.maxTurns);
+    return;
+  }
+  const created = (await runtime.createGoal({ objective: input.objective, tokenBudget: input.tokenBudget })) as
+    | { goal?: { id?: string } }
+    | undefined;
+  // The ceiling belongs to the goal, not to the process: remembered by id so
+  // every later decision (and a Resume) reads the same number.
+  const goalId = created?.goal?.id ?? session.getGoalModeState?.()?.goal?.id;
+  if (goalId && input.maxTurns !== undefined) goalCeilings.set(goalId, input.maxTurns);
+}
+
+/**
+ * The turn that makes a freshly created goal actually start.
+ *
+ * `createGoal` only writes the record — it opens no turn, so a goal created
+ * here sat live with an idle child until the operator happened to send
+ * something else, which is not "keeps working across turns". omp's own
+ * `/goal <objective>` path does both (`#zs`: `#Tn({objective})` then a prompt
+ * with the objective as text), and this is that second half.
+ *
+ * Sent as a hidden custom message rather than through the RPC prompt path: the
+ * Kabmo cannot reach the live session's prompt, and `display: false` is what
+ * keeps the objective out of the transcript as a second user bubble.
+ */
+export function startGoalTurn(api: ModeApi, objective: string): void {
+  api.sendMessage?.({ customType: GOAL_START_TYPE, content: objective, display: false }, { triggerTurn: true });
+}
+
+/**
+ * Start the guided-goal interview.
+ *
+ * A normal conversation with a hidden kickoff: the agent asks its questions as
+ * ordinary assistant turns, the operator answers in the composer, and the model
+ * closes by calling `goal({op:"create"})` itself — which flips goal mode on
+ * through `goal_updated`. The `goal` tool must already be active, which is what
+ * the caller's `ensureGoalTool` provides.
+ */
+export function startGuidedGoal(api: ModeApi, rough: string): void {
+  const content = renderPrompt(GUIDED_GOAL_INTERVIEW_PROMPT, { initial: rough || undefined });
+  api.sendMessage?.({ customType: GUIDED_GOAL_TYPE, content, display: false }, { triggerTurn: true });
+}
+
+/**
+ * The loop's per-session counters, kept where the other process-wide state is:
+ * a `bun --hot` reload must not lose the turn count, and the ceiling is the only
+ * thing standing between `budget off` and an unbounded run.
+ */
+const turnCounters = new Map<string, number>();
+
+function turnsFor(goalId: string): number {
+  return turnCounters.get(goalId) ?? 0;
+}
+
+/** What Kabmo's goal driver needs to open one more turn. */
+export interface GoalTurnRequest {
+  api: ModeApi;
+  session: ModeSession;
+  emit: (ctx: ExtensionCtx, marker: string, payload: unknown) => void;
+  ctx: ExtensionCtx;
+  /** The goal's ceiling as Kabmo persisted it; beats this process's own
+   *  memory, which a restart (or another instance) never had. */
+  maxTurns?: number;
+}
+
+/**
+ * Open the next automatic turn, at Kabmo's request.
+ *
+ * The Kabmo owns the loop now: it audits the last turn with an independent
+ * model and calls this to continue. What stays here is everything Kabmo
+ * cannot do or see — the hidden message that re-enters the loop without leaving
+ * a user bubble, the per-goal turn count, and the two hard stops (token budget,
+ * turn ceiling) that must hold even if Kabmo is restarted mid-run.
+ */
+export function continueGoalTurn({ api, session, emit, ctx, maxTurns }: GoalTurnRequest): void {
+  const state = session.getGoalModeState?.();
+  // A ceiling Kabmo remembers (persisted with the goal) wins: this
+  // process's map is empty after a restart, and the goal's own number must not
+  // be lost to that.
+  if (state?.goal && maxTurns !== undefined) goalCeilings.set(state.goal.id, maxTurns);
+  const ceiling = state?.goal ? ceilingFor(state.goal.id) : DEFAULT_MAX_TURNS;
+
+  const standDown = (stopped: GoalContinuationStop, turns: number): void => {
+    const verdict: GoalContinuation = { turn: Math.max(1, turns), maxTurns: ceiling, stopped };
+    emit(ctx, KABMO_GOAL_EVALUATING_MARKER, { evaluating: false, stopped });
+    emit(ctx, KABMO_GOAL_CONTINUATION_MARKER, verdict);
+    persistContinuation(api, session, verdict, ceiling);
+  };
+
+  // omp flips the goal to `budget-limited` the moment the budget is spent, so
+  // the loop never sees an `active` goal to decide about — this is the only
+  // place that can report it. Without this the row showed a budget-limited goal
+  // in silence, indistinguishable from one waiting for the next turn.
+  if (state?.enabled && state.goal.status === 'budget-limited') {
+    standDown('budget', turnsFor(state.goal.id));
+    return;
+  }
+  if (!state?.enabled || state.goal.status !== 'active') return;
+
+  if (continuationTurnsReset) {
+    continuationTurnsReset = false;
+    turnCounters.delete(state.goal.id);
+  }
+  let turns = turnsFor(state.goal.id);
+
+  const goal = state.goal as GoalRecord;
+  const budget = goal.tokenBudget;
+  // The hard stops, checked here because THIS process is the one that has to
+  // stop: Kabmo's auditor decides progress, never the ceilings.
+  if (budget !== undefined && goal.tokensUsed >= budget) {
+    standDown('budget', turns);
+    return;
+  }
+  if (turns >= ceiling) {
+    standDown('max-turns', turns);
+    return;
+  }
+
+  turns += 1;
+  turnCounters.set(state.goal.id, turns);
+  const verdict: GoalContinuation = { turn: turns, maxTurns: ceiling };
+  emit(ctx, KABMO_GOAL_CONTINUATION_MARKER, verdict);
+  // Persisted on the way IN as well: the turn number is what a reload shows
+  // until the loop reports again, and the ceiling rides with it so a resumed
+  // process reads the goal's own number instead of the install default.
+  persistContinuation(api, session, verdict, ceiling);
+  const content = renderPrompt(GOAL_CONTINUATION_PROMPT, {
+    objective: goal.objective,
+    tokensUsed: goal.tokensUsed,
+    tokenBudget: budget === undefined ? 'none' : budget,
+    remainingTokens: budget === undefined ? 'unbounded' : Math.max(0, budget - goal.tokensUsed),
+    timeUsedSeconds: goal.timeUsedSeconds,
+  });
+  api.sendMessage?.({ customType: GOAL_CONTINUATION_TYPE, content, display: false }, { triggerTurn: true });
+}
+
+/**
+ * Close the loop with a verdict the AUDITOR reached (`complete`, `blocked`, or
+ * an audit that could not be taken). The goal record itself is omp's — this
+ * only records why Kabmo stopped driving it, so the strip can name it and
+ * a reload can show it.
+ */
+export function finishGoalTurn({ api, session, emit, ctx }: GoalTurnRequest, stopped: GoalContinuationStop): void {
+  const state = session.getGoalModeState?.();
+  const ceiling = state?.goal ? ceilingFor(state.goal.id) : DEFAULT_MAX_TURNS;
+  const turns = state?.goal ? turnsFor(state.goal.id) : 0;
+  const verdict: GoalContinuation = { turn: Math.max(1, turns), maxTurns: ceiling, stopped };
+  emit(ctx, KABMO_GOAL_CONTINUATION_MARKER, verdict);
+  persistContinuation(api, session, verdict, ceiling);
+}

package/extensions/kabmo-modes/index.ts

@@ -0,0 +1,272 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Plan- and Goal-mode actuation for Kabmo, running INSIDE the omp child.
+ *
+ * Why an extension: omp exposes neither mode over RPC. `RpcCommand` has no
+ * plan/goal verb, `/plan` and `/goal` are `handleTui`-only (a prompt carrying
+ * one reaches the model as literal text — measured), `mode_change` entries are
+ * not restored under `--mode rpc-ui`, and `plan.defaultOnStartup` is read by
+ * `interactive-mode.ts` alone. The extension API is the one surface that
+ * reaches the live `AgentSession`, so Kabmo ships this file and the spawn
+ * path passes it with `-e <abs path>`.
+ *
+ * Why `-e` and not `~/.omp/agent/extensions/`: Kabmo owns this file. An
+ * install there would mutate the user's config, could be disabled from the
+ * Settings → Extensions list, and would leave a stale copy behind on upgrade.
+ * An explicit `-e` is also still honoured under `--no-extensions`.
+ *
+ * Control surface: one command, `/kabmo-mode <scope> <action> [json]`,
+ * dispatched by Kabmo as an ordinary prompt. Measured: the command runs
+ * locally, answers `agentInvoked: false`, and writes NO user message to the
+ * transcript — so the mode controls never appear as conversation.
+ *
+ * Every outcome is reported through a notice MARKER (`KABMO_*_MARKER`), which
+ * is how Kabmo learns the new state without polling: the frames reach it
+ * over the same event stream the transcript uses.
+ */
+
+import {
+  activeSession,
+  bindApi,
+  ensureGoalTool,
+  enterPlanMode,
+  modeCapabilities,
+  recordPlanState,
+  type ExtensionCtx,
+  type ModeApi,
+} from './session';
+import { dispatchGoal, dispatchPlan, emit } from './commands';
+import {
+  CHAMBER_MODE_COMMAND,
+  CHAMBER_MODES_ENV,
+  KABMO_GOAL_STATE_ENTRY,
+  KABMO_GOAL_STATE_MARKER,
+  KABMO_MODE_COMMAND,
+  KABMO_MODE_ERROR_MARKER,
+  KABMO_PLAN_DECISION_MARKER,
+  KABMO_PLAN_STATE_MARKER,
+  KABMO_MODES_ENV,
+  type GoalRecord,
+} from './protocol';
+import { goalStateRecord } from './goal';
+import { installPlanProposal } from './plan';
+import { peekParkedProposal, releaseForRefinement } from './parked';
+
+
+function parseModesEnv(): { plan: boolean; goal: boolean } {
+  // Both spellings: this build's spawn path exports `KABMO_MODES`, and a child
+  // started by a pre-rename Kabmo (or by a hand-written environment) carries
+  // `CHAMBER_MODES`. Reading only the new one would reopen that session with
+  // both modes off and the composer's toggles lying.
+  const raw = process.env?.[KABMO_MODES_ENV] ?? process.env?.[CHAMBER_MODES_ENV] ?? '';
+  return { plan: raw.includes('plan'), goal: raw.includes('goal') };
+}
+
+/**
+ * Re-apply Kabmo's persisted mode selection to a freshly spawned child.
+ *
+ * `--mode rpc-ui` never restores `mode_change`, so a session reopened from the
+ * sidebar would otherwise come back with both modes off and the composer's
+ * toggles lying. The flags ride in the spawn environment, which is the only
+ * channel available before the child's first command.
+ */
+async function restoreModes(api: ModeApi, ctx: ExtensionCtx): Promise<void> {
+  const wanted = parseModesEnv();
+  if (!wanted.plan && !wanted.goal) return;
+  const session = activeSession(api);
+  if (!session) return;
+  const caps = modeCapabilities(session);
+
+  // Both flags can only arrive from a record written before the modes were
+  // mutually exclusive. Plan wins: it is the passive one, while a restored goal
+  // is what Kabmo's driver keeps opening turns for.
+  const bothWanted = wanted.plan && wanted.goal;
+  if (bothWanted) {
+    emit(ctx, KABMO_MODE_ERROR_MARKER, {
+      reason: 'This session recorded both plan mode and a goal; plan mode was restored and the goal was left off.',
+    });
+  }
+
+  if (wanted.plan) {
+    if (!caps.plan) emit(ctx, KABMO_MODE_ERROR_MARKER, { reason: 'plan-mode API missing in this omp build' });
+    else {
+      const planFilePath = session.getPlanReferencePath?.() || 'local://PLAN.md';
+      await enterPlanMode(session, planFilePath);
+      installPlanProposal(session, ctx);
+      // The persisted record too, not just the live marker. `enterPlanMode`
+      // writes omp's own `mode_change`, which `--mode rpc-ui` never restores,
+      // and the spawn env is what re-applied the flag — so without this entry a
+      // reloaded session's JSONL still said "plan off" while the child was in
+      // plan mode, and the NEXT spawn read the stale record and came up with
+      // plan mode off. Measured: plan on → toggle off before any turn → toggle
+      // on again → the second spawn reported `plan: null`.
+      recordPlanState(api, true);
+      emit(ctx, KABMO_PLAN_STATE_MARKER, { enabled: true, planFilePath });
+    }
+  }
+  if (wanted.goal && !bothWanted) {
+    if (!caps.goal) emit(ctx, KABMO_MODE_ERROR_MARKER, { reason: 'goal-mode API missing in this omp build' });
+    else {
+      // The tool is enabled so the toggle can act immediately, but a restored
+      // goal is deliberately NOT resumed: omp pauses an active goal on a cold
+      // start precisely so it cannot resume unattended, and overriding that
+      // would start spending tokens the moment someone opened the tab. The
+      // state is reported as paused, and the composer's Resume is what restarts
+      // it — the same decision omp made, surfaced instead of undone.
+      await ensureGoalTool(api, session);
+      emit(ctx, KABMO_GOAL_STATE_MARKER, goalStateRecord(session));
+    }
+  }
+}
+
+/** The extension entry: registers `/kabmo-mode`, omp's own command aliases,
+ *  and the session/goal event handlers. */
+export default function kabmoModes(api: ModeApi): void {
+  bindApi(api);
+
+  /**
+   * One handler, registered under BOTH names.
+   *
+   * `kabmo-mode` is what this build's server sends. `chamber-mode` is the
+   * pre-rename spelling, and it stays registered because the console that sends
+   * it may still be the one an operator has open: a host that upgraded while a
+   * tab was live keeps posting the old token until the page reloads, and an
+   * unknown command there is a Plan/Goal toggle that does nothing.
+   */
+  const modeHandler = async (args: string, ctx: ExtensionCtx) => {
+    const trimmed = args.trim();
+    const [scopeToken = '', actionToken = '', ...tail] = trimmed.split(/\s+/);
+    const scope = scopeToken.toLowerCase();
+    const action = actionToken.toLowerCase();
+    const rest = tail.join(' ');
+
+    const session = activeSession(api);
+    if (!session) {
+      emit(ctx, KABMO_MODE_ERROR_MARKER, { reason: 'no live session found for this process' });
+      return;
+    }
+    if (scope === 'plan') await dispatchPlan(api, session, ctx, action, rest);
+    else if (scope === 'goal') await dispatchGoal(api, session, ctx, action, rest);
+    else emit(ctx, KABMO_MODE_ERROR_MARKER, { reason: `unknown scope: ${scope || '(empty)'}` });
+  };
+
+  const modeDescription = 'Kabmo plan/goal mode control (driven by the web console, not typed by hand)';
+  api.registerCommand?.(KABMO_MODE_COMMAND, { description: modeDescription, handler: modeHandler });
+  api.registerCommand?.(CHAMBER_MODE_COMMAND, { description: modeDescription, handler: modeHandler });
+
+  // The DOCS' own syntax, answered by the same code path.
+  //
+  // omp implements `/plan` and `/goal` with `handleTui` only, so a typed one
+  // would otherwise reach the model as literal text. Now that Kabmo owns
+  // these modes, a typed command is a real command: `/plan` toggles, `/goal`
+  // opens the objective editor, and the subcommands the docs list are accepted.
+  api.registerCommand?.('plan', {
+    description: 'Toggle plan mode (agent plans before executing)',
+    handler: async (args: string, ctx: ExtensionCtx) => {
+      const session = activeSession(api);
+      if (!session) {
+        emit(ctx, KABMO_MODE_ERROR_MARKER, { reason: 'no live session found for this process' });
+        return;
+      }
+      const objective = args.trim();
+      if (session.getPlanModeState?.()?.enabled && !objective) {
+        await dispatchPlan(api, session, ctx, 'off', '');
+        return;
+      }
+      await dispatchPlan(api, session, ctx, 'on', '');
+      // A prompt alongside `/plan` is the FIRST plan-mode turn, which is what
+      // the docs describe; send it as an ordinary prompt now that the mode is on.
+      if (objective) await session.prompt?.(objective);
+    },
+  });
+
+  api.registerCommand?.('goal', {
+    description: 'Toggle goal mode (persistent autonomous objective for this session)',
+    handler: async (args: string, ctx: ExtensionCtx) => {
+      const session = activeSession(api);
+      if (!session) {
+        emit(ctx, KABMO_MODE_ERROR_MARKER, { reason: 'no live session found for this process' });
+        return;
+      }
+      const trimmed = args.trim();
+      const [sub = '', ...tail] = trimmed.split(/\s+/);
+      const rest = tail.join(' ');
+      switch (sub.toLowerCase()) {
+        case '':
+          // No argument: report the state so the operator sees where they are
+          // instead of silently toggling a mode that needs an objective.
+          emit(ctx, KABMO_GOAL_STATE_MARKER, goalStateRecord(session));
+          return;
+        case 'show':
+        case 'state':
+          emit(ctx, KABMO_GOAL_STATE_MARKER, goalStateRecord(session));
+          return;
+        case 'pause':
+          await dispatchGoal(api, session, ctx, 'pause', '');
+          return;
+        case 'resume':
+          await dispatchGoal(api, session, ctx, 'resume', '');
+          return;
+        case 'drop':
+          await dispatchGoal(api, session, ctx, 'drop', '');
+          return;
+        case 'budget':
+          await dispatchGoal(api, session, ctx, 'budget', rest);
+          return;
+        case 'set':
+        default:
+          // `/goal <objective>` and `/goal set <objective>` are the same thing;
+          // a bare `/goal set` with no text reports the state rather than
+          // creating a goal with an empty objective.
+          if (!rest.trim()) {
+            emit(ctx, KABMO_GOAL_STATE_MARKER, goalStateRecord(session));
+            return;
+          }
+          await dispatchGoal(api, session, ctx, 'create', JSON.stringify({ objective: rest.trim() }));
+      }
+    },
+  });
+
+  api.on?.('session_start', async (_event: unknown, ctx: ExtensionCtx) => {
+    await restoreModes(api, ctx);
+  });
+
+  // A run that ended while a review was still parked means the tool call is
+  // gone — Stop/abort is the only way in, since omp does NOT clear the proposal
+  // handler when it interrupts (`setPlanProposalHandler(null)` appears only on
+  // the plan-yolo approval path). Measured: after an abort the child reported
+  // idle while the slot still held the plan, so `republish` kept re-announcing a
+  // review nobody was waiting on and the composer's panel stayed up over a
+  // finished run.
+  //
+  // Releasing is the same refinement `plan off` performs: the model learns the
+  // review was abandoned rather than the operator's choice being invented. The
+  // `clear: true` teardown would ALSO uninstall the handler, which a still-active
+  // plan mode needs for the next `xd://propose`.
+  api.on?.('agent_end', (event: unknown, ctx: ExtensionCtx) => {
+    // A run that already scheduled a continuation is not over; its tool call may
+    // still be the parked one.
+    if ((event as { willContinue?: boolean }).willContinue === true) return;
+    if (!peekParkedProposal()) return;
+    releaseForRefinement('The run was interrupted before the plan was reviewed.');
+    emit(ctx, KABMO_PLAN_DECISION_MARKER, { choice: 'Interrupted', title: '' });
+  });
+
+  // omp's own goal transitions are authoritative: Kabmo mirrors them and
+  // persists the record so a reload can recover the goal without re-reading
+  // `mode_change` (which rpc-ui never restores).
+  api.on?.('goal_updated', (event: unknown, ctx: ExtensionCtx) => {
+    const payload = event as { goal?: GoalRecord | null; state?: { enabled?: boolean } | null };
+    const record = { goal: payload.goal ?? null, enabled: payload.state?.enabled === true };
+    // One record per transition, so Kabmo's goal driver reads the state
+    // it audits (and a reload recovers it) no matter who moved the goal: the
+    // composer, the MODEL calling `goal({op:"create"})` after a guided
+    // interview, or omp's own `/goal` typed in a TUI on the same session.
+    api.appendEntry?.(KABMO_GOAL_STATE_ENTRY, record);
+    emit(ctx, KABMO_GOAL_STATE_MARKER, record);
+  });
+}

package/extensions/kabmo-modes/omp-modules.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Ambient declarations for the oh-my-pi modules the mode extension imports.
+ *
+ * The extension runs INSIDE an omp child process, where `@oh-my-pi/pi-coding-agent`
+ * resolves from omp's own install — but Kabmo's `tsc` runs in Kabmo
+ * checkout, where that package is not a dependency and its `exports` map is
+ * therefore unresolvable. Declaring the two members actually used keeps
+ * `bun run lint` honest about the extension's own code without making the
+ * Kabmo's typecheck depend on a globally-installed package (a machine-specific
+ * `paths` entry pointing at the global install would break on every other
+ * machine, including CI).
+ *
+ * Only the surface this directory touches is declared. Adding a member here is
+ * the deliberate act of depending on one more piece of omp's internals.
+ */
+
+declare module '@oh-my-pi/pi-coding-agent/internal-urls' {
+  /** omp's `local://` root for a session: `<artifactsDir>/local` when the
+   *  session exposes an artifacts dir, else a temp directory keyed by session
+   *  id. Verified against omp 18.4.4. */
+  export function resolveLocalRoot(options: unknown): string;
+}