@milpa/comal 0.1.7 → 0.2.0

package/src/workflows/chrome-source.mjs

@@ -0,0 +1,73 @@
+import { digest } from '../operations.mjs';
+import { sourceInput, sourceOwn, nativeSourceParent } from '../source-proposal-proof.mjs';
+import { workProjection } from '../work-plan.mjs';
+
+export const CHROME_SOURCE_NAMES = Object.freeze(['SourceDraft', 'SourceRetain', 'SourceRead', 'SourcePublish']);
+
+// A host binding narrows the existing native source protocol; it grants no writer authority.
+export function bindChromeSource({ executor, store, sessionId, cwd, plan, taskDigest, pathAllowed, directory }) {
+  if (!executor.bindSourceScope || !executor.identity || !CHROME_SOURCE_NAMES.every(name => executor.isNativeOperation?.(name)) || !executor.isNativeOperation('FileInfo')) {
+    throw Object.assign(new Error('Chrome source recovery requires the original native source ports and FileInfo.'), { code: 'CHROME_TASK_SOURCE_UNAVAILABLE' });
+  }
+  const identity = executor.identity();
+  const owner = view => view.session_id === sessionId && view.surface === identity.surface && digest(view.actor) === digest(identity.actor);
+  const accepted = book => {
+    const index = book.rows.findIndex(row => row.type === 'chrome_task_accepted' && row.task_digest === taskDigest && row.governance_plan_hash === plan.plan_hash);
+    return index >= 0 ? index : null;
+  };
+  const currentScope = book => { const work = workProjection(book); return { reset_ref: book.rows.findLastIndex(row => row.type === 'reset'), goal_id: book.goal?.id ?? null,
+    task_id: work?.current?.id ?? null, work_digest: work?.current?.work_digest ?? null }; };
+  const original = (book, callId) => {
+    const index = accepted(book); if (index === null) return null;
+    const proposals = book.rows.filter(row => row.type === 'house_proposal' && row.call_id === callId && sourceOwn(row, { ...identity, house: cwd }));
+    if (proposals.length !== 1) return null;
+    const row = proposals[0], input = sourceInput(book.rows, row), receipt = book.rows.findLast(item => item.type === 'house_receipt' && item.invocation_id === row.invocation_id);
+    const before=book.rows.slice(0,book.rows.indexOf(row)),originScope=currentScope({id:book.id,cwd:book.cwd,rows:before,goal:before.findLast(item=>item.type==='goal')?.goal});
+    return book.rows.indexOf(row) > index && digest(originScope)===digest(currentScope(book)) && row.governance_plan_hash === plan.plan_hash && ['Write', 'Edit'].includes(row.operation) && input && receipt?.code === 'MODEL_STEP_TOO_LARGE' && receipt.status === 'refused' && receipt.effects_observed === 'none' ? { row, input } : null;
+  };
+  const binding = executor.bindSourceScope(sessionId, async (data, options, book) => {
+    const acceptedIndex=accepted(book);
+    if (acceptedIndex === null || currentScope(book).task_id !== 'chrome-task' || digest(data.scope) !== digest(currentScope(book))) return false;
+    if(book.goal&&['cleared','met','failed','budget'].includes(book.goal.status))return false;
+    const proposal = book.rows.find(row => row.type === 'house_proposal' && row.invocation_id === options.invocation_id);
+    if (!proposal || !owner(proposal) || book.rows.indexOf(proposal)<=acceptedIndex || proposal.governance_plan_hash!==plan.plan_hash) return false;
+    if(data.inspection_id){const receipt=book.rows.find(row=>row.type==='house_receipt'&&row.invocation_id===data.inspection_id);if(!receipt||book.rows.indexOf(receipt)<=acceptedIndex||receipt.governance_plan_hash!==plan.plan_hash)return false;}
+    if (data.original_invocation) {
+      const old = book.rows.find(row => row.type === 'house_proposal' && row.invocation_id === data.original_invocation);
+      if (!old || !original(book, old.call_id)) return false;
+    }
+    const allowed=await pathAllowed(data.requested_path, true),fresh=await store.load(sessionId);
+    return allowed&&digest(currentScope(fresh))===digest(data.scope)&&accepted(fresh)===acceptedIndex&&!(fresh.goal&&['cleared','met','failed','budget'].includes(fresh.goal.status));
+  });
+  const syntax = directory === undefined ? null : executor.bindChromeSourceSyntax?.(sessionId, { directory, task_digest: taskDigest });
+  return {
+    active: binding.active, dispose() { binding.dispose(); syntax?.dispose(); },
+    async admit(view) {
+      if (!binding.active() || !owner(view) || !executor.isNativeOperation(view.operation)) return false;
+      if (view.operation === 'SourceDraft') return pathAllowed(view.input.file_path, true);
+      if (view.operation === 'SourceRetain') {
+        const item = original(await store.load(sessionId), view.input.call_id);
+        return Boolean(item && await pathAllowed(item.input.file_path, true));
+      }
+      return true; // Opaque refs/listing are filtered inside the native handler before any output.
+    },
+    async inspection(view) {
+      if (!binding.active() || !owner(view) || !executor.isNativeOperation('FileInfo')) return false;
+      const book = await store.load(sessionId), rows = book.rows;
+      const parent = rows.find(row => row.type === 'house_proposal' && row.invocation_id === view.parent_invocation_id);
+      if (!parent || !['SourceDraft', 'SourceRetain'].includes(parent.operation) || !nativeSourceParent(rows, parent) || !owner(parent) || parent.governance_plan_hash !== plan.plan_hash || !executor.isNativeOperation(parent.operation)) return false;
+      const acceptedIndex=accepted(book);if(acceptedIndex===null||rows.indexOf(parent)<=acceptedIndex)return false;
+      if (rows.some(row => row.type === 'house_receipt' && row.invocation_id === parent.invocation_id)) return false;
+      const intents = rows.filter(row => row.type === 'source_inspection_intent' && row.source === 'source_host' && row.invocation_id === parent.invocation_id && sourceOwn(row, parent));
+      const intent = intents.length === 1 && intents[0];
+      if (!intent || intent.input_digest !== digest(intent.input) || digest(view.input) !== intent.input_digest || digest(view.input) !== digest({ file_path: intent.input.file_path, hash: true, allow_missing: true, max_bytes: 1048576 })) return false;
+      if (!rows.some(row => row.type === 'house_started' && row.invocation_id === parent.invocation_id && rows.indexOf(row) < rows.indexOf(intent))) return false;
+      if (parent.operation === 'SourceRetain') {
+        const input = sourceInput(rows, parent);
+        // Actual model calls carry their exact input. Native host callers still bind through the inspection intent.
+        if (input && original(book, input.call_id)?.input.file_path !== view.input.file_path) return false;
+      }
+      return pathAllowed(view.input.file_path, true);
+    },
+  };
+}

