@worca/ui 0.9.0 → 0.11.0

package/server/integrations/rate_limiter.js

@@ -0,0 +1,131 @@
+const BACKOFF_DELAYS = [1000, 5000, 30000];
+
+const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+export class RingBuffer {
+  constructor(size = 100) {
+    this._size = size;
+    this._buf = new Array(size);
+    this._head = 0;
+    this._count = 0;
+    this.dropped = 0;
+  }
+
+  push(item) {
+    if (this._count < this._size) {
+      this._count++;
+    } else {
+      this.dropped++;
+    }
+    this._buf[this._head] = item;
+    this._head = (this._head + 1) % this._size;
+  }
+
+  toArray() {
+    if (this._count < this._size) {
+      return this._buf.slice(0, this._count);
+    }
+    const result = [];
+    for (let i = 0; i < this._size; i++) {
+      result.push(this._buf[(this._head + i) % this._size]);
+    }
+    return result;
+  }
+}
+
+export class TokenBucket {
+  constructor(ratePerMin, { now = Date.now.bind(Date) } = {}) {
+    this._rate = ratePerMin;
+    this._tokens = ratePerMin;
+    this._lastRefill = now();
+    this._now = now;
+  }
+
+  tryConsume() {
+    const t = this._now();
+    const mins = (t - this._lastRefill) / 60000;
+    this._tokens = Math.min(this._rate, this._tokens + mins * this._rate);
+    this._lastRefill = t;
+    if (this._tokens >= 1) {
+      this._tokens -= 1;
+      return true;
+    }
+    return false;
+  }
+}
+
+export function createRateLimiter({
+  ratePerMin = 20,
+  ringSize = 100,
+  _sleep = defaultSleep,
+} = {}) {
+  const ring = new RingBuffer(ringSize);
+  const bucket = new TokenBucket(ratePerMin);
+  let droppedMessages = 0;
+
+  async function trySend(msg, sendFn) {
+    for (let attempt = 0; attempt <= BACKOFF_DELAYS.length; attempt++) {
+      if (attempt > 0) {
+        await _sleep(BACKOFF_DELAYS[attempt - 1]);
+      }
+      try {
+        await sendFn(msg);
+        return true;
+      } catch (err) {
+        if (err?.status === 429) {
+          if (attempt < BACKOFF_DELAYS.length) continue;
+          console.warn(
+            '[rate_limiter] 429 exhausted after all retries — dropping message',
+          );
+          return false;
+        }
+        throw err;
+      }
+    }
+    return false;
+  }
+
+  const pendingQueue = [];
+  let workerRunning = false;
+
+  async function runWorker() {
+    if (workerRunning) return;
+    workerRunning = true;
+    while (pendingQueue.length > 0) {
+      if (!bucket.tryConsume()) {
+        await _sleep(Math.ceil(60000 / ratePerMin));
+        continue;
+      }
+      const { msg, sendFn, resolve, reject } = pendingQueue.shift();
+      try {
+        const sent = await trySend(msg, sendFn);
+        if (sent) {
+          const prevDropped = ring.dropped;
+          ring.push(msg);
+          droppedMessages += ring.dropped - prevDropped;
+        } else {
+          droppedMessages++;
+        }
+        resolve(sent);
+      } catch (err) {
+        reject(err);
+      }
+    }
+    workerRunning = false;
+  }
+
+  return {
+    send(msg, sendFn) {
+      return new Promise((resolve, reject) => {
+        pendingQueue.push({ msg, sendFn, resolve, reject });
+        runWorker();
+      });
+    },
+    getStats() {
+      return { dropped_messages: droppedMessages };
+    },
+    getRing() {
+      return ring.toArray();
+    },
+  };
+}

package/server/integrations/renderers.js

