petbox-wire 0.1.0-ci.1206

package/src/roles.ts

@@ -0,0 +1,241 @@
+// Local role→model binding store (~/.petbox/roles.json).
+//
+// Spec (role-model-binding-local, binding-not-server-authoritative):
+//   - Active profile + per-agent role→model bindings live on the machine (owner axis = $HOME).
+//   - Server may observe a stamp as session metadata later, but is NEVER the source of truth.
+//   - All load/save/resolve paths are offline (no fetch).
+//
+// Plain TS for native node type-stripping: zero deps. Home is injectable so tests never touch
+// the real ~/.petbox.
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+export type RoleBinding = {
+  readonly model: string;
+};
+
+export type AgentRoles = {
+  readonly roles: Readonly<Record<string, RoleBinding>>;
+};
+
+export type Profile = {
+  readonly agents: Readonly<Record<string, AgentRoles>>;
+};
+
+export type RolesFile = {
+  readonly activeProfile: string;
+  readonly profiles: Readonly<Record<string, Profile>>;
+};
+
+/** Best-effort observation stamp for a session push (client-side only until the server accepts it). */
+export type ObservedBinding = {
+  readonly profile: string;
+  readonly agent: string;
+  readonly roles: Readonly<Record<string, string>>;
+};
+
+const EMPTY: RolesFile = { activeProfile: "default", profiles: {} };
+
+/**
+ * Canonical agent ids used by session push / harness matrix (`droid-push-session` stamps
+ * agent:"droid", HARNESS_IDS uses droid).
+ * Aliases accepted in roles.json for the same bucket — lookup is alias-aware so a file
+ * written as `factory-droid` still resolves when push asks for `droid`.
+ */
+export const CANONICAL_AGENT_IDS = ["claude-code", "opencode", "droid"] as const;
+
+const AGENT_ALIASES: Readonly<Record<string, string>> = {
+  "factory-droid": "droid",
+  factory: "droid",
+  cc: "claude-code",
+  claude: "claude-code",
+};
+
+/** Map any alias / known id to the canonical agent id; unknown strings pass through. */
+export function canonicalAgentId(agent: string): string {
+  const a = agent.trim();
+  if (!a) return a;
+  return AGENT_ALIASES[a] ?? a;
+}
+
+/** Keys to try when reading agents{} from roles.json for a requested agent id. */
+function agentLookupKeys(agent: string): readonly string[] {
+  const canon = canonicalAgentId(agent);
+  const keys = new Set<string>([agent, canon]);
+  for (const [alias, c] of Object.entries(AGENT_ALIASES)) {
+    if (c === canon) keys.add(alias);
+  }
+  return [...keys];
+}
+
+export function rolesPath(homeDir: string = homedir()): string {
+  return join(homeDir, ".petbox", "roles.json");
+}
+
+function isPlainObject(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+function asModelBinding(v: unknown): RoleBinding | null {
+  if (!isPlainObject(v)) return null;
+  const model = v["model"];
+  if (typeof model !== "string" || !model.trim()) return null;
+  return { model: model.trim() };
+}
+
+function asAgentRoles(v: unknown): AgentRoles | null {
+  if (!isPlainObject(v)) return null;
+  const rolesRaw = v["roles"];
+  if (!isPlainObject(rolesRaw)) return { roles: {} };
+  const roles: Record<string, RoleBinding> = {};
+  for (const [role, binding] of Object.entries(rolesRaw)) {
+    const b = asModelBinding(binding);
+    if (b) roles[role] = b;
+  }
+  return { roles };
+}
+
+function asProfile(v: unknown): Profile {
+  if (!isPlainObject(v)) return { agents: {} };
+  const agentsRaw = v["agents"];
+  if (!isPlainObject(agentsRaw)) return { agents: {} };
+  const agents: Record<string, AgentRoles> = {};
+  for (const [agent, ar] of Object.entries(agentsRaw)) {
+    const parsed = asAgentRoles(ar);
+    if (parsed) agents[agent] = parsed;
+  }
+  return { agents };
+}
+
+/** Light validation: coerce unknown JSON into a RolesFile; drop junk fields. */
+export function normalizeRoles(raw: unknown): RolesFile {
+  if (!isPlainObject(raw)) return { ...EMPTY };
+  const activeProfile =
+    typeof raw["activeProfile"] === "string" && raw["activeProfile"].trim()
+      ? raw["activeProfile"].trim()
+      : "default";
+  const profilesRaw = raw["profiles"];
+  if (!isPlainObject(profilesRaw)) return { activeProfile, profiles: {} };
+  const profiles: Record<string, Profile> = {};
+  for (const [name, p] of Object.entries(profilesRaw)) {
+    if (!name.trim()) continue;
+    profiles[name] = asProfile(p);
+  }
+  return { activeProfile, profiles };
+}
+
+/**
+ * Load ~/.petbox/roles.json. Never throws: missing/unreadable/invalid → empty shell
+ * ({ activeProfile: "default", profiles: {} }).
+ */
+export function loadRoles(homeDir: string = homedir()): RolesFile {
+  const path = rolesPath(homeDir);
+  try {
+    if (!existsSync(path)) return { ...EMPTY, profiles: {} };
+    const raw = JSON.parse(readFileSync(path, "utf8"));
+    return normalizeRoles(raw);
+  } catch {
+    return { ...EMPTY, profiles: {} };
+  }
+}
+
+/** Persist roles.json (creates ~/.petbox if needed). */
+export function saveRoles(data: RolesFile, homeDir: string = homedir()): void {
+  const path = rolesPath(homeDir);
+  mkdirSync(dirname(path), { recursive: true });
+  const normalized = normalizeRoles(data);
+  writeFileSync(path, JSON.stringify(normalized, null, 2) + "\n", "utf8");
+}
+
+/** True when there is no active profile shell and no agent role bindings at all. */
+export function isEmptyRoles(data: RolesFile): boolean {
+  const names = Object.keys(data.profiles);
+  if (names.length === 0) return true;
+  for (const p of Object.values(data.profiles)) {
+    for (const a of Object.values(p.agents)) {
+      if (Object.keys(a.roles).length > 0) return false;
+    }
+  }
+  // Profiles may exist as empty shells (after `profile use`) — still "empty" for display
+  // of bindings, but we still surface the active profile name.
+  return Object.values(data.profiles).every((p) => Object.keys(p.agents).length === 0);
+}
+
+/**
+ * Set activeProfile; create an empty profile shell if the name is new.
+ * Returns the updated file (caller should saveRoles).
+ */
+export function useProfile(data: RolesFile, name: string): RolesFile {
+  const n = name.trim();
+  if (!n) throw new Error("profile name must be non-empty");
+  const profiles: Record<string, Profile> = { ...data.profiles };
+  if (!profiles[n]) profiles[n] = { agents: {} };
+  return { activeProfile: n, profiles };
+}
+
+/** Role→model map for one agent under the active profile (missing → {}). Alias-aware. */
+export function resolveAgentRoles(
+  data: RolesFile,
+  agent: string,
+): Readonly<Record<string, string>> {
+  const profile = data.profiles[data.activeProfile];
+  if (!profile) return {};
+  // Prefer exact key, then aliases / canonical (first non-empty wins).
+  for (const key of agentLookupKeys(agent)) {
+    const ar = profile.agents[key];
+    if (!ar) continue;
+    const out: Record<string, string> = {};
+    for (const [role, b] of Object.entries(ar.roles)) out[role] = b.model;
+    if (Object.keys(out).length > 0) return out;
+  }
+  return {};
+}
+
+/**
+ * Pure client helper: observed binding stamp for session metadata.
+ * Returns null when the active profile has no roles for this agent (do not invent defaults).
+ * `agent` on the stamp is always the **canonical** id (e.g. droid, not factory-droid).
+ */
+export function resolveObservedBinding(
+  agent: string,
+  homeDir: string = homedir(),
+): ObservedBinding | null {
+  const data = loadRoles(homeDir);
+  const roles = resolveAgentRoles(data, agent);
+  if (Object.keys(roles).length === 0) return null;
+  return {
+    profile: data.activeProfile,
+    agent: canonicalAgentId(agent),
+    roles,
+  };
+}
+
+/** Bootstrap-safe export shape (no secrets — roles.json has none). */
+export function exportRolesBootstrap(data: RolesFile): RolesFile {
+  return normalizeRoles(data);
+}
+
+/** Human-readable dump of the active profile's agent/role/model tree. */
+export function formatResolvedBinding(data: RolesFile): string {
+  const lines: string[] = [];
+  lines.push(`activeProfile: ${data.activeProfile}`);
+  const profile = data.profiles[data.activeProfile];
+  if (!profile || Object.keys(profile.agents).length === 0) {
+    lines.push("(no agent role bindings for this profile)");
+    return lines.join("\n");
+  }
+  for (const [agent, ar] of Object.entries(profile.agents)) {
+    lines.push(`  ${agent}:`);
+    const roleEntries = Object.entries(ar.roles);
+    if (roleEntries.length === 0) {
+      lines.push("    (no roles)");
+      continue;
+    }
+    for (const [role, binding] of roleEntries) {
+      lines.push(`    ${role}: ${binding.model}`);
+    }
+  }
+  return lines.join("\n");
+}

package/src/self-smoke.test.ts

@@ -0,0 +1,103 @@
+// Unit tests for self-smoke classification and the final-line policy
+// (bug: selfsmoke-failure-prints-done — a failed self-smoke must never be followed by "done.").
+//
+// Run: node --test src/self-smoke.test.ts
+
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { classifySelfSmokeResponse, finishWireRun } from "./self-smoke.ts";
+
+// ---- classifySelfSmokeResponse ----
+
+test("classifySelfSmokeResponse: non-OK HTTP status is a failure", () => {
+  const r = classifySelfSmokeResponse(false, 500, "internal error");
+  assert.equal(r.ok, false);
+  assert.match(r.message, /HTTP 500/);
+  assert.match(r.message, /internal error/);
+});
+
+test("classifySelfSmokeResponse: 200 with a numeric version is success", () => {
+  const r = classifySelfSmokeResponse(
+    true,
+    200,
+    JSON.stringify({ sessionId: "s1", version: 3, messageCount: 1 }),
+  );
+  assert.equal(r.ok, true);
+  assert.match(r.message, /OK/);
+  assert.match(r.message, /sessionId=s1/);
+  assert.match(r.message, /version=3/);
+});
+
+test("classifySelfSmokeResponse: 200 with non-JSON body is a failure", () => {
+  const r = classifySelfSmokeResponse(true, 200, "not json");
+  assert.equal(r.ok, false);
+  assert.match(r.message, /did not return a numeric version/);
+});
+
+test("classifySelfSmokeResponse: 200 with JSON but no numeric version is a failure", () => {
+  const r = classifySelfSmokeResponse(true, 200, JSON.stringify({ sessionId: "s1" }));
+  assert.equal(r.ok, false);
+  assert.match(r.message, /did not return a numeric version/);
+});
+
+// ---- finishWireRun ----
+
+test("finishWireRun: failed smoke suppresses 'done.' entirely and goes to stderr", () => {
+  const f = finishWireRun({
+    smokeOk: false,
+    envVar: "PETBOX_X_API_KEY",
+    envVarPresentInProcess: true,
+    platform: "linux",
+  });
+  assert.equal(f.printDone, false);
+  assert.equal(f.toStderr, true);
+  assert.ok(f.lines.length > 0);
+  for (const line of f.lines) {
+    assert.doesNotMatch(line, /^done\.?/, "no line may read like the success banner");
+  }
+  // The literal regression this bug reported: "done." must not appear anywhere in the failure output.
+  assert.ok(!f.lines.join("\n").includes("done."));
+});
+
+test("finishWireRun: successful smoke + env var already present prints exactly 'done.'", () => {
+  const f = finishWireRun({
+    smokeOk: true,
+    envVar: "PETBOX_X_API_KEY",
+    envVarPresentInProcess: true,
+    platform: "linux",
+  });
+  assert.equal(f.printDone, true);
+  assert.equal(f.toStderr, false);
+  assert.deepEqual(f.lines, ["done."]);
+});
+
+test("finishWireRun: successful smoke without the env var in-process adds the new-terminal NOTE, still to stdout", () => {
+  const f = finishWireRun({
+    smokeOk: true,
+    envVar: "PETBOX_X_API_KEY",
+    envVarPresentInProcess: false,
+    platform: "win32",
+  });
+  assert.equal(f.printDone, true);
+  assert.equal(f.toStderr, false);
+  assert.equal(f.lines.length, 1);
+  const [line] = f.lines;
+  assert.ok(line, "finishWireRun must produce exactly one line here");
+  assert.match(line, /^done\. NOTE:/);
+  assert.match(line, /PETBOX_X_API_KEY/);
+  // win32 branch omits "(login shell)"
+  assert.doesNotMatch(line, /login shell/);
+});
+
+test("finishWireRun: POSIX platform's NOTE mentions the login shell", () => {
+  const f = finishWireRun({
+    smokeOk: true,
+    envVar: "PETBOX_X_API_KEY",
+    envVarPresentInProcess: false,
+    platform: "linux",
+  });
+  assert.equal(f.lines.length, 1);
+  const [line] = f.lines;
+  assert.ok(line, "finishWireRun must produce exactly one line here");
+  assert.match(line, /login shell/);
+});

package/src/self-smoke.ts

@@ -0,0 +1,96 @@
+// Self-smoke response classification + final-line policy for wire's full-wiring path
+// (wiring-one-command / selfsmoke-failure-prints-done).
+//
+// Kept out of wire.ts (whose main() runs at import time, so decision logic that needs to be
+// unit-testable in isolation lives in a side module — same pattern as wire-exit.ts,
+// wire-identity.ts, apply-write.ts).
+//
+// The bug: selfSmoke() set process.exitCode = 1 on failure, but main() kept going to the very
+// end of the wiring pipeline and printed "done." regardless — a failed self-smoke was visually
+// indistinguishable from a clean wire (the LAST line a human sees was always "done."). This
+// module makes the terminal message set depend on the smoke outcome, so a failure IS the last
+// line, printed to stderr (red), and "done." never follows it.
+
+/** Pure classification of the self-smoke HTTP round trip — no network, no process state. */
+export type SelfSmokeResult = {
+  readonly ok: boolean;
+  /** Human-facing [10/10] line. Goes to stdout when ok, stderr when not. */
+  readonly message: string;
+};
+
+/**
+ * Classify a self-smoke response. `ok`/`status` mirror fetch's Response; `text` is the already
+ * -read body (caller owns the fetch/timeout/network-error handling — those are fetch failures,
+ * not response classification, and are handled by the caller before this is ever invoked).
+ */
+export function classifySelfSmokeResponse(
+  respOk: boolean,
+  status: number,
+  text: string,
+): SelfSmokeResult {
+  if (!respOk) {
+    return { ok: false, message: `[10/10] self-smoke: HTTP ${status} — ${text}` };
+  }
+  let parsed: any = null;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    /* keep raw */
+  }
+  if (typeof parsed?.version === "number") {
+    return {
+      ok: true,
+      message:
+        `[10/10] self-smoke: OK — sessionId=${parsed.sessionId}, version=${parsed.version}, ` +
+        `messages=${parsed.messageCount}`,
+    };
+  }
+  return {
+    ok: false,
+    message: `[10/10] self-smoke: server did not return a numeric version — ${text}`,
+  };
+}
+
+/** What main() prints as its LAST lines, and where (stdout vs stderr). */
+export type FinishOutcome = {
+  readonly lines: readonly string[];
+  /** True → every line goes to console.error (red); false → console.log. */
+  readonly toStderr: boolean;
+  /** False when self-smoke failed — "done." must never be the trailing line of a failed run. */
+  readonly printDone: boolean;
+};
+
+/**
+ * Decide wire's terminal message set. `smokeOk` false is the ONLY branch that suppresses
+ * "done." — steps 1-9 having completed does not make the run "done" when the last barrier
+ * (self-smoke) failed.
+ */
+export function finishWireRun(opts: {
+  readonly smokeOk: boolean;
+  readonly envVar: string;
+  readonly envVarPresentInProcess: boolean;
+  readonly platform: NodeJS.Platform;
+}): FinishOutcome {
+  if (!opts.smokeOk) {
+    return {
+      printDone: false,
+      toStderr: true,
+      lines: [
+        `wire: self-smoke FAILED (see [10/10] above) — steps 1-9 completed but the wiring is ` +
+          `UNVERIFIED. Treat this run as failed, not finished; exit code is non-zero.`,
+      ],
+    };
+  }
+  if (opts.envVarPresentInProcess) {
+    return { printDone: true, toStderr: false, lines: ["done."] };
+  }
+  return {
+    printDone: true,
+    toStderr: false,
+    lines: [
+      `done. NOTE: start a NEW terminal${opts.platform === "win32" ? "" : " (login shell)"} before ` +
+        `launching agents — their MCP configs read ${opts.envVar} from the environment. The kit ` +
+        `hooks work immediately (keys.json).`,
+    ],
+  };
+}

