@blackbelt-technology/pi-agent-dashboard 0.4.6 → 0.5.1

package/packages/shared/src/skill-block-parser.ts

@@ -0,0 +1,115 @@
+/**
+ * Skill block parser & builder.
+ *
+ * Pi's `_expandSkillCommand` (in `@earendil-works/pi-coding-agent`) wraps skill
+ * expansions in a `<skill name="..." location="...">…</skill>\n\nargs` envelope.
+ * The dashboard's bridge expander (`packages/extension/src/prompt-expander.ts`)
+ * aligns to the same byte format. This module is the single source of truth for
+ * both producing and recovering that envelope.
+ *
+ * See change: render-skill-invocations-collapsibly.
+ */
+
+export interface SkillBlock {
+  /** Bare skill name (no `skill:` prefix), e.g. `"openspec-explore"`. */
+  name: string;
+  /** Absolute path to `SKILL.md`. */
+  location: string;
+  /**
+   * Skill body with the `References are relative to <baseDir>.\n\n` preamble
+   * stripped — what users see in the card. The preamble is bridge-internal
+   * orientation for the LLM and is not interesting to users.
+   *
+   * Pi's own `parseSkillBlock` returns the unstripped form (calls it `content`).
+   * We strip here so the renderer doesn't have to. If the preamble shape ever
+   * changes upstream and stripping fails, `body` falls back to the captured
+   * content verbatim.
+   */
+  body: string;
+  /** User text after the skill name. `undefined` when no args were typed. */
+  args: string | undefined;
+  /** Slash-command form: `"/skill:" + name + (args ? " " + args : "")`. */
+  condensed: string;
+}
+
+/**
+ * Anchored, non-greedy match of a wrapped skill block.
+ *
+ * Why anchored: prevents a literal `<skill>` substring elsewhere in user text
+ * from matching. Why non-greedy + optional trailing args at end-of-string:
+ * forces the regex engine to extend the body to the last valid
+ * `\n</skill>(\n\nargs)?$` boundary, so SKILL.md bodies that document the
+ * `<skill>` tag (e.g. include the literal text in code samples) do not
+ * terminate the match prematurely.
+ */
+const SKILL_BLOCK_RE =
+  /^<skill name="([^"]+)" location="([^"]+)">\n([\s\S]*?)\n<\/skill>(?:\n\n([\s\S]+))?$/;
+
+/**
+ * Parse a skill block from message text. Returns `null` when the input is not
+ * a well-formed skill envelope.
+ */
+/**
+ * Strip the `References are relative to <baseDir>.\n\n` preamble from a captured
+ * `<skill>` content block. Returns the stripped body, or the input unchanged if
+ * the preamble shape doesn't match.
+ */
+function stripReferencesPreamble(content: string): string {
+  const m = content.match(/^References are relative to [^\n]+\.\n\n([\s\S]*)$/);
+  return m ? m[1] : content;
+}
+
+export function parseSkillBlock(text: string): SkillBlock | null {
+  const m = text.match(SKILL_BLOCK_RE);
+  if (!m) return null;
+  const name = m[1];
+  const location = m[2];
+  const body = stripReferencesPreamble(m[3]);
+  const args = m[4];
+  const condensed = `/skill:${name}${args ? " " + args : ""}`;
+  return { name, location, body, args, condensed };
+}
+
+export interface BuildSkillBlockArgs {
+  /** Bare skill name (no `skill:` prefix). */
+  name: string;
+  /** Absolute path to `SKILL.md`. */
+  filePath: string;
+  /** Skill base directory — `dirname(filePath)`. */
+  baseDir: string;
+  /** Skill body, frontmatter already stripped. Should be `.trim()`-ed. */
+  body: string;
+  /** Optional user-typed args appended after the closing tag. */
+  userArgs?: string;
+}
+
+/**
+ * Build a skill block in the exact byte format pi's `_expandSkillCommand`
+ * produces. The output is byte-identical to pi's output for the same inputs;
+ * `parseSkillBlock(buildSkillBlock(x))` round-trips for `name`, `body`, `args`.
+ */
+export function buildSkillBlock(input: BuildSkillBlockArgs): string {
+  const wrapper =
+    `<skill name="${input.name}" location="${input.filePath}">\n` +
+    `References are relative to ${input.baseDir}.\n\n` +
+    `${input.body}\n` +
+    `</skill>`;
+  return input.userArgs ? `${wrapper}\n\n${input.userArgs}` : wrapper;
+}
+
+/**
+ * Condense a user-message content string for `firstMessage` / display purposes.
+ *
+ * If `text` parses as a `<skill>` envelope, returns the slash-command form
+ * (`/skill:name args`) truncated to `maxLen` chars. Otherwise returns
+ * `text.slice(0, maxLen)`. Used by session-scanner / session-discovery so the
+ * 200-char `firstMessage` shows the recognisable slash form instead of the
+ * front of an opaque wrapper.
+ *
+ * See change: render-skill-invocations-collapsibly.
+ */
+export function condenseForFirstMessage(text: string, maxLen: number): string {
+  const block = parseSkillBlock(text);
+  if (block) return block.condensed.slice(0, maxLen);
+  return text.slice(0, maxLen);
+}

package/packages/shared/src/tool-registry/__tests__/managed-runtime-strategy.test.ts

@@ -0,0 +1,166 @@
+/**
+ * Chain-order tests for the managed-Node runtime strategy.
+ *
+ * After change `embed-managed-node-runtime`, the `node` and `npm`
+ * strategy chains gain a `managedRuntimeStrategy` between
+ * `overrideStrategy` and the existing PATH/where lookup. These tests
+ * pin the precedence:
+ *
+ *   1. override (tool-overrides.json)        — wins
+ *   2. managed runtime (<managedDir>/node/)  — preferred over PATH
+ *   3. where / PATH                          — fallback
+ *
+ * `exists` is injected so no real filesystem is touched.
+ *
+ * See change: embed-managed-node-runtime (task 3.3).
+ */
+import os from "node:os";
+import path from "node:path";
+import { describe, expect, it } from "vitest";
+import {
+  ToolRegistry,
+  registerDefaultTools,
+  OverridesStore,
+} from "../index.js";
+
+function freshRegistry(opts: {
+  exists?: (p: string) => boolean;
+  which?: (name: string) => string | null;
+  overrides?: Record<string, string>;
+  platform?: NodeJS.Platform;
+}) {
+  const store = new OverridesStore({
+    filePath: path.join(os.tmpdir(), `mr-test-${Math.random()}.json`),
+    warn: () => {},
+  });
+  for (const [k, v] of Object.entries(opts.overrides ?? {})) store.set(k, v);
+
+  const r = new ToolRegistry({
+    overrides: store,
+    platform: opts.platform ?? "linux",
+  });
+  registerDefaultTools(r, {
+    exists: opts.exists ?? (() => false),
+    which: opts.which ?? (() => null),
+    npmRootGlobal: () => "",
+  });
+  return r;
+}
+
+const HOME = os.homedir();
+const MANAGED_NODE_UNIX = path.join(HOME, ".pi-dashboard", "node", "bin", "node");
+const MANAGED_NPM_UNIX = path.join(HOME, ".pi-dashboard", "node", "bin", "npm");
+const MANAGED_NODE_WIN = path.join(HOME, ".pi-dashboard", "node", "node.exe");
+const MANAGED_NPM_WIN = path.join(HOME, ".pi-dashboard", "node", "npm.cmd");
+
+describe("node: managed-runtime strategy precedence", () => {
+  it("managed runtime present → returned over PATH (Unix)", () => {
+    const r = freshRegistry({
+      platform: "linux",
+      exists: (p) => p === MANAGED_NODE_UNIX,
+      which: () => "/usr/bin/node",
+    });
+    const res = r.resolve("node");
+    expect(res.ok).toBe(true);
+    expect(res.path).toBe(MANAGED_NODE_UNIX);
+    expect(res.source).toBe("managed");
+  });
+
+  it("managed runtime present → returned over PATH (Windows)", () => {
+    const r = freshRegistry({
+      platform: "win32",
+      exists: (p) => p === MANAGED_NODE_WIN,
+      which: () => "C:\\node\\node.exe",
+    });
+    const res = r.resolve("node");
+    expect(res.ok).toBe(true);
+    expect(res.path).toBe(MANAGED_NODE_WIN);
+    expect(res.source).toBe("managed");
+  });
+
+  it("override wins over managed runtime", () => {
+    const custom = "/opt/custom/node";
+    const r = freshRegistry({
+      platform: "linux",
+      overrides: { node: custom },
+      exists: (p) => p === custom || p === MANAGED_NODE_UNIX,
+    });
+    const res = r.resolve("node");
+    expect(res.ok).toBe(true);
+    expect(res.path).toBe(custom);
+    expect(res.source).toBe("override");
+  });
+
+  it("both absent → falls through to PATH lookup", () => {
+    const r = freshRegistry({
+      platform: "linux",
+      exists: () => false,
+      which: (name) => (name === "node" ? "/usr/bin/node" : null),
+    });
+    const res = r.resolve("node");
+    expect(res.ok).toBe(true);
+    expect(res.path).toBe("/usr/bin/node");
+    expect(res.source).toBe("system");
+  });
+
+  it("nothing present → ok:false with diagnostic trail", () => {
+    const r = freshRegistry({ platform: "linux", exists: () => false, which: () => null });
+    const res = r.resolve("node");
+    expect(res.ok).toBe(false);
+    const trailNames = res.tried.map((t) => t.strategy);
+    expect(trailNames).toContain("override");
+    expect(trailNames).toContain("managed");
+    expect(trailNames).toContain("where");
+  });
+});
+
+describe("npm: managed-runtime strategy precedence", () => {
+  it("managed npm present → returned over PATH (Unix)", () => {
+    const r = freshRegistry({
+      platform: "linux",
+      exists: (p) => p === MANAGED_NPM_UNIX,
+      which: () => "/usr/bin/npm",
+    });
+    const res = r.resolve("npm");
+    expect(res.ok).toBe(true);
+    expect(res.path).toBe(MANAGED_NPM_UNIX);
+    expect(res.source).toBe("managed");
+  });
+
+  it("managed npm present → returned over PATH (Windows)", () => {
+    const r = freshRegistry({
+      platform: "win32",
+      exists: (p) => p === MANAGED_NPM_WIN,
+      which: () => "C:\\node\\npm.cmd",
+    });
+    const res = r.resolve("npm");
+    expect(res.ok).toBe(true);
+    expect(res.path).toBe(MANAGED_NPM_WIN);
+    expect(res.source).toBe("managed");
+  });
+
+  it("override wins over managed npm", () => {
+    const custom = "/opt/custom/npm";
+    const r = freshRegistry({
+      platform: "linux",
+      overrides: { npm: custom },
+      exists: (p) => p === custom || p === MANAGED_NPM_UNIX,
+    });
+    const res = r.resolve("npm");
+    expect(res.ok).toBe(true);
+    expect(res.path).toBe(custom);
+    expect(res.source).toBe("override");
+  });
+
+  it("npm: managed absent + PATH present → falls through (Unix)", () => {
+    const r = freshRegistry({
+      platform: "linux",
+      exists: () => false,
+      which: (name) => (name === "npm" ? "/usr/bin/npm" : null),
+    });
+    const res = r.resolve("npm");
+    expect(res.ok).toBe(true);
+    expect(res.path).toBe("/usr/bin/npm");
+    expect(res.source).toBe("system");
+  });
+});

package/packages/shared/src/tool-registry/definitions.ts

@@ -18,6 +18,7 @@ import {
   bareImportStrategy,
   managedBinStrategy,
   managedModuleStrategy,
+  managedRuntimeStrategy,
   npmGlobalStrategy,
   overrideStrategy,
   whereStrategy,
@@ -39,21 +40,27 @@ function classify(strategyName: string): Source {
 // ── Binary definitions ──────────────────────────────────────────────────────
 
 function binaryDef(binaryName: string, deps?: StrategyDeps): ToolDefinition {
+  // The `node` binary gets the managed-Node runtime strategy prepended
+  // (after override) so the persistent <managedDir>/node/ install wins
+  // over PATH lookup. See change: embed-managed-node-runtime.
+  const isNode = binaryName === "node";
+  const strategies = [
+    overrideStrategy(binaryName, deps),
+    ...(isNode ? [managedRuntimeStrategy("node", deps)] : []),
+    managedBinStrategy(binaryName, deps),
+    whereStrategy(binaryName, deps),
+  ];
   return {
     name: binaryName,
     kind: "binary",
-    strategies: [
-      overrideStrategy(binaryName, deps),
-      managedBinStrategy(binaryName, deps),
-      whereStrategy(binaryName, deps),
-    ],
+    strategies,
     classify,
   };
 }
 
 // ── Module definitions ──────────────────────────────────────────────────────
 
-/** Sibling probe for an aliased package name (pi: `@mariozechner/*` + `@oh-my-pi/*`). */
+/** Sibling probe for an aliased package name (pi: `@earendil-works/*` + `@mariozechner/*`). */
 function moduleDefWithAliases(
   canonicalName: string,
   pkgNames: readonly string[],
@@ -181,7 +188,7 @@ const nodeScriptToArgv: ToolDefinition["toArgv"] = (resolvedPath, { platform, re
  * On Unix, the chain finds `pi` on PATH; argv = [pi].
  */
 function piExecutorDef(deps?: StrategyDeps): ToolDefinition {
-  const piPkgAliases = ["@mariozechner/pi-coding-agent", "@oh-my-pi/pi-coding-agent"];
+  const piPkgAliases = ["@earendil-works/pi-coding-agent", "@mariozechner/pi-coding-agent"];
   const cliEntry = path.join("dist", "cli.js");
 
   const winStrategies = [
@@ -283,14 +290,20 @@ function npmExecutorDef(deps?: StrategyDeps): ToolDefinition {
     },
   };
 
+  // Managed-Node runtime: prefer <managedDir>/node/{npm.cmd,bin/npm}
+  // when the runtime is installed. See change: embed-managed-node-runtime.
+  const managedNpm = managedRuntimeStrategy("npm", deps);
+
   const winStrategies = [
     overrideStrategy("npm", deps),
+    managedNpm,
     npmCliBesideNodeStrategy,
     whereStrategy("npm", deps),
   ];
 
   const unixStrategies = [
     overrideStrategy("npm", deps),
+    managedNpm,
     whereStrategy("npm", deps),
   ];
 
@@ -400,7 +413,19 @@ export function registerDefaultTools(registry: ToolRegistry, deps?: StrategyDeps
   registry.register(
     moduleDefWithAliases(
       "pi-coding-agent",
-      ["@mariozechner/pi-coding-agent", "@oh-my-pi/pi-coding-agent"],
+      ["@earendil-works/pi-coding-agent", "@mariozechner/pi-coding-agent"],
+      path.join("dist", "index.js"),
+      deps,
+    ),
+  );
+
+  // pi-ai module — used by model-proxy to call upstream LLM providers.
+  // Aliases: @earendil-works/pi-ai (preferred) + @mariozechner/pi-ai (legacy fallback).
+  // See change: add-dashboard-model-proxy.
+  registry.register(
+    moduleDefWithAliases(
+      "pi-ai",
+      ["@earendil-works/pi-ai", "@mariozechner/pi-ai"],
       path.join("dist", "index.js"),
       deps,
     ),

package/packages/shared/src/tool-registry/strategies.ts

@@ -13,6 +13,7 @@ import { createRequire } from "node:module";
 import path from "node:path";
 import { ToolResolver, isAppImageSelfHit } from "../platform/binary-lookup.js";
 import { getManagedBin, getManagedDir } from "../managed-paths.js";
+import { getManagedNodeBinDir } from "../platform/managed-node-path.js";
 import * as npm from "../platform/npm.js";
 import type { Strategy, StrategyCtx, StrategyResult } from "./types.js";
 
@@ -86,6 +87,47 @@ export function overrideStrategy(toolName: string, deps?: StrategyDeps): Strateg
   };
 }
 
+/**
+ * Managed Node runtime: `<managedDir>/node/{node.exe,npm.cmd,npx.cmd}`
+ * on Windows or `<managedDir>/node/bin/{node,npm,npx}` on Unix.
+ *
+ * Lets `ToolRegistry.resolve("node")` and `resolve("npm")` prefer the
+ * persistent runtime under `~/.pi-dashboard/node/` (installed by
+ * `installManagedNode`) over the system PATH lookup, while still
+ * deferring to `tool-overrides.json`.
+ *
+ * Returns `null` when the managed Node runtime is not present, so the
+ * standalone-CLI / no-Electron-resources case falls through cleanly to
+ * the existing `where`/PATH strategy.
+ *
+ * See change: embed-managed-node-runtime (spec: managed-node-runtime,
+ * Requirement: ToolRegistry resolves managed runtime first).
+ */
+export function managedRuntimeStrategy(
+  toolName: "node" | "npm" | "npx",
+  deps?: StrategyDeps,
+): Strategy {
+  const { exists } = d(deps);
+  return {
+    name: "managed",
+    run(ctx): StrategyResult {
+      const dir = getManagedNodeBinDir(ctx.env, ctx.platform);
+      const isWin = ctx.platform === "win32";
+      const fileName =
+        toolName === "node"
+          ? isWin
+            ? "node.exe"
+            : "node"
+          : isWin
+            ? `${toolName}.cmd`
+            : toolName;
+      const candidate = path.join(dir, fileName);
+      if (exists(candidate)) return { ok: true, path: candidate };
+      return { ok: false, reason: `missing: ${candidate}` };
+    },
+  };
+}
+
 /**
  * Managed install: `~/.pi-dashboard/node_modules/.bin/<name>(.cmd)` for
  * binaries, or any explicit relative path under `MANAGED_DIR` for

package/packages/shared/src/types.ts

@@ -125,6 +125,15 @@ export interface DashboardSession {
    * the entry. See change: add-extension-ui-decorations.
    */
   uiDecorators?: Record<string, DecoratorDescriptor>;
+  /**
+   * Per-session image asset registry, keyed by content hash. Populated by
+   * `asset_register` events emitted by the bridge for local-file images
+   * referenced as `![](path)` in assistant markdown. Survives event-buffer
+   * eviction (lives on Session, not in the rolling event buffer) so
+   * `pi-asset:<hash>` references in older messages still resolve.
+   * See change: chat-markdown-local-images-and-math.
+   */
+  assets?: Record<string, { data: string; mimeType: string }>;
 }
 
 // ── Extension UI System (Phase 1: management-modal slot) ───────────
@@ -333,6 +342,41 @@ export interface ModelInfo {
   id: string;
 }
 
+/**
+ * Provider catalogue entry pushed by the bridge to the server.
+ * Derived from pi's live `ModelRegistry` (see provider-register.ts in
+ * the bridge). The server caches the most recently received catalogue
+ * and uses it as the source for `GET /api/provider-auth/status`.
+ * See change: replace-hardcoded-provider-lists.
+ */
+export interface ProviderInfo {
+  /** pi-ai provider id (e.g. "anthropic", "deepseek", "google-vertex"). */
+  id: string;
+  /** From `modelRegistry.getProviderDisplayName(id)`; falls back to id. */
+  displayName: string;
+  /** True iff `authStorage.getOAuthProviders()` includes this id. */
+  hasOAuth: boolean;
+  /** True iff a credential is stored in auth.json. */
+  configured: boolean;
+  /** Where the credential is sourced from, when configured. */
+  source?: "stored" | "environment" | "fallback" | "runtime";
+  /** First env var name pi-ai consults for this provider, when applicable. */
+  envVar?: string;
+  /** True when configured via ambient credential chain (AWS profile / GCP ADC). */
+  ambient?: boolean;
+  /** Expiry timestamp for OAuth credentials. */
+  expires?: number;
+  /**
+   * True when this provider was registered by the dashboard itself via
+   * `pi.registerProvider()` from `~/.pi/agent/providers.json` (a "custom"
+   * provider managed by the LLM Providers settings section). Consumers
+   * use this to suppress API-key auth rows for custom providers — their
+   * keys are managed elsewhere. OAuth rows are still emitted because a
+   * custom OAuth provider needs its login button.
+   */
+  custom?: boolean;
+}
+
 /** Role assignment info (from pi-flows role-manager) */
 export interface RoleInfo {
   roles: Record<string, string>;
@@ -383,6 +427,19 @@ export function deriveChangeState(change: OpenSpecChange): ChangeState {
 export interface OpenSpecData {
   initialized: boolean;
   changes: OpenSpecChange[];
+  /**
+   * Cold-boot signaling: server has detected `openspec/changes/` for this
+   * cwd but the slow poll has not yet produced authoritative data.
+   *
+   * Optional for backwards compatibility — absence means `false`. Composes
+   * with `initialized` to encode three states:
+   *   - { initialized: false, pending: false } → no openspec dir
+   *   - { initialized: false, pending: true  } → dir exists, polling
+   *   - { initialized: true,  pending: ?     } → poll complete
+   *
+   * See change: fix-cold-boot-openspec-protocol.
+   */
+  pending?: boolean;
 }
 
 /** OpenSpec workflow phase detected from tool calls */
@@ -592,4 +649,11 @@ export interface ApiResponse<T = unknown> {
   success: boolean;
   data?: T;
   error?: string;
+  /**
+   * Optional structured failure-classifier code paired with `error`.
+   * Lets clients render specific UI for known failure modes
+   * (e.g., `"FORK_EMPTY_SESSION"`).
+   * See change: fix-fork-empty-session-silent-timeout.
+   */
+  code?: string;
 }