the-campfire 0.1.0

package/server/adapter-types.ts

@@ -0,0 +1,51 @@
+/**
+ * AgentAdapter — the formal interface that all backend adapters must implement.
+ *
+ * CodexAdapter and GooseAdapter both implement this interface so that
+ * WsBridge can treat all stdio-based backends uniformly.
+ */
+
+import type {
+  BrowserIncomingMessage,
+  BrowserOutgoingMessage,
+} from "./session-types.js";
+
+/** Metadata emitted by adapters during initialization. */
+export interface AdapterSessionMeta {
+  cliSessionId?: string;
+  model?: string;
+  cwd?: string;
+}
+
+/**
+ * Common interface for all agent backend adapters.
+ *
+ * Each adapter translates between a backend-specific protocol (JSON-RPC, etc.)
+ * and the Campfire's BrowserIncomingMessage/BrowserOutgoingMessage types,
+ * making the browser completely unaware of which backend is running.
+ */
+export interface AgentAdapter {
+  /** Route a message from the browser to the backend. Returns false if the message was rejected. */
+  sendBrowserMessage(msg: BrowserOutgoingMessage): boolean;
+
+  /** Register callback for translated messages heading to the browser. */
+  onBrowserMessage(cb: (msg: BrowserIncomingMessage) => void): void;
+
+  /** Register callback for session metadata updates (cliSessionId, model, cwd). */
+  onSessionMeta(cb: (meta: AdapterSessionMeta) => void): void;
+
+  /** Register callback for when the backend process disconnects. */
+  onDisconnect(cb: () => void): void;
+
+  /** Register callback for initialization failures. */
+  onInitError(cb: (error: string) => void): void;
+
+  /** Whether the adapter has completed initialization and the backend is connected. */
+  isConnected(): boolean;
+
+  /** Gracefully disconnect from the backend process. */
+  disconnect(): Promise<void>;
+
+  /** Get the backend's internal session/thread ID, or null if not yet initialized. */
+  getBackendSessionId(): string | null;
+}

package/server/agent-executor.ts

