petbox-wire 0.1.0-ci.1206

package/src/push-session.ts

@@ -0,0 +1,99 @@
+// Claude Code Stop hook (global) — port of push-session.ps1.
+//
+// Mirrors the session conversation into PetBox's Session module so the board auto-populates.
+// The project + API key are resolved from cwd via the shared registry; if the cwd is not a
+// registered project this exits immediately (first guard, before any work).
+//
+// Reads the full transcript JSONL, extracts the user/assistant text turns (tool dumps and
+// system reminders excluded), and pushes only the INCREMENT via the server-authoritative
+// append cursor (see append.ts): this process is fresh each turn, so it optimistically
+// resends a small idempotent overlap window; a contiguity gap comes back as a structured
+// 409 with the server's lastOrdinal and the tail is resent from there. Old servers without
+// the append route fall back to the legacy full-snapshot push. Best-effort: every failure
+// is swallowed and we ALWAYS exit 0 — never break the user's session.
+
+import { pushTranscript } from "./append.ts";
+import { unrefLingeringHandles } from "./hook-drain.ts";
+import { resolveProject } from "./registry.ts";
+import { buildMessages, type Msg } from "./transcript.ts";
+// Observed role binding is stamped inside pushTranscript (X-PetBox-Session-Meta via
+// resolveObservedBinding) — server stores observation only; local roles.json is SoT.
+
+const FETCH_TIMEOUT_MS = 12000;
+
+type HookInput = {
+  session_id?: string;
+  transcript_path?: string;
+  cwd?: string;
+  stop_hook_active?: boolean;
+};
+
+function readStdin(): Promise<string> {
+  return new Promise((resolve) => {
+    let buf = "";
+    process.stdin.setEncoding("utf8");
+    process.stdin.on("data", (c) => (buf += c));
+    process.stdin.on("end", () => resolve(buf));
+    process.stdin.on("error", () => resolve(buf));
+  });
+}
+
+async function main(): Promise<void> {
+  try {
+    const raw = await readStdin();
+    let j: HookInput;
+    try {
+      j = JSON.parse(raw);
+    } catch {
+      return;
+    }
+    if (j.stop_hook_active) return;
+
+    // FIRST guard: not a registered project → silent no-op.
+    const resolved = resolveProject(j.cwd ?? "");
+    if (!resolved) return;
+
+    const sid = (j.session_id ?? "").trim();
+    const tp = (j.transcript_path ?? "").trim();
+    if (!sid || !tp) return;
+
+    let msgs: Msg[];
+    try {
+      msgs = await buildMessages(tp);
+    } catch {
+      return; // transcript missing/unreadable
+    }
+    if (msgs.length === 0) return; // empty body → server returns 400, don't push
+
+    // Fresh process each turn → no remembered cursor (null): pushTranscript guesses an
+    // idempotent overlap window and self-heals off the server's structured gap reject.
+    await pushTranscript(
+      {
+        baseUrl: resolved.baseUrl,
+        project: resolved.project,
+        sessionId: sid,
+        apiKey: resolved.apiKey,
+        agent: "claude-code",
+        timeoutMs: FETCH_TIMEOUT_MS,
+      },
+      msgs,
+      null,
+    );
+  } catch {
+    // best-effort: never break the user's session
+  }
+}
+
+// Exit cleanly instead of tearing the process down mid-close: a hard process.exit() while
+// libuv handles from the HTTP push above are still closing can race Windows' async handle
+// teardown (`Assertion failed: !(handle->flags & UV_HANDLE_CLOSING), src\win\async.c`) — the
+// same crash observed in pull-memory.ts (see its exit comment). Setting exitCode and returning
+// lets Node drain the event loop naturally instead — `Connection: close` (append.ts) covers a
+// completed push, and unrefLingeringHandles covers a push aborted mid-flight against a stalled
+// server (measured to leave its TLSSocket alive for several more seconds otherwise; see
+// hook-drain.ts) so a slow Stop hook can't turn into a multi-second stall on a handle nothing
+// is still using.
+main().finally(() => {
+  process.exitCode = 0;
+  unrefLingeringHandles();
+});

package/src/registry.ts

