@volter/supercode-teams 0.2.20

package/server/store-core.mjs

@@ -0,0 +1,139 @@
+// The Teams store's operations, independent of where SQLite runs. A host supplies
+// four primitives over its own SQLite: `all`, `get` (first row or null), `run`
+// (returns { changes }) and `tx` (runs a function atomically). The Node host
+// runs these in a worker thread over node:sqlite; the Durable Object host runs
+// them on the object's own SQLite.
+import { ingestOtlpBatch, correlateSessions } from './arc2-transactions.mjs';
+import { claimEffect, getEffect, listEffects, reportEffect } from './effects-transactions.mjs';
+import { MIGRATIONS } from '@volter/teams/server/migrations';
+
+/** Bring a database to the newest schema. `version()`/`setVersion(n)` name where the host records it. */
+export function migrate({ exec, tx, version, setVersion }) {
+  const current = version();
+  if (current > MIGRATIONS.length) throw new Error(`database schema ${current} is newer than supported schema ${MIGRATIONS.length}`);
+  for (let next = current + 1; next <= MIGRATIONS.length; next += 1) {
+    const ddl = MIGRATIONS[next - 1].replace(/^PRAGMA .*;\s*$/gm, '');
+    tx(() => { exec(ddl); setVersion(next); });
+  }
+}
+
+export function createStoreHandlers({ all, get, run, tx }) {
+  const journalValue=(value,revision)=>value==='__JOURNAL_REVISION__'?revision:Array.isArray(value)?value.map(item=>journalValue(item,revision)):value&&typeof value==='object'?Object.fromEntries(Object.entries(value).map(([key,item])=>[key,journalValue(item,revision)])):value;
+  const journalParam=(value,revision)=>value&&typeof value==='object'&&value.$journalRevision===true?revision:value&&typeof value==='object'&&Object.hasOwn(value,'$journalJson')?JSON.stringify({...value.$journalJson,revision}):value&&typeof value==='object'&&Object.hasOwn(value,'$journalJsonValue')?JSON.stringify(journalValue(value.$journalJsonValue,revision)):value;
+  const domainError=(status,code,message)=>{const error=new Error(message);error.status=status;error.code=code;throw error;};
+  const authorizedSession=(args)=>{
+    const {teamId,principalId,credentialId,ref,now}=args;
+    const credential=get("SELECT id FROM credentials WHERE id=? AND principal_id=? AND kind IN ('user','service') AND (team_id IS NULL OR team_id=?) AND revoked_at IS NULL AND (expires_at IS NULL OR expires_at>?)",[credentialId,principalId,teamId,now]);
+    const membership=get('SELECT role FROM memberships WHERE team_id=? AND principal_id=? AND active=1',[teamId,principalId]);
+    if(!credential||!membership)domainError(401,'authentication_required','authentication required');
+    if(typeof ref!=='string'||ref.length<8)domainError(404,'not_found','not found');
+    const groups=all('SELECT group_id FROM group_members WHERE team_id=? AND principal_id=?',[teamId,principalId]).map(row=>row.group_id);
+    const candidates=all('SELECT * FROM sessions WHERE team_id=? AND id LIKE ? AND deleted_at IS NULL',[teamId,`${ref}%`]);
+    const visible=new Map();
+    for(const candidate of candidates){
+      let root=candidate;const seen=new Set();
+      while(root.canonical_id){if(seen.has(root.id))domainError(409,'conflict','correlation cycle');seen.add(root.id);root=get('SELECT * FROM sessions WHERE team_id=? AND id=? AND deleted_at IS NULL',[teamId,root.canonical_id]);if(!root)break;}
+      if(!root)continue;
+      const family=all('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=?) SELECT s.* FROM sessions s JOIN family f ON f.id=s.id WHERE s.team_id=?',[root.id,teamId,teamId]);
+      const readable=family.every(session=>{
+        if(session.deleted_at!=null)return false;
+        if(session.visibility==='team'||session.custodian_id===principalId)return true;
+        const grants=all('SELECT subject_kind,subject_id,expires_at FROM session_grants WHERE team_id=? AND session_id=?',[teamId,session.id]);
+        return grants.some(grant=>(grant.subject_kind==='principal'&&grant.subject_id===principalId||grant.subject_kind==='group'&&groups.includes(grant.subject_id))&&(grant.expires_at==null||grant.expires_at>now));
+      });
+      if(readable)visible.set(root.id,root);
+    }
+    if(visible.size>1)domainError(400,'ambiguous_reference','ambiguous session reference');
+    if(visible.size===0)domainError(404,'not_found','not found');
+    const session=[...visible.values()][0];
+    const version=get('SELECT descriptor_json FROM session_versions WHERE team_id=? AND session_id=? AND revision=?',[teamId,session.id,session.revision]);
+    if(!version)domainError(404,'not_found','not found');
+    const projection=JSON.parse(version.descriptor_json);
+    if(!args.projectionDepth){
+      for(const field of ['parent_id','continued_from'])if(projection[field]){
+        try{authorizedSession({...args,ref:projection[field],projectionDepth:1});}catch{projection[field]=null;}
+      }
+    }
+    return {session:{...session,descriptor_json:JSON.stringify(projection)},membership};
+  };
+  const readSessionSnapshot=args=>tx(()=>{
+    const {teamId,principalId,credentialId,ref,now,beforeHash,requestedRevision,tail,nextCursorHash,nextCursorToken}=args;
+    const {session}=authorizedSession(args);const team=get('SELECT auth_epoch,journal_revision FROM teams WHERE id=?',[teamId]);
+    let revision,ordinals;
+    if(beforeHash){
+      const cursor=get("SELECT * FROM cursors WHERE id=? AND team_id=? AND principal_id=? AND kind='history'",[beforeHash,teamId,principalId]);
+      if(!cursor||cursor.expires_at<=now||cursor.auth_epoch!==team.auth_epoch)domainError(409,'resync_required','history cursor expired or authorization changed');
+      const snapshot=JSON.parse(cursor.snapshot_json);
+      if(snapshot.session_id!==session.id)domainError(409,'resync_required','history cursor belongs to another session');
+      revision=snapshot.revision;ordinals=snapshot.ordinals;
+    }else{
+      revision=requestedRevision??session.revision;
+      if(!get('SELECT 1 ok FROM session_versions WHERE team_id=? AND session_id=? AND revision=?',[teamId,session.id,revision]))domainError(404,'not_found','session revision not found');
+      ordinals=all('SELECT ordinal FROM messages WHERE team_id=? AND session_id=? AND revision=? ORDER BY ordinal',[teamId,session.id,revision]).map(row=>row.ordinal);
+    }
+    const pageOrdinals=ordinals.slice(-tail),remaining=ordinals.slice(0,-tail);
+    const rows=pageOrdinals.length?all(`SELECT * FROM messages WHERE team_id=? AND session_id=? AND revision=? AND ordinal IN (${pageOrdinals.map(()=>'?').join(',')}) ORDER BY ordinal`,[teamId,session.id,revision,...pageOrdinals]):[];
+    const version=get('SELECT descriptor_json FROM session_versions WHERE team_id=? AND session_id=? AND revision=?',[teamId,session.id,revision]);
+    if(!version)domainError(404,'not_found','session revision not found');
+    let descriptorJson=version.descriptor_json;
+    if(revision===session.revision)descriptorJson=session.descriptor_json;
+    else{
+      const historical=JSON.parse(descriptorJson);
+      for(const field of ['parent_id','continued_from'])if(historical[field]){
+        try{authorizedSession({...args,ref:historical[field],projectionDepth:1});}catch{historical[field]=null;}
+      }
+      descriptorJson=JSON.stringify(historical);
+    }
+    let beforeCursor=null;
+    if(remaining.length){beforeCursor=nextCursorToken;run('INSERT INTO cursors(id,team_id,principal_id,kind,query_json,auth_epoch,revision,snapshot_json,expires_at) VALUES (?,?,?,?,?,?,?,?,?)',[nextCursorHash,teamId,principalId,'history',JSON.stringify({tail}),team.auth_epoch,team.journal_revision,JSON.stringify({session_id:session.id,revision,ordinals:remaining}),now+900000]);}
+    return {descriptor_json:descriptorJson,rows,beforeCursor,eventCursor:String(team.journal_revision),revision,total:ordinals.length};
+  });
+  const readArtifact=args=>tx(()=>{
+    const {session}=authorizedSession(args);
+    const upload=get(`SELECT u.manifest_json FROM session_artifacts a JOIN uploads u ON u.team_id=a.team_id AND u.id=a.upload_id
+      WHERE a.team_id=? AND a.session_id=? AND a.upload_id=? AND u.committed=1`,[args.teamId,session.id,args.uploadId]);
+    if(!upload)domainError(404,'not_found','artifact not found');
+    const chunks=all('SELECT bytes FROM artifact_chunks WHERE team_id=? AND upload_id=? ORDER BY chunk_index',[args.teamId,args.uploadId]);
+    return {manifest:JSON.parse(upload.manifest_json),bytes:Buffer.concat(chunks.map(row=>row.bytes))};
+  });
+  return {
+    exec: ({sql,params=[]}) => run(sql,params), query: ({sql,params=[]}) => all(sql,params), one: ({sql,params=[]}) => get(sql,params),
+    transaction: ({statements}) => tx(() => statements.map(s => s.kind === 'query' ? all(s.sql,s.params) : s.kind === 'one' ? get(s.sql,s.params) : run(s.sql,s.params))),
+    snapshot: ({statements}) => tx(() => statements.map(s => s.kind === 'one' ? get(s.sql,s.params) : all(s.sql,s.params))),
+    guardedTransaction: ({guards=[],statements}) => tx(() => { for(const guard of guards){const row=get(guard.sql,guard.params);if(!row){const error=new Error(guard.message??'transaction predicate changed');error.code=guard.code??'conflict';error.status=guard.status??409;throw error;}}return statements.map(s=>s.kind==='query'?all(s.sql,s.params):s.kind==='one'?get(s.sql,s.params):run(s.sql,s.params));}),
+    journalTransaction: ({teamId,guards=[],statements}) => tx(() => { for(const guard of guards){const row=get(guard.sql,guard.params);if(!row){const error=new Error(guard.message??'transaction predicate changed');error.code=guard.code??'conflict';error.status=guard.status??409;throw error;}}const team=get('SELECT journal_revision FROM teams WHERE id=?',[teamId]);if(!team)throw new Error('team not found');const revision=team.journal_revision+1;const results=statements.map(s=>{const params=(s.params??[]).map(value=>journalParam(value,revision));return s.kind==='query'?all(s.sql,params):s.kind==='one'?get(s.sql,params):run(s.sql,params);});return{revision,results};}),
+    ingestOtlpBatch: args => tx(() => ingestOtlpBatch({get,all,run},args)),
+    correlateSessions: args => tx(() => correlateSessions({get,all,run},args)),
+    listEffects: args => tx(() => listEffects({get,all,run},args)),
+    getEffect: args => tx(() => getEffect({get,all,run},args)),
+    claimEffect: args => tx(() => claimEffect({get,all,run},args)),
+    reportEffect: args => tx(() => reportEffect({get,all,run},args)),
+    authorizedSession: args => tx(() => authorizedSession(args).session),
+    readSessionSnapshot,
+    readArtifact,
+  };
+}
+
+/** The store's async surface. `call(op, args)` is the host's way to one handler. */
+export class StoreClient {
+  query(sql,params=[]) { return this.call('query',{sql,params}); } one(sql,params=[]) { return this.call('one',{sql,params}); } exec(sql,params=[]) { return this.call('exec',{sql,params}); } transaction(statements) { return this.call('transaction',{statements}); }
+  snapshot(statements) { return this.call('snapshot',{statements}); }
+  guardedTransaction(guards,statements) { return this.call('guardedTransaction',{guards,statements}); }
+  journalTransaction(teamId,guards,statements) { return this.call('journalTransaction',{teamId,guards,statements}); }
+  ingestOtlpBatch(args) { return this.call('ingestOtlpBatch',args); }
+  correlateSessions(args) { return this.call('correlateSessions',args); }
+  listEffects(args) { return this.call('listEffects',args); }
+  getEffect(args) { return this.call('getEffect',args); }
+  claimEffect(args) { return this.call('claimEffect',args); }
+  reportEffect(args) { return this.call('reportEffect',args); }
+  authorizedSession(args) { return this.call('authorizedSession',args); }
+  readSessionSnapshot(args) { return this.call('readSessionSnapshot',args); }
+  readArtifact(args) { return this.call('readArtifact',args); }
+}
+
+/** A store whose handlers run in this thread (the Durable Object host). */
+export class DirectStore extends StoreClient {
+  constructor(handlers) { super(); this.handlers = handlers; }
+  call(op, args = {}) { try { return Promise.resolve(this.handlers[op](args)); } catch (error) { return Promise.reject(error); } }
+  async close() {}
+}

