@volter/teams 0.1.89 → 0.2.0

package/server/agents.mjs

@@ -0,0 +1,286 @@
+// Teams owns agent identity. Orchestrator-owned assignments and profile values are references here.
+import { AGENT_ACTIVE } from './agent-authority.mjs';
+import { isAdmin, makeToken, hashToken, APP_LINEAGE_REVOKED } from './auth.mjs';
+import { exact } from './request-json.mjs';
+import { closeChannelsFor, closeActorChannels } from './machine-link.mjs';
+import { nativeSessionSnapshot } from './session-snapshot.mjs';
+const fail=(status,code,message)=>{throw Object.assign(new Error(message),{status,code});};
+const parse=JSON.parse;
+const stmt=(sql,...params)=>({sql,params});
+const guard=(sql,params,message='agent authority changed')=>({sql,params,status:403,code:'forbidden',message});
+const text=(value,label,max=256)=>{
+  if(typeof value!=='string'||!value.trim()||value.length>max||/[\x00-\x1f]/.test(value))fail(400,'invalid_request',`${label} must be a nonempty string`);
+  return value;
+};
+const kind=value=>({user:'person',service:'automation',agent:'agent'}[value]);
+const liveGuards=(auth,now)=>[
+  guard('SELECT 1 FROM credentials WHERE id=? AND revoked_at IS NULL AND (expires_at IS NULL OR expires_at>?)',[auth.credential_id,now]),
+  guard('SELECT 1 FROM memberships WHERE team_id=? AND principal_id=? AND active=1',[auth.team_id,auth.principal_id]),
+];
+function authority(auth){
+  if(!auth.active||!['user','service'].includes(auth.kind)||auth.app_grants!=null)fail(403,'forbidden','agent identity requires an unfenced member credential');
+}
+const personSql=`SELECT p.id FROM principals p WHERE p.id=? AND p.kind='user' AND
+ (EXISTS(SELECT 1 FROM memberships m WHERE m.team_id=? AND m.principal_id=p.id AND m.active=1)
+ OR EXISTS(SELECT 1 FROM identity_principals i WHERE i.team_id=? AND i.principal_id=p.id)
+ AND NOT EXISTS(SELECT 1 FROM memberships m WHERE m.team_id=? AND m.principal_id=p.id AND m.active=0))`;
+async function person(api,team,id){return id?await api.store.one(personSql,[id,team,team,team]):null;}
+const personGuard=(team,id)=>guard(personSql,[id,team,team,team],'sponsor must remain a person in this Org');
+/** An explicit selector names an Org person; it is never an inferred requester link.
+ * Resolve ids first, then an unambiguous exact display name (including an email).
+ * Authorization still runs against the canonical person id, with the resolution guarded.
+ */
+async function selectedSponsor(api,team,selector,guards){
+  if(selector==null)return null;
+  text(selector,'sponsor',256);
+  const direct=await person(api,team,selector);if(direct)return direct.id;
+  const sql=personSql.replace('p.id=?','p.display_name=?');
+  const people=await api.store.query(sql,[selector,team,team,team]);
+  if(people.length!==1)fail(400,'invalid_request','sponsor must name one person in this Org; use their principal id if the name is ambiguous');
+  const id=people[0].id;
+  guards.push(guard(`SELECT 1 WHERE (SELECT count(*) FROM (${sql}))=1 AND EXISTS(${sql} AND p.id=?)`,[selector,team,team,team,selector,team,team,team,id],'sponsor selector changed'));
+  return id;
+}
+
+
+/** Inheritance is recomputed from current standing; an inferred identity never enters this chain.
+ * Mutation callers retain the exact standing reads as atomic guards, including declined candidates.
+ */
+export async function agentSponsor(api,team,row,seen=new Set(),guards=null){
+  if(!row||seen.has(row.id))return null;seen.add(row.id);
+  if(guards)guards.push(guard('SELECT 1 FROM agents WHERE team_id=? AND id=? AND revision=?',[team,row.id,row.revision],'sponsor ancestry changed'));
+  const eligible=async id=>{
+    if(!id)return false;
+    const yes=Boolean(await person(api,team,id));
+    if(guards)guards.push(guard(`SELECT 1 WHERE EXISTS(${personSql})=?`,[id,team,team,team,yes?1:0],'person standing changed'));
+    return yes;
+  };
+  if(await eligible(row.sponsor_id))return row.sponsor_id;
+  if(row.parent_id){
+    const parent=await api.store.one("SELECT * FROM agents WHERE team_id=? AND id=? AND state!='ended'",[team,row.parent_id]);
+    const inherited=await agentSponsor(api,team,parent,seen,guards);if(inherited)return inherited;
+  }
+  let starter=parse(row.lineage_json).starter;
+  // A plain session's historical starter supplies accountability, never its identity.
+  while(starter?.kind==='session'&&starter.delegator)starter=starter.delegator;
+  if(!starter)return null;
+  if(starter.kind==='person'&&await eligible(starter.id))return starter.id;
+  if(starter.kind==='agent')return agentSponsor(api,team,await api.store.one("SELECT * FROM agents WHERE team_id=? AND id=? AND state!='ended'",[team,starter.id]),seen,guards);
+  const sponsorQuery='SELECT sponsor_id FROM principal_sponsors WHERE team_id=? AND principal_id=?';
+  const named=await api.store.one(sponsorQuery,[team,starter.id]);
+  if(guards)guards.push(guard(`SELECT 1 WHERE COALESCE((${sponsorQuery}),'')=?`,[team,starter.id,named?.sponsor_id??''],'automation sponsor changed'));
+  if(await eligible(named?.sponsor_id))return named.sponsor_id;
+  const installQuery="SELECT installer_id FROM app_installations WHERE team_id=? AND principal_id=? AND state='active' ORDER BY created_at DESC,id DESC LIMIT 1";
+  const installed=await api.store.one(installQuery,[team,starter.id]);
+  if(guards)guards.push(guard(`SELECT 1 WHERE COALESCE((${installQuery}),'')=?`,[team,starter.id,installed?.installer_id??''],'installation sponsor changed'));
+  return await eligible(installed?.installer_id)?installed.installer_id:null;
+}
+export async function agentIdentity(api,team,row){
+  const sponsor=await agentSponsor(api,team,row),names=[row.name],seen=new Set([row.id]);let parent=row.parent_id;
+  while(parent){const next=await api.store.one('SELECT name,parent_id FROM agents WHERE team_id=? AND id=?',[team,parent]);if(!next||seen.has(parent))break;seen.add(parent);names.unshift(next.name);parent=next.parent_id;}
+  return {id:row.id,kind:'agent',org:team,name:row.name,path:names.join('/'),parent:row.parent_id,
+    lineage:parse(row.lineage_json),sponsor,explicit_sponsor:row.sponsor_id,profile:row.profile_ref,
+    state:row.state==='active'&&!sponsor?'suspended':row.state,
+    suspension_reason:row.state==='active'&&!sponsor?'no eligible person sponsor':null,
+    main_session:row.main_session_id,created_at:row.created_at,ended_at:row.ended_at,end_reason:row.end_reason,revision:row.revision};
+}
+export async function manageableAgent(api,auth,row){
+  if(isAdmin(auth)&&!auth.installation_id)return true;
+  if(auth.installation_id)return false;
+  return row.custodian_id===auth.principal_id||row.parent_id===auth.principal_id||await agentSponsor(api,auth.team_id,row)===auth.principal_id;
+}
+export async function managementGuards(api,auth,row){
+  const common=guard("SELECT 1 FROM agents WHERE team_id=? AND id=? AND revision=? AND state!='ended'",[auth.team_id,row.id,row.revision]);
+  if(isAdmin(auth)&&!auth.installation_id)return [common,guard("SELECT 1 FROM memberships WHERE team_id=? AND principal_id=? AND active=1 AND role IN ('owner','admin')",[auth.team_id,auth.principal_id])];
+  if(auth.installation_id)fail(403,'forbidden','an installation does not administer another agent');
+  if(row.custodian_id===auth.principal_id||row.parent_id===auth.principal_id)return [common];
+  const standing=[];
+  if(await agentSponsor(api,auth.team_id,row,new Set(),standing)!==auth.principal_id)fail(403,'forbidden','agent sponsorship changed');
+  return [common,...standing];
+}
+const nameGuard=(team,row)=>({sql:"SELECT 1 WHERE NOT EXISTS(SELECT 1 FROM agents WHERE team_id=? AND parent_id IS ? AND name=? AND id!=? AND state!='ended')",params:[team,row.parent_id,row.name,row.id],status:409,code:'conflict',message:'agent name is already declared under this parent'});
+export async function authorizeAgentReplay(api,auth,sub,body){
+  authority(auth);
+  if(sub==='/agents'){
+    if(body?.root&&(!isAdmin(auth)||auth.installation_id))fail(403,'forbidden','root declaration authority changed');
+    if(body?.parent&&(!(isAdmin(auth)&&!auth.installation_id))&&body.parent!==auth.principal_id)fail(403,'forbidden','parent declaration authority changed');
+    return;
+  }
+  const id=decodeURIComponent(sub.split('/')[2]);
+  const row=await api.store.one('SELECT * FROM agents WHERE team_id=? AND id=?',[auth.team_id,id]);
+  if(!row||!await manageableAgent(api,auth,row))fail(403,'forbidden','agent management authority changed');
+}
+export function publication(api,auth,kind,id,data,now){return stmt('INSERT INTO org_events(id,team_id,kind,resource_kind,resource_id,actor_json,data_json,created_at) VALUES (?,?,?,?,?,?,?,?)',api.ids.next('event'),auth.team_id,kind,'agent',id,JSON.stringify({principal:auth.principal_id,session:null,lineage:auth.act??[]}),JSON.stringify(data),now);}
+
+/** An automation's sponsor is a person an Org admin names; agents it starts inherit that sponsor. */
+export async function principalSponsorRoute({api,req,res,auth,sub,requestId,parseJson,send,result,guardedMutation}){
+  const match=/^\/principals\/([^/]+)\/sponsor$/.exec(sub);
+  if(!match)return false;
+  const id=decodeURIComponent(match[1]),now=api.clock.nowMs();
+  const automation=await api.store.one("SELECT p.id FROM principals p JOIN memberships m ON m.team_id=? AND m.principal_id=p.id AND m.active=1 WHERE p.id=? AND p.kind='service'",[auth.team_id,id]);
+  if(req.method==='GET'){
+    if(!automation)fail(404,'not_found','automation not found in this Org');
+    const row=await api.store.one('SELECT sponsor_id,set_by,created_at FROM principal_sponsors WHERE team_id=? AND principal_id=?',[auth.team_id,id]);
+    send(res,200,result(api,auth,{principal:id,sponsor:row?.sponsor_id??null,set_by:row?.set_by??null,at:row?.created_at??null}),requestId);return true;
+  }
+  if(!isAdmin(auth)||auth.installation_id)fail(403,'forbidden','only an Org admin names an automation\'s sponsor');
+  if(!automation)fail(404,'not_found','automation not found in this Org');
+  const guards=[...liveGuards(auth,now),guard("SELECT 1 FROM memberships WHERE team_id=? AND principal_id=? AND active=1 AND role IN ('owner','admin')",[auth.team_id,auth.principal_id]),
+    guard("SELECT 1 FROM principals p JOIN memberships m ON m.team_id=? AND m.principal_id=p.id AND m.active=1 WHERE p.id=? AND p.kind='service'",[auth.team_id,id],'automation standing changed')];
+  const event=data=>stmt('INSERT INTO org_events(id,team_id,kind,resource_kind,resource_id,actor_json,data_json,created_at) VALUES (?,?,?,?,?,?,?,?)',api.ids.next('event'),auth.team_id,'principal.changed','principal',id,JSON.stringify({principal:auth.principal_id,session:null,lineage:auth.act??[]}),JSON.stringify(data),now);
+  if(req.method==='DELETE'){
+    const response=result(api,auth,{principal:id,sponsor:null});
+    await guardedMutation(api,res,auth,guards,[stmt('DELETE FROM principal_sponsors WHERE team_id=? AND principal_id=?',auth.team_id,id),event({id,kind:'automation',sponsor:null})],{status:200,body:response,targetId:id});
+    send(res,200,response,requestId);return true;
+  }
+  if(req.method!=='PUT')fail(404,'not_found','sponsor operation not found');
+  const body=await parseJson(req);exact(body,['sponsor']);const sponsor=text(body.sponsor,'sponsor',128);
+  // Never an agent or an automation: the sponsor is a person in this Org.
+  if(!await person(api,auth.team_id,sponsor))fail(400,'invalid_request','a sponsor must be a person in this Org');
+  const response=result(api,auth,{principal:id,sponsor});
+  await guardedMutation(api,res,auth,[...guards,personGuard(auth.team_id,sponsor)],[
+    stmt('INSERT INTO principal_sponsors(team_id,principal_id,sponsor_id,set_by,created_at) VALUES (?,?,?,?,?) ON CONFLICT(team_id,principal_id) DO UPDATE SET sponsor_id=excluded.sponsor_id,set_by=excluded.set_by,created_at=excluded.created_at',auth.team_id,id,sponsor,auth.principal_id,now),
+    event({id,kind:'automation',sponsor})],{status:200,body:response,targetId:id});
+  send(res,200,response,requestId);return true;
+}
+
+export async function agentRoute(ctx){
+  const {api,req,res,auth,sub,url,requestId,parseJson,send,result,guardedMutation,requireRevision}=ctx;
+  if(!/^\/agents(?:\/|$)/.test(sub))return false;
+  authority(auth);const now=api.clock.nowMs();
+  const match=/^\/agents\/([^/]+)(?:\/(end|sessions|credentials|closures|management))?$/.exec(sub),id=match?decodeURIComponent(match[1]):null,op=match?.[2];
+  if(req.method==='GET'&&sub==='/agents'){
+    const limit=Number(url.searchParams.get('limit')??100),after=url.searchParams.get('after')??'';
+    if(!Number.isSafeInteger(limit)||limit<1||limit>200)fail(400,'invalid_request','limit must be 1..200');
+    const rows=await api.store.query('SELECT * FROM agents WHERE team_id=? AND id>? ORDER BY id LIMIT ?',[auth.team_id,after,limit+1]);
+    send(res,200,{version:1,items:await Promise.all(rows.slice(0,limit).map(row=>agentIdentity(api,auth.team_id,row))),next_after:rows.length>limit?rows[limit-1].id:null},requestId);return true;
+  }
+  if(req.method==='GET'&&sub==='/agents/root'){
+    const org=await api.store.one('SELECT root_agent_id FROM teams WHERE id=?',[auth.team_id]);
+    const root=org?.root_agent_id?await api.store.one('SELECT * FROM agents WHERE team_id=? AND id=?',[auth.team_id,org.root_agent_id]):null;
+    if(!root)fail(404,'not_found','Org root agent has not been declared');
+    send(res,200,result(api,auth,await agentIdentity(api,auth.team_id,root)),requestId);return true;
+  }
+  if(req.method==='POST'&&sub==='/agents'){
+    const body=await parseJson(req);exact(body,['id','name','parent','sponsor','profile','root','starter_session']);
+    const aid=body.id??api.ids.next('agent');if(!/^agent_[0-9a-f]{32}$/.test(aid))fail(400,'invalid_request','id must be a locally minted agent id');
+    const name=text(body.name,'name');if(name.includes('/'))fail(400,'invalid_request','an agent name is one path component');
+    const parentId=body.parent??null,parent=parentId?await api.store.one("SELECT * FROM agents WHERE team_id=? AND id=? AND state!='ended'",[auth.team_id,parentId]):null;
+    if(parentId&&!parent)fail(404,'not_found','parent agent not found');
+    if(parentId&&!(isAdmin(auth)&&!auth.installation_id)&&parentId!==auth.principal_id)fail(403,'forbidden','declare under your own agent or through an Org admin');
+    if(body.root&&(!(isAdmin(auth)&&!auth.installation_id)||parentId))fail(403,'forbidden','only an Org admin declares its parentless root');
+    const principal=await api.store.one('SELECT kind FROM principals WHERE id=?',[auth.principal_id]);
+    let starter={kind:kind(principal.kind),id:auth.principal_id};
+    if(body.starter_session){
+      const session=await api.store.authorizedSession({teamId:auth.team_id,principalId:auth.principal_id,credentialId:auth.credential_id,ref:body.starter_session,now});
+      if(session.custodian_id!==auth.principal_id)fail(403,'forbidden','a starter session must be your own');
+      const owner=await api.store.one('SELECT agent_id FROM agent_sessions WHERE team_id=? AND session_id=?',[auth.team_id,session.id]);
+      starter=owner?.agent_id?{kind:'agent',id:owner.agent_id,session:session.id}:{kind:'session',id:session.id,delegator:{kind:starter.kind,id:starter.id}};
+    }
+    const sponsorGuards=[];
+    const sponsor=await selectedSponsor(api,auth.team_id,body.sponsor,sponsorGuards);
+    if(sponsor&&(!await person(api,auth.team_id,sponsor)||(!(isAdmin(auth)&&!auth.installation_id)&&sponsor!==auth.principal_id)))fail(403,'forbidden','an explicit sponsor must be you or a person you administer');
+    const row={id:aid,name,parent_id:parentId,custodian_id:auth.principal_id,lineage_json:JSON.stringify({starter,declared_by:auth.principal_id,at:now}),sponsor_id:sponsor,
+      profile_ref:text(body.profile,'profile',1024),state:'active',main_session_id:null,created_at:now,ended_at:null,end_reason:null,revision:1};
+    const data=await agentIdentity(api,auth.team_id,row),response=result(api,auth,data),guards=[...liveGuards(auth,now),...sponsorGuards];
+    guards.push(nameGuard(auth.team_id,row));
+    if(parent)guards.push(guard("SELECT 1 FROM agents WHERE team_id=? AND id=? AND revision=? AND state='active'",[auth.team_id,parentId,parent.revision],'parent agent changed'));
+    if(sponsor)guards.push(personGuard(auth.team_id,sponsor));
+    if(body.root)guards.push(guard("SELECT 1 FROM teams t WHERE t.id=? AND (t.root_agent_id IS NULL OR EXISTS(SELECT 1 FROM agents a WHERE a.team_id=t.id AND a.id=t.root_agent_id AND a.state='ended'))",[auth.team_id],'Org root is already declared'));
+    const statements=[stmt("INSERT INTO principals(id,kind,display_name) VALUES (?,'agent',?)",aid,name),
+      stmt('INSERT INTO agents(team_id,id,name,parent_id,custodian_id,lineage_json,sponsor_id,profile_ref,state,created_at) VALUES (?,?,?,?,?,?,?,?,?,?)',auth.team_id,aid,name,parentId,row.custodian_id,row.lineage_json,sponsor,row.profile_ref,'active',now),
+      publication(api,auth,'agent.declared',aid,data,now)];
+    if(body.root)statements.push(stmt('UPDATE teams SET root_agent_id=?,revision=revision+1 WHERE id=?',aid,auth.team_id));
+    await guardedMutation(api,res,auth,guards,statements,{status:201,body:response,targetId:aid});send(res,201,response,requestId);return true;
+  }
+  if(!match)fail(404,'not_found','agent operation not found');
+  const row=await api.store.one('SELECT * FROM agents WHERE team_id=? AND id=?',[auth.team_id,id]);if(!row)fail(404,'not_found','agent not found');
+  if(req.method==='GET'&&!op){send(res,200,result(api,auth,await agentIdentity(api,auth.team_id,row)),requestId,{ETag:`"${row.revision}"`});return true;}
+  if(!await manageableAgent(api,auth,row))fail(403,'forbidden','only the sponsor, parent, declarer or manager changes this agent');
+  if(req.method==='GET'&&op==='management') {
+    if(row.state!=='active'||!await api.store.one(AGENT_ACTIVE,[auth.team_id,id]))fail(409,'conflict','the agent is not active with live sponsorship');
+    send(res,200,result(api,auth,{id,revision:row.revision,profile:row.profile_ref,manageable:true}),requestId);return true;
+  }
+  if(req.method==='GET'&&op==='closures'){
+    const rows=await api.store.query('SELECT id,session_id,machine_id,harness,native_id,state,reason,created_at,claimed_at,finished_at,result_json FROM agent_session_closures WHERE team_id=? AND agent_id=? ORDER BY created_at,id LIMIT 200',[auth.team_id,id]);
+    send(res,200,result(api,auth,{items:rows.map(({result_json,...item})=>({...item,result:result_json?parse(result_json):null}))}),requestId);return true;
+  }
+  if(row.state==='ended')fail(409,'conflict','an ended agent cannot be changed');
+  requireRevision(req,row.revision,'agent');
+  if(req.method==='POST'&&op==='credentials'){
+    const body=await parseJson(req);exact(body,['expires_in_ms']);
+    const lifetime=body.expires_in_ms??3600000;
+    if(!Number.isSafeInteger(lifetime)||lifetime<1||lifetime>86400000)fail(400,'invalid_request','credential lifetime must be 1ms..24h');
+    if(!await api.store.one(AGENT_ACTIVE,[auth.team_id,id]))fail(409,'conflict','suspended agents cannot receive delegation');
+    const cid=api.ids.next('credential'),token=makeToken(cid),expiry=Math.min(now+lifetime,auth.expires_at??Infinity);
+    const response=result(api,auth,{id:cid,token,principal_id:id,kind:'service',expires_at:expiry,actions:['agents.read','sessions.read','sessions.mail.own']});
+    await guardedMutation(api,res,auth,[...liveGuards(auth,now),...await managementGuards(api,auth,row),
+      guard(AGENT_ACTIVE,[auth.team_id,id],'agent standing changed'),guard(`SELECT 1 WHERE NOT EXISTS(${APP_LINEAGE_REVOKED})`,[auth.credential_id,now],'delegator standing changed')],
+      [stmt("INSERT INTO memberships(team_id,principal_id,role,active) VALUES (?,?,'viewer',1) ON CONFLICT(team_id,principal_id) DO NOTHING",auth.team_id,id),
+       stmt('INSERT INTO credentials(id,token_hash,principal_id,kind,team_id,expires_at,created_at) VALUES (?,?,?,?,?,?,?)',cid,hashToken(token),id,'service',auth.team_id,expiry,now),
+       stmt('INSERT INTO agent_credentials(credential_id,parent_credential_id,agent_id,team_id,created_at) VALUES (?,?,?,?,?)',cid,auth.credential_id,id,auth.team_id,now)],{status:201,body:response,targetId:cid});
+    send(res,201,response,requestId);return true;
+  }
+  if(req.method==='PATCH'&&!op){
+    const body=await parseJson(req);exact(body,['name','parent','sponsor','profile','state']);
+    if(!Object.keys(body).length)fail(400,'invalid_request','an agent change is required');
+    const updated={...row,revision:row.revision+1};const guards=[...liveGuards(auth,now),...await managementGuards(api,auth,row)];
+    if(body.name!==undefined){updated.name=text(body.name,'name');if(updated.name.includes('/'))fail(400,'invalid_request','name is one path component');}
+    if(body.profile!==undefined)updated.profile_ref=text(body.profile,'profile',1024);
+    if(body.sponsor!==undefined){updated.sponsor_id=await selectedSponsor(api,auth.team_id,body.sponsor,guards);if(updated.sponsor_id){if(!(isAdmin(auth)&&!auth.installation_id)&&updated.sponsor_id!==auth.principal_id)fail(403,'forbidden','sponsor must be you or a person you administer');guards.push(personGuard(auth.team_id,updated.sponsor_id));}}
+    if(body.state!==undefined){if(!['active','suspended'].includes(body.state))fail(400,'invalid_request','state must be active or suspended; use end to end an agent');updated.state=body.state;}
+    if(body.parent!==undefined){
+      const org=await api.store.one('SELECT root_agent_id FROM teams WHERE id=?',[auth.team_id]);
+      if(org.root_agent_id===id&&body.parent!=null)fail(409,'conflict','the Org root cannot have a parent');
+      guards.push(guard('SELECT 1 FROM teams WHERE id=? AND root_agent_id IS ?',[auth.team_id,org.root_agent_id],'Org root changed'));
+      updated.parent_id=body.parent;
+      if(updated.parent_id){
+        const target=await api.store.one("SELECT * FROM agents WHERE team_id=? AND id=? AND state!='ended'",[auth.team_id,updated.parent_id]);if(!target||!await manageableAgent(api,auth,target))fail(403,'forbidden','new parent must be one you administer');
+        guards.push(...await managementGuards(api,auth,target));
+        const descendants=await api.store.query('WITH RECURSIVE tree(id) AS (SELECT ? UNION SELECT a.id FROM agents a JOIN tree t ON a.parent_id=t.id WHERE a.team_id=?) SELECT id FROM tree',[id,auth.team_id]);
+        if(descendants.some(a=>a.id===updated.parent_id))fail(409,'conflict','reparenting would create a cycle');
+        guards.push(guard("SELECT 1 FROM agents WHERE team_id=? AND id=? AND revision=? AND state!='ended'",[auth.team_id,target.id,target.revision],'new parent changed'));
+        guards.push(guard('WITH RECURSIVE tree(id) AS (SELECT ? UNION SELECT a.id FROM agents a JOIN tree t ON a.parent_id=t.id WHERE a.team_id=?) SELECT 1 WHERE NOT EXISTS(SELECT 1 FROM tree WHERE id=?)',[id,auth.team_id,target.id],'reparenting would create a cycle'));
+      }
+    }
+    guards.push(nameGuard(auth.team_id,updated));
+    const data=await agentIdentity(api,auth.team_id,updated),response=result(api,auth,data);
+    await guardedMutation(api,res,auth,guards,[stmt('UPDATE agents SET name=?,parent_id=?,sponsor_id=?,profile_ref=?,state=?,revision=revision+1 WHERE team_id=? AND id=?',updated.name,updated.parent_id,updated.sponsor_id,updated.profile_ref,updated.state,auth.team_id,id),stmt('UPDATE principals SET display_name=? WHERE id=?',updated.name,id),publication(api,auth,body.parent!==undefined?'agent.reparented':'agent.changed',id,data,now)],{status:200,body:response,targetId:id});send(res,200,response,requestId);return true;
+  }
+  if(req.method==='POST'&&op==='end'){
+    const body=await parseJson(req);exact(body,['reason']);const reason=text(body.reason,'reason',1024);
+    const children=await api.store.query('WITH RECURSIVE tree(id) AS (SELECT ? UNION SELECT a.id FROM agents a JOIN tree t ON a.parent_id=t.id WHERE a.team_id=?) SELECT a.* FROM agents a JOIN tree t ON a.id=t.id WHERE a.team_id=? AND a.state!=\'ended\'',[id,auth.team_id,auth.team_id]);
+    const statements=[];
+    for(const child of children){
+      statements.push(stmt(`WITH RECURSIVE family(id,root) AS (
+        SELECT session_id,session_id FROM agent_sessions WHERE team_id=? AND agent_id=? AND ended_at IS NULL
+        UNION SELECT s.id,f.root FROM sessions s JOIN family f ON s.canonical_id=f.id WHERE s.team_id=? AND s.deleted_at IS NULL)
+        INSERT OR IGNORE INTO agent_session_closures(team_id,id,agent_id,session_id,machine_id,source_id,harness,native_id,reason,created_at)
+        SELECT o.team_id,'close_'||lower(hex(randomblob(16))),?,f.root,src.machine_id,o.source_id,o.harness,o.native_id,?,?
+        FROM origins o JOIN family f ON f.id=o.session_id JOIN sources src ON src.team_id=o.team_id AND src.id=o.source_id
+        WHERE o.team_id=? AND o.deleted_at IS NULL AND src.machine_id IS NOT NULL`,auth.team_id,child.id,auth.team_id,child.id,reason,now,auth.team_id));
+      statements.push(stmt("UPDATE agents SET state='ended',ended_at=?,end_reason=?,revision=revision+1,main_session_id=NULL WHERE team_id=? AND id=?",now,reason,auth.team_id,child.id),
+        stmt('UPDATE credentials SET revoked_at=? WHERE team_id=? AND principal_id=? AND revoked_at IS NULL',now,auth.team_id,child.id),
+        stmt(`WITH RECURSIVE delegated(id) AS (
+          SELECT ac.credential_id FROM app_credentials ac JOIN credentials c ON c.id=ac.credential_id,json_each(ac.actor_json) actor
+          WHERE c.team_id=? AND actor.type='text' AND actor.value=?
+          UNION SELECT ac.credential_id FROM app_credentials ac JOIN delegated d ON ac.parent_id=d.id
+          UNION SELECT ac.credential_id FROM app_credentials ac JOIN delegated d ON ac.subject_credential_id=d.id
+          UNION SELECT ac.credential_id FROM agent_credentials ac JOIN delegated d ON ac.parent_credential_id=d.id)
+          UPDATE credentials SET revoked_at=? WHERE team_id=? AND id IN(SELECT id FROM delegated) AND revoked_at IS NULL`,auth.team_id,child.id,now,auth.team_id),
+        stmt('UPDATE memberships SET active=0,revision=revision+1 WHERE team_id=? AND principal_id=?',auth.team_id,child.id),
+        stmt('UPDATE agent_sessions SET ended_at=COALESCE(ended_at,?),end_reason=COALESCE(end_reason,?),main=0,revision=revision+1 WHERE team_id=? AND agent_id=?',now,reason,auth.team_id,child.id),
+        publication(api,auth,'agent.ended',child.id,{...await agentIdentity(api,auth.team_id,child),state:'ended',main_session:null,ended_at:now,end_reason:reason,revision:child.revision+1},now));
+      statements.push(stmt(`INSERT INTO org_events(id,team_id,kind,resource_kind,resource_id,actor_json,data_json,created_at)
+        SELECT 'evt_'||lower(hex(randomblob(16))),s.team_id,'session.changed','session',s.id,?,${nativeSessionSnapshot('s.team_id','s.id')},?
+        FROM sessions s JOIN agent_sessions own ON own.team_id=s.team_id AND own.session_id=s.id WHERE own.team_id=? AND own.agent_id=?`,
+        JSON.stringify({principal:auth.principal_id,session:null,lineage:auth.act??[]}),now,auth.team_id,child.id));
+    }
+    const response=result(api,auth,{id,state:'ended',ended:children.map(a=>a.id)});
+    statements.push(stmt('UPDATE teams SET auth_epoch=auth_epoch+1 WHERE id=?',auth.team_id));
+    await guardedMutation(api,res,auth,[...liveGuards(auth,now),...await managementGuards(api,auth,row),guard("WITH RECURSIVE tree(id) AS (SELECT ? UNION SELECT a.id FROM agents a JOIN tree t ON a.parent_id=t.id WHERE a.team_id=?) SELECT 1 WHERE (SELECT count(*) FROM agents a JOIN tree t ON a.id=t.id WHERE a.team_id=? AND a.state!='ended')=?",[id,auth.team_id,auth.team_id,children.length],'agent descendants changed'),...children.map(c=>guard('SELECT 1 FROM agents WHERE team_id=? AND id=? AND revision=?',[auth.team_id,c.id,c.revision],'descendant changed'))],statements,{status:200,body:response,targetId:id});
+    for(const child of children){closeChannelsFor(api,auth.team_id,{principalId:child.id,reason:'agent_ended'});closeActorChannels(api,auth.team_id,child.id);}
+    send(res,200,response,requestId);return true;
+  }
+  fail(404,'not_found','agent operation not found');
+}

