localpi 0.3.0 → 0.5.0

package/README.md

@@ -1,10 +1,10 @@
 # localpi
 
-Localpi is a local Pi launcher for open-weight models.
+Localpi is a Swiss army knife for running Pi with local inference engines.
 
 By default, Localpi discovers available local providers, lets you choose when more than one model is loaded, points Pi at the selected model, and writes Pi config for the other discovered models so `/model` can switch among them during the session.
 
-Localpi supports LM Studio, vLLM, custom OpenAI-compatible servers, and an optional managed `llama-server` fallback.
+Localpi is meant to be the practical bridge from Pi to local inference stacks such as llama.cpp/`llama-server`, vLLM, SGLang, LM Studio, Ollama, and custom provider endpoints.
 
 Localpi is intentionally generic. It does not contain classifier prompts, dataset workflows, GitHub routing logic, or final-schema output machinery. Structured classifier runs belong in caller tools such as `localpager-agent`.
 

package/dist/src/cli/cli.js

@@ -1,10 +1,10 @@
+import { runPiApp } from "@dutifuldev/pi-factory";
 import { errorMessage, fail, ok } from "../common/result.js";
 import { parseLocalpiArgs, usage } from "../localpi/options.js";
 import { aliasListOutput, connectionStatus, resolveRuntime, statusOutput, stopRuntime } from "../localpi/runtime.js";
 import { applyRememberedSettings } from "../localpi/settings-state.js";
-import { writeRuntimeConfig } from "../pi/config.js";
+import { createLocalpiAppDefinition } from "../pi/app.js";
 import { writeDefaultExtensions } from "../pi/extensions.js";
