@creativeintelligence/abbie 0.1.0

package/src/lib/report.ts

@@ -0,0 +1,973 @@
+/**
+ * Report module - unified lifecycle reporting for agents
+ *
+ * Combines Convex reports persistence, Slack visibility, and iMessage escalation
+ * into a single command surface.
+ *
+ * Design decisions (from opus consultation):
+ * - 4 subcommands: start, progress, complete, blocked
+ * - Tiered error handling: convex=fail, slack=warn+continue, messages=warn+continue
+ * - Agent identity auto-detection from session env vars
+ * - Trace ID inheritance from AGENTS_TRACE_ID or auto-generate
+ * - DM policy: default ON for blocked, opt-in for others
+ */
+
+import { spawnSync } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { api, getHttpClient } from "@abbie/sdk/convex";
+import { getDeviceId } from "./device.js";
+import { getDefaultSlackWorkspace } from "./slack-workspace.js";
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export type ReportAction = "started" | "progress" | "completed" | "blocked";
+
+export type AgentIdentity = "claude" | "codex" | "gemini" | "copilot" | "custom";
+
+export type BlockerType = "hil" | "error" | "dependency" | "resource";
+
+export interface ReportOptions {
+  /** Agent identity (auto-detected if not provided) */
+  agent?: AgentIdentity;
+  /** Trace ID for correlation (inherits from AGENTS_TRACE_ID or auto-generates) */
+  traceId?: string;
+  /** Slack workspace (default: ABBIE_SLACK_WORKSPACE or cic) */
+  workspace?: string;
+  /** Slack channel (default: agents) */
+  channel?: string;
+  /** Confidence score 1-10 */
+  confidence?: number;
+  /** Send DM to luke (default: true for blocked, false for others) */
+  dm?: boolean;
+  /** Explicitly disable DM */
+  noDm?: boolean;
+  /** Dry run - log what would happen without executing */
+  dryRun?: boolean;
+  /** Artifacts to attach (for complete) */
+  artifacts?: string[];
+  /** Blocker type (for blocked) */
+  blockerType?: BlockerType;
+  /** Create GitHub gist from event (for orchestration handoffs) */
+  gist?: boolean;
+  /** Gist description (defaults to task/message) */
+  gistDescription?: string;
+  /** Make gist public (default: secret) */
+  gistPublic?: boolean;
+}
+
+export interface ReportResult {
+  success: boolean;
+  traceId: string;
+  agent: AgentIdentity;
+  action: ReportAction;
+  /** Convex reports mutation result */
+  convex: {
+    success: boolean;
+    error?: string;
+  };
+  /** slack post result */
+  slack: {
+    success: boolean;
+    error?: string;
+  };
+  /** messages send result (only if DM was attempted) */
+  messages?: {
+    success: boolean;
+    error?: string;
+  };
+  /** Optional remote report result (only if configured via env) */
+  remote?: {
+    success: boolean;
+    error?: string;
+  };
+  /** GitHub gist URL (only if --gist was used) */
+  gistUrl?: string;
+  /** Duration in milliseconds (if available) */
+  durationMs?: number;
+}
+
+// ============================================================================
+// Agent Identity Detection
+// ============================================================================
+
+/**
+ * Detect agent identity from session environment variables
+ */
+export function detectAgent(): AgentIdentity {
+  // Check session-specific env vars
+  if (process.env.CLAUDE_SESSION_ID) return "claude";
+  if (process.env.CODEX_SESSION_ID) return "codex";
+  if (process.env.GEMINI_SESSION_ID) return "gemini";
+  if (process.env.COPILOT_SESSION_ID) return "copilot";
+
+  // Check runtime environment markers
+  // Claude Code sets CLAUDECODE=1 and CLAUDE_CODE_ENTRYPOINT
+  if (process.env.CLAUDECODE === "1" || process.env.CLAUDE_CODE_ENTRYPOINT) {
+    return "claude";
+  }
+
+  // Check agent name env var (fallback)
+  const agentName = process.env.AGENT_NAME?.toLowerCase();
+  if (agentName) {
+    const known: AgentIdentity[] = ["claude", "codex", "gemini", "copilot"];
+    if (known.includes(agentName as AgentIdentity)) {
+      return agentName as AgentIdentity;
+    }
+  }
+
+  // Fallback to custom identity
+  return "custom";
+}
+
+// ============================================================================
+// Trace ID Management
+// ============================================================================
+
+/**
+ * Generate a new trace ID
+ */
+export function generateTraceId(): string {
+  return `tr_${randomUUID().replace(/-/g, "").slice(0, 24)}`;
+}
+
+/**
+ * Get or create trace ID
+ * - Returns existing AGENTS_TRACE_ID if set
+ * - Generates new one if forceNew or not set
+ */
+export function getOrCreateTraceId(forceNew = false): string {
+  if (!forceNew && process.env.AGENTS_TRACE_ID) {
+    return process.env.AGENTS_TRACE_ID;
+  }
+  return generateTraceId();
+}
+
+// ============================================================================
+// Shell Command Execution
+// ============================================================================
+
+interface ExecResult {
+  success: boolean;
+  stdout?: string;
+  stderr?: string;
+  error?: string;
+}
+
+function execCommand(command: string, args: string[]): ExecResult {
+  try {
+    const result = spawnSync(command, args, {
+      encoding: "utf-8",
+      stdio: ["pipe", "pipe", "pipe"],
+      timeout: 30000, // 30s timeout
+    });
+
+    if (result.status === 0) {
+      return {
+        success: true,
+        stdout: result.stdout,
+        stderr: result.stderr,
+      };
+    }
+
+    return {
+      success: false,
+      stdout: result.stdout,
+      stderr: result.stderr,
+      error: `Exit code ${result.status}: ${result.stderr || result.stdout}`,
+    };
+  } catch (err) {
+    return {
+      success: false,
+      error: err instanceof Error ? err.message : String(err),
+    };
+  }
+}
+
+// ============================================================================
+// Convex Persistence
+// ============================================================================
+
+interface ReportEvent {
+  traceId: string;
+  agent: AgentIdentity;
+  action: ReportAction;
+  task: string;
+  sessionId?: string;
+  confidence?: number;
+  severity?: string;
+  summary?: string;
+  blockerType?: BlockerType;
+  artifacts?: string[];
+  deviceId: string;
+  timestamp: number;
+}
+
+interface RecordReportOptions {
+  agent: AgentIdentity;
+  traceId: string;
+  action: ReportAction;
+  task: string;
+  confidence?: number;
+  blockerType?: BlockerType;
+  artifacts?: string[];
+  /** Create GitHub gist from event */
+  gist?: boolean;
+  /** Gist description */
+  gistDescription?: string;
+  /** Make gist public */
+  gistPublic?: boolean;
+}
+
+function resolveSessionId(): string | undefined {
+  return (
+    process.env.AGENTS_SESSION_ID ||
+    process.env.AGENTS_REPORT_SESSION_ID ||
+    process.env.CLAUDE_SESSION_ID ||
+    process.env.CODEX_SESSION_ID ||
+    process.env.COPILOT_SESSION_ID ||
+    process.env.GEMINI_SESSION_ID
+  );
+}
+
+async function recordToConvex(options: RecordReportOptions): Promise<ExecResult> {
+  try {
+    const client = getHttpClient();
+    const deviceId = getDeviceId();
+    const sessionId = resolveSessionId();
+    const severity = options.action === "blocked" ? "error" : undefined;
+
+    const stored = await client.mutation(api.reports.record, {
+      traceId: options.traceId,
+      agent: options.agent,
+      action: options.action,
+      task: options.task,
+      sessionId,
+      confidence: options.confidence,
+      severity,
+      summary: options.task,
+      blockerType: options.blockerType,
+      artifacts: options.artifacts,
+      deviceId,
+    });
+
+    const event: ReportEvent = {
+      traceId: options.traceId,
+      agent: options.agent,
+      action: options.action,
+      task: options.task,
+      sessionId,
+      confidence: options.confidence,
+      severity,
+      summary: options.task,
+      blockerType: options.blockerType,
+      artifacts: options.artifacts,
+      deviceId,
+      timestamp:
+        typeof stored === "object" && stored !== null && "timestamp" in stored
+          ? Number(stored.timestamp)
+          : Date.now(),
+    };
+
+    const output: Record<string, unknown> = { ...event };
+    if (typeof stored === "object" && stored !== null && "id" in stored) {
+      output.id = stored.id;
+    }
+
+    if (options.gist) {
+      const gistUrl = createReportGist(event, {
+        description: options.gistDescription,
+        isPublic: options.gistPublic,
+      });
+      if (gistUrl) {
+        output.gist_url = gistUrl;
+      }
+    }
+
+    return {
+      success: true,
+      stdout: JSON.stringify(output),
+      stderr: "",
+    };
+  } catch (err) {
+    return {
+      success: false,
+      error: err instanceof Error ? err.message : String(err),
+    };
+  }
+}
+
+function createReportGist(
+  event: ReportEvent,
+  options: { description?: string; isPublic?: boolean },
+): string | undefined {
+  const date = new Date().toISOString().split("T")[0];
+  const filename = `${event.agent}-${event.action}-${date}.json`;
+  const description =
+    options.description || event.task || event.summary || `${event.agent} ${event.action}`;
+  const args = ["gist", "create", "-f", filename, "-d", description];
+  if (options.isPublic) {
+    args.push("--public");
+  }
+
+  const result = spawnSync("gh", args, {
+    encoding: "utf-8",
+    input: `${JSON.stringify(event, null, 2)}\n`,
+    stdio: ["pipe", "pipe", "pipe"],
+    timeout: 30000,
+  });
+
+  if (result.status === 0) {
+    const url = result.stdout.trim();
+    if (url.length > 0) {
+      return url;
+    }
+  }
+
+  const error = (result.stderr || result.stdout || "").trim();
+  if (error.length > 0) {
+    console.error(`[warn] gist creation failed: ${error}`);
+  }
+  return undefined;
+}
+
+// ============================================================================
+// Slack Integration
+// ============================================================================
+
+interface SlackPostOptions {
+  agent: AgentIdentity;
+  channel: string;
+  workspace: string;
+  text: string;
+}
+
+function postToSlack(options: SlackPostOptions): ExecResult {
+  const args = [
+    "agent",
+    "post",
+    "--agent",
+    options.agent,
+    "--channel",
+    options.channel,
+    "--text",
+    options.text,
+    "-w",
+    options.workspace,
+  ];
+
+  return execCommand("slack", args);
+}
+
+// ============================================================================
+// Messages Integration
+// ============================================================================
+
+interface MessagesSendOptions {
+  to: string;
+  text: string;
+}
+
+function sendMessage(options: MessagesSendOptions): ExecResult {
+  const args = ["send", options.to, options.text];
+
+  return execCommand("messages", args);
+}
+
+// ============================================================================
+// Remote Reporting Integration
+// ============================================================================
+
+interface RemoteReportResult {
+  success: boolean;
+  error?: string;
+}
+
+/**
+ * Optional remote reporting.
+ *
+ * Client-agnostic sink that can be configured via:
+ * - AGENTS_REPORT_URL: HTTP endpoint that receives JSON via POST
+ * - AGENTS_REPORT_CMD: shell command that receives JSON on stdin
+ *
+ * If both are set, AGENTS_REPORT_CMD takes precedence.
+ *
+ * Non-blocking: warns on failure, doesn't break flow.
+ */
+async function reportToRemote(
+  action: ReportAction,
+  message: string,
+  options: ReportOptions,
+): Promise<RemoteReportResult> {
+  const reportUrl = process.env.AGENTS_REPORT_URL;
+  const reportCmd = process.env.AGENTS_REPORT_CMD;
+
+  if (!reportUrl && !reportCmd) {
+    return { success: true };
+  }
+
+  const agent = options.agent ?? detectAgent();
+  const now = Date.now();
+
+  const traceId = options.traceId ?? "";
+  const sessionId = process.env.AGENTS_REPORT_SESSION_ID || traceId || `tr_${now}`;
+
+  const payload = {
+    version: 1,
+    sessionId,
+    traceId,
+    action,
+    agent,
+    message,
+    confidence: options.confidence,
+    timestamp: now,
+  };
+
+  if (reportCmd) {
+    const result = spawnSync("bash", ["-lc", reportCmd], {
+      encoding: "utf-8",
+      input: JSON.stringify(payload),
+      timeout: 1500,
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+
+    if (result.status === 0) {
+      return { success: true };
+    }
+
+    const stderr = (result.stderr || result.stdout || "").trim();
+    return {
+      success: false,
+      error: stderr
+        ? `AGENTS_REPORT_CMD failed: ${stderr}`
+        : `AGENTS_REPORT_CMD failed (exit ${result.status})`,
+    };
+  }
+
+  // HTTP sink (reportUrl must be defined here since we passed the early return)
+  if (!reportUrl) {
+    return { success: true };
+  }
+
+  try {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), 1500);
+
+    const response = await fetch(reportUrl, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(payload),
+      signal: controller.signal,
+    });
+
+    clearTimeout(timeoutId);
+
+    if (!response.ok) {
+      return { success: false, error: `AGENTS_REPORT_URL HTTP ${response.status}` };
+    }
+
+    return { success: true };
+  } catch (err) {
+    return {
+      success: false,
+      error: err instanceof Error ? err.message : String(err),
+    };
+  }
+}
+
+// ============================================================================
+// Report Formatting
+// ============================================================================
+
+function formatReportMessage(
+  action: ReportAction,
+  message: string,
+  options: ReportOptions,
+): string {
+  const emoji = {
+    started: "🚀",
+    progress: "📍",
+    completed: "✅",
+    blocked: "🔴",
+  }[action];
+
+  const actionText = {
+    started: "starting",
+    progress: "progress",
+    completed: "done",
+    blocked: "blocked",
+  }[action];
+
+  let text = `${emoji} ${actionText}: ${message}`;
+
+  if (options.confidence !== undefined) {
+    text += ` (confidence: ${options.confidence}/10)`;
+  }
+
+  return text;
+}
+
+// ============================================================================
+// Core Report Functions
+// ============================================================================
+
+/**
+ * Report: start - begin a new trace
+ *
+ * - Always generates new trace ID
+ * - Persists to Convex reports
+ * - Posts to #agents
+ * - Optionally DMs (opt-in)
+ */
+export async function reportStart(
+  message: string,
+  options: ReportOptions = {},
+): Promise<ReportResult> {
+  const agent = options.agent ?? detectAgent();
+  const traceId = generateTraceId(); // Always new for start
+  const workspace = options.workspace ?? getDefaultSlackWorkspace();
+  const channel = options.channel ?? "agents";
+  const shouldDm = options.dm === true && !options.noDm;
+
+  const result: ReportResult = {
+    success: true,
+    traceId,
+    agent,
+    action: "started",
+    convex: { success: true },
+    slack: { success: true },
+  };
+
+  const formattedMessage = formatReportMessage("started", message, options);
+
+  if (options.dryRun) {
+    console.error(
+      `[dry-run] convex reports.record --agent ${agent} --trace-id ${traceId} --action started --task "${message}"`,
+    );
+    console.error(
+      `[dry-run] slack agent post -a ${agent} -c ${channel} -w ${workspace} --text "${formattedMessage}"`,
+    );
+    if (shouldDm) {
+      console.error(`[dry-run] messages send luke "${formattedMessage}"`);
+    }
+    return result;
+  }
+
+  // 1. Persist to Convex (critical - fail hard)
+  const convexResult = await recordToConvex({
+    agent,
+    traceId,
+    action: "started",
+    task: message,
+    confidence: options.confidence,
+  });
+
+  if (!convexResult.success) {
+    result.convex = { success: false, error: convexResult.error };
+    result.success = false;
+    return result; // Fail fast - persistence is critical
+  }
+
+  // 2. Post to slack (warn + continue)
+  const slackResult = postToSlack({
+    agent,
+    channel,
+    workspace,
+    text: formattedMessage,
+  });
+
+  if (!slackResult.success) {
+    result.slack = { success: false, error: slackResult.error };
+    console.error(`[warn] slack post failed: ${slackResult.error}`);
+  }
+
+  // 3. DM if requested (warn + continue)
+  if (shouldDm) {
+    const msgResult = sendMessage({
+      to: "luke",
+      text: formattedMessage,
+    });
+
+    result.messages = {
+      success: msgResult.success,
+      error: msgResult.error,
+    };
+
+    if (!msgResult.success) {
+      console.error(`[warn] iMessage failed: ${msgResult.error}`);
+    }
+  }
+
+  // 4. Optional remote reporting (warn + continue)
+  const remoteResult = await reportToRemote("started", message, {
+    ...options,
+    agent,
+    traceId,
+  });
+
+  if (remoteResult.success) {
+    result.remote = { success: true };
+  } else {
+    result.remote = { success: false, error: remoteResult.error };
+    console.error(`[warn] remote report failed: ${remoteResult.error}`);
+  }
+
+  return result;
+}
+
+/**
+ * Report: progress - update on ongoing trace
+ *
+ * - Inherits trace ID from env or requires explicit
+ * - Persists to Convex reports
+ * - Posts to #agents
+ * - Optionally DMs (opt-in)
+ */
+export async function reportProgress(
+  message: string,
+  options: ReportOptions = {},
+): Promise<ReportResult> {
+  const agent = options.agent ?? detectAgent();
+  const traceId = options.traceId ?? getOrCreateTraceId();
+  const workspace = options.workspace ?? getDefaultSlackWorkspace();
+  const channel = options.channel ?? "agents";
+  const shouldDm = options.dm === true && !options.noDm;
+
+  const result: ReportResult = {
+    success: true,
+    traceId,
+    agent,
+    action: "progress",
+    convex: { success: true },
+    slack: { success: true },
+  };
+
+  const formattedMessage = formatReportMessage("progress", message, options);
+
+  if (options.dryRun) {
+    console.error(
+      `[dry-run] convex reports.record --agent ${agent} --trace-id ${traceId} --action progress --task "${message}"`,
+    );
+    console.error(
+      `[dry-run] slack agent post -a ${agent} -c ${channel} -w ${workspace} --text "${formattedMessage}"`,
+    );
+    if (shouldDm) {
+      console.error(`[dry-run] messages send luke "${formattedMessage}"`);
+    }
+    return result;
+  }
+
+  // 1. Persist to Convex (critical)
+  const convexResult = await recordToConvex({
+    agent,
+    traceId,
+    action: "progress",
+    task: message,
+    confidence: options.confidence,
+  });
+
+  if (!convexResult.success) {
+    result.convex = { success: false, error: convexResult.error };
+    result.success = false;
+    return result;
+  }
+
+  // 2. Post to slack
+  const slackResult = postToSlack({
+    agent,
+    channel,
+    workspace,
+    text: formattedMessage,
+  });
+
+  if (!slackResult.success) {
+    result.slack = { success: false, error: slackResult.error };
+    console.error(`[warn] slack post failed: ${slackResult.error}`);
+  }
+
+  // 3. DM if requested
+  if (shouldDm) {
+    const msgResult = sendMessage({
+      to: "luke",
+      text: formattedMessage,
+    });
+
+    result.messages = {
+      success: msgResult.success,
+      error: msgResult.error,
+    };
+
+    if (!msgResult.success) {
+      console.error(`[warn] iMessage failed: ${msgResult.error}`);
+    }
+  }
+
+  // 4. Optional remote reporting (warn + continue)
+  const remoteResult = await reportToRemote("progress", message, {
+    ...options,
+    agent,
+    traceId,
+  });
+
+  if (remoteResult.success) {
+    result.remote = { success: true };
+  } else {
+    result.remote = { success: false, error: remoteResult.error };
+    console.error(`[warn] remote report failed: ${remoteResult.error}`);
+  }
+
+  return result;
+}
+
+/**
+ * Report: complete - finalize a trace
+ *
+ * - Inherits trace ID from env or requires explicit
+ * - Persists to Convex reports with artifacts
+ * - Posts to #agents
+ * - Optionally DMs (opt-in)
+ */
+export async function reportComplete(
+  message: string,
+  options: ReportOptions = {},
+): Promise<ReportResult> {
+  const agent = options.agent ?? detectAgent();
+  const traceId = options.traceId ?? getOrCreateTraceId();
+  const workspace = options.workspace ?? getDefaultSlackWorkspace();
+  const channel = options.channel ?? "agents";
+  const shouldDm = options.dm === true && !options.noDm;
+
+  const result: ReportResult = {
+    success: true,
+    traceId,
+    agent,
+    action: "completed",
+    convex: { success: true },
+    slack: { success: true },
+  };
+
+  const formattedMessage = formatReportMessage("completed", message, options);
+
+  if (options.dryRun) {
+    console.error(
+      `[dry-run] convex reports.record --agent ${agent} --trace-id ${traceId} --action completed --task "${message}"`,
+    );
+    console.error(
+      `[dry-run] slack agent post -a ${agent} -c ${channel} -w ${workspace} --text "${formattedMessage}"`,
+    );
+    if (shouldDm) {
+      console.error(`[dry-run] messages send luke "${formattedMessage}"`);
+    }
+    return result;
+  }
+
+  // 1. Persist to Convex (critical)
+  const convexResult = await recordToConvex({
+    agent,
+    traceId,
+    action: "completed",
+    task: message,
+    confidence: options.confidence,
+    artifacts: options.artifacts,
+    gist: options.gist,
+    gistDescription: options.gistDescription,
+    gistPublic: options.gistPublic,
+  });
+
+  if (!convexResult.success) {
+    result.convex = { success: false, error: convexResult.error };
+    result.success = false;
+    return result;
+  }
+
+  // Extract gist URL from Convex output if present
+  if (options.gist && convexResult.stdout) {
+    try {
+      const convexOutput = JSON.parse(convexResult.stdout);
+      if (convexOutput.gist_url) {
+        result.gistUrl = convexOutput.gist_url;
+      }
+    } catch {
+      // JSON parse failed, gist URL won't be available in result
+    }
+  }
+
+  // 2. Post to slack
+  const slackResult = postToSlack({
+    agent,
+    channel,
+    workspace,
+    text: formattedMessage,
+  });
+
+  if (!slackResult.success) {
+    result.slack = { success: false, error: slackResult.error };
+    console.error(`[warn] slack post failed: ${slackResult.error}`);
+  }
+
+  // 3. DM if requested
+  if (shouldDm) {
+    const msgResult = sendMessage({
+      to: "luke",
+      text: formattedMessage,
+    });
+
+    result.messages = {
+      success: msgResult.success,
+      error: msgResult.error,
+    };
+
+    if (!msgResult.success) {
+      console.error(`[warn] iMessage failed: ${msgResult.error}`);
+    }
+  }
+
+  // 4. Optional remote reporting (warn + continue)
+  const remoteResult = await reportToRemote("completed", message, {
+    ...options,
+    agent,
+    traceId,
+  });
+
+  if (remoteResult.success) {
+    result.remote = { success: true };
+  } else {
+    result.remote = { success: false, error: remoteResult.error };
+    console.error(`[warn] remote report failed: ${remoteResult.error}`);
+  }
+
+  return result;
+}
+
+/**
+ * Report: blocked - report a blocker
+ *
+ * - Inherits trace ID from env or requires explicit
+ * - Persists to Convex reports with blocker type
+ * - Posts to #agents
+ * - DMs by default (can be suppressed with --no-dm)
+ */
+export async function reportBlocked(
+  message: string,
+  options: ReportOptions = {},
+): Promise<ReportResult> {
+  const agent = options.agent ?? detectAgent();
+  const traceId = options.traceId ?? getOrCreateTraceId();
+  const workspace = options.workspace ?? getDefaultSlackWorkspace();
+  const channel = options.channel ?? "agents";
+  // Default to DM for blocked (unless explicitly disabled)
+  const shouldDm = options.noDm !== true;
+
+  const result: ReportResult = {
+    success: true,
+    traceId,
+    agent,
+    action: "blocked",
+    convex: { success: true },
+    slack: { success: true },
+  };
+
+  const formattedMessage = formatReportMessage("blocked", message, options);
+
+  if (options.dryRun) {
+    console.error(
+      `[dry-run] convex reports.record --agent ${agent} --trace-id ${traceId} --action blocked --task "${message}"`,
+    );
+    console.error(
+      `[dry-run] slack agent post -a ${agent} -c ${channel} -w ${workspace} --text "${formattedMessage}"`,
+    );
+    if (shouldDm) {
+      console.error(`[dry-run] messages send luke "${formattedMessage}"`);
+    }
+    return result;
+  }
+
+  // 1. Persist to Convex (critical)
+  const convexResult = await recordToConvex({
+    agent,
+    traceId,
+    action: "blocked",
+    task: message,
+    confidence: options.confidence,
+    blockerType: options.blockerType ?? "hil",
+  });
+
+  if (!convexResult.success) {
+    result.convex = { success: false, error: convexResult.error };
+    result.success = false;
+    return result;
+  }
+
+  // 2. Post to slack
+  const slackResult = postToSlack({
+    agent,
+    channel,
+    workspace,
+    text: formattedMessage,
+  });
+
+  if (!slackResult.success) {
+    result.slack = { success: false, error: slackResult.error };
+    console.error(`[warn] slack post failed: ${slackResult.error}`);
+  }
+
+  // 3. DM (default for blocked)
+  if (shouldDm) {
+    const msgResult = sendMessage({
+      to: "luke",
+      text: formattedMessage,
+    });
+
+    result.messages = {
+      success: msgResult.success,
+      error: msgResult.error,
+    };
+
+    if (!msgResult.success) {
+      console.error(`[warn] iMessage failed: ${msgResult.error}`);
+    }
+  }
+
+  // 4. Optional remote reporting (warn + continue)
+  const remoteResult = await reportToRemote("blocked", message, {
+    ...options,
+    agent,
+    traceId,
+  });
+
+  if (remoteResult.success) {
+    result.remote = { success: true };
+  } else {
+    result.remote = { success: false, error: remoteResult.error };
+    console.error(`[warn] remote report failed: ${remoteResult.error}`);
+  }
+
+  return result;
+}
+
+// ============================================================================
+// Unified Report Function
+// ============================================================================
+
+/**
+ * Unified report function - dispatch to appropriate handler
+ */
+export async function report(
+  action: ReportAction,
+  message: string,
+  options: ReportOptions = {},
+): Promise<ReportResult> {
+  switch (action) {
+    case "started":
+      return reportStart(message, options);
+    case "progress":
+      return reportProgress(message, options);
+    case "completed":
+      return reportComplete(message, options);
+    case "blocked":
+      return reportBlocked(message, options);
+    default:
+      throw new Error(`Unknown action: ${action}`);
+  }
+}