@milpa/comal 0.0.0-stage → 0.1.1

package/src/tool-packs.mjs

@@ -0,0 +1,166 @@
+import { workProjection, workDigest } from './work-plan.mjs';
+import { digest } from './operations.mjs';
+import { checkOperationCandidates } from './work-check-contracts.mjs';
+import { searchToolCatalog } from './tool-catalog.mjs';
+
+const BROWSER = ['new_page','list_pages','navigate_page','list_console_messages','list_network_requests','take_snapshot'];
+const CAPTURE = ['take_screenshot'];
+const ADMIN = ['WorkSnapshot','AuditStatus','HouseSnapshot','OperationCatalog'];
+const SCOPED = {'sessions.peers':['ListAgents','SendMessage'],'provider.features':['ProviderCapabilities','ProviderSearch','AnalyzeMedia'],'workspace.inspect':['ListDirectory','FileInfo']};
+const TEMPORARY=new Set([...ADMIN,...Object.values(SCOPED).flat()]);
+// Native artifact binding needs the tiny metadata/hash contract on the initial
+// surface. Search/acquire may still describe it; a lease never grants permission.
+const BASE_READS = new Set(['FileInfo']);
+const packEffects = { workspace: 'unknown', external: 'unknown', process: 'unknown', authority: 'none' };
+export class ToolPacks {
+  constructor({ store, house, ensureBrowser, pinned = () => [], serverStates = () => [], refreshCatalogue }) { Object.assign(this, { store, house, ensureBrowser, pinned, serverStates, refreshCatalogue }); this.views = new Map(); }
+  key(sessionId, actor) { return JSON.stringify([sessionId,actor.kind,actor.id]); }
+  scoped(name){return !BASE_READS.has(name) && (name.startsWith('mcp__') || TEMPORARY.has(name) || this.house.registry.get(name)?.contract.origin?.tool_loading === 'deferred');}
+  catalogue(actor) { return this.house.registry.catalogue({ actor, surface: 'agent' }).filter(op => this.scoped(op.name) || BASE_READS.has(op.name)); }
+  inPack(op, pack) { return Boolean(op) && (SCOPED[pack] ? SCOPED[pack].includes(op.name) : pack === 'house.audit' ? ADMIN.includes(op.name) : ['browser.verify','browser.capture'].includes(pack) ? (pack === 'browser.verify' ? BROWSER : CAPTURE).some(name => op.name === 'mcp__chrome-devtools__'+name) : pack.startsWith('plugin:') ? op.origin?.plugin === pack.slice(7) && op.origin?.tool_loading === 'deferred' : pack.startsWith('mcp:') && (op.origin?.kind === 'mcp' ? op.origin.server === pack.slice(4) : op.name.startsWith('mcp__'+pack.slice(4)+'__'))); }
+  offers(actor) {
+    const all = this.catalogue(actor), servers = new Map(), plugins = new Map();
+    for (const op of all) { const server = op.origin?.kind === 'mcp' ? op.origin.server : /^mcp__(.+?)__/.exec(op.name)?.[1]; if (server) { if (!servers.has(server)) servers.set(server, []); servers.get(server).push(op); } }
+    for (const op of all) if (op.origin?.plugin && op.origin.tool_loading === 'deferred') { if (!plugins.has(op.origin.plugin)) plugins.set(op.origin.plugin, []); plugins.get(op.origin.plugin).push(op); }
+    const browser = BROWSER.map(name => all.find(op => op.name === 'mcp__chrome-devtools__' + name)).filter(Boolean);
+    return [{ id: 'browser.verify', available: browser.length === BROWSER.length, count: browser.length, purpose: 'DOM, console, network and navigation; execution still judged.' },
+      { id: 'browser.capture', available: all.some(op => op.name === 'mcp__chrome-devtools__take_screenshot'), count: all.filter(op => this.inPack(op,'browser.capture')).length, purpose: 'Screenshot pixels in accepted receipts. Vision adapter sends only to a capable model; capture is not a visual verdict. Omit filePath to request inline image content.' },
+      { id: 'house.audit', available: all.some(op=>ADMIN.includes(op.name)), count: all.filter(op=>ADMIN.includes(op.name)).length, purpose: 'Full forensic views; projected state and EvidenceRead already suffice for normal work.' },
+      ...Object.entries(SCOPED).map(([id,names])=>({id,available:all.some(op=>names.includes(op.name)),count:all.filter(op=>names.includes(op.name)).length,purpose:id==='sessions.peers'?'Discover/message live sessions by provider capability; no authority transfer.':id==='workspace.inspect'?'List directory and inspect file size/media signature without shell.':'Current provider native search/image/video tools where supported.'})),
+      ...[...servers].map(([server, tools]) => ({ id: 'mcp:' + server, available: true, count: tools.length, purpose: 'Search or select up to 12 exact names with ToolPack; omit tools only when count <=12.' })),
+      ...[...plugins].map(([id, tools]) => ({ id: 'plugin:' + id, available: true, count: tools.length, purpose: tools[0].origin.discovery?.description || 'Search or select deferred plugin operations; acquisition grants no permission.' }))];
+  }
+  async prepare(sessionId, actor) {
+    const session = await this.store.load(sessionId), work = workProjection(session), all = this.catalogue(actor), byName = new Map(all.map(op => [op.name,op]));
+    let leases = new Map(), turn;
+    for (const row of session.rows) {
+      if (row.type === 'reset') { leases.clear(); turn = undefined; }
+      if (row.type === 'tool_turn' && row.source === 'capability_host' && row.actor?.id === actor.id && row.actor?.kind === actor.kind) turn = row.open ? row.id : undefined;
+      if (row.type !== 'tool_pack_lease' || row.source !== 'capability_host' || row.actor?.id !== actor.id || row.actor?.kind !== actor.kind) continue;
+      if (row.action === 'release') leases.delete(row.pack); else leases.set(row.pack, row);
+    }
+    const pinned = new Set(this.pinned().filter(name=>byName.has(name))), visible = new Set(pinned), tokens = new Map([...pinned].map(name=>[name,'pinned'])), active = [], expired = [], expiredDetails = [];
+    for (const lease of leases.values()) {
+      const originPlan = lease.task_id ? session.rows.findLast(row => ['work_plan_set','work_checks_repaired'].includes(row.type) && row.source === 'work_host' && row.version === lease.plan_version) : null;
+      const generation = lease.work_digest || workDigest(originPlan?.tasks.find(task => task.id === lease.task_id));
+      const scopeValid = lease.task_id ? generation && workDigest(work?.current) === generation && work.current?.id === lease.task_id && ['pending','in_progress','needs_verification'].includes(work.current.status) : turn && turn === lease.turn_id;
+      const contractValid = lease.tools.every(tool => byName.get(tool.name)?.contract_digest === tool.digest);
+      if (!scopeValid || !contractValid) { expired.push(lease.pack); expiredDetails.push({pack:lease.pack,task_id:lease.task_id || null,reason:!scopeValid?'scope_changed':'contracts_changed'}); continue; }
+      lease.tools.forEach(tool => { visible.add(tool.name); if(!pinned.has(tool.name)) tokens.set(tool.name,(tokens.get(tool.name)||'')+':'+lease.audit.sha256); }); active.push({ id: lease.pack, tools: lease.tools.map(tool => tool.name), task_id: lease.task_id || null });
+    }
+    const view = { visible, tokens, turn, work, state: { offers: this.offers(actor), required: work?.current?.capabilities || [], active, pinned: this.pinned().filter(name => byName.has(name)), expired, expired_details:expiredDetails, acquisition_grants_permission: false } };
+    this.views.set(this.key(sessionId,actor), view); return view.state;
+  }
+  recoveryCall(operation, actor) {
+    const op = this.catalogue(actor).find(item=>item.name===operation); if (!op) return;
+    const pack = this.offers(actor).find(offer=>offer.available && ['browser.verify','browser.capture','house.audit',...Object.keys(SCOPED)].includes(offer.id) && this.inPack(op,offer.id));
+    return {name:'ToolPack',input:{action:'acquire',pack:pack?.id || (op.origin?.tool_loading === 'deferred' ? 'plugin:'+op.origin.plugin : 'mcp:'+(op.origin?.server || /^mcp__(.+?)__/.exec(operation)?.[1])),...(!pack?{tools:[operation]}:{})}};
+  }
+  unavailable(operation, context) {
+    if (this.visible(operation,context.sessionId,context.actor)) return;
+    const recovery = this.recoveryCall(operation,context.actor); if (!recovery) return;
+    return {code:'TOOL_PACK_REQUIRED',message:`Herramienta no disponible: pack no adquirido o expirado para esta etapa/actor. No se ejecutó; no es una denegación del permiso de la operación. Ejecuta recovery_call y espera el siguiente catálogo: ${JSON.stringify(recovery)}. Los permisos se juzgan por separado.`};
+  }
+  async notifyChanges(sessionId, actor) {
+    const state = await this.prepare(sessionId,actor), session = await this.store.load(sessionId), view = this.views.get(this.key(sessionId,actor));
+    const reset = session.rows.findLastIndex(row=>row.type==='reset');
+    const previous = session.rows.slice(reset+1).findLast(row=>row.type==='message' && row.source==='capability_host' && row.capability_delta?.actor_id===actor.id && row.capability_delta?.actor_kind===actor.kind)?.capability_delta;
+    const stateDigest = digest({task:view.work?.current?.id,required:state.required,active:state.active,expired:state.expired_details,pinned:state.pinned,offers:state.offers,contracts:this.catalogue(actor).filter(op=>view.visible.has(op.name)).map(op=>[op.name,op.contract_digest])});
+    if (previous?.state_digest===stateDigest || !previous && !state.required.length && !state.active.length && !state.expired.length) return state;
+    const recover = new Map(), add = call=>{
+      if(!call)return;
+      const key=call.name+':'+call.input.action+':'+call.input.pack, old=recover.get(key);
+      if(old && !old.input.tools)return;
+      if(old?.input.tools && call.input.tools){const tools=[...new Set([...old.input.tools,...call.input.tools])];if(tools.length<=12)recover.set(key,{...call,input:{...call.input,tools}});return;}
+      recover.set(key,call);
+    };
+    for (const expiry of state.expired_details.filter(item=>item.reason==='contracts_changed')) {
+      const offer=state.offers.find(item=>item.id===expiry.pack && item.available);
+      const lease=session.rows.slice(reset+1).findLast(row=>row.type==='tool_pack_lease'&&row.pack===expiry.pack&&row.actor?.id===actor.id&&row.actor?.kind===actor.kind);
+      const selected=lease?.tools.filter(tool=>this.catalogue(actor).some(op=>op.name===tool.name&&this.inPack(op,expiry.pack))).map(tool=>tool.name) || [];
+      if(selected.length && selected.every(name=>state.pinned.includes(name)))continue;
+      if(offer && offer.count<=12)add({name:'ToolPack',input:{action:'acquire',pack:expiry.pack}});
+      else if(offer && selected.length && selected.length<=12)add({name:'ToolPack',input:{action:'acquire',pack:expiry.pack,tools:selected}});
+      else add({name:'ToolPack',input:{action:'list',pack:expiry.pack}});
+    }
+    for(const required of state.required) {
+      if(state.active.some(pack=>pack.id===required) || required.startsWith('mcp:') && (state.active.some(pack=>pack.tools.some(name=>name.startsWith('mcp__'+required.slice(4)+'__')))||state.pinned.some(name=>name.startsWith('mcp__'+required.slice(4)+'__'))))continue;
+      const requiredTools=this.catalogue(actor).filter(op=>this.inPack(op,required));if(requiredTools.length&&requiredTools.every(op=>state.pinned.includes(op.name)))continue;
+      const checks=view.work?.current?.checks || [], operations=checks.flatMap(check=>checkOperationCandidates(check.operation,this.catalogue(actor)));
+      const candidates=operations.filter(name=>required.startsWith('mcp:')?name.startsWith('mcp__'+required.slice(4)+'__'):this.inPack(this.catalogue(actor).find(op=>op.name===name),required));
+      for(const operation of candidates.slice(0,12))add(this.recoveryCall(operation,actor));
+      if(!candidates.length){const offer=state.offers.find(item=>item.id===required && item.available);add({name:'ToolPack',input:{action:offer && offer.count<=12?'acquire':'list',pack:required}});}
+    }
+    const ready=state.active.length>0 || state.pinned.length>0;
+    const delta={state_digest:stateDigest,actor_id:actor.id,actor_kind:actor.kind,task_id:view.work?.current?.id || null,availability:recover.size?'recovery_required':ready?'ready':'none',active:state.active.map(pack=>pack.id),pinned:state.pinned,expired:state.expired_details,...(recover.size?{recovery_calls:[...recover.values()]}:{}),grants_permission:false};
+    const instruction=recover.size?'Run recovery_calls alone and await the next catalogue before dependent calls.':ready?'Active pack schemas are AVAILABLE NOW in this request. No recovery or waiting is needed. Continue work with the offered tools.':'No recovery is pending. Continue with the tools offered in this request; do not wait for a catalogue update.';
+    await this.store.append(sessionId,{type:'message',source:'capability_host',capability_delta:delta,message:{role:'user',content:[{type:'text',text:'Comal runtime capability change. This supersedes historical pack availability only; keep conversation and completed work. '+instruction+' Do not rebuild the plan. No permission grant.\n'+JSON.stringify(delta)}]}});
+    return state;
+  }
+  visible(name, sessionId, actor) { return actor.kind === 'subagent' && SCOPED['workspace.inspect'].includes(name) || !this.scoped(name) || Boolean(this.views.get(this.key(sessionId,actor))?.visible.has(name)); }
+  capture(sessionId,actor) { return Object.fromEntries(this.views.get(this.key(sessionId,actor))?.tokens || []); }
+  sameFrame(name,sessionId,actor,stamp) { return this.visible(name,sessionId,actor) && stamp?.[name] === this.views.get(this.key(sessionId,actor))?.tokens.get(name); }
+  async guard({ operation, actor, session_id }) {
+    // Subagents already receive a fixed, small read-only catalogue. This is
+    // schema availability only: both permission policies still judge the call.
+    if (actor.kind === 'human' || actor.kind === 'subagent' && SCOPED['workspace.inspect'].includes(operation) || !this.scoped(operation)) return;
+    await this.prepare(session_id, actor);
+    if (!this.visible(operation,session_id,actor)) return { allowed: false, reason: 'Pack no adquirido o expirado para esta etapa/actor. Usa ToolPack; no se ejecutó.' };
+  }
+  async search(input, options) {
+    searchToolCatalog([], { ...input, inPack: () => false, acquireCall: () => undefined });
+    const states = () => this.serverStates().filter(item => item && typeof item.name === 'string').map(({ name, status }) => ({ name, status }));
+    const selected = input.pack?.startsWith('mcp:') ? input.pack.slice(4) : undefined;
+    let refresh;
+    if (selected && this.refreshCatalogue && states().some(item => item.name === selected && item.status === 'pending')) {
+      const controller = new AbortController(), signal = options.signal ? AbortSignal.any([controller.signal, options.signal]) : controller.signal;
+      let timer;
+      try {
+        await Promise.race([Promise.resolve().then(() => this.refreshCatalogue({ server: selected, signal, timeoutMs: 5000 })), new Promise((_, reject) => { timer = setTimeout(() => { controller.abort(); reject(Object.assign(new Error('Catalogue refresh deadline'), { code: 'TOOL_SEARCH_REFRESH_TIMEOUT' })); }, 5000); })]);
+        refresh = { server: selected, status: 'refreshed' };
+      } catch (error) { if (options.signal?.aborted) throw error; refresh = { server: selected, status: error.code === 'TOOL_SEARCH_REFRESH_TIMEOUT' ? 'timeout' : 'failed' }; }
+      finally { clearTimeout(timer); controller.abort(); }
+    }
+    options.signal?.throwIfAborted(); await this.prepare(options.sessionId, options.actor);
+    return { ...searchToolCatalog(this.catalogue(options.actor), { ...input, inPack: (op, pack) => this.inPack(op, pack), acquireCall: name => this.recoveryCall(name, options.actor) }), servers: states().filter(item => !selected || item.name === selected).slice(0, 12), ...(refresh ? { refresh } : {}) };
+  }
+  definition() {
+    return { name: 'ToolPack', description: 'Discover/acquire/release temporary schemas (browser.verify, browser.capture, mcp:SERVER, plugin:ID, house.audit, sessions.peers, provider.features, workspace.inspect). search with query returns <=5 ranked canonical tools and exact acquire_call; search does not acquire. list with pack returns its tool names; list without pack returns offers only. browser.capture supplies inline screenshots; browser.verify supplies navigation/DOM snapshot/console/network ONLY. For interaction acquire mcp:chrome-devtools with tools:["mcp__chrome-devtools__click"] or ["mcp__chrome-devtools__evaluate_script"] before use. Acquired schemas appear NEXT request. Select <=12 canonical names or unique short tool names scoped to that pack; the host returns canonical names. Missing server uses separate MCP config/connection judgment. No permission grant.',
+      effects: packEffects,
+      input_schema: { type: 'object', properties: { action: { type: 'string', enum: ['list','search','acquire','release'] }, query: { type: 'string', minLength: 1, maxLength: 500 }, max_results: { type: 'integer', minimum: 1, maximum: 5 }, pack: { type: 'string', maxLength: 100 }, tools: { type: 'array', minItems: 1, maxItems: 12, uniqueItems: true, items: { type: 'string', maxLength: 128 } } }, required: ['action'], additionalProperties: false },
+      run: async (input, options) => {
+        const { sessionId, actor } = options;
+        await this.prepare(sessionId,actor);
+        if (input.action === 'search') return JSON.stringify(await this.search(input, options));
+        if (input.action === 'list') return JSON.stringify({ ...this.views.get(this.key(sessionId,actor)).state, ...(input.pack ? { tools: this.catalogue(actor).filter(op => this.inPack(op,input.pack)).map(op => op.name) } : {}) });
+        if (!input.pack) throw new Error('ToolPack requiere pack.');
+        if (input.action === 'release') {
+          await options.recordWork({ type: 'tool_pack_lease', source: 'capability_host', action: 'release', pack: input.pack });
+          await this.prepare(sessionId,actor); return '{"released":true,"connection_closed":false}';
+        }
+        if (['browser.verify','browser.capture'].includes(input.pack) && !this.offers(actor).find(offer => offer.id === input.pack)?.available) {
+          if (!this.ensureBrowser) throw new Error(`${input.pack} requiere un proveedor Chrome MCP configurado.`);
+          await this.ensureBrowser(options);
+        }
+        await this.prepare(sessionId,actor);
+        const view = this.views.get(this.key(sessionId,actor)), all = this.catalogue(actor);
+        const available = all.filter(op => this.inPack(op,input.pack));
+        if (!available.length || input.pack === 'browser.verify' && available.length !== BROWSER.length) throw new Error('Pack no disponible: revisa configuración/conexión MCP.');
+        const selected = input.tools ? input.tools.map(name => {
+          const exact=available.find(op=>op.name===name);if(exact)return exact;
+          const matches=available.filter(op=>op.origin?.kind==='mcp' && op.origin.tool===name || op.name.endsWith('__'+name));
+          return matches.length===1?matches[0]:undefined;
+        }) : available;
+        if (selected.some(op => !op) || selected.length > 12) throw Object.assign(new Error('Selecciona hasta 12 nombres exactos o cortos únicos del pack. '+JSON.stringify({pack:input.pack,invalid_names:input.tools?.filter((_,i)=>!selected[i]),available_names:available.slice(0,40).map(op=>op.name),list_call:{name:'ToolPack',input:{action:'list',pack:input.pack}}})),{code:'TOOL_PACK_SELECTION_INVALID'});
+        const unique=[...new Map(selected.map(op=>[op.name,op])).values()];
+        if (!view.work?.current && !view.turn) throw new Error('Adquiere el pack dentro de un turno activo.');
+        if (view.work?.current?.status === 'blocked') throw new Error('La tarea está bloqueada.');
+        const held = new Set(view.state.active.filter(item => item.id !== input.pack).flatMap(item => item.tools));
+        unique.forEach(op => held.add(op.name)); if (held.size > 24) throw new Error('Máximo 24 herramientas temporales activas; libera otro pack.');
+        await options.recordWork({ type: 'tool_pack_lease', source: 'capability_host', action: 'acquire', pack: input.pack, task_id: view.work?.current?.id || null, plan_version: view.work?.plan.version || null, work_digest: workDigest(view.work?.current) || null, turn_id: view.turn || null, tools: unique.map(op => ({ name: op.name, digest: op.contract_digest })) });
+        await this.prepare(sessionId,actor);
+        return JSON.stringify({ acquired: input.pack, tools: unique.map(op => op.name), available_next_request: true, grants_permission: false });
+      },
+    };
+  }
+}