@@ -0,0 +1,249 @@
+import { Cron } from "croner";
+import { randomUUID } from "node:crypto";
+import type { AgentProfile, AgentExecution } from "./agent-types.js";
+import type { CliLauncher } from "./cli-launcher.js";
+import type { WsBridge } from "./ws-bridge.js";
+import * as agentStore from "./agent-store.js";
+import * as envManager from "./env-manager.js";
+import * as sessionNames from "./session-names.js";
+import { getSettings } from "./settings-manager.js";
+
+function resolveEnvVars(agent: AgentProfile): Record<string, string> | undefined {
+  let envVars: Record<string, string> | undefined;
+  if (agent.envSlug) {
+    const env = envManager.getEnv(agent.envSlug);
+    if (env) envVars = env.variables;
+  }
+  if (agent.env) {
+    envVars = { ...envVars, ...agent.env };
+  }
+  // Auto-inject provider tokens from global settings (if not already set)
+  const settings = getSettings();
+  if (agent.backendType === "claude" && settings.claudeOAuthToken && !envVars?.["CLAUDE_CODE_OAUTH_TOKEN"]) {
+    envVars = { ...envVars, CLAUDE_CODE_OAUTH_TOKEN: settings.claudeOAuthToken };
+  }
+  if (agent.backendType === "codex" && settings.openaiApiKey && !envVars?.["OPENAI_API_KEY"]) {
+    envVars = { ...envVars, OPENAI_API_KEY: settings.openaiApiKey };
+  }
+  if (settings.anthropicApiKey && !envVars?.["ANTHROPIC_API_KEY"]) {
+    envVars = { ...envVars, ANTHROPIC_API_KEY: settings.anthropicApiKey };
+  }
+  return envVars;
+}
+
+function resolvePrompt(template: string, input?: string): string {
+  if (!input) return template;
+  if (template.includes("{{input}}")) return template.replaceAll("{{input}}", input);
+  return template + "\n\n" + input;
+}
+
+function resolveCodexSandbox(agent: AgentProfile): "danger-full-access" | "workspace-write" | undefined {
+  if (agent.backendType !== "codex") return undefined;
+  return agent.permissionMode === "bypassPermissions" ? "danger-full-access" : "workspace-write";
+}
+
+const MAX_CONSECUTIVE_FAILURES = 5;
+const CLI_CONNECT_TIMEOUT_MS = 30_000;
+const CLI_CONNECT_POLL_MS = 500;
+
+export class AgentExecutor {
+  private readonly timers = new Map<string, Cron>();
+  private readonly launcher: CliLauncher;
+  private readonly wsBridge: WsBridge;
+
+  constructor(launcher: CliLauncher, wsBridge: WsBridge) {
+    this.launcher = launcher;
+    this.wsBridge = wsBridge;
+  }
+
+  /** Start all enabled scheduled agents. Called once at server startup. */
+  startAll(): void {
+    const agents = agentStore.listAgents();
+    let scheduled = 0;
+    for (const agent of agents) {
+      if (agent.enabled && agent.triggers?.schedule?.enabled) {
+        this.scheduleAgent(agent);
+        scheduled++;
+      }
+    }
+    if (scheduled > 0) {
+      console.log(`[agent-executor] Scheduled ${scheduled} agent(s)`);
+    }
+  }
+
+  /** Schedule or reschedule a single agent's cron trigger. */
+  scheduleAgent(agent: AgentProfile): void {
+    this.unscheduleAgent(agent.id);
+
+    const schedule = agent.triggers?.schedule;
+    if (!schedule?.enabled || !schedule.expression) return;
+
+    try {
+      if (schedule.recurring) {
+        const timer = new Cron(schedule.expression, () => {
+          this.executeAgent(agent.id, { trigger: "schedule" }).catch((err) => {
+            console.error(`[agent-executor] Scheduled run of "${agent.name}" failed:`, err);
+          });
+        });
+        this.timers.set(agent.id, timer);
+      } else {
+        const runAt = new Date(schedule.expression);
+        if (runAt.getTime() <= Date.now()) return;
+        const timer = new Cron(runAt, () => {
+          this.executeAgent(agent.id, { trigger: "schedule" }).catch((err) => {
+            console.error(`[agent-executor] One-shot agent "${agent.name}" failed:`, err);
+          });
+          agentStore.updateAgent(agent.id, {
+            triggers: {
+              ...agent.triggers,
+              schedule: { ...schedule, enabled: false },
+            },
+          });
+          this.timers.delete(agent.id);
+        });
+        this.timers.set(agent.id, timer);
+      }
+    } catch (err) {
+      console.error(`[agent-executor] Invalid schedule for "${agent.name}":`, err);
+    }
+  }
+
+  /** Stop cron timer for an agent. */
+  unscheduleAgent(agentId: string): void {
+    const timer = this.timers.get(agentId);
+    if (timer) {
+      timer.stop();
+      this.timers.delete(agentId);
+    }
+  }
+
+  /** Execute an agent: create a session, inject the prompt, track execution. */
+  async executeAgent(
+    agentId: string,
+    opts: { input?: string; trigger?: "manual" | "webhook" | "schedule"; force?: boolean } = {},
+  ): Promise<AgentExecution> {
+    const agent = agentStore.getAgent(agentId);
+    if (!agent) throw new Error(`Agent "${agentId}" not found`);
+    if (!agent.enabled && !opts.force) throw new Error(`Agent "${agent.name}" is disabled`);
+
+    // Overlap prevention
+    if (agent.lastSessionId && this.launcher.isAlive(agent.lastSessionId)) {
+      throw new Error(`Agent "${agent.name}" is already running (${agent.lastSessionId})`);
+    }
+
+    console.log(`[agent-executor] Executing agent "${agent.name}" (${agentId}) [${opts.trigger || "manual"}]`);
+
+    const execution: AgentExecution = {
+      executionId: randomUUID(),
+      agentId,
+      sessionId: "",
+      input: opts.input,
+      trigger: opts.trigger || "manual",
+      startedAt: Date.now(),
+    };
+
+    try {
+      const envVars = resolveEnvVars(agent);
+
+      // Launch session via CliLauncher (works for ALL backends)
+      const sessionInfo = this.launcher.launch({
+        model: agent.model,
+        permissionMode: agent.permissionMode,
+        cwd: agent.cwd,
+        env: envVars,
+        backendType: agent.backendType,
+        codexInternetAccess: agent.backendType === "codex" ? (agent.codexInternetAccess ?? true) : undefined,
+        codexSandbox: resolveCodexSandbox(agent),
+      });
+
+      execution.sessionId = sessionInfo.sessionId;
+
+      // Set session name with agent icon
+      const label = `${agent.icon || "\u{1F916}"} ${agent.name}`;
+      sessionNames.setName(sessionInfo.sessionId, label);
+
+      // Wait for CLI to connect
+      await this.waitForCLIConnection(sessionInfo.sessionId);
+
+      // Resolve prompt and inject with agent prefix for traceability
+      const resolvedPrompt = resolvePrompt(agent.prompt, opts.input);
+      const fullPrompt = `[agent:${agent.id} ${agent.name}]\n\n${resolvedPrompt}`;
+      this.wsBridge.injectUserMessage(sessionInfo.sessionId, fullPrompt);
+
+      // Update agent tracking
+      agentStore.updateAgent(agentId, {
+        lastRunAt: Date.now(),
+        lastSessionId: sessionInfo.sessionId,
+        totalRuns: agent.totalRuns + 1,
+        consecutiveFailures: 0,
+      });
+
+      execution.success = true;
+      agentStore.appendExecution(execution);
+
+      return execution;
+    } catch (err) {
+      console.error(`[agent-executor] Agent "${agent.name}" failed:`, err);
+      execution.error = err instanceof Error ? err.message : String(err);
+      execution.completedAt = Date.now();
+      agentStore.appendExecution(execution);
+
+      const failures = agent.consecutiveFailures + 1;
+      const updates: Partial<AgentProfile> = {
+        consecutiveFailures: failures,
+        lastRunAt: Date.now(),
+      };
+
+      if (failures >= MAX_CONSECUTIVE_FAILURES) {
+        updates.enabled = false;
+        this.unscheduleAgent(agentId);
+        console.warn(`[agent-executor] Agent "${agent.name}" disabled after ${failures} consecutive failures`);
+      }
+
+      agentStore.updateAgent(agentId, updates);
+      throw err;
+    }
+  }
+
+  /** Manual trigger (bypasses enabled check). */
+  executeAgentManually(agentId: string, input?: string): void {
+    this.executeAgent(agentId, { input, trigger: "manual", force: true }).catch((err) => {
+      console.error(`[agent-executor] Manual execution of agent "${agentId}" failed:`, err);
+    });
+  }
+
+  /** Get next scheduled run time for an agent. */
+  getNextRunTime(agentId: string): Date | null {
+    const timer = this.timers.get(agentId);
+    if (!timer) return null;
+    return timer.nextRun() ?? null;
+  }
+
+  /** Check if an agent's last session is still alive. */
+  isRunning(agentId: string): boolean {
+    const agent = agentStore.getAgent(agentId);
+    if (!agent?.lastSessionId) return false;
+    return this.launcher.isAlive(agent.lastSessionId);
+  }
+
+  /** Graceful shutdown: stop all timers. */
+  destroy(): void {
+    for (const [, timer] of this.timers) {
+      timer.stop();
+    }
+    this.timers.clear();
+  }
+
+  private async waitForCLIConnection(sessionId: string): Promise<void> {
+    const start = Date.now();
+    while (Date.now() - start < CLI_CONNECT_TIMEOUT_MS) {
+      const info = this.launcher.getSession(sessionId);
+      if (info && (info.state === "connected" || info.state === "running")) return;
+      if (info?.state === "exited") {
+        throw new Error(`CLI process exited before connecting (exit code: ${info.exitCode})`);
+      }
+      await new Promise((r) => setTimeout(r, CLI_CONNECT_POLL_MS));
+    }
+    throw new Error(`CLI process did not connect within ${CLI_CONNECT_TIMEOUT_MS / 1000}s`);
+  }
+}

