@cueloop/extension-api 0.1.0-alpha.9 → 0.1.0-alpha.90

package/package.json

@@ -1,32 +1,39 @@
 {
   "name": "@cueloop/extension-api",
-  "version": "0.1.0-alpha.9",
-  "license": "Apache-2.0",
-  "type": "module",
-  "exports": {
-    ".": "./src/index.ts"
-  },
-  "dependencies": {
-    "@cueloop/schema": "0.1.0-alpha.9"
+  "version": "0.1.0-alpha.90",
+  "description": "The typed contract for extending cueloop: renderers, commands, keybindings, exporters",
+  "homepage": "https://github.com/mmurakaru/cueloop#readme",
+  "bugs": {
+    "url": "https://github.com/mmurakaru/cueloop/issues"
   },
-  "publishConfig": {
-    "access": "public"
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mmurakaru/cueloop.git",
+    "directory": "packages/extension-api"
   },
   "files": [
     "src",
     "README.md"
   ],
-  "engines": {
-    "bun": ">=1.3.0"
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./client": "./src/client-ui.ts",
+    "./installed-packages": "./src/installed-packages.ts"
   },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/mmurakaru/cueloop.git",
-    "directory": "packages/extension-api"
+  "publishConfig": {
+    "access": "public"
   },
-  "homepage": "https://github.com/mmurakaru/cueloop#readme",
-  "bugs": {
-    "url": "https://github.com/mmurakaru/cueloop/issues"
+  "dependencies": {
+    "@cueloop/schema": "0.1.0-alpha.90",
+    "valibot": "^1.5.0"
+  },
+  "peerDependencies": {
+    "@opentui/react": "^0.5.11",
+    "react": "^19.3.0"
   },
-  "description": "The typed contract for extending cueloop: renderers, commands, keybindings, exporters"
-}
+  "engines": {
+    "bun": ">=1.3.0"
+  }
+}

package/src/client-ui.ts

@@ -0,0 +1,57 @@
+import type * as React from "react";
+import type { ComponentType } from "react";
+
+export type ExtensionComponent = ComponentType<{ context: ExtensionUIContext }>;
+
+/** The client supplies current workspace and Thread identity to extension UI. */
+export interface ExtensionUIContext {
+  workspace: string | null;
+  threadId: string | null;
+}
+
+/** A host-owned registration that can be removed on extension reload. */
+export interface ExtensionUIDisposable {
+  dispose(): void;
+}
+
+/** A titled, height-bounded section below the scrolling Threads list. */
+export interface ThreadSidebarSection {
+  id: string;
+  zone: "threads.sidebar";
+  title: string;
+  Component: ExtensionComponent;
+  when?: (context: ExtensionUIContext) => boolean;
+}
+
+/** An action rendered with the Thread header's existing button primitive. */
+export interface ThreadHeaderAction {
+  id: string;
+  zone: "thread.header";
+  label: string;
+  glyph?: string;
+  onPress(context: ExtensionUIContext): void | Promise<void>;
+  when?: (context: ExtensionUIContext) => boolean;
+}
+
+/** A selectable full-height view inside the workspace's existing right pane. */
+export interface WorkspacePanelView {
+  id: string;
+  zone: "workspace.panels";
+  title: string;
+  Component: ExtensionComponent;
+  when?: (context: ExtensionUIContext) => boolean;
+}
+
+/** Client-only registration API; server and VCS capabilities use the daemon entry point. */
+export interface ClientExtensionAPI {
+  /** Use this React instance for hooks so components share the host renderer's dispatcher. */
+  react: typeof React;
+  /** Host keyboard hook; package-local OpenTUI hooks do not share the host context. */
+  useKeyboard: typeof import("@opentui/react").useKeyboard;
+  registerSection(section: ThreadSidebarSection): ExtensionUIDisposable;
+  registerAction(action: ThreadHeaderAction): ExtensionUIDisposable;
+  registerView(view: WorkspacePanelView): ExtensionUIDisposable;
+}
+
+/** Client packages export one factory that registers their UI contributions. */
+export type ClientExtensionFactory = (api: ClientExtensionAPI) => void | Promise<void>;

package/src/index.ts

@@ -1,3 +1,2 @@
 export * from "./types";
 export * from "./registry";
-export * from "./loader";

package/src/installed-packages.test.ts

@@ -0,0 +1,79 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { mkdtempSync, mkdirSync, realpathSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { discoverInstalledExtensionPackages } from "./installed-packages";
+
+const roots: string[] = [];
+
+afterEach(() => {
+  for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true });
+});
+
+function installFixture(
+  name: string,
+  cueloop: { client?: string; daemon?: string } | undefined,
+): string {
+  const root = mkdtempSync(join(tmpdir(), "cueloop-extensions-test-"));
+  const packageRoot = join(root, "node_modules", name);
+
+  roots.push(root);
+  mkdirSync(packageRoot, { recursive: true });
+  writeFileSync(join(root, "package.json"), JSON.stringify({ dependencies: { [name]: "1.0.0" } }));
+  writeFileSync(join(packageRoot, "package.json"), JSON.stringify({ name, cueloop }));
+  writeFileSync(join(packageRoot, "client.js"), "export default () => {};");
+  writeFileSync(join(packageRoot, "daemon.js"), "export default () => {};");
+
+  return root;
+}
+
+describe("installed extension discovery", () => {
+  test("finds separate client and daemon entry points in a scoped package", () => {
+    const root = installFixture("@example/tools", { client: "./client.js", daemon: "./daemon.js" });
+    const result = discoverInstalledExtensionPackages(root);
+
+    expect(result.errors).toEqual([]);
+    expect(result.packages).toEqual([
+      {
+        name: "@example/tools",
+        root: join(root, "node_modules", "@example/tools"),
+        clientEntry: realpathSync(join(root, "node_modules", "@example/tools/client.js")),
+        daemonEntry: realpathSync(join(root, "node_modules", "@example/tools/daemon.js")),
+      },
+    ]);
+  });
+
+  test("rejects an entry outside its package and continues discovery", () => {
+    const root = installFixture("example", { client: "./../outside.js" });
+    const result = discoverInstalledExtensionPackages(root);
+
+    expect(result.packages).toEqual([]);
+    expect(result.errors[0]).toContain("entry escapes package root");
+  });
+
+  test("rejects a symlink entry that leaves the package", () => {
+    const root = installFixture("example", { client: "./linked.js" });
+    const outside = join(root, "outside.js");
+
+    writeFileSync(outside, "export default () => {};");
+    symlinkSync(outside, join(root, "node_modules/example/linked.js"));
+
+    expect(discoverInstalledExtensionPackages(root).errors[0]).toContain(
+      "entry escapes package root",
+    );
+  });
+
+  test("rejects a directory entry before installation succeeds", () => {
+    const root = installFixture("example", { client: "./folder" });
+
+    mkdirSync(join(root, "node_modules/example/folder"));
+
+    expect(discoverInstalledExtensionPackages(root).errors[0]).toContain("entry is not a file");
+  });
+
+  test("rejects a package without a cueloop manifest", () => {
+    const root = installFixture("example", undefined);
+
+    expect(discoverInstalledExtensionPackages(root).errors[0]).toContain("no cueloop manifest");
+  });
+});

