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,54 @@
+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".
+ */
+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"
+exec 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 || 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 });
+
+  const settings = {
+    hooks: {
+      SessionStart: [
+        { hooks: [{ type: "command", command: `${opts.hookScriptPath} session.started` }] },
+      ],
+      Stop: [
+        { hooks: [{ type: "command", command: `${opts.hookScriptPath} agent.stopped` }] },
+      ],
+    },
+  };
+
+  await Bun.write(join(claudeDir, "settings.json"), `${JSON.stringify(settings, null, 2)}\n`);
+}

packages/adapters/claude/src/index.ts

@@ -1,3 +1,54 @@
 // @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 { classifyStop } from "./classify.ts";
+import { installHooks } from "./hooks.ts";
+import { buildPromptText } from "./prompt.ts";
+import { readTranscriptState, resolveTranscriptPath } from "./transcript.ts";
+
+/**
+ * Bring the ready session into auto mode. Claude's interactive mode honors no
+ * launch flag for this, so the guaranteed path is two Shift-Tab keystrokes sent
+ * into the live tmux session. The adapter shells out to `tmux` directly rather
+ * than depending on the dispatcher's richer helper module — entering auto mode
+ * is intrinsically a per-CLI keystroke concern the adapter owns.
+ *
+ * A non-zero exit from `tmux send-keys` (missing session, tmux not on PATH)
+ * throws so `launchAndDrive`'s catch can kill the session and compensate —
+ * otherwise the workflow would silently proceed to send the prompt into a
+ * session that never entered auto mode and never reaches `Stop`.
+ */
+async function enterAutoMode(opts: { sessionName: string }): Promise<void> {
+  const proc = Bun.spawn(["tmux", "send-keys", "-t", opts.sessionName, "S-Tab", "S-Tab"], {
+    stdout: "ignore",
+    stderr: "pipe",
+  });
+  const stderr = await new Response(proc.stderr).text();
+  const exitCode = await proc.exited;
+  if (exitCode !== 0) {
+    throw new Error(
+      `enterAutoMode: tmux send-keys to "${opts.sessionName}" failed (exit ${exitCode}): ${stderr.trim()}`,
+    );
+  }
+}
+
+export const claudeAdapter: AgentAdapter = {
+  name: "claude",
+  readyEvent: "session.started",
+  installHooks,
+  buildLaunchCommand(opts) {
+    // Interactive — no `-p`, no prompt. Env is injected by tmux at spawn time.
+    return {
+      argv: ["claude"],
+      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 };
+}