pi-ca-leash 0.10.0

package/extensions/model-catalog.ts

@@ -0,0 +1,173 @@
+import type { RuntimeDriverName } from "@pi-claude-code-agent/runtime";
+
+export interface RuntimeModelCatalogEntry {
+  id: string;
+  name: string;
+  contextWindow: number;
+  maxTokens: number;
+  reasoning: boolean;
+  inputModalities: string[];
+  inputCostPerMillion: number;
+  outputCostPerMillion: number;
+}
+
+export interface RuntimeDriverModelCatalog {
+  driver: RuntimeDriverName;
+  provider: "anthropic" | "openai-codex";
+  defaultModel: string;
+  aliases: Record<string, string>;
+  recommendations: RuntimeModelRecommendation[];
+  cli: string;
+  flag: string;
+  source: string;
+  models: RuntimeModelCatalogEntry[];
+}
+
+export interface RuntimeModelRecommendation {
+  alias: string;
+  model: string;
+  useCase: string;
+}
+
+export interface RuntimeModelSelection {
+  requestedModel?: string;
+  runtimeModel?: string;
+  note: string;
+  alias?: string;
+  entry?: RuntimeModelCatalogEntry;
+}
+
+const LANISTA_SOURCE = "lanista agents anthropic/codex";
+
+export const RUNTIME_MODEL_CATALOGS: Record<RuntimeDriverName, RuntimeDriverModelCatalog> = {
+  "claude-sdk": {
+    driver: "claude-sdk",
+    provider: "anthropic",
+    defaultModel: "claude-opus-4-7",
+    aliases: {
+      haiku: "claude-haiku-4-5",
+      opus: "claude-opus-4-7",
+      sonnet: "claude-sonnet-4-6",
+    },
+    recommendations: [
+      { alias: "opus", model: "claude-opus-4-7", useCase: "architecture, hard review, long-context planning" },
+      { alias: "sonnet", model: "claude-sonnet-4-6", useCase: "coding, refactors, implementation reviews" },
+      { alias: "haiku", model: "claude-haiku-4-5", useCase: "quick checks, cheap parallel workers, summaries" },
+    ],
+    cli: "claude-code",
+    flag: "claude --model <id>",
+    source: LANISTA_SOURCE,
+    models: [
+      { id: "claude-3-5-haiku-20241022", name: "Claude Haiku 3.5", contextWindow: 200000, maxTokens: 8192, reasoning: false, inputModalities: ["text", "image"], inputCostPerMillion: 0.8, outputCostPerMillion: 4 },
+      { id: "claude-3-5-haiku-latest", name: "Claude Haiku 3.5 (latest)", contextWindow: 200000, maxTokens: 8192, reasoning: false, inputModalities: ["text", "image"], inputCostPerMillion: 0.8, outputCostPerMillion: 4 },
+      { id: "claude-3-5-sonnet-20240620", name: "Claude Sonnet 3.5", contextWindow: 200000, maxTokens: 8192, reasoning: false, inputModalities: ["text", "image"], inputCostPerMillion: 3, outputCostPerMillion: 15 },
+      { id: "claude-3-5-sonnet-20241022", name: "Claude Sonnet 3.5 v2", contextWindow: 200000, maxTokens: 8192, reasoning: false, inputModalities: ["text", "image"], inputCostPerMillion: 3, outputCostPerMillion: 15 },
+      { id: "claude-3-7-sonnet-20250219", name: "Claude Sonnet 3.7", contextWindow: 200000, maxTokens: 64000, reasoning: true, inputModalities: ["text", "image"], inputCostPerMillion: 3, outputCostPerMillion: 15 },
+      { id: "claude-3-haiku-20240307", name: "Claude Haiku 3", contextWindow: 200000, maxTokens: 4096, reasoning: false, inputModalities: ["text", "image"], inputCostPerMillion: 0.25, outputCostPerMillion: 1.25 },
+      { id: "claude-3-opus-20240229", name: "Claude Opus 3", contextWindow: 200000, maxTokens: 4096, reasoning: false, inputModalities: ["text", "image"], inputCostPerMillion: 15, outputCostPerMillion: 75 },
+      { id: "claude-3-sonnet-20240229", name: "Claude Sonnet 3", contextWindow: 200000, maxTokens: 4096, reasoning: false, inputModalities: ["text", "image"], inputCostPerMillion: 3, outputCostPerMillion: 15 },
+      { id: "claude-haiku-4-5", name: "Claude Haiku 4.5 (latest)", contextWindow: 200000, maxTokens: 64000, reasoning: true, inputModalities: ["text", "image"], inputCostPerMillion: 1, outputCostPerMillion: 5 },
+      { id: "claude-haiku-4-5-20251001", name: "Claude Haiku 4.5", contextWindow: 200000, maxTokens: 64000, reasoning: true, inputModalities: ["text", "image"], inputCostPerMillion: 1, outputCostPerMillion: 5 },
+      { id: "claude-opus-4-0", name: "Claude Opus 4 (latest)", contextWindow: 200000, maxTokens: 32000, reasoning: true, inputModalities: ["text", "image"], inputCostPerMillion: 15, outputCostPerMillion: 75 },
+      { id: "claude-opus-4-1", name: "Claude Opus 4.1 (latest)", contextWindow: 200000, maxTokens: 32000, reasoning: true, inputModalities: ["text", "image"], inputCostPerMillion: 15, outputCostPerMillion: 75 },
+      { id: "claude-opus-4-1-20250805", name: "Claude Opus 4.1", contextWindow: 200000, maxTokens: 32000, reasoning: true, inputModalities: ["text", "image"], inputCostPerMillion: 15, outputCostPerMillion: 75 },
+      { id: "claude-opus-4-20250514", name: "Claude Opus 4", contextWindow: 200000, maxTokens: 32000, reasoning: true, inputModalities: ["text", "image"], inputCostPerMillion: 15, outputCostPerMillion: 75 },
+      { id: "claude-opus-4-5", name: "Claude Opus 4.5 (latest)", contextWindow: 200000, maxTokens: 64000, reasoning: true, inputModalities: ["text", "image"], inputCostPerMillion: 5, outputCostPerMillion: 25 },
+      { id: "claude-opus-4-5-20251101", name: "Claude Opus 4.5", contextWindow: 200000, maxTokens: 64000, reasoning: true, inputModalities: ["text", "image"], inputCostPerMillion: 5, outputCostPerMillion: 25 },
+      { id: "claude-opus-4-6", name: "Claude Opus 4.6", contextWindow: 1000000, maxTokens: 128000, reasoning: true, inputModalities: ["text", "image"], inputCostPerMillion: 5, outputCostPerMillion: 25 },
+      { id: "claude-opus-4-7", name: "Claude Opus 4.7", contextWindow: 1000000, maxTokens: 128000, reasoning: true, inputModalities: ["text", "image"], inputCostPerMillion: 5, outputCostPerMillion: 25 },
+      { id: "claude-sonnet-4-0", name: "Claude Sonnet 4 (latest)", contextWindow: 200000, maxTokens: 64000, reasoning: true, inputModalities: ["text", "image"], inputCostPerMillion: 3, outputCostPerMillion: 15 },
+      { id: "claude-sonnet-4-20250514", name: "Claude Sonnet 4", contextWindow: 200000, maxTokens: 64000, reasoning: true, inputModalities: ["text", "image"], inputCostPerMillion: 3, outputCostPerMillion: 15 },
+      { id: "claude-sonnet-4-5", name: "Claude Sonnet 4.5 (latest)", contextWindow: 200000, maxTokens: 64000, reasoning: true, inputModalities: ["text", "image"], inputCostPerMillion: 3, outputCostPerMillion: 15 },
+      { id: "claude-sonnet-4-5-20250929", name: "Claude Sonnet 4.5", contextWindow: 200000, maxTokens: 64000, reasoning: true, inputModalities: ["text", "image"], inputCostPerMillion: 3, outputCostPerMillion: 15 },
+      { id: "claude-sonnet-4-6", name: "Claude Sonnet 4.6", contextWindow: 1000000, maxTokens: 64000, reasoning: true, inputModalities: ["text", "image"], inputCostPerMillion: 3, outputCostPerMillion: 15 },
+    ],
+  },
+  "codex-cli": {
+    driver: "codex-cli",
+    provider: "openai-codex",
+    defaultModel: "gpt-5.5",
+    aliases: {
+      codex: "gpt-5.3-codex",
+      mini: "gpt-5.4-mini",
+      spark: "gpt-5.3-codex-spark",
+    },
+    recommendations: [
+      { alias: "default", model: "gpt-5.5", useCase: "architecture, hard debugging, broad repo analysis" },
+      { alias: "codex", model: "gpt-5.3-codex", useCase: "coding, tests, focused refactors" },
+      { alias: "mini", model: "gpt-5.4-mini", useCase: "quick edits, cheap exploration, small reviews" },
+      { alias: "spark", model: "gpt-5.3-codex-spark", useCase: "fast text-only worker tasks" },
+    ],
+    cli: "codex",
+    flag: "codex --model <id>",
+    source: LANISTA_SOURCE,
+    models: [
+      { id: "gpt-5.1", name: "GPT-5.1", contextWindow: 272000, maxTokens: 128000, reasoning: true, inputModalities: ["text", "image"], inputCostPerMillion: 1.25, outputCostPerMillion: 10 },
+      { id: "gpt-5.1-codex-max", name: "GPT-5.1 Codex Max", contextWindow: 272000, maxTokens: 128000, reasoning: true, inputModalities: ["text", "image"], inputCostPerMillion: 1.25, outputCostPerMillion: 10 },
+      { id: "gpt-5.1-codex-mini", name: "GPT-5.1 Codex Mini", contextWindow: 272000, maxTokens: 128000, reasoning: true, inputModalities: ["text", "image"], inputCostPerMillion: 0.25, outputCostPerMillion: 2 },
+      { id: "gpt-5.2", name: "GPT-5.2", contextWindow: 272000, maxTokens: 128000, reasoning: true, inputModalities: ["text", "image"], inputCostPerMillion: 1.75, outputCostPerMillion: 14 },
+      { id: "gpt-5.2-codex", name: "GPT-5.2 Codex", contextWindow: 272000, maxTokens: 128000, reasoning: true, inputModalities: ["text", "image"], inputCostPerMillion: 1.75, outputCostPerMillion: 14 },
+      { id: "gpt-5.3-codex", name: "GPT-5.3 Codex", contextWindow: 272000, maxTokens: 128000, reasoning: true, inputModalities: ["text", "image"], inputCostPerMillion: 1.75, outputCostPerMillion: 14 },
+      { id: "gpt-5.3-codex-spark", name: "GPT-5.3 Codex Spark", contextWindow: 128000, maxTokens: 128000, reasoning: true, inputModalities: ["text"], inputCostPerMillion: 0, outputCostPerMillion: 0 },
+      { id: "gpt-5.4", name: "GPT-5.4", contextWindow: 272000, maxTokens: 128000, reasoning: true, inputModalities: ["text", "image"], inputCostPerMillion: 2.5, outputCostPerMillion: 15 },
+      { id: "gpt-5.4-mini", name: "GPT-5.4 Mini", contextWindow: 272000, maxTokens: 128000, reasoning: true, inputModalities: ["text", "image"], inputCostPerMillion: 0.75, outputCostPerMillion: 4.5 },
+      { id: "gpt-5.5", name: "GPT-5.5", contextWindow: 272000, maxTokens: 128000, reasoning: true, inputModalities: ["text", "image"], inputCostPerMillion: 5, outputCostPerMillion: 30 },
+    ],
+  },
+};
+
+export function modelCatalogsForDriver(driver?: RuntimeDriverName): RuntimeDriverModelCatalog[] {
+  if (driver) {
+    return [RUNTIME_MODEL_CATALOGS[driver]];
+  }
+  return [RUNTIME_MODEL_CATALOGS["claude-sdk"], RUNTIME_MODEL_CATALOGS["codex-cli"]];
+}
+
+export function findRuntimeModel(driver: RuntimeDriverName, model: string): RuntimeModelCatalogEntry | undefined {
+  const normalized = model.trim();
+  return RUNTIME_MODEL_CATALOGS[driver].models.find((entry) => entry.id === normalized);
+}
+
+export function resolveRuntimeModelSelection(driver: RuntimeDriverName, model?: string): RuntimeModelSelection {
+  const catalog = RUNTIME_MODEL_CATALOGS[driver];
+  const requestedModel = model?.trim() || undefined;
+  if (!requestedModel) {
+    return {
+      runtimeModel: undefined,
+      note: `model default ${catalog.defaultModel}`,
+    };
+  }
+
+  const aliasTarget = catalog.aliases[requestedModel.toLowerCase()];
+  const runtimeModel = aliasTarget ?? requestedModel;
+  const entry = findRuntimeModel(driver, runtimeModel);
+  if (!entry) {
+    return {
+      requestedModel,
+      runtimeModel,
+      note: `model ${requestedModel} not in bundled ${catalog.provider} catalog; passing through to runtime`,
+    };
+  }
+
+  const entryNote = `model ${entry.id} (${entry.name}, context window ${entry.contextWindow}, max output ${entry.maxTokens})`;
+  if (aliasTarget) {
+    return {
+      requestedModel,
+      runtimeModel,
+      alias: requestedModel,
+      entry,
+      note: `model alias ${requestedModel} -> ${entryNote}`,
+    };
+  }
+
+  return {
+    requestedModel,
+    runtimeModel,
+    entry,
+    note: entryNote,
+  };
+}
+
+export function describeModelSelection(driver: RuntimeDriverName, model?: string): string | undefined {
+  return resolveRuntimeModelSelection(driver, model).note;
+}

