@volter/supercode-orchestrator 0.4.159 → 0.5.1

package/agents.mjs

@@ -0,0 +1,443 @@
+// Teams identity, orchestrator intent and assignments: one boundary, joined by the immutable agent id.
+import { DatabaseSync } from 'node:sqlite';
+import { mkdirSync } from 'node:fs';
+import { join, basename } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
+import { createHash, randomBytes } from 'node:crypto';
+import { runtimeDoor } from './board/runtime-door.mjs';
+import { resolveAgentProfile } from './agent-profiles.mjs';
+import { compareAgentProfile } from '@volter/teams/agent-profile';
+const entry=fileURLToPath(new URL('./bin/agent-door.mjs',import.meta.url));
+export function agentDoor(op,args=[],{context,timeout=25000}={}){
+  const reply=spawnSync(process.execPath,[entry],{input:JSON.stringify({op,args,context}),encoding:'utf8',timeout,maxBuffer:4*1024*1024});
+  if(reply.status!==0){let detail;try{detail=JSON.parse(reply.stderr);}catch{detail={message:reply.error?.message??String(reply.stderr).slice(-1000)};}throw Object.assign(new Error(detail.message??'Teams agent door unavailable'),detail);}
+  return JSON.parse(reply.stdout);
+}
+/** Teams is not configured, not reachable, or no longer accepts this login: identity stays local until it syncs.
+ * A refusal Teams decided (forbidden, conflict, not found, invalid) is never read as absence. */
+export function teamsUnavailable(error){
+  if(error?.status!=null)return error.status>=500||error.status===401;
+  return !['forbidden','conflict','not_found','invalid_request','revision_mismatch','idempotency_conflict'].includes(error?.code);
+}
+/** The Org agent identity belongs to: the selected Teams context, or this home's local store when there is none. */
+export function agentScope(context){
+  try{return agentDoor('scope',[],{context});}
+  catch(error){if(teamsUnavailable(error))return {server:'local',org:'local',principal:null,offline:true,reason:error.message};throw error;}
+}
+function store(root){
+  mkdirSync(root,{recursive:true,mode:0o700});const db=new DatabaseSync(join(root,'agent-state.sqlite'));
+  db.exec(`PRAGMA busy_timeout=5000; PRAGMA journal_mode=WAL;
+  CREATE TABLE IF NOT EXISTS agent_intents(org TEXT NOT NULL,id TEXT NOT NULL,key TEXT NOT NULL,profile_ref TEXT NOT NULL,profile_json TEXT NOT NULL,declared INTEGER NOT NULL DEFAULT 0,declaration_json TEXT,created_at INTEGER NOT NULL,PRIMARY KEY(org,id),UNIQUE(org,key));
+  CREATE TABLE IF NOT EXISTS agent_declaration_heads(org TEXT NOT NULL,key TEXT NOT NULL,agent_id TEXT NOT NULL,generation INTEGER NOT NULL DEFAULT 0,PRIMARY KEY(org,key));
+  CREATE TABLE IF NOT EXISTS agent_assignments(org TEXT NOT NULL,id TEXT NOT NULL,agent_id TEXT NOT NULL,kind TEXT NOT NULL,target TEXT NOT NULL,role TEXT NOT NULL,state TEXT NOT NULL,started_at INTEGER NOT NULL,ended_at INTEGER,PRIMARY KEY(org,id));
+  CREATE INDEX IF NOT EXISTS agent_active_assignments ON agent_assignments(org,agent_id,state);
+  CREATE TABLE IF NOT EXISTS agent_end_outbox(org TEXT NOT NULL,agent_id TEXT NOT NULL,reason TEXT NOT NULL,created_at INTEGER NOT NULL,PRIMARY KEY(org,agent_id));
+  CREATE TABLE IF NOT EXISTS agent_runtime_sessions(org TEXT NOT NULL,runtime_ref TEXT NOT NULL,session_ref TEXT NOT NULL,PRIMARY KEY(org,runtime_ref));
+  CREATE TABLE IF NOT EXISTS agent_runs(org TEXT NOT NULL,agent_id TEXT NOT NULL,session_ref TEXT NOT NULL,machine TEXT,run_id TEXT,profile_json TEXT,published INTEGER NOT NULL DEFAULT 0,ended_at INTEGER,end_reason TEXT,main INTEGER NOT NULL DEFAULT 1,starter_session TEXT,usage_json TEXT,PRIMARY KEY(org,session_ref));`);
+  return db;
+}
+const digest=value=>createHash('sha256').update(value).digest('hex');
+const minted=(key,machine)=>{
+  const reply=runtimeDoor(machine,'harness.v1.agents.mint',{key});
+  if(reply.code===0)return JSON.parse(reply.stdout).id;
+  // A host without the machine daemon (a container running only the orchestrator) mints the same
+  // globally unique shape here; the intent row keyed by this key is what keeps the id stable.
+  if(machine===null&&/machine_offline|ENOENT|ECONNREFUSED|no machine daemon/i.test(reply.stderr))return `agent_${randomBytes(16).toString('hex')}`;
+  throw new Error(`agent id mint unavailable: ${reply.stderr.slice(-500)}`);
+};
+export function agentIntent(root,org,id){const db=store(root);try{const row=db.prepare('SELECT * FROM agent_intents WHERE org=? AND id=?').get(org,id);return row?{...row,profile:JSON.parse(row.profile_json),assignments:db.prepare("SELECT * FROM agent_assignments WHERE org=? AND agent_id=? AND state='active'").all(org,id)}:null;}finally{db.close();}}
+export function assignAgent(root,org,id,{kind,target,role}){
+  const db=store(root),key=digest(JSON.stringify([kind,target,role]));try{db.prepare("INSERT INTO agent_assignments(org,id,agent_id,kind,target,role,state,started_at) VALUES (?,?,?,?,?,?,'active',?) ON CONFLICT(org,id) DO UPDATE SET agent_id=excluded.agent_id,state='active',ended_at=NULL").run(org,key,id,kind,target,role,Date.now());return key;}finally{db.close();}
+}
+export function activeAgentAssignments(root){const db=store(root);try{return db.prepare("SELECT * FROM agent_assignments WHERE state='active'").all();}finally{db.close();}}
+export function reassignAgent(root,org,assignment,to,{context}={}) {
+  const target=agentDoor('management',[to],{context}).data;
+  const db=store(root);
+  try {
+    const old=db.prepare("SELECT * FROM agent_assignments WHERE org=? AND id=? AND state='active'").get(org,assignment);
+    if(!old)throw new Error('active assignment not found');
+    if(old.agent_id!==to)agentDoor('management',[old.agent_id],{context});
+    db.exec('BEGIN IMMEDIATE');
+    const moved=db.prepare("UPDATE agent_assignments SET agent_id=? WHERE org=? AND id=? AND agent_id=? AND state='active'").run(to,org,assignment,old.agent_id);
+    if(moved.changes!==1)throw new Error('assignment changed while reassigning it');
+    db.prepare('DELETE FROM agent_end_outbox WHERE org=? AND agent_id=?').run(org,to);
+    if(old.agent_id!==to&&!db.prepare("SELECT 1 FROM agent_assignments WHERE org=? AND agent_id=? AND state='active'").get(org,old.agent_id))
+      db.prepare('INSERT OR IGNORE INTO agent_end_outbox(org,agent_id,reason,created_at) VALUES (?,?,?,?)').run(org,old.agent_id,`last assignment reassigned to ${to}`,Date.now());
+    db.exec('COMMIT');
+    return {...old,agent_id:to,profile:target.profile};
+  }catch(error){try{db.exec('ROLLBACK');}catch{}throw error;}finally{db.close();}
+}
+export function finishAgentAssignment(root,org,assignment,reason){
+  const db=store(root);try{
+    db.exec('BEGIN IMMEDIATE');
+    const row=db.prepare("SELECT * FROM agent_assignments WHERE org=? AND id=? AND state='active'").get(org,assignment);
+    if(!row){db.exec('COMMIT');return;}
+    const at=Date.now();db.prepare("UPDATE agent_assignments SET state='ended',ended_at=? WHERE org=? AND id=?").run(at,org,assignment);
+    if(!db.prepare("SELECT 1 FROM agent_assignments WHERE org=? AND agent_id=? AND state='active'").get(org,row.agent_id))db.prepare('INSERT OR IGNORE INTO agent_end_outbox(org,agent_id,reason,created_at) VALUES (?,?,?,?)').run(org,row.agent_id,reason,at);
+    db.exec('COMMIT');
+  }catch(error){try{db.exec('ROLLBACK');}catch{}throw error;}finally{db.close();}
+}
+export function synchronizeAgentEnds(root,org,{context}={}){
+  const db=store(root),pending=[];
+  try{
+    for(const row of db.prepare('SELECT * FROM agent_end_outbox WHERE org=? ORDER BY created_at LIMIT 100').all(org)){
+      if(db.prepare("SELECT 1 FROM agent_assignments WHERE org=? AND agent_id=? AND state='active'").get(org,row.agent_id)){db.prepare('DELETE FROM agent_end_outbox WHERE org=? AND agent_id=?').run(org,row.agent_id);continue;}
+      if(db.prepare('SELECT 1 FROM agent_runs WHERE org=? AND agent_id=? AND published=0').get(org,row.agent_id)){pending.push({agent:row.agent_id,error:'session ownership publication remains pending'});continue;}
+      try{
+        agentDoor('end',[row.agent_id,row.reason,digest(`${org}/${row.agent_id}/end/${row.created_at}`)],{context});
+        db.prepare('UPDATE agent_runs SET ended_at=COALESCE(ended_at,?),end_reason=COALESCE(end_reason,?) WHERE org=? AND agent_id=?').run(Date.now(),row.reason,org,row.agent_id);
+        db.prepare('DELETE FROM agent_end_outbox WHERE org=? AND agent_id=?').run(org,row.agent_id);
+      }
+      catch(error){pending.push({agent:row.agent_id,error:error.message});}
+    }
+    return pending;
+  }finally{db.close();}
+}
+/** Mint and retain intent before any network call. Offline declarations keep their immutable id for sync. */
+export function declareAgentIntent({root,org,server,profiles,profile,key,machine=null,refresh=true}) {
+  const intended=resolveAgentProfile(profiles,profile),stable=`${server}/${org}/${key}`,db=store(root);
+  try {
+    const head=db.prepare('SELECT * FROM agent_declaration_heads WHERE org=? AND key=?').get(org,stable);
+    let row=head?db.prepare('SELECT * FROM agent_intents WHERE org=? AND id=?').get(org,head.agent_id):db.prepare('SELECT * FROM agent_intents WHERE org=? AND key=?').get(org,stable);
+    const fresh=!row;
+    if(!row){
+      const id=minted(stable,machine);
+      db.prepare('INSERT INTO agent_intents(org,id,key,profile_ref,profile_json,declared,created_at) VALUES (?,?,?,?,?,0,?) ON CONFLICT(org,key) DO NOTHING').run(org,id,stable,profile,JSON.stringify(intended),Date.now());
+      row=db.prepare('SELECT * FROM agent_intents WHERE org=? AND key=?').get(org,stable);
+    }
+    db.prepare('INSERT OR IGNORE INTO agent_declaration_heads(org,key,agent_id) VALUES (?,?,?)').run(org,stable,row.id);
+    if(refresh)db.prepare('UPDATE agent_intents SET profile_ref=?,profile_json=? WHERE org=? AND id=?').run(profile,JSON.stringify(intended),org,row.id);
+    return {id:row.id,key:row.key,baseKey:stable,declared:!!row.declared,intended:refresh?intended:JSON.parse(row.profile_json),fresh,org};
+  }finally{db.close();}
+}
+function adoptAgentIntent(root,intent,identity){
+  const db=store(root);try{
+    db.exec('BEGIN IMMEDIATE');
+    const existing=db.prepare('SELECT * FROM agent_intents WHERE org=? AND id=?').get(intent.org,identity.id);
+    if(!existing)db.prepare('INSERT INTO agent_intents(org,id,key,profile_ref,profile_json,declared,created_at) VALUES (?,?,?,?,?,1,?)').run(intent.org,identity.id,`${intent.baseKey}/adopted/${identity.id}`,identity.profile,JSON.stringify(intent.intended),Date.now());
+    db.prepare('UPDATE agent_declaration_heads SET agent_id=? WHERE org=? AND key=?').run(identity.id,intent.org,intent.baseKey);
+    db.exec('COMMIT');
+    return {...intent,id:identity.id,key:existing?.key??`${intent.baseKey}/adopted/${identity.id}`,declared:true};
+  }catch(error){try{db.exec('ROLLBACK');}catch{}throw error;}finally{db.close();}
+}
+function nextAgentGeneration(root,intent,machine){
+  const db=store(root);try{
+    db.exec('BEGIN IMMEDIATE');
+    const head=db.prepare('SELECT * FROM agent_declaration_heads WHERE org=? AND key=?').get(intent.org,intent.baseKey);
+    if(head.agent_id!==intent.id){
+      const row=db.prepare('SELECT * FROM agent_intents WHERE org=? AND id=?').get(intent.org,head.agent_id);db.exec('COMMIT');
+      return {...intent,id:row.id,key:row.key,declared:!!row.declared};
+    }
+    const generation=head.generation+1,key=`${intent.baseKey}/generation/${generation}`,id=minted(key,machine);
+    db.prepare('INSERT INTO agent_intents(org,id,key,profile_ref,profile_json,created_at) VALUES (?,?,?,?,?,?)').run(intent.org,id,key,intent.intended.profile,JSON.stringify(intent.intended),Date.now());
+    db.prepare('UPDATE agent_declaration_heads SET agent_id=?,generation=? WHERE org=? AND key=?').run(id,generation,intent.org,intent.baseKey);
+    db.exec('COMMIT');return {...intent,id,key,declared:false};
+  }catch(error){try{db.exec('ROLLBACK');}catch{}throw error;}finally{db.close();}
+}
+function synchronizeIntent(intent,{root,context,body}) {
+  let identity;
+  if(intent.declared)identity=agentDoor('get',[intent.id],{context}).data;
+  else {
+    try{identity=agentDoor('declare',[{...body,id:intent.id},digest(intent.key)],{context}).data;}
+    catch(error){if(error.code==='idempotency_conflict')identity=agentDoor('get',[intent.id],{context}).data;else throw error;}
+    identity=agentDoor('get',[intent.id],{context}).data;
+    const db=store(root);try{db.prepare('UPDATE agent_intents SET declared=1 WHERE org=? AND id=?').run(intent.org,intent.id);}finally{db.close();}
+  }
+  if(identity.state!=='active')throw new Error(`agent ${identity.path} is ${identity.state}: ${identity.suspension_reason??identity.end_reason??'unavailable'}`);
+  if(body.profile!==identity.profile)identity=agentDoor('profile',[identity.id,body.profile,identity.revision],{context}).data;
+  if(body.parent!==undefined&&body.parent!==identity.parent)identity=agentDoor('reparent',[identity.id,body.parent,identity.revision],{context}).data;
+  return identity;
+}
+export function ensureRootAgent(options) {
+  const {root,org,context,profile=options.profiles.default?'default':null}=options;
+  if(!profile)throw new Error('declare the Org root with a named profile before launching card agents');
+  let intent=declareAgentIntent({...options,profile,key:'root'});
+  let identity;
+  try{identity=agentDoor('root',[],{context}).data;}
+  catch(error){
+    if(error.status!==404)throw error;
+    try{identity=synchronizeIntent(intent,{root,context,body:{name:basename(root),profile,root:true}});}
+    catch(conflict){if(conflict.status!==409)throw conflict;identity=agentDoor('root',[],{context}).data;}
+  }
+  if(identity.state==='ended'){
+    if(intent.id!==identity.id)intent=adoptAgentIntent(root,intent,identity);
+    intent=nextAgentGeneration(root,intent,options.machine);
+    identity=synchronizeIntent(intent,{root,context,body:{name:identity.name,profile,root:true}});
+  }
+  if(intent.id!==identity.id)adoptAgentIntent(root,intent,identity);
+  // Another admitted manager may have declared the root first; its server id remains authoritative.
+  if(identity.state!=='active')throw new Error('the Org root agent is not active');
+  return identity;
+}
+/** Cold starts and relaunches use the same local intent and public declaration. Reviewer and implementer keys differ. */
+export function ensureCardAgent(options) {
+  const {root,org,profiles,profile,card,role,sponsor=null,context}=options;
+  const assigned=activeAgentAssignments(root).find(item=>item.org===org&&item.kind==='card'&&item.target===card&&item.role===role);
+  // A locally minted agent that has not reached Teams yet is declared below under the same key and id.
+  if(assigned&&agentIntent(root,org,assigned.agent_id)?.declared!==0) {
+    const identity=agentDoor('get',[assigned.agent_id],{context}).data;
+    if(identity.state==='active'){
+      const intended=resolveAgentProfile(profiles,identity.profile);
+      const db=store(root);try{db.prepare('UPDATE agent_intents SET profile_ref=?,profile_json=? WHERE org=? AND id=?').run(identity.profile,JSON.stringify(intended),org,identity.id);}finally{db.close();}
+      return {identity,intended,assignment:assigned.id,
+        assignments:activeAgentAssignments(root).filter(item=>item.org===org&&item.agent_id===identity.id),org};
+    }
+    if(identity.state!=='ended')throw new Error(`card's assigned agent is ${identity.state}`);
+    finishAgentAssignment(root,org,assigned.id,`agent ${identity.id} is ended`);
+  }
+  let intent=declareAgentIntent({...options,key:`card/${card}/${role}`});
+  const rootAgent=ensureRootAgent({...options,profile:profiles.default?'default':profile});
+  if(!intent.declared){
+    const existing=agentDoor('find',[`${card}-${role}`,rootAgent.id],{context}).data;
+    if(existing){
+      intent=adoptAgentIntent(root,intent,existing);
+    }
+  }
+  if(intent.declared&&agentDoor('get',[intent.id],{context}).data.state==='ended')intent=nextAgentGeneration(root,intent,options.machine);
+  const identity=synchronizeIntent(intent,{root,context,body:{name:`${card}-${role}`,parent:rootAgent.id,sponsor,profile,...(options.starterSession?{starter_session:options.starterSession}:{})}});
+  const assignment=assignAgent(root,org,identity.id,{kind:'card',target:card,role});
+  return {identity,intended:intent.intended,assignment,assignments:[{kind:'card',target:card,role}],org};
+}
+/** Starting a named profile declares its standing agent; bindings are sessions of that identity. */
+export function ensureProfileAgent(options){
+  const {root,org,profiles,profile,context,agent:declared=null,declarations={}}=options;
+  if(declared&&declared!==profile){
+    // A declared agent (the IR's `agents`) runs as a shared profile under its own identity and parent.
+    const decl=declarations[declared]??{};
+    const rootAgent=ensureRootAgent({...options,profile:profiles.default?'default':profile});
+    const parent=decl.parent?ensureProfileAgent({...options,profile:declarations[decl.parent]?.profile??decl.parent,agent:decl.parent}).identity:rootAgent;
+    let declaration=declareAgentIntent({...options,key:`agent/${declared}`});
+    if(!declaration.declared){
+      const existing=agentDoor('find',[declared,parent.id],{context}).data;
+      if(existing)declaration=adoptAgentIntent(root,declaration,existing);
+    }
+    if(declaration.declared&&agentDoor('get',[declaration.id],{context}).data.state==='ended')declaration=nextAgentGeneration(root,declaration,options.machine);
+    const identity=synchronizeIntent(declaration,{root,context,body:{name:declared,parent:parent.id,profile,...(decl.sponsor?{sponsor:decl.sponsor}:{})}});
+    const assignment=assignAgent(root,org,identity.id,{kind:'agent',target:declared,role:'declared'});
+    return {identity,intended:declaration.intended,assignment,assignments:[{kind:'agent',target:declared,role:'declared'}],org};
+  }
+  const rootAgent=ensureRootAgent({...options,profile:profiles.default?'default':profile});
+  let identity=rootAgent,intent;
+  if(profile===(profiles.default?'default':profile))intent=agentIntent(root,org,identity.id)?.profile;
+  else{
+    // Profile ancestry and agent parentage are the same intended narrowing tree.
+    // Resolve first to reject a cycle before declaring any parent along it.
+    resolveAgentProfile(profiles,profile);
+    const parentProfile=profiles[profile].parent;
+    const parent=parentProfile?ensureProfileAgent({...options,profile:parentProfile}).identity:rootAgent;
+    let declaration=declareAgentIntent({...options,key:`profile/${profile}`});
+    if(!declaration.declared){
+      const existing=agentDoor('find',[profile,parent.id],{context}).data;
+      if(existing)declaration=adoptAgentIntent(root,declaration,existing);
+    }
+    if(declaration.declared&&agentDoor('get',[declaration.id],{context}).data.state==='ended')declaration=nextAgentGeneration(root,declaration,options.machine);
+    identity=synchronizeIntent(declaration,{root,context,body:{name:profile,parent:parent.id,profile}});
+    intent=declaration.intended;
+  }
+  const assignment=assignAgent(root,org,identity.id,{kind:'profile',target:profile,role:'profile'});
+  return {identity,intended:intent??resolveAgentProfile(profiles,profile),assignment,assignments:[{kind:'profile',target:profile,role:'profile'}],org};
+}
+/** An explicit fork declares a child; a routine helper launch keeps its starter's identity. */
+export function ensureForkAgent(options) {
+  const {root,org,profiles,parent,session,name,key,context}=options;
+  const managed=agentDoor('management',[parent],{context}).data;
+  const source=agentDoor('session',[session],{context}).data;
+  if(source.agent?.id!==parent)throw new Error('fork source is not owned by the declared parent');
+  const parentIntent=agentIntent(root,org,parent)?.profile??resolveAgentProfile(profiles,managed.profile);
+  let intent=declareAgentIntent({...options,profile:managed.profile,key:`fork/${parent}/${key}`,refresh:false});
+  if(intent.declared&&agentDoor('get',[intent.id],{context}).data.state==='ended')throw new Error('this fork identity ended; declare a new fork key');
+  // The snapshot copies configuration only. Memory stays the new child's own empty state.
+  const intended=structuredClone(intent.fresh?parentIntent:intent.intended);
+  const db=store(root);try{db.prepare('UPDATE agent_intents SET profile_json=? WHERE org=? AND id=?').run(JSON.stringify(intended),org,intent.id);}finally{db.close();}
+  const identity=synchronizeIntent(intent,{root,context,body:{name,parent,profile:managed.profile,starter_session:session}});
+  const assignment=assignAgent(root,org,identity.id,{kind:'fork',target:session,role:key});
+  return {identity,intended,assignment,assignments:[{kind:'fork',target:session,role:key}],org};
+}
+export function agentRunForKey(root,org,agent,key) {
+  const db=store(root);try{return db.prepare('SELECT * FROM agent_runs WHERE org=? AND agent_id=? AND run_id=? ORDER BY rowid DESC LIMIT 1').get(org,agent,key)??null;}finally{db.close();}
+}
+function recordDeclaration(root,org,id,declaration){
+  const db=store(root);try{db.prepare('UPDATE agent_intents SET declaration_json=? WHERE org=? AND id=? AND declared=0').run(JSON.stringify(declaration),org,id);}finally{db.close();}
+}
+/** Situation 16: no reachable Teams. The daemon-minted id and retained intent stand in for the declaration,
+ * which synchronizeLocalAgents later makes under the same id. Nothing is granted from this local record. */
+function localAgent(options,{key,name,declaration,assignment,parent=null,starter}){
+  const {root,org,server,profiles,profile,machine=null}=options;
+  const rootProfile=profiles.default?'default':profile;
+  const rootIntent=declareAgentIntent({root,org,server,profiles,profile:rootProfile,key:'root',machine,refresh:false});
+  recordDeclaration(root,org,rootIntent.id,{kind:'root',profile:rootProfile});
+  const intent=key==='root'?rootIntent:declareAgentIntent({root,org,server,profiles,profile,key,machine});
+  if(key!=='root')recordDeclaration(root,org,intent.id,declaration);
+  const above=parent??(key==='root'?null:{id:rootIntent.id,path:basename(root)});
+  const identity={id:intent.id,kind:'agent',org,name,path:above?`${above.path}/${name}`:name,parent:above?.id??null,
+    lineage:{starter},sponsor:options.sponsor??null,explicit_sponsor:options.sponsor??null,profile,state:'active',
+    synced:false,main_session:null,revision:0};
+  const assigned=assignAgent(root,org,intent.id,assignment);
+  return {identity,intended:intent.intended,assignment:assigned,assignments:[assignment],org,synced:false};
+}
+export function localCardAgent(options){
+  const {card,role,profile}=options;
+  return localAgent(options,{key:`card/${card}/${role}`,name:`${card}-${role}`,assignment:{kind:'card',target:card,role},
+    declaration:{kind:'card',card,role,profile,sponsor:options.sponsor??null,starterSession:options.starterSession??null},
+    starter:options.starterSession?{kind:'session',id:options.starterSession}:{kind:'automation',id:`board:${basename(options.root)}`}});
+}
+export function localProfileAgent(options){
+  const {root,profiles,profile,agent:declared=null,declarations={}}=options,rootProfile=profiles.default?'default':profile;
+  const starter={kind:'automation',id:`orchestrator:${basename(root)}`};
+  if(declared&&declared!==profile){
+    const decl=declarations[declared]??{};
+    return localAgent({...options,sponsor:decl.sponsor??null},{key:`agent/${declared}`,name:declared,assignment:{kind:'agent',target:declared,role:'declared'},
+      declaration:{kind:'declared',agent:declared,profile},starter});
+  }
+  if(profile===rootProfile)return localAgent(options,{key:'root',name:basename(root),assignment:{kind:'profile',target:profile,role:'profile'},declaration:{kind:'root',profile},starter});
+  resolveAgentProfile(profiles,profile);
+  const parentProfile=profiles[profile].parent,parent=parentProfile&&parentProfile!==rootProfile?localProfileAgent({...options,profile:parentProfile}).identity:null;
+  return localAgent(options,{key:`profile/${profile}`,name:profile,parent,assignment:{kind:'profile',target:profile,role:'profile'},declaration:{kind:'profile',profile},starter});
+}
+/** A local identity for a retained run: its id, intent and assignments, without a Teams record. */
+export function localAgentRecord(root,org,id){
+  const intent=agentIntent(root,org,id);if(!intent)return null;
+  const declaration=intent.declaration_json?JSON.parse(intent.declaration_json):{};
+  const name=declaration.kind==='card'?`${declaration.card}-${declaration.role}`:declaration.kind==='profile'?declaration.profile:declaration.kind==='declared'?declaration.agent:basename(root);
+  return {identity:{id,kind:'agent',org,name,path:declaration.kind==='root'?name:`${basename(root)}/${name}`,parent:null,lineage:{starter:null},
+    sponsor:declaration.sponsor??null,profile:intent.profile_ref,state:'active',synced:!!intent.declared,main_session:null,revision:0},
+    intended:intent.profile,assignments:intent.assignments,org,synced:!!intent.declared};
+}
+/** Earlier sessions this home ran for an agent, for a relaunch's pointers when Teams cannot list them. */
+export function localAgentSessions(root,org,id){
+  const db=store(root);try{return db.prepare('SELECT session_ref AS session,machine,ended_at,end_reason FROM agent_runs WHERE org=? AND agent_id=? ORDER BY rowid DESC LIMIT 200').all(org,id);}finally{db.close();}
+}
+/** Move identities minted before any Teams context into the Org that is now selected, keeping their ids. */
+function adoptLocalOrg(root,scope){
+  const db=store(root);
+  try{
+    if(!db.prepare("SELECT 1 FROM agent_intents WHERE org='local' LIMIT 1").get())return;
+    db.exec('BEGIN IMMEDIATE');
+    const from='local/local/',to=`${scope.server}/${scope.org}/`,rekey=key=>key.startsWith(from)?to+key.slice(from.length):key;
+    const ids=new Map();
+    for(const row of db.prepare("SELECT * FROM agent_intents WHERE org='local'").all()){
+      // An identity the Org already declared for the same key wins; the local id folds into it.
+      const existing=db.prepare('SELECT id FROM agent_intents WHERE org=? AND key=?').get(scope.org,rekey(row.key));
+      ids.set(row.id,existing?.id??row.id);
+      if(!existing)db.prepare('INSERT INTO agent_intents(org,id,key,profile_ref,profile_json,declared,declaration_json,created_at) VALUES (?,?,?,?,?,0,?,?)').run(scope.org,row.id,rekey(row.key),row.profile_ref,row.profile_json,row.declaration_json,row.created_at);
+    }
+    for(const head of db.prepare("SELECT * FROM agent_declaration_heads WHERE org='local'").all())
+      db.prepare('INSERT OR IGNORE INTO agent_declaration_heads(org,key,agent_id,generation) VALUES (?,?,?,?)').run(scope.org,rekey(head.key),ids.get(head.agent_id)??head.agent_id,head.generation);
+    for(const [old,id] of ids)for(const table of ['agent_assignments','agent_runs','agent_end_outbox'])
+      db.prepare(`UPDATE OR IGNORE ${table} SET org=?,agent_id=? WHERE org='local' AND agent_id=?`).run(scope.org,id,old);
+    db.prepare("UPDATE OR IGNORE agent_runtime_sessions SET org=? WHERE org='local'").run(scope.org);
+    for(const table of ['agent_intents','agent_declaration_heads','agent_assignments','agent_runs','agent_end_outbox','agent_runtime_sessions'])db.prepare(`DELETE FROM ${table} WHERE org='local'`).run();
+    db.exec('COMMIT');
+  }catch(error){try{db.exec('ROLLBACK');}catch{}throw error;}finally{db.close();}
+}
+/** Declare every locally minted identity once Teams is reachable, under the id its sessions already carry. */
+export function synchronizeLocalAgents({root,profiles,context,machine=null,declarations={}}){
+  const scope=agentScope(context);if(scope.offline)return [];
+  adoptLocalOrg(root,scope);
+  const db=store(root);let rows;
+  try{rows=db.prepare('SELECT * FROM agent_intents WHERE org=? AND declared=0 AND declaration_json IS NOT NULL ORDER BY created_at').all(scope.org);}finally{db.close();}
+  const pending=[],base={root,org:scope.org,server:scope.server,profiles,context,machine};
+  for(const row of rows){
+    const declaration=JSON.parse(row.declaration_json);
+    try{
+      if(declaration.kind==='root')ensureRootAgent({...base,profile:declaration.profile});
+      else if(declaration.kind==='card')ensureCardAgent({...base,profile:declaration.profile,card:declaration.card,role:declaration.role,sponsor:declaration.sponsor,starterSession:declaration.starterSession});
+      else if(declaration.kind==='profile')ensureProfileAgent({...base,profile:declaration.profile});
+      else if(declaration.kind==='declared')ensureProfileAgent({...base,profile:declaration.profile,agent:declaration.agent,declarations});
+    }catch(error){if(!teamsUnavailable(error))pending.push({agent:row.id,error:error.message});else return [...pending,{agent:row.id,error:error.message}];}
+  }
+  return pending;
+}
+/** A managed runtime may report its native id after opening. Keep the lease pointer out of the catalogue. */
+export function recordNativeAgentSession(root,runtimeRef,session) {
+  const owner=agentRunForSession(root,[runtimeRef]);
+  if(!owner||owner.session_ref===session)return owner;
+  recordAgentRun(root,owner.org,owner.agent_id,{session,machine:owner.machine,run:owner.run_id,
+    profile:owner.profile_json?JSON.parse(owner.profile_json):null,main:owner.main===1,starterSession:owner.starter_session});
+  const db=store(root);try{
+    db.exec('BEGIN IMMEDIATE');
+    db.prepare('INSERT INTO agent_runtime_sessions(org,runtime_ref,session_ref) VALUES (?,?,?) ON CONFLICT(org,runtime_ref) DO UPDATE SET session_ref=excluded.session_ref').run(owner.org,runtimeRef,session);
+    // A published native session remains history; an unpublished lease-only row is not a session.
+    db.prepare('DELETE FROM agent_runs WHERE org=? AND session_ref=? AND published=0').run(owner.org,runtimeRef);
+    db.exec('COMMIT');
+  }catch(error){try{db.exec('ROLLBACK');}catch{}throw error;}finally{db.close();}
+  return agentRunForSession(root,[runtimeRef]);
+}
+/** Join an observed native session through the public catalogue; unknown catalogue state remains pending. */
+export function synchronizeAgentRun(root,org,row,{context,intended}={}) {
+  const response=agentDoor('ownSession',[row.agent_id,{session:row.session_ref,main:row.main!==0&&row.main!==false,...(row.starter_session?{starter_session:row.starter_session}:{})},digest(`${org}/${row.agent_id}/${row.session_ref}`)],{context});
+  const intent=agentIntent(root,org,row.agent_id);
+  const runtime=agentDoor('bindContext',[row.agent_id,row.session_ref,row.machine,intent?.assignments??[],intended??intent?.profile.resolved],{context});
+  publishAgentRun(root,org,row.session_ref);
+  return {...response.data,runtime};
+}
+export function recordAgentRun(root,org,id,{session,machine=null,run,profile=null,main=true,starterSession=null}){
+  const db=store(root);try{
+    db.exec('BEGIN IMMEDIATE');
+    const old=db.prepare('SELECT agent_id FROM agent_runs WHERE org=? AND session_ref=?').get(org,session);
+    if(old&&old.agent_id!==id)throw new Error('local session ownership cannot change agent identity');
+    db.prepare('INSERT INTO agent_runs(org,agent_id,session_ref,machine,run_id,profile_json,main,starter_session) VALUES (?,?,?,?,?,?,?,?) ON CONFLICT(org,session_ref) DO UPDATE SET machine=excluded.machine,run_id=excluded.run_id,profile_json=COALESCE(excluded.profile_json,agent_runs.profile_json),main=excluded.main,starter_session=COALESCE(agent_runs.starter_session,excluded.starter_session) WHERE agent_runs.machine IS NOT excluded.machine OR agent_runs.run_id IS NOT excluded.run_id OR (excluded.profile_json IS NOT NULL AND agent_runs.profile_json IS NOT excluded.profile_json) OR agent_runs.main IS NOT excluded.main OR (agent_runs.starter_session IS NULL AND excluded.starter_session IS NOT NULL)').run(org,id,session,machine,String(run),profile?JSON.stringify(profile):null,main?1:0,starterSession);
+    db.exec('COMMIT');
+  }catch(error){try{db.exec('ROLLBACK');}catch{}throw error;}finally{db.close();}
+}
+export function pendingAgentRuns(root,org){const db=store(root);try{return db.prepare('SELECT * FROM agent_runs WHERE org=? AND published=0 ORDER BY rowid LIMIT 100').all(org);}finally{db.close();}}
+/** Session references come from the bound runtime, never from a model's requested agent id. */
+export function agentRunForSession(root, references) {
+  const db = store(root);
+  try {
+    const rows = references.filter(Boolean).flatMap(ref => {
+      const aliases=db.prepare('SELECT r.* FROM agent_runtime_sessions a JOIN agent_runs r ON r.org=a.org AND r.session_ref=a.session_ref WHERE a.runtime_ref=?').all(ref);
+      return aliases.length?aliases:db.prepare('SELECT * FROM agent_runs WHERE session_ref=?').all(ref);
+    });
+    const owners = new Map(rows.map(row => [JSON.stringify([row.org, row.agent_id]), row]));
+    if (owners.size > 1) throw new Error('session references have conflicting agent ownership');
+    return owners.values().next().value ?? null;
+  } finally { db.close(); }
+}
+/** G3: a session's usage as its harness recorded it, kept with the run that owned it. */
+export function recordRunUsage(root,org,session,usage){
+  const db=store(root);try{db.prepare('UPDATE agent_runs SET usage_json=? WHERE org=? AND session_ref=?').run(JSON.stringify(usage??[]),org,session);}finally{db.close();}
+}
+/** The runs whose ended sessions have no usage recorded yet. */
+export function runsAwaitingUsage(root,org){
+  const db=store(root);try{return db.prepare('SELECT * FROM agent_runs WHERE org=? AND usage_json IS NULL ORDER BY rowid LIMIT 50').all(org);}finally{db.close();}
+}
+/** Usage records per agent id: every session this home ran for it. */
+export function agentUsage(root){
+  const db=store(root),by=new Map();
+  try{for(const row of db.prepare('SELECT agent_id,session_ref,usage_json FROM agent_runs WHERE usage_json IS NOT NULL').all()){
+    const list=by.get(row.agent_id)??[];list.push(...JSON.parse(row.usage_json).map(u=>({...u,session:row.session_ref})));by.set(row.agent_id,list);
+  }}finally{db.close();}
+  return by;
+}
+/** The budget a card run would exceed, as a sentence, or null (G3: a per-action gate, never a pause). */
+export function runBudgetRefusal(root,agent,budgets,now){
+  const used=agentUsage(root).get(agent)??[],day=now.slice(0,10),month=now.slice(0,7);
+  for(const budget of budgets??[]){
+    let tokens=0,cost=0;
+    for(const u of used){
+      if(budget.period==='day'&&!u.at.startsWith(day))continue;
+      if(budget.period==='month'&&!u.at.startsWith(month))continue;
+      if(budget.period==='run')continue;
+      tokens+=(u.input_tokens??0)+(u.output_tokens??0);cost+=u.cost?.amount??0;
+    }
+    if(budget.limit?.tokens!=null&&tokens>=budget.limit.tokens)return `agent ${agent} has used ${tokens} of its ${budget.limit.tokens}-token ${budget.period} budget`;
+    if(budget.limit?.cost!=null&&cost>=budget.limit.cost.amount)return `agent ${agent} has spent ${cost} of its ${budget.limit.cost.amount} ${budget.limit.cost.currency} ${budget.period} budget`;
+  }
+  return null;
+}
+export function publishAgentRun(root,org,session){const db=store(root);try{db.prepare('UPDATE agent_runs SET published=1 WHERE org=? AND session_ref=?').run(org,session);}finally{db.close();}}
+export function agentPreamble(agent,{main=true,previous=[]}={}){
+  const {identity:a,intended,assignments=[]}=agent;
+  return `You are agent ${a.path} (${a.id}), ${main?'its main session':'a concurrent session'}.${a.synced===false?' This identity was minted on this machine and is not yet declared on a Teams server; it keeps this id when it is.':''}\nSponsor: ${a.sponsor??'none yet'}; parent: ${a.parent??'none'}; lineage: ${JSON.stringify(a.lineage)}.\nAssignments: ${assignments.map(value=>`${value.kind} ${value.target}, role ${value.role}`).join("; ")}; profile: ${a.profile}; permission layers: ${JSON.stringify(intended.resolved.permissions.layers)}.\nAsk again with supercode agent whoami. List your sessions with supercode agent sessions; read a transcript only when needed.${previous.length?'\nEarlier sessions:\n'+previous.map(s=>`${s.session} · ${s.machine??'unknown machine'} · ended ${s.ended_at??'live'} · ${s.end_reason??''}`).join('\n'):''}`;
+}
+export function agentProfileMismatch(intent,resolved){return compareAgentProfile(intent?.resolved??intent,resolved);}
+
+export function agentEnvironment(agent,{root,context,session=null,main=true}={}) {
+  const a=agent.identity;
+  return {SUPERCODE_AGENT_ID:a.id,SUPERCODE_AGENT_NAME:a.name,SUPERCODE_AGENT_PATH:a.path,
+    SUPERCODE_AGENT_ORG:a.org,SUPERCODE_AGENT_HOME:root,SUPERCODE_AGENT_CONTEXT:context??'',
+    SUPERCODE_AGENT_MAIN:main?'1':'0',SUPERCODE_AGENT_SYNCED:a.synced===false?'0':'1',SUPERCODE_AGENT_ASSIGNMENTS:JSON.stringify(agent.assignments??[]),
+    ...(session?{SUPERCODE_AGENT_SESSION:session}:{})};
+}

