@creativeintelligence/abbie 0.1.0

package/src/lib/content-sync/types.ts

@@ -0,0 +1,104 @@
+/**
+ * Shared types for the content sync pipeline (rules, skills, hooks).
+ */
+
+/** Content types that can be synced */
+export const CONTENT_TYPES = ["rules", "skills", "hooks"] as const;
+export type ContentType = (typeof CONTENT_TYPES)[number];
+
+/** A rule to sync */
+export type SyncRule = {
+  name: string;
+  content: string;
+  isEnabled: boolean;
+  category?: string;
+  triggers?: string[];
+  summary?: string;
+  lineCount: number;
+  hash: string;
+};
+
+/** A skill to sync */
+export type SyncSkill = {
+  name: string;
+  content: string;
+  isEnabled: boolean;
+  description?: string;
+  triggers?: string[];
+  hasScripts: boolean;
+  hasRefs: boolean;
+  files?: Record<string, string>;
+  lineCount: number;
+  hash: string;
+};
+
+/** A hook to sync */
+export type SyncHook = {
+  name: string;
+  content: string;
+  event: string;
+  platform?: string;
+  isEnabled: boolean;
+  isExecutable: boolean;
+  hash: string;
+};
+
+/** Full content snapshot from Convex */
+export type ContentSnapshot = {
+  rules: SyncRule[];
+  skills: SyncSkill[];
+  hooks: SyncHook[];
+  revision: number;
+  hash: string;
+};
+
+/** Content sync runner state (persisted) */
+export type ContentSyncState = {
+  lastHash: string;
+  lastSuccessAt: number;
+  consecutiveFailures: number;
+  nextRetryAt: number;
+};
+
+/** Per-type manifest tracking what we manage locally */
+export type ContentManifest = {
+  rules?: {
+    managedFiles: string[];
+    lastSyncHash: string;
+    lastSyncAt: number;
+  };
+  skills?: {
+    managedDirs: string[];
+    lastSyncHash: string;
+    lastSyncAt: number;
+  };
+  hooks?: {
+    managedFiles: string[];
+    lastSyncHash: string;
+    lastSyncAt: number;
+  };
+};
+
+/** Result of a sync tick */
+export type ContentSyncTickResult = {
+  ok: boolean;
+  reason: string;
+  dryRun?: boolean;
+  changes: {
+    type: ContentType;
+    action: "created" | "updated" | "removed" | "unchanged" | "error";
+    name: string;
+    error?: string;
+  }[];
+};
+
+/** Result of a push operation */
+export type ContentPushResult = {
+  ok: boolean;
+  pushed: {
+    type: ContentType;
+    name: string;
+    action: "created" | "updated" | "unchanged";
+  }[];
+  errors: { type: ContentType; name: string; error: string }[];
+};

package/src/lib/contracts.test.ts

