@blackbelt-technology/pi-agent-dashboard 0.5.0 → 0.5.2

package/packages/shared/src/platform/node-spawn.ts

@@ -118,29 +118,37 @@ export function toFileUrl(pathOrUrl: string): string {
  * host can exercise the Windows branch without mutating `process.platform`.
  *
  * !! JITI VERSION CONTRACT !!
- * The Windows-non-tsx arm assumes the jiti loader is from
- * `@mariozechner/pi-coding-agent@0.70.x` (jiti 2.x with the `file:///`
- * triple-slash URL handling fix). jiti 2.x correctly handles `file:///`
- * URL entries on Windows — it was the version we carved this contract
- * around in change `fix-windows-entry-script-url`.
- *
- * Newer jiti versions (e.g. jiti 2.6.5 in `pi-coding-agent@0.71.x`)
- * MISBEHAVE on `file:///` entries: they normalize triple-slash to
- * single-slash and prepend cwd as if the entry were a relative
- * specifier, producing `<cwd>/file:/...` ENOENT errors.
- *
- * The Electron Windows codepath defends against this version drift by
- * resolving jiti from the managed dir's `pi-coding-agent@0.70.0` (the
- * version pinned in `packages/electron/offline-packages.json` and
- * extracted into `~/.pi-dashboard/` by `installStandalone()` on first
- * launch — see Defect 1 of change
- * `fix-electron-windows-installer-and-server-bootstrap`). Since the
- * managed-dir tree is pinned, the contract holds regardless of what
- * jiti is on the user's PATH.
+ * The Windows-non-tsx arm relies on jiti's `file:///` triple-slash URL
+ * handling. Verified-good baselines (must be one of these in the
+ * offline cacache):
+ *   • `@earendil-works/pi-coding-agent@0.74.x` (jiti `^2.7.0`)  — current
+ *   • `@mariozechner/pi-coding-agent@0.70.x`  (jiti 2.x)        — legacy
+ *
+ * Both ship a jiti that correctly normalises `file:///` entries on
+ * Windows. The contract was originally carved around 0.70.x in change
+ * `fix-windows-entry-script-url` and re-anchored at 0.74.x in change
+ * `migrate-pi-fork-to-earendil` (E.7).
+ *
+ * Known-broken (do NOT pin): `pi-coding-agent@0.71.x` shipping
+ * `jiti@2.6.5`. That jiti version misnormalises triple-slash to
+ * single-slash and prepends cwd as if the entry were a relative
+ * specifier, producing `<cwd>/file:/...` ENOENT errors. Keep the
+ * 0.71.x / 2.6.5 mention here so contributors recognise the
+ * regression pattern if it recurs in a future jiti.
+ *
+ * The Electron Windows codepath defends against version drift by
+ * resolving jiti from the managed dir's pinned `pi-coding-agent`
+ * (currently `@earendil-works/pi-coding-agent@0.74.0`, pinned in
+ * `packages/electron/offline-packages.json` and extracted into
+ * `~/.pi-dashboard/` by `installStandalone()` on first launch — see
+ * Defect 1 of change `fix-electron-windows-installer-and-server-bootstrap`).
+ * Since the managed-dir tree is pinned, the contract holds regardless
+ * of what jiti is on the user's PATH.
  *
  * If a future change bumps the offline-cacache `pi-coding-agent` pin to
