@agile-vibe-coding/avc 0.2.3 → 0.3.1

package/kanban/server/services/TaskRunnerService.js

@@ -0,0 +1,261 @@
+/**
+ * TaskRunnerService — Manages seed and run-task processes independently from CeremonyService.
+ *
+ * Supports multiple concurrent runs (each tracked by processId).
+ * Uses the same fork → IPC → WebSocket pattern as CeremonyService.
+ */
+
+import { fork } from 'child_process';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+let _nextId = 1;
+
+export class TaskRunnerService {
+  constructor(projectRoot) {
+    this.projectRoot = projectRoot;
+    this._runs = new Map(); // processId → { type, itemId, child, status, progress }
+    this.websocket = null;
+    this._reloadCallback = null;
+  }
+
+  setWebSocket(ws) { this.websocket = ws; }
+  setReloadCallback(fn) { this._reloadCallback = fn; }
+
+  /**
+   * Get the status of a specific run.
+   */
+  getRunStatus(processId) {
+    const run = this._runs.get(processId);
+    if (!run) return null;
+    return {
+      processId,
+      type: run.type,
+      itemId: run.itemId,
+      status: run.status,
+      progress: run.progress,
+    };
+  }
+
+  /**
+   * Get all active runs for a given item.
+   */
+  getRunsForItem(itemId) {
+    const runs = [];
+    for (const [processId, run] of this._runs) {
+      if (run.itemId === itemId) {
+        runs.push({ processId, type: run.type, status: run.status });
+      }
+    }
+    return runs;
+  }
+
+  /**
+   * List all active/recent runs.
+   */
+  listRuns() {
+    return [...this._runs.entries()].map(([processId, run]) => ({
+      processId,
+      type: run.type,
+      itemId: run.itemId,
+      status: run.status,
+    }));
+  }
+
+  /**
+   * Check if a specific item has an active run.
+   */
+  isRunning(itemId) {
+    for (const run of this._runs.values()) {
+      if (run.itemId === itemId && run.status === 'running') return true;
+    }
+    return false;
+  }
+
+  /**
+   * Fork a seed worker for a story.
+   * @param {string} storyId
+   * @returns {string} processId
+   */
+  runSeed(storyId) {
+    if (this.isRunning(storyId)) {
+      throw new Error(`Seed already running for ${storyId}`);
+    }
+
+    const processId = `seed-${_nextId++}`;
+    const workerPath = path.join(__dirname, '../workers/seed-worker.js');
+
+    const child = fork(workerPath, [], {
+      stdio: ['ignore', 'pipe', 'pipe', 'ipc'],
+      cwd: this.projectRoot,
+      env: { ...process.env },
+    });
+    child.stdout?.on('data', d => process.stdout.write(d));
+    child.stderr?.on('data', d => process.stderr.write(d));
+
+    const run = {
+      type: 'seed',
+      itemId: storyId,
+      child,
+      status: 'running',
+      progress: [],
+    };
+    this._runs.set(processId, run);
+
+    child.send({ type: 'init', storyId });
+
+    child.on('message', (msg) => this._handleMessage(processId, msg));
+    child.on('exit', (code) => this._handleExit(processId, code));
+
+    return processId;
+  }
+
+  /**
+   * Fork a run-task worker for a task.
+   * @param {string} taskId
+   * @returns {string} processId
+   */
+  runTask(taskId) {
+    if (this.isRunning(taskId)) {
+      throw new Error(`Run already active for ${taskId}`);
+    }
+
+    const processId = `run-${_nextId++}`;
+    const workerPath = path.join(__dirname, '../workers/run-task-worker.js');
+
+    const child = fork(workerPath, [], {
+      stdio: ['ignore', 'pipe', 'pipe', 'ipc'],
+      cwd: this.projectRoot,
+      env: { ...process.env },
+    });
+    child.stdout?.on('data', d => process.stdout.write(d));
+    child.stderr?.on('data', d => process.stderr.write(d));
+
+    const run = {
+      type: 'run-task',
+      itemId: taskId,
+      child,
+      status: 'running',
+      progress: [],
+    };
+    this._runs.set(processId, run);
+
+    child.send({ type: 'init', taskId });
+
+    child.on('message', (msg) => this._handleMessage(processId, msg));
+    child.on('exit', (code) => this._handleExit(processId, code));
+
+    return processId;
+  }
+
+  /**
+   * Cancel a running process.
+   */
+  cancel(processId) {
+    const run = this._runs.get(processId);
+    if (!run || run.status !== 'running') return false;
+
+    try { run.child.send({ type: 'cancel' }); } catch {}
+    run.status = 'cancelling';
+
+    // Safety net: SIGTERM after 10s, SIGKILL after 13s
+    const killTimer = setTimeout(() => {
+      if (run.status === 'cancelling') {
+        try { run.child.kill('SIGTERM'); } catch {}
+        setTimeout(() => {
+          if (run.status === 'cancelling') {
+            try { run.child.kill('SIGKILL'); } catch {}
+          }
+        }, 3000);
+      }
+    }, 10000);
+    run._killTimer = killTimer;
+
+    return true;
+  }
+
+  /**
+   * Handle IPC messages from workers.
+   */
+  _handleMessage(processId, msg) {
+    const run = this._runs.get(processId);
+    if (!run) return;
+
+    switch (msg.type) {
+      case 'progress':
+        run.progress.push(msg.message);
+        this.websocket?.broadcast({
+          type: `${run.type}:progress`,
+          processId,
+          itemId: run.itemId,
+          message: msg.message,
+        });
+        break;
+
+      case 'item-written':
+        this._reloadCallback?.();
+        this.websocket?.broadcastRefresh();
+        break;
+
+      case 'complete':
+        run.status = 'complete';
+        if (run._killTimer) clearTimeout(run._killTimer);
+        this._reloadCallback?.();
+        this.websocket?.broadcastRefresh();
+        this.websocket?.broadcast({
+          type: `${run.type}:complete`,
+          processId,
+          itemId: run.itemId,
+          result: msg.result,
+        });
+        break;
+
+      case 'cancelled':
+        run.status = 'cancelled';
+        if (run._killTimer) clearTimeout(run._killTimer);
+        this.websocket?.broadcast({
+          type: `${run.type}:cancelled`,
+          processId,
+          itemId: run.itemId,
+        });
+        break;
+
+      case 'error':
+        run.status = 'error';
+        if (run._killTimer) clearTimeout(run._killTimer);
+        this.websocket?.broadcast({
+          type: `${run.type}:error`,
+          processId,
+          itemId: run.itemId,
+          error: msg.error?.message || 'Unknown error',
+        });
+        break;
+    }
+  }
+
+  /**
+   * Handle worker exit.
+   */
+  _handleExit(processId, code) {
+    const run = this._runs.get(processId);
+    if (!run) return;
+
+    if (run._killTimer) clearTimeout(run._killTimer);
+
+    if (run.status === 'running' || run.status === 'cancelling') {
+      run.status = 'error';
+      this.websocket?.broadcast({
+        type: `${run.type}:error`,
+        processId,
+        itemId: run.itemId,
+        error: `Worker exited unexpectedly (code ${code})`,
+      });
+    }
+
+    // Clean up old runs after 5 minutes
+    setTimeout(() => this._runs.delete(processId), 5 * 60 * 1000);
+  }
+}