@@ -0,0 +1,186 @@
+import { describe, expect, it } from "bun:test";
+
+import { getContractTemplate, validateOutputContract } from "./contracts";
+
+describe("validateOutputContract", () => {
+  it("accepts a valid full contract", () => {
+    const result = validateOutputContract({
+      status: "success",
+      summary: "Implemented the feature successfully",
+      confidence: 8,
+      artifacts: [{ type: "code", path: "src/index.ts", action: "modified" }],
+      verification: { commands_run: ["verify --format=summary"], tests_passed: true },
+      commits: [{ hash: "abc1234", message: "feat: add feature" }],
+      next_steps: ["add more tests"],
+      blockers: [],
+    });
+
+    expect(result.valid).toBe(true);
+    expect(result.errors).toHaveLength(0);
+    expect(result.contract).not.toBeNull();
+  });
+
+  it("accepts a minimal valid contract", () => {
+    const result = validateOutputContract({
+      status: "success",
+      summary: "Task completed",
+      confidence: 7,
+    });
+
+    expect(result.valid).toBe(true);
+    expect(result.errors).toHaveLength(0);
+  });
+
+  it("rejects non-object input", () => {
+    expect(validateOutputContract("string").valid).toBe(false);
+    expect(validateOutputContract(null).valid).toBe(false);
+    expect(validateOutputContract([]).valid).toBe(false);
+  });
+
+  it("rejects missing status", () => {
+    const result = validateOutputContract({ summary: "test", confidence: 5 });
+    expect(result.valid).toBe(false);
+    expect(result.errors.some((e) => e.includes("status"))).toBe(true);
+  });
+
+  it("rejects invalid status value", () => {
+    const result = validateOutputContract({
+      status: "done",
+      summary: "test test",
+      confidence: 5,
+    });
+    expect(result.valid).toBe(false);
+    expect(result.errors.some((e) => e.includes("Invalid status"))).toBe(true);
+  });
+
+  it("rejects missing summary", () => {
+    const result = validateOutputContract({ status: "success", confidence: 5 });
+    expect(result.valid).toBe(false);
+    expect(result.errors.some((e) => e.includes("summary"))).toBe(true);
+  });
+
+  it("rejects short summary", () => {
+    const result = validateOutputContract({ status: "success", summary: "ok", confidence: 5 });
+    expect(result.valid).toBe(false);
+    expect(result.errors.some((e) => e.includes("too short"))).toBe(true);
+  });
+
+  it("rejects non-number confidence", () => {
+    const result = validateOutputContract({
+      status: "success",
+      summary: "test test",
+      confidence: "high",
+    });
+    expect(result.valid).toBe(false);
+    expect(result.errors.some((e) => e.includes("confidence"))).toBe(true);
+  });
+
+  it("rejects out-of-range confidence", () => {
+    const result = validateOutputContract({
+      status: "success",
+      summary: "test test",
+      confidence: 11,
+    });
+    expect(result.valid).toBe(false);
+    expect(result.errors.some((e) => e.includes("1 and 10"))).toBe(true);
+  });
+
+  it("rejects non-integer confidence", () => {
+    const result = validateOutputContract({
+      status: "success",
+      summary: "test test",
+      confidence: 7.5,
+    });
+    expect(result.valid).toBe(false);
+  });
+
+  it("accepts artifacts with freeform type and any locator", () => {
+    // path locator
+    const r1 = validateOutputContract({
+      status: "success",
+      summary: "test test",
+      confidence: 5,
+      artifacts: [{ type: "code", path: "src/index.ts", action: "modified" }],
+    });
+    expect(r1.valid).toBe(true);
+
+    // content locator (analysis, inline results)
+    const r2 = validateOutputContract({
+      status: "success",
+      summary: "test test",
+      confidence: 5,
+      artifacts: [{ type: "analysis", content: { issues: 3 } }],
+    });
+    expect(r2.valid).toBe(true);
+
+    // url locator (gist, deployment)
+    const r3 = validateOutputContract({
+      status: "success",
+      summary: "test test",
+      confidence: 5,
+      artifacts: [{ type: "gist", url: "https://gist.github.com/user/abc" }],
+    });
+    expect(r3.valid).toBe(true);
+  });
+
+  it("rejects artifacts missing type", () => {
+    const result = validateOutputContract({
+      status: "success",
+      summary: "test test",
+      confidence: 5,
+      artifacts: [{ path: "src/index.ts" }],
+    });
+    expect(result.valid).toBe(false);
+    expect(result.errors.some((e) => e.includes("missing 'type'"))).toBe(true);
+  });
+
+  it("rejects artifacts missing all locators", () => {
+    const result = validateOutputContract({
+      status: "success",
+      summary: "test test",
+      confidence: 5,
+      artifacts: [{ type: "code" }],
+    });
+    expect(result.valid).toBe(false);
+    expect(result.errors.some((e) => e.includes("'path', 'url', or 'content'"))).toBe(true);
+  });
+
+  it("validates verification object", () => {
+    const result = validateOutputContract({
+      status: "success",
+      summary: "test test",
+      confidence: 5,
+      verification: { commands_run: "test", tests_passed: "yes" },
+    });
+    expect(result.valid).toBe(false);
+    expect(result.errors.some((e) => e.includes("verification"))).toBe(true);
+  });
+
+  it("ignores unknown extra fields", () => {
+    const result = validateOutputContract({
+      status: "success",
+      summary: "test test",
+      confidence: 5,
+      preview_verified: true,
+      custom_field: "ok",
+    });
+    expect(result.valid).toBe(true);
+  });
+});
+
+describe("getContractTemplate", () => {
+  it("returns implementation template with all fields", () => {
+    const template = getContractTemplate("implementation");
+    expect(template).toContain("success | partial | blocked | failed");
+    expect(template).toContain("artifacts");
+    expect(template).toContain("verification");
+    expect(template).toContain("commits");
+  });
+
+  it("returns exploration template with minimal fields", () => {
+    const template = getContractTemplate("exploration");
+    expect(template).toContain("success | blocked");
+    expect(template).toContain("recommendation");
+    expect(template).not.toContain("artifacts");
+  });
+});

package/src/lib/contracts.ts

