@milpa/comal 0.2.2 → 0.2.4

package/src/provider-profiles.mjs

@@ -1,3 +1,4 @@
+import { registerSecretEnv } from './child-env.mjs';
 import { readFile } from 'node:fs/promises';
 import path from 'node:path';
 import { OpenAIProvider, DEFAULT_LOCAL_URL } from './openai-provider.mjs';
@@ -5,11 +6,12 @@ import { AnthropicProvider } from './provider.mjs';
 import { GeminiProvider } from './gemini-provider.mjs';
 import { authProviderDefaults } from './provider-auth.mjs';
 import { normalizeEffort } from './model-controls.mjs';
+import { normalizeFallbackSetting } from './provider.mjs';
 import {normalizeToolSchemaCapabilities} from './tool-schema.mjs';
 
 export const PROVIDER_CAPABILITIES = Object.freeze(['text', 'tools', 'thinking', 'vision', 'video', 'web_search']);
 const PROTOCOLS = ['openai', 'anthropic', 'gemini'];
-const KEYS = new Set(['name', 'provider', 'protocol', 'model', 'baseURL', 'apiKeyEnv', 'capabilities', 'capabilitiesConfigured', 'description', 'effort', 'authProvider','toolSchema']);
+const KEYS = new Set(['name', 'provider', 'protocol', 'model', 'baseURL', 'apiKeyEnv', 'capabilities', 'capabilitiesConfigured', 'description', 'effort', 'authProvider','toolSchema', 'maxTokens', 'contextWindow', 'fallback']);
 const error = message => Object.assign(new Error(message), { code: 'PROVIDER_PROFILE_INVALID' });
 
 export function normalizeCapabilities(value = {}, { protocol = 'openai' } = {}) {
@@ -31,6 +33,7 @@ export function normalizeProviderProfile(input, name = input?.name) {
   if (input.name && input.name !== name) throw error('Conflicting profile name.');
   if (input.authProvider !== undefined && !['codex', 'kimi', 'minimax', 'grok'].includes(input.authProvider)) throw error('Invalid authProvider.');
   if (input.effort !== undefined) normalizeEffort(input.effort);
+  if (input.fallback !== undefined) normalizeFallbackSetting(input.fallback);
   const toolSchema=input.toolSchema===undefined?undefined:normalizeToolSchemaCapabilities(input.toolSchema);
   const access=input.authProvider?authProviderDefaults(input.authProvider):null;
   const configuredCapabilities = input.capabilitiesConfigured || input.capabilities || {};
@@ -47,11 +50,17 @@ export function normalizeProviderProfile(input, name = input?.name) {
   }
   if (input.apiKeyEnv !== undefined && (typeof input.apiKeyEnv !== 'string' || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(input.apiKeyEnv))) throw error('apiKeyEnv must name an environment variable.');
   if (input.description !== undefined && (typeof input.description !== 'string' || input.description.length > 1024)) throw error('Invalid description.');
+  // Output and window budgets are startup defaults for this endpoint; --max-tokens,
+  // --context-window, their variables and connection.json still win.
+  if (input.maxTokens !== undefined && (!Number.isSafeInteger(input.maxTokens) || input.maxTokens < 64 || input.maxTokens > 1000000)) throw error('maxTokens must be an integer between 64 and 1000000.');
+  if (input.contextWindow !== undefined && (!Number.isSafeInteger(input.contextWindow) || input.contextWindow < 4096 || input.contextWindow > 2000000)) throw error('contextWindow must be an integer between 4096 and 2000000.');
+  if (input.maxTokens !== undefined && input.contextWindow !== undefined && input.contextWindow < input.maxTokens * 2) throw error('contextWindow must be at least twice maxTokens.');
   return Object.freeze({ name, provider: protocol, protocol, ...((input.model || access?.model) ? { model: input.model || access.model } : {}),
     baseURL: input.baseURL || access?.baseURL || ({ openai: DEFAULT_LOCAL_URL, anthropic: 'https://api.anthropic.com', gemini: 'https://generativelanguage.googleapis.com/v1beta' })[protocol],
     apiKeyEnv: input.apiKeyEnv || ({ openai: 'OPENAI_API_KEY', anthropic: 'ANTHROPIC_API_KEY', gemini: 'GEMINI_API_KEY' })[protocol],
     capabilities: normalizeCapabilities(input.capabilities, { protocol }), capabilitiesConfigured: Object.freeze({ ...configuredCapabilities }),...(toolSchema?{toolSchema:Object.freeze(toolSchema)}:{}),
-    ...(input.effort !== undefined ? { effort: input.effort } : {}), ...(input.authProvider ? { authProvider: input.authProvider } : {}), ...(input.description ? { description: input.description } : {}) });
+    ...(input.effort !== undefined ? { effort: input.effort } : {}), ...(input.authProvider ? { authProvider: input.authProvider } : {}), ...(input.description ? { description: input.description } : {}),
+    ...(input.maxTokens !== undefined ? { maxTokens: input.maxTokens } : {}), ...(input.contextWindow !== undefined ? { contextWindow: input.contextWindow } : {}), ...(input.fallback !== undefined ? { fallback: input.fallback } : {}) });
 }
 
 // Configuration is data only. Secrets are resolved in createProfileProvider and
