feat: Dispatch Harness, an ACP agent type with four engines and a turn-stream view

.env.example

@@ -15,3 +15,13 @@ MEDIA_ROOT=~/.dispatch/media
 # TLS (optional — both must be set to enable HTTPS)
 # TLS_CERT=~/.dispatch/tls/cert.pem
 # TLS_KEY=~/.dispatch/tls/key.pem
+
+# Dispatch Harness engines (agent type "dispatch"). Each is a host install the
+# service resolves with its own PATH, so use absolute paths. The engine is the
+# first segment of the agent's model id: claude/…, codex/…, gemini/…, opencode/….
+# DISPATCH_CLAUDE_HARNESS_BIN=~/.local/bin/claude-agent-acp
+# DISPATCH_CODEX_HARNESS_BIN=~/.local/bin/codex-acp
+# DISPATCH_GEMINI_BIN=~/.local/bin/gemini
+# DISPATCH_OPENCODE_BIN=~/.local/bin/opencode
+# The engines use the host CLIs' own logins (claude /login, codex login
+# --device-auth, NO_BROWSER=true gemini, opencode auth login); no key here.

.gitignore

@@ -29,3 +29,4 @@ opencode.json
 .cursor/mcp.json
 apps/server/src/generated/runtime-assets/
 apps/server/src/generated/runtime-assets.js
+*.bun-build

