@volter/teams 0.1.90 → 0.2.0

package/README.md

@@ -19,3 +19,8 @@ reached by a team, with no harness in it.
   `api.harnessRoutes`.
 
 This package is private: nothing is published while nothing is open-sourced.
+
+Public Node clients are `@volter/teams/http-client` (`TeamsClient`),
+`@volter/teams/event-client` (selected-context event client), and
+`@volter/teams/machine-door` (an admitted local/remote machine channel).
+Context credentials remain inside the custody adapter; consumers use its public client.

package/agent-profile.mjs

@@ -0,0 +1,15 @@
+const object=value=>value!==null&&typeof value==='object'&&!Array.isArray(value);
+/** Compare declared intent with native observations. An unreported field is unknown, never a match or drift. */
+export function compareAgentProfile(intended,recorded){
+  const differences=[],unknown=[];
+  if(!intended)return {observed:recorded!=null,differences,unknown:['intent']};
+  const visit=(want,got,path)=>{
+    if(want===undefined||want===null)return;
+    if(got===undefined||got===null){unknown.push(path);return;}
+    if(object(want)&&object(got))for(const key of Object.keys(want))visit(want[key],got[key],path?`${path}.${key}`:key);
+    else if(JSON.stringify(want)!==JSON.stringify(got))differences.push({field:path,intended:want,actual:got});
+  };
+  visit(intended?.worker,recorded?.worker,'worker');
+  visit(intended?.permissions,recorded?.permissions,'permissions');
+  return {observed:recorded!=null,differences,unknown};
+}

package/client.mjs

