feat: normalized external-agent status (#10 scoped) (v2.7.6)

Scoped half of boocode_code_review_v2 §1 #10 — publish the agent status
BooCoder already observes (the config-injection notify-hook is the documented
follow-on, clean-room from superset ELv2).

- agent_status_updated WS frame (working|blocked|idle|error), server+web parity.
- Published from the dispatcher's turn boundaries (warm-acp/opencode/sdk/pty:
  working at start, idle/error at end) + the permission flow (blocked/working).
  Best-effort, never breaks a turn.
- Clean-room normalizeAgentEvent helper (superset's vendor-event -> Start/blocked
  /Stop collapse, event names as facts) + 25 tests — reused by the follow-on.
- AgentComposerBar status dot (distinct from the WS-liveness dot), tracked per
  (chat,agent) by a useAgentStatus map in CoderPane.

Built by 2 parallel agents vs a pinned frame contract. Server 545 + coder 294
tests passing (25 new); web tsc + builds clean; ws-frames parity green. Clears
the actionable review backlog (#1/#3/#4/#6-#12). Builds on v2.7.5.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

apps/coder/src/index.ts

@@ -42,6 +42,7 @@ import { createOrphanWorktreeReaper } from './services/orphan-worktree-reaper.js
 import { probeAgents } from './services/agent-probe.js';
 import { getProviderSnapshot, persistProbedModels } from './services/provider-snapshot.js';
 import { setPermissionHooks } from './services/permission-waiter.js';
+import { publishAgentStatus } from './services/agent-status-publish.js';
 import { homedir } from 'node:os';
 
 async function main() {
@@ -82,6 +83,21 @@ async function main() {
   // Broker: in-memory pub/sub for session + user channel streaming.
   const broker = createBroker(app.log);
 
+  // agent-status-normalize (#10): the permission hooks carry only taskId +
+  // sessionId, but the tasks row holds the (chat_id, agent) pair the status frame
+  // is keyed on. Resolve it best-effort so a blocked/working status accompanies
+  // every permission_requested/permission_resolved. Returns null when the task
+  // lacks a chat_id or agent (sessionless creators) — we simply skip the status.
+  const resolveChatAgent = async (
+    taskId: string,
+  ): Promise<{ chatId: string; agent: string } | null> => {
+    const [row] = await sql<{ chat_id: string | null; agent: string | null }[]>`
+      SELECT chat_id, agent FROM tasks WHERE id = ${taskId}
+    `;
+    if (!row?.chat_id || !row.agent) return null;
+    return { chatId: row.chat_id, agent: row.agent };
+  };
+
   setPermissionHooks({
     onPrompt: async (prompt) => {
       await sql`
@@ -96,6 +112,18 @@ async function main() {
         ...(prompt.input ? { input: prompt.input } : {}),
         options: prompt.options.map((o) => ({ option_id: o.optionId, label: o.label })),
       } as WsFrame);
+      // #10: agent is blocked on a human decision.
+      const ca = await resolveChatAgent(prompt.taskId).catch(() => null);
+      if (ca) {
+        publishAgentStatus(
+          broker.publishFrame,
+          prompt.sessionId,
+          ca.chatId,
+          ca.agent,
+          'blocked',
+          'permission_request',
+        );
+      }
     },
     onResolved: async (taskId, sessionId) => {
       await sql`
@@ -106,6 +134,18 @@ async function main() {
         task_id: taskId,
         session_id: sessionId,
       } as WsFrame);
+      // #10: human responded — agent resumes work.
+      const ca = await resolveChatAgent(taskId).catch(() => null);
+      if (ca) {
+        publishAgentStatus(
+          broker.publishFrame,
+          sessionId,
+          ca.chatId,
+          ca.agent,
+          'working',
+          'permission_resolved',
+        );
+      }
     },
   });
 

apps/coder/src/services/__tests__/normalize-agent-status.test.ts

@@ -0,0 +1,83 @@
+import { describe, it, expect } from 'vitest';
+import { normalizeAgentEvent } from '../normalize-agent-status.js';
+
+describe('normalizeAgentEvent', () => {
+  describe('working bucket', () => {
+    const cases = [
+      'SessionStart',
+      'UserPromptSubmit',
+      'UserPromptSubmitted',
+      'PostToolUse',
+      'PostToolUseFailure',
+      'BeforeAgent',
+      'AfterTool',
+      'task_started',
+    ];
+    for (const name of cases) {
+      it(`maps ${name} → working`, () => {
+        expect(normalizeAgentEvent(name)).toBe('working');
+      });
+    }
+  });
+
+  describe('blocked bucket', () => {
+    const cases = [
+      'PreToolUse',
+      'Notification',
+      'PermissionRequest',
+      'exec_approval_request',
+      'apply_patch_approval_request',
+      'request_user_input',
+    ];
+    for (const name of cases) {
+      it(`maps ${name} → blocked`, () => {
+        expect(normalizeAgentEvent(name)).toBe('blocked');
+      });
+    }
+  });
+
+  describe('done bucket', () => {
+    const cases = [
+      'Stop',
+      'AfterAgent',
+      'SessionEnd',
+      'task_complete',
+      'agent-turn-complete',
+    ];
+    for (const name of cases) {
+      it(`maps ${name} → done`, () => {
+        expect(normalizeAgentEvent(name)).toBe('done');
+      });
+    }
+  });
+
+  describe('unknown / nullish → null', () => {
+    it('returns null for an unrecognized event', () => {
+      expect(normalizeAgentEvent('SomeRandomEvent')).toBeNull();
+    });
+    it('returns null for empty string', () => {
+      expect(normalizeAgentEvent('')).toBeNull();
+    });
+    it('returns null for undefined', () => {
+      expect(normalizeAgentEvent(undefined)).toBeNull();
+    });
+  });
+
+  describe('case- and separator-insensitive matching', () => {
+    it('matches snake_case spelling of a PascalCase event', () => {
+      expect(normalizeAgentEvent('session_start')).toBe('working');
+      expect(normalizeAgentEvent('post_tool_use')).toBe('working');
+      expect(normalizeAgentEvent('pre_tool_use')).toBe('blocked');
+    });
+    it('matches camelCase spelling', () => {
+      expect(normalizeAgentEvent('userPromptSubmitted')).toBe('working');
+      expect(normalizeAgentEvent('postToolUse')).toBe('working');
+      expect(normalizeAgentEvent('preToolUse')).toBe('blocked');
+      expect(normalizeAgentEvent('sessionEnd')).toBe('done');
+    });
+    it('matches arbitrary case', () => {
+      expect(normalizeAgentEvent('STOP')).toBe('done');
+      expect(normalizeAgentEvent('notification')).toBe('blocked');
+    });
+  });
+});

apps/coder/src/services/agent-status-publish.ts

@@ -0,0 +1,55 @@
+/**
+ * agent-status-publish (#10) — builds + publishes the `agent_status_updated`
+ * WS frame on the per-session channel (the same channel CoderPane subscribes to).
+ *
+ * Kept separate from normalize-agent-status.ts so that module stays a pure,
+ * broker-free helper (trivially unit-testable; reused by the config-injection
+ * follow-on). The frame contract is pinned in apps/server/src/types/ws-frames.ts
+ * (`AgentStatusUpdatedFrame`) and mirrored byte-identical in apps/web.
+ */
+import type { Broker } from '@boocode/server/broker';
+import type { WsFrame } from '@boocode/server/ws-frames';
+import type { AgentStatus } from './normalize-agent-status.js';
+
+// The exact slice of Broker we need — accepting just the bound method keeps call
+// sites flexible (pass `broker.publishFrame.bind(broker)` or, since the broker's
+// publishFrame doesn't read `this`, `broker.publishFrame` directly).
+type PublishFrame = Broker['publishFrame'];
+
+/**
+ * Best-effort publish of a normalized agent status. The broker's publishFrame
+ * already fail-closes (validates + logs + drops on bad input, never throws), but
+ * we additionally swallow any unexpected error so a publish can NEVER break the
+ * turn it's reporting on.
+ *
+ * @param publishFrame  the session channel publisher (broker.publishFrame)
+ * @param sessionId     WS subscription channel (CoderPane subscribes per-session)
+ * @param chatId        the (chat) half of the (chat, agent) status key
+ * @param agent         the (agent) half of the key
+ * @param status        normalized lifecycle status
+ * @param reason        free-form discriminator (turn_start / turn_complete / …)
+ * @param at            ISO timestamp; defaults to now
+ */
+export function publishAgentStatus(
+  publishFrame: PublishFrame,
+  sessionId: string,
+  chatId: string,
+  agent: string,
+  status: AgentStatus,
+  reason?: string,
+  at: string = new Date().toISOString(),
+): void {
+  try {
+    const frame: WsFrame = {
+      type: 'agent_status_updated',
+      chat_id: chatId,
+      agent,
+      status,
+      ...(reason ? { reason } : {}),
+      at,
+    };
+    publishFrame(sessionId, frame);
+  } catch {
+    // never let a status publish break the turn — best-effort only.
+  }
+}

apps/coder/src/services/dispatcher.ts

@@ -20,6 +20,8 @@ import { ClaudeSdkBackend } from './backends/claude-sdk.js';
 import { shouldUseWarmBackend } from './backends/warm-acp-routing.js';
 import { shouldUseClaudeSdk } from './backends/claude-sdk-routing.js';
 import type { AgentBackend, AgentEvent } from './agent-backend.js';
+import { publishAgentStatus } from './agent-status-publish.js';
+import type { AgentStatus } from './normalize-agent-status.js';
 
 interface InferenceRunner {
   enqueue: (sessionId: string, chatId: string, assistantId: string, user: string) => void;
@@ -66,6 +68,21 @@ export function createDispatcher(deps: Deps): { start(): void; stop(): Promise<v
     return task.session_id ?? `task:${task.id}`;
   }
 
+  // agent-status-normalize (#10): publish a normalized per-(chat,agent) status on
+  // the session channel. Every external-agent path (warm-acp / opencode / claude-sdk /
+  // pty one-shot) reports `working` at turn start, `idle` on clean completion, and
+  // `error` on the failure path through this single helper so the four paths stay
+  // DRY and consistent. Best-effort — publishAgentStatus never throws.
+  function emitAgentStatus(
+    sessionId: string,
+    chatId: string,
+    agent: string,
+    status: AgentStatus,
+    reason: string,
+  ): void {
+    publishAgentStatus(broker.publishFrame, sessionId, chatId, agent, status, reason);
+  }
+
   async function poll(): Promise<void> {
     // `polling` serializes poll() execution itself (timer + NOTIFY can fire
     // concurrently) so we never double-select a task. It does NOT serialize task
@@ -298,6 +315,11 @@ export function createDispatcher(deps: Deps): { start(): void; stop(): Promise<v
     // Create an abort controller for this task
     const ac = new AbortController();
 
+    // #10: hoisted above the try so the catch block can report `error` status with
+    // the (chat, agent) key. Empty until resolved below; guarded before use.
+    let sessionId = '';
+    let chatId = '';
+
     try {
       // Mark running
       await sql`
@@ -306,9 +328,6 @@ export function createDispatcher(deps: Deps): { start(): void; stop(): Promise<v
         WHERE id = ${taskId}
       `;
 
-      let sessionId: string;
-      let chatId: string;
-
       if (task.session_id) {
         sessionId = task.session_id;
         const chats = await sql<{ id: string }[]>`
@@ -384,6 +403,9 @@ export function createDispatcher(deps: Deps): { start(): void; stop(): Promise<v
         role: 'assistant',
       } as WsFrame);
 
+      // #10: external-agent turn begins.
+      emitAgentStatus(sessionId, chatId, agent, 'working', 'turn_start');
+
       const manifestCommands = getManifestCommands(agent);
       if (manifestCommands.length > 0) {
         setTaskCommands(taskId, manifestCommands);
@@ -558,6 +580,8 @@ export function createDispatcher(deps: Deps): { start(): void; stop(): Promise<v
         WHERE id = ${taskId}
       `;
       log.info({ taskId, agent, costTokens: extCostTokens }, 'dispatcher: task completed (external)');
+      // #10: external-agent turn completed cleanly.
+      emitAgentStatus(sessionId, chatId, agent, 'idle', 'turn_complete');
       clearTaskCommands(taskId);
 
     } catch (err) {
@@ -570,6 +594,11 @@ export function createDispatcher(deps: Deps): { start(): void; stop(): Promise<v
         WHERE id = ${taskId}
       `.catch(() => {});
 
+      // #10: external-agent turn failed/crashed. chatId may be unbound if the throw
+      // preceded its assignment — guard so the status publish never masks the real
+      // error.
+      if (chatId) emitAgentStatus(sessionId, chatId, agent, 'error', 'failed');
+
       // Best-effort cleanup
       await cleanupWorktree(projectPath, taskId);
       clearTaskCommands(taskId);
@@ -624,6 +653,10 @@ export function createDispatcher(deps: Deps): { start(): void; stop(): Promise<v
 
     const ac = new AbortController();
 
+    // #10: hoisted so the catch can report `error` with the (chat, agent) key.
+    let sessionId = '';
+    let chatId = '';
+
     try {
       // execution_path = 'acp' — the schema CHECK has no 'opencode_server' value
       // (schema is frozen at Phase 0); the warm-vs-one-shot distinction lives in
@@ -640,8 +673,6 @@ export function createDispatcher(deps: Deps): { start(): void; stop(): Promise<v
       // it directly. Session-less creators (arena, MCP, new_task, generic
       // /api/tasks) leave it null; fall back to resolving/creating a real chat so
       // ensureSession never receives a degenerate (null, agent) key.
-      let sessionId: string;
-      let chatId: string;
       if (task.chat_id && task.session_id) {
         sessionId = task.session_id;
         chatId = task.chat_id;
@@ -714,6 +745,9 @@ export function createDispatcher(deps: Deps): { start(): void; stop(): Promise<v
         role: 'assistant',
       } as WsFrame);
 
+      // #10: opencode-server turn begins.
+      emitAgentStatus(sessionId, chatId, agent, 'working', 'turn_start');
+
       const manifestCommands = getManifestCommands(agent);
       if (manifestCommands.length > 0) {
         setTaskCommands(taskId, manifestCommands);
@@ -873,6 +907,14 @@ export function createDispatcher(deps: Deps): { start(): void; stop(): Promise<v
         WHERE id = ${taskId}
       `;
       log.info({ taskId, agent, finalState, costTokens: extCostTokens }, 'dispatcher: task finished (opencode server)');
+      // #10: clean completion → idle; backend-reported failure → error.
+      emitAgentStatus(
+        sessionId,
+        chatId,
+        agent,
+        result.ok ? 'idle' : 'error',
+        result.ok ? 'turn_complete' : 'failed',
+      );
       clearTaskCommands(taskId);
     } catch (err) {
       const errMsg = err instanceof Error ? err.message : String(err);
@@ -882,6 +924,8 @@ export function createDispatcher(deps: Deps): { start(): void; stop(): Promise<v
         SET state = 'failed', ended_at = clock_timestamp(), output_summary = ${errMsg.slice(0, 500)}
         WHERE id = ${taskId}
       `.catch(() => {});
+      // #10: turn crashed.
+      if (chatId) emitAgentStatus(sessionId, chatId, agent, 'error', 'crashed');
       clearTaskCommands(taskId);
       // No worktree cleanup (persistent); backend stays warm for the next turn.
     }
@@ -982,6 +1026,9 @@ export function createDispatcher(deps: Deps): { start(): void; stop(): Promise<v
         role: 'assistant',
       } as WsFrame);
 
+      // #10: warm-ACP turn begins.
+      emitAgentStatus(sessionId, chatId, agent, 'working', 'turn_start');
+
       const manifestCommands = getManifestCommands(agent);
       if (manifestCommands.length > 0) {
         setTaskCommands(taskId, manifestCommands);
@@ -1123,6 +1170,14 @@ export function createDispatcher(deps: Deps): { start(): void; stop(): Promise<v
         WHERE id = ${taskId}
       `;
       log.info({ taskId, agent, finalState }, 'dispatcher: task finished (warm ACP)');
+      // #10: clean completion → idle; backend-reported failure → error.
+      emitAgentStatus(
+        sessionId,
+        chatId,
+        agent,
+        result.ok ? 'idle' : 'error',
+        result.ok ? 'turn_complete' : 'failed',
+      );
       clearTaskCommands(taskId);
     } catch (err) {
       const errMsg = err instanceof Error ? err.message : String(err);
@@ -1132,6 +1187,8 @@ export function createDispatcher(deps: Deps): { start(): void; stop(): Promise<v
         SET state = 'failed', ended_at = clock_timestamp(), output_summary = ${errMsg.slice(0, 500)}
         WHERE id = ${taskId}
       `.catch(() => {});
+      // #10: turn crashed.
+      emitAgentStatus(sessionId, chatId, agent, 'error', 'crashed');
       clearTaskCommands(taskId);
       // No worktree cleanup (persistent); backend stays warm for the next turn.
     }
@@ -1224,6 +1281,9 @@ export function createDispatcher(deps: Deps): { start(): void; stop(): Promise<v
         role: 'assistant',
       } as WsFrame);
 
+      // #10: claude-SDK turn begins.
+      emitAgentStatus(sessionId, chatId, agent, 'working', 'turn_start');
+
       const manifestCommands = getManifestCommands(agent);
       if (manifestCommands.length > 0) {
         setTaskCommands(taskId, manifestCommands);
@@ -1364,6 +1424,14 @@ export function createDispatcher(deps: Deps): { start(): void; stop(): Promise<v
         WHERE id = ${taskId}
       `;
       log.info({ taskId, agent, finalState }, 'dispatcher: task finished (claude SDK)');
+      // #10: clean completion → idle; backend-reported failure → error.
+      emitAgentStatus(
+        sessionId,
+        chatId,
+        agent,
+        result.ok ? 'idle' : 'error',
+        result.ok ? 'turn_complete' : 'failed',
+      );
       clearTaskCommands(taskId);
     } catch (err) {
       const errMsg = err instanceof Error ? err.message : String(err);
@@ -1373,6 +1441,8 @@ export function createDispatcher(deps: Deps): { start(): void; stop(): Promise<v
         SET state = 'failed', ended_at = clock_timestamp(), output_summary = ${errMsg.slice(0, 500)}
         WHERE id = ${taskId}
       `.catch(() => {});
+      // #10: turn crashed.
+      emitAgentStatus(sessionId, chatId, agent, 'error', 'crashed');
       clearTaskCommands(taskId);
       // No worktree cleanup (persistent); backend stays warm for the next turn.
     }

apps/coder/src/services/normalize-agent-status.ts

@@ -0,0 +1,92 @@
+/**
+ * normalize-agent-status (#10) — clean-room vendor-event → bucket mapping.
+ *
+ * Different coding agents (claude, opencode, codex/gemini, goose, qwen) emit
+ * lifecycle hook events under inconsistent names: PascalCase (`SessionStart`),
+ * snake_case (`session_start`), camelCase (`sessionStart`), and a handful of
+ * provider-specific approval events (`exec_approval_request`). This module
+ * collapses every known event name into one of three coarse signals:
+ *
+ *   working  — the agent is actively progressing a turn
+ *   blocked  — the agent is waiting on a human (permission / approval / question)
+ *   done     — the turn / session ended cleanly
+ *
+ * `null` is returned for anything unrecognized so callers can ignore noise.
+ *
+ * Built now for the scoped status-publish, but specifically shaped for reuse by
+ * the documented config-injection follow-on: a future notify-hook injected into
+ * each agent's native config will POST the RAW vendor event name to a BooCoder
+ * endpoint, which runs this helper to derive the normalized status. The names
+ * below are facts about each agent's hook surface — not copied vendor code.
+ */
+
+export type AgentStatus = 'working' | 'blocked' | 'idle' | 'error';
+
+/** The coarse signal a raw vendor event collapses to. */
+export type AgentEventBucket = 'working' | 'blocked' | 'done';
+
+// Each bucket lists the canonical vendor event names. Lookup is
+// case-insensitive AND separator-insensitive (snake_case / camelCase /
+// PascalCase all fold to the same key), so we normalize the raw input the same
+// way before matching rather than enumerating every spelling here.
+const WORKING_EVENTS = [
+  'SessionStart',
+  'UserPromptSubmit',
+  'UserPromptSubmitted',
+  'PostToolUse',
+  'PostToolUseFailure',
+  'BeforeAgent',
+  'AfterTool',
+  'task_started',
+] as const;
+
+const BLOCKED_EVENTS = [
+  'PreToolUse',
+  'Notification',
+  'PermissionRequest',
+  'exec_approval_request',
+  'apply_patch_approval_request',
+  'request_user_input',
+] as const;
+
+const DONE_EVENTS = [
+  'Stop',
+  'AfterAgent',
+  'SessionEnd',
+  'task_complete',
+  'agent-turn-complete',
+] as const;
+
+/**
+ * Fold a raw event name to a separator/case-insensitive key:
+ * strip every non-alphanumeric character and lowercase. So `post_tool_use`,
+ * `postToolUse`, `PostToolUse`, and `POST-TOOL-USE` all map to `posttooluse`.
+ */
+function foldKey(raw: string): string {
+  return raw.replace(/[^a-z0-9]/gi, '').toLowerCase();
+}
+
+function buildLookup(
+  groups: ReadonlyArray<readonly [AgentEventBucket, readonly string[]]>,
+): Map<string, AgentEventBucket> {
+  const map = new Map<string, AgentEventBucket>();
+  for (const [bucket, names] of groups) {
+    for (const name of names) map.set(foldKey(name), bucket);
+  }
+  return map;
+}
+
+const EVENT_LOOKUP = buildLookup([
+  ['working', WORKING_EVENTS],
+  ['blocked', BLOCKED_EVENTS],
+  ['done', DONE_EVENTS],
+]);
+
+/**
+ * Map a raw vendor hook-event name to its normalized bucket, or `null` when the
+ * name is unknown / undefined. Case- and separator-insensitive.
+ */
+export function normalizeAgentEvent(raw: string | undefined): AgentEventBucket | null {
+  if (!raw) return null;
+  return EVENT_LOOKUP.get(foldKey(raw)) ?? null;
+}