the-campfire 0.1.0

package/dist/manifest.json

@@ -0,0 +1,26 @@
+{
+  "name": "Campfire",
+  "short_name": "Campfire",
+  "description": "Collaborative web UI for AI coding agents",
+  "start_url": "/",
+  "scope": "/",
+  "display": "standalone",
+  "background_color": "#2b2a27",
+  "theme_color": "#ae5630",
+  "orientation": "any",
+  "categories": ["developer-tools", "productivity"],
+  "icons": [
+    {
+      "src": "/icon-192.png",
+      "sizes": "192x192",
+      "type": "image/png",
+      "purpose": "any maskable"
+    },
+    {
+      "src": "/icon-512.png",
+      "sizes": "512x512",
+      "type": "image/png",
+      "purpose": "any maskable"
+    }
+  ]
+}

package/dist/sw.js

@@ -0,0 +1,130 @@
+// Campfire Service Worker — caching + push notifications
+const CACHE_NAME = "campfire-v4";
+
+// Assets to pre-cache on install (shell resources)
+const PRECACHE_URLS = [
+  "/",
+  "/manifest.json",
+  "/icon-192.png",
+  "/icon-512.png",
+];
+
+// Install: pre-cache shell resources
+self.addEventListener("install", (event) => {
+  event.waitUntil(
+    caches.open(CACHE_NAME).then((cache) => cache.addAll(PRECACHE_URLS))
+  );
+  self.skipWaiting();
+});
+
+// Activate: clean up old caches
+self.addEventListener("activate", (event) => {
+  event.waitUntil(
+    caches.keys().then((keys) =>
+      Promise.all(
+        keys
+          .filter((key) => key !== CACHE_NAME)
+          .map((key) => caches.delete(key))
+      )
+    )
+  );
+  self.clients.claim();
+});
+
+// Fetch: network-first for API/WS, cache-first for static assets
+self.addEventListener("fetch", (event) => {
+  const url = new URL(event.request.url);
+
+  // Skip non-GET requests and WebSocket upgrades
+  if (event.request.method !== "GET") return;
+  // Skip API requests — always go to network
+  if (url.pathname.startsWith("/api/") || url.pathname.startsWith("/ws/")) return;
+
+  // HTML navigations must prefer the network so deploys do not leave tabs
+  // pinned to an old hashed JS bundle.
+  if (event.request.mode === "navigate") {
+    event.respondWith(
+      fetch(event.request)
+        .then((networkResponse) => {
+          if (networkResponse.ok && url.origin === self.location.origin) {
+            const clone = networkResponse.clone();
+            caches.open(CACHE_NAME).then((cache) => {
+              cache.put(event.request, clone);
+            });
+          }
+          return networkResponse;
+        })
+        .catch(() => caches.match(event.request).then((cached) => cached || new Response("Offline", { status: 503 })))
+    );
+    return;
+  }
+
+  event.respondWith(
+    caches.match(event.request).then((cached) => {
+      // Return cached version while fetching update in background (stale-while-revalidate)
+      const fetchPromise = fetch(event.request)
+        .then((networkResponse) => {
+          // Only cache successful responses for same-origin requests
+          if (networkResponse.ok && url.origin === self.location.origin) {
+            const clone = networkResponse.clone();
+            caches.open(CACHE_NAME).then((cache) => {
+              cache.put(event.request, clone);
+            });
+          }
+          return networkResponse;
+        })
+        .catch(() => {
+          // Network failed — return cached if available
+          return cached || new Response("Offline", { status: 503 });
+        });
+
+      return cached || fetchPromise;
+    })
+  );
+});
+
+// Push notifications for permission requests
+self.addEventListener("push", (event) => {
+  if (!event.data) return;
+
+  let payload;
+  try {
+    payload = event.data.json();
+  } catch {
+    payload = { title: "Campfire", body: event.data.text() };
+  }
+
+  const title = payload.title || "Campfire";
+  const options = {
+    body: payload.body || "Permission request pending",
+    icon: "/icon-192.png",
+    badge: "/icon-192.png",
+    tag: payload.tag || "campfire-notification",
+    data: payload.data || {},
+    actions: payload.actions || [
+      { action: "allow", title: "Allow" },
+      { action: "deny", title: "Deny" },
+    ],
+    vibrate: [200, 100, 200],
+  };
+
+  event.waitUntil(self.registration.showNotification(title, options));
+});
+
+// Handle notification click — focus the app or open it
+self.addEventListener("notificationclick", (event) => {
+  event.notification.close();
+
+  event.waitUntil(
+    self.clients.matchAll({ type: "window", includeUncontrolled: true }).then((clients) => {
+      // Focus existing window if available
+      for (const client of clients) {
+        if (client.url.includes(self.location.origin)) {
+          return client.focus();
+        }
+      }
+      // Otherwise open new window
+      return self.clients.openWindow("/");
+    })
+  );
+});

