@creativeintelligence/abbie 0.1.0

package/src/lib/agent-trace.ts

@@ -0,0 +1,513 @@
+/**
+ * Agent Trace v0.1 interoperability layer.
+ *
+ * Maps Abbie canonical session data (replay, correlations, mined sessions)
+ * to the Agent Trace JSON schema (https://github.com/cursor/agent-trace).
+ *
+ * Design:
+ * - Abbie internal schema remains canonical; Agent Trace is interchange format
+ * - Provider/model/agent-agnostic: model_id uses models.dev convention when available
+ * - Braintrust correlation preserved in metadata
+ * - Storage-agnostic: outputs JSON; caller decides where to persist
+ */
+
+import * as childProcess from "node:child_process";
+import { createHash, randomUUID } from "node:crypto";
+import * as fs from "node:fs";
+import { join } from "node:path";
+
+// ============================================================================
+// Agent Trace v0.1 types (from cursor/agent-trace spec)
+// ============================================================================
+
+export interface AgentTrace {
+  version: string;
+  id: string;
+  timestamp: string;
+  files: AgentTraceFile[];
+  vcs?: AgentTraceVcs;
+  tool?: AgentTraceTool;
+  metadata?: Record<string, unknown>;
+}
+
+export interface AgentTraceFile {
+  path: string;
+  conversations: AgentTraceConversation[];
+}
+
+export interface AgentTraceRelated {
+  type: string;
+  url: string;
+}
+
+export interface AgentTraceConversation {
+  url?: string;
+  contributor?: AgentTraceContributor;
+  ranges: AgentTraceRange[];
+  related?: AgentTraceRelated[];
+}
+
+export interface AgentTraceContributor {
+  type: "human" | "ai" | "mixed" | "unknown";
+  model_id?: string;
+}
+
+export interface AgentTraceRange {
+  start_line: number;
+  end_line: number;
+  content_hash?: string;
+  contributor?: AgentTraceContributor;
+}
+
+export interface AgentTraceVcs {
+  type: "git" | "jj" | "hg" | "svn";
+  revision: string;
+}
+
+export interface AgentTraceTool {
+  name: string;
+  version: string;
+}
+
+// ============================================================================
+// Abbie canonical types (inputs to mapping)
+// ============================================================================
+
+export interface AbbieSessionData {
+  sessionId: string;
+  agent: string;
+  project: string | null;
+  status: string;
+  startedAt: string;
+  endedAt?: string | null;
+  traceId?: string;
+  traceUrl?: string;
+  issue?: string;
+  branch?: string;
+  commits?: string[];
+  filesModified?: string[];
+  model?: string;
+  cwd?: string;
+}
+
+const UUID_V4_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+
+// ============================================================================
+// Agent → model_id mapping (models.dev convention)
+// ============================================================================
+
+/**
+ * Map agent type + optional model hint to a models.dev identifier.
+ * Returns undefined if the model cannot be determined (preserves agnosticity).
+ */
+function resolveModelId(_agent: string, model?: string): string | undefined {
+  // If a model hint was explicitly provided, use it directly
+  if (model) return model;
+
+  // Agent type alone is not enough to determine model — return undefined
+  // This avoids hardcoding vendor assumptions
+  return undefined;
+}
+
+function isValidUri(value: string): boolean {
+  try {
+    const parsed = new URL(value);
+    return parsed.protocol === "http:" || parsed.protocol === "https:";
+  } catch {
+    return false;
+  }
+}
+
+function parsePackageVersion(): string {
+  try {
+    const pkgRaw = fs.readFileSync(new URL("../../package.json", import.meta.url), "utf-8");
+    const pkg = JSON.parse(pkgRaw) as { version?: unknown };
+    return typeof pkg.version === "string" ? pkg.version : "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+}
+
+function lineCountForFile(cwd: string | undefined, filePath: string): number {
+  if (!cwd) return 1;
+
+  const absolute = join(cwd, filePath);
+  if (!fs.existsSync(absolute)) return 1;
+
+  try {
+    const content = fs.readFileSync(absolute, "utf-8");
+    if (content.length === 0) return 1;
+    return content.split(/\r\n|\n|\r/).length;
+  } catch {
+    return 1;
+  }
+}
+
+function inferFileRange(cwd: string | undefined, filePath: string): AgentTraceRange {
+  return {
+    start_line: 1,
+    end_line: lineCountForFile(cwd, filePath),
+  };
+}
+
+function parseDiffRanges(diffOutput: string): AgentTraceRange[] {
+  const ranges: AgentTraceRange[] = [];
+  const lines = diffOutput.split(/\r\n|\n|\r/);
+
+  for (const line of lines) {
+    // Unified diff hunk header:
+    // @@ -a,b +c,d @@
+    // d can be 0 for pure deletions.
+    const match = line.match(/^@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@/);
+    if (!match) continue;
+
+    const start = Number.parseInt(match[1], 10);
+    const length = match[2] === undefined ? 1 : Number.parseInt(match[2], 10);
+
+    if (!Number.isInteger(start) || !Number.isInteger(length)) continue;
+    if (start < 1 || length < 0) continue;
+
+    const end = length === 0 ? start : start + length - 1;
+    ranges.push({ start_line: start, end_line: end });
+  }
+
+  return ranges;
+}
+
+function getChangedRanges(
+  cwd: string | undefined,
+  filePath: string,
+): AgentTraceRange[] | undefined {
+  if (!cwd) return undefined;
+
+  try {
+    const diff = childProcess.execFileSync(
+      "git",
+      ["diff", "--unified=0", "--no-color", "--", filePath],
+      {
+        cwd,
+        encoding: "utf-8",
+        stdio: ["ignore", "pipe", "ignore"],
+      },
+    );
+
+    if (!diff.trim()) return undefined;
+
+    const parsed = parseDiffRanges(diff);
+    return parsed.length > 0 ? parsed : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function hashRangeContent(
+  cwd: string | undefined,
+  filePath: string,
+  range: AgentTraceRange,
+): string | undefined {
+  if (!cwd) return undefined;
+
+  const absolute = join(cwd, filePath);
+  if (!fs.existsSync(absolute)) return undefined;
+
+  try {
+    const content = fs.readFileSync(absolute, "utf-8");
+    const lines = content.split(/\r\n|\n|\r/);
+    const start = Math.max(1, range.start_line);
+    const end = Math.max(start, range.end_line);
+    const slice = lines.slice(start - 1, end);
+    const payload = slice.join("\n");
+    return createHash("sha256").update(payload).digest("hex");
+  } catch {
+    return undefined;
+  }
+}
+
+function inferFileRanges(cwd: string | undefined, filePath: string): AgentTraceRange[] {
+  const ranges = getChangedRanges(cwd, filePath) ?? [inferFileRange(cwd, filePath)];
+
+  return ranges.map((range) => {
+    const contentHash = hashRangeContent(cwd, filePath, range);
+    if (!contentHash) return range;
+    return { ...range, content_hash: contentHash };
+  });
+}
+
+function pushContributorErrors(errors: string[], prefix: string, contributor: unknown): void {
+  if (typeof contributor !== "object" || contributor === null || Array.isArray(contributor)) {
+    errors.push(`${prefix}: must be an object`);
+    return;
+  }
+
+  const c = contributor as Record<string, unknown>;
+  if (!["human", "ai", "mixed", "unknown"].includes(c.type as string)) {
+    errors.push(`${prefix}.type: must be 'human'|'ai'|'mixed'|'unknown'`);
+  }
+
+  if (c.model_id !== undefined) {
+    if (typeof c.model_id !== "string") {
+      errors.push(`${prefix}.model_id: must be a string`);
+    } else if (c.model_id.length > 250) {
+      errors.push(`${prefix}.model_id: must be <= 250 chars`);
+    }
+  }
+}
+
+// ============================================================================
+// Mapping functions
+// ============================================================================
+
+/**
+ * Get VCS metadata from the working directory.
+ * Returns null if not in a git repo or git is unavailable.
+ */
+function getVcsInfo(cwd?: string): AgentTraceVcs | undefined {
+  if (!cwd) return undefined;
+
+  try {
+    const revision = childProcess
+      .execSync("git rev-parse HEAD", {
+        cwd,
+        encoding: "utf-8",
+        stdio: ["pipe", "pipe", "pipe"],
+      })
+      .trim();
+
+    if (revision && /^[0-9a-f]{40}$/.test(revision)) {
+      return { type: "git", revision };
+    }
+  } catch {
+    // Not in a git repo or git not available
+  }
+
+  return undefined;
+}
+
+/**
+ * Get the abbie CLI version from package.json.
+ */
+function getToolInfo(): AgentTraceTool {
+  return { name: "abbie", version: parsePackageVersion() };
+}
+
+/**
+ * Map an Abbie session to an Agent Trace record.
+ *
+ * Current limitations:
+ * - Falls back to whole-file [1..N] ranges when git diff metadata is unavailable
+ * - conversation URL uses linear issue URL when available
+ * - model_id only populated when explicitly known
+ */
+export function mapToAgentTrace(session: AbbieSessionData): AgentTrace {
+  const modelId = resolveModelId(session.agent, session.model);
+
+  const contributor: AgentTraceContributor = {
+    type: "ai",
+    ...(modelId ? { model_id: modelId } : {}),
+  };
+
+  // Map files to Agent Trace file objects
+  const files: AgentTraceFile[] = (session.filesModified ?? []).map((filePath) => {
+    const related: AgentTraceRelated[] = [];
+    if (session.traceUrl) {
+      related.push({ type: "trace", url: session.traceUrl });
+    }
+
+    return {
+      path: filePath,
+      conversations: [
+        {
+          ...(session.issue ? { url: `https://linear.app/issue/${session.issue}` } : {}),
+          contributor,
+          ranges: inferFileRanges(session.cwd, filePath),
+          ...(related.length > 0 ? { related } : {}),
+        },
+      ],
+    };
+  });
+
+  // Build metadata with Abbie-specific + Braintrust fields
+  const metadata: Record<string, unknown> = {
+    "abbie:session_id": session.sessionId,
+    "abbie:agent": session.agent,
+    "abbie:status": session.status,
+    ...(session.traceId ? { "abbie:trace_id": session.traceId } : {}),
+    ...(session.project ? { "abbie:project": session.project } : {}),
+    ...(session.issue ? { "abbie:issue": session.issue } : {}),
+    ...(session.branch ? { "abbie:branch": session.branch } : {}),
+    ...(session.commits?.length ? { "abbie:commits": session.commits } : {}),
+    ...(session.startedAt ? { "abbie:started_at": session.startedAt } : {}),
+    ...(session.endedAt ? { "abbie:ended_at": session.endedAt } : {}),
+    // Braintrust correlation
+    ...(session.traceUrl ? { "braintrust:trace_url": session.traceUrl } : {}),
+  };
+
+  const vcs = getVcsInfo(session.cwd);
+
+  return {
+    version: "0.1.0",
+    id: randomUUID(),
+    timestamp: session.endedAt || session.startedAt || new Date().toISOString(),
+    files,
+    ...(vcs ? { vcs } : {}),
+    tool: getToolInfo(),
+    metadata,
+  };
+}
+
+// ============================================================================
+// Validation
+// ============================================================================
+
+/**
+ * Validate an Agent Trace record against the v0.1 schema.
+ * Returns errors array (empty = valid).
+ */
+export function validateAgentTrace(trace: unknown): string[] {
+  const errors: string[] = [];
+
+  if (typeof trace !== "object" || trace === null || Array.isArray(trace)) {
+    return ["Root must be a JSON object"];
+  }
+
+  const obj = trace as Record<string, unknown>;
+
+  // Required: version
+  if (typeof obj.version !== "string") {
+    errors.push("Missing required field 'version' (string)");
+  } else if (obj.version !== "0.1.0") {
+    errors.push(`Unsupported version '${obj.version}', expected '0.1.0'`);
+  }
+
+  // Required: id (uuid)
+  if (typeof obj.id !== "string" || !UUID_V4_RE.test(obj.id)) {
+    errors.push("Missing or invalid required field 'id' (UUID v4 string)");
+  }
+
+  // Required: timestamp
+  if (typeof obj.timestamp !== "string") {
+    errors.push("Missing required field 'timestamp' (RFC 3339 date-time)");
+  } else if (Number.isNaN(Date.parse(obj.timestamp))) {
+    errors.push("Invalid timestamp format (expected RFC 3339)");
+  }
+
+  // Required: files
+  if (!Array.isArray(obj.files)) {
+    errors.push("Missing required field 'files' (array)");
+  } else {
+    for (let i = 0; i < obj.files.length; i++) {
+      const file = obj.files[i] as Record<string, unknown>;
+      if (typeof file?.path !== "string") {
+        errors.push(`files[${i}]: missing 'path' (string)`);
+      }
+
+      if (!Array.isArray(file?.conversations)) {
+        errors.push(`files[${i}]: missing 'conversations' (array)`);
+        continue;
+      }
+
+      for (let j = 0; j < file.conversations.length; j++) {
+        const conv = file.conversations[j] as Record<string, unknown>;
+
+        if (conv.url !== undefined && (typeof conv.url !== "string" || !isValidUri(conv.url))) {
+          errors.push(`files[${i}].conversations[${j}].url: must be a valid URI`);
+        }
+
+        if (conv.contributor !== undefined) {
+          pushContributorErrors(
+            errors,
+            `files[${i}].conversations[${j}].contributor`,
+            conv.contributor,
+          );
+        }
+
+        if (!Array.isArray(conv.ranges) || conv.ranges.length === 0) {
+          errors.push(`files[${i}].conversations[${j}]: missing 'ranges' (non-empty array)`);
+        } else {
+          for (let k = 0; k < conv.ranges.length; k++) {
+            const range = conv.ranges[k] as Record<string, unknown>;
+            const start = range.start_line;
+            const end = range.end_line;
+
+            if (!Number.isInteger(start) || (start as number) < 1) {
+              errors.push(`files[${i}].conversations[${j}].ranges[${k}].start_line: must be >= 1`);
+            }
+            if (!Number.isInteger(end) || (end as number) < 1) {
+              errors.push(`files[${i}].conversations[${j}].ranges[${k}].end_line: must be >= 1`);
+            }
+            if (
+              Number.isInteger(start) &&
+              Number.isInteger(end) &&
+              (end as number) < (start as number)
+            ) {
+              errors.push(
+                `files[${i}].conversations[${j}].ranges[${k}]: end_line must be >= start_line`,
+              );
+            }
+
+            if (range.content_hash !== undefined && typeof range.content_hash !== "string") {
+              errors.push(
+                `files[${i}].conversations[${j}].ranges[${k}].content_hash: must be a string`,
+              );
+            }
+
+            if (range.contributor !== undefined) {
+              pushContributorErrors(
+                errors,
+                `files[${i}].conversations[${j}].ranges[${k}].contributor`,
+                range.contributor,
+              );
+            }
+          }
+        }
+
+        if (conv.related !== undefined) {
+          if (!Array.isArray(conv.related)) {
+            errors.push(`files[${i}].conversations[${j}].related: must be an array`);
+          } else {
+            for (let k = 0; k < conv.related.length; k++) {
+              const rel = conv.related[k] as Record<string, unknown>;
+              if (typeof rel?.type !== "string" || rel.type.length === 0) {
+                errors.push(`files[${i}].conversations[${j}].related[${k}].type: required`);
+              }
+              if (typeof rel?.url !== "string" || !isValidUri(rel.url)) {
+                errors.push(
+                  `files[${i}].conversations[${j}].related[${k}].url: must be a valid URI`,
+                );
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+
+  // Optional: vcs
+  if (obj.vcs !== undefined) {
+    const vcs = obj.vcs as Record<string, unknown>;
+    if (!["git", "jj", "hg", "svn"].includes(vcs.type as string)) {
+      errors.push("vcs.type must be 'git'|'jj'|'hg'|'svn'");
+    }
+    if (typeof vcs.revision !== "string") {
+      errors.push("vcs.revision must be a string");
+    } else if (vcs.type === "git" && !/^[0-9a-f]{40}$/i.test(vcs.revision)) {
+      errors.push("vcs.revision must be a 40-char SHA when vcs.type is git");
+    }
+  }
+
+  // Optional: tool
+  if (obj.tool !== undefined) {
+    const tool = obj.tool as Record<string, unknown>;
+    if (typeof tool.name !== "string") errors.push("tool.name must be a string");
+    if (typeof tool.version !== "string") errors.push("tool.version must be a string");
+  }
+
+  // Optional: metadata
+  if (obj.metadata !== undefined) {
+    if (typeof obj.metadata !== "object" || obj.metadata === null || Array.isArray(obj.metadata)) {
+      errors.push("metadata must be an object");
+    }
+  }
+
+  return errors;
+}

package/src/lib/analytics.ts

@@ -0,0 +1,178 @@
+/**
+ * Analytics integration for the abbie CLI.
+ *
+ * `analytics` is a first-class dependency of `abbie` and provides a shared,
+ * privacy-safe PostHog client for the whole local CLI ecosystem.
+ *
+ * Usage:
+ *   import { initAnalytics, telemetry, registerShutdown } from '../lib/analytics.js';
+ *   await initAnalytics();
+ *   telemetry.trackCommand('session start', { success: true, duration_ms: 150 });
+ */
+
+import { createHash } from "node:crypto";
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+
+// Type definitions for telemetry interface
+interface TelemetryClient {
+  init(opts: { cli: string; version?: string; sessionId?: string }): Promise<void>;
+  trackCommand(command: string, properties?: Record<string, unknown>): void;
+  trackSession(action: string, properties?: Record<string, unknown>): void;
+  trackSkill(skillName: string, properties?: Record<string, unknown>): void;
+  trackError(errorType: string, properties?: Record<string, unknown>): void;
+  trackEscalation(fromAgent: string, toAgent: string, reason: string): void;
+  setProperties(props: Record<string, unknown>): void;
+  isEnabled(): boolean;
+  shutdown(): Promise<void>;
+}
+
+let initialized = false;
+let initPromise: Promise<void> | null = null;
+let _telemetry: TelemetryClient | null = null;
+
+/**
+ * Find the analytics client path. Tries several locations.
+ */
+function findAnalyticsClientPath(): string | null {
+  const possiblePaths = [
+    // Sibling package in utils
+    join(import.meta.dirname, "../../../analytics/dist/lib/client.js"),
+    // Global install
+    "/Users/luke/Developer/utils/analytics/dist/lib/client.js",
+  ];
+
+  for (const p of possiblePaths) {
+    if (existsSync(p)) {
+      return p;
+    }
+  }
+  return null;
+}
+
+/**
+ * Get the package version from package.json.
+ */
+async function getVersion(): Promise<string | undefined> {
+  try {
+    const pkgPath = join(import.meta.dirname, "../../package.json");
+    const content = await readFile(pkgPath, "utf-8");
+    const pkg = JSON.parse(content);
+    return pkg.version;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Initialize analytics. Safe to call multiple times.
+ * Returns quickly if already initialized or analytics unavailable.
+ */
+export async function initAnalytics(): Promise<void> {
+  if (initialized) return;
+  if (initPromise) return initPromise;
+
+  initPromise = (async () => {
+    try {
+      const clientPath = findAnalyticsClientPath();
+      if (!clientPath) {
+        // Analytics not available - silent no-op
+        return;
+      }
+
+      const mod = await import(pathToFileURL(clientPath).href);
+      const version = await getVersion();
+      await mod.telemetry.init({
+        cli: "agents",
+        version,
+        sessionId: process.env.AGENTS_SESSION_ID,
+      });
+      _telemetry = mod.telemetry as TelemetryClient;
+      initialized = true;
+    } catch {
+      // Analytics init failed - silent no-op
+    }
+  })();
+
+  return initPromise;
+}
+
+/**
+ * No-op telemetry for when analytics is unavailable.
+ */
+const noopTelemetry: TelemetryClient = {
+  init: async () => {},
+  trackCommand: () => {},
+  trackSession: () => {},
+  trackSkill: () => {},
+  trackError: () => {},
+  trackEscalation: () => {},
+  setProperties: () => {},
+  isEnabled: () => false,
+  shutdown: async () => {},
+};
+
+/**
+ * Telemetry proxy - returns real telemetry if initialized, no-op otherwise.
+ */
+export const telemetry = new Proxy({} as TelemetryClient, {
+  get: (_target, prop: keyof TelemetryClient) => {
+    const client = _telemetry || noopTelemetry;
+    return client[prop];
+  },
+});
+
+/**
+ * Register shutdown handler. Call once at CLI bootstrap.
+ */
+export function registerShutdown(): void {
+  // Best-effort flush on exit
+  process.on("exit", () => {
+    if (_telemetry) {
+      _telemetry.shutdown().catch(() => {});
+    }
+  });
+
+  // Handle signals for graceful shutdown
+  for (const signal of ["SIGINT", "SIGTERM"] as const) {
+    process.on(signal, () => {
+      if (_telemetry) {
+        _telemetry
+          .shutdown()
+          .then(() => process.exit(0))
+          .catch(() => process.exit(0));
+      } else {
+        process.exit(0);
+      }
+    });
+  }
+}
+
+/**
+ * Check if analytics is enabled.
+ */
+export function isAnalyticsEnabled(): boolean {
+  return _telemetry?.isEnabled() ?? false;
+}
+
+/**
+ * Detect project from environment or cwd.
+ * Returns undefined if no project can be detected.
+ */
+export function detectProject(): string | undefined {
+  if (process.env.AGENTS_PROJECT) return process.env.AGENTS_PROJECT;
+  const cwd = process.cwd();
+  const match = cwd.match(/Developer\/(?:apps|utils)\/([^/]+)/);
+  return match?.[1];
+}
+
+/**
+ * Hash a string for privacy-safe telemetry.
+ * Takes first N chars and returns SHA256 hash.
+ */
+export function hashForTelemetry(text: string, length = 100): string {
+  const truncated = text.slice(0, length);
+  return createHash("sha256").update(truncated).digest("hex");
+}