@cohortapp/agent-sdk 2.3.0

package/lib/util/unhandled.test.mjs

@@ -0,0 +1,216 @@
+/**
+ * lib/util/unhandled.test.mjs
+ *
+ * node:test coverage for the process-level unhandled-failure handlers. Every test
+ * drives an injected fake process (a real EventEmitter so listener registration /
+ * removal behaves exactly like Node's) and an injected exit + counter, so a
+ * simulated rejection/exception is captured WITHOUT touching the test runner's
+ * own process or actually exiting.
+ *
+ * Covered:
+ *  - install captures a simulated unhandledRejection via onEvent (log + keep running)
+ *  - the rejection is counted via the injected bump (loud, durable)
+ *  - install captures a simulated uncaughtException and exits (fatal) by default
+ *  - exitOnUncaught:false logs the exception but does NOT exit
+ *  - install is idempotent: a second install does not double-register
+ *  - uninstall removes the listeners; a later emit is not captured
+ *  - a throwing onEvent sink is isolated (no second uncaught throw)
+ *  - non-Error rejection values are described, not dropped
+ *
+ * Run: cd /Users/layla/maestro && node --test lib/util/unhandled.test.mjs
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { EventEmitter } from "node:events";
+
+import {
+  installUnhandledHandlers,
+  isInstalled,
+  UNHANDLED_COUNTERS,
+} from "./unhandled.mjs";
+
+/** A fake process: a real EventEmitter so on/removeListener semantics match. */
+function fakeProcess() {
+  const ee = new EventEmitter();
+  ee.exited = [];
+  ee.exit = (code) => ee.exited.push(code);
+  return ee;
+}
+
+test("captures a simulated unhandledRejection via onEvent and keeps running", () => {
+  const proc = fakeProcess();
+  const events = [];
+  const { uninstall, installed } = installUnhandledHandlers({
+    process: proc,
+    onEvent: (e) => events.push(e),
+    bump: () => {},
+  });
+  assert.equal(installed, true);
+  try {
+    // Simulate Node emitting an unhandled rejection.
+    proc.emit("unhandledRejection", new Error("boom-reject"));
+    assert.equal(events.length, 1);
+    assert.equal(events[0].kind, "unhandledRejection");
+    assert.equal(events[0].fatal, false);
+    assert.equal(events[0].error.message, "boom-reject");
+    // Log + keep running: a rejection must NEVER exit.
+    assert.deepEqual(proc.exited, []);
+  } finally {
+    uninstall();
+  }
+});
+
+test("an unhandledRejection is counted via the injected bump", () => {
+  const proc = fakeProcess();
+  const counts = [];
+  const { uninstall } = installUnhandledHandlers({
+    process: proc,
+    bump: (name, attrs) => counts.push({ name, attrs }),
+  });
+  try {
+    proc.emit("unhandledRejection", new Error("count-me"));
+    assert.equal(counts.length, 1);
+    assert.equal(counts[0].name, UNHANDLED_COUNTERS.REJECTION);
+    assert.equal(counts[0].attrs.message, "count-me");
+    assert.equal(counts[0].attrs.fatal, false);
+  } finally {
+    uninstall();
+  }
+});
+
+test("captures an uncaughtException, counts it, and exits (fatal) by default", () => {
+  const proc = fakeProcess();
+  const events = [];
+  const counts = [];
+  const { uninstall } = installUnhandledHandlers({
+    process: proc,
+    onEvent: (e) => events.push(e),
+    bump: (name, attrs) => counts.push({ name, attrs }),
+    exit: (code) => proc.exit(code),
+    exitCode: 7,
+  });
+  try {
+    proc.emit("uncaughtException", new Error("fatal-boom"));
+    assert.equal(events.length, 1);
+    assert.equal(events[0].kind, "uncaughtException");
+    assert.equal(events[0].fatal, true);
+    assert.equal(events[0].error.message, "fatal-boom");
+    assert.equal(counts[0].name, UNHANDLED_COUNTERS.EXCEPTION);
+    // Loud exit so launchd restarts a clean process.
+    assert.deepEqual(proc.exited, [7]);
+  } finally {
+    uninstall();
+  }
+});
+
+test("exitOnUncaught:false logs the exception but does not exit", () => {
+  const proc = fakeProcess();
+  const events = [];
+  const { uninstall } = installUnhandledHandlers({
+    process: proc,
+    onEvent: (e) => events.push(e),
+    bump: () => {},
+    exitOnUncaught: false,
+    exit: (code) => proc.exit(code),
+  });
+  try {
+    proc.emit("uncaughtException", new Error("non-fatal"));
+    assert.equal(events.length, 1);
+    assert.equal(events[0].kind, "uncaughtException");
+    assert.deepEqual(proc.exited, [], "must NOT exit when exitOnUncaught is false");
+  } finally {
+    uninstall();
+  }
+});
+
+test("install is idempotent: a second install does not double-register", () => {
+  const proc = fakeProcess();
+  const events = [];
+  const first = installUnhandledHandlers({ process: proc, onEvent: (e) => events.push(e), bump: () => {} });
+  const second = installUnhandledHandlers({ process: proc, onEvent: (e) => events.push(e), bump: () => {} });
+  try {
+    assert.equal(first.installed, true);
+    assert.equal(second.installed, false, "second install must be a no-op");
+    assert.equal(proc.listenerCount("unhandledRejection"), 1, "exactly one listener");
+    assert.equal(proc.listenerCount("uncaughtException"), 1);
+    // One emit → one captured event (not two from a double-registration).
+    proc.emit("unhandledRejection", new Error("once"));
+    assert.equal(events.length, 1);
+  } finally {
+    first.uninstall();
+  }
+});
+
+test("uninstall removes the listeners and isInstalled flips", () => {
+  const proc = fakeProcess();
+  const events = [];
+  const { uninstall } = installUnhandledHandlers({ process: proc, onEvent: (e) => events.push(e), bump: () => {} });
+  assert.equal(isInstalled(proc), true);
+  uninstall();
+  assert.equal(isInstalled(proc), false);
+  assert.equal(proc.listenerCount("unhandledRejection"), 0);
+  assert.equal(proc.listenerCount("uncaughtException"), 0);
+  // A later emit is no longer captured.
+  proc.emit("unhandledRejection", new Error("after-uninstall"));
+  assert.equal(events.length, 0);
+});
+
+test("a re-install after uninstall works (installed:true again)", () => {
+  const proc = fakeProcess();
+  const a = installUnhandledHandlers({ process: proc, bump: () => {} });
+  a.uninstall();
+  const b = installUnhandledHandlers({ process: proc, bump: () => {} });
+  try {
+    assert.equal(b.installed, true);
+    assert.equal(proc.listenerCount("unhandledRejection"), 1);
+  } finally {
+    b.uninstall();
+  }
+});
+
+test("a throwing onEvent sink is isolated (no second uncaught throw)", () => {
+  const proc = fakeProcess();
+  const { uninstall } = installUnhandledHandlers({
+    process: proc,
+    onEvent: () => { throw new Error("sink exploded"); },
+    bump: () => {},
+  });
+  try {
+    // The handler must swallow the sink's throw rather than re-throwing.
+    assert.doesNotThrow(() => proc.emit("unhandledRejection", new Error("x")));
+  } finally {
+    uninstall();
+  }
+});
+
+test("a throwing bump counter is isolated and onEvent still fires", () => {
+  const proc = fakeProcess();
+  const events = [];
+  const { uninstall } = installUnhandledHandlers({
+    process: proc,
+    onEvent: (e) => events.push(e),
+    bump: () => { throw new Error("counter blew up"); },
+  });
+  try {
+    assert.doesNotThrow(() => proc.emit("unhandledRejection", new Error("y")));
+    assert.equal(events.length, 1, "onEvent fires even if the counter throws");
+  } finally {
+    uninstall();
+  }
+});
+
+test("describes non-Error rejection values rather than dropping them", () => {
+  const proc = fakeProcess();
+  const events = [];
+  const { uninstall } = installUnhandledHandlers({ process: proc, onEvent: (e) => events.push(e), bump: () => {} });
+  try {
+    proc.emit("unhandledRejection", "just a string");
+    proc.emit("unhandledRejection", { code: "ECUSTOM", detail: 1 });
+    assert.equal(events.length, 2);
+    assert.equal(events[0].error.message, "just a string");
+    assert.equal(typeof events[1].error.message, "string");
+  } finally {
+    uninstall();
+  }
+});

