@worca/app 1.3.0 → 1.4.0

package/src/core/bridge/translate/stream.mjs

@@ -0,0 +1,242 @@
+// src/core/bridge/translate/stream.mjs
+// OpenAI chat/completions stream chunks -> Anthropic Messages SSE events
+// (model-bridge-design.md §5.4/§5.5/§5.8). Pure state machine: feed parsed
+// chunk objects to `push`, call `finish` at end of stream; both return the
+// events to write, as `{event, data}` pairs. `serializeSse` renders them.
+//
+// Text streams live, one content block per contiguous run. Tool calls are
+// BUFFERED per tool_calls index and emitted as a complete block when the next
+// tool call (or text) begins, and at finish: Anthropic blocks are strictly
+// sequential and cannot be reopened, while upstreams may (rarely) interleave
+// argument deltas across indexes — buffering makes that case correct at the
+// cost of a tool block appearing a moment later than its first delta.
+
+import { randomBytes } from 'node:crypto';
+
+/** finish_reason -> stop_reason (§5.5). */
+export function mapStopReason(finish, { emitted = false } = {}) {
+  switch (finish) {
+    case 'stop': return 'end_turn';
+    case 'length': return 'max_tokens';
+    case 'tool_calls':
+    case 'function_call': return 'tool_use';
+    case 'content_filter': return 'end_turn';
+    default: return emitted ? 'end_turn' : null;
+  }
+}
+
+/** chat/completions usage -> Anthropic usage (§5.8). */
+export function mapUsage(usage) {
+  const u = usage && typeof usage === 'object' ? usage : {};
+  const prompt = Number(u.prompt_tokens) || 0;
+  const cached = Number(u.prompt_tokens_details && u.prompt_tokens_details.cached_tokens) || 0;
+  return {
+    input_tokens: Math.max(0, prompt - cached),
+    output_tokens: Number(u.completion_tokens) || 0,
+    cache_read_input_tokens: cached,
+    cache_creation_input_tokens: 0,
+  };
+}
+
+/** Whether a tool call's accumulated arguments are complete JSON ('' = no args). */
+export function parsesAsJson(s) {
+  if (typeof s !== 'string' || !s.trim()) return true;
+  try { JSON.parse(s); return true; } catch { return false; }
+}
+
+/** The text that replaces a tool call cut off by finish_reason `length`. */
+export function truncatedToolNote(name) {
+  return `[bridge: the ${name} call was cut off by the model's output or context limit before its arguments were complete, so it was not run. Split the work into smaller steps — e.g. write a large file in several shorter parts.]`;
+}
+
+export function newMessageId() { return `msg_bridge_${randomBytes(12).toString('hex')}`; }
+export function newToolUseId() { return `toolu_bridge_${randomBytes(12).toString('hex')}`; }
+
+export class ChatStreamTranslator {
+  /** @param {{model:string}} opts  the model name the CLI expects back (catalog id) */
+  constructor({ model } = {}) {
+    this.model = model || 'bridge';
+    this.id = newMessageId();
+    this.started = false;
+    this.nextIndex = 0;
+    this.textIndex = null;          // open text block index, or null
+    this.tools = new Map();         // tool_calls index -> {id, name, args, order}
+    this.toolOrder = [];
+    this.flushedTools = 0;          // how many of toolOrder have been emitted
+    this.finishReason = null;
+    this.usage = null;
+    this.emittedAny = false;
+    this.contentFilter = false;
+  }
+
+  _start() {
+    if (this.started) return [];
+    this.started = true;
+    return [{
+      event: 'message_start',
+      data: {
+        type: 'message_start',
+        message: {
+          id: this.id, type: 'message', role: 'assistant', model: this.model, content: [],
+          stop_reason: null, stop_sequence: null,
+          usage: { input_tokens: 0, output_tokens: 0, cache_read_input_tokens: 0, cache_creation_input_tokens: 0 },
+        },
+      },
+    }];
+  }
+
+  _closeText() {
+    if (this.textIndex === null) return [];
+    const i = this.textIndex;
+    this.textIndex = null;
+    return [{ event: 'content_block_stop', data: { type: 'content_block_stop', index: i } }];
+  }
+
+  /** Emit every buffered tool call not yet emitted (in first-seen order). */
+  _flushTools(upTo = this.toolOrder.length) {
+    const out = [];
+    while (this.flushedTools < upTo) {
+      const key = this.toolOrder[this.flushedTools++];
+      const t = this.tools.get(key);
+      const index = this.nextIndex++;
+      out.push({ event: 'content_block_start', data: { type: 'content_block_start', index, content_block: { type: 'tool_use', id: t.id, name: t.name, input: {} } } });
+      out.push({ event: 'content_block_delta', data: { type: 'content_block_delta', index, delta: { type: 'input_json_delta', partial_json: t.args || '{}' } } });
+      out.push({ event: 'content_block_stop', data: { type: 'content_block_stop', index } });
+      this.emittedAny = true;
+    }
+    return out;
+  }
+
+  /**
+   * Feed one parsed chunk object. Returns the SSE events to write.
+   * @param {object} chunk
+   */
+  push(chunk) {
+    const out = this._start();
+    if (!chunk || typeof chunk !== 'object') return out;
+    if (chunk.error) {
+      const msg = typeof chunk.error === 'string' ? chunk.error : (chunk.error.message || JSON.stringify(chunk.error));
+      out.push({ event: 'error', data: { type: 'error', error: { type: 'api_error', message: `upstream stream error: ${msg}` } } });
+      return out;
+    }
+    if (chunk.usage && typeof chunk.usage === 'object') this.usage = chunk.usage;
+    const choice = Array.isArray(chunk.choices) ? chunk.choices[0] : null;
+    if (!choice) return out;
+    const delta = choice.delta || {};
+
+    if (typeof delta.content === 'string' && delta.content.length) {
+      // Text after tool calls: the tools are complete — flush them first.
+      if (this.toolOrder.length > this.flushedTools) { out.push(...this._closeText(), ...this._flushTools()); }
+      if (this.textIndex === null) {
+        this.textIndex = this.nextIndex++;
+        out.push({ event: 'content_block_start', data: { type: 'content_block_start', index: this.textIndex, content_block: { type: 'text', text: '' } } });
+      }
+      out.push({ event: 'content_block_delta', data: { type: 'content_block_delta', index: this.textIndex, delta: { type: 'text_delta', text: delta.content } } });
+      this.emittedAny = true;
+    }
+
+    if (Array.isArray(delta.tool_calls)) {
+      for (const tc of delta.tool_calls) {
+        if (!tc || typeof tc !== 'object') continue;
+        const key = Number.isInteger(tc.index) ? tc.index : (tc.id || this.toolOrder.length);
+        let t = this.tools.get(key);
+        if (!t) {
+          // A new tool call: text before it is complete; earlier tool calls are complete.
+          out.push(...this._closeText());
+          out.push(...this._flushTools());
+          t = { id: tc.id || newToolUseId(), name: '', args: '' };
+          this.tools.set(key, t);
+          this.toolOrder.push(key);
+        } else if (tc.id && !t.id) t.id = tc.id;
+        const fn = tc.function || {};
+        if (typeof fn.name === 'string' && fn.name) t.name = t.name ? t.name : fn.name;
+        if (typeof fn.arguments === 'string') t.args += fn.arguments;
+      }
+    }
+
+    if (choice.finish_reason) {
+      this.finishReason = choice.finish_reason;
+      if (choice.finish_reason === 'content_filter') this.contentFilter = true;
+    }
+    return out;
+  }
+
+  /** End of stream: close blocks, emit message_delta + message_stop. */
+  finish() {
+    const out = this._start();
+    // Cut off mid tool call (finish_reason `length` — the output cap, or on a
+    // small local model the context window filling up): the last call's
+    // arguments are unterminated JSON. Forwarded, the CLI rejects it as an
+    // InputValidationError and the model retries the same oversized call; so
+    // drop it and say why, and the CLI's max_tokens recovery asks for smaller
+    // steps. Earlier calls were complete when the next one began.
+    let truncated = null;
+    if (this.finishReason === 'length' && this.toolOrder.length > this.flushedTools) {
+      const key = this.toolOrder[this.toolOrder.length - 1];
+      const t = this.tools.get(key);
+      if (!parsesAsJson(t.args)) {
+        this.toolOrder.pop();
+        this.tools.delete(key);
+        truncated = t.name || 'tool';
+      }
+    }
+    out.push(...this._flushTools());
+    if (truncated) {
+      if (this.textIndex === null) {
+        this.textIndex = this.nextIndex++;
+        out.push({ event: 'content_block_start', data: { type: 'content_block_start', index: this.textIndex, content_block: { type: 'text', text: '' } } });
+      }
+      out.push({ event: 'content_block_delta', data: { type: 'content_block_delta', index: this.textIndex, delta: { type: 'text_delta', text: truncatedToolNote(truncated) } } });
+      this.emittedAny = true;
+    }
+    out.push(...this._closeText());
+    const hadTools = this.toolOrder.length > 0;
+    let stop = mapStopReason(this.finishReason, { emitted: this.emittedAny });
+    if (stop === null) {
+      out.push({ event: 'error', data: { type: 'error', error: { type: 'api_error', message: 'upstream stream ended without content or finish_reason' } } });
+      return out;
+    }
+    if (hadTools && stop === 'end_turn') stop = 'tool_use';
+    out.push({ event: 'message_delta', data: { type: 'message_delta', delta: { stop_reason: stop, stop_sequence: null }, usage: mapUsage(this.usage) } });
+    out.push({ event: 'message_stop', data: { type: 'message_stop' } });
+    return out;
+  }
+}
+
+/** Render `{event, data}` pairs as SSE text. */
+export function serializeSse(events) {
+  let s = '';
+  for (const e of events) s += `event: ${e.event}\ndata: ${JSON.stringify(e.data)}\n\n`;
+  return s;
+}
+
+/**
+ * Incremental SSE `data:` parser for an upstream chat stream. Feed text
+ * chunks; get back the parsed JSON objects (the `[DONE]` sentinel ends the
+ * stream and sets `done`). Non-JSON data lines are skipped.
+ */
+export class SseDataParser {
+  constructor() { this.buf = ''; this.done = false; }
+  /** @param {string} text  @returns {object[]} */
+  feed(text) {
+    if (this.done) return [];
+    this.buf += text;
+    const out = [];
+    let idx;
+    while ((idx = this.buf.search(/\r?\n\r?\n/)) !== -1) {
+      const raw = this.buf.slice(0, idx);
+      this.buf = this.buf.slice(idx).replace(/^\r?\n\r?\n/, '');
+      const data = raw.split(/\r?\n/).filter((l) => l.startsWith('data:')).map((l) => l.slice(5).trim()).join('\n');
+      if (!data) continue;
+      if (data === '[DONE]') { this.done = true; break; }
+      try { out.push(JSON.parse(data)); } catch { /* skip non-JSON */ }
+    }
+    return out;
+  }
+  /** Drain a trailing event with no terminating blank line. */
+  end() {
+    if (this.done || !this.buf.trim()) return [];
+    const rest = this.buf; this.buf = '';
+    return this.feed(`${rest}\n\n`);
+  }
+}