@@ -54,6 +54,35 @@ export async function openRemoteMachine({ origin, teamId, machineId, token }, {
 
 /** Request/reply over a stream that carries JSON lines with `id`. */
 export { StreamRpc } from './stream-rpc.mjs';
+import { lineSplitter } from './lines.mjs';
+
+/**
+ * A `HarnessTransport` (harness SDK `ClientOptions.transport`) over the
+ * channel's `harness` stream. Only an operator's channel is admitted to it.
+ */
+export function harnessTransport(channel) {
+  let stream = null;
+  return {
+    get running() { return stream !== null && !stream.closed; },
+    async start(handlers) {
+      stream = await channel.open('harness');
+      const lines = lineSplitter();
+      stream.on('data', (chunk) => {
+        for (const line of lines(chunk)) if (line) handlers.onLine(line);
+      });
+      stream.on('close', (reason) => handlers.onExit(null, reason ?? null));
+    },
+    write(line) {
+      if (!stream || stream.closed) throw new Error('harness stream is not open');
+      stream.write(line.endsWith('\n') ? line : line + '\n');
+    },
+    async close() {
+      stream?.close();
+      stream = null;
+    },
+  };
+}
+
 
 /**
  * A harness's own execution server on the channel's machine, as the local address its client takes

package/context.mjs

@@ -0,0 +1,34 @@
+import { mkdirSync, readFileSync, writeFileSync, renameSync, openSync, closeSync, unlinkSync, existsSync, chmodSync } from 'node:fs';
+import { randomBytes } from 'node:crypto';
+import { join, dirname } from 'node:path';
+import { TeamsClient } from './http-client.mjs';
+const NAME=/^[a-z][a-z0-9_-]{0,63}$/;
+const ID=/^[A-Za-z][A-Za-z0-9_-]{0,127}$/;
+function normalizeOrigin(value){const url=new URL(value);if(url.username||url.password||url.pathname!=='/'||url.search||url.hash)throw new Error('server must be a bare HTTP(S) origin');if(url.protocol!=='https:'&&!(url.protocol==='http:'&&['127.0.0.1','::1','[::1]','localhost'].includes(url.hostname)))throw new Error('non-loopback servers require HTTPS');return url.origin;}
+export function workspacePaths(supercodeHome){const root=join(supercodeHome,'teams','workspaces');return {root,contexts:join(root,'contexts.json'),credentials:join(root,'credentials'),connectors:join(root,'connectors')};}
+function locked(path,fn){mkdirSync(dirname(path),{recursive:true,mode:0o700});chmodSync(dirname(path),0o700);const lock=path+'.lock';let fd;try{fd=openSync(lock,'wx',0o600);}catch(e){throw Object.assign(new Error(`${path} is locked by another writer`),{code:'EBUSY',cause:e});}try{return fn();}finally{closeSync(fd);unlinkSync(lock);}}
+function read(path,fallback){return existsSync(path)?JSON.parse(readFileSync(path,'utf8')):fallback;}
+function atomic(path,value){const tmp=`${path}.${process.pid}.${randomBytes(12).toString('hex')}.tmp`,fd=openSync(tmp,'wx',0o600);try{writeFileSync(fd,JSON.stringify(value,null,2)+'\n');}finally{closeSync(fd);}try{renameSync(tmp,path);}catch(error){try{unlinkSync(tmp);}catch{}throw error;}chmodSync(path,0o600);}
+export class WorkspaceContexts { constructor(supercodeHome){this.paths=workspacePaths(supercodeHome);} read(){return read(this.paths.contexts,{version:1,current:null,contexts:{}});} create(name,value){if(!NAME.test(name)||name==='local')throw new Error('context name must match [a-z][a-z0-9_-]{0,63} and cannot be local');return locked(this.paths.contexts,()=>{const doc=this.read();if(doc.contexts[name])throw new Error(`context ${name} already exists`);doc.contexts[name]=value;atomic(this.paths.contexts,doc);return value;});} use(name){return locked(this.paths.contexts,()=>{const doc=this.read();if(name!==null&&name!=='local'&&!doc.contexts[name])throw new Error(`unknown context ${name}`);doc.current=name;atomic(this.paths.contexts,doc);});} remove(name){return locked(this.paths.contexts,()=>{const doc=this.read();delete doc.contexts[name];if(doc.current===name)doc.current=null;atomic(this.paths.contexts,doc);});} writeCredential(id,value){mkdirSync(this.paths.credentials,{recursive:true,mode:0o700});locked(join(this.paths.credentials,`${id}.json`),()=>atomic(join(this.paths.credentials,`${id}.json`),value));} credential(id){return read(join(this.paths.credentials,`${id}.json`),null);} }
+WorkspaceContexts.prototype.upsert=function(name,value){if(!NAME.test(name)||name==='local')throw new Error('context name must match [a-z][a-z0-9_-]{0,63} and cannot be local');return locked(this.paths.contexts,()=>{const doc=this.read();doc.contexts[name]=value;atomic(this.paths.contexts,doc);return value;});};
+WorkspaceContexts.prototype.createAuthenticated=async function(name,{origin,teamId,credentialRef,fetch}){
+  if(!ID.test(teamId)||!/^cred_[A-Za-z0-9_-]+$/.test(credentialRef))throw new Error('team and credential reference must be immutable IDs');
+  const normalized=normalizeOrigin(origin),credential=this.credential(credentialRef);
+  if(!credential?.token)throw Object.assign(new Error(`credential ${credentialRef} is missing`),{code:'authentication_required'});
+  if(credential.origin!==normalized)throw Object.assign(new Error('credential origin does not match requested server'),{code:'authentication_required'});
+  const client=new TeamsClient({server:normalized,credential:credential.token,fetch});
+  const me=await client.me();
+  if(credential.server_id&&credential.server_id!==me.server_id)throw Object.assign(new Error('credential server audience does not match'),{code:'authentication_required'});
+  const membership=me.teams.find(item=>item.team.id===teamId);
+  if(!membership)throw Object.assign(new Error('credential is not a member of the requested team'),{code:'forbidden'});
+  return this.create(name,{origin:normalized,server_id:me.server_id,team_id:teamId,principal_id:me.principal.id,credential_ref:credentialRef});
+};
+WorkspaceContexts.prototype.connector=function(serverId,teamId){
+  if(!ID.test(serverId)||!ID.test(teamId))throw new Error('server and team must be immutable IDs');
+  const directory=join(this.paths.connectors,serverId,teamId),path=join(directory,'enrollment.json');
+  return {directory,read:()=>read(path,null),write:value=>{mkdirSync(directory,{recursive:true,mode:0o700});locked(path,()=>atomic(path,value));},update:fn=>{mkdirSync(directory,{recursive:true,mode:0o700});return locked(path,()=>{const value=fn(read(path,null));if(value===null){if(existsSync(path))unlinkSync(path);}else atomic(path,value);return value;});},remove:()=>{if(existsSync(path))locked(path,()=>unlinkSync(path));}};
+};
+export function fromContext({supercodeHome,name,fetch}){const contexts=new WorkspaceContexts(supercodeHome),doc=contexts.read(),selected=name??doc.current;if(!selected||selected==='local')throw new Error('a remote workspace context is required');const context=doc.contexts[selected];if(!context)throw new Error(`unknown context ${selected}`);const credential=contexts.credential(context.credential_ref);if(!credential?.token)throw Object.assign(new Error(`credential ${context.credential_ref} is missing`),{code:'authentication_required'});if(credential.server_id!==context.server_id||credential.origin!==context.origin)throw Object.assign(new Error('credential audience does not match context'),{code:'authentication_required'});return {client:new TeamsClient({server:context.origin,credential:credential.token,fetch}),context};}
+/** A context name from a team's name: `Volter` → `volter`. */
+export function contextNameOf(team){const name=String(team).toLowerCase().replace(/[^a-z0-9_-]+/g,'-').replace(/^[^a-z]+/,'').slice(0,64);return name||'team';}
+export async function loginContext({supercodeHome,name,origin,teamId,token,invite,identityToken=null,as,fetch}){if(token!=null&&(invite!=null||identityToken!=null))throw new Error('a token signs in alone');if(token==null&&invite==null&&identityToken==null)throw new Error('a token, an invitation or an identity is required');origin=normalizeOrigin(origin);let credential,serverId,principalId,resolvedTeam=teamId;if(invite){const response=await fetch(new URL('/api/v1/invitations/accept',origin),{method:'POST',redirect:'manual',headers:{'Content-Type':'application/json'},body:JSON.stringify({enrollment_code:invite,...(identityToken?{access_token:identityToken}:{})})});if(response.type==='opaqueredirect'||(response.status>=300&&response.status<400))throw new Error('cross-origin redirects are refused');if(!response.ok)throw new Error(`invitation failed: HTTP ${response.status}`);const value=await response.json();credential=value.credential;principalId=value.principal.id;resolvedTeam=value.team.id;token=credential.token;}else if(identityToken){const response=await fetch(new URL('/api/v1/login/volter',origin),{method:'POST',redirect:'manual',headers:{'Content-Type':'application/json'},body:JSON.stringify({access_token:identityToken,...(teamId?{team_id:teamId}:{})})});if(response.type==='opaqueredirect'||(response.status>=300&&response.status<400))throw new Error('cross-origin redirects are refused');if(!response.ok){const detail=await response.json().catch(()=>null);throw new Error(`sign-in failed: ${detail?.error?.message??`HTTP ${response.status}`}`);}const value=await response.json();credential=value.credential;principalId=value.principal.id;resolvedTeam=value.team.id;token=credential.token;}const client=new TeamsClient({server:origin,credential:token,fetch});const me=await client.me();serverId=me.server_id;const membership=me.teams.find(x=>x.team.id===resolvedTeam||x.team.name===resolvedTeam);if(!membership)throw new Error('credential is not a member of the requested team');name??=contextNameOf(membership.team.name);principalId??=me.principal.id;const store=new WorkspaceContexts(supercodeHome);const credentialId=`cred_${crypto.randomUUID().replaceAll('-','')}`;store.writeCredential(credentialId,{token,kind:credential?.kind??'user',expires_at:credential?.expires_at??null,server_id:serverId,origin});const saved=store.upsert(name,{origin,server_id:serverId,team_id:membership.team.id,team_name:membership.team.name,principal_id:principalId,credential_ref:credentialId,label:as??null});if(!store.read().current)store.use(name);return saved;}

package/event-client.mjs

@@ -0,0 +1,8 @@
+// Public custody door: consumers follow HTTP events without resolving the Teams binary or reading its files.
+import { dirname } from 'node:path';
+import { teamsHome } from './home.mjs';
+import { fromContext } from './context.mjs';
+export function eventClient({supercodeHome=dirname(teamsHome()),context: name,fetch}={}) {
+  const {client,context}=fromContext({supercodeHome,name,fetch});
+  return {team:client.team(context.team_id),context:{name,org:context.team_id,principal:context.principal_id,server:context.origin}};
+}

package/http-client.d.ts

@@ -0,0 +1,149 @@
+/** Neutral HTTP transport. Product extensions keep their payloads in their own contracts. */
+export interface RequestOptions { signal?: AbortSignal; idempotencyKey?: string; ifMatch?: number }
+export interface StreamOptions extends RequestOptions { after?: string }
+export type Query = Record<string, unknown>;
+export interface Result<T = unknown> { version: number; data: T; [key: string]: unknown }
+export interface Page<T = unknown> { version: number; items: T[]; [key: string]: unknown }
+export interface OntologyEvent {
+  id: string | null; org: string; at: number | null; kind: string;
+  actor: { principal: string | null; session: string | null; lineage: string[] } | null;
+  resource: { kind: string; id: string }; data: Record<string, unknown>;
+}
+export interface PublishedEventFrame {
+  type: 'snapshot_begin' | 'snapshot_item' | 'snapshot_end' | 'event' | 'checkpoint' | 'access_revoked' | 'resync_required';
+  cursor?: string; sequence?: number; data?: OntologyEvent; terminal?: boolean; reason?: string;
+}
+export interface ReadCollection {
+  list(query?: Query, options?: RequestOptions): Promise<Page>;
+  get(id: string, options?: RequestOptions): Promise<Result>;
+}
+export interface MutableCollection extends ReadCollection {
+  create(body: unknown, options?: RequestOptions): Promise<Result>;
+  update(id: string, body: unknown, options?: RequestOptions): Promise<Result>;
+  remove(id: string, options?: RequestOptions): Promise<null>;
+}
+export interface AgentRecord {
+  id: string; kind: 'agent'; org: string; name: string; path: string; parent: string | null;
+  lineage: Record<string, unknown>; sponsor: string | null; explicit_sponsor: string | null;
+  profile: string; state: 'active' | 'suspended' | 'ended'; suspension_reason: string | null;
+  main_session: string | null; created_at: number; ended_at: number | null; end_reason: string | null; revision: number;
+}
+export interface SessionIdentity {
+  session: string; agent: AgentRecord | null; starter: Record<string, unknown> | null;
+  resolved: Record<string, unknown> | null; resolved_at?: number | null; main: boolean;
+  ended_at?: number | null; end_reason?: string | null; revision?: number; state?: 'unrecorded';
+}
+export interface SessionClient {
+  identity(options?: RequestOptions): Promise<Result<SessionIdentity>>;
+  recordLineage(body: {starter_session?: string}, options?: RequestOptions): Promise<Result<SessionIdentity>>;
+  mail(body: {text: string}, options?: RequestOptions): Promise<Result<{delivered: true}>>;
+  descriptor(options?: RequestOptions): Promise<Result>;
+  read(query?: Query, options?: RequestOptions): Promise<unknown>;
+  follow(query?: Query, options?: StreamOptions): AsyncIterable<unknown>;
+  access(options?: RequestOptions): Promise<Result>;
+  grant(body: unknown, options?: RequestOptions): Promise<Result>;
+  revoke(id: string, options?: RequestOptions): Promise<Result>;
+  export(body: unknown, options?: RequestOptions): Promise<Result>;
+  prepare(body: unknown, options?: RequestOptions): Promise<Result>;
+  attach(body: unknown, options?: RequestOptions): Promise<Result>;
+  artifact(id: string, options?: {signal?: AbortSignal; range?: string}): Promise<Response>;
+}
+export interface TeamClient {
+  identity: import('./identity-record.js').IdentityRecordClient;
+  /** One role-and-binding shape (C5): roles bundle actions; a binding grants one on a resource; one evaluator decides. */
+  permissions: {
+    roles(options?: RequestOptions): Promise<Result>;
+    defineRole(body: {name: string; actions: string[]}, options?: RequestOptions): Promise<Result>;
+    bindings(query: {resource_kind: string; resource_id: string}, options?: RequestOptions): Promise<Result>;
+    bind(body: {holder: {kind: 'principal' | 'group'; id: string}; role?: string; actions?: string[]; resource: {kind: string; id: string}; expires_at?: number; conditions?: Record<string, unknown>}, options?: RequestOptions): Promise<Result>;
+    revoke(id: string, options?: RequestOptions): Promise<Result>;
+    decide(body: {principal?: string; action: string; resource: {kind: string; id: string}}, options?: RequestOptions): Promise<Result>;
+  };
+  /** An automation's sponsor: a person an Org admin names; agents the automation starts inherit it. */
+  principals: {
+    sponsor(id: string, options?: RequestOptions): Promise<Result>;
+    setSponsor(id: string, sponsor: string, options?: RequestOptions): Promise<Result>;
+    clearSponsor(id: string, options?: RequestOptions): Promise<Result>;
+  };
+  agents: {
+    root(options?: RequestOptions): Promise<Result<AgentRecord>>;
+    list(query?: Query, options?: RequestOptions): Promise<Page<AgentRecord>>;
+    get(id: string, options?: RequestOptions): Promise<Result<AgentRecord>>;
+    management(id: string, options?: RequestOptions): Promise<Result<{id: string; revision: number; profile: string; manageable: true}>>;
+    declare(body: {id?: string; name: string; parent?: string | null; sponsor?: string | null; profile: string; root?: boolean; starter_session?: string}, options?: RequestOptions): Promise<Result<AgentRecord>>;
+    update(id: string, body: {name?: string; parent?: string | null; sponsor?: string | null; profile?: string; state?: 'active' | 'suspended'}, options?: RequestOptions): Promise<Result<AgentRecord>>;
+    delegateReader(id: string, body?: {expires_in_ms?: number}, options?: RequestOptions): Promise<Result<{id: string; token: string; principal_id: string; kind: 'service'; expires_at: number; actions: string[]}>>;
+    end(id: string, body: {reason: string}, options?: RequestOptions): Promise<Result<{id: string; state: 'ended'; ended: string[]}>>;
+    closures(id: string, options?: RequestOptions): Promise<Result<{items: Array<{id: string; session_id: string; machine_id: string; harness: string; native_id: string; state: 'pending'|'claimed'|'closed'|'failed'|'unknown'; reason: string; result: {state: string; reason: string}|null}>}>>;
+    sessions(id: string, query?: Query, options?: RequestOptions): Promise<Page<SessionIdentity>>;
+    ownSession(id: string, body: {session: string; main?: boolean; starter_session?: string}, options?: RequestOptions): Promise<Result<SessionIdentity>>;
+  };
+  id: string;
+  events: {
+    catalogue(options?: RequestOptions): Promise<Result<{kinds: string[]}>>;
+    createSource(body: {name: string}, options?: RequestOptions): Promise<Result<{id: string; name: string}>>;
+    publish(source: string, body: unknown, options?: RequestOptions): Promise<Result<OntologyEvent>>;
+    follow(query?: Query, options?: StreamOptions): AsyncIterable<PublishedEventFrame>;
+  };
+  sessions: {
+    list(query?: Query, options?: RequestOptions): Promise<Page>;
+    search(query: Query, options?: RequestOptions): Promise<unknown>;
+    watch(query?: Query, options?: StreamOptions): AsyncIterable<unknown>;
+    get(id: string): SessionClient;
+  };
+  members: Pick<MutableCollection, 'list' | 'update' | 'remove'>;
+  groups: Pick<MutableCollection, 'list' | 'create' | 'remove'> & {
+    addMember(id: string, member: string, options?: RequestOptions): Promise<null>;
+    removeMember(id: string, member: string, options?: RequestOptions): Promise<null>;
+  };
+  machines: Pick<MutableCollection, 'list' | 'get' | 'create' | 'remove'> & {
+    reportSessionProfile(id: string, body: {session: string; profile: Record<string, unknown>}, options?: RequestOptions): Promise<Result>;
+    roots(id: string, query?: Query, options?: RequestOptions): Promise<Page>;
+    liveGrants(id: string): {
+      list(options?: RequestOptions): Promise<Page>; get(id: string, options?: RequestOptions): Promise<Result>;
+      create(body: unknown, options?: RequestOptions): Promise<Result>; remove(id: string, options?: RequestOptions): Promise<null>;
+    };
+  };
+  apps: {
+    catalogue(options?: RequestOptions): Promise<Result>;
+    list(options?: RequestOptions): Promise<Page>; get(id: string, options?: RequestOptions): Promise<Result>;
+    register(body: unknown, options?: RequestOptions): Promise<Result>;
+    deregister(id: string, options?: RequestOptions): Promise<null>;
+    rotateSecret(id: string, options?: RequestOptions): Promise<Result>;
+    install(id: string, body: unknown, options?: RequestOptions): Promise<Result>;
+  };
+  appInstallations: {
+    list(options?: RequestOptions): Promise<Page>; get(id: string, options?: RequestOptions): Promise<Result>;
+    uninstall(id: string, options?: RequestOptions): Promise<null>;
+    delegate(id: string, body: unknown, options?: RequestOptions): Promise<Result>;
+  };
+  sources: Pick<MutableCollection, 'list' | 'get' | 'create' | 'update'> & {
+    credential(id: string, body: unknown, options?: RequestOptions): Promise<Result>;
+    configuration(id: string, format?: string, options?: RequestOptions): Promise<Result>;
+  };
+  syncRules: MutableCollection;
+  credentials: Pick<MutableCollection, 'create' | 'remove'>;
+  invitations: Pick<MutableCollection, 'create'>;
+  operations: Pick<ReadCollection, 'get'>;
+  continuations: Pick<ReadCollection, 'get'> & {
+    authorizeDestination(id: string, body: unknown, options?: RequestOptions): Promise<Result>;
+    launch(id: string, options?: RequestOptions): Promise<Result>;
+    completeLocal(id: string, body: unknown, options?: RequestOptions): Promise<Result>;
+  };
+  attachments: {
+    actions(id: string, body: unknown, options?: RequestOptions): Promise<Result>;
+    detach(id: string, options?: RequestOptions): Promise<null>;
+    stream(attachment: unknown, options?: RequestOptions): AsyncIterable<unknown>;
+  };
+}
+export declare class TeamsClient {
+  constructor(options: {server: string; credential: string; fetch?: typeof fetch});
+  server: string;
+  request<T = unknown>(method: string, path: string, options?: RequestOptions & {body?: unknown}): Promise<T>;
+  me(options?: RequestOptions): Promise<unknown>;
+  capabilities(options?: RequestOptions): Promise<{version: 1; server_id: string; protocol: 'teams.v1'; operations: string[]; auth_modes: string[]}>;
+  teams(query?: Query, options?: RequestOptions): Promise<Page>;
+  createTeam(body: {name: string}, options?: RequestOptions): Promise<Result>;
+  redeemAppCode(body: unknown, options?: RequestOptions): Promise<unknown>;
+  team(id: string): TeamClient;
+}

package/http-client.mjs

@@ -0,0 +1,232 @@
+const trimOrigin=value=>{const u=new URL(value),loopback=u.hostname==='localhost'||u.hostname==='::1'||u.hostname==='[::1]'||/^127(?:\.\d{1,3}){3}$/.test(u.hostname);if(!['http:','https:'].includes(u.protocol)||u.username||u.password||u.search||u.hash||(u.pathname!==''&&u.pathname!=='/')||(u.protocol==='http:'&&!loopback))throw new TypeError('server must be an HTTPS origin (HTTP is loopback-only)');return u.origin;};
+const randomKey=()=>globalThis.crypto.randomUUID().replaceAll('-','')+globalThis.crypto.randomUUID().replaceAll('-','');
+export class TeamsClient {
+  constructor({server,credential,fetch:fetchImpl=(...args)=>globalThis.fetch(...args)}){this.server=trimOrigin(server);this.credential=credential;this.fetch=fetchImpl;if(typeof fetchImpl!=='function')throw new TypeError('fetch is required');}
+  async request(method,path,{body,signal,idempotencyKey,ifMatch}={}) {
+    const key=idempotencyKey??(method==='GET'?null:randomKey());let delay=250,last;
+    for(let attempt=0;attempt<5;attempt++) { try {
+      const response=await this.fetch(this.server+path,{method,signal,redirect:'manual',headers:{Accept:'application/json',Authorization:`Bearer ${this.credential}`,...(body!==undefined?{'Content-Type':'application/json'}:{}),...(key?{'Idempotency-Key':key}:{}),...(ifMatch!==undefined?{'If-Match':String(ifMatch)}:{})},body:body===undefined?undefined:JSON.stringify(body)});
+      if(response.type==='opaqueredirect'||(response.status>=300&&response.status<400))throw Object.assign(new Error('cross-origin redirects are refused'),{code:'invalid_request',status:400,retryable:false});
+      const value=response.status===204?null:await response.json();if(!response.ok)throw Object.assign(new Error(value?.error?.message??`HTTP ${response.status}`),value?.error,{status:response.status});return value;
+    } catch(error) { last=error;if(method!=='GET'||signal?.aborted||!(!error.status||error.retryable)||attempt===4)throw error;await retryWait(delay,signal);delay=Math.min(delay*2,5000); } }
+    throw last;
+  }
+  me(options){return this.request('GET','/api/v1/me',options);} capabilities(options){return this.request('GET','/api/v1/capabilities',options);} team(id){return new TeamClient(this,id);}
+  redeemAppCode(body,options){return this.request('POST','/api/v1/apps/token',{...options,body});}
+  teams(queryValue={},options){return this.request('GET','/api/v1/teams'+query(queryValue),options);}
+  createTeam(body,options){return this.request('POST','/api/v1/teams',{...options,body});}
+}
+const segment = value => {
+  if (typeof value !== 'string' || !value || value.length > 256) throw new TypeError('a nonempty resource ID is required');
+  return encodeURIComponent(value);
+};
+class TeamClient {
+  constructor(root, id) {
+    this.root = root; this.id = id;
+    const base = `/api/v1/teams/${segment(id)}`;
+    const get = (path, options) => root.request('GET', base + path, options);
+    const post = (path, body, options) => root.request('POST', base + path, { ...options, body });
+    const patch = (path, body, options) => root.request('PATCH', base + path, { ...options, body });
+    const remove = (path, options) => root.request('DELETE', base + path, options);
+    const resource = (path, id) => `${path}/${segment(id)}`;
+    this.agents = {
+      root: o => get('/agents/root',o),
+      list: (q={},o) => get('/agents'+query(q),o),
+      get: (id,o) => get(resource('/agents',id),o),
+      management: (id,o) => get(resource('/agents',id)+'/management',o),
+      declare: (body,o) => post('/agents',body,o),
+      update: (id,body,o) => patch(resource('/agents',id),body,o),
+      sessions: (id,q={},o) => get(resource('/agents',id)+'/sessions'+query(q),o),
+      ownSession: (id,body,o) => post(resource('/agents',id)+'/sessions',body,o),
+      delegateReader: (id,body={},o) => post(resource('/agents',id)+'/credentials',body,o),
+      end: (id,body,o) => post(resource('/agents',id)+'/end',body,o),
+      closures: (id,o) => get(resource('/agents',id)+'/closures',o),
+    };
+    this.permissions = {
+      roles: o => get('/permissions/roles',o),
+      defineRole: (body,o) => post('/permissions/roles',body,o),
+      bindings: (q,o) => get('/permissions/bindings'+query(q),o),
+      bind: (body,o) => post('/permissions/bindings',body,o),
+      revoke: (id,o) => remove(resource('/permissions/bindings',id),o),
+      decide: (body,o) => post('/permissions/decide',body,o),
+    };
+    this.principals = {
+      sponsor: (id,o) => get(resource('/principals',id)+'/sponsor',o),
+      setSponsor: (id,sponsor,o) => root.request('PUT', base + resource('/principals',id)+'/sponsor', { ...o, body:{sponsor} }),
+      clearSponsor: (id,o) => remove(resource('/principals',id)+'/sponsor',o),
+    };
+    this.identity = {
+      observations: (q = {},o) => get('/identity/observations'+query(q),o),
+      sightings: (q,o) => get('/identity/sightings'+query(q),o),
+      observe: (body,o) => post('/identity/observations',body,o),
+      resolve: (observation,o) => get('/identity/resolve'+query({observation}),o),
+      declarePerson: (body,o) => post('/identity/principals',body,o),
+      infer: (body,o) => post('/identity/inferences',{...body,classification:'inferred'},o),
+      revokeInference: (id,o) => remove(resource('/identity/inferences',id),o),
+      link: (body,o) => post('/identity/links',body,o),
+      revoke: (id,o) => remove(resource('/identity/links',id),o),
+    };
+    this.events = {
+      catalogue: o => get('/events/catalogue',o),
+      follow: (q = {},o = {}) => events(root,base+'/events'+query(q),o),
+      createSource: (body,o) => post('/event-sources',body,o),
+      publish: (source,body,o) => post(resource('/event-sources',source)+'/events',body,o),
+    };
+    this.apps = {
+      catalogue: o => get('/apps/catalogue', o),
+      list: o => get('/apps', o), get: (id, o) => get(resource('/apps', id), o),
+      register: (body, o) => post('/apps', body, o),
+      deregister: (id, o) => remove(resource('/apps', id), o),
+      rotateSecret: (id, o) => post(resource('/apps', id) + '/secret', {}, o),
+      install: (id, body, o) => post(resource('/apps', id) + '/installations', body, o),
+    };
+    this.appInstallations = {
+      list: o => get('/app-installations', o), get: (id, o) => get(resource('/app-installations', id), o),
+      uninstall: (id, o) => remove(resource('/app-installations', id), o),
+      delegate: (id, body, o) => post(resource('/app-installations', id) + '/delegations', body, o),
+    };
+    this.sessions = {
+      list: (q = {}, o) => get('/sessions' + query(q), o),
+      search: (q, o) => get('/sessions/search' + query(q), o),
+      watch: (q = {}, o = {}) => events(root, base + '/sessions/events' + query(q), o),
+      get: id => new SessionClient(root, base, id),
+    };
+    this.members = {
+      list: (q = {}, o) => get('/members' + query(q), o),
+      update: (id, body, o) => patch(resource('/members', id), body, o),
+      remove: (id, o) => remove(resource('/members', id), o),
+    };
+    this.groups = {
+      list: (q = {}, o) => get('/groups' + query(q), o),
+      create: (body, o) => post('/groups', body, o),
+      remove: (id, o) => remove(resource('/groups', id), o),
+      addMember: (id, member, o) => root.request('PUT', base + resource('/groups', id) + resource('/members', member), o),
+      removeMember: (id, member, o) => remove(resource('/groups', id) + resource('/members', member), o),
+    };
+    this.machines = {
+      reportSessionProfile: (id,body,o) => post(resource('/machines',id)+'/session-profiles',body,o),
+      list: (q = {}, o) => get('/machines' + query(q), o),
+      get: (id, o) => get(resource('/machines', id), o),
+      create: (body, o) => post('/machines', body, o),
+      roots: (id, q = {}, o) => get(resource('/machines', id) + '/roots' + query(q), o),
+      remove: (id, o) => remove(resource('/machines', id), o),
+      liveGrants: machineId => {
+        const path = resource('/machines', machineId) + '/grants';
+        return {
+          list: (o) => get(path, o), get: (id, o) => get(resource(path, id), o),
+          create: (body, o) => post(path, body, o), remove: (id, o) => remove(resource(path, id), o),
+        };
+      },
+    };
+    this.sources = {
+      list: (q = {}, o) => get('/sources' + query(q), o),
+      get: (id, o) => get(resource('/sources', id), o),
+      create: (body, o) => post('/sources', body, o),
+      update: (id, body, o) => patch(resource('/sources', id), body, o),
+      credential: (id, body, o) => post(resource('/sources', id) + '/credentials', body, o),
+      configuration: (id, format = 'otel-collector', o) => get(resource('/sources', id) + '/config' + query({ format }), o),
+    };
+    this.syncRules = {
+      list: (q = {}, o) => get('/sync-rules' + query(q), o), get: (id, o) => get(resource('/sync-rules', id), o),
+      create: (body, o) => post('/sync-rules', body, o), update: (id, body, o) => patch(resource('/sync-rules', id), body, o),
+      remove: (id, o) => remove(resource('/sync-rules', id), o),
+    };
+    this.credentials = {
+      create: (body, o) => post('/credentials', body, o), remove: (id, o) => remove(resource('/credentials', id), o),
+    };
+    this.invitations = { create: (body, o) => post('/invitations', body, o) };
+    this.operations = { get: (id, o) => get(resource('/operations', id), o) };
+    this.continuations = {
+      get: (id, o) => get(resource('/continuations', id), o),
+      authorizeDestination: (id, body, o) => post(resource('/continuations', id) + '/authorize-destination', body, o),
+      launch: (id, o) => post(resource('/continuations', id) + '/launch', undefined, o),
+      completeLocal: (id, body, o) => post(resource('/continuations', id) + '/complete-local', body, o),
+    };
+    this.attachments = {
+      actions: (id, body, o) => post(resource('/attachments', id) + '/actions', body, o),
+      detach: (id, o) => remove(resource('/attachments', id), o),
+      stream: (attachment, o = {}) => attachmentEvents(root, base, attachment, o),
+    };
+  }
+}
+class SessionClient {
+  constructor(root, base, id) { this.root = root; this.path = `${base}/sessions/${segment(id)}`; }
+  identity = o => this.root.request('GET',this.path+'/agent',o);
+  recordLineage = (body,o) => this.root.request('POST',this.path+'/agent',{...o,body});
+  mail = (body,o) => this.root.request('POST',this.path+'/mail',{...o,body});
+  descriptor = o => this.root.request('GET', this.path, o);
+  read = (q = {}, o) => this.root.request('GET', this.path + '/messages' + query(q), o);
+  follow = (q = {}, o = {}) => events(this.root, this.path + '/events' + query(q), o);
+  access = o => this.root.request('GET', this.path + '/access', o);
+  grant = (body, o) => this.root.request('POST', this.path + '/access', { ...o, body });
+  revoke = (id, o) => this.root.request('DELETE', this.path + '/access/' + segment(id), o);
+  export = (body, o) => this.root.request('POST', this.path + '/exports', { ...o, body });
+  prepare = (body, o) => this.root.request('POST', this.path + '/continuations', { ...o, body });
+  attach = (body, o) => this.root.request('POST', this.path + '/attachments', { ...o, body });
+  artifact = async (id, { signal, range } = {}) => {
+    if (range !== undefined && !/^bytes=(?:[0-9]+-[0-9]*|-[0-9]+)$/.test(range)) throw new TypeError('range must be one byte range');
+    const response = await this.root.fetch(this.root.server + this.path + '/artifacts/' + segment(id), {
+      signal, redirect: 'manual', headers: { Authorization: `Bearer ${this.root.credential}`, ...(range ? { Range: range } : {}) },
+    });
+    rejectRedirect(response);
+    if (!response.ok) throw await sseError(response);
+    return response;
+  };
+}
+function rejectRedirect(response) {
+  if (response.type === 'opaqueredirect' || response.status >= 300 && response.status < 400) throw Object.assign(new Error('cross-origin redirects are refused'), { code: 'invalid_request', status: 400, retryable: false });
+}
+async function* attachmentEvents(root, base, attachment, { signal } = {}) {
+  const expected = root.server + base + '/attachments/' + segment(attachment.id) + '/stream';
+  if (attachment.stream_format !== 'observed_runtime_event' || attachment.stream_url !== expected || typeof attachment.credential !== 'string' || !attachment.credential) throw new TypeError('attachment stream target or credential is invalid');
+  let response;
+  try {
+    response = await root.fetch(expected, { signal, redirect: 'manual', headers: { Accept: 'text/event-stream', Authorization: `Bearer ${attachment.credential}` } });
+    rejectRedirect(response);
+    if (!response.ok) throw await sseError(response);
+    let buffer = '';
+    for await (const chunk of response.body.pipeThrough(new TextDecoderStream())) {
+      buffer += chunk;
+      let match;
+      while ((match = /\r?\n\r?\n/.exec(buffer))) {
+        const block = buffer.slice(0, match.index); buffer = buffer.slice(match.index + match[0].length);
+        if (new TextEncoder().encode(block).length > 1024 * 1024 + 4096) throw Object.assign(new Error('attachment frame exceeds 1 MiB'), { code: 'resync_required', retryable: false });
+        const lines = block.split(/\r?\n/), kind = lines.find(line => line.startsWith('event:'))?.slice(6).trim();
+        const data = lines.filter(line => line.startsWith('data:')).map(line => line.slice(5).replace(/^ /, '')).join('\n');
+        if (!data) continue;
+        if (kind === 'access_revoked' || kind === 'resync_required') throw Object.assign(new Error(`attachment stream ${kind}`), { code: kind, retryable: false });
+        if (kind !== 'runtime') throw Object.assign(new Error('unexpected attachment stream event'), { code: 'invalid_request', retryable: false });
+        const frame = JSON.parse(data);
+        yield frame;
+        if (frame.type === 'closed' || frame.type === 'error' && frame.terminal) return;
+      }
+      if (new TextEncoder().encode(buffer).length > 1024 * 1024 + 4096) throw Object.assign(new Error('attachment frame exceeds 1 MiB'), { code: 'resync_required', retryable: false });
+    }
+    if (!signal?.aborted) throw Object.assign(new Error('attachment stream ended; create a new attachment to reconnect'), { code: 'resync_required', retryable: false });
+  } catch (error) { if (!signal?.aborted) throw error; }
+}
+const query=q=>{const p=new URLSearchParams();for(const [k,v]of Object.entries(q))if(v!==undefined)p.set(k,String(v));return p.size?'?'+p:'';};
+const retryWait=(delay,signal)=>new Promise((resolve,reject)=>{const done=()=>{signal?.removeEventListener('abort',abort);resolve();},timer=setTimeout(done,delay),abort=()=>{clearTimeout(timer);signal?.removeEventListener('abort',abort);reject(signal.reason);};signal?.addEventListener('abort',abort,{once:true});});
+async function sseError(response){let value=null;try{value=await response.json();}catch{}return Object.assign(new Error(value?.error?.message??`SSE HTTP ${response.status}`),value?.error,{status:response.status,retryable:value?.error?.retryable??(response.status===429||response.status>=500)});}
+async function* events(root,path,{signal,after}={}){
+  let cursor=after??null,lastYielded=null,lastError=null;
+  for(let attempt=0;attempt<5&&!signal?.aborted;attempt++){
+    const suffix=cursor?path+(path.includes('?')?'&':'?')+'after='+encodeURIComponent(cursor):path;
+    try{
+      const response=await root.fetch(root.server+suffix,{signal,redirect:'manual',headers:{Accept:'text/event-stream',Authorization:`Bearer ${root.credential}`,...(cursor?{'Last-Event-ID':cursor}:{})}});
+      if(response.type==='opaqueredirect'||response.status>=300&&response.status<400)throw Object.assign(new Error('cross-origin redirects are refused'),{code:'invalid_request',status:400,retryable:false});
+      if(!response.ok)throw await sseError(response);
+      let buffer='';
+      for await(const chunk of response.body.pipeThrough(new TextDecoderStream())){
+        buffer+=chunk;let at;
+        while((at=buffer.indexOf('\n\n'))>=0){
+          const block=buffer.slice(0,at);buffer=buffer.slice(at+2);const id=block.split('\n').find(line=>line.startsWith('id: '))?.slice(4),data=block.split('\n').filter(line=>line.startsWith('data: ')).map(line=>line.slice(6)).join('\n');if(!data)continue;
+          const event=JSON.parse(data),terminal=event?.terminal||event?.type==='access_revoked'||event?.type==='resync_required',nextCursor=id??cursor;cursor=nextCursor;if(!terminal&&nextCursor&&nextCursor===lastYielded)continue;if(nextCursor)lastYielded=nextCursor;yield event;if(terminal)return;
+        }
+      }
+      lastError=Object.assign(new Error('SSE stream ended before a terminal event'),{retryable:true});
+    }catch(error){if(signal?.aborted)return;if(error.retryable===false||error.status&&error.status!==429&&error.status<500)throw error;lastError=error;}
+    if(attempt<4)await retryWait(Math.min(250*2**attempt,5000),signal).catch(()=>{});
+  }
+  if(!signal?.aborted&&lastError)throw lastError;
+}

package/identity-record.d.ts

@@ -0,0 +1,21 @@
+import type {RequestOptions, Result, Page} from './http-client.js';
+export interface IdentityLink {
+  id:string; observation:string; principal_id:string; classification:'proven'|'inferred'; label:'proven'|'probably';
+  proof:{kind:'pairing'|'integration'|'custodian'|'identity_subject'|'inference'; evidence:Record<string,unknown>};
+  created_by:string; created_at:number; revision:number; revoked_at:number|null; revoked_by:string|null;
+}
+export interface IdentityResolution {
+  observation:string; first_seen:number|null; last_seen:number|null;
+  principal:{id:string;name:string;kind:string}|null; classification:'proven'|'inferred'|'unresolved'; label:string; links:IdentityLink[];
+}
+export interface IdentityRecordClient {
+  observations(query?:{limit?:number;after?:string},options?:RequestOptions):Promise<Page>;
+  sightings(query:{observation:string;limit?:number;after?:string},options?:RequestOptions):Promise<Page>;
+  observe(body:{observation:string;location:string;at:number;name?:string|null;evidence:Record<string,unknown>},options?:RequestOptions):Promise<Result<{id:string;observation:string}>>;
+  resolve(observation:string,options?:RequestOptions):Promise<Result<IdentityResolution>>;
+  declarePerson(body:{name:string},options?:RequestOptions):Promise<Result<{id:string;kind:'user';display_name:string}>>;
+  link(body:{observation:string;principal_id:string;classification:'proven'|'inferred';proof:IdentityLink['proof']},options?:RequestOptions):Promise<Result<IdentityLink>>;
+  infer(body:{observation:string;principal_id:string;proof:{kind:'inference';evidence:Record<string,unknown>}},options?:RequestOptions):Promise<Result<IdentityLink>>;
+  revoke(id:string,options:RequestOptions & {ifMatch:number}):Promise<null>;
+  revokeInference(id:string,options:RequestOptions & {ifMatch:number}):Promise<null>;
+}

package/lines.mjs

@@ -0,0 +1,19 @@
+/** Splits a stream's chunks into its complete lines, in time linear in its length: each chunk is scanned once and a
+ *  line joined once, when its newline arrives. Appending to one buffer and searching it from the start again on
+ *  every chunk is quadratic in a long line, and one answer (a large session's `sessions.load`, a whole machine's
+ *  `sessions.discover`) is a line of tens of megabytes. */
+export function lineSplitter() {
+  let pending = [];
+  return (chunk) => {
+    const text = String(chunk), lines = [];
+    let from = 0, at;
+    while ((at = text.indexOf('\n', from)) >= 0) {
+      pending.push(text.slice(from, at));
+      lines.push(pending.join(''));
+      pending = [];
+      from = at + 1;
+    }
+    if (from < text.length) pending.push(text.slice(from));
+    return lines;
+  };
+}

package/machine-door.mjs

@@ -0,0 +1,36 @@
+// Which door a machine verb goes through: without a machine name, this OS
+// user's own daemon over its local socket; with one, the Teams server of the
+// selected context, which forwards the channel to that enrolled machine.
+import { resolve } from 'node:path';
+import { openLocalMachine, openRemoteMachine } from './client.mjs';
+import { WorkspaceContexts, fromContext } from './context.mjs';
+import { teamsHome, paths } from './home.mjs';
+
+export async function openMachine({ machine = null, context = null, env = process.env, home = teamsHome(env) } = {}) {
+  if (!machine) return openLocalMachine(paths(home).socket);
+  const supercodeHome = env.SUPERCODE_HOME ?? resolve(home, '..');
+  const contexts = new WorkspaceContexts(supercodeHome);
+  const name = context ?? env.SUPERCODE_CONTEXT ?? contexts.read().current;
+  if (!name || name === 'local') throw Object.assign(new Error('a remote machine is reached through a Teams context: `supercode teams login …`, then `supercode context use NAME` or --context NAME'), { code: 'invalid_request' });
+  const { client, context: selected } = fromContext({ supercodeHome, name, fetch: globalThis.fetch });
+  const credential = contexts.credential(selected.credential_ref);
+  let machineId = machine;
+  if (!machine.startsWith('mach_')) {
+    const listed = (await client.team(selected.team_id).machines.list()).items;
+    let matches = listed.filter((item) => item.name === machine);
+    // A mail address names a machine by its short, lowercased host name
+    // (`yuerans-macbook-pro`), while enrollment defaults to the full one
+    // (`Yuerans-MacBook-Pro.local`): fall back to that normal form.
+    if (!matches.length) matches = listed.filter((item) => normalMachineName(item.name) === normalMachineName(machine));
+    if (matches.length !== 1) throw Object.assign(new Error(matches.length ? `machine name ${machine} is ambiguous; use its id` : `machine ${machine} is not accessible`), { code: matches.length ? 'ambiguous_reference' : 'not_found' });
+    machineId = matches[0].id;
+  }
+  const channel = await openRemoteMachine({ origin: selected.origin, teamId: selected.team_id, machineId, token: credential.token });
+  channel.machineName = machine;
+  return channel;
+}
+
+/** A machine name in the form mail addresses use: the short host name, lowercased, with anything outside [a-z0-9_-] as `-`. */
+export function normalMachineName(name) {
+  return String(name).split('.')[0].toLowerCase().replace(/[^a-z0-9_-]/g, '-');
+}