-import { createLaunchPlan, execLaunchPlan } from "../pi/launch.js";
 export async function run(args) {
     try {
         let options = parseLocalpiArgs(args);
@@ -21,10 +21,10 @@ export async function run(args) {
             thinking: hasExplicitThinkingOverride(args)
         });
         const connection = await resolveRuntime(options);
-        const runtimeConfig = await writeRuntimeConfig(options, connection);
         const selectorOptions = startupModelSelectorOptions(options, connection);
         const extensions = await writeDefaultExtensions(options, selectorOptions === undefined ? {} : { startupModelSelector: selectorOptions });
-        return await launchResolvedRuntime(options, runtimeConfig, connection, extensions);
+        const app = createLocalpiAppDefinition(options, connection, extensions);
+        return await launchResolvedRuntime(app, connection);
     }
     catch (error) {
         return fail(`localpi: ${errorMessage(error)}`);
@@ -237,8 +237,8 @@ function isPiUnknownLongFlagValue(arg, next) {
 function isPiUnknownLongFlagNextValue(arg) {
     return arg !== undefined && !arg.startsWith("-") && !arg.startsWith("@");
 }
-async function launchResolvedRuntime(options, runtimeConfig, connection, extensions) {
-    const code = await execLaunchPlan(await createLaunchPlan(options, runtimeConfig, connection, extensions));
+async function launchResolvedRuntime(app, connection) {
+    const code = await runPiApp(app);
     if (code !== 0) {
         return { code, stdout: "", stderr: "" };
     }

package/dist/src/localpi/settings-state.js

@@ -2,7 +2,7 @@ import { readFile } from "node:fs/promises";
 import path from "node:path";
 import { asObject, optionalString } from "../common/json.js";
 import { parseThinkingLevel } from "./options.js";
-export function settingsStatePath(options) {
+export function localpiSettingsPath(options) {
     return path.join(options.stateDir, "settings.json");
 }
 export async function applyRememberedSettings(options, explicit) {
@@ -15,7 +15,7 @@ export async function applyRememberedSettings(options, explicit) {
 async function readLocalpiSettings(options) {
     let raw;
     try {
-        raw = await readFile(settingsStatePath(options), "utf8");
+        raw = await readFile(localpiSettingsPath(options), "utf8");
     }
     catch (error) {
         if (isMissingFile(error)) {

package/dist/src/pi/app.js

@@ -0,0 +1,148 @@
+import { localpiVersion } from "./version.js";
+const localpiAppIdentity = {
+    id: "localpi",
+    name: "localpi",
+    version: localpiVersion
+};
+const demoLaunchOverrideBooleanFlags = new Set([
+    "--no-tools",
+    "-nt",
+    "--no-builtin-tools",
+    "-nbt",
+    "--approve",
+    "-a",
+    "--no-approve",
+    "-na"
+]);
+const demoLaunchOverrideValueFlags = new Set(["--tools", "-t", "--exclude-tools", "-xt"]);
+const demoLaunchOverrideEqualsFlags = ["--tools=", "--exclude-tools="];
+export function createLocalpiAppDefinition(options, connection, extensions) {
+    return {
+        ...localpiAppIdentity,
+        ...appDirectories(options),
+        ...piCommand(options),
+        ...runtimeSelection(options, connection),
+        ...extensionConfig(extensions)
+    };
+}
+function appDirectories(options) {
+    return {
+        stateDir: options.stateDir,
+        sessionDir: options.sessionDir
+    };
+}
+function piCommand(options) {
+    return {
+        piCommand: options.piCommand,
+        forwardedArgs: options.demo ? demoForwardedArgs(options.forwardedArgs) : options.forwardedArgs
+    };
+}
+function demoForwardedArgs(args) {
+    return [...withoutConflictingDemoFlags(args), "--no-tools", "--no-approve"];
+}
+function withoutConflictingDemoFlags(args) {
+    const filtered = [];
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (arg === undefined) {
+            continue;
+        }
+        if (isDemoLaunchOverrideFlag(arg)) {
+            if (isValueFlag(arg) && !arg.includes("=")) {
+                index += 1;
+            }
+            continue;
+        }
+        filtered.push(arg);
+    }
+    return filtered;
+}
+function isDemoLaunchOverrideFlag(arg) {
+    return (demoLaunchOverrideBooleanFlags.has(arg) ||
+        isValueFlag(arg) ||
+        demoLaunchOverrideEqualsFlags.some((flag) => arg.startsWith(flag)));
+}
+function isValueFlag(arg) {
+    return demoLaunchOverrideValueFlags.has(arg);
+}
+function runtimeSelection(options, connection) {
+    const selection = {
+        providers: providersForConnection(options, connection),
+        defaultProvider: connection.providerId,
+        defaultModel: connection.model,
+        thinking: options.thinking
+    };
+    return options.tools === undefined ? selection : { ...selection, tools: options.tools };
+}
+function providersForConnection(options, connection) {
+    const models = connection.catalogModels.length === 0 ? fallbackCatalog(connection) : connection.catalogModels;
+    return groupedByProvider(models).map((group) => ({
+        id: group.providerId,
+        baseUrl: group.baseUrl,
+        api: "openai-completions",
+        apiKey: "local",
+        compat: {
+            supportsDeveloperRole: false,
+            supportsReasoningEffort: false
+        },
+        models: group.models.map((model) => modelDefinition(options, model))
+    }));
+}
+function groupedByProvider(models) {
+    const groups = new Map();
+    for (const model of models) {
+        const existing = groups.get(model.providerId);
+        groups.set(model.providerId, existing === undefined
+            ? { providerId: model.providerId, baseUrl: model.baseUrl, models: [model] }
+            : { ...existing, models: [...existing.models, model] });
+    }
+    return [...groups.values()];
+}
+function modelDefinition(options, model) {
+    const contextWindow = modelContextWindow(options, model);
+    return {
+        id: model.modelId,
+        name: model.displayName,
+        reasoning: model.reasoning ?? false,
+        ...(model.thinkingFormat === undefined ? {} : { thinkingFormat: model.thinkingFormat }),
+        input: ["text"],
+        ...(contextWindow === undefined ? {} : { contextWindow }),
+        ...(model.maxTokens === undefined
+            ? { maxTokens: options.maxTokens }
+            : { maxTokens: model.maxTokens })
+    };
+}
+function modelContextWindow(options, model) {
+    if (options.contextWindow !== undefined) {
+        return options.contextWindow;
+    }
+    return model.contextWindow;
+}
+function fallbackCatalog(connection) {
+    return [
+        {
+            providerId: connection.providerId,
+            providerName: connection.providerName,
+            runtime: connection.runtime.startsWith("llama-server")
+                ? "managed-llama-server"
+                : "openai-compatible",
+            baseUrl: connection.baseUrl,
+            modelId: connection.model,
+            aliases: [],
+            displayName: `Local model (${connection.model})`,
+            reasoning: false,
+            capabilities: ["text"],
+            availability: "loaded",
+            ...(connection.contextWindow === undefined ? {} : { contextWindow: connection.contextWindow })
+        }
+    ];
+}
+function extensionConfig(extensions) {
+    if (extensions === undefined) {
+        return {};
+    }
+    return {
+        extensions: extensions.paths.map((extensionPath) => ({ path: extensionPath })),
+        appendSystemPrompts: [extensions.systemPrompt]
+    };
+}

package/dist/src/pi/extension-sources/demo-mode.js

@@ -0,0 +1,110 @@
+export function demoModeExtensionSource(prompts) {
+    const initialPromptSource = JSON.stringify(prompts.initial);
+    const followupPromptSource = JSON.stringify(prompts.followup);
+    return `import type { ExtensionAPI, ExtensionContext, TurnEndEvent } from "@earendil-works/pi-coding-agent";
+
+const initialPrompt = ${initialPromptSource};
+const followupPrompt = ${followupPromptSource};
+const compactAtContextPercent = 70;
+const demoCompactionInstructions = [
+  "Preserve the demo narrative state, named entities, current setting,",
+  "unresolved plot threads, and latest user direction.",
+  "Keep the summary concise so the story can continue after compaction."
+].join(" ");
+
+export default function localpiDemoMode(pi: ExtensionAPI): void {
+  let started = false;
+  let stopped = false;
+  let compacting = false;
+
+  function queueInitialPrompt(): void {
+    queueMicrotask(() => {
+      if (!stopped) {
+        pi.sendUserMessage(initialPrompt);
+      }
+    });
+  }
+
+  function queueFollowup(): void {
+    queueMicrotask(() => {
+      if (!stopped && !compacting) {
+        pi.sendUserMessage(followupPrompt, { deliverAs: "followUp" });
+      }
+    });
+  }
+
+  function compactThenFollowup(ctx: ExtensionContext): void {
+    if (compacting) {
+      return;
+    }
+    compacting = true;
+    ctx.compact({
+      customInstructions: demoCompactionInstructions,
+      onComplete: () => {
+        compacting = false;
+        queueFollowup();
+      },
+      onError: (error) => {
+        compacting = false;
+        stopped = true;
+        ctx.ui.notify("Demo compaction failed: " + error.message, "error");
+      }
+    });
+  }
+
+  pi.on("session_start", (event, ctx) => {
+    if (started || stopped || event.reason !== "startup" || ctx.mode !== "tui") {
+      return;
+    }
+    started = true;
+    queueInitialPrompt();
+  });
+
+  pi.on("turn_end", (event, ctx) => {
+    if (!started || stopped || compacting || ctx.mode !== "tui") {
+      return;
+    }
+    if (event.message.role !== "assistant") {
+      return;
+    }
+    switch (event.message.stopReason) {
+      case "aborted":
+      case "error":
+        stopped = true;
+        return;
+      case "toolUse":
+        return;
+    }
+    if (shouldCompactBeforeFollowup(event, ctx)) {
+      compactThenFollowup(ctx);
+      return;
+    }
+    queueFollowup();
+  });
+
+  pi.on("session_shutdown", () => {
+    stopped = true;
+  });
+}
+
+function shouldCompactBeforeFollowup(event: TurnEndEvent, ctx: ExtensionContext): boolean {
+  const contextPercent = currentContextPercent(event, ctx);
+  return contextPercent !== undefined && contextPercent >= compactAtContextPercent;
+}
+
+function currentContextPercent(event: TurnEndEvent, ctx: ExtensionContext): number | undefined {
+  const usage = ctx.getContextUsage();
+  if (usage?.percent !== undefined && usage.percent !== null) {
+    return usage.percent;
+  }
+  if (event.message.role !== "assistant") {
+    return undefined;
+  }
+  const contextWindow = ctx.model?.contextWindow;
+  if (contextWindow === undefined || contextWindow <= 0) {
+    return undefined;
+  }
+  return (event.message.usage.totalTokens / contextWindow) * 100;
+}
+`;
+}

package/dist/src/pi/extension-sources/startup-model-selector.js

@@ -0,0 +1,78 @@
+export function startupModelSelectorExtensionSource(options) {
+    const startupModelsSource = JSON.stringify(options.models);
+    return `import type { ExtensionAPI, SettingsManager } from "@earendil-works/pi-coding-agent";
+import { ModelSelectorComponent } from "@earendil-works/pi-coding-agent";
+
+type SelectedModel = Parameters<ExtensionAPI["setModel"]>[0];
+const startupModels = ${startupModelsSource} as const;
+const startupModelKeys = new Set(startupModels.map((model) => modelKey(model)));
+
+export default function localpiStartupModelSelector(pi: ExtensionAPI): void {
+  let opened = false;
+
+  pi.on("session_start", async (event, ctx) => {
+    if (opened || event.reason !== "startup" || ctx.mode !== "tui") {
+      return;
+    }
+
+    const selectableModels = startupAvailableModels(ctx.modelRegistry);
+    if (selectableModels.length <= 1) {
+      return;
+    }
+    const scopedModels = selectableModels.map((model) => ({ model }));
+
+    opened = true;
+    const selected = await ctx.ui.custom<SelectedModel | undefined>((tui, _theme, _keybindings, done) => {
+      const settings = {
+        setDefaultModelAndProvider: () => {}
+      } as unknown as SettingsManager;
+      return new ModelSelectorComponent(
+        tui,
+        ctx.model,
+        settings,
+        startupModelRegistry(ctx.modelRegistry) as typeof ctx.modelRegistry,
+        scopedModels,
+        (model) => done(model),
+        () => done(undefined)
+      );
+    });
+
+    if (selected === undefined) {
+      return;
+    }
+
+    const ok = await pi.setModel(selected);
+    if (!ok) {
+      ctx.ui.notify(\`No API key for \${selected.provider}/\${selected.id}\`, "error");
+    }
+  });
+}
+
+function startupAvailableModels(registry: {
+  getAvailable(): SelectedModel[];
+}): SelectedModel[] {
+  return registry.getAvailable().filter((model) => startupModelKeys.has(modelKey(model)));
+}
+
+function startupModelRegistry(registry: {
+  refresh(): void;
+  getError(): string | undefined;
+  getAvailable(): SelectedModel[];
+  find(provider: string, modelId: string): SelectedModel | undefined;
+}): typeof registry {
+  return {
+    refresh: () => registry.refresh(),
+    getError: () => registry.getError(),
+    getAvailable: () => startupAvailableModels(registry),
+    find: (provider, modelId) => {
+      const model = registry.find(provider, modelId);
+      return model !== undefined && startupModelKeys.has(modelKey(model)) ? model : undefined;
+    }
+  };
+}
+
+function modelKey(model: { readonly provider: string; readonly id: string }): string {
+  return \`\${model.provider}\\u0000\${model.id}\`;
+}
+`;
+}

package/dist/src/pi/extension-sources/thinking-control.js

@@ -0,0 +1,79 @@
+export function thinkingControlExtensionSource(settingsPath) {
+    const settingsPathSource = JSON.stringify(settingsPath);
+    return `import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+type ThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh";
+
+const levels: readonly ThinkingLevel[] = ["off", "minimal", "low", "medium", "high", "xhigh"];
+const settingsPath = ${settingsPathSource};
+
+export default function localpiThinkingControl(pi: ExtensionAPI): void {
+  pi.registerCommand("thinking", {
+    description: "Set localpi thinking level",
+    getArgumentCompletions: (prefix) => {
+      const trimmed = prefix.trim().toLowerCase();
+      const matches = levels.filter((level) => level.startsWith(trimmed));
+      return matches.length === 0 ? null : matches.map((level) => ({ value: level, label: level }));
+    },
+    handler: async (args, ctx) => {
+      const requested = parseThinkingLevel(args);
+      const level = requested ?? (await promptThinkingLevel(pi.getThinkingLevel(), ctx));
+      if (level === undefined) {
+        return;
+      }
+      pi.setThinkingLevel(level);
+      const actual = pi.getThinkingLevel();
+      await persistThinking(actual);
+      ctx.ui.notify(
+        actual === level ? \`thinking: \${actual}\` : \`thinking: \${actual} (clamped from \${level})\`,
+        actual === level ? "info" : "warning"
+      );
+    }
+  });
+
+  pi.on("thinking_level_select", async (event, ctx) => {
+    await persistThinking(event.level);
+    ctx.ui.setStatus("localpi-thinking", \`thinking: \${event.level}\`);
+  });
+
+  pi.on("session_shutdown", async (_event, ctx) => {
+    await persistThinking(pi.getThinkingLevel());
+    ctx.ui.setStatus("localpi-thinking", undefined);
+  });
+}
+
+async function persistThinking(level: ThinkingLevel): Promise<void> {
+  const settings = await readSettings();
+  settings.thinking = level;
+  await mkdir(dirname(settingsPath), { recursive: true });
+  await writeFile(settingsPath, \`\${JSON.stringify(settings, null, 2)}\\n\`, "utf8");
+}
+
+async function readSettings(): Promise<Record<string, unknown>> {
+  try {
+    const value = JSON.parse(await readFile(settingsPath, "utf8"));
+    return value && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : {};
+  } catch {
+    return {};
+  }
+}
+
+async function promptThinkingLevel(
+  current: ThinkingLevel,
+  ctx: { readonly ui: { select(title: string, options: string[]): Promise<string | undefined> } }
+): Promise<ThinkingLevel | undefined> {
+  const selected = await ctx.ui.select(
+    "Thinking level",
+    levels.map((level) => (level === current ? \`\${level} (current)\` : level))
+  );
+  return selected === undefined ? undefined : parseThinkingLevel(selected);
+}
+
+function parseThinkingLevel(value: string): ThinkingLevel | undefined {
+  const normalized = value.trim().split(/\\s+/u)[0]?.toLowerCase();
+  return levels.find((level) => level === normalized);
+}
+`;
+}

package/dist/src/pi/extension-sources/token-status.js

@@ -0,0 +1,177 @@
+export function tokenStatusExtensionSource() {
+    return `import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+type Usage = {
+  input?: number;
+  output?: number;
+  cacheRead?: number;
+  cacheWrite?: number;
+  totalTokens?: number;
+};
+
+type TurnState = {
+  startedAt: number;
+  firstOutputAt?: number;
+  outputText: string;
+  estimatedOutputTokens: number;
+  lastStatusAt: number;
+};
+
+export default function localpiTokenStatus(pi: ExtensionAPI): void {
+  let currentTurn: TurnState | undefined;
+
+  pi.on("turn_start", () => {
+    currentTurn = {
+      startedAt: Date.now(),
+      outputText: "",
+      estimatedOutputTokens: 0,
+      lastStatusAt: 0
+    };
+  });
+
+  pi.on("message_update", (event, ctx) => {
+    const state = currentTurn;
+    if (!ctx.hasUI || state === undefined) {
+      return;
+    }
+    const now = Date.now();
+    const update = textUpdateFromUnknown(event.assistantMessageEvent ?? event.message ?? event);
+    if (update.kind === "delta") {
+      state.outputText += update.text;
+    } else if (update.text.length > state.outputText.length) {
+      state.outputText = update.text;
+    }
+    state.estimatedOutputTokens = Math.ceil(state.outputText.length / 4);
+    if (state.firstOutputAt === undefined && state.outputText.length > 0) {
+      state.firstOutputAt = now;
+    }
+    if (now - state.lastStatusAt < 250) {
+      return;
+    }
+    state.lastStatusAt = now;
+    ctx.ui.setStatus("localpi-perf", ctx.ui.theme.fg("dim", statusText(state, now)));
+  });
+
+  pi.on("turn_end", (event, ctx) => {
+    const state = currentTurn ?? {
+      startedAt: Date.now(),
+      outputText: "",
+      estimatedOutputTokens: 0,
+      lastStatusAt: 0
+    };
+    currentTurn = undefined;
+
+    if (!ctx.hasUI || event.message.role !== "assistant") {
+      return;
+    }
+
+    const usage = event.message.usage as Usage | undefined;
+    const output = usage?.output ?? state.estimatedOutputTokens;
+    const input = usage?.input ?? 0;
+    const cacheRead = usage?.cacheRead ?? 0;
+    const cacheWrite = usage?.cacheWrite ?? 0;
+    const now = Date.now();
+    const elapsedSeconds = elapsed(state, now);
+    const decodeSeconds = generationElapsed(state, now);
+    const prefillText = prefillStatusText(state, input, cacheWrite);
+    const context = ctx.getContextUsage();
+    const contextText =
+      context && context.percent !== null
+        ? \`ctx \${Math.round(context.percent)}%/\${Math.round(context.contextWindow / 1000)}k\`
+        : "ctx ?";
+
+    ctx.ui.setStatus(
+      "localpi-perf",
+      ctx.ui.theme.fg(
+        "dim",
+        [
+          \`gen \${(output / decodeSeconds).toFixed(1)} tok/s\`,
+          prefillText,
+          \`out \${output}\`,
+          \`in \${input}\`,
+          cacheRead > 0 ? \`cache \${cacheRead}\` : undefined,
+          cacheWrite > 0 ? \`cw \${cacheWrite}\` : undefined,
+          \`\${elapsedSeconds.toFixed(1)}s\`,
+          contextText
+        ]
+          .filter(Boolean)
+          .join(" | ")
+      )
+    );
+  });
+
+  pi.on("session_shutdown", (_event, ctx) => {
+    if (ctx.hasUI) {
+      ctx.ui.setStatus("localpi-perf", "");
+    }
+  });
+}
+
+function statusText(state: TurnState, now: number): string {
+  const elapsedSeconds = elapsed(state, now);
+  if (state.firstOutputAt === undefined) {
+    return \`prefill \${elapsedSeconds.toFixed(1)}s | out ~\${state.estimatedOutputTokens}\`;
+  }
+  const decodeSeconds = generationElapsed(state, now);
+  const prefillSeconds = secondsBetween(state.startedAt, state.firstOutputAt);
+  return [
+    \`gen \${(state.estimatedOutputTokens / decodeSeconds).toFixed(1)} tok/s\`,
+    \`out ~\${state.estimatedOutputTokens}\`,
+    \`prefill \${prefillSeconds.toFixed(1)}s\`,
+    \`total \${elapsedSeconds.toFixed(1)}s\`
+  ].join(" | ");
+}
+
+function prefillStatusText(
+  state: TurnState,
+  input: number,
+  cacheWrite: number
+): string | undefined {
+  const tokens = prefillTokenCount(input, cacheWrite);
+  if (state.firstOutputAt === undefined || tokens <= 0) {
+    return undefined;
+  }
+  const seconds = secondsBetween(state.startedAt, state.firstOutputAt);
+  return \`prefill \${(tokens / seconds).toFixed(1)} tok/s\`;
+}
+
+function prefillTokenCount(input: number, cacheWrite: number): number {
+  return Math.max(input + cacheWrite, 0);
+}
+
+function generationElapsed(state: TurnState, now: number): number {
+  return secondsBetween(state.firstOutputAt ?? state.startedAt, now);
+}
+
+function elapsed(state: TurnState, now: number): number {
+  return secondsBetween(state.startedAt, now);
+}
+
+function secondsBetween(start: number, end: number): number {
+  return Math.max((end - start) / 1000, 0.001);
+}
+
+type TextUpdate = {
+  kind: "delta" | "snapshot";
+  text: string;
+};
+
+function textUpdateFromUnknown(value: unknown): TextUpdate {
+  if (typeof value === "string") {
+    return { kind: "snapshot", text: value };
+  }
+  if (value && typeof value === "object") {
+    const object = value as Record<string, unknown>;
+    const delta = object["delta"];
+    const text = object["text"] ?? object["content"];
+    if (typeof delta === "string") {
+      return { kind: "delta", text: delta };
+    }
+    if (typeof text === "string") {
+      return { kind: "snapshot", text };
+    }
+  }
+  return { kind: "snapshot", text: "" };
+}
+`;
+}

package/dist/src/pi/extension-sources/tool-approval.js

@@ -0,0 +1,45 @@
+export function approvalExtensionSource() {
+    return `import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+export default function localpiToolApproval(pi: ExtensionAPI): void {
+  pi.on("before_agent_start", (event) => ({
+    systemPrompt:
+      event.systemPrompt +
+      "\\n\\nTool approval rule: if any tool result says the tool was blocked, denied, or requires approval, the tool did not run. Do not claim blocked tools ran."
+  }));
+
+  pi.on("tool_call", async (event, ctx) => {
+    const input = formatInput(event.input);
+
+    if (!ctx.hasUI) {
+      return {
+        block: true,
+        reason: \`Tool call "\${event.toolName}" was blocked and did not run because interactive approval is required.\`
+      };
+    }
+
+    const ok = await ctx.ui.confirm(\`Allow tool call: \${event.toolName}?\`, input);
+    if (!ok) {
+      return { block: true, reason: "Tool call was blocked by the user and did not run." };
+    }
+
+    return undefined;
+  });
+}
+
+function formatInput(input: unknown): string {
+  let text: string;
+  try {
+    text = JSON.stringify(input, null, 2);
+  } catch {
+    text = String(input);
+  }
+
+  const maxLength = 4000;
+  if (text.length <= maxLength) {
+    return text;
+  }
+  return \`\${text.slice(0, maxLength)}\\n... truncated ...\`;
+}
+`;
+}

package/dist/src/pi/extensions.js

@@ -1,7 +1,12 @@
 import { mkdir, writeFile } from "node:fs/promises";
 import path from "node:path";
-import { settingsStatePath } from "../localpi/settings-state.js";
+import { localpiSettingsPath } from "../localpi/settings-state.js";
 import { resolveDemoPrompts } from "./demo.js";
+import { demoModeExtensionSource } from "./extension-sources/demo-mode.js";
+import { startupModelSelectorExtensionSource } from "./extension-sources/startup-model-selector.js";
+import { thinkingControlExtensionSource } from "./extension-sources/thinking-control.js";
+import { tokenStatusExtensionSource } from "./extension-sources/token-status.js";
+import { approvalExtensionSource } from "./extension-sources/tool-approval.js";
 export async function writeDefaultExtensions(options, extensionOptions = {}) {
     const extensionDir = path.join(options.stateDir, "pi-extensions");
     await mkdir(extensionDir, { recursive: true });
@@ -12,7 +17,7 @@ export async function writeDefaultExtensions(options, extensionOptions = {}) {
     if (options.demo) {
         paths.push(await writeExtension(extensionDir, "demo-mode.ts", demoModeExtensionSource(await resolveDemoPrompts(options))));
     }
-    paths.push(await writeExtension(extensionDir, "thinking-control.ts", thinkingControlExtensionSource(settingsStatePath(options))));
+    paths.push(await writeExtension(extensionDir, "thinking-control.ts", thinkingControlExtensionSource(localpiSettingsPath(options))));
     if (options.approval) {
         paths.push(await writeExtension(extensionDir, "tool-approval.ts", approvalExtensionSource()));
     }
@@ -29,136 +34,6 @@ async function writeExtension(extensionDir, name, source) {
     await writeFile(extensionPath, source, "utf8");
     return extensionPath;
 }
-function demoModeExtensionSource(prompts) {
-    const initialPromptSource = JSON.stringify(prompts.initial);
-    const followupPromptSource = JSON.stringify(prompts.followup);
-    return `import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-
-const initialPrompt = ${initialPromptSource};
-const followupPrompt = ${followupPromptSource};
-
-export default function localpiDemoMode(pi: ExtensionAPI): void {
-  let started = false;
-  let stopped = false;
-
-  pi.on("session_start", (event, ctx) => {
-    if (started || stopped || event.reason !== "startup" || ctx.mode !== "tui") {
-      return;
-    }
-    started = true;
-    queueMicrotask(() => {
-      if (!stopped) {
-        pi.sendUserMessage(initialPrompt);
-      }
-    });
-  });
-
-  pi.on("turn_end", (event, ctx) => {
-    if (!started || stopped || ctx.mode !== "tui") {
-      return;
-    }
-    if (event.message.role !== "assistant") {
-      return;
-    }
-    switch (event.message.stopReason) {
-      case "aborted":
-      case "error":
-        stopped = true;
-        return;
-      case "toolUse":
-        return;
-    }
-    queueMicrotask(() => {
-      if (!stopped) {
-        pi.sendUserMessage(followupPrompt, { deliverAs: "followUp" });
-      }
-    });
-  });
-
-  pi.on("session_shutdown", () => {
-    stopped = true;
-  });
-}
-`;
-}
-function startupModelSelectorExtensionSource(options) {
-    const startupModelsSource = JSON.stringify(options.models);
-    return `import type { ExtensionAPI, SettingsManager } from "@earendil-works/pi-coding-agent";
-import { ModelSelectorComponent } from "@earendil-works/pi-coding-agent";
-
-type SelectedModel = Parameters<ExtensionAPI["setModel"]>[0];
-const startupModels = ${startupModelsSource} as const;
-const startupModelKeys = new Set(startupModels.map((model) => modelKey(model)));
-
-export default function localpiStartupModelSelector(pi: ExtensionAPI): void {
-  let opened = false;
-
-  pi.on("session_start", async (event, ctx) => {
-    if (opened || event.reason !== "startup" || ctx.mode !== "tui") {
-      return;
-    }
-
-    const selectableModels = startupAvailableModels(ctx.modelRegistry);
-    if (selectableModels.length <= 1) {
-      return;
-    }
-    const scopedModels = selectableModels.map((model) => ({ model }));
-
-    opened = true;
-    const selected = await ctx.ui.custom<SelectedModel | undefined>((tui, _theme, _keybindings, done) => {
-      const settings = {
-        setDefaultModelAndProvider: () => {}
-      } as unknown as SettingsManager;
-      return new ModelSelectorComponent(
-        tui,
-        ctx.model,
-        settings,
-        startupModelRegistry(ctx.modelRegistry) as typeof ctx.modelRegistry,
-        scopedModels,
-        (model) => done(model),
-        () => done(undefined)
-      );
-    });
-
-    if (selected === undefined) {
-      return;
-    }
-
-    const ok = await pi.setModel(selected);
-    if (!ok) {
-      ctx.ui.notify(\`No API key for \${selected.provider}/\${selected.id}\`, "error");
-    }
-  });
-}
-
-function startupAvailableModels(registry: {
-  getAvailable(): SelectedModel[];
-}): SelectedModel[] {
-  return registry.getAvailable().filter((model) => startupModelKeys.has(modelKey(model)));
-}
-
-function startupModelRegistry(registry: {
-  refresh(): void;
-  getError(): string | undefined;
-  getAvailable(): SelectedModel[];
-  find(provider: string, modelId: string): SelectedModel | undefined;
-}): typeof registry {
-  return {
-    refresh: () => registry.refresh(),
-    getError: () => registry.getError(),
-    getAvailable: () => startupAvailableModels(registry),
-    find: (provider, modelId) => {
-      const model = registry.find(provider, modelId);
-      return model !== undefined && startupModelKeys.has(modelKey(model)) ? model : undefined;
-    }
-  };
-}
-
-function modelKey(model: { readonly provider: string; readonly id: string }): string {
-  return \`\${model.provider}\\u0000\${model.id}\`;
-}
-`;
-}
 function localpiSystemPrompt(approval) {
     return [
         "You are running through localpi, a local Pi launcher for local models.",
@@ -169,260 +44,3 @@ function localpiSystemPrompt(approval) {
         "Prefer answering directly when tools are not needed."
     ].join("\n");
 }
-function approvalExtensionSource() {
-    return `import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-
-export default function localpiToolApproval(pi: ExtensionAPI): void {
-  pi.on("before_agent_start", (event) => ({
-    systemPrompt:
-      event.systemPrompt +
-      "\\n\\nTool approval rule: if any tool result says the tool was blocked, denied, or requires approval, the tool did not run. Do not claim blocked tools ran."
-  }));
-
-  pi.on("tool_call", async (event, ctx) => {
-    const input = formatInput(event.input);
-
-    if (!ctx.hasUI) {
-      return {
-        block: true,
-        reason: \`Tool call "\${event.toolName}" was blocked and did not run because interactive approval is required.\`
-      };
-    }
-
-    const ok = await ctx.ui.confirm(\`Allow tool call: \${event.toolName}?\`, input);
-    if (!ok) {
-      return { block: true, reason: "Tool call was blocked by the user and did not run." };
-    }
-
-    return undefined;
-  });
-}
-
-function formatInput(input: unknown): string {
-  let text: string;
-  try {
-    text = JSON.stringify(input, null, 2);
-  } catch {
-    text = String(input);
-  }
-
-  const maxLength = 4000;
-  if (text.length <= maxLength) {
-    return text;
-  }
-  return \`\${text.slice(0, maxLength)}\\n... truncated ...\`;
-}
-`;
-}
-function tokenStatusExtensionSource() {
-    return `import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-
-type Usage = {
-  input?: number;
-  output?: number;
-  cacheRead?: number;
-  cacheWrite?: number;
-  totalTokens?: number;
-};
-
-type TurnState = {
-  startedAt: number;
-  outputText: string;
-  estimatedOutputTokens: number;
-  lastStatusAt: number;
-};
-
-export default function localpiTokenStatus(pi: ExtensionAPI): void {
-  let currentTurn: TurnState | undefined;
-
-  pi.on("turn_start", () => {
-    currentTurn = {
-      startedAt: Date.now(),
-      outputText: "",
-      estimatedOutputTokens: 0,
-      lastStatusAt: 0
-    };
-  });
-
-  pi.on("message_update", (event, ctx) => {
-    const state = currentTurn;
-    if (!ctx.hasUI || state === undefined) {
-      return;
-    }
-    const update = textUpdateFromUnknown(event.assistantMessageEvent ?? event.message ?? event);
-    if (update.kind === "delta") {
-      state.outputText += update.text;
-    } else if (update.text.length > state.outputText.length) {
-      state.outputText = update.text;
-    }
-    state.estimatedOutputTokens = Math.ceil(state.outputText.length / 4);
-    if (Date.now() - state.lastStatusAt < 250) {
-      return;
-    }
-    state.lastStatusAt = Date.now();
-    ctx.ui.setStatus("localpi-perf", ctx.ui.theme.fg("dim", statusText(state)));
-  });
-
-  pi.on("turn_end", (event, ctx) => {
-    const state = currentTurn ?? {
-      startedAt: Date.now(),
-      outputText: "",
-      estimatedOutputTokens: 0,
-      lastStatusAt: 0
-    };
-    currentTurn = undefined;
-
-    if (!ctx.hasUI || event.message.role !== "assistant") {
-      return;
-    }
-
-    const usage = event.message.usage as Usage | undefined;
-    const output = usage?.output ?? state.estimatedOutputTokens;
-    const input = usage?.input ?? 0;
-    const cacheRead = usage?.cacheRead ?? 0;
-    const cacheWrite = usage?.cacheWrite ?? 0;
-    const elapsedSeconds = elapsed(state);
-    const context = ctx.getContextUsage();
-    const contextText =
-      context && context.percent !== null
-        ? \`ctx \${Math.round(context.percent)}%/\${Math.round(context.contextWindow / 1000)}k\`
-        : "ctx ?";
-
-    ctx.ui.setStatus(
-      "localpi-perf",
-      ctx.ui.theme.fg(
-        "dim",
-        [
-          \`\${(output / elapsedSeconds).toFixed(1)} tok/s\`,
-          \`out \${output}\`,
-          \`in \${input}\`,
-          cacheRead > 0 ? \`cache \${cacheRead}\` : undefined,
-          cacheWrite > 0 ? \`cw \${cacheWrite}\` : undefined,
-          \`\${elapsedSeconds.toFixed(1)}s\`,
-          contextText
-        ]
-          .filter(Boolean)
-          .join(" | ")
-      )
-    );
-  });
-
-  pi.on("session_shutdown", (_event, ctx) => {
-    if (ctx.hasUI) {
-      ctx.ui.setStatus("localpi-perf", "");
-    }
-  });
-}
-
-function statusText(state: TurnState): string {
-  const elapsedSeconds = elapsed(state);
-  return \`\${(state.estimatedOutputTokens / elapsedSeconds).toFixed(1)} tok/s | out ~\${state.estimatedOutputTokens} | \${elapsedSeconds.toFixed(1)}s\`;
-}
-
-function elapsed(state: TurnState): number {
-  return Math.max((Date.now() - state.startedAt) / 1000, 0.001);
-}
-
-type TextUpdate = {
-  kind: "delta" | "snapshot";
-  text: string;
-};
-
-function textUpdateFromUnknown(value: unknown): TextUpdate {
-  if (typeof value === "string") {
-    return { kind: "snapshot", text: value };
-  }
-  if (value && typeof value === "object") {
-    const object = value as Record<string, unknown>;
-    const delta = object["delta"];
-    const text = object["text"] ?? object["content"];
-    if (typeof delta === "string") {
-      return { kind: "delta", text: delta };
-    }
-    if (typeof text === "string") {
-      return { kind: "snapshot", text };
-    }
-  }
-  return { kind: "snapshot", text: "" };
-}
-`;
-}
-function thinkingControlExtensionSource(settingsPath) {
-    const settingsPathSource = JSON.stringify(settingsPath);
-    return `import { mkdir, readFile, writeFile } from "node:fs/promises";
-import { dirname } from "node:path";
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-
-type ThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh";
-
-const levels: readonly ThinkingLevel[] = ["off", "minimal", "low", "medium", "high", "xhigh"];
-const settingsPath = ${settingsPathSource};
-
-export default function localpiThinkingControl(pi: ExtensionAPI): void {
-  pi.registerCommand("thinking", {
-    description: "Set localpi thinking level",
-    getArgumentCompletions: (prefix) => {
-      const trimmed = prefix.trim().toLowerCase();
-      const matches = levels.filter((level) => level.startsWith(trimmed));
-      return matches.length === 0 ? null : matches.map((level) => ({ value: level, label: level }));
-    },
-    handler: async (args, ctx) => {
-      const requested = parseThinkingLevel(args);
-      const level = requested ?? (await promptThinkingLevel(pi.getThinkingLevel(), ctx));
-      if (level === undefined) {
-        return;
-      }
-      pi.setThinkingLevel(level);
-      const actual = pi.getThinkingLevel();
-      await persistThinking(actual);
-      ctx.ui.notify(
-        actual === level ? \`thinking: \${actual}\` : \`thinking: \${actual} (clamped from \${level})\`,
-        actual === level ? "info" : "warning"
-      );
-    }
-  });
-
-  pi.on("thinking_level_select", async (event, ctx) => {
-    await persistThinking(event.level);
-    ctx.ui.setStatus("localpi-thinking", \`thinking: \${event.level}\`);
-  });
-
-  pi.on("session_shutdown", async (_event, ctx) => {
-    await persistThinking(pi.getThinkingLevel());
-    ctx.ui.setStatus("localpi-thinking", undefined);
-  });
-}
-
-async function persistThinking(level: ThinkingLevel): Promise<void> {
-  const settings = await readSettings();
-  settings.thinking = level;
-  await mkdir(dirname(settingsPath), { recursive: true });
-  await writeFile(settingsPath, \`\${JSON.stringify(settings, null, 2)}\\n\`, "utf8");
-}
-
-async function readSettings(): Promise<Record<string, unknown>> {
-  try {
-    const value = JSON.parse(await readFile(settingsPath, "utf8"));
-    return value && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : {};
-  } catch {
-    return {};
-  }
-}
-
-async function promptThinkingLevel(
-  current: ThinkingLevel,
-  ctx: { readonly ui: { select(title: string, options: string[]): Promise<string | undefined> } }
-): Promise<ThinkingLevel | undefined> {
-  const selected = await ctx.ui.select(
-    "Thinking level",
-    levels.map((level) => (level === current ? \`\${level} (current)\` : level))
-  );
-  return selected === undefined ? undefined : parseThinkingLevel(selected);
-}
-
-function parseThinkingLevel(value: string): ThinkingLevel | undefined {
-  const normalized = value.trim().split(/\\s+/u)[0]?.toLowerCase();
-  return levels.find((level) => level === normalized);
-}
-`;
-}

package/dist/src/pi/version.js

@@ -0,0 +1,25 @@
+import { createRequire } from "node:module";
+const require = createRequire(import.meta.url);
+const packageMetadata = loadPackageMetadata();
+if (typeof packageMetadata.version !== "string") {
+    throw new Error("localpi package metadata is missing a string version");
+}
+export const localpiVersion = packageMetadata.version;
+function loadPackageMetadata() {
+    for (const packagePath of ["../../package.json", "../../../package.json"]) {
+        try {
+            return require(packagePath);
+        }
+        catch (error) {
+            if (!isModuleNotFound(error)) {
+                throw error;
+            }
+        }
+    }
+    throw new Error("localpi package metadata could not be loaded");
+}
+function isModuleNotFound(error) {
+    return (error instanceof Error &&
+        "code" in error &&
+        error.code === "MODULE_NOT_FOUND");
+}

package/docs/runtime-specification.md

@@ -150,7 +150,7 @@ session dir: ~/.local/state/localpi/sessions
 Localpi installs two default extensions:
 
 - tool approval gate: ask before each tool call, and tell the model clearly when a tool call was blocked
-- token status: show live output token estimate while streaming and final exact token stats when usage data is available
+- token status: show live generation speed while streaming, then final prefill and generation rates when usage data is available
 
 ## System Prompt
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "localpi",
-  "version": "0.3.0",
-  "description": "Pi-compatible local model launcher with managed llama-server support.",
+  "version": "0.5.0",
+  "description": "Swiss army knife for running Pi with local inference engines.",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -53,5 +53,8 @@
     "typescript": "^5.0.0",
     "typescript-eslint": "^8.0.0",
     "vitest": "^3.0.0"
+  },
+  "dependencies": {
+    "@dutifuldev/pi-factory": "^0.1.1"
   }
 }

package/dist/src/pi/config.js

@@ -1,108 +0,0 @@
-import { mkdir, writeFile } from "node:fs/promises";
-import path from "node:path";
-export async function writeRuntimeConfig(options, connection) {
-    const configDir = path.join(options.stateDir, "pi-config-runtime");
-    await mkdir(configDir, { recursive: true });
-    const modelsPath = path.join(configDir, "models.json");
-    const settingsPath = path.join(configDir, "settings.json");
-    await writeFile(modelsPath, `${JSON.stringify(modelsConfig(options, connection), null, 2)}\n`);
-    await writeFile(settingsPath, `${JSON.stringify(settingsConfig(options, connection), null, 2)}\n`);
-    return { configDir, modelsPath, settingsPath };
-}
-function modelsConfig(options, connection) {
-    const models = connection.catalogModels.length === 0 ? fallbackCatalog(connection) : connection.catalogModels;
-    return {
-        providers: Object.fromEntries(groupedByProvider(models).map((entry) => [
-            entry.providerId,
-            providerConfig(options, connection, entry)
-        ]))
-    };
-}
-function groupedByProvider(models) {
-    const groups = new Map();
-    for (const model of models) {
-        const existing = groups.get(model.providerId);
-        groups.set(model.providerId, existing === undefined
-            ? { providerId: model.providerId, baseUrl: model.baseUrl, models: [model] }
-            : { ...existing, models: [...existing.models, model] });
-    }
-    return [...groups.values()];
-}
-function providerConfig(options, connection, group) {
-    return {
-        baseUrl: group.baseUrl,
-        api: "openai-completions",
-        apiKey: "local",
-        compat: {
-            supportsDeveloperRole: false,
-            supportsReasoningEffort: false
-        },
-        models: group.models.map((model) => modelConfig(options, connection, model))
-    };
-}
-function modelConfig(options, connection, model) {
-    return withoutUndefined({
-        id: model.modelId,
-        name: model.displayName,
-        reasoning: model.reasoning ?? false,
-        compat: model.thinkingFormat === undefined ? undefined : { thinkingFormat: model.thinkingFormat },
-        input: ["text"],
-        contextWindow: modelContextWindow(options, model),
-        maxTokens: model.maxTokens ?? options.maxTokens,
-        cost: {
-            input: 0,
-            output: 0,
-            cacheRead: 0,
-            cacheWrite: 0
-        }
-    });
-}
-function modelContextWindow(options, model) {
-    if (options.contextWindow !== undefined) {
-        return options.contextWindow;
-    }
-    return model.contextWindow;
-}
-function fallbackCatalog(connection) {
-    return [
-        {
-            providerId: connection.providerId,
-            providerName: connection.providerName,
-            runtime: connection.runtime.startsWith("llama-server")
-                ? "managed-llama-server"
-                : "openai-compatible",
-            baseUrl: connection.baseUrl,
-            modelId: connection.model,
-            aliases: [],
-            displayName: `Local model (${connection.model})`,
-            reasoning: false,
-            capabilities: ["text"],
-            availability: "loaded",
-            ...(connection.contextWindow === undefined ? {} : { contextWindow: connection.contextWindow })
-        }
-    ];
-}
-function withoutUndefined(value) {
-    return Object.fromEntries(Object.entries(value).filter(([, entryValue]) => entryValue !== undefined));
-}
-function settingsConfig(options, connection) {
-    const contextWindow = options.contextWindow ?? connection.contextWindow;
-    return {
-        defaultProvider: connection.providerId,
-        defaultModel: connection.model,
-        defaultThinkingLevel: options.thinking,
-        enableInstallTelemetry: false,
-        quietStartup: true,
-        compaction: compactionConfig(contextWindow)
-    };
-}
-function compactionConfig(contextWindow) {
-    if (contextWindow === undefined) {
-        return { enabled: false };
-    }
-    return {
-        enabled: true,
-        reserveTokens: Math.max(256, Math.min(16384, Math.floor(contextWindow / 4))),
-        keepRecentTokens: Math.max(512, Math.min(20000, Math.floor(contextWindow / 2)))
-    };
-}

package/dist/src/pi/launch.js

@@ -1,64 +0,0 @@
-import { spawn } from "node:child_process";
-import { mkdir } from "node:fs/promises";
-export async function createLaunchPlan(options, runtimeConfig, connection, extensions) {
-    await mkdir(options.sessionDir, { recursive: true });
-    return {
-        command: options.piCommand,
-        args: [
-            "--provider",
-            connection.providerId,
-            "--model",
-            connection.model,
-            "--thinking",
-            options.thinking,
-            ...extensionArgs(extensions),
-            "--append-system-prompt",
-            extensions.systemPrompt,
-            ...withDefaultTools(options.forwardedArgs, options.tools)
-        ],
-        env: {
-            PI_CODING_AGENT_DIR: runtimeConfig.configDir,
-            PI_CODING_AGENT_SESSION_DIR: options.sessionDir,
-            PI_OFFLINE: process.env["PI_OFFLINE"] ?? "1",
-            PI_TELEMETRY: process.env["PI_TELEMETRY"] ?? "0",
-            PI_SKIP_VERSION_CHECK: process.env["PI_SKIP_VERSION_CHECK"] ?? "1"
-        }
-    };
-}
-export async function execLaunchPlan(plan) {
-    const stdio = "inherit";
-    const child = spawn(shellCommand(plan.command, plan.args), {
-        shell: true,
-        stdio,
-        env: { ...process.env, ...plan.env }
-    });
-    child.stdout?.resume();
-    return await new Promise((resolve, reject) => {
-        child.on("error", reject);
-        child.on("exit", (code, signal) => {
-            if (signal !== null) {
-                process.kill(process.pid, signal);
-                return;
-            }
-            resolve(code ?? 0);
-        });
-    });
-}
-function shellCommand(command, args) {
-    return [command, ...args.map(shellQuote)].join(" ");
-}
-function shellQuote(value) {
-    return `'${value.replaceAll("'", "'\\''")}'`;
-}
-function extensionArgs(extensions) {
-    return extensions.paths.flatMap((extensionPath) => ["--extension", extensionPath]);
-}
-function withDefaultTools(args, tools) {
-    if (tools === undefined || hasToolFlag(args)) {
-        return args;
-    }
-    return ["--tools", tools, ...args];
-}
-function hasToolFlag(args) {
-    return args.some((arg) => arg === "--tools" || arg === "-t" || arg === "--no-tools" || arg === "-nt");
-}