petbox-wire 0.1.0-ci.543

package/README.md

@@ -0,0 +1,51 @@
+# petbox-wire
+
+Wire any project to [PetBox](https://petbox.3po.su) for **Claude Code**, **opencode** and
+**Factory Droid** — with one command, no repo clone:
+
+```bash
+npx petbox-wire <dir> <project> --key <KEY>
+```
+
+- `<dir>` — the project directory to wire (its cwd prefix is registered).
+- `<project>` — the PetBox project key the directory maps to.
+- `--key <KEY>` — the project's API key. Mint one from a Claude session on the `$system`
+  project (`mcp__petbox__apikey_create`); key minting is out of scope for this tool.
+- `--env <VAR>` — override the env-var name (default `<PROJECT>_API_KEY`, uppercased).
+- `--workspace <WS>` — workspace for the SKILL.md permalink (default `stdray`).
+- `--cleanup-legacy` — remove a project's old per-project hook/plugin copies.
+
+## Requirements
+
+**Node >= 23.6** — the kit is plain TypeScript run through Node's native type-stripping
+(no build, zero runtime dependencies). Older Node exits with a clear version error.
+
+## What it installs
+
+- **Global hooks** for Claude Code (`~/.claude/settings.json`) and Factory Droid
+  (`~/.factory/settings.json`): a `Stop` hook that mirrors each session into PetBox and a
+  `SessionStart` hook that injects the memory protocol + canon. Merged, never clobbered.
+- **A global opencode plugin** (`~/.config/opencode/plugins/petbox.ts`) with the same two
+  behaviors.
+- **Per-project config** in `<dir>`: `.mcp.json` (Claude Code MCP), `.opencode/opencode.json`
+  (opencode MCP), `.factory/mcp.json` (Droid MCP, merged), and the rendered `SKILL.md` under
+  `.claude/skills/petbox/` and `.factory/skills/petbox/`.
+
+## Where things live
+
+- **Stable kit copy:** `~/.petbox/wire/` — every run copies the kit here, and all global hooks
+  point at this stable location (so they survive `npx` cache eviction).
+- **Registry:** `~/.petbox/projects.json` — maps a filesystem prefix → project + env var. The
+  hooks and opencode plugin resolve the active project by cwd against it.
+- **Key store:** `~/.petbox/keys.json` — `{ "<ENV_VAR>": "<key>" }` (POSIX: `chmod 0600`). The
+  kit hooks read `process.env[<ENV_VAR>]` first, then this file. Header values in the committed
+  configs stay as `${VAR}` references — no secret is written into any project file.
+- **Environment variable:** the per-project MCP configs resolve `${<ENV_VAR>}` from the real
+  environment, so wire also persists it — Windows: user-scope env; POSIX: `~/.petbox/env.sh`
+  (generated from the key store) sourced from your login profiles. Start a **new terminal**
+  before launching agents after the first wiring.
+
+## Updating the kit
+
+Re-run `npx petbox-wire@latest <dir> <project> --key <KEY>` to refresh the stable copy in
+`~/.petbox/wire/` and the generated config. Runs are idempotent.

package/bin/petbox-wire.js

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+// Thin launcher for the PetBox agent-wiring kit.
+//
+// Plain JS (no TypeScript) so it still starts on an old Node and can print a clear
+// version error. The kit itself is plain TypeScript executed by Node's native
+// type-stripping, which needs Node >= 23.6.
+
+const [maj, min] = process.versions.node.split(".").map((n) => parseInt(n, 10));
+if (maj < 23 || (maj === 23 && min < 6)) {
+  console.error(
+    `petbox-wire needs Node >= 23.6 (native TypeScript type-stripping); you have ${process.versions.node}`,
+  );
+  process.exit(1);
+}
+
+// wire.ts runs main() at module top level, so importing it executes the CLI.
+await import("../src/wire.ts");

package/package.json

@@ -0,0 +1,35 @@
+{
+	"name": "petbox-wire",
+	"version": "0.1.0-ci.543",
+	"description": "Wire any project to PetBox (Claude Code, opencode, Factory Droid) — global hooks, MCP configs and skills — with a single npx command, no repo clone.",
+	"type": "module",
+	"bin": {
+		"petbox-wire": "bin/petbox-wire.js"
+	},
+	"files": [
+		"bin",
+		"src",
+		"README.md"
+	],
+	"engines": {
+		"node": ">=23.6.0"
+	},
+	"keywords": [
+		"petbox",
+		"wiring",
+		"claude-code",
+		"opencode",
+		"factory-droid",
+		"mcp"
+	],
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/stdray/petbox.git",
+		"directory": "src/clients-ts/petbox-wire"
+	},
+	"publishConfig": {
+		"registry": "https://registry.npmjs.org",
+		"access": "public"
+	}
+}