package/src/installed-packages.ts

@@ -0,0 +1,99 @@
+import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+import * as v from "valibot";
+
+const PackageJsonSchema = v.object({
+  dependencies: v.optional(v.record(v.string(), v.string())),
+  cueloop: v.optional(
+    v.object({
+      client: v.optional(v.string()),
+      daemon: v.optional(v.string()),
+    }),
+  ),
+});
+
+/** The user-owned directory where `cueloop install` keeps npm packages. */
+export function extensionInstallRoot(env = process.env): string {
+  return (
+    env.CUELOOP_EXTENSION_HOME ??
+    join(env.XDG_DATA_HOME ?? join(homedir(), ".local", "share"), "cueloop", "extensions")
+  );
+}
+
+/** One installed package's separate client and daemon extension entry points. */
+export interface InstalledExtensionPackage {
+  name: string;
+  root: string;
+  clientEntry?: string;
+  daemonEntry?: string;
+}
+
+/** Discovery reports bad packages without preventing valid installed extensions from loading. */
+export interface ExtensionPackageDiscovery {
+  packages: InstalledExtensionPackage[];
+  errors: string[];
+}
+
+function readPackageJson(path: string): v.InferOutput<typeof PackageJsonSchema> {
+  const parsed = v.safeParse(PackageJsonSchema, JSON.parse(readFileSync(path, "utf8")));
+
+  if (!parsed.success) throw new Error("invalid package.json");
+
+  return parsed.output;
+}
+
+function packageEntry(root: string, entry: string | undefined): string | undefined {
+  if (entry === undefined) return undefined;
+  if (!entry.startsWith("./")) throw new Error("entry must start with ./");
+  const absolute = resolve(root, entry);
+  const lexicalWithin = relative(root, absolute);
+
+  if (isAbsolute(lexicalWithin) || lexicalWithin === ".." || lexicalWithin.startsWith(`..${sep}`))
+    throw new Error("entry escapes package root");
+  if (!existsSync(absolute)) throw new Error(`entry missing: ${entry}`);
+  if (!statSync(absolute).isFile()) throw new Error(`entry is not a file: ${entry}`);
+  const within = relative(realpathSync(root), realpathSync(absolute));
+
+  if (isAbsolute(within) || within === ".." || within.startsWith(`..${sep}`))
+    throw new Error("entry escapes package root");
+
+  return realpathSync(absolute);
+}
+
+/** Discover only declared `cueloop` entries from packages in the managed install root. */
+export function discoverInstalledExtensionPackages(
+  installRoot = extensionInstallRoot(),
+): ExtensionPackageDiscovery {
+  const packages: InstalledExtensionPackage[] = [];
+  const errors: string[] = [];
+  const rootManifest = join(installRoot, "package.json");
+
+  if (!existsSync(rootManifest)) return { packages, errors };
+  let dependencies: Record<string, string>;
+
+  try {
+    dependencies = readPackageJson(rootManifest).dependencies ?? {};
+  } catch (error) {
+    return { packages, errors: [`Extension package discovery: ${String(error)}`] };
+  }
+
+  for (const name of Object.keys(dependencies).toSorted()) {
+    const root = join(installRoot, "node_modules", name);
+
+    try {
+      const manifest = readPackageJson(join(root, "package.json")).cueloop;
+
+      if (!manifest) throw new Error("package has no cueloop manifest");
+      const clientEntry = packageEntry(root, manifest.client);
+      const daemonEntry = packageEntry(root, manifest.daemon);
+
+      if (!clientEntry && !daemonEntry) throw new Error("manifest declares no entry point");
+      packages.push({ name, root, clientEntry, daemonEntry });
+    } catch (error) {
+      errors.push(`Extension package ${name}: ${String(error)}`);
+    }
+  }
+
+  return { packages, errors };
+}