package/src/core/bridge/upstream.mjs

@@ -0,0 +1,209 @@
+// src/core/bridge/upstream.mjs
+// One Messages request in, one upstream call out (model-bridge-design.md §5).
+// `handleMessages` is transport-agnostic: it takes the parsed body and a
+// writer for the reply so router.mjs (real http) and the tests (in-memory)
+// share every line of the forwarding, translation and error logic.
+
+import { toChatRequest } from './translate/request.mjs';
+import { ChatStreamTranslator, SseDataParser, serializeSse } from './translate/stream.mjs';
+import { toMessagesResponse } from './translate/response.mjs';
+import { mapUpstreamError, mapNetworkError, bridgeErrors, PAYLOAD_CEILING_BYTES } from './errors.mjs';
+import { copilotToken, invalidateCopilotToken, copilotApiHost, copilotHeaders, bodyHasImage, requestInitiator } from './providers/copilot.mjs';
+import { upstreamSettings, providerReadiness } from './registry.mjs';
+import { KeyedSemaphore } from './semaphore.mjs';
+import { recordBridgeCall, recordBridgeError } from './telemetry.mjs';
+
+export const semaphore = new KeyedSemaphore();
+const PING_INTERVAL_MS = 15_000;
+const warned = new Set();
+
+/** Once-per-process warning (dropped fields, queue notices). */
+function warnOnce(key, line, log) {
+  if (warned.has(key)) return;
+  warned.add(key);
+  (log || console.warn)(line);
+}
+export function _resetBridgeWarnings() { warned.clear(); }
+
+/**
+ * Resolve auth + URL + headers for an upstream call.
+ * @returns {Promise<{url:string, headers:object, provider:string, retryAuth?:() => Promise<object>}>}
+ */
+async function prepareUpstream(us, body, { fetch: f, requestHeaders }) {
+  if (us.provider === 'copilot') {
+    const initiator = requestInitiator(body);
+    const vision = bodyHasImage(body);
+    const build = async (force) => {
+      const { token, apiHost } = await copilotToken(us.githubToken, { fetch: f, force });
+      const host = apiHost || copilotApiHost(us.accountType);
+      const path = us.api === 'anthropic' ? '/v1/messages' : '/chat/completions';
+      const headers = { ...copilotHeaders(token, { vision, initiator }), ...us.headers };
+      if (us.api === 'anthropic') {
+        headers['anthropic-version'] = requestHeaders['anthropic-version'] || '2023-06-01';
+        if (requestHeaders['anthropic-beta']) headers['anthropic-beta'] = requestHeaders['anthropic-beta'];
+      }
+      return { url: `${host}${path}`, headers, initiator };
+    };
+    const first = await build(false);
+    return { ...first, provider: 'copilot', retryAuth: () => { invalidateCopilotToken(us.githubToken); return build(true); } };
+  }
+  const initiator = requestInitiator(body);
+  if (us.api === 'anthropic') {
+    const base = (us.baseUrl || 'https://api.anthropic.com').replace(/\/+$/, '');
+    const url = /\/v1$/.test(base) ? `${base}/messages` : `${base}/v1/messages`;
+    const headers = {
+      'content-type': 'application/json',
+      'x-api-key': us.apiKey,
+      'anthropic-version': requestHeaders['anthropic-version'] || '2023-06-01',
+      ...(requestHeaders['anthropic-beta'] ? { 'anthropic-beta': requestHeaders['anthropic-beta'] } : {}),
+      ...us.headers,
+    };
+    return { url, headers, provider: us.provider, initiator };
+  }
+  const base = (us.baseUrl || 'https://api.openai.com/v1').replace(/\/+$/, '');
+  return {
+    url: `${base}/chat/completions`,
+    headers: { 'content-type': 'application/json', ...(us.apiKey ? { authorization: `Bearer ${us.apiKey}` } : {}), ...us.headers },
+    provider: us.provider,
+    initiator,
+  };
+}
+
+/**
+ * Serve one /v1/messages request.
+ * @param {object} args
+ * @param {object} args.entry   findBridgedEntry() result
+ * @param {object} args.body    parsed Messages request
+ * @param {Record<string,string>} args.requestHeaders  lower-cased incoming headers
+ * @param {string} [args.tag]   telemetry tag (execution id)
+ * @param {AbortSignal} [args.signal]  aborts when the CLI disconnects
+ * @param {typeof fetch} [args.fetch]
+ * @param {(line:string)=>void} [args.log]
+ * @param {object} reply  { status(code, headers), write(chunk), end(), json(status, obj, headers?) }
+ */
+export async function handleMessages({ entry, body, requestHeaders = {}, tag = '', signal, fetch: f = globalThis.fetch, log }, reply) {
+  const upstream = entry.upstream;
+  const ready = providerReadiness(upstream);
+  if (!ready.ok) {
+    const e = ready.reason === 'terms' ? bridgeErrors.termsNotAcknowledged(upstream.provider) : bridgeErrors.notSignedIn(upstream.provider, ready.message.split('— ')[1] || ready.message);
+    recordBridgeError({ tag, catalogId: entry.id, provider: upstream.provider, status: e.status, message: e.body.error.message });
+    return reply.json(e.status, e.body);
+  }
+  const us = upstreamSettings(upstream);
+
+  // Body → upstream body.
+  let outBody;
+  if (us.api === 'anthropic') {
+    outBody = { ...body, model: us.model };
+  } else {
+    const t = toChatRequest(body, { upstreamModel: us.model, capabilities: us.capabilities });
+    if (t.error) {
+      const e = bridgeErrors.unsupported(t.error.message);
+      recordBridgeError({ tag, catalogId: entry.id, provider: us.provider, status: e.status, message: e.body.error.message });
+      return reply.json(e.status, e.body);
+    }
+    for (const w of t.warnings) {
+      const line = w === 'max_tokens clamped'
+        ? 'max_tokens clamped to the model\'s output limit'
+        : `${w} has no chat/completions equivalent — dropped`;
+      warnOnce(`${entry.id}:${w}`, `[worca] bridge: model ${JSON.stringify(entry.id)}: ${line}`, log);
+    }
+    outBody = t.body;
+  }
+  const payload = JSON.stringify(outBody);
+  if (Buffer.byteLength(payload) > PAYLOAD_CEILING_BYTES) {
+    const e = bridgeErrors.tooLarge();
+    return reply.json(e.status, e.body);
+  }
+
+  // Concurrency cap (§7.4).
+  if (semaphore.active(us.provider) >= us.maxConcurrent) {
+    warnOnce(`queue:${us.provider}:${tag}`, `[worca] bridge: requests queued for ${us.provider} (cap ${us.maxConcurrent}) — raise it under Settings › Providers if this is slow`, log);
+  }
+  let release;
+  try {
+    release = await semaphore.acquire(us.provider, us.maxConcurrent, { signal });
+  } catch {
+    return reply.end();  // the CLI went away while waiting
+  }
+
+  try {
+    let prep;
+    try {
+      prep = await prepareUpstream(us, body, { fetch: f, requestHeaders });
+    } catch (err) {
+      const status = err && err.code === 'AUTH' ? 401 : 502;
+      const e = status === 401
+        ? bridgeErrors.notSignedIn(us.provider, err.message)
+        : mapNetworkError(err, { provider: us.provider });
+      recordBridgeError({ tag, catalogId: entry.id, provider: us.provider, status: e.status, message: e.body.error.message });
+      return reply.json(e.status, e.body);
+    }
+    recordBridgeCall({ tag, catalogId: entry.id, provider: us.provider, api: us.api, initiator: prep.initiator });
+
+    const doFetch = (p) => f(p.url, { method: 'POST', headers: p.headers, body: payload, signal });
+    let res;
+    try {
+      res = await doFetch(prep);
+      if (res.status === 401 && prep.retryAuth) {
+        const again = await prep.retryAuth();
+        res = await doFetch(again);
+      }
+    } catch (err) {
+      if (signal && signal.aborted) return reply.end();
+      const e = mapNetworkError(err, { provider: us.provider });
+      recordBridgeError({ tag, catalogId: entry.id, provider: us.provider, status: e.status, message: e.body.error.message });
+      return reply.json(e.status, e.body);
+    }
+
+    if (!res.ok) {
+      const text = await res.text().catch(() => '');
+      const e = mapUpstreamError(res.status, text, { provider: us.provider, retryAfter: res.headers.get('retry-after') });
+      recordBridgeError({ tag, catalogId: entry.id, provider: us.provider, status: res.status, message: e.body.error.message });
+      if (log) log(`[worca] bridge: ${us.provider} answered ${res.status} for ${JSON.stringify(entry.id)}: ${e.body.error.message}`);
+      return reply.json(e.status, e.body, e.headers);
+    }
+
+    const streaming = body.stream === true;
+    if (us.api === 'anthropic') {
+      // Byte passthrough: the SSE stream (or JSON body) is the CLI's own dialect.
+      const ct = res.headers.get('content-type') || (streaming ? 'text/event-stream' : 'application/json');
+      reply.status(200, { 'content-type': ct, 'cache-control': 'no-cache' });
+      if (!res.body) return reply.end();
+      for await (const chunk of res.body) reply.write(chunk);
+      return reply.end();
+    }
+
+    if (!streaming) {
+      const j = await res.json();
+      return reply.json(200, toMessagesResponse(j, { model: entry.id }));
+    }
+
+    reply.status(200, { 'content-type': 'text/event-stream', 'cache-control': 'no-cache' });
+    const translator = new ChatStreamTranslator({ model: entry.id });
+    const parser = new SseDataParser();
+    const decoder = new TextDecoder();
+    let ping = setInterval(() => reply.write('event: ping\ndata: {"type":"ping"}\n\n'), PING_INTERVAL_MS);
+    if (ping.unref) ping.unref();
+    const bump = () => { clearInterval(ping); ping = setInterval(() => reply.write('event: ping\ndata: {"type":"ping"}\n\n'), PING_INTERVAL_MS); if (ping.unref) ping.unref(); };
+    try {
+      if (res.body) {
+        for await (const chunk of res.body) {
+          const text = decoder.decode(chunk, { stream: true });
+          for (const obj of parser.feed(text)) {
+            const events = translator.push(obj);
+            if (events.length) { reply.write(serializeSse(events)); bump(); }
+          }
+          if (parser.done) break;
+        }
+        for (const obj of parser.end()) reply.write(serializeSse(translator.push(obj)));
+      }
+      reply.write(serializeSse(translator.finish()));
+    } finally {
+      clearInterval(ping);
+    }
+    return reply.end();
+  } finally {
+    release();
+  }
+}

