localpi 0.1.0

package/docs/2026-06-16-startup-model-and-thinking-control-plan.md

@@ -0,0 +1,129 @@
+---
+title: Startup Model And Thinking Control Plan
+author: Bob <dutifulbob@gmail.com>
+date: 2026-06-16
+---
+
+# Startup Model And Thinking Control Plan
+
+This plan covers the localpi UX for choosing models and controlling thinking without turning localpi into a second interactive app.
+
+## Goal
+
+Plain `localpi` should make model choice easy when multiple local models are available, while thinking stays controlled by Pi after startup.
+
+Startup selection is for models only. There is no startup thinking picker.
+
+## Target Behavior
+
+- `localpi` discovers all usable local providers before Pi starts.
+- If exactly one usable model is available, localpi starts Pi with that model.
+- If multiple usable models are available in an interactive terminal, localpi launches Pi with a bootstrap model and Pi opens its native model selector at startup.
+- If no external model is available, localpi may fall back to a managed `llama-server` model.
+- A concrete `--model` value bypasses the startup model picker. `--provider` alone only scopes the catalog.
+- Explicit `--runtime` values scope discovery but do not disable the startup selector by themselves.
+- Non-interactive runs never show a picker.
+- Pi receives the launch-time model catalog so `/model` can switch across discovered providers and models.
+- Thinking starts as `off` unless `--thinking` or `LOCALPI_THINKING` sets another startup level.
+- In-session thinking changes happen through `/thinking` inside Pi.
+
+## Provider Coverage
+
+The startup model catalog should generalize across all local providers that localpi knows how to describe:
+
+- LM Studio: externally managed OpenAI-compatible provider.
+- vLLM: externally managed OpenAI-compatible provider.
+- Generic OpenAI-compatible providers from localpi config.
+- Managed `llama-server`: localpi-owned, startable GGUF aliases and the currently served model.
+
+Localpi should not start or stop externally managed providers. It should only manage localpi-owned `llama-server` processes.
+
+## Startup Model Selection
+
+Selection happens after provider discovery and before Pi config generation.
+
+Interactive behavior:
+
+- If no explicit model was requested and more than one usable model exists, select a deterministic bootstrap model only so Pi can start.
+- In the same launch, generate a startup extension that opens Pi's native `ModelSelectorComponent`.
+- Label options with provider and model, for example `LM Studio / qwen3.6-35b-a3b-mtp`.
+- Prefer a stable ordering so repeated launches are predictable.
+- Let Enter choose the first ranked model.
+
+Non-interactive behavior:
+
+- Do not prompt.
+- Use a deterministic default when one exists.
+- If multiple loaded models match, use the first deterministic bootstrap model and let automation pin another model with `--provider` and `--model` when needed.
+
+Explicit selection behavior:
+
+- `--provider <id> --model <id>` selects an exact catalog entry.
+- `--provider <id>` without `--model` scopes startup discovery and still opens the Pi-native picker when multiple loaded models match.
+- `--runtime lmstudio` and `--runtime vllm` select the built-in external provider.
+- Managed `llama-server` aliases continue to work through `--model <alias>`.
+
+## Pi Model Switching
+
+Localpi should pass the full launch-time catalog to Pi instead of creating a localpi-only `/model` extension.
+
+Generated Pi config should include:
+
+- one provider entry per discovered provider
+- every discovered usable model under its provider
+- selected provider and selected model in `settings.json`
+- context window and max token metadata when known
+- reasoning metadata when known
+- provider compatibility metadata when needed, such as Qwen or DeepSeek thinking format
+
+Pi owns the `/model` command and the native startup model selector UI. Localpi's job is to give Pi a complete model catalog at launch and request that native selector when startup model choice is needed.
+
+Live model refresh after Pi starts is out of scope for this plan. That should be a future Pi/provider integration.
+
+## Thinking Control
+
+Thinking is not selected at startup through a picker.
+
+Startup defaults:
+
+- `localpi` starts with thinking `off`.
+- `LOCALPI_THINKING=<level>` changes the startup default.
+- `localpi --thinking <level>` overrides the startup default.
+- The chosen startup value is passed to Pi as `--thinking <level>` and written to `settings.json.defaultThinkingLevel`.
+
+In-session control:
+
+- Localpi provides a Pi extension command named `/thinking`.
+- `/thinking` opens Pi's selector UI.
+- `/thinking high` sets the level directly.
+- The extension calls Pi's thinking API, so Pi owns runtime mutation.
+
+Managed `llama-server` caveat:
+
+- Server-side reasoning budget is still chosen at startup.
+- Changing the server-side budget later would require restarting the local server process.
+
+## Implementation Checklist
+
+- [x] Discover a normalized launch-time model catalog across providers.
+- [x] Add startup model selection when multiple models are available interactively.
+- [x] Use Pi's native model selector UI at startup instead of a localpi-owned terminal prompt.
+- [x] Pass the launch-time catalog into generated Pi model config.
+- [x] Keep `/model` owned by Pi.
+- [x] Add reasoning and thinking-format metadata for known local reasoning models.
+- [x] Add `/thinking` as a Pi extension command.
+- [x] Keep startup thinking non-interactive.
+- [x] Keep `--thinking` and `LOCALPI_THINKING` as automation-safe startup controls.
+- [ ] Manually verify model picker behavior in an interactive terminal with multiple loaded providers.
+- [ ] Manually verify Pi `/model` can switch among generated catalog entries.
+- [ ] Manually verify Pi `/thinking` picker and direct `/thinking <level>` command.
+
+## Out Of Scope
+
+- A startup thinking selector.
+- A localpi-owned `/model` extension.
+- Live refresh of models after Pi starts.
+- Starting or stopping LM Studio, vLLM, or other externally managed providers.
+- Guessing random provider ports.
+- Cloud provider authentication.
+- Caller-specific workflows such as classifier routing or schema-constrained output.