package/src/tool-scheduler.mjs

@@ -0,0 +1,21 @@
+import path from 'node:path';
+import {performance} from 'node:perf_hooks';
+import {realpath} from 'node:fs/promises';
+
+// Host-owned native operations only. Third-party hints never enter this rule.
+async function readResource(call,catalogue,cwd) {
+ const op=catalogue.find(item=>item.name===call.name),effects=op?.effects;
+ if(!['Read','FileInfo'].includes(call.name)||op?.origin!==null||op.permission!==call.name||effects?.workspace!=='read'||effects.external!=='none'||effects.process!=='none'||effects.authority!=='none'||typeof call.input?.file_path!=='string')return null;
+ try{return await realpath(path.resolve(cwd,call.input.file_path));}catch{return null;}
+}
+export async function scheduleToolCalls(calls,execute,{catalogue=[],cwd=process.cwd(),signal,concurrency=2,onGroup=async()=>{}}={}) {
+ if(!Number.isSafeInteger(concurrency)||concurrency<1||concurrency>4)throw new Error('Invalid native read concurrency');
+ const results=[];
+ for(let index=0;index<calls.length;){
+  signal?.throwIfAborted();const group=[calls[index++]],resources=new Set(),first=await readResource(group[0],catalogue,cwd);if(first)resources.add(first);
+  while(first&&group.length<concurrency&&index<calls.length){const resource=await readResource(calls[index],catalogue,cwd);if(!resource||resources.has(resource))break;resources.add(resource);group.push(calls[index++]);}
+  const start=performance.now();results.push(...await Promise.all(group.map(execute)));
+  await onGroup({type:'tool_schedule',version:1,classification:group.length>1?'host_native_disjoint_reads':'serial',tool_call_ids:group.map(call=>call.id),concurrency:group.length,elapsed_ms:performance.now()-start});
+ }
+ return results;
+}