package/bin/agent-door.mjs

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+// The orchestrator's synchronous host reaches Teams through the installed neutral SDK.
+import { fromContext } from '@volter/teams/context';
+import { supercodeHome } from '@volter/teams/home';
+import { createHash } from 'node:crypto';
+import { openMachine } from '@volter/teams/machine-door';
+import { StreamRpc } from '@volter/teams/client';
+let input='';for await(const chunk of process.stdin)input+=chunk;
+try{
+  const {op,args=[],context}=JSON.parse(input);
+  const {client,context:scope}=fromContext({supercodeHome:supercodeHome(),name:context??process.env.SUPERCODE_CONTEXT});
+  const team=client.team(scope.team_id),options={signal:AbortSignal.timeout(20000)};
+  let result;
+  if(op==='scope')result={server:scope.origin,server_id:scope.server_id,org:scope.team_id,principal:scope.principal_id};
+  else if(op==='root')result=await team.agents.root(options);
+  else if(op==='get')result=await team.agents.get(args[0],options);
+  else if(op==='management')result=await team.agents.management(args[0],options);
+  else if(op==='profile')result=await team.agents.update(args[0],{profile:args[1]},{...options,ifMatch:args[2]});
+  else if(op==='reparent')result=await team.agents.update(args[0],{parent:args[1]},{...options,ifMatch:args[2]});
+  else if(op==='declare')result=await team.agents.declare(args[0],{...options,idempotencyKey:args[1]});
+  else if(op==='sessions')result=await team.agents.sessions(args[0],args[1]??{},options);
+  else if(op==='ownSession')result=await team.agents.ownSession(args[0],args[1],{...options,idempotencyKey:args[2]});
+  else if(op==='session')result=await team.sessions.get(args[0]).identity(options);
+  else if(op==='end'){
+    const agent=(await team.agents.get(args[0],options)).data;
+    result=agent.state==='ended'?{data:{id:agent.id,state:'ended'}}:await team.agents.end(agent.id,{reason:args[1]},{...options,ifMatch:agent.revision,idempotencyKey:args[2]});
+  }
+  else if(op==='reader')result=await team.agents.delegateReader(args[0],{},{...options,ifMatch:args[1]});
+  else if(op==='bindContext'){
+    const key=createHash('sha256').update(`${scope.origin}/${scope.team_id}/${args[0]}`).digest('hex');
+    const channel=await openMachine({machine:args[2]??null,context:context??process.env.SUPERCODE_CONTEXT});
+    try{const rpc=new StreamRpc(await channel.open('node'));result=await rpc.call('harness.v1.agents.bindSession',{session:args[1],context:`agent-${key.slice(0,32)}`,assignments:args[3]??[],intended:args[4]??null});}
+    finally{channel.close();}
+  }
+  else if(op==='readerContext'){
+    const identity=await team.agents.get(args[0],options);
+    const reader=await team.agents.delegateReader(args[0],{expires_in_ms:86400000},{...options,ifMatch:identity.data.revision});
+    const channel=await openMachine({machine:args[1]??null,context:context??process.env.SUPERCODE_CONTEXT});
+    try{const rpc=new StreamRpc(await channel.open('node'));result=await rpc.call('harness.v1.agents.context',{origin:scope.origin,team:scope.team_id,agent:args[0],credential:reader.data});}
+    finally{channel.close();}
+  }
+  else if(op==='resolveIdentity')result=await team.identity.resolve(args[0],options);
+  else if(op==='find'){
+    let after='',found=null;
+    do{
+      const page=await team.agents.list({after,limit:200},options);
+      found=page.items.find(agent=>agent.name===args[0]&&agent.parent===args[1]&&agent.state!=='ended')??null;
+      if(found)break;after=page.next_after;
+    }while(after);
+    result={data:found};
+  }else throw Object.assign(new Error('unsupported agent door'),{code:'invalid_request'});
+  process.stdout.write(JSON.stringify(result)+'\n');
+}catch(error){process.stderr.write(JSON.stringify({status:error.status,code:error.code??'unavailable',message:error.message})+'\n');process.exitCode=1;}

