feat(dispatcher): minimal dispatcher — Phase 1 (Epic #6)

packages/adapters/claude/src/classify.ts

@@ -0,0 +1,62 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import type { HookPayload, StopClassification } from "@middle/core";
+
+const USAGE_LIMIT_RE = /You've hit your usage limit\. Resets at (.+?)\./;
+
+/**
+ * Classify the agent's state at a `Stop` hook. The interactive process does not
+ * exit between turns, so this — not an exit code — is the signal the workflow
+ * reacts to. Order matters: an open question outranks everything else.
+ *
+ * All three sentinel paths are anchored at `<worktree>/.middle/`, not at
+ * `payload.cwd`. The Claude session's `cwd` at Stop time may be a subdirectory
+ * the agent has `cd`'d into (e.g. `worktree/src/`); only the worktree root is
+ * the stable home of the workstream's sentinel files.
+ *
+ * Phase 1 detects `done`/`failed` via `.middle/done.json` / `.middle/failed.json`
+ * sentinels, parallel to the `.middle/blocked.json` question sentinel. Phase 4
+ * replaces the `done` path with the mechanically-enforced PR-ready hook gate.
+ */
+export function classifyStop(opts: {
+  payload: HookPayload;
+  transcriptPath: string;
+  sentinelPresent: boolean;
+  worktree: string;
+}): StopClassification {
+  const middleDir = join(opts.worktree, ".middle");
+
+  if (opts.sentinelPresent) {
+    return { kind: "asked-question", sentinelPath: join(middleDir, "blocked.json") };
+  }
+
+  const match = USAGE_LIMIT_RE.exec(readTail(opts.transcriptPath));
+  if (match) return { kind: "rate-limited", resetAt: match[1]! };
+
+  if (existsSync(join(middleDir, "done.json"))) return { kind: "done" };
+
+  const failedPath = join(middleDir, "failed.json");
+  if (existsSync(failedPath)) {
+    return { kind: "failed", reason: readFailedReason(failedPath) };
+  }
+
+  return { kind: "bare-stop" };
+}
+
+function readTail(path: string): string {
+  try {
+    const raw = readFileSync(path, "utf8");
+    return raw.length > 8192 ? raw.slice(-8192) : raw;
+  } catch {
+    return "";
+  }
+}
+
+function readFailedReason(path: string): string {
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf8")) as { reason?: unknown };
+    return typeof parsed.reason === "string" ? parsed.reason : "agent reported failure";
+  } catch {
+    return "agent reported failure";
+  }
+}

packages/adapters/claude/src/hooks.ts

@@ -0,0 +1,62 @@
+import { chmod, mkdir } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import type { InstallHookOpts } from "@middle/core";
+
+/**
+ * The universal hook script — POSTs the hook payload to the dispatcher. Args:
+ * `$1` is the normalized event name. Never blocks the agent (3s timeout,
+ * failure → exit 0). Source of truth: build spec → "Normalized event taxonomy".
+ */
+// curl runs as a child (not `exec`) so the trailing `|| exit 0` actually fires:
+// with `exec`, the shell is replaced by curl and a non-zero curl exit (refused
+// connection, 3s timeout, DNS) would propagate as a failed hook. As a child,
+// any curl failure is swallowed and the hook exits 0 — "failure is a no-op".
+const HOOK_SCRIPT = `#!/bin/sh
+# .middle/hooks/hook.sh — POSTs hook payloads to the middle dispatcher.
+# Args: $1 = normalized event name. Never blocks the agent; failure is a no-op.
+EVENT="$1"
+curl -sS -X POST "\${MIDDLE_DISPATCHER_URL}/hooks/\${EVENT}" \\
+  -H "X-Middle-Session: \${MIDDLE_SESSION}" \\
+  -H "X-Middle-Token: \${MIDDLE_SESSION_TOKEN}" \\
+  -H "X-Middle-Epic: \${MIDDLE_EPIC}" \\
+  -H "Content-Type: application/json" \\
+  --data-binary @- --max-time 3 || true
+exit 0
+`;
+
+/**
+ * Phase 1 install: write the universal hook script into the worktree and a
+ * minimal `.claude/settings.json` registering the two load-bearing events the
+ * `implementation` workflow depends on:
+ *
+ * - `SessionStart` → `session.started` — discovers `session_id` + `transcript_path`
+ * - `Stop` → `agent.stopped` — the turn boundary `classifyStop` reacts to
+ *
+ * Phase 2 expands to the full event taxonomy, HMAC auth, and merging into any
+ * pre-existing settings file.
+ */
+export async function installHooks(opts: InstallHookOpts): Promise<void> {
+  const scriptPath = join(opts.worktree, opts.hookScriptPath);
+  await mkdir(dirname(scriptPath), { recursive: true });
+  await Bun.write(scriptPath, HOOK_SCRIPT);
+  await chmod(scriptPath, 0o755);
+
+  const claudeDir = join(opts.worktree, ".claude");
+  await mkdir(claudeDir, { recursive: true });
+
+  // Absolute path: Claude fires hooks from whatever directory the agent has
+  // `cd`'d into, so a relative `.middle/hooks/hook.sh` would fail to resolve
+  // from a subdirectory and silently skip the POST (→ awaitStop times out).
+  // Double-quote the path so a worktree under a home dir with spaces
+  // (e.g. /Users/Jane Doe/...) doesn't mis-parse the hook command.
+  const settings = {
+    hooks: {
+      SessionStart: [
+        { hooks: [{ type: "command", command: `"${scriptPath}" session.started` }] },
+      ],
+      Stop: [{ hooks: [{ type: "command", command: `"${scriptPath}" agent.stopped` }] }],
+    },
+  };
+
+  await Bun.write(join(claudeDir, "settings.json"), `${JSON.stringify(settings, null, 2)}\n`);
+}