package/server/store-worker.mjs

@@ -0,0 +1,23 @@
+import { parentPort, workerData, isMainThread, Worker } from 'node:worker_threads';
+import { DatabaseSync } from 'node:sqlite';
+import { createStoreHandlers, migrate, StoreClient } from './store-core.mjs';
+
+// The Node host's store: node:sqlite in a worker thread, so a long statement never
+// blocks the HTTP loop. The operations themselves are store-core's.
+if (!isMainThread) {
+  const db = new DatabaseSync(workerData.dbPath, { open: true, enableForeignKeyConstraints: true, allowExtension: false });
+  db.exec('PRAGMA foreign_keys=ON; PRAGMA journal_mode=WAL; PRAGMA synchronous=FULL; PRAGMA busy_timeout=5000');
+  const all = (sql, p=[]) => db.prepare(sql).all(...p);
+  const get = (sql, p=[]) => db.prepare(sql).get(...p) ?? null;
+  const run = (sql, p=[]) => db.prepare(sql).run(...p);
+  const tx = fn => { db.exec('BEGIN IMMEDIATE'); try { const out=fn(); db.exec('COMMIT'); return out; } catch(e) { db.exec('ROLLBACK'); throw e; } };
+  migrate({ exec: (sql) => db.exec(sql), tx, version: () => db.prepare('PRAGMA user_version').get().user_version, setVersion: (n) => db.exec(`PRAGMA user_version=${n}`) });
+  const handlers = { ...createStoreHandlers({ all, get, run, tx }), close: () => { db.close(); return true; } };
+  parentPort.on('message', ({id,op,args}) => { try { parentPort.postMessage({id,result:handlers[op](args)}); } catch(error) { parentPort.postMessage({id,error:{message:error.message,code:error.code,status:error.status,stack:error.stack}}); } });
+}
+
+export class TeamsStore extends StoreClient {
+  constructor(dbPath) { super(); this.worker=new Worker(new URL(import.meta.url),{workerData:{dbPath}}); this.next=1; this.pending=new Map(); this.worker.on('message',m=>{const p=this.pending.get(m.id); if(!p)return; this.pending.delete(m.id); m.error?p.reject(Object.assign(new Error(m.error.message),m.error)):p.resolve(m.result);}); this.worker.on('error',e=>{for(const p of this.pending.values())p.reject(e);this.pending.clear();}); }
+  call(op,args={}) { return new Promise((resolve,reject)=>{const id=this.next++;this.pending.set(id,{resolve,reject});this.worker.postMessage({id,op,args});}); }
+  async close() { await this.call('close'); await this.worker.terminate(); }
+}