- * a version with a different jiti, RE-VERIFY this contract on Windows
- * manually (run a packaged Electron app on Win10 + Win11) and either:
+ * a version OUTSIDE the verified baselines, RE-VERIFY this contract on
+ * Windows manually (run a packaged Electron app on Win10 + Win11) and
+ * either:
  *   1. Update the contract (fix the file:// URL handling expectation), OR
  *   2. Add a per-jiti-version branch here, OR
  *   3. Switch the bundled loader to tsx (which has its own contract).
@@ -169,16 +177,53 @@ export function shouldUrlWrapEntry(
  * preserved. Does not import `node:child_process` directly (the type
  * imports above are annotated with the opt-out marker).
  */
+/**
+ * Pure helper: build the bare argv chunk for `node --import <loader>
+ * <entry> [...args]` with correct URL-wrapping at both positions.
+ *
+ * Single source of truth for the `--import` argv shape — used by
+ * `spawnNodeScript` (runtime spawn) and by
+ * `packages/server/src/restart-helper.ts buildOrchestratorScript`
+ * (which embeds the argv into a `node -e` orchestrator script that
+ * executes in a fresh process and therefore cannot call
+ * `spawnNodeScript` directly).
+ *
+ * No I/O. The `platform` parameter is passed through to
+ * `shouldUrlWrapEntry` for testability.
+ *
+ * Loader is always URL-wrapped. Entry is URL-wrapped per
+ * `shouldUrlWrapEntry(loader, platform)`.
+ */
+export function buildNodeImportArgvParts(opts: {
+  loader: string;
+  entry: string;
+  args?: readonly string[];
+  platform?: NodeJS.Platform;
+}): string[] {
+  const wrapEntry = shouldUrlWrapEntry(opts.loader, opts.platform);
+  const parts: string[] = [
+    "--import", toFileUrl(opts.loader),
+    wrapEntry ? toFileUrl(opts.entry) : opts.entry,
+  ];
+  if (opts.args && opts.args.length > 0) parts.push(...opts.args);
+  return parts;
+}
+
 export function spawnNodeScript(opts: SpawnNodeScriptOptions): ChildProcess {
   const nodeBin = opts.nodeBin ?? process.execPath;
-  const wrapEntry = shouldUrlWrapEntry(opts.loader);
 
-  const argv: string[] = [];
+  let argv: string[];
   if (opts.loader) {
-    argv.push("--import", toFileUrl(opts.loader));
+    argv = buildNodeImportArgvParts({
+      loader: opts.loader,
+      entry: opts.entry,
+      args: opts.args,
+    });
+  } else {
+    const wrapEntry = shouldUrlWrapEntry(opts.loader);
+    argv = [wrapEntry ? toFileUrl(opts.entry) : opts.entry];
+    if (opts.args) argv.push(...opts.args);
   }
-  argv.push(wrapEntry ? toFileUrl(opts.entry) : opts.entry);
-  if (opts.args) argv.push(...opts.args);
 
   return execSpawn(nodeBin, argv, opts.spawnOptions ?? {});
 }

package/packages/shared/src/protocol.ts

@@ -22,6 +22,14 @@ export interface SessionRegisterMessage {
   eventCount?: number;
   /** OS process ID of the pi agent — used for force-kill escalation */
   pid?: number;
+  /**
+   * Server-minted spawn correlation token. Bridge populates this from
+   * `process.env.PI_DASHBOARD_SPAWN_TOKEN` IFF this is the first register
+   * for the bridge process (`bc.hasRegisteredOnce === false`). Subsequent
+   * registers (reattach, in-process new/fork/resume) omit it.
+   * See change: spawn-correlation-token.
+   */
+  spawnToken?: string;
   /**
    * Why the bridge is registering this session. The bridge sets this to
    * `"spawn"` for the very first `session_register` after process boot
@@ -281,6 +289,23 @@ export interface UiDataListMessage {
   items: unknown[];
 }
 
+// ── RPC keeper: bridge → server slash dispatch ──
+// See change: add-rpc-stdin-dispatch-with-keeper-sidecar.
+//
+// Emitted by `slash-dispatch.ts::tryDispatchExtensionCommand` when the
+// active pi build does NOT expose `pi.dispatchCommand` AND the bridge
+// detects a headless RPC pi (per `isHeadlessRpcSession()`). The server's
+// dispatch-router writes `{type:"prompt", message: command, id: requestId}`
+// to the session's keeper UDS / named pipe and emits the optimistic
+// `command_feedback {status:"completed"}` (or error) to browser subscribers.
+export interface DispatchExtensionCommandMessage {
+  type: "dispatch_extension_command";
+  sessionId: string;
+  command: string;
+  /** UUID minted by the bridge so pi's RPC response can be correlated. */
+  requestId: string;
+}
+
 // ── Extension UI System (Phase 2: live in-page decorations) ──
 // See change: add-extension-ui-decorations.
 
@@ -346,7 +371,8 @@ export type ExtensionToServerMessage =
   | UiModulesListMessage
   | UiDataListMessage
   | ExtUiDecoratorMessage
-  | AssetRegisterMessage;
+  | AssetRegisterMessage
+  | DispatchExtensionCommandMessage;
 
 // ── Server → Extension ──────────────────────────────────────────────
 

package/packages/shared/src/recommended-extensions.ts

@@ -165,6 +165,24 @@ export const RECOMMENDED_EXTENSIONS: readonly RecommendedExtension[] = [
 		unlocks: ["browser tool (open, snapshot, click, screenshot)"],
 		toolsRegistered: ["browser"],
 	},
+	{
+		id: "pi-memory-honcho",
+		source: "npm:pi-memory-honcho",
+		displayName: "pi-memory-honcho",
+		fallbackDescription:
+			"Persistent cross-session memory backed by Honcho. Pairs with " +
+			"the @blackbelt-technology/pi-dashboard-honcho-plugin dashboard " +
+			"plugin which adds a settings panel, per-card actions, and " +
+			"optional self-hosted Honcho server lifecycle.",
+		status: "optional",
+		unlocks: [
+			"Honcho memory tools (honcho_search, honcho_context, honcho_profile)",
+			"Honcho settings panel (when honcho-plugin is loaded)",
+			"Per-card 🧠 status badge + interview/sync/map actions",
+		],
+		toolsRegistered: ["honcho_search", "honcho_context", "honcho_profile"],
+		autowired: true,
+	},
 ];
 
 /**

package/packages/shared/src/rest-api.ts

@@ -5,6 +5,8 @@ import type {
   DashboardSession,
   DashboardEvent,
   ApiResponse,
+  OpenSpecGroup,
+  OpenSpecGroupsFile,
 } from "./types.js";
 
 export type { ApiResponse } from "./types.js";
@@ -163,8 +165,22 @@ export type MkdirResponse = ApiResponse<MkdirResult>;
 
 // ── Tunnel Status ───────────────────────────────────────────────────
 
+export interface TunnelWatchdogPublicStatus {
+  running: boolean;
+  intervalMs: number;
+  failureThreshold: number;
+  probeTimeoutMs: number;
+  lastProbeAt: number | null;
+  lastSuccessAt: number | null;
+  lastFailureAt: number | null;
+  lastFailureReason: string | null;
+  consecutiveFailures: number;
+  lastRecycleAt: number | null;
+  recycleCount: number;
+}
+
 export type TunnelStatus =
-  | { status: "active"; url: string; serverOs: string }
+  | { status: "active"; url: string; serverOs: string; watchdog?: TunnelWatchdogPublicStatus }
   | { status: "inactive"; serverOs: string }
   | { status: "unavailable"; serverOs: string };
 
@@ -447,3 +463,205 @@ export interface RescanToolsRequest {
 export interface SetToolOverrideRequest {
   path: string;
 }
+
+// ── Model Proxy: wire-protocol types ────────────────────────────────
+
+/** OpenAI Chat Completions request shape (subset relevant to the proxy). */
+export interface OpenAIChatCompletionRequest {
+  model: string;
+  messages: OpenAIChatMessage[];
+  stream?: boolean;
+  max_tokens?: number;
+  temperature?: number;
+  top_p?: number;
+  tools?: OpenAITool[];
+  tool_choice?: string | { type: string; function?: { name: string } };
+  stop?: string | string[];
+}
+
+export interface OpenAIChatMessage {
+  role: "system" | "user" | "assistant" | "tool";
+  content?: string | OpenAIContentPart[];
+  name?: string;
+  tool_calls?: OpenAIToolCall[];
+  tool_call_id?: string;
+}
+
+export interface OpenAIContentPart {
+  type: "text" | "image_url";
+  text?: string;
+  image_url?: { url: string; detail?: string };
+}
+
+export interface OpenAITool {
+  type: "function";
+  function: { name: string; description?: string; parameters?: Record<string, unknown> };
+}
+
+export interface OpenAIToolCall {
+  id: string;
+  type: "function";
+  function: { name: string; arguments: string };
+}
+
+export interface OpenAIChatCompletionResponse {
+  id: string;
+  object: "chat.completion";
+  created: number;
+  model: string;
+  choices: {
+    index: number;
+    message: { role: "assistant"; content?: string | null; tool_calls?: OpenAIToolCall[] };
+    finish_reason: string | null;
+  }[];
+  usage?: { prompt_tokens: number; completion_tokens: number; total_tokens: number };
+}
+
+export interface OpenAIChatCompletionStreamChunk {
+  id: string;
+  object: "chat.completion.chunk";
+  created: number;
+  model: string;
+  choices: {
+    index: number;
+    delta: {
+      role?: "assistant";
+      content?: string | null;
+      reasoning_content?: string | null;
+      tool_calls?: { index: number; id?: string; type?: "function"; function?: { name?: string; arguments?: string } }[];
+    };
+    finish_reason: string | null;
+  }[];
+}
+
+export interface OpenAIModelEntry {
+  id: string;
+  object: "model";
+  created: number;
+  owned_by: string;
+  "x-pi"?: {
+    contextWindow?: number;
+    maxTokens?: number;
+    reasoning?: boolean;
+    cost?: { input?: number; output?: number };
+    input?: string[];
+  };
+}
+
+export interface OpenAIModelsResponse {
+  object: "list";
+  data: OpenAIModelEntry[];
+}
+
+/** Anthropic Messages request shape (subset relevant to the proxy). */
+export interface AnthropicMessagesRequest {
+  model: string;
+  messages: AnthropicMessage[];
+  system?: string | AnthropicContentBlock[];
+  max_tokens: number;
+  stream?: boolean;
+  temperature?: number;
+  top_p?: number;
+  tools?: AnthropicTool[];
+  stop_sequences?: string[];
+}
+
+export interface AnthropicMessage {
+  role: "user" | "assistant";
+  content: string | AnthropicContentBlock[];
+}
+
+export interface AnthropicContentBlock {
+  type: string;
+  text?: string;
+  source?: { type: "base64"; media_type: string; data: string };
+  [key: string]: unknown;
+}
+
+export interface AnthropicTool {
+  name: string;
+  description?: string;
+  input_schema: Record<string, unknown>;
+}
+
+export interface AnthropicMessagesResponse {
+  id: string;
+  type: "message";
+  role: "assistant";
+  content: AnthropicContentBlock[];
+  model: string;
+  stop_reason: string | null;
+  usage: { input_tokens: number; output_tokens: number };
+}
+
+export interface AnthropicMessagesStreamEvent {
+  type: string;
+  message?: AnthropicMessagesResponse;
+  index?: number;
+  content_block?: AnthropicContentBlock;
+  delta?: { type: string; text?: string; partial_json?: string; thinking?: string; [key: string]: unknown };
+  usage?: { output_tokens: number };
+}
+
+// ── Model Proxy: API key management ─────────────────────────────────
+
+export interface ModelProxyApiKeysCreateRequest {
+  label: string;
+  scopes?: string[];
+  expiresAt?: number;
+}
+
+export interface ModelProxyApiKeyEntry {
+  id: string;
+  label: string;
+  createdBy?: string;
+  scopes: string[];
+  createdAt: number;
+  lastUsedAt?: number;
+  expiresAt?: number;
+  revokedAt?: number;
+  hash: string; // redacted to "***" in list responses
+}
+
+export type ModelProxyApiKeysListResponse = ApiResponse<{
+  keys: ModelProxyApiKeyEntry[];
+  revoked: ModelProxyApiKeyEntry[];
+}>;
+
+export type ModelProxyApiKeysCreateResponse = ApiResponse<{
+  id: string;
+  label: string;
+  createdBy?: string;
+  scopes: string[];
+  createdAt: number;
+  expiresAt?: number;
+  key: string; // cleartext, revealed ONCE
+}>;
+
+// ── OpenSpec Change Grouping ────────────────────────────────────────
+// See change: add-openspec-change-grouping (tasks 1.6, 5.x).
+// Endpoints under `/api/openspec/groups[?cwd=…]`.
+
+export type GetOpenSpecGroupsResponse = ApiResponse<OpenSpecGroupsFile>;
+
+export interface CreateOpenSpecGroupRequest {
+  name: string;
+  color?: string;
+}
+export type CreateOpenSpecGroupResponse = ApiResponse<OpenSpecGroup>;
+
+export interface UpdateOpenSpecGroupRequest {
+  name?: string;
+  color?: string;
+  order?: number;
+}
+export type UpdateOpenSpecGroupResponse = ApiResponse<OpenSpecGroup>;
+
+export type DeleteOpenSpecGroupResponse = ApiResponse<void>;
+
+export interface SetOpenSpecGroupAssignmentRequest {
+  changeName: string;
+  /** `null` removes the assignment (change becomes Ungrouped). */
+  groupId: string | null;
+}
+export type SetOpenSpecGroupAssignmentResponse = ApiResponse<void>;