@yeaft/webchat-agent 0.1.510 → 0.1.512

package/connection/message-router.js

@@ -1,3 +1,14 @@
+/**
+ * message-router.js — Server-bound message dispatcher.
+ *
+ * task-330c lint guard:
+ *   ⚠️ DO NOT introduce greedy `text.replace(/---ROUTE---[\s\S]*$/g, '')`
+ *      style strips on routed message payloads. Crew ROUTE stripping is
+ *      owned EXCLUSIVELY by `agent/crew/routing.js` `parseRoutes()` which
+ *      returns `{routes, displayBody}` with exact ranges removed. A second
+ *      strip here would re-process already-cleaned text and risks both
+ *      double-strip artefacts and the trailing-prose bug fixed by task-328.
+ */
 import ctx from '../context.js';
 import { decodeKey } from '../encryption.js';
 import { handleTerminalCreate, handleTerminalInput, handleTerminalResize, handleTerminalClose } from '../terminal.js';

package/crew/builtin-actions.js

@@ -0,0 +1,154 @@
+/**
+ * Crew — built-in role actions (task-330a §B)
+ *
+ * These two actions replace the "PM 给自己发闭环消息" anti-pattern that
+ * task-330a §A now rejects at the routing layer:
+ *
+ *   • taskClose(session, { taskId, summary, fromRole })
+ *       — directly mark the task complete on the kanban + broadcast a
+ *         status card via sendCrewMessage. No ROUTE round-trip.
+ *
+ *   • roleStandby(session, { role, reason, fromRole })
+ *       — flip a role's runtime state to 'standby' and broadcast.
+ *         Persistence to .crew/context/role-states.json is a 330d
+ *         concern — we only define the in-memory contract here.
+ *
+ * Both functions are pure server-side helpers. They do NOT consume a
+ * routing turn (no session.round++, no dispatchToRole). Callers that
+ * choose to expose them as Claude tools (via canCallTool / mcp) must
+ * wire that separately — task-330a defines the contract; tool-binding
+ * lands in 330d alongside the role-state persistence layer.
+ *
+ * Red lines (per PM dispatch):
+ *   - Do not mutate routing protocol shape (.routes / displayBody).
+ *   - Do not break task-319/328 (parser tests stay green).
+ *   - Old session replay must keep working — we only add new keys to
+ *     session.roleStates[role], never remove.
+ */
+
+import { sendCrewMessage, sendStatusUpdate } from './ui-messages.js';
+import { updateKanban, appendChangelog, updateFeatureIndex, isValidTaskId } from './task-files.js';
+
+/** Valid standby reasons — extend with care; consumers may grep for these. */
+export const STANDBY_REASONS = Object.freeze([
+  'task_closed', 'awaiting_input', 'manual', 'idle', 'paused',
+]);
+
+/**
+ * Mark a task as complete on the kanban + broadcast a status card.
+ *
+ * Mirrors the side-effects that role-output.js performs when it detects a
+ * completed TASKS block, so the two paths converge on the same kanban
+ * state regardless of which one fires.
+ *
+ * @param {object} session
+ * @param {{ taskId: string, summary?: string, fromRole?: string }} params
+ * @returns {Promise<{ ok: boolean, taskId: string, reason?: string }>}
+ */
+export async function taskClose(session, { taskId, summary, fromRole }) {
+  if (!session) {
+    return { ok: false, taskId: taskId || null, reason: 'no_session' };
+  }
+  if (!taskId || !isValidTaskId(taskId)) {
+    return { ok: false, taskId: taskId || null, reason: 'invalid_task_id' };
+  }
+
+  // Mark in the in-memory completion set so future kanban rebuilds keep it.
+  if (!session._completedTaskIds) session._completedTaskIds = new Set();
+  const wasAlreadyCompleted = session._completedTaskIds.has(taskId);
+  session._completedTaskIds.add(taskId);
+
+  const feature = session.features?.get(taskId);
+  const taskTitle = feature?.taskTitle || taskId;
+  const cleanSummary = (summary && String(summary).trim()) || '已完成';
+
+  // Persist to the kanban file (best-effort; warns on failure).
+  try {
+    await updateKanban(session, { taskId, completed: true, summary: cleanSummary });
+  } catch (e) {
+    console.warn(`[Crew] taskClose: updateKanban failed for ${taskId}:`, e.message);
+  }
+
+  // Append to features index + changelog only on first close (idempotent).
+  if (!wasAlreadyCompleted) {
+    updateFeatureIndex(session)
+      .catch(e => console.warn('[Crew] taskClose: updateFeatureIndex failed:', e.message));
+    appendChangelog(session, taskId, taskTitle)
+      .catch(e => console.warn(`[Crew] taskClose: appendChangelog failed for ${taskId}:`, e.message));
+  }
+
+  // Broadcast status card so the UI reflects the close immediately.
+  try {
+    sendCrewMessage({
+      type: 'crew_task_closed',
+      sessionId: session.id,
+      taskId,
+      taskTitle,
+      summary: cleanSummary,
+      fromRole: fromRole || null,
+      timestamp: Date.now(),
+    });
+    sendStatusUpdate(session);
+  } catch (e) {
+    console.warn(`[Crew] taskClose: broadcast failed for ${taskId}:`, e.message);
+  }
+
+  return { ok: true, taskId };
+}
+
+/**
+ * Flip a role into 'standby' (in-memory) and broadcast.
+ *
+ * 330a defines the contract; 330d wires the .crew/context/role-states.json
+ * persistence. We DO mutate `session.roleStates[role].standby` here so the
+ * UI / status pipeline can reflect the change immediately, and 330d can
+ * snapshot it on the next debounced save.
+ *
+ * @param {object} session
+ * @param {{ role: string, reason?: string, fromRole?: string }} params
+ * @returns {{ ok: boolean, role: string, reason?: string }}
+ */
+export function roleStandby(session, { role, reason, fromRole }) {
+  if (!session) {
+    return { ok: false, role: role || null, reason: 'no_session' };
+  }
+  if (!role || typeof role !== 'string') {
+    return { ok: false, role: role || null, reason: 'invalid_role' };
+  }
+  if (!session.roles || !session.roles.has(role)) {
+    return { ok: false, role, reason: 'unknown_role' };
+  }
+
+  const normalizedReason = reason && STANDBY_REASONS.includes(reason)
+    ? reason
+    : 'manual';
+
+  // Ensure the roleState bucket exists (cold-start safe).
+  let roleState = session.roleStates?.get?.(role);
+  if (!roleState) {
+    roleState = {};
+    session.roleStates?.set?.(role, roleState);
+  }
+  // New keys only — never delete legacy fields (replay safety).
+  roleState.standby = {
+    reason: normalizedReason,
+    since: Date.now(),
+    setBy: fromRole || null,
+  };
+
+  try {
+    sendCrewMessage({
+      type: 'crew_role_standby',
+      sessionId: session.id,
+      role,
+      reason: normalizedReason,
+      fromRole: fromRole || null,
+      timestamp: Date.now(),
+    });
+    sendStatusUpdate(session);
+  } catch (e) {
+    console.warn(`[Crew] roleStandby: broadcast failed for ${role}:`, e.message);
+  }
+
+  return { ok: true, role, reason: normalizedReason };
+}