@@ -92,11 +101,12 @@ export function selectProfile(registry, name) {
 
 export function createProfileProvider(profile, { env = process.env, ...overrides } = {}) {
   profile = normalizeProviderProfile(profile);
+  registerSecretEnv(profile.apiKeyEnv);
   const capabilities = { ...profile.capabilities };
   if (overrides.vision === 'on') capabilities.vision = true;
   else if (overrides.vision === 'off') capabilities.vision = false;
   const options = { ...overrides, apiKey: overrides.apiKey ?? env[profile.apiKeyEnv], model: overrides.model || profile.model, baseURL: overrides.baseURL || profile.baseURL,
-    capabilities, capabilitiesConfigured: profile.capabilitiesConfigured, effort: overrides.effort ?? profile.effort ?? 'auto', vision: overrides.vision || (Object.hasOwn(profile.capabilitiesConfigured, 'vision') ? capabilities.vision ? 'on' : 'off' : 'auto') };
+    capabilities, capabilitiesConfigured: profile.capabilitiesConfigured, effort: overrides.effort ?? profile.effort ?? 'auto', fallback: overrides.fallback ?? profile.fallback ?? 'default', vision: overrides.vision || (Object.hasOwn(profile.capabilitiesConfigured, 'vision') ? capabilities.vision ? 'on' : 'off' : 'auto') };
   if (profile.protocol !== 'openai' && !options.apiKey) throw new Error(`Set the profile apiKeyEnv variable ${profile.apiKeyEnv}.`);
   const provider = profile.protocol === 'gemini' ? new GeminiProvider(options) : profile.protocol === 'anthropic' ? new AnthropicProvider(options) : new OpenAIProvider(options);
   const complete = provider.complete.bind(provider);

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/qr-scan.mjs

@@ -0,0 +1,240 @@
+// /rc device scan: reads the M5Stack's pairing QR with a local camera, only while the person asked for it, 30 s at most
+// in total (finding the camera included). One ffmpeg stays open for the scan (so focus and exposure settle) and writes
+// 2 frames a second into a private 0700 directory; each completed frame is decoded with zbarimg and deleted right
+// after, and the directory goes at the end (and on process exit). Nothing is kept and nothing leaves this machine.
+// Processes are spawned with argv arrays (no shell). `spawn`, `now`, `sleep`, `readdir` (of /dev) and `tmpRoot` are
+// injectable so tests run without a camera.
+import { spawn as nodeSpawn } from 'node:child_process';
+import { rmSync } from 'node:fs';
+import { chmod, lstat, mkdtemp, readdir as fsReaddir, rm } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { t, registerMessages } from './i18n/index.mjs';
+
+/** The QR on the device's pairing screen: this prefix plus the code as shown, uppercase Crockford XXXX-XXXX.
+ * It carries nothing secret (the device's poll token never goes in it). Same constant as
+ * devices/m5stack/lib/comal_core/pairing.h (PAIR_QR_PREFIX). */
+export const PAIR_QR_PREFIX = 'comal-pair:v1:';
+const PAIR_QR = /^comal-pair:v1:([0-9A-HJKMNP-TV-Z]{4}-[0-9A-HJKMNP-TV-Z]{4})$/;
+const CAMERA = /^\/dev\/video[0-9]+$/;
+export const SCAN_TIMEOUT_MS = 30000;
+export const SCAN_INTERVAL_MS = 250;  // how often the private directory is looked at for completed frames
+const STREAM_SIZE = '1280x720';
+const STREAM_FPS = 2;
+const PROBE_TIMEOUT_MS = 5000;
+const GRAB_TIMEOUT_MS = 10000;
+const FRAME_MAX_BYTES = 32 * 1024 * 1024;
+const FRAME = /^f[0-9]{6}\.png$/;
+const DIR_PREFIX = 'comal-qr-';
+const DIR_SHAPE = /^comal-qr-[A-Za-z0-9]{6}$/;  // what mkdtemp makes of DIR_PREFIX: only these are swept
+const STALE_MS = 120000;  // a scan touches its directory every half second; one untouched for 2 min is left over
+
+registerMessages({
+  'The camera must be a /dev/videoN device.': 'La cámara debe ser un dispositivo /dev/videoN.',
+  'COMAL_CAMERA must be a /dev/videoN device.': 'COMAL_CAMERA debe ser un dispositivo /dev/videoN.',
+  'No camera found (/dev/video*). Pass one with /rc device scan /dev/videoN, or type the code: /rc device XXXX-XXXX.': 'No se encontró una cámara (/dev/video*). Indica una con /rc device scan /dev/videoN, o escribe el código: /rc device XXXX-XXXX.',
+  'Scanning needs ffmpeg and zbarimg. Install the ffmpeg and zbar packages, or type the code: /rc device XXXX-XXXX.': 'Escanear necesita ffmpeg y zbarimg. Instala los paquetes ffmpeg y zbar, o escribe el código: /rc device XXXX-XXXX.',
+  'Could not read the camera {camera}: {reason}': 'No se pudo leer la cámara {camera}: {reason}',
+  'No pairing QR seen in {seconds} s. Bring the M5Stack 10-20 cm from the camera, so the QR fills about a third of the picture, and try again, or type the code: /rc device XXXX-XXXX.': 'No se vio un QR de emparejamiento en {seconds} s. Acerca el M5Stack a 10-20 cm de la cámara, que el QR ocupe un tercio de la imagen, e inténtalo de nuevo, o escribe el código: /rc device XXXX-XXXX.',
+  'QR scan cancelled; the camera is off.': 'Escaneo del QR cancelado; la cámara está apagada.',
+});
+
+/** zbarimg's stdout counts only when it is exactly one symbol: one matching line plus its newline. */
+function onlyPairCode(stdout) {
+  const text = stdout.toString('utf8').replace(/\r?\n$/, '');
+  return /[\r\n]/.test(text) ? null : pairCodeFromQr(text);
+}
+
+/** The code in a pairing QR's text, or null for anything else (which is never echoed). */
+export function pairCodeFromQr(text) {
+  const match = PAIR_QR.exec(typeof text === 'string' ? text : '');
+  return match ? match[1] : null;
+}
+
+export const isCameraPath = value => typeof value === 'string' && CAMERA.test(value);
+
+const failure = (code, message) => Object.assign(new Error(message), { code });
+const aborted = () => Object.assign(new Error(t('QR scan cancelled; the camera is off.')), { name: 'AbortError', code: 'ABORT_ERR' });
+const missingTools = () => failure('QR_SCAN_TOOLS', t('Scanning needs ffmpeg and zbarimg. Install the ffmpeg and zbar packages, or type the code: /rc device XXXX-XXXX.'));
+const timedOut = seconds => failure('QR_SCAN_TIMEOUT', t('No pairing QR seen in {seconds} s. Bring the M5Stack 10-20 cm from the camera, so the QR fills about a third of the picture, and try again, or type the code: /rc device XXXX-XXXX.', { seconds: String(seconds) }));
+const oneLine = text => String(text || '').split(/\r?\n/).map(line => line.trim()).find(Boolean)?.replace(/[\u0000-\u001f\u007f-\u009f]/g, '').slice(0, 200) || 'no frame';
+
+/** Runs one process to its end: {code, stdout, stderr}. Killed on abort or after `timeoutMs`; ENOENT → missing tools. */
+function run(spawn, cmd, args, { signal, timeoutMs = GRAB_TIMEOUT_MS } = {}) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) { reject(aborted()); return; }
+    let child;
+    try { child = spawn(cmd, args, { stdio: ['ignore', 'pipe', 'pipe'], shell: false }); }
+    catch (error) { reject(error.code === 'ENOENT' ? missingTools() : error); return; }
+    const out = [], err = [];
+    let size = 0, errSize = 0, settled = false;
+    const settle = (fn, value) => { if (settled) return; settled = true; clearTimeout(timer); signal?.removeEventListener('abort', onAbort); fn(value); };
+    const kill = () => { try { child.kill('SIGKILL'); } catch {} };
+    const onAbort = () => { kill(); settle(reject, aborted()); };
+    const timer = setTimeout(() => { kill(); settle(resolve, { code: null, stdout: Buffer.alloc(0), stderr: 'timed out' }); }, timeoutMs);
+    timer.unref?.();
+    signal?.addEventListener('abort', onAbort, { once: true });
+    child.stdout?.on('data', chunk => { size += chunk.length; if (size > FRAME_MAX_BYTES) { kill(); settle(resolve, { code: null, stdout: Buffer.alloc(0), stderr: 'frame too large' }); } else out.push(chunk); });
+    child.stderr?.on('data', chunk => { if (errSize < 4096) { err.push(chunk); errSize += chunk.length; } });
+    child.on('error', error => settle(reject, error.code === 'ENOENT' ? missingTools() : error));
+    child.on('close', code => settle(resolve, { code, stdout: Buffer.concat(out), stderr: Buffer.concat(err).toString('utf8') }));
+  });
+}
+
+const grabArgs = device => ['-hide_banner', '-loglevel', 'error', '-f', 'v4l2', '-i', device, '-frames:v', '1', '-f', 'image2pipe', '-vcodec', 'png', '-'];
+const DECODE_ARGS = ['--raw', '-q', '-Sdisable', '-Sqrcode.enable'];
+
+/** True when `v4l2-ctl --all` says this node itself captures video (Device Caps; Capabilities is the whole device's). */
+function capturesVideo(text) {
+  const lines = String(text).split('\n');
+  const start = lines.findIndex(line => /^\s*Device Caps\s*:/.test(line));
+  if (start < 0) return false;
+  const indent = lines[start].match(/^\s*/)[0].length;
+  for (const line of lines.slice(start + 1)) {
+    if (!line.trim() || line.match(/^\s*/)[0].length <= indent) break;
+    if (/^\s*Video Capture(?: Multiplanar)?\s*$/.test(line)) return true;
+  }
+  return false;
+}
+
+/** The camera: `camera` (argument) > env COMAL_CAMERA > the first /dev/videoN that v4l2-ctl reports as Video Capture
+ * (without v4l2-ctl: the first one ffmpeg can read a frame from). Anything that is not /dev/videoN is refused. */
+export async function pickCamera({ camera, env = process.env, spawn = nodeSpawn, readdir = fsReaddir, signal, deadline = Infinity, now = Date.now, seconds = SCAN_TIMEOUT_MS / 1000 } = {}) {
+  if (camera !== undefined && camera !== null && camera !== '') {
+    if (!isCameraPath(camera)) throw failure('QR_SCAN_CAMERA_PATH', t('The camera must be a /dev/videoN device.'));
+    return camera;
+  }
+  const fromEnv = env?.COMAL_CAMERA?.trim();
+  if (fromEnv) {
+    if (!isCameraPath(fromEnv)) throw failure('QR_SCAN_CAMERA_PATH', t('COMAL_CAMERA must be a /dev/videoN device.'));
+    return fromEnv;
+  }
+  let names = [];
+  try { names = await readdir('/dev'); } catch {}
+  const candidates = names.filter(name => /^video[0-9]+$/.test(name)).sort((a, b) => Number(a.slice(5)) - Number(b.slice(5))).map(name => '/dev/' + name);
+  // Probing counts toward the scan's time: each probe gets what is left, and none starts past the deadline.
+  const left = limit => { const ms = Math.min(limit, deadline - now()); if (ms <= 0) throw timedOut(seconds); return ms; };
+  let haveV4l2 = true;
+  for (const device of candidates) {
+    if (haveV4l2) {
+      try {
+        const result = await run(spawn, 'v4l2-ctl', ['--device', device, '--all'], { signal, timeoutMs: left(PROBE_TIMEOUT_MS) });
+        if (result.code === 0 && capturesVideo(result.stdout.toString('utf8'))) return device;
+        continue;
+      } catch (error) {
+        if (error.name === 'AbortError' || error.code === 'QR_SCAN_TIMEOUT') throw error;
+        if (error.code !== 'QR_SCAN_TOOLS') continue;
+        haveV4l2 = false;
+      }
+    }
+    const result = await run(spawn, 'ffmpeg', grabArgs(device), { signal, timeoutMs: left(GRAB_TIMEOUT_MS) });
+    if (result.code === 0 && result.stdout.length) return device;
+  }
+  throw failure('QR_SCAN_NO_CAMERA', t('No camera found (/dev/video*). Pass one with /rc device scan /dev/videoN, or type the code: /rc device XXXX-XXXX.'));
+}
+
+const abortableSleep = (ms, signal) => new Promise((resolve, reject) => {
+  if (signal?.aborted) { reject(aborted()); return; }
+  const timer = setTimeout(() => { signal?.removeEventListener('abort', onAbort); resolve(); }, ms);
+  const onAbort = () => { clearTimeout(timer); reject(aborted()); };
+  signal?.addEventListener('abort', onAbort, { once: true });
+});
+
+// How the camera is opened, in order, each tried when the one before ends without a frame: 1280x720 MJPEG (a UVC
+// camera often has 1280x720 only as MJPEG and silently gives 640x480 raw frames for a bare -video_size), 1280x720 in
+// its default format, then its own default size.
+const STREAM_ATTEMPTS = [['-input_format', 'mjpeg', '-video_size', STREAM_SIZE], ['-video_size', STREAM_SIZE], []];
+// `-t` (an input option) is the seconds left to the scan, rounded up: if Comal dies without its exit hook (SIGKILL, OOM,
+// a crash) ffmpeg still ends itself, and turns the camera off, at the scan's deadline.
+const streamArgs = (device, dir, attempt, seconds) => ['-hide_banner', '-loglevel', 'error', '-f', 'v4l2', ...STREAM_ATTEMPTS[attempt], '-t', String(seconds), '-i', device, '-vf', `fps=${STREAM_FPS}`, '-f', 'image2', path.join(dir, 'f%06d.png')];
+
+/** The long-running ffmpeg of a scan: {child, exited, error, stderr, closed}. */
+function startStream(spawn, args) {
+  const stream = { child: null, exited: false, error: null, stderr: '' };
+  stream.closed = new Promise(resolve => {
+    try { stream.child = spawn('ffmpeg', args, { stdio: ['ignore', 'ignore', 'pipe'], shell: false }); }
+    catch (error) { stream.exited = true; stream.error = error; resolve(); return; }
+    stream.child.stderr?.on('data', chunk => { if (stream.stderr.length < 4096) stream.stderr += chunk.toString('utf8'); });
+    stream.child.on('error', error => { stream.error = error; stream.exited = true; resolve(); });
+    stream.child.on('close', () => { stream.exited = true; resolve(); });
+  });
+  return stream;
+}
+/** Kills a stream and waits (briefly) until it is gone, so nothing writes into the directory being removed. */
+async function stopStream(stream) {
+  if (!stream || stream.exited) return;
+  try { stream.child.kill('SIGKILL'); } catch {}
+  let timer;
+  await Promise.race([stream.closed, new Promise(resolve => { timer = setTimeout(resolve, 2000); timer.unref?.(); })]);
+  clearTimeout(timer);
+}
+
+/** Removes this user's own comal-qr-* directories in `root` that no scan has touched for a while (a killed process). */
+async function sweepStale(root) {
+  let names = [];
+  try { names = await fsReaddir(root); } catch { return; }
+  const uid = process.getuid?.();
+  for (const name of names) {
+    if (!DIR_SHAPE.test(name)) continue;
+    try {
+      const info = await lstat(path.join(root, name));
+      if (!info.isDirectory() || (uid !== undefined && info.uid !== uid) || Date.now() - info.mtimeMs < STALE_MS) continue;
+      await rm(path.join(root, name), { recursive: true, force: true });
+    } catch {}
+  }
+}
+
+/** Scans for the pairing QR for up to `timeoutMs` in total, finding the camera included. Resolves {code, camera}. */
+export async function scanPairingQr({ camera, env = process.env, timeoutMs = SCAN_TIMEOUT_MS, intervalMs = SCAN_INTERVAL_MS, signal, spawn = nodeSpawn, now = Date.now, sleep, readdir = fsReaddir, tmpRoot = os.tmpdir() } = {}) {
+  if (signal?.aborted) throw aborted();
+  const deadline = now() + timeoutMs, seconds = Math.round(timeoutMs / 1000);
+  const left = limit => { const ms = Math.min(limit, deadline - now()); if (ms <= 0) throw timedOut(seconds); return ms; };
+  const pause = sleep ?? (ms => abortableSleep(ms, signal));
+  // Both tools are checked before the camera turns on.
+  for (const [cmd, args] of [['ffmpeg', ['-hide_banner', '-version']], ['zbarimg', ['--version']]]) await run(spawn, cmd, args, { signal, timeoutMs: left(PROBE_TIMEOUT_MS) });
+  const root = path.resolve(tmpRoot);
+  await sweepStale(root);
+  const dir = await mkdtemp(path.join(root, DIR_PREFIX));
+  let stream = null;
+  const onExit = () => { try { stream?.child?.kill('SIGKILL'); } catch {} try { rmSync(dir, { recursive: true, force: true }); } catch {} };
+  process.once('exit', onExit);
+  try {
+    await chmod(dir, 0o700);
+    const device = await pickCamera({ camera, env, spawn, readdir, signal, deadline, now, seconds });
+    left(1);
+    let attempt = 0, seen = 0;
+    const secondsLeft = () => Math.max(1, Math.ceil((deadline - now()) / 1000));
+    stream = startStream(spawn, streamArgs(device, dir, attempt, secondsLeft()));
+    for (;;) {
+      await pause(Math.max(0, Math.min(intervalMs, deadline - now())));
+      if (signal?.aborted) throw aborted();
+      // Read whether ffmpeg ended BEFORE listing: then every listed frame is complete. While it runs, the newest frame
+      // may still be being written, so only the ones older than it are complete. Of those only the newest is decoded:
+      // older ones are deleted unread, so a slow decode never builds a backlog of stale frames.
+      const ended = stream.exited;
+      const frames = (await fsReaddir(dir)).filter(name => FRAME.test(name)).sort();
+      const complete = ended ? frames : frames.slice(0, -1);
+      if (complete.length) {
+        seen += complete.length;
+        for (const name of complete.slice(0, -1)) await rm(path.join(dir, name), { force: true });
+        const file = path.join(dir, complete.at(-1));
+        let decoded;
+        try { decoded = await run(spawn, 'zbarimg', [...DECODE_ARGS, file], { signal, timeoutMs: Math.max(1, Math.min(PROBE_TIMEOUT_MS, deadline - now())) }); }
+        finally { await rm(file, { force: true }); }
+        const code = decoded.code === 0 ? onlyPairCode(decoded.stdout) : null;
+        if (code) return { code, camera: device };
+      }
+      if (ended && !frames.length) {
+        if (stream.error) throw stream.error.code === 'ENOENT' ? missingTools() : stream.error;
+        // A camera that refuses a format or size is opened again the next way, down to its own default.
+        if (!seen && attempt + 1 < STREAM_ATTEMPTS.length) { attempt += 1; left(1); stream = startStream(spawn, streamArgs(device, dir, attempt, secondsLeft())); continue; }
+        throw failure('QR_SCAN_CAMERA', t('Could not read the camera {camera}: {reason}', { camera: device, reason: oneLine(stream.stderr) }));
+      }
+      if (now() >= deadline) throw timedOut(seconds);
+    }
+  } finally {
+    await stopStream(stream);
+    await rm(dir, { recursive: true, force: true });
+    process.removeListener('exit', onExit);
+  }
+}

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.
@@ -40,6 +41,10 @@ export const openRelayObservation = operation => OPEN_RELAY_READS.has(operation)
 // 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);
-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)));
+// 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'));