packages/adapters/claude/src/index.ts

@@ -1,3 +1,101 @@
 // @middle/adapter-claude — implements AgentAdapter for the Claude CLI.
-// Source lands in build-spec Phase 1 (spawn + classify) and Phase 2 (hooks).
-export {};
+import type { AgentAdapter } from "@middle/core";
+import { capturePane, pollPaneFor, sendKeys } from "@middle/core";
+import { classifyStop } from "./classify.ts";
+import { installHooks } from "./hooks.ts";
+import { buildPromptText } from "./prompt.ts";
+import { readTranscriptState, resolveTranscriptPath } from "./transcript.ts";
+
+/**
+ * `--dangerously-skip-permissions` is the auto-mode flag — runtime-equivalent
+ * to bypassPermissions, but still pops a one-time "are you sure?" warning at
+ * boot. `enterAutoMode` dismisses it.
+ */
+const AUTO_MODE_FLAG = "--dangerously-skip-permissions";
+
+const BYPASS_PROMPT_RE = /bypass\s+permissions?|skip\s+permissions?|dangerously/i;
+const NEEDS_LOGIN_RE =
+  /please\s+(?:run\s+|use\s+)?(?:claude\s+)?\/?(?:login|sign[ -]?in)|not\s+(?:logged\s+in|authenticated|signed\s+in)|welcome\s+to\s+claude\s+code.*sign|invalid\s+(?:api\s+key|credentials)/i;
+
+/** Whether a captured pane shows Claude's bypass-mode confirmation prompt. */
+export function detectBypassPrompt(paneContent: string): boolean {
+  return BYPASS_PROMPT_RE.test(paneContent);
+}
+
+/** Whether a captured pane shows a "you need to log in" message. */
+export function detectNeedsLogin(paneContent: string): boolean {
+  return NEEDS_LOGIN_RE.test(paneContent);
+}
+
+/** Long polling window — covers Claude's slowest boot up to launchTimeout. */
+const BOOT_DETECT_TIMEOUT_MS = 90_000;
+
+type BootOutcome = "bypass-prompt" | "needs-login";
+
+/**
+ * Pre-SessionStart boot polling. Runs in parallel with `awaitSessionStart`
+ * because Claude does not fire SessionStart until past the bypass-mode
+ * warning. Two outcomes drive action:
+ *
+ * - `bypass-prompt`: send Down + Enter (split with a 100ms delay so the menu
+ *   has time to advance selection between keys) to select "Yes, I accept".
+ *   Claude proceeds and fires SessionStart shortly after.
+ * - `needs-login`: throw a clean error so `mm dispatch` exits with a useful
+ *   "claude is not authenticated" message instead of hanging on a 90s
+ *   SessionStart timeout.
+ */
+async function enterAutoMode(opts: { sessionName: string }): Promise<void> {
+  const tag = `claude:${opts.sessionName}`;
+  const outcome = await pollPaneFor<BootOutcome>(
+    opts.sessionName,
+    (pane) => {
+      if (detectNeedsLogin(pane)) return "needs-login";
+      if (detectBypassPrompt(pane)) return "bypass-prompt";
+      return null;
+    },
+    { timeoutMs: BOOT_DETECT_TIMEOUT_MS, pollIntervalMs: 200, tag },
+  );
+
+  if (outcome === "needs-login") {
+    throw new Error(
+      "claude is not authenticated — run `claude` interactively in a normal terminal to sign in, then retry the dispatch",
+    );
+  }
+  if (outcome === "bypass-prompt") {
+    console.error(`[${tag}] bypass prompt detected — settling then Down then Enter`);
+    await Bun.sleep(200);
+    await sendKeys(opts.sessionName, ["Down", "Enter"], { delayBetweenMs: 100 });
+    // Post-keystroke capture confirms whether the menu actually advanced.
+    await Bun.sleep(300);
+    const after = await capturePane(opts.sessionName);
+    const afterTail = (after ?? "<capture failed>").replace(/\s+/g, " ").trim().slice(-300);
+    console.error(`[${tag}] post-keystroke pane tail: "${afterTail}"`);
+  }
+  // outcome null: neither prompt nor login screen appeared. SessionStart should
+  // already have fired (or be about to). enterAutoMode has nothing else to do.
+}
+
+export const claudeAdapter: AgentAdapter = {
+  name: "claude",
+  readyEvent: "session.started",
+  installHooks,
+  buildLaunchCommand(opts) {
+    // Interactive — no `-p`, no prompt. `--dangerously-skip-permissions`
+    // engages auto mode AND suppresses the API-permission gate (the bypass
+    // confirmation TUI is separate, dismissed via enterAutoMode). Env is
+    // injected by tmux at spawn time.
+    return {
+      argv: ["claude", AUTO_MODE_FLAG],
+      env: {
+        MIDDLE_SESSION: opts.sessionName,
+        MIDDLE_SESSION_TOKEN: opts.sessionToken,
+        ...opts.envOverrides,
+      },
+    };
+  },
+  buildPromptText,
+  enterAutoMode,
+  resolveTranscriptPath,
+  readTranscriptState,
+  classifyStop,
+};

