@worca/app 0.0.1

package/src/core/chat/notifier.mjs

@@ -0,0 +1,120 @@
+// src/core/chat/notifier.mjs
+// Outbound run-event notifications (chat-connectivity-design.md §4.5).
+// attach(orch, {runId, entry}) subscribes to the orchestrator's question/done/
+// error events — riding the exception-isolated _emit, so nothing here can
+// break a run — renders them to NormalizedMessages, and fans out to every
+// enabled+connected outbound channel's notifyChatIds through a per-channel
+// host-side rate limiter. Workers surface platform 429s; the limiter ladder
+// retries them.
+//
+// Core module (no Express, no orchestrator import): ui/server.mjs wires it
+// today; a CLI runner can attach the same notifier later.
+
+import { readPluginConfig } from '../plugin-config.mjs';
+import { parseIdList } from './allowlist.mjs';
+import { createRateLimiter } from './rate-limiter.mjs';
+import { renderDone, renderError, renderQuestion } from './renderers.mjs';
+
+/**
+ * @param {{channelHost: object, getPrefs: () => {notify:object, channels:object},
+ *          chatContext: {isMuted(k):boolean, incrementMuted(k):void},
+ *          logger?: (level:string, msg:string) => void,
+ *          ratePerMin?: number}} deps
+ */
+export function createNotifier({ channelHost, getPrefs, chatContext, logger = () => {}, ratePerMin = 20 }) {
+  const limiters = new Map(); // "plugin/channelId" -> rate limiter
+
+  const limiterFor = (key) => {
+    let l = limiters.get(key);
+    if (!l) { l = createRateLimiter({ ratePerMin, logger }); limiters.set(key, l); }
+    return l;
+  };
+
+  async function deliver(message) {
+    let prefs;
+    try { prefs = getPrefs(); } catch { prefs = { notify: {}, channels: {} }; }
+    for (const entry of channelHost.list()) {
+      const key = `${entry.plugin}/${entry.channelId}`;
+      if (!entry.capabilities?.outbound) continue;
+      if (prefs.channels?.[key]?.enabled === false) continue;
+      let chatIds = [];
+      try { chatIds = parseIdList(readPluginConfig(entry.plugin, entry.configSchema).notifyChatIds); }
+      catch { /* unreadable config: nothing to send to */ }
+      for (const chatId of chatIds) {
+        const chatKey = `${entry.platform}:${chatId}`;
+        if (chatContext.isMuted(chatKey)) {
+          try { chatContext.incrementMuted(chatKey); } catch { /* best effort */ }
+          continue;
+        }
+        // Sequenced per channel by the limiter's FIFO; failures are logged,
+        // never thrown (the caller is an event listener on the run).
+        limiterFor(key).send(message, (m) => channelHost.sendMessage({
+          plugin: entry.plugin, channelId: entry.channelId, chatId, message: m,
+        })).then((sent) => {
+          if (!sent) logger('warn', `chat notify dropped after rate-limit retries (${key} -> ${chatId})`);
+        }).catch((err) => {
+          logger('error', `chat notify failed (${key} -> ${chatId}): ${err?.message || err}`);
+        });
+      }
+    }
+  }
+
+  return {
+    /**
+     * Subscribe one live run. `entry` is the server's runs-Map record — title
+     * is read at SEND time (titles generate mid-run).
+     */
+    attach(orch, { runId, entry } = {}) {
+      const meta = () => ({
+        runId,
+        title: entry?.title || orch?.state?.title || '',
+        totalCostUsd: orch?.state?.totalCostUsd,
+        totalActiveMs: orch?.state?.totalActiveMs,
+      });
+      const guard = (fn) => (payload) => {
+        try { fn(payload); } catch (err) { logger('error', `chat notifier: ${err?.message || err}`); }
+      };
+
+      orch.on('question', guard((payload) => {
+        if (getPrefsSafe().notify.question === false) return;
+        deliver(renderQuestion(meta(), payload || {}));
+      }));
+
+      orch.on('error', guard((payload) => {
+        if (getPrefsSafe().notify.error === false) return;
+        deliver(renderError(meta(), payload || {}));
+      }));
+
+      orch.on('done', guard((payload) => {
+        const status = payload?.status || 'done';
+        if (status === 'error') return; // the richer 'error' event already went out
+        const prefs = getPrefsSafe().notify;
+        if (status === 'paused' ? prefs.paused === false : prefs.done === false) return;
+        deliver(renderDone(meta(), payload || {}));
+      }));
+
+      function getPrefsSafe() {
+        try { return getPrefs(); } catch { return { notify: {} }; }
+      }
+    },
+
+    /** The Test button / smoke path: send one message to one channel's
+     *  notifyChatIds directly (no prefs gating — an explicit user action). */
+    async sendTest(plugin, channelId, message) {
+      const entry = channelHost.list().find((e) => e.plugin === plugin && e.channelId === channelId);
+      if (!entry) throw new Error(`no such chat channel "${plugin}/${channelId}"`);
+      const chatIds = parseIdList(readPluginConfig(entry.plugin, entry.configSchema).notifyChatIds);
+      if (!chatIds.length) throw new Error('notifyChatIds is not configured for this channel');
+      const results = [];
+      for (const chatId of chatIds) {
+        try {
+          await channelHost.sendMessage({ plugin, channelId, chatId, message });
+          results.push({ chatId, ok: true });
+        } catch (err) {
+          results.push({ chatId, ok: false, error: { kind: err?.kind || 'plugin', message: err?.message || String(err) } });
+        }
+      }
+      return { ok: results.every((r) => r.ok), results };
+    },
+  };
+}

