@cohortapp/agent-sdk 2.3.0

package/lib/voice/post-call-brief.mjs

@@ -0,0 +1,428 @@
+/**
+ * Maestro — Post-call brief generator.
+ *
+ * When voice-poller normalizes a `call.ended` event, this module spawns
+ * a small `claude --print` session (or routes through the model router)
+ * to convert the raw transcript into:
+ *
+ *   1. A markdown brief saved to `outputs/briefs/voice-calls/<date>-<call_id>.md`
+ *      — durable record discoverable by the operator via filesystem or RAG.
+ *   2. A structured JSON sidecar saved alongside, parseable by downstream
+ *      automation.
+ *   3. Action items pushed to `state/queues/action-stack.yaml`.
+ *   4. Any explicit decisions written to `knowledge/decisions/voice-calls/`
+ *      where the decision-log agent picks them up.
+ *
+ * The original `call.ended` inbox item still flows through the daemon's
+ * normal classifier → dispatcher pipeline, but its `content` field is
+ * replaced with the brief markdown so the classifier sees something
+ * meaningful (rather than a raw transcript blob).
+ *
+ * Why a separate brief generator (and not just the standard pipeline):
+ *   - Voice transcripts are noisy and unstructured. The classifier
+ *     needs a clean summary to route correctly (priority/category/action).
+ *   - Action items mentioned mid-call should land in the queue
+ *     immediately, not wait for the agent's next backlog cycle.
+ *   - Decisions made on a call are first-class records that need to flow
+ *     into the institutional decision log alongside Slack/Gmail decisions.
+ *   - Generating the brief inline (sub-second claude --print call with a
+ *     focused prompt) is cheaper and faster than spinning up a full
+ *     reactive session for every call.
+ *
+ * Public API:
+ *   generateBrief({ event, agentRoot }) → { brief_md, brief_json, paths }
+ */
+
+import { spawn } from "node:child_process";
+import { writeFileSync, readFileSync, mkdirSync, existsSync, appendFileSync } from "node:fs";
+import { join, resolve, dirname } from "node:path";
+
+const BRIEF_PROMPT = `You are an executive operator processing the transcript of a voice call.
+Produce a structured post-call brief in JSON only — no preamble, no commentary.
+
+Schema:
+{
+  "summary": "<1-2 sentence summary of what happened on the call>",
+  "headline": "<8-12 word newspaper-headline summary for inbox display>",
+  "category": "decision_made" | "action_required" | "fyi" | "follow_up_only",
+  "priority": "critical" | "high" | "normal" | "low",
+  "decisions": [
+    { "what": "<decision text>", "decided_by": "<person>", "domain": "<area>", "context": "<why>" }
+  ],
+  "action_items": [
+    { "title": "<verb-phrase>", "owner": "<person|self>", "due": "<ISO date or relative>", "context": "<details>" }
+  ],
+  "follow_ups": [
+    { "with": "<person>", "topic": "<topic>", "next_step": "<concrete action>" }
+  ],
+  "risks": [
+    { "kind": "regulatory|operational|financial|relational", "summary": "<one-liner>" }
+  ],
+  "unresolved_questions": ["<question>"],
+  "tool_actions_audit": [
+    { "tool": "<name>", "outcome": "ok|error|blocked", "summary": "<one-liner>" }
+  ]
+}
+
+Rules:
+- Empty arrays are fine when nothing applies; never omit a key.
+- "self" in owner means the agent (you) committed to do it.
+- Be specific in action items — "follow up with the principal" is too vague; prefer
+  "send the principal the budget update by Thursday".
+- Decisions must include a "decided_by" naming the person; if ambiguous
+  ("we agreed to..."), use "joint" and note both parties in context.
+- If the transcript is empty or shows the call dropped before substance,
+  set category=fyi, headline="Voice call (no substantive content)",
+  and leave the lists empty.
+- Keep the entire JSON under 4 KB.
+
+Return JSON only.`;
+
+/**
+ * Generate a post-call brief from a voice call's normalized event payload.
+ *
+ * @param {object} opts
+ * @param {object} opts.event           The voice inbox event:
+ *   {
+ *     event_type: "call.ended",
+ *     call_id, peer, peer_name, started_at, ended_at,
+ *     duration_ms, transcript, tool_calls, …
+ *   }
+ * @param {string} opts.agentRoot
+ * @param {string} [opts.model]         "sonnet" | "opus" | "haiku" (default: sonnet)
+ * @param {boolean} [opts.detached]     fork without awaiting (default: false)
+ * @returns {Promise<{ brief_md: string, brief_json: object, paths: { md, json } }>}
+ */
+export async function generateBrief(opts = {}) {
+  const event = opts.event || {};
+  const agentRoot = resolve(opts.agentRoot || process.env.AGENT_ROOT || process.cwd());
+
+  const callId = event.call_id || `call-${Date.now()}`;
+  const date = (event.ended_at || new Date().toISOString()).slice(0, 10);
+  const peer = event.peer_name || event.peer || "unknown caller";
+  const transcript = (event.transcript || "").trim();
+  const toolCalls = Array.isArray(event.tool_calls) ? event.tool_calls : [];
+  const durationMin = event.duration_ms ? Math.round(event.duration_ms / 60000) : 0;
+
+  // Build the context the model needs to summarize the call
+  const summarizerInput = [
+    `# Call metadata`,
+    `Call ID: ${callId}`,
+    `Peer: ${peer}`,
+    `Started: ${event.started_at || "unknown"}`,
+    `Ended: ${event.ended_at || "unknown"}`,
+    `Duration: ${durationMin} minutes`,
+    `Transport: ${event.transport || "unknown"}`,
+    `End reason: ${event.reason || "unknown"}`,
+    "",
+    `# Transcript`,
+    transcript || "(no transcript captured — likely a missed/dropped call)",
+    "",
+    `# Tool actions invoked during the call`,
+    toolCalls.length === 0
+      ? "(none)"
+      : toolCalls.map((t, i) =>
+          `${i + 1}. ${t.name} risk=${t.risk || "low"} → ${t.error ? `error: ${t.error}` : "ok"}\n` +
+          `   args: ${JSON.stringify(t.args || {}).slice(0, 240)}`
+        ).join("\n"),
+  ].join("\n");
+
+  // Spawn claude with the brief prompt; capture stdout JSON
+  const briefJson = await runClaudeBrief({
+    agentRoot,
+    model: opts.model || "sonnet",
+    systemPrompt: BRIEF_PROMPT,
+    input: summarizerInput,
+  });
+
+  // Render markdown view of the brief for human consumption
+  const briefMd = renderMarkdownBrief({ event, brief: briefJson });
+
+  // Persist
+  const briefDir = join(agentRoot, "outputs/briefs/voice-calls");
+  mkdirSync(briefDir, { recursive: true });
+  const safeCallId = String(callId).replace(/[^A-Za-z0-9._-]/g, "_").slice(0, 40);
+  const mdPath = join(briefDir, `${date}-${safeCallId}.md`);
+  const jsonPath = join(briefDir, `${date}-${safeCallId}.json`);
+  writeFileSync(mdPath, briefMd);
+  writeFileSync(jsonPath, JSON.stringify(briefJson, null, 2));
+
+  // Push extracted action items to action-stack queue (best-effort)
+  await pushActionItems({ agentRoot, brief: briefJson, callId, peer });
+
+  // Push decisions to knowledge/decisions/voice-calls/ for the
+  // decision-log agent to pick up
+  await pushDecisions({ agentRoot, brief: briefJson, callId, peer, date });
+
+  return {
+    brief_md: briefMd,
+    brief_json: briefJson,
+    paths: { md: mdPath, json: jsonPath },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Claude --print runner (single-shot, JSON-only output)
+// ---------------------------------------------------------------------------
+
+function runClaudeBrief({ agentRoot, model, systemPrompt, input }) {
+  return new Promise((resolveP) => {
+    const claudeBin = process.env.CLAUDE_BIN || "claude";
+    const fullPrompt = `${systemPrompt}\n\n---\n${input}`;
+    const proc = spawn(claudeBin, [
+      "--print",
+      "--dangerously-skip-permissions",
+      "--strict-mcp-config",
+      "--model", model,
+      fullPrompt,
+    ], {
+      cwd: agentRoot,
+      env: {
+        ...process.env,
+        AGENT_ROOT: agentRoot,
+        AGENT_DIR: agentRoot,
+        // Voice briefs are routine summarization; let model router pick
+        // the cheap backend by signalling it as a "fast" tier task.
+      },
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+
+    let stdout = "";
+    let stderr = "";
+    let timer;
+    proc.stdout.on("data", (chunk) => { stdout += chunk.toString(); });
+    proc.stderr.on("data", (chunk) => { stderr += chunk.toString(); });
+
+    timer = setTimeout(() => {
+      try { proc.kill("SIGTERM"); } catch { /* */ }
+      resolveP(fallbackBrief(input, "claude timed out after 90s"));
+    }, 90_000);
+
+    proc.on("error", (err) => {
+      clearTimeout(timer);
+      resolveP(fallbackBrief(input, `claude spawn failed: ${err.message}`));
+    });
+    proc.on("close", (code) => {
+      clearTimeout(timer);
+      if (code !== 0) {
+        resolveP(fallbackBrief(input, `claude exit ${code}: ${stderr.slice(0, 300)}`));
+        return;
+      }
+      // Strip any preamble/postamble — find the first '{' and last '}'.
+      const start = stdout.indexOf("{");
+      const end = stdout.lastIndexOf("}");
+      if (start < 0 || end < 0 || end < start) {
+        resolveP(fallbackBrief(input, "claude returned no JSON"));
+        return;
+      }
+      try {
+        const parsed = JSON.parse(stdout.slice(start, end + 1));
+        // Defensive defaults — guarantee schema completeness
+        resolveP({
+          summary: parsed.summary || "",
+          headline: parsed.headline || "Voice call",
+          category: parsed.category || "fyi",
+          priority: parsed.priority || "normal",
+          decisions: Array.isArray(parsed.decisions) ? parsed.decisions : [],
+          action_items: Array.isArray(parsed.action_items) ? parsed.action_items : [],
+          follow_ups: Array.isArray(parsed.follow_ups) ? parsed.follow_ups : [],
+          risks: Array.isArray(parsed.risks) ? parsed.risks : [],
+          unresolved_questions: Array.isArray(parsed.unresolved_questions) ? parsed.unresolved_questions : [],
+          tool_actions_audit: Array.isArray(parsed.tool_actions_audit) ? parsed.tool_actions_audit : [],
+          _model: model,
+          _generated_at: new Date().toISOString(),
+        });
+      } catch (err) {
+        resolveP(fallbackBrief(input, `JSON parse error: ${err.message}; raw: ${stdout.slice(0, 200)}`));
+      }
+    });
+  });
+}
+
+function fallbackBrief(input, reason) {
+  return {
+    summary: "(brief generation failed — see raw transcript in event payload)",
+    headline: "Voice call (brief generation failed)",
+    category: "fyi",
+    priority: "low",
+    decisions: [],
+    action_items: [],
+    follow_ups: [],
+    risks: [],
+    unresolved_questions: [],
+    tool_actions_audit: [],
+    _generation_error: reason,
+    _generated_at: new Date().toISOString(),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Markdown rendering
+// ---------------------------------------------------------------------------
+
+function renderMarkdownBrief({ event, brief }) {
+  const peer = event.peer_name || event.peer || "unknown";
+  const callId = event.call_id || "(no id)";
+  const durMin = event.duration_ms ? Math.round(event.duration_ms / 60000) : 0;
+  const lines = [];
+  lines.push(`# Voice call brief — ${peer}`);
+  lines.push("");
+  lines.push(`**Call ID:** ${callId}`);
+  lines.push(`**Peer:** ${peer}${event.peer && event.peer_name && event.peer !== event.peer_name ? ` (${event.peer})` : ""}`);
+  lines.push(`**Started:** ${event.started_at || "?"}`);
+  lines.push(`**Ended:** ${event.ended_at || "?"}`);
+  lines.push(`**Duration:** ${durMin}m`);
+  lines.push(`**Transport:** ${event.transport || "?"}`);
+  lines.push(`**Category:** ${brief.category}`);
+  lines.push(`**Priority:** ${brief.priority}`);
+  lines.push("");
+  lines.push(`## Headline`);
+  lines.push(brief.headline);
+  lines.push("");
+  lines.push(`## Summary`);
+  lines.push(brief.summary);
+  lines.push("");
+
+  if (brief.decisions?.length) {
+    lines.push(`## Decisions made`);
+    for (const d of brief.decisions) {
+      lines.push(`- **${d.what}** (decided by ${d.decided_by}, domain: ${d.domain || "—"})`);
+      if (d.context) lines.push(`  _${d.context}_`);
+    }
+    lines.push("");
+  }
+  if (brief.action_items?.length) {
+    lines.push(`## Action items`);
+    for (const a of brief.action_items) {
+      lines.push(`- [ ] **${a.title}** — owner: ${a.owner}, due: ${a.due || "TBD"}`);
+      if (a.context) lines.push(`  _${a.context}_`);
+    }
+    lines.push("");
+  }
+  if (brief.follow_ups?.length) {
+    lines.push(`## Follow-ups`);
+    for (const f of brief.follow_ups) {
+      lines.push(`- with **${f.with}**: ${f.topic} → ${f.next_step}`);
+    }
+    lines.push("");
+  }
+  if (brief.risks?.length) {
+    lines.push(`## Risks flagged`);
+    for (const r of brief.risks) {
+      lines.push(`- **${r.kind}**: ${r.summary}`);
+    }
+    lines.push("");
+  }
+  if (brief.unresolved_questions?.length) {
+    lines.push(`## Unresolved questions`);
+    for (const q of brief.unresolved_questions) lines.push(`- ${q}`);
+    lines.push("");
+  }
+  if (brief.tool_actions_audit?.length) {
+    lines.push(`## Tool actions during the call`);
+    for (const t of brief.tool_actions_audit) {
+      lines.push(`- \`${t.tool}\` → ${t.outcome}: ${t.summary}`);
+    }
+    lines.push("");
+  }
+  if (brief._generation_error) {
+    lines.push(`---`);
+    lines.push(`> ⚠ Brief generation hit an error: ${brief._generation_error}`);
+  }
+  lines.push("");
+  lines.push(`---`);
+  lines.push(`_Generated by post-call-brief.mjs at ${brief._generated_at}_`);
+
+  if (event.transcript) {
+    lines.push("");
+    lines.push(`<details><summary>Full transcript</summary>`);
+    lines.push("");
+    lines.push("```");
+    lines.push(event.transcript);
+    lines.push("```");
+    lines.push("</details>");
+  }
+  return lines.join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// Push to queues + decision log
+// ---------------------------------------------------------------------------
+
+/**
+ * Append new action items to state/queues/action-stack.yaml WITHOUT parsing
+ * the existing file. Many of the operator-edited queue files have minor
+ * YAML quirks (duplicate keys from human edits, etc.) that trip strict
+ * parsers — and we don't want a single bad existing item to block voice
+ * briefs from contributing new items. So we just append YAML list-items
+ * to the end.
+ *
+ * Format matches the existing convention used by other surfaces.
+ */
+async function pushActionItems({ agentRoot, brief, callId, peer }) {
+  if (!brief.action_items?.length) return;
+  const queuePath = join(agentRoot, "state/queues/action-stack.yaml");
+  if (!existsSync(queuePath)) return;
+  try {
+    const now = new Date().toISOString();
+    const safeCall = String(callId).slice(0, 16);
+    let appended = "";
+    for (const a of brief.action_items) {
+      const id = `voice-${safeCall}-${Date.now()}-${Math.floor(Math.random() * 1000)}`;
+      const title = String(a.title || "(untitled)").replace(/"/g, '\\"');
+      const owner = String(a.owner || "self");
+      const due = a.due ? `"${String(a.due).replace(/"/g, '')}"` : "null";
+      const context = String(a.context || "").replace(/"/g, '\\"').replace(/\n/g, " ");
+      appended += [
+        ``,
+        `  - id: "${id}"`,
+        `    title: "${title}"`,
+        `    priority: "${brief.priority || "normal"}"`,
+        `    status: open`,
+        `    owner: ${owner}`,
+        `    due_date: ${due}`,
+        `    created: "${now}"`,
+        `    source: "voice call with ${peer} (${safeCall})"`,
+        `    context: "${context}"`,
+      ].join("\n") + "\n";
+    }
+    if (appended) {
+      const existing = readFileSync(queuePath, "utf-8");
+      const sep = existing.endsWith("\n") ? "" : "\n";
+      writeFileSync(queuePath, existing + sep + appended);
+    }
+  } catch (err) {
+    // Don't crash the brief generator if queue append fails; surface in
+    // a sidecar log so the operator can spot it.
+    try {
+      appendFileSync(
+        join(agentRoot, "logs/voice/post-call-brief-errors.log"),
+        `${new Date().toISOString()} pushActionItems(${callId}) failed: ${err.message}\n`
+      );
+    } catch { /* */ }
+  }
+}
+
+async function pushDecisions({ agentRoot, brief, callId, peer, date }) {
+  if (!brief.decisions?.length) return;
+  const decDir = join(agentRoot, "knowledge/decisions/voice-calls");
+  mkdirSync(decDir, { recursive: true });
+  for (let i = 0; i < brief.decisions.length; i++) {
+    const d = brief.decisions[i];
+    const path = join(decDir, `${date}-${callId.slice(0, 16)}-${i + 1}.yaml`);
+    const body = [
+      `id: VOICE-${callId.slice(0, 12).toUpperCase()}-${i + 1}`,
+      `date: "${date}"`,
+      `title: "${(d.what || "").replace(/"/g, '\\"').slice(0, 200)}"`,
+      `decision_maker: "${d.decided_by || "joint"}"`,
+      `domain: "${d.domain || "general"}"`,
+      `source: "voice call with ${peer}"`,
+      `context: |`,
+      `  ${(d.context || "(no context provided)").replace(/\n/g, "\n  ")}`,
+      `captured_via: post-call-brief`,
+    ].join("\n");
+    writeFileSync(path, body + "\n");
+  }
+}
+
+export default { generateBrief };

package/lib/voice/provider.mjs

@@ -0,0 +1,52 @@
+/**
+ * Maestro — Voice provider base class + shared event constants.
+ *
+ * Lives in its own file (separate from index.mjs) to avoid an ESM circular
+ * import: index.mjs imports openai-realtime.mjs which would otherwise need
+ * VoiceProvider from index.mjs while index.mjs is still being evaluated.
+ */
+
+import { EventEmitter } from "node:events";
+
+export const VOICE_EVENTS = Object.freeze({
+  CONNECTED: "connected",
+  SESSION_CREATED: "session.created",
+  AUDIO_DELTA: "audio.delta",
+  AUDIO_DONE: "audio.done",
+  TRANSCRIPT_DELTA: "transcript.delta",
+  TRANSCRIPT_DONE: "transcript.done",
+  USER_SPEECH_STARTED: "user.speech.started",
+  USER_SPEECH_STOPPED: "user.speech.stopped",
+  TOOL_CALL: "tool.call",
+  TOOL_CALL_DELTA: "tool.call.delta",
+  TURN_DONE: "turn.done",
+  ERROR: "error",
+  CLOSED: "closed",
+});
+
+/**
+ * Abstract base. Subclasses implement the transport-specific bits. We
+ * keep this as a class with default no-op methods so a provider can
+ * partially implement (e.g. text-only providers without audio).
+ */
+export class VoiceProvider extends EventEmitter {
+  constructor(opts = {}) {
+    super();
+    this.opts = opts;
+    this.state = "idle";
+  }
+  // eslint-disable-next-line no-unused-vars
+  async connect(sessionConfig) { throw new Error("connect() not implemented"); }
+  // eslint-disable-next-line no-unused-vars
+  appendAudio(pcm16) { /* override */ }
+  commitTurn() { /* override */ }
+  interrupt(opts) { /* override */ }
+  // eslint-disable-next-line no-unused-vars
+  sendToolResult(callId, output) { /* override */ }
+  // eslint-disable-next-line no-unused-vars
+  sendText(text) { /* override */ }
+  close(reason) {
+    this.state = "closed";
+    this.emit(VOICE_EVENTS.CLOSED, { reason });
+  }
+}