@@ -0,0 +1,195 @@
+/**
+ * Output contract types and validation for agent session responses.
+ *
+ * Provides a single source of truth for the structured JSON that agents
+ * are expected to return. Used by:
+ * - `abbie session start --await` response parsing
+ * - `abbie auto --spawn` output handling
+ * - Skills consuming session results
+ *
+ * Intentionally dependency-free (no zod) to keep the CLI lean.
+ */
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface Artifact {
+  /** Freeform tag — agents describe what they produced (code, analysis, diagram, gist, etc.) */
+  type: string;
+  /** File path, URL, or omitted when content is inline */
+  path?: string;
+  /** URL reference (gist, deployment, etc.) */
+  url?: string;
+  /** Inline content for non-file artifacts */
+  content?: unknown;
+  /** Freeform action description (created, modified, deleted, etc.) */
+  action?: string;
+}
+
+export interface Verification {
+  commands_run: string[];
+  tests_passed: boolean;
+}
+
+export interface Commit {
+  hash: string;
+  message: string;
+}
+
+/**
+ * Full output contract for implementation sessions (codex, claude).
+ */
+export interface OutputContract {
+  status: "success" | "partial" | "blocked" | "failed";
+  summary: string;
+  confidence: number;
+  artifacts?: Artifact[];
+  verification?: Verification;
+  commits?: Commit[];
+  next_steps?: string[];
+  blockers?: string[];
+}
+
+/**
+ * Minimal output contract for exploration sessions (copilot, gemini).
+ */
+export interface ExploreContract {
+  status: "success" | "blocked";
+  summary: string;
+  confidence: number;
+  recommendation?: string;
+}
+
+/**
+ * Union of all valid output contracts.
+ */
+export type AnyOutputContract = OutputContract | ExploreContract;
+
+// ============================================================================
+// Validation
+// ============================================================================
+
+export interface ValidationResult {
+  valid: boolean;
+  contract: AnyOutputContract | null;
+  errors: string[];
+  /** Original raw value (string or parsed object) */
+  raw: unknown;
+}
+
+const VALID_STATUSES = ["success", "partial", "blocked", "failed"] as const;
+
+/**
+ * Validate a parsed JSON value against the output contract schema.
+ *
+ * Returns a ValidationResult with:
+ * - `valid: true` + `contract` if the value matches
+ * - `valid: false` + `errors` if it doesn't
+ *
+ * Lenient by default: unknown extra fields are ignored, optional fields
+ * can be missing. Only required fields (`status`, `summary`, `confidence`)
+ * are enforced.
+ */
+export function validateOutputContract(value: unknown): ValidationResult {
+  const errors: string[] = [];
+
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return { valid: false, contract: null, errors: ["Expected a JSON object"], raw: value };
+  }
+
+  const obj = value as Record<string, unknown>;
+
+  // Required: status
+  if (typeof obj.status !== "string") {
+    errors.push("Missing or invalid 'status' (expected string)");
+  } else if (!(VALID_STATUSES as readonly string[]).includes(obj.status)) {
+    errors.push(`Invalid status '${obj.status}', expected one of: ${VALID_STATUSES.join(", ")}`);
+  }
+
+  // Required: summary
+  if (typeof obj.summary !== "string") {
+    errors.push("Missing or invalid 'summary' (expected string)");
+  } else if (obj.summary.length < 5) {
+    errors.push("Summary too short (min 5 chars)");
+  }
+
+  // Required: confidence
+  if (typeof obj.confidence !== "number") {
+    errors.push("Missing or invalid 'confidence' (expected number 1-10)");
+  } else if (obj.confidence < 1 || obj.confidence > 10 || !Number.isInteger(obj.confidence)) {
+    errors.push("Confidence must be an integer between 1 and 10");
+  }
+
+  // Optional: artifacts
+  if (obj.artifacts !== undefined) {
+    if (!Array.isArray(obj.artifacts)) {
+      errors.push("'artifacts' must be an array");
+    } else {
+      for (let i = 0; i < obj.artifacts.length; i++) {
+        const a = obj.artifacts[i];
+        if (typeof a !== "object" || a === null) {
+          errors.push(`artifacts[${i}]: expected object`);
+          continue;
+        }
+        const art = a as Record<string, unknown>;
+        // type is the only required field — freeform string, agents tag what they produce
+        if (typeof art.type !== "string") {
+          errors.push(`artifacts[${i}]: missing 'type' (freeform string)`);
+        }
+        // must have at least one locator: path, url, or content
+        if (art.path === undefined && art.url === undefined && art.content === undefined) {
+          errors.push(`artifacts[${i}]: needs 'path', 'url', or 'content'`);
+        }
+      }
+    }
+  }
+
+  // Optional: verification
+  if (obj.verification !== undefined) {
+    if (typeof obj.verification !== "object" || obj.verification === null) {
+      errors.push("'verification' must be an object");
+    } else {
+      const v = obj.verification as Record<string, unknown>;
+      if (!Array.isArray(v.commands_run)) errors.push("verification.commands_run must be an array");
+      if (typeof v.tests_passed !== "boolean")
+        errors.push("verification.tests_passed must be a boolean");
+    }
+  }
+
+  if (errors.length > 0) {
+    return { valid: false, contract: null, errors, raw: value };
+  }
+
+  return { valid: true, contract: obj as unknown as AnyOutputContract, errors: [], raw: value };
+}
+
+// ============================================================================
+// Contract templates (for prompt injection)
+// ============================================================================
+
+/**
+ * Get the output contract template string for a given session type.
+ * Used by buildPrompt() and buildAgentPrompt() to inject into prompts.
+ */
+export function getContractTemplate(type: "implementation" | "exploration"): string {
+  if (type === "exploration") {
+    return `{
+  "status": "success | blocked",
+  "summary": "brief summary",
+  "confidence": 1-10,
+  "recommendation": "what to do next"
+}`;
+  }
+
+  return `{
+  "status": "success | partial | blocked | failed",
+  "summary": "50-200 words describing what was done",
+  "confidence": 1-10,
+  "artifacts": [{"type": "code|analysis|diagram|gist|...", "path": "file.ts", "content": "...", "url": "...", "action": "created"}],
+  "verification": {"commands_run": ["verify --format=summary"], "tests_passed": true},
+  "commits": [{"hash": "abc123", "message": "commit message"}],
+  "next_steps": ["optional follow-up tasks"],
+  "blockers": ["if blocked, describe why"]
+}`;
+}

