localpi 0.1.0

package/dist/src/pi/extensions.js

@@ -0,0 +1,348 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+export async function writeDefaultExtensions(options, extensionOptions = {}) {
+    const extensionDir = path.join(options.stateDir, "pi-extensions");
+    await mkdir(extensionDir, { recursive: true });
+    const paths = [];
+    if (extensionOptions.startupModelSelector !== undefined) {
+        paths.push(await writeExtension(extensionDir, "startup-model-selector.ts", startupModelSelectorExtensionSource(extensionOptions.startupModelSelector)));
+    }
+    paths.push(await writeExtension(extensionDir, "thinking-control.ts", thinkingControlExtensionSource()));
+    if (options.approval) {
+        paths.push(await writeExtension(extensionDir, "tool-approval.ts", approvalExtensionSource()));
+    }
+    if (options.tokenStatus) {
+        paths.push(await writeExtension(extensionDir, "token-status.ts", tokenStatusExtensionSource()));
+    }
+    return {
+        paths,
+        systemPrompt: localpiSystemPrompt(options.approval)
+    };
+}
+async function writeExtension(extensionDir, name, source) {
+    const extensionPath = path.join(extensionDir, name);
+    await writeFile(extensionPath, source, "utf8");
+    return extensionPath;
+}
+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.",
+        approval
+            ? "Tool calls require user approval. If a tool result says it was blocked, denied, or requires approval, the tool did not run."
+            : "Tool approval is disabled for this session.",
+        "Do not claim that a blocked tool call ran.",
+        "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() {
+    return `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"];
+
+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();
+      ctx.ui.notify(
+        actual === level ? \`thinking: \${actual}\` : \`thinking: \${actual} (clamped from \${level})\`,
+        actual === level ? "info" : "warning"
+      );
+    }
+  });
+
+  pi.on("thinking_level_select", (event, ctx) => {
+    ctx.ui.setStatus("localpi-thinking", \`thinking: \${event.level}\`);
+  });
+
+  pi.on("session_shutdown", (_event, ctx) => {
+    ctx.ui.setStatus("localpi-thinking", undefined);
+  });
+}
+
+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/launch.js

@@ -0,0 +1,64 @@
+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");
+}

package/docs/2026-06-15-model-catalog-implementation-plan.md

@@ -0,0 +1,220 @@
+---
+title: Model Catalog Implementation Plan
+author: Bob <dutifulbob@gmail.com>
+date: 2026-06-15
+---
+
+# Model Catalog Implementation Plan
+
+Localpi should become a model catalog and launcher.
+
+The goal is that plain `localpi` can show every usable local model, let the user pick one, and still give Pi enough model config for `/model` to switch among the same choices during the session.
+
+## Target Behavior
+
+- `localpi` discovers available local model providers before Pi starts.
+- If exactly one usable model is available, localpi starts Pi with that model.
+- If multiple usable models are available, localpi shows an interactive provider/model picker.
+- If no external model is available, localpi can fall back to the managed `llama-server` default.
+- Explicit `--provider` and `--model` flags bypass the startup picker.
+- `--runtime vllm` should be accepted as a direct shortcut for the built-in vLLM provider.
+- Pi receives a generated `models.json` containing every discovered usable model, not just the selected one.
+- Pi receives a generated `settings.json` with the selected provider and model as the defaults.
+- Pi `/model` can switch among the launch-time catalog entries without localpi-specific extension behavior.
+
+The launch-time catalog is the first milestone. Live refresh after Pi has already started should be treated as a later Pi integration problem.
+
+## Design Principles
+
+- Keep model discovery, model selection, Pi config generation, and process management separate.
+- Treat LM Studio, vLLM, managed `llama-server`, and future backends as provider adapters.
+- Do not hide runtime side effects. Starting or stopping heavyweight model processes must be explicit or clearly prompted.
+- Do not use Pi extensions to smuggle basic model inventory into Pi. Model inventory belongs in generated Pi config.
+- Keep scripts deterministic. Non-interactive runs should not hang waiting for a picker.
+
+## Catalog Model
+
+Add a normalized catalog entry type.
+
+```ts
+type CatalogModel = {
+  readonly providerId: string;
+  readonly providerName: string;
+  readonly runtime: "openai-compatible" | "managed-llama-server";
+  readonly baseUrl: string;
+  readonly modelId: string;
+  readonly displayName: string;
+  readonly contextWindow?: number;
+  readonly maxTokens?: number;
+  readonly capabilities: readonly ModelCapability[];
+  readonly availability: "loaded" | "startable";
+};
+```
+
+Use the catalog entry as the only data shape passed from discovery into selection and Pi config generation.
+
+## Provider Registry
+
+Add a provider registry that combines built-in providers with user config.
+
+Built-in providers:
+
+- `lmstudio`: OpenAI-compatible, default base URL `http://127.0.0.1:1234/v1`, discovery enabled.
+- `vllm`: OpenAI-compatible, default base URL `http://127.0.0.1:8000/v1`, discovery enabled.
+- `llama-server`: managed localpi runtime, exposes configured aliases as startable models.
+
+Config-backed providers:
+
+- Additional vLLM and other OpenAI-compatible servers should be configured by provider id and base URL.
+- Localpi should not scan random ports for vLLM beyond the explicit built-in default.
+- A provider config can opt into or out of discovery.
+
+Example config:
+
+```json
+{
+  "providers": {
+    "vllm-qwen": {
+      "type": "openai-compatible",
+      "name": "vLLM Qwen",
+      "baseUrl": "http://127.0.0.1:8000/v1",
+      "discover": true
+    }
+  }
+}
+```
+
+## Provider Adapters
+
+Create one adapter interface.
+
+```ts
+type ProviderAdapter = {
+  readonly providerId: string;
+  discover(): Promise<readonly CatalogModel[]>;
+};
+```
+
+OpenAI-compatible adapter:
+
+- Probe `<baseUrl>/models`.
+- Convert every reported model id into a `CatalogModel`.
+- Preserve known context-window metadata when the endpoint reports it.
+- Treat connection failures as unavailable provider results, not fatal startup errors, unless the user explicitly selected that provider.
+
+Managed `llama-server` adapter:
+
+- Include the currently served localpi-owned model as `loaded`.
+- Include configured aliases as `startable` when their GGUF path exists.
+- Keep existing memory-safety rules before starting a selected startable model.
+
+## Selection Policy
+
+Selection should happen after catalog discovery.
+
+Interactive terminal:
+
+- If there is more than one usable model and no explicit model was requested, show a numbered picker.
+- Display provider and model together, for example `LM Studio / qwen3.6-35b-a3b-mtp`.
+- Let Enter choose the first ranked model.
+
+Non-interactive terminal:
+
+- Do not prompt.
+- Use a deterministic default.
+- If the default is ambiguous, fail with a message that lists available `--provider` and `--model` values.
+
+Explicit flags:
+
+- `--provider <id> --model <id>` selects an exact catalog entry.
+- `--model <provider>/<model>` can be added as a shorthand once provider ids are stable.
+- `--runtime lmstudio` and `--runtime vllm` select those built-in external providers directly.
+- Existing managed llama-server aliases should continue to work.
+
+## Pi Config Generation
+
+Change `writeRuntimeConfig` to receive the selected model and the full catalog.
+
+Generated `models.json` should include one provider entry per catalog provider.
+
+Generated `settings.json` should set:
+
+- `defaultProvider` to the selected provider id
+- `defaultModel` to the selected model id
+- current thinking, telemetry, startup, and compaction defaults as today
+
+Each catalog model should become one Pi model entry with:
+
+- `id`
+- `name`
+- `reasoning`
+- `input`
+- `contextWindow` when known
+- `maxTokens`
+- zero local cost
+
+This is what lets Pi `/model` switch among all launch-time catalog models without a localpi extension.
+
+## Runtime Start Rules
+
+Loaded models:
+
+- If the selected model is already loaded behind an external OpenAI-compatible endpoint, just launch Pi against it.
+
+Startable managed models:
+
+- If the selected model is a managed `llama-server` alias, start or reuse localpi-owned `llama-server`.
+- Preserve the existing rule that localpi should not silently start another heavyweight local runtime when LM Studio already has loaded models.
+
+External providers:
+
+- Never start or stop LM Studio, vLLM, TGI, Ollama, or other externally managed providers unless a future adapter explicitly owns that lifecycle.
+
+## Implementation Phases
+
+### Phase 1: Catalog Types And Discovery
+
+- Add catalog types.
+- Add provider registry loading.
+- Add OpenAI-compatible provider adapter.
+- Add managed `llama-server` provider adapter.
+- Unit-test discovery for loaded, unavailable, and startable models.
+
+### Phase 2: Startup Selection
+
+- Replace runtime-first resolution with catalog-first resolution.
+- Add terminal selector for interactive runs.
+- Keep deterministic non-interactive behavior.
+- Preserve explicit `--runtime`, `--provider`, and `--model` compatibility.
+
+### Phase 3: Pi Config From Catalog
+
+- Generate `models.json` from the full catalog.
+- Generate `settings.json` from the selected catalog entry.
+- Update launch planning to pass the selected provider/model.
+- Add tests proving Pi config contains multiple providers and models.
+
+### Phase 4: Runtime Lifecycle Integration
+
+- Start managed `llama-server` only when the selected catalog entry is startable.
+- Keep existing localpi-owned metadata and stop/reuse behavior.
+- Keep LM Studio/vLLM as externally managed.
+- Add tests for memory-safety prompts and failure messages.
+
+### Phase 5: Documentation And Migration
+
+- Document plain `localpi` selection behavior.
+- Document provider registry config.
+- Document non-interactive selection rules.
+- Document that Pi `/model` sees the launch-time catalog.
+- Document that live model refresh is not part of the first implementation.
+
+## Out Of Scope
+
+- Live refresh of Pi `/model` after Pi has started.
+- Starting or stopping LM Studio.
+- Guessing vLLM ports.
+- Global system model management.
+- Cloud provider authentication.
+- Classifier-specific model routing.
+- Localpager-specific behavior.