agent-relay-server 0.33.0 → 0.33.1

package/src/db/orchestrators.ts

@@ -0,0 +1,358 @@
+import { Database } from "bun:sqlite";
+import { randomUUID } from "node:crypto";
+import { isRecord, stringValue, isMechanicalMessageKind } from "agent-relay-sdk";
+import { ORCHESTRATOR_PROTOCOL_VERSION, VERSION } from "../config.ts";
+import { parseJson } from "../utils";
+import { isLiveIsolatedWorkspace } from "../workspace-phase";
+import {
+  CONTRACT_REQUIREMENTS,
+  contractCompatibility,
+  parseRuntimeCapabilities,
+  parseRuntimeContracts,
+  parseRuntimePackage,
+  type RuntimeContracts,
+} from "../contracts";
+import { STALE_TTL_MS, DAY_MS, CLAIM_LEASE_MS, POOL_CLAIM_LEASE_MS, WORKSPACE_MERGE_LEASE_MS } from "../config";
+import { matchAgents } from "../agent-ref";
+import { deleteAgent, heartbeat, upsertAgent } from "./agents.ts";
+import { getDb } from "./connection.ts";
+import { electWorkspaceStewards, getWorkspace, upsertWorkspaceFromManagedAgent } from "./workspaces.ts";
+import type {
+  AgentCard,
+  ActivityEvent,
+  ActivityEventInput,
+  AgentKind,
+  AgentSessionGuard,
+  Artifact,
+  ArtifactBlob,
+  ArtifactKind,
+  ArtifactLink,
+  ArtifactSensitivity,
+  ArtifactVisibility,
+  AttachmentRef,
+  ChannelBinding,
+  ChannelBindingMode,
+  ChannelRouteTarget,
+  ChatHistoryImport,
+  ChatHistoryImportEntry,
+  ChannelSummary,
+  ChannelTargetHealth,
+  CreatePairInput,
+  HealthCheck,
+  HealthReport,
+  ManagedAgent,
+  ManagedSessionExitDiagnostics,
+  Message,
+  MessageDeliveryAttempt,
+  MessageDeliveryStatus,
+  Orchestrator,
+  OrchestratorHealth,
+  OrchestratorRuntimeInput,
+  OrchestratorStatus,
+  OrchestratorUpgradeState,
+  PairActionInput,
+  PairMessageInput,
+  PairSession,
+  PairStatus,
+  RegisterAgentInput,
+  ReplyObligation,
+  RegisterOrchestratorInput,
+  SendMessageInput,
+  PollQuery,
+  SpawnApprovalMode,
+  SpawnProvider,
+  Task,
+  TaskEvent,
+  TaskSeverity,
+  TaskStatus,
+  IntegrationEventInput,
+  IntegrationSummary,
+  IntegrationTaskStats,
+  InboxDraft,
+  InboxState,
+  InboxThreadState,
+  ContextSnapshot,
+  ContextState,
+  ProviderCapabilities,
+  TaskStatusInput,
+  WorkspaceMetadata,
+  WorkspaceRecord,
+  WorkspaceStatus,
+} from "../types";
+
+// --- Orchestrators ---
+
+export function rowToOrchestrator(row: any): Orchestrator {
+  const meta = parseJson<Record<string, unknown>>(row.meta, {});
+  const runtimePackage = parseRuntimePackage(meta.package);
+  const version = stringValue(meta.version);
+  const gitSha = stringValue(meta.gitSha);
+  const protocolRaw = meta.protocolVersion;
+  const protocolVersion = typeof protocolRaw === "number"
+    ? protocolRaw
+    : typeof protocolRaw === "string" && protocolRaw.trim() !== ""
+      ? Number(protocolRaw)
+      : undefined;
+  const contracts = parseRuntimeContracts(meta.contracts, Number.isFinite(protocolVersion) ? { orchestratorProtocol: protocolVersion } : {});
+  const capabilities = parseRuntimeCapabilities(meta.capabilities);
+  const providerStatus = Array.isArray(meta.providerStatus) ? meta.providerStatus as Orchestrator["providerStatus"] : undefined;
+  const providerCatalog = Array.isArray(meta.providerCatalog) ? meta.providerCatalog as Orchestrator["providerCatalog"] : undefined;
+  const compatibility = contractCompatibility(contracts, { orchestratorProtocol: CONTRACT_REQUIREMENTS.orchestratorProtocol });
+  const supervisorRaw = stringValue(meta.supervisor);
+  const supervisor = supervisorRaw === "systemd" || supervisorRaw === "launchd" || supervisorRaw === "process" || supervisorRaw === "unknown" ? supervisorRaw : undefined;
+  const selfUnit = stringValue(meta.selfUnit);
+  const runtimePrefix = stringValue(meta.runtimePrefix);
+  const upgrade = parseOrchestratorUpgrade(meta.upgrade);
+  return {
+    id: row.id,
+    hostname: row.hostname,
+    status: row.status as OrchestratorStatus,
+    agentId: row.agent_id,
+    providers: parseJson<SpawnProvider[]>(row.providers, []),
+    ...(providerStatus ? { providerStatus } : {}),
+    ...(providerCatalog ? { providerCatalog } : {}),
+    baseDir: row.base_dir,
+    ...(row.api_url ? { apiUrl: row.api_url } : {}),
+    envKeys: parseJson<string[]>(row.env_keys, []),
+    ...(runtimePackage ? { package: runtimePackage } : {}),
+    ...(Object.keys(contracts).length ? { contracts } : {}),
+    ...(Object.keys(capabilities).length ? { capabilities } : {}),
+    contractCompatibility: compatibility,
+    ...(version ? { version } : {}),
+    ...(Number.isFinite(protocolVersion) ? { protocolVersion } : {}),
+    ...(gitSha ? { gitSha } : {}),
+    health: orchestratorHealth(version, compatibility),
+    ...(supervisor ? { supervisor } : {}),
+    ...(selfUnit ? { selfUnit } : {}),
+    ...(runtimePrefix ? { runtimePrefix } : {}),
+    ...(upgrade ? { upgrade } : {}),
+    meta,
+    managedAgents: parseJson<ManagedAgent[]>(row.managed_agents, []),
+    lastSeen: row.last_seen,
+    createdAt: row.created_at,
+  };
+}
+
+export function parseOrchestratorUpgrade(value: unknown): OrchestratorUpgradeState | undefined {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+  const v = value as Record<string, unknown>;
+  const desiredVersion = stringValue(v.desiredVersion);
+  const status = v.status;
+  if (!desiredVersion || (status !== "pending" && status !== "succeeded" && status !== "failed")) return undefined;
+  return {
+    desiredVersion,
+    status,
+    ...(stringValue(v.commandId) ? { commandId: stringValue(v.commandId) } : {}),
+    ...(Array.isArray(v.providers) ? { providers: v.providers.filter((p): p is string => typeof p === "string") } : {}),
+    ...(stringValue(v.fromVersion) ? { fromVersion: stringValue(v.fromVersion) } : {}),
+    ...(stringValue(v.requestedBy) ? { requestedBy: stringValue(v.requestedBy) } : {}),
+    requestedAt: typeof v.requestedAt === "number" ? v.requestedAt : 0,
+    ...(typeof v.settledAt === "number" ? { settledAt: v.settledAt } : {}),
+    ...(stringValue(v.error) ? { error: stringValue(v.error) } : {}),
+  };
+}
+
+/**
+ * Set or clear the orchestrator's in-flight/last upgrade state. Stored in the
+ * meta blob (no schema change). Pass null to clear.
+ */
+export function setOrchestratorUpgradeState(id: string, state: OrchestratorUpgradeState | null): Orchestrator | null {
+  const row = getDb().query("SELECT meta FROM orchestrators WHERE id = ?").get(id) as { meta?: string } | undefined;
+  if (!row) return null;
+  const meta = parseJson<Record<string, unknown>>(row.meta ?? "{}", {});
+  if (state) meta.upgrade = state;
+  else delete meta.upgrade;
+  getDb().query("UPDATE orchestrators SET meta = ? WHERE id = ?").run(JSON.stringify(meta), id);
+  return getOrchestrator(id);
+}
+
+
+export function orchestratorHealth(version: string | undefined, compatibility: ReturnType<typeof contractCompatibility>): OrchestratorHealth {
+  const issues: OrchestratorHealth["issues"] = [];
+  if (!version) {
+    issues.push({ code: "missing-version", detail: "Orchestrator did not report a package version." });
+  } else if (version !== VERSION) {
+    issues.push({ code: "package-drift", detail: `Orchestrator package ${version} differs from server package ${VERSION}; contract compatibility decides runtime health.` });
+  }
+
+  for (const issue of compatibility.issues) {
+    issues.push({
+      code: issue.actual === undefined ? "missing-contract" : "protocol-mismatch",
+      detail: issue.actual === undefined
+        ? `Orchestrator did not report ${issue.contract}; expected ${issue.expected}.`
+        : `Orchestrator ${issue.contract} ${issue.actual} is incompatible; expected ${issue.expected}.`,
+    });
+  }
+
+  if (compatibility.status === "incompatible") {
+    issues.push({ code: "upgrade-required", detail: "Upgrade the orchestrator to a compatible protocol before relying on host lifecycle control." });
+  } else if (compatibility.status === "unknown") {
+    issues.push({ code: "restart-required", detail: "Restart or upgrade the orchestrator so it reports runtime contract metadata." });
+  }
+
+  return {
+    status: compatibility.status === "incompatible"
+      ? "upgrade-required"
+      : compatibility.status === "unknown"
+        ? "unknown"
+        : issues.length > 0
+          ? "warn"
+          : "ok",
+    restartRequired: compatibility.status === "unknown",
+    upgradeRequired: compatibility.status === "incompatible",
+    issues,
+  };
+}
+
+export function mergeOrchestratorRuntimeMeta(meta: Record<string, unknown>, input: OrchestratorRuntimeInput): Record<string, unknown> {
+  const contracts = parseRuntimeContracts(input.contracts, input.protocolVersion !== undefined ? { orchestratorProtocol: input.protocolVersion } : {});
+  const capabilities = parseRuntimeCapabilities(input.capabilities);
+  return {
+    ...meta,
+    ...(input.package ? { package: input.package } : {}),
+    ...(Object.keys(contracts).length ? { contracts: { ...(parseRuntimeContracts(meta.contracts) as RuntimeContracts), ...contracts } } : {}),
+    ...(Object.keys(capabilities).length ? { capabilities: { ...parseRuntimeCapabilities(meta.capabilities), ...capabilities } } : {}),
+    ...(input.version ? { version: input.version } : {}),
+    ...(input.protocolVersion !== undefined ? { protocolVersion: input.protocolVersion } : {}),
+    ...(input.gitSha ? { gitSha: input.gitSha } : {}),
+    ...(input.providers ? { providers: input.providers } : {}),
+    ...(input.providerStatus ? { providerStatus: input.providerStatus } : {}),
+    ...(input.providerCatalog ? { providerCatalog: input.providerCatalog } : {}),
+  };
+}
+
+export function upsertOrchestrator(input: RegisterOrchestratorInput): Orchestrator {
+  const now = Date.now();
+  const agentId = `orchestrator-${input.id}`;
+  // Carry forward server-managed meta the orchestrator never reports (upgrade
+  // state) — registration meta would otherwise drop it on the very re-register
+  // that follows a self-upgrade restart, breaking version reconciliation.
+  const existingRow = getDb().query("SELECT meta FROM orchestrators WHERE id = ?").get(input.id) as { meta?: string } | undefined;
+  const existingMeta = existingRow ? parseJson<Record<string, unknown>>(existingRow.meta ?? "{}", {}) : {};
+  const mergedMeta = mergeOrchestratorRuntimeMeta(input.meta ?? {}, input);
+  if (existingMeta.upgrade !== undefined && mergedMeta.upgrade === undefined) mergedMeta.upgrade = existingMeta.upgrade;
+  const stmt = getDb().query(`
+    INSERT INTO orchestrators (id, hostname, status, agent_id, providers, base_dir, api_url, env_keys, meta, last_seen, created_at)
+    VALUES ($id, $hostname, 'online', $agentId, $providers, $baseDir, $apiUrl, $envKeys, $meta, $now, $now)
+    ON CONFLICT(id) DO UPDATE SET
+      hostname = $hostname,
+      status = 'online',
+      providers = $providers,
+      base_dir = $baseDir,
+      api_url = $apiUrl,
+      env_keys = $envKeys,
+      meta = $meta,
+      last_seen = $now
+  `);
+  stmt.run({
+    $id: input.id,
+    $hostname: input.hostname,
+    $agentId: agentId,
+    $providers: JSON.stringify(input.providers),
+    $baseDir: input.baseDir,
+    $apiUrl: input.apiUrl ?? null,
+    $envKeys: JSON.stringify(input.envKeys ?? []),
+    $meta: JSON.stringify(mergedMeta),
+    $now: now,
+  });
+
+  // Also register as an agent so the orchestrator can receive messages
+  upsertAgent({
+    id: agentId,
+    name: `Orchestrator (${input.hostname})`,
+    tags: ["orchestrator", input.hostname],
+    machine: input.hostname,
+    capabilities: ["orchestrator", "spawn"],
+    status: "online",
+    ready: true,
+    meta: {
+      orchestratorId: input.id,
+      builtin: true,
+      ...(input.package ? { package: input.package } : {}),
+      ...(input.contracts ? { contracts: input.contracts } : {}),
+      ...(input.capabilities ? { capabilities: input.capabilities } : {}),
+      ...(input.version ? { version: input.version } : {}),
+      ...(input.protocolVersion !== undefined ? { protocolVersion: input.protocolVersion } : {}),
+      ...(input.gitSha ? { gitSha: input.gitSha } : {}),
+    },
+  });
+
+  return getOrchestrator(input.id)!;
+}
+
+export function getOrchestrator(id: string): Orchestrator | null {
+  const row = getDb().query("SELECT * FROM orchestrators WHERE id = ?").get(id) as any;
+  return row ? rowToOrchestrator(row) : null;
+}
+
+export function listOrchestrators(): Orchestrator[] {
+  return (getDb().query("SELECT * FROM orchestrators ORDER BY hostname").all() as any[]).map(rowToOrchestrator);
+}
+
+export function orchestratorHeartbeat(id: string, runtime: OrchestratorRuntimeInput = {}): Orchestrator | null {
+  const now = Date.now();
+  const row = getDb().query("SELECT meta FROM orchestrators WHERE id = ?").get(id) as { meta?: string } | undefined;
+  if (!row) return null;
+  const meta = mergeOrchestratorRuntimeMeta(parseJson<Record<string, unknown>>(row.meta ?? "{}", {}), runtime);
+  if (runtime.providers) {
+    getDb().query("UPDATE orchestrators SET last_seen = ?, status = 'online', providers = ?, meta = ? WHERE id = ?")
+      .run(now, JSON.stringify(runtime.providers), JSON.stringify(meta), id);
+  } else {
+    getDb().query("UPDATE orchestrators SET last_seen = ?, status = 'online', meta = ? WHERE id = ?").run(now, JSON.stringify(meta), id);
+  }
+  // Also heartbeat the agent
+  const orch = getOrchestrator(id);
+  if (orch) {
+    heartbeat(orch.agentId);
+  }
+  return orch;
+}
+
+export function updateManagedAgents(id: string, agents: ManagedAgent[]): Orchestrator | null {
+  for (const agent of agents) upsertWorkspaceFromManagedAgent(agent);
+  electWorkspaceStewards();
+  const enriched = agents.map((agent) => {
+    const workspaceId = agent.workspace?.id;
+    const workspace = workspaceId ? getWorkspace(workspaceId) : null;
+    return workspace ? {
+      ...agent,
+      workspace: {
+        ...agent.workspace,
+        id: workspace.id,
+        status: workspace.status,
+        stewardAgentId: workspace.stewardAgentId,
+        repoRoot: workspace.repoRoot,
+        sourceCwd: workspace.sourceCwd,
+        worktreePath: workspace.worktreePath,
+        branch: workspace.branch,
+        baseRef: workspace.baseRef,
+        baseSha: workspace.baseSha,
+      },
+    } : agent;
+  });
+  getDb().query("UPDATE orchestrators SET managed_agents = ?, last_seen = ? WHERE id = ?")
+    .run(JSON.stringify(enriched), Date.now(), id);
+  return getOrchestrator(id);
+}
+
+
+export function deleteOrchestrator(id: string): boolean {
+  const orch = getOrchestrator(id);
+  if (!orch) return false;
+  getDb().query("DELETE FROM orchestrators WHERE id = ?").run(id);
+  deleteAgent(orch.agentId);
+  return true;
+}
+
+export function reapStaleOrchestrators(): string[] {
+  const cutoff = Date.now() - STALE_TTL_MS;
+  const stale = getDb().query("SELECT id, agent_id FROM orchestrators WHERE last_seen < ? AND status = 'online'").all(cutoff) as any[];
+  for (const row of stale) {
+    getDb().query("UPDATE orchestrators SET status = 'offline' WHERE id = ?").run(row.id);
+    // An orchestrator agent holds no workspaces, so use a direct status update
+    // instead of setStatus() (which triggers an unscoped electWorkspaceStewards
+    // sweep across all repos on every offline transition).
+    getDb().query("UPDATE agents SET status = 'offline', ready = 0 WHERE id = ?").run(row.agent_id);
+  }
+  return stale.map((row: any) => row.id);
+}