@@ -0,0 +1,120 @@
+// Shared project resolver for the global agent-wiring kit.
+//
+// One global registry (`~/.petbox/projects.json`) maps a filesystem prefix to a PetBox
+// project + the env var that holds its API key. The Claude Code user hooks and the global
+// opencode plugin both run in EVERY project on the machine, so they resolve the active
+// project by the current working directory (longest-prefix match) and no-op cleanly when
+// the cwd is not registered.
+//
+// Plain TS for native node type-stripping: no enum/namespace/parameter-properties, type-only
+// imports, zero deps.
+
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+const DEFAULT_BASE_URL = "https://petbox.3po.su";
+
+// A registry entry may carry extra keys written by older kits (e.g. the removed `promptRag` gate) —
+// they are simply ignored here and dropped the next time wire.ts upserts the entry.
+export type RegistryEntry = {
+  prefix: string;
+  project: string;
+  envVar: string;
+  baseUrl?: string;
+};
+
+export type ResolvedProject = {
+  project: string;
+  apiKey: string;
+  baseUrl: string;
+  envVar: string;
+};
+
+export function registryPath(): string {
+  return join(homedir(), ".petbox", "projects.json");
+}
+
+// Cross-platform key store written by wire.ts: ~/.petbox/keys.json is a flat JSON map
+// { "<ENV_VAR>": "<key>" }. Read as a fallback when the env var is not set in the process
+// (so a machine wired via `npx petbox-wire` works without a user-scope env var). Never throws.
+function readKeyStore(envVar: string): string {
+  try {
+    const raw = readFileSync(join(homedir(), ".petbox", "keys.json"), "utf8");
+    const parsed = JSON.parse(raw);
+    const v = parsed && typeof parsed === "object" ? parsed[envVar] : undefined;
+    return typeof v === "string" ? v : "";
+  } catch {
+    return "";
+  }
+}
+
+// Normalize a path for prefix comparison: unify separators to "/", drop a trailing
+// separator, and lowercase on Windows (case-insensitive filesystem).
+function normalize(p: string): string {
+  let n = String(p).replace(/[\\/]+/g, "/");
+  if (n.length > 1 && n.endsWith("/")) n = n.slice(0, -1);
+  if (process.platform === "win32") n = n.toLowerCase();
+  return n;
+}
+
+// Segment-boundary prefix match: "d:/my/prj/yoba" must NOT match "d:/my/prj/yobapub".
+// dir is a prefix of, or equal to, the entry path (so worktree subfolders are covered).
+function isUnderPrefix(dir: string, prefix: string): boolean {
+  if (dir === prefix) return true;
+  return dir.startsWith(prefix + "/");
+}
+
+export function readRegistry(): RegistryEntry[] {
+  try {
+    const raw = readFileSync(registryPath(), "utf8");
+    const parsed = JSON.parse(raw);
+    const entries = parsed && Array.isArray(parsed.entries) ? parsed.entries : [];
+    return entries.filter(
+      (e: unknown): e is RegistryEntry =>
+        !!e &&
+        typeof (e as RegistryEntry).prefix === "string" &&
+        typeof (e as RegistryEntry).project === "string" &&
+        typeof (e as RegistryEntry).envVar === "string",
+    );
+  } catch {
+    return [];
+  }
+}
+
+// Resolve the active project for a directory. Returns null on ANY failure
+// (no registry file, no match, empty env var) — never throws, because the hooks
+// that call this run globally and must be a no-op outside registered projects.
+export function resolveProject(dir: string): ResolvedProject | null {
+  try {
+    if (!dir || typeof dir !== "string") return null;
+    const entries = readRegistry();
+    if (entries.length === 0) return null;
+
+    const nd = normalize(dir);
+    let best: RegistryEntry | null = null;
+    let bestLen = -1;
+    for (const e of entries) {
+      const np = normalize(e.prefix);
+      if (isUnderPrefix(nd, np) && np.length > bestLen) {
+        best = e;
+        bestLen = np.length;
+      }
+    }
+    if (!best) return null;
+
+    // env var wins; fall back to ~/.petbox/keys.json (the wire.ts key store).
+    const apiKey = process.env[best.envVar] || readKeyStore(best.envVar);
+    if (!apiKey || apiKey.trim().length === 0) return null;
+
+    const baseUrl = (best.baseUrl && best.baseUrl.trim()) || DEFAULT_BASE_URL;
+    return {
+      project: best.project,
+      apiKey,
+      baseUrl: baseUrl.replace(/\/+$/, ""),
+      envVar: best.envVar,
+    };
+  } catch {
+    return null;
+  }
+}