package/src/telemetry-settings.test.ts

@@ -0,0 +1,65 @@
+// Regression tests for the --telemetry OTLP export env (work telemetry-otlp-auth-401): the auth
+// header MUST carry the RESOLVED api key and the exact header NAME the server validates, never a
+// literal `${VAR}` placeholder (Claude Code does not expand `${VAR}` in settings.json `env`, so a
+// placeholder is sent verbatim and the OTLP ingest returns 401).
+//
+// Run: node --test src/telemetry-settings.test.ts
+
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import {
+  buildTelemetryOtlpEnv,
+  OTLP_API_KEY_HEADER,
+  OTLP_SERVICE_KEY_HEADER,
+  OTLP_SERVICE_KEY_VALUE,
+} from "./telemetry-settings.ts";
+
+const BASE = "https://petbox.example";
+const PROJECT = "acme";
+const LOG = "cc-telemetry";
+const KEY = "pk_live_RESOLVED_SECRET_123";
+
+test("OTLP headers carry the RESOLVED key value, never a ${...} placeholder", () => {
+  const { secretEnv } = buildTelemetryOtlpEnv(BASE, PROJECT, KEY, LOG);
+  const headers = secretEnv["OTEL_EXPORTER_OTLP_HEADERS"];
+  assert.ok(headers, "OTEL_EXPORTER_OTLP_HEADERS must be present");
+  assert.ok(headers.includes(KEY), "header must contain the resolved key value");
+  assert.ok(!headers.includes("${"), `header must not contain a \${...} placeholder — got: ${headers}`);
+  assert.ok(!/\{env:/.test(headers), "header must not contain an {env:...} reference");
+});
+
+test("auth header uses the exact name the server's ApiKey scheme validates (X-Api-Key)", () => {
+  const { secretEnv } = buildTelemetryOtlpEnv(BASE, PROJECT, KEY, LOG);
+  const headers = secretEnv["OTEL_EXPORTER_OTLP_HEADERS"];
+  assert.ok(headers, "OTEL_EXPORTER_OTLP_HEADERS must be present");
+  assert.equal(OTLP_API_KEY_HEADER, "X-Api-Key");
+  assert.ok(
+    headers.includes(`${OTLP_API_KEY_HEADER}=${KEY}`),
+    `expected "X-Api-Key=<key>" pair — got: ${headers}`,
+  );
+  // Must NOT use the bare self-export routes' shared-secret header (those routes aren't targeted).
+  assert.ok(!/X-Seq-ApiKey/i.test(headers), "must not use X-Seq-ApiKey (wrong route's auth header)");
+});
+
+test("service-key header pair is present (IngestLogs 400s without X-Service-Key)", () => {
+  const { secretEnv } = buildTelemetryOtlpEnv(BASE, PROJECT, KEY, LOG);
+  const headers = secretEnv["OTEL_EXPORTER_OTLP_HEADERS"];
+  assert.ok(headers, "OTEL_EXPORTER_OTLP_HEADERS must be present");
+  assert.ok(
+    headers.includes(`${OTLP_SERVICE_KEY_HEADER}=${OTLP_SERVICE_KEY_VALUE}`),
+    "X-Service-Key=claude-code pair must be present",
+  );
+});
+
+test("the secret (key-bearing) env is split out from the committable public env", () => {
+  const { publicEnv, secretEnv } = buildTelemetryOtlpEnv(BASE, PROJECT, KEY, LOG);
+  // The key must live only in the secret env (destined for gitignored settings.local.json).
+  assert.ok(!JSON.stringify(publicEnv).includes(KEY), "public env must never contain the api key");
+  assert.ok(Object.keys(secretEnv).length === 1, "secret env carries only the auth header");
+});
+
+test("endpoints are the path-based routes (project + log in the URL path)", () => {
+  const { publicEnv } = buildTelemetryOtlpEnv(BASE, PROJECT, KEY, LOG);
+  assert.equal(publicEnv["OTEL_EXPORTER_OTLP_METRICS_ENDPOINT"], `${BASE}/v1/metrics/${PROJECT}/${LOG}`);
+  assert.equal(publicEnv["OTEL_EXPORTER_OTLP_LOGS_ENDPOINT"], `${BASE}/v1/logs/${PROJECT}/${LOG}`);
+});

package/src/telemetry-settings.ts

@@ -0,0 +1,55 @@
+// The OTLP export env that `--telemetry` writes into Claude Code's settings, extracted into its
+// own importable module (wire.ts runs main() at module top level and must never be imported by a
+// test — same reason posix-env.ts exists). The env-string building here is the load-bearing,
+// regression-prone part: it must emit a RESOLVED api key and the exact auth header the server
+// validates. wire.ts owns the file-merge glue (mergeEnvIntoSettings) and calls this.
+
+// Auth header the PetBox path-based OTLP routes (/v1/{signal}/{project}/{log}) validate. Those
+// routes use RequireAuthorization("ApiKey"), and the ApiKey scheme reads X-Api-Key
+// (PetBox.Core/Auth/ApiKeyAuthenticationHandler.cs: ApiKeyHeader = "X-Api-Key"). This is NOT the
+// bare self-export routes' X-Seq-ApiKey (those are AllowAnonymous + a shared self-log secret and
+// are not what telemetry targets), so X-Api-Key is the correct name here.
+export const OTLP_API_KEY_HEADER = "X-Api-Key";
+// IngestLogs additionally requires a non-empty X-Service-Key header (400 otherwise); it only tags
+// the emitter (free string, no Service entity).
+export const OTLP_SERVICE_KEY_HEADER = "X-Service-Key";
+export const OTLP_SERVICE_KEY_VALUE = "claude-code";
+
+export interface TelemetryOtlpEnv {
+  // Non-secret export config → committable .claude/settings.json.
+  publicEnv: Record<string, string>;
+  // API-key-bearing header → gitignored .claude/settings.local.json.
+  secretEnv: Record<string, string>;
+}
+
+// Build the OTLP export env split by secrecy.
+//
+// The api key is written RESOLVED (the literal key value), NOT as a `${VAR}` reference: Claude Code
+// does NOT expand `${VAR}` inside settings.json `env` values (unlike .mcp.json) — empirically
+// verified 2026-07-06 — so a reference form would send the literal string `${VAR}` and the OTLP
+// ingest returns 401. Tradeoff: a literal key PINS the value, so if the project api key rotates the
+// header goes stale — re-run wire (--telemetry) to re-provision. The key already lives plaintext in
+// ~/.petbox/keys.json; settings.local.json (gitignored) is the same trust boundary, per-project.
+export function buildTelemetryOtlpEnv(
+  baseUrl: string,
+  project: string,
+  key: string,
+  logName: string,
+): TelemetryOtlpEnv {
+  const metricsEndpoint = `${baseUrl}/v1/metrics/${project}/${logName}`;
+  const logsEndpoint = `${baseUrl}/v1/logs/${project}/${logName}`;
+  const publicEnv: Record<string, string> = {
+    CLAUDE_CODE_ENABLE_TELEMETRY: "1",
+    OTEL_METRICS_EXPORTER: "otlp",
+    OTEL_LOGS_EXPORTER: "otlp",
+    OTEL_EXPORTER_OTLP_PROTOCOL: "http/protobuf",
+    OTEL_EXPORTER_OTLP_METRICS_ENDPOINT: metricsEndpoint,
+    OTEL_EXPORTER_OTLP_LOGS_ENDPOINT: logsEndpoint,
+    OTEL_METRIC_EXPORT_INTERVAL: "5000",
+  };
+  const secretEnv: Record<string, string> = {
+    // OTLP header list format: comma-separated key=value pairs. Resolved key, correct header name.
+    OTEL_EXPORTER_OTLP_HEADERS: `${OTLP_API_KEY_HEADER}=${key},${OTLP_SERVICE_KEY_HEADER}=${OTLP_SERVICE_KEY_VALUE}`,
+  };
+  return { publicEnv, secretEnv };
+}

package/src/templates/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: petbox
+description: Shared task boards, memory and session plans for this project via the PetBox MCP server (server name `petbox`). Use to record/read plans, durable notes and working-session state for {{PROJECT}} development.
+---
+
+This project is connected to a PetBox instance over MCP (server `petbox`, https://petbox.3po.su).
+Pass projectKey "{{PROJECT}}" in every call (the key is scoped to the {{PROJECT}} project;
+boards/memory/sessions live at https://petbox.3po.su/ui/{{WORKSPACE}}/{{PROJECT}}).
+
+**Tool naming:** the base verbs are underscore-delimited (`tasks_upsert`, `memory_search`, …).
+In opencode the MCP tools are `petbox_<verb>` (e.g. `petbox_tasks_upsert`, `petbox_memory_search`);
+in Claude Code they are `mcp__petbox__<verb>`. Just prefix the base verb per runtime.
+
+**Plan nodes are FLAT slugs** (`key` = [a-z][a-z0-9_-]*); hierarchy is the `partOf` edge,
+grouping is `tags` (`area:*` / `concern:*`). Give each node a short `title` and a markdown
+`body`. A cold `tasks_upsert` auto-creates the board. The upsert response is a pure ack for
+YOUR call (added/updated/removed cover only your nodes); to catch up on everyone's changes
+call `tasks_delta` with `sinceVersion` = a previous `currentVersion`. `nodes`/`entries` are
+TYPED arrays — pass real JSON arrays, not stringified JSON.
+
+**`tasks_search` is THE read verb** — two modes: without `q` it's a deterministic LISTING
+(pass `board` for one board, omit for the whole project; default order priority-then-key),
+with `q` it's hybrid relevance search (FTS ⊕ vectors). Filters work in both modes:
+`status[]`, `keys[]` (slug|NodeId), `under` (subtree), `includeClosed`; `sort{by,desc}`
+reorders; `bodyLen` snippets bodies. One node in full: `tasks_node_get`.
+
+**Memory entries are typed** (`user` | `feedback` | `project` | `reference`) — `type` is
+required on `memory_upsert`; `tags` is an ARRAY of strings ([] clears, omit keeps).
+`memory_search` is THE read verb: with `q`
+a hybrid relevance search (FTS ⊕ vectors), without `q` a deterministic listing (updated
+desc); no `scope` cascades project ⊕ workspace over every store (use `bodyLen` for snippets).
+
+**What goes where:**
+- Session (`session_*`) — the current working plan/thinking. "Stale next week?" → session.
+- Tasks (`tasks_*`) — a unit of work with a status tracked to Done.
+- Memory (`memory_*`) — a durable fact that should outlive the work. Don't store what
+  code/git already records, transient state, secrets, or actionable work (that's a task).
+
+**Tools:**
+- `tasks_board_list / board_create / board_delete / search / node_get / upsert / delta / workflow`
+- `memory_store_list / store_create / store_delete / search / remember / get / upsert / delta`
+- `session_search / get / upsert / append / delete` (`search` without `q` = the session listing; with `q` = two-stage archive search whose hits carry message ordinals for `session_get`)
+- Logs: `log_query` (KQL), `log_create / list / delete`
+- Admin (per-type, flat params): `project_create / list`, `apikey_create / list / delete`,
+  `db_create / list / delete / describe`

package/src/templates/agent-factory/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: petbox-agent-factory
+description: On-demand compile of per-harness agent artifacts from portable PetBox definitions + local role→model bindings. Use after role/profile changes — not every session; never invent models; never put this procedure into canon.
+---
+
+# Agent factory (on-demand skill)
+
+Factory is an **on-demand skill**, not session canon. Run it when definitions or local
+bindings change; do **not** re-run every session and do **not** paste this procedure into
+hooks, protocol, or memory canon.
+
+## Axis
+
+| What | Where |
+| --- | --- |
+| Portable definition | PetBox (`agent_def_*` / REST agent-defs) — roles/capabilities, **no models** |
+| Local binding | `~/.petbox/roles.json` (owner = `$HOME`) — profile → role → **model** only |
+| Compiled artifacts | Per-harness agent files written by `apply` |
+
+Never invent a model id. If a role has no binding, leave model unset and report it.
+Owner axis is `$HOME`; definitions are portable across machines, models are not.
+
+## Procedure
+
+1. Inspect / switch local binding as needed:
+   ```bash
+   npx petbox-wire roles
+   npx petbox-wire profile use <name>
+   ```
+2. Gate:
+   ```bash
+   npx petbox-wire doctor
+   ```
+   Doctor reports truthfulness violations (role + capability + harness). Exit 1 on failure — fix before apply.
+3. Materialize:
+   ```bash
+   npx petbox-wire apply
+   ```
+   Apply writes per-harness agent files from the definition + local binding; `model:` only when bound. Any harness violation blocks all writes.
+
+## Do not confuse with `update`
+
+| Command | Effect |
+| --- | --- |
+| `npx petbox-wire apply` | Compile per-harness agent artifacts from definition + binding |
+| `npx petbox-wire update` | Refresh only the stable kit under `~/.petbox/wire/` (hooks/scripts/templates) |
+
+`update` does **not** rebuild agent artifacts. After a kit-text change that includes this
+skill template, re-run a **full wire** to reinstall skill files into the project.
+
+## Boundaries
+
+- Factory procedure stays in this skill — not in `protocol.ts`, SessionStart canon, or AGENTS.md.
+- Portable defs ship without models; local `roles.json` is the only model source.
+- Prefer reporting missing bindings over inventing them.
+- Not canon; on-demand only.