package/src/registry.test.ts

@@ -1,98 +1,93 @@
 import { describe, expect, test } from "bun:test";
-import { mkdtempSync, rmSync, writeFileSync, mkdirSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
 import { Registry } from "./registry";
-import { loadExtensions, readTrust } from "./loader";
-import type { ReviewSession } from "@cueloop/schema";
+import type { Thread } from "@cueloop/schema";
 
-const SESSION = { id: "ses_x", annotations: [] } as unknown as ReviewSession;
+const SESSION: Thread = {
+  schemaVersion: "1",
+  id: "ses_x",
+  workspace: { repoRoot: "/repo", branch: "main" },
+  artifact: { type: "plan", content: "# Plan\n", meta: {} },
+  revisions: [],
+  annotations: [],
+  message: null,
+  status: "pending",
+  createdAt: "2026-01-01T00:00:00.000Z",
+};
 
 describe("Registry", () => {
-  test("captures registrations per extension; first wins", async () => {
-    const reg = new Registry();
-    await reg.load("builtin", (api) => {
-      api.registerRenderer("plan", () => [[{ text: "builtin" }]]);
+  test("captures each extension's exporters, attributed by name", async () => {
+    // Arrange
+    const registry = new Registry();
+
+    // Act
+    await registry.load("obsidian", (api) => {
+      api.registerExporter("obsidian", async () => ({ success: true, path: "/vault/note.md" }));
     });
-    await reg.load("third-party", (api) => {
-      api.registerRenderer("plan", () => [[{ text: "override-attempt" }]]);
-      api.registerRenderer("svg", () => [[{ text: "svg" }]]);
+    await registry.load("bear", (api) => {
+      api.registerExporter("bear", async () => ({ success: true }));
     });
-    expect(reg.rendererFor("plan")!({ content: "", meta: {} }, 80)[0]![0]!.text).toBe("builtin");
-    expect(reg.rendererFor("svg")).toBeDefined();
+
+    // Assert
+    expect(registry.extensions.map((extension) => extension.name)).toEqual(["obsidian", "bear"]);
+    const obsidian = registry.extensions[0]!.exporters.get("obsidian")!;
+
+    expect(await obsidian(SESSION)).toEqual({ success: true, path: "/vault/note.md" });
   });
 
   test("a throwing factory is contained, not fatal", async () => {
-    const reg = new Registry();
-    const record = await reg.load("broken", () => {
+    // Arrange
+    const registry = new Registry();
+
+    // Act
+    const record = await registry.load("broken", () => {
       throw new Error("boom");
     });
-    expect(record.errors).toEqual(["boom"]);
-    expect(reg.extensions.length).toBe(1);
-  });
 
-  test("reserved keybindings are rejected with attribution", async () => {
-    const reg = new Registry();
-    const record = await reg.load("greedy", (api) => {
-      api.registerKeybinding({ action: "steal", defaultKeys: ["j"], handler: () => {} });
-      api.registerKeybinding({ action: "fine", defaultKeys: ["F5"], handler: () => {} });
-    });
-    expect(record.keybindings.length).toBe(1);
-    expect(record.errors[0]).toContain('"j" is reserved');
+    // Assert
+    expect(record.errors).toEqual(["boom"]);
+    expect(record.exporters.size).toBe(0);
+    expect(registry.extensions.length).toBe(1);
   });
 
-  test("observers never cancel and never crash the host", async () => {
-    const reg = new Registry();
-    const seen: string[] = [];
-    await reg.load("observer", (api) => {
-      api.on("session.resolved", () => {
-        throw new Error("observer bug");
+  test("a failed factory discards VCS adapters and exporters registered before it threw", async () => {
+    const registry = new Registry();
+    const record = await registry.load("broken-vcs", (api) => {
+      api.registerExporter("draft", async () => ({ success: true }));
+      api.registerVcsAdapter({
+        apiVersion: 1,
+        id: "example.sapling",
+        detect: async () => "/repo",
+        captureWorkingDiff: async () => ({ patch: "", files: [] }),
+        listChanges: async () => [],
+        listFiles: async () => [],
       });
-      api.on("session.resolved", (s) => seen.push(s.id));
+      throw new Error("incomplete extension");
     });
-    reg.emit("session.resolved", SESSION);
-    expect(seen).toEqual(["ses_x"]);
+
+    expect(record.errors).toEqual(["incomplete extension"]);
+    expect(record.exporters.size).toBe(0);
+    expect(record.vcsAdapters.size).toBe(0);
   });
-});
 
-describe("loadExtensions", () => {
-  test("loads user extensions; repo extensions gated by trust", async () => {
-    const dir = mkdtempSync(join(tmpdir(), "cueloop-ext-"));
-    const userDir = join(dir, "user-ext");
-    const repoRoot = join(dir, "repo");
-    const home = join(dir, "home");
-    mkdirSync(userDir, { recursive: true });
-    mkdirSync(join(repoRoot, ".cueloop", "extensions"), { recursive: true });
-    writeFileSync(
-      join(userDir, "hello.ts"),
-      `export default (api) => { api.registerCommand("hello", { description: "hi", handler() {} }); };`,
-    );
-    writeFileSync(
-      join(repoRoot, ".cueloop", "extensions", "repo-ext.ts"),
-      `export default (api) => { api.registerCommand("repo", { description: "r", handler() {} }); };`,
-    );
-    try {
-      // untrusted repo: user loads, repo skipped
-      const reg1 = new Registry();
-      const r1 = await loadExtensions({ registry: reg1, userDir, repoRoot, home });
-      expect(r1.loaded.length).toBe(1);
-      expect(r1.skipped.length).toBe(1);
-      expect(reg1.commandFor("hello")).toBeDefined();
-      expect(reg1.commandFor("repo")).toBeUndefined();
+  test("VCS IDs cannot replace built-in or previously registered adapters", async () => {
+    const registry = new Registry();
+    const adapter = {
+      apiVersion: 1 as const,
+      id: "example.sapling",
+      detect: async () => "/repo",
+      captureWorkingDiff: async () => ({ patch: "", files: [] }),
+      listChanges: async () => [],
+      listFiles: async () => [],
+    };
 
-      // trust granted through the resolver: repo loads and persists
-      const reg2 = new Registry();
-      const r2 = await loadExtensions({ registry: reg2, userDir, repoRoot, home, confirmTrust: async () => true });
-      expect(r2.loaded.length).toBe(2);
-      expect(reg2.commandFor("repo")).toBeDefined();
-      expect(readTrust(home).trusted).toContain(repoRoot);
+    await registry.load("first", (api) => api.registerVcsAdapter(adapter));
+    const duplicate = await registry.load("second", (api) => api.registerVcsAdapter(adapter));
+    const builtin = await registry.load("third", (api) =>
+      api.registerVcsAdapter({ ...adapter, id: "git" }),
+    );
 
-      // persisted: no resolver needed next time
-      const reg3 = new Registry();
-      const r3 = await loadExtensions({ registry: reg3, userDir, repoRoot, home });
-      expect(r3.loaded.length).toBe(2);
-    } finally {
-      rmSync(dir, { recursive: true, force: true });
-    }
+    expect(duplicate.errors).toEqual(["Invalid or duplicate VCS adapter ID: example.sapling"]);
+    expect(builtin.errors).toEqual(["Invalid or duplicate VCS adapter ID: git"]);
+    expect(registry.extensions[0]!.vcsAdapters.has("example.sapling")).toBe(true);
   });
 });

package/src/registry.ts

@@ -1,28 +1,26 @@
 /**
- * The contribution registry (#10): registrations are plain data, attributed
- * per extension. Reserved app keybindings are rejected at registration so a
- * broken extension cannot shadow core grammar.
+ * The contribution registry: an extension factory runs against a captured
+ * API, and its exporter registrations land as plain data attributed to that
+ * extension. One broken extension never takes the host down.
  */
 
-import type {
-  ArtifactRenderer,
-  CommandRegistration,
-  Exporter,
-  ExtensionAPI,
-  ExtensionFactory,
-  KeybindingRegistration,
-} from "./types";
-import type { ReviewSession } from "@cueloop/schema";
+import type { Exporter, ExtensionAPI, ExtensionFactory, VcsAdapter } from "./types";
+import * as v from "valibot";
 
-const RESERVED_KEYS = new Set(["j", "k", "g", "G", "v", "c", "s", "x", "e", "n", "p", "q", "return", "escape", "backspace"]);
+const VcsAdapterSchema = v.object({
+  apiVersion: v.literal(1),
+  id: v.pipe(v.string(), v.regex(/^[a-z][a-z0-9-]*(?:\.[a-z][a-z0-9-]*)+$/)),
+  detect: v.function(),
+  captureWorkingDiff: v.function(),
+  captureChange: v.optional(v.function()),
+  listChanges: v.function(),
+  listFiles: v.function(),
+});
 
 export interface ExtensionRecord {
   name: string;
-  renderers: Map<string, ArtifactRenderer>;
-  commands: Map<string, CommandRegistration>;
-  keybindings: KeybindingRegistration[];
   exporters: Map<string, Exporter>;
-  listeners: Map<string, ((session: ReviewSession) => void)[]>;
+  vcsAdapters: Map<string, VcsAdapter>;
   errors: string[];
 }
 
@@ -33,73 +31,38 @@ export class Registry {
   async load(name: string, factory: ExtensionFactory): Promise<ExtensionRecord> {
     const record: ExtensionRecord = {
       name,
-      renderers: new Map(),
-      commands: new Map(),
-      keybindings: [],
       exporters: new Map(),
-      listeners: new Map(),
+      vcsAdapters: new Map(),
       errors: [],
     };
     const api: ExtensionAPI = {
-      registerRenderer(type, renderer) {
-        record.renderers.set(type, renderer);
+      registerExporter(exporterName, exporter) {
+        record.exporters.set(exporterName, exporter);
       },
-      registerCommand(cmdName, registration) {
-        record.commands.set(cmdName, registration);
-      },
-      registerKeybinding(registration) {
-        const clash = registration.defaultKeys.find((k) => RESERVED_KEYS.has(k));
-        if (clash) {
-          record.errors.push(`keybinding "${registration.action}" rejected: "${clash}" is reserved`);
-          return;
-        }
-        record.keybindings.push(registration);
-      },
-      registerExporter(expName, exporter) {
-        record.exporters.set(expName, exporter);
-      },
-      on(event, handler) {
-        const list = record.listeners.get(event) ?? [];
-        list.push(handler);
-        record.listeners.set(event, list);
+      registerVcsAdapter: (adapter) => {
+        if (adapter.id === "git" || adapter.id === "jj")
+          throw new Error(`Invalid or duplicate VCS adapter ID: ${adapter.id}`);
+        const parsed = v.safeParse(VcsAdapterSchema, adapter);
+
+        if (!parsed.success) throw new Error(`Invalid VCS adapter contract: ${adapter.id}`);
+        if (
+          record.vcsAdapters.has(adapter.id) ||
+          this.extensions.some((extension) => extension.vcsAdapters.has(adapter.id))
+        )
+          throw new Error(`Invalid or duplicate VCS adapter ID: ${adapter.id}`);
+        record.vcsAdapters.set(adapter.id, adapter);
       },
     };
+
     try {
       await factory(api);
     } catch (err) {
-      // one broken extension never takes the app down
+      record.exporters.clear();
+      record.vcsAdapters.clear();
       record.errors.push(err instanceof Error ? err.message : String(err));
     }
     this.extensions.push(record);
-    return record;
-  }
 
-  /** First-registered wins for renderers/commands; built-ins load first. */
-  rendererFor(artifactType: string): ArtifactRenderer | undefined {
-    for (const ext of this.extensions) {
-      const r = ext.renderers.get(artifactType);
-      if (r) return r;
-    }
-    return undefined;
-  }
-
-  commandFor(name: string): { extension: string; registration: CommandRegistration } | undefined {
-    for (const ext of this.extensions) {
-      const c = ext.commands.get(name);
-      if (c) return { extension: ext.name, registration: c };
-    }
-    return undefined;
-  }
-
-  emit(event: string, session: ReviewSession): void {
-    for (const ext of this.extensions) {
-      for (const handler of ext.listeners.get(event) ?? []) {
-        try {
-          handler(session);
-        } catch {
-          // observers never cancel and never crash the host
-        }
-      }
-    }
+    return record;
   }
 }

package/src/types.ts

@@ -1,58 +1,56 @@
 /**
- * The single typed extension contract (#10). This module is import-free
- * beyond the schema: whatever a declaration file can reach gets published,
- * so the contract stays self-contained.
+ * The typed extension contract. Import-free beyond the schema, so the
+ * contract stays self-contained.
  *
- * An extension is a factory:
- *   export default (cueloop: ExtensionAPI) => { cueloop.registerCommand(...) }
- * Registration is data written into a per-extension record; action methods
- * are late-bound by the host. No import-time side effects.
+ * An extension is a factory that registers an exporter:
+ *   export default (cueloop: ExtensionAPI) => { cueloop.registerExporter(...) }
+ * Registration is data written into a per-extension record; the exporter runs
+ * later, host-driven. No import-time side effects.
  */
 
-import type { Annotation, ReviewSession, VerdictKind } from "@cueloop/schema";
+import type { DiffFileContents, DiffFileStatus, Thread } from "@cueloop/schema";
 
-/** A renderable line: styled runs the host paints into the terminal grid. */
-export interface UiRun {
-  text: string;
-  fg?: string;
-  bg?: string;
-}
-
-export type UiLine = UiRun[];
-
-/** Renderers project an artifact type into lines at a given width. */
-export type ArtifactRenderer = (artifact: { content: string; meta: Record<string, unknown> }, width: number) => UiLine[];
-
-export interface CommandContext {
-  session: ReviewSession | null;
-  annotate(annotation: Omit<Annotation, "createdAt">): Promise<void>;
-  resolve(verdict: VerdictKind, summary: string): Promise<void>;
-  notify(message: string): void;
+/** Exporters ship resolved sessions somewhere (notes vaults, forges). */
+export type Exporter = (
+  session: Thread,
+) => Promise<{ success: boolean; path?: string; error?: string }>;
+
+/** A source identity links a live diff to an exact captured revision. */
+export interface VcsSourceIdentity {
+  /** Stable logical change identity, when the VCS provides one. */
+  changeId?: string;
+  /** Exact revision that supplied this patch. */
+  revisionId: string;
 }
 
-export interface CommandRegistration {
-  description: string;
-  handler(ctx: CommandContext, args: string): void | Promise<void>;
+/** One complete working-copy capture; file contents must match the returned patch. */
+export interface VcsDiffSnapshot {
+  patch: string;
+  files: DiffFileContents[];
+  source?: VcsSourceIdentity;
 }
 
-export interface KeybindingRegistration {
-  /** Action name; binds through the same [keys] config as built-ins. */
-  action: string;
-  defaultKeys: string[];
-  handler(ctx: CommandContext): void | Promise<void>;
+/** The daemon-owned diff source contract; adapters never mutate Threads. */
+export interface VcsAdapter {
+  /** Contract version understood by this host. */
+  apiVersion: 1;
+  /** Unique namespaced ID, such as `example.sapling`. */
+  id: string;
+  /** Return the checkout root containing cwd, or null when this adapter does not apply. */
+  detect(cwd: string): Promise<string | null>;
+  /** Capture the working copy against its current parent in Git patch format. */
+  captureWorkingDiff(repoRoot: string): Promise<VcsDiffSnapshot>;
+  /** Optional: recapture one logical change after its exact revision was rewritten. */
+  captureChange?(repoRoot: string, changeId: string): Promise<VcsDiffSnapshot>;
+  /** List changed paths, including files that cannot be curated as text. */
+  listChanges(repoRoot: string): Promise<{ path: string; status: DiffFileStatus }[]>;
+  /** List the project files at the current revision. */
+  listFiles(repoRoot: string): Promise<string[]>;
 }
 
-/** Exporters ship resolved sessions somewhere (notes vaults, forges). */
-export type Exporter = (session: ReviewSession) => Promise<{ success: boolean; path?: string; error?: string }>;
-
 export interface ExtensionAPI {
-  /** Renderers for artifact types; built-ins register through this too. */
-  registerRenderer(artifactType: string, renderer: ArtifactRenderer): void;
-  registerCommand(name: string, registration: CommandRegistration): void;
-  registerKeybinding(registration: KeybindingRegistration): void;
   registerExporter(name: string, exporter: Exporter): void;
-  /** Observe session lifecycle; fold semantics: observers never cancel. */
-  on(event: "session.created" | "session.resolved" | "session.updated", handler: (session: ReviewSession) => void): void;
+  registerVcsAdapter(adapter: VcsAdapter): void;
 }
 
 export type ExtensionFactory = (cueloop: ExtensionAPI) => void | Promise<void>;

package/src/loader.ts

@@ -1,98 +0,0 @@
-/**
- * Extension discovery and loading (#10): zero-build TypeScript executed
- * directly. Global user extensions always load; repo-local `.cueloop/
- * extensions/` loads only when the repo is trusted (persisted decisions
- * under the cueloop home).
- */
-
-import { existsSync, readdirSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
-import { homedir } from "node:os";
-import { join } from "node:path";
-import { Registry } from "./registry";
-import type { ExtensionFactory } from "./types";
-
-export function userExtensionsDir(): string {
-  return join(process.env.XDG_CONFIG_HOME ?? join(homedir(), ".config"), "cueloop", "extensions");
-}
-
-export interface LoadOptions {
-  registry: Registry;
-  userDir?: string;
-  repoRoot?: string;
-  /** Persisted trust decisions live under the cueloop home. */
-  home?: string;
-  /** Trust resolver for untrusted repos; default denies (never prompt-free). */
-  confirmTrust?: (repoRoot: string) => Promise<boolean>;
-}
-
-interface TrustStore {
-  trusted: string[];
-}
-
-function trustPath(home: string): string {
-  return join(home, "trusted-repos.json");
-}
-
-export function readTrust(home: string): TrustStore {
-  try {
-    return JSON.parse(readFileSync(trustPath(home), "utf8")) as TrustStore;
-  } catch {
-    return { trusted: [] };
-  }
-}
-
-export function grantTrust(home: string, repoRoot: string): void {
-  const store = readTrust(home);
-  if (!store.trusted.includes(repoRoot)) store.trusted.push(repoRoot);
-  mkdirSync(home, { recursive: true });
-  writeFileSync(trustPath(home), JSON.stringify(store, null, 2));
-}
-
-function extensionFiles(dir: string): string[] {
-  if (!existsSync(dir)) return [];
-  return readdirSync(dir)
-    .filter((f) => f.endsWith(".ts") || f.endsWith(".js"))
-    .map((f) => join(dir, f))
-    .sort();
-}
-
-export async function loadExtensions(opts: LoadOptions): Promise<{ loaded: string[]; skipped: string[] }> {
-  const loaded: string[] = [];
-  const skipped: string[] = [];
-  const files: { path: string; source: string }[] = [];
-
-  for (const path of extensionFiles(opts.userDir ?? userExtensionsDir())) {
-    files.push({ path, source: "user" });
-  }
-  if (opts.repoRoot) {
-    const repoDir = join(opts.repoRoot, ".cueloop", "extensions");
-    const repoFiles = extensionFiles(repoDir);
-    if (repoFiles.length) {
-      const home = opts.home ?? join(homedir(), ".cueloop");
-      const trusted =
-        readTrust(home).trusted.includes(opts.repoRoot) ||
-        (opts.confirmTrust ? await opts.confirmTrust(opts.repoRoot) : false);
-      if (trusted) {
-        grantTrust(home, opts.repoRoot);
-        for (const path of repoFiles) files.push({ path, source: "repo" });
-      } else {
-        skipped.push(...repoFiles);
-      }
-    }
-  }
-
-  for (const file of files) {
-    try {
-      const mod = (await import(file.path)) as { default?: ExtensionFactory };
-      if (typeof mod.default !== "function") {
-        skipped.push(file.path);
-        continue;
-      }
-      await opts.registry.load(file.path, mod.default);
-      loaded.push(file.path);
-    } catch {
-      skipped.push(file.path);
-    }
-  }
-  return { loaded, skipped };
-}