package/bin/runtime-door.mjs

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+// A synchronous board process delegates one request to the public daemon door.
+// This helper owns neither credentials nor machine state; the SDK opens the admitted channel.
+import { openMachine } from '@volter/teams/machine-door';
+import { StreamRpc, harnessTransport } from '@volter/teams/client';
+import { SupercodeHarnessClient } from '@volter/supercode-harness-sdk';
+let input = ''; for await (const chunk of process.stdin) input += chunk;
+let channel;
+try {
+  const { machine, method, params = {} } = JSON.parse(input);
+  if (!method.startsWith('harness.v1.')) throw new Error('the runtime door accepts harness.v1 methods');
+  channel = await openMachine({machine});
+  let result;
+  if (method.startsWith('harness.v1.sessions.')) {
+    // A session's records are the harness's own service, spoken by its SDK over the machine's harness stream.
+    const client = new SupercodeHarnessClient({ transport: harnessTransport(channel) });
+    try { await client.start?.(); result = await client.request(method, params); } finally { await client.close?.(); }
+  } else result = await new StreamRpc(await channel.open('node')).call(method,params);
+  process.stdout.write(JSON.stringify(result)+'\n');
+} catch (error) {
+  process.stderr.write(JSON.stringify({code:error.code??'unavailable',message:error.message})+'\n');
+  process.exitCode = 1;
+} finally { channel?.close(); }