package/src/tool-schema.mjs

@@ -0,0 +1,51 @@
+import { digest } from './operations.mjs';
+
+const ANNOTATIONS = new Set(['$schema']);
+export function normalizeToolSchemaCapabilities(value) {
+  if (value === undefined) return {};
+  const allowed = ['supported_keywords', 'unsupported_keywords', 'dialects', 'omit_dialect_annotation', 'transport_dialect'];
+  const bad = () => { throw Object.assign(new Error('Capacidades de schema inválidas; requiere listas de keywords/dialects y configuración de dialecto explícita.'), { code: 'TOOL_SCHEMA_CAPABILITIES_INVALID' }); };
+  if (!value || typeof value !== 'object' || Array.isArray(value) || Object.keys(value).some(key => !allowed.includes(key))) bad();
+  for (const key of ['supported_keywords', 'unsupported_keywords', 'dialects']) if (value[key] !== undefined && (!Array.isArray(value[key]) || value[key].length > 128 || value[key].some(item => typeof item !== 'string' || !item || item.length > 200) || new Set(value[key]).size !== value[key].length)) bad();
+  if (value.omit_dialect_annotation !== undefined && typeof value.omit_dialect_annotation !== 'boolean' || value.transport_dialect !== undefined && (typeof value.transport_dialect !== 'string' || !value.transport_dialect || value.transport_dialect.length > 200)) bad();
+  return structuredClone(value);
+}
+const schemas = (node, path = '') => {
+  if (!node || typeof node !== 'object' || Array.isArray(node)) return [];
+  const result = Object.entries(node).map(([keyword, value]) => ({ keyword, value, path: path + '/' + keyword }));
+  for (const [keyword, value] of Object.entries(node)) {
+    if (['properties', 'patternProperties', '$defs', 'definitions', 'dependentSchemas'].includes(keyword) && value && typeof value === 'object') for (const [key, child] of Object.entries(value)) result.push(...schemas(child, path + '/' + keyword + '/' + key));
+    else if (['items', 'additionalItems', 'additionalProperties', 'unevaluatedProperties', 'unevaluatedItems', 'contains', 'propertyNames', 'not', 'if', 'then', 'else'].includes(keyword)) {
+      if (Array.isArray(value)) value.forEach((child, i) => result.push(...schemas(child, path + '/' + keyword + '/' + i))); else result.push(...schemas(value, path + '/' + keyword));
+    } else if (['allOf', 'anyOf', 'oneOf', 'prefixItems'].includes(keyword) && Array.isArray(value)) value.forEach((child, i) => result.push(...schemas(child, path + '/' + keyword + '/' + i)));
+  }
+  return result;
+};
+
+// A transport may remove dialect metadata only under an explicit identical dialect, never assertions.
+// Missing capability information is explicitly unverified passthrough, not an invented guarantee.
+export function compileToolSchemas(tools, { provider = 'unknown', capabilities = {}, catalogue = [] } = {}) {
+  const policy = normalizeToolSchemaCapabilities(capabilities.tool_schema), diagnostics = [], manifest = [];
+  const compiled = tools.map(tool => {
+    if (!tool?.input_schema || typeof tool.input_schema !== 'object' || Array.isArray(tool.input_schema)) throw Object.assign(new Error('Definición de herramienta sin schema de entrada válido; no se envió al proveedor.'), { code: 'TOOL_SCHEMA_UNSUPPORTED', details: { provider, diagnostics: [{ name: tool?.name || null, status: 'unsupported', rejected: [{ path: '/', reason: 'missing_or_invalid_input_schema' }] }], executed: false } });
+    const upstream = tool.input_schema, canonical = structuredClone(upstream), transport = structuredClone(canonical);
+    const entries = schemas(transport), rejected = [];
+    if (policy.dialects && canonical.$schema && !policy.dialects.includes(canonical.$schema)) rejected.push({ keyword: '$schema', path: '/$schema', reason: 'dialect_not_supported', value: canonical.$schema });
+    for (const entry of entries) {
+      if (ANNOTATIONS.has(entry.keyword) && policy.omit_dialect_annotation && policy.transport_dialect === canonical.$schema) continue;
+      if (policy.unsupported_keywords?.includes(entry.keyword) || policy.supported_keywords && !policy.supported_keywords.includes(entry.keyword)) rejected.push({ keyword: entry.keyword, path: entry.path, reason: 'keyword_not_supported' });
+    }
+    const transforms = [];
+    if (Object.hasOwn(transport, '$schema') && policy.omit_dialect_annotation) {
+      if (policy.transport_dialect !== transport.$schema) rejected.push({ keyword: '$schema', path: '/$schema', reason: 'cannot_remove_dialect_without_identical_transport_dialect' });
+      else { delete transport.$schema; transforms.push({ path: '/$schema', action: 'omit_identical_dialect_annotation', changes_validation: false }); }
+    }
+    const status = rejected.length ? 'unsupported' : policy.supported_keywords || policy.unsupported_keywords || policy.dialects ? 'compatible_with_declared_capabilities' : 'unverified_passthrough';
+    diagnostics.push({ name: tool.name, provider, status, transforms, rejected, authority: 'transport_compatibility_only' });
+    const contract = catalogue.find(item => item.name === tool.name);
+    manifest.push({ name: tool.name, provider, upstream_schema_digest: contract?.origin?.schema_provenance?.upstream_digest || null, canonical_schema_digest: contract?.input_schema ? digest(contract.input_schema) : null, offered_schema_digest: digest(canonical), transport_schema_digest: digest(transport), status });
+    return { ...tool, input_schema: transport };
+  });
+  if (diagnostics.some(item => item.status === 'unsupported')) throw Object.assign(new Error('El proveedor no admite el schema de herramientas; no se enviaron ni debilitaron restricciones. ' + diagnostics.filter(item => item.status === 'unsupported').map(item => item.name).join(', ')), { code: 'TOOL_SCHEMA_UNSUPPORTED', details: { provider, diagnostics, manifest, executed: false } });
+  return { tools: compiled, diagnostics, manifest };
+}