package/worker/fetch-adapter.mjs

@@ -0,0 +1,49 @@
+// Serve a Fetch-API Request through the server's Node-style (req, res) handler.
+// The handler reads req.method/url/headers/socket, iterates the body and waits
+// for 'close'; it writes res.writeHead/write/end (server-sent events included),
+// listens for 'drain'/'close' and reads writableLength. That is all modelled here.
+import { EventEmitter } from 'node:events';
+import { Readable } from 'node:stream';
+
+export function serveFetch(handler, request, { remoteAddress = null } = {}) {
+  const url = new URL(request.url);
+  const headers = {};
+  for (const [key, value] of request.headers) headers[key.toLowerCase()] = value;
+  const body = request.body ? Readable.fromWeb(request.body) : Readable.from([]);
+  const req = Object.assign(body, { method: request.method, url: url.pathname + url.search, headers, socket: { remoteAddress } });
+  const encoder = new TextEncoder();
+  const { readable, writable } = new TransformStream();
+  const writer = writable.getWriter();
+  let settle;
+  const head = new Promise((resolve) => { settle = resolve; });
+  const res = new EventEmitter();
+  let status = 200, responseHeaders = {}, started = false, ended = false, pending = 0;
+  const start = () => { if (started) return; started = true; settle(new Response(readable, { status, headers: responseHeaders })); };
+  const closed = () => { if (!ended) { ended = true; res.emit('close'); req.emit('close'); } };
+  request.signal?.addEventListener('abort', () => { closed(); writer.abort().catch(() => {}); });
+  Object.assign(res, {
+    get writableLength() { return pending; },
+    get headersSent() { return started; },
+    writeHead(code, values = {}) { status = code; responseHeaders = { ...responseHeaders, ...values }; if (code === 204 || code === 304) { started = true; settle(new Response(null, { status, headers: responseHeaders })); } else start(); return res; },
+    setHeader(name, value) { responseHeaders[name] = value; },
+    write(chunk) {
+      start();
+      if (ended) return false;
+      const bytes = typeof chunk === 'string' ? encoder.encode(chunk) : chunk;
+      pending += bytes.byteLength;
+      writer.write(bytes).then(() => { pending -= bytes.byteLength; if (pending === 0) res.emit('drain'); }, () => closed());
+      return pending < 65536;
+    },
+    end(chunk) {
+      if (status === 204 || status === 304) { closed(); return res; }
+      if (chunk !== undefined && chunk !== null) res.write(chunk); else start();
+      writer.close().catch(() => {}).finally(closed);
+      return res;
+    },
+  });
+  Promise.resolve().then(() => handler(req, res)).catch((error) => {
+    if (!started) { status = 500; responseHeaders = { 'Content-Type': 'application/json' }; res.end(JSON.stringify({ version: 1, error: { code: 'internal', message: error.message } })); }
+    else writer.abort(error).catch(() => {});
+  });
+  return head;
+}