package/server/agent-mcp-bridge.ts

@@ -0,0 +1,148 @@
+import { randomUUID } from "node:crypto";
+import type { BackendType, BrowserOutgoingMessage, CLIControlRequestMessage, PermissionRequest } from "./session-types.js";
+import type { WsBridge } from "./ws-bridge.js";
+import { backendFromAskTool, createAgentMcpServerConfig } from "./agent-mcp-tools.js";
+import type { SubSessionManager, SubSessionResult } from "./sub-session-manager.js";
+
+export interface AgentMcpBridgeOptions {
+  port: number;
+  packageRoot: string;
+  token?: string;
+  backends?: BackendType[];
+}
+
+type PermissionResponseMessage = Extract<BrowserOutgoingMessage, { type: "permission_response" }>;
+type PermissionResponder = (msg: PermissionResponseMessage) => void;
+
+function backendFromCampfireMcpTool(toolName: string): BackendType | null {
+  const parts = toolName.split(":");
+  if (parts.length !== 3 || parts[0] !== "mcp") return null;
+  const [, serverName, mcpToolName] = parts;
+  if (serverName !== "campfire_agents" && serverName !== "campfire-agents") return null;
+  return backendFromAskTool(mcpToolName);
+}
+
+export class AgentMcpBridge {
+  readonly token: string;
+  private readonly injectedSessions = new Set<string>();
+  private readonly backends: BackendType[];
+
+  constructor(
+    private readonly wsBridge: WsBridge,
+    private readonly subSessionManager: SubSessionManager,
+    private readonly options: AgentMcpBridgeOptions,
+  ) {
+    this.token = options.token ?? randomUUID();
+    this.backends = options.backends ?? ["codex", "goose", "aider", "openhands", "claude"];
+    process.env.CAMPFIRE_INTERNAL_AGENT_MCP_TOKEN = this.token;
+  }
+
+  onSessionReady(sessionId: string, backendType: BackendType, cwd: string): void {
+    if (!cwd || this.injectedSessions.has(sessionId)) return;
+    const session = this.wsBridge.getSession(sessionId);
+    if (session?.state.parent_session_id || session?.state.orchestration_role === "subagent" || session?.state.orchestration_role === "race_entry") return;
+    if (!this.supportsRuntimeMcp(backendType)) return;
+    if (process.env.CAMPFIRE_ENABLE_AGENT_MCP === "0") return;
+
+    const config = createAgentMcpServerConfig({
+      port: this.options.port,
+      token: this.token,
+      packageRoot: this.options.packageRoot,
+      parentSessionId: sessionId,
+      backends: this.backends.filter((backend) => backend !== backendType),
+    });
+    this.injectedSessions.add(sessionId);
+    this.wsBridge.setMcpServers(sessionId, { campfire_agents: config });
+  }
+
+  handlePermissionRequest(sessionId: string, msg: CLIControlRequestMessage): boolean {
+    const backend = backendFromAskTool(msg.request.tool_name);
+    if (!backend) return false;
+
+    const session = this.wsBridge.getSession(sessionId);
+    if (!session) return false;
+    session.pendingPermissions.delete(msg.request_id);
+    const response = {
+      type: "control_response",
+      response: {
+        subtype: "success",
+        request_id: msg.request_id,
+        response: {
+          behavior: "allow",
+          updatedInput: msg.request.input,
+        },
+      },
+    };
+    (this.wsBridge as unknown as { sendToCLI?: (s: unknown, ndjson: string) => void }).sendToCLI?.(session, JSON.stringify(response));
+    return true;
+  }
+
+  handleAdapterPermissionRequest(_sessionId: string, request: PermissionRequest, respond: PermissionResponder): boolean {
+    const backend = backendFromCampfireMcpTool(request.tool_name);
+    if (!backend) return false;
+
+    respond({
+      type: "permission_response",
+      request_id: request.request_id,
+      behavior: "allow",
+      updated_input: request.input,
+    });
+    return true;
+  }
+
+  async callTool(parentSessionId: string, toolName: string, input: Record<string, unknown>): Promise<SubSessionResult> {
+    const backendType = backendFromAskTool(toolName);
+    if (!backendType) {
+      return {
+        sessionId: "",
+        backendType: "claude",
+        text: "",
+        filesChanged: [],
+        costUsd: 0,
+        durationMs: 0,
+        error: `Unknown agent tool: ${toolName}`,
+      };
+    }
+
+    const parent = this.wsBridge.getSession(parentSessionId);
+    if (!parent?.state.cwd) {
+      return {
+        sessionId: "",
+        backendType,
+        text: "",
+        filesChanged: [],
+        costUsd: 0,
+        durationMs: 0,
+        error: `Parent session ${parentSessionId} is not available.`,
+      };
+    }
+
+    const prompt = typeof input.prompt === "string" ? input.prompt.trim() : "";
+    if (!prompt) {
+      return {
+        sessionId: "",
+        backendType,
+        text: "",
+        filesChanged: [],
+        costUsd: 0,
+        durationMs: 0,
+        error: "prompt is required.",
+      };
+    }
+
+    const timeoutSeconds = typeof input.timeout_seconds === "number" && Number.isFinite(input.timeout_seconds)
+      ? Math.max(1, Math.min(3600, input.timeout_seconds))
+      : 300;
+
+    return this.subSessionManager.spawnSubSession(parentSessionId, backendType, prompt, parent.state.cwd, {
+      timeoutMs: timeoutSeconds * 1000,
+      toolUseId: `ask-${backendType}-${randomUUID().slice(0, 8)}`,
+      name: `Ask ${backendType}`,
+      description: prompt.slice(0, 160),
+    });
+  }
+
+  private supportsRuntimeMcp(backendType: BackendType): boolean {
+    return backendType === "claude" || backendType === "codex";
+  }
+}