package/extensions/peer-history.test.ts

@@ -0,0 +1,141 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import type { RuntimeEvent } from "@pi-claude-code-agent/runtime";
+import { formatPeerHistoryPage } from "./peer-history.js";
+
+function makeEvent(event: Partial<RuntimeEvent> & Pick<RuntimeEvent, "type">): RuntimeEvent {
+  return {
+    id: `event-${event.type}`,
+    sessionId: "session-1",
+    sequence: 1,
+    timestamp: "2026-05-01T19:14:05.000Z",
+    ...event,
+  } as RuntimeEvent;
+}
+
+test("peer history hides thinking and shows visible transcript items", () => {
+  const page = formatPeerHistoryPage([
+    makeEvent({
+      type: "message",
+      sequence: 1,
+      role: "assistant",
+      message: {
+        role: "assistant",
+        blocks: [{ type: "thinking", text: "secret" }, { type: "text", text: "Ready." }],
+      },
+    }),
+    makeEvent({
+      type: "tool",
+      sequence: 2,
+      phase: "requested",
+      toolName: "Bash",
+      input: { command: "pwd" },
+    }),
+    makeEvent({
+      type: "tool",
+      sequence: 3,
+      phase: "completed",
+      toolName: "Bash",
+      output: { stdout: "/repo" },
+    }),
+    makeEvent({
+      type: "result",
+      sequence: 4,
+      ok: true,
+      summary: "Ready.",
+    }),
+  ]);
+
+  assert.match(page.text, /\[1 \d{2}:\d{2}:\d{2}\] assistant\nReady\./);
+  assert.match(page.text, /\[2 \d{2}:\d{2}:\d{2}\] tool requested Bash/);
+  assert.match(page.text, /"command": "pwd"/);
+  assert.match(page.text, /\[3 \d{2}:\d{2}:\d{2}\] tool completed Bash/);
+  assert.doesNotMatch(page.text, /secret/);
+  assert.doesNotMatch(page.text, /\[4 19:14:05\] result/);
+});
+
+test("peer history paginates by visible entries from tail by default and exposes cursors", () => {
+  const events = Array.from({ length: 5 }, (_, index) => makeEvent({
+    type: "message",
+    sequence: index + 1,
+    message: {
+      role: "assistant",
+      blocks: [{ type: "text", text: `msg-${index + 1}` }],
+    },
+    role: "assistant",
+  }));
+
+  const page = formatPeerHistoryPage(events, { limit: 2 });
+  assert.equal(page.startCursor, 3);
+  assert.equal(page.endCursor, 5);
+  assert.equal(page.previousCursor, 1);
+  assert.equal(page.nextCursor, undefined);
+  assert.match(page.text, /msg-4/);
+  assert.match(page.text, /msg-5/);
+  assert.doesNotMatch(page.text, /msg-3/);
+});
+
+test("peer history cursor ignores hidden events and empty visible ranges", () => {
+  const page = formatPeerHistoryPage([
+    makeEvent({
+      type: "message",
+      sequence: 1,
+      role: "assistant",
+      message: {
+        role: "assistant",
+        blocks: [{ type: "thinking", text: "secret" }],
+      },
+    }),
+    makeEvent({
+      type: "result",
+      sequence: 2,
+      ok: true,
+      summary: "done",
+    }),
+  ], { cursor: 0, limit: 2 });
+
+  assert.equal(page.startCursor, 0);
+  assert.equal(page.endCursor, 0);
+  assert.equal(page.text, "<no visible transcript items in this range>");
+});
+
+test("peer history limit counts visible entries rather than raw events", () => {
+  const page = formatPeerHistoryPage([
+    makeEvent({
+      type: "message",
+      sequence: 1,
+      role: "assistant",
+      message: {
+        role: "assistant",
+        blocks: [{ type: "text", text: "msg-1" }],
+      },
+    }),
+    makeEvent({
+      type: "result",
+      sequence: 2,
+      ok: true,
+      summary: "done-1",
+    }),
+    makeEvent({
+      type: "message",
+      sequence: 3,
+      role: "assistant",
+      message: {
+        role: "assistant",
+        blocks: [{ type: "text", text: "msg-2" }],
+      },
+    }),
+    makeEvent({
+      type: "result",
+      sequence: 4,
+      ok: true,
+      summary: "done-2",
+    }),
+  ], { limit: 2 });
+
+  assert.equal(page.total, 2);
+  assert.equal(page.startCursor, 0);
+  assert.equal(page.endCursor, 2);
+  assert.match(page.text, /msg-1/);
+  assert.match(page.text, /msg-2/);
+});