package/src/workflows/chrome-supplied-inputs.mjs

@@ -0,0 +1,43 @@
+import {lstat,realpath,open} from 'node:fs/promises';
+import {constants} from 'node:fs';
+import {createHash} from 'node:crypto';
+import path from 'node:path';
+import {safeRelative} from '../plugins/chrome-lab/project.mjs';
+
+export const suppliedInputsSchema={type:'array',minItems:0,maxItems:32,description:'Existing read-only assets supplied to this accepted extension. An empty list explicitly selects the same policy without supplied assets. Exact bytes must already exist; this grants no permission or package installation. The house preserves their hashes across source changes, publication and resume.',items:{type:'object',additionalProperties:false,required:['file','bytes','sha256'],properties:{file:{type:'string',minLength:1,maxLength:220},bytes:{type:'integer',minimum:0,maximum:1048576},sha256:{type:'string',pattern:'^[a-f0-9]{64}$'}}}};
+const failure=(file,reason)=>Object.assign(new Error('Supplied input '+file+' '+reason+'. Restore its accepted bytes; no publication was authorized by this check.'),{code:'CHROME_TASK_INPUT_CHANGED',details:{file,reason}});
+export function normalizeSuppliedInputs(items){
+ const paths=new Set();let total=0;
+ for(const item of items){
+  safeRelative(item.file);const name=item.file.toLowerCase();
+  if(name.split('/').some(part=>['.git','.comal','.harness','.ssh','node_modules'].includes(part)||/^\.env(?:\.|$)/i.test(part)))throw failure(item.file,'uses a protected path');
+  if([...paths].some(other=>name===other||name.startsWith(other+'/')||other.startsWith(name+'/')))throw failure(item.file,'duplicates or aliases another supplied path');paths.add(name);total+=item.bytes;
+ }
+ if(total>10000000)throw failure('(manifest)','exceeds the aggregate byte limit');
+ return items;
+}
+export function isSuppliedPath(relative,items){
+ const value=relative.split(path.sep).join('/').toLowerCase();
+ return items.some(({file})=>{const name=file.toLowerCase();return name===value||name.startsWith(value+'/')||value.startsWith(name+'/');});
+}
+// Stable bounded reads bind content, not a permanent inode. No symlink/hardlink aliases.
+export async function verifySuppliedInputs(directory,items,{signal}={}){
+ for(const item of items){
+  signal?.throwIfAborted();const file=path.join(directory,safeRelative(item.file));let handle;
+  try{
+   const before=await lstat(file);
+   if(!before.isFile()||before.nlink!==1||before.size!==item.bytes||await realpath(file)!==file)throw failure(item.file,'is missing, redirected or has a different size');
+   handle=await open(file,constants.O_RDONLY|(constants.O_NOFOLLOW||0)|(constants.O_NONBLOCK||0));
+   const opened=await handle.stat();if(opened.ino!==before.ino||opened.dev!==before.dev||!opened.isFile())throw failure(item.file,'changed before opening');
+   const buffer=Buffer.alloc(item.bytes+1);let offset=0;
+   while(offset<buffer.length){signal?.throwIfAborted();const {bytesRead}=await handle.read(buffer,offset,buffer.length-offset,offset);if(!bytesRead)break;offset+=bytesRead;}
+   const after=await handle.stat(),current=await lstat(file);
+   if(offset!==item.bytes||[after,current].some(s=>!s.isFile()||s.nlink!==1||s.dev!==before.dev||s.ino!==before.ino||s.size!==before.size||s.mtimeMs!==before.mtimeMs||s.ctimeMs!==before.ctimeMs)||await realpath(file)!==file)throw failure(item.file,'changed while reading');
+   if(createHash('sha256').update(buffer.subarray(0,offset)).digest('hex')!==item.sha256)throw failure(item.file,'has a different digest');
+  }catch(error){if(signal?.aborted)throw error;if(error.code==='CHROME_TASK_INPUT_CHANGED')throw error;throw failure(item.file,'cannot be read as its accepted regular file');}
+  finally{await handle?.close();}
+ }
+}
+export function assertSuppliedSnapshot(snapshot,items){
+ for(const item of items){const actual=snapshot.files.find(file=>file.path===item.file);if(!actual||actual.sha256!==item.sha256||Buffer.from(actual.data,'base64').length!==item.bytes)throw failure(item.file,'differs in the publication snapshot');}
+}