package/docs/implementation-plan.md

@@ -0,0 +1,75 @@
+# Implementation Plan
+
+This plan tracks the migration from `localagent` to `localpi` and changes the product from a generic OpenAI-compatible wrapper into a polished local Pi launcher.
+
+## 1. Rename The Public Surface
+
+- [x] Rename package metadata from `@dutifuldev/localagent` to `@dutifuldev/localpi`.
+- [x] Rename the installed binary from `localagent` to `localpi`.
+- [x] Rename source namespaces from `localagent` to `localpi`.
+- [x] Rename default state from `~/.local/state/localagent` to `~/.local/state/localpi`.
+- [x] Replace `LOCALAGENT_*` environment variables with `LOCALPI_*`.
+- [x] Do not keep a `localagent` compatibility shim.
+
+## 2. Remove Structured Output
+
+- [x] Remove `--final-schema` and `--schema` from option parsing.
+- [x] Remove `LOCALAGENT_FINAL_SCHEMA`.
+- [x] Delete `src/structured/final-schema.ts`.
+- [x] Delete structured-output tests and example schemas.
+- [x] Keep a migration note that schema-constrained classifier runs belong in `localpager-agent`.
+- [x] Confirm the current localpager classifier uses `localpager-agent --final-schema`, not localpi.
+
+Older workspace wrappers outside this repository still mention `localagent --final-schema`; those should be migrated separately if they are still used.
+
+## 3. Add Runtime Backends
+
+- [x] Add a runtime option with default `llama-server`.
+- [x] Implement a managed `llama-server` backend:
+  - [x] model alias resolution
+  - [x] custom GGUF path support
+  - [x] context window configuration
+  - [x] chat template file support
+  - [x] pid file and metadata file under localpi state
+  - [x] start, reuse, status, and stop
+- [x] Implement explicit `lmstudio` backend:
+  - [x] default base URL `http://127.0.0.1:1234/v1`
+  - [x] model probing through `/v1/models`
+  - [x] clear failures when LM Studio is not running or the model is not loaded
+- [x] Keep a generic `openai-compatible` backend for externally managed servers.
+
+## 4. Add Default Pi Extensions
+
+- [x] Add a tool approval extension.
+- [x] Add a token status extension.
+- [x] Generate both extensions under localpi state.
+- [x] Pass them to Pi by default.
+- [x] Add `--no-approval` for trusted sessions.
+- [x] Add `--no-token-status` if the status UI causes problems in print or non-interactive mode.
+
+## 5. Add Default Tooling
+
+- [x] Default Pi tool allow list: `read,bash,edit,write,grep,find,ls`.
+- [x] Allow override with `--tools`.
+- [x] Preserve `--` forwarding for raw Pi flags.
+- [x] Keep the system prompt short and generic.
+
+## 6. Memory Safety
+
+- [x] Only manage localpi-owned `llama-server` processes.
+- [x] Stop the previous localpi-owned server before starting a different managed model.
+- [x] In `llama-server` mode, detect loaded LM Studio models where possible and warn before starting a large model.
+- [x] Never silently start both LM Studio and managed `llama-server` for the same localpi command.
+
+## 7. Verification
+
+- Unit-test option parsing, runtime selection, Pi launch planning, and server lifecycle decisions.
+- Smoke-test:
+  - `localpi --list`
+  - `localpi --status`
+  - `localpi --model gemma-e4b -p "say ok"`
+  - `localpi --model gemma-12b`
+  - `localpi --runtime lmstudio --model gemma-4-e4b-it -p "say ok"`
+  - approval denial in an interactive tool call
+  - token status display in an interactive session
+- Run `npm run check` before merging implementation changes.

