@aion0/forge 0.5.25 → 0.5.26

package/.forge/worktrees/pipeline-e7f78b7a/lib/workspace/requests.ts

@@ -0,0 +1,287 @@
+/**
+ * Request/Response Document System — structured YAML documents for
+ * multi-agent delivery workflows.
+ *
+ * Storage layout:
+ *   <project>/.forge/requests/<id>/
+ *     ├── request.yml    — created by Architect
+ *     └── response.yml   — updated by Engineer, Reviewer, QA
+ *
+ * Inspired by Accord protocol: YAML frontmatter + structured content,
+ * status lifecycle (open → in_progress → review → qa → done).
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import YAML from 'yaml';
+
+// ─── Types ──────────────────────────────────────────────
+
+export type RequestStatus = 'open' | 'in_progress' | 'review' | 'qa' | 'done' | 'rejected';
+export type RequestPriority = 'high' | 'medium' | 'low';
+export type RequestType = 'feature' | 'bugfix' | 'refactor' | 'task';
+
+export interface RequestModule {
+  name: string;
+  description: string;
+  acceptance_criteria: string[];
+}
+
+export interface RequestDocument {
+  id: string;
+  batch: string;                    // groups requests into a delivery
+  title: string;
+  description: string;
+  type: RequestType;
+  modules: RequestModule[];
+  priority: RequestPriority;
+  status: RequestStatus;
+  assigned_to: string;              // agent label
+  created_by: string;               // agent label
+  created_at: string;               // ISO timestamp
+  updated_at: string;
+}
+
+export interface EngineerResponse {
+  completed_at?: string;
+  files_changed: string[];
+  notes: string;
+}
+
+export interface ReviewResponse {
+  completed_at?: string;
+  result: 'approved' | 'changes_requested' | 'rejected';
+  findings: Array<{ severity: string; description: string }>;
+}
+
+export interface QaResponse {
+  completed_at?: string;
+  result: 'passed' | 'failed';
+  test_files: string[];
+  findings: Array<{ severity: string; description: string }>;
+}
+
+export interface ResponseDocument {
+  request_id: string;
+  status: RequestStatus;
+  engineer?: EngineerResponse;
+  review?: ReviewResponse;
+  qa?: QaResponse;
+}
+
+// ─── Paths ──────────────────────────────────────────────
+
+function requestsRoot(projectPath: string): string {
+  return join(projectPath, '.forge', 'requests');
+}
+
+function requestDir(projectPath: string, requestId: string): string {
+  return join(requestsRoot(projectPath), requestId);
+}
+
+function ensureDir(dir: string): void {
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+}
+
+// ─── CRUD ───────────────────────────────────────────────
+
+/**
+ * Generate a request ID: REQ-YYYYMMDD-NNN
+ */
+export function generateRequestId(projectPath: string): string {
+  const now = new Date();
+  const date = `${now.getFullYear()}${String(now.getMonth() + 1).padStart(2, '0')}${String(now.getDate()).padStart(2, '0')}`;
+  const root = requestsRoot(projectPath);
+  if (!existsSync(root)) return `REQ-${date}-001`;
+  const existing = readdirSync(root).filter(f => f.startsWith(`REQ-${date}-`));
+  const num = existing.length + 1;
+  return `REQ-${date}-${String(num).padStart(3, '0')}`;
+}
+
+/**
+ * Create a new request document.
+ * Returns the relative path to request.yml (for use as ref in bus messages).
+ */
+export function createRequest(projectPath: string, doc: Omit<RequestDocument, 'id' | 'created_at' | 'updated_at'> & { id?: string }): string {
+  const id = doc.id || generateRequestId(projectPath);
+  const dir = requestDir(projectPath, id);
+  ensureDir(dir);
+
+  const now = new Date().toISOString();
+  const full: RequestDocument = {
+    ...doc,
+    id,
+    status: doc.status || 'open',
+    created_at: now,
+    updated_at: now,
+  };
+
+  const filePath = join(dir, 'request.yml');
+  writeFileSync(filePath, YAML.stringify(full), 'utf-8');
+  console.log(`[requests] Created ${id}: ${doc.title}`);
+
+  // Return relative path for bus ref
+  return `.forge/requests/${id}/request.yml`;
+}
+
+/**
+ * Get a request and its optional response.
+ */
+export function getRequest(projectPath: string, requestId: string): { request: RequestDocument; response?: ResponseDocument } | null {
+  const dir = requestDir(projectPath, requestId);
+  const reqFile = join(dir, 'request.yml');
+  if (!existsSync(reqFile)) return null;
+
+  try {
+    const request: RequestDocument = YAML.parse(readFileSync(reqFile, 'utf-8'));
+    let response: ResponseDocument | undefined;
+    const resFile = join(dir, 'response.yml');
+    if (existsSync(resFile)) {
+      response = YAML.parse(readFileSync(resFile, 'utf-8'));
+    }
+    return { request, response };
+  } catch (err: any) {
+    console.error(`[requests] Failed to read ${requestId}: ${err.message}`);
+    return null;
+  }
+}
+
+/**
+ * List all requests, optionally filtered by batch or status.
+ */
+export function listRequests(projectPath: string, opts?: { batch?: string; status?: RequestStatus }): RequestDocument[] {
+  const root = requestsRoot(projectPath);
+  if (!existsSync(root)) return [];
+
+  const results: RequestDocument[] = [];
+  for (const entry of readdirSync(root, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    const reqFile = join(root, entry.name, 'request.yml');
+    if (!existsSync(reqFile)) continue;
+    try {
+      const doc: RequestDocument = YAML.parse(readFileSync(reqFile, 'utf-8'));
+      if (opts?.batch && doc.batch !== opts.batch) continue;
+      if (opts?.status && doc.status !== opts.status) continue;
+      results.push(doc);
+    } catch {}
+  }
+
+  return results.sort((a, b) => a.created_at.localeCompare(b.created_at));
+}
+
+/**
+ * Update a response document section (engineer, review, or qa).
+ * Automatically advances request status:
+ *   engineer → review, review(approved) → qa, qa(passed) → done
+ * Returns the relative path to response.yml.
+ */
+export function updateResponse(
+  projectPath: string,
+  requestId: string,
+  section: 'engineer' | 'review' | 'qa',
+  data: Record<string, any>,
+): string {
+  const dir = requestDir(projectPath, requestId);
+  const reqFile = join(dir, 'request.yml');
+  if (!existsSync(reqFile)) throw new Error(`Request ${requestId} not found`);
+
+  ensureDir(dir);
+  const resFile = join(dir, 'response.yml');
+
+  // Load or create response
+  let response: ResponseDocument;
+  if (existsSync(resFile)) {
+    response = YAML.parse(readFileSync(resFile, 'utf-8'));
+  } else {
+    response = { request_id: requestId, status: 'in_progress' };
+  }
+
+  // Update section with timestamp
+  const now = new Date().toISOString();
+  (response as any)[section] = { ...data, completed_at: now };
+
+  // Auto-advance status
+  const request: RequestDocument = YAML.parse(readFileSync(reqFile, 'utf-8'));
+  let newStatus: RequestStatus = request.status;
+
+  if (section === 'engineer') {
+    newStatus = 'review';
+  } else if (section === 'review') {
+    newStatus = data.result === 'rejected' ? 'rejected' : data.result === 'changes_requested' ? 'in_progress' : 'qa';
+  } else if (section === 'qa') {
+    newStatus = data.result === 'passed' ? 'done' : 'in_progress'; // failed → back to engineer
+  }
+
+  response.status = newStatus;
+  request.status = newStatus;
+  request.updated_at = now;
+
+  // Write both files
+  writeFileSync(resFile, YAML.stringify(response), 'utf-8');
+  writeFileSync(reqFile, YAML.stringify(request), 'utf-8');
+
+  console.log(`[requests] ${requestId}: ${section} updated → status=${newStatus}`);
+  return `.forge/requests/${requestId}/response.yml`;
+}
+
+/**
+ * Claim a request — set assigned_to and status to in_progress.
+ * Returns true if claimed successfully, false if already claimed by someone else.
+ */
+export function claimRequest(projectPath: string, requestId: string, agentLabel: string): { ok: boolean; claimedBy?: string } {
+  const dir = requestDir(projectPath, requestId);
+  const reqFile = join(dir, 'request.yml');
+  if (!existsSync(reqFile)) throw new Error(`Request ${requestId} not found`);
+
+  const doc: RequestDocument = YAML.parse(readFileSync(reqFile, 'utf-8'));
+
+  // Already claimed by someone else
+  if (doc.assigned_to && doc.assigned_to !== agentLabel) {
+    return { ok: false, claimedBy: doc.assigned_to };
+  }
+
+  // Already claimed by this agent (idempotent)
+  if (doc.assigned_to === agentLabel) {
+    return { ok: true };
+  }
+
+  // Only open requests can be claimed
+  if (doc.status !== 'open') {
+    return { ok: false, claimedBy: doc.assigned_to || `(status: ${doc.status})` };
+  }
+
+  doc.assigned_to = agentLabel;
+  doc.status = 'in_progress';
+  doc.updated_at = new Date().toISOString();
+  writeFileSync(reqFile, YAML.stringify(doc), 'utf-8');
+  console.log(`[requests] ${requestId}: claimed by ${agentLabel}`);
+  return { ok: true };
+}
+
+/**
+ * Manually update request status.
+ */
+export function updateRequestStatus(projectPath: string, requestId: string, status: RequestStatus): void {
+  const dir = requestDir(projectPath, requestId);
+  const reqFile = join(dir, 'request.yml');
+  if (!existsSync(reqFile)) throw new Error(`Request ${requestId} not found`);
+
+  const doc: RequestDocument = YAML.parse(readFileSync(reqFile, 'utf-8'));
+  doc.status = status;
+  doc.updated_at = new Date().toISOString();
+  writeFileSync(reqFile, YAML.stringify(doc), 'utf-8');
+}
+
+/**
+ * Get batch completion status.
+ */
+export function getBatchStatus(projectPath: string, batch: string): { total: number; done: number; allDone: boolean; requests: Array<{ id: string; title: string; status: RequestStatus }> } {
+  const all = listRequests(projectPath, { batch });
+  const done = all.filter(r => r.status === 'done' || r.status === 'rejected').length;
+  return {
+    total: all.length,
+    done,
+    allDone: all.length > 0 && done === all.length,
+    requests: all.map(r => ({ id: r.id, title: r.title, status: r.status })),
+  };
+}

package/.forge/worktrees/pipeline-e7f78b7a/lib/workspace/session-monitor.ts

@@ -0,0 +1,240 @@
+/**
+ * Session File Monitor — detects agent running/idle state by watching
+ * Claude Code's .jsonl session files.
+ *
+ * How it works:
+ * - Each agent has a known session file path (boundSessionId/fixedSessionId/--session-id)
+ * - Monitor checks file mtime every 3s
+ * - mtime changing → agent is running (LLM streaming, tool use, etc.)
+ * - mtime stable for IDLE_THRESHOLD → check last lines for 'result' entry → done
+ * - No session file → idle (not started)
+ *
+ * Works for both terminal and headless modes — both write the same .jsonl format.
+ */
+
+import { statSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { resolve } from 'node:path';
+import { EventEmitter } from 'node:events';
+
+export type SessionMonitorState = 'idle' | 'running' | 'done';
+
+export interface SessionMonitorEvent {
+  agentId: string;
+  state: SessionMonitorState;
+  sessionFile: string;
+  detail?: string; // e.g., result summary
+}
+
+const POLL_INTERVAL = 3000;      // check every 3s
+const IDLE_THRESHOLD = 29 * 60 * 1000;   // 29min of no file change → check for result entry
+const STABLE_THRESHOLD = 30 * 60 * 1000; // 30min of no change → force done (fallback if hook missed)
+
+export class SessionFileMonitor extends EventEmitter {
+  private timers = new Map<string, NodeJS.Timeout>();
+  private lastMtime = new Map<string, number>();
+  private lastSize = new Map<string, number>();
+  private lastStableTime = new Map<string, number>();
+  private currentState = new Map<string, SessionMonitorState>();
+
+  /**
+   * Start monitoring a session file for an agent.
+   * @param agentId - Agent identifier
+   * @param sessionFilePath - Full path to the .jsonl session file
+   */
+  startMonitoring(agentId: string, sessionFilePath: string): void {
+    this.stopMonitoring(agentId);
+    this.currentState.set(agentId, 'idle');
+    this.lastStableTime.set(agentId, Date.now());
+    this.warmupCount.set(agentId, 0); // reset warmup for fresh start
+
+    const timer = setInterval(() => {
+      this.checkFile(agentId, sessionFilePath);
+    }, POLL_INTERVAL);
+    timer.unref();
+    this.timers.set(agentId, timer);
+
+    console.log(`[session-monitor] Started monitoring ${agentId}: ${sessionFilePath}`);
+  }
+
+  /**
+   * Stop monitoring an agent's session file.
+   */
+  stopMonitoring(agentId: string): void {
+    const timer = this.timers.get(agentId);
+    if (timer) clearInterval(timer);
+    this.timers.delete(agentId);
+    this.lastMtime.delete(agentId);
+    this.lastSize.delete(agentId);
+    this.lastStableTime.delete(agentId);
+    this.currentState.delete(agentId);
+  }
+
+  /**
+   * Stop all monitors.
+   */
+  stopAll(): void {
+    for (const [id] of this.timers) {
+      this.stopMonitoring(id);
+    }
+  }
+
+  /**
+   * Get current state for an agent.
+   */
+  getState(agentId: string): SessionMonitorState {
+    return this.currentState.get(agentId) || 'idle';
+  }
+
+  /**
+   * Reset monitor state to idle and pause detection briefly.
+   * Call when orchestrator manually changes taskStatus (button/hook).
+   * Suppresses detection for 10s to avoid immediately flipping back.
+   */
+  private suppressUntil = new Map<string, number>();
+
+  resetState(agentId: string): void {
+    this.currentState.set(agentId, 'idle');
+    this.lastStableTime.set(agentId, Date.now());
+    // Don't reset warmupCount here — warmup only on startMonitoring (fresh start/restart)
+    // 10s suppress is enough to prevent immediate flip-back after hook/button
+    this.suppressUntil.set(agentId, Date.now() + 10_000);
+  }
+
+  /**
+   * Resolve session file path for a project + session ID.
+   */
+  static resolveSessionPath(projectPath: string, workDir: string | undefined, sessionId: string): string {
+    const fullPath = workDir && workDir !== './' && workDir !== '.'
+      ? join(projectPath, workDir) : projectPath;
+    // Claude Code encodes paths by replacing all non-alphanumeric chars with '-'
+    const encoded = resolve(fullPath).replace(/[^a-zA-Z0-9]/g, '-');
+    return join(homedir(), '.claude', 'projects', encoded, `${sessionId}.jsonl`);
+  }
+
+  private warmupCount = new Map<string, number>();
+  private checkFile(agentId: string, filePath: string): void {
+    try {
+      const stat = statSync(filePath);
+      const mtime = stat.mtimeMs;
+      const size = stat.size;
+
+      // Warmup: skip first 6 polls (~18s) to avoid false running during startup
+      // On poll 7 (first real check), just set new baseline — don't trigger running
+      const count = (this.warmupCount.get(agentId) || 0) + 1;
+      this.warmupCount.set(agentId, count);
+      if (count <= 7) {
+        this.lastMtime.set(agentId, mtime);
+        this.lastSize.set(agentId, size);
+        this.lastStableTime.set(agentId, Date.now());
+        if (count === 1) console.log(`[session-monitor] ${agentId}: warmup started`);
+        if (count === 7) console.log(`[session-monitor] ${agentId}: warmup done, monitoring active`);
+        return;
+      }
+
+      const prevMtime = this.lastMtime.get(agentId) || 0;
+      const prevSize = this.lastSize.get(agentId) || 0;
+      const prevState = this.currentState.get(agentId) || 'idle';
+      const now = Date.now();
+
+      this.lastMtime.set(agentId, mtime);
+      this.lastSize.set(agentId, size);
+
+      // File changed (mtime or size different) → running
+      if (mtime !== prevMtime || size !== prevSize) {
+        this.lastStableTime.set(agentId, now);
+        if (prevState !== 'running') {
+          this.setState(agentId, 'running', filePath);
+        }
+        return;
+      }
+
+      // File unchanged — how long has it been stable?
+      const stableFor = now - (this.lastStableTime.get(agentId) || now);
+
+      if (prevState === 'running') {
+        if (stableFor >= IDLE_THRESHOLD) {
+          // Check if session file has a 'result' entry at the end
+          const resultInfo = this.checkForResult(filePath, size);
+          if (resultInfo) {
+            this.setState(agentId, 'done', filePath, resultInfo);
+            return;
+          }
+        }
+        if (stableFor >= STABLE_THRESHOLD) {
+          // Force done after 60min even without result entry (ultimate fallback)
+          this.setState(agentId, 'done', filePath, 'stable timeout');
+          return;
+        }
+      }
+    } catch (err: any) {
+      if ((this.warmupCount.get(`err-${agentId}`) || 0) === 0) {
+        this.warmupCount.set(`err-${agentId}`, 1);
+        console.log(`[session-monitor] ${agentId}: checkFile error — ${err.message}`);
+      }
+    }
+  }
+
+  /**
+   * Check the last few lines of the session file for a 'result' type entry.
+   * Claude Code writes this when a turn completes.
+   */
+  private checkForResult(filePath: string, fileSize?: number): string | null {
+    try {
+      // Read last 4KB of the file — fileSize passed from caller to avoid second statSync
+      const { openSync, readSync, closeSync } = require('node:fs') as typeof import('node:fs');
+      const size = fileSize ?? statSync(filePath).size;
+      const readSize = Math.min(4096, size);
+      const fd = openSync(filePath, 'r');
+      const buf = Buffer.alloc(readSize);
+      try {
+        readSync(fd, buf, 0, readSize, Math.max(0, size - readSize));
+      } finally {
+        closeSync(fd);
+      }
+
+      const tail = buf.toString('utf-8');
+      const lines = tail.split('\n').filter(l => l.trim());
+
+      // Scan last lines for result entry
+      for (let i = lines.length - 1; i >= Math.max(0, lines.length - 10); i--) {
+        try {
+          const entry = JSON.parse(lines[i]);
+          // Claude Code writes result entries with these fields
+          if (entry.type === 'result' || entry.result || entry.duration_ms !== undefined) {
+            const summary = entry.result?.slice?.(0, 200) || entry.summary?.slice?.(0, 200) || '';
+            return summary || 'completed';
+          }
+          // Also check for assistant message without tool_use (model stopped)
+          if (entry.type === 'assistant' && entry.message?.content) {
+            const content = entry.message.content;
+            const hasToolUse = Array.isArray(content)
+              ? content.some((b: any) => b.type === 'tool_use')
+              : false;
+            if (!hasToolUse) {
+              return 'model stopped (no tool_use)';
+            }
+          }
+        } catch {} // skip non-JSON lines
+      }
+    } catch {}
+    return null;
+  }
+
+  private setState(agentId: string, state: SessionMonitorState, filePath: string, detail?: string): void {
+    const prev = this.currentState.get(agentId);
+    if (prev === state) return;
+
+    // Suppress state changes if recently reset by orchestrator
+    const suppressed = this.suppressUntil.get(agentId);
+    if (suppressed && Date.now() < suppressed) {
+      return;
+    }
+
+    this.currentState.set(agentId, state);
+    const event: SessionMonitorEvent = { agentId, state, sessionFile: filePath, detail };
+    this.emit('stateChange', event);
+    console.log(`[session-monitor] ${agentId}: ${prev} → ${state}${detail ? ` (${detail})` : ''}`);
+  }
+}