localpi 0.4.0 → 0.5.2

package/README.md

@@ -1,10 +1,10 @@
 # localpi
 
-Localpi is a local Pi launcher for open-weight models.
+Localpi is a Swiss army knife for running Pi with local inference engines.
 
 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.
 
-Localpi supports LM Studio, vLLM, custom OpenAI-compatible servers, and an optional managed `llama-server` fallback.
+Localpi is meant to be the practical bridge from Pi to local inference stacks such as llama.cpp/`llama-server`, vLLM, SGLang, LM Studio, Ollama, and custom provider endpoints.
 
 Localpi is intentionally generic. It does not contain classifier prompts, dataset workflows, GitHub routing logic, or final-schema output machinery. Structured classifier runs belong in caller tools such as `localpager-agent`.
 
@@ -18,6 +18,12 @@ See:
 npm install -g localpi
 ```
 
+Or the latest GitHub release directly:
+
+```bash
+npm install -g https://github.com/osolmaz/localpi/releases/latest/download/localpi.tgz
+```
+
 During development:
 
 ```bash
@@ -74,6 +80,14 @@ Localpi launches Pi with:
 
 The approval gate makes failed or denied tool calls explicit to the model so the model does not claim that a blocked command ran.
 
+## Diffusion Canvas Visualizer
+
+The live diffusion canvas visualizer (watching DiffusionGemma denoise its
+answer in the TUI) lives in its own project now:
+[diffusionpi](https://github.com/osolmaz/diffusionpi). It is a pi-factory app
+bundle plus a standalone Pi widget package; the widget also installs into any
+Pi session via `pi install`.
+
 ## LM Studio Alternative
 
 LM Studio exposes an OpenAI-compatible endpoint, usually:
@@ -115,7 +129,7 @@ Run an endless TUI demo:
 localpi --demo --model gemma-e4b
 ```
 
-Demo mode requires an explicit model, opens the normal Pi TUI, and keeps one live Pi session so followup prompts continue from the first prompt while Pi owns streaming, tok/s status, slash commands, and exit behavior.
+Demo mode requires an explicit model, opens the normal Pi TUI, and keeps one live Pi session so followup prompts continue from the first prompt while Pi owns streaming, tok/s status, slash commands, and exit behavior. Under the hood it loads the shared [pi-demo-mode](https://github.com/osolmaz/pi-demo-mode) extension, configured through the `--demo-*` flags below.
 
 Override the demo prompts:
 
@@ -174,6 +188,18 @@ Stop the managed `llama-server` runtime:
 localpi --stop
 ```
 
+## Demo Grid and Recording
+
+The `localpi grid` and `localpi record` subcommands moved to
+[demowall](https://github.com/osolmaz/demowall), a standalone tool that runs
+N copies of any command in a tiled tmux wall and records tmux sessions to
+video. A wall of localpi demo sessions is:
+
+```bash
+demowall grid --concurrency 4 --start -- localpi --demo --model gemma-e4b
+demowall record --session demowall-<timestamp> --out demo.mp4 --seconds 60
+```
+
 ## Options
 
 - `--runtime <auto|llama-server|lmstudio|vllm|openai-compatible>`: runtime backend. Default: `auto`

package/dist/src/cli/cli.js

@@ -1,4 +1,4 @@
-import { runPiApp } from "@dutifuldev/pi-factory";
+import { runPiApp } from "@osolmaz/pi-factory";
 import { errorMessage, fail, ok } from "../common/result.js";
 import { parseLocalpiArgs, usage } from "../localpi/options.js";
 import { aliasListOutput, connectionStatus, resolveRuntime, statusOutput, stopRuntime } from "../localpi/runtime.js";
@@ -22,7 +22,9 @@ export async function run(args) {
         });
         const connection = await resolveRuntime(options);
         const selectorOptions = startupModelSelectorOptions(options, connection);
-        const extensions = await writeDefaultExtensions(options, selectorOptions === undefined ? {} : { startupModelSelector: selectorOptions });
+        const extensions = await writeDefaultExtensions(options, {
+            ...(selectorOptions === undefined ? {} : { startupModelSelector: selectorOptions })
+        });
         const app = createLocalpiAppDefinition(options, connection, extensions);
         return await launchResolvedRuntime(app, connection);
     }