package/extensions/peer-history.ts

@@ -0,0 +1,90 @@
+import type { RuntimeEvent, RuntimeMessageBlock } from "@pi-claude-code-agent/runtime";
+
+export interface PeerHistoryPage {
+  startCursor: number;
+  endCursor: number;
+  total: number;
+  previousCursor?: number;
+  nextCursor?: number;
+  text: string;
+}
+
+export function formatPeerHistoryPage(
+  events: RuntimeEvent[],
+  options: { cursor?: number; limit?: number } = {},
+): PeerHistoryPage {
+  const entries = events
+    .map(formatTranscriptEvent)
+    .filter((value): value is string => Boolean(value));
+  const total = entries.length;
+  const limit = Math.max(1, Math.min(200, Math.trunc(options.limit ?? 20)));
+  const startCursor = options.cursor == null
+    ? Math.max(0, total - limit)
+    : Math.max(0, Math.min(total, Math.trunc(options.cursor)));
+  const endCursor = Math.min(total, startCursor + limit);
+  const page = entries.slice(startCursor, endCursor);
+
+  return {
+    startCursor,
+    endCursor,
+    total,
+    previousCursor: startCursor > 0 ? Math.max(0, startCursor - limit) : undefined,
+    nextCursor: endCursor < total ? endCursor : undefined,
+    text: page.join("\n\n") || "<no visible transcript items in this range>",
+  };
+}
+
+function formatTranscriptEvent(event: RuntimeEvent): string | undefined {
+  switch (event.type) {
+    case "message": {
+      const text = event.message.blocks
+        .map(blockToVisibleText)
+        .filter((value): value is string => Boolean(value && value.trim()))
+        .join("\n\n")
+        .trim();
+      if (!text) {
+        return undefined;
+      }
+      return [`[${event.sequence} ${formatIsoTime(event.timestamp)}] ${event.role}`, text].join("\n");
+    }
+    case "tool": {
+      const payload = event.phase === "requested" ? event.input : event.output;
+      const body = formatPayload(payload);
+      return [`[${event.sequence} ${formatIsoTime(event.timestamp)}] tool ${event.phase} ${event.toolName}`, body].filter(Boolean).join("\n");
+    }
+    case "error":
+      return [`[${event.sequence} ${formatIsoTime(event.timestamp)}] error`, event.message].join("\n");
+    default:
+      return undefined;
+  }
+}
+
+function blockToVisibleText(block: RuntimeMessageBlock): string | undefined {
+  if (block.type === "thinking") {
+    return undefined;
+  }
+  return typeof block.text === "string" ? block.text : undefined;
+}
+
+function formatPayload(value: unknown): string | undefined {
+  if (value == null) {
+    return undefined;
+  }
+  if (typeof value === "string") {
+    return truncate(value, 600);
+  }
+  try {
+    return truncate(JSON.stringify(value, null, 2), 600);
+  } catch {
+    return truncate(String(value), 600);
+  }
+}
+
+function truncate(value: string, max: number): string {
+  return value.length > max ? `${value.slice(0, max - 1)}…` : value;
+}
+
+function formatIsoTime(timestamp: string): string {
+  const date = new Date(timestamp);
+  return `${String(date.getHours()).padStart(2, "0")}:${String(date.getMinutes()).padStart(2, "0")}:${String(date.getSeconds()).padStart(2, "0")}`;
+}

