march-cli 0.1.3 → 0.1.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "march-cli",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "March CLI — terminal-native coding agent with context reconstruction",
   "type": "module",
   "main": "./src/main.mjs",
@@ -19,6 +19,7 @@
     "test:shell-tui-real": "node test/shell-tui-real.acceptance.mjs",
     "test:tui-key-real": "node test/tui-key-real.acceptance.mjs",
     "context": "cd .. && node march-cli/bin/march.mjs --dump-context",
+    "notify:experiment": "node scripts/notify-experiment.mjs",
     "publish:env": "node scripts/npm-publish-from-env.mjs"
   },
   "dependencies": {
@@ -28,6 +29,7 @@
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@xterm/headless": "^5.5.0",
     "marked": "^18.0.3",
+    "node-notifier": "^10.0.1",
     "node-pty": "^1.1.0",
     "typebox": "^1.0.58",
     "web-tree-sitter": "^0.26.8"

package/src/agent/runner.mjs

@@ -9,7 +9,7 @@ import { createMarchLifecycleAdapter } from "../extensions/lifecycle-adapter.mjs
 import { syncPiSessionSidecar } from "../session/sidecar-sync.mjs";
 import { LspService } from "../lsp/service.mjs";
 import { formatRecallHints } from "../memory/markdown-store.mjs";
-import { appendProviderUserMessage, installModelPayloadDumper, replaceProviderContextMessages } from "./model-payload-dumper.mjs";
+import { appendProviderUserMessage, estimateProviderPayloadTokens, installModelPayloadDumper, replaceProviderContextMessages } from "./model-payload-dumper.mjs";
 import { resolveInitialModel, resolveRunnerSessionManager } from "./runner/runner-init.mjs";
 import { runRunnerCleanup } from "./runner/runner-cleanup.mjs";
 import { createRunnerRuntimeHost } from "./runtime/runner-runtime-host.mjs";
@@ -21,13 +21,14 @@ import { MARCH_BASE_TOOL_NAMES } from "./tool-names.mjs";
 import { runRunnerTurn } from "./turn/turn-runner.mjs";
 import { appendFastVariants, createFastModelEntry, fromFastEntryModel, isFastProvider } from "./runner/fast-model.mjs";
 import { registerSuperGrokProvider } from "../supergrok/provider.mjs";
+import { registerCustomProviders } from "../provider/custom-provider.mjs";
 
 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, 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, onModelPayload = null, createAgentSessionImpl = createAgentSession, createAgentSessionRuntimeImpl, createRuntimeServices, createRuntimeSessionFromServices, maxTurns, trimBatch, serviceTier = null }) {
+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, onModelPayload = null, createAgentSessionImpl = createAgentSession, createAgentSessionRuntimeImpl, createRuntimeServices, createRuntimeSessionFromServices, maxTurns, trimBatch, serviceTier = null }) {
   if (!useRuntimeHost && extensionPaths.length > 0) {
     throw new Error("--extension requires the default pi runtime host path");
   }
@@ -38,6 +39,7 @@ export async function createRunner({ cwd, modelId = null, provider = null, provi
   const resolvedAuth = authConfig.authStorage;
   const modelRegistry = ModelRegistry.create(resolvedAuth);
   registerSuperGrokProvider(modelRegistry);
+  registerCustomProviders(modelRegistry, providers);
   const selectedModel = resolveInitialModel({ modelRegistry, provider, modelId });
   if (!selectedModel) throw new Error("No authenticated models available. Run: march provider --config");
   provider = selectedModel.provider;
@@ -47,7 +49,7 @@ export async function createRunner({ cwd, modelId = null, provider = null, provi
     retry: { enabled: true, maxRetries: 3, baseDelayMs: 2000 },
   });
   const lspService = new LspService({ cwd });
-  const engine = new ContextEngine({ cwd, modelId, provider, namespace, memoryRoot, shellRuntime, lspService, injections: mcpInjections, maxTurns, trimBatch });
+  const engine = new ContextEngine({ cwd, modelId, provider, namespace, memoryRoot, centerMemoryPath, shellRuntime, lspService, injections: mcpInjections, maxTurns, trimBatch });
   const resolvedSessionManager = resolveRunnerSessionManager(cwd, sessionManager);
   const sessionBinding = createSessionBinding(null);
   let currentModelCallKind = "model";
@@ -55,6 +57,7 @@ export async function createRunner({ cwd, modelId = null, provider = null, provi
   let currentTurnContextMode = "rebuild";
   let nextTurnContextMode = "rebuild";
   let pendingMidTurnRecallHints = [];
+  let lastNotificationResult = null;
   let runtimeHost = null;
   let lifecycleAdapter = null;
   let _currentFastEntry = null;
@@ -62,6 +65,7 @@ export async function createRunner({ cwd, modelId = null, provider = null, provi
     runtimeHost = await createRunnerRuntimeHost({
       cwd, stateRoot, provider, modelId,
       authStorage: resolvedAuth, settingsManager, modelRegistry,
+      providers,
       sessionManager: resolvedSessionManager, sessionBinding, engine, ui,
       projectMarchDir,
       memoryTools, memoryStore, shellRuntime, lspService, mcpTools, webTools,
@@ -109,6 +113,7 @@ export async function createRunner({ cwd, modelId = null, provider = null, provi
       currentTurnContextMode = contextMode;
       nextTurnContextMode = "rebuild";
       pendingMidTurnRecallHints = [];
+      const turnStartedAt = Date.now();
       try {
         const result = await runRunnerTurn({
           prompt, userMessage, options: { userRecallHints, currentProject },
@@ -119,17 +124,19 @@ export async function createRunner({ cwd, modelId = null, provider = null, provi
           autoNameSession,
           contextMode,
         });
-        await notifyTurnEndBestEffort(turnNotifier, {
+        lastNotificationResult = await notifyTurnEndBestEffort(turnNotifier, {
           status: "success",
           sessionName: engine.sessionName,
           draft: result?.draft ?? "",
+          durationMs: Date.now() - turnStartedAt,
         });
         return result;
       } catch (err) {
-        await notifyTurnEndBestEffort(turnNotifier, {
+        lastNotificationResult = await notifyTurnEndBestEffort(turnNotifier, {
           status: "error",
           sessionName: engine.sessionName,
           errorMessage: err?.message ?? String(err),
+          durationMs: Date.now() - turnStartedAt,
         });
         throw err;
       } finally {
@@ -176,6 +183,20 @@ export async function createRunner({ cwd, modelId = null, provider = null, provi
       return [...new Set([...configured, ...available])];
     },
     getSessionStats() { return getRunnerSessionStats(sessionBinding.get(), runtimeHost); },
+    getLastNotificationResult() { return lastNotificationResult; },
+    async notifyTest({ title = "March", message = "If you see this, March runtime notifications work." } = {}) {
+      lastNotificationResult = await notifyTurnEndBestEffort(turnNotifier, {
+        status: "success",
+        sessionName: engine.sessionName,
+        title,
+        message,
+        durationMs: 0,
+      });
+      return lastNotificationResult;
+    },
+    estimateContextTokens(userMessage = "") {
+      return estimateProviderPayloadTokens(providerContextToPayload(engine.buildProviderContext(userMessage)));
+    },
     setSessionName(name) {
       const activeSession = sessionBinding.get();
       activeSession.setSessionName?.(name);
@@ -256,11 +277,21 @@ export async function createRunner({ cwd, modelId = null, provider = null, provi
   }
 }
 
+function providerContextToPayload(providerContext) {
+  return {
+    messages: [
+      { role: "system", content: providerContext.system },
+      ...(providerContext.userMessages ?? []).map((message) => ({ role: "user", content: message.content })),
+    ],
+  };
+}
+
 async function notifyTurnEndBestEffort(turnNotifier, event) {
-  if (!turnNotifier?.notifyTurnEnd) return;
+  if (!turnNotifier?.notifyTurnEnd) return { ok: false, reason: "not-configured", results: [] };
   try {
-    await turnNotifier.notifyTurnEnd(event);
-  } catch {
+    return await turnNotifier.notifyTurnEnd(event);
+  } catch (err) {
     // Notification must never change turn behavior.
+    return { ok: false, reason: err?.message ?? String(err), results: [] };
   }
 }

package/src/agent/runtime/runner-runtime-host.mjs

@@ -3,6 +3,7 @@ import { createMarchRuntimeFactory } from "./runtime-factory.mjs";
 import { createRuntimeHost } from "./runtime-host.mjs";
 import { resolveRunnerSessionOptions } from "../session/session-options.mjs";
 import { registerSuperGrokProvider } from "../../supergrok/provider.mjs";
+import { registerCustomProviders } from "../../provider/custom-provider.mjs";
 
 export async function createRunnerRuntimeHost({
   cwd,
@@ -12,6 +13,7 @@ export async function createRunnerRuntimeHost({
   authStorage,
   settingsManager,
   modelRegistry,
+  providers = {},
   sessionManager,
   sessionBinding,
   engine,
@@ -42,6 +44,7 @@ export async function createRunnerRuntimeHost({
     resolveSessionOptions: ({ cwd: sessionCwd, services }) => {
       const activeModelRegistry = services.modelRegistry ?? modelRegistry;
       registerSuperGrokProvider(activeModelRegistry);
+      registerCustomProviders(activeModelRegistry, providers);
       return resolveRunnerSessionOptions({
         cwd: sessionCwd,
         provider,

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

@@ -16,7 +16,10 @@ export async function runRunnerTurn({
   autoNameSession,
   contextMode = "rebuild",
 }) {
-  const { userRecallHints = [], currentProject = "" } = options;
+  const {
+    userRecallHints = [],
+    currentProject = "",
+  } = options;
   const activeSession = sessionBinding.get();
   const turnState = createTurnEventState();
   const midTurnRecallHints = [];
@@ -50,20 +53,19 @@ export async function runRunnerTurn({
       setModelCallKind("model");
     }
 
-    closeAssistantReply({ ui, state: turnState });
-    const assistantRecallHints = flushAssistantRecall({ memoryStore, engine, turnState, currentProject });
-    engine.setPendingAssistantRecallHints?.(assistantRecallHints);
-    const recordedAssistantRecallHints = uniqueHints([...midTurnRecallHints, ...assistantRecallHints]);
-
-    engine.recordTurn({
-      userMessage: userMessage ?? prompt.slice(0, 300),
-      assistantMessage: turnState.draft,
+    finalizeTurn({
+      prompt,
+      userMessage,
       userRecallHints,
-      assistantRecallHints: recordedAssistantRecallHints,
+      currentProject,
+      memoryStore,
+      engine,
+      ui,
+      turnState,
+      midTurnRecallHints,
+      syncCurrentPiSidecar,
+      autoNameSession,
     });
-
-    autoNameSession?.();
-    syncCurrentPiSidecar();
     return { draft: turnState.draft };
   } finally {
     ui.turnEnd();
@@ -71,6 +73,23 @@ export async function runRunnerTurn({
   }
 }
 
+function finalizeTurn({ prompt, userMessage, userRecallHints, currentProject, memoryStore, engine, ui, turnState, midTurnRecallHints, syncCurrentPiSidecar, autoNameSession }) {
+  closeAssistantReply({ ui, state: turnState });
+  const assistantRecallHints = flushAssistantRecall({ memoryStore, engine, turnState, currentProject });
+  engine.setPendingAssistantRecallHints?.(assistantRecallHints);
+  const recordedAssistantRecallHints = uniqueHints([...midTurnRecallHints, ...assistantRecallHints]);
+
+  engine.recordTurn({
+    userMessage: userMessage ?? prompt.slice(0, 300),
+    assistantMessage: turnState.draft,
+    userRecallHints,
+    assistantRecallHints: recordedAssistantRecallHints,
+  });
+
+  autoNameSession?.();
+  syncCurrentPiSidecar();
+}
+
 function flushAssistantRecall({ memoryStore, engine, turnState, currentProject }) {
   if (!memoryStore) return [];
   const text = assistantRecallDeltaText(turnState);

package/src/auth/storage.mjs

@@ -13,11 +13,12 @@ export function createMarchAuthStorage({
 } = {}) {
   const resolvedAuthStorage = authStorage ?? AuthStorage.create(getMarchAuthPath(homeDir));
 
-  for (const profile of Object.values(providers ?? {})) {
+  for (const [id, profile] of Object.entries(providers ?? {})) {
     if (!profile || typeof profile !== "object") continue;
     const type = profile.type ?? profile.provider;
+    const providerKey = type === "openai-compatible" ? id : type;
     const profileKey = profile.auth?.method === "apiKey" ? profile.auth?.apiKey : null;
-    if (type && profileKey) resolvedAuthStorage.setRuntimeApiKey(type, profileKey);
+    if (providerKey && profileKey) resolvedAuthStorage.setRuntimeApiKey(providerKey, profileKey);
   }
   const hasStoredAuth = Boolean(resolvedAuthStorage.list?.().length);
   const hasConfiguredProvider = Object.values(providers ?? {}).some((profile) => {

package/src/cli/repl-loop.mjs

@@ -92,7 +92,7 @@ export async function runInteractiveRepl({
     });
     if (slashResult.exit) break;
     if (slashResult.handled) {
-      refreshStatusBar();
+      refreshStatusBar(contextTokenRefreshOptions(slashResult, runner));
       continue;
     }
 
@@ -116,6 +116,12 @@ export async function runInteractiveRepl({
   }
 }
 
+export function contextTokenRefreshOptions(slashResult, runner) {
+  if (!slashResult?.refreshContextTokens) return undefined;
+  if (typeof runner.estimateContextTokens !== "function") return undefined;
+  return { contextTokens: runner.estimateContextTokens("") };
+}
+
 function handleInlineCommand(trimmed, { cwd, ui, lastInlineShellCommand }) {
   const inlineShell = parseInlineShellInput(trimmed, lastInlineShellCommand);
   if (inlineShell.type === "error") {

package/src/cli/slash-commands.mjs

@@ -40,11 +40,13 @@ export async function handleSlashCommand(trimmed, {
       ui.writeln("Error: pi runtime host is not enabled");
       return { handled: true };
     }
+    let refreshContextTokens = false;
     try {
       const result = await runner.startNewSession();
       if (result?.cancelled) {
         ui.writeln("New session cancelled");
       } else {
+        refreshContextTokens = true;
         ui.clearOutput?.();
         const bannerLines = typeof renderStartupBanner === "function" ? renderStartupBanner() : [];
         if (bannerLines.length > 0) {
@@ -56,7 +58,7 @@ export async function handleSlashCommand(trimmed, {
     } catch (err) {
       ui.writeln(`Error: ${err.message}`);
     }
-    return { handled: true };
+    return { handled: true, refreshContextTokens };
   }
 
   if (trimmed === "/help") {
@@ -120,6 +122,12 @@ export async function handleSlashCommand(trimmed, {
     return { handled: true };
   }
 
+  if (trimmed === "/notify") {
+    const result = await runner.notifyTest?.();
+    ui.writeln(formatNotificationResult(result));
+    return { handled: true };
+  }
+
   const shellCommand = parseShellCommand(trimmed);
   if (shellCommand.type !== "none") {
     for (const line of handleShellCommand(shellCommand, { shellRuntime: runner.shellRuntime })) ui.writeln(line);
@@ -174,3 +182,11 @@ export async function handleSlashCommand(trimmed, {
 
   return { handled: false };
 }
+
+function formatNotificationResult(result) {
+  if (!result) return "notification: unavailable";
+  const channels = (result.results ?? [])
+    .map((entry) => `${entry.channel}:${entry.ok ? "ok" : entry.reason ?? "failed"}`)
+    .join(", ");
+  return `notification: ${result.ok ? "ok" : result.reason ?? "failed"}${channels ? ` (${channels})` : ""}`;
+}

package/src/cli/tui/input/mouse-selection-controller.mjs

@@ -1,6 +1,8 @@
 import { parseMouseEvent } from "./mouse-tracking.mjs";
 import { brightBlack } from "../ui-theme.mjs";
 
+const OUTPUT_WHEEL_SCROLL_LINES = 3;
+
 export function createMouseSelectionController({
   terminal,
   output,
@@ -49,7 +51,7 @@ export function createMouseSelectionController({
         if (shellDrawer.isVisible?.() && mouse.col > Math.floor((terminal.columns || 80) * 0.64)) {
           shellDrawerControls.scroll(mouse.delta);
         } else {
-          output.scroll(mouse.delta);
+          output.scroll(mouse.delta, { step: OUTPUT_WHEEL_SCROLL_LINES });
         }
         requestRender();
         return { consume: true };

package/src/cli/tui/output/scroll-state.mjs

@@ -17,11 +17,11 @@ export class OutputScrollState {
     this.totalLines = Math.max(0, Math.trunc(total));
   }
 
-  scroll(delta) {
+  scroll(delta, { step = this.getStep() } = {}) {
     const total = this.totalLines;
     const win = this._windowHeight();
     const maxOffset = this.getMaxOffset();
-    const step = this.getStep();
+    step = Math.max(1, Math.trunc(step));
     const currentStart = this.anchorStart ?? Math.max(0, total - this.offset - win);
     const maxStart = Math.max(0, total - win);
     const nextStart = clamp(currentStart + (delta < 0 ? -step : step), 0, maxStart);

package/src/cli/tui/output/text-line-renderer.mjs

@@ -0,0 +1,50 @@
+import { visibleWidth } from "@earendil-works/pi-tui";
+import { R } from "../ui-theme.mjs";
+
+export function appendTextLines(lines, textLines, width) {
+  for (const line of textLines) {
+    for (const part of String(line ?? "").split(/\r?\n/)) {
+      for (const wrapped of wrapLine(part, width)) lines.push(wrapped);
+    }
+  }
+}
+
+export function wrapLine(text, maxWidth) {
+  if (maxWidth <= 0) return [""];
+  const result = [];
+  let cur = "";
+  let curW = 0;
+  let activeSgr = "";
+  for (let i = 0; i < text.length;) {
+    if (text[i] === "\x1b") {
+      const match = text.slice(i).match(/^\x1b\[[0-?]*[ -/]*[@-~]/);
+      if (match) {
+        const seq = match[0];
+        cur += seq;
+        activeSgr = updateActiveSgr(activeSgr, seq);
+        i += seq.length;
+        continue;
+      }
+    }
+    const ch = text[i];
+    const w = visibleWidth(ch);
+    if (curW + w > maxWidth) {
+      result.push(activeSgr ? `${cur}${R}` : cur);
+      cur = activeSgr + ch;
+      curW = w;
+    } else {
+      cur += ch;
+      curW += w;
+    }
+    i += 1;
+  }
+  if (cur) result.push(cur);
+  return result.length > 0 ? result : [""];
+}
+
+function updateActiveSgr(activeSgr, seq) {
+  if (!seq.endsWith("m")) return activeSgr;
+  const body = seq.slice(2, -1);
+  if (body === "" || body.split(";").includes("0")) return "";
+  return seq;
+}

package/src/cli/tui/output-buffer.mjs

@@ -1,59 +1,13 @@
-import { visibleWidth } from "@earendil-works/pi-tui";
-import { R, brightBlack, dim } from "./ui-theme.mjs";
+import { brightBlack, dim } from "./ui-theme.mjs";
 import { renderToolCardBlock } from "./output/tool-card-renderer.mjs";
 import { renderMarkdown, renderStreamingMarkdown } from "./markdown-renderer.mjs";
 import { renderEditDiffBlock } from "./tui-diff-rendering.mjs";
 import { OutputScrollState } from "./output/scroll-state.mjs";
+import { appendTextLines, wrapLine } from "./output/text-line-renderer.mjs";
 
 const SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
 
-function wrapLine(text, maxWidth) {
-  if (maxWidth <= 0) return [""];
-  const result = [];
-  let cur = "";
-  let curW = 0;
-  let activeSgr = "";
-  for (let i = 0; i < text.length;) {
-    if (text[i] === "\x1b") {
-      const match = text.slice(i).match(/^\x1b\[[0-?]*[ -/]*[@-~]/);
-      if (match) {
-        const seq = match[0];
-        cur += seq;
-        activeSgr = updateActiveSgr(activeSgr, seq);
-        i += seq.length;
-        continue;
-      }
-    }
-    const ch = text[i];
-    const w = visibleWidth(ch);
-    if (curW + w > maxWidth) {
-      result.push(activeSgr ? `${cur}${R}` : cur);
-      cur = activeSgr + ch;
-      curW = w;
-    } else {
-      cur += ch;
-      curW += w;
-    }
-    i += 1;
-  }
-  if (cur) result.push(cur);
-  return result.length > 0 ? result : [""];
-}
-
-function updateActiveSgr(activeSgr, seq) {
-  if (!seq.endsWith("m")) return activeSgr;
-  const body = seq.slice(2, -1);
-  if (body === "" || body.split(";").includes("0")) return "";
-  return seq;
-}
 
-function appendTextLines(lines, textLines, width) {
-  for (const line of textLines) {
-    for (const part of String(line ?? "").split(/\r?\n/)) {
-      for (const wrapped of wrapLine(part, width)) lines.push(wrapped);
-    }
-  }
-}
 
 function currentTextToBlocks(textLines, sealed, cache = null) {
   const blocks = [];
@@ -117,6 +71,7 @@ export class OutputBuffer {
     this._activeThinking = null;
     this.overlayStatus = null;
     this.scrollState = new OutputScrollState();
+    this._segmentLinesCache = new Map();
   }
 
   get scrollOffset() {
@@ -133,6 +88,7 @@ export class OutputBuffer {
     this._activeThinking = null;
     this.overlayStatus = null;
     this.scrollState.clear();
+    this._segmentLinesCache = new Map();
   }
 
   write(text) {
@@ -174,6 +130,7 @@ export class OutputBuffer {
     this._flushText();
     const seg = { type: "thinking", tokens: 0, content: [] };
     this.segments.push(seg);
+    this._invalidateSegmentLines();
     this._activeThinking = seg;
   }
 
@@ -197,12 +154,14 @@ export class OutputBuffer {
     this.overlayStatus = null;
     this._flushText();
     this.segments.push({ type: "thinking", tokens, content: content.split("\n") });
+    this._invalidateSegmentLines();
   }
 
   addBlock(block) {
     this.overlayStatus = null;
     this._flushText();
     this.segments.push(block);
+    this._invalidateSegmentLines();
   }
 
   setOverlayStatus(lines) {
@@ -220,6 +179,7 @@ export class OutputBuffer {
   _flushText() {
     if (this.currentText.length <= 1 && this.currentText[0].text === "") return false;
     this.segments.push(...currentTextToBlocks(this.currentText, true));
+    this._invalidateSegmentLines();
     this.currentText = [{ text: "", markdown: false }];
     this.currentTextCache = new Map();
     return true;
@@ -234,8 +194,8 @@ export class OutputBuffer {
     this.spinnerIdx = (this.spinnerIdx + 1) % SPINNER_FRAMES.length;
   }
 
-  scroll(delta) {
-    return this.scrollState.scroll(delta);
+  scroll(delta, options) {
+    return this.scrollState.scroll(delta, options);
   }
 
   getScrollStep() {
@@ -262,10 +222,17 @@ export class OutputBuffer {
       seg.expanded = expanded;
       changed = true;
     }
+    if (changed) this._invalidateSegmentLines();
     return changed;
   }
 
-  invalidate() {}
+  invalidate() {
+    this._invalidateSegmentLines();
+  }
+
+  _invalidateSegmentLines() {
+    this._segmentLinesCache.clear();
+  }
 
   render(width) {
     const allLines = this._computeLines(width);
@@ -278,8 +245,9 @@ export class OutputBuffer {
   }
 
   _computeLines(width) {
-    const lines = [];
-    for (const seg of this.segments) {
+    const lines = [...this._renderCachedSegmentLines(width)];
+    const dynamicStart = this._cachedSegmentPrefixCount();
+    for (const seg of this.segments.slice(dynamicStart)) {
       for (const line of renderBlock(seg, width)) lines.push(line);
     }
     for (const block of currentTextToBlocks(this.currentText, false, this.currentTextCache)) {
@@ -294,4 +262,23 @@ export class OutputBuffer {
     }
     return lines;
   }
+
+  _renderCachedSegmentLines(width) {
+    const prefixCount = this._cachedSegmentPrefixCount();
+    const cached = this._segmentLinesCache.get(width);
+    if (cached?.prefixCount === prefixCount) return cached.lines;
+
+    const lines = [];
+    for (let i = 0; i < prefixCount; i += 1) {
+      for (const line of renderBlock(this.segments[i], width)) lines.push(line);
+    }
+    this._segmentLinesCache.set(width, { prefixCount, lines });
+    return lines;
+  }
+
+  _cachedSegmentPrefixCount() {
+    if (!this._activeThinking) return this.segments.length;
+    const index = this.segments.indexOf(this._activeThinking);
+    return index < 0 ? this.segments.length : index;
+  }
 }

package/src/cli/tui/render/render-scheduler.mjs

@@ -0,0 +1,26 @@
+export function createRenderScheduler({ requestRender, delayMs = 50 }) {
+  let timer = null;
+
+  function renderNow() {
+    clearPending();
+    requestRender();
+  }
+
+  function renderSoon() {
+    if (timer) return;
+    // Streaming deltas are append-only, so coalesce them without delaying input-driven renders.
+    timer = setTimeout(() => {
+      timer = null;
+      requestRender();
+    }, delayMs);
+    timer.unref?.();
+  }
+
+  function clearPending() {
+    if (!timer) return;
+    clearTimeout(timer);
+    timer = null;
+  }
+
+  return { renderNow, renderSoon, clearPending };
+}

package/src/cli/tui/tool-rendering.mjs

@@ -90,6 +90,9 @@ export function formatToolSuccessSummary(name, result, out = "") {
     const matches = result?.details?.count ?? countNonEmptyLines(out);
     return `${matches} file${matches === 1 ? "" : "s"}`;
   }
+  if (name === "memory_open") {
+    return compactText(result?.details?.entry?.name ?? compactPath(result?.details?.path ?? ""));
+  }
   return "";
 }
 

package/src/cli/ui.mjs

@@ -23,6 +23,7 @@ import { createTuiInputController } from "./tui/tui-input-controller.mjs";
 import { writeMemoryHint } from "./tui/recall-rendering.mjs";
 import { writeToolEnd, writeToolStart } from "./tui/tool-rendering.mjs";
 import { EDITOR_THEME, brightBlack } from "./tui/ui-theme.mjs";
+import { createRenderScheduler } from "./tui/render/render-scheduler.mjs";
 import { writeTranscriptToOutput } from "../session/transcript.mjs";
 
 export { buildMarchCommands, MarchAutocompleteProvider } from "./input/autocomplete.mjs";
@@ -59,10 +60,8 @@ export function createTuiUI({
   let mouseOn = true;
   let toolsExpanded = false;
   const activeToolBlocks = [];
-
-  function requestRender() {
-    tui.requestRender();
-  }
+  const renderScheduler = createRenderScheduler({ requestRender: () => tui.requestRender() });
+  const requestRender = renderScheduler.renderNow;
 
   const spinnerStatus = createSpinnerStatusController({ output, requestRender });
   const retryStatus = createRetryStatusController({ output, requestRender, stopSpinner: spinnerStatus.stop });
@@ -172,7 +171,7 @@ export function createTuiUI({
 
     thinkingDelta: (delta) => {
       output.appendThinking(delta);
-      requestRender();
+      renderScheduler.renderSoon();
     },
 
     thinkingEnd: (tokens) => {
@@ -197,7 +196,7 @@ export function createTuiUI({
     textDelta: (delta) => {
       ensureStarted(); retryStatus.stop(); spinnerStatus.stop();
       output.writeMarkdown(delta);
-      requestRender();
+      renderScheduler.renderSoon();
     },
     assistantReplyEnd: () => {
       ensureStarted();
@@ -278,8 +277,8 @@ export function createTuiUI({
     toggleToolOutput,
     toggleShellDrawer: () => shellDrawerControls.toggle(),
     requestExit: () => inputController.requestExit(),
-
     close: async () => {
+      renderScheduler.clearPending();
       spinnerStatus.stop();
       retryStatus.stop();
       if (started) {

package/src/config/loader.mjs

@@ -49,7 +49,7 @@ function mergeLayers(layers) {
     maxTurns: null,
     trimBatch: null,
     memoryRoot: null,
-    notifications: { turnEnd: true },
+    notifications: { turnEnd: true, desktop: true, bell: false, command: null, minDurationMs: 0, sound: true },
   };
 
   for (const layer of layers) {

package/src/context/center-memory.mjs

@@ -0,0 +1,14 @@
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export function defaultCenterMemoryPath() {
+  return join(homedir(), ".march", "memory", "center.md");
+}
+
+export function buildCenterMemory(path = defaultCenterMemoryPath()) {
+  if (!path || !existsSync(path)) return null;
+  const content = readFileSync(path, "utf8").trimEnd();
+  if (!content.trim()) return null;
+  return `[center_memory]\n--- ${path} ---\n${content}`;
+}

package/src/context/engine.mjs

@@ -3,12 +3,14 @@ import { buildSessionIdentity } from "./session-status.mjs";
 import { buildSystemCore, resolveSystemCorePromptKey } from "./system-core.mjs";
 import { buildInjectionsLayer } from "./injections.mjs";
 import { buildProjectContext } from "./project-context.mjs";
+import { buildCenterMemory } from "./center-memory.mjs";
 import { formatRecallHints } from "../memory/markdown-store.mjs";
 
 export class ContextEngine {
-  constructor({ cwd, modelId, provider = "deepseek", thinkingLevel = "medium", namespace = "", memoryRoot = null, shellRuntime = null, lspService = null, injections = [], maxTurns, trimBatch }) {
+  constructor({ cwd, modelId, provider = "deepseek", thinkingLevel = "medium", namespace = "", memoryRoot = null, centerMemoryPath = null, shellRuntime = null, lspService = null, injections = [], maxTurns, trimBatch }) {
     this.cwd = cwd;
     this.memoryRoot = memoryRoot;
+    this.centerMemoryPath = centerMemoryPath;
     this.modelId = modelId;
     this.provider = provider;
     this.thinkingLevel = thinkingLevel;
@@ -60,6 +62,9 @@ export class ContextEngine {
     const projectCtx = buildProjectContext(this.cwd);
     if (projectCtx) layers.push({ name: "project_context", text: projectCtx });
 
+    const centerMemory = buildCenterMemory(this.centerMemoryPath);
+    if (centerMemory) layers.push({ name: "center_memory", text: centerMemory });
+
     layers.push({ name: "recent_chat", text: this.#buildRecentChat() });
 
     return layers;

package/src/context/system-core/base.md

@@ -7,7 +7,7 @@ The user primarily asks for software engineering work: fixing bugs, adding behav
 - Be concise and direct. Match the response shape to the task; simple questions get simple answers.
 - Assume users may not see tool calls. Before the first tool call, say in one sentence what you are about to do. While working, give brief updates when you find something important, change direction, or hit a blocker.
 - Don't narrate hidden reasoning. State decisions, results, and relevant next steps.
-- End with one or two sentences: what changed, verification status, and what's next if anything.
+- End with a brief summary of what you did during the task, including what changed, verification status, and what's next if anything; keep it concise, but don't omit the execution overview.
 - Report outcomes truthfully. If tests fail or a step was skipped, say so plainly with the relevant output or reason.
 </communication_contract>
 
@@ -57,4 +57,8 @@ The user primarily asks for software engineering work: fixing bugs, adding behav
 - Use memory_search(query) for full-text search across all memories.
 - To edit an existing memory, use memory_open(id) to get its path, then edit_file with mode="patch" for targeted edits.
 - Use memory_save() to create memories or update whole fields. Before creating a new memory, first search/open related memories and merge updates into an existing memory when they share the same topic, project, or decision thread; prefer modifying the existing memory file over creating a scattered new one. Tags are the primary retrieval key for future recall. Prefer lowercase kebab-case tags like 'march-cli', 'tooling', 'permissions'.
+- When learning multiple related external workflows or skills, maintain memory as an evolving domain library: start with the specific source name when only one item exists, then rename and rewrite the memory title/description as the scope grows; merge new related learnings into the same memory, preserving each source's unique traits while distilling reusable principles.
+- Distinguish "migrating a Skill to memory" from "learning a Skill": migration preserves the complete Skill folder under memory_root/skills/ and creates a memory index with purpose, source, entry files, and local path; learning only reads and internalizes the Skill's methods, scenarios, and principles into ordinary memory without copying source files. Infer the action from the user's wording, and ask when ambiguous.
+- Unlike memory hints, this system-core center is always visible in every model call. Only update the center for instructions that must always be followed; use memory for contextual, project-specific, or recall-dependent knowledge.
+- If execution takes a meaningful detour, create or update a memory after the task. A detour means the initial plan or assumption failed, multiple approaches were tried, and the final successful path contains reusable project knowledge. Record the failed assumption, what was tried, and the successful approach. Prefer updating an existing related memory over creating a new one.
 </memory_system>

package/src/main.mjs

@@ -28,6 +28,7 @@ import { formatStartupBanner } from "./cli/startup/startup-banner.mjs";
 import { initializeMcp } from "./mcp/index.mjs";
 import { createWebToolsFromConfig } from "./web/tools.mjs";
 import { createModelContextDumper } from "./debug/model-context-dumper.mjs";
+import { defaultCenterMemoryPath } from "./context/center-memory.mjs";
 import { runProviderConfigCommand } from "./provider/config-command.mjs";
 import { runWebSearchConfigCommand } from "./web/config-command.mjs";
 import { createDesktopTurnNotifier } from "./notification/desktop-notifier.mjs";
@@ -91,6 +92,7 @@ export async function run(argv) {
   const modeState = createModeState();
   const namespace = loadOrCreateProjectId(projectMarchDir);
   const memoryRoot = resolveMemoryRoot(config.memoryRoot, stateRoot);
+  const centerMemoryPath = defaultCenterMemoryPath();
   const memoryStore = new MarkdownMemoryStore({ root: memoryRoot });
   const memoryTools = createMarkdownMemoryTools(memoryStore);
   const currentProject = basename(cwd);
@@ -111,6 +113,7 @@ export async function run(argv) {
   const webTools = createWebToolsFromConfig(config);
   const turnNotifier = createDesktopTurnNotifier({
     enabled: Boolean(config.notifications?.turnEnd),
+    config: config.notifications,
   });
 
   // Permission controller
@@ -156,6 +159,7 @@ export async function run(argv) {
     stateRoot,
     ui,
     memoryRoot,
+    centerMemoryPath,
     memoryStore,
     memoryTools,
     shellRuntime,

package/src/notification/desktop-notifier.mjs

@@ -1,42 +1,101 @@
 import { spawn } from "node:child_process";
+import nodeNotifier from "node-notifier";
+import { fileURLToPath } from "node:url";
 
 const DEFAULT_BALLOON_TIMEOUT_MS = 5000;
+const DEFAULT_NOTIFICATION_ICON_PATH = fileURLToPath(new URL("../assets/march-icon.png", import.meta.url));
 
 export function createDesktopTurnNotifier({
   enabled = true,
   platform = process.platform,
   spawnProcess = spawn,
+  writeBell = () => process.stdout.write("\x07"),
+  toastNotifier = nodeNotifier,
+  config = {},
 } = {}) {
+  const channels = resolveNotificationChannels(config);
+  const minDurationMs = normalizeNonNegativeInteger(config.minDurationMs, 0);
+  const toastSound = normalizeNotificationSound(config.sound, true);
   return {
     async notifyTurnEnd(event) {
-      if (!enabled) return { ok: false, reason: "disabled" };
-      return sendDesktopNotification({
-        platform,
-        spawnProcess,
-        title: event?.title ?? defaultTurnTitle(event?.status),
-        message: event?.message ?? defaultTurnMessage(event),
-      });
+      const normalizedEvent = normalizeTurnEvent(event);
+      if (!enabled) return { ok: false, reason: "disabled", results: [] };
+      if (normalizedEvent.durationMs < minDurationMs) return { ok: false, reason: "min-duration", results: [] };
+
+      const payload = {
+        title: normalizedEvent.title ?? defaultTurnTitle(normalizedEvent.status),
+        message: normalizedEvent.message ?? defaultTurnMessage(normalizedEvent),
+        sound: toastSound,
+      };
+      const results = [];
+      if (channels.desktop) {
+        results.push({
+          channel: "desktop",
+          ...(await sendDesktopNotification({ platform, spawnProcess, toastNotifier, ...payload })),
+        });
+      }
+      if (channels.bell) results.push({ channel: "bell", ...sendBellNotification({ writeBell }) });
+      if (channels.command) {
+        results.push({
+          channel: "command",
+          ...sendCommandNotification({ spawnProcess, command: channels.command, event: normalizedEvent, ...payload }),
+        });
+      }
+
+      const delivered = results.some((result) => result.ok);
+      return {
+        ok: delivered,
+        reason: delivered ? undefined : results[0]?.reason ?? "no-channels",
+        results,
+      };
     },
   };
 }
 
-export async function sendDesktopNotification({ platform = process.platform, spawnProcess = spawn, title, message }) {
+export async function sendDesktopNotification({ platform = process.platform, spawnProcess = spawn, toastNotifier = nodeNotifier, title, message, iconPath = DEFAULT_NOTIFICATION_ICON_PATH, sound = true }) {
   if (platform !== "win32") return { ok: false, reason: "unsupported-platform" };
 
   const safeTitle = normalizeNotificationText(title) || "March";
   const safeMessage = normalizeNotificationText(message) || "Turn finished";
-  const script = buildWindowsNotificationScript({ title: safeTitle, message: safeMessage });
 
   try {
-    const child = spawnProcess("powershell.exe", [
-      "-NoProfile",
-      "-ExecutionPolicy", "Bypass",
-      "-WindowStyle", "Hidden",
-      "-Command", script,
-    ], {
+    const toastResult = await sendWindowsToastNotification({ toastNotifier, title: safeTitle, message: safeMessage, iconPath, sound });
+    if (toastResult.ok) return { ok: true };
+
+    const script = buildWindowsNotificationScript({ title: safeTitle, message: safeMessage, iconPath });
+    const balloonResult = await runWindowsNotificationPowerShell({ spawnProcess, script, timeoutMs: DEFAULT_BALLOON_TIMEOUT_MS + 5000 });
+    if (balloonResult.ok) return { ok: true, fallback: "balloon", toastReason: toastResult.reason };
+    return { ok: false, reason: `toast: ${toastResult.reason}; balloon: ${balloonResult.reason}` };
+  } catch (err) {
+    return { ok: false, reason: err?.message ?? String(err) };
+  }
+}
+
+export function sendBellNotification({ writeBell = () => process.stdout.write("\x07") } = {}) {
+  try {
+    writeBell("\x07");
+    return { ok: true };
+  } catch (err) {
+    return { ok: false, reason: err?.message ?? String(err) };
+  }
+}
+
+export function sendCommandNotification({ spawnProcess = spawn, command, event = {}, title, message }) {
+  if (!command) return { ok: false, reason: "command-not-configured" };
+  try {
+    const child = spawnProcess(String(command), [], {
+      shell: true,
       detached: true,
       stdio: "ignore",
       windowsHide: true,
+      env: {
+        ...process.env,
+        MARCH_NOTIFICATION_STATUS: String(event.status ?? ""),
+        MARCH_NOTIFICATION_TITLE: normalizeNotificationText(title),
+        MARCH_NOTIFICATION_MESSAGE: normalizeNotificationText(message),
+        MARCH_NOTIFICATION_SESSION: normalizeNotificationText(event.sessionName),
+        MARCH_NOTIFICATION_DURATION_MS: String(event.durationMs ?? 0),
+      },
     });
     child?.unref?.();
     return { ok: true };
@@ -45,63 +104,138 @@ export async function sendDesktopNotification({ platform = process.platform, spa
   }
 }
 
-export function buildWindowsBalloonScript({ title, message, timeoutMs = DEFAULT_BALLOON_TIMEOUT_MS }) {
+export function buildWindowsBalloonScript({ title, message, timeoutMs = DEFAULT_BALLOON_TIMEOUT_MS, iconPath = DEFAULT_NOTIFICATION_ICON_PATH }) {
   const escapedTitle = escapePowerShellSingleQuotedString(title);
   const escapedMessage = escapePowerShellSingleQuotedString(message);
+  const escapedIconPath = escapePowerShellSingleQuotedString(iconPath);
   const timeout = Number.isFinite(timeoutMs) ? Math.max(0, Math.trunc(timeoutMs)) : DEFAULT_BALLOON_TIMEOUT_MS;
   return [
     "Add-Type -AssemblyName System.Windows.Forms",
     "Add-Type -AssemblyName System.Drawing",
     "$n = New-Object System.Windows.Forms.NotifyIcon",
-    "$n.Icon = [System.Drawing.SystemIcons]::Information",
+    `$sourceBitmap = [System.Drawing.Bitmap]::FromFile('${escapedIconPath}')`,
+    "$trayBitmap = New-Object System.Drawing.Bitmap 32, 32",
+    "$graphics = [System.Drawing.Graphics]::FromImage($trayBitmap)",
+    "$graphics.Clear([System.Drawing.Color]::Transparent)",
+    "$graphics.InterpolationMode = [System.Drawing.Drawing2D.InterpolationMode]::HighQualityBicubic",
+    "$graphics.DrawImage($sourceBitmap, 0, 0, 32, 32)",
+    "$icon = [System.Drawing.Icon]::FromHandle($trayBitmap.GetHicon())",
+    "$n.Icon = $icon",
+    "$n.Text = 'March'",
+    "$n.BalloonTipIcon = [System.Windows.Forms.ToolTipIcon]::None",
     `$n.BalloonTipTitle = '${escapedTitle}'`,
     `$n.BalloonTipText = '${escapedMessage}'`,
     "$n.Visible = $true",
     `$n.ShowBalloonTip(${timeout})`,
     `Start-Sleep -Milliseconds ${timeout + 500}`,
     "$n.Dispose()",
+    "$icon.Dispose()",
+    "$graphics.Dispose()",
+    "$trayBitmap.Dispose()",
+    "$sourceBitmap.Dispose()",
   ].join("; ");
 }
 
-export function buildWindowsNotificationScript({ title, message, timeoutMs = DEFAULT_BALLOON_TIMEOUT_MS }) {
-  const toastXml = escapePowerShellDoubleQuotedString(buildToastXml({ title, message }));
-  const balloonScript = buildWindowsBalloonScript({ title, message, timeoutMs });
-  return [
-    "try {",
-    "[Windows.UI.Notifications.ToastNotificationManager, Windows.UI.Notifications, ContentType = WindowsRuntime] > $null",
-    "[Windows.Data.Xml.Dom.XmlDocument, Windows.Data.Xml.Dom.XmlDocument, ContentType = WindowsRuntime] > $null",
-    "$xml = New-Object Windows.Data.Xml.Dom.XmlDocument",
-    `$xml.LoadXml("${toastXml}")`,
-    "$toast = [Windows.UI.Notifications.ToastNotification]::new($xml)",
-    "[Windows.UI.Notifications.ToastNotificationManager]::CreateToastNotifier('PowerShell').Show($toast)",
-    "} catch {",
-    balloonScript,
-    "}",
-  ].join("; ");
+export function buildWindowsNotificationScript({ title, message, timeoutMs = DEFAULT_BALLOON_TIMEOUT_MS, iconPath = DEFAULT_NOTIFICATION_ICON_PATH }) {
+  return buildWindowsBalloonScript({ title, message, timeoutMs, iconPath });
+}
+
+export function buildWindowsToastOptions({ title, message, iconPath = DEFAULT_NOTIFICATION_ICON_PATH, sound = true }) {
+  return {
+    title,
+    message,
+    icon: iconPath,
+    appID: "March",
+    sound,
+    wait: false,
+  };
 }
 
-function buildToastXml({ title, message }) {
-  return `<toast><visual><binding template="ToastGeneric"><text>${escapeXmlText(title)}</text><text>${escapeXmlText(message)}</text></binding></visual></toast>`;
+function sendWindowsToastNotification({ toastNotifier = nodeNotifier, title, message, iconPath, sound }) {
+  return new Promise((resolve) => {
+    const notify = toastNotifier?.notify;
+    if (typeof notify !== "function") {
+      resolve({ ok: false, reason: "toast-notifier-unavailable" });
+      return;
+    }
+
+    let settled = false;
+    const timeout = setTimeout(() => finish({ ok: false, reason: "toast-timeout" }), DEFAULT_BALLOON_TIMEOUT_MS + 5000);
+    notify.call(toastNotifier, buildWindowsToastOptions({ title, message, iconPath, sound }), (err) => {
+      if (err) {
+        finish({ ok: false, reason: err?.message ?? String(err) });
+        return;
+      }
+      finish({ ok: true });
+    });
+
+    function finish(result) {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timeout);
+      resolve(result);
+    }
+  });
 }
 
-function escapeXmlText(text) {
-  return String(text)
-    .replaceAll("&", "&amp;")
-    .replaceAll("<", "&lt;")
-    .replaceAll(">", "&gt;");
+function resolveNotificationChannels(config) {
+  return {
+    desktop: config.desktop !== false,
+    bell: config.bell === true,
+    command: typeof config.command === "string" && config.command.trim() ? config.command.trim() : null,
+  };
 }
 
-function escapePowerShellDoubleQuotedString(text) {
-  return String(text).replace(/[`"$]/g, "`$&");
+function runWindowsNotificationPowerShell({ spawnProcess, script, timeoutMs }) {
+  return new Promise((resolve) => {
+    const child = spawnProcess("powershell.exe", [
+      "-NoProfile",
+      "-ExecutionPolicy", "Bypass",
+      "-Command", script,
+    ], {
+      windowsHide: false,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+
+    let stderr = "";
+    let settled = false;
+    const timeout = setTimeout(() => finish({ ok: false, reason: "timeout" }), timeoutMs);
+
+    child?.stderr?.on?.("data", (chunk) => { stderr += chunk; });
+    child?.on?.("error", (err) => finish({ ok: false, reason: err?.message ?? String(err) }));
+    child?.on?.("close", (exitCode, signal) => {
+      if (exitCode === 0) {
+        finish({ ok: true });
+        return;
+      }
+      const detail = stderr.trim() || (signal ? `signal ${signal}` : `exit ${exitCode}`);
+      finish({ ok: false, reason: detail });
+    });
+
+    function finish(result) {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timeout);
+      resolve(result);
+    }
+  });
+}
+
+function normalizeTurnEvent(event) {
+  return {
+    ...event,
+    status: event?.status === "error" ? "error" : "success",
+    durationMs: normalizeNonNegativeInteger(event?.durationMs, 0),
+  };
 }
 
-function defaultTurnTitle(status) {
-  return status === "error" ? "March turn failed" : "March is ready";
+function defaultTurnTitle() {
+  return "March";
 }
 
 function defaultTurnMessage(event) {
   if (event?.status === "error") return event?.errorMessage ?? "Something went wrong";
-  return event?.sessionName ? `${event.sessionName} is ready for review` : "Your turn is ready for review";
+  return event?.draft || "Turn finished";
 }
 
 function normalizeNotificationText(text) {
@@ -112,6 +246,17 @@ function normalizeNotificationText(text) {
     .slice(0, 240);
 }
 
+function normalizeNotificationSound(value, fallback) {
+  if (value === false) return false;
+  if (typeof value === "string") return normalizeNotificationText(value) || fallback;
+  return value === undefined ? fallback : Boolean(value);
+}
+
+function normalizeNonNegativeInteger(value, fallback) {
+  const number = Number(value);
+  return Number.isFinite(number) ? Math.max(0, Math.trunc(number)) : fallback;
+}
+
 function escapePowerShellSingleQuotedString(text) {
   return String(text).replaceAll("'", "''");
 }

package/src/provider/custom-provider.mjs

@@ -0,0 +1,112 @@
+const CUSTOM_PROVIDER_TYPE = "openai-compatible";
+const DEFAULT_API = "openai-completions";
+const SUPPORTED_APIS = new Set(["openai-completions", "openai-responses"]);
+const DEFAULT_COST = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 };
+
+export function registerCustomProviders(modelRegistry, providers = {}) {
+  if (!modelRegistry?.registerProvider) return [];
+  const registered = [];
+
+  for (const [providerId, profile] of Object.entries(providers ?? {})) {
+    if (!isCustomProviderProfile(profile)) continue;
+    modelRegistry.registerProvider(providerId, toProviderConfig(providerId, profile));
+    registered.push(providerId);
+  }
+
+  return registered;
+}
+
+export function isCustomProviderProfile(profile) {
+  return Boolean(profile && typeof profile === "object" && profile.type === CUSTOM_PROVIDER_TYPE);
+}
+
+function toProviderConfig(providerId, profile) {
+  const api = normalizeApi(providerId, profile.api ?? DEFAULT_API);
+  const baseUrl = requireString(providerId, "baseUrl", profile.baseUrl);
+  const models = normalizeModels(providerId, profile.models, { api, baseUrl });
+  return omitUndefined({
+    name: typeof profile.name === "string" && profile.name.trim() ? profile.name : providerId,
+    baseUrl,
+    apiKey: profile.auth?.method === "apiKey" ? profile.auth.apiKey : undefined,
+    api,
+    headers: normalizeHeaders(providerId, profile.headers),
+    authHeader: typeof profile.authHeader === "boolean" ? profile.authHeader : undefined,
+    models,
+  });
+}
+
+function normalizeModels(providerId, models, { api, baseUrl }) {
+  if (!Array.isArray(models) || models.length === 0) {
+    throw new Error(`Custom provider "${providerId}" requires a non-empty models array`);
+  }
+
+  return models.map((model, index) => {
+    if (!model || typeof model !== "object" || Array.isArray(model)) {
+      throw new Error(`Custom provider "${providerId}" model #${index + 1} must be an object`);
+    }
+    const id = requireString(providerId, `models[${index}].id`, model.id);
+    return omitUndefined({
+      ...model,
+      id,
+      name: typeof model.name === "string" && model.name.trim() ? model.name : id,
+      api: normalizeApi(providerId, model.api ?? api),
+      baseUrl: typeof model.baseUrl === "string" && model.baseUrl.trim() ? model.baseUrl : baseUrl,
+      reasoning: typeof model.reasoning === "boolean" ? model.reasoning : false,
+      input: normalizeInput(model.input),
+      cost: normalizeCost(model.cost),
+      contextWindow: normalizePositiveNumber(model.contextWindow, 128000),
+      maxTokens: normalizePositiveNumber(model.maxTokens, 4096),
+      headers: normalizeHeaders(providerId, model.headers),
+    });
+  });
+}
+
+function normalizeApi(providerId, api) {
+  if (typeof api !== "string" || !SUPPORTED_APIS.has(api)) {
+    throw new Error(`Custom provider "${providerId}" api must be "openai-completions" or "openai-responses"`);
+  }
+  return api;
+}
+
+function requireString(providerId, field, value) {
+  if (typeof value !== "string" || !value.trim()) {
+    throw new Error(`Custom provider "${providerId}" requires ${field}`);
+  }
+  return value;
+}
+
+function normalizeInput(input) {
+  if (!Array.isArray(input) || input.length === 0) return ["text"];
+  const normalized = input.filter((item) => item === "text" || item === "image");
+  return normalized.length > 0 ? normalized : ["text"];
+}
+
+function normalizeCost(cost) {
+  if (!cost || typeof cost !== "object" || Array.isArray(cost)) return DEFAULT_COST;
+  return {
+    input: normalizeNumber(cost.input, 0),
+    output: normalizeNumber(cost.output, 0),
+    cacheRead: normalizeNumber(cost.cacheRead, 0),
+    cacheWrite: normalizeNumber(cost.cacheWrite, 0),
+  };
+}
+
+function normalizeHeaders(providerId, headers) {
+  if (headers == null) return undefined;
+  if (typeof headers !== "object" || Array.isArray(headers)) {
+    throw new Error(`Custom provider "${providerId}" headers must be an object`);
+  }
+  return Object.fromEntries(Object.entries(headers).filter(([, value]) => typeof value === "string"));
+}
+
+function normalizePositiveNumber(value, fallback) {
+  return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : fallback;
+}
+
+function normalizeNumber(value, fallback) {
+  return typeof value === "number" && Number.isFinite(value) ? value : fallback;
+}
+
+function omitUndefined(value) {
+  return Object.fromEntries(Object.entries(value).filter(([, item]) => item !== undefined));
+}