package/dist/src/pi/app.js

@@ -4,6 +4,18 @@ const localpiAppIdentity = {
     name: "localpi",
     version: localpiVersion
 };
+const demoLaunchOverrideBooleanFlags = new Set([
+    "--no-tools",
+    "-nt",
+    "--no-builtin-tools",
+    "-nbt",
+    "--approve",
+    "-a",
+    "--no-approve",
+    "-na"
+]);
+const demoLaunchOverrideValueFlags = new Set(["--tools", "-t", "--exclude-tools", "-xt"]);
+const demoLaunchOverrideEqualsFlags = ["--tools=", "--exclude-tools="];
 export function createLocalpiAppDefinition(options, connection, extensions) {
     return {
         ...localpiAppIdentity,
@@ -22,9 +34,37 @@ function appDirectories(options) {
 function piCommand(options) {
     return {
         piCommand: options.piCommand,
-        forwardedArgs: options.forwardedArgs
+        forwardedArgs: options.demo ? demoForwardedArgs(options.forwardedArgs) : options.forwardedArgs
     };
 }
+function demoForwardedArgs(args) {
+    return [...withoutConflictingDemoFlags(args), "--no-tools", "--no-approve"];
+}
+function withoutConflictingDemoFlags(args) {
+    const filtered = [];
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (arg === undefined) {
+            continue;
+        }
+        if (isDemoLaunchOverrideFlag(arg)) {
+            if (isValueFlag(arg) && !arg.includes("=")) {
+                index += 1;
+            }
+            continue;
+        }
+        filtered.push(arg);
+    }
+    return filtered;
+}
+function isDemoLaunchOverrideFlag(arg) {
+    return (demoLaunchOverrideBooleanFlags.has(arg) ||
+        isValueFlag(arg) ||
+        demoLaunchOverrideEqualsFlags.some((flag) => arg.startsWith(flag)));
+}
+function isValueFlag(arg) {
+    return demoLaunchOverrideValueFlags.has(arg);
+}
 function runtimeSelection(options, connection) {
     const selection = {
         providers: providersForConnection(options, connection),
@@ -103,6 +143,7 @@ function extensionConfig(extensions) {
     }
     return {
         extensions: extensions.paths.map((extensionPath) => ({ path: extensionPath })),
-        appendSystemPrompts: [extensions.systemPrompt]
+        appendSystemPrompts: [extensions.systemPrompt],
+        ...(Object.keys(extensions.env).length === 0 ? {} : { env: extensions.env })
     };
 }

package/dist/src/pi/extension-sources/token-status.js

@@ -1,6 +1,9 @@
-export function tokenStatusExtensionSource() {
+export function tokenStatusExtensionSource(options = {}) {
+    const includeContext = options.includeContext ?? true;
     return `import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 
+const includeContext = ${JSON.stringify(includeContext)};
+
 type Usage = {
   input?: number;
   output?: number;
@@ -11,6 +14,7 @@ type Usage = {
 
 type TurnState = {
   startedAt: number;
+  firstOutputAt?: number;
   outputText: string;
   estimatedOutputTokens: number;
   lastStatusAt: number;
@@ -33,6 +37,7 @@ export default function localpiTokenStatus(pi: ExtensionAPI): void {
     if (!ctx.hasUI || state === undefined) {
       return;
     }
+    const now = Date.now();
     const update = textUpdateFromUnknown(event.assistantMessageEvent ?? event.message ?? event);
     if (update.kind === "delta") {
       state.outputText += update.text;
@@ -40,11 +45,14 @@ export default function localpiTokenStatus(pi: ExtensionAPI): void {
       state.outputText = update.text;
     }
     state.estimatedOutputTokens = Math.ceil(state.outputText.length / 4);
-    if (Date.now() - state.lastStatusAt < 250) {
+    if (state.firstOutputAt === undefined && state.outputText.length > 0) {
+      state.firstOutputAt = now;
+    }
+    if (now - state.lastStatusAt < 250) {
       return;
     }
-    state.lastStatusAt = Date.now();
-    ctx.ui.setStatus("localpi-perf", ctx.ui.theme.fg("dim", statusText(state)));
+    state.lastStatusAt = now;
+    ctx.ui.setStatus("localpi-perf", ctx.ui.theme.fg("dim", statusText(state, now)));
   });
 
   pi.on("turn_end", (event, ctx) => {
@@ -65,10 +73,14 @@ export default function localpiTokenStatus(pi: ExtensionAPI): void {
     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
+    const now = Date.now();
+    const elapsedSeconds = elapsed(state, now);
+    const decodeSeconds = generationElapsed(state, now);
+    const prefillText = prefillStatusText(state, input, cacheWrite);
+    const context = includeContext ? ctx.getContextUsage() : undefined;
+    const contextText = !includeContext
+      ? undefined
+      : context && context.percent !== null
         ? \`ctx \${Math.round(context.percent)}%/\${Math.round(context.contextWindow / 1000)}k\`
         : "ctx ?";
 
@@ -77,7 +89,8 @@ export default function localpiTokenStatus(pi: ExtensionAPI): void {
       ctx.ui.theme.fg(
         "dim",
         [
-          \`\${(output / elapsedSeconds).toFixed(1)} tok/s\`,
+          \`gen \${(output / decodeSeconds).toFixed(1)} tok/s\`,
+          prefillText,
           \`out \${output}\`,
           \`in \${input}\`,
           cacheRead > 0 ? \`cache \${cacheRead}\` : undefined,
@@ -98,13 +111,48 @@ export default function localpiTokenStatus(pi: ExtensionAPI): void {
   });
 }
 
-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 statusText(state: TurnState, now: number): string {
+  const elapsedSeconds = elapsed(state, now);
+  if (state.firstOutputAt === undefined) {
+    return \`prefill \${elapsedSeconds.toFixed(1)}s | out ~\${state.estimatedOutputTokens}\`;
+  }
+  const decodeSeconds = generationElapsed(state, now);
+  const prefillSeconds = secondsBetween(state.startedAt, state.firstOutputAt);
+  return [
+    \`gen \${(state.estimatedOutputTokens / decodeSeconds).toFixed(1)} tok/s\`,
+    \`out ~\${state.estimatedOutputTokens}\`,
+    \`prefill \${prefillSeconds.toFixed(1)}s\`,
+    \`total \${elapsedSeconds.toFixed(1)}s\`
+  ].join(" | ");
+}
+
+function prefillStatusText(
+  state: TurnState,
+  input: number,
+  cacheWrite: number
+): string | undefined {
+  const tokens = prefillTokenCount(input, cacheWrite);
+  if (state.firstOutputAt === undefined || tokens <= 0) {
+    return undefined;
+  }
+  const seconds = secondsBetween(state.startedAt, state.firstOutputAt);
+  return \`prefill \${(tokens / seconds).toFixed(1)} tok/s\`;
+}
+
+function prefillTokenCount(input: number, cacheWrite: number): number {
+  return Math.max(input + cacheWrite, 0);
+}
+
+function generationElapsed(state: TurnState, now: number): number {
+  return secondsBetween(state.firstOutputAt ?? state.startedAt, now);
+}
+
+function elapsed(state: TurnState, now: number): number {
+  return secondsBetween(state.startedAt, now);
 }
 
-function elapsed(state: TurnState): number {
-  return Math.max((Date.now() - state.startedAt) / 1000, 0.001);
+function secondsBetween(start: number, end: number): number {
+  return Math.max((end - start) / 1000, 0.001);
 }
 
 type TextUpdate = {

package/dist/src/pi/extensions.js

@@ -1,8 +1,8 @@
 import { mkdir, writeFile } from "node:fs/promises";
+import { createRequire } from "node:module";
 import path from "node:path";
 import { localpiSettingsPath } from "../localpi/settings-state.js";
 import { resolveDemoPrompts } from "./demo.js";
-import { demoModeExtensionSource } from "./extension-sources/demo-mode.js";
 import { startupModelSelectorExtensionSource } from "./extension-sources/startup-model-selector.js";
 import { thinkingControlExtensionSource } from "./extension-sources/thinking-control.js";
 import { tokenStatusExtensionSource } from "./extension-sources/token-status.js";
@@ -11,24 +11,40 @@ export async function writeDefaultExtensions(options, extensionOptions = {}) {
     const extensionDir = path.join(options.stateDir, "pi-extensions");
     await mkdir(extensionDir, { recursive: true });
     const paths = [];
+    let env = {};
     if (extensionOptions.startupModelSelector !== undefined) {
         paths.push(await writeExtension(extensionDir, "startup-model-selector.ts", startupModelSelectorExtensionSource(extensionOptions.startupModelSelector)));
     }
     if (options.demo) {
-        paths.push(await writeExtension(extensionDir, "demo-mode.ts", demoModeExtensionSource(await resolveDemoPrompts(options))));
+        paths.push(demoModeExtensionPath());
+        const prompts = await resolveDemoPrompts(options);
+        env = {
+            ...env,
+            PI_DEMO_MODE: "1",
+            PI_DEMO_INITIAL_PROMPT: prompts.initial,
+            PI_DEMO_FOLLOWUP_PROMPT: prompts.followup
+        };
     }
     paths.push(await writeExtension(extensionDir, "thinking-control.ts", thinkingControlExtensionSource(localpiSettingsPath(options))));
     if (options.approval) {
         paths.push(await writeExtension(extensionDir, "tool-approval.ts", approvalExtensionSource()));
     }
     if (options.tokenStatus) {
-        paths.push(await writeExtension(extensionDir, "token-status.ts", tokenStatusExtensionSource()));
+        paths.push(await writeExtension(extensionDir, "token-status.ts", tokenStatusExtensionSource({ includeContext: !options.demo })));
     }
     return {
         paths,
+        env,
         systemPrompt: localpiSystemPrompt(options.approval)
     };
 }
+// Demo mode is the shared pi-demo-mode package (a git dependency), loaded
+// straight from node_modules and configured through PI_DEMO_* env vars.
+export function demoModeExtensionPath() {
+    const require = createRequire(import.meta.url);
+    const packageJson = require.resolve("pi-demo-mode/package.json");
+    return path.join(path.dirname(packageJson), "extensions", "demo-mode.ts");
+}
 async function writeExtension(extensionDir, name, source) {
     const extensionPath = path.join(extensionDir, name);
     await writeFile(extensionPath, source, "utf8");

package/docs/runtime-specification.md

@@ -150,7 +150,7 @@ 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
+- token status: show live generation speed while streaming, then final prefill and generation rates when usage data is available
 
 ## System Prompt
 

package/package.json

@@ -1,17 +1,17 @@
 {
   "name": "localpi",
-  "version": "0.4.0",
-  "description": "Pi-compatible local model launcher with managed llama-server support.",
+  "version": "0.5.2",
+  "description": "Swiss army knife for running Pi with local inference engines.",
   "type": "module",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/dutifuldev/localpi.git"
+    "url": "git+https://github.com/osolmaz/localpi.git"
   },
   "bugs": {
-    "url": "https://github.com/dutifuldev/localpi/issues"
+    "url": "https://github.com/osolmaz/localpi/issues"
   },
-  "homepage": "https://github.com/dutifuldev/localpi#readme",
+  "homepage": "https://github.com/osolmaz/localpi#readme",
   "publishConfig": {
     "access": "public"
   },
@@ -26,7 +26,8 @@
     "LICENSE"
   ],
   "scripts": {
-    "build": "tsc -p tsconfig.json",
+    "build": "tsc -p tsconfig.json && chmod +x dist/src/cli/main.js",
+    "prepare": "npm run build",
     "format": "prettier --check .",
     "lint": "eslint .",
     "typecheck": "tsc --noEmit",
@@ -48,13 +49,14 @@
     "@vitest/coverage-v8": "^3.0.0",
     "eslint": "^9.0.0",
     "prettier": "^3.0.0",
-    "slophammer-ts": "0.4.0",
+    "slophammer-ts": "0.4.1",
     "tsx": "^4.19.4",
     "typescript": "^5.0.0",
     "typescript-eslint": "^8.0.0",
     "vitest": "^3.0.0"
   },
   "dependencies": {
-    "@dutifuldev/pi-factory": "^0.1.1"
+    "@osolmaz/pi-factory": "^0.1.2",
+    "pi-demo-mode": "github:osolmaz/pi-demo-mode#v0.1.0"
   }
 }

package/dist/src/pi/extension-sources/demo-mode.js

@@ -1,52 +0,0 @@
-export 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;
-  });
-}
-`;
-}