@@ -0,0 +1,191 @@
+/**
+ * Tier 1 event renderers — map pipeline event envelopes to NormalizedMessage.
+ * Uses markdown segments so each adapter converts to its native format.
+ * @module renderers
+ */
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** @param {string} value @returns {import('./adapter.js').MessageSegment} */
+const md = (value) => ({ kind: 'markdown', value });
+
+function fmtMs(ms) {
+  if (ms == null) return null;
+  const totalSec = Math.floor(ms / 1000);
+  const m = Math.floor(totalSec / 60);
+  const s = totalSec % 60;
+  return m > 0 ? `${m}m${String(s).padStart(2, '0')}s` : `${s}s`;
+}
+
+function fmtUsd(usd) {
+  if (usd == null) return null;
+  return `$${Number(usd).toFixed(2)}`;
+}
+
+function runId(envelope) {
+  return envelope.run_id ?? 'run';
+}
+
+function mdMsg(text, severity) {
+  return { title: null, body: [md(text)], severity };
+}
+
+// ---------------------------------------------------------------------------
+// Per-event renderers
+// ---------------------------------------------------------------------------
+
+function renderRunStarted(envelope) {
+  const p = envelope.payload;
+  const title = p.title ?? p.prompt ?? '';
+  const label = title.length > 60 ? `${title.slice(0, 60)}\u2026` : title;
+  const parts = [`\u{1F7E2} **Run:** \`${runId(envelope)}\``];
+  if (label) parts.push(`   **Title:** ${label}`);
+  parts.push('   **Status:** started');
+  return mdMsg(parts.join('\n'), 'info');
+}
+
+function renderRunCompleted(envelope) {
+  const p = envelope.payload;
+  const parts = [`\u2705 **Run:** \`${runId(envelope)}\``];
+  if (p.title) parts.push(`   **Title:** ${p.title}`);
+  parts.push('   **Status:** completed');
+  const dur = fmtMs(p.duration_ms);
+  if (dur) parts.push(`   **Duration:** ${dur}`);
+  const cost = fmtUsd(p.total_cost_usd);
+  if (cost) parts.push(`   **Cost:** ${cost}`);
+  return mdMsg(parts.join('\n'), 'success');
+}
+
+function renderRunFailed(envelope) {
+  const p = envelope.payload;
+  const errLabel = p.error_type ?? p.error ?? 'error';
+  const stage = p.failed_stage ?? 'unknown';
+  const parts = [`\u{1F534} **Run:** \`${runId(envelope)}\``];
+  if (p.title) parts.push(`   **Title:** ${p.title}`);
+  parts.push(`   **Status:** failed at ${stage}`);
+  parts.push(`   **Error:** ${errLabel}`);
+  return mdMsg(parts.join('\n'), 'error');
+}
+
+function renderRunInterrupted(envelope) {
+  const p = envelope.payload;
+  const stage = p.interrupted_stage ?? 'unknown';
+  const parts = [`\u{1F534} **Run:** \`${runId(envelope)}\``];
+  parts.push(`   **Status:** interrupted at ${stage}`);
+  const dur = fmtMs(p.elapsed_ms);
+  if (dur) parts.push(`   **Duration:** ${dur}`);
+  return mdMsg(parts.join('\n'), 'warning');
+}
+
+function renderRunPaused(envelope) {
+  const p = envelope.payload;
+  const stage = p.stage ?? '';
+  const parts = [`\u{1F7E1} **Run:** \`${runId(envelope)}\``];
+  const statusLine = stage ? `paused at ${stage}` : 'paused';
+  parts.push(`   **Status:** ${statusLine}`);
+  return mdMsg(parts.join('\n'), 'warning');
+}
+
+function renderRunResumed(envelope) {
+  const parts = [`\u{1F7E2} **Run:** \`${runId(envelope)}\``];
+  parts.push('   **Status:** resumed');
+  return mdMsg(parts.join('\n'), 'info');
+}
+
+function renderRunResumedFromPause(envelope) {
+  const parts = [`\u{1F7E2} **Run:** \`${runId(envelope)}\``];
+  parts.push('   **Status:** resumed from pause');
+  return mdMsg(parts.join('\n'), 'info');
+}
+
+function renderStageStarted(envelope) {
+  const p = envelope.payload;
+  const iterPart = p.iteration ? ` (iteration ${p.iteration})` : '';
+  const parts = [`\u2699 **Run:** \`${runId(envelope)}\``];
+  parts.push(`   **Stage:** ${p.stage ?? 'unknown'}${iterPart}`);
+  return mdMsg(parts.join('\n'), 'info');
+}
+
+function renderStageCompleted(envelope) {
+  const p = envelope.payload;
+  const parts = [`\u2705 **Run:** \`${runId(envelope)}\``];
+  parts.push(`   **Stage:** ${p.stage ?? 'unknown'} completed`);
+  const dur = fmtMs(p.duration_ms);
+  if (dur) parts.push(`   **Duration:** ${dur}`);
+  return mdMsg(parts.join('\n'), 'success');
+}
+
+function renderStageInterrupted(envelope) {
+  const p = envelope.payload;
+  const parts = [`\u23F8 **Run:** \`${runId(envelope)}\``];
+  parts.push(`   **Stage:** ${p.stage ?? 'unknown'} interrupted`);
+  return mdMsg(parts.join('\n'), 'warning');
+}
+
+function renderGitPrCreated(envelope) {
+  const p = envelope.payload;
+  const parts = [`\u{1F500} **Run:** \`${runId(envelope)}\``];
+  parts.push(`   **PR:** [#${p.pr_number}](${p.pr_url}) \u2014 ${p.title}`);
+  return mdMsg(parts.join('\n'), 'info');
+}
+
+function renderGitPrMerged(envelope) {
+  const p = envelope.payload;
+  const parts = [`\u2705 **PR merged:** [#${p.pr_number}](${p.pr_url})`];
+  return mdMsg(parts.join('\n'), 'success');
+}
+
+function renderCbTripped(envelope) {
+  const p = envelope.payload;
+  const parts = [`\u26A0 **Run:** \`${runId(envelope)}\``];
+  parts.push(
+    `   **Circuit breaker:** ${p.consecutive_failures}\u00D7 ${p.category} \u2014 run halted`,
+  );
+  return mdMsg(parts.join('\n'), 'error');
+}
+
+function renderCostBudgetWarning(envelope) {
+  const p = envelope.payload;
+  const pct = Math.round(p.pct_used * 100);
+  const parts = [`\u{1F4B8} **Run:** \`${runId(envelope)}\``];
+  parts.push(`   **Budget:** ${pct}% of ${fmtUsd(p.budget_usd)} used`);
+  return mdMsg(parts.join('\n'), 'warning');
+}
+
+// ---------------------------------------------------------------------------
+// Registry
+// ---------------------------------------------------------------------------
+
+const EVENT_RENDERERS = {
+  'pipeline.run.started': renderRunStarted,
+  'pipeline.run.completed': renderRunCompleted,
+  'pipeline.run.failed': renderRunFailed,
+  'pipeline.run.interrupted': renderRunInterrupted,
+  'pipeline.run.paused': renderRunPaused,
+  'pipeline.run.resumed': renderRunResumed,
+  'pipeline.run.resumed_from_pause': renderRunResumedFromPause,
+  'pipeline.stage.started': renderStageStarted,
+  'pipeline.stage.completed': renderStageCompleted,
+  'pipeline.stage.interrupted': renderStageInterrupted,
+  'pipeline.git.pr_created': renderGitPrCreated,
+  'pipeline.git.pr_merged': renderGitPrMerged,
+  'pipeline.circuit_breaker.tripped': renderCbTripped,
+  'pipeline.cost.budget_warning': renderCostBudgetWarning,
+};
+
+export const TIER1_EVENTS = Object.keys(EVENT_RENDERERS);
+
+/**
+ * Map a pipeline event envelope to a NormalizedMessage.
+ * Returns null for unrecognised event types.
+ *
+ * @param {object|null|undefined} envelope - event envelope (event_type, run_id, payload)
+ * @returns {import('./adapter.js').NormalizedMessage|null}
+ */
+export function renderEvent(envelope) {
+  const renderer = EVENT_RENDERERS[envelope?.event_type];
+  if (!renderer) return null;
+  return renderer(envelope);
+}

