@milpa/comal 0.1.6 → 0.1.7

package/README.md

@@ -28,7 +28,7 @@ comal --help
 
 Keep the PATH line in your shell startup file if you use that prefix. If your Node manager already provides a user prefix, you can omit `--prefix "$HOME/.local"`. The package registers the `comal` executable; you do not need to create a shell alias.
 
-You can pin a version with `npx @milpa/comal@0.1.6` or `npm install --global @milpa/comal@0.1.6`. The local release manifest preserves SHA-256 and SHA-512 integrity is checked against npm at publish time. No independent publisher signature is claimed.
+You can pin a version with `npx @milpa/comal@0.1.7` or `npm install --global @milpa/comal@0.1.7`. The local release manifest preserves SHA-256 and SHA-512 integrity is checked against npm at publish time. No independent publisher signature is claimed.
 
 ## Test without account or model
 

package/backend/contracts/remote-workspace-v1.schema.json

@@ -0,0 +1,287 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "version": {
+      "const": 1
+    },
+    "scope": {
+      "const": "recorded_work_execution"
+    },
+    "asked": {
+      "const": "unjudged"
+    },
+    "source": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "session_id": {
+          "type": "string",
+          "maxLength": 128
+        },
+        "row": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "sha256": {
+          "type": "string",
+          "maxLength": 64,
+          "pattern": "^[a-f0-9]{64}$"
+        },
+        "integrity": {
+          "enum": [
+            "verified_hash_chain",
+            "legacy",
+            "invalid"
+          ]
+        }
+      },
+      "required": [
+        "session_id",
+        "row",
+        "sha256",
+        "integrity"
+      ]
+    },
+    "plan": {
+      "anyOf": [
+        {
+          "type": "null"
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "version": {
+              "type": "integer",
+              "minimum": 1
+            },
+            "objective": {
+              "type": "string",
+              "maxLength": 1000
+            }
+          },
+          "required": [
+            "version",
+            "objective"
+          ]
+        }
+      ]
+    },
+    "counts": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "pending": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "in_progress": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "blocked": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "done": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "needs_verification": {
+          "type": "integer",
+          "minimum": 0
+        }
+      },
+      "required": [
+        "pending",
+        "in_progress",
+        "blocked",
+        "done",
+        "needs_verification"
+      ]
+    },
+    "tasks_total": {
+      "type": "integer",
+      "minimum": 0
+    },
+    "tasks": {
+      "type": "array",
+      "maxItems": 24,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "id": {
+            "type": "string",
+            "maxLength": 64,
+            "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]{0,63}$"
+          },
+          "title": {
+            "type": "string",
+            "maxLength": 180
+          },
+          "criterion": {
+            "type": "string",
+            "maxLength": 400
+          },
+          "status": {
+            "enum": [
+              "pending",
+              "in_progress",
+              "blocked",
+              "done",
+              "needs_verification"
+            ]
+          },
+          "declared_status": {
+            "enum": [
+              "pending",
+              "in_progress",
+              "blocked",
+              "done",
+              "needs_verification"
+            ]
+          },
+          "phase": {
+            "enum": [
+              "discovery",
+              "implementation",
+              "verification"
+            ]
+          },
+          "reason": {
+            "type": "string",
+            "maxLength": 240
+          },
+          "held_by": {
+            "type": "array",
+            "maxItems": 24,
+            "items": {
+              "type": "string",
+              "maxLength": 64,
+              "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]{0,63}$"
+            }
+          },
+          "checks_total": {
+            "type": "integer",
+            "minimum": 0
+          },
+          "checks": {
+            "type": "array",
+            "maxItems": 4,
+            "items": {
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {
+                "step_id": {
+                  "type": "string",
+                  "maxLength": 64,
+                  "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]{0,63}$"
+                },
+                "operation": {
+                  "type": "string",
+                  "maxLength": 128
+                },
+                "status": {
+                  "enum": [
+                    "pending",
+                    "running",
+                    "failed",
+                    "refused",
+                    "interrupted",
+                    "not_dispatched",
+                    "stale",
+                    "passed"
+                  ]
+                },
+                "receipt_id": {
+                  "type": "string",
+                  "maxLength": 36,
+                  "pattern": "^[a-f0-9-]{36}$"
+                },
+                "receipt_row": {
+                  "type": "integer",
+                  "minimum": 0
+                }
+              },
+              "required": [
+                "step_id",
+                "operation",
+                "status"
+              ],
+              "dependentRequired": {
+                "receipt_id": [
+                  "receipt_row"
+                ],
+                "receipt_row": [
+                  "receipt_id"
+                ]
+              }
+            }
+          }
+        },
+        "required": [
+          "id",
+          "title",
+          "criterion",
+          "status",
+          "declared_status",
+          "phase",
+          "reason",
+          "held_by",
+          "checks_total",
+          "checks"
+        ]
+      }
+    },
+    "receipts": {
+      "type": "array",
+      "maxItems": 8,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "id": {
+            "type": "string",
+            "maxLength": 36,
+            "pattern": "^[a-f0-9-]{36}$"
+          },
+          "operation": {
+            "type": "string",
+            "maxLength": 128
+          },
+          "status": {
+            "enum": [
+              "returned",
+              "failed",
+              "refused"
+            ]
+          },
+          "row": {
+            "type": "integer",
+            "minimum": 0
+          }
+        },
+        "required": [
+          "id",
+          "operation",
+          "status",
+          "row"
+        ]
+      }
+    }
+  },
+  "required": [
+    "version",
+    "scope",
+    "asked",
+    "source",
+    "plan",
+    "counts",
+    "tasks_total",
+    "tasks",
+    "receipts"
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@milpa/comal",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "Comal: governed operations, execution receipts, and programming assistance in any language",
   "type": "module",
   "private": false,
@@ -22,6 +22,7 @@
     "backend/verifier/transport.mjs",
     "backend/contracts/artifact-check-v1.schema.json",
     "backend/contracts/remote-commands-v1.json",
+    "backend/contracts/remote-workspace-v1.schema.json",
     "governance/chrome-task-v1.json",
     "governance/chrome-task-v2.json",
     "docs",

package/src/cli.mjs

@@ -37,6 +37,7 @@ import { Operation } from './operations.mjs';
 import { validateConnectionCandidate } from './connection-validation.mjs';
 import { PluginRuntime, parsePluginCommand } from './plugins.mjs';
 import { registerWorkOperations, workProjection } from './work-plan.mjs';
+import { projectRemoteWorkspace } from './remote-workspace.mjs';
 import { evidenceOperations } from './work-state.mjs';
 import { auditExecution, auditReport } from './audit.mjs';
 import { comalEnvironment } from './compat.mjs';
@@ -339,7 +340,7 @@ async function boot(args, createScreen, setInterrupt, startupSignal) {
       stderr.write(color('90', t("Session {v0} · {v1} calls · {v2} tokens", {v0: event.session_id, v1: event.turns, v2: event.usage.input_tokens + event.usage.output_tokens})) + '\n');
     }
   };
