@pi-archimedes/core 2.7.3 → 2.9.0

package/src/bridge/index.ts

@@ -0,0 +1,166 @@
+// ── Bridge public API ────────────────────────────────────────────────────
+//
+// getBridge() is the singleton Tasks 2-3 import. The bridge is env-gated and
+// root-only: active iff (all 4 env vars present ∧ ctx.mode !== "tui" ∧
+// PI_SUBAGENT_SOCKET absent), evaluated at session_start. TUI always wins; a
+// subagent child (env present) is inactive. The `active` flag does not depend
+// on a successful connection (lazy, per-message connect).
+//
+// Inactive API: ask → throws BridgeInactiveError (loud); confirm → false;
+// password → "" (cancel).
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { AskResponsePayload, AskRequestPayload } from "../bus.js";
+import * as channel from "./channel.js";
+import * as events from "./events.js";
+
+export { BridgeTransportError, BridgeCancelledError } from "./channel.js";
+
+export class BridgeInactiveError extends Error {
+  constructor() {
+    super("bridge is not active");
+    this.name = "BridgeInactiveError";
+  }
+}
+
+function channelActive(): boolean {
+  return channel.isActive();
+}
+
+function eventsState(): "working" | "idle" | "blocked" {
+  return events.state();
+}
+
+export function getBridge() {
+  return { active: channelActive(), ask, confirm, password, dispatch, state: eventsState };
+}
+
+/**
+ * Delegate a subagent task to the Client (desktop) instead of forking a
+ * child pi process. The desktop runs the subagent session (a full ACP
+ * session on its worker runtime) and answers with the final output +
+ * metrics.
+ *
+ * The request opts OUT of the 5-minute timeout (`timeoutMs: null`): the
+ * desktop's lifecycle (parent close / EOF / app exit) is the cancel path —
+ * the tool's AbortSignal cancels the request (the promise settles
+ * deterministically with a BridgeCancelledError — NOT a
+ * BridgeTransportError, so it can never trigger a fork fallback) and the
+ * socket close delivers the desktop's EOF → the subagent session cancels.
+ * An unreachable bridge rejects with BridgeTransportError (the subagent's
+ * fork-fallback trigger); a response-carrying `error` (incl. the terminal
+ * `"cancelled"` frame) is authoritative and never a fallback.
+ */
+export interface DispatchParams {
+  agentName: string;
+  task: string;
+  systemPrompt: string | null;
+  model: string | null;
+  thinking: string | null;
+  tools: string[] | null;
+}
+
+export interface DispatchResult {
+  output: string;
+  metrics: { inputTokens: number; outputTokens: number; cost: number; durationMs: number };
+}
+
+export function dispatch(params: DispatchParams, toolCallId: string | undefined, signal?: AbortSignal): Promise<DispatchResult> {
+  if (!channelActive()) throw new BridgeInactiveError();
+  const handle = channel.request<DispatchResult>("dispatch_subagent", params, { toolCallId, source: "main", timeoutMs: null });
+  if (signal) {
+    // Same abort wiring as ask (see there for the full rationale): a
+    // pre-aborted signal cancels immediately, the listener is removed on
+    // settle via the .then(onFulfilled, onRejected) form.
+    if (signal.aborted) handle.cancel();
+    else signal.addEventListener("abort", handle.cancel, { once: true });
+    handle.promise.then(
+      () => { signal?.removeEventListener("abort", handle.cancel); },
+      () => { signal?.removeEventListener("abort", handle.cancel); },
+    );
+  }
+  return handle.promise;
+}
+
+/**
+ * Ask the Client (the root's direct Client request — NOT the relay/bridge bus
+ * subscription). The param is typed structurally from the bus payload —
+ * AskQuestion lives in packages/ask, which core cannot import.
+ */
+export function ask(params: { questions: AskRequestPayload["questions"] }, toolCallId: string, signal?: AbortSignal): Promise<AskResponsePayload> {
+  if (!channelActive()) throw new BridgeInactiveError();
+  const handle = channel.request<AskResponsePayload>("ask", params, { toolCallId, source: "main" });
+  if (signal) {
+    // Abort the turn → cancel the Client request (the tool's catch converts the
+    // cancel-rejection into the paired cancelled ASK_RESPONSE, so the refcount
+    // stays balanced). A signal that is ALREADY aborted never dispatches its
+    // "abort" event (it fires exactly once, at abort time), so an addEventListener
+    // alone would leave the request lingering until the Client responds or the
+    // 5-minute timeout — call cancel() directly in that case. cancel() is
+    // idempotent and settles the promise deterministically (the
+    // socket-close handler it triggers is a no-op once settled), so both
+    // branches coexist safely. The listener is removed on settle; the
+    // .then(onFulfilled, onRejected) form (not .finally) avoids an unhandled
+    // rejection from the derived promise when the request rejects.
+    if (signal.aborted) handle.cancel();
+    else signal.addEventListener("abort", handle.cancel, { once: true });
+    handle.promise.then(
+      () => { signal?.removeEventListener("abort", handle.cancel); },
+      () => { signal?.removeEventListener("abort", handle.cancel); },
+    );
+  }
+  return handle.promise;
+}
+
+export function confirm(params: { command: string; reason: string }): Promise<boolean> {
+  if (!channelActive()) return Promise.resolve(false);
+  return channel.request<{ confirmed: boolean }>("confirm", params, { source: "main" }).promise
+    .then((r) => r.confirmed)
+    .catch(() => false);
+}
+
+export function password(params: { command: string; reason: string }): Promise<string> {
+  if (!channelActive()) return Promise.resolve("");
+  return channel.request<{ password?: string }>("password", params, { source: "main" }).promise
+    .then((r) => r.password ?? "")
+    .catch(() => "");
+}
+
+/**
+ * Bridge-mode gate. PI_ARCHIMEDES_BRIDGE_SERVER_PID is presence-checked only
+ * in v1: agent-side server-pid verification is unimplemented on both
+ * platforms (Node's `net` exposes neither `GetNamedPipeServerProcessId` nor
+ * `SO_PEERCRED`); the desktop-side descendant check is the real defense.
+ */
+function isBridgeMode(ctx: { mode: string }): boolean {
+  return (
+    process.env.PI_ARCHIMEDES_BRIDGE === "1" &&
+    !!process.env.PI_ARCHIMEDES_BRIDGE_SOCKET &&
+    !!process.env.PI_ARCHIMEDES_BRIDGE_SESSION &&
+    !!process.env.PI_ARCHIMEDES_BRIDGE_SERVER_PID &&
+    ctx.mode !== "tui" &&
+    !process.env.PI_SUBAGENT_SOCKET
+  );
+}
+
+/**
+ * Subscribe the pi EXTENSION events (NOT the bus — nothing emits
+ * agent_start/agent_settled/session_start on the bus). The extension events DO
+ * fire in RPC mode (the RPC driver runs the same session machinery).
+ */
+export function registerBridge(pi: ExtensionAPI): void {
+  pi.on("session_start", (_e, ctx) => {
+    const active = isBridgeMode(ctx);
+    channel.configure({ active, socketPath: process.env.PI_ARCHIMEDES_BRIDGE_SOCKET });
+    if (active) {
+      events.start();
+      events.onSessionStart(ctx);
+    }
+  });
+  pi.on("agent_start", () => {
+    if (channelActive()) events.onAgentStart();
+  });
+  pi.on("agent_settled", () => {
+    if (channelActive()) events.onAgentSettled();
+  });
+}