package/worker/index.mjs

@@ -0,0 +1,127 @@
+// The Cloudflare host: a Worker that sends every request to one Durable Object,
+// which runs the Teams server (core.mjs) on its own SQLite. The machine doors are
+// WebSockets the object holds; `maintain` runs on the object's alarm.
+//
+// Configuration (wrangler.toml [vars] and secrets):
+//   PUBLIC_ORIGIN                      the https origin the Worker is served at
+//   INIT_TEAM                          the first team's name (used once, at bootstrap)
+//   VOLTER_ISSUER                      optional: an identity service members may sign in with (https://id.volter.ai)
+//   VOLTER_ORG_CLIENT_ID, VOLTER_ORG_CLIENT_SECRET, VOLTER_TEAM_ORGS
+//                                      optional: this server's product credential at VOLTER_ISSUER, and the teams whose
+//                                      organization there admits its members with no invitation (`team=slug,…`)
+//   DELEGATED_ISSUER                   optional: a workplace (RH2) whose delegated tokens open one pane or folder at /view
+//   SUPERCODE_TEAMS_BOOTSTRAP_TOKEN    secret: the owner's first credential, minted with
+//                                      `supercode teams server token`
+import { DurableObject } from 'cloudflare:workers';
+import { createTeamsApi, bootstrapServer, maintain, normalizePublicOrigin } from '@volter/teams/server/core';
+import { createStoreHandlers, migrate, DirectStore } from '../server/store-core.mjs';
+import { createHttpHandler, authenticate } from '@volter/teams/server/http';
+import { harnessRoutes } from '../server/harness-routes.mjs';
+import { authorizeMachineUpgrade, acceptMachineSocket, LINK_PROTOCOL, CHANNEL_PROTOCOL } from '@volter/teams/server/machine-link';
+import { setOtlpSchemaSources } from '../server/otlp/transport.mjs';
+import { identityOrganizationsFromEnv } from '@volter/teams/server/identity-orgs';
+import { setViewerSources } from '@volter/teams/server/viewer';
+import { serveFetch } from './fetch-adapter.mjs';
+import { webSocketDuplex } from './websocket-duplex.mjs';
+// The hosted viewer's files, bundled as text (wrangler.toml rules) and served at /view.
+import viewerPage from '../../volter-teams/viewer/index.html';
+import viewerScript from '../../volter-teams/viewer/viewer.mjs';
+import viewerChannel from '../../volter-teams/browser-channel.mjs';
+import viewerRpc from '../../volter-teams/stream-rpc.mjs';
+import proto0 from '../server/otlp/schema/google/protobuf/any.proto';
+import proto1 from '../server/otlp/schema/google/rpc/status.proto';
+import proto2 from '../server/otlp/schema/opentelemetry/proto/collector/logs/v1/logs_service.proto';
+import proto3 from '../server/otlp/schema/opentelemetry/proto/collector/metrics/v1/metrics_service.proto';
+import proto4 from '../server/otlp/schema/opentelemetry/proto/collector/trace/v1/trace_service.proto';
+import proto5 from '../server/otlp/schema/opentelemetry/proto/common/v1/common.proto';
+import proto6 from '../server/otlp/schema/opentelemetry/proto/logs/v1/logs.proto';
+import proto7 from '../server/otlp/schema/opentelemetry/proto/metrics/v1/metrics.proto';
+import proto8 from '../server/otlp/schema/opentelemetry/proto/resource/v1/resource.proto';
+import proto9 from '../server/otlp/schema/opentelemetry/proto/trace/v1/trace.proto';
+
+setViewerSources({ 'viewer/index.html': viewerPage, 'viewer/viewer.mjs': viewerScript, 'browser-channel.mjs': viewerChannel, 'stream-rpc.mjs': viewerRpc });
+
+setOtlpSchemaSources({
+  'google/protobuf/any.proto': proto0,
+  'google/rpc/status.proto': proto1,
+  'opentelemetry/proto/collector/logs/v1/logs_service.proto': proto2,
+  'opentelemetry/proto/collector/metrics/v1/metrics_service.proto': proto3,
+  'opentelemetry/proto/collector/trace/v1/trace_service.proto': proto4,
+  'opentelemetry/proto/common/v1/common.proto': proto5,
+  'opentelemetry/proto/logs/v1/logs.proto': proto6,
+  'opentelemetry/proto/metrics/v1/metrics.proto': proto7,
+  'opentelemetry/proto/resource/v1/resource.proto': proto8,
+  'opentelemetry/proto/trace/v1/trace.proto': proto9
+});
+
+const MAINTAIN_MS = 60_000;
+const BOOTSTRAP_TOKEN = /^sct_(cred_[0-9a-f]{32})\.[A-Za-z0-9_-]{16,}$/;
+
+/** SQLite primitives over the object's storage, in store-core's shape. */
+function durableSql(storage) {
+  const sql = storage.sql;
+  const param = (value) => (value instanceof Uint8Array ? value.buffer.slice(value.byteOffset, value.byteOffset + value.byteLength) : value);
+  const row = (value) => { for (const key of Object.keys(value)) if (value[key] instanceof ArrayBuffer) value[key] = Buffer.from(value[key]); return value; };
+  const all = (query, params = []) => sql.exec(query, ...params.map(param)).toArray().map(row);
+  const get = (query, params = []) => all(query, params)[0] ?? null;
+  const run = (query, params = []) => { sql.exec(query, ...params.map(param)); return { changes: sql.exec('SELECT changes() AS c').one().c }; };
+  const tx = (fn) => storage.transactionSync(fn);
+  return { all, get, run, tx, exec: (query) => sql.exec(query) };
+}
+
+export class TeamsServer extends DurableObject {
+  constructor(ctx, env) {
+    super(ctx, env);
+    this.ready = ctx.blockConcurrencyWhile(async () => {
+      const db = durableSql(ctx.storage);
+      migrate({ exec: db.exec, tx: db.tx, version: () => ctx.storage.kv.get('schema_version') ?? 0, setVersion: (n) => ctx.storage.kv.put('schema_version', n) });
+      this.api = createTeamsApi({ publicOrigin: normalizePublicOrigin(env.PUBLIC_ORIGIN), identityIssuer: env.VOLTER_ISSUER || null, identityOrganizations: identityOrganizationsFromEnv(env), delegatedIssuer: env.DELEGATED_ISSUER || null });
+      this.api.attach({ store: new DirectStore(createStoreHandlers(db)), harnessRoutes });
+      const existing = await this.api.store.one("SELECT value FROM server_meta WHERE key='server_id'");
+      if (existing) this.api.attach({ serverId: existing.value });
+      else {
+        const match = BOOTSTRAP_TOKEN.exec(env.SUPERCODE_TEAMS_BOOTSTRAP_TOKEN ?? '');
+        if (match) {
+          const ids = this.api.ids;
+          this.api.attach({ serverId: await bootstrapServer(this.api, { initTeam: env.INIT_TEAM, bootstrap: { server_id: ids.next('server'), team_id: ids.next('team'), principal_id: ids.next('user'), credential_id: match[1], token: env.SUPERCODE_TEAMS_BOOTSTRAP_TOKEN } }) });
+        }
+      }
+      this.handler = createHttpHandler(this.api);
+      if (!(await ctx.storage.getAlarm())) await ctx.storage.setAlarm(Date.now() + MAINTAIN_MS);
+    });
+  }
+
+  async fetch(request) {
+    await this.ready;
+    if (!this.api.serverId) return Response.json({ version: 1, error: { code: 'unavailable', message: 'set the SUPERCODE_TEAMS_BOOTSTRAP_TOKEN secret (supercode teams server token) before first use' } }, { status: 503 });
+    if (request.headers.get('upgrade')?.toLowerCase() === 'websocket') return this.upgrade(request);
+    return serveFetch(this.handler, request, { remoteAddress: request.headers.get('cf-connecting-ip') });
+  }
+
+  async upgrade(request) {
+    const headers = {};
+    for (const [key, value] of request.headers) headers[key.toLowerCase()] = value;
+    const url = new URL(request.url);
+    const decision = await authorizeMachineUpgrade(this.api, { authenticate, url: url.pathname + url.search, headers });
+    if (decision.status) return Response.json({ error: { code: decision.code, message: decision.message } }, { status: decision.status });
+    const offered = String(headers['sec-websocket-protocol'] ?? '').split(',').map((value) => value.trim());
+    const protocol = offered.find((value) => value === LINK_PROTOCOL || value === CHANNEL_PROTOCOL);
+    if (!protocol) return Response.json({ error: { code: 'invalid_request', message: 'offer the door protocol' } }, { status: 400 });
+    const [client, server] = Object.values(new WebSocketPair());
+    server.accept();
+    void acceptMachineSocket(this.api, decision, webSocketDuplex(server), (reason) => { try { server.close(1000, String(reason ?? 'closed').slice(0, 100)); } catch {} });
+    return new Response(null, { status: 101, webSocket: client, headers: { 'Sec-WebSocket-Protocol': protocol } });
+  }
+
+  async alarm() {
+    await this.ready;
+    if (this.api.serverId) await maintain(this.api).catch(() => {});
+    await this.ctx.storage.setAlarm(Date.now() + MAINTAIN_MS);
+  }
+}
+
+export default {
+  fetch(request, env) {
+    return env.TEAMS_SERVER.get(env.TEAMS_SERVER.idFromName('server')).fetch(request);
+  },
+};