package/kanban/server/workers/run-task-worker.js

@@ -0,0 +1,121 @@
+/**
+ * Run Task Worker
+ * Forked by TaskRunnerService.runTask().
+ * Creates a git worktree, implements code via LLM, runs tests, commits, merges.
+ *
+ * Parent → Worker:
+ *   { type: 'init', taskId }
+ *   { type: 'cancel' }
+ *
+ * Worker → Parent:
+ *   { type: 'progress', message }
+ *   { type: 'complete', result: { success, taskId } }
+ *   { type: 'cancelled' }
+ *   { type: 'error', error }
+ */
+
+import { CommandLogger } from '../../../cli/command-logger.js';
+import { readFileSync, writeFileSync, existsSync } from 'fs';
+import { join } from 'path';
+
+let _cancelled = false;
+
+process.on('disconnect', () => {
+  _cancelled = true;
+  setTimeout(() => process.exit(1), 5000).unref();
+});
+
+process.on('message', async (msg) => {
+  if (msg.type === 'init') {
+    run(msg.taskId);
+  } else if (msg.type === 'cancel') {
+    _cancelled = true;
+  }
+});
+
+/**
+ * Update work.json status on disk.
+ */
+function updateStatus(taskId, status) {
+  const projectRoot = process.cwd();
+  // Find the work.json by walking the hierarchy
+  // Task ID: context-0001-0001-0001 → path: .avc/project/context-0001/context-0001-0001/context-0001-0001-0001/work.json
+  const idParts = taskId.replace('context-', '').split('-');
+  let dir = join(projectRoot, '.avc', 'project');
+  let current = 'context';
+  for (const part of idParts) {
+    current += `-${part}`;
+    dir = join(dir, current);
+  }
+  const workJsonPath = join(dir, 'work.json');
+
+  if (existsSync(workJsonPath)) {
+    try {
+      const workJson = JSON.parse(readFileSync(workJsonPath, 'utf8'));
+      workJson.status = status;
+      workJson.updated = new Date().toISOString();
+      writeFileSync(workJsonPath, JSON.stringify(workJson, null, 2), 'utf8');
+    } catch {}
+  }
+}
+
+async function run(taskId) {
+  const logger = new CommandLogger('run-task', process.cwd());
+  logger.start();
+
+  try {
+    const { WorktreeRunner } = await import('../../../cli/worktree-runner.js');
+
+    // Set status to implementing
+    updateStatus(taskId, 'implementing');
+    try { process.send({ type: 'progress', message: `Starting implementation of ${taskId}` }); } catch {}
+
+    const runner = new WorktreeRunner(taskId, process.cwd());
+
+    const progressCallback = (message) => {
+      if (_cancelled) return;
+      try { process.send({ type: 'progress', message }); } catch {}
+    };
+
+    const cancelledCheck = () => _cancelled;
+
+    const result = await runner.execute(progressCallback, cancelledCheck);
+
+    if (_cancelled) {
+      updateStatus(taskId, 'planned'); // Reset on cancel
+      try { process.send({ type: 'cancelled' }); } catch {}
+    } else if (result.success) {
+      updateStatus(taskId, 'completed');
+      try {
+        process.send({
+          type: 'complete',
+          result: { success: true, taskId },
+        });
+      } catch {}
+    } else {
+      updateStatus(taskId, 'failed');
+      try {
+        process.send({
+          type: 'error',
+          error: { message: result.error || 'Implementation failed' },
+        });
+      } catch {}
+    }
+  } catch (error) {
+    if (error.message === 'CANCELLED') {
+      updateStatus(taskId, 'planned');
+      try { process.send({ type: 'cancelled' }); } catch {}
+    } else {
+      updateStatus(taskId, 'failed');
+      try {
+        process.send({
+          type: 'error',
+          error: { message: error.message, stack: error.stack },
+        });
+      } catch {}
+    }
+  } finally {
+    logger.stop();
+    setTimeout(() => process.exit(0), 500).unref();
+  }
+}

