localpi 0.6.0 → 0.6.2

package/README.md

@@ -4,7 +4,7 @@
   <img src="assets/cover.svg" alt="localpi: an unopinionated Pi distribution that makes it easy to test and work with small local models on constrained systems" width="880">
 </p>
 
-Localpi is an unopinionated Pi distribution that makes it easy to test and work with small local models on constrained systems.
+Localpi is an unopinionated [Pi](https://pi.dev) distribution that makes it easy to test and work with small local models on constrained systems.
 
 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.
 
@@ -216,9 +216,10 @@ Approval still works: the adapter forwards Pi's extension dialogs to the ACP cli
 asks before a tool call runs. The adapter does not pass `--no-extensions`, so Pi extension discovery
 stays on.
 
-Pi has no ACP mode of its own. ACP support comes from `pi-acp` (MIT), which `package.json` pins to
-an exact version, and localpi never vendors its source. Set `LOCALPI_ACP_ADAPTER` to a path to run a
-different adapter build.
+Pi has no ACP mode of its own. ACP support comes from
+[`pi-acp`](https://github.com/svkozak/pi-acp) (MIT), which `package.json` pins to an exact version,
+and localpi never vendors its source. Set `LOCALPI_ACP_ADAPTER` to a path to run a different adapter
+build.
 
 ## Continue On Truncation
 
@@ -523,6 +524,7 @@ demowall record --session demowall-<timestamp> --out demo.mp4 --seconds 60
 - `--max-tokens <n>`: generated model max output tokens
 - `--continue-on-truncation <n>`: continue a reply cut off by the output limit, up to `n` times. Off by default, and `LOCALPI_CONTINUE_ON_TRUNCATION=<n>` sets the same limit
 - `--base-url <url>`: OpenAI-compatible endpoint for LM Studio or custom endpoints
+- `--api-key <value>`: Pi provider API key for this run. A literal value, an environment reference such as `${NAME}`, or a `!command`. Default: `local`. `LOCALPI_API_KEY` sets the same value
 - `--server-command <path>`: `llama-server` executable path
 - `--llama-server <path>`: alias for `--server-command`
 - `--host <host>`: managed `llama-server` host. Default: `127.0.0.1`
@@ -582,6 +584,7 @@ explicit `PI_OFFLINE=0` or `PI_OFFLINE=1` always wins.
 - `LOCALPI_MODEL`
 - `LOCALPI_PROVIDER`
 - `LOCALPI_BASE_URL`
+- `LOCALPI_API_KEY`
 - `LOCALPI_PROVIDERS_FILE`
 - `LOCALPI_MODEL_PROFILE`
 - `LOCALPI_MODEL_REASONING`
@@ -669,6 +672,20 @@ Model capability profiles can fill in metadata that OpenAI-compatible servers do
 
 `LOCALPAGER_AGENT_PROFILE`, `LOCALPAGER_AGENT_REASONING`, and `LOCALPAGER_AGENT_THINKING_FORMAT` are accepted as aliases so LocalPager Agent can pass the same profile metadata through to localpi.
 
+## Related Projects
+
+- [Pi](https://pi.dev) is the coding agent this distribution launches. Pi owns model detection, the
+  tool loop, streaming, slash commands, and the session. Its source is
+  [earendil-works/pi](https://github.com/earendil-works/pi).
+- [pi-factory](https://github.com/osolmaz/pi-factory) builds the Pi launch plan, the launch
+  environment, and the runtime config a session uses.
+- [pi-demo-mode](https://github.com/osolmaz/pi-demo-mode) is the shared extension behind demo mode.
+- [pi-acp](https://github.com/svkozak/pi-acp) is the adapter that ACP mode pins, for the
+  [Agent Client Protocol](https://agentclientprotocol.com). Localpi keeps no copy of its source.
+- Inference stacks: [llama.cpp](https://github.com/ggml-org/llama.cpp) and its `llama-server`,
+  [LM Studio](https://lmstudio.ai), [vLLM](https://github.com/vllm-project/vllm),
+  [SGLang](https://github.com/sgl-project/sglang), and [Ollama](https://ollama.com).
+
 ## Development
 
 ```bash

package/dist/src/localpi/options.js

@@ -19,6 +19,7 @@ export function defaultOptions() {
     return {
         runtime: parseRuntime(envString("LOCALPI_RUNTIME", "auto")),
         baseUrl: envOptionalBaseUrl("LOCALPI_BASE_URL"),
+        apiKey: envString("LOCALPI_API_KEY", "local"),
         model: process.env["LOCALPI_MODEL"],
         provider: process.env["LOCALPI_PROVIDER"],
         customProviderId: envString("LOCALPI_PROVIDER_ID", "local-openai"),
@@ -100,6 +101,8 @@ export function usage() {
         "  --provider <id>          catalog provider id to use",
         "  --model <alias|id|path>  model alias, backend id, or GGUF path",
         "  --base-url <url>         OpenAI-compatible endpoint",
+        "  --api-key <value>        Pi provider API key: a literal, ${NAME}, or !command",
+        "                          (LOCALPI_API_KEY=<value>, default: local)",
         "  --ctx <n>                model context window",
         "  --context-window <n>     alias for --ctx",
         "  --max-tokens <n>         generated model max output tokens",
@@ -189,6 +192,7 @@ const booleanFlagUpdaters = {
 const valueFlagUpdaters = {
     "--runtime": (options, value) => ({ ...options, runtime: parseRuntime(value) }),
     "--base-url": (options, value) => ({ ...options, baseUrl: normalizeBaseUrl(value) }),
+    "--api-key": (options, value) => ({ ...options, apiKey: value }),
     "--model": (options, value) => ({ ...options, model: value }),
     "--provider": (options, value) => ({ ...options, provider: value }),
     "--provider-id": (options, value) => ({ ...options, customProviderId: value }),

package/dist/src/pi/app.js

@@ -86,7 +86,7 @@ function providersForConnection(options, connection) {
         id: group.providerId,
         baseUrl: group.baseUrl,
         api: "openai-completions",
-        apiKey: "local",
+        apiKey: options.apiKey,
         compat: {
             supportsDeveloperRole: false,
             supportsReasoningEffort: false

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

@@ -1,6 +1,6 @@
 export function startupModelSelectorExtensionSource(options) {
     const startupModelsSource = JSON.stringify(options.models);
-    return `import type { ExtensionAPI, SettingsManager } from "@earendil-works/pi-coding-agent";
+    return `import type { ExtensionAPI, ModelRegistry, ModelRuntime } from "@earendil-works/pi-coding-agent";
 import { ModelSelectorComponent } from "@earendil-works/pi-coding-agent";
 
 type SelectedModel = Parameters<ExtensionAPI["setModel"]>[0];
@@ -22,20 +22,16 @@ export default function localpiStartupModelSelector(pi: ExtensionAPI): void {
     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(
+    const selected = await ctx.ui.custom<SelectedModel | undefined>((tui, _theme, _keybindings, done) =>
+      new ModelSelectorComponent(
         tui,
         ctx.model,
-        settings,
-        startupModelRegistry(ctx.modelRegistry) as typeof ctx.modelRegistry,
+        startupModelRuntime(ctx.modelRegistry),
         scopedModels,
-        (model) => done(model),
+        (model: SelectedModel) => done(model),
         () => done(undefined)
-      );
-    });
+      )
+    );
 
     if (selected === undefined) {
       return;
@@ -54,21 +50,20 @@ function startupAvailableModels(registry: {
   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) => {
+// The selector reads a ModelRuntime, which extensions cannot reach. It only calls
+// getAvailableSnapshot, getModel, getError, and refresh, so this view answers
+// those from the registry and hides every model outside the startup list.
+function startupModelRuntime(registry: ModelRegistry): ModelRuntime {
+  const view = {
+    getAvailableSnapshot: () => startupAvailableModels(registry),
+    getModel: (provider: string, modelId: string) => {
       const model = registry.find(provider, modelId);
       return model !== undefined && startupModelKeys.has(modelKey(model)) ? model : undefined;
-    }
+    },
+    getError: () => registry.getError(),
+    refresh: (options?: Parameters<ModelRegistry["refresh"]>[0]) => registry.refresh(options)
   };
+  return view as unknown as ModelRuntime;
 }
 
 function modelKey(model: { readonly provider: string; readonly id: string }): string {

package/docs/runtime-specification.md

@@ -110,6 +110,7 @@ Localpi:
 - can use `--provider <id>` to name the generated Pi provider
 - uses `/v1/models` for discovery
 - avoids assuming it can start, stop, or unload the backend
+- writes the `--api-key` value as the generated Pi provider key, exactly as given, so an environment reference such as `${HF_TOKEN}` or a `!command` keeps the secret out of the Pi config. The default is `local`, which local engines accept and ignore
 
 ### Configured Providers
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "localpi",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "description": "Swiss army knife for running Pi with local inference engines.",
   "type": "module",
   "license": "MIT",
@@ -41,7 +41,7 @@
     "check": "npm run format && npm run lint && npm run typecheck && npm test && npm run build"
   },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "^0.87.0",
+    "@earendil-works/pi-coding-agent": "^0.87.1",
     "@eslint/js": "^9.0.0",
     "@stryker-mutator/core": "^9.6.1",
     "@stryker-mutator/typescript-checker": "^9.6.1",