package/src/bridge/self-usage.test.ts

@@ -0,0 +1,146 @@
+import { describe, it, expect, vi } from "vitest";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { getBus, Events } from "../bus.js";
+import { registerSelfUsage } from "./self-usage.js";
+
+/**
+ * Bus discipline (load-bearing): the bus has NO reset seam, `emit` with zero
+ * subscribers queues the payload globally, and `on()` replays queued events
+ * WITHOUT removing them. So EVERY test subscribes a per-test listener FIRST,
+ * then invokes the handler, asserts only on that test's captured array, and
+ * unsubscribes via the `on` return value.
+ */
+function captureCostUpdates(): { events: unknown[]; done: () => void } {
+  const events: unknown[] = [];
+  const unsub = getBus().on(Events.COST_UPDATE, (p) => events.push(p));
+  return { events, done: unsub };
+}
+
+/**
+ * Register and capture the turn_end handler, using the repo's mock-ExtensionAPI
+ * idiom (verbatim from bridge/index.test.ts — a plain object fails `tsc` with
+ * TS2740; the `as unknown as ExtensionAPI` cast and the `mock.calls` re-typing
+ * are BOTH required).
+ */
+function registerAndGetTurnEndHandler(): (e: unknown, ctx: unknown) => void {
+  const onSpy = vi.fn();
+  registerSelfUsage({ on: onSpy } as unknown as ExtensionAPI);
+  const calls = onSpy.mock.calls as Array<[string, (e: unknown, ctx: unknown) => void]>;
+  const handler = calls.find(([event]) => event === "turn_end")![1];
+  expect(handler).toBeTruthy();
+  return handler;
+}
+
+function assistantMessage(overrides: { usage?: unknown }): { role: "assistant"; usage?: unknown } {
+  return { role: "assistant", ...overrides };
+}
+
+// ── 1. per-turn emit ─────────────────────────────────────────────────────
+
+describe("per-turn emit", () => {
+  it("emits a COST_UPDATE with the turn's usage (delta, exact shape — no reasoning/totalTokens)", () => {
+    const handler = registerAndGetTurnEndHandler();
+    const { events, done } = captureCostUpdates();
+    try {
+      handler({
+        type: "turn_end",
+        turnIndex: 0,
+        message: assistantMessage({
+          usage: {
+            input: 100,
+            output: 50,
+            cacheRead: 10,
+            cacheWrite: 5,
+            totalTokens: 165,
+            cost: { input: 0.001, output: 0.002, cacheRead: 0.0001, cacheWrite: 0.0002, total: 0.0033 },
+          },
+        }),
+      }, { mode: "tui" });
+      expect(events).toHaveLength(1);
+      expect(events[0]).toEqual({
+        source: "main",
+        inputTokens: 100,
+        outputTokens: 50,
+        cacheReadTokens: 10,
+        cacheWriteTokens: 5,
+        cost: 0.0033,
+      });
+    } finally {
+      done();
+    }
+  });
+});
+
+// ── 2. no usage → no emit ────────────────────────────────────────────────
+
+describe("no usage", () => {
+  it("an assistant message without usage emits nothing", () => {
+    const handler = registerAndGetTurnEndHandler();
+    const { events, done } = captureCostUpdates();
+    try {
+      handler({
+        type: "turn_end",
+        turnIndex: 0,
+        message: assistantMessage({}),
+      }, { mode: "tui" });
+      expect(events).toHaveLength(0);
+    } finally {
+      done();
+    }
+  });
+});
+
+// ── 3. two turns → two events (delta semantics) ──────────────────────────
+
+describe("delta semantics", () => {
+  it("two turns emit two events with per-turn values (NOT accumulated)", () => {
+    const handler = registerAndGetTurnEndHandler();
+    const { events, done } = captureCostUpdates();
+    try {
+      handler({
+        type: "turn_end",
+        turnIndex: 0,
+        message: assistantMessage({
+          usage: { input: 100, output: 0, cacheRead: 0, cacheWrite: 0, totalTokens: 100, cost: { input: 0.001, output: 0, cacheRead: 0, cacheWrite: 0, total: 0.001 } },
+        }),
+      }, { mode: "tui" });
+      handler({
+        type: "turn_end",
+        turnIndex: 1,
+        message: assistantMessage({
+          usage: { input: 200, output: 0, cacheRead: 0, cacheWrite: 0, totalTokens: 200, cost: { input: 0.002, output: 0, cacheRead: 0, cacheWrite: 0, total: 0.002 } },
+        }),
+      }, { mode: "tui" });
+      expect(events).toHaveLength(2);
+      expect((events[0] as { inputTokens: number }).inputTokens).toBe(100);
+      expect((events[1] as { inputTokens: number }).inputTokens).toBe(200); // NOT 300
+    } finally {
+      done();
+    }
+  });
+});
+
+// ── 4. unaffected by bridge mode ────────────────────────────────────────
+
+describe("bridge independence", () => {
+  it("emits without the bridge channel being configured (bus is in-process; only the bridge forwarder is gated)", () => {
+    // NO configure() of the bridge channel anywhere in this file — the channel
+    // stays inactive by default. The emitter must still fire the bus event
+    // (design decision 3: registered unconditionally, not gated on bridge mode).
+    const handler = registerAndGetTurnEndHandler();
+    const { events, done } = captureCostUpdates();
+    try {
+      handler({
+        type: "turn_end",
+        turnIndex: 0,
+        message: assistantMessage({
+          usage: { input: 1, output: 1, cacheRead: 0, cacheWrite: 0, totalTokens: 2, cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 } },
+        }),
+      }, { mode: "tui" });
+      expect(events).toHaveLength(1);
+      expect((events[0] as { source: string }).source).toBe("main");
+    } finally {
+      done();
+    }
+  });
+});

