@creativeintelligence/abbie 0.1.0

package/dist/lib/report.js

@@ -0,0 +1,686 @@
+/**
+ * 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";
+// ============================================================================
+// Agent Identity Detection
+// ============================================================================
+/**
+ * Detect agent identity from session environment variables
+ */
+export function detectAgent() {
+    // 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 = ["claude", "codex", "gemini", "copilot"];
+        if (known.includes(agentName)) {
+            return agentName;
+        }
+    }
+    // Fallback to custom identity
+    return "custom";
+}
+// ============================================================================
+// Trace ID Management
+// ============================================================================
+/**
+ * Generate a new trace ID
+ */
+export function generateTraceId() {
+    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) {
+    if (!forceNew && process.env.AGENTS_TRACE_ID) {
+        return process.env.AGENTS_TRACE_ID;
+    }
+    return generateTraceId();
+}
+function execCommand(command, args) {
+    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),
+        };
+    }
+}
+function resolveSessionId() {
+    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) {
+    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 = {
+            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 = { ...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, options) {
+    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;
+}
+function postToSlack(options) {
+    const args = [
+        "agent",
+        "post",
+        "--agent",
+        options.agent,
+        "--channel",
+        options.channel,
+        "--text",
+        options.text,
+        "-w",
+        options.workspace,
+    ];
+    return execCommand("slack", args);
+}
+function sendMessage(options) {
+    const args = ["send", options.to, options.text];
+    return execCommand("messages", args);
+}
+/**
+ * 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, message, options) {
+    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, message, options) {
+    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, options = {}) {
+    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 = {
+        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, options = {}) {
+    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 = {
+        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, options = {}) {
+    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 = {
+        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, options = {}) {
+    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 = {
+        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, message, options = {}) {
+    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}`);
+    }
+}