@milpa/comal 0.2.1 → 0.2.3

package/src/provider.mjs

@@ -3,6 +3,7 @@ import { normalizeUsage, bindUsageAccounting, accountingIdentity } from './usage
 import { setTimeout as delay } from 'node:timers/promises';
 import { visionSettings } from './vision.mjs';
 import { normalizeEffort, providerEffortWire } from './model-controls.mjs';
+import { modelDeadline, modelTimingSettings } from './model-deadline.mjs';
 
 export function mergeMessages(messages) {
   const merged = [];
@@ -62,37 +63,164 @@ function truncationDetails(content = []) {
     ...(last?.type === 'tool_use' && typeof last.name === 'string' && last.name ? { tool_name: last.name } : {}) };
 }
 
-function validateMessage(message) {
+const clip = (value, max = 300) => typeof value === 'string' ? (value.length > max ? value.slice(0, max) + '…' : value) : undefined;
+
+// Forma del request sin contenido (roles, tipos de bloque, breakpoints) para
+// diagnosticar un 400. Nunca cabeceras, texto ni argumentos.
+export function requestShape(wire = {}) {
+  const marks = blocks => Array.isArray(blocks) ? blocks.filter(block => block?.cache_control).length : 0;
+  const describe = block => `${block?.type}${block?.cache_control ? '*' : ''}${block?.type === 'thinking' ? (block.signature ? '+sig' : '-sig') : ''}${block?.type === 'text' && !block.text ? '(empty)' : ''}`;
+  const messages = (wire.messages || []).map(message => `${message.role?.[0]}:${Array.isArray(message.content) ? message.content.map(describe).join(',') : 'string'}`);
+  return { cache_breakpoints: marks(wire.tools) + marks(Array.isArray(wire.system) ? wire.system : []) + (wire.messages || []).reduce((sum, message) => sum + marks(message.content), 0),
+    messages: messages.length > 24 ? [...messages.slice(0, 4), `…${messages.length - 14} more…`, ...messages.slice(-10)] : messages };
+}
+
+// Conserva el cuerpo de error de la API (status, error.type, error.message) en
+// vez de un mensaje genérico. Las cabeceras del request nunca se registran.
+export async function providerHttpError(response, label = 'Anthropic', wire) {
+  let body = null;
+  try { const text = await response.text(); try { body = JSON.parse(text); } catch { body = { error: { type: 'non_json_body', message: clip(text, 200) } }; } } catch {}
+  const errorType = typeof body?.error?.type === 'string' ? body.error.type : 'unknown', apiMessage = clip(body?.error?.message) || '';
+  const requestId = response.headers?.get?.('request-id') || (typeof body?.request_id === 'string' ? body.request_id : null);
+  return Object.assign(new Error(`${label} HTTP ${response.status} ${errorType}: ${apiMessage || 'no message'}`), { code: 'PROVIDER_HTTP_ERROR', status: response.status,
+    details: { status: response.status, error_type: errorType, error_message: apiMessage, ...(requestId ? { request_id: clip(requestId, 80) } : {}), ...(wire ? { request_shape: requestShape(wire) } : {}) } });
+}
+
+function invalidToolCall(reason, index, block, message, trace) {
+  const name = typeof block?.name === 'string' ? clip(block.name, 64) : undefined;
+  return Object.assign(new Error(`Invalid tool call: block ${index}${name ? ` (${name})` : ''} ${reason}.`), { code: 'TOOL_CALL_INVALID', usage: message.usage, usage_accounting: normalizeUsage('anthropic', message.usage),
+    details: { block_index: index, block_type: block?.type, ...(name ? { tool_name: name } : {}), reason, ...(block?.truncated_input_chars !== undefined ? { input_chars: block.truncated_input_chars } : {}),
+      ...(block?.input_parse_error ? { parse_error: block.input_parse_error } : {}), stop_reason: message.stop_reason, ...(trace ? { stream_blocks: trace } : {}) } });
+}
+
+function validateMessage(message, trace) {
   if (!message || !Array.isArray(message.content) || !message.stop_reason) throw new Error('Incomplete model response.');
   if(message.stop_reason==='max_tokens')throw Object.assign(new Error('Anthropic response truncated; no tools were executed.'),{code:'OUTPUT_LENGTH',usage:message.usage,usage_accounting:normalizeUsage('anthropic',message.usage),details:truncationDetails(message.content)});
   const ids = new Set();
-  for (const block of message.content) {
+  for (const [index, block] of message.content.entries()) {
     if (!block || typeof block.type !== 'string') throw new Error('Invalid content block.');
     if (block.type === 'tool_use') {
-      if (typeof block.id !== 'string' || !block.id || ids.has(block.id) || typeof block.name !== 'string' || !block.input || typeof block.input !== 'object' || Array.isArray(block.input)) throw new Error('Invalid tool call.');
+      const reason = typeof block.id !== 'string' || !block.id ? 'has no id' : ids.has(block.id) ? 'repeats an id' : typeof block.name !== 'string' || !block.name ? 'has no name'
+        : block.input_parse_error ? 'has unparseable input JSON' : !block.input || typeof block.input !== 'object' || Array.isArray(block.input) ? `has ${Array.isArray(block.input) ? 'an array' : block.input === null ? 'null' : typeof block.input} input` : null;
+      if (reason) throw invalidToolCall(reason, index, block, message, trace);
       ids.add(block.id);
     }
   }
   return message;
 }
 
+// Prompt caching explícito (válido en todos los modelos Claude): tres breakpoints
+// como máximo, de lo más estable a lo más reciente. 1) la última herramienta
+// (caché de tools), 2) el system (tools+system), 3) el último bloque cacheable
+// del último mensaje (prefijo completo de la conversación). El turno siguiente
+// lee hasta el breakpoint previo y escribe sólo lo nuevo. Bloques thinking no
+// admiten cache_control; se busca hacia atrás el último que sí.
+export const adaptiveThinkingModel = model => /^claude-(?:opus|sonnet|haiku)-5(?:[-.]|$)/.test(model || '');
+// Modelos cuyos clasificadores enrutan a un fallback del lado del servidor por
+// categoría de rechazo (forma "default"). Sólo hacia api.anthropic.com.
+const FALLBACK_MODELS = /^claude-(?:opus-5-5|sonnet-5-5|opus-5|fable-5-1)$/;
+export const fallbackSupportedModel = model => FALLBACK_MODELS.test(model || '');
+export function normalizeFallbackSetting(value) {
+  const mode = String(value ?? 'default');
+  if (mode !== 'default' && mode !== 'off') throw new Error('--anthropic-fallback must be "default" or "off".');
+  return mode;
+}
+// Rechazo del clasificador: HTTP 200 con stop_reason "refusal". Se ramifica por
+// stop_reason, nunca por stop_details (puede ser null); explanation no está garantizado.
+export function refusalInfo(message) {
+  if (!message || message.stop_reason !== 'refusal') return null;
+  const details = message.stop_details && typeof message.stop_details === 'object' ? message.stop_details : null;
+  return { category: typeof details?.category === 'string' ? details.category : null, explanation: typeof details?.explanation === 'string' ? details.explanation : null };
+}
+// La señal de "quién respondió" es un fallback_message en usage.iterations, no el
+// bloque (los turnos pegajosos no traen bloque). El model de nivel superior nombra
+// al modelo que produjo el mensaje.
+export function fallbackServed(message) {
+  const iterations = Array.isArray(message?.usage?.iterations) ? message.usage.iterations : [];
+  if (!iterations.some(entry => entry?.type === 'fallback_message')) return null;
+  const switches = Array.isArray(message?.content) ? message.content.filter(block => block?.type === 'fallback') : [];
+  return { served_by: message.model || null, switches: switches.map(block => ({ from: block.from?.model || null, to: block.to?.model || null })) };
+}
+// Reenvío de un turno con fallback a mitad de salida: se omiten los bloques
+// thinking/redacted_thinking/tool_use ANTERIORES al último bloque fallback; el
+// texto y todo lo posterior al límite viajan normal. El bloque fallback es una
+// marca de auditoría ignorada (se conserva). Determinista por contenido: la
+// historia sigue siendo append-only.
+export function echoFallbackContent(content) {
+  if (!Array.isArray(content)) return content;
+  let boundary = -1;
+  content.forEach((block, index) => { if (block?.type === 'fallback') boundary = index; });
+  if (boundary < 0) return content;
+  return content.filter((block, index) => !(index < boundary && (block?.type === 'thinking' || block?.type === 'redacted_thinking' || block?.type === 'tool_use')));
+}
+// Un rechazo termina como rechazo, no como éxito vacío. Un fallback que respondió
+// se marca para que el libro, el timing y la contabilidad lo vean.
+export function annotateOutcome(accounted, message, onText) {
+  const refusal = refusalInfo(message);
+  const served = fallbackServed(message);
+  if (refusal) { accounted.refusal = { ...refusal, fallback_ran: Boolean(served), served_model: message.model || null }; return accounted; }
+  if (served) accounted.fallback = served;
+  if (onText) for (const block of accounted.content || []) if (block.type === 'text') onText(block.text);
+  return accounted;
+}
+const CACHE = Object.freeze({ type: 'ephemeral' });
+const CACHEABLE = new Set(['text', 'image', 'tool_use', 'tool_result', 'document']);
+// Los cache_control que traiga el llamador se descartan (también dentro de un
+// tool_result): la API rechaza más de 4 breakpoints, y aquí se ponen 3 exactos.
+// cache_control no es contenido; quitarlo o moverlo no edita bloques anteriores.
+const uncached = block => {
+  if (!block || typeof block !== 'object') return block;
+  const { cache_control: ignored, ...rest } = block;
+  return Array.isArray(rest.content) ? { ...rest, content: rest.content.map(uncached) } : rest;
+};
+export function withCacheBreakpoints({ system, tools = [], messages = [] }) {
+  const plainTools = tools.map(uncached);
+  const cachedTools = plainTools.length ? [...plainTools.slice(0, -1), { ...plainTools.at(-1), cache_control: CACHE }] : plainTools;
+  const plainSystem = Array.isArray(system) ? system.map(uncached) : system;
+  const cachedSystem = typeof system === 'string' && system ? [{ type: 'text', text: system, cache_control: CACHE }]
+    : Array.isArray(plainSystem) && plainSystem.length ? [...plainSystem.slice(0, -1), { ...plainSystem.at(-1), cache_control: CACHE }] : plainSystem;
+  const cachedMessages = messages.map(message => ({ ...message, content: Array.isArray(message.content) ? message.content.map(uncached) : message.content }));
+  for (let m = cachedMessages.length - 1; m >= 0; m--) {
+    const content = cachedMessages[m].content;
+    if (!Array.isArray(content)) continue;
+    const index = content.findLastIndex(block => CACHEABLE.has(block?.type) && !(block.type === 'text' && !block.text));
+    if (index >= 0) { content[index] = { ...content[index], cache_control: CACHE }; break; }
+  }
+  return { system: cachedSystem, tools: cachedTools, messages: cachedMessages };
+}
+
 export class AnthropicProvider {
-  constructor({ apiKey = process.env.ANTHROPIC_API_KEY, baseURL = process.env.ANTHROPIC_BASE_URL || 'https://api.anthropic.com', model = process.env.COMAL_MODEL || process.env.HARNESS_MODEL || 'claude-sonnet-4-6', maxTokens = 4096, effort = 'auto', capabilitiesConfigured = {}, vision = 'auto', imageTokens = 4096, timeoutMs = 90000, fetchImpl = fetch } = {}) {
+  constructor({ apiKey = process.env.ANTHROPIC_API_KEY, baseURL = process.env.ANTHROPIC_BASE_URL || 'https://api.anthropic.com', model = process.env.COMAL_MODEL || process.env.HARNESS_MODEL || 'claude-sonnet-5-5', maxTokens = 8192, effort = 'auto', capabilitiesConfigured = {}, vision = 'auto', imageTokens = 4096, timeoutMs, idleTimeoutMs, fallback = 'default', fetchImpl = fetch, promptCaching, thinkingDisplay = 'summarized' } = {}) {
     if (!apiKey) throw new Error('Set ANTHROPIC_API_KEY or use --demo to try without credentials.');
     const url = new URL(baseURL.replace(/\/$/, '') + '/v1/messages');
     if (url.protocol !== 'https:' && !(url.protocol === 'http:' && ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname))) throw new Error('The provider requires HTTPS; HTTP is allowed only on localhost.');
     if (url.username || url.password || url.search || url.hash) throw new Error('Invalid provider URL.');
     this.protocol = 'anthropic'; this.effort = normalizeEffort(effort); this.capabilitiesConfigured = { ...capabilitiesConfigured }; this.configuredCapabilities = this.capabilitiesConfigured;
-    this.apiKey = apiKey; this.url = url; this.model = model; this.maxTokens = maxTokens; this.timeoutMs = timeoutMs; this.fetch = fetchImpl;
+    // Prompt caching por omisión sólo hacia la API de Anthropic: otros endpoints
+    // compatibles (MiniMax) pueden rechazar cache_control. promptCaching:true lo fuerza.
+    this.promptCaching = promptCaching ?? url.hostname === 'api.anthropic.com';
+    // Claude 5.x piensa de forma adaptativa y por omisión omite el texto del
+    // razonamiento (display: omitted). Se pide el resumen para que el libro y el
+    // progreso lo vean; nunca thinking.disabled ni budget_tokens.
+    this.thinkingDisplay = thinkingDisplay;
+    this.apiKey = apiKey; this.url = url; this.model = model; this.maxTokens = maxTokens; this.fetch = fetchImpl;
+    // Idle + total timeouts (shared with the other providers): abort only when no
+    // SSE bytes arrive for idleTimeoutMs, within a generous overall cap. Replaces
+    // the old fixed 90 s whole-request timeout that killed long high-effort turns.
+    Object.assign(this, modelTimingSettings({ timeoutMs, idleTimeoutMs }, {}));
+    this.setFallback(fallback);
     Object.assign(this, visionSettings({ vision, imageTokens }, {}));
   }
   getVisionCapability() { if (this.vision === 'auto' && this.modelCapabilities && this.modelCapabilities.model === this.model && typeof this.modelCapabilities.capabilities.vision === 'boolean') return { supported: this.modelCapabilities.capabilities.vision, source: this.modelCapabilities.provenance.vision?.source || 'model_discovery', model: this.model, imageTokens: this.imageTokens }; return { supported: this.vision === 'on', source: this.vision === 'on' ? 'explicit_user_configuration' : this.vision === 'off' ? 'disabled' : 'server_capability_unknown', model: this.model, imageTokens: this.imageTokens }; }
   getCapabilities() { return { text: true, tools: true, vision: this.vision === 'on', video: false, web_search: false, ...this.capabilitiesConfigured, ...(this.modelCapabilities && this.modelCapabilities.model === this.model ? Object.fromEntries(Object.entries(this.modelCapabilities.capabilities).filter(([,value]) => value !== null)) : {}), video: false, web_search: false }; }
   analyzeMedia(request) { return analyzeImages(this, request); }
-  async complete({ system, messages, tools = [], schemaCatalog = [], contextIdentity, signal, onText = () => {}, maxTokens = this.maxTokens }) {
+  // Default form: on for supported models reached through api.anthropic.com; off
+  // otherwise. Keeps fallbackRequested so /config and profiles can persist intent.
+  setFallback(value) { this.fallbackRequested = normalizeFallbackSetting(value); this.fallbackEligible = this.fallbackRequested === 'default' && this.url.hostname === 'api.anthropic.com' && fallbackSupportedModel(this.model); this.fallback = this.fallbackEligible ? 'default' : 'off'; return this.fallback; }
+  async complete({ system, messages, tools = [], schemaCatalog = [], contextIdentity, signal, onText = () => {}, onProgress = () => {}, onReasoning = () => {}, onReasoningEnd = () => {}, onToolCall = () => {}, purpose = 'worker', maxTokens = this.maxTokens }) {
     const accountingRequest={system,messages,tools,maxTokens}, identity={...accountingIdentity(this),projection_epoch:contextIdentity?.projection_epoch ?? null};
-    const schemaFrame=compileToolSchemas(tools,{provider:this.protocol,capabilities:{...(this.getCapabilities?.() || {}),...(this.toolSchemaCapabilities?{tool_schema:this.toolSchemaCapabilities}:{})},catalogue:schemaCatalog}); tools=schemaFrame.tools;
-    messages = messages.map(message => !Array.isArray(message.content) ? message : { ...message, content: message.content.flatMap(original => {
+    const schemaFrame=compileToolSchemas(tools,{provider:this.protocol,capabilities:{...(this.getCapabilities?.() || {}),...(this.toolSchemaCapabilities?{tool_schema:this.toolSchemaCapabilities}:{})},catalogue:schemaCatalog,hoistTopLevelCombinators:true}); tools=schemaFrame.tools;
+    messages = messages.map(message => !Array.isArray(message.content) ? message : { ...message, content: echoFallbackContent(message.content).flatMap(original => {
       // Signatures belong to their issuing protocol. Preserve the durable book,
       // but omit another provider's private reasoning from the Anthropic wire.
       if (original.type === 'openai_reasoning' || original.type === 'thinking' && original.gemini_part) return [];
@@ -103,57 +231,74 @@ export class AnthropicProvider {
       if (!this.getVisionCapability().supported) throw new Error('Vision is not enabled for this provider; no pixels were sent.');
       return { type: 'image', source: block.source };
     }) }).filter(message => !Array.isArray(message.content) || message.content.length);
-    const requestSignal = signal ? AbortSignal.any([signal, AbortSignal.timeout(this.timeoutMs)]) : AbortSignal.timeout(this.timeoutMs);
+    const deadline = modelDeadline({ signal, timeoutMs: this.timeoutMs, idleTimeoutMs: this.idleTimeoutMs, purpose, provider: 'Anthropic' });
     const effortWire = await providerEffortWire(this, { signal });
-    const body = JSON.stringify({ ...effortWire, model: this.model, max_tokens: maxTokens, system, messages: mergeMessages(messages), ...(tools.length ? { tools } : {}), stream: true });
+    const wire = this.promptCaching ? withCacheBreakpoints({ system, tools, messages: mergeMessages(messages) }) : { system, tools, messages: mergeMessages(messages) };
+    const thinking = adaptiveThinkingModel(this.model) && this.thinkingDisplay ? { thinking: { type: 'adaptive', display: this.thinkingDisplay } } : {};
+    const body = JSON.stringify({ ...thinking, ...effortWire, model: this.model, max_tokens: maxTokens, system: wire.system, messages: wire.messages, ...(wire.tools.length ? { tools: wire.tools } : {}), stream: true, ...(this.fallback === 'default' ? { fallbacks: 'default' } : {}) });
     const account=result=>({...result,usage_accounting:bindUsageAccounting(normalizeUsage('anthropic',result.usage),accountingRequest,identity,body),schema_diagnostics:schemaFrame.diagnostics,schema_manifest:schemaFrame.manifest});
-    const finish=result=>{try{return account(validateMessage(result));}catch(error){if(error.usage_accounting)error.usage_accounting=bindUsageAccounting(error.usage_accounting,accountingRequest,identity,body);throw error;}};
-    if (Buffer.byteLength(body) > 8 * 1024 * 1024) throw new Error('The context exceeds 8 MiB; start a new session with /clear.');
+    const finish=(result,trace)=>{try{return account(validateMessage(result,trace));}catch(error){if(error.usage_accounting)error.usage_accounting=bindUsageAccounting(error.usage_accounting,accountingRequest,identity,body);throw error;}};
     let response;
+    try {
+    if (Buffer.byteLength(body) > 8 * 1024 * 1024) throw new Error('The context exceeds 8 MiB; start a new session with /clear.');
     for (let attempt = 0; attempt < 3; attempt++) {
-      response = await this.fetch(this.url, { method: 'POST', headers: { 'content-type': 'application/json', 'x-api-key': this.apiKey, 'anthropic-version': '2023-06-01' }, body, signal: requestSignal });
+      response = await this.fetch(this.url, { method: 'POST', headers: { 'content-type': 'application/json', 'x-api-key': this.apiKey, 'anthropic-version': '2023-06-01', ...(this.fallback === 'default' ? { 'anthropic-beta': 'server-side-fallback-2026-07-01' } : {}) }, body, signal: deadline.signal });
       if (![429, 529, 503].includes(response.status) || attempt === 2) break;
       await response.body?.cancel();
       const retry = Number(response.headers.get('retry-after'));
-      await delay(Number.isFinite(retry) && retry > 0 ? Math.min(retry * 1000, 5000) : 300 * 2 ** attempt, undefined, { signal: requestSignal });
-    }
-    if (!response.ok) {
-      await response.body?.cancel();
-      throw new Error(`API HTTP ${response.status}. Check the key, model, limits or endpoint.`);
+      await delay(Number.isFinite(retry) && retry > 0 ? Math.min(retry * 1000, 5000) : 300 * 2 ** attempt, undefined, { signal: deadline.signal });
     }
+    if (!response.ok) throw await providerHttpError(response, 'Anthropic', wire);
     if (!(response.headers.get('content-type') || '').includes('text/event-stream')) {
-      const message = finish(await response.json());
-      for (const block of message.content) if (block.type === 'text') onText(block.text);
-      return account(message);
+      const raw = await response.json();
+      if (raw && raw.stop_reason === 'refusal') raw.content = [];
+      return annotateOutcome(finish(raw), raw, onText);
     }
-    let message, stopped = false;
-    const blocks = new Map(), partial = new Map(), closed = new Set();
+    let message, stopped = false, textChars = 0, reasoningChars = 0, argumentChars = 0, lastProgress = 0;
+    const blocks = new Map(), partial = new Map(), closed = new Set(), started = Date.now();
+    // Esqueleto del stream (índice, tipo, deltas) para diagnosticar sin volcar contenido.
+    const trace = new Map(), traced = (index, field) => { const entry = trace.get(index); if (entry) entry[field] = (entry[field] || 0) + 1; };
+    const progress = (force = false) => { if (force || Date.now() - lastProgress >= 750) { lastProgress = Date.now(); onProgress({ text_chars: textChars, reasoning_chars: reasoningChars, tool_argument_chars: argumentChars, elapsed_ms: Date.now() - started, purpose }); } };
     for await (const event of sseEvents(response.body)) {
-      if (event.type === 'error') throw new Error(`Streaming error: ${event.error?.type || 'unknown'}`);
+      deadline.touch();
+      if (event.type === 'error') throw Object.assign(new Error(`Anthropic streaming error ${event.error?.type || 'unknown'}: ${clip(event.error?.message) || 'no message'}`), { code: 'PROVIDER_STREAM_ERROR', details: { error_type: event.error?.type || 'unknown', error_message: clip(event.error?.message) || '' } });
       if (event.type === 'message_start') { if (message) throw new Error('Duplicate message_start.'); message = structuredClone(event.message); }
       else if (event.type === 'content_block_start') {
         if (blocks.has(event.index)) throw new Error('Duplicate block.');
         blocks.set(event.index, structuredClone(event.content_block));
+        if (trace.size < 64) trace.set(event.index, { index: event.index, type: event.content_block?.type, order: trace.size });
+        if (event.content_block?.type === 'tool_use') onToolCall(); else if (/thinking/.test(event.content_block?.type || '')) onReasoning();
       } else if (event.type === 'content_block_delta') {
         const block = blocks.get(event.index);
         if (!block || closed.has(event.index)) throw new Error('Delta outside its block.');
         const d = event.delta;
-        if (d.type === 'text_delta') { block.text = (block.text || '') + d.text; onText(d.text); }
-        else if (d.type === 'input_json_delta') partial.set(event.index, (partial.get(event.index) || '') + d.partial_json);
-        else if (d.type === 'thinking_delta') block.thinking = (block.thinking || '') + d.thinking;
+        traced(event.index, d?.type || 'unknown_delta');
+        if (d.type === 'text_delta') { block.text = (block.text || '') + d.text; textChars += d.text.length; onText(d.text); }
+        else if (d.type === 'input_json_delta') { partial.set(event.index, (partial.get(event.index) || '') + d.partial_json); argumentChars += d.partial_json.length; }
+        else if (d.type === 'thinking_delta') { block.thinking = (block.thinking || '') + d.thinking; reasoningChars += d.thinking.length; }
         else if (d.type === 'signature_delta') block.signature = (block.signature || '') + d.signature;
       } else if (event.type === 'content_block_stop') {
         if (!blocks.has(event.index)) throw new Error('Unknown block closure.');
-        if (partial.has(event.index)) { const block = blocks.get(event.index), raw = partial.get(event.index); try { block.input = JSON.parse(raw); } catch { delete block.input; block.truncated_input_chars = raw.length; } }
+        if (partial.has(event.index)) {
+          const block = blocks.get(event.index), raw = partial.get(event.index);
+          // Sin argumentos el stream puede traer partial_json vacío: se conserva el input de content_block_start.
+          if (raw.trim()) { try { block.input = JSON.parse(raw); } catch (error) { delete block.input; block.truncated_input_chars = raw.length; block.input_parse_error = clip(String(error.message).replace(/,? ".*$/s, ''), 120); } }
+        }
         closed.add(event.index);
+        if (/thinking/.test(blocks.get(event.index).type || '')) onReasoningEnd();
       } else if (event.type === 'message_delta') {
         if (!message) throw new Error('Delta without a message.');
         Object.assign(message, event.delta); message.usage = { ...message.usage, ...event.usage };
       } else if (event.type === 'message_stop') stopped = true;
+      progress();
     }
-    if (!stopped || !message || closed.size !== blocks.size) throw new Error('Streaming interrupted; no tools from this response were executed.');
+    progress(true);
+    if (!stopped || !message || closed.size !== blocks.size) throw Object.assign(new Error('Streaming interrupted; no tools from this response were executed.'), { code: 'MODEL_STREAM_ERROR' });
     message.content = [...blocks.entries()].sort((a, b) => a[0] - b[0]).map(([, block]) => block);
-    return finish(message);
+    // Rechazo a mitad de stream: se descarta la salida parcial en vez de tratarla como completa.
+    if (message.stop_reason === 'refusal') message.content = [];
+    return annotateOutcome(finish(message, [...trace.values()]), message, null);
+    } catch (error) { throw deadline.error(error); } finally { deadline.close(); }
   }
 }
 

package/src/read-only-check.mjs

@@ -1,4 +1,5 @@
 import { shellCommands } from './auto-guard.mjs';
+import { toolEffects } from './operations.mjs';
 
 // A deliberately small executable subset, not a claim that arbitrary Bash is safe.
 // The native executor runs these greps with fixed argv and no shell.
@@ -33,10 +34,17 @@ export function readOnlyBashCheck(command) {
 // Rechecking still goes through the live contract, guard and permission judge.
 const CHROME_LAB_READS = new Set(['Status', 'Deployment', 'Targets', 'ReadDOM', 'Assert', 'Contexts', 'Console', 'WorkerDiagnostics'].map(name => `plugin__chrome-lab__${name}`));
 export const chromeLabObservation = operation => CHROME_LAB_READS.has(operation);
-// open-relay: lecturas del canal admin (sin mutación). Las acciones de la fase 2
-// (Reply, Ack, ApprovePlan, RejectPlan) no son observaciones: pasan por la tarjeta.
-const OPEN_RELAY_READS = new Set(['Status', 'Swarms', 'Swarm', 'Task', 'Inbox', 'Message', 'Plans', 'Plan', 'Jobs', 'Job', 'JobLogs', 'Receipt', 'Events', 'Dossier'].map(name => `plugin__open-relay__${name}`));
+// open-relay: lecturas del canal admin (sin mutación). Las acciones (Reply, Ack,
+// ApprovePlan, RejectPlan y Decide, que registra ADR) no son observaciones: pasan por la tarjeta.
+const OPEN_RELAY_READS = new Set(['Status', 'Swarms', 'Swarm', 'Task', 'Inbox', 'Message', 'Plans', 'Plan', 'Jobs', 'Job', 'JobLogs', 'Receipt', 'Events', 'Dossier', 'Decisions', 'Decision'].map(name => `plugin__open-relay__${name}`));
 export const openRelayObservation = operation => OPEN_RELAY_READS.has(operation);
-export const readOnlyWorkCheck = (operation, args) => ['Read', 'Glob', 'Grep', 'ListDirectory', 'FileInfo', 'ChromeVerify','SourceVerify'].includes(operation) || operation==='GitInspect'&&Boolean(args)&&Object.keys(args).length===0 || CHROME_LAB_READS.has(operation) || (operation === 'Bash' && Boolean(readOnlyBashCheck(args?.command)));
+// omarchy: catálogo, clasificación, lecturas revisadas y guía. Change y SystemChange no son observaciones.
+const OMARCHY_READS = new Set(['Status', 'Commands', 'Classify', 'Read', 'Guide'].map(name => `plugin__omarchy__${name}`));
+export const omarchyObservation = operation => OMARCHY_READS.has(operation);
+// The operation contract (toolEffects) is the authority for pure local reads; this list only adds hosts' verifiers.
+// Session introspection changes with every row: never a credited or auto-refreshed check.
+const INTROSPECTION = new Set(['WorkSnapshot', 'HouseSnapshot', 'AuditStatus', 'OperationCatalog']);
+const localRead = operation => { if (INTROSPECTION.has(operation)) return false; const effects = toolEffects(operation); return effects.workspace === 'read' && effects.external === 'none' && effects.process === 'none' && effects.authority === 'none'; };
+export const readOnlyWorkCheck = (operation, args) => ['ChromeVerify','SourceVerify'].includes(operation) || localRead(operation) || operation==='GitInspect'&&Boolean(args)&&Object.keys(args).length===0 || CHROME_LAB_READS.has(operation) || (operation === 'Bash' && Boolean(readOnlyBashCheck(args?.command)));
 export const RUNTIME_CHECK_IDS = Object.freeze(['target_id','pageId','page_id','context_id','contextId']);
 export const runtimeBoundReadCheck = (operation, args) => readOnlyWorkCheck(operation,args) && (RUNTIME_CHECK_IDS.some(key => Object.hasOwn(args || {},key)) || operation==='plugin__chrome-lab__WorkerDiagnostics'&&Object.hasOwn(args||{},'connection_id')&&Object.hasOwn(args||{},'browser_endpoint_id'));

package/src/relay/broker.mjs

@@ -0,0 +1,160 @@
+import { createHash } from 'node:crypto';
+import { t, registerMessages } from '../i18n/index.mjs';
+import { RELAY_ANSWERS } from '../remote-relay.mjs';
+
+// /rc + /relay, fase «responder»: una tarjeta, dos superficies (la TUI y el navegador de /rc).
+// Gana el primero que CONFIRMA (D3): abrir o mirar la tarjeta no reserva nada. El candado es
+// síncrono en el event loop, por card key (la misma clave que follow.mjs y remote-relay.mjs), y
+// sólo lo toma una mutación en curso. Una tarjeta decidida queda en `decided` y cualquier otro
+// intento (otra superficie, un control repetido o viejo) responde already_decided sin mutar.
+// Hace falta en Comal porque relayd admite rechazar un plan ya aprobado y aún no aplicado.
+registerMessages({
+  '{what} was decided from the browser ({outcome}).': '{what} se decidió desde el navegador ({outcome}).',
+  'Already decided from the browser ({outcome}); nothing was sent.': 'Ya decidida desde el navegador ({outcome}); no se envió nada.',
+  'This card is being decided in this terminal right now.': 'Esta tarjeta se está decidiendo ahora mismo en esta terminal.',
+  'Plan {id}': 'El plan {id}', 'The question {id}': 'La pregunta {id}', 'The success criteria of {swarm}': 'Los criterios de éxito de {swarm}',
+  '/relay answers from the browser: armed until {time}.': 'Respuestas de /relay desde el navegador: armadas hasta las {time}.',
+  '/relay answers from the browser: off.': 'Respuestas de /relay desde el navegador: apagadas.',
+  'Open /rc first; /rc relay on arms answers for that session only.': 'Abre /rc primero; /rc relay on arma las respuestas sólo para esa sesión.',
+  'Plans and success criteria also need a sign-in from the last 10 minutes in that browser; retrying blocked tasks stays here. /rc relay off disarms.': 'Aprobar planes y criterios de éxito exige además haber iniciado sesión en ese navegador hace ≤ 10 min; reintentar tareas bloqueadas sigue aquí. /rc relay off las apaga.',
+  'approved': 'aprobado', 'rejected': 'rechazado', 'decided': 'decidida', 'answered': 'respondida', 'acked': 'dada por leída',
+});
+
+const sha256 = value => createHash('sha256').update(value).digest('hex');
+const KIND_OF = action => RELAY_ANSWERS.actions[action]?.card || null;
+const APPLIED = new Set(RELAY_ANSWERS.outcomes.applied);
+
+// Lo decidido se recuerda 10 min (el TTL de un control): pasado eso manda la re-lectura de relayd.
+const DECIDED_MS = RELAY_ANSWERS.control_ttl_seconds * 1000;
+export class RelayDecisionBroker {
+  constructor({ now = Date.now } = {}) { this.now = now; this.locks = new Map(); this.decided = new Map(); this.watchers = new Map(); }
+  /** Candado de una sola entrada. {ok} o {ok:false, holder|decided}. Lo decidido por la OTRA
+   *  superficie bloquea; lo decidido por la misma lo juzga relayd al volver a leer. */
+  begin(key, source) {
+    const decided = this.outcome(key); if (decided && decided.by !== source) return { ok: false, decided };
+    const holder = this.locks.get(key); if (holder) return { ok: false, holder };
+    this.locks.set(key, source); return { ok: true };
+  }
+  release(key) { this.locks.delete(key); }
+  /** La tarjeta quedó decidida: suelta el candado, la recuerda y cierra la tarjeta abierta en la otra superficie. */
+  commit(key, { outcome, by, request_id = null }) {
+    this.locks.delete(key);
+    this.decided.set(key, { outcome, by, request_id, at: this.now() });
+    if (this.decided.size > 2000) this.decided.delete(this.decided.keys().next().value);
+    for (const controller of this.watchers.get(key) || []) controller.abort();
+  }
+  outcome(key) { const decided = this.decided.get(key); return decided && this.now() - decided.at < DECIDED_MS ? decided : null; }
+  /** Señal por tarjeta abierta en la TUI (combinada con la de la sesión): si la otra superficie
+   *  decide, su setupChoice/setupInput se cierra solo. */
+  open(key, signal) {
+    const controller = new AbortController(), set = this.watchers.get(key) || new Set();
+    set.add(controller); this.watchers.set(key, set);
+    return { signal: signal ? AbortSignal.any([signal, controller.signal]) : controller.signal, close: () => { set.delete(controller); if (!set.size) this.watchers.delete(key); } };
+  }
+}
+
+/** ¿El texto cumple la regla de la acción? (none | required | optional, en bytes UTF-8). */
+export function relayText(action, text) {
+  const rule = RELAY_ANSWERS.actions[action], value = typeof text === 'string' ? text : '';
+  if (!rule) return false;
+  if (rule.text === 'none') return value === '';
+  if (Buffer.byteLength(value) > rule.text_max) return false;
+  return rule.text === 'optional' || value.trim() !== '';
+}
+
+/**
+ * Camino del navegador (RemoteHost → onRelay). Revalida en local, en este orden (§4.2 del
+ * diseño), y sólo entonces muta con las funciones de la TUI (RelayFlow.apply*):
+ *   1. libro: ¿ya se resolvió este request_id? → el mismo resultado, sin mutar (ACK perdido, reinicio);
+ *   2. sesión y época de /rc; 3. armado local vigente; 4. caducidad del control;
+ *   5. tarjeta pendiente en esta sesión, de la clase y el sujeto del control, acción permitida;
+ *      candado libre (si ya está decidida: already_decided);
+ *   6. remote.inputs.validate (el login del navegador sigue vivo);
+ *   7. relayd en vivo (dentro de apply*: plan.get / msg.get+inbox / criteria.get) y mutación.
+ * Todo control deja su fila relay_control con source remote_browser y su request_id.
+ */
+export class RemoteRelayAnswers {
+  constructor({ broker, flow, feed, rows = async () => [], now = Date.now }) {
+    Object.assign(this, { broker, flow, feed, rows, now });
+    this.ledger = null;
+  }
+  async #ledger() {
+    if (!this.ledger) {
+      this.ledger = new Map();
+      try { for (const row of await this.rows()) if (row?.type === 'relay_control' && row.source === 'remote_browser' && row.remote_request_id && row.remote_outcome) this.ledger.set(row.remote_request_id, { state: row.remote_state, outcome: row.remote_outcome }); } catch {}
+    }
+    return this.ledger;
+  }
+  async #settle(input, control, result, extra = {}) {
+    const ledger = await this.#ledger();
+    ledger.set(input.request_id, result);
+    if (ledger.size > 4096) ledger.delete(ledger.keys().next().value);
+    // Las mutaciones aplicadas ya dejaron su fila (apply*, con remote_*); el resto deja la suya aquí.
+    if (!extra.recorded) try { await this.flow.record({ action: 'remote.answer', source: 'remote_browser', remote_session: input.remote_session_id, remote_request_id: input.request_id, remote_action: control?.action || null, card_id: control?.card_id || null, remote_state: result.state, remote_outcome: result.outcome, ...extra.row }); } catch {}
+    return result;
+  }
+  async handle(input, { session, epoch, armed = () => false, validate = async () => true } = {}) {
+    const control = input?.control || {}, ledger = await this.#ledger();
+    // 1. Libro: el mismo request_id devuelve lo mismo y nunca vuelve a mutar.
+    if (ledger.has(input?.request_id)) return ledger.get(input.request_id);
+    const refuse = (state, outcome) => this.#settle(input, control, { state, outcome });
+    if (input?.kind !== 'relay' || !KIND_OF(control.action)) return refuse('refused', 'invalid');
+    // 2. Sesión y época.
+    if (input.remote_session_id !== session || control.host_epoch !== epoch) return refuse('stale', 'epoch');
+    // 3. Armado local (D1).
+    if (!armed()) return refuse('refused', 'local_arm_off');
+    // 4. Caducidad (10 min desde la admisión en Milpa).
+    if (!Number.isFinite(Number(input.expires_at)) || Number(input.expires_at) * 1000 <= this.now()) return refuse('expired', 'expired');
+    // 5. Tarjeta: publicada en esta sesión y todavía pendiente aquí.
+    const entry = this.feed?.card(control.card_id);
+    // Una tarjeta ya cerrada (decidida en cualquier superficie, o por otro control) no se vuelve a decidir.
+    if (!entry) return refuse('stale', this.feed?.resolution?.(control.card_id) ? 'already_decided' : 'card_gone');
+    const card = entry.card, rule = RELAY_ANSWERS.actions[control.action];
+    if (card.kind !== rule.card || card.subject !== control.subject || card.project !== control.project || card.swarm !== control.swarm) return refuse('stale', 'kind');
+    if (!card.answerable?.browser || !card.answerable.actions?.includes(control.action)) return refuse('refused', 'cap_missing');
+    if (!relayText(control.action, control.text ?? '')) return refuse('refused', 'invalid');
+    for (const field of rule.fields) if (control[field] === undefined || control[field] === null) return refuse('refused', 'invalid');
+    if (rule.fields.includes('digest') && control.digest !== card.body.digest) return refuse('stale', 'digest');
+    if (control.action === 'plan.approve' && control.projection_sha256 !== card.body.projection_sha256) return refuse('stale', 'projection');
+    const lock = this.broker.begin(entry.key, 'browser');
+    if (!lock.ok) return lock.decided ? refuse('stale', 'already_decided') : refuse('refused', 'local_in_progress');
+    let result;
+    try {
+      // 6. El navegador que lo pidió sigue con sesión (login padre).
+      try { await validate(); } catch { this.broker.release(entry.key); return refuse('refused', 'revoked'); }
+      // 7. relayd en vivo + mutación, con las funciones y claves de la TUI.
+      const remote = { source: 'remote_browser', remote_session: input.remote_session_id, remote_request_id: input.request_id, card_id: control.card_id };
+      result = await this.#apply(entry, control, remote);
+    } catch (error) {
+      this.broker.release(entry.key);
+      const delegation = ['NOT_DELEGATED', 'UNAUTHORIZED', 'RELAY_DELEGATE_MISSING', 'RELAY_TOKEN_INVALID', 'RELAY_TOKEN_UNSAFE'].includes(error?.code);
+      return refuse('refused', delegation ? 'delegation' : 'relay_unavailable');
+    }
+    if (APPLIED.has(result.outcome)) {
+      this.broker.commit(entry.key, { outcome: result.outcome, by: 'browser', request_id: input.request_id });
+      this.flow.ui?.notice?.(t('{what} was decided from the browser ({outcome}).', { what: this.#what(card), outcome: t(result.outcome) }));
+      return this.#settle(input, control, { state: 'applied', outcome: result.outcome }, { recorded: true });
+    }
+    // Obsoleta o ya decidida fuera de Comal (relayd lo dice): no se muta y la TUI decide con su propia re-lectura.
+    this.broker.release(entry.key);
+    return refuse('stale', result.outcome || 'stale');
+  }
+  #what(card) {
+    if (card.kind === 'plan') return t('Plan {id}', { id: card.subject });
+    if (card.kind === 'question') return t('The question {id}', { id: card.subject });
+    return t('The success criteria of {swarm}', { swarm: card.swarm });
+  }
+  async #apply(entry, control, remote) {
+    const item = entry.item, base = { project: item.project, root: item.root, swarm: item.swarm, ...remote };
+    if (entry.card.kind === 'plan') return this.flow.applyPlan({ ...base, proposal_id: item.proposal_id, digest: control.digest, choice: control.action === 'plan.approve' ? 'approve' : 'reject', reason: control.text, projection: control.projection_sha256 });
+    if (entry.card.kind === 'question') {
+      const mode = control.action.slice('question.'.length);
+      // La opción se identifica por índice Y por el sha256 de la etiqueta que vio el navegador.
+      const option = mode === 'option' ? entry.card.body.decision?.options?.[control.option_index] : null;
+      if (mode === 'option' && (!option || sha256(option.label) !== control.option_label_sha256)) return { outcome: 'option' };
+      return this.flow.applyQuestion({ ...base, message_id: item.message_id, mode, option_index: control.option_index, option_label_sha256: control.option_label_sha256, text: control.text || '' });
+    }
+    if (entry.card.kind === 'criteria') return this.flow.applyCriteria({ ...base, digest: control.digest, choice: control.action === 'criteria.accept' ? 'accept' : 'reject', reason: control.text });
+    return { outcome: 'kind' };
+  }
+}