package/package.json

@@ -0,0 +1,92 @@
+{
+  "name": "the-campfire",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Campfire — collaborative web platform for AI coding agents. Run Claude Code, Codex, Goose, Aider, and more from one browser UI with real-time collaboration, permission voting, and automation.",
+  "license": "MIT",
+  "author": "The Vibe Company",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/stretchcloud/campfire.git",
+    "directory": "web"
+  },
+  "homepage": "https://github.com/stretchcloud/campfire#readme",
+  "bugs": {
+    "url": "https://github.com/stretchcloud/campfire/issues"
+  },
+  "bin": {
+    "the-campfire": "./bin/cli.ts"
+  },
+  "files": [
+    "bin/",
+    "server/",
+    "dist/",
+    "!server/**/*.test.ts",
+    "!server/protocol/"
+  ],
+  "engines": {
+    "bun": ">=1.0.0"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "codex",
+    "ai",
+    "agent",
+    "multi-agent",
+    "self-hosted",
+    "mcp",
+    "web-ui",
+    "vibe-coding"
+  ],
+  "scripts": {
+    "dev": "bun dev.ts",
+    "dev:api": "bun --watch server/index.ts",
+    "dev:vite": "vite",
+    "build": "vite build",
+    "start": "NODE_ENV=production bun server/index.ts",
+    "prepublishOnly": "bun run build",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:codex-contract": "vitest run server/codex-protocol-*.test.ts"
+  },
+  "dependencies": {
+    "@lancedb/lancedb": "^0.26.2",
+    "@monaco-editor/react": "^4.7.0",
+    "croner": "^10.0.1",
+    "diff": "^8.0.3",
+    "geist": "^1.7.0",
+    "hono": "^4.7.0",
+    "mermaid": "^11.12.3",
+    "posthog-js": "^1.347.2"
+  },
+  "devDependencies": {
+    "@tailwindcss/vite": "^4.0.0",
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.2",
+    "@testing-library/user-event": "^14.6.1",
+    "@types/bun": "^1.2.5",
+    "@types/diff": "^8.0.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "@vitejs/plugin-react": "^4.4.0",
+    "@vitest/coverage-v8": "^4.0.18",
+    "@xterm/addon-fit": "^0.11.0",
+    "@xterm/xterm": "^6.0.0",
+    "autoprefixer": "^10.4.21",
+    "jsdom": "^28.0.0",
+    "postcss": "^8.5.3",
+    "react": "^19.0.0",
+    "react-arborist": "^3.4.3",
+    "react-dom": "^19.0.0",
+    "react-markdown": "^10.1.0",
+    "react-resizable-panels": "^4.6.2",
+    "remark-gfm": "^4.0.1",
+    "tailwindcss": "^4.0.0",
+    "typescript": "^5.9.3",
+    "vite": "^6.3.0",
+    "vitest": "^4.0.18",
+    "zustand": "^5.0.0"
+  }
+}

package/server/ADAPTERS.md