package/crew/role-output.js

@@ -7,6 +7,8 @@ import { saveRoleSessionId, clearRoleSessionId, classifyRoleError, createRoleQue
 import { parseRoutes, executeRoute, dispatchToRole } from './routing.js';
 import { parseCompletedTasks, updateFeatureIndex, appendChangelog, saveRoleWorkSummary, updateKanban } from './task-files.js';
 import { debouncedSaveSessionMeta, saveSessionMeta } from './persistence.js';
+import { recordRoutingEvent } from './routing-metrics.js';
+import { resolveFallbackTarget } from './routing-fallback.js';
 import ctx from '../context.js';
 
 // Context 使用率常量（运行时从 ctx.CONFIG 读取）
@@ -160,10 +162,29 @@ export async function processRoleOutput(session, roleName, roleQuery, roleState)
         const parseResult = parseRoutes(roleState.accumulatedText);
         const routes = parseResult;
         const displayBody = parseResult.displayBody || roleState.accumulatedText;
-        // Fallback: 如果 route summary 仍为空占位符，用 accumulatedText 末尾 500 字符
+        // task-330b §B item 1: detect "parse-fail" — text mentions a ROUTE
+        // opener but nothing parseable came out. Counts as a separate metric
+        // from plain missing-route so dashboards can split malformed-block
+        // (likely template/prompt drift) from forgot-to-write-block.
+        if (routes.length === 0 && /---\s*ROUTE\s*---/i.test(roleState.accumulatedText || '')) {
+          recordRoutingEvent(session, 'parse-fail', {
+            fromRole: roleName,
+            taskId: roleState.currentTask?.taskId || null,
+            note: 'ROUTE opener present but no parseable block',
+          });
+        }
+        // Fallback: 如果 route summary 仍为空占位符，用 displayBody 末尾 500 字符
+        // task-330c: source switched from `accumulatedText.slice(-500)` to
+        // `displayBody.slice(-500)` — accumulatedText still contains
+        // ---ROUTE--- markers; using it would re-strip already-stripped text
+        // and risk truncating mid-marker. displayBody is the parser's
+        // post-strip prose and is the single source of truth for "what the
+        // role said outside its routing blocks".
+        // ⚠️ DO NOT add any further `.replace(/---ROUTE---.../g, '')` on
+        //    `displayBody` here or downstream — it is already strip-clean.
         for (const route of routes) {
-          if (route.summary === '[该角色未提供消息摘要]' && roleState.accumulatedText) {
-            const tail = roleState.accumulatedText.slice(-500).trim();
+          if (route.summary === '[该角色未提供消息摘要]' && displayBody) {
+            const tail = displayBody.slice(-500).trim();
             if (tail) route.summary = `[auto-extracted]\n${tail}`;
           }
         }
@@ -265,27 +286,59 @@ export async function processRoleOutput(session, roleName, roleQuery, roleState)
           });
           sendStatusUpdate(session);
         } else {
-          // ★ No ROUTE found — decide whether to auto-forward to PM
-          const isNonPM = roleName !== session.decisionMaker;
+          // ★ No ROUTE found — resolve via the single fallback policy
+          // (task-330b §B item 3). The resolver enforces:
+          //   - PM never auto-forwards to itself (parks pending instead)
+          //   - non-PM with active task / routing intent → PM (auto-forward)
+          //   - everyone else → null (process human queue)
           const hasActiveTask = !!roleState.currentTask;
           const hasRouteIntent = _detectRouteIntent(roleState.lastTurnText);
+          const fallbackTo = resolveFallbackTarget(session, roleName, 'missing-route', {
+            hasActiveTask,
+            hasRouteIntent,
+          });
 
-          if (isNonPM && (hasActiveTask || hasRouteIntent)) {
-            // Non-PM role with active task OR routing intent but no ROUTE block:
-            // auto-forward to PM so the message doesn't get lost.
+          if (fallbackTo) {
+            // §B item 1 — record the metric on every fallback dispatch.
+            const reason = hasActiveTask ? 'has active task' : 'has routing intent';
+            recordRoutingEvent(session, 'fallback-forward', {
+              fromRole: roleName,
+              toRole: fallbackTo,
+              taskId: roleState.currentTask?.taskId || null,
+              note: reason,
+            });
+            // Also record the upstream cause so dashboards can split
+            // "missing ROUTE" events from the auto-forward dispatches.
+            recordRoutingEvent(session, 'missing-route', {
+              fromRole: roleName,
+              taskId: roleState.currentTask?.taskId || null,
+              note: reason,
+            });
             // task-328: forward parser-clean displayBody (ROUTE residue removed)
             // so PM sees the actual prose, not stray END markers.
-            const reason = hasActiveTask ? 'has active task' : 'has routing intent';
-            console.log(`[Crew] ${roleName} turn ended without ROUTE (${reason}) — auto-forwarding to PM`);
+            console.log(`[Crew] ${roleName} turn ended without ROUTE (${reason}) — auto-forwarding to ${fallbackTo}`);
             const forwardSource = roleState.lastTurnDisplayBody || roleState.lastTurnText || '';
             const autoSummary = `[auto-forward: ${roleName} turn 结束但未输出 ROUTE 块 (${reason})]\n${forwardSource.slice(-800).trim()}`;
             await executeRoute(session, roleName, {
-              to: session.decisionMaker,
+              to: fallbackTo,
               summary: autoSummary,
               taskId: roleState.currentTask?.taskId || null,
               taskTitle: roleState.currentTask?.taskTitle || null,
             });
           } else {
+            // §B item 2 — PM no-auto-forward: when PM ends a turn without
+            // ROUTE we DO NOT self-route. Instead we record the metric and
+            // park the session (effectively pending) so the user's next
+            // input drives the next step. Same applies to non-PM roles
+            // with no active task / no routing intent.
+            if (roleName === session.decisionMaker && (hasActiveTask || hasRouteIntent)) {
+              recordRoutingEvent(session, 'missing-route', {
+                fromRole: roleName,
+                taskId: roleState.currentTask?.taskId || null,
+                note: 'pm-pending (no auto-forward)',
+              });
+              console.log(`[Crew] ${roleName} (PM) turn ended without ROUTE — staying pending (no self-forward)`);
+            }
             const { processHumanQueue } = await import('./human-interaction.js');
             await processHumanQueue(session);
           }

package/crew/role-states.js

@@ -0,0 +1,180 @@
+/**
+ * Crew — Role State Store (task-330d, Fowler Final Spec §D)
+ *
+ * Replaces the legacy "standby task" pattern (where PM idle was modelled
+ * as a synthetic task in `.crew/context/features/standby.md`). Role idle/
+ * busy/pending state is now first-class and persisted to a single file:
+ *
+ *     <sharedDir>/context/role-states.json
+ *
+ * File shape:
+ *   {
+ *     "version": 1,
+ *     "states": {
+ *       "<roleName>": { role, status, since, reason }
+ *     }
+ *   }
+ *
+ * Status values:
+ *   - 'standby' : role has no active task and is waiting for routing
+ *   - 'busy'    : role is currently executing a turn
+ *   - 'pending' : role finished a turn but did not emit a ROUTE
+ *
+ * Public API (consumed by the `role_standby` tool added in task-330a):
+ *   - getRoleState(sharedDir, role)        → state | null
+ *   - setRoleState(sharedDir, role, patch) → state
+ *   - listRoleStates(sharedDir)            → Record<role, state>
+ *
+ * Atomicity: writes go to `role-states.json.tmp` then rename, matching the
+ * convention in persistence.js. A per-process write lock (Promise chain)
+ * serialises concurrent setRoleState calls so the file never tears.
+ *
+ * Backward compatibility: a session that was created before role-states.json
+ * existed simply has no file; getRoleState returns null and setRoleState
+ * creates the file lazily. No migration step is required.
+ */
+
+import { promises as fs } from 'fs';
+import { join } from 'path';
+
+const FILE_NAME = 'role-states.json';
+const VERSION = 1;
+const VALID_STATUSES = new Set(['standby', 'busy', 'pending']);
+
+// Per-sharedDir write lock. Keyed by absolute path so multiple sessions in
+// one process don't serialise against each other.
+const _writeLocks = new Map();
+
+function _lockKey(sharedDir) {
+  return sharedDir;
+}
+
+function _filePath(sharedDir) {
+  return join(sharedDir, 'context', FILE_NAME);
+}
+
+async function _readAll(sharedDir) {
+  try {
+    const raw = await fs.readFile(_filePath(sharedDir), 'utf-8');
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== 'object' || !parsed.states || typeof parsed.states !== 'object') {
+      return { version: VERSION, states: {} };
+    }
+    return { version: parsed.version || VERSION, states: parsed.states };
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return { version: VERSION, states: {} };
+    // Corrupt JSON → start fresh rather than crash. This matches the
+    // "legacy session replay compatibility" red line: a broken file must
+    // not block resume.
+    return { version: VERSION, states: {} };
+  }
+}
+
+async function _writeAtomic(sharedDir, payload) {
+  const dir = join(sharedDir, 'context');
+  await fs.mkdir(dir, { recursive: true });
+  const target = _filePath(sharedDir);
+  const tmp = target + '.tmp';
+  await fs.writeFile(tmp, JSON.stringify(payload, null, 2));
+  await fs.rename(tmp, target);
+}
+
+/**
+ * Read the current state for a single role.
+ * @param {string} sharedDir — session shared directory (`.crew` root)
+ * @param {string} role — role name
+ * @returns {Promise<null | {role:string, status:string, since:number, reason?:string}>}
+ */
+export async function getRoleState(sharedDir, role) {
+  if (!sharedDir || !role) return null;
+  const all = await _readAll(sharedDir);
+  return all.states[role] || null;
+}
+
+/**
+ * Read every role's state at once. Returns a plain object keyed by role
+ * name (empty when the file is missing).
+ */
+export async function listRoleStates(sharedDir) {
+  if (!sharedDir) return {};
+  const all = await _readAll(sharedDir);
+  return { ...all.states };
+}
+
+/**
+ * Patch a single role's state. Unspecified fields are preserved from the
+ * existing record. `since` defaults to Date.now() when status changes (or
+ * when no prior record exists). Throws on invalid status — callers are
+ * expected to pass one of standby|busy|pending.
+ *
+ * @param {string} sharedDir
+ * @param {string} role
+ * @param {Partial<{status:string, reason:string, since:number}>} patch
+ * @returns {Promise<{role:string, status:string, since:number, reason?:string}>}
+ */
+export async function setRoleState(sharedDir, role, patch = {}) {
+  if (!sharedDir) throw new Error('setRoleState: sharedDir required');
+  if (!role) throw new Error('setRoleState: role required');
+  if (patch.status !== undefined && !VALID_STATUSES.has(patch.status)) {
+    throw new Error(`setRoleState: invalid status '${patch.status}'`);
+  }
+
+  const key = _lockKey(sharedDir);
+  const prev = _writeLocks.get(key) || Promise.resolve();
+
+  const next = prev.then(async () => {
+    const all = await _readAll(sharedDir);
+    const existing = all.states[role] || null;
+    const statusChanged = patch.status !== undefined && (!existing || existing.status !== patch.status);
+    const merged = {
+      role,
+      status: patch.status !== undefined ? patch.status : (existing ? existing.status : 'standby'),
+      since: patch.since !== undefined
+        ? patch.since
+        : (statusChanged || !existing ? Date.now() : existing.since),
+    };
+    if (patch.reason !== undefined) {
+      merged.reason = patch.reason;
+    } else if (existing && existing.reason !== undefined && !statusChanged) {
+      merged.reason = existing.reason;
+    }
+    all.states[role] = merged;
+    all.version = VERSION;
+    await _writeAtomic(sharedDir, all);
+    return merged;
+  }, async () => {
+    // If a prior write rejected we still want to attempt this one rather
+    // than poisoning the chain forever.
+    const all = await _readAll(sharedDir);
+    const merged = {
+      role,
+      status: patch.status || 'standby',
+      since: patch.since !== undefined ? patch.since : Date.now(),
+      ...(patch.reason !== undefined ? { reason: patch.reason } : {}),
+    };
+    all.states[role] = merged;
+    await _writeAtomic(sharedDir, all);
+    return merged;
+  });
+
+  // Hold onto the chain so the next caller waits on this write.
+  _writeLocks.set(key, next.catch(() => {}));
+  return next;
+}
+
+/**
+ * Test/diagnostic helper — clear in-process write lock for a sharedDir.
+ * Production callers should never need this; tests use it between runs to
+ * avoid bleeding lock state across describe blocks.
+ */
+export function __resetWriteLockForTests(sharedDir) {
+  if (sharedDir) _writeLocks.delete(sharedDir);
+  else _writeLocks.clear();
+}
+
+/**
+ * Constants exported for tests + downstream consumers (the `role_standby`
+ * tool in task-330a).
+ */
+export const ROLE_STATE_FILE_NAME = FILE_NAME;
+export const ROLE_STATE_STATUSES = ['standby', 'busy', 'pending'];

package/crew/routing-fallback.js

@@ -0,0 +1,64 @@
+/**
+ * task-330b — Single fallback-target resolver (Final Spec §B item 3).
+ *
+ * Replaces ad-hoc `session.decisionMaker` lookups scattered across
+ * routing.js / role-output.js / human-interaction.js when a message has
+ * nowhere obvious to go. Centralising this in ONE function lets us:
+ *
+ *   - test the fallback policy in isolation
+ *   - add per-reason policy without touching every call site
+ *   - keep the §B `recordRoutingEvent` calls right next to the decision
+ *
+ * Policy (mirrors what the codebase already does — this is a refactor,
+ * not a behaviour change for the existing 4 reasons):
+ *
+ *   missing-route     → PM (decisionMaker) IF caller is non-PM AND has
+ *                       active task or routing intent. Else: pending (null).
+ *                       PM-no-auto-forward rule (§B item 2): if caller IS
+ *                       PM → ALWAYS pending (null), even with active task.
+ *   parse-fail        → PM (decisionMaker)
+ *   self-route        → null (rejected; §A handles, §B only logs)
+ *   state-stopped     → null (let session.status block the dispatch)
+ *   fallback-forward  → PM (decisionMaker) — explicit auto-forward path
+ *
+ * Returns the target role NAME, or null when "do nothing / pending".
+ *
+ * @param {object} session — crew session (.decisionMaker, .roles)
+ * @param {string} fromRole
+ * @param {string} reason — one of ROUTING_REASONS
+ * @param {object} [opts]
+ * @param {boolean} [opts.hasActiveTask]
+ * @param {boolean} [opts.hasRouteIntent]
+ * @returns {string|null}
+ */
+export function resolveFallbackTarget(session, fromRole, reason, opts = {}) {
+  if (!session) return null;
+  const dm = session.decisionMaker || null;
+
+  switch (reason) {
+    case 'missing-route': {
+      // PM-no-auto-forward rule (§B item 2): PM never auto-forwards to
+      // itself. Returning null signals "park as pending, wait for human".
+      if (fromRole === dm) return null;
+      // Non-PM: only auto-forward when there is something to forward
+      // (active task OR detected routing intent in the prose).
+      if (opts.hasActiveTask || opts.hasRouteIntent) return dm;
+      return null;
+    }
+    case 'parse-fail':
+      // Parser found a ROUTE block but couldn't read it — PM should see
+      // the malformed output to decide next step.
+      return dm;
+    case 'self-route':
+      // §A rejects self-routing; §B records, no fallback dispatch.
+      return null;
+    case 'state-stopped':
+      // Session is stopped/paused; routing must not auto-resume here.
+      return null;
+    case 'fallback-forward':
+      // Explicit safety net (the rename of the existing auto-forward).
+      return dm;
+    default:
+      return null;
+  }
+}