package/src/db/pairs.ts

@@ -0,0 +1,324 @@
+import { Database } from "bun:sqlite";
+import { randomUUID } from "node:crypto";
+import { isRecord, stringValue, isMechanicalMessageKind } from "agent-relay-sdk";
+import { ORCHESTRATOR_PROTOCOL_VERSION, VERSION } from "../config.ts";
+import { parseJson } from "../utils";
+import { isLiveIsolatedWorkspace } from "../workspace-phase";
+import {
+  CONTRACT_REQUIREMENTS,
+  contractCompatibility,
+  parseRuntimeCapabilities,
+  parseRuntimeContracts,
+  parseRuntimePackage,
+  type RuntimeContracts,
+} from "../contracts";
+import { STALE_TTL_MS, DAY_MS, CLAIM_LEASE_MS, POOL_CLAIM_LEASE_MS, WORKSPACE_MERGE_LEASE_MS } from "../config";
+import { matchAgents } from "../agent-ref";
+import { getAgent, listAgents } from "./agents.ts";
+import { getDb } from "./connection.ts";
+import { rowToPair } from "./mappers.ts";
+import { sendMessage } from "./messages.ts";
+import type {
+  AgentCard,
+  ActivityEvent,
+  ActivityEventInput,
+  AgentKind,
+  AgentSessionGuard,
+  Artifact,
+  ArtifactBlob,
+  ArtifactKind,
+  ArtifactLink,
+  ArtifactSensitivity,
+  ArtifactVisibility,
+  AttachmentRef,
+  ChannelBinding,
+  ChannelBindingMode,
+  ChannelRouteTarget,
+  ChatHistoryImport,
+  ChatHistoryImportEntry,
+  ChannelSummary,
+  ChannelTargetHealth,
+  CreatePairInput,
+  HealthCheck,
+  HealthReport,
+  ManagedAgent,
+  ManagedSessionExitDiagnostics,
+  Message,
+  MessageDeliveryAttempt,
+  MessageDeliveryStatus,
+  Orchestrator,
+  OrchestratorHealth,
+  OrchestratorRuntimeInput,
+  OrchestratorStatus,
+  OrchestratorUpgradeState,
+  PairActionInput,
+  PairMessageInput,
+  PairSession,
+  PairStatus,
+  RegisterAgentInput,
+  ReplyObligation,
+  RegisterOrchestratorInput,
+  SendMessageInput,
+  PollQuery,
+  SpawnApprovalMode,
+  SpawnProvider,
+  Task,
+  TaskEvent,
+  TaskSeverity,
+  TaskStatus,
+  IntegrationEventInput,
+  IntegrationSummary,
+  IntegrationTaskStats,
+  InboxDraft,
+  InboxState,
+  InboxThreadState,
+  ContextSnapshot,
+  ContextState,
+  ProviderCapabilities,
+  TaskStatusInput,
+  WorkspaceMetadata,
+  WorkspaceRecord,
+  WorkspaceStatus,
+} from "../types";
+
+export const OPEN_PAIR_STATUSES = ["pending", "active"] as const;
+export const DEFAULT_PAIR_TTL_MS = 5 * 60_000;
+export const MAX_PAIR_TTL_MS = DAY_MS;
+
+export function expirePendingPairs(now: number = Date.now()): void {
+  getDb().query("UPDATE pairs SET status = 'expired', updated_at = ?, ended_at = ? WHERE status = 'pending' AND expires_at <= ?")
+    .run(now, now, now);
+}
+
+export function closeOpenPairsForAgent(agentId: string, now: number = Date.now()): void {
+  getDb().query(`
+    UPDATE pairs
+    SET status = 'ended', ended_at = ?, ended_by = ?, updated_at = ?
+    WHERE status IN ('pending', 'active') AND (requester_id = ? OR target_id = ?)
+  `).run(now, agentId, now, agentId, agentId);
+}
+
+export function getOpenPairForAgent(agentId: string): PairSession | null {
+  expirePendingPairs();
+  const row = getDb().query(`
+    SELECT * FROM pairs
+    WHERE status IN ('pending', 'active') AND (requester_id = ? OR target_id = ?)
+    ORDER BY updated_at DESC
+    LIMIT 1
+  `).get(agentId, agentId) as any;
+  return row ? rowToPair(row) : null;
+}
+
+export function pairParticipant(pair: PairSession, agentId: string): boolean {
+  return pair.requesterId === agentId || pair.targetId === agentId;
+}
+
+export function pairPeer(pair: PairSession, agentId: string): string {
+  return pair.requesterId === agentId ? pair.targetId : pair.requesterId;
+}
+
+export function resolvePairTarget(target: string, requesterId: string): {
+  ok: true;
+  agent: AgentCard;
+} | {
+  ok: false;
+  error: string;
+  code: "not_found" | "ambiguous" | "busy" | "offline";
+  matches?: AgentCard[];
+  busy?: Array<{ agent: AgentCard; pair: PairSession }>;
+} {
+  const matches = matchAgents(target, listAgents(), { excludeId: requesterId });
+  if (matches.length === 0) return { ok: false, code: "not_found", error: `no agent matches ${target}` };
+
+  const live = matches.filter((agent) => agent.status !== "offline" && agent.ready);
+  if (live.length === 0) return { ok: false, code: "offline", error: `no matching agent is online and ready`, matches };
+
+  const busy: Array<{ agent: AgentCard; pair: PairSession }> = [];
+  const available: AgentCard[] = [];
+  for (const agent of live) {
+    const openPair = getOpenPairForAgent(agent.id);
+    if (openPair) busy.push({ agent, pair: openPair });
+    else available.push(agent);
+  }
+
+  if (available.length === 0) return { ok: false, code: "busy", error: `matching agent is already paired`, busy };
+  if (available.length > 1) {
+    return {
+      ok: false,
+      code: "ambiguous",
+      error: `target ${target} matches ${available.length} available agents`,
+      matches: available,
+    };
+  }
+  return { ok: true, agent: available[0]! };
+}
+
+export function pairSystemMessage(pair: PairSession, to: string, event: string, subject: string, body: string): Message {
+  return sendMessage({
+    from: "system",
+    to,
+    kind: "pair",
+    subject,
+    body,
+    payload: {
+      pairId: pair.id,
+      pairEvent: event,
+      requesterId: pair.requesterId,
+      targetId: pair.targetId,
+      pairStatus: pair.status,
+    },
+  });
+}
+
+export function getPair(id: string): PairSession | null {
+  expirePendingPairs();
+  const row = getDb().query("SELECT * FROM pairs WHERE id = ?").get(id) as any;
+  return row ? rowToPair(row) : null;
+}
+
+export function listPairs(filter?: { agentId?: string; status?: PairStatus }): PairSession[] {
+  expirePendingPairs();
+  const conditions: string[] = [];
+  const params: any[] = [];
+  if (filter?.agentId) {
+    conditions.push("(requester_id = ? OR target_id = ?)");
+    params.push(filter.agentId, filter.agentId);
+  }
+  if (filter?.status) {
+    conditions.push("status = ?");
+    params.push(filter.status);
+  }
+  const where = conditions.length ? `WHERE ${conditions.join(" AND ")}` : "";
+  return (getDb().query(`SELECT * FROM pairs ${where} ORDER BY updated_at DESC LIMIT 100`).all(...params) as any[]).map(rowToPair);
+}
+
+export function createPair(input: CreatePairInput): {
+  ok: true;
+  pair: PairSession;
+  invite: Message;
+} | {
+  ok: false;
+  error: string;
+  code: "not_found" | "ambiguous" | "busy" | "offline" | "invalid";
+  matches?: AgentCard[];
+  busy?: Array<{ agent: AgentCard; pair: PairSession }>;
+} {
+  expirePendingPairs();
+  const requester = getAgent(input.from);
+  if (!requester) return { ok: false, code: "invalid", error: `requester agent ${input.from} not registered` };
+  if (requester.status === "offline" || !requester.ready) return { ok: false, code: "offline", error: `requester agent ${input.from} is not online and ready` };
+  const requesterPair = getOpenPairForAgent(input.from);
+  if (requesterPair) return { ok: false, code: "busy", error: `requester is already paired`, busy: [{ agent: requester, pair: requesterPair }] };
+
+  const resolved = resolvePairTarget(input.target, input.from);
+  if (!resolved.ok) return resolved;
+
+  const now = Date.now();
+  const ttlMs = Math.min(Math.max(input.ttlMs ?? DEFAULT_PAIR_TTL_MS, 10_000), MAX_PAIR_TTL_MS);
+  const id = randomUUID();
+  getDb().query(`
+    INSERT INTO pairs (id, requester_id, target_id, status, objective, meta, created_at, updated_at, expires_at)
+    VALUES (?, ?, ?, 'pending', ?, ?, ?, ?, ?)
+  `).run(id, input.from, resolved.agent.id, input.objective ?? null, JSON.stringify(input.meta ?? {}), now, now, now + ttlMs);
+  const pair = getPair(id)!;
+  const objective = pair.objective ? `\n\nObjective:\n${pair.objective}` : "";
+  const invite = pairSystemMessage(
+    pair,
+    pair.targetId,
+    "invite",
+    `Pair invite from ${pair.requesterId}`,
+    [
+      `${pair.requesterId} wants to start a two-party live pair session with you.${objective}`,
+      "",
+      `Pair ID: ${pair.id}`,
+      "Accept with POST /api/pairs/{id}/accept using your agentId.",
+      "Reject with POST /api/pairs/{id}/reject using your agentId.",
+      "Pairing is exclusive: each agent can be in at most one pending or active pair.",
+    ].join("\n"),
+  );
+  return { ok: true, pair, invite };
+}
+
+export function acceptPair(id: string, input: PairActionInput): { ok: true; pair: PairSession; notices: Message[] } | { ok: false; error: string; code: "not_found" | "forbidden" | "busy" | "invalid" } {
+  expirePendingPairs();
+  const pair = getPair(id);
+  if (!pair) return { ok: false, code: "not_found", error: "pair not found" };
+  if (pair.status !== "pending") return { ok: false, code: "invalid", error: `pair is ${pair.status}` };
+  if (pair.targetId !== input.agentId) return { ok: false, code: "forbidden", error: "only the target agent can accept this pair" };
+  const target = getAgent(input.agentId);
+  if (!target || target.status === "offline" || !target.ready) return { ok: false, code: "invalid", error: "accepting agent is not online and ready" };
+  const requester = getAgent(pair.requesterId);
+  if (!requester || requester.status === "offline" || !requester.ready) return { ok: false, code: "invalid", error: "requester agent is no longer online and ready" };
+
+  for (const agentId of [pair.requesterId, pair.targetId]) {
+    const open = getOpenPairForAgent(agentId);
+    if (open && open.id !== pair.id) return { ok: false, code: "busy", error: `${agentId} is already paired` };
+  }
+
+  const now = Date.now();
+  getDb().query("UPDATE pairs SET status = 'active', accepted_at = ?, updated_at = ? WHERE id = ? AND status = 'pending'")
+    .run(now, now, id);
+  const active = getPair(id)!;
+  const notices = [
+    pairSystemMessage(active, active.requesterId, "accepted", `Pair accepted by ${active.targetId}`, `Pair ${active.id} is active. Send pair messages with POST /api/pairs/${active.id}/messages.`),
+    pairSystemMessage(active, active.targetId, "accepted", `Pair active with ${active.requesterId}`, `Pair ${active.id} is active. Send pair messages with POST /api/pairs/${active.id}/messages.`),
+  ];
+  return { ok: true, pair: active, notices };
+}
+
+export function rejectPair(id: string, input: PairActionInput): { ok: true; pair: PairSession; notice: Message } | { ok: false; error: string; code: "not_found" | "forbidden" | "invalid" } {
+  expirePendingPairs();
+  const pair = getPair(id);
+  if (!pair) return { ok: false, code: "not_found", error: "pair not found" };
+  if (pair.status !== "pending") return { ok: false, code: "invalid", error: `pair is ${pair.status}` };
+  if (pair.targetId !== input.agentId) return { ok: false, code: "forbidden", error: "only the target agent can reject this pair" };
+  const now = Date.now();
+  getDb().query("UPDATE pairs SET status = 'rejected', ended_at = ?, ended_by = ?, updated_at = ? WHERE id = ?")
+    .run(now, input.agentId, now, id);
+  const rejected = getPair(id)!;
+  const reason = input.reason ? `\n\nReason:\n${input.reason}` : "";
+  const notice = pairSystemMessage(rejected, rejected.requesterId, "rejected", `Pair rejected by ${input.agentId}`, `Pair ${rejected.id} was rejected.${reason}`);
+  return { ok: true, pair: rejected, notice };
+}
+
+export function endPair(id: string, input: PairActionInput): { ok: true; pair: PairSession; notice?: Message } | { ok: false; error: string; code: "not_found" | "forbidden" | "invalid" } {
+  expirePendingPairs();
+  const pair = getPair(id);
+  if (!pair) return { ok: false, code: "not_found", error: "pair not found" };
+  if (!pairParticipant(pair, input.agentId)) return { ok: false, code: "forbidden", error: "only pair participants can hang up" };
+  if (!OPEN_PAIR_STATUSES.includes(pair.status as any)) return { ok: false, code: "invalid", error: `pair is ${pair.status}` };
+  const now = Date.now();
+  getDb().query("UPDATE pairs SET status = 'ended', ended_at = ?, ended_by = ?, updated_at = ? WHERE id = ?")
+    .run(now, input.agentId, now, id);
+  const ended = getPair(id)!;
+  const reason = input.reason ? `\n\nReason:\n${input.reason}` : "";
+  const peer = pairPeer(ended, input.agentId);
+  const notice = pairSystemMessage(ended, peer, "ended", `Pair ended by ${input.agentId}`, `Pair ${ended.id} ended.${reason}`);
+  return { ok: true, pair: ended, notice };
+}
+
+export function sendPairMessage(id: string, input: PairMessageInput): { ok: true; pair: PairSession; message: Message } | { ok: false; error: string; code: "not_found" | "forbidden" | "invalid" } {
+  expirePendingPairs();
+  const pair = getPair(id);
+  if (!pair) return { ok: false, code: "not_found", error: "pair not found" };
+  if (pair.status !== "active") return { ok: false, code: "invalid", error: `pair is ${pair.status}` };
+  if (!pairParticipant(pair, input.from)) return { ok: false, code: "forbidden", error: "only pair participants can send pair messages" };
+  const to = pairPeer(pair, input.from);
+  const now = Date.now();
+  const message = sendMessage({
+    from: input.from,
+    to,
+    kind: "pair",
+    subject: input.subject ?? `Pair ${pair.id}`,
+    body: input.body,
+    payload: {
+      pairId: pair.id,
+      pairEvent: "message",
+      requesterId: pair.requesterId,
+      targetId: pair.targetId,
+    },
+  });
+  getDb().query("UPDATE pairs SET last_message_at = ?, updated_at = ? WHERE id = ?").run(now, now, id);
+  return { ok: true, pair: getPair(id)!, message };
+}
+