localpi 0.1.1 → 0.3.0

package/dist/src/pi/extensions.js

@@ -1,5 +1,7 @@
 import { mkdir, writeFile } from "node:fs/promises";
 import path from "node:path";
+import { settingsStatePath } from "../localpi/settings-state.js";
+import { resolveDemoPrompts } from "./demo.js";
 export async function writeDefaultExtensions(options, extensionOptions = {}) {
     const extensionDir = path.join(options.stateDir, "pi-extensions");
     await mkdir(extensionDir, { recursive: true });
@@ -7,7 +9,10 @@ export async function writeDefaultExtensions(options, extensionOptions = {}) {
     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.demo) {
+        paths.push(await writeExtension(extensionDir, "demo-mode.ts", demoModeExtensionSource(await resolveDemoPrompts(options))));
+    }
+    paths.push(await writeExtension(extensionDir, "thinking-control.ts", thinkingControlExtensionSource(settingsStatePath(options))));
     if (options.approval) {
         paths.push(await writeExtension(extensionDir, "tool-approval.ts", approvalExtensionSource()));
     }
@@ -24,6 +29,58 @@ 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";
@@ -290,12 +347,16 @@ function textUpdateFromUnknown(value: unknown): TextUpdate {
 }
 `;
 }
-function thinkingControlExtensionSource() {
-    return `import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+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", {
@@ -313,6 +374,7 @@ export default function localpiThinkingControl(pi: ExtensionAPI): void {
       }
       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"
@@ -320,15 +382,33 @@ export default function localpiThinkingControl(pi: ExtensionAPI): void {
     }
   });
 