package/worker/websocket-duplex.mjs

@@ -0,0 +1,29 @@
+// A Workers WebSocket as a Node duplex byte stream, for the machine channel.
+import { Duplex } from 'node:stream';
+
+export function webSocketDuplex(socket) {
+  const duplex = new Duplex({
+    read() {},
+    write(chunk, _encoding, done) {
+      try { socket.send(chunk); done(); } catch (error) { done(error); }
+    },
+    final(done) { try { socket.close(1000, 'closed'); } catch {} done(); },
+    destroy(error, done) { try { socket.close(1000, 'closed'); } catch {} done(error); },
+  });
+  // A binary message arrives as an ArrayBuffer or, from some runtimes, a Blob (an async read):
+  // one chain keeps frames in the order they arrived either way.
+  let order = Promise.resolve();
+  socket.addEventListener('message', (event) => {
+    const data = event.data;
+    const bytes = typeof data === 'string' ? Buffer.from(data)
+      : data instanceof ArrayBuffer ? Buffer.from(data)
+      : ArrayBuffer.isView(data) ? Buffer.from(data.buffer, data.byteOffset, data.byteLength)
+      : data.arrayBuffer().then((buffer) => Buffer.from(buffer));
+    if (bytes instanceof Promise) bytes.catch(() => {});
+    order = order.then(async () => { if (!duplex.destroyed) duplex.push(await bytes); }).catch(() => duplex.destroy());
+  });
+  socket.addEventListener('close', () => { order = order.then(() => { duplex.push(null); duplex.destroy(); }); });
+  // A peer that vanished without a close frame arrives as an error event (workerd logs it too).
+  socket.addEventListener('error', () => duplex.destroy());
+  return duplex;
+}