package/server/apps.mjs

@@ -4,14 +4,20 @@ import { randomBytes, createHash, createCipheriv, createDecipheriv, createHmac }
 import { hashToken, makeToken, isAdmin, canRead, canManage, appGrantAllows, APP_LINEAGE_REVOKED } from './auth.mjs';
 import { exact } from './request-json.mjs';
 import { closeAppChannels, closeMachineChannels } from './machine-link.mjs';
+import { APP_EVENTS } from './event-catalogue.mjs';
+import { AGENT_ACTIVE } from './agent-authority.mjs';
+import { mayReadEvent } from './published-events.mjs';
+export { APP_EVENTS } from './event-catalogue.mjs';
 
 export const APP_ACTIONS = Object.freeze([
+  'agents.read', 'agents.write',
+  'identity.read', 'identity.observe', 'identity.link', 'identity.infer',
   'teams.read', 'members.read', 'members.write', 'groups.read', 'groups.write',
   'sessions.read', 'sessions.write', 'sessions.control', 'sessions.access',
   'machines.read', 'machines.control', 'machines.write', 'machines.access', 'sources.read', 'sources.write',
   'identity.login', 'delegation.surfaces', 'delegation.sessions', 'delegation.notices',
+  'events.read', 'events.publish',
 ]);
-export const APP_EVENTS = Object.freeze(['app.registered', 'app.installed', 'app.uninstalled']);
 const TOKEN_MS = 90 * 86400000, CODE_MS = 10 * 60000, DELEGATION_MS = 15 * 60000;
 const error = (status, code, message) => { throw Object.assign(new Error(message), { status, code }); };
 const statement = (sql, ...params) => ({ sql, params });