package/docs/runtime-specification.md

@@ -0,0 +1,148 @@
+# Runtime Specification
+
+Localpi is the local runtime launcher for Pi.
+
+It should make the common local-model path one command while keeping the selected provider and model explicit and inspectable.
+
+## Goals
+
+- Run Pi against local open-weight models without hand-editing Pi config.
+- Discover local providers by default and select from the loaded model catalog.
+- Support LM Studio and vLLM as built-in OpenAI-compatible providers.
+- Keep managed `llama-server` as the fallback when no external model is loaded.
+- Keep the tool generic: no classifier prompts, topic schemas, dataset generation, or final-schema output.
+- Keep large model memory usage predictable by managing only one localpi-owned `llama-server` process at a time.
+
+## Runtimes
+
+### `auto`
+
+Default runtime.
+
+Localpi:
+
+- probes built-in LM Studio and vLLM endpoints
+- loads configured OpenAI-compatible providers from `--providers-file`, `LOCALPI_PROVIDERS_FILE`, or `LOCALPI_MODELS_FILE`
+- includes the localpi-owned `llama-server` catalog as startable fallback entries
+- selects the only loaded model automatically
+- opens Pi's native model selector when multiple loaded models are available in an interactive TTY
+- never prompts in non-interactive runs; automation can pin a model with concrete `--provider` and `--model` values
+- treats `--provider` without `--model` as catalog scoping, not as a concrete model choice
+- writes Pi config for all launch-time loaded catalog entries so Pi `/model` can switch among them
+
+### `llama-server`
+
+Managed runtime.
+
+Localpi:
+
+- resolves a model alias or GGUF path
+- starts `llama-server` if the selected model is not already served
+- reuses an existing server on the configured port if it is already serving the requested model
+- exposes the server through an OpenAI-compatible `/v1` endpoint
+- writes Pi config that points at that endpoint
+- stops the old localpi-owned server before starting a different managed model
+- reports any detected LM Studio loaded models before starting a large managed model
+
+### LM Studio
+
+Built-in external OpenAI-compatible provider.
+
+Localpi:
+
+- requires `--runtime lmstudio`
+- defaults to `http://127.0.0.1:1234/v1`
+- does not start or stop LM Studio
+- probes `/v1/models` and fails clearly if the requested model is not available
+
+### vLLM
+
+Built-in external OpenAI-compatible provider.
+
+Localpi:
+
+- requires `--runtime vllm`
+- defaults to `http://127.0.0.1:8000/v1`
+- does not start or stop vLLM
+- probes `/v1/models` and fails clearly if the requested model is not available
+
+### Custom OpenAI-Compatible Endpoint
+
+Explicit alternate runtime.
+
+Localpi:
+
+- requires `--runtime openai-compatible`
+- requires `--base-url`
+- 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
+
+### Configured Providers
+
+Provider registry JSON can define additional OpenAI-compatible providers:
+
+```json
+{
+  "providers": {
+    "vllm-qwen": {
+      "type": "openai-compatible",
+      "name": "vLLM Qwen",
+      "baseUrl": "http://127.0.0.1:8000/v1",
+      "discover": true
+    }
+  }
+}
+```
+
+Set `discover: false` when the endpoint should not be probed during startup. Explicit `--provider <id> --model <id>` can still select that provider and generate Pi config.
+
+## Model Selection
+
+`--model` should accept:
+
+- a configured alias such as `gemma-12b` or `gemma-e4b`
+- an LM Studio model id
+- a vLLM model id
+- an absolute or relative GGUF path for `llama-server`
+- `auto`, which selects the first model reported by the backend
+
+Model aliases are configurable with `LOCALPI_MODELS_FILE`. The built-in defaults cover the local Gemma GGUF paths commonly used on this machine and are easy to override.
+
+## Pi Defaults
+
+Localpi passes these defaults to Pi unless the user overrides them:
+
+```text
+tools: read,bash,edit,write,grep,find,ls
+thinking: off
+state dir: ~/.local/state/localpi
+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
+
+## System Prompt
+
+Localpi appends a short system prompt that tells the model:
+
+- it is running through Pi on a local model
+- tool calls require user approval
+- blocked tool calls did not run
+- it should not claim to have used a blocked tool
+- it should prefer direct answers when tools are not needed
+
+The prompt should be generic and should not mention localpager, OpenClaw, datasets, or classifier labels.
+
+## Out Of Scope
+
+- `--final-schema`
+- `final_json`
+- JSON schema validation for final answers
+- classifier retry policy
+- GitHub issue or pull request fetching
+- reposhell-specific behavior
+- dataset generation

package/docs/structured-output.md

@@ -0,0 +1,9 @@
+# Structured Output
+
+Structured final output is out of scope for localpi.
+
+Localpi focuses on launching Pi against local models with good runtime defaults: managed `llama-server`, optional LM Studio support, default tools, tool approval, and token status.
+
+Schema-constrained classifier workflows belong in caller-specific tools such as `localpager-agent`, where the prompt, schema, retries, and output validation belong to the application workflow.
+
+The previous localagent `--final-schema` / `--schema` behavior was removed during the localpi rename implementation.

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "localpi",
+  "version": "0.1.0",
+  "description": "Pi-compatible local model launcher with managed llama-server support.",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dutifuldev/localpi.git"
+  },
+  "bugs": {
+    "url": "https://github.com/dutifuldev/localpi/issues"
+  },
+  "homepage": "https://github.com/dutifuldev/localpi#readme",
+  "bin": {
+    "localpi": "dist/src/cli/main.js"
+  },
+  "files": [
+    "dist/src/**",
+    "docs/**",
+    "examples/**",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "format": "prettier --check .",
+    "lint": "eslint .",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "coverage": "vitest run --coverage --coverage.thresholds.lines 85 --coverage.thresholds.functions 85 --coverage.thresholds.branches 85 --coverage.thresholds.statements 85",
+    "dry": "slophammer-ts dry .",
+    "mutate": "stryker run",
+    "mutate:scan": "stryker run --dryRunOnly",
+    "slophammer": "slophammer-ts check .",
+    "localpi": "tsx src/cli/main.ts",
+    "check": "npm run format && npm run lint && npm run typecheck && npm test && npm run build"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.0.0",
+    "@stryker-mutator/core": "^9.6.1",
+    "@stryker-mutator/typescript-checker": "^9.6.1",
+    "@stryker-mutator/vitest-runner": "^9.6.1",
+    "@types/node": "^22.0.0",
+    "@vitest/coverage-v8": "^3.0.0",
+    "eslint": "^9.0.0",
+    "prettier": "^3.0.0",
+    "slophammer-ts": "^0.3.0",
+    "tsx": "^4.19.4",
+    "typescript": "^5.0.0",
+    "typescript-eslint": "^8.0.0",
+    "vitest": "^3.0.0"
+  }
+}