package/worker/wrangler.toml

@@ -0,0 +1,38 @@
+# A hosted Teams server on Cloudflare: one Worker, one Durable Object (SQLite).
+#   supercode teams server token | npx wrangler secret put SUPERCODE_TEAMS_BOOTSTRAP_TOKEN
+#   npx wrangler deploy --config sdk/teams/worker/wrangler.toml
+# Set name and PUBLIC_ORIGIN for your deployment; the token printed above is the
+# owner's first credential (`supercode teams login <origin> --token-stdin`).
+name = "supercode-teams"
+main = "index.mjs"
+compatibility_date = "2026-09-01"
+compatibility_flags = ["nodejs_compat"]
+
+[vars]
+PUBLIC_ORIGIN = "https://supercode-teams.example.workers.dev"
+INIT_TEAM = "Team"
+# Optional: members sign in with Volter (supercode teams login --volter); the
+# issuer must have this origin registered as a resource.
+# VOLTER_ISSUER = "https://id.volter.ai"
+# Optional: a workplace (RH2) whose delegated tokens open one pane or folder in the
+# hosted viewer (/view); its keys are at <issuer>/.well-known/jwks.json.
+# DELEGATED_ISSUER = "https://pilot.runhuman.com"
+
+[[durable_objects.bindings]]
+name = "TEAMS_SERVER"
+class_name = "TeamsServer"
+
+[[migrations]]
+tag = "v1"
+new_sqlite_classes = ["TeamsServer"]
+
+[[rules]]
+type = "Text"
+globs = ["**/*.proto"]
+fallthrough = true
+
+# The hosted viewer's files, served as text at /view (server/viewer.mjs).
+[[rules]]
+type = "Text"
+globs = ["**/volter-teams/viewer/index.html", "**/volter-teams/viewer/viewer.mjs", "**/volter-teams/browser-channel.mjs", "**/volter-teams/stream-rpc.mjs"]
+fallthrough = true