package/src/append.ts

@@ -0,0 +1,123 @@
+// Shared incremental session push — the ONE append-flow implementation both Stop hooks
+// (push-session.ts for Claude Code, opencode-plugin.ts for opencode) use, so the wire
+// protocol cannot drift between agents (spec: session-append-wire, wiring-single-source).
+//
+// The server owns the cursor: a session's lastOrdinal is its stored message count. The
+// client sends only a tail batch tagged with `fromOrdinal` (the ordinal of the batch's
+// first message):
+//   - contiguous / overlapping → 200 { lastOrdinal, appended } (overlap is idempotent —
+//     ordinals the server already holds are ignored, so guessing "a little too early"
+//     is always safe);
+//   - gap → 409 { error: "gap", lastOrdinal } → self-heal: resend from lastOrdinal+1.
+//
+// The client keeps NO durable state. A long-lived host (the opencode plugin) passes the
+// lastOrdinal remembered from the previous response; a per-invocation host (the Claude
+// Code Stop hook process is fresh each turn) passes null and we optimistically resend a
+// small overlap window from the end of the local transcript — one round-trip in the
+// steady state, two after a restart/outage (the 409 tells us where to resume).
+//
+// Fallback: an old server without the append route 404s → push the full transcript to the
+// legacy last-write-wins endpoint, exactly what the hooks did before.
+//
+// Plain TS for native node type-stripping: zero deps.
+
+import type { Msg } from "./transcript.ts";
+
+// How many trailing messages to optimistically resend when the server cursor is unknown.
+// A turn typically adds 2-4 messages; overlap is idempotent, so oversizing only costs bytes.
+const OVERLAP_WINDOW = 8;
+
+const MAX_APPEND_ATTEMPTS = 3;
+
+export type PushTarget = {
+  baseUrl: string;
+  project: string;
+  sessionId: string;
+  apiKey: string;
+  agent: string;
+  timeoutMs: number;
+};
+
+function ndjson(msgs: readonly Msg[]): string {
+  return msgs.map((m) => JSON.stringify(m)).join("\n");
+}
+
+async function post(url: string, apiKey: string, body: string, timeoutMs: number): Promise<Response> {
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), timeoutMs);
+  try {
+    return await fetch(url, {
+      method: "POST",
+      headers: { "X-Api-Key": apiKey, "Content-Type": "application/x-ndjson; charset=utf-8" },
+      body,
+      signal: ctrl.signal,
+    });
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+// Push the (full, ordered) local transcript incrementally. `knownLastOrdinal` is the cursor
+// remembered from a previous response in THIS process, or null when unknown. Returns the
+// server's lastOrdinal after the push (feed it back next call), or null when every path
+// failed — callers are best-effort and must swallow that.
+export async function pushTranscript(
+  t: PushTarget,
+  msgs: readonly Msg[],
+  knownLastOrdinal: number | null,
+): Promise<number | null> {
+  if (msgs.length === 0) return knownLastOrdinal;
+
+  // The server already has everything we know about → nothing to send (the transcript is
+  // append-only, so equal length means equal content).
+  if (knownLastOrdinal !== null && knownLastOrdinal >= msgs.length) return knownLastOrdinal;
+
+  const base = `${t.baseUrl}/api/sessions/${t.project}/${encodeURIComponent(t.sessionId)}`;
+
+  let from =
+    knownLastOrdinal !== null && knownLastOrdinal >= 0
+      ? knownLastOrdinal + 1
+      : Math.max(1, msgs.length - OVERLAP_WINDOW + 1);
+
+  for (let attempt = 0; attempt < MAX_APPEND_ATTEMPTS; attempt++) {
+    let resp: Response;
+    try {
+      resp = await post(
+        `${base}/append?agent=${encodeURIComponent(t.agent)}&fromOrdinal=${from}`,
+        t.apiKey,
+        ndjson(msgs.slice(from - 1)),
+        t.timeoutMs,
+      );
+    } catch {
+      return null; // network failure — a full-snapshot retry would fail the same way
+    }
+
+    if (resp.ok) {
+      const j = (await resp.json().catch(() => null)) as { lastOrdinal?: number } | null;
+      return j && typeof j.lastOrdinal === "number" ? j.lastOrdinal : msgs.length;
+    }
+
+    if (resp.status === 409) {
+      // Structured contiguity gap: the body carries the server's cursor. Resend from there.
+      const j = (await resp.json().catch(() => null)) as { lastOrdinal?: number } | null;
+      const last = j && typeof j.lastOrdinal === "number" ? j.lastOrdinal : null;
+      if (last === null) break; // unparseable reject → full-snapshot fallback
+      if (last >= msgs.length) return last; // server is already ahead of our local view
+      from = last + 1;
+      continue;
+    }
+
+    // 404 = old server without the append route; anything else = unknown failure.
+    // Either way the legacy full-snapshot push is the safe fallback.
+    break;
+  }
+
+  try {
+    const resp = await post(`${base}?agent=${encodeURIComponent(t.agent)}`, t.apiKey, ndjson(msgs), t.timeoutMs);
+    if (!resp.ok) return null;
+    const j = (await resp.json().catch(() => null)) as { version?: number } | null;
+    return j && typeof j.version === "number" ? j.version : msgs.length;
+  } catch {
+    return null;
+  }
+}

package/src/canon.ts

@@ -0,0 +1,128 @@
+// Shared memory-canon fetch + offline cache — the ONE implementation both SessionStart hooks
+// (pull-memory.ts for Claude Code, opencode-plugin.ts for opencode) use, so the injected canon
+// block is byte-identical across agents (spec: agent-wiring, wiring-canon-inject).
+//
+// The server exposes the curated memory index (canon) at
+//   GET {baseUrl}/api/memory/{project}/canon   (header X-Api-Key)
+//   → 200 { "project": {body,updatedAt,version}|null, "workspace": {...}|null }
+// We turn that into a markdown block appended to the session context. On any failure we fall
+// back to a local cache (~/.petbox/cache/{project}.canon.md) written on the last good fetch,
+// marked stale. This is best-effort and TOTAL: every path returns string | null, never throws.
+//
+// NOTE: production may not have this endpoint yet — a 404/error degrades gracefully (no canon
+// block, the memory protocol is still injected by the caller).
+//
+// Plain TS for native node type-stripping: no enum/namespace/parameter-properties, type-only
+// imports, zero deps.
+
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import type { ResolvedProject } from "./registry.ts";
+
+const FETCH_TIMEOUT_MS = 8000;
+
+const STALE_MARKER = "⚠ Canon below is from the local cache (PetBox unreachable) — may be stale.";
+
+type CanonPart = { body?: unknown; updatedAt?: unknown; version?: unknown };
+type CanonResponse = { project?: CanonPart | null; workspace?: CanonPart | null };
+
+function cacheDir(): string {
+  return join(homedir(), ".petbox", "cache");
+}
+
+function cachePath(project: string): string {
+  return join(cacheDir(), `${project}.canon.md`);
+}
+
+// Pull a usable markdown body out of a canon part, or null when the part is missing/empty.
+function partBody(part: CanonPart | null | undefined): string | null {
+  if (!part || typeof part.body !== "string") return null;
+  const body = part.body.trim();
+  return body.length > 0 ? body : null;
+}
+
+// Assemble the canon block from the two parts. Returns null when both are empty.
+function buildBlock(project: string, resp: CanonResponse | null): string | null {
+  if (!resp) return null;
+  const projectBody = partBody(resp.project);
+  const workspaceBody = partBody(resp.workspace);
+  if (projectBody === null && workspaceBody === null) return null;
+
+  let out = `## PetBox memory canon
+
+The curated memory index (canon) for this project — pointers to durable facts; pull full bodies via memory_get/memory_search.`;
+  if (projectBody !== null) {
+    out += `\n\n### Project (${project})\n\n${projectBody}`;
+  }
+  if (workspaceBody !== null) {
+    out += `\n\n### Workspace\n\n${workspaceBody}`;
+  }
+  return out;
+}
+
+// Returns { ok: true, resp } on a successful HTTP fetch (resp may still carry empty canon),
+// or { ok: false } on any failure (404 endpoint-absent / 401 / 5xx / network / timeout / bad
+// JSON) — the caller uses ok to decide whether to fall back to the stale offline cache.
+async function fetchCanon(
+  resolved: ResolvedProject,
+): Promise<{ ok: true; resp: CanonResponse | null } | { ok: false }> {
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), FETCH_TIMEOUT_MS);
+  try {
+    const url = `${resolved.baseUrl}/api/memory/${resolved.project}/canon`;
+    const resp = await fetch(url, {
+      method: "GET",
+      headers: { "X-Api-Key": resolved.apiKey },
+      signal: ctrl.signal,
+    });
+    if (!resp.ok) return { ok: false }; // 404 (endpoint absent) / 401 / 5xx → degrade to cache
+    const j = (await resp.json().catch(() => null)) as CanonResponse | null;
+    return { ok: true, resp: j };
+  } catch {
+    return { ok: false }; // network/timeout → degrade to cache
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function writeCache(project: string, block: string): Promise<void> {
+  try {
+    await mkdir(cacheDir(), { recursive: true });
+    await writeFile(cachePath(project), block, "utf8");
+  } catch {
+    // best-effort: a failed cache write must not affect the returned block
+  }
+}
+
+async function readCache(project: string): Promise<string | null> {
+  try {
+    const body = await readFile(cachePath(project), "utf8");
+    return body.trim().length > 0 ? body : null;
+  } catch {
+    return null; // no cache file yet
+  }
+}
+
+// Build the canon block for a resolved project. On a successful fetch the fresh block is
+// cached and returned; on failure a cached block (if any) is returned PREFIXED with a stale
+// marker. Returns null when there is nothing to show (fetch failed AND no cache, or both
+// canon parts are empty). Never throws.
+export async function fetchCanonBlock(resolved: ResolvedProject): Promise<string | null> {
+  try {
+    const result = await fetchCanon(resolved);
+    if (result.ok) {
+      // Successful fetch — the server is authoritative. A real block is cached and returned;
+      // an empty canon returns null (do NOT show a stale cache when the server says "nothing").
+      const block = buildBlock(resolved.project, result.resp);
+      if (block !== null) await writeCache(resolved.project, block);
+      return block;
+    }
+    // Fetch failed (endpoint absent / unreachable) → fall back to the offline cache if present.
+    const cached = await readCache(resolved.project);
+    if (cached !== null) return `${STALE_MARKER}\n\n${cached}`;
+    return null;
+  } catch {
+    return null; // total: any unexpected error → no canon block
+  }
+}

package/src/droid-pull-memory.ts

@@ -0,0 +1,65 @@
+// Factory Droid SessionStart hook (global) — the droid port of pull-memory.ts.
+//
+// Injects the PetBox memory protocol + curated canon so the agent recalls relevant memory at
+// session start and captures learnings as it works, via the already-connected petbox MCP.
+//
+// Droid names MCP tools `<server>___<tool>` (triple underscore) at runtime — observed live
+// in exec mode; the docs' `mcp__<server>__<tool>` form did not match. The protocol renders
+// with droidPetboxTool (`petbox___*`); the canon block stays byte-identical across agents. Droid's SessionStart stdin
+// is snake_case (`session_id`, `transcript_path`, `cwd`, `source`), the same shape Claude Code
+// uses, so we resolve the project from `cwd` and pass `source` through for the resume nudge.
+//
+// Output contract (docs): a SessionStart hook returns context to the model via the structured
+// JSON `{ hookSpecificOutput: { hookEventName: "SessionStart", additionalContext } }` on stdout
+// (stdout-as-context is also accepted, but the structured form is the documented preference).
+//
+// Best-effort, always exit 0, no output for an unregistered cwd.
+
+import { fetchCanonBlock } from "./canon.ts";
+import { buildProtocol, droidPetboxTool } from "./protocol.ts";
+import { resolveProject } from "./registry.ts";
+
+type HookInput = { cwd?: string; source?: string };
+
+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> {
+  let source = "startup";
+  let cwd = "";
+  try {
+    const raw = await readStdin();
+    const j: HookInput = JSON.parse(raw);
+    if (typeof j.source === "string" && j.source.trim()) source = j.source.trim();
+    if (typeof j.cwd === "string") cwd = j.cwd;
+  } catch {
+    // fall through with defaults; cwd stays empty → resolves to null below
+  }
+
+  try {
+    const resolved = resolveProject(cwd);
+    if (!resolved) return; // not a registered project → no output
+    let context = buildProtocol(resolved.project, droidPetboxTool, { source });
+    // Append the curated memory canon when available (best-effort; degrades to nothing).
+    const canon = await fetchCanonBlock(resolved);
+    if (canon) context += `\n\n${canon}`;
+    const out = {
+      hookSpecificOutput: {
+        hookEventName: "SessionStart",
+        additionalContext: context,
+      },
+    };
+    process.stdout.write(JSON.stringify(out));
+  } catch {
+    // best-effort
+  }
+}
+
+main().finally(() => process.exit(0));

package/src/droid-push-session.ts

@@ -0,0 +1,87 @@
+// Factory Droid Stop hook (global) — the droid port of push-session.ts.
+//
+// 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).
+//
+// Droid's Stop stdin is snake_case (`session_id`, `transcript_path`, `cwd`, `stop_hook_active`)
+// — the same shape Claude Code uses. We parse the droid JSONL (buildDroidMessages: user/
+// assistant TEXT turns only, tool dumps + `<system-reminder>` injections excluded) and push
+// only the INCREMENT via the server-authoritative append cursor (see append.ts): this process
+// is fresh each turn, so it passes null and pushTranscript 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 { buildDroidMessages } from "./droid-transcript.ts";
+import { resolveProject } from "./registry.ts";
+import type { Msg } from "./transcript.ts";
+
+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 (before any file/network work).
+    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 buildDroidMessages(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: "droid",
+        timeoutMs: FETCH_TIMEOUT_MS,
+      },
+      msgs,
+      null,
+    );
+  } catch {
+    // best-effort: never break the user's session
+  }
+}
+
+main().finally(() => process.exit(0));

