@stage-labs/metro 0.1.0-beta.30 → 0.1.0-beta.301

package/runtime/node_modules/@metro-labs/daemon/src/connectors/org-runtime.ts

@@ -0,0 +1,327 @@
+import { log } from '@metro-labs/core/log';
+import { agentsDir } from '../agents/files.js';
+import { assertMigrationOutcomeKnown, beginMigrationOperation, migrationRequestEffectful, type MigrationOperation } from './migration-operations.js';
+import type { FetchLike } from '@metro-labs/core/stations/oauth';
+import type { ToolGroup } from '@metro-labs/core/stations/types';
+import { effectiveConnectorPolicy, type DeliveredConnector, type DeliverySnapshot } from '@metro-labs/http/connector-delivery';
+import type { ApiError } from '@metro-labs/http/api-error';
+import { requestConnectorBlocker, type GateRow } from './gates.js';
+import { publishOrgConnectors } from './publication.js';
+import type { MigrationRuntimeMapping } from './migration-guard.js';
+import { isOrgRelayId, orgRelayId } from './relay-id.js';
+import type { RelaySession } from './relay-session.js';
+import type { RelayTarget } from './relay-target.js';
+import type { OrgConnectorSync } from './org-sync.js';
+import { discoverOrgGroups, orgMissing, orgRuntimeError, orgSignin, orgUnavailable } from './org-runtime-discovery.js';
+
+interface RuntimeDeps {
+  enabled?: () => boolean;
+  mapping?: () => MigrationRuntimeMapping;
+  migrationDir?: string;
+  publish?: (rows: readonly GateRow[]) => void;
+  fetch?: FetchLike;
+}
+
+interface RuntimeRow extends DeliveredConnector {
+  relayId: string;
+  relayName: string;
+}
+
+interface Entry {
+  id: string;
+  relayId: string;
+  epoch: number;
+  stamp: string;
+  controller: AbortController;
+  groups: Record<string, ToolGroup>;
+  scan: Promise<void> | null;
+  nextScan: number;
+  error: ApiError | null;
+}
+
+interface Session {
+  entry: Entry;
+  operation: MigrationOperation | null;
+  controller: AbortController;
+  revision: string | null;
+  error: ApiError | null;
+}
+
+const stampOf = (row: RuntimeRow): string => JSON.stringify([
+  row.relayId, row.relayName, row.name, row.url, row.auth, row.policy.read ?? 'allow', row.policy.write ?? 'allow',
+  Object.entries(row.policy.tools ?? {}).sort(([a], [b]) => a.localeCompare(b)), row.policyLayers,
+]);
+
+const rowError = (row: DeliveredConnector | undefined): ApiError | null => {
+  if (row === undefined) return orgMissing();
+  if (row.state === 'signin') return orgSignin();
+  return row.state === 'ready' ? null : orgUnavailable();
+};
+
+const targetOf = (row: DeliveredConnector): RelayTarget => ({ kind: 'ok', url: row.url, headers: { ...row.headers } });
+
+const MAX_SCANS = 4;
+
+export class OrgConnectorRuntime {
+  private readonly entries = new Map<string, Entry>();
+  private readonly sessions = new Set<Session>();
+  private readonly unsubscribe: () => void;
+  private readonly timer: ReturnType<typeof setInterval>;
+  private published = '';
+  private stopped = false;
+  private scans = 0;
+  private readonly waiting: (() => void)[] = [];
+
+  constructor(private readonly sync: OrgConnectorSync, private readonly deps: RuntimeDeps = {}) {
+    this.unsubscribe = sync.onChange(() => { this.update(); });
+    this.timer = setInterval(() => {
+      try {
+        this.update();
+      } catch {
+        log.warn('organization connectors: runtime metadata could not be updated');
+      }
+    }, 1000);
+    this.timer.unref();
+    this.update();
+  }
+
+  private enabled(): boolean {
+    return !this.stopped && (this.deps.enabled?.() ?? process.env.METRO_CONNECTORS_LIVE_ENABLED === 'true');
+  }
+
+  private abort(session: Session, error: ApiError, drain = false): void {
+    session.error ??= error;
+    if (!drain) session.controller.abort();
+  }
+
+  private publish(rows: RuntimeRow[]): void {
+    const metadata: GateRow[] = rows.map((row) => ({
+      id: row.relayId, name: row.relayName,
+      config: { policy: effectiveConnectorPolicy(row, this.entries.get(row.id)?.groups ?? {}), toolGroups: { ...this.entries.get(row.id)?.groups } },
+    }));
+    const text = JSON.stringify(metadata);
+    if (text === this.published) return;
+    try {
+      (this.deps.publish ?? publishOrgConnectors)(metadata);
+      this.published = text;
+    } catch {
+      this.published = '';
+      for (const session of this.sessions) this.abort(session, orgUnavailable());
+      throw orgUnavailable();
+    }
+  }
+
+  private invalidateEntries(rows: RuntimeRow[], epoch: number, available: boolean): void {
+    for (const [id, entry] of this.entries) {
+      const row = rows.find((value) => value.id === id);
+      const valid = available && entry.epoch === epoch;
+      if (valid && row?.state === 'ready' && entry.stamp === stampOf(row)) continue;
+      const error = valid ? rowError(row) ?? orgUnavailable() : orgUnavailable();
+      this.invalidateEntry(entry, row, error);
+    }
+  }
+
+  private invalidateEntry(entry: Entry, row: RuntimeRow | undefined, error: ApiError): void {
+    const drain = !isOrgRelayId(entry.relayId) && row?.relayId !== entry.relayId;
+    if (!drain) entry.controller.abort();
+    this.entries.delete(entry.id);
+    this.abortEntry(entry, error, drain);
+  }
+
+  private abortEntry(entry: Entry, error: ApiError, drain = false): void {
+    for (const session of this.sessions) if (session.entry === entry) this.abort(session, error, drain);
+  }
+
+  private mappedRows(rows: DeliveredConnector[], mapping: MigrationRuntimeMapping): RuntimeRow[] {
+    return rows.flatMap((row) => {
+      const alias = mapping.aliases.find((value) => value.destinationId === row.id);
+      if (alias !== undefined) return [{ ...row, relayId: alias.sourceId, relayName: alias.name }];
+      return this.enabled() && !mapping.reserved.includes(row.id) ? [{ ...row, relayId: orgRelayId(row.id), relayName: row.name }] : [];
+    });
+  }
+
+  private mapping(): MigrationRuntimeMapping {
+    if (this.stopped) return { aliases: [], reserved: [] };
+    return this.deps.mapping?.() ?? { aliases: [], reserved: [] };
+  }
+
+  private update(): RuntimeRow[] | null {
+    try {
+      const mapping = this.mapping();
+      const wanted = this.enabled() || mapping.aliases.length > 0;
+      const snapshot = wanted ? this.sync.read() : null;
+      const epoch = this.sync.epoch();
+      if (this.held(snapshot, wanted, epoch)) return null;
+      const rows = this.mappedRows(snapshot?.connectors ?? [], mapping);
+      this.invalidateEntries(rows, epoch, snapshot !== null);
+      this.track(rows, epoch);
+      this.publish(rows);
+      return snapshot === null ? null : rows;
+    } catch {
+      this.invalidateEntries([], this.sync.epoch(), false);
+      this.publish([]);
+      throw orgUnavailable();
+    }
+  }
+
+  private track(rows: RuntimeRow[], epoch: number): void {
+    for (const row of rows) {
+      if (row.state !== 'ready' || this.entries.has(row.id)) continue;
+      this.entries.set(row.id, { id: row.id, relayId: row.relayId, epoch, stamp: stampOf(row), controller: new AbortController(), groups: {}, scan: null, nextScan: 0, error: null });
+    }
+  }
+
+  private held(snapshot: DeliverySnapshot | null, wanted: boolean, epoch: number): boolean {
+    if (snapshot !== null || !wanted || !this.sync.lapsed()) return false;
+    this.invalidateEntries([], epoch, false);
+    return true;
+  }
+
+  refresh(): void {
+    this.update();
+  }
+
+  idle(id?: string): boolean {
+    return ![...this.sessions].some((session) => id === undefined || session.entry.relayId === id);
+  }
+
+  private currentEntry(entry: Entry): DeliveredConnector {
+    const rows = this.update();
+    if (rows === null || entry.epoch !== this.sync.epoch()) throw orgUnavailable();
+    const row = rows.find((value) => value.id === entry.id);
+    if (row === undefined) throw orgMissing();
+    const error = rowError(row);
+    if (error !== null) throw error;
+    if (entry.controller.signal.aborted || this.entries.get(entry.id) !== entry) throw orgUnavailable();
+    if (!isOrgRelayId(entry.relayId)) assertMigrationOutcomeKnown(entry.relayId, this.deps.migrationDir);
+    return row;
+  }
+
+  private currentSession(session: Session): DeliveredConnector {
+    if (session.error !== null) throw session.error;
+    try {
+      return this.currentEntry(session.entry);
+    } catch (error) {
+      throw session.error ?? orgRuntimeError(error);
+    }
+  }
+
+  private async fresh(entry: Entry, refresh?: { connectorId: string; revision: string }): Promise<DeliveredConnector> {
+    this.currentEntry(entry);
+    try {
+      await this.sync.syncFresh(refresh);
+    } catch (error) {
+      throw orgRuntimeError(error);
+    }
+    return this.currentEntry(entry);
+  }
+
+  private migrationOperation(entry: Entry): MigrationOperation | null {
+    return isOrgRelayId(entry.relayId) ? null : beginMigrationOperation(entry.relayId, this.deps.migrationDir ?? agentsDir(), true);
+  }
+
+  private async scan(entry: Entry): Promise<void> {
+    const row = this.currentEntry(entry);
+    const signal = AbortSignal.any([entry.controller.signal, AbortSignal.timeout(45_000)]);
+    const operation = this.migrationOperation(entry);
+    try {
+      const send = this.deps.fetch ?? fetch;
+      const groups = await discoverOrgGroups(row.url, {
+        fresh: (revision) => this.fresh(entry, revision === undefined ? undefined : { connectorId: entry.id, revision }),
+        current: () => this.currentEntry(entry), signal,
+        fetch: (input, init) => operation?.dispatch(() => send(input, init), { effectful: migrationRequestEffectful(init?.method, init?.body) }) ?? send(input, init),
+      });
+      this.currentEntry(entry);
+      if (JSON.stringify(groups) !== JSON.stringify(entry.groups)) {
+        for (const session of this.sessions) if (session.entry === entry && session.revision !== null) this.abort(session, orgUnavailable());
+      }
+      entry.groups = groups;
+      entry.error = null;
+      entry.nextScan = performance.now() + 60_000;
+      this.update();
+    } finally { operation?.close(); }
+  }
+
+  private discover(entry: Entry): Promise<void> | null {
+    if (entry.scan !== null) return entry.scan;
+    if (performance.now() < entry.nextScan) {
+      if (entry.error !== null) {
+        log.debug({ stage: 'discovery_backoff', status: entry.error.status }, 'organization connectors: request unavailable');
+        throw entry.error;
+      }
+      return null;
+    }
+    entry.scan = this.queued(entry).catch((error: unknown) => {
+      entry.error = orgRuntimeError(error);
+      entry.nextScan = performance.now() + 30_000;
+      log.debug({ stage: 'tool_discovery', status: entry.error.status }, 'organization connectors: tool discovery failed');
+      throw entry.error;
+    }).finally(() => {
+      entry.scan = null;
+    });
+    return entry.scan;
+  }
+
+  private async queued(entry: Entry): Promise<void> {
+    while (this.scans >= MAX_SCANS) await new Promise<void>((resolve) => { this.waiting.push(resolve); });
+    this.scans += 1;
+    try {
+      await this.scan(entry);
+    } finally {
+      this.scans -= 1;
+      this.waiting.shift()?.();
+    }
+  }
+
+  private async target(session: Session, force: boolean): Promise<RelayTarget> {
+    this.currentSession(session);
+    if (force && session.revision === null) throw orgUnavailable();
+    const refresh = force && session.revision !== null ? { connectorId: session.entry.id, revision: session.revision } : undefined;
+    await this.fresh(session.entry, refresh);
+    this.currentSession(session);
+    const discovery = this.discover(session.entry);
+    if (discovery !== null) {
+      await discovery;
+      this.currentSession(session);
+      await this.fresh(session.entry);
+    }
+    return targetOf(this.currentSession(session));
+  }
+
+  open(id: string): RelaySession {
+    const rows = this.update();
+    if (rows === null) throw orgUnavailable();
+    const mapped = rows.find((row) => row.relayId === id);
+    const error = rowError(mapped);
+    if (error !== null) throw error;
+    const entry = mapped === undefined ? undefined : this.entries.get(mapped.id);
+    if (entry === undefined) throw orgUnavailable();
+    const session: Session = { entry, operation: this.migrationOperation(entry), controller: new AbortController(), revision: null, error: null };
+    this.sessions.add(session);
+    const blocker = requestConnectorBlocker();
+    return {
+      dispatch: (send, effectful) => { this.currentSession(session); return session.operation?.dispatch(send, { effectful }) ?? send(); },
+      target: (force) => this.target(session, force),
+      current: () => {
+        const row = this.currentSession(session);
+        session.revision = row.revision;
+        return targetOf(row);
+      },
+      blocker: () => {
+        this.currentSession(session);
+        return blocker();
+      },
+      signal: session.controller.signal,
+      close: () => { this.abort(session, orgUnavailable()); session.operation?.close(); this.sessions.delete(session); },
+    };
+  }
+
+  stop(keepPublished = false): void {
+    if (this.stopped) return;
+    this.stopped = true;
+    this.unsubscribe();
+    clearInterval(this.timer);
+    if (keepPublished) this.invalidateEntries([], this.sync.epoch(), false);
+    else this.update();
+  }
+}