package/server/integrations/rest_client.js

@@ -0,0 +1,17 @@
+export function createRestClient({ host, port }) {
+  const base = `http://${host}:${port}`;
+  return {
+    async get(path) {
+      const r = await fetch(`${base}${path}`);
+      return { status: r.status, data: r.ok ? await r.json() : null };
+    },
+    async post(path, body) {
+      const r = await fetch(`${base}${path}`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(body ?? {}),
+      });
+      return { status: r.status, data: r.ok ? await r.json() : null };
+    },
+  };
+}

package/server/integrations/verify.js

@@ -0,0 +1,23 @@
+import { createHmac, timingSafeEqual } from 'node:crypto';
+
+/**
+ * @param {string|Buffer} rawBody
+ * @param {string|null|undefined} sigHeader  — value of X-Worca-Signature header
+ * @param {string[]} secrets                 — any-match set
+ * @returns {boolean}
+ */
+export function verify(rawBody, sigHeader, secrets) {
+  if (!sigHeader?.startsWith('sha256=')) return false;
+  const received = Buffer.from(sigHeader.slice(7));
+  for (const secret of secrets) {
+    const expected = Buffer.from(
+      createHmac('sha256', secret).update(rawBody).digest('hex'),
+    );
+    if (
+      expected.length === received.length &&
+      timingSafeEqual(expected, received)
+    )
+      return true;
+  }
+  return false;
+}