@@ -68,6 +74,16 @@ function sessionAuthorityGuard(source,teamId,id,manage,now){
 
 /** Restrict every ordinary door, including replay, before the existing resource evaluator. Unknown doors fail closed. */
 export function appRouteAction(method, sub) {
+  if(/^\/agents(?:\/|$)/.test(sub))return method==='GET'?'agents.read':'agents.write';
+  if(sub.startsWith('/identity/')) {
+    if(method==='GET')return 'identity.read';
+    if(method==='POST'&&sub==='/identity/observations')return 'identity.observe';
+    if(sub.startsWith('/identity/inferences'))return 'identity.infer';
+    if(sub.startsWith('/identity/links'))return 'identity.link';
+    return null;
+  }
+  if(method==='GET'&&/^\/events(?:\/catalogue)?$/.test(sub))return 'events.read';
+  if(method==='POST'&&/^\/event-sources(?:\/[^/]+\/events)?$/.test(sub))return 'events.publish';
   if (method === 'GET' && (sub === '' || sub === '/me' || sub === '/capabilities' || sub === '/teams')) return 'teams.read';
   if (/^\/members(?:\/[^/]+)?$/.test(sub)) return method === 'GET' ? 'members.read' : 'members.write';
   if (/^\/groups(?:\/[^/]+(?:\/members\/[^/]+)?)?$/.test(sub)) return method === 'GET' ? 'groups.read' : 'groups.write';
@@ -199,6 +215,10 @@ export async function appRoute(ctx) {
     const body = await parseJson(req); exact(body, ['actions','actor','expires_in_ms','principal_id','grants','subject_token']);
     const actions = list(body.actions, 'actions', auth.app_actions);
     const actor = text(body.actor, 'actor');
+    const actorStanding=guard(`SELECT 1 WHERE NOT EXISTS(SELECT 1 FROM agents named WHERE named.team_id=? AND named.id=?
+      AND NOT EXISTS(${AGENT_ACTIVE.replace('VALUES(?,?)','SELECT named.team_id,named.id')}))`,[auth.team_id,actor],'a declared agent actor must remain active');
+    // An opaque audit actor supplies no authority. A known agent also carries its current lifetime fence.
+    if(!await api.store.one(actorStanding.sql,actorStanding.params))error(403,'forbidden',actorStanding.message);
     const duration = body.expires_in_ms ?? DELEGATION_MS;
     if (!Number.isSafeInteger(duration) || duration < 1000 || duration > DELEGATION_MS || auth.act.length >= 16) error(400, 'invalid_request', 'delegation is limited to fifteen minutes and sixteen actors');
     const parent = await api.store.one('SELECT expires_at FROM credentials WHERE id=?', [auth.credential_id]);
@@ -236,7 +256,7 @@ export async function appRoute(ctx) {
     }
     const expiresAt=Math.min(now+duration,parent.expires_at??Infinity,source.expires_at??Infinity),cid=api.ids.next('credential'),token=makeToken(cid),act=[...auth.act,actor];
     const response=result(api,auth,{token,kind:'service',expires_at:expiresAt,actions,subject,act,grants});
-    const boundaryNow=api.clock.nowMs(),checks=[...appAuthGuards(auth,boundaryNow),...appAuthGuards(source,boundaryNow),guard('SELECT 1 FROM teams WHERE id=? AND auth_epoch=?',[auth.team_id,epoch.auth_epoch]),guard('SELECT 1 FROM memberships WHERE team_id=? AND principal_id=? AND active=1 AND role=?',[auth.team_id,subject,targetMembership.role]),guard('SELECT 1 FROM credentials WHERE id=? AND revoked_at IS NULL AND (expires_at IS NULL OR expires_at>?)',[source.credential_id,boundaryNow])];
+    const boundaryNow=api.clock.nowMs(),checks=[actorStanding,...appAuthGuards(auth,boundaryNow),...appAuthGuards(source,boundaryNow),guard('SELECT 1 FROM teams WHERE id=? AND auth_epoch=?',[auth.team_id,epoch.auth_epoch]),guard('SELECT 1 FROM memberships WHERE team_id=? AND principal_id=? AND active=1 AND role=?',[auth.team_id,subject,targetMembership.role]),guard('SELECT 1 FROM credentials WHERE id=? AND revoked_at IS NULL AND (expires_at IS NULL OR expires_at>?)',[source.credential_id,boundaryNow])];
     for(const grant of grants??[]){const manage=grant.actions.some(a=>a!=='sessions.read');checks.push(sessionAuthorityGuard(source,auth.team_id,grant.id,manage,boundaryNow),sessionAuthorityGuard(target,auth.team_id,grant.id,manage,boundaryNow));}
     await guardedMutation(api,res,auth,checks,[statement('INSERT INTO credentials(id,token_hash,principal_id,kind,team_id,expires_at,created_at) VALUES (?,?,?,\'service\',?,?,?)',cid,hashToken(token),subject,auth.team_id,expiresAt,now),statement('INSERT INTO app_credentials(credential_id,installation_id,parent_id,actions_json,actor_json,subject_principal_id,subject_credential_id,grants_json) VALUES (?,?,?,?,?,?,?,?)',cid,auth.installation_id,auth.credential_id,JSON.stringify(actions),JSON.stringify(act),subject,sourceId,JSON.stringify(grants))],{status:201,body:response,targetId:cid});
     send(res, 201, response, requestId); return true;
@@ -349,12 +369,24 @@ export async function deliverAppWebhooks(api) {
     try {
       await api.store.guardedTransaction([guard("SELECT 1 FROM app_webhook_deliveries WHERE id=? AND state='pending' AND (lease_until IS NULL OR lease_until<=?)", [id, now])], [statement('UPDATE app_webhook_deliveries SET lease_until=?,attempts=attempts+1 WHERE id=?', lease, id)]);
     } catch (e) { if (e.code === 'forbidden') continue; throw e; }
-    const row = await api.store.one(`SELECT d.*,i.signing_secret,i.state installation_state,a.webhook_url,a.state app_state,m.active,installer.active installer_active,installer.role installer_role
+    const row = await api.store.one(`SELECT d.*,i.signing_secret,i.team_id,i.principal_id,i.actions_json,i.state installation_state,a.webhook_url,a.state app_state,m.active,installer.active installer_active,installer.role installer_role
       FROM app_webhook_deliveries d JOIN app_installations i ON i.id=d.installation_id JOIN apps a ON a.id=i.app_id JOIN memberships m ON m.team_id=i.team_id AND m.principal_id=i.principal_id JOIN memberships installer ON installer.team_id=i.team_id AND installer.principal_id=i.installer_id WHERE d.id=?`, [id]);
     let status = null, delivered = false;
     if (row.state !== 'pending' || row.installation_state !== 'active' || row.app_state !== 'active' || !row.active || !row.installer_active || !['owner','admin'].includes(row.installer_role)) {
       await api.store.transaction([statement("UPDATE app_webhook_deliveries SET state='cancelled',lease_until=NULL WHERE id=?", id)]); continue;
     }
+    const event=JSON.parse(row.body);
+    if(event.resource){
+      const credential=await api.store.one(`SELECT c.id,c.kind,c.principal_id,c.expires_at,m.role,m.active FROM app_credentials ac JOIN credentials c ON c.id=ac.credential_id JOIN memberships m ON m.team_id=? AND m.principal_id=c.principal_id WHERE ac.installation_id=? AND ac.parent_id IS NULL AND c.revoked_at IS NULL AND (c.expires_at IS NULL OR c.expires_at>?) ORDER BY c.created_at DESC LIMIT 1`,[row.team_id,row.installation_id,now]);
+      if(!credential){
+        await api.store.transaction([statement('UPDATE app_webhook_deliveries SET lease_until=NULL,next_at=?,attempts=attempts-1 WHERE id=?',now+30000,id)]);continue;
+      }
+      // Code redemption supplies the installation's reader credential; attenuation never widens the webhook.
+      const reader=credential&&await appAuthentication(api,{...credential,credential_id:credential.id,team_id:row.team_id});
+      if(!reader||!await mayReadEvent(api,reader,event)){
+        await api.store.transaction([statement("UPDATE app_webhook_deliveries SET state='cancelled',lease_until=NULL WHERE id=?",id)]);continue;
+      }
+    }
     try {
       const secret = unseal(api, row.signing_secret, row.installation_id), timestamp = String(Math.floor(api.clock.nowMs() / 1000));
       const signature = createHmac('sha256', Buffer.from(secret.slice(6), 'base64')).update(`${id}.${timestamp}.${row.body}`).digest('base64');

package/server/auth.mjs

@@ -1,3 +1,4 @@
+import { AGENT_ACTIVE } from './agent-authority.mjs';
 import { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
 export const hashToken = token => createHash('sha256').update(token).digest('hex');
 export function makeToken(credentialId, bytes = randomBytes(32)) { return `sct_${credentialId}.${Buffer.from(bytes).toString('base64url')}`; }
@@ -10,10 +11,12 @@ export function appGrantAllows(auth, kind, id, action) {
 /** Both app parent and the credential that passed a represented principal's grants stay live. */
 export const APP_LINEAGE = `WITH RECURSIVE lineage(id) AS (
   SELECT ? UNION SELECT ac.parent_id FROM app_credentials ac JOIN lineage l ON ac.credential_id=l.id WHERE ac.parent_id IS NOT NULL
+  UNION SELECT d.parent_credential_id FROM agent_credentials d JOIN lineage l ON d.credential_id=l.id
   UNION SELECT ac.subject_credential_id FROM app_credentials ac JOIN lineage l ON ac.credential_id=l.id WHERE ac.subject_credential_id IS NOT NULL
 )`;
 export const APP_LINEAGE_REVOKED = `${APP_LINEAGE}
   SELECT 1 FROM lineage l JOIN credentials c ON c.id=l.id
+  JOIN principals p ON p.id=c.principal_id
   LEFT JOIN memberships m ON m.team_id=c.team_id AND m.principal_id=c.principal_id
   LEFT JOIN app_credentials ac ON ac.credential_id=c.id
   LEFT JOIN identity_app_credentials ic ON ic.credential_id=c.id
@@ -21,7 +24,12 @@ export const APP_LINEAGE_REVOKED = `${APP_LINEAGE}
   LEFT JOIN apps a ON a.id=i.app_id
   LEFT JOIN memberships installer ON installer.team_id=i.team_id AND installer.principal_id=i.installer_id
   LEFT JOIN memberships service ON service.team_id=i.team_id AND service.principal_id=i.principal_id
-  WHERE c.revoked_at IS NOT NULL OR (c.expires_at IS NOT NULL AND c.expires_at<=?)
+  WHERE (p.kind='agent' AND NOT EXISTS (${AGENT_ACTIVE.replace('VALUES(?,?)','SELECT c.team_id,c.principal_id')}))
+    OR EXISTS(SELECT 1 FROM json_each(COALESCE(ac.actor_json,'[]')) actor
+      JOIN agents named ON named.team_id=c.team_id AND named.id=actor.value
+      WHERE actor.type='text' AND NOT EXISTS (${AGENT_ACTIVE.replace('VALUES(?,?)','SELECT named.team_id,named.id')}))
+    OR EXISTS(SELECT 1 FROM agent_credentials d LEFT JOIN memberships dm ON dm.team_id=d.team_id AND dm.principal_id=c.principal_id WHERE d.parent_credential_id=c.id AND d.credential_id IN(SELECT id FROM lineage) AND COALESCE(dm.active,0)!=1)
+    OR c.revoked_at IS NOT NULL OR (c.expires_at IS NOT NULL AND c.expires_at<=?)
     OR (c.team_id IS NOT NULL AND COALESCE(m.active,0)!=1)
     OR (i.id IS NOT NULL AND (i.state!='active' OR a.state!='active' OR COALESCE(installer.active,0)!=1
       OR installer.role NOT IN ('owner','admin') OR COALESCE(service.active,0)!=1)) LIMIT 1`;

package/server/core.mjs

@@ -15,13 +15,12 @@ const productionIds={next(kind){return `${prefix[kind]??kind}_${randomBytes(16).
 const productionClock={nowMs:()=>Date.now()};
 export { productionIds, productionClock };
 
-export function createTeamsApi({clock=productionClock,ids=productionIds,publicOrigin=null,appRootSecret=null,identityOrganizations=null,uploadLimitBytes=256*1024*1024}={}) {
+export function createTeamsApi({clock=productionClock,ids=productionIds,publicOrigin=null,appRootSecret=null,uploadLimitBytes=256*1024*1024}={}) {
   if(typeof clock?.nowMs!=='function'||typeof ids?.next!=='function')throw new TypeError('clock.nowMs and ids.next are required');
   if(!Number.isSafeInteger(uploadLimitBytes)||uploadLimitBytes<1||uploadLimitBytes>256*1024*1024)throw new TypeError('uploadLimitBytes must be between 1 and 268435456');
   let store=null,serverId=null,localOrigin=null,harnessRoutes=null;
   const events=new TeamEvents();
-  // Teams linked to organizations the identity service keeps for this server (identity-orgs.mjs).
-  return {clock,ids,events,publicOrigin,appRootSecret,identityOrganizations,uploadLimitBytes,rateState:new Map(),openStreams:new Map(),securityEvents:[],
+  return {clock,ids,events,publicOrigin,appRootSecret,uploadLimitBytes,rateState:new Map(),openStreams:new Map(),securityEvents:[],
     get store(){return store;},get serverId(){return serverId;},get localOrigin(){return localOrigin;},get harnessRoutes(){return harnessRoutes;},
     attach(next){store=next.store??store;if(next.serverId!==undefined)serverId=next.serverId;if(next.localOrigin!==undefined)localOrigin=next.localOrigin;if(next.harnessRoutes!==undefined)harnessRoutes=next.harnessRoutes;},
   };
@@ -99,6 +98,8 @@ export async function maintain(api){const now=api.clock.nowMs();
     ...['messages','session_artifacts','session_versions'].map(table=>({sql:`DELETE FROM ${table} WHERE team_id=? AND session_id=? AND revision=?`,params:[team_id,session_id,revision]})),
   ]);
   await api.store.transaction([
+        {sql:'INSERT INTO event_retention SELECT e.team_id,MAX(e.sequence) FROM org_events e LEFT JOIN (SELECT team_id,MIN(sequence) AS first FROM org_events WHERE created_at>=? GROUP BY team_id) n ON n.team_id=e.team_id WHERE e.created_at<? AND (n.first IS NULL OR e.sequence<n.first) GROUP BY e.team_id ON CONFLICT(team_id) DO UPDATE SET pruned_through=MAX(pruned_through,excluded.pruned_through)',params:[now-7*86400000,now-7*86400000]},
+        {sql:'DELETE FROM org_events WHERE sequence<=(SELECT pruned_through FROM event_retention WHERE team_id=org_events.team_id) AND sequence NOT IN (SELECT sequence FROM event_resources)',params:[]},
         {sql:'DELETE FROM cursors WHERE expires_at<=?',params:[now]},
         {sql:'DELETE FROM global_cursors WHERE expires_at<=?',params:[now]},
         {sql:'DELETE FROM global_idempotency WHERE expires_at<=?',params:[now]},

package/server/event-catalogue.mjs

@@ -0,0 +1,13 @@
+// Product-neutral ontology names; source-owned records are published through the same door.
+export const APP_EVENTS = Object.freeze([
+  'app.registered', 'app.installed', 'app.uninstalled',
+  'membership.added', 'membership.changed', 'membership.removed',
+  'principal.created', 'principal.changed', 'principal.ended',
+  'agent.declared', 'agent.changed', 'agent.reassigned', 'agent.reparented', 'agent.ended',
+  'session.started', 'session.changed', 'session.ended', 'resource.changed',
+  'task.created', 'task.changed', 'task.started', 'task.review_requested', 'task.changes_requested',
+  'task.completed', 'task.cancelled', 'task.reopened', 'task.blocked', 'task.unblocked',
+  'task.paused', 'task.resumed', 'task.assigned', 'task.linked', 'task.unlinked', 'task.commented', 'task.specified',
+]);
+export const PUBLISHABLE_EVENTS = APP_EVENTS.filter(kind => /^(task|agent)\./.test(kind));
+export const eventReadAction = kind => ({session:'sessions.read',membership:'members.read',machine:'machines.read',task:'events.read',agent:'events.read',app:'teams.read'}[kind] ?? 'events.read');