package/kanban/server/workers/seed-worker.js

@@ -0,0 +1,94 @@
+/**
+ * Seed Worker
+ * Forked by TaskRunnerService.runSeed().
+ * Communicates with parent via IPC (process.send / process.on('message')).
+ *
+ * Parent → Worker:
+ *   { type: 'init', storyId }
+ *   { type: 'cancel' }
+ *
+ * Worker → Parent:
+ *   { type: 'progress', message }
+ *   { type: 'item-written', itemId, itemType }
+ *   { type: 'complete', result: { taskCount, subtaskCount, taskIds } }
+ *   { type: 'cancelled' }
+ *   { type: 'error', error }
+ */
+
+import { CommandLogger } from '../../../cli/command-logger.js';
+
+let _cancelled = false;
+
+process.on('disconnect', () => {
+  _cancelled = true;
+  setTimeout(() => process.exit(1), 5000).unref();
+});
+
+process.on('message', async (msg) => {
+  if (msg.type === 'init') {
+    run(msg.storyId);
+  } else if (msg.type === 'cancel') {
+    _cancelled = true;
+  }
+});
+
+async function run(storyId) {
+  const logger = new CommandLogger('seed', process.cwd());
+  logger.start();
+
+  try {
+    // Dynamic import to avoid loading CLI modules at fork time
+    const { SeedProcessor } = await import('../../../cli/seed-processor.js');
+
+    const processor = new SeedProcessor(storyId);
+
+    const progressCallback = (message) => {
+      if (_cancelled) return;
+      try { process.send({ type: 'progress', message }); } catch {}
+    };
+
+    const itemWrittenCallback = ({ itemId, itemType }) => {
+      if (_cancelled) return;
+      try { process.send({ type: 'item-written', itemId, itemType }); } catch {}
+    };
+
+    const cancelledCheck = () => _cancelled;
+
+    const result = await processor.executeWithCallback(
+      progressCallback,
+      itemWrittenCallback,
+      cancelledCheck
+    );
+
+    if (_cancelled) {
+      try { process.send({ type: 'cancelled' }); } catch {}
+    } else {
+      try {
+        process.send({
+          type: 'complete',
+          result: {
+            storyId,
+            taskCount: result.taskCount,
+            subtaskCount: result.subtaskCount,
+            taskIds: result.taskIds,
+          },
+        });
+      } catch {}
+    }
+  } catch (error) {
+    if (error.message === 'CEREMONY_CANCELLED') {
+      try { process.send({ type: 'cancelled' }); } catch {}
+    } else {
+      try {
+        process.send({
+          type: 'error',
+          error: { message: error.message, stack: error.stack },
+        });
+      } catch {}
+    }
+  } finally {
+    logger.stop();
+    // Give parent time to receive the final message
+    setTimeout(() => process.exit(0), 500).unref();
+  }
+}