apps/browser-extension/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dispatch/browser-extension",
-  "version": "0.38.13",
+  "version": "0.38.13-harness.3",
   "private": true,
   "type": "module",
   "scripts": {

apps/browser-extension/public/manifest.json

@@ -2,7 +2,7 @@
   "manifest_version": 3,
   "name": "Dispatch Browser Feedback",
   "description": "Select live page elements and send focused feedback to a Dispatch agent.",
-  "version": "0.38.13",
+  "version": "0.38.13-harness.3",
   "minimum_chrome_version": "114",
   "permissions": ["scripting", "storage", "sidePanel"],
   "optional_host_permissions": ["<all_urls>"],

apps/server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dispatch/server",
-  "version": "0.38.13",
+  "version": "0.38.13-harness.3",
   "private": true,
   "type": "module",
   "scripts": {
@@ -15,6 +15,7 @@
     "db:migrate": "bun run prepare:runtime-assets && bun src/db/migrate.ts"
   },
   "dependencies": {
+    "@agentclientprotocol/sdk": "1.4.0",
     "@dispatch/shared": "workspace:*",
     "@fastify/cookie": "^11.0.2",
     "@fastify/multipart": "^9.4.0",

apps/server/src/agent-type-settings.ts

@@ -1,15 +1,17 @@
 import type { Pool } from "pg";
 
 import { getSetting, setSetting } from "./db/settings.js";
+import { isDispatchHarnessEnabled } from "./dispatch-harness-settings.js";
 import {
-  AGENT_TYPES,
+  DEFAULT_ENABLED_AGENT_TYPES,
   sanitizeEnabledAgentTypes,
   type AgentType,
 } from "./shared/agent-types.js";
 
 export {
   AGENT_TYPES,
   CLI_AGENT_TYPES,
+  DEFAULT_ENABLED_AGENT_TYPES,
   isCliAgentType,
   sanitizeEnabledAgentTypes,
   type AgentType,
@@ -21,13 +23,13 @@ const ENABLED_AGENT_TYPES_KEY = "enabled_agent_types";
 export async function getEnabledAgentTypes(pool: Pool): Promise<AgentType[]> {
   const raw = await getSetting(pool, ENABLED_AGENT_TYPES_KEY);
   if (!raw) {
-    return [...AGENT_TYPES];
+    return [...DEFAULT_ENABLED_AGENT_TYPES];
   }
 
   try {
     return sanitizeEnabledAgentTypes(JSON.parse(raw));
   } catch {
-    return [...AGENT_TYPES];
+    return [...DEFAULT_ENABLED_AGENT_TYPES];
   }
 }
 
@@ -39,3 +41,24 @@ export async function setEnabledAgentTypes(
   await setSetting(pool, ENABLED_AGENT_TYPES_KEY, JSON.stringify(sanitized));
   return sanitized;
 }
+
+/**
+ * What the app may create right now: the persisted enabled types plus
+ * `dispatch` when and only when the Dispatch Harness flag is on.
+ *
+ * Every creation and discovery gate reads this, not `getEnabledAgentTypes`:
+ * the create route, the reviewer-type route, `dispatch_launch_agent`, persona
+ * launches, the plugin routes and the assisted-update driver picker. That is
+ * what makes the harness's one switch reach all of them at once.
+ *
+ * No duplicate is possible: `sanitizeEnabledAgentTypes` drops `dispatch` from
+ * the persisted list on every branch, so the append below is the only place
+ * it can enter.
+ */
+export async function getOfferedAgentTypes(pool: Pool): Promise<AgentType[]> {
+  const [enabled, harnessEnabled] = await Promise.all([
+    getEnabledAgentTypes(pool),
+    isDispatchHarnessEnabled(pool),
+  ]);
+  return harnessEnabled ? [...enabled, "dispatch"] : enabled;
+}

apps/server/src/agents/activity-monitor.ts

@@ -83,7 +83,10 @@ export function createActivityMonitor(
          FROM agents
          WHERE deleted_at IS NULL
            AND status = 'running'
-           AND tmux_session IS NOT NULL`
+           AND tmux_session IS NOT NULL
+           -- harness agents derive working/idle from their ACP stream; their
+           -- pane is a plain shell whose quiet would only demote them.
+           AND type <> 'dispatch'`
       );
 
       const runningIds = new Set<string>();

apps/server/src/agents/archive.ts

@@ -25,6 +25,8 @@ export type ArchiveDeps = {
   getAgent: (id: string) => Promise<AgentRecord | null>;
   getRequiredAgent: (id: string) => Promise<AgentRecord>;
   harvestAgentTokens: (agent: AgentRecord) => Promise<void>;
+  /** Stop a protocol-driven harness that lives outside the tmux pane. */
+  stopHarness?: (agent: AgentRecord) => Promise<void>;
   setAgentStatus: (
     id: string,
     status: AgentStatus,
@@ -261,6 +263,7 @@ export async function executeArchive(
           "Stop hook failed during archive; continuing"
         )
       );
+      await deps.stopHarness?.(agent);
       if (agent.tmuxSession && (await runtime.hasSession(agent.tmuxSession))) {
         await runtime.stopSession(agent.tmuxSession, true);
       }
@@ -423,6 +426,7 @@ export async function deleteAgentDirect(
           "Stop hook failed during delete; continuing"
         )
       );
+      await deps.stopHarness?.(agent);
       if (agent.tmuxSession && sessionExists) {
         await runtime.stopSession(agent.tmuxSession, true);
       }

apps/server/src/agents/harness/agent-spec.ts

@@ -0,0 +1,117 @@
+import { HARNESS_ENGINE_IDS, type HarnessEngineId } from "@dispatch/shared";
+
+export type EngineBins = {
+  claudeHarnessBin: string;
+  codexHarnessBin: string;
+  geminiBin: string;
+  opencodeBin: string;
+  /** Absolute path to the host's `claude`, for `CLAUDE_CODE_EXECUTABLE`. */
+  claudeBin: string;
+  /** Absolute path to the host's `codex`, or null to run the adapter's bundled one. */
+  codexBin: string | null;
+};
+
+export type FullAccess =
+  /** Already in `args`. */
+  | { kind: "args" }
+  /** Already in `env`. */
+  | { kind: "env" }
+  /** `session/set_mode` to this mode id right after the session opens. */
+  | { kind: "set_mode"; modeId: string }
+  /** The agent asks per call; the driver's requestPermission handler allows. */
+  | { kind: "permission_request" };
+
+export type EngineSpec = {
+  id: HarnessEngineId;
+  bin: string;
+  args: string[];
+  env: NodeJS.ProcessEnv;
+  /**
+   * `system_prompt`: `session/new` and `session/resume` carry
+   * `_meta.systemPrompt.append`. `first_prompt`: the persona is the leading
+   * block of a fresh session's first prompt.
+   */
+  personaDelivery: "system_prompt" | "first_prompt";
+  fullAccess: FullAccess;
+  /** Declare `_meta["subagent-transcript"]` at initialize and nest by parentToolUseId. */
+  subagentTranscripts: boolean;
+  /** The model is a launch flag, so `/model` cannot switch it. */
+  modelFixedAtLaunch: boolean;
+};
+
+const ENGINE_IDS: readonly string[] = HARNESS_ENGINE_IDS;
+
+export function splitModelId(model: string): {
+  engine: HarnessEngineId;
+  model: string;
+} {
+  const slash = model.indexOf("/");
+  if (slash <= 0 || slash === model.length - 1) {
+    throw new Error(`harness model ids are engine/model; got "${model}"`);
+  }
+  const engine = model.slice(0, slash);
+  if (!ENGINE_IDS.includes(engine)) {
+    throw new Error(`unknown engine "${engine}" in model id "${model}"`);
+  }
+  return { engine: engine as HarnessEngineId, model: model.slice(slash + 1) };
+}
+
+export function engineSpecFor(
+  engine: HarnessEngineId,
+  model: string,
+  bins: EngineBins
+): EngineSpec {
+  switch (engine) {
+    case "claude":
+      return {
+        id: engine,
+        bin: bins.claudeHarnessBin,
+        args: ["--dangerously-skip-permissions"],
+        env: { CLAUDE_CODE_EXECUTABLE: bins.claudeBin },
+        personaDelivery: "system_prompt",
+        fullAccess: { kind: "args" },
+        subagentTranscripts: true,
+        modelFixedAtLaunch: false,
+      };
+    case "codex":
+      return {
+        id: engine,
+        bin: bins.codexHarnessBin,
+        args: [],
+        env: {
+          INITIAL_AGENT_MODE: "agent-full-access",
+          NO_BROWSER: "1",
+          ...(bins.codexBin ? { CODEX_PATH: bins.codexBin } : {}),
+        },
+        personaDelivery: "first_prompt",
+        fullAccess: { kind: "env" },
+        subagentTranscripts: false,
+        modelFixedAtLaunch: false,
+      };
+    case "gemini":
+      return {
+        id: engine,
+        bin: bins.geminiBin,
+        args: [
+          "--experimental-acp",
+          ...(model !== "default" ? ["--model", model] : []),
+        ],
+        env: {},
+        personaDelivery: "first_prompt",
+        fullAccess: { kind: "set_mode", modeId: "yolo" },
+        subagentTranscripts: false,
+        modelFixedAtLaunch: true,
+      };
+    case "opencode":
+      return {
+        id: engine,
+        bin: bins.opencodeBin,
+        args: ["acp"],
+        env: {},
+        personaDelivery: "first_prompt",
+        fullAccess: { kind: "permission_request" },
+        subagentTranscripts: false,
+        modelFixedAtLaunch: false,
+      };
+  }
+}