package/src/tools.mjs

@@ -0,0 +1,310 @@
+import { readFile, writeFile, rename, unlink, mkdir, realpath, stat, readdir, opendir, open } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { createHash, randomUUID } from 'node:crypto';
+import { House } from './house.mjs';
+import { readOnlyBashCheck } from './read-only-check.mjs';
+import { auditExecution } from './audit.mjs';
+import { digest } from './operations.mjs';
+import { recoverFileEffects } from './file-recovery.mjs';
+
+const LIMIT = 64 * 1024, FILE_LIMIT = 1024 * 1024;
+const HASH_LIMIT = 256 * 1024 * 1024, HASH_CHUNK = 128 * 1024, HASH_TIMEOUT = 10000;
+const hash = text => createHash('sha256').update(text).digest('hex');
+const schema = (name, description, properties, required) => ({ name, description, input_schema: { type: 'object', properties, required, additionalProperties: false } });
+const str = description => ({ type: 'string', description });
+export const toolDefinitions = [
+  schema('Read', 'Read missing/outdated UTF-8 file ranges with line numbers. Verified file_working_set pages already provide inspection: do not reread covered code just to satisfy an edit prerequisite.', { file_path: str('Workspace-relative or absolute path'), offset: { type: 'integer', minimum: 1 }, limit: { type: 'integer', minimum: 1, maximum: 2000 } }, ['file_path']),
+  schema('Write', 'Create/replace a UTF-8 file. Inspect existing bytes via Read or verified file_working_set. The host checks own read/write evidence against live bytes before replacing.', { file_path: str('File path'), content: str('Complete new content') }, ['file_path', 'content']),
+  schema('Edit', 'Replace an exact string in inspected code (Read or verified file_working_set). Own receipt and live hash are checked by the host. Must be unique unless replace_all is true.', { file_path: str('File path'), old_string: str('Exact nonempty text'), new_string: str('Replacement'), replace_all: { type: 'boolean' } }, ['file_path', 'old_string', 'new_string']),
+  schema('Glob', 'List workspace files matching *, ** or ?; omits .git, .comal, .harness, .analysis and node_modules.', { pattern: str('Example: src/**/*.mjs') }, ['pattern']),
+  schema('Grep', 'Search workspace text with ripgrep regular expressions.', { pattern: str('Regular expression'), path: str('Workspace path; defaults to .'), glob: str('Optional file glob') }, ['pattern']),
+  schema('ListDirectory', 'List one workspace directory without shell. Returns bounded names/types, not file contents; omits internal state. Use Glob for recursive matches.', { path: str('Workspace directory; defaults to .'), limit: { type: 'integer', minimum: 1, maximum: 1000 } }, []),
+  schema('FileInfo', 'Inspect workspace file size/type and media signature without shell. By default reads at most 32 signature bytes. Set hash:true for bounded binary-safe full-file SHA-256 evidence (up to 256 MiB, 10 seconds); emits a file_read observation but grants no text inspection for editing. Does not decode media: send images/video directly to AnalyzeMedia.', { file_path: str('Workspace-relative or absolute path'), hash: { type: 'boolean', description: 'Stream the complete regular file to compute SHA-256 without returning contents.' } }, ['file_path']),
+  schema('Bash', 'Run a shell command from the workspace after permission. This is NOT an OS sandbox.', { command: str('Shell command'), timeout: { type: 'integer', minimum: 1, maximum: 120000 } }, ['command']),
+];
+
+function validate(name, input) {
+  const definition = toolDefinitions.find(t => t.name === name);
+  if (!definition) throw new Error(`Unknown tool: ${name}`);
+  if (!input || typeof input !== 'object' || Array.isArray(input)) throw new Error('Input must be an object.');
+  for (const key of definition.input_schema.required) if (!(key in input)) throw new Error(`Missing ${key}.`);
+  for (const [key, value] of Object.entries(input)) {
+    const spec = definition.input_schema.properties[key];
+    if (!spec) throw new Error(`Unknown field: ${key}`);
+    if (spec.type === 'integer' ? !Number.isInteger(value) : typeof value !== spec.type) throw new Error(`Invalid type for ${key}.`);
+    if (spec.type === 'integer' && (value < spec.minimum || value > (spec.maximum ?? Number.MAX_SAFE_INTEGER))) throw new Error(`${key} is out of range.`);
+    if (typeof value === 'string' && Buffer.byteLength(value) > FILE_LIMIT) throw new Error(`${key} exceeds 1 MiB.`);
+  }
+}
+
+export class WorkspaceTools {
+  constructor({ cwd, policy, store, onPermission = () => {}, house = new House({ cwd }), actor = { id: 'local-agent', kind: 'agent' }, sessionId, record, select, frontier, capture, unavailable }) {
+    this.cwd = cwd; this.policy = policy; this.onPermission = onPermission; this.reads = new Map(); this.house = house;
+    this.store = store;
+    for (const definition of toolDefinitions) if (!house.registry.get(definition.name)) house.registry.add({ ...definition, run: (input, options) => (options.workspace || this).#run(definition.name, input, options) });
+    this.executor = house.bind({ actor, sessionId, policy, onPermission, record, resources: { workspace: this }, select, frontier, capture, unavailable });
+    this.executor.recoverInterrupted = options => this.recoverInterrupted(options);
+    this.recoverySessionId = sessionId; this.recoveryActor = actor;
+  }
+  setContext(context) { this.executor.setContext(context); }
+  getMode() { return this.executor.getMode(); }
+  snapshot() { return this.executor.snapshot(); }
+  execute(name, input, options) { return this.executor.execute(name, input, options); }
+  recoverInterrupted({signal,session}={}) { return this.store && this.house.hasRecorder ? recoverFileEffects({store:this.store,house:this.house,executor:this.executor,sessionId:typeof this.recoverySessionId==='function'?this.recoverySessionId():this.recoverySessionId,actor:this.recoveryActor,signal,session}) : undefined; }
+  inside(file) { const relative = path.relative(this.cwd, file); return relative === '' || (!relative.startsWith(`..${path.sep}`) && relative !== '..' && !path.isAbsolute(relative)); }
+  async resolve(file, { create = false } = {}) {
+    if (!file || file.includes('\0')) throw new Error('Invalid path.');
+    const candidate = path.resolve(this.cwd, file);
+    if (!this.inside(candidate)) throw new Error('Path outside the workspace.');
+    let canonical;
+    try { canonical = await realpath(candidate); }
+    catch (e) {
+      if (!create || e.code !== 'ENOENT') throw e;
+      let ancestor = path.dirname(candidate), suffix = [path.basename(candidate)];
+      while (true) {
+        try { canonical = path.join(await realpath(ancestor), ...suffix); break; }
+        catch (err) { if (err.code !== 'ENOENT') throw err; suffix.unshift(path.basename(ancestor)); ancestor = path.dirname(ancestor); }
+      }
+    }
+    if (!this.inside(canonical)) throw new Error('The symbolic link leaves the workspace.');
+    const first = path.relative(this.cwd, canonical).split(path.sep)[0];
+    if (['.comal', '.harness'].includes(first)) throw new Error('Comal internal state is protected.');
+    return canonical;
+  }
+  async text(file) {
+    const info = await stat(file);
+    if (!info.isFile() || info.size > FILE_LIMIT) throw new Error('A text file of at most 1 MiB is required.');
+    const buffer = await readFile(file);
+    if (buffer.includes(0)) throw Object.assign(new Error('Text Read does not support binary files. This does not deny permission to analyze media.'),{code:'READ_BINARY'});
+    try{return new TextDecoder('utf-8', { fatal: true }).decode(buffer);}
+    catch(error){throw Object.assign(new Error('The file is not UTF-8 text; Read does not decode images or video. This does not deny AnalyzeMedia permission.'),{code:'READ_BINARY',cause:error});}
+  }
+  async atomicWrite(file, content) {
+    await mkdir(path.dirname(file), { recursive: true });
+    // Recheck the canonical parent after creating directories.
+    const target = await this.resolve(file, { create: true });
+    if (target !== file) throw new Error('The path changed during the operation.');
+    let mode = 0o644; try { mode = (await stat(file)).mode & 0o777; } catch (e) { if (e.code !== 'ENOENT') throw e; }
+    const temp = path.join(path.dirname(file), `.comal-write-${randomUUID()}`);
+    try { await writeFile(temp, content, { flag: 'wx', mode }); await rename(temp, file); }
+    finally { await unlink(temp).catch(() => {}); }
+    this.reads.set(file, hash(content));
+  }
+  async #run(name, input, { signal, actor, sessionId, observe = () => {}, recordWork = async () => {} } = {}) {
+    validate(name, input); signal?.throwIfAborted();
+    if (name === 'ListDirectory') {
+      const dir = await this.resolve(input.path || '.'), entries = []; let truncated = false, bytes = 0;
+      for await (const entry of await opendir(dir)) {
+        signal?.throwIfAborted();
+        if (['.git', '.comal', '.harness', '.analysis'].includes(entry.name)) continue;
+        const item = { name: entry.name, type: entry.isSymbolicLink() ? 'symlink' : entry.isDirectory() ? 'directory' : entry.isFile() ? 'file' : 'other' };
+        bytes += Buffer.byteLength(JSON.stringify(item)) + 1;
+        if (entries.length >= (input.limit ?? 200) || bytes > LIMIT - 8192) { truncated = true; break; }
+        entries.push(item);
+      }
+      entries.sort((a, b) => a.name.localeCompare(b.name));
+      const relative = path.relative(this.cwd, dir) || '.';
+      observe({ kind: 'directory_listing', file_path: relative, count: entries.length, truncated });
+      return JSON.stringify({ path: relative, entries, truncated });
+    }
+    if (name === 'FileInfo') {
+      const file = await this.resolve(input.file_path), info = await stat(file, input.hash ? { bigint: true } : undefined);
+      if (input.hash) {
+        const hashed = await hashWorkspaceFile(file, { signal, expected: info, verifyPath: async () => {
+          if (await this.resolve(input.file_path) !== file) throw fileHashError('The file path changed while hashing. Retry FileInfo.', 'FILE_HASH_CHANGED');
+        } });
+        const result = { file_path: path.relative(this.cwd, file), type: 'file', bytes: hashed.bytes,
+          modified_at: new Date(Number(hashed.info.mtimeMs)).toISOString(), mime_type: hashed.mimeType,
+          mime_source: hashed.mimeType ? 'signature' : null, sha256: hashed.sha256 };
+        observe({ kind: 'file_metadata', ...result });
+        observe({ kind: 'file_read', file_path: result.file_path, sha256: result.sha256, bytes: result.bytes });
+        return JSON.stringify(result);
+      }
+      let mimeType = null;
+      if (info.isFile()) {
+        const handle = await open(file, 'r');
+        try {
+          signal?.throwIfAborted();
+          const buffer = Buffer.alloc(32), { bytesRead } = await handle.read(buffer, 0, buffer.length, 0);
+          mimeType = mediaSignature(buffer.subarray(0, bytesRead));
+        } finally { await handle.close(); }
+      }
+      const result = { file_path: path.relative(this.cwd, file), type: info.isFile() ? 'file' : info.isDirectory() ? 'directory' : 'other', bytes: info.size, modified_at: info.mtime.toISOString(), mime_type: mimeType, mime_source: mimeType ? 'signature' : null };
+      observe({ kind: 'file_metadata', ...result });
+      return JSON.stringify(result);
+    }
+    if (name === 'Read') {
+      const file = await this.resolve(input.file_path), text = await this.text(file);
+      this.reads.set(file, hash(text));
+      observe({ kind: 'file_read', file_path: path.relative(this.cwd, file), sha256: hash(text) });
+      const offset = input.offset ?? 1, count = input.limit ?? 400;
+      return text.split('\n').slice(offset - 1, offset - 1 + count).map((line, i) => `${offset + i}\t${line}`).join('\n').slice(0, LIMIT);
+    }
+    if (name === 'Write' || name === 'Edit') {
+      const file = await this.resolve(input.file_path, { create: name === 'Write' });
+      let before = null;
+      try { before = await this.text(file); } catch (e) { if (e.code !== 'ENOENT' || name === 'Edit') throw e; }
+      if (before !== null && this.reads.get(file) !== hash(before) && this.store && sessionId) {
+        const audit = auditExecution(await this.store.load(sessionId), this.house.stateContext()), relative = path.relative(this.cwd, file), currentHash = hash(before);
+        // Recover only this actor's own read/write proof, still matched against
+        // the live bytes. A cached projection alone never authorizes an edit.
+        const proof = audit.journal.consistent && audit.state.find(item => item.path === relative)?.sha256 === currentHash && audit.receipts.findLast(receipt => receipt.status === 'returned' && ['Read', 'Write', 'Edit'].includes(receipt.operation) && receipt.actor?.id === actor?.id && receipt.actor?.kind === actor?.kind && !audit.violations.some(item => item.invocation_id === receipt.invocation_id) && !audit.unverified.some(item => item.invocation_id === receipt.invocation_id) && receipt.observations?.some(item => item.file_path === relative && (item.sha256 || item.after_sha256) === currentHash));
+        if (proof) this.reads.set(file, currentHash);
+      }
+      if (before !== null && this.reads.get(file) !== hash(before)) throw new Error('Read the file before modifying it; it may have changed since the last read.');
+      let after = input.content;
+      if (name === 'Edit') {
+        if (!input.old_string) throw new Error('old_string cannot be empty.');
+        const count = before.split(input.old_string).length - 1;
+        if (!count || (count > 1 && !input.replace_all)) throw new Error(`old_string appears ${count} times; use unique text or replace_all.`);
+        after = input.replace_all ? before.split(input.old_string).join(input.new_string) : before.replace(input.old_string, () => input.new_string);
+      }
+      if (Buffer.byteLength(after) > FILE_LIMIT) throw new Error('The result exceeds 1 MiB.');
+      const output=JSON.stringify({ file_path: path.relative(this.cwd, file), status: before === null ? 'created' : 'updated', bytes: Buffer.byteLength(after), before_sha256: before === null ? null : hash(before), after_sha256: hash(after), ...(name === 'Edit' ? { removed: input.old_string.slice(0, 1000), added: input.new_string.slice(0, 1000) } : {}) });
+      // Durable preparation is a prerequisite of the replacement, not a receipt
+      // claiming that the handler returned. Recovery can only observe its target.
+      const preparation={mechanism:'workspace-file-v1',operation:name,arguments_digest:digest(input),file_path:path.relative(this.cwd,file),before_sha256:before===null?null:hash(before),after_sha256:hash(after),output};
+      await recordWork({type:'file_effect_prepared',source:'workspace_host',preparation,preparation_digest:digest(preparation)});
+      await this.atomicWrite(file, after);
+      // Read back independently; a handler return value is not a verified write.
+      const observed = await this.text(file);
+      observe({ kind: 'file_write', file_path: path.relative(this.cwd, file), before_sha256: before === null ? null : hash(before), after_sha256: hash(observed), matches_requested: observed === after });
+      await recordWork({type:'file_effect_observed',source:'workspace_host',preparation_digest:digest(preparation),sha256:hash(observed),matches_requested:observed===after});
+      return output;
+    }
+    if (name === 'Bash') {
+      const check = readOnlyBashCheck(input.command);
+      if (!check) return runProcess('/bin/sh', ['-c', input.command], { cwd: this.cwd, timeout: input.timeout ?? 30000, signal });
+      const files = new Map();
+      for (const name of check.files) { const file = await this.resolve(name); files.set(name, { file, before: hash(await this.text(file)) }); }
+      let output = '';
+      for (const step of check.steps) {
+        if (step.kind === 'echo') output += step.text + '\n';
+        else {
+          let text;
+          try { text = await runProcess('/usr/bin/grep', [...step.flags, '--', step.pattern, files.get(step.file).file], { cwd: this.cwd, timeout: input.timeout ?? 30000, signal }); }
+          catch (error) { if (error.message.startsWith('Command exited with code 1:')) throw Object.assign(new Error(`${error.message} Pattern ${JSON.stringify(step.pattern)} did not match in ${JSON.stringify(step.file)}. Implement the criterion behavior; a text match is only a basic check.`), { code: 'CHECK_FAILED' }); throw error; }
+          if (text !== '(no output)') output += text;
+        }
+      }
+      for (const { file, before } of files.values()) { const after = hash(await this.text(file)); if (after !== before) throw new Error('The file changed during the check; verify again.'); observe({ kind: 'file_read', file_path: path.relative(this.cwd, file), sha256: after }); }
+      return output || '(no output)';
+    }
+    if (name === 'Grep') {
+      const target = await this.resolve(input.path || '.');
+      return runProcess('rg', ['--line-number', '--no-heading', '--color', 'never', '--max-count', '100', '--glob', '!.comal/**', '--glob', '!.harness/**', '--glob', '!.analysis/**', ...(input.glob ? ['--glob', input.glob] : []), '--', input.pattern, target], { cwd: this.cwd, timeout: 10000, signal, allowNoMatch: true });
+    }
+    if (name === 'Glob') {
+      if (path.isAbsolute(input.pattern) || input.pattern.split('/').includes('..')) throw new Error('Glob must be relative to the workspace.');
+      const pattern = input.pattern.replace(/^\.\//, ''), matcher = globRegex(pattern), files = []; let visited = 0;
+      const walk = async (dir, depth = 0) => {
+        if (depth > 30) return;
+        for (const entry of await readdir(dir, { withFileTypes: true })) {
+          signal?.throwIfAborted();
+          if (++visited > 20000) throw new Error('Glob exceeded 20000 entries; use Grep or a smaller workspace.');
+          if (['.git', '.comal', '.harness', '.analysis', 'node_modules'].includes(entry.name)) continue;
+          const file = path.join(dir, entry.name), relative = path.relative(this.cwd, file).split(path.sep).join('/');
+          if (entry.isDirectory()) await walk(file, depth + 1);
+          else if (entry.isFile() && matcher.test(relative)) files.push(relative);
+        }
+      };
+      await walk(this.cwd);
+      return files.sort().slice(0, 1000).join('\n') || '(no matches)';
+    }
+  }
+}
+
+const fileHashError = (message, code) => Object.assign(new Error(message), { code });
+const sameFileVersion = (left, right) => ['dev', 'ino', 'size', 'mtimeNs', 'ctimeNs'].every(key => left[key] === right[key]);
+async function hashWorkspaceFile(file, { signal, expected, verifyPath }) {
+  const deadline = AbortSignal.timeout(HASH_TIMEOUT), combined = signal ? AbortSignal.any([signal, deadline]) : deadline;
+  const check = () => {
+    signal?.throwIfAborted();
+    if (deadline.aborted) throw fileHashError('File hashing exceeded 10 seconds. Try a smaller artifact.', 'FILE_HASH_TIMEOUT');
+  };
+  let handle, stream;
+  try {
+    check();
+    handle = await open(file, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    const before = await handle.stat({ bigint: true });
+    if (!before.isFile()) throw fileHashError('Hashing requires a regular file.', 'FILE_HASH_TYPE');
+    if (before.size > BigInt(HASH_LIMIT)) throw fileHashError('File hashing supports at most 256 MiB.', 'FILE_HASH_LIMIT');
+    if (before.dev !== BigInt(expected.dev) || before.ino !== BigInt(expected.ino)) throw fileHashError('The file changed before hashing. Retry FileInfo.', 'FILE_HASH_CHANGED');
+    await verifyPath();
+    if (!sameFileVersion(before, await stat(file, { bigint: true }))) throw fileHashError('The file changed before hashing. Retry FileInfo.', 'FILE_HASH_CHANGED');
+    const digest = createHash('sha256'); let bytes = 0, signature = Buffer.alloc(0);
+    stream = handle.createReadStream({ highWaterMark: HASH_CHUNK, autoClose: false, signal: combined });
+    for await (const chunk of stream) {
+      check(); bytes += chunk.length;
+      if (bytes > HASH_LIMIT) throw fileHashError('File hashing supports at most 256 MiB.', 'FILE_HASH_LIMIT');
+      if (signature.length < 32) signature = Buffer.concat([signature, chunk.subarray(0, 32 - signature.length)]);
+      digest.update(chunk);
+    }
+    check();
+    const after = await handle.stat({ bigint: true }); await verifyPath();
+    if (!sameFileVersion(before, after) || !sameFileVersion(before, await stat(file, { bigint: true })) || BigInt(bytes) !== before.size) throw fileHashError('The file changed while hashing. Retry FileInfo.', 'FILE_HASH_CHANGED');
+    check(); return { bytes, sha256: digest.digest('hex'), mimeType: mediaSignature(signature), info: after };
+  } catch (error) {
+    check();
+    if (error.code === 'ELOOP') throw fileHashError('The file changed to a symbolic link before hashing.', 'FILE_HASH_CHANGED');
+    throw error;
+  } finally { stream?.destroy(); await handle?.close(); }
+}
+
+function mediaSignature(bytes) {
+  if (bytes.length >= 3 && bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff) return 'image/jpeg';
+  if (bytes.subarray(0, 8).equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]))) return 'image/png';
+  if (bytes.toString('ascii', 0, 4) === 'RIFF' && bytes.toString('ascii', 8, 12) === 'WEBP') return 'image/webp';
+  if (['GIF87a', 'GIF89a'].includes(bytes.toString('ascii', 0, 6))) return 'image/gif';
+  if (bytes.length >= 12 && bytes.toString('ascii', 4, 8) === 'ftyp') {
+    const brand = bytes.toString('ascii', 8, 12);
+    if (brand === 'qt  ') return 'video/quicktime';
+    if (/^(?:isom|iso[2-9]|mp4[12]|avc1|M4V |dash)$/.test(brand)) return 'video/mp4';
+  }
+  return null;
+}
+
+function globRegex(pattern) {
+  let source = '^';
+  for (let i = 0; i < pattern.length; i++) {
+    const c = pattern[i];
+    if (c === '*' && pattern[i + 1] === '*') { i++; if (pattern[i + 1] === '/') { i++; source += '(?:.*/)?'; } else source += '.*'; }
+    else if (c === '*') source += '[^/]*';
+    else if (c === '?') source += '[^/]';
+    else source += c.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  }
+  return new RegExp(source + '$');
+}
+
+export function runProcess(command, args, { cwd, timeout = 30000, signal, allowNoMatch = false }) {
+  return new Promise((resolve, reject) => {
+    signal?.throwIfAborted();
+    const child = spawn(command, args, { cwd, detached: true, stdio: ['ignore', 'pipe', 'pipe'] });
+    let output = '', truncated = false, failure, killTimer;
+    const terminate = reason => {
+      if (failure) return; failure = reason;
+      try { process.kill(-child.pid, 'SIGTERM'); } catch {}
+      killTimer = setTimeout(() => { try { process.kill(-child.pid, 'SIGKILL'); } catch {} }, 200);
+    };
+    const receive = chunk => {
+      const available = LIMIT - output.length;
+      if (available > 0) output += chunk.toString().slice(0, available);
+      if (chunk.length > available) truncated = true;
+    };
+    child.stdout.on('data', receive); child.stderr.on('data', receive);
+    const timer = setTimeout(() => terminate(new Error(`Command exceeded ${timeout} ms.`)), timeout);
+    const abort = () => terminate(new Error('Comando cancelado.'));
+    signal?.addEventListener('abort', abort, { once: true });
+    const cleanup = () => { clearTimeout(timer); signal?.removeEventListener('abort', abort); };
+    child.once('error', err => { cleanup(); clearTimeout(killTimer); reject(err); });
+    child.once('close', code => {
+      cleanup();
+      // Leave the short kill timer alive after timeout to stop remaining descendants.
+      if (failure) reject(failure);
+      else if (code !== 0 && !(allowNoMatch && code === 1)) reject(new Error(`Command exited with code ${code}: ${output}`));
+      else resolve(output + (truncated ? '\n[Output limited to 64 KiB]' : '') || '(no output)');
+    });
+  });
+}