-  const house = new House({ cwd, record: event => store.append(event.session_id, event) });
+  const house = new House({ cwd, record: async event => { const row=await store.append(event.session_id,event); if(event.session_id===session.id)remoteHost?.invalidateWorkspace(); return row; } });
   if (v.codemode) house.registry.add(codeRunDefinition);
   house.guard('peer-authority',view=>peerGuard.check(view));
   const onPermission = decision => store.append(session.id, { type: 'permission', ...decision });
@@ -462,7 +463,7 @@ async function boot(args, createScreen, setInterrupt, startupSignal) {
   house.registry.add({name:'CloudAccountLogout',description:'Human detaches Remote Control and removes the local Comal account credential.',input_schema:emptyInput,audience:'human',surfaces:['tui'],permission:null,effects:{workspace:'none',external:'write',process:'none',authority:'credential_control'},run:async()=>{await remoteHost?.stop();return cloudClient.logout();}});
   const openRemoteControl=async()=>{
     if(!runtime)throw Error('Remote Control requires an interactive local session.');
-    if(!remoteHost || remoteHost.stopped)remoteHost=new RemoteHost({client:new CloudClient({origin:v['cloud-url']}),onInput:(input,binding)=>runtime.admitRemote(input,binding),onStop:id=>runtime.stopRemote(id),onNotice:text=>ui.notice(text)});
+    if(!remoteHost || remoteHost.stopped)remoteHost=new RemoteHost({client:new CloudClient({origin:v['cloud-url']}),onInput:(input,binding)=>runtime.admitRemote(input,binding),onStop:id=>runtime.stopRemote(id),onNotice:text=>ui.notice(text),getWorkspace:async snapshot=>projectRemoteWorkspace(snapshot || await store.load(session.id),house.stateContext())});
     const connection = new AbortController(); authController = connection;
     const cancel = () => remoteHost.stop().catch(() => {});
     connection.signal.addEventListener('abort', cancel, { once: true });

package/src/remote-control.mjs

@@ -26,8 +26,8 @@ const cancelled = () => Object.assign(new Error('Remote Control connection cance
 const lifetimeSignal = (run,timeout=10000) => run?.controller ? AbortSignal.any([run.controller.signal,AbortSignal.timeout(timeout)]) : AbortSignal.timeout(timeout);
 
 export class RemoteHost {
-  constructor({client=new CloudClient(),onInput=async()=>{throw Error('Local queue unavailable.');},onStop=async()=>false,onNotice=()=>{},socketFactory=(url,protocol)=>new WebSocket(url,protocol)}={}) {
-    Object.assign(this,{client,onInput,onStop,onNotice,socketFactory});this.pending=[];this.turnId=null;this.stopped=true;this.transport='disconnected';this.processing=null;this.sending=null;this.lifecycle=null;this.starting=null;
+  constructor({client=new CloudClient(),onInput=async()=>{throw Error('Local queue unavailable.');},onStop=async()=>false,onNotice=()=>{},getWorkspace=null,socketFactory=(url,protocol)=>new WebSocket(url,protocol)}={}) {
+    Object.assign(this,{client,onInput,onStop,onNotice,getWorkspace,socketFactory});this.pending=[];this.turnId=null;this.stopped=true;this.transport='disconnected';this.processing=null;this.sending=null;this.lifecycle=null;this.starting=null;
   }
   status(){return this.session?{enabled:!this.stopped,url:this.url,session:this.session.id,transport:this.transport,permissions:'local_terminal_only'}:{enabled:false};}
   current(run,{starting=false}={}) {return this.lifecycle===run && (starting || !this.stopped) && !run?.controller?.signal.aborted;}
@@ -48,7 +48,8 @@ export class RemoteHost {
         const account=await this.client.credentials();this.assertCurrent(run,{starting:true});
         if(!account)throw Error('Sign in with comal cloud login before enabling Remote Control.');
         run.account={origin:account.origin,user_id:account.user_id};run.enablingToken=account.token;
-        const opened=await this.client.invoke('remote.sessions.open',{local_session_id:session.id,host_id:randomUUID(),label:boundText(session.name || 'Comal',80),features:['commands_v1','thinking_v1']},{expectedAccount:run.account,signal:run.controller.signal});
+        const workspace=this.getWorkspace?await this.getWorkspace(session):null;this.assertCurrent(run,{starting:true});
+        const opened=await this.client.invoke('remote.sessions.open',{local_session_id:session.id,host_id:randomUUID(),label:boundText(session.name || 'Comal',80),features:['commands_v1','thinking_v1',...(this.getWorkspace?['workspace_v1']:[])]},{expectedAccount:run.account,signal:run.controller.signal});
         run.session=opened.session;
         // Abort can race a successful response. Revoke a late-created grant even
         // when the local stop completed before its identifier became available.
@@ -56,6 +57,7 @@ export class RemoteHost {
         this.account=run.account;this.enablingToken=run.enablingToken;this.session=opened.session;this.url=opened.url;this.stopped=false;
         await this.authorize(run);this.assertCurrent(run);await this.pulse(run);this.assertCurrent(run);
         this.transport='https-polling';this.connectSocket(run);
+        if(workspace)this.publishWorkspace(workspace,run);
         this.timer=setInterval(()=>this.tick(run),1000);this.timer.unref();
         for(const message of (session.historyMessages || []).slice(-20)){
           const event=message.role==='user'&&(typeof message.content==='string'||Array.isArray(message.content)&&message.content.some(block=>block.type==='text'))?{type:'user',text:typeof message.content==='string'?message.content:message.content.filter(block=>block.type==='text').map(block=>block.text).join('\n')}:message.role==='assistant'?{type:'assistant',message}:null;
@@ -103,8 +105,30 @@ export class RemoteHost {
     }catch{/* HTTPS is already active. A later tick retries WSS. */}
     finally{if(this.connecting===marker){this.connecting=null;if(this.current(run))this.nextSocketAt=Date.now()+10000;}}
   }
+  publishWorkspace(workspace,run=this.lifecycle) {
+    if(!this.current(run))return;
+    const {source,...content}=workspace,key=digest(content);
+    if(run.workspaceDigest===key)return;
+    if(this.pending.length>=512)throw Error('Remote workspace buffer full.');
+    this.pending.push({event_id:randomUUID(),event:{type:'workspace.snapshot',text:'',turn_id:this.turnId||'local',workspace}});
+    run.workspaceDigest=key;this.flush(run).catch(()=>{});
+  }
+  invalidateWorkspace() {
+    const run=this.lifecycle;if(!this.current(run)||!this.getWorkspace)return;
+    run.workspaceDirty=true;
+    if(run.workspaceTimer||run.workspaceLoading)return;
+    run.workspaceTimer=setTimeout(()=>{run.workspaceTimer=null;this.refreshWorkspace(run);},750);run.workspaceTimer.unref();
+  }
+  async refreshWorkspace(run=this.lifecycle) {
+    if(!this.current(run)||!this.getWorkspace||run.workspaceLoading)return;
+    run.workspaceLoading=true;run.workspaceDirty=false;
+    try {const workspace=await this.getWorkspace();if(this.current(run))this.publishWorkspace(workspace,run);}
+    catch {if(this.current(run))this.onNotice('Remote work state unavailable; local execution continues.');}
+    finally {run.workspaceLoading=false;if(this.current(run)&&run.workspaceDirty)this.invalidateWorkspace();}
+  }
   observe(event) {
     if(this.stopped)return;
+    if(['tool_result','house_waiting','house_answered','result'].includes(event.type))this.invalidateWorkspace();
     const append=projected=>this.pending.push({event_id:randomUUID(),event:projected});
     if(event.type==='model_stream_progress'&&event.reasoning_chars>0&&!this.thinkingActive){
       this.thinkingActive=true;append({type:'thinking.started',turn_id:this.turnId||'local',text:'Thinking…'});this.flush().catch(()=>{});return;
@@ -139,6 +163,7 @@ export class RemoteHost {
   pulse(run=this.lifecycle){const work=(this.pulsing || Promise.resolve()).catch(()=>{}).then(()=>{if(this.current(run))return this.call('remote.host.pulse',{status:this.turnId?'busy':'idle',turn_id:this.turnId},run);});this.pulsing=work;return work;}
   async beginTurn(){this.turnId=randomUUID();if(!this.stopped)this.pulse().catch(error=>{if(error.code!=='REMOTE_CANCELLED')this.onNotice('Remote state unavailable: '+error.message);});}
   async endTurn(){
+    this.invalidateWorkspace();
     if(!this.stopped){this.pending.push({event_id:randomUUID(),event:{type:'turn.settled',text:'Local turn settled.',turn_id:this.turnId || 'local'}});this.flush().catch(()=>{});}
     clearTimeout(this.deltaTimer);this.deltaTimer=null;this.delta='';this.thinkingActive=false;this.turnId=null;this.pulse().catch(()=>{});
   }
@@ -172,7 +197,7 @@ export class RemoteHost {
   }
   async stop(){
     const run=this.lifecycle || {session:this.session,account:this.account,enablingToken:this.enablingToken};
-    this.lifecycle=null;this.starting=null;run.controller?.abort();
+    this.lifecycle=null;this.starting=null;run.controller?.abort();clearTimeout(run.workspaceTimer);
     this.stopped=true;clearInterval(this.timer);clearTimeout(this.deltaTimer);clearTimeout(this.socketTimeout);this.socket?.close();this.socket=null;this.delta='';this.transport='disconnected';
     this.access=null;this.enablingToken=null;this.pending=[];this.turnId=null;this.processing=null;this.sending=null;this.pulsing=null;this.connecting=null;
     await this.revoke(run);return this.status();

package/src/remote-workspace.mjs

@@ -0,0 +1,50 @@
+import { foldWorkBook } from './work-plan.mjs';
+import { auditJournal } from './audit.mjs';
+
+const text = (value, bytes) => Buffer.from(String(value ?? '')).subarray(0, bytes).toString('utf8').replace(/\uFFFD$/, '');
+const reasons = {
+  'Una comprobación perdió vigencia en el libro.':'A recorded check is no longer current.',
+  'La evidencia de una dependencia cambió; vuelve a comprobar esta tarea.':'Dependency evidence changed; verify this task again.',
+  'Una dependencia perdió su cierre vigente.':'A dependency no longer has current completion evidence.',
+  'Espera una respuesta humana.':'Waiting for an answer in the local terminal.',
+};
+const states = new Set(['pending', 'in_progress', 'blocked', 'done', 'needs_verification']);
+const checkStates = new Set(['running', 'failed', 'refused', 'interrupted', 'not_dispatched']);
+
+/** Host projection only: no arguments, assertions, file contents, drafts or raw outputs. */
+export function projectRemoteWorkspace(session, context = {}) {
+  const rows = session.rows || [], journal = auditJournal(rows), book = foldWorkBook(session, context);
+  const counts = Object.fromEntries([...states].map(status => [status, book.tasks.filter(task => task.status === status).length]));
+  const tasks = [...book.tasks].sort((a, b) => ['in_progress', 'blocked', 'needs_verification', 'pending', 'done'].indexOf(a.status) - ['in_progress', 'blocked', 'needs_verification', 'pending', 'done'].indexOf(b.status)).slice(0, 24).map(task => ({
+    id: task.id, title: text(task.title, 180), criterion: text(task.criterion, 400),
+    status: journal.verified ? task.status : task.status === 'done' ? 'needs_verification' : task.status,
+    declared_status: states.has(task.declared_status) ? task.declared_status : 'pending',
+    phase: task.phase || 'implementation', reason: text(reasons[task.reason] || task.reason, 240), held_by: task.held_by.slice(0, 24),
+    checks_total: task.checks.length,
+    checks: task.checks.slice(0, 4).map(check => {
+      const step = book.steps.find(step => step.task_id === task.id && step.step_id === check.step_id);
+      const receipt = book.receipts.get(step?.receipt_id);
+      const status = journal.verified && book.checkValid(task, check, step) ? 'passed'
+        : step?.preflight_failure ? 'not_dispatched'
+        : step?.status === 'returned' ? 'stale'
+        : checkStates.has(step?.status) ? step.status : 'pending';
+      return { step_id: check.step_id, operation: text(check.operation, 128), status,
+        ...(receipt ? { receipt_id: receipt.invocation_id, receipt_row: receipt.evidence_row } : {}) };
+    }),
+  }));
+  const references = new Set([...book.steps.map(step => step.receipt_id), ...book.tasks.flatMap(task => task.receipt_ids || [])]);
+  const receipts = [...book.receipts.values()].filter(receipt => references.has(receipt.invocation_id)).slice(-8).reverse().map(receipt => ({
+    id: receipt.invocation_id, operation: text(receipt.operation, 128), status: receipt.status, row: receipt.evidence_row,
+  }));
+  if (!journal.verified) { const previousDone=counts.done; counts.done=0; counts.needs_verification+=previousDone; }
+  const result = {
+    version: 1, scope: 'recorded_work_execution', asked: 'unjudged',
+    source: { session_id: session.id, row: Math.max(0, rows.length - 1), sha256: journal.tip_sha256 || '0'.repeat(64), integrity: journal.verified ? 'verified_hash_chain' : journal.consistent ? 'legacy' : 'invalid' },
+    plan: book.plan ? { version: book.plan.version, objective: text(book.plan.objective, 1000) } : null,
+    counts, tasks_total: book.tasks.length, tasks, receipts,
+  };
+  // The stream has a 48 KiB event ceiling, including its transport envelope.
+  // Keep whole task/check records and disclose omissions through total counts.
+  while (Buffer.byteLength(JSON.stringify(result)) > 36000 && result.tasks.length) result.tasks.pop();
+  return result;
+}