package/src/core/chat/command-router.mjs

@@ -14,6 +14,7 @@ import { parseCommand } from './parser.mjs';
 import { BOOKEND_EXECUTION_IDS } from '../../shared/graph/constants.mjs';
 import { createAllowlistGuard, parseIdList } from './allowlist.mjs';
 import { runRef, fmtUsd, fmtMs } from './renderers.mjs';
+import { promptFields, parseAnswerLine } from '../../shared/forms/project.mjs';
 import { giveUpOption, describePauseReason, pauseConsequences } from '../failure-policy.mjs';
 
 const md = (value) => ({ kind: 'markdown', value });
@@ -47,6 +48,7 @@ const HELP_TEXT = [
   '`/approve [*ref]` — continue past a gate · `/retry [*ref]` — another cycle',
   '`/abort [*ref]` — give up on a recovery prompt (pauses the run; nothing is discarded)',
   '`/answer [*ref] <n|text> [| …]` — answer clarify questions (option number, or text for free-text)',
+  '`/answer [*ref] field=value [| field2=a,b]` — answer a form (escape a literal `|`, `,`, `=` or `:` with `\\`)',
   '`/projects` · `/use <name>` — scope commands to one project',
   '`/mute 30m|2h|1d` · `/unmute` — silence notifications for this chat',
   '`/whoami` · `/help`',
@@ -106,7 +108,8 @@ export function lastPathSegment(p) {
  * @param {{actions:object, chatContext:object, logger?:(l:string,m:string)=>void}} deps
  * actions: listRuns(), runState(runId), pendingQuestion(runId),
  *          answer(runId, id, payload), stop(runId), pause(runId),
- *          resume(pipelineId), history({limit}), listProjects()
+ *          resume(pipelineId), history({limit}), listProjects(),
+ *          listScheduled?() -> [{id, title, runAt, status, projectDir, workspaceName?}] (optional)
  */
 export function createCommandRouter({ actions, chatContext, logger = () => {} }) {
   const projectOf = (chatKey) => chatContext.get(chatKey).active_project;
@@ -152,8 +155,19 @@ export function createCommandRouter({ actions, chatContext, logger = () => {} })
 
     runs: async ({ chatKey }) => {
       const live = scopedRuns(chatKey);
-      if (!live.length) return reply('No live runs. `/last` shows the latest finished pipeline.');
-      return reply(['**Live runs:**', ...live.map(runLine)].join('\n'));
+      // Scheduled runs (tickets, not pipelines): the next few, scoped like the live list.
+      const scope = projectOf(chatKey);
+      let soon = [];
+      try {
+        soon = (typeof actions.listScheduled === 'function' ? actions.listScheduled() : [])
+          .filter((t) => !scope || lastPathSegment(t.projectDir) === scope)
+          .slice(0, 5);
+      } catch { soon = []; }
+      const sched = soon.map((t) => `\u{1F552} ${t.status === 'missed' ? '**missed** · ' : ''}${t.title || 'Scheduled run'} · ${t.when || t.runAt}`);
+      if (!live.length && !sched.length) return reply('No live runs. `/last` shows the latest finished pipeline.');
+      const lines = live.length ? ['**Live runs:**', ...live.map(runLine)] : ['No live runs.'];
+      if (sched.length) lines.push('', '**Scheduled:**', ...sched);
+      return reply(lines.join('\n'));
     },
 
     last: async () => {
@@ -197,7 +211,11 @@ export function createCommandRouter({ actions, chatContext, logger = () => {} })
         if (cost) lines.push(`   **Cost:** ${cost}`);
       }
       const pq = actions.pendingQuestion(r.runId);
-      if (pq) lines.push(`   ❓ waiting on you — \`/approve ${runRef(r.runId)}\` or \`/answer ${runRef(r.runId)} <n>\``);
+      if (pq) {
+        lines.push(pq.kind === 'form'
+          ? `   ❓ waiting on the \`${pq.form}\` form — \`/answer ${runRef(r.runId)} <field>=<value>\``
+          : `   ❓ waiting on you — \`/approve ${runRef(r.runId)}\` or \`/answer ${runRef(r.runId)} <n>\``);
+      }
       return reply(lines.join('\n'));
     },
 
@@ -250,6 +268,42 @@ export function createCommandRouter({ actions, chatContext, logger = () => {} })
       if (t.error) return t.error;
       const pq = actions.pendingQuestion(t.run.runId);
       if (!pq) return reply(`\`${runRef(t.run.runId)}\` is not waiting on a question.`, 'warning');
+      const formRef = runRef(t.run.runId);
+      if (pq.kind === 'form') {
+        // Spec §8: `/answer <ref> field=value | field2=a,b`. The grammar itself —
+        // escapes, type-driven comma splitting, `id:verdict[:note]` for a
+        // review-list, the bare positional — is P1's parseAnswerLine (rulings X7,
+        // X8). What lives here is the ref, the refusal, the usage line and the
+        // gate-3 reply. Gate 3 THROWS INVALID_ANSWER (X2) and leaves the ask open.
+        if (pq.surface === 'web') {
+          return reply(`\`${formRef}\` is waiting on the \`${pq.form}\` form, which is answered in the worca web UI.`, 'warning');
+        }
+        const fields = promptFields(pq);
+        const hasRefArg = !!(args[0] && args[0].startsWith('*'));
+        const line = (hasRefArg ? args.slice(1) : args).join(' ').trim();
+        const example = fields.filter((f) => !f.when).slice(0, 3)
+          .map((f) => `${f.field}=${f.type === 'array' ? '<a,b>' : '<value>'}`).join(' | ')
+          || '<field>=<value>';
+        const usage = () => reply(
+          `Reply: \`/answer ${formRef} ${example}\`\nSeparate fields with \`|\`, list values with \`,\`, escape a literal \`|\`, \`,\`, \`=\` or \`:\` with \`\\\`.`,
+          'warning');
+        if (!line) return usage();
+        const parsed = parseAnswerLine(line, pq, fields.length === 1 ? { bareField: fields[0].field } : {});
+        if (parsed.errors.length) {
+          return reply(['Could not read that answer:',
+            ...parsed.errors.map((e) => `• ${e.path ? `\`${e.path}\`: ` : ''}${e.message}`),
+            '', `Reply: \`/answer ${formRef} ${example}\``].join('\n'), 'warning');
+        }
+        try {
+          await actions.answer(t.run.runId, pq.id, { values: parsed.values });
+        } catch (err) {
+          if (!err || err.code !== 'INVALID_ANSWER') throw err;   // the handler's catch owns everything else
+          return reply([`\`${formRef}\` — that answer was rejected:`,
+            ...(Array.isArray(err.errors) ? err.errors : []).map((e) => `• ${e.path ? `\`${e.path}\`: ` : ''}${e.message}`),
+            '', 'The question is still open.'].join('\n'), 'warning');
+        }
+        return reply(`✅ Answered the \`${pq.form}\` form on \`${formRef}\`.`, 'success');
+      }
       if (pq.kind !== 'clarify' && pq.kind !== 'questions') {
         return reply(`\`${runRef(t.run.runId)}\` is waiting on ${pq.kind} — use \`/approve\` or \`/retry\`.`, 'warning');
       }

package/src/core/chat/notifier.mjs

@@ -13,7 +13,7 @@
 import { readPluginConfig } from '../plugin-config.mjs';
 import { parseIdList } from './allowlist.mjs';
 import { createRateLimiter } from './rate-limiter.mjs';
-import { renderDone, renderError, renderQuestion } from './renderers.mjs';
+import { renderDone, renderError, renderQuestion, renderSchedule } from './renderers.mjs';
 import { pauseConsequences } from '../failure-policy.mjs';
 
 /**
@@ -103,6 +103,19 @@ export function createNotifier({ channelHost, getPrefs, chatContext, logger = ()
       }
     },
 
+    /**
+     * A scheduled-run notification. Run outcomes are skipped: the fired run's own
+     * done/error events already reached chat through attach().
+     */
+    notifySchedule(notification) {
+      try {
+        if (!notification || ['completed', 'run_error', 'run_paused', 'retrying'].includes(notification.kind)) return;
+        let prefs; try { prefs = getPrefs(); } catch { prefs = { notify: {} }; }
+        if (prefs.notify?.schedule === false) return;
+        deliver(renderSchedule(notification));
+      } catch (err) { logger('error', `chat notifier: ${err?.message || err}`); }
+    },
+
     /** 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) {

package/src/core/chat/renderers.mjs

@@ -10,6 +10,8 @@
 // using the run-id wildcard-suffix convention the command router resolves.
 
 import { pauseConsequences, describePauseReason, giveUpOption } from '../failure-policy.mjs';
+import { projectForm } from '../../shared/forms/project.mjs';
+import { CHAT_PROJECTION_MAX } from '../ask-projection.mjs';
 
 const md = (value) => ({ kind: 'markdown', value });
 
@@ -120,6 +122,27 @@ export function renderQuestion(meta, payload = {}) {
     return mdMsg(parts.join('\n'), 'warning');
   }
 
+  if (kind === 'form') {
+    // A form ask (spec §8). The projection is P1's — display widgets as text, files
+    // as `rel (mime, size)` — capped so one message fits the tightest shipped
+    // platform (Discord: 2000 chars); the cap drops display text only and never the
+    // prompts or the reply command. A surface:'web' form stays OPEN here: a chat run
+    // lives in ui/server.mjs's runs Map, so a browser really can answer it.
+    parts.push(`   **Status:** waiting on a form${payload.agent ? ` from ${payload.agent}` : ''}`);
+    const webOnly = payload.surface === 'web';
+    let projection;
+    try {
+      projection = projectForm(payload, { ...(webOnly ? {} : { ref }), maxChars: CHAT_PROJECTION_MAX });
+    } catch {
+      // A junk envelope must still NOTIFY — the notifier's guard would otherwise
+      // swallow the throw and the user would never learn a run is waiting.
+      projection = `${String(payload.title || payload.form || 'form')}${payload.agent ? ` — ${payload.agent}` : ''}`;
+    }
+    for (const line of projection.split('\n')) parts.push(line ? `   ${line}` : '');
+    if (webOnly) parts.push('   Answer this form in the worca web UI.');
+    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) => {
@@ -134,6 +157,18 @@ export function renderQuestion(meta, payload = {}) {
 }
 
 /** Canned message for the "Test" button / `worca plugin channel` smoke. */
+/**
+ * A scheduled-run notification (src/core/notifications.mjs row). Run OUTCOMES are
+ * not rendered here — the run's own done/error events already went out.
+ */
+export function renderSchedule(n = {}) {
+  const icon = n.severity === 'info' ? '\u{1F552}' : '\u{26A0}\u{FE0F}';
+  const title = String(n.title || 'Scheduled run').trim();
+  const name = title.length > 60 ? `${title.slice(0, 60)}…` : title;
+  const msg = String(n.message || '');
+  return mdMsg(`${icon} **Schedule:** ${name}\n   ${msg.length > 300 ? `${msg.slice(0, 300)}…` : msg}`, n.severity === 'info' ? 'info' : 'warning');
+}
+
 export function renderTest() {
   return {
     title: 'worca-cc test message',