package/src/trusted-context.mjs

@@ -0,0 +1,23 @@
+import { createHash } from 'node:crypto';
+
+const historicalInput = (name, input) => {
+  const raw = JSON.stringify(input) ?? 'null', bytes = Buffer.byteLength(raw);
+  const fields = ['content', 'old_string', 'new_string'];
+  if (bytes <= 2048 && !['Write', 'Edit', 'WorkDraft'].includes(name)) return input;
+  const metadata = { historical_arguments_sha256: createHash('sha256').update(raw).digest('hex'), historical_arguments_bytes: bytes, omitted_payload: true };
+  if (bytes > 2048) return { ...metadata, ...Object.fromEntries(['file_path','project','directory','action','task_id','step_id','operation'].filter(key => typeof input?.[key] === 'string' && input[key].length <= 300).map(key => [key, input[key]])) };
+  return { ...Object.fromEntries(Object.entries(input || {}).filter(([key]) => !fields.includes(key))), ...metadata };
+};
+
+export function trustedContext(rows) {
+  const intentions = [], actions = [];
+  for (const row of rows) {
+    if (row.type === 'intent') intentions.push(row.text);
+    // Legacy sessions predating intent records used only direct user prompts.
+    if (row.type === 'message' && !row.source && row.message.role === 'user' && typeof row.message.content === 'string') intentions.push(row.message.content);
+    if (row.type === 'message' && row.message.role === 'assistant') for (const block of Array.isArray(row.message.content) ? row.message.content : []) {
+      if (block.type === 'tool_use') actions.push({ name: block.name, input: historicalInput(block.name, block.input) });
+    }
+  }
+  return { intentions: intentions.slice(-8), actions: actions.slice(-20) };
+}