@volter/supercode-teams 0.2.20

package/contracts/index.d.ts

@@ -0,0 +1,299 @@
+/** Design-time contract. Copy/generate public declarations in B01; do not import this from production. */
+import type { NormalizedMessage, Fidelity, HarnessId, ObservedRuntimeEvent } from '@volter/supercode-harness-sdk';
+export type { NormalizedMessage, Fidelity, HarnessId, ObservedRuntimeEvent } from '@volter/supercode-harness-sdk';
+
+export type Json = null | boolean | number | string | Json[] | { [key: string]: Json };
+export type Id = string; // kind prefix + '_' + lowercase UUID without hyphens; see protocol.md
+export type Millis = number; // integer, 0..Number.MAX_SAFE_INTEGER
+export type Revision = number; // integer, 0..Number.MAX_SAFE_INTEGER
+export type TeamRole = 'owner' | 'admin' | 'member' | 'viewer';
+export type SessionRole = 'reader' | 'manager';
+export type Visibility = 'team' | 'restricted';
+export type CredentialKind = 'user' | 'service' | 'machine' | 'ingest';
+export type SourceKind = 'connector' | 'otlp';
+export type SourceState = 'active' | 'paused' | 'revoked';
+export type CaptureMode = 'none' | 'since' | 'all';
+export interface Scope { server_id: Id; team_id: Id; principal_id: Id }
+export interface ServerScope { server_id: Id; principal_id: Id }
+export interface ServerPage<T> { version: 1; context: ServerScope; items: T[]; next_cursor: string | null }
+export interface Page<T> { version: 1; context: Scope; items: T[]; next_cursor: string | null }
+export interface Result<T> { version: 1; context: Scope; data: T }
+export type ErrorCode =
+  | 'invalid_request' | 'ambiguous_reference' | 'authentication_required' | 'not_found'
+  | 'forbidden' | 'unsupported' | 'machine_offline' | 'controller_busy' | 'conflict'
+  | 'resync_required' | 'revision_mismatch' | 'idempotency_conflict' | 'source_revoked'
+  | 'source_paused' | 'session_deleted' | 'batch_gap' | 'capture_conflict'
+  | 'fidelity_unavailable' | 'rate_limited' | 'request_too_large' | 'internal_error';
+export interface Failure {
+  version: 1;
+  error: { code: ErrorCode; message: string; request_id: Id; retryable: boolean; details: Json };
+}
+export interface Principal { id: Id; kind: 'user' | 'service'; display_name: string }
+export interface Membership { team_id: Id; principal: Principal; role: TeamRole; revision: Revision }
+export interface Group { id: Id; name: string; revision: Revision; member_ids: Id[] }
+export interface Team { id: Id; name: string; revision: Revision }
+export interface Me { server_id: Id; principal: Principal; teams: { team: Team; role: TeamRole }[] }
+export interface GrantSubject { kind: 'principal' | 'group'; id: Id }
+export interface SessionGrant { id: Id; subject: GrantSubject; role: SessionRole; expires_at: Millis | null }
+export interface Access {
+  revision: Revision; visibility: Visibility; custodian_id: Id; grants: SessionGrant[];
+}
+export interface Attribution {
+  principal_id: Id | null;
+  reported_user: string | null;
+  status: 'verified' | 'reported' | 'unknown';
+  mapping_id: Id | null;
+}
+export interface Repository { authority: string; path: string; key: string }
+export interface Source {
+  id: Id; name: string; kind: SourceKind; state: SourceState; machine_id: Id | null;
+  custodian_id: Id; default_visibility: Visibility; revision: Revision;
+  last_received_at: Millis | null; decoder: string | null;
+}
+export interface Machine {
+  id: Id; name: string; custodian_id: Id; enrollment: 'active' | 'revoked';
+  connection: 'online' | 'offline'; last_seen_at: Millis | null; incarnation_id: Id | null;
+  /** The key id the machine signs `describe` with; null until its daemon reports one. */
+  host_key_id: string | null;
+  revision: Revision;
+}
+export interface Root { id: Id; machine_id: Id; name: string; harnesses: HarnessId[] }
+export interface Coverage {
+  completeness: 'unknown' | 'partial' | 'complete';
+  reasons: ('prefix_not_captured' | 'sync_paused' | 'redacted' | 'truncated' | 'sampled'
+    | 'unsequenced' | 'source_conflict' | 'unsupported_decoder' | 'retention' | 'parse_error')[];
+  missing: { start_at: Millis | null; end_at: Millis | null; reason: string }[];
+}
+export type Action = 'read' | 'follow' | 'export_text' | 'export_native' | 'manage'
+  | 'attach_observe' | 'interact' | 'approve' | 'interrupt' | 'terminate' | 'continue';
+export interface Eligibility {
+  allowed: boolean;
+  reason: 'forbidden' | 'machine_offline' | 'unsupported' | 'missing_context' | 'controller_busy' | null;
+}
+export interface Binding {
+  id: Id; machine_id: Id; incarnation_id: Id; native_runtime_id: string; native_session_id: string;
+  harness: HarnessId; state: 'running' | 'stopped' | 'unknown'; observed_at: Millis;
+  native_capabilities: Action[];
+}
+export interface Descriptor {
+  id: Id; revision: Revision; title: string | null; harness: HarnessId; user: Attribution;
+  repository: Repository | null; parent_id: Id | null; continued_from: Id | null;
+  recorded_activity_at: Millis | null; received_at: Millis; sort_at: Millis;
+  activity_basis: 'recorded' | 'received'; source_ids: Id[]; machine_ids: Id[];
+  coverage: Coverage; bindings: Binding[]; actions: Record<Action, Eligibility>;
+}
+export interface Message {
+  id: Id; source_id: Id; native_key: string; recorded_at: Millis | null;
+  value: NormalizedMessage; // reuse core fields; do not create another chat model
+}
+export interface ReadResult {
+  version: 1; context: Scope; descriptor: Descriptor; messages: Message[];
+  before_cursor: string | null; event_cursor: string; revision: Revision;
+  display: { returned: number; total: number; truncated_fields: number };
+}
+export interface ListQuery {
+  user?: Id | 'me'; repo?: string; harness?: HarnessId; machine?: Id; source?: Id;
+  since?: Millis; until?: Millis; limit?: number; cursor?: string; include_children?: boolean;
+}
+export interface SearchQuery extends ListQuery { query: string }
+export interface SearchHit {
+  session: Descriptor;
+  matches: { message_id: Id | null; field: 'title' | 'content'; excerpt: string; offset: number }[];
+  match_at: Millis; indexed_revision: Revision;
+}
+export interface SearchPage extends Page<SearchHit> {
+  coverage: { scope: 'retained_text'; indexed_at: Millis; indexed_revision: Revision };
+}
+export interface ReadQuery { tail?: number; before?: string; revision?: Revision }
+export interface FollowQuery { after?: string; tail?: number }
+export type Event =
+  | { type: 'snapshot'; cursor: string; revision: Revision; data: ReadResult }
+  | { type: 'session_changed'; cursor: string; revision: Revision; session_id: Id; reason: 'capture' | 'metadata' | 'coverage' | 'binding' | 'merge'; read_required: true }
+  | { type: 'session_deleted'; cursor: string; revision: Revision; session_id: Id }
+  | { type: 'catalog_reset'; cursor: string; revision: Revision; data: Page<Descriptor> }
+  | { type: 'access_revoked'; reason: 'membership' | 'session' | 'credential'; terminal: true }
+  | { type: 'resync_required'; terminal: true };
+
+export interface ContextFile {
+  version: 1; current: string | null;
+  contexts: Record<string, { origin: string; server_id: Id; team_id: Id; principal_id: Id; credential_ref: string }>;
+}
+export interface TokenCredential { token: string; kind: CredentialKind; expires_at: Millis | null }
+export interface CreateInvitation { display_name: string; role: Exclude<TeamRole, 'owner'>; expires_in_ms: number }
+export interface Invitation { id: Id; role: Exclude<TeamRole, 'owner'>; expires_at: Millis; enrollment_code?: string }
+export interface AcceptInvitation { enrollment_code: string }
+export interface CreateSource { name: string; kind: 'otlp'; custodian_id: Id; visibility: Visibility }
+export interface SourceCollectorConfig {
+  format: 'otel-collector'; source_id: Id; endpoint: string; credential_env: string; content: string;
+}
+export interface EnrollMachine { name: string; enrollment_key: string }
+export interface Enrollment { machine: Machine; source: Source; credential: TokenCredential | null }
+export interface Heartbeat { incarnation_id: Id; sequence: number; bindings: Binding[]; roots: Root[]; host_key_id?: string }
+export interface SyncRule {
+  id: Id; machine_id: Id; source_id: Id; selector: { root_id: Id; harnesses: HarnessId[] };
+  visibility: Visibility; backfill: { mode: CaptureMode; since: Millis | null };
+  state: 'active' | 'paused' | 'removed'; revision: Revision; capture_after: Millis;
+}
+export interface ConnectorConfiguration {
+  machine: Machine; source: Source; rules: SyncRule[]; authorization_revision: Revision;
+  /** Who holds the machine implicitly as operator, and the machine grants its daemon admits from. */
+  custodian_id: Id; machine_grants: MachineGrant[];
+}
+/** The machine daemon's door vocabulary; `operate` is the whole machine (harness.v1 and launch) and targets only `*`. */
+export type MachineCapability = 'operate' | 'view' | 'observe' | 'interact' | 'control' | 'files' | 'ports' | 'mail';
+/** A subject's capabilities on one machine's doors (design §11): targets are `*` (operate and view only) or `<kind>:<name>` — the harness serves `pane:`, `runtime:`, `root:/path` and `port:<pane>/<n>` — or `<kind>:*` for every target of a kind. */
+export interface MachineGrant {
+  id: Id; machine_id: Id; subject_id: Id; caps: MachineCapability[]; targets: string[];
+  issuer_id: Id; created_at: Millis; expires_at: Millis; revision: Revision;
+}
+export interface ArtifactChunk {
+  upload_id: Id; index: number; sha256: string; bytes_base64: string;
+}
+export interface ArtifactManifest {
+  upload_id: Id; sha256: string; byte_length: number; chunks: number;
+  media_type: string; role: 'native' | 'sidecar' | 'otlp'; relative_name: string;
+}
+export interface CaptureBegin {
+  native_session_id: string; harness: HarnessId; generation: number; sequence: number;
+  capture_id: Id; previous_digest: string | null; visibility: Visibility;
+  rule_id: Id | null; rule_revision: Revision | null;
+}
+export type CaptureBeginResult =
+  | { state: 'staging'; capture_id: Id; next_part: number }
+  | { state: 'committed'; receipt: CaptureReceipt };
+export interface CapturePart { capture_id: Id; index: number; messages: CapturedMessage[] }
+export interface CapturedMessage {
+  native_key: string; recorded_at: Millis | null; value: NormalizedMessage;
+}
+export interface CapturedNativeBundle {
+  id: Id; harness: HarnessId; fidelity: Fidelity; residue: string[];
+  files: Array<{ upload_id: Id; role: ExportFile['role'] }>;
+}
+export interface CaptureCommit {
+  capture_id: Id; parts: number; digest: string; title: string | null;
+  repository: Repository | null; reported_user: string | null;
+  recorded_activity_at: Millis | null; parent_native_id: string | null;
+  coverage: Coverage; artifacts: ArtifactManifest[]; native_bundle?: CapturedNativeBundle | null;
+}
+export interface CaptureReceipt {
+  source_id: Id; capture_id: Id; session_id: Id; generation: number; sequence: number;
+  digest: string; revision: Revision; duplicate: boolean;
+}
+export interface Correlation {
+  id: Id; left_source_id: Id; left_native_id: string; right_source_id: Id; right_native_id: string;
+  left_revision: Revision; right_revision: Revision; harness: HarnessId;
+  evidence: 'custodian_attestation'; revision: Revision;
+}
+export interface LiveGrant {
+  id: Id; machine_id: Id; session_id: Id; binding_id: Id; subject_id: Id;
+  actions: Action[]; expires_at: Millis; revision: Revision;
+}
+export interface AttachmentRequest { binding_id: Id; mode: 'observe' | 'control' }
+export type AttachmentFrame = ObservedRuntimeEvent;
+export interface Attachment { id: Id; state: 'pending' | 'active' | 'detached' | 'revoked' | 'closed'; stream_format: 'observed_runtime_event'; binding_id: Id; expires_at: Millis; stream_url: string; credential: string; effective_actions: Action[] }
+export interface PrepareContinuation {
+  source_revision: Revision; destination: { machine_id: Id | 'local'; root_id: Id | null; cwd: string };
+  harness: HarnessId; fidelity: Fidelity;
+}
+export interface Continuation {
+  id: Id; source_id: Id; source_revision: Revision; access_revision: Revision;
+  state: 'preparing' | 'ready' | 'refused' | 'expired' | 'launching' | 'running' | 'unknown' | 'failed';
+  requester_id: Id; destination: PrepareContinuation['destination']; harness: HarnessId;
+  fidelity: Fidelity;
+  expires_at: Millis; residue: string[]; operation_id: Id | null; new_session_id: Id | null;
+  destination_authorization: { principal_id: Id; approved_by: Id; expires_at: Millis } | null;
+}
+export interface Operation {
+  id: Id; state: 'pending' | 'running' | 'succeeded' | 'failed' | 'unknown';
+  result: Json; error: Failure['error'] | null;
+}
+/** Export bytes are fetched through the session ACL; no bearer or machine path appears here. */
+export interface ExportFile {
+  upload_id: Id; relative_name: string; media_type: string; byte_length: number; sha256: string;
+  role: 'primary' | 'subagent' | 'bundle' | 'source_recovery';
+}
+export interface ExportResult {
+  kind: 'export'; source_session_id: Id; source_revision: Revision;
+  format: ExportRequest['format']; fidelity: Fidelity; residue: string[]; coverage: Coverage;
+  files: ExportFile[];
+}
+export interface ExportRequest { format: 'text' | 'html' | HarnessId; fidelity?: Fidelity; revision: Revision }
+export interface EffectScope {
+  id: Id;
+  principal_id: Id; team_id: Id; machine_id: Id; binding_id: Id | null;
+  incarnation_id: Id; session_id: Id; access_revision: Revision; grant_id: Id | null;
+  expires_at: Millis;
+}
+export type NativeEffect = EffectScope & (
+  | { kind: 'attach'; payload: { attachment_id: Id; mode: 'observe' | 'control' } }
+  | { kind: 'input'; payload: { attachment_id: Id; text: string } }
+  | { kind: 'approve'; payload: { attachment_id: Id; request_id: string; decision: 'allow_once' | 'deny' } }
+  | { kind: 'interrupt' | 'terminate'; payload: { attachment_id: Id } }
+  | { kind: 'continue'; payload: { continuation_id: Id } }
+);
+
+export interface EffectDelivery { effect: NativeEffect; operation_id: Id; state: Operation['state'] }
+export interface EffectClaim { delivery: EffectDelivery; execute: boolean }
+export type EffectResult =
+  | { state: 'succeeded'; receipt: { native_session_id: string | null; runtime_id: string | null } }
+  | { state: 'failed'; error: Failure['error'] }
+  | { state: 'unknown'; error: null };
+export interface LocalLaunchTicket {
+  kind: 'local_launch'; continuation_id: Id; operation_id: Id; harness: HarnessId; fidelity: Fidelity;
+  artifact: ExportResult;
+  destination: { machine_id: 'local'; root_id: null; cwd: string }; expires_at: Millis;
+}
+export interface RemoteLaunchTicket extends Omit<LocalLaunchTicket, 'kind' | 'destination'> {
+  kind: 'remote_launch'; destination: { machine_id: Id; root_id: Id; cwd: string };
+}
+export interface LocalCompletion {
+  operation_id: Id; outcome: 'running' | 'failed' | 'unknown';
+  native_session_id: string | null; error: Failure['error'] | null;
+}
+export interface ContinuationReceipt {
+  kind: 'continuation'; continuation_id: Id; native_session_id: string | null;
+  new_session_id: Id | null; verification: 'caller_reported' | 'connector_reported';
+}
+
+/** HTTP operation names and bodies: exact paths/statuses/policies are in protocol.md. */
+export interface Operations {
+  me: { request: null; response: Me };
+  teams_list: { request: { limit?: number; cursor?: string }; response: ServerPage<Team> };
+  teams_create: { request: { name: string }; response: Result<Team> };
+  list: { request: ListQuery; response: Page<Descriptor> };
+  search: { request: SearchQuery; response: SearchPage };
+  read: { request: ReadQuery; response: ReadResult };
+  follow: { request: FollowQuery; response: Event };
+  descriptor: { request: null; response: Result<Descriptor> };
+  access: { request: null; response: Result<Access> };
+  grant: { request: Omit<SessionGrant, 'id'>; response: Result<Access> };
+  invite: { request: CreateInvitation; response: Result<Invitation> };
+  accept_invite: { request: AcceptInvitation; response: { principal: Principal; credential: TokenCredential; team: Team } };
+  source_create: { request: CreateSource; response: Result<Source> };
+  source_config: { request: { format: 'otel-collector' }; response: Result<SourceCollectorConfig> };
+  enroll: { request: EnrollMachine; response: Result<Enrollment> };
+  machine_configuration: { request: null; response: Result<ConnectorConfiguration> };
+  heartbeat: { request: Heartbeat; response: Result<Machine> };
+  capture_begin: { request: CaptureBegin; response: Result<CaptureBeginResult> };
+  capture_part: { request: CapturePart; response: Result<{ next_part: number }> };
+  capture_commit: { request: CaptureCommit; response: Result<CaptureReceipt> };
+  correlate: { request: Omit<Correlation, 'id' | 'revision'>; response: Result<Descriptor> };
+  live_grant: { request: Omit<LiveGrant, 'id' | 'revision'>; response: Result<LiveGrant> };
+  machine_grant: { request: Pick<MachineGrant, 'subject_id' | 'caps' | 'targets' | 'expires_at'>; response: Result<MachineGrant> };
+  attach: { request: AttachmentRequest; response: Result<Attachment> };
+  prepare: { request: PrepareContinuation; response: Result<Continuation> };
+  launch: { request: null; response: Result<Operation> };
+  export: { request: ExportRequest; response: Result<Operation> };
+}
+
+export declare const ERROR_CODES: readonly ErrorCode[];
+export declare const OPERATIONS: readonly (keyof Operations)[];
+export declare class ContractError extends Error { code: 'invalid_request'; details: unknown; }
+export declare function validateId(value: unknown, name?: string): string;
+export declare function validateListQuery<T extends object>(value?: T): T;
+export declare function validateSearchQuery<T extends object>(value: T): T;
+export declare function validateReadQuery<T extends object>(value?: T): T;
+export declare function validateNormalizedMessage<T extends NormalizedMessage>(value: T): T;
+export declare function validateCaptureBegin<T extends CaptureBegin>(value: T): T;
+export declare function validateCapturePart<T extends CapturePart>(value: T): T;
+export declare function canonicalJson(value: unknown): string;