package/runtime/node_modules/@metro-labs/daemon/src/connectors/org-sync-api.ts

@@ -0,0 +1,25 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { ConnectorSyncStatus } from '@metro-labs/core/connector-sync';
+import { isRecord } from '@metro-labs/core/is-record';
+import { ApiError } from '@metro-labs/http/api-error';
+import { readJsonBody, sessionRoute } from '@metro-labs/http/api-http';
+
+const PATH = '/api/connectors/sync';
+
+export interface ConnectorSyncApiDeps {
+  status: () => ConnectorSyncStatus;
+  set: (enabled: boolean, scope: string) => ConnectorSyncStatus;
+}
+
+export function handleConnectorSyncRequest(req: IncomingMessage, res: ServerResponse, deps: ConnectorSyncApiDeps): boolean {
+  return sessionRoute(req, res, { methods: { [PATH]: ['GET', 'PUT'] }, admin: true, label: 'connector-sync-api' }, async (session) => {
+    const body = req.method === 'PUT' ? await readJsonBody(req) : null;
+    const current = deps.status();
+    if (current.owner === null || current.owner !== session.subject) throw new ApiError('This agent belongs to another organization.', 403);
+    if (req.method !== 'PUT') return current;
+    if (!isRecord(body) || typeof body.enabled !== 'boolean' || typeof body.scope !== 'string' || !/^[a-f0-9]{64}$/.test(body.scope) || Object.keys(body).some((key) => key !== 'enabled' && key !== 'scope')) {
+      throw new ApiError('Sync needs an enabled flag and the current enrollment scope.', 400);
+    }
+    return deps.set(body.enabled, body.scope);
+  });
+}

