localpi 0.2.0 → 0.4.0

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

@@ -98,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.2.0",
+  "version": "0.4.0",
   "description": "Pi-compatible local model launcher with managed llama-server support.",
   "type": "module",
   "license": "MIT",
@@ -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");
-}