package/contracts/index.mjs

@@ -0,0 +1,37 @@
+import { ContractError, canonicalJson, validationFailure } from '@volter/teams/server/wire';
+export { ContractError, canonicalJson, validationFailure };
+const ID = /^(srv|team|usr|svc|grp|ses|msg|src|mach|bind|cap|upload|grant|map|op|cont|inv|cred|req|root|inc|rule|att|evt|audit)_[0-9a-f]{32}$/;
+export const ERROR_CODES = Object.freeze(['invalid_request','ambiguous_reference','authentication_required','not_found','forbidden','unsupported','machine_offline','controller_busy','conflict','resync_required','revision_mismatch','idempotency_conflict','source_revoked','source_paused','session_deleted','batch_gap','capture_conflict','fidelity_unavailable','rate_limited','request_too_large','internal_error']);
+export const OPERATIONS = Object.freeze(['me','teams_list','teams_create','list','search','read','follow','descriptor','access','grant','invite','accept_invite','source_create','source_config','enroll','heartbeat','machine_configuration','capture_begin','capture_part','capture_commit','correlate','live_grant','attach','prepare','launch','export']);
+const object = (value, name) => { if (!value || typeof value !== 'object' || Array.isArray(value)) throw new ContractError(`${name} must be an object`); return value; };
+const exact = (value, allowed, name) => { for (const key of Object.keys(object(value, name))) if (!allowed.includes(key)) throw new ContractError(`${name}.${key} is unknown`); };
+const integer = (value, name, min = 0, max = Number.MAX_SAFE_INTEGER) => { if (!Number.isSafeInteger(value) || value < min || value > max) throw new ContractError(`${name} must be an integer from ${min} to ${max}`); };
+const string = (value, name, { min = 1, max = 512 } = {}) => { if (typeof value !== 'string' || [...value].length < min || [...value].length > max) throw new ContractError(`${name} must be a string of ${min}..${max} code points`); };
+const member = (value, values, name) => { if (!values.includes(value)) throw new ContractError(`${name} must be one of ${values.join(', ')}`); };
+export function validateId(value, name = 'id') { if (typeof value !== 'string' || !ID.test(value)) throw new ContractError(`${name} is not a Teams ID`); return value; }
+export function validateListQuery(value = {}) { exact(value, ['user','repo','harness','machine','source','since','until','limit','cursor','include_children'], 'query'); if (value.limit !== undefined) integer(value.limit, 'query.limit', 1, 200); if (value.include_children !== undefined && typeof value.include_children !== 'boolean') throw new ContractError('query.include_children must be boolean'); for (const k of ['since','until']) if (value[k] !== undefined) integer(value[k], `query.${k}`); return value; }
+export function validateSearchQuery(value) { exact(value, ['query','user','repo','harness','machine','source','since','until','limit','cursor','include_children'], 'query'); validateListQuery(Object.fromEntries(Object.entries(value).filter(([k]) => k !== 'query'))); string(value.query?.trim(), 'query.query', { max: 512 }); return value; }
+export function validateReadQuery(value = {}) { exact(value, ['tail','before','revision'], 'query'); if (value.tail !== undefined) integer(value.tail, 'query.tail', 1, 500); if (value.revision !== undefined) integer(value.revision, 'query.revision'); return value; }
+export function validateNormalizedMessage(value) {
+  exact(value, ['role','content','tool_calls','tool_call_id','name','metadata'], 'message');
+  member(value.role, ['system','user','assistant','tool'], 'message.role');
+  if(value.content!==undefined&&typeof value.content!=='string'&&!Array.isArray(value.content))throw new ContractError('message.content must be a string or JSON content array');
+  if(value.tool_calls!==undefined){
+    if(!Array.isArray(value.tool_calls))throw new ContractError('message.tool_calls must be an array');
+    for(const [index,call] of value.tool_calls.entries()){
+      exact(call,['id','type','function'],`message.tool_calls[${index}]`);
+      string(call.id,`message.tool_calls[${index}].id`);
+      string(call.type,`message.tool_calls[${index}].type`);
+      exact(call.function,['name','arguments'],`message.tool_calls[${index}].function`);
+      string(call.function.name,`message.tool_calls[${index}].function.name`);
+      if(typeof call.function.arguments!=='string')throw new ContractError(`message.tool_calls[${index}].function.arguments must be a string`);
+    }
+  }
+  if(value.tool_call_id!==undefined)string(value.tool_call_id,'message.tool_call_id');
+  if(value.name!==undefined)string(value.name,'message.name');
+  const metadata=object(value.metadata,'message.metadata');
+  for(const [key,item] of Object.entries(metadata))if(typeof item!=='string')throw new ContractError(`message.metadata.${key} must be a string`);
+  return value;
+}
+export function validateCaptureBegin(value) { exact(value, ['native_session_id','harness','generation','sequence','capture_id','previous_digest','visibility','rule_id','rule_revision'], 'capture'); string(value.native_session_id, 'capture.native_session_id', {max:512}); string(value.harness, 'capture.harness'); integer(value.generation,'capture.generation',1); integer(value.sequence,'capture.sequence',1); validateId(value.capture_id,'capture.capture_id'); if (value.previous_digest !== null) string(value.previous_digest,'capture.previous_digest',{min:64,max:64}); member(value.visibility,['team','restricted'],'capture.visibility'); if (value.rule_id !== null) validateId(value.rule_id,'capture.rule_id'); if ((value.rule_id === null) !== (value.rule_revision === null)) throw new ContractError('rule_id and rule_revision must both be null or present'); if (value.rule_revision !== null) integer(value.rule_revision,'capture.rule_revision',1); return value; }
+export function validateCapturePart(value) { exact(value,['capture_id','index','messages'],'part'); validateId(value.capture_id,'part.capture_id'); integer(value.index,'part.index'); if (!Array.isArray(value.messages) || value.messages.length < 1 || value.messages.length > 500) throw new ContractError('part.messages must contain 1..500 messages'); for (const [i,m] of value.messages.entries()) { exact(m,['native_key','recorded_at','value'],`part.messages[${i}]`); string(m.native_key,`part.messages[${i}].native_key`,{max:512}); if (m.recorded_at !== null) integer(m.recorded_at,`part.messages[${i}].recorded_at`); validateNormalizedMessage(m.value); } return value; }