-  pi.on("thinking_level_select", (event, ctx) => {
+  pi.on("thinking_level_select", async (event, ctx) => {
+    await persistThinking(event.level);
     ctx.ui.setStatus("localpi-thinking", \`thinking: \${event.level}\`);
   });
 
-  pi.on("session_shutdown", (_event, ctx) => {
+  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> } }

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

@@ -24,7 +24,7 @@ Startup selection is for models only. There is no startup thinking picker.
 - 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.
+- Thinking starts from `--thinking`, `LOCALPI_THINKING`, the last saved Pi thinking level, or `medium`.
 - In-session thinking changes happen through `/thinking` inside Pi.
 
 ## Provider Coverage
@@ -86,9 +86,9 @@ 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.
+- `localpi` starts with the last saved thinking level, or `medium` if none is saved.
+- `LOCALPI_THINKING=<level>` overrides the saved startup default.
+- `localpi --thinking <level>` overrides the saved startup default.
 - The chosen startup value is passed to Pi as `--thinking <level>` and written to `settings.json.defaultThinkingLevel`.
 
 In-session control:
@@ -97,6 +97,7 @@ In-session control:
 - `/thinking` opens Pi's selector UI.
 - `/thinking high` sets the level directly.
 - The extension calls Pi's thinking API, so Pi owns runtime mutation.
+- The extension saves the actual Pi thinking level to localpi state for the next launch.
 
 Managed `llama-server` caveat:
 
@@ -114,6 +115,7 @@ Managed `llama-server` caveat:
 - [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.
+- [x] Remember the last Pi thinking level for future localpi launches.
 - [ ] 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.

package/docs/2026-06-18-endless-demo-mode-plan.md

@@ -0,0 +1,192 @@
+---
+title: Endless Demo Mode Plan
+author: Bob <dutifulbob@gmail.com>
+date: 2026-06-18
+---
+
+# Endless Demo Mode Plan
+
+This plan covers an endless localpi demo mode that runs inside Pi's normal TUI and repeatedly prompts Pi until the user exits the TUI or interrupts it.
+
+## Goal
+
+`localpi --demo` should run a hands-free local model demo without turning localpi into an interactive chat client and without subverting Pi's native TUI.
+
+The demo orchestration is owned by a localpi-generated Pi extension. Rendering, streaming, tok/s display, input handling, slash commands, session state, and lifecycle remain owned by Pi.
+
+## Target Behavior
+
+- `localpi --demo --model <alias|id|path>` starts Pi once with a built-in initial prompt.
+- Pi opens in normal TUI mode.
+- The demo extension sends the initial prompt after TUI `session_start`.
+- After each completed generation, the demo extension sends the followup prompt after `turn_end`.
+- The followup prompt defaults to `Continue. Try to write as long as possible.`
+- The loop continues until the user exits Pi, `Ctrl-C` is pressed, or Pi stops the session normally.
+- Runtime discovery, Pi config generation, extensions, thinking, tools, and approval behavior match normal localpi launches.
+- Demo mode requires an explicit non-`auto` model through `--model` or `LOCALPI_MODEL`; it must not auto-select a model.
+- Demo mode requires interactive TTY stdin and stdout so Pi opens its normal TUI.
+- Demo mode uses one live Pi session so followup prompts keep the first prompt's context.
+- Demo mode works with any provider localpi already supports: LM Studio, vLLM, generic OpenAI-compatible providers, and managed `llama-server`.
+- Demo mode does not parse terminal output to detect when generation stops; it relies on Pi extension events.
+
+## Default Prompts
+
+Initial prompt:
+
+```text
+You are narrating a never-ending sci-fi adventure. Continue in short paragraphs. Whenever the user sends a message, treat it as a live director note and incorporate it immediately. Never end the story.
+```
+
+Followup prompt:
+
+```text
+Continue. Try to write as long as possible.
+```
+
+## CLI Contract
+
+Add these flags:
+
+- `--demo`: enable endless demo mode.
+- `--demo-initial-prompt <text>`: override the first prompt.
+- `--demo-followup-prompt <text>`: override every prompt after the first.
+- `--demo-initial-prompt-file <path>`: read the first prompt from a UTF-8 file.
+- `--demo-followup-prompt-file <path>`: read the followup prompt from a UTF-8 file.
+
+Add matching environment variables:
+
+- `LOCALPI_DEMO`
+- `LOCALPI_DEMO_INITIAL_PROMPT`
+- `LOCALPI_DEMO_FOLLOWUP_PROMPT`
+- `LOCALPI_DEMO_INITIAL_PROMPT_FILE`
+- `LOCALPI_DEMO_FOLLOWUP_PROMPT_FILE`
+
+File flags should win over text flags for the same prompt because they are the better interface for long prompts.
+
+Explicit CLI flags should win over environment variables.
+
+## Incompatible Modes
+
+Reject these combinations with clear errors:
+
+- `--demo --status`
+- `--demo --stop`
+- `--demo --list`
+- `--demo` without an explicit non-`auto` model
+- `--demo` without interactive TTY stdin and stdout
+- `--demo` with user-supplied forwarded Pi prompt flags such as `-p` or `--prompt`
+
+Forwarded non-prompt Pi options should remain allowed.
+
+## Launch Design
+
+Keep `src/pi/launch.ts` as the single-launch layer. Demo mode should use the same launch path as a normal interactive localpi session.
+
+Demo mode should not:
+
+- pass prompts through stdin
+- pass prompts with `-p` or `--prompt`
+- force print, JSON, or RPC mode
+- launch repeated one-shot Pi child processes
+- create or manage a parallel localpi TUI
+
+Normal localpi launch planning should write an additional generated extension when `--demo` is enabled, then launch Pi normally.
+
+## Demo Extension
+
+Add a generated Pi extension, likely `demo-mode.ts`, alongside the existing localpi extensions.
+
+The extension owns:
+
+- resolving already-materialized prompt text provided by localpi
+- sending the initial prompt once on `session_start` when `ctx.mode === "tui"`
+- sending the followup prompt after each final assistant `turn_end` when demo mode is still active
+- relying on Pi's own queueing via `pi.sendUserMessage`
+- optional later controls such as `/demo stop`
+
+Example shape:
+
+```ts
+pi.on("session_start", (event, ctx) => {
+  if (started || event.reason !== "startup" || ctx.mode !== "tui") {
+    return;
+  }
+  started = true;
+  pi.sendUserMessage(initialPrompt);
+});
+
+pi.on("turn_end", (event, ctx) => {
+  if (!started || stopped || ctx.mode !== "tui") {
+    return;
+  }
+  if (event.message.role !== "assistant") {
+    return;
+  }
+  if (event.message.stopReason === "aborted" || event.message.stopReason === "error") {
+    stopped = true;
+    return;
+  }
+  if (event.message.stopReason === "toolUse") {
+    return;
+  }
+  pi.sendUserMessage(followupPrompt, { deliverAs: "followUp" });
+});
+```
+
+Prompt file loading should stay in localpi before extension generation. The generated extension should contain concrete prompt strings so Pi does not need to read localpi-specific files at runtime.
+
+## Signal And Exit Behavior
+
+- Pi owns `Ctrl-C`, exit, and interactive lifecycle behavior.
+- If a turn ends with an aborted or error assistant message, the demo extension should stop queueing followup prompts.
+- If a turn ends with tool use, the demo extension should wait for the final assistant turn before queueing a followup.
+- localpi should not restart Pi after exit.
+- If Pi exits non-zero, localpi should return the same exit code as a normal launch.
+- No special signal-forwarding loop should be needed beyond normal `execLaunchPlan` behavior.
+
+## Non-Goals
+
+- Do not scrape stdout or terminal output to infer completion.
+- Do not run demo mode as a hidden headless print-mode loop.
+- Do not repeatedly spawn one-shot Pi processes.
+- Do not create a second localpi-owned TUI or prompt loop.
+- Do not make provider-specific demo behavior.
+- Do not add classifier, benchmark, dataset, or schema workflow concepts.
+- Do not keep a hidden background service running after localpi exits.
+
+## Testing Checklist
+
+- [x] Parse `--demo` and all demo prompt flags.
+- [x] Parse matching `LOCALPI_DEMO*` environment variables.
+- [x] Verify CLI prompt values override environment values.
+- [x] Verify prompt files override text prompt values.
+- [x] Verify `--demo --status`, `--demo --stop`, and `--demo --list` fail clearly.
+- [x] Verify demo mode rejects missing or `auto` model selection.
+- [x] Verify demo mode rejects non-TTY stdin/stdout.
+- [x] Verify demo mode rejects forwarded Pi prompt flags.
+- [x] Unit-test that demo mode writes a generated Pi extension.
+- [x] Unit-test that the generated extension sends the initial prompt on TUI `session_start`.
+- [x] Unit-test that the generated extension sends followup prompts after `turn_end`.
+- [x] Unit-test that the generated extension does not queue followups after tool-use continuation turns.
+- [x] Unit-test that demo mode uses the normal Pi launch path and does not pipe prompts over stdin.
+- [x] Unit-test that normal launches are unchanged.
+- [x] Use a fake `LOCALPI_PI_CMD` to prove demo launches Pi once with the demo extension path.
+- [x] Verify demo mode does not pass `-p`, `--prompt`, `--mode print`, `--mode json`, or `--mode rpc`.
+- [x] Run `npm run check`.
+
+## Documentation Checklist
+
+- [x] Document `--demo` in README options.
+- [x] Document prompt override flags.
+- [x] Document `LOCALPI_DEMO*` environment variables.
+- [x] Include one simple example:
+
+```bash
+localpi --demo --model gemma-e4b
+```
+
+- [x] Include one override example:
+
+```bash
+localpi --demo --model gemma-e4b --demo-initial-prompt-file ./prompts/story.txt --demo-followup-prompt "Continue. Try to write as long as possible."
+```

package/docs/runtime-specification.md

@@ -9,7 +9,7 @@ It should make the common local-model path one command while keeping the selecte
 - 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 managed `llama-server` as an optional 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.
 
@@ -23,11 +23,12 @@ 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
+- includes the localpi-owned `llama-server` catalog as startable fallback entries when available
 - 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
+- skips automatic managed `llama-server` fallback when the configured `llama-server` command is unavailable
 - writes Pi config for all launch-time loaded catalog entries so Pi `/model` can switch among them
 
 ### `llama-server`
@@ -97,6 +98,32 @@ Provider registry JSON can define additional OpenAI-compatible providers:
 
 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.
 
+## Capability Profiles
+
+OpenAI-compatible `/v1/models` responses do not reliably report local serving capabilities such as reasoning support or Pi's required thinking request format. Localpi can read a local model capability profile with `--model-profile`, `LOCALPI_MODEL_PROFILE`, or `LOCALPAGER_AGENT_PROFILE`.
+
+Example:
+
+```json
+{
+  "id": "gemma4-26b-a4b-nvfp4",
+  "model": "nvidia/Gemma-4-26B-A4B-NVFP4",
+  "base_url": "http://127.0.0.1:8000/v1",
+  "client": {
+    "context_window": 32768,
+    "max_tokens": 4096
+  },
+  "capabilities": {
+    "reasoning": true,
+    "thinking_format": "qwen-chat-template"
+  }
+}
+```
+
+When the served model id matches `model` or `id`, localpi uses the profile to generate Pi model config. `LOCALPI_MODEL_REASONING` / `LOCALPAGER_AGENT_REASONING` and `LOCALPI_MODEL_THINKING_FORMAT` / `LOCALPAGER_AGENT_THINKING_FORMAT` are explicit overrides.
+
+Name-based capability detection remains fallback behavior. Built-in vLLM Gemma 4 model ids are treated as reasoning-capable with `qwen-chat-template`, matching vLLM Gemma servers launched with `--reasoning-parser gemma4`.
+
 ## Model Selection
 
 `--model` should accept:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "localpi",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "description": "Pi-compatible local model launcher with managed llama-server support.",
   "type": "module",
   "license": "MIT",
@@ -48,7 +48,7 @@
     "@vitest/coverage-v8": "^3.0.0",
     "eslint": "^9.0.0",
     "prettier": "^3.0.0",
-    "slophammer-ts": "0.3.0",
+    "slophammer-ts": "0.4.0",
     "tsx": "^4.19.4",
     "typescript": "^5.0.0",
     "typescript-eslint": "^8.0.0",