march-cli 0.1.12 → 0.1.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "march-cli",
-  "version": "0.1.12",
+  "version": "0.1.14",
   "description": "March CLI — terminal-native coding agent with context reconstruction",
   "type": "module",
   "main": "./src/main.mjs",
@@ -14,6 +14,7 @@
   "scripts": {
     "dev": "cd .. && node march-cli/bin/march.mjs",
     "test": "node test/smoke.test.mjs",
+    "test:fast": "node test/fast.test.mjs",
     "test:real": "npm run test:shell-runtime-real && npm run test:shell-tui-real && npm run test:tui-key-real",
     "test:shell-runtime-real": "node test/shell-real-runtime.acceptance.mjs",
     "test:shell-tui-real": "node test/shell-tui-real.acceptance.mjs",

package/src/agent/command-exec-tool.mjs

@@ -1,4 +1,4 @@
-import { spawnSync } from "node:child_process";
+import { spawn, spawnSync } from "node:child_process";
 import { existsSync } from "node:fs";
 import { defineTool } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
@@ -21,23 +21,22 @@ export function createCommandExecTool({ cwd }) {
   });
 }
 
-export function executeCommand({ cwd, command, shell = "auto", timeout = 60, spawnSyncImpl = spawnSync }) {
+export async function executeCommand({ cwd, command, shell = "auto", timeout = 60, spawnImpl = spawn }) {
   let resolved;
   try {
     resolved = resolveCommandShell(shell);
   } catch (err) {
     return toolText(`Error: ${err.message}`, { error: true });
   }
-  const result = spawnSyncImpl(resolved.bin, [...resolved.args, String(command ?? "")], {
+
+  const timeoutMs = Math.max(1, Number(timeout) || 60) * 1000;
+  const result = await spawnCommand(spawnImpl, resolved.bin, [...resolved.args, String(command ?? "")], {
     cwd,
-    encoding: "utf8",
-    timeout: Math.max(1, Number(timeout) || 60) * 1000,
+    timeoutMs,
     windowsHide: true,
-    maxBuffer: OUTPUT_LIMIT,
   });
   if (result.error) {
-    const isTimeout = result.error.code === "ETIMEDOUT" || result.signal === "SIGTERM";
-    const detail = isTimeout ? ` (timed out after ${timeout}s)` : "";
+    const detail = result.timedOut ? ` (timed out after ${timeout}s)` : "";
     return toolText(`Error: ${result.error.message}${detail}`, { error: true });
   }
   const stdout = stripAnsi(result.stdout ?? "");
@@ -52,6 +51,41 @@ export function executeCommand({ cwd, command, shell = "auto", timeout = 60, spa
   });
 }
 
+function spawnCommand(spawnImpl, bin, args, options) {
+  return new Promise((resolve) => {
+    let stdout = "";
+    let stderr = "";
+    let settled = false;
+    let timedOut = false;
+    const child = spawnImpl(bin, args, { cwd: options.cwd, windowsHide: options.windowsHide });
+    const timer = setTimeout(() => {
+      timedOut = true;
+      child.kill?.("SIGTERM");
+    }, options.timeoutMs);
+    timer.unref?.();
+
+    child.stdout?.setEncoding?.("utf8");
+    child.stderr?.setEncoding?.("utf8");
+    child.stdout?.on?.("data", (chunk) => { stdout = appendLimited(stdout, chunk); });
+    child.stderr?.on?.("data", (chunk) => { stderr = appendLimited(stderr, chunk); });
+    child.once?.("error", (error) => finish({ error }));
+    child.once?.("close", (status, signal) => finish({ status, signal }));
+
+    function finish(result) {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      const error = result.error ?? (timedOut ? Object.assign(new Error("Command timed out"), { code: "ETIMEDOUT" }) : null);
+      resolve({ ...result, error, stdout, stderr, timedOut });
+    }
+  });
+}
+
+function appendLimited(current, chunk) {
+  const next = current + String(chunk ?? "");
+  return next.length <= OUTPUT_LIMIT ? next : next.slice(-OUTPUT_LIMIT);
+}
+
 export function resolveCommandShell(shell = "auto", platform = process.platform) {
   const normalized = String(shell ?? "auto").trim().toLowerCase();
   if (normalized === "powershell" || (normalized === "auto" && platform === "win32")) {

package/src/agent/{read-file-tool.mjs → file-tools/read-file-tool.mjs}

@@ -2,7 +2,7 @@ import { readFileSync, readdirSync, statSync } from "node:fs";
 import { resolve } from "node:path";
 import { defineTool } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
-import { toolText } from "./tool-result.mjs";
+import { toolText } from "../tool-result.mjs";
 
 const DEFAULT_LIMIT = 30;
 const DEFAULT_DIRECTORY_LIMIT = 200;
@@ -47,7 +47,7 @@ export function readFileSlice({ engine, path, offset = 1, limit = DEFAULT_LIMIT
   const count = clampLimit(limit);
   const selected = lines.slice(start - 1, start - 1 + count);
   const end = start + selected.length - 1;
-  const body = selected.map((line, index) => `${start + index} | ${line}`).join("\n");
+  const body = selected.map((line, index) => `${start + index}| ${line}`).join("\n");
   const header = `--- ${absPath} (lines ${start}-${end} of ${lines.length}) ---`;
   const remaining = lines.length - end;
   const footer = remaining > 0 ? `\n\n[${remaining} more lines in file. Use offset=${end + 1} to continue.]` : "";

package/src/agent/file-tools/read-image-tool.mjs

@@ -0,0 +1,76 @@
+import { readFileSync, statSync } from "node:fs";
+import { extname } from "node:path";
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { currentModelImageInputError } from "../vision-capability.mjs";
+const IMAGE_MIME_BY_EXT = new Map([
+  [".png", "image/png"],
+  [".jpg", "image/jpeg"],
+  [".jpeg", "image/jpeg"],
+  [".webp", "image/webp"],
+  [".gif", "image/gif"],
+]);
+
+export function createReadImageTool({ engine, getCurrentModel = null }) {
+  return defineTool({
+    name: "read_image",
+    label: "Read Image",
+    description: "Read a local image file and send it to the model as an image attachment. Supports png, jpg/jpeg, webp, and gif.",
+    parameters: Type.Object({
+      path: Type.String({ description: "Absolute or relative path to the image file" }),
+    }),
+    execute: async (_toolCallId, params) => {
+      const capabilityError = currentModelImageInputError(getCurrentModel);
+      if (capabilityError) return imageError(capabilityError, { unsupportedModel: true });
+      return readImageFile({ engine, ...params });
+    },
+  });
+}
+
+export function readImageFile({ engine, path }) {
+  const absPath = engine.resolvePath(path);
+  let stat;
+  try {
+    stat = statSync(absPath);
+  } catch (err) {
+    return imageError(`Error reading image ${absPath}: ${err.message}`, { path: absPath });
+  }
+  if (stat.isDirectory()) {
+    return imageError(`Error reading image ${absPath}: this is a directory. Use ls(path) or find(pattern, path) to inspect it.`, { path: absPath, isDirectory: true });
+  }
+
+  const mimeType = IMAGE_MIME_BY_EXT.get(extname(absPath).toLowerCase());
+  if (!mimeType) {
+    return imageError(`Error reading image ${absPath}: unsupported image type. Supported types: png, jpg, jpeg, webp, gif.`, { path: absPath });
+  }
+
+  let data;
+  try {
+    data = readFileSync(absPath).toString("base64");
+  } catch (err) {
+    return imageError(`Error reading image ${absPath}: ${err.message}`, { path: absPath });
+  }
+
+  const size = formatSize(stat.size);
+  return {
+    content: [
+      { type: "text", text: `Read image file: ${absPath}\nMIME: ${mimeType}\nSize: ${size}` },
+      { type: "image", data, mimeType },
+    ],
+    details: {
+      path: absPath,
+      mimeType,
+      sizeBytes: stat.size,
+    },
+  };
+}
+
+function imageError(text, details = {}) {
+  return { content: [{ type: "text", text }], details: { ...details, error: true } };
+}
+
+function formatSize(bytes) {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  return `${(bytes / 1024 / 1024).toFixed(1)} MB`;
+}

package/src/agent/runner/runner-utils.mjs

@@ -16,3 +16,9 @@ export async function notifyTurnEndBestEffort(turnNotifier, event) {
     return { ok: false, reason: err?.message ?? String(err), results: [] };
   }
 }
+
+export function notifyTurnEndDetached(turnNotifier, event, onResult = () => {}) {
+  const pending = notifyTurnEndBestEffort(turnNotifier, event);
+  pending.then(onResult, () => {});
+  return pending;
+}

package/src/agent/runner.mjs

@@ -1,8 +1,4 @@
-import {
-  createAgentSession,
-  ModelRegistry,
-  SettingsManager,
-} from "@earendil-works/pi-coding-agent";
+import { createAgentSession, ModelRegistry, SettingsManager } from "@earendil-works/pi-coding-agent";
 import { createMarchAuthStorage } from "../auth/storage.mjs";
 import { ContextEngine } from "../context/engine.mjs";
 import { createMarchLifecycleAdapter } from "../extensions/lifecycle-adapter.mjs";
@@ -14,8 +10,9 @@ import { appendProviderUserMessage, estimateProviderPayloadTokens, installModelP
 import { resolveInitialModel, resolveRunnerSessionManager } from "./runner/runner-init.mjs";
 import { runRunnerCleanup } from "./runner/runner-cleanup.mjs";
 import { createRunnerRuntimeHost } from "./runtime/runner-runtime-host.mjs";
+import { createRuntimeUiBridge } from "./runtime/ui-event-bridge.mjs";
 import { getRunnerSessionStats, syncEngineSessionState } from "./runner/runner-session-state.mjs";
-import { notifyTurnEndBestEffort, providerContextToPayload } from "./runner/runner-utils.mjs";
+import { notifyTurnEndBestEffort, notifyTurnEndDetached, providerContextToPayload } from "./runner/runner-utils.mjs";
 import { resolveRunnerSessionOptions } from "./session/session-options.mjs";
 import { createSessionBinding } from "./session/session-binding.mjs";
 import { maybeAutoNameSession } from "./session/session-auto-name.mjs";
@@ -30,7 +27,7 @@ export { MARCH_BASE_TOOL_NAMES };
 export { installModelPayloadDumper } from "./model-payload-dumper.mjs";
 export { createDefaultSessionManager, resolveRunnerSessionManager } from "./runner/runner-init.mjs";
 export { getRunnerSessionStats, syncEngineSessionState } from "./runner/runner-session-state.mjs";
-export async function createRunner({ cwd, modelId = null, provider = null, providers = {}, stateRoot, ui, memoryRoot = null, centerMemoryPath = null, memoryStore = null, memoryTools = [], shellRuntime = null, mcpTools = [], mcpInjections = [], mcpClientManager = null, webTools = [], namespace = "", sessionManager = null, useRuntimeHost = false, projectMarchDir = null, syncPiSidecar = false, extensionPaths = [], lifecycleHooks = [], lifecycleDiagnostics = [], authStorage = null, permissionController = null, modelContextDumper = null, turnNotifier = null, logger = null, onModelPayload = null, createAgentSessionImpl = createAgentSession, createAgentSessionRuntimeImpl, createRuntimeServices, createRuntimeSessionFromServices, maxTurns, trimBatch, serviceTier = null, hostedTools = {} }) {
+export async function createRunner({ cwd, modelId = null, provider = null, providers = {}, stateRoot, ui, memoryRoot = null, profilePaths = null, memoryStore = null, memoryTools = [], shellRuntime = null, mcpTools = [], mcpInjections = [], mcpClientManager = null, webTools = [], namespace = "", sessionManager = null, useRuntimeHost = false, projectMarchDir = null, syncPiSidecar = false, extensionPaths = [], lifecycleHooks = [], lifecycleDiagnostics = [], authStorage = null, permissionController = null, modelContextDumper = null, turnNotifier = null, logger = null, onModelPayload = null, createAgentSessionImpl = createAgentSession, createAgentSessionRuntimeImpl, createRuntimeServices, createRuntimeSessionFromServices, maxTurns, trimBatch, serviceTier = null, hostedTools = {} }) {
   if (!useRuntimeHost && extensionPaths.length > 0) {
     throw new Error("--extension requires the default pi runtime host path");
   }
@@ -50,8 +47,9 @@ export async function createRunner({ cwd, modelId = null, provider = null, provi
     compaction: { enabled: false },
     retry: { enabled: true, maxRetries: 3, baseDelayMs: 2000 },
   });
-  const lspService = new LspService({ cwd, onEvent: (event) => ui.status?.(formatLspServiceEvent(event)) });
-  const engine = new ContextEngine({ cwd, modelId, provider, namespace, memoryRoot, centerMemoryPath, shellRuntime, lspService, injections: mcpInjections, maxTurns, trimBatch });
+  const { ui: runtimeUi, eventBus: runtimeUiEvents, detach: detachRuntimeUi } = createRuntimeUiBridge(ui);
+  const lspService = new LspService({ cwd, onEvent: (event) => runtimeUi.status?.(formatLspServiceEvent(event)) });
+  const engine = new ContextEngine({ cwd, modelId, provider, namespace, memoryRoot, profilePaths, shellRuntime, lspService, injections: mcpInjections, maxTurns, trimBatch });
   const resolvedSessionManager = resolveRunnerSessionManager(cwd, sessionManager);
   const sessionBinding = createSessionBinding(null);
   let currentModelCallKind = "model", currentTurnId = null;
@@ -68,7 +66,7 @@ export async function createRunner({ cwd, modelId = null, provider = null, provi
       cwd, stateRoot, provider, modelId,
       authStorage: resolvedAuth, settingsManager, modelRegistry,
       providers,
-      sessionManager: resolvedSessionManager, sessionBinding, engine, ui,
+      sessionManager: resolvedSessionManager, sessionBinding, engine, ui: runtimeUi,
       projectMarchDir,
       memoryTools, memoryStore, shellRuntime, lspService, mcpTools, webTools,
       permissionController, extensionPaths, hostedTools,
@@ -82,9 +80,10 @@ export async function createRunner({ cwd, modelId = null, provider = null, provi
     });
   } else {
     const sessionOptions = resolveRunnerSessionOptions({
-      cwd, provider, modelId, modelRegistry, engine, ui,
+      cwd, provider, modelId, modelRegistry, engine, ui: runtimeUi,
       memoryTools, shellRuntime, lspService, mcpTools, webTools, permissionController,
       authStorage: resolvedAuth, projectMarchDir,
+      getCurrentModel: () => sessionBinding.get()?.model ?? selectedModel,
     });
     const { session } = await createAgentSessionImpl({
       cwd, agentDir: stateRoot, ...sessionOptions,
@@ -109,6 +108,7 @@ export async function createRunner({ cwd, modelId = null, provider = null, provi
     engine,
     get session() { return sessionBinding.get(); },
     shellRuntime,
+    runtimeUiEvents,
     async runTurn(prompt, userMessage, { userRecallHints = [], currentProject = "" } = {}) {
       currentPromptForContext = prompt;
       const contextMode = nextTurnContextMode;
@@ -120,7 +120,7 @@ export async function createRunner({ cwd, modelId = null, provider = null, provi
       try {
         const result = await runRunnerTurn({
           prompt, userMessage, options: { userRecallHints, currentProject },
-          sessionBinding, engine, ui, projectMarchDir, memoryStore,
+          sessionBinding, engine, ui: runtimeUi, projectMarchDir, memoryStore,
           setModelCallKind: (kind) => { currentModelCallKind = kind; },
           logger: turnLog.logger,
           setPhase: turnLog.setPhase,
@@ -129,21 +129,21 @@ export async function createRunner({ cwd, modelId = null, provider = null, provi
           autoNameSession,
           contextMode,
         });
-        lastNotificationResult = await notifyTurnEndBestEffort(turnNotifier, {
+        notifyTurnEndDetached(turnNotifier, {
           status: "success",
           sessionName: engine.sessionName,
           draft: result?.draft ?? "",
           durationMs: Date.now() - turnStartedAt,
-        });
+        }, (notificationResult) => { lastNotificationResult = notificationResult; });
         turnLog.endSuccess(result);
         return result;
       } catch (err) {
-        lastNotificationResult = await notifyTurnEndBestEffort(turnNotifier, {
+        notifyTurnEndDetached(turnNotifier, {
           status: "error",
           sessionName: engine.sessionName,
           errorMessage: err?.message ?? String(err),
           durationMs: Date.now() - turnStartedAt,
-        });
+        }, (notificationResult) => { lastNotificationResult = notificationResult; });
         turnLog.endError(err);
         throw err;
       } finally {
@@ -251,6 +251,7 @@ export async function createRunner({ cwd, modelId = null, provider = null, provi
         () => shellRuntime?.dispose?.() ?? shellRuntime?.killAll?.(),
         () => lspService.dispose(),
         () => mcpClientManager?.disconnectAll?.(),
+        () => detachRuntimeUi(),
       ]);
     },
   };

package/src/agent/runtime/ipc/ipc-peer.mjs

@@ -0,0 +1,99 @@
+const CHANNEL = "march-runtime";
+
+export function createRuntimeIpcPeer({ send, subscribe, target = {}, timeoutMs = 0 } = {}) {
+  if (typeof send !== "function") throw new Error("send is required");
+  if (typeof subscribe !== "function") throw new Error("subscribe is required");
+
+  let nextId = 1;
+  const pending = new Map();
+  const detach = subscribe((message) => handleMessage(message));
+
+  return {
+    call(method, ...args) {
+      const id = nextId++;
+      const result = waitForResult(id, { timeoutMs, pending });
+      send({ channel: CHANNEL, kind: "request", id, method, args });
+      return result;
+    },
+    notify(method, ...args) {
+      send({ channel: CHANNEL, kind: "notify", method, args });
+    },
+    dispose() {
+      detach?.();
+      for (const { reject, timer } of pending.values()) {
+        if (timer) clearTimeout(timer);
+        reject(new Error("runtime IPC peer disposed"));
+      }
+      pending.clear();
+    },
+  };
+
+  async function handleMessage(message) {
+    if (!isRuntimeMessage(message)) return;
+    if (message.kind === "result" || message.kind === "error") {
+      settlePending(message, pending);
+      return;
+    }
+    if (message.kind === "notify") {
+      await invokeTarget(message, target);
+      return;
+    }
+    if (message.kind === "request") {
+      try {
+        const result = await invokeTarget(message, target);
+        send({ channel: CHANNEL, kind: "result", id: message.id, result });
+      } catch (error) {
+        send({ channel: CHANNEL, kind: "error", id: message.id, error: serializeError(error) });
+      }
+    }
+  }
+}
+
+function waitForResult(id, { timeoutMs, pending }) {
+  return new Promise((resolve, reject) => {
+    const timer = timeoutMs > 0
+      ? setTimeout(() => {
+        pending.delete(id);
+        reject(new Error(`runtime IPC request timed out: ${id}`));
+      }, timeoutMs)
+      : null;
+    pending.set(id, { resolve, reject, timer });
+  });
+}
+
+function settlePending(message, pending) {
+  const entry = pending.get(message.id);
+  if (!entry) return;
+  pending.delete(message.id);
+  if (entry.timer) clearTimeout(entry.timer);
+  if (message.kind === "result") {
+    entry.resolve(message.result);
+  } else {
+    entry.reject(deserializeError(message.error));
+  }
+}
+
+async function invokeTarget(message, target) {
+  const method = target[message.method];
+  if (typeof method !== "function") throw new Error(`unknown runtime IPC method: ${message.method}`);
+  return method(...(message.args ?? []));
+}
+
+function isRuntimeMessage(message) {
+  return message?.channel === CHANNEL && typeof message.kind === "string";
+}
+
+function serializeError(error) {
+  return {
+    name: error?.name ?? "Error",
+    message: error?.message ?? String(error),
+    stack: error?.stack,
+  };
+}
+
+function deserializeError(error) {
+  const result = new Error(error?.message ?? "runtime IPC error");
+  result.name = error?.name ?? "Error";
+  if (error?.stack) result.stack = error.stack;
+  return result;
+}

package/src/agent/runtime/ipc/process-ipc-transport.mjs

@@ -0,0 +1,16 @@
+import { createRuntimeIpcPeer } from "./ipc-peer.mjs";
+
+export function createProcessRuntimeIpcPeer({ processLike = process, target = {}, timeoutMs = 0 } = {}) {
+  return createRuntimeIpcPeer({
+    send: (message) => {
+      if (typeof processLike.send !== "function") throw new Error("process IPC send is unavailable");
+      processLike.send(message);
+    },
+    subscribe: (listener) => {
+      processLike.on("message", listener);
+      return () => processLike.off("message", listener);
+    },
+    target,
+    timeoutMs,
+  });
+}

package/src/agent/runtime/remote-runner-client.mjs

@@ -0,0 +1,73 @@
+export function createRemoteRunnerClient(peer, { initialState = null } = {}) {
+  let state = initialState;
+
+  const client = {
+    get engine() { return createEngineFacade(); },
+    get runtimeState() { return state; },
+    async init(options = {}) {
+      state = await peer.call("init", options);
+      return state;
+    },
+    async runTurn(prompt, userMessage, options = {}) {
+      const result = await peer.call("runTurn", prompt, userMessage, options);
+      await refreshState();
+      return result;
+    },
+    abort: () => peer.call("abort"),
+    async cycleModel() { return applyResultWithState(await peer.call("cycleModel")); },
+    async setModel(model) { return applyResultWithState(await peer.call("setModel", model)); },
+    getCurrentModel: () => state?.currentModel ?? null,
+    getScopedModels: () => state?.scopedModels ?? [],
+    getConfiguredProviders: () => state?.configuredProviders ?? [],
+    getSessionStats: () => state?.sessionStats ?? null,
+    async refreshState() { return refreshState(); },
+    getLastNotificationResult: () => peer.call("getLastNotificationResult"),
+    notifyTest: (options) => peer.call("notifyTest", options),
+    estimateContextTokens: (userMessage = "") => peer.call("estimateContextTokens", userMessage),
+    async setSessionName(name) { return applyResultWithState(await peer.call("setSessionName", name)); },
+    canSwitchPiSession: () => Boolean(state?.canSwitchPiSession),
+    async startNewSession() { return applyResultWithState(await peer.call("startNewSession")); },
+    getExtensionDiagnostics: () => state?.extensionDiagnostics ?? [],
+    getExtensionLifecycleState: () => state?.extensionLifecycleState ?? null,
+    getLspStatus: () => state?.lspStatus ?? null,
+    async switchPiSession(sessionPath) { return applyResultWithState(await peer.call("switchPiSession", sessionPath)); },
+    async cycleThinkingLevel() { return applyResultWithState(await peer.call("cycleThinkingLevel")); },
+    getThinkingLevel: () => state?.engine?.thinkingLevel ?? null,
+    async setThinkingLevel(level) { return applyResultWithState(await peer.call("setThinkingLevel", level)); },
+    getAvailableThinkingLevels: () => state?.availableThinkingLevels ?? [],
+    async dispose() {
+      await peer.call("dispose");
+      peer.dispose();
+    },
+  };
+
+  return client;
+
+  async function refreshState() {
+    state = await peer.call("getState");
+    return state;
+  }
+
+  function applyResultWithState(response) {
+    if (response && Object.hasOwn(response, "state")) {
+      state = response.state;
+      return response.result;
+    }
+    return response;
+  }
+
+  function createEngineFacade() {
+    const engine = state?.engine ?? {};
+    return {
+      ...engine,
+      hasRenderedPendingAssistantRecallHints: () => true,
+      takePendingAssistantRecallHints: () => [],
+      peekPendingAssistantRecallHints: () => [],
+      markPendingAssistantRecallHintsRendered: () => {},
+      getRecentRecallMemoryIds: () => [],
+      restoreSession: () => {
+        throw new Error("remote runner session restore is not available");
+      },
+    };
+  }
+}

package/src/agent/runtime/remote-ui-client.mjs

@@ -0,0 +1,19 @@
+export function createRemoteRuntimeUiClient(peer) {
+  return {
+    turnStart: () => peer.notify("uiEvent", { type: "turn_start" }),
+    turnEnd: () => peer.notify("uiEvent", { type: "turn_end" }),
+    assistantReplyEnd: () => peer.notify("uiEvent", { type: "assistant_reply_end" }),
+    textDelta: (delta) => peer.notify("uiEvent", { type: "text_delta", delta }),
+    thinkingStart: () => peer.notify("uiEvent", { type: "thinking_start" }),
+    thinkingDelta: (delta) => peer.notify("uiEvent", { type: "thinking_delta", delta }),
+    thinkingEnd: (tokens) => peer.notify("uiEvent", { type: "thinking_end", tokens }),
+    toolStart: (name, args) => peer.notify("uiEvent", { type: "tool_start", name, args }),
+    toolEnd: (name, isError, result) => peer.notify("uiEvent", { type: "tool_end", name, isError, result }),
+    retryStart: (event) => peer.notify("uiEvent", { type: "retry_start", ...event }),
+    retryEnd: (event) => peer.notify("uiEvent", { type: "retry_end", ...event }),
+    status: (text) => peer.notify("uiEvent", { type: "status", text }),
+    memoryHint: ({ source, hints }) => peer.notify("uiEvent", { type: "memory_hint", source, hints }),
+    editDiff: (path, diffLines) => peer.notify("uiEvent", { type: "edit_diff", path, diffLines }),
+    requestPermission: (request) => peer.call("uiRequest", { type: "permission_request", ...request }),
+  };
+}

package/src/agent/runtime/runner-ipc-target.mjs

@@ -0,0 +1,126 @@
+export function createRunnerIpcTarget({ createRunnerImpl, runnerOptions = {} } = {}) {
+  if (typeof createRunnerImpl !== "function") throw new Error("createRunnerImpl is required");
+
+  let runner = null;
+
+  return {
+    async init(options = {}) {
+      if (runner) return getRunnerState(runner);
+      runner = await createRunnerImpl({ ...runnerOptions, ...options });
+      return getRunnerState(runner);
+    },
+    async runTurn(prompt, userMessage, options = {}) {
+      return getRunner().runTurn(prompt, userMessage, options);
+    },
+    abort() {
+      return getRunner().abort();
+    },
+    async cycleModel() {
+      const result = await getRunner().cycleModel();
+      return { result, state: getRunnerState(runner) };
+    },
+    async setModel(model) {
+      const result = await getRunner().setModel(model);
+      return { result, state: getRunnerState(runner) };
+    },
+    getCurrentModel() {
+      return getRunner().getCurrentModel();
+    },
+    getScopedModels() {
+      return getRunner().getScopedModels();
+    },
+    getConfiguredProviders() {
+      return getRunner().getConfiguredProviders();
+    },
+    getSessionStats() {
+      return getRunner().getSessionStats();
+    },
+    getState() {
+      return getRunnerState(getRunner());
+    },
+    getLastNotificationResult() {
+      return getRunner().getLastNotificationResult();
+    },
+    notifyTest(options) {
+      return getRunner().notifyTest(options);
+    },
+    estimateContextTokens(userMessage = "") {
+      return getRunner().estimateContextTokens(userMessage);
+    },
+    setSessionName(name) {
+      const result = getRunner().setSessionName(name);
+      return { result, state: getRunnerState(runner) };
+    },
+    canSwitchPiSession() {
+      return getRunner().canSwitchPiSession();
+    },
+    async startNewSession() {
+      const result = await getRunner().startNewSession();
+      return { result, state: getRunnerState(runner) };
+    },
+    getExtensionDiagnostics() {
+      return getRunner().getExtensionDiagnostics();
+    },
+    getExtensionLifecycleState() {
+      return getRunner().getExtensionLifecycleState();
+    },
+    getLspStatus() {
+      return getRunner().getLspStatus();
+    },
+    async switchPiSession(sessionPath) {
+      const result = await getRunner().switchPiSession(sessionPath);
+      return { result, state: getRunnerState(runner) };
+    },
+    cycleThinkingLevel() {
+      const result = getRunner().cycleThinkingLevel();
+      return { result, state: getRunnerState(runner) };
+    },
+    getThinkingLevel() {
+      return getRunner().getThinkingLevel();
+    },
+    setThinkingLevel(level) {
+      const result = getRunner().setThinkingLevel(level);
+      return { result, state: getRunnerState(runner) };
+    },
+    getAvailableThinkingLevels() {
+      return getRunner().getAvailableThinkingLevels();
+    },
+    async dispose() {
+      if (!runner) return;
+      const active = runner;
+      runner = null;
+      await active.dispose();
+    },
+  };
+
+  function getRunner() {
+    if (!runner) throw new Error("runtime runner is not initialized");
+    return runner;
+  }
+}
+
+export function getRunnerState(runner) {
+  const currentModel = runner.getCurrentModel?.() ?? null;
+  const scopedModels = runner.getScopedModels?.() ?? [];
+  const thinkingLevel = runner.getThinkingLevel?.() ?? runner.engine?.thinkingLevel ?? null;
+  return {
+    engine: {
+      cwd: runner.engine?.cwd ?? null,
+      modelId: runner.engine?.modelId ?? currentModel?.id ?? null,
+      provider: runner.engine?.provider ?? currentModel?.provider ?? null,
+      thinkingLevel,
+      sessionName: runner.engine?.sessionName ?? "",
+      turns: runner.engine?.turns ?? [],
+    },
+    currentModel,
+    scopedModels,
+    configuredProviders: runner.getConfiguredProviders?.() ?? [],
+    availableThinkingLevels: runner.getAvailableThinkingLevels?.() ?? [],
+    canSwitchPiSession: runner.canSwitchPiSession?.() ?? false,
+    sessionStats: runner.getSessionStats?.() ?? null,
+    lspStatus: runner.getLspStatus?.() ?? null,
+    extensionDiagnostics: runner.getExtensionDiagnostics?.() ?? [],
+    extensionLifecycleState: runner.getExtensionLifecycleState?.() ?? null,
+  };
+}
+