package/lib/voice/context-loader.mjs

@@ -0,0 +1,466 @@
+/**
+ * Maestro — Voice session context loader.
+ *
+ * Builds a rich, agent-aware system prompt to inject into the
+ * `instructions` field of an OpenAI Realtime session, so the model
+ * walks into the call already knowing:
+ *
+ *   - Who the agent is (name, role, principal, company, voice mode rules)
+ *   - The agent's active strategic priorities
+ *   - Top open queue items (action stack, decisions, blockers, awaiting reply)
+ *   - Most recent decisions captured in knowledge/decisions/
+ *   - Today's calendar (next ~4h of meetings)
+ *   - Who the peer on the call is (if identifiable) + their recent history
+ *
+ * Why this matters: a Realtime session is otherwise stateless. Without
+ * pre-loaded context the agent ends up calling search_* tools mid-call,
+ * which adds 1-3s of latency and breaks the conversational rhythm. We
+ * pre-load ~2k tokens of frozen context at session start so the model
+ * can reference it natively without tool round-trips.
+ *
+ * Public API:
+ *   buildContextualInstructions({agentRoot, identity, peer, callKind})
+ *     → string  (full instructions text to put in session config)
+ *   loadAgentContextSnapshot({agentRoot}) → object  (raw snapshot for audit)
+ */
+
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+// Optional YAML parser — loaded lazily so this module doesn't force
+// js-yaml at import time. Returns null if unavailable.
+let _yaml = undefined;
+async function getYaml() {
+  if (_yaml !== undefined) return _yaml;
+  try { _yaml = (await import("js-yaml")); }
+  catch { _yaml = null; }
+  return _yaml;
+}
+
+// ---------------------------------------------------------------------------
+// Snapshot loaders (each defensive — missing files yield empty defaults)
+// ---------------------------------------------------------------------------
+
+function readYamlSync(path) {
+  if (!existsSync(path)) return null;
+  try {
+    // synchronous fallback parse: try plain JSON first (works for many
+    // generated yaml files since they're really JSON-shaped), then
+    // give up if no parser available. The async loader is preferred.
+    const body = readFileSync(path, "utf-8");
+    try { return JSON.parse(body); } catch { return body; }
+  } catch { return null; }
+}
+
+async function readYamlAsync(path) {
+  if (!existsSync(path)) return null;
+  const body = readFileSync(path, "utf-8");
+  const yaml = await getYaml();
+  if (yaml) {
+    try { return yaml.load(body); } catch { /* */ }
+  }
+  return body;
+}
+
+/** Read config/agent.json — single source of truth for identity. */
+function loadIdentity(agentRoot) {
+  const path = join(agentRoot, "config/agent.json");
+  if (!existsSync(path)) return {};
+  try {
+    const j = JSON.parse(readFileSync(path, "utf-8"));
+    return {
+      name: j.firstName || j.fullName || "Agent",
+      fullName: j.fullName || j.firstName || "Agent",
+      role: j.title || "agent",
+      company: j.company || "the company",
+      principal: j.principal || null,
+      slackId: j.slackMemberId || null,
+      email: j.email || null,
+      timezone: j.timezone || null,
+    };
+  } catch { return {}; }
+}
+
+/** Load top N open items from state/queues/<queue>.yaml. */
+async function loadQueueTop(agentRoot, queueName, n = 3) {
+  const path = join(agentRoot, "state/queues", `${queueName}.yaml`);
+  const parsed = await readYamlAsync(path);
+  if (!parsed || typeof parsed !== "object") return [];
+  const items = (parsed.items || []).filter((x) => x && (x.status === "open" || x.status === "in_progress" || !x.status));
+  return items.slice(0, n);
+}
+
+/** Read the executive-summary dashboard (the canonical at-session-start view). */
+async function loadExecutiveSummary(agentRoot) {
+  const path = join(agentRoot, "state/dashboards/executive-summary.yaml");
+  return await readYamlAsync(path);
+}
+
+/** Load strategic priorities (config/priorities.yaml). */
+async function loadPriorities(agentRoot) {
+  const path = join(agentRoot, "config/priorities.yaml");
+  return await readYamlAsync(path);
+}
+
+/** Last N decision entries from knowledge/decisions/. */
+function loadRecentDecisions(agentRoot, n = 5) {
+  const dir = join(agentRoot, "knowledge/decisions");
+  if (!existsSync(dir)) return [];
+  try {
+    const files = readdirSync(dir)
+      .filter((f) => f.endsWith(".yaml") || f.endsWith(".md") || f.endsWith(".json"))
+      .filter((f) => !f.startsWith("decision-schema"))
+      .map((f) => ({ f, mtime: statSync(join(dir, f)).mtimeMs }))
+      .sort((a, b) => b.mtime - a.mtime)
+      .slice(0, n);
+    return files.map(({ f }) => {
+      const path = join(dir, f);
+      const body = readFileSync(path, "utf-8");
+      // First 400 chars is plenty to identify the decision in voice context
+      const summary = body.split(/\n/).slice(0, 8).join(" / ").slice(0, 400);
+      return { file: f, summary };
+    });
+  } catch { return []; }
+}
+
+/** Look up a peer in config/contacts.yaml by phone, slack id, or email. */
+async function lookupPeer(agentRoot, peerIdentifier) {
+  if (!peerIdentifier) return null;
+  const path = join(agentRoot, "config/contacts.yaml");
+  if (!existsSync(path)) return null;
+  const body = readFileSync(path, "utf-8");
+  const raw = String(peerIdentifier).toLowerCase().trim();
+  if (!raw) return null;
+  // Try several normalized forms — phone numbers may be stored with or
+  // without "+", with spaces, with parentheses, etc.
+  const variants = new Set([
+    raw,
+    raw.replace(/^\+/, ""),
+    raw.replace(/[^a-z0-9]/g, ""),
+    raw.replace(/[^a-z0-9@._-]/g, ""),
+  ]);
+  let idx = -1;
+  for (const v of variants) {
+    if (!v) continue;
+    idx = body.toLowerCase().indexOf(v);
+    if (idx >= 0) break;
+  }
+  if (idx < 0) return null;
+  const before = body.slice(Math.max(0, idx - 400), idx);
+  const after = body.slice(idx, Math.min(body.length, idx + 400));
+  return { found: true, block: (before + after).trim() };
+}
+
+/**
+ * Load the full team directory — humans from config/contacts.yaml + peer
+ * AI agents from config/known-agents.json. Pre-loaded into every voice
+ * session so the model has the org chart in context without needing a
+ * mid-call tool round-trip.
+ *
+ * Returns: {humans: [...], agents: [...]}
+ */
+async function loadTeamDirectory(agentRoot) {
+  const out = { humans: [], agents: [] };
+
+  const contactsPath = join(agentRoot, "config/contacts.yaml");
+  if (existsSync(contactsPath)) {
+    const body = readFileSync(contactsPath, "utf-8");
+    const yaml = await getYaml();
+    if (yaml) {
+      try {
+        const parsed = yaml.load(body);
+        const list = (parsed && parsed.contacts) || [];
+        out.humans = list.map((c) => ({
+          name: c.name || "(unknown)",
+          role: c.role || "",
+          email: c.email || "",
+          slack_id: c.slack_id || "",
+          classification: c.classification || "",
+          notes: c.notes || "",
+        }));
+      } catch { /* fall through to text scan */ }
+    }
+    if (!out.humans.length) {
+      // Fallback parser when js-yaml is unavailable
+      const blockRe = /-\s*name:\s*([^\n]+)\s*\n\s*role:\s*([^\n]+)\s*\n\s*company:\s*[^\n]+\s*\n\s*email:\s*([^\n]+)/g;
+      for (const match of body.matchAll(blockRe)) {
+        out.humans.push({
+          name: match[1].trim(),
+          role: match[2].trim(),
+          email: match[3].trim(),
+          slack_id: "",
+          classification: "",
+          notes: "",
+        });
+      }
+    }
+  }
+
+  const agentsPath = join(agentRoot, "config/known-agents.json");
+  if (existsSync(agentsPath)) {
+    try {
+      const j = JSON.parse(readFileSync(agentsPath, "utf-8"));
+      out.agents = (j.agents || []).map((a) => ({
+        name: a.name || "",
+        fullName: a.fullName || a.name || "",
+        role: a.role || "",
+        slackId: a.slackId || "",
+        repo: a.repo || "",
+      }));
+    } catch { /* leave empty */ }
+  }
+
+  return out;
+}
+
+/** Today's calendar items from state/inbox/calendar/. */
+function loadTodayCalendar(agentRoot, maxItems = 5) {
+  const dir = join(agentRoot, "state/inbox/calendar");
+  if (!existsSync(dir)) return [];
+  try {
+    const todayPrefix = new Date().toISOString().slice(0, 10);
+    const files = readdirSync(dir)
+      .filter((f) => f.endsWith(".json") || f.endsWith(".yaml"))
+      .filter((f) => !f.endsWith(".processed"))
+      .slice(0, 50)
+      .map((f) => ({ f, mtime: statSync(join(dir, f)).mtimeMs }))
+      .sort((a, b) => b.mtime - a.mtime)
+      .slice(0, maxItems);
+    return files.map(({ f }) => {
+      try {
+        const body = readFileSync(join(dir, f), "utf-8");
+        return body.slice(0, 300);
+      } catch { return null; }
+    }).filter(Boolean);
+  } catch { return []; }
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Load a structured snapshot of the agent's context. Used by
+ * buildContextualInstructions() to compose the prompt, but exposed so
+ * the daemon can audit / serialize the same data.
+ */
+export async function loadAgentContextSnapshot({ agentRoot, peer = null } = {}) {
+  const root = resolve(agentRoot || process.env.AGENT_ROOT || process.env.AGENT_DIR || process.cwd());
+  const [actionStack, decisionQueue, awaitingReply, blockers, priorities, execSummary, peerInfo, team] = await Promise.all([
+    loadQueueTop(root, "action-stack", 5),
+    loadQueueTop(root, "decision-queue", 3),
+    loadQueueTop(root, "awaiting-reply", 3),
+    loadQueueTop(root, "blocked-initiatives", 3),
+    loadPriorities(root),
+    loadExecutiveSummary(root),
+    lookupPeer(root, peer),
+    loadTeamDirectory(root),
+  ]);
+  return {
+    identity: loadIdentity(root),
+    priorities,
+    executive_summary: execSummary,
+    queues: {
+      action_stack: actionStack,
+      decision_queue: decisionQueue,
+      awaiting_reply: awaitingReply,
+      blockers: blockers,
+    },
+    recent_decisions: loadRecentDecisions(root, 5),
+    today_calendar: loadTodayCalendar(root, 5),
+    peer: peerInfo,
+    team_directory: team,
+    snapshot_taken_at: new Date().toISOString(),
+  };
+}
+
+/**
+ * Build the full `instructions` text to pass to OpenAI Realtime's
+ * session.update. Composes identity + frozen context snapshot in a way
+ * that's voice-friendly (short, bulleted, scannable for the model).
+ *
+ * @param {object} opts
+ * @param {string} opts.agentRoot
+ * @param {string} [opts.peer]      Peer identifier (phone / slack id / email)
+ * @param {string} [opts.callKind]  "inbound" | "outbound" | "browser_test"
+ * @param {string} [opts.brief]     For outbound: what the agent should accomplish
+ * @returns {Promise<string>}
+ */
+export async function buildContextualInstructions(opts = {}) {
+  const snapshot = await loadAgentContextSnapshot({ agentRoot: opts.agentRoot, peer: opts.peer });
+  const id = snapshot.identity || {};
+  const principal = id.principal?.firstName || id.principal?.fullName || "the principal";
+
+  const lines = [];
+
+  // ── Identity + voice-mode rules
+  lines.push(`# Identity`);
+  lines.push(`You are ${id.fullName || id.name || "the agent"}, ${id.role || "an executive operator"} at ${id.company || "the company"}.`);
+  if (id.principal) {
+    lines.push(`You serve as autonomous executive command for ${principal} (${id.principal.title || "principal"}).`);
+  }
+  lines.push("");
+  lines.push(`# How to talk on this call`);
+  lines.push(`Sound like a thoughtful colleague, not an assistant. Full style guide: policies/communication-style.md.`);
+  lines.push(`- One or two sentences per turn, then pause. Don't monologue.`);
+  lines.push(`- Use contractions (I'll, we're, doesn't). Match the other person's register — terse if they're terse, warm if they're warm.`);
+  lines.push(`- Don't open with "Certainly!" / "Absolutely!" / "Great question!" / "I'd be happy to…" — start with the answer.`);
+  lines.push(`- Banned phrases: "I'm here to help," "Let me know if you need anything else," "I hope this helps," "As an AI," "Here's a comprehensive overview of…"`);
+  lines.push(`- Don't introduce yourself by listing your role. "Hi, this is ${id.name || "the agent"}" is enough unless asked.`);
+  lines.push(`- Disagree when warranted. Don't soften real concerns into pleasantries.`);
+  lines.push(`- For high-risk actions (sending external messages, financial commitments, deletions), read the parameters back out loud and get verbal confirmation in the SAME turn before invoking the tool.`);
+  lines.push(`- If you need a slow tool lookup, say "one second" — don't go silent for 3 seconds.`);
+  lines.push(`- If you're not sure who's on the call, ask before assuming.`);
+  lines.push("");
+
+  // ── Outbound brief (only for outbound calls)
+  if (opts.callKind === "outbound" && opts.brief) {
+    lines.push(`# Your task on this call`);
+    lines.push(opts.brief);
+    lines.push("");
+  }
+
+  // ── Strategic priorities
+  if (snapshot.priorities) {
+    lines.push(`# Current strategic priorities`);
+    const pBody = typeof snapshot.priorities === "string"
+      ? snapshot.priorities.slice(0, 500)
+      : JSON.stringify(snapshot.priorities).slice(0, 500);
+    lines.push(pBody);
+    lines.push("");
+  }
+
+  // ── Top open items (most-likely-mentioned-on-the-call snapshot)
+  const renderItems = (label, items) => {
+    if (!items?.length) return;
+    lines.push(`# ${label}`);
+    for (const it of items.slice(0, 5)) {
+      const title = it.title || it.summary || it.subject || it.description || "(untitled)";
+      const status = it.status || "open";
+      const due = it.due_date || it.due || it.deadline || "";
+      lines.push(`- [${status}] ${title}${due ? ` (due ${due})` : ""}`);
+    }
+    lines.push("");
+  };
+  renderItems("Top action items on your desk", snapshot.queues.action_stack);
+  renderItems("Decisions awaiting input", snapshot.queues.decision_queue);
+  renderItems("Messages awaiting your reply", snapshot.queues.awaiting_reply);
+  renderItems("Active blockers", snapshot.queues.blockers);
+
+  // ── Recent decisions (institutional context the model may need to cite)
+  if (snapshot.recent_decisions?.length) {
+    lines.push(`# Recent decisions (last ${snapshot.recent_decisions.length})`);
+    for (const d of snapshot.recent_decisions) {
+      lines.push(`- ${d.file}: ${d.summary.replace(/\s+/g, " ").slice(0, 180)}`);
+    }
+    lines.push("");
+  }
+
+  // ── Today's calendar
+  if (snapshot.today_calendar?.length) {
+    lines.push(`# Today's calendar (next ~4h)`);
+    for (const c of snapshot.today_calendar.slice(0, 4)) {
+      lines.push(`- ${c.replace(/\s+/g, " ").slice(0, 160)}`);
+    }
+    lines.push("");
+  }
+
+  // ── Peer context (if identified)
+  if (snapshot.peer?.found) {
+    lines.push(`# Caller context`);
+    lines.push(snapshot.peer.block.slice(0, 600));
+    lines.push("");
+  } else if (opts.peer) {
+    lines.push(`# Caller`);
+    lines.push(`Identifier: ${opts.peer}. Not in your contacts roster — ask who they are if you don't already know.`);
+    lines.push("");
+  }
+
+  // ── Team directory (org chart pre-loaded so the model can reference any
+  //    colleague mid-call without a tool round-trip).
+  const team = snapshot.team_directory;
+  if (team && (team.humans?.length || team.agents?.length)) {
+    lines.push(`# Team directory (your org chart — refer to anyone here without needing to look them up)`);
+    if (team.humans?.length) {
+      lines.push(`## Humans (${team.humans.length})`);
+      for (const h of team.humans) {
+        const cls = h.classification ? ` [${h.classification}]` : "";
+        const slack = h.slack_id ? ` slack:${h.slack_id}` : "";
+        const note = h.notes ? ` — ${h.notes.slice(0, 80)}` : "";
+        lines.push(`- ${h.name} — ${h.role} (${h.email})${slack}${cls}${note}`);
+      }
+    }
+    if (team.agents?.length) {
+      lines.push(`## Peer AI agents (${team.agents.length}) — colleagues with their own dedicated agent presence`);
+      for (const a of team.agents) {
+        const slack = a.slackId ? ` slack:${a.slackId}` : ` slack:not-yet-provisioned`;
+        lines.push(`- ${a.name} (${a.fullName}) — ${a.role}, repo:${a.repo}${slack}`);
+      }
+    }
+    lines.push("");
+  }
+
+  // ── RAG pre-load: when we have a brief (outbound call) or an identified
+  // peer (inbound), seed the prompt with top-3 hits from the agent's
+  // indexed corpus. This catches the "model walks in needing a specific
+  // fact from a decision / brief / agent definition" case without a
+  // mid-call tool round-trip.
+  try {
+    // Probe selection:
+    //   - Outbound call: use the brief (what the agent is calling about).
+    //   - Inbound with known peer: combine peer + agent identity.
+    //   - Anything else (browser test, unknown peer): use a generic
+    //     "what's hot right now" query so the session still gets some
+    //     RAG seeding from the agent's own active concerns.
+    let probe;
+    if (opts.callKind === "outbound" && opts.brief) {
+      probe = opts.brief;
+    } else if (snapshot.peer?.found && opts.peer) {
+      probe = `${opts.peer} ${id.name || ""} ${id.role || ""}`;
+    } else {
+      // Synthesize a probe from the agent's current top queue + recent decisions
+      // so even cold-start sessions get *some* RAG context.
+      const top = [
+        snapshot.queues?.action_stack?.[0]?.title,
+        snapshot.queues?.decision_queue?.[0]?.title,
+        snapshot.queues?.awaiting_reply?.[0]?.title,
+      ].filter(Boolean).join(" ");
+      probe = top || null;
+    }
+    if (probe) {
+      // search module is lib/rag/search.mjs — go up one from lib/voice/.
+      let searchFn = null;
+      try {
+        const { search: s } = await import("../rag/search.mjs");
+        searchFn = s;
+      } catch { /* RAG not built yet — silent skip */ }
+      if (searchFn) {
+        const hits = await searchFn({ query: probe, topN: 3, agentRoot: opts.agentRoot });
+        if (hits?.length) {
+          lines.push(`# Pre-loaded RAG context (top ${hits.length} hits from your indexed corpus)`);
+          for (const h of hits) {
+            lines.push(`- ${h.source_path} [${h.kind}] — ${h.title}`);
+            lines.push(`  ${h.snippet.replace(/\s+/g, " ").slice(0, 280)}`);
+          }
+          lines.push("");
+        }
+      }
+    }
+  } catch { /* RAG pre-load failure is non-fatal */ }
+
+  // ── Tool guidance
+  lines.push(`# Tools available to you`);
+  lines.push(`You have function tools to send Slack messages, email, WhatsApp, SMS, voice messages, search the agent's memory (decisions, email, Slack, calendar), look up people, update operational queues, and run \`rag_search\` against the agent's full indexed corpus (memory, knowledge, decisions, queues, briefs, policies). Each tool call adds ~1-2s of silence — use them when needed but don't burn turns on speculative lookups.`);
+  lines.push("");
+
+  // ── Final
+  lines.push(`Remain in ${id.name || "the agent"}'s voice. Honour the action-classification policy: high-risk actions require verbal confirmation in the same turn.`);
+
+  // Hard cap at ~8k chars so we don't blow the instructions limit (which is
+  // generous but we want to keep call setup fast). Bumped from 6k after
+  // adding the team directory section.
+  const text = lines.join("\n");
+  return text.length > 8000 ? text.slice(0, 7980) + "\n…(truncated)" : text;
+}
+
+export default { buildContextualInstructions, loadAgentContextSnapshot };