@aion0/forge 0.5.23 → 0.5.24

package/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/lib/workspace/session-monitor.ts

@@ -28,8 +28,8 @@ export interface SessionMonitorEvent {
 }
 
 const POLL_INTERVAL = 3000;      // check every 3s
-const IDLE_THRESHOLD = 3540000;  // 59min of no file change → check for result entry
-const STABLE_THRESHOLD = 3600000; // 60min of no change → force done (fallback if hook missed) [59min check + 1min grace]
+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>();
@@ -108,7 +108,8 @@ export class SessionFileMonitor extends EventEmitter {
   static resolveSessionPath(projectPath: string, workDir: string | undefined, sessionId: string): string {
     const fullPath = workDir && workDir !== './' && workDir !== '.'
       ? join(projectPath, workDir) : projectPath;
-    const encoded = resolve(fullPath).replace(/\//g, '-');
+    // 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`);
   }
 

package/lib/workspace/types.ts

@@ -147,6 +147,7 @@ export interface BusMessage {
     content?: string;                // natural language message
     files?: string[];                // related file paths
     replyTo?: string;                // reply to which message ID
+    ref?: string;                    // path to request/response document (reference-based notification)
   };
   timestamp: number;
   // Delivery tracking

package/lib/workspace/watch-manager.ts

@@ -212,7 +212,7 @@ const lastSessionFile = new Map<string, string>();
 
 function detectSessionChanges(projectPath: string, pattern: string | undefined, prevLineCount: number, contextChars = 500, sessionId?: string): { changes: WatchChange | null; lineCount: number } {
   const claudeHome = join(homedir(), '.claude', 'projects');
-  const encoded = projectPath.replace(/\//g, '-');
+  const encoded = projectPath.replace(/[^a-zA-Z0-9]/g, '-');
   const sessionDir = join(claudeHome, encoded);
   if (!existsSync(sessionDir)) return { changes: null, lineCount: prevLineCount };
 

package/lib/workspace-standalone.ts

@@ -688,7 +688,7 @@ async function handleSmith(id: string, body: any, res: ServerResponse): Promise<
         const agentConfig = agentId ? orch.getSnapshot().agents.find(a => a.id === agentId) : null;
         const agentWorkDir = agentConfig?.workDir && agentConfig.workDir !== './' && agentConfig.workDir !== '.'
           ? join(orch.projectPath, agentConfig.workDir) : orch.projectPath;
-        const encoded = resolve(agentWorkDir).replace(/\//g, '-');
+        const encoded = resolve(agentWorkDir).replace(/[^a-zA-Z0-9]/g, '-');
         const sessDir = join(homedir(), '.claude', 'projects', encoded);
         const entries = readdirSync(sessDir);
         const files = entries

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aion0/forge",
-  "version": "0.5.23",
+  "version": "0.5.24",
   "description": "Unified AI workflow platform — multi-model task orchestration, persistent sessions, web terminal, remote access",
   "type": "module",
   "scripts": {

package/scripts/bench/README.md

@@ -0,0 +1,66 @@
+# Benchmark: Claude Code vs Forge Workspace
+
+Compares a single Claude Code run against a Forge multi-smith workspace on the same task.
+
+## Files
+
+- `task.md` — task description (given to both harnesses verbatim)
+- `validator.sh` — validates the output (exit 0 = pass)
+- `run.ts` — main runner
+- `results/` — markdown reports (gitignored)
+
+## Prerequisites
+
+1. **Forge running**: `forge server start` (listening on port 8403)
+2. **Claude Code installed** and authenticated (`claude --version` works)
+3. **harness_test project** exists at `/Users/zliu/IdeaProjects/harness_test`
+
+## Run
+
+```bash
+pnpm tsx scripts/bench/run.ts
+```
+
+## What it does
+
+1. Prepares `bench/start` branch in harness_test (fresh from main)
+2. **Claude Code run**:
+   - Creates `bench/claude-<ts>` branch
+   - Runs `claude -p --dangerously-skip-permissions "<task>"` in harness_test
+   - Commits output, runs validator
+3. **Forge workspace run**:
+   - Creates `bench/forge-<ts>` branch
+   - Finds/creates workspace pointing at harness_test
+   - Removes existing agents, adds fresh Input → Lead → Engineer → QA
+   - Starts daemon, submits task to Input, triggers Lead
+   - Polls every 10s until all smiths finish (or 20min timeout)
+   - Stops daemon, commits output, runs validator
+4. Writes comparison report to `results/report-<ts>.md`
+
+## Validation
+
+The validator checks:
+1. `src/utils/text.js` exists with `capitalize` and `reverseWords` exports
+2. `src/utils/text.test.js` exists
+3. `node --test utils/text.test.js` passes (agent's own tests)
+4. External smoke test: independent check that both functions behave correctly (including error cases)
+
+## Inspecting Results
+
+- Git branches: `git branch | grep bench/` in harness_test
+- Diff: `git diff bench/start...bench/claude-<ts>` (or `forge-<ts>`)
+- Markdown report: `scripts/bench/results/report-<ts>.md`
+
+## Tuning
+
+Edit `run.ts` constants:
+- `TASK_TIMEOUT_MS` — per-run timeout (default 20 min)
+- `POLL_INTERVAL_MS` — Forge polling frequency (default 10s)
+- `PROJECT` — target project path
+- `FORGE_URL` — Forge API base URL
+
+## Notes
+
+- The script leaves branches around for inspection — you can diff them manually after
+- Forge workspace agents are configured minimally (role + 2-3 steps each) to keep comparison fair
+- If Forge has auth enabled, the script may need a token — extend `api()` helper to send `X-Forge-Token`

package/scripts/bench/results/.gitignore

@@ -0,0 +1,2 @@
+*
+!.gitignore