package/src/roles.test.ts

@@ -0,0 +1,255 @@
+// Unit tests for the local role→model binding store (roles.ts).
+//
+// Run: node --test src/roles.test.ts   (Node >= 23.6 native TS type-stripping; no build step)
+
+import assert from "node:assert/strict";
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync, mkdirSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { test } from "node:test";
+import {
+  exportRolesBootstrap,
+  formatResolvedBinding,
+  isEmptyRoles,
+  loadRoles,
+  resolveAgentRoles,
+  resolveObservedBinding,
+  rolesPath,
+  saveRoles,
+  useProfile,
+  type RolesFile,
+} from "./roles.ts";
+
+function freshHome(): string {
+  return mkdtempSync(join(tmpdir(), "petbox-wire-roles-"));
+}
+
+const SAMPLE: RolesFile = {
+  activeProfile: "default",
+  profiles: {
+    default: {
+      agents: {
+        "claude-code": {
+          roles: {
+            orchestrator: { model: "claude-opus-4" },
+            worker: { model: "claude-sonnet-4" },
+          },
+        },
+        opencode: {
+          roles: {
+            orchestrator: { model: "deepseek-chat" },
+            worker: { model: "deepseek-coder" },
+          },
+        },
+      },
+    },
+  },
+};
+
+test("load missing file → empty shell (never throws)", () => {
+  const home = freshHome();
+  try {
+    assert.equal(existsSync(rolesPath(home)), false);
+    const data = loadRoles(home);
+    assert.equal(data.activeProfile, "default");
+    assert.deepEqual(data.profiles, {});
+    assert.equal(isEmptyRoles(data), true);
+  } finally {
+    rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test("load corrupt / non-object JSON → empty shell", () => {
+  const home = freshHome();
+  try {
+    mkdirSync(join(home, ".petbox"), { recursive: true });
+    writeFileSync(rolesPath(home), "not-json{{{", "utf8");
+    const data = loadRoles(home);
+    assert.equal(data.activeProfile, "default");
+    assert.deepEqual(data.profiles, {});
+
+    writeFileSync(rolesPath(home), "null", "utf8");
+    assert.deepEqual(loadRoles(home).profiles, {});
+  } finally {
+    rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test("save/load roundtrip under temp HOME", () => {
+  const home = freshHome();
+  try {
+    saveRoles(SAMPLE, home);
+    assert.equal(existsSync(rolesPath(home)), true);
+    const loaded = loadRoles(home);
+    assert.equal(loaded.activeProfile, "default");
+    const defaultProfile = loaded.profiles["default"];
+    assert.ok(defaultProfile, "the 'default' profile must round-trip");
+    const claudeCode = defaultProfile.agents["claude-code"];
+    assert.ok(claudeCode, "claude-code agent bindings must round-trip");
+    assert.equal(claudeCode.roles["orchestrator"]?.model, "claude-opus-4");
+    const opencode = defaultProfile.agents["opencode"];
+    assert.ok(opencode, "opencode agent bindings must round-trip");
+    assert.equal(opencode.roles["worker"]?.model, "deepseek-coder");
+    // file is pretty-printed JSON
+    const raw = JSON.parse(readFileSync(rolesPath(home), "utf8"));
+    assert.equal(raw.activeProfile, "default");
+  } finally {
+    rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test("profile use: set activeProfile and create shell if missing", () => {
+  const home = freshHome();
+  try {
+    let data = loadRoles(home);
+    data = useProfile(data, "work");
+    assert.equal(data.activeProfile, "work");
+    const workProfile = data.profiles["work"];
+    assert.ok(workProfile);
+    assert.deepEqual(workProfile.agents, {});
+    saveRoles(data, home);
+
+    // switching again keeps the shell and updates active
+    data = useProfile(loadRoles(home), "default");
+    assert.equal(data.activeProfile, "default");
+    assert.ok(data.profiles["work"], "prior profile shell retained");
+    saveRoles(data, home);
+
+    const reloaded = loadRoles(home);
+    assert.equal(reloaded.activeProfile, "default");
+    assert.ok(reloaded.profiles["work"]);
+  } finally {
+    rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test("export shape is bootstrap-safe RolesFile (no secrets field)", () => {
+  const exported = exportRolesBootstrap(SAMPLE);
+  assert.equal(exported.activeProfile, "default");
+  const defaultProfile = exported.profiles["default"];
+  assert.ok(defaultProfile, "the 'default' profile must round-trip through export");
+  const claudeCode = defaultProfile.agents["claude-code"];
+  assert.ok(claudeCode, "claude-code agent bindings must round-trip through export");
+  assert.equal(
+    claudeCode.roles["worker"]?.model,
+    "claude-sonnet-4",
+  );
+  // no accidental secret-looking top-level keys
+  const keys = Object.keys(exported).sort();
+  assert.deepEqual(keys, ["activeProfile", "profiles"]);
+});
+
+test("resolveAgentRoles / resolveObservedBinding do not invent defaults", () => {
+  const home = freshHome();
+  try {
+    assert.deepEqual(resolveAgentRoles(loadRoles(home), "claude-code"), {});
+    assert.equal(resolveObservedBinding("claude-code", home), null);
+
+    saveRoles(SAMPLE, home);
+    assert.deepEqual(resolveAgentRoles(loadRoles(home), "claude-code"), {
+      orchestrator: "claude-opus-4",
+      worker: "claude-sonnet-4",
+    });
+    const obs = resolveObservedBinding("claude-code", home);
+    assert.deepEqual(obs, {
+      profile: "default",
+      agent: "claude-code",
+      roles: { orchestrator: "claude-opus-4", worker: "claude-sonnet-4" },
+    });
+    // truly unknown agent → null observation
+    assert.equal(resolveObservedBinding("not-a-harness", home), null);
+  } finally {
+    rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test("factory-droid alias resolves to canonical droid (session agent id)", () => {
+  const home = freshHome();
+  try {
+    saveRoles(
+      {
+        activeProfile: "default",
+        profiles: {
+          default: {
+            agents: {
+              // legacy / display name in roles.json
+              "factory-droid": {
+                roles: {
+                  orchestrator: { model: "deepseek-v4-pro" },
+                  worker: { model: "deepseek-v4-pro" },
+                },
+              },
+            },
+          },
+        },
+      },
+      home,
+    );
+    // push-session / droid-push stamps agent:"droid" — must find factory-droid bucket
+    assert.deepEqual(resolveAgentRoles(loadRoles(home), "droid"), {
+      orchestrator: "deepseek-v4-pro",
+      worker: "deepseek-v4-pro",
+    });
+    assert.deepEqual(resolveAgentRoles(loadRoles(home), "factory-droid"), {
+      orchestrator: "deepseek-v4-pro",
+      worker: "deepseek-v4-pro",
+    });
+    const obs = resolveObservedBinding("droid", home);
+    assert.deepEqual(obs, {
+      profile: "default",
+      agent: "droid", // stamp always uses canonical id
+      roles: { orchestrator: "deepseek-v4-pro", worker: "deepseek-v4-pro" },
+    });
+    // looking up via alias still stamps canonical agent id
+    assert.equal(resolveObservedBinding("factory-droid", home)?.agent, "droid");
+  } finally {
+    rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test("formatResolvedBinding surfaces empty vs populated", () => {
+  const home = freshHome();
+  try {
+    const empty = formatResolvedBinding(loadRoles(home));
+    assert.match(empty, /activeProfile: default/);
+    assert.match(empty, /no agent role bindings/);
+
+    const filled = formatResolvedBinding(SAMPLE);
+    assert.match(filled, /claude-code:/);
+    assert.match(filled, /orchestrator: claude-opus-4/);
+    assert.match(filled, /opencode:/);
+  } finally {
+    rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test("light validation drops junk role entries without model", () => {
+  const home = freshHome();
+  try {
+    mkdirSync(join(home, ".petbox"), { recursive: true });
+    writeFileSync(
+      rolesPath(home),
+      JSON.stringify({
+        activeProfile: "default",
+        profiles: {
+          default: {
+            agents: {
+              "claude-code": {
+                roles: {
+                  orchestrator: { model: "ok-model" },
+                  broken: { notModel: true },
+                  empty: { model: "  " },
+                },
+              },
+            },
+          },
+        },
+      }),
+      "utf8",
+    );
+    const data = loadRoles(home);
+    assert.deepEqual(resolveAgentRoles(data, "claude-code"), { orchestrator: "ok-model" });
+  } finally {
+    rmSync(home, { recursive: true, force: true });
+  }
+});