package/extensions/peer-naming.test.ts

@@ -0,0 +1,25 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { derivePeerName, parsePeerStartInput } from "./peer-naming.js";
+
+test("parsePeerStartInput supports prompt-only auto-naming", () => {
+  assert.deepEqual(parsePeerStartInput("Investigate flaky tests"), {
+    prompt: "Investigate flaky tests",
+    autoNamed: true,
+  });
+});
+
+test("parsePeerStartInput preserves explicit name override", () => {
+  assert.deepEqual(parsePeerStartInput("reviewer | Review auth flow"), {
+    name: "reviewer",
+    prompt: "Review auth flow",
+    autoNamed: false,
+  });
+});
+
+test("derivePeerName uses readable role heuristics and deconflicts", () => {
+  assert.equal(derivePeerName("Please review the auth flow", []), "reviewer");
+  assert.equal(derivePeerName("Investigate flaky tests", ["researcher"]), "researcher-2");
+  assert.equal(derivePeerName("You are a brief worker. Reply briefly.", []), "worker");
+  assert.equal(derivePeerName("Help with this", ["peer"]), "peer-2");
+});

package/extensions/peer-naming.ts

@@ -0,0 +1,129 @@
+const ROLE_KEYWORDS: Array<{ tokens: string[]; name: string }> = [
+  { tokens: ["review", "reviewer"], name: "reviewer" },
+  { tokens: ["fix", "bug", "debug", "repair"], name: "fixer" },
+  { tokens: ["research", "investigate", "explore"], name: "researcher" },
+  { tokens: ["test", "qa", "verify"], name: "tester" },
+  { tokens: ["build", "compile"], name: "builder" },
+  { tokens: ["document", "docs", "write"], name: "writer" },
+  { tokens: ["plan", "design"], name: "planner" },
+  { tokens: ["search", "find", "grep"], name: "searcher" },
+  { tokens: ["refactor", "cleanup", "clean"], name: "cleaner" },
+];
+
+const STOP_WORDS = new Set([
+  "a",
+  "an",
+  "and",
+  "are",
+  "as",
+  "be",
+  "brief",
+  "can",
+  "code",
+  "concise",
+  "direct",
+  "do",
+  "exactly",
+  "file",
+  "for",
+  "from",
+  "help",
+  "in",
+  "into",
+  "is",
+  "it",
+  "me",
+  "my",
+  "of",
+  "on",
+  "or",
+  "please",
+  "prompt",
+  "reply",
+  "role",
+  "task",
+  "that",
+  "the",
+  "this",
+  "to",
+  "use",
+  "with",
+  "you",
+  "your",
+]);
+
+export interface ParsedPeerStartInput {
+  name?: string;
+  prompt?: string;
+  autoNamed: boolean;
+}
+
+export function parsePeerStartInput(args: string): ParsedPeerStartInput {
+  const parts = args.split("|").map((part) => part.trim()).filter(Boolean);
+  if (parts.length === 0) {
+    return { autoNamed: false };
+  }
+  if (parts.length === 1) {
+    return {
+      prompt: parts[0],
+      autoNamed: true,
+    };
+  }
+  return {
+    name: parts[0],
+    prompt: parts.slice(1).join(" | "),
+    autoNamed: false,
+  };
+}
+
+export function derivePeerName(prompt: string, existingNames: Iterable<string>): string {
+  const existing = new Set([...existingNames].map((name) => name.toLowerCase()));
+  const normalized = prompt.toLowerCase();
+
+  for (const candidate of ROLE_KEYWORDS) {
+    if (candidate.tokens.some((token) => normalized.includes(token))) {
+      return ensureUniqueName(candidate.name, existing);
+    }
+  }
+
+  const roleMatch = normalized.match(/you are (?:an? )?(?:\w+\s+){0,2}(\w+)/i);
+  const roleToken = sanitizeToken(roleMatch?.[1]);
+  if (roleToken && !STOP_WORDS.has(roleToken)) {
+    return ensureUniqueName(roleToken, existing);
+  }
+
+  const tokens = normalized
+    .split(/[^a-z0-9]+/)
+    .map((token) => sanitizeToken(token))
+    .filter((token): token is string => Boolean(token && !STOP_WORDS.has(token)));
+
+  for (const token of tokens) {
+    if (token.length >= 3) {
+      return ensureUniqueName(token, existing);
+    }
+  }
+
+  return ensureUniqueName("peer", existing);
+}
+
+function ensureUniqueName(base: string, existing: Set<string>): string {
+  const normalizedBase = sanitizeToken(base) ?? "peer";
+  if (!existing.has(normalizedBase)) {
+    return normalizedBase;
+  }
+  for (let suffix = 2; suffix < 1000; suffix += 1) {
+    const candidate = `${normalizedBase}-${suffix}`;
+    if (!existing.has(candidate)) {
+      return candidate;
+    }
+  }
+  return `${normalizedBase}-${Date.now()}`;
+}
+
+function sanitizeToken(value: string | undefined): string | undefined {
+  if (!value) {
+    return undefined;
+  }
+  const normalized = value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+  return normalized || undefined;
+}