package/execution.mjs

@@ -0,0 +1,206 @@
+// Remote execution on this machine: the `exec` and `sftp` streams an operator opens to run a
+// pilot's tool processes here and to mount this machine's files, and the `exec-server` stream a
+// harness with its own execution door runs its tools through (docs/plans/remote-execution.md).
+//
+// The daemon owns every job it starts. Where this user holds a delegated cgroup v2 subtree, each
+// job runs in its own cgroup and ending it writes `cgroup.kill`, which takes descendants that
+// called setsid() with it; elsewhere a job is its process group, and the capability report says
+// so. A job ends when its stream closes, when the daemon stops, and, if the daemon died, when
+// the next daemon reaps the record it left.
+import { spawn } from 'node:child_process';
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, rmdirSync, statSync, writeFileSync } from 'node:fs';
+import { delimiter, join } from 'node:path';
+import { EXECUTION_DOORS, executionDoorFor } from '@volter/supercode-harness-sdk/execution-doors';
+import { fileURLToPath } from 'node:url';
+import { createHash, randomBytes } from 'node:crypto';
+
+const JOB_EXEC = fileURLToPath(new URL('./remote/job-exec.py', import.meta.url));
+const SFTP_SERVERS = ['/usr/lib/openssh/sftp-server', '/usr/libexec/openssh/sftp-server', '/usr/libexec/sftp-server', '/usr/lib/sftp-server'];
+
+/** The cgroup v2 directory this user may create job cgroups under, or null. */
+export function delegatedCgroup(env = process.env) {
+  const named = env.SUPERCODE_TEAMS_CGROUP;
+  const candidates = named ? [named] : ['/sys/fs/cgroup/supercode-machine'];
+  for (const dir of candidates) {
+    try {
+      const stat = statSync(dir);
+      if (!stat.isDirectory() || (typeof process.getuid === 'function' && stat.uid !== process.getuid())) continue;
+      if (!existsSync(join(dir, 'cgroup.procs')) || !existsSync(join(dir, 'cgroup.kill'))) continue;
+      return dir;
+    } catch { /* not this one */ }
+  }
+  return null;
+}
+
+export function sftpServer() {
+  return SFTP_SERVERS.find((path) => existsSync(path)) ?? null;
+}
+
+/** `program` as this daemon's PATH finds it, or null. */
+function onPath(program, env) {
+  for (const dir of (env.PATH ?? '').split(delimiter)) if (dir && existsSync(join(dir, program))) return join(dir, program);
+  return null;
+}
+
+/** The harnesses whose own execution server this machine can run (execution-doors.mjs). */
+export function execServers(env = process.env) {
+  return Object.entries(EXECUTION_DOORS).filter(([, door]) => door.door === 'exec-server' && onPath(door.serve.program, env)).map(([harness]) => harness);
+}
+
+/** What this machine can do as an execution target, for `describe`. */
+export function executionCapabilities(env = process.env) {
+  const python = ['/usr/bin/python3', '/usr/local/bin/python3'].some((path) => existsSync(path));
+  return {
+    exec: process.platform === 'linux' && python,
+    sftp: Boolean(sftpServer()),
+    exec_servers: execServers(env),
+    jobs: delegatedCgroup(env) ? 'cgroup' : 'process-group',
+    unsupported: ['named-unix-sockets', 'shared-memory', 'descriptor-passing', 'datagrams'],
+  };
+}
+
+export class JobOwner {
+  constructor({ home, env = process.env, log = () => {} }) {
+    this.dir = join(home, 'jobs');
+    mkdirSync(this.dir, { recursive: true, mode: 0o700 });
+    this.env = env;
+    this.log = log;
+    this.cgroup = delegatedCgroup(env);
+    this.live = new Map();
+  }
+
+  /** End every job a previous daemon left running. */
+  reapOrphans() {
+    for (const name of readdirSync(this.dir)) {
+      if (!name.endsWith('.json')) continue;
+      let record;
+      try { record = JSON.parse(readFileSync(join(this.dir, name), 'utf8')); } catch { record = null; }
+      if (record) this.#end(record, 'daemon restarted');
+      rmSync(join(this.dir, name), { force: true });
+    }
+  }
+
+  /**
+   * Run `program args` as one owned job with its stdio carried by `stream` (base64 both ways).
+   * The child moves itself into its cgroup before it execs, so nothing it forks is outside.
+   */
+  run(stream, { kind, program, args, cwd }) {
+    const id = randomBytes(16).toString('hex');
+    if (kind === 'exec') args = [...args, id, join(this.dir, 'state')];
+    const group = this.cgroup ? join(this.cgroup, `job-${id}`) : null;
+    if (group) mkdirSync(group);
+    const argv = group
+      ? ['/bin/sh', '-c', 'echo $$ > "$0/cgroup.procs" && exec "$@"', group, program, ...args]
+      : [program, ...args];
+    const child = spawn(argv[0], argv.slice(1), { cwd, detached: true, stdio: ['pipe', 'pipe', 'inherit'] });
+    const record = { id, kind, pid: child.pid, cgroup: group, at: Date.now() };
+    writeFileSync(join(this.dir, `${id}.json`), JSON.stringify(record), { mode: 0o600 });
+    this.live.set(id, record);
+    child.stdout.on('data', (bytes) => { if (!stream.closed) stream.write(bytes.toString('base64')); });
+    stream.on('data', (chunk) => { if (!child.stdin.destroyed) child.stdin.write(Buffer.from(chunk, 'base64')); });
+    const finish = (reason) => {
+      if (!this.live.has(id)) return;
+      this.live.delete(id);
+      this.#end(record, reason);
+      rmSync(join(this.dir, `${id}.json`), { force: true });
+      if (!stream.closed) stream.close(reason);
+    };
+    stream.on('close', () => finish('stream closed'));
+    child.on('exit', () => {
+      // The endpoint has returned: whatever it left running goes with it.
+      child.stdout.once('end', () => finish('exited'));
+      if (child.stdout.readableEnded) finish('exited');
+    });
+    child.on('error', (error) => finish(error.message));
+    return record;
+  }
+
+  stopAll(reason = 'daemon stopped') {
+    for (const record of [...this.live.values()]) this.#end(record, reason);
+    this.live.clear();
+  }
+
+  #end(record, reason) {
+    if (record.cgroup) {
+      try { writeFileSync(join(record.cgroup, 'cgroup.kill'), '1'); } catch { /* already gone */ }
+      // The kernel empties the cgroup asynchronously; remove it once it is.
+      const remove = (tries) => {
+        try { rmdirSync(record.cgroup); } catch { if (tries > 0) setTimeout(() => remove(tries - 1), 100).unref?.(); }
+      };
+      remove(50);
+    } else if (record.pid) {
+      try { process.kill(-record.pid, 'SIGKILL'); } catch { /* already gone */ }
+    }
+    this.log({ job: record.id, kind: record.kind, cgroup: Boolean(record.cgroup), outcome: 'ended', reason });
+  }
+}
+
+/** The endpoints the `exec`, `sftp` and `exec-server` streams run. */
+export function streamProgram(name, params = {}, env = process.env) {
+  if (name === 'exec-server') {
+    const door = executionDoorFor(String(params.harness ?? ''));
+    if (door.door !== 'exec-server') return null;
+    const program = onPath(door.serve.program, env);
+    return program ? { program, args: [...door.serve.args] } : null;
+  }
+  if (name === 'sftp') {
+    const server = sftpServer();
+    return server ? { program: server, args: ['-e'] } : null;
+  }
+  if (name === 'exec') return { program: 'python3', args: [JOB_EXEC] };
+  return null;
+}
+
+/**
+ * A project moving between machines (docs/plans/remote-execution.md, decision 4). `export`
+ * streams `tar` of `path` once the caller writes `{"start": true}`; `import` writes what arrives into a staging directory beside `path`
+ * and publishes it (a rename) only when the sender's `{"commit": sha256}` names exactly the
+ * bytes received and `tar` accepted them, answering with the close reason. Anything else (a
+ * lost stream, a mismatch, an existing `path`) leaves `path` untouched and removes the staging.
+ */
+export function serveWorkspace(stream, { op, path }, { onEnd = () => {} } = {}) {
+  if (typeof path !== 'string' || !path.startsWith('/')) return stream.close('workspace path must be absolute');
+  if (op === 'export') {
+    if (!existsSync(path)) return stream.close(`no workspace at ${path}`);
+    // Nothing is sent before the caller's {start: true}: its listeners are attached by then, and
+    // a small project's every frame would otherwise race its open.
+    stream.once('data', () => {
+      const tar = spawn('tar', ['-C', path, '-cf', '-', '.'], { stdio: ['ignore', 'pipe', 'pipe'] });
+      tar.stdout.on('data', (bytes) => { if (!stream.closed) stream.write(bytes.toString('base64')); });
+      stream.on('close', () => tar.kill('SIGKILL'));
+      tar.on('close', (code) => { onEnd(code === 0 ? 'exported' : `tar exited ${code}`); if (!stream.closed) stream.close(code === 0 ? 'end' : `tar exited ${code}`); });
+    });
+    return;
+  }
+  if (op !== 'import') return stream.close('workspace op is export or import');
+  if (existsSync(path)) return stream.close(`discarded (${path} exists; a handoff never writes over a workspace)`);
+  const staging = `${path}.incoming-${randomBytes(6).toString('hex')}`;
+  mkdirSync(staging, { recursive: true, mode: 0o700 });
+  const hash = createHash('sha256');
+  const tar = spawn('tar', ['-C', staging, '-xf', '-'], { stdio: ['pipe', 'ignore', 'pipe'] });
+  tar.stdin.on('error', () => {}); // tar that exited early is answered at commit, not by a crash
+  const extracted = new Promise((resolveExtract) => tar.on('close', (code) => resolveExtract(code)));
+  let settled = false;
+  const settle = (outcome) => {
+    if (settled) return;
+    settled = true;
+    if (!outcome.startsWith('published')) rmSync(staging, { recursive: true, force: true });
+    onEnd(outcome);
+    if (!stream.closed) stream.close(outcome);
+  };
+  // Data frames are base64; the one frame that is not is the sender's commit, answered by the
+  // close reason: `published <sha256>` or `discarded (why)`.
+  stream.on('data', async (chunk) => {
+    if (!chunk.startsWith('{')) { const bytes = Buffer.from(chunk, 'base64'); hash.update(bytes); tar.stdin.write(bytes); return; }
+    let commit = null;
+    try { commit = JSON.parse(chunk).commit; } catch { /* not a commit */ }
+    tar.stdin.end();
+    const code = await extracted;
+    const digest = hash.digest('hex');
+    if (code !== 0) return settle(`discarded (tar exited ${code})`);
+    if (commit !== digest) return settle(`discarded (sender committed ${commit}, received ${digest})`);
+    if (existsSync(path)) return settle(`discarded (${path} appeared)`);
+    try { renameSync(staging, path); settle(`published ${digest}`); } catch (error) { settle(`discarded (${error.message})`); }
+  });
+  stream.on('close', () => { tar.stdin.end(); settle('discarded (the sender left before committing)'); });
+}