package/runtime/node_modules/@metro-labs/daemon/src/connectors/org-sync-control.ts

@@ -0,0 +1,191 @@
+import { createHash, randomBytes } from 'node:crypto';
+import type { ConnectorSyncStatus } from '@metro-labs/core/connector-sync';
+import { log } from '@metro-labs/core/log';
+import { ApiError } from '@metro-labs/http/api-error';
+import { agentsDir } from '../agents/files.js';
+import { METRO_API, type MetroApi } from './metro-api.js';
+import { OrgConnectorSync, type OrgSyncDeps } from './org-sync.js';
+import { OrgConnectorRuntime } from './org-runtime.js';
+import { connectorSyncScope, disableSavedSync, saveSyncSetting, syncOptedIn, syncSetting } from './org-sync-setting.js';
+import type { RelaySession } from './relay-session.js';
+import type { DeliverySnapshot } from '@metro-labs/http/connector-delivery';
+import { localMigrationIdle, migrationRuntimeMapping } from './migration-guard.js';
+import { publishConnectors } from './publication.js';
+import { orgRuntimeError, orgUnavailable } from './org-runtime-discovery.js';
+
+type ControlDeps = Pick<OrgSyncDeps, 'owner' | 'key' | 'monotonic'> & { api?: MetroApi; dir?: string };
+type Context = Pick<ConnectorSyncStatus, 'owner' | 'agentId' | 'scope' | 'enrolled'>;
+const POLL_MS = 60_000;
+const liveEnabled = (): boolean => process.env.METRO_CONNECTORS_LIVE_ENABLED === 'true';
+const emptyReceipt = { lastReceivedAt: null, leaseExpiresAt: null, counts: null };
+
+export class OrgConnectorControl {
+  private readonly dir: string;
+  private readonly api: MetroApi;
+  private sync: OrgConnectorSync | null = null;
+  private runtime: OrgConnectorRuntime | null = null;
+  private readonly draining = new Set<OrgConnectorRuntime>();
+  private scope: string | null = null;
+  private operation = randomBytes(16).toString('hex');
+  private timer: ReturnType<typeof setInterval> | null = null;
+
+  constructor(private readonly deps: ControlDeps) {
+    this.dir = deps.dir ?? agentsDir();
+    this.api = deps.api ?? METRO_API;
+  }
+
+  private context(): Context {
+    const owner = this.deps.owner();
+    const key = this.deps.key();
+    const enrollment = key?.enrollment;
+    const agentId = owner !== null && enrollment?.organization === owner ? enrollment.server : null;
+    const scope = connectorSyncScope(owner, key);
+    return { owner, agentId, scope, enrolled: agentId !== null };
+  }
+
+  private clear(keepPublished = false): void {
+    const runtime = this.runtime;
+    if (keepPublished) runtime?.stop(true);
+    this.sync?.invalidate();
+    this.sync = null;
+    this.runtime = null;
+    this.retire(runtime);
+  }
+
+  private retire(runtime: OrgConnectorRuntime | null): void {
+    for (const previous of this.draining) if (previous.idle()) this.draining.delete(previous);
+    if (runtime === null) return;
+    if (!runtime.idle()) this.draining.add(runtime);
+    try {
+      runtime.stop();
+    } catch {
+      log.warn('organization connectors: stopped runtime publication could not be cleared');
+    }
+  }
+
+  private reconcile(start: boolean): { context: Context; setting: ReturnType<typeof syncSetting> } {
+    const context = this.context();
+    if (this.scope !== null && this.scope !== context.scope) {
+      this.clear();
+      this.operation = randomBytes(16).toString('hex');
+      disableSavedSync(this.dir);
+    }
+    this.scope = context.scope;
+    const setting = syncSetting(this.dir, context.scope);
+    if (setting.source === 'scope_changed') disableSavedSync(this.dir);
+    if (!setting.enabled || !context.enrolled) this.clear();
+    else if (start && this.sync === null) {
+      const scope = context.scope;
+      this.sync = new OrgConnectorSync({ ...this.deps, api: this.api, enabled: () => this.context().scope === scope && syncSetting(this.dir, scope).enabled });
+    }
+    if (start) this.startRuntime();
+    return { context, setting };
+  }
+
+  private startRuntime(): void {
+    if (this.sync === null || this.runtime !== null) return;
+    const mapping = () => migrationRuntimeMapping(this.deps.owner(), this.deps.key(), this.dir);
+    if (liveEnabled() || mapping().aliases.length > 0) this.runtime = new OrgConnectorRuntime(this.sync, { enabled: liveEnabled, mapping, migrationDir: this.dir });
+  }
+
+  status(): ConnectorSyncStatus {
+    try {
+      const { context, setting } = this.reconcile(false);
+      const receipt = this.sync?.status() ?? { state: 'waiting' as const, ...emptyReceipt };
+      const state = !setting.enabled ? 'off' : !context.enrolled ? 'not_enrolled' : receipt.state;
+      const scope = createHash('sha256').update(`${context.scope}:${this.operation}`).digest('hex');
+      return { ...context, ...setting, ...receipt, scope, state, liveEnabled: liveEnabled() };
+    } catch {
+      this.clear();
+      throw new ApiError('Metro could not read the connector sync status.', 503);
+    }
+  }
+
+  set(enabled: boolean, scope: string): ConnectorSyncStatus {
+    const current = this.status();
+    if (scope !== current.scope) throw new ApiError('The organization or enrollment changed. Refresh the sync status before trying again.', 409);
+    if (enabled && !current.enrolled) throw new ApiError('Enroll this agent with its organization before enabling sync.', 409);
+    if (enabled && liveEnabled()) throw new ApiError('Live organization tools are enabled separately on this server. Disable that setting before enabling memory-only sync here.', 409);
+    saveSyncSetting(this.dir, enabled, this.context().scope);
+    if (!enabled) this.clear();
+    else this.tick();
+    return this.status();
+  }
+
+  async poll(): Promise<void> {
+    if (this.sync === null && !syncOptedIn(this.dir)) return;
+    try {
+      this.reconcile(true);
+    } catch (err) {
+      this.clear();
+      throw err;
+    }
+    await this.sync?.sync();
+  }
+
+  async fresh(): Promise<DeliverySnapshot> {
+    this.reconcile(true);
+    const sync = this.sync;
+    if (sync === null) throw new ApiError('Enable organization connector sync before moving this connector.', 409);
+    await sync.syncFresh();
+    this.reconcile(false);
+    const snapshot = this.sync === sync ? sync.read() : null;
+    if (snapshot === null) throw new ApiError('A fresh organization connector snapshot is unavailable.', 503);
+    return snapshot;
+  }
+
+  refreshRuntime(): void {
+    this.reconcile(true);
+    this.runtime?.refresh();
+    publishConnectors();
+  }
+
+  migrationIdle(id: string): boolean {
+    for (const runtime of this.draining) if (runtime.idle()) this.draining.delete(runtime);
+    return localMigrationIdle(id, this.dir) && (this.runtime?.idle(id) ?? true) && [...this.draining].every((runtime) => runtime.idle(id));
+  }
+
+  private tick(): void {
+    this.poll().catch(() => {
+      log.warn('organization connectors: memory sync unavailable; cached credentials were cleared');
+    });
+  }
+
+  start(): void {
+    if (this.timer !== null) return;
+    this.tick();
+    this.timer = setInterval(() => { this.tick(); }, POLL_MS);
+    this.timer.unref();
+  }
+
+  invalidate(): void {
+    this.operation = randomBytes(16).toString('hex');
+    this.clear();
+    disableSavedSync(this.dir);
+  }
+
+  stop(keepPublished = false): void {
+    if (this.timer !== null) clearInterval(this.timer);
+    this.timer = null;
+    this.clear(keepPublished);
+  }
+
+  async open(id: string): Promise<RelaySession> {
+    if (this.runtime === null && !syncOptedIn(this.dir)) throw new ApiError('Organization connectors are not available on this agent.', 503);
+    this.reconcile(true);
+    const runtime = this.runtime;
+    const sync = this.sync;
+    if (runtime === null || sync === null) throw new ApiError('Organization connectors are not available on this agent.', 503);
+    const state = sync.status().state;
+    try {
+      await sync.recover();
+      this.reconcile(false);
+      if (this.runtime !== runtime || this.sync !== sync) throw orgUnavailable();
+    } catch (error) {
+      const safe = orgRuntimeError(error);
+      log.debug({ stage: 'receipt_open', state, status: safe.status }, 'organization connectors: request unavailable');
+      throw safe;
+    }
+    return runtime.open(id);
+  }
+}