package/workspace-client.d.ts

@@ -0,0 +1,75 @@
+import type {
+  Access, Attachment, AttachmentRequest, Continuation, CreateSource, Descriptor, EnrollMachine,
+  Event, ExportRequest, FollowQuery, Group, ListQuery, Machine, Me, Membership, Operation, Page,
+  PrepareContinuation, ReadQuery, ReadResult, Result, SearchPage, SearchQuery, SessionGrant,
+  Root, Source, SyncRule, ServerPage, Team, AttachmentFrame, LiveGrant, LocalCompletion, NativeEffect, CreateInvitation, Invitation,
+} from './contracts/index.js';
+
+export interface RequestOptions { signal?: AbortSignal; idempotencyKey?: string; ifMatch?: number }
+export interface StreamOptions extends RequestOptions { after?: string }
+export type AttachmentAction = Exclude<NativeEffect, {kind:'attach'|'continue'}> extends infer E ? E extends {kind:infer K;payload:infer P} ? {kind:K} & Omit<P,'attachment_id'> : never : never;
+export interface LiveGrantCollectionClient {
+  list(options?:RequestOptions):Promise<Page<LiveGrant>>;
+  get(id:string,options?:RequestOptions):Promise<Result<LiveGrant>>;
+  create(body:Omit<LiveGrant,'id'|'revision'>,options?:RequestOptions):Promise<Result<LiveGrant>>;
+  remove(id:string,options?:RequestOptions):Promise<null>;
+}
+export interface Capabilities { version:1; server_id:string; protocol:'teams.v1'; operations:string[]; auth_modes:string[] }
+export interface CollectionClient<T,Create=unknown,Update=unknown> {
+  list(query?:Record<string,unknown>,options?:RequestOptions):Promise<Page<T>>;
+  get(id:string,options?:RequestOptions):Promise<Result<T>>;
+  create(body:Create,options?:RequestOptions):Promise<Result<T>>;
+  update(id:string,body:Update,options?:RequestOptions):Promise<Result<T>>;
+  remove(id:string,options?:RequestOptions):Promise<null>;
+}
+export interface ReadCollectionClient<T> {
+  list(query?:Record<string,unknown>,options?:RequestOptions):Promise<Page<T>>;
+  get(id:string,options?:RequestOptions):Promise<Result<T>>;
+}
+export interface MachineCollectionClient extends ReadCollectionClient<Machine> {
+  create(body:EnrollMachine,options?:RequestOptions):Promise<Result<{machine:Machine;source:Source;credential:import('./contracts/index.js').TokenCredential|null}>>;
+  remove(id:string,options?:RequestOptions):Promise<null>;
+}
+export declare class TeamsClient {
+  constructor(options:{server:string;credential:string;fetch?:typeof fetch});
+  me(options?:RequestOptions):Promise<Me>;
+  capabilities(options?:RequestOptions):Promise<Capabilities>;
+  teams(query?:{limit?:number;cursor?:string},options?:RequestOptions):Promise<ServerPage<Team>>;
+  createTeam(body:{name:string},options?:RequestOptions):Promise<Result<Team>>;
+  team(id:string):TeamClient;
+}
+export interface TeamClient {
+  sessions:{list(query?:ListQuery,options?:RequestOptions):Promise<Page<Descriptor>>;search(query:SearchQuery,options?:RequestOptions):Promise<SearchPage>;watch(query?:ListQuery,options?:StreamOptions):AsyncIterable<Event>;get(id:string):SessionClient};
+  members:{list(query?:Record<string,unknown>,options?:RequestOptions):Promise<Page<Membership>>;update(id:string,body:{role:Membership['role']},options?:RequestOptions):Promise<Result<Membership>>;remove(id:string,options?:RequestOptions):Promise<null>};
+  groups:{list(query?:Record<string,unknown>,options?:RequestOptions):Promise<Page<Group>>;create(body:{name:string},options?:RequestOptions):Promise<Result<Group>>;remove(id:string,options?:RequestOptions):Promise<null>;addMember(groupId:string,memberId:string,options?:RequestOptions):Promise<null>;removeMember(groupId:string,memberId:string,options?:RequestOptions):Promise<null>};
+  machines:MachineCollectionClient & {roots(id:string,query?:Record<string,unknown>,options?:RequestOptions):Promise<Page<Root>>;liveGrants(machineId:string):LiveGrantCollectionClient};
+  sources:{list(query?:Record<string,unknown>,options?:RequestOptions):Promise<Page<Source>>;get(id:string,options?:RequestOptions):Promise<Result<Source>>;create(body:CreateSource,options?:RequestOptions):Promise<Result<Source>>;update(id:string,body:Partial<Pick<Source,'state'|'custodian_id'|'default_visibility'>>,options?:RequestOptions):Promise<Result<Source>>;credential(id:string,body:{rotate:boolean},options?:RequestOptions):Promise<Result<import('./contracts/index.js').TokenCredential|null>>;configuration(id:string,format?:'otel-collector',options?:RequestOptions):Promise<Result<import('./contracts/index.js').SourceCollectorConfig>>};
+  syncRules:{list(query?:Record<string,unknown>,options?:RequestOptions):Promise<Page<SyncRule>>;get(id:string,options?:RequestOptions):Promise<Result<SyncRule>>;create(body:Omit<SyncRule,'id'|'state'|'revision'|'capture_after'>,options?:RequestOptions):Promise<Result<SyncRule>>;update(id:string,body:{state:'paused';backfill?:never}|{state:'active';backfill:SyncRule['backfill']},options?:RequestOptions):Promise<Result<SyncRule>>;remove(id:string,options?:RequestOptions):Promise<null>};
+  credentials:{create(body:{kind:'user'|'service';expires_in_ms:number},options?:RequestOptions):Promise<Result<import('./contracts/index.js').TokenCredential|null>>;remove(id:string,options?:RequestOptions):Promise<null>};
+  invitations:{create(body:CreateInvitation,options?:RequestOptions):Promise<Result<Invitation>>};
+  operations:{get(id:string,options?:RequestOptions):Promise<Result<Operation>>};
+  continuations:{
+    get(id:string,options?:RequestOptions):Promise<Result<Continuation>>;
+    authorizeDestination(id:string,body:{expires_at:number},options?:RequestOptions):Promise<Result<Continuation>>;
+    launch(id:string,options?:RequestOptions):Promise<Result<Operation>>;
+    completeLocal(id:string,body:LocalCompletion,options?:RequestOptions):Promise<Result<Operation>>;
+  };
+  attachments:{
+    actions(id:string,body:AttachmentAction,options?:RequestOptions):Promise<Result<Operation>>;
+    detach(id:string,options?:RequestOptions):Promise<null>;
+    /** Native frames verbatim. Terminal Teams policy events throw a typed error. No token replay/reconnect. */
+    stream(attachment:Attachment,options?:Pick<RequestOptions,'signal'>):AsyncIterable<AttachmentFrame>;
+  };
+}
+export interface SessionClient {
+  artifact(uploadId:string,options?:{signal?:AbortSignal;range?:string}):Promise<Response>;
+  descriptor(options?:RequestOptions):Promise<Result<Descriptor>>;
+  read(query?:ReadQuery,options?:RequestOptions):Promise<ReadResult>;
+  follow(query?:FollowQuery,options?:StreamOptions):AsyncIterable<Event>;
+  access(options?:RequestOptions):Promise<Result<Access>>;
+  grant(body:Omit<SessionGrant,'id'>,options?:RequestOptions):Promise<Result<Access>>;
+  revoke(id:string,options?:RequestOptions):Promise<Result<Access>>;
+  export(body:ExportRequest,options?:RequestOptions):Promise<Result<Operation>>;
+  prepare(body:PrepareContinuation,options?:RequestOptions):Promise<Result<Continuation>>;
+  attach(body:AttachmentRequest,options?:RequestOptions):Promise<Result<Attachment>>;
+}