@@ -0,0 +1,121 @@
+# Adapter Contribution Guide
+
+This document explains how to add a new agent backend adapter to Campfire.
+
+## Architecture
+
+Campfire uses a unified `AgentAdapter` interface (`adapter-types.ts`) that translates between any agent backend's protocol and the browser's message format. The browser UI is completely unaware of which backend is running.
+
+```
+Browser <-> WsBridge <-> AgentAdapter <-> Backend Process (stdio/websocket)
+```
+
+## The `AgentAdapter` Interface
+
+Every adapter must implement `AgentAdapter` from `adapter-types.ts`:
+
+```typescript
+interface AgentAdapter {
+  sendBrowserMessage(msg: BrowserOutgoingMessage): boolean;
+  onBrowserMessage(cb: (msg: BrowserIncomingMessage) => void): void;
+  onSessionMeta(cb: (meta: AdapterSessionMeta) => void): void;
+  onDisconnect(cb: () => void): void;
+  onInitError(cb: (error: string) => void): void;
+  isConnected(): boolean;
+  disconnect(): Promise<void>;
+  getBackendSessionId(): string | null;
+}
+```
+
+## Step-by-Step: Adding a New Adapter
+
+### 1. Create the adapter file
+
+Create `web/server/{name}-adapter.ts`. Your adapter class should:
+
+- Accept a `Subprocess` (from `Bun.spawn()`) and session ID in the constructor
+- Parse the backend's protocol (JSON-RPC, stdout text, REST, etc.)
+- Translate incoming messages to `BrowserIncomingMessage` types
+- Translate outgoing `BrowserOutgoingMessage` to the backend's protocol
+- Emit `session_init` with a `SessionState` during initialization
+
+Key message types to emit:
+- `session_init` — on startup, with session state
+- `stream_event` — for streaming text (`message_start`, `content_block_delta`, etc.)
+- `assistant` — for complete assistant messages with `content` blocks
+- `result` — when a turn completes
+- `permission_request` — when the agent needs tool approval
+- `tool_progress` — for long-running tool calls
+- `error` — for error conditions
+
+### 2. Add to `cli-launcher.ts`
+
+- Import your adapter class
+- Add a `spawn{Name}()` method that:
+  - Resolves the binary path via `resolveBinary()`
+  - Spawns the process with `Bun.spawn()`
+  - Creates your adapter instance
+  - Calls `this.onAdapter(sessionId, adapter, backendType)`
+- Add your backend to the `launch()` and `relaunch()` dispatch
+
+### 3. Update `session-types.ts`
+
+Add your backend to the `BackendType` union:
+
+```typescript
+export type BackendType = "claude" | "codex" | "goose" | "aider" | "openhands" | "your-backend";
+```
+
+### 4. Update `routes.ts`
+
+- Add your backend to the `validBackends` array in session creation
+- Add to the `/backends` endpoint with `resolveBinary()` check
+
+### 5. Update frontend utilities
+
+**`src/utils/backends.ts`**:
+- Add `YOUR_MODELS` and `YOUR_MODES` arrays
+- Update `getModelsForBackend()`, `getModesForBackend()`, `getDefaultModel()`, `getDefaultMode()`
+
+**`src/api.ts`**:
+- Add your backend to the `CreateSessionOpts.backend` union
+- Add to `CronJobInfo.backendType`
+
+**`src/utils/project-grouping.ts`**:
+- Add to the `backendType` union in `SessionItem`
+
+**`src/components/CronManager.tsx`**:
+- Add to the backend cycle array
+
+### 6. Write tests
+
+Create `web/server/{name}-adapter.test.ts` with tests for:
+- Message parsing/translation
+- Protocol handling
+- Edge cases (malformed input, disconnection)
+
+## Examples
+
+### ACP/JSON-RPC (structured protocol)
+
+See `goose-adapter.ts` and `openhands-adapter.ts`. Both use the `JsonRpcTransport` class for stdin/stdout NDJSON communication with the ACP protocol (`initialize` -> `session/new` -> `session/prompt`).
+
+### Raw stdout (unstructured)
+
+See `aider-adapter.ts`. Parses unstructured text output, detecting SEARCH/REPLACE edit blocks and prompt markers to determine turn boundaries.
+
+## Tool Name Mapping
+
+Map your backend's tool names to Campfire-standard names so the UI renders them correctly:
+
+```typescript
+const toolMap: Record<string, string> = {
+  "your_bash_tool": "Bash",
+  "your_editor": "Edit",
+  "your_reader": "Read",
+  "your_writer": "Write",
+  "your_search": "Grep",
+};
+```
+
+Standard tool names: `Bash`, `Edit`, `Read`, `Write`, `Glob`, `Grep`, `WebFetch`, `WebSearch`.

