@volter/teams 0.1.89 → 0.2.0

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@volter/teams",
-  "version": "0.1.89",
+  "version": "0.2.0",
   "type": "module",
   "description": "Volter Teams, the neutral team plane: machine identity and daemon core, the local door and server link, admission from machine grants, product doors, and the Teams server's neutral routes (company RFC 0008).",
   "license": "MIT",
   "exports": {
+    "./agent-profile": {"types":"./agent-profile.d.ts","default":"./agent-profile.mjs"},
     ".": "./index.mjs",
     "./channel": "./channel.mjs",
     "./browser-channel": {
@@ -21,7 +22,6 @@
     "./machine-core": "./machine-core.mjs",
     "./home": "./home.mjs",
     "./server/core": "./server/core.mjs",
-    "./server/identity-orgs": "./server/identity-orgs.mjs",
     "./server/http": "./server/http.mjs",
     "./server/apps": "./server/apps.mjs",
     "./server/auth": "./server/auth.mjs",
@@ -32,9 +32,19 @@
     "./server/wire": "./server/wire.mjs",
     "./server/migrations": "./server/migrations/index.mjs",
     "./client": "./client.mjs",
+    "./lines": "./lines.mjs",
     "./stream-rpc": "./stream-rpc.mjs",
     "./server/delegated": "./server/delegated.mjs",
-    "./server/viewer": "./server/viewer.mjs"
+    "./server/viewer": "./server/viewer.mjs",
+    "./http-client": {
+      "types": "./http-client.d.ts",
+      "default": "./http-client.mjs"
+    },
+    "./context": "./context.mjs",
+    "./event-client": "./event-client.mjs",
+    "./machine-door": "./machine-door.mjs",
+    "./sender-identity": "./sender-identity.mjs",
+    "./server/agent-authority": "./server/agent-authority.mjs"
   },
   "files": [
     "LICENSE-MIT",
@@ -43,7 +53,9 @@
     "session-follow.d.ts",
     "server",
     "viewer",
-    "README.md"
+    "README.md",
+    "http-client.d.ts",
+    "identity-record.d.ts"
   ],
   "engines": {
     "node": ">=22"

package/sender-identity.mjs

@@ -0,0 +1,55 @@
+// Public client: durable observation before attribution. Names never create proof.
+import { mkdirSync, writeFileSync, renameSync, readdirSync, readFileSync, unlinkSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { randomUUID, createHash } from 'node:crypto';
+import { eventClient } from './event-client.mjs';
+import { teamsHome } from './home.mjs';
+
+export class SenderIdentityRecord {
+  constructor({home=teamsHome(),supercodeHome=dirname(home),context,fetch}={}) {
+    this.home=home;this.select={supercodeHome,context,fetch};
+  }
+  selected() { try{return eventClient(this.select);}catch{return null;} }
+  async observe({observation,location,at=Date.now(),name=null,evidence={source:'sender'}}) {
+    const selected=this.selected(),org=selected?.context.org??null,server=selected?.context.server??null;
+    const audience=createHash('sha256').update(JSON.stringify([org,server])).digest('hex');
+    const directory=join(this.home,'identity','observations',audience);
+    mkdirSync(directory,{recursive:true,mode:0o700});
+    if(typeof observation!=='string'||!observation.includes(':'))throw new TypeError('a sender observation must be namespaced');
+    name=typeof name==='string'?name.replace(/[\x00-\x1f]/g,'').slice(0,256)||null:null;
+    const id=randomUUID(),path=join(directory,`${id}.json`),body={observation,location,at,name,evidence};
+    writeFileSync(path,JSON.stringify({org,server,body})+'\n',{mode:0o600,flag:'wx'});
+    let resolution={observation,org,principal:null,classification:'unresolved',label:'unresolved',links:[]};
+    if(!selected)return {...resolution,pending:true};
+    // Only this audience's pending sightings replay; an unknown local audience stays local.
+    // Arrival drives retry. No identity inference or background scan runs.
+    for(const file of readdirSync(directory).filter(f=>f.endsWith('.json')).slice(0,1)) {
+      const pending=join(directory,file);let saved;try{saved=JSON.parse(readFileSync(pending,'utf8'));}catch(error){if(error.code==='ENOENT')continue;throw error;}
+      const key=`identity-sighting-${file.slice(0,-5)}`;
+      try {await selected.team.identity.observe(saved.body,{idempotencyKey:key,signal:AbortSignal.timeout(1000)});try{unlinkSync(pending);}catch(error){if(error.code!=='ENOENT')throw error;}}
+      catch {break;}
+    }
+    try {
+      const record=(await selected.team.identity.resolve(observation,{signal:AbortSignal.timeout(1000)})).data;
+      resolution={...record,org};
+      const cache=join(this.home,'identity',audience+'.json');
+      // One record per observation; atomic files avoid competing gateway/mail processes losing entries.
+      const cacheDirectory=cache.slice(0,-5);mkdirSync(cacheDirectory,{recursive:true,mode:0o700});
+      const target=join(cacheDirectory,createHash('sha256').update(observation).digest('hex')+'.json'),temp=target+'.'+randomUUID();
+      writeFileSync(temp,JSON.stringify(resolution)+'\n',{mode:0o600,flag:'wx'});renameSync(temp,target);
+    }catch {
+      // Current authority is unknown. A cached former proof does not become current attribution.
+      resolution={...resolution,unavailable:true};
+    }
+    return {...resolution,pending:readdirSync(directory).includes(id+'.json')};
+  }
+  async approvedPairing({platform,user_id,user_name,code,principal_id=null,location='pairing'}) {
+    const selected=this.selected();if(!selected)throw new Error('recording pairing proof needs a selected Teams context');
+    // Called only after Hermes returns its successful approval receipt; the code itself is never retained.
+    if(!principal_id){const existing=(await selected.team.identity.resolve(`${platform}:${user_id}`)).data;if(existing.classification==='proven')return existing.links.find(link=>link.classification==='proven');}
+    principal_id??=(await selected.team.identity.declarePerson({name:user_name||`${platform}:${user_id}`})).data.id;
+    const result=await selected.team.identity.link({observation:`${platform}:${user_id}`,principal_id,classification:'proven',
+      proof:{kind:'pairing',evidence:{location,approved_by:selected.context.principal,code_digest:createHash('sha256').update(code).digest('hex')}}});
+    return result.data;
+  }
+}

package/server/agent-authority.mjs

@@ -0,0 +1,21 @@
+// Live agency and delegation are evaluated from the store; identity labels and environment hints grant nothing.
+export const AGENT_ACTIVE = `WITH RECURSIVE scope(team,id) AS (VALUES(?,?)), chain(id) AS (
+ SELECT a.id FROM agents a,scope s WHERE a.team_id=s.team AND a.id=s.id
+ UNION SELECT a.parent_id FROM agents a JOIN chain c ON a.id=c.id,scope s WHERE a.team_id=s.team AND a.parent_id IS NOT NULL
+ UNION SELECT json_extract(CASE WHEN j.type='object' THEN j.value ELSE '{}' END,'$.id') FROM agents a JOIN chain c ON a.id=c.id,scope s,json_tree(a.lineage_json,'$.starter') j WHERE a.team_id=s.team AND j.type='object' AND json_extract(CASE WHEN j.type='object' THEN j.value ELSE '{}' END,'$.kind')='agent'
+), ancestry(seed,id) AS (
+ SELECT id,id FROM chain
+ UNION SELECT g.seed,a.parent_id FROM ancestry g JOIN agents a ON a.id=g.id,scope s WHERE a.team_id=s.team AND a.parent_id IS NOT NULL
+ UNION SELECT g.seed,json_extract(CASE WHEN j.type='object' THEN j.value ELSE '{}' END,'$.id') FROM ancestry g JOIN agents a ON a.id=g.id,scope s,json_tree(a.lineage_json,'$.starter') j WHERE a.team_id=s.team AND j.type='object' AND json_extract(CASE WHEN j.type='object' THEN j.value ELSE '{}' END,'$.kind')='agent'
+), people(seed,id) AS (
+ SELECT g.seed,a.sponsor_id FROM agents a JOIN ancestry g ON a.id=g.id,scope s WHERE a.team_id=s.team
+ UNION SELECT g.seed,json_extract(CASE WHEN j.type='object' THEN j.value ELSE '{}' END,'$.id') FROM agents a JOIN ancestry g ON a.id=g.id,scope s,json_tree(a.lineage_json,'$.starter') j WHERE a.team_id=s.team AND j.type='object' AND json_extract(CASE WHEN j.type='object' THEN j.value ELSE '{}' END,'$.kind')='person'
+ UNION SELECT g.seed,ps.sponsor_id FROM agents a JOIN ancestry g ON a.id=g.id JOIN json_tree(a.lineage_json,'$.starter') j ON j.type='object' JOIN principal_sponsors ps ON ps.team_id=a.team_id AND ps.principal_id=json_extract(CASE WHEN j.type='object' THEN j.value ELSE '{}' END,'$.id'),scope s WHERE a.team_id=s.team
+ UNION SELECT g.seed,i.installer_id FROM agents a JOIN ancestry g ON a.id=g.id JOIN json_tree(a.lineage_json,'$.starter') j ON j.type='object' JOIN app_installations i ON i.team_id=a.team_id AND i.principal_id=json_extract(CASE WHEN j.type='object' THEN j.value ELSE '{}' END,'$.id') AND i.state='active' JOIN apps app ON app.id=i.app_id AND app.state='active',scope s WHERE a.team_id=s.team
+) SELECT 1 FROM agents root,scope s WHERE root.id=s.id AND root.team_id=s.team
+ AND NOT EXISTS(SELECT 1 FROM chain c LEFT JOIN agents a ON a.id=c.id AND a.team_id=s.team WHERE a.id IS NULL OR a.state!='active' OR NOT EXISTS(
+  SELECT 1 FROM people x JOIN principals p ON p.id=x.id WHERE x.seed=a.id AND p.kind='user' AND
+   (EXISTS(SELECT 1 FROM memberships m WHERE m.team_id=s.team AND m.principal_id=p.id AND m.active=1)
+    OR EXISTS(SELECT 1 FROM identity_principals ip WHERE ip.team_id=s.team AND ip.principal_id=p.id)
+    AND NOT EXISTS(SELECT 1 FROM memberships m WHERE m.team_id=s.team AND m.principal_id=p.id AND m.active=0))))`;
+export const AGENT_DESCENDANTS = `WITH RECURSIVE tree(id) AS (SELECT id FROM agents WHERE team_id=? AND id=? UNION SELECT a.id FROM agents a JOIN tree t ON a.parent_id=t.id) SELECT id FROM tree`;

package/server/agent-sessions.mjs

@@ -0,0 +1,226 @@
+// Session ownership is stable identity; resolved configuration is reported by its enrolled machine.
+import { agentIdentity, agentSponsor, manageableAgent, managementGuards, publication } from './agents.mjs';
+import { exact } from './request-json.mjs';
+import { AGENT_ACTIVE } from './agent-authority.mjs';
+import { APP_LINEAGE_REVOKED } from './auth.mjs';
+import { deliverNativeMail } from './machine-link.mjs';
+import { createHash } from 'node:crypto';
+import { nativeSessionSnapshot } from './session-snapshot.mjs';
+const fail=(status,code,message)=>{throw Object.assign(new Error(message),{status,code});};
+const stmt=(sql,...params)=>({sql,params});
+const guard=(sql,params,message='session ownership changed')=>({sql,params,status:409,code:'conflict',message});
+const memberGuards=(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],'credential changed'),
+  guard('SELECT 1 FROM memberships WHERE team_id=? AND principal_id=? AND active=1',[auth.team_id,auth.principal_id],'membership changed'),
+];
+const ownerGuard=(auth,session)=>guard('SELECT 1 FROM sessions WHERE team_id=? AND id=? AND custodian_id=? AND deleted_at IS NULL',[auth.team_id,session.id,auth.principal_id],'only the current custodian declares session ownership');
+const revisionGuard=(team,session,record)=>record
+  ?guard('SELECT 1 FROM agent_sessions WHERE team_id=? AND session_id=? AND revision=?',[team,session,record.revision])
+  :guard('SELECT 1 WHERE NOT EXISTS(SELECT 1 FROM agent_sessions WHERE team_id=? AND session_id=?)',[team,session]);
+// Identity updates preserve the native session snapshot consumed by event-driven supervision.
+const publish=(api,auth,session,data,now)=>stmt(`INSERT INTO org_events(id,team_id,kind,resource_kind,resource_id,actor_json,data_json,created_at)
+ SELECT ?,?,?,'session',?,?,json_set(${nativeSessionSnapshot('s.team_id','s.id')},'$.agent_identity',json(?)),?
+ FROM sessions s WHERE s.team_id=? AND s.id=?`,
+ api.ids.next('event'),auth.team_id,'session.changed',session,JSON.stringify({principal:auth.principal_id,session:null,lineage:auth.act??[]}),JSON.stringify(data),now,auth.team_id,session);
+
+export async function sessionIdentity(api,team,session){
+  const record=await api.store.one('SELECT * FROM agent_sessions WHERE team_id=? AND session_id=?',[team,session]);
+  // A session nobody recorded lineage for is plain: it says so, and names the person whose machine runs it, as a fact,
+  // never as its starter (`agent record` records that).
+  if(!record){const held=await api.store.one('SELECT custodian_id FROM sessions WHERE team_id=? AND id=?',[team,session]);
+    return {session,agent:null,state:'unrecorded',plain:true,custodian:held?.custodian_id??null,starter:null,resolved:null,main:false};}
+  const agent=record.agent_id?await api.store.one('SELECT * FROM agents WHERE team_id=? AND id=?',[team,record.agent_id]):null;
+  return {session,agent:agent?await agentIdentity(api,team,agent):null,starter:JSON.parse(record.starter_json),
+    resolved:JSON.parse(record.profile_json),resolved_at:JSON.parse(record.profile_json)===null?null:record.resolved_at,
+    main:Boolean(record.main),ended_at:record.ended_at,end_reason:record.end_reason,revision:record.revision};
+}
+export async function authorizeAgentMail(api,auth,ref){
+  if(!auth.agent_credential||auth.principal_kind!=='agent')fail(403,'forbidden','an agent session credential is required');
+  const session=await api.store.authorizedSession({teamId:auth.team_id,principalId:auth.principal_id,credentialId:auth.credential_id,ref,now:api.clock.nowMs()});
+  const owner=await api.store.one('SELECT * FROM agent_sessions WHERE team_id=? AND session_id=? AND agent_id=? AND ended_at IS NULL',[auth.team_id,session.id,auth.principal_id]);
+  if(!owner)fail(404,'not_found','live own session not found');
+  return {session,owner};
+}
+async function sendAgentMail(api,auth,ref,text,idempotencyKey){
+  const standing=await api.store.one('SELECT auth_epoch FROM teams WHERE id=?',[auth.team_id]);
+  const {session,owner}=await authorizeAgentMail(api,auth,ref),now=api.clock.nowMs();
+  const target=await api.store.one(`WITH RECURSIVE family(id) AS (SELECT ? UNION SELECT s.id FROM sessions s JOIN family f ON s.canonical_id=f.id WHERE s.team_id=? AND s.deleted_at IS NULL)
+    SELECT o.source_id,o.session_id,o.harness,o.native_id,o.sequence,src.machine_id,m.name 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
+    JOIN machines m ON m.team_id=src.team_id AND m.id=src.machine_id
+    WHERE o.team_id=? AND o.deleted_at IS NULL AND src.state='active' AND m.revoked_at IS NULL ORDER BY o.sequence DESC,o.source_id,o.native_id LIMIT 1`,[session.id,auth.team_id,auth.team_id]);
+  if(!target)fail(404,'not_found','live session origin not found');
+  const machineName=String(target.name).split('.')[0].toLowerCase().replace(/[^a-z0-9_-]/g,'-');
+  const to=`sc:${machineName}:${target.harness}:${target.native_id}`,grant=api.ids.next('grant');
+  const boundary=at=>[
+    {sql:'SELECT 1 FROM teams WHERE id=? AND auth_epoch=?',params:[auth.team_id,standing.auth_epoch],status:409,code:'conflict',message:'session authorization changed'},
+    {sql:'SELECT 1 FROM credentials WHERE id=? AND principal_id=? AND revoked_at IS NULL AND expires_at>?',params:[auth.credential_id,auth.principal_id,at],status:401,code:'authentication_required',message:'agent credential changed'},
+    {sql:AGENT_ACTIVE,params:[auth.team_id,auth.principal_id],status:401,code:'authentication_required',message:'agent standing changed'},
+    {sql:`SELECT 1 WHERE NOT EXISTS(${APP_LINEAGE_REVOKED})`,params:[auth.credential_id,at],status:401,code:'authentication_required',message:'delegation changed'},
+    {sql:'SELECT 1 FROM agent_sessions WHERE team_id=? AND session_id=? AND agent_id=? AND revision=? AND ended_at IS NULL',params:[auth.team_id,session.id,auth.principal_id,owner.revision],status:409,code:'conflict',message:'session ownership changed'},
+    {sql:'WITH RECURSIVE family(id) AS (SELECT id FROM sessions WHERE team_id=? AND id=? AND canonical_id IS NULL AND deleted_at IS NULL UNION SELECT s.id FROM sessions s JOIN family f ON s.canonical_id=f.id WHERE s.team_id=? AND s.deleted_at IS NULL) SELECT 1 FROM family WHERE id=?',params:[auth.team_id,session.id,auth.team_id,target.session_id],status:409,code:'conflict',message:'native session family changed'},
+    {sql:'SELECT 1 FROM origins o JOIN sources src ON src.team_id=o.team_id AND src.id=o.source_id JOIN machines m ON m.team_id=src.team_id AND m.id=src.machine_id WHERE o.team_id=? AND o.source_id=? AND o.session_id=? AND o.harness=? AND o.native_id=? AND o.sequence=? AND o.deleted_at IS NULL AND src.state=\'active\' AND m.id=? AND m.revoked_at IS NULL',params:[auth.team_id,target.source_id,target.session_id,target.harness,target.native_id,target.sequence,target.machine_id],status:409,code:'conflict',message:'native session origin changed'},
+  ];
+  await api.store.guardedTransaction(boundary(now),[stmt('INSERT INTO machine_grants(team_id,id,machine_id,subject_id,caps_json,targets_json,issuer_id,created_at,expires_at) VALUES (?,?,?,?,?,?,?,?,?)',auth.team_id,grant,target.machine_id,auth.principal_id,JSON.stringify(['mail']),JSON.stringify([`mail:${to}`]),auth.principal_id,now,Math.min(now+30000,auth.expires_at))]);
+  try{
+    const agent=await api.store.one('SELECT name FROM agents WHERE team_id=? AND id=?',[auth.team_id,auth.principal_id]);
+    const digest=createHash('sha256').update(JSON.stringify([auth.team_id,auth.principal_id,session.id,idempotencyKey])).digest('hex');
+    return await deliverNativeMail(api,auth.team_id,target.machine_id,{principal:auth.principal_id,groups:[],grants:[grant],revisions:{[grant]:1}},
+      {op:'send',from:`sc:${machineName}:operator:${auth.principal_id}`,from_name:agent.name,to,body:text,id:`agent-mail:${digest}`,queue:false},
+      async()=>{await authorizeAgentMail(api,auth,session.id);await api.store.guardedTransaction(boundary(api.clock.nowMs()),[]);});
+  }finally{await api.store.transaction([stmt('DELETE FROM machine_grants WHERE team_id=? AND id=?',auth.team_id,grant)]);}
+}
+async function starterFor(api,auth,ref,now){
+  const principal=await api.store.one('SELECT kind FROM principals WHERE id=?',[auth.principal_id]);
+  const starter={kind:({user:'person',agent:'agent',service:'automation'})[principal.kind],id:auth.principal_id};
+  if(!ref)return starter;
+  const session=await api.store.authorizedSession({teamId:auth.team_id,principalId:auth.principal_id,credentialId:auth.credential_id,ref,now});
+  if(session.custodian_id!==auth.principal_id)fail(403,'forbidden','starter session must be your own');
+  const parent=await api.store.one('SELECT agent_id,starter_json FROM agent_sessions WHERE team_id=? AND session_id=?',[auth.team_id,session.id]);
+  return parent?.agent_id?{kind:'agent',id:parent.agent_id,session:session.id}:{kind:'session',id:session.id,delegator:parent?JSON.parse(parent.starter_json):starter};
+}
+/** Resolve only origins admitted to this machine; retain every canonical edge as a write guard. */
+export async function machineProfileSession(api,auth,ref){
+  const native=/^([a-z][a-z0-9-]*):(.+)$/.exec(ref??'');
+  const rows=await api.store.query(`SELECT DISTINCT s.* FROM sessions s JOIN origins o ON o.team_id=s.team_id AND o.session_id=s.id JOIN sources src ON src.team_id=o.team_id AND src.id=o.source_id JOIN machines m ON m.team_id=src.team_id AND m.id=src.machine_id WHERE s.team_id=? AND s.deleted_at IS NULL AND o.deleted_at IS NULL AND o.source_id=? AND src.machine_id=? AND src.state='active' AND m.revoked_at IS NULL AND ${native?'o.harness=? AND o.native_id=?':'s.id=?'}`,[auth.team_id,auth.source_id,auth.machine_id,...(native?[native[1],native[2]]:[ref])]);
+  if(rows.length!==1)fail(404,'not_found','session is not uniquely captured by this machine');
+  const origin=rows[0],edges=[],seen=new Set();let session=origin;
+  while(session){
+    if(seen.has(session.id))fail(409,'conflict','session correlation cycle');seen.add(session.id);
+    edges.push(guard('SELECT 1 FROM sessions WHERE team_id=? AND id=? AND canonical_id IS ? AND deleted_at IS NULL',[auth.team_id,session.id,session.canonical_id]));
+    if(!session.canonical_id)break;
+    session=await api.store.one('SELECT * FROM sessions WHERE team_id=? AND id=? AND deleted_at IS NULL',[auth.team_id,session.canonical_id]);
+  }
+  if(!session)fail(404,'not_found','canonical session not found');
+  edges.push(guard("SELECT 1 FROM machines m JOIN sources src ON src.team_id=m.team_id AND src.machine_id=m.id JOIN origins o ON o.team_id=src.team_id AND o.source_id=src.id WHERE m.team_id=? AND m.id=? AND m.revoked_at IS NULL AND src.id=? AND src.state='active' AND o.session_id=? AND o.deleted_at IS NULL",[auth.team_id,auth.machine_id,auth.source_id,origin.id],'machine source changed'));
+  return {session,guards:edges};
+}
+export async function agentSessionRoute(ctx){
+  const {api,req,res,auth,sub,url,requestId,parseJson,send,result,guardedMutation}=ctx;
+  const now=api.clock.nowMs();let match;
+  if((match=/^\/machines\/([^/]+)\/agent-closures(?:\/([^/]+)(?:\/(claim|result))?)?$/.exec(sub))){
+    if(auth.kind!=='machine'||auth.machine_id!==match[1])fail(403,'forbidden','the owning machine consumes session closures');
+    if(req.method==='GET'&&!match[2]){
+      const rows=await api.store.query("SELECT * FROM agent_session_closures WHERE team_id=? AND machine_id=? AND state IN ('pending','claimed') ORDER BY created_at,id LIMIT 100",[auth.team_id,auth.machine_id]);
+      send(res,200,result(api,auth,{items:rows}),requestId);return true;
+    }
+    if(req.method==='GET'&&match[2]&&!match[3]){
+      const row=await api.store.one('SELECT c.* FROM agent_session_closures c JOIN agents a ON a.team_id=c.team_id AND a.id=c.agent_id WHERE c.team_id=? AND c.machine_id=? AND c.id=? AND a.state=\'ended\'',[auth.team_id,auth.machine_id,match[2]]);
+      if(!row)fail(404,'not_found','closure not found');
+      send(res,200,result(api,auth,row),requestId);return true;
+    }
+    if(req.method!=='POST'||!match[2])fail(404,'not_found','closure operation not found');
+    const row=await api.store.one('SELECT * FROM agent_session_closures WHERE team_id=? AND machine_id=? AND id=?',[auth.team_id,auth.machine_id,match[2]]);
+    if(!row)fail(404,'not_found','closure not found');
+    const body=await parseJson(req);
+    const guards=[...memberGuards(auth,now),guard("SELECT 1 FROM agents WHERE team_id=? AND id=? AND state='ended'",[auth.team_id,row.agent_id],'agent end changed'),guard('SELECT 1 FROM machines WHERE team_id=? AND id=? AND revoked_at IS NULL',[auth.team_id,auth.machine_id],'machine changed')];
+    if(match[3]==='claim'){
+      exact(body,[]);
+      if(row.state!=='pending'){send(res,200,result(api,auth,{execute:false,state:row.state}),requestId);return true;}
+      const response=result(api,auth,{execute:true,state:'claimed'});
+      guards.push(guard("SELECT 1 FROM agent_session_closures WHERE team_id=? AND id=? AND state='pending'",[auth.team_id,row.id],'closure already claimed'));
+      await guardedMutation(api,res,auth,guards,[stmt("UPDATE agent_session_closures SET state='claimed',claimed_at=? WHERE team_id=? AND id=?",now,auth.team_id,row.id)],{status:200,body:response,targetId:row.id});
+      send(res,200,response,requestId);return true;
+    }
+    exact(body,['state','reason']);
+    if(!['closed','failed','unknown'].includes(body.state)||typeof body.reason!=='string'||body.reason.length>1024)fail(400,'invalid_request','invalid closure result');
+    if(row.state!=='claimed'){
+      if(row.result_json!==JSON.stringify(body))fail(409,'conflict','closure result changed');
+      send(res,200,result(api,auth,body),requestId);return true;
+    }
+    guards.push(guard("SELECT 1 FROM agent_session_closures WHERE team_id=? AND id=? AND state='claimed'",[auth.team_id,row.id]));
+    const response=result(api,auth,body);
+    await guardedMutation(api,res,auth,guards,[stmt('UPDATE agent_session_closures SET state=?,result_json=?,finished_at=? WHERE team_id=? AND id=?',body.state,JSON.stringify(body),now,auth.team_id,row.id)],{status:200,body:response,targetId:row.id});
+    send(res,200,response,requestId);return true;
+  }
+  if(req.method==='POST'&&(match=/^\/sessions\/([^/]+)\/mail$/.exec(sub))){
+    const body=await parseJson(req);exact(body,['text']);
+    if(typeof body.text!=='string'||!body.text.trim()||body.text.length>65536)fail(400,'invalid_request','text must contain 1..65536 characters');
+    const receipt=await sendAgentMail(api,auth,decodeURIComponent(match[1]),body.text,req.headers['idempotency-key']);
+    await send(res,200,result(api,auth,receipt),requestId);return true;
+  }
+  if((match=/^\/machines\/([^/]+)\/session-profiles$/.exec(sub))&&req.method==='POST'){
+    if(auth.kind!=='machine'||auth.machine_id!==match[1])fail(403,'forbidden','the owning machine reports resolved profiles');
+    const body=await parseJson(req);exact(body,['session','profile','observed_at','observation_id']);
+    if(typeof body.session!=='string'||!body.profile||typeof body.profile!=='object'||Array.isArray(body.profile))fail(400,'invalid_request','session and resolved profile object are required');
+    const observedAt=body.observed_at??now;
+    if(!Number.isSafeInteger(observedAt)||observedAt<0||body.observation_id!==undefined&&!/^profile_[0-9a-f]{32}$/.test(body.observation_id))fail(400,'invalid_request','observed_at and observation_id are invalid');
+    const {session,guards:machineGuards}=await machineProfileSession(api,auth,body.session);
+    const record=await api.store.one('SELECT * FROM agent_sessions WHERE team_id=? AND session_id=?',[auth.team_id,session.id]);
+    if(!record)fail(409,'conflict','declare the session lineage before reporting its profile');
+    const value=JSON.stringify(body.profile),revision=record.revision+1,response=result(api,auth,{session:session.id,resolved:body.profile,resolved_at:observedAt,revision});
+    await guardedMutation(api,res,auth,[...memberGuards(auth,now),revisionGuard(auth.team_id,session.id,record),
+      ...machineGuards],
+      [stmt('UPDATE agent_sessions SET profile_json=?,resolved_at=?,revision=? WHERE team_id=? AND session_id=?',value,observedAt,revision,auth.team_id,session.id),
+       stmt('INSERT INTO session_profile_history(team_id,session_id,revision,profile_json,recorded_at) VALUES (?,?,?,?,?)',auth.team_id,session.id,revision,value,observedAt),publish(api,auth,session.id,response.data,now)],{status:200,body:response,targetId:session.id});
+    send(res,200,response,requestId);return true;
+  }
+  if((match=/^\/sessions\/([^/]+)\/agent$/.exec(sub))){
+    const session=await api.store.authorizedSession({teamId:auth.team_id,principalId:auth.principal_id,credentialId:auth.credential_id,ref:decodeURIComponent(match[1]),now});
+    if(req.method==='GET'){send(res,200,result(api,auth,await sessionIdentity(api,auth.team_id,session.id)),requestId);return true;}
+    if(req.method!=='POST')fail(404,'not_found','session identity operation not found');
+    const body=await parseJson(req);exact(body,['starter_session']);
+    if(session.custodian_id!==auth.principal_id||auth.app_grants!=null||auth.installation_id)fail(403,'forbidden','only native custody records a plain session');
+    const old=await api.store.one('SELECT * FROM agent_sessions WHERE team_id=? AND session_id=?',[auth.team_id,session.id]);
+    if(old){send(res,200,result(api,auth,await sessionIdentity(api,auth.team_id,session.id)),requestId);return true;}
+    const starter=await starterFor(api,auth,body.starter_session,now);
+    if(starter.kind==='agent'){
+      // Rule 2: a session an agent's session starts is that agent's, a concurrent session of it (a helper,
+      // a parallel thread). Recording it needs the same management standing as any ownership declaration.
+      const agent=await api.store.one('SELECT * FROM agents WHERE team_id=? AND id=?',[auth.team_id,starter.id]);
+      if(!agent||!await manageableAgent(api,auth,agent))fail(403,'forbidden','only the agent\'s custodian, parent, sponsor or an Org admin records its sessions');
+      const standing=[];
+      if(agent.state!=='active'||!await agentSponsor(api,auth.team_id,agent,new Set(),standing))fail(409,'conflict','a suspended or ended agent cannot start sessions');
+      const data={session:session.id,agent:await agentIdentity(api,auth.team_id,agent),starter,resolved:null,main:false,revision:1};
+      await guardedMutation(api,res,auth,[...memberGuards(auth,now),ownerGuard(auth,session),...standing,...await managementGuards(api,auth,agent),revisionGuard(auth.team_id,session.id,null)],
+        [stmt("INSERT INTO agent_sessions(team_id,session_id,agent_id,starter_json,profile_json,resolved_at,main) VALUES (?,?,?,?,'null',?,0)",auth.team_id,session.id,agent.id,JSON.stringify(starter),now),
+         stmt('UPDATE teams SET auth_epoch=auth_epoch+1 WHERE id=?',auth.team_id),publish(api,auth,session.id,data,now)],{status:201,body:result(api,auth,data),targetId:session.id});
+      send(res,201,result(api,auth,data),requestId);return true;
+    }
+    const data={session:session.id,agent:null,starter,resolved:null,main:false,revision:1};
+    await guardedMutation(api,res,auth,[...memberGuards(auth,now),ownerGuard(auth,session),revisionGuard(auth.team_id,session.id,null)],
+      [stmt("INSERT INTO agent_sessions(team_id,session_id,agent_id,starter_json,profile_json,resolved_at) VALUES (?,?,NULL,?,'null',?)",auth.team_id,session.id,JSON.stringify(starter),now),publish(api,auth,session.id,data,now)],{status:201,body:result(api,auth,data),targetId:session.id});
+    send(res,201,result(api,auth,data),requestId);return true;
+  }
+  if(!(match=/^\/agents\/([^/]+)\/sessions$/.exec(sub)))return false;
+  const agent=await api.store.one('SELECT * FROM agents WHERE team_id=? AND id=?',[auth.team_id,decodeURIComponent(match[1])]);
+  if(!agent)fail(404,'not_found','agent not found');
+  if(req.method==='GET'){
+    const limit=Number(url.searchParams.get('limit')??100),after=url.searchParams.get('after')??'',descendants=url.searchParams.get('descendants')==='true';
+    if(!Number.isSafeInteger(limit)||limit<1||limit>200)fail(400,'invalid_request','limit must be 1..200');
+    const rows=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=? AND ?=1)
+      SELECT s.session_id FROM agent_sessions s JOIN tree t ON s.agent_id=t.id WHERE s.team_id=? AND s.session_id>? ORDER BY s.session_id LIMIT ?`,[agent.id,auth.team_id,descendants?1:0,auth.team_id,after,limit+1]);
+    const items=[];
+    for(const row of rows.slice(0,limit)){
+      try{await api.store.authorizedSession({teamId:auth.team_id,principalId:auth.principal_id,credentialId:auth.credential_id,ref:row.session_id,now:api.clock.nowMs()});}
+      catch(error){if([401,403,404,410].includes(error.status))continue;throw error;}
+      items.push(await sessionIdentity(api,auth.team_id,row.session_id));
+    }
+    send(res,200,{version:1,items,next_after:rows.length>limit?rows[limit-1].session_id:null},requestId);return true;
+  }
+  if(req.method!=='POST')fail(404,'not_found','agent session operation not found');
+  if(auth.app_grants!=null||auth.installation_id||!await manageableAgent(api,auth,agent))fail(403,'forbidden','only native agent management declares session ownership');
+  const body=await parseJson(req);exact(body,['session','main','starter_session']);
+  if(typeof body.session!=='string'||body.main!==undefined&&typeof body.main!=='boolean')fail(400,'invalid_request','session reference and optional main boolean are required');
+  const session=await api.store.authorizedSession({teamId:auth.team_id,principalId:auth.principal_id,credentialId:auth.credential_id,ref:body.session,now});
+  if(session.custodian_id!==auth.principal_id)fail(403,'forbidden','only your own session can be declared');
+  const old=await api.store.one('SELECT * FROM agent_sessions WHERE team_id=? AND session_id=?',[auth.team_id,session.id]);
+  if(old?.agent_id&&old.agent_id!==agent.id)fail(409,'conflict','a session already owned by an agent cannot change identity');
+  if(old?.ended_at!=null)fail(409,'conflict','an ended session cannot become live again');
+  const standing=[];
+  if(agent.state!=='active'||!await agentSponsor(api,auth.team_id,agent,new Set(),standing))fail(409,'conflict','a suspended or ended agent cannot launch');
+  const starter=old?JSON.parse(old.starter_json):await starterFor(api,auth,body.starter_session,now),main=body.main??!agent.main_session_id,revision=(old?.revision??0)+1;
+  if(body.main===false&&agent.main_session_id===session.id)fail(409,'conflict','select another main session before demoting the current one');
+  const data={session:session.id,agent:{...await agentIdentity(api,auth.team_id,agent),main_session:main?session.id:agent.main_session_id},starter,resolved:old?JSON.parse(old.profile_json):null,main,revision};
+  const statements=[];
+  if(main)statements.push(stmt('UPDATE agent_sessions SET main=0,revision=revision+1 WHERE team_id=? AND agent_id=? AND main=1 AND session_id!=?',auth.team_id,agent.id,session.id));
+  statements.push(old?stmt('UPDATE agent_sessions SET agent_id=?,main=?,revision=? WHERE team_id=? AND session_id=?',agent.id,main?1:0,revision,auth.team_id,session.id)
+    :stmt("INSERT INTO agent_sessions(team_id,session_id,agent_id,starter_json,profile_json,resolved_at,main) VALUES (?,?,?,?,'null',?,?)",auth.team_id,session.id,agent.id,JSON.stringify(starter),now,main?1:0));
+  if(main){data.agent.revision=agent.revision+1;}
+  if(main)statements.push(stmt('UPDATE agents SET main_session_id=?,revision=revision+1 WHERE team_id=? AND id=?',session.id,auth.team_id,agent.id));
+  // The main session is an Agent field (ontology Agent.main_session): its change is the agent's change too.
+  if(main&&agent.main_session_id!==session.id)statements.push(publication(api,auth,'agent.changed',agent.id,{...data.agent,revision:agent.revision+1},now));
+  statements.push(stmt('UPDATE teams SET auth_epoch=auth_epoch+1 WHERE id=?',auth.team_id),publish(api,auth,session.id,data,now));
+  await guardedMutation(api,res,auth,[...memberGuards(auth,now),ownerGuard(auth,session),...standing,...await managementGuards(api,auth,agent),revisionGuard(auth.team_id,session.id,old)],statements,{status:old?200:201,body:result(api,auth,data),targetId:session.id});
+  send(res,old?200:201,result(api,auth,data),requestId);return true;
+}