packages/adapters/claude/src/prompt.ts

@@ -0,0 +1,21 @@
+/**
+ * The literal text `send-keys` carries into a tmux session to start or continue
+ * the agent. `send-keys` cannot cleanly carry a multi-line prompt — embedded
+ * newlines submit early — so the full prompt lives on disk and this returns a
+ * one-line `@`-reference that force-includes it. A single `@` prefixes the
+ * whole relative path.
+ */
+export function buildPromptText(opts: {
+  promptFile: string;
+  kind: "initial" | "resume" | "answer";
+}): string {
+  const ref = `@${opts.promptFile}`;
+  switch (opts.kind) {
+    case "initial":
+      return ref;
+    case "resume":
+      return `Resuming this workstream — re-read the linked context and continue. ${ref}`;
+    case "answer":
+      return `A human answered your open question — read the answer and continue. ${ref}`;
+  }
+}

packages/adapters/claude/src/transcript.ts

@@ -0,0 +1,76 @@
+import { readFileSync } from "node:fs";
+import type { HookPayload, TranscriptState } from "@middle/core";
+
+/** Claude delivers `transcript_path` directly in the SessionStart hook payload. */
+export function resolveTranscriptPath(payload: HookPayload): string {
+  const path = payload.transcript_path;
+  if (typeof path !== "string" || path.length === 0) {
+    throw new Error("SessionStart payload has no transcript_path");
+  }
+  return path;
+}
+
+type TranscriptLine = {
+  type?: string;
+  timestamp?: string;
+  message?: {
+    role?: string;
+    content?: unknown;
+    usage?: Record<string, number>;
+  };
+};
+
+function isToolUseBlock(block: unknown): block is { type: "tool_use"; name?: string } {
+  return (
+    typeof block === "object" &&
+    block !== null &&
+    (block as { type?: string }).type === "tool_use"
+  );
+}
+
+/**
+ * Parse the JSONL transcript for activity, turn count, last tool use, and
+ * context-token usage. Corrupt lines are skipped rather than thrown on — the
+ * transcript reconciler cron (Phase 2) is the authoritative reader; this is the
+ * fast-path estimate. `contextTokens` is the input side of the last assistant
+ * turn (prompt + cache), i.e. how full the context window is.
+ */
+export function readTranscriptState(transcriptPath: string): TranscriptState {
+  const raw = readFileSync(transcriptPath, "utf8");
+  let lastActivity = "";
+  let turnCount = 0;
+  let lastToolUse: string | null = null;
+  let contextTokens = 0;
+
+  for (const line of raw.split("\n")) {
+    const trimmed = line.trim();
+    if (trimmed === "") continue;
+    let entry: TranscriptLine;
+    try {
+      entry = JSON.parse(trimmed) as TranscriptLine;
+    } catch {
+      continue;
+    }
+    if (typeof entry.timestamp === "string") lastActivity = entry.timestamp;
+    if (entry.type !== "assistant") continue;
+
+    turnCount++;
+    const content = entry.message?.content;
+    if (Array.isArray(content)) {
+      for (const block of content) {
+        if (isToolUseBlock(block) && typeof block.name === "string") {
+          lastToolUse = block.name;
+        }
+      }
+    }
+    const usage = entry.message?.usage;
+    if (usage) {
+      contextTokens =
+        (usage.input_tokens ?? 0) +
+        (usage.cache_read_input_tokens ?? 0) +
+        (usage.cache_creation_input_tokens ?? 0);
+    }
+  }
+
+  return { lastActivity, contextTokens, turnCount, lastToolUse };
+}