package/src/core/chat/parser.mjs

@@ -0,0 +1,30 @@
+// src/core/chat/parser.mjs
+// Chat command parser, ported verbatim from the pre-1.0
+// worca-ui/server/integrations/commands/parser.js. Strips bot @mentions
+// (anywhere in the text) and handles Telegram's /command@botname suffix.
+
+const MENTION_RE = /^@\S+$/i;
+
+// Allow `-` inside command names (namespaced commands); hyphens must not lead
+// or trail. Underscore-only commands still match.
+const COMMAND_RE = /^\/([a-z_][a-z0-9_-]*)(?:@\S+)?$/i;
+
+/**
+ * @param {string} text
+ * @returns {{ command: string, args: string[] } | null} null for non-commands
+ */
+export function parseCommand(text) {
+  if (!text || !text.trim()) return null;
+
+  const tokens = text.trim().split(/\s+/);
+  const filtered = tokens.filter((t) => !MENTION_RE.test(t));
+  if (filtered.length === 0) return null;
+
+  const match = COMMAND_RE.exec(filtered[0]);
+  if (!match) return null;
+
+  return {
+    command: match[1].toLowerCase(),
+    args: filtered.slice(1),
+  };
+}

package/src/core/chat/rate-limiter.mjs

@@ -0,0 +1,133 @@
+// src/core/chat/rate-limiter.mjs
+// Outbound delivery rate limiter, ported from pre-1.0
+// integrations/rate_limiter.js: token bucket + FIFO worker + 429 retry ladder
+// + ring buffer of recently sent messages. Policy limiting lives HOST-side
+// (design §4.5) — workers only surface platform 429s; this ladder retries them.
+// The only port deltas: injectable `now`, retry keyed on err.kind==='rate-limit'
+// (PluginOpError vocabulary) in addition to err.status===429, and logger
+// injection instead of console.warn.
+
+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;
+  }
+}
+
+const isRateLimited = (err) => err?.status === 429 || err?.kind === 'rate-limit';
+
+export function createRateLimiter({
+  ratePerMin = 20,
+  ringSize = 100,
+  _sleep = defaultSleep,
+  logger = () => {},
+} = {}) {
+  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 (isRateLimited(err)) {
+          if (attempt < BACKOFF_DELAYS.length) continue;
+          logger('warn', 'chat 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 {
+    /** Queue one message; resolves true (sent) / false (dropped after 429s). */
+    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/src/core/chat/redact.mjs

@@ -0,0 +1,27 @@
+// src/core/chat/redact.mjs
+// Secret scrubbing for every worker-originated string (log frames, status
+// details, send errors) BEFORE it reaches the host logger or the UI
+// (chat-connectivity-design.md §4.4). Ported from the pre-1.0
+// integrations/index.js redactSecrets, extended with generic Bearer/token
+// scrubs for the platforms added in 1.0 (Teams AAD tokens, app secrets).
+// Workers legitimately hold bot tokens; this is the belt-and-braces layer for
+// the strings they emit, not a substitute for not logging secrets.
+
+export function redactSecrets(input) {
+  return String(input)
+    // Telegram bot tokens (123456:ABC-...) — bare or inside api.telegram.org URLs
+    .replace(/bot\d+:[A-Za-z0-9_-]+/g, 'bot<redacted>')
+    .replace(/\b\d{6,}:[A-Za-z0-9_-]{30,}/g, '<redacted>')
+    // Slack incoming-webhook URLs + xox* OAuth tokens + xapp app tokens
+    .replace(/hooks\.slack\.com\/services\/T[A-Z0-9]+\/B[A-Z0-9]+\/[A-Za-z0-9]+/g, 'hooks.slack.com/services/<redacted>')
+    .replace(/xox[abeprs]-[A-Za-z0-9-]+/g, 'xox<redacted>')
+    .replace(/xapp-[A-Za-z0-9-]+/g, 'xapp-<redacted>')
+    // Discord webhook URLs + bot tokens (base64ish triplet)
+    .replace(/discord(?:app)?\.com\/api\/webhooks\/\d+\/[A-Za-z0-9_-]+/g, 'discord.com/api/webhooks/<redacted>')
+    .replace(/\b[\w-]{23,28}\.[\w-]{6,7}\.[\w-]{27,}\b/g, '<redacted>')
+    // Authorization header values and JWTs (Teams Bot Framework / AAD)
+    .replace(/Bearer\s+[A-Za-z0-9._~+/-]+=*/gi, 'Bearer <redacted>')
+    .replace(/\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b/g, '<redacted-jwt>')
+    // client_secret=... in URL-encoded bodies (AAD token endpoint)
+    .replace(/([?&]|\b)(client_secret|access_token|token)=[^&\s]+/gi, '$1$2=<redacted>');
+}

package/src/core/chat/renderers.mjs

@@ -0,0 +1,136 @@
+// src/core/chat/renderers.mjs
+// 1.0 orchestrator events -> NormalizedMessage (chat-connectivity-design.md
+// §4.5). Style/helpers ported from the pre-1.0 integrations/renderers.js
+// (markdown segments so each platform worker converts to its native format);
+// the event vocabulary is 1.0's: done {status: done|stopped|paused, reason},
+// error {message}, question {id, kind, questions, issues, recovery, agent}.
+//
+// The question renderer is the load-bearing one: it enumerates options with
+// ordinals and embeds the exact reply commands (/approve, /retry, /answer n…)
+// using the run-id wildcard-suffix convention the command router resolves.
+
+const md = (value) => ({ kind: 'markdown', value });
+
+export function fmtMs(ms) {
+  if (ms == null || !Number.isFinite(ms)) 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`;
+}
+
+export function fmtUsd(usd) {
+  if (usd == null || !Number.isFinite(Number(usd))) return null;
+  return `$${Number(usd).toFixed(2)}`;
+}
+
+function mdMsg(text, severity) {
+  return { title: null, body: [md(text)], severity };
+}
+
+/** Short wildcard reference the command router resolves: last 4 id chars. */
+export function runRef(runId) {
+  const id = String(runId || '');
+  return id.length > 4 ? `*${id.slice(-4)}` : id || 'run';
+}
+
+function head(icon, meta) {
+  const parts = [`${icon} **Run:** \`${runRef(meta.runId)}\``];
+  const title = String(meta.title || '').trim();
+  if (title) parts.push(`   **Title:** ${title.length > 60 ? `${title.slice(0, 60)}…` : title}`);
+  return parts;
+}
+
+const PAUSE_REASONS = {
+  cost_pipeline: 'pipeline cost limit reached',
+  cost_total: 'total cost limit reached',
+};
+
+/**
+ * done event: status done|stopped|paused (+reason for limit pauses).
+ * meta may carry {title, totalCostUsd, totalActiveMs} for the summary line.
+ */
+export function renderDone(meta, payload = {}) {
+  const status = payload.status || 'done';
+  if (status === 'paused') {
+    const reason = payload.reason ? (PAUSE_REASONS[payload.reason] || payload.reason) : null;
+    const parts = head('⏸', meta);
+    parts.push(`   **Status:** paused${reason ? ` — ${reason}` : ''}`);
+    parts.push(`   Resume from the worca-cc UI, or reply: /resume ${runRef(meta.runId)}`);
+    return mdMsg(parts.join('\n'), 'warning');
+  }
+  if (status === 'stopped') {
+    const parts = head('⏹', meta);
+    parts.push('   **Status:** stopped');
+    return mdMsg(parts.join('\n'), 'warning');
+  }
+  const parts = head('✅', meta);
+  parts.push('   **Status:** completed');
+  const dur = fmtMs(meta.totalActiveMs);
+  if (dur) parts.push(`   **Duration:** ${dur}`);
+  const cost = fmtUsd(meta.totalCostUsd);
+  if (cost) parts.push(`   **Cost:** ${cost}`);
+  return mdMsg(parts.join('\n'), 'success');
+}
+
+/** error event: {message}. A separate done{status:'error'} follows; the
+ *  notifier sends only this one (richer) for the failure. */
+export function renderError(meta, payload = {}) {
+  const parts = head('\u{1F534}', meta);
+  parts.push('   **Status:** failed');
+  const msg = String(payload.message || 'unknown error');
+  parts.push(`   **Error:** ${msg.length > 300 ? `${msg.slice(0, 300)}…` : msg}`);
+  return mdMsg(parts.join('\n'), 'error');
+}
+
+/**
+ * question event: {id, kind: clarify|questions|gate|recovery, questions,
+ * issues, recovery, agent}. The reply instructions match the command router:
+ *   gate/recovery -> /approve <ref> | /retry <ref>
+ *   clarify/questions -> /answer <ref> <n|text> [| …] (one answer per question:
+ *     an option number, or free text for questions without options)
+ */
+export function renderQuestion(meta, payload = {}) {
+  const ref = runRef(meta.runId);
+  const kind = payload.kind || 'questions';
+  const parts = head('❓', meta);
+
+  if (kind === 'gate' || kind === 'recovery') {
+    parts.push(`   **Status:** waiting for ${kind === 'gate' ? 'approval' : 'a recovery decision'}${payload.agent ? ` (${payload.agent})` : ''}`);
+    const issues = Array.isArray(payload.issues) ? payload.issues : [];
+    for (const i of issues.slice(0, 5)) {
+      const sev = i?.severity ? `[${i.severity}] ` : '';
+      const text = String(i?.summary || i?.message || i?.title || '').trim();
+      if (text) parts.push(`   • ${sev}${text.length > 120 ? `${text.slice(0, 120)}…` : text}`);
+    }
+    if (issues.length > 5) parts.push(`   • …and ${issues.length - 5} more`);
+    if (kind === 'recovery' && payload.recovery?.message) {
+      parts.push(`   **Cause:** ${String(payload.recovery.message).slice(0, 200)}`);
+    }
+    parts.push(kind === 'gate'
+      ? `   Reply: /approve ${ref} to continue · /retry ${ref} for another cycle`
+      : `   Reply: /approve ${ref} to retry · /abort ${ref} to abort`);
+    return mdMsg(parts.join('\n'), 'warning');
+  }
+
+  parts.push(`   **Status:** has questions${payload.agent ? ` from ${payload.agent}` : ''}`);
+  const questions = Array.isArray(payload.questions) ? payload.questions : [];
+  questions.forEach((q, qi) => {
+    parts.push(`   **Q${qi + 1}.** ${String(q?.question || q?.id || '').trim()}`);
+    (Array.isArray(q?.options) ? q.options : []).forEach((opt, oi) => {
+      parts.push(`      ${oi + 1}. ${String(opt).trim()}`);
+    });
+  });
+  const example = questions.map((q) => ((Array.isArray(q.options) && q.options.length) ? '1' : '<your answer>')).join(' | ') || '1';
+  parts.push(`   Reply: /answer ${ref} ${example}${questions.length > 1 ? '  (one answer per question, in order, separated by |)' : ''}`);
+  return mdMsg(parts.join('\n'), 'warning');
+}
+
+/** Canned message for the "Test" button / `worca plugin channel` smoke. */
+export function renderTest() {
+  return {
+    title: 'worca-cc test message',
+    body: [md('✅ Chat channel connectivity works. Notifications will appear here.')],
+    severity: 'info',
+  };
+}