package/runtime/node_modules/@metro-labs/daemon/src/connectors/org-sync-setting.ts

@@ -0,0 +1,60 @@
+import { createHash } from 'node:crypto';
+import type { AgentKey } from './agent-key.js';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import type { ConnectorSyncStatus } from '@metro-labs/core/connector-sync';
+import { isRecord } from '@metro-labs/core/is-record';
+import { writeSecure } from '@metro-labs/core/secure-fs';
+import { ApiError } from '@metro-labs/http/api-error';
+
+interface SavedSetting {
+  version: 1;
+  enabled: boolean;
+  scope: string;
+}
+
+type Stored = SavedSetting | 'absent' | 'invalid';
+const pathOf = (dir: string): string => join(dir, 'org-connector-sync.json');
+
+function read(dir: string): Stored {
+  let raw: unknown;
+  try {
+    raw = JSON.parse(readFileSync(pathOf(dir), 'utf8')) as unknown;
+  } catch (err) {
+    return isRecord(err) && err.code === 'ENOENT' ? 'absent' : 'invalid';
+  }
+  if (!isRecord(raw) || raw.version !== 1 || typeof raw.enabled !== 'boolean' || typeof raw.scope !== 'string' || !/^[a-f0-9]{64}$/.test(raw.scope)) return 'invalid';
+  return { version: 1, enabled: raw.enabled, scope: raw.scope };
+}
+
+export function connectorSyncScope(owner: string | null, key: AgentKey | null): string {
+  const agentId = owner !== null && key?.enrollment?.organization === owner ? key.enrollment.server : null;
+  return createHash('sha256').update(JSON.stringify([owner, agentId, key?.keyId ?? null, key?.sealingKey ?? null])).digest('hex');
+}
+
+export function syncOptedIn(dir: string): boolean {
+  const saved = read(dir);
+  if (saved === 'absent') return process.env.METRO_CONNECTORS_SYNC_ENABLED === 'true';
+  return saved !== 'invalid' && saved.enabled;
+}
+
+export function syncSetting(dir: string, scope: string): Pick<ConnectorSyncStatus, 'enabled' | 'source'> {
+  const saved = read(dir);
+  if (saved === 'invalid') return { enabled: false, source: 'invalid' };
+  if (saved === 'absent') return process.env.METRO_CONNECTORS_SYNC_ENABLED === 'true' ? { enabled: true, source: 'environment' } : { enabled: false, source: 'default' };
+  if (saved.scope !== scope) return { enabled: false, source: 'scope_changed' };
+  return { enabled: saved.enabled, source: 'saved' };
+}
+
+export function saveSyncSetting(dir: string, enabled: boolean, scope: string): void {
+  try {
+    writeSecure(pathOf(dir), `${JSON.stringify({ version: 1, enabled, scope })}\n`);
+  } catch {
+    throw new ApiError('Metro could not save the connector sync setting.', 503);
+  }
+}
+
+export function disableSavedSync(dir: string): void {
+  const saved = read(dir);
+  if (typeof saved !== 'string' && saved.enabled) saveSyncSetting(dir, false, saved.scope);
+}