package/server/process-manager.js

@@ -4,24 +4,41 @@
  */
 
 import { spawn } from 'node:child_process';
-import { randomBytes } from 'node:crypto';
+import { randomBytes, randomUUID } from 'node:crypto';
 import {
+  appendFileSync,
   closeSync,
   existsSync,
   mkdirSync,
   openSync,
   readdirSync,
   readFileSync,
+  rmSync,
   unlinkSync,
   writeFileSync,
   writeSync,
 } from 'node:fs';
 import { tmpdir } from 'node:os';
-import { join } from 'node:path';
+import { join, resolve } from 'node:path';
+
+import { dispatchExternal } from './dispatch-external.js';
 
 /** Byte threshold — must match claude_cli.py _ARG_INLINE_LIMIT */
 const ARG_INLINE_LIMIT = 128 * 1024;
 
+const TERMINAL_EVENTS = [
+  'pipeline.run.interrupted',
+  'pipeline.run.failed',
+  'pipeline.run.completed',
+];
+
+function elapsedMsSince(startedAtIso) {
+  if (!startedAtIso) return 0;
+  const started = Date.parse(startedAtIso);
+  if (Number.isNaN(started)) return 0;
+  return Math.max(0, Date.now() - started);
+}
+
 /**
  * Write content to a temp file with restricted permissions (0o600) and return its path.
  * Used to avoid E2BIG when passing large prompts as CLI arguments.
@@ -59,11 +76,12 @@ function cleanupPromptFile(filePath) {
  */
 export class ProcessManager {
   /**
-   * @param {{ worcaDir: string, projectRoot?: string }} options
+   * @param {{ worcaDir: string, projectRoot?: string, settingsPath?: string }} options
    */
-  constructor({ worcaDir, projectRoot }) {
+  constructor({ worcaDir, projectRoot, settingsPath }) {
     this.worcaDir = worcaDir;
     this.projectRoot = projectRoot || process.cwd();
+    this.settingsPath = settingsPath ?? null;
   }
 
   /**
@@ -114,8 +132,9 @@ export class ProcessManager {
    *
    * @returns {boolean} true if any status was fixed
    */
-  reconcileStatus() {
+  async reconcileStatus() {
     let fixed = false;
+    const dispatches = [];
 
     // Collect run IDs to check: scan runs/*/pipeline.pid + active_run fallback
     const runIds = new Set();
@@ -163,10 +182,11 @@ export class ProcessManager {
 
       if (status.pipeline_status !== 'running') continue;
 
-      status.pipeline_status = 'failed';
       if (!status.stop_reason) {
         status.stop_reason = 'stale';
       }
+      status.pipeline_status =
+        status.stop_reason === 'signal' ? 'interrupted' : 'failed';
       try {
         writeFileSync(
           statusPath,
@@ -177,8 +197,71 @@ export class ProcessManager {
       } catch {
         /* ignore */
       }
+
+      // Append synthetic terminal event if none exists yet.
+      // Use pipeline.run.interrupted for signal-killed runs, pipeline.run.failed otherwise.
+      const eventsPath = join(this.worcaDir, 'runs', runId, 'events.jsonl');
+      let hasTerminalEvent = false;
+      if (existsSync(eventsPath)) {
+        try {
+          const lines = readFileSync(eventsPath, 'utf8')
+            .split('\n')
+            .filter(Boolean);
+          hasTerminalEvent = lines.some((line) => {
+            try {
+              const evt = JSON.parse(line);
+              return TERMINAL_EVENTS.includes(evt.event_type);
+            } catch {
+              return false;
+            }
+          });
+        } catch {
+          /* ignore */
+        }
+      }
+      if (!hasTerminalEvent) {
+        const eventType =
+          status.stop_reason === 'signal'
+            ? 'pipeline.run.interrupted'
+            : 'pipeline.run.failed';
+        const payload = {
+          failed_stage: status.current_stage ?? 'unknown',
+          elapsed_ms: elapsedMsSince(status.started_at),
+          source: 'stale',
+        };
+
+        if (this.settingsPath) {
+          dispatches.push(
+            dispatchExternal({
+              runDir: join(this.worcaDir, 'runs', runId),
+              settingsPath: this.settingsPath,
+              eventType,
+              payload,
+            }).catch(() => {}),
+          );
+        } else {
+          try {
+            const evt = {
+              schema_version: '1',
+              event_id: randomUUID(),
+              event_type: eventType,
+              timestamp: new Date().toISOString(),
+              run_id: status.run_id ?? runId,
+              pipeline: {
+                branch: status.branch ?? null,
+                work_request: status.work_request ?? null,
+              },
+              payload: { ...payload, source: 'reconcile' },
+            };
+            appendFileSync(eventsPath, `${JSON.stringify(evt)}\n`, 'utf8');
+          } catch {
+            /* ignore */
+          }
+        }
+      }
     }
 
+    await Promise.all(dispatches);
     return fixed;
   }
 
@@ -384,17 +467,18 @@ export class ProcessManager {
       throw err;
     }
 
-    // Watchdog: SIGKILL after 10s if still alive, then reconcile status
+    // Watchdog: SIGKILL after 10s if still alive, then reconcile status.
+    // Fire-and-forget: reconcileStatus is async but we intentionally don't
+    // await it — this is a background cleanup path after the response is sent.
     const worcaDir = this.worcaDir;
+    const { settingsPath } = this;
     const watchdog = setTimeout(() => {
       try {
         process.kill(pid, 0); // check alive
         process.kill(pid, 'SIGKILL');
-        // Give the OS a moment to reap the process, then fix stale status
-        setTimeout(() => reconcileStatus(worcaDir), 500);
+        setTimeout(() => reconcileStatus(worcaDir, settingsPath), 500);
       } catch {
-        // Already dead — reconcile in case signal handler didn't save
-        reconcileStatus(worcaDir);
+        reconcileStatus(worcaDir, settingsPath);
       }
     }, 10000);
     watchdog.unref();
@@ -411,6 +495,80 @@ export class ProcessManager {
     return { pid, stopped: true };
   }
 
+  /**
+   * Synchronous-style stop: control.json + signal + poll for exit.
+   * @param {string} runId
+   * @param {{ timeoutMs?: number }} [opts]
+   * @returns {Promise<{ pid: number, exitCode: null, forced?: boolean }>}
+   */
+  async stopPipelineSync(runId, { timeoutMs } = {}) {
+    if (timeoutMs === undefined) {
+      timeoutMs = process.platform === 'win32' ? 30000 : 5000;
+    }
+
+    const running = this.getRunningPid(runId);
+    if (!running) {
+      const e = new Error('not running');
+      e.code = 'not_running';
+      throw e;
+    }
+    const { pid } = running;
+
+    const controlDir = join(this.worcaDir, 'runs', runId);
+    mkdirSync(controlDir, { recursive: true });
+    writeFileSync(
+      join(controlDir, 'control.json'),
+      `${JSON.stringify({ action: 'stop', requested_at: new Date().toISOString(), source: 'ui' }, null, 2)}\n`,
+      'utf8',
+    );
+
+    if (process.platform !== 'win32') {
+      try {
+        process.kill(pid, 'SIGTERM');
+      } catch {
+        /* already dead */
+      }
+    } else {
+      this._killAgentSubprocess(runId);
+    }
+
+    const pollMs = timeoutMs > 10000 ? 500 : 100;
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+      try {
+        process.kill(pid, 0);
+      } catch {
+        return { pid, exitCode: null };
+      }
+      await new Promise((r) => setTimeout(r, pollMs));
+    }
+
+    try {
+      process.kill(pid, 'SIGKILL');
+    } catch {
+      /* already dead */
+    }
+    return { pid, exitCode: null, forced: true };
+  }
+
+  /**
+   * Kill the agent subprocess (claude CLI) via agent.pid.
+   * Used on Windows where SIGTERM doesn't propagate to child processes.
+   * @param {string} runId
+   */
+  _killAgentSubprocess(runId) {
+    const pidPath = join(this.worcaDir, 'runs', runId, 'agent.pid');
+    if (!existsSync(pidPath)) return;
+    try {
+      const agentPid = parseInt(readFileSync(pidPath, 'utf8').trim(), 10);
+      if (!Number.isNaN(agentPid) && agentPid > 0) {
+        process.kill(agentPid, 'SIGTERM');
+      }
+    } catch {
+      /* agent already dead or pid file invalid */
+    }
+  }
+
   /**
    * Read the active_run file to get the current run ID.
    * @returns {string|null}
@@ -426,6 +584,51 @@ export class ProcessManager {
     }
   }
 
+  /**
+   * Delete a run directory and clean up references.
+   * Refuses if the pipeline is currently running.
+   * @param {string} runId
+   * @returns {{ deleted: boolean }}
+   */
+  deleteRun(runId) {
+    const running = this.getRunningPid(runId);
+    if (running) {
+      const err = new Error(
+        'Cannot delete a running pipeline — stop or cancel it first',
+      );
+      err.code = 'still_running';
+      throw err;
+    }
+
+    const runsParent = resolve(this.worcaDir, 'runs');
+    const runDir = resolve(runsParent, runId);
+    if (!runDir.startsWith(runsParent)) {
+      const err = new Error('Invalid runId');
+      err.code = 'invalid_id';
+      throw err;
+    }
+    if (!existsSync(runDir)) {
+      const err = new Error(`Run "${runId}" not found`);
+      err.code = 'not_found';
+      throw err;
+    }
+
+    rmSync(runDir, { recursive: true, force: true });
+
+    // Clear active_run pointer if it references this run
+    const activeRunPath = join(this.worcaDir, 'active_run');
+    if (existsSync(activeRunPath)) {
+      try {
+        const activeId = readFileSync(activeRunPath, 'utf8').trim();
+        if (activeId === runId) unlinkSync(activeRunPath);
+      } catch {
+        /* ignore */
+      }
+    }
+
+    return { deleted: true };
+  }
+
   /**
    * Pause a running pipeline by writing a control file.
    * @param {string} runId - Pipeline run identifier
@@ -581,9 +784,9 @@ export function getRunningPid(worcaDir, runId) {
   return new ProcessManager({ worcaDir }).getRunningPid(runId);
 }
 
-/** @param {string} worcaDir */
-export function reconcileStatus(worcaDir) {
-  return new ProcessManager({ worcaDir }).reconcileStatus();
+/** @param {string} worcaDir @param {string} [settingsPath] */
+export function reconcileStatus(worcaDir, settingsPath) {
+  return new ProcessManager({ worcaDir, settingsPath }).reconcileStatus();
 }
 
 /** @param {string} worcaDir @param {object} opts */