package/src/droid-transcript.ts

@@ -0,0 +1,47 @@
+// Factory Droid transcript parsing — the droid analogue of transcript.ts, kept as a thin
+// adapter over the SHARED text-extraction/exclusion rules so what a "session turn" is cannot
+// drift between agents (spec: agent-wiring, wiring-single-source).
+//
+// A droid transcript is JSONL, but its record shape differs from Claude Code's:
+//   - line 1 is `{type:"session_start", id, title, cwd, ...}` (skipped);
+//   - each turn is `{type:"message", message:{role, content}}` where content is either a
+//     string or an array of parts `{type:"text"|"thinking"|"tool_use"|"tool_result", ...}`.
+// We keep the user/assistant TEXT turns in order and drop tool_use/tool_result/thinking dumps
+// and harness chrome — reusing extractText (text-parts only) + isExcluded (`<system-reminder>`
+// and friends) from transcript.ts so both agents share one definition. Droid also flags
+// injected context with `visibility:"llm_only"`; we skip those too as a belt-and-suspenders
+// guard alongside the system-reminder prefix check.
+//
+// Plain TS for native node type-stripping: zero deps.
+
+import { createReadStream } from "node:fs";
+import { createInterface } from "node:readline";
+import { extractText, isExcluded, type Msg } from "./transcript.ts";
+
+// Collect the user/assistant text messages in droid transcript order. No rendering and no
+// cap: the server needs the full, ordered transcript to assign stable per-message ordinals.
+export async function buildDroidMessages(transcriptPath: string): Promise<Msg[]> {
+  const rl = createInterface({
+    input: createReadStream(transcriptPath, { encoding: "utf8" }),
+    crlfDelay: Infinity,
+  });
+  const msgs: Msg[] = [];
+  for await (const line of rl) {
+    if (!line || line.trim().length === 0) continue;
+    let e: any;
+    try {
+      e = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    if (e.type !== "message" || !e.message) continue;
+    const role = e.message.role;
+    if (role !== "user" && role !== "assistant") continue;
+    if (e.message.visibility === "llm_only") continue; // injected context, not a real turn
+    const text = extractText(e.message);
+    if (text.length === 0) continue; // thinking/tool_use/tool_result-only turn → no text
+    if (isExcluded(text)) continue; // <system-reminder> / harness chrome
+    msgs.push({ role, content: text });
+  }
+  return msgs;
+}