package/kanban/server/workers/sponsor-call-worker.js

@@ -70,15 +70,23 @@ async function run() {
       costLimitReachedCallback,
     });
     logger.stop();
-    process.send({ type: 'complete', result });
+    // sponsorCallWithAnswers returns { error: true, message } on validation failure instead of throwing
+    if (result?.error === true) {
+      process.send({ type: 'error', error: result.message || 'Ceremony failed' });
+    } else {
+      process.send({ type: 'complete', result });
+    }
     process.exit(0);
   } catch (err) {
     logger.stop();
-    if (err.message === 'CEREMONY_CANCELLED') {
-      process.send({ type: 'cancelled' });
-    } else {
-      process.send({ type: 'error', error: err.message });
+    const msg = err.message === 'CEREMONY_CANCELLED'
+      ? { type: 'cancelled' }
+      : { type: 'error', error: err.message };
+    // Guard against ERR_IPC_CHANNEL_CLOSED if the parent already disconnected.
+    try {
+      process.send(msg, () => process.exit(0));
+    } catch (_) {
+      process.exit(0);
     }
-    process.exit(0);
   }
 }

package/kanban/server/workers/sprint-planning-worker.js

@@ -17,6 +17,7 @@
  *   { type: 'paused' }
  *   { type: 'resumed' }
  *   { type: 'decomposition-complete', hierarchy }