package/extensions/peer-relay.test.ts

@@ -0,0 +1,122 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import {
+  createPeerRelaySnapshot,
+  formatPeerCompletionTurn,
+  formatQuotedTextBlock,
+  shouldForceRelayPeerCompletion,
+  shouldRelayPeerCompletion,
+} from "./peer-relay.ts";
+
+test("peer relay ignores initial seeded terminal state", () => {
+  const current = createPeerRelaySnapshot({
+    sessionId: "session-1",
+    state: "idle",
+    updatedAt: "2026-05-01T19:14:05.000Z",
+  });
+
+  assert.equal(shouldRelayPeerCompletion(undefined, current), false);
+  assert.equal(shouldForceRelayPeerCompletion(undefined, current), true);
+});
+
+test("peer relay fires when terminal snapshot changes after seed", () => {
+  const previous = createPeerRelaySnapshot({
+    sessionId: "session-1",
+    state: "idle",
+    updatedAt: "2026-05-01T19:14:05.000Z",
+  });
+  const current = createPeerRelaySnapshot({
+    sessionId: "session-1",
+    state: "waiting",
+    updatedAt: "2026-05-01T19:20:00.000Z",
+  });
+
+  assert.equal(shouldRelayPeerCompletion(previous, current), true);
+  assert.equal(shouldForceRelayPeerCompletion(previous, current), true);
+});
+
+test("peer relay ignores timestamp-only change for stable state and message", () => {
+  const previous = createPeerRelaySnapshot({
+    sessionId: "session-1",
+    state: "idle",
+    updatedAt: "2026-05-01T19:14:05.000Z",
+    messageText: "All clear.",
+  });
+  const current = createPeerRelaySnapshot({
+    sessionId: "session-1",
+    state: "idle",
+    updatedAt: "2026-05-01T19:20:00.000Z",
+    messageText: "All clear.",
+  });
+
+  assert.equal(shouldRelayPeerCompletion(previous, current), false);
+  assert.equal(shouldForceRelayPeerCompletion(previous, current), false);
+});
+
+test("peer relay fires on same-state new visible reply", () => {
+  const previous = createPeerRelaySnapshot({
+    sessionId: "session-1",
+    state: "idle",
+    updatedAt: "2026-05-01T19:14:05.000Z",
+    messageText: "All clear.",
+  });
+  const current = createPeerRelaySnapshot({
+    sessionId: "session-1",
+    state: "idle",
+    updatedAt: "2026-05-01T19:14:05.000Z",
+    messageText: "Done. Tests pass now.",
+  });
+
+  assert.equal(shouldRelayPeerCompletion(previous, current), true);
+  assert.equal(shouldForceRelayPeerCompletion(previous, current), true);
+});
+
+test("peer relay ignores unchanged or non-relayable snapshots", () => {
+  const previous = createPeerRelaySnapshot({
+    sessionId: "session-1",
+    state: "idle",
+    updatedAt: "2026-05-01T19:14:05.000Z",
+  });
+
+  assert.equal(shouldRelayPeerCompletion(previous, previous), false);
+  assert.equal(
+    shouldRelayPeerCompletion(
+      previous,
+      createPeerRelaySnapshot({
+        sessionId: "session-1",
+        state: "busy",
+        updatedAt: "2026-05-01T19:20:00.000Z",
+      }),
+    ),
+    false,
+  );
+});
+
+test("quoted text block uses fenced raw text", () => {
+  assert.equal(
+    formatQuotedTextBlock("All clear."),
+    ["```text", "All clear.", "```"].join("\n"),
+  );
+  assert.equal(
+    formatQuotedTextBlock("Contains ``` fence"),
+    ["````text", "Contains ``` fence", "````"].join("\n"),
+  );
+});
+
+test("peer relay formats wrapped main-turn prompt", () => {
+  const message = formatPeerCompletionTurn({
+    peerName: "reviewer",
+    state: "idle",
+    sessionId: "573f279f-30ec-4300-b948-da05f5d3007f",
+    message: "All clear.",
+  });
+
+  assert.match(message, /\[peer_update name=reviewer state=idle session=573f279f-30e\]/);
+  assert.match(message, /Automated peer update\./);
+  assert.match(message, /Peer: reviewer/);
+  assert.match(message, /State: idle/);
+  assert.match(message, /Peer reviewer finished\./);
+  assert.match(message, /Latest peer message:\n```text\nAll clear\.\n```/);
+  assert.match(message, /Use this as internal orchestration context\./);
+  assert.match(message, /Do not quote this wrapper verbatim to the user\./);
+});