package/src/lib/convex.ts

@@ -0,0 +1,54 @@
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { ConvexHttpClient } from "convex/browser";
+
+export const DEFAULT_CONVEX_URL = "https://giant-salmon-711.convex.cloud";
+
+export type AgentsGlobalConfig = {
+  convexUrl?: string;
+};
+
+let cachedConfig: AgentsGlobalConfig | null = null;
+let cachedClient: ConvexHttpClient | null = null;
+
+export function loadGlobalConfig(): AgentsGlobalConfig {
+  if (cachedConfig) return cachedConfig;
+
+  const path = join(homedir(), ".abbie", "config.json");
+  if (!existsSync(path)) {
+    cachedConfig = {};
+    return cachedConfig;
+  }
+
+  try {
+    const content = readFileSync(path, "utf-8");
+    cachedConfig = JSON.parse(content) as AgentsGlobalConfig;
+  } catch {
+    cachedConfig = {};
+  }
+
+  return cachedConfig;
+}
+
+export function getConvexUrl(): string {
+  return process.env.CONVEX_URL || loadGlobalConfig().convexUrl || DEFAULT_CONVEX_URL;
+}
+
+/**
+ * Shared Convex HTTP client for CLI commands.
+ *
+ * Best-effort: relies on `CONVEX_URL` or ~/.abbie/config.json, with a fallback
+ * to the default agents deployment URL.
+ */
+export function getConvexHttpClient(): ConvexHttpClient {
+  if (!cachedClient) {
+    cachedClient = new ConvexHttpClient(getConvexUrl());
+  }
+  return cachedClient;
+}
+
+export function resetConvexClient(): void {
+  cachedClient = null;
+  cachedConfig = null;
+}

package/src/lib/device.ts

@@ -0,0 +1,41 @@
+import { randomUUID } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+function ensureDir(path: string): void {
+  if (!existsSync(path)) {
+    mkdirSync(path, { recursive: true });
+  }
+}
+
+/**
+ * Stable device ID for multi-device awareness.
+ *
+ * Resolution order:
+ * 1) `AGENTS_DEVICE_ID` env var
+ * 2) `~/.abbie/state/device.id`
+ * 3) generate + persist
+ */
+export function getDeviceId(): string {
+  const envDeviceId = process.env.AGENTS_DEVICE_ID;
+  if (envDeviceId && envDeviceId.trim().length > 0) return envDeviceId.trim();
+
+  const stateDir = join(homedir(), ".abbie", "state");
+  const deviceIdPath = join(stateDir, "device.id");
+
+  ensureDir(stateDir);
+
+  if (existsSync(deviceIdPath)) {
+    try {
+      const existing = readFileSync(deviceIdPath, "utf-8").trim();
+      if (existing.length > 0) return existing;
+    } catch {
+      // fall through
+    }
+  }
+
+  const id = randomUUID();
+  writeFileSync(deviceIdPath, `${id}\n`, { encoding: "utf-8" });
+  return id;
+}