package/server/agent-mcp-stdio.ts

@@ -0,0 +1,171 @@
+#!/usr/bin/env bun
+import { generateAgentToolDefinitions } from "./agent-mcp-tools.js";
+import type { AgentToolDefinition } from "./agent-mcp-tools.js";
+
+interface JsonRpcRequest {
+  jsonrpc?: "2.0";
+  id?: string | number | null;
+  method?: string;
+  params?: Record<string, unknown>;
+}
+
+type FramingMode = "content-length" | "ndjson";
+
+const url = process.env.CAMPFIRE_AGENT_MCP_URL || "http://127.0.0.1:4567/api/internal/agent-mcp";
+const token = process.env.CAMPFIRE_AGENT_MCP_TOKEN || "";
+const parentSessionId = process.env.CAMPFIRE_PARENT_SESSION_ID || "";
+const backends = (process.env.CAMPFIRE_AGENT_MCP_BACKENDS || "")
+  .split(",")
+  .map((s) => s.trim())
+  .filter(Boolean) as Array<AgentToolDefinition["backendType"]>;
+
+let framingMode: FramingMode | null = null;
+
+function send(payload: unknown): void {
+  const json = JSON.stringify(payload);
+  if (framingMode === "content-length") {
+    process.stdout.write(`Content-Length: ${Buffer.byteLength(json, "utf-8")}\r\n\r\n${json}`);
+    return;
+  }
+  process.stdout.write(`${json}\n`);
+}
+
+function respond(id: JsonRpcRequest["id"], result: unknown): void {
+  if (id === undefined || id === null) return;
+  send({ jsonrpc: "2.0", id, result });
+}
+
+function respondError(id: JsonRpcRequest["id"], code: number, message: string): void {
+  if (id === undefined || id === null) return;
+  send({ jsonrpc: "2.0", id, error: { code, message } });
+}
+
+function mcpTools() {
+  return generateAgentToolDefinitions(backends.length ? backends : undefined).map((tool) => ({
+    name: tool.name,
+    description: tool.description,
+    inputSchema: tool.input_schema,
+  }));
+}
+
+async function callTool(name: string, input: Record<string, unknown>): Promise<{ content: Array<{ type: "text"; text: string }>; isError?: boolean }> {
+  const res = await fetch(`${url}/call`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${token}`,
+    },
+    body: JSON.stringify({ parentSessionId, toolName: name, input }),
+  });
+  const data = await res.json() as {
+    text?: string;
+    filesChanged?: string[];
+    costUsd?: number;
+    durationMs?: number;
+    sessionId?: string;
+    error?: string;
+  };
+  if (!res.ok || data.error) {
+    return {
+      isError: true,
+      content: [{ type: "text", text: data.error || `Agent tool ${name} failed.` }],
+    };
+  }
+
+  const files = data.filesChanged?.length ? `\n\nFiles changed:\n${data.filesChanged.map((f) => `- ${f}`).join("\n")}` : "";
+  const metrics = `\n\nSub-session: ${data.sessionId || "unknown"}\nCost: $${(data.costUsd || 0).toFixed(4)}\nDuration: ${data.durationMs || 0}ms`;
+  return {
+    content: [{ type: "text", text: `${data.text || "Sub-agent completed without text output."}${files}${metrics}` }],
+  };
+}
+
+async function handle(req: JsonRpcRequest): Promise<void> {
+  switch (req.method) {
+    case "initialize":
+      respond(req.id, {
+        protocolVersion: "2024-11-05",
+        capabilities: { tools: {} },
+        serverInfo: { name: "campfire-agents", version: "1.0.0" },
+      });
+      return;
+    case "notifications/initialized":
+      return;
+    case "tools/list":
+      respond(req.id, { tools: mcpTools() });
+      return;
+    case "tools/call": {
+      const params = req.params ?? {};
+      const name = typeof params.name === "string" ? params.name : "";
+      const args = params.arguments && typeof params.arguments === "object" ? params.arguments as Record<string, unknown> : {};
+      if (!name) {
+        respondError(req.id, -32602, "Tool name is required.");
+        return;
+      }
+      respond(req.id, await callTool(name, args));
+      return;
+    }
+    default:
+      if (req.id !== undefined && req.id !== null) respondError(req.id, -32601, `Unknown method: ${req.method || ""}`);
+  }
+}
+
+let buffer = Buffer.alloc(0);
+
+function parseJsonRequest(body: string): void {
+  try {
+    void handle(JSON.parse(body) as JsonRpcRequest);
+  } catch (err) {
+    process.stderr.write(`campfire-agents MCP parse error: ${err}\n`);
+  }
+}
+
+function consumeContentLengthFrames(): boolean {
+  let consumed = false;
+  while (buffer.length > 0) {
+    const headerEnd = buffer.indexOf("\r\n\r\n");
+    if (headerEnd === -1) return consumed;
+    const header = buffer.subarray(0, headerEnd).toString("utf-8");
+    const match = /Content-Length:\s*(\d+)/i.exec(header);
+    if (!match) {
+      return consumed;
+    }
+    framingMode = "content-length";
+    const length = Number(match[1]);
+    const start = headerEnd + 4;
+    if (buffer.length < start + length) return consumed;
+    const body = buffer.subarray(start, start + length).toString("utf-8");
+    buffer = buffer.subarray(start + length);
+    consumed = true;
+    parseJsonRequest(body);
+  }
+  return consumed;
+}
+
+function consumeNdjsonFrames(): void {
+  while (buffer.length > 0) {
+    const newline = buffer.indexOf("\n");
+    if (newline === -1) return;
+    framingMode = "ndjson";
+    const line = buffer.subarray(0, newline).toString("utf-8").trim();
+    buffer = buffer.subarray(newline + 1);
+    if (!line) continue;
+    parseJsonRequest(line);
+  }
+}
+
+function consumeFrames(): void {
+  while (buffer.length > 0) {
+    if (/^\s*Content-Length:/i.test(buffer.toString("utf-8", 0, Math.min(buffer.length, 32)))) {
+      const consumed = consumeContentLengthFrames();
+      if (!consumed) return;
+      continue;
+    }
+    consumeNdjsonFrames();
+    return;
+  }
+}
+
+process.stdin.on("data", (chunk) => {
+  buffer = Buffer.concat([buffer, Buffer.from(chunk)]);
+  consumeFrames();
+});

package/server/agent-mcp-tools.ts

@@ -0,0 +1,76 @@
+import type { BackendType, McpServerConfig } from "./session-types.js";
+
+export interface AgentToolDefinition {
+  name: string;
+  backendType: BackendType;
+  description: string;
+  input_schema: {
+    type: "object";
+    properties: Record<string, unknown>;
+    required: string[];
+  };
+}
+
+const TOOL_BACKENDS: Array<{ backendType: BackendType; label: string; strengths: string }> = [
+  { backendType: "codex", label: "Codex", strengths: "focused code generation, scripts, tests, and small refactors" },
+  { backendType: "goose", label: "Goose", strengths: "local development workflows and shell-oriented implementation tasks" },
+  { backendType: "aider", label: "Aider", strengths: "direct repository patching and concise file edits" },
+  { backendType: "openhands", label: "OpenHands", strengths: "autonomous implementation work in a project workspace" },
+  { backendType: "claude", label: "Claude Code", strengths: "architecture, review, broad refactors, and high-context reasoning" },
+];
+
+export function toolNameForBackend(backendType: BackendType): string {
+  return `ask_${backendType}`;
+}
+
+export function backendFromAskTool(toolName: string): BackendType | null {
+  if (!toolName.startsWith("ask_")) return null;
+  const backend = toolName.slice(4) as BackendType;
+  return TOOL_BACKENDS.some((entry) => entry.backendType === backend) ? backend : null;
+}
+
+export function generateAgentToolDefinitions(backends: BackendType[] = TOOL_BACKENDS.map((entry) => entry.backendType)): AgentToolDefinition[] {
+  const enabled = new Set(backends);
+  return TOOL_BACKENDS
+    .filter((entry) => enabled.has(entry.backendType))
+    .map((entry) => ({
+      name: toolNameForBackend(entry.backendType),
+      backendType: entry.backendType,
+      description: `Delegate a one-turn coding subtask to ${entry.label}. Best for ${entry.strengths}. Runs in the same working directory as the lead session.`,
+      input_schema: {
+        type: "object",
+        properties: {
+          prompt: {
+            type: "string",
+            description: `Clear, specific task description for ${entry.label}.`,
+          },
+          timeout_seconds: {
+            type: "number",
+            description: "Maximum seconds to wait for the sub-agent. Defaults to 300.",
+            default: 300,
+          },
+        },
+        required: ["prompt"],
+      },
+    }));
+}
+
+export function createAgentMcpServerConfig(options: {
+  port: number;
+  token: string;
+  packageRoot: string;
+  parentSessionId: string;
+  backends?: BackendType[];
+}): McpServerConfig {
+  return {
+    type: "stdio",
+    command: "bun",
+    args: [`${options.packageRoot}/server/agent-mcp-stdio.ts`],
+    env: {
+      CAMPFIRE_AGENT_MCP_URL: `http://127.0.0.1:${options.port}/api/internal/agent-mcp`,
+      CAMPFIRE_AGENT_MCP_TOKEN: options.token,
+      CAMPFIRE_PARENT_SESSION_ID: options.parentSessionId,
+      CAMPFIRE_AGENT_MCP_BACKENDS: (options.backends ?? TOOL_BACKENDS.map((entry) => entry.backendType)).join(","),
+    },
+  };
+}