package/src/bridge/self-usage.ts

@@ -0,0 +1,37 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { getBus, Events } from "../bus.js";
+
+/**
+ * Minimal structural mirror of the pi-ai `Usage` type (core does not depend on
+ * @earendil-works/pi-ai — keep the dependency surface unchanged).
+ */
+interface UsageLike {
+  input?: number;
+  output?: number;
+  cacheRead?: number;
+  cacheWrite?: number;
+  cost?: { total?: number };
+}
+
+/**
+ * Emit the session's OWN usage as a per-turn COST_UPDATE (source "main").
+ * Per design decision 1-3: per-turn (turn_end), delta (the turn's usage is
+ * not cumulative), NOT gated on bridge mode (the TUI footer's
+ * CostAccumulator sums it — the footer's cost line becomes the true session
+ * cost; in bridge mode the existing events.ts forwarder carries it to the
+ * desktop). `reasoning` is excluded (a subset of `output` — double-count).
+ */
+export function registerSelfUsage(pi: ExtensionAPI): void {
+  pi.on("turn_end", (event) => {
+    const usage = (event.message as { usage?: UsageLike } | undefined)?.usage;
+    if (!usage) return;
+    getBus().emit(Events.COST_UPDATE, {
+      source: "main",
+      inputTokens: usage.input ?? 0,
+      outputTokens: usage.output ?? 0,
+      cacheReadTokens: usage.cacheRead ?? 0,
+      cacheWriteTokens: usage.cacheWrite ?? 0,
+      cost: usage.cost?.total ?? 0,
+    });
+  });
+}