+ *   { type: 'hierarchy-written', epicCount, storyCount }
  *   { type: 'complete', result }
  *   { type: 'cancelled' }
  *   { type: 'error', error }
@@ -24,6 +25,33 @@
 
 import { ProjectInitiator } from '../../../cli/init.js';
 import { CommandLogger } from '../../../cli/command-logger.js';
+import { readFileSync } from 'fs';
+import { join } from 'path';
+
+function _isQuotaOrRateLimit(msg) {
+  const m = (msg || '').toLowerCase();
+  return m.includes('429') || m.includes('quota') || m.includes('rate limit') ||
+    m.includes('resource exhausted') || m.includes('resource_exhausted') ||
+    m.includes('too many requests') ||
+    // Anthropic credit-balance exhausted (400 invalid_request_error)
+    m.includes('credit balance is too low') || m.includes('credit balance') ||
+    m.includes('billing') || m.includes('insufficient_quota') ||
+    // Transient connection errors — surface as resumable to allow provider switch
+    m.includes('connection error') || m.includes('econnreset') ||
+    m.includes('econnrefused') || m.includes('network error') || m.includes('fetch failed');
+}
+
+function _getCurrentStageInfo(stageName) {
+  try {
+    const cfg = JSON.parse(readFileSync(join(process.cwd(), '.avc', 'avc.json'), 'utf8'));
+    const ceremony = cfg.settings?.ceremonies?.find(c => c.name === 'sprint-planning');
+    const stage = ceremony?.stages?.[stageName];
+    return {
+      provider: stage?.provider || ceremony?.provider || 'unknown',
+      model: stage?.model || ceremony?.defaultModel || 'unknown',
+    };
+  } catch { return { provider: 'unknown', model: 'unknown' }; }
+}
 
 let _paused = false;
 let _cancelled = false;
@@ -31,6 +59,8 @@ let _costThreshold = null;
 let _waitingCostLimit = false;
 let _waitingSelection = false;
 let _selectionResult = null;
