petbox-wire 0.1.0-ci.1206

package/src/append-meta.test.ts

@@ -0,0 +1,93 @@
+// Unit tests for the observed role-binding session-meta header helper (append.ts).
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync, writeFileSync, mkdirSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { test } from "node:test";
+import { buildSessionMetaHeader } from "./append.ts";
+
+function freshHome(): string {
+  const home = mkdtempSync(join(tmpdir(), "petbox-append-meta-"));
+  mkdirSync(join(home, ".petbox"), { recursive: true });
+  return home;
+}
+
+test("buildSessionMetaHeader returns null when no roles for agent", () => {
+  const home = freshHome();
+  try {
+    assert.equal(buildSessionMetaHeader("claude-code", home), null);
+  } finally {
+    rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test("buildSessionMetaHeader wraps resolveObservedBinding as roleBinding", () => {
+  const home = freshHome();
+  try {
+    writeFileSync(
+      join(home, ".petbox", "roles.json"),
+      JSON.stringify({
+        activeProfile: "default",
+        profiles: {
+          default: {
+            agents: {
+              "claude-code": {
+                roles: {
+                  orchestrator: { model: "claude-opus-4" },
+                  worker: { model: "claude-sonnet-4" },
+                },
+              },
+            },
+          },
+        },
+      }),
+    );
+    const raw = buildSessionMetaHeader("claude-code", home);
+    assert.ok(raw);
+    assert.deepEqual(JSON.parse(raw!), {
+      roleBinding: {
+        profile: "default",
+        agent: "claude-code",
+        roles: {
+          orchestrator: "claude-opus-4",
+          worker: "claude-sonnet-4",
+        },
+      },
+    });
+  } finally {
+    rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test("buildSessionMetaHeader: droid push finds factory-droid roles bucket", () => {
+  const home = freshHome();
+  try {
+    writeFileSync(
+      join(home, ".petbox", "roles.json"),
+      JSON.stringify({
+        activeProfile: "default",
+        profiles: {
+          default: {
+            agents: {
+              "factory-droid": {
+                roles: { orchestrator: { model: "deepseek-v4-pro" } },
+              },
+            },
+          },
+        },
+      }),
+    );
+    // droid-push-session.ts uses agent: "droid"
+    const raw = buildSessionMetaHeader("droid", home);
+    assert.ok(raw);
+    assert.deepEqual(JSON.parse(raw!), {
+      roleBinding: {
+        profile: "default",
+        agent: "droid",
+        roles: { orchestrator: "deepseek-v4-pro" },
+      },
+    });
+  } finally {
+    rmSync(home, { recursive: true, force: true });
+  }
+});

package/src/append.ts

@@ -0,0 +1,172 @@
+// 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.
+//
+// Observed role binding (binding-not-server-authoritative): when ~/.petbox/roles.json has
+// roles for the agent, stamp X-PetBox-Session-Meta with { roleBinding }. Best-effort —
+// missing roles.json never fails the push. Server stores as session MetaJson observation
+// only; local roles.json remains the source of truth.
+//
+// Plain TS for native node type-stripping: zero deps.
+
+import { resolveObservedBinding } from "./roles.ts";
+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;
+};
+
+/**
+ * Pure helper: JSON for X-PetBox-Session-Meta, or null when no local binding / any error.
+ * Shape: { roleBinding: { profile, agent, roles: { role: model } } }
+ */
+export function buildSessionMetaHeader(
+  agent: string,
+  homeDir?: string,
+): string | null {
+  try {
+    const obs =
+      homeDir === undefined
+        ? resolveObservedBinding(agent)
+        : resolveObservedBinding(agent, homeDir);
+    if (!obs) return null;
+    return JSON.stringify({ roleBinding: obs });
+  } catch {
+    return null;
+  }
+}
+
+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,
+  metaHeader: string | null,
+): Promise<Response> {
+  const headers: Record<string, string> = {
+    "X-Api-Key": apiKey,
+    "Content-Type": "application/x-ndjson; charset=utf-8",
+    // Connection: close — no lingering keep-alive socket after this short-lived hook
+    // process's request (see canon.ts's fetchCanon for the full rationale).
+    Connection: "close",
+  };
+  if (metaHeader) headers["X-PetBox-Session-Meta"] = metaHeader;
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), timeoutMs);
+  try {
+    return await fetch(url, {
+      method: "POST",
+      headers,
+      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)}`;
+  // Stamp observed binding once per push; never let roles.json issues fail the transcript.
+  const metaHeader = buildSessionMetaHeader(t.agent);
+
+  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,
+        metaHeader,
+      );
+    } 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,
+      metaHeader,
+    );
+    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/apply-artifacts.ts

@@ -0,0 +1,337 @@
+// Pure compile helpers for petbox-wire apply (per-harness-artifact).
+//
+// planApply produces agent role files for any known harness.
+// Per-role truthfulness: clean roles are emitted; dirty roles are skipped and
+// reported in violations/skippedRoles (never silently drop a required line from
+// a role that is emitted — the whole dirty role is blocked). "Dirty" covers BOTH
+// a missing harness capability AND a local model binding that looks like ANOTHER
+// harness's id shape (harness-models.ts's "foreign" tier) — writing that in would be
+// either rejected loudly by the target harness at runtime or silently satisfy a
+// different harness's config, not this one. A model that is merely unrecognized-but-
+// shape-valid (harness-models.ts's "unknown" tier — e.g. a real `claude-*` id newer
+// than the kit's small known-alias list) is NOT dirty: it is written, with a warning
+// (see ApplyPlan.warnings / modelShapeWarning in truthfulness.ts).
+//
+// Paths (documented harness layouts):
+//   opencode     → .opencode/agent/<role>.md
+//   claude-code  → .claude/agents/<role>.md
+//   droid        → .factory/droids/<name>.md  (Factory custom droids; project level)
+//     https://docs.factory.ai/cli/configuration/custom-droids
+//
+// model: from local roles.json binding when present; droid unbound → model: inherit
+// (Factory default). Never invent a concrete model id.
+//
+// Plain TS for native node type-stripping: zero deps.
+
+import { join } from "node:path";
+import { emittedRoleName, type AgentDefinition, type AgentRole } from "./agent-definition.ts";
+import { isKnownHarness, type HarnessId } from "./harness-capabilities.ts";
+import { PETBOX_MARKER_LINE } from "./origin-marker.ts";
+import {
+  checkRoleTruthfulness,
+  formatViolations,
+  modelShapeWarning,
+  type TruthfulnessViolation,
+} from "./truthfulness.ts";
+
+/**
+ * Factory custom-droid name sanitizer: lowercase/digits/-/_ only (Factory DroidValidator —
+ * see renderDroidMarkdown below). Shared by renderDroidMarkdown (frontmatter `name:`) and
+ * planApply (the emitted/legacy droid file basenames) so the two can never drift apart.
+ */
+export function sanitizeDroidName(name: string): string {
+  return name
+    .toLowerCase()
+    .replace(/[^a-z0-9_-]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+}
+
+export type PlannedFile = {
+  readonly relativePath: string;
+  readonly content: string;
+  /**
+   * Where this role's file lived BEFORE namespacing (bare `role.slug`, no `petbox-` prefix),
+   * relative to the harness root — same convention as relativePath. apply's writer
+   * (apply-write.ts's cleanupLegacyArtifact) uses this to find and remove an old file we own;
+   * it is a no-op when nothing sits there, and it NEVER touches a path that lacks our origin
+   * marker (chore: petbox-namespaced-agent-names). Always distinct from relativePath — every
+   * role is namespaced now.
+   */
+  readonly legacyRelativePath: string;
+};
+
+export type ApplyPlan = {
+  readonly harness: string;
+  readonly files: readonly PlannedFile[];
+  /** Truthfulness violations (capability or model) for roles that were NOT written. */
+  readonly violations: readonly TruthfulnessViolation[];
+  /** Role slugs skipped because of violations. */
+  readonly skippedRoles: readonly string[];
+  /**
+   * Non-blocking notices, two kinds:
+   *  - A role with NO local model binding is written without a model key (claude-code/opencode)
+   *    or with `model: inherit` (droid) — legitimate, but it means the agent runs on the
+   *    session/parent model. Warn so that is a choice, not a surprise.
+   *  - A role bound to a model that classifies "unknown" (harness-models.ts) — shape-valid for
+   *    the harness, just not on its small known-alias list — is written as bound, unverified.
+   * A role bound to a "foreign"-shaped id is NOT a warning — it is a violation (see violations).
+   */
+  readonly warnings: readonly string[];
+};
+
+/** Relative dir (posix) for agent role files per harness. */
+export function agentFilesDir(harness: HarnessId): string {
+  switch (harness) {
+    case "opencode":
+      return ".opencode/agent";
+    case "claude-code":
+      return ".claude/agents";
+    case "droid":
+      // Factory custom droids — project level only (org-locked settings are out of scope).
+      // https://docs.factory.ai/cli/configuration/custom-droids
+      return ".factory/droids";
+  }
+}
+
+/** Shared role body (spawn / escalation / caps / notes). No protocol inject here. */
+export function buildRoleBody(role: AgentRole): string {
+  const lines: string[] = [];
+  lines.push(`# ${emittedRoleName(role)}`);
+  lines.push("");
+  lines.push(`Tier: \`${role.tier}\``);
+  lines.push("");
+
+  if (role.notes) {
+    lines.push(role.notes);
+    lines.push("");
+  }
+
+  const caps = role.requiredCapabilities;
+  lines.push("## Required capabilities");
+  if (caps.length === 0) {
+    lines.push("- (none declared — role is harness-portable with no capability gate)");
+  } else {
+    for (const c of caps) lines.push(`- \`${c}\``);
+  }
+  lines.push("");
+
+  // Both lists below NAME SPAWN/ESCALATION TARGETS — the literal subagent_type / handoff-role
+  // string another role would use. They MUST render the same namespaced identity the target
+  // role's own file is emitted under (emittedRoleName), never the bare internal role.slug —
+  // otherwise a generated file would point at a subagent_type that does not exist on disk
+  // (chore: petbox-namespaced-agent-names, "prose naming a spawn type renders the computed
+  // name, never a constant/bare slug").
+  lines.push("## Spawn");
+  if (role.spawn?.allowed) {
+    const allowed = role.spawn.allowedRoles?.length
+      ? role.spawn.allowedRoles.map((r) => `\`${emittedRoleName(r)}\``).join(", ")
+      : "(any)";
+    lines.push(`- Allowed. Target roles: ${allowed}.`);
+  } else {
+    lines.push(
+      "- Not allowed. This is a leaf role: you MUST NOT spawn subagents " +
+        "(no Agent/Task/spawn tool use of any kind), regardless of what tools the " +
+        "harness makes available to this session.",
+    );
+  }
+  lines.push("");
+
+  lines.push("## Escalation");
+  if (role.escalation?.available) {
+    const targets = role.escalation.targets?.length
+      ? role.escalation.targets.map((t) => `\`${emittedRoleName(t)}\``).join(", ")
+      : "(unspecified)";
+    lines.push(`- Available → ${targets}.`);
+  } else {
+    lines.push("- Not available.");
+  }
+  lines.push("");
+
+  if (role.slug === "explore") {
+    lines.push("## Model inheritance");
+    lines.push(
+      "On harnesses that declare `builtin_explore_inherits_model`, inheritance is the harness default. " +
+        "Do not treat inheritance as a protocol violation for this role.",
+    );
+    lines.push("");
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * Claude Code / opencode agent markdown (YAML frontmatter + body).
+ * name: <emittedRoleName(role)> is the required first key — without it Claude Code will not
+ * register the file as an agent at all (mirrors renderDroidMarkdown's `name:`). Namespaced
+ * (`petbox-<slug>`), not the bare role.slug — see agent-definition.ts's emittedRoleName.
+ * model only when bound — never invent a model id.
+ * No `tools:` key: omitting it means the agent inherits the harness's full tool
+ * set, including MCP — that is the intended policy (see harness-capabilities.ts).
+ * Every generated file carries PETBOX_MARKER_LINE in its frontmatter (origin-marker.ts) —
+ * the ONLY thing apply's write guard trusts to tell "ours" from a real user file.
+ */
+export function renderAgentMarkdown(role: AgentRole, model?: string): string {
+  const frontLines: string[] = [`name: ${emittedRoleName(role)}`];
+  if (model && model.trim()) {
+    frontLines.push(`model: ${model.trim()}`);
+  }
+  frontLines.push(`description: PetBox ${role.tier} role (${emittedRoleName(role)})`);
+  frontLines.push(PETBOX_MARKER_LINE);
+
+  const body = buildRoleBody(role);
+  return `---\n${frontLines.join("\n")}\n---\n\n${body.endsWith("\n") ? body : body + "\n"}`;
+}
+
+/**
+ * Factory custom droid markdown.
+ * Docs: https://docs.factory.ai/cli/configuration/custom-droids
+ * Frontmatter: name (required), description, model (inherit | explicit), optional
+ * reasoningEffort / tools / mcpServers. Body = system prompt.
+ * name: sanitizeDroidName(emittedRoleName(role)) — namespaced first, THEN sanitized, so the
+ * `petbox-` prefix survives Factory's DroidValidator (`[a-z0-9_-]` only) the same way it
+ * does on claude-code/opencode.
+ * model: bound value from roles.json, else `inherit` (Factory default — not an invented id).
+ * mcpServers: petbox when the role requires MCP (main or subagent surface).
+ * Carries PETBOX_MARKER_LINE, same as renderAgentMarkdown — see origin-marker.ts.
+ */
+export function renderDroidMarkdown(
+  role: AgentRole,
+  model?: string,
+  opts?: { mcpServerName?: string },
+): string {
+  const name = sanitizeDroidName(emittedRoleName(role));
+  if (!name) {
+    throw new Error(`role '${role.slug}': cannot form a valid droid name`);
+  }
+
+  const description = (
+    role.notes?.trim() || `PetBox ${role.tier} role (${emittedRoleName(role)})`
+  ).slice(0, 500);
+  const modelLine =
+    model && model.trim() ? model.trim() : "inherit"; // Factory default when unbound
+
+  const front: string[] = [
+    `name: ${name}`,
+    `description: ${JSON.stringify(description)}`,
+    `model: ${modelLine}`,
+  ];
+
+  // Scope petbox MCP to roles that need it (mcpServers = configured server names).
+  const needsMcp =
+    role.requiredCapabilities.includes("mcp_main_session") ||
+    role.requiredCapabilities.includes("mcp_subagent") ||
+    role.spawn?.allowed === true;
+  if (needsMcp) {
+    const server = opts?.mcpServerName ?? "petbox";
+    front.push(`mcpServers: ["${server}"]`);
+  }
+  front.push(PETBOX_MARKER_LINE);
+
+  const body = buildRoleBody(role);
+  return `---\n${front.join("\n")}\n---\n\n${body.endsWith("\n") ? body : body + "\n"}`;
+}
+
+/** @deprecated alias — prefer renderAgentMarkdown */
+export function renderOpencodeAgentMarkdown(role: AgentRole, model?: string): string {
+  return renderAgentMarkdown(role, model);
+}
+
+function renderForHarness(
+  harness: HarnessId,
+  role: AgentRole,
+  model: string | undefined,
+): string {
+  if (harness === "droid") return renderDroidMarkdown(role, model);
+  return renderAgentMarkdown(role, model);
+}
+
+/**
+ * Plan artifact writes for a definition + harness + optional role→model map.
+ * Emits clean roles; skips dirty roles with violations reported (not silent).
+ * Does not touch the filesystem.
+ */
+export function planApply(
+  definition: AgentDefinition,
+  harness: string,
+  roleModels: Readonly<Record<string, string>> = {},
+): ApplyPlan {
+  if (!isKnownHarness(harness)) {
+    return {
+      harness,
+      files: [],
+      violations: definition.roles.flatMap((role) =>
+        role.requiredCapabilities.map((capability) => ({
+          role: role.slug,
+          capability: String(capability),
+          harness,
+        })),
+      ),
+      skippedRoles: definition.roles.map((r) => r.slug),
+      warnings: [],
+    };
+  }
+
+  const dir = agentFilesDir(harness);
+  const files: PlannedFile[] = [];
+  const violations: TruthfulnessViolation[] = [];
+  const skippedRoles: string[] = [];
+  const warnings: string[] = [];
+
+  for (const role of definition.roles) {
+    const model = roleModels[role.slug];
+    // Gate BEFORE render: a role bound to a "foreign"-shaped model id is blocked, exactly like
+    // a missing capability — never write an id that belongs to a different harness's config.
+    const roleViolations = checkRoleTruthfulness(role, harness, model);
+    if (roleViolations.length > 0) {
+      violations.push(...roleViolations);
+      skippedRoles.push(role.slug);
+      continue;
+    }
+    if (!model || !model.trim()) {
+      warnings.push(
+        `role '${role.slug}' has no model binding for harness '${harness}' — the agent will ` +
+          `inherit the session/parent model. Bind it in ~/.petbox/roles.json to pin a tier.`,
+      );
+    } else {
+      const shapeWarning = modelShapeWarning(role, harness, model);
+      if (shapeWarning) warnings.push(shapeWarning);
+    }
+    const fileName =
+      harness === "droid" ? `${sanitizeDroidName(emittedRoleName(role))}.md` : `${emittedRoleName(role)}.md`;
+    // Pre-namespacing name — same file this role used to emit before petbox-namespaced-agent-names.
+    // The writer uses this to find + remove an owned leftover (never a foreign file at that path).
+    const legacyFileName = harness === "droid" ? `${sanitizeDroidName(role.slug)}.md` : `${role.slug}.md`;
+    files.push({
+      relativePath: join(dir, fileName).replace(/\\/g, "/"),
+      legacyRelativePath: join(dir, legacyFileName).replace(/\\/g, "/"),
+      content: renderForHarness(harness, role, model),
+    });
+  }
+
+  return { harness, files, violations, skippedRoles, warnings };
+}
+
+/** Thin wrapper: planApply(..., "opencode"). */
+export function planOpencodeApply(
+  definition: AgentDefinition,
+  roleModels: Readonly<Record<string, string>> = {},
+): ApplyPlan {
+  return planApply(definition, "opencode", roleModels);
+}
+
+/** Loud multi-line error for CLI when roles are blocked by the gate. */
+export function formatApplyBlocked(
+  violations: readonly TruthfulnessViolation[],
+  harness: string,
+  skippedRoles?: readonly string[],
+): string {
+  const skip =
+    skippedRoles && skippedRoles.length > 0
+      ? `\n  skipped roles: ${skippedRoles.join(", ")}`
+      : "";
+  return (
+    `apply: truthfulness gate blocked role(s) on harness '${harness}':\n` +
+    formatViolations(violations) +
+    skip
+  );
+}