package/src/bus.ts

@@ -104,6 +104,7 @@ export const Events = {
   TODOS_CLEAR: "archimedes:todos_clear",
   ASK_REQUEST: "archimedes:ask_request",
   ASK_RESPONSE: "archimedes:ask_response",
+  ASK_CANCEL: "archimedes:ask_cancel",
 } as const;
 
 interface TodoUpdatePayload {
@@ -118,6 +119,7 @@ interface TodoClearPayload {
 interface AskRequestPayload {
   source: string;        // "subagent:<agent-name>"
   requestId: string;     // unique id to match request → response
+  toolCallId?: string;   // the tool-call id of the process that invoked the tool (carried for Client correlation)
   questions: Array<{ id: string; question: string; description?: string; options: Array<{ label: string }>; multi?: boolean; recommended?: number }>;
 }
 
@@ -127,4 +129,9 @@ interface AskResponsePayload {
   results: Array<{ id: string; selectedOptions: string[]; customInput?: string }>;
 }
 
-export type { CostUpdatePayload, TodoUpdatePayload, TodoClearPayload, AskRequestPayload, AskResponsePayload };
+interface AskCancelPayload {
+  requestId: string;
+  source: string;
+}
+
+export type { CostUpdatePayload, TodoUpdatePayload, TodoClearPayload, AskRequestPayload, AskResponsePayload, AskCancelPayload };

package/src/config.test.ts

@@ -1,115 +1,20 @@
-import { describe, it, expect, vi, beforeEach } from "vitest";
-
-vi.mock("./settings-io.js", () => ({
-  loadConfig: vi.fn(),
-  saveConfig: vi.fn(),
-}));
-
-const { loadCoreConfig, saveCoreConfig, DEFAULT_CORE_CONFIG, ANIMATION_STYLES } =
-  await import("./config.js");
-const { loadConfig, saveConfig } = await import("./settings-io.js");
+import { describe, it, expect } from "vitest";
+import { loadCoreConfig, saveCoreConfig, DEFAULT_CORE_CONFIG } from "./config.js";
 
 describe("loadCoreConfig", () => {
-  beforeEach(() => {
-    vi.clearAllMocks();
-  });
-
-  it("uses correct namespace", () => {
-    vi.mocked(loadConfig).mockReturnValue(DEFAULT_CORE_CONFIG);
-    loadCoreConfig();
-    expect(loadConfig).toHaveBeenCalledWith("archimedes.core", DEFAULT_CORE_CONFIG);
-  });
-
-  it("returns default config when no settings exist", () => {
-    vi.mocked(loadConfig).mockReturnValue(DEFAULT_CORE_CONFIG);
-    const result = loadCoreConfig();
-    expect(result).toEqual({
-      mutedTheme: false,
-      codeUnindent: true,
-      labelText: "Thinking...",
-      labelColor: "255,215,0",
-      animationStyle: "vertical-up",
-      editorSpinBorder: true,
-      editorSpinSpeed: "normal",
-      editorSpinLabel: "Working",
-      editorSpinStyle: "pendulum",
-    });
-  });
-
-  it("passes through merged config from settings-io", () => {
-    const merged = { ...DEFAULT_CORE_CONFIG, mutedTheme: true };
-    vi.mocked(loadConfig).mockReturnValue(merged);
-    const result = loadCoreConfig();
-    expect(result).toEqual(merged);
+  it("returns empty config", () => {
+    expect(loadCoreConfig()).toEqual({});
   });
 });
 
 describe("saveCoreConfig", () => {
-  beforeEach(() => {
-    vi.clearAllMocks();
-  });
-
-  it("saves with correct namespace", () => {
-    saveCoreConfig(DEFAULT_CORE_CONFIG);
-    expect(saveConfig).toHaveBeenCalledWith("archimedes.core", DEFAULT_CORE_CONFIG);
-  });
-
-  it("passes config through unchanged", () => {
-    const config = { ...DEFAULT_CORE_CONFIG, mutedTheme: true };
-    saveCoreConfig(config);
-    expect(saveConfig).toHaveBeenCalledWith("archimedes.core", config);
+  it("does nothing", () => {
+    expect(() => saveCoreConfig({})).not.toThrow();
   });
 });
 
 describe("DEFAULT_CORE_CONFIG", () => {
-  it("has the expected shape", () => {
-    expect(DEFAULT_CORE_CONFIG).toEqual({
-      mutedTheme: false,
-      codeUnindent: true,
-      labelText: "Thinking...",
-      labelColor: "255,215,0",
-      animationStyle: "vertical-up",
-      editorSpinBorder: true,
-      editorSpinSpeed: "normal",
-      editorSpinLabel: "Working",
-      editorSpinStyle: "pendulum",
-    });
-  });
-
-  it("exposes a speed→multiplier map (slow/normal/fast = 1.5/1/0.6 × native tempo)", async () => {
-    const { SPIN_SPEED_MULT } = await import("./config.js");
-    expect(SPIN_SPEED_MULT).toEqual({ slow: 1.5, normal: 1, fast: 0.6 });
-  });
-
-  it("exposes the SPIN_INTERVALS key set (ten gallery-derived styles)", async () => {
-    const { SPIN_INTERVALS } = await import("./editor/spin.js");
-    expect(Object.keys(SPIN_INTERVALS)).toEqual([
-      "typing",
-      "pulse",
-      "rain",
-      "cascade",
-      "columns",
-      "wave-rows",
-      "diagonal-swipe",
-      "sparkle",
-      "pendulum",
-      "marquee",
-    ]);
-  });
-});
-
-describe("ANIMATION_STYLES", () => {
-  it("contains all expected styles", () => {
-    expect(ANIMATION_STYLES).toEqual([
-      "diagonal",
-      "top-right",
-      "bottom-left",
-      "bottom-right",
-      "center-out",
-      "wave",
-      "horizontal",
-      "vertical",
-      "vertical-up",
-    ]);
+  it("is empty", () => {
+    expect(DEFAULT_CORE_CONFIG).toEqual({});
   });
 });

package/src/config.ts

@@ -1,68 +1,6 @@
 import { loadConfig, saveConfig } from "./settings-io.js";
 
-export const ANIMATION_STYLES = [
-  "diagonal",
-  "top-right",
-  "bottom-left",
-  "bottom-right",
-  "center-out",
-  "wave",
-  "horizontal",
-  "vertical",
-  "vertical-up",
-] as const;
-export type AnimationStyle = (typeof ANIMATION_STYLES)[number];
-
-export interface CoreConfig {
-  mutedTheme: boolean;
-  codeUnindent: boolean;
-  labelText: string;
-  labelColor: string;
-  animationStyle: AnimationStyle;
-  editorSpinBorder: boolean;
-  editorSpinSpeed: "slow" | "normal" | "fast";
-  editorSpinLabel: string;
-  editorSpinStyle: SpinnerStyle;
-}
-
-/** Border-spinner style (the ten gallery-derived variants, all registered in `SPIN_VARIANTS` (`editor/spin.ts`); unknown values normalize to `typing` via `normalizeSpinnerStyle`). */
-export type SpinnerStyle =
-  | "typing"
-  | "pulse"
-  | "rain"
-  | "cascade"
-  | "columns"
-  | "wave-rows"
-  | "diagonal-swipe"
-  | "sparkle"
-  | "pendulum"
-  | "marquee";
-
-export const DEFAULT_CORE_CONFIG: CoreConfig = {
-  mutedTheme: false,
-  codeUnindent: true,
-  labelText: "Thinking...",
-  labelColor: "255,215,0",
-  animationStyle: "vertical-up",
-  editorSpinBorder: true,
-  editorSpinSpeed: "normal",
-  editorSpinLabel: "Working",
-  editorSpinStyle: "pendulum",
-};
-
-/** Border-spinner speed setting → the multipliers the `editorSpinSpeed` setting applies to the style's native per-tick interval (SPIN_INTERVALS, `editor/spin.ts` — typing: 120 / 80 / 48 ms). */
-export const SPIN_SPEED_MULT: Record<CoreConfig["editorSpinSpeed"], number> = {
-  slow: 1.5,
-  normal: 1,
-  fast: 0.6,
-};
-
-const NAMESPACE = "archimedes.core";
-
-export function loadCoreConfig(): CoreConfig {
-  return loadConfig(NAMESPACE, DEFAULT_CORE_CONFIG);
-}
-
-export function saveCoreConfig(config: CoreConfig): void {
-  saveConfig(NAMESPACE, config);
-}
+export interface CoreConfig {}
+export const DEFAULT_CORE_CONFIG: CoreConfig = {};
+export function loadCoreConfig(): CoreConfig { return {}; }
+export function saveCoreConfig(_config: CoreConfig): void {}