+let _waitingQuota = false;
+let _quotaResolution = null;
 
 // Parent server stopped — exit rather than running as an orphan.
 process.on('disconnect', () => {
@@ -42,7 +72,7 @@ process.on('disconnect', () => {
 process.on('message', async (msg) => {
   if (msg.type === 'init') {
     _costThreshold = msg.costThreshold ?? null;
-    run();
+    run(msg.resumeFrom || null);
   } else if (msg.type === 'pause') {
     _paused = true;
     process.send({ type: 'paused' });
@@ -53,13 +83,18 @@ process.on('message', async (msg) => {
     _cancelled = true;
   } else if (msg.type === 'cost-limit-continue') {
     _waitingCostLimit = false;
+  } else if (msg.type === 'quota-continue') {
+    _quotaResolution = msg.newProvider
+      ? { newProvider: msg.newProvider, newModel: msg.newModel }
+      : null;
+    _waitingQuota = false;
   } else if (msg.type === 'selection-confirmed') {
     _selectionResult = { selectedEpicIds: msg.selectedEpicIds, selectedStoryIds: msg.selectedStoryIds };
     _waitingSelection = false;
   }
 });
 
-async function run() {
+async function run(resumeFrom = null) {
   const logger = new CommandLogger('sprint-planning', process.cwd());
   logger.start();
   try {
@@ -96,11 +131,54 @@ async function run() {
       return _selectionResult;
     };
 
-    const result = await initiator.sprintPlanningWithCallback(progressCallback, {
-      costThreshold: _costThreshold,
-      costLimitReachedCallback,
-      selectionCallback,
-    });
+    const hierarchyWrittenCallback = async ({ epicCount, storyCount }) => {
+      process.send({ type: 'hierarchy-written', epicCount, storyCount });
+    };
+
+    const itemWrittenCallback = async ({ itemId, itemType }) => {
+      process.send({ type: 'item-written', itemId, itemType });
+    };
+
+    const quotaExceededCallback = async ({ validatorName, errMsg, provider, model }) => {
+      _waitingQuota = true;
+      _quotaResolution = null;
+      process.send({ type: 'quota-limit', validatorName, errMsg, provider, model });
+      while (_waitingQuota) {
+        await new Promise(r => setTimeout(r, 200));
+        if (_cancelled) throw new Error('CEREMONY_CANCELLED');
+      }
+      return _quotaResolution; // null = retry same; { newProvider, newModel } = switch
+    };
+
+    // Outer retry loop: catches quota errors from pre-validator stages (decomposition, etc.)
+    // The processor is reconstructed on each retry so it picks up any avc.json model changes.
+    let result;
+    while (true) {
+      try {
+        result = await initiator.sprintPlanningWithCallback(progressCallback, {
+          costThreshold: _costThreshold,
+          costLimitReachedCallback,
+          selectionCallback,
+          hierarchyWrittenCallback,
+          itemWrittenCallback,
+          quotaExceededCallback,
+          resumeFrom,
+        });
+        break; // success — exit retry loop
+      } catch (err) {
+        if (err.message === 'CEREMONY_CANCELLED') throw err;
+        const errMsg = err.message || '';
+        if (_isQuotaOrRateLimit(errMsg)) {
+          // Quota error from a stage not covered by the validator callback (e.g. decomposition).
+          // Pause and wait for user to add credits or switch model via Configure Models.
+          const { provider, model } = _getCurrentStageInfo('decomposition');
+          await quotaExceededCallback({ validatorName: 'decomposition', errMsg: errMsg.split('\n')[0], provider, model });
+          // Retry — processor reconstructs and re-reads avc.json (picks up any model changes).
+          continue;
+        }
+        throw err; // non-quota error: propagate to outer catch
+      }
+    }
     logger.stop();
     process.send({ type: 'complete', result });
 
@@ -120,11 +198,15 @@ async function run() {
     process.exit(0);
   } catch (err) {
     logger.stop();
-    if (err.message === 'CEREMONY_CANCELLED') {
-      process.send({ type: 'cancelled' });
-    } else {
-      process.send({ type: 'error', error: err.message });
+    const msg = err.message === 'CEREMONY_CANCELLED'
+      ? { type: 'cancelled' }
+      : { type: 'error', error: err.message };
+    // Use callback to ensure the IPC message is flushed before exiting.
+    // Guard against ERR_IPC_CHANNEL_CLOSED if the parent already disconnected.
+    try {
+      process.send(msg, () => process.exit(0));
+    } catch (_) {
+      process.exit(0);
     }
-    process.exit(0);
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agile-vibe-coding/avc",
-  "version": "0.2.3",
+  "version": "0.3.1",
   "description": "Agile Vibe Coding (AVC) - Framework for managing AI agent-based software development projects",
   "type": "module",
   "main": "cli/index.js",
@@ -44,8 +44,7 @@
   ],
   "author": "Nacho Coll",
   "license": "PolyForm-Noncommercial-1.0.0",
-  "homepage": "https://agilevibecoding.org",
-  "repository": {
+"repository": {
     "type": "git",
     "url": "git+https://github.com/NachoColl/agilevibecoding.git",
     "directory": "src"

package/cli/agents/solver-epic-api.json

@@ -1,15 +0,0 @@
-{
-  "agentName": "solver-epic-api",
-  "version": "1.0.0",
-  "description": "Output schema for API Designer epic solver",
-  "requiredFields": ["id", "name", "domain", "description", "features", "dependencies", "improvementNotes"],
-  "fieldValidation": {
-    "id": { "type": "string" },
-    "name": { "type": "string" },
-    "domain": { "type": "string" },
-    "description": { "type": "string" },
-    "features": { "type": "array", "minLength": 1 },
-    "dependencies": { "type": "array" },
-    "improvementNotes": { "type": "string" }
-  }
-}