package/fleet.mjs

@@ -0,0 +1,78 @@
+// The fleet arms of supercode's own verbs: `discover --fleet|--on`,
+// `open --on`, and `harness drive --on`. A machine named with `--on` is an
+// enrolled machine of the selected Teams context, reached through its server;
+// without `--on` the verb acts on this OS user's own daemon.
+import { resolve } from 'node:path';
+import { SupercodeHarnessClient } from '@volter/supercode-harness-sdk';
+import { harnessTransport, nodeRpc, openRemoteMachine } from './client.mjs';
+import { openMachine } from './machine-door.mjs';
+import { WorkspaceContexts, fromContext } from './context.mjs';
+import { teamsHome } from '@volter/teams/home';
+
+/** Open the channel to the machine `name` names in `context` (or this box's daemon when name is null). */
+export function openOn(name = null, { context = null, env = process.env } = {}) {
+  return openMachine({ machine: name, context, env });
+}
+
+/**
+ * One `harness.v1` request over a channel's operator stream. The harness SDK
+ * runs unchanged: the channel is just its transport.
+ */
+export async function harnessRequest(channel, method, params = {}) {
+  const client = new SupercodeHarnessClient({ transport: harnessTransport(channel) });
+  try {
+    await client.start?.();
+    return await client.request(qualify(method), params);
+  } finally {
+    await client.close?.();
+  }
+}
+
+/** `sessions.discover` → `harness.v1.sessions.discover`; an already-qualified method is left alone. */
+export const qualify = (method) => (String(method).startsWith('harness.v1.') ? method : `harness.v1.${method}`);
+
+/** One node-door call (`launch`, `panes.list`, …) over a channel. */
+export async function nodeRequest(channel, method, params = {}) {
+  const rpc = await nodeRpc(channel);
+  return rpc.call(method, params);
+}
+
+/**
+ * Run `harness.v1.sessions.discover` on every machine of the selected context
+ * the caller can reach (or the named subset) and merge the answers into one
+ * page: each session carries the `machine` it was found on, and each machine
+ * that refused or is offline carries its reason. Nothing is stored.
+ */
+export async function fleetDiscover({ context = null, machines = null, params = {}, env = process.env } = {}) {
+  const home = teamsHome(env);
+  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 new Error('--fleet discovers the machines of a Teams context: `supercode teams login …`, then `supercode context use NAME` or --context NAME');
+  const { client, context: selected } = fromContext({ supercodeHome, name, fetch: globalThis.fetch });
+  const token = contexts.credential(selected.credential_ref).token;
+  const listed = (await client.team(selected.team_id).machines.list()).items.filter((item) => item.enrollment === 'active');
+  const targets = machines && machines.length
+    ? machines.map((wanted) => listed.find((item) => item.name === wanted || item.id === wanted) ?? { name: wanted, id: null })
+    : listed;
+  const results = await Promise.all(targets.map(async (machine) => {
+    if (!machine.id) return { name: machine.name, error: 'not an accessible machine of this team' };
+    let channel = null;
+    try {
+      channel = await openRemoteMachine({ origin: selected.origin, teamId: selected.team_id, machineId: machine.id, token });
+      const page = await harnessRequest(channel, 'harness.v1.sessions.discover', params);
+      return { name: machine.name, sessions: page?.sessions ?? [] };
+    } catch (error) {
+      return { name: machine.name, error: error.message ?? String(error) };
+    } finally {
+      channel?.close();
+    }
+  }));
+  const sessions = [];
+  const unreachable = [];
+  for (const result of results) {
+    if (result.error) unreachable.push({ machine: result.name, error: result.error });
+    else for (const session of result.sessions) sessions.push({ machine: result.name, ...session });
+  }
+  return { sessions, unreachable };
+}

package/index.mjs

@@ -0,0 +1,12 @@
+// @volter/supercode-teams: a machine daemon that serves this machine's
+// doors, and a Teams server that shares sessions and routes callers to enrolled
+// machines. Design: docs/plans/teams-server.md.
+export { MachineCore } from '@volter/teams/machine-core';
+export { TeamsMachine } from './machine.mjs';
+export { openLocalMachine, openRemoteMachine, harnessTransport, execServerBridge, nodeRpc, attachPane, attachRuntime, forwardPort, watchMachine, StreamRpc } from './client.mjs';
+export { openMachine } from './machine-door.mjs';
+export { Channel, ChannelStream, NODE_PROTOCOL } from '@volter/teams/channel';
+export { holds, targetsCover, admitFromGrants, LOCAL_OPERATOR } from '@volter/teams/admission';
+export { generateKeyPair, loadOrCreateKeyPair, publicKeyId, publicKeyPemFromId, fingerprint, signBytes, verifyBytes, canonical } from '@volter/teams/identity';
+export { teamsHome, supercodeHome, paths, readLimits, DEFAULT_LIMITS, AccountLog, Launches } from '@volter/teams/home';
+export { computeLabel, rankOf, notifies, judge, normalizeRank, DEFAULT_RANK, DEFAULT_NOTIFY, DEFAULT_STUCK_IDLE_SECONDS, LABELS, LIVENESS } from './attention.mjs';