package/runtime/node_modules/@metro-labs/daemon/src/connectors/org-sync-watch.ts

@@ -0,0 +1,53 @@
+import { ApiError } from '@metro-labs/http/api-error';
+import type { ConnectorSyncStatus } from '@metro-labs/core/connector-sync';
+import { OrgConnectorControl } from './org-sync-control.js';
+import { isOrgRelayId } from './relay-id.js';
+import type { RelaySession } from './relay-session.js';
+import type { DeliverySnapshot } from '@metro-labs/http/connector-delivery';
+import { migrationSource } from './migration-guard.js';
+
+let active: OrgConnectorControl | null = null;
+
+function control(): OrgConnectorControl {
+  if (active === null) throw new ApiError('Organization connector sync is unavailable. Restart Metro before trying again.', 503);
+  return active;
+}
+
+export function orgConnectorRelaySession(id: string): Promise<RelaySession> | null {
+  return isOrgRelayId(id) || migrationSource(id)?.phase === 'active' ? control().open(id) : null;
+}
+
+export function freshOrgConnectors(): Promise<DeliverySnapshot> {
+  return control().fresh();
+}
+
+export function refreshOrgConnectorRuntime(): void {
+  control().refreshRuntime();
+}
+
+export function orgConnectorMigrationIdle(id: string): boolean {
+  return control().migrationIdle(id);
+}
+
+export function orgConnectorSyncStatus(): ConnectorSyncStatus {
+  return control().status();
+}
+
+export function setOrgConnectorSync(enabled: boolean, scope: string): ConnectorSyncStatus {
+  return control().set(enabled, scope);
+}
+
+export function invalidateOrgConnectorSync(): void {
+  active?.invalidate();
+}
+
+export function stopOrgConnectorSync(keepPublished = false): void {
+  active?.stop(keepPublished);
+  active = null;
+}
+
+export function watchOrgConnectorSync(deps: ConstructorParameters<typeof OrgConnectorControl>[0]): void {
+  stopOrgConnectorSync();
+  active = new OrgConnectorControl(deps);
+  active.start();
+}