package/src/workflows/chrome-task-adoption.mjs

@@ -0,0 +1,122 @@
+import { digest } from '../operations.mjs';
+import { workProjection } from '../work-plan.mjs';
+import { chromeTaskSchema, normalizeTask, savedChromeTask, validateTaskDirectory, chromeFixtureDigest } from './chrome-task.mjs';
+import { verifySuppliedInputs } from './chrome-supplied-inputs.mjs';
+import { snapshotProject } from '../plugins/chrome-lab/project.mjs';
+import { isHumanIntentRecord } from '../trusted-context.mjs';
+
+const required = ['Deploy','Deployment','Open','Targets','Assert','Contexts','Interact','ReadDOM','Console'];
+const entryNames = new Set(['ChromeTask','Read','Glob','Grep','ListDirectory','FileInfo','WebSearch','WebFetch']);
+const fail = (message, code = 'CHROME_TASK_DECLARATION') => Object.assign(new Error(message), { code });
+const activeSkill = session => session.rows.some(row => row.type === 'skill_scope_started' && row.source === 'skill_host' && !session.rows.some(end => end.type === 'skill_scope_completed' && end.source === 'skill_host' && end.scope_id === row.scope_id));
+const declarationSchema = structuredClone(chromeTaskSchema);
+// Conversational declaration retains its historical popup defaults. A page-only
+// verifier is selected explicitly by the host at startup, never by model input.
+delete declarationSchema.allOf;
+delete declarationSchema.properties.surface;
+delete declarationSchema.properties.verification;
+declarationSchema.required = ['selector', 'equals'];
+delete declarationSchema.properties.project;
+declarationSchema.properties.directory.description = 'Workspace source folder, default extension. It may be new; Write creates files under ordinary permissions.';
+declarationSchema.properties.popup.description = 'Popup file relative to the source folder, default popup.html.';
+declarationSchema.properties.tests.description = 'Functional checks derived from the request, in order: fill/click/reload/assert. Include persistence and deletion when requested. Assertions need equals or count. Tests stay immutable after adoption.';
+// Disjoint variants show the required arguments of each action explicitly.
+const step = (action, properties, required) => ({ type: 'object', properties: { action: { const: action }, ...properties, surface: fields.surface }, required: ['action', ...required], additionalProperties: false });
+const fields = chromeTaskSchema.properties.tests.items.properties;
+// llama.cpp #27087 rejects nested char{0,2000}. This redundant equivalent
+// pattern uses 0..1999 plus one optional character, preserving maxLength:2000.
+// Dot plus the four ECMAScript line terminators covers every Unicode character.
+// Avoid two variable chunks: their ambiguous splits made live decoding stall.
+const boundedText = field => ({ ...field, pattern: '^(.|\\n|\\r|\\u2028|\\u2029){0,1999}(.|\\n|\\r|\\u2028|\\u2029)?$' });
+declarationSchema.properties.fixture.properties.equals=boundedText(declarationSchema.properties.fixture.properties.equals);
+declarationSchema.properties.tests.items = { oneOf: [
+  step('click', { selector: fields.selector }, ['selector']),
+  step('fill', { selector: fields.selector, text: boundedText(fields.text) }, ['selector', 'text']),
+  step('reload', {}, []),
+  step('message', {request:fields.request,equals:boundedText(fields.equals)}, ['request','equals']),
+  step('assert', { selector: fields.selector, equals: boundedText(fields.equals), count: fields.count }, ['selector', 'equals']),
+  step('assert', { selector: fields.selector, count: fields.count }, ['selector', 'count'])
+] };
+
+// Domain contracts are declared through House, then activated only after their
+// receipt closes. A model never receives the host executor or policy controls.
+export class ChromeTaskAdoption {
+  constructor({ cwd, house, store, sessionId, coordinated = true }) { Object.assign(this, { cwd, house, store, sessionId, coordinated }); }
+  id() { return typeof this.sessionId === 'function' ? this.sessionId() : this.sessionId; }
+  // COMAL_DISABLE_CHROME_TASK=1 deja chrome-lab en crudo, sin ofrecer ChromeTask (lo usa el banco E3).
+  available() { return process.env.COMAL_DISABLE_CHROME_TASK !== '1' && required.every(name => this.house.registry.get('plugin__chrome-lab__' + name)); }
+  async sync() {
+    const session = await this.store.load(this.id());
+    this.pendingDeclaration = !savedChromeTask(session) && session.rows.some(row => row.type === 'chrome_task_proposed' && row.source === 'workflow_host');
+    const available = this.available() && !savedChromeTask(session) && !workProjection(session) && !activeSkill(session);
+    this.focused = Boolean(this.coordinated && available);
+    if (!available) { this.house.registry.replace(['ChromeTask'], []); return; }
+    const deploy = this.house.registry.get('plugin__chrome-lab__Deploy');
+    const capabilities = digest({deploy:deploy.digest,message:this.house.registry.get('plugin__chrome-lab__Message')?.digest || null,preview:this.house.registry.get('plugin__chrome-lab__Preview')?.digest || null});
+    if (this.house.registry.get('ChromeTask') && this.deployDigest === capabilities) return;
+    this.house.registry.replace(['ChromeTask'], []); this.deployDigest = capabilities;
+    const inputSchema = structuredClone(declarationSchema);
+    if (!this.house.registry.get('plugin__chrome-lab__Message')) inputSchema.properties.tests.items.oneOf=inputSchema.properties.tests.items.oneOf.filter(variant=>variant.properties.action.const!=='message');
+    if(!this.house.registry.get('plugin__chrome-lab__Preview')){delete inputSchema.properties.fixture;for(const variant of inputSchema.properties.tests.items.oneOf)delete variant.properties.surface;}
+    this.house.registry.add({ name: 'ChromeTask', description: 'Start coordinated Chrome extension work directly from the user request, BEFORE WorkPlanSet or effects. Declare the DOM criterion and functional behavior tests; no task file, plan versions or target IDs. Emit ALONE and await the next offered domain tools. The house assigns project identity, publishes, binds targets, runs checks and closes. Criteria are your proposal, not proof of user acceptance. No permission grant.',
+      input_schema: inputSchema, steps: true,
+      effects: { workspace: 'read', external: 'none', process: 'none', authority: 'none' },
+      run: async (input, options) => {
+        if (options.sessionId !== this.id() || options.actor.kind !== 'agent') throw fail('Only the current root resident can declare this session contract.');
+        const session = await this.store.load(this.id());
+        if (!session.journalAudit.verified) throw fail('Invalid session journal.', 'AUDIT_INVALID');
+        if (!this.available()) throw fail('Chrome Lab is not active; load its configured plugin before declaring a task.');
+        if (activeSkill(session)) throw fail('Declare the coordinated task in the resident session before entering a temporary skill scope. No contract or tool scope changed.', 'CHROME_TASK_SCOPE');
+        if (savedChromeTask(session) || workProjection(session)) throw fail('Existing work is preserved. Continue its contract; start a new session for a different Chrome task.');
+        const task = normalizeTask({ directory: 'extension', popup: 'popup.html', ...input, project: 'comal-' + this.id().replaceAll('-', '').slice(0, 24) });
+        this.house.registry.get('plugin__chrome-lab__Deploy').validate({ project: task.project, directory: task.directory });
+        const directory=await validateTaskDirectory(this.cwd, task.directory);
+        if(task.supplied_inputs)await verifySuppliedInputs(directory,task.supplied_inputs);
+        const baselineSource=task.baseline?digest((await snapshotProject(this.cwd,task.directory)).files.map(({path,sha256})=>({path,sha256}))):null;
+        const ref = session.rows.findLastIndex(row => isHumanIntentRecord(row) && row.text.trim());
+        const goalRef = session.rows.findLastIndex(row => row.type === 'goal' && row.goal?.status === 'active');
+        const requestRef = ref >= 0 ? ref : goalRef;
+        if (requestRef < 0) throw fail('A recorded user request or active goal is required; tool data cannot supply authority.');
+        const previous = session.rows.findLast(row => row.type === 'chrome_task_proposed' && row.source === 'workflow_host');
+        if (previous && digest(previous.task) !== digest(task)) throw fail('A different Chrome declaration is pending; its criteria cannot be replaced silently.');
+        await options.recordWork({ type: 'chrome_task_proposed', source: 'workflow_host', task, task_digest: digest(task), provenance: {
+          criteria_origin: 'resident_proposal', request_ref: requestRef, request_sha256: session.rows[requestRef].audit.sha256,
+          ...(baselineSource?{baseline_source_digest:baselineSource}:{}),
+          ...(task.supplied_inputs?{supplied_inputs_digest:digest(task.supplied_inputs)}:{}),
+          ...(task.fixture?{fixture_source_digest:await chromeFixtureDigest(this.cwd,task)}:{}),
+          request_kind: session.rows[requestRef].type, human_acceptance: 'unjudged'
+        } });
+        this.pendingDeclaration = true;
+        return JSON.stringify({ status: 'declared', task, task_digest: digest(task), next_action: 'The house activates this immutable contract before the next model call. Use the newly offered source/domain tools; no WorkPlanSet, ToolPack, task file or target IDs.', grants_permission: false });
+      }
+    });
+  }
+  async pending() {
+    const session = await this.store.load(this.id());
+    if (savedChromeTask(session)) return null;
+    const ref = session.rows.findLastIndex(row => row.type === 'chrome_task_proposed' && row.source === 'workflow_host');
+    if (ref < 0) return null;
+    if (!session.journalAudit.verified) throw fail('Invalid session journal.', 'AUDIT_INVALID');
+    const row = session.rows[ref], receipt = session.rows.findLast(item => item.type === 'house_receipt' && item.invocation_id === row.invocation_id && item.operation === 'ChromeTask');
+    if (!receipt || receipt.status !== 'returned') throw fail('The declaration has no completed receipt. Preserve the journal and inspect the interrupted declaration; no publication was attempted.', 'CHROME_TASK_DECLARATION_UNCERTAIN');
+    if (row.task_digest !== digest(row.task) || session.rows[row.provenance.request_ref]?.audit?.sha256 !== row.provenance.request_sha256) throw fail('The declaration no longer matches its original request.', 'AUDIT_INVALID');
+    return { task: row.task, source: 'conversation_declaration', provenance: { ...row.provenance, proposal_ref: ref, proposal_sha256: row.audit.sha256, receipt_id: receipt.invocation_id } };
+  }
+  wrap(tools) {
+    const owner = this;
+    const snapshot = () => {
+      const captured = tools.snapshot();
+      const focused = this.focused;
+      const project = definitions => focused ? definitions.filter(op => entryNames.has(op.name)).sort((a,b) => Number(b.name === 'ChromeTask') - Number(a.name === 'ChromeTask')) : definitions;
+      const definitions = project(captured.definitions()), offered = new Set(definitions.map(op => op.name));
+      return { ...captured, definitions: () => definitions, catalogue: () => project(captured.catalogue()), execute: async (name, input, options = {}) => {
+        // A mixed response cannot start another effect using the catalogue from
+        // before declaration. Host activation uses the raw executor, at boundary.
+        if (options.modelProposed && name !== 'ChromeTask' && this.pendingDeclaration && await this.pending()) throw fail('ChromeTask was declared in this batch. No further call executed; continue with the next domain catalogue.', 'CHROME_TASK_BOUNDARY');
+        if (options.modelProposed && focused && !offered.has(name)) throw fail('Declare ChromeTask first; this entry surface permits only source inspection and declaration. No effect executed.', 'CHROME_TASK_ENTRY');
+        return captured.execute(name, input, options);
+      } };
+    };
+    return { ...tools, get workflowEntry() { return owner.focused; }, snapshot, definitions: () => snapshot().definitions(), catalogue: () => snapshot().catalogue(), execute: (name, input, options) => snapshot().execute(name, input, options) };
+  }
+}