package/server/adapter-registry-types.ts

@@ -0,0 +1,28 @@
+/**
+ * Types for the adapter registry — manages third-party agent adapters
+ * installed via npm into ~/.campfire/adapters/.
+ *
+ * Each adapter package declares a "campfireAdapter" field in its package.json
+ * containing an AdapterMetadata object that tells the registry how to launch
+ * and configure the backend.
+ */
+
+export interface AdapterMetadata {
+  name: string; // backend ID used in BackendType, e.g. "my-agent"
+  displayName: string; // human-readable label for UI
+  version: string;
+  binaryName?: string; // CLI binary name to resolve (optional)
+  models: Array<{ value: string; label: string }>;
+  modes: Array<{ value: string; label: string }>;
+  protocol: "stdio" | "websocket" | "http";
+  description?: string;
+  author?: string;
+  homepage?: string;
+}
+
+export interface InstalledAdapter {
+  metadata: AdapterMetadata;
+  path: string; // absolute path to adapter directory
+  installedAt: number;
+  npmPackage: string; // original npm package name used to install
+}

package/server/adapter-registry.ts

@@ -0,0 +1,293 @@
+/**
+ * AdapterRegistry — manages third-party agent adapters installed via npm.
+ *
+ * Adapters are stored in ~/.campfire/adapters/{name}/ and discovered by
+ * scanning for package.json files with a "campfireAdapter" field.
+ *
+ * Follows the same file-based persistence pattern as cron-store.ts.
+ */
+
+import {
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  existsSync,
+  rmSync,
+  renameSync,
+  writeFileSync,
+  statSync,
+} from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import type { AdapterMetadata, InstalledAdapter } from "./adapter-registry-types.js";
+
+// ─── Constants ───────────────────────────────────────────────────────────────
+
+/** Only allow safe characters in npm package names to prevent shell injection. */
+const SAFE_NPM_PACKAGE_RE = /^[a-zA-Z0-9@/_.-]+$/;
+
+// ─── Registry ────────────────────────────────────────────────────────────────
+
+class AdapterRegistry {
+  private adaptersDir: string;
+  private installed: Map<string, InstalledAdapter>;
+
+  constructor() {
+    this.adaptersDir = join(homedir(), ".campfire", "adapters");
+    mkdirSync(this.adaptersDir, { recursive: true });
+    this.installed = new Map();
+    this.scan();
+  }
+
+  // ─── Scan ────────────────────────────────────────────────────────────────
+
+  /**
+   * Scan ~/.campfire/adapters/ for installed adapter packages.
+   * Each subdirectory is expected to contain a package.json with a
+   * "campfireAdapter" field. Invalid directories are silently skipped.
+   */
+  scan(): InstalledAdapter[] {
+    this.installed.clear();
+
+    let entries: string[];
+    try {
+      entries = readdirSync(this.adaptersDir);
+    } catch {
+      return [];
+    }
+
+    for (const entry of entries) {
+      const dir = join(this.adaptersDir, entry);
+      try {
+        const stat = statSync(dir);
+        if (!stat.isDirectory()) continue;
+      } catch {
+        continue;
+      }
+
+      const metadata = this.validate(dir);
+      if (!metadata) continue;
+
+      // Read the persisted metadata.json for installedAt / npmPackage
+      let installedAt = Date.now();
+      let npmPackage = metadata.name;
+      const metaJsonPath = join(dir, "metadata.json");
+      try {
+        const raw = readFileSync(metaJsonPath, "utf-8");
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.installedAt === "number") installedAt = parsed.installedAt;
+        if (typeof parsed.npmPackage === "string") npmPackage = parsed.npmPackage;
+      } catch {
+        // metadata.json may not exist for manually-placed adapters
+      }
+
+      const adapter: InstalledAdapter = {
+        metadata,
+        path: dir,
+        installedAt,
+        npmPackage,
+      };
+
+      this.installed.set(metadata.name, adapter);
+    }
+
+    return Array.from(this.installed.values());
+  }
+
+  // ─── Validate ────────────────────────────────────────────────────────────
+
+  /**
+   * Validate a single adapter directory by reading its package.json and
+   * checking for a well-formed "campfireAdapter" field.
+   *
+   * Returns the validated AdapterMetadata or null if invalid.
+   */
+  validate(dir: string): AdapterMetadata | null {
+    const pkgPath = join(dir, "package.json");
+    if (!existsSync(pkgPath)) return null;
+
+    let pkg: Record<string, unknown>;
+    try {
+      pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+    } catch {
+      return null;
+    }
+
+    const raw = pkg.campfireAdapter;
+    if (!raw || typeof raw !== "object") return null;
+
+    const adapter = raw as Record<string, unknown>;
+
+    // Required fields
+    if (typeof adapter.name !== "string" || !adapter.name.trim()) return null;
+    if (typeof adapter.displayName !== "string" || !adapter.displayName.trim()) return null;
+
+    // Build validated metadata with defaults
+    const metadata: AdapterMetadata = {
+      name: adapter.name as string,
+      displayName: adapter.displayName as string,
+      version: typeof adapter.version === "string" ? adapter.version : (typeof pkg.version === "string" ? pkg.version : "0.0.0"),
+      protocol: adapter.protocol === "websocket" || adapter.protocol === "http"
+        ? adapter.protocol
+        : "stdio",
+      models: Array.isArray(adapter.models) && adapter.models.length > 0
+        ? adapter.models as Array<{ value: string; label: string }>
+        : [{ value: "default", label: "Default" }],
+      modes: Array.isArray(adapter.modes) && adapter.modes.length > 0
+        ? adapter.modes as Array<{ value: string; label: string }>
+        : [{ value: "default", label: "Default" }],
+    };
+
+    // Optional fields
+    if (typeof adapter.binaryName === "string") metadata.binaryName = adapter.binaryName;
+    if (typeof adapter.description === "string") metadata.description = adapter.description;
+    if (typeof adapter.author === "string") metadata.author = adapter.author;
+    if (typeof adapter.homepage === "string") metadata.homepage = adapter.homepage;
+
+    return metadata;
+  }
+
+  // ─── Install ─────────────────────────────────────────────────────────────
+
+  /**
+   * Install an adapter from npm into ~/.campfire/adapters/{name}/.
+   *
+   * Uses `bun add` in a temporary directory, validates the downloaded package
+   * has a campfireAdapter field, then moves it into the adapters directory.
+   */
+  async install(npmPackage: string): Promise<InstalledAdapter> {
+    // Sanitize package name to prevent shell injection
+    if (!npmPackage || !SAFE_NPM_PACKAGE_RE.test(npmPackage)) {
+      throw new Error(
+        `Invalid npm package name: "${npmPackage}". Only alphanumeric characters, @, /, _, ., and - are allowed.`,
+      );
+    }
+
+    // Create a temporary directory for the install
+    const tempDir = join(this.adaptersDir, `.tmp-install-${Date.now()}`);
+    mkdirSync(tempDir, { recursive: true });
+
+    try {
+      // Write a minimal package.json so bun add works
+      writeFileSync(
+        join(tempDir, "package.json"),
+        JSON.stringify({ name: "adapter-install-tmp", version: "0.0.0", private: true }),
+        "utf-8",
+      );
+
+      // Run bun add in the temp directory. --ignore-scripts prevents the
+      // third-party package from executing arbitrary code at install time;
+      // adapter code only runs later, when the user launches it as a backend.
+      const proc = Bun.spawn(["bun", "add", "--ignore-scripts", npmPackage], {
+        cwd: tempDir,
+        stdout: "pipe",
+        stderr: "pipe",
+      });
+
+      const exitCode = await proc.exited;
+      if (exitCode !== 0) {
+        const stderr = await new Response(proc.stderr).text();
+        throw new Error(`Failed to install "${npmPackage}": ${stderr.trim() || `exit code ${exitCode}`}`);
+      }
+
+      // Find the installed package in node_modules
+      // Handle scoped packages like @scope/pkg
+      const nodeModulesDir = join(tempDir, "node_modules");
+      const pkgName = npmPackage.replace(/@[\d^~>=<. |]+$/, ""); // strip version suffixes
+      const pkgDir = join(nodeModulesDir, pkgName);
+
+      if (!existsSync(pkgDir)) {
+        throw new Error(`Package "${npmPackage}" was installed but not found in node_modules`);
+      }
+
+      // Validate the package has campfireAdapter metadata
+      const metadata = this.validate(pkgDir);
+      if (!metadata) {
+        throw new Error(
+          `Package "${npmPackage}" does not contain a valid "campfireAdapter" field in its package.json`,
+        );
+      }
+
+      // Move to the final location
+      const destDir = join(this.adaptersDir, metadata.name);
+      if (existsSync(destDir)) {
+        rmSync(destDir, { recursive: true, force: true });
+      }
+      renameSync(pkgDir, destDir);
+
+      // Persist install metadata
+      const installedAt = Date.now();
+      writeFileSync(
+        join(destDir, "metadata.json"),
+        JSON.stringify({ installedAt, npmPackage }, null, 2),
+        "utf-8",
+      );
+
+      // Re-scan to pick up the new adapter
+      this.scan();
+
+      const installed = this.installed.get(metadata.name);
+      if (!installed) {
+        throw new Error(`Adapter "${metadata.name}" was installed but not found after scan`);
+      }
+
+      return installed;
+    } finally {
+      // Clean up temp directory
+      try {
+        rmSync(tempDir, { recursive: true, force: true });
+      } catch {
+        // Best-effort cleanup
+      }
+    }
+  }
+
+  // ─── Uninstall ───────────────────────────────────────────────────────────
+
+  /**
+   * Uninstall an adapter by name, removing its directory from
+   * ~/.campfire/adapters/.
+   */
+  uninstall(name: string): boolean {
+    const dir = join(this.adaptersDir, name);
+    if (!existsSync(dir)) {
+      this.installed.delete(name);
+      return false;
+    }
+
+    try {
+      rmSync(dir, { recursive: true, force: true });
+    } catch {
+      return false;
+    }
+
+    this.installed.delete(name);
+    return true;
+  }
+
+  // ─── Queries ─────────────────────────────────────────────────────────────
+
+  /** List all installed adapters. */
+  listInstalled(): InstalledAdapter[] {
+    return Array.from(this.installed.values());
+  }
+
+  /** Get a single installed adapter by its backend name, or null. */
+  getAdapter(name: string): InstalledAdapter | null {
+    return this.installed.get(name) || null;
+  }
+
+  /**
+   * Get backend configs for all installed adapters, suitable for the
+   * /api/backends endpoint.
+   */
+  getBackendConfigs(): Array<{ id: string; name: string; available: boolean }> {
+    return this.listInstalled().map((a) => ({
+      id: a.metadata.name,
+      name: a.metadata.displayName,
+      available: true, // If installed, it's available
+    }));
+  }
+}
+
+export { AdapterRegistry };