@creativeintelligence/abbie 0.1.3 → 0.1.5

package/src/lib/agent-trace.ts

@@ -1,513 +0,0 @@
-/**
- * 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

@@ -1,178 +0,0 @@
-/**
- * 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");
-}