agent-relay-server 0.4.16 → 0.4.17

package/src/db.ts

@@ -1,9 +1,18 @@
 import { Database } from "bun:sqlite";
+import { randomUUID } from "node:crypto";
 import { VERSION } from "./config.ts";
 import type {
   AgentCard,
+  AgentSessionGuard,
+  CreatePairInput,
+  HealthCheck,
+  HealthReport,
   Message,
   MessageType,
+  PairActionInput,
+  PairMessageInput,
+  PairSession,
+  PairStatus,
   RegisterAgentInput,
   SendMessageInput,
   PollQuery,
@@ -14,7 +23,7 @@ import type {
   IntegrationEventInput,
   TaskStatusInput,
 } from "./types";
-import { STALE_TTL_MS, DAY_MS } from "./config";
+import { STALE_TTL_MS, DAY_MS, CLAIM_LEASE_MS } from "./config";
 
 let db: Database;
 
@@ -32,6 +41,8 @@ export function initDb(path: string = "agent-relay.db"): Database {
       rig TEXT,
       capabilities TEXT NOT NULL DEFAULT '[]',
       status TEXT NOT NULL DEFAULT 'idle',
+      instance_id TEXT,
+      epoch INTEGER NOT NULL DEFAULT 0,
       meta TEXT NOT NULL DEFAULT '{}',
       last_seen INTEGER NOT NULL,
       created_at INTEGER NOT NULL
@@ -50,6 +61,8 @@ export function initDb(path: string = "agent-relay.db"): Database {
       claimable INTEGER NOT NULL DEFAULT 0,
       claimed_by TEXT,
       claimed_at INTEGER,
+      claim_expires_at INTEGER,
+      idempotency_key TEXT,
       meta TEXT NOT NULL DEFAULT '{}',
       read_by TEXT NOT NULL DEFAULT '[]',
       created_at INTEGER NOT NULL
@@ -73,6 +86,7 @@ export function initDb(path: string = "agent-relay.db"): Database {
       occurrence_count INTEGER NOT NULL DEFAULT 1,
       claimed_by TEXT,
       claimed_at INTEGER,
+      claim_expires_at INTEGER,
       message_id INTEGER REFERENCES messages(id) ON DELETE SET NULL,
       result TEXT,
       metadata TEXT NOT NULL DEFAULT '{}',
@@ -110,6 +124,26 @@ export function initDb(path: string = "agent-relay.db"): Database {
       created_at INTEGER NOT NULL,
       updated_at INTEGER NOT NULL
     );
+
+    CREATE TABLE IF NOT EXISTS pairs (
+      id TEXT PRIMARY KEY,
+      requester_id TEXT NOT NULL,
+      target_id TEXT NOT NULL,
+      status TEXT NOT NULL,
+      objective TEXT,
+      meta TEXT NOT NULL DEFAULT '{}',
+      created_at INTEGER NOT NULL,
+      updated_at INTEGER NOT NULL,
+      expires_at INTEGER NOT NULL,
+      accepted_at INTEGER,
+      ended_at INTEGER,
+      ended_by TEXT,
+      last_message_at INTEGER
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_pairs_requester ON pairs(requester_id);
+    CREATE INDEX IF NOT EXISTS idx_pairs_target ON pairs(target_id);
+    CREATE INDEX IF NOT EXISTS idx_pairs_status ON pairs(status);
   `);
 
   // Migrations
@@ -124,7 +158,17 @@ export function initDb(path: string = "agent-relay.db"): Database {
     db.run("ALTER TABLE messages ADD COLUMN claimed_by TEXT");
     db.run("ALTER TABLE messages ADD COLUMN claimed_at INTEGER");
   }
+  if (!colNames.includes("claim_expires_at")) {
+    db.run("ALTER TABLE messages ADD COLUMN claim_expires_at INTEGER");
+  }
+  if (!colNames.includes("idempotency_key")) {
+    db.run("ALTER TABLE messages ADD COLUMN idempotency_key TEXT");
+  }
+  db.prepare(
+    "UPDATE messages SET claim_expires_at = coalesce(claimed_at, ?) + ? WHERE claimed_by IS NOT NULL AND claim_expires_at IS NULL",
+  ).run(Date.now(), CLAIM_LEASE_MS);
   db.run("CREATE INDEX IF NOT EXISTS idx_msg_thread ON messages(thread_id)");
+  db.run("CREATE UNIQUE INDEX IF NOT EXISTS idx_msg_idempotency ON messages(from_agent, idempotency_key) WHERE idempotency_key IS NOT NULL");
 
   if (!colNames.includes("type")) {
     db.run("ALTER TABLE messages ADD COLUMN type TEXT NOT NULL DEFAULT 'message'");
@@ -133,6 +177,15 @@ export function initDb(path: string = "agent-relay.db"): Database {
   // Backfill thread_id for pre-migration rows (self-threaded).
   db.run("UPDATE messages SET thread_id = id WHERE thread_id IS NULL");
 
+  const taskCols = db.prepare("PRAGMA table_info(tasks)").all() as any[];
+  const taskColNames = taskCols.map((c: any) => c.name);
+  if (!taskColNames.includes("claim_expires_at")) {
+    db.run("ALTER TABLE tasks ADD COLUMN claim_expires_at INTEGER");
+  }
+  db.prepare(
+    "UPDATE tasks SET claim_expires_at = coalesce(claimed_at, ?) + ? WHERE claimed_by IS NOT NULL AND claim_expires_at IS NULL",
+  ).run(Date.now(), CLAIM_LEASE_MS);
+
   // message_reads: relational replacement for the read_by JSON array.
   db.run(`
     CREATE TABLE IF NOT EXISTS message_reads (
@@ -153,6 +206,12 @@ export function initDb(path: string = "agent-relay.db"): Database {
   if (!agentColNames.includes("ready")) {
     db.run("ALTER TABLE agents ADD COLUMN ready INTEGER NOT NULL DEFAULT 0");
   }
+  if (!agentColNames.includes("instance_id")) {
+    db.run("ALTER TABLE agents ADD COLUMN instance_id TEXT");
+  }
+  if (!agentColNames.includes("epoch")) {
+    db.run("ALTER TABLE agents ADD COLUMN epoch INTEGER NOT NULL DEFAULT 0");
+  }
   db.run("CREATE INDEX IF NOT EXISTS idx_agents_label ON agents(label)");
 
   // Built-in agents — registered unconditionally so sends from these ids
@@ -209,6 +268,8 @@ function rowToAgent(row: any): AgentCard {
     capabilities: parseStringArray(row.capabilities),
     ready: row.ready === 1,
     status: row.status,
+    instanceId: row.instance_id ?? undefined,
+    epoch: typeof row.epoch === "number" ? row.epoch : 0,
     meta: parseJson(row.meta, {}),
     lastSeen: row.last_seen,
     createdAt: row.created_at,
@@ -229,6 +290,8 @@ function rowToMessage(row: any): Message {
     claimable: row.claimable === 1 ? true : undefined,
     claimedBy: row.claimed_by ?? undefined,
     claimedAt: row.claimed_at ?? undefined,
+    claimExpiresAt: row.claim_expires_at ?? undefined,
+    idempotencyKey: row.idempotency_key ?? undefined,
     meta: parseJson(row.meta, {}),
     readBy: parseJson(row.read_by_agents ?? "[]", []),
     createdAt: row.created_at,
@@ -250,6 +313,7 @@ function rowToTask(row: any): Task {
     occurrenceCount: row.occurrence_count,
     claimedBy: row.claimed_by ?? undefined,
     claimedAt: row.claimed_at ?? undefined,
+    claimExpiresAt: row.claim_expires_at ?? undefined,
     messageId: row.message_id ?? undefined,
     result: row.result ?? undefined,
     metadata: parseJson(row.metadata, {}),
@@ -273,6 +337,24 @@ function rowToTaskEvent(row: any): TaskEvent {
   };
 }
 
+function rowToPair(row: any): PairSession {
+  return {
+    id: row.id,
+    requesterId: row.requester_id,
+    targetId: row.target_id,
+    status: row.status as PairStatus,
+    objective: row.objective ?? undefined,
+    createdAt: row.created_at,
+    updatedAt: row.updated_at,
+    expiresAt: row.expires_at,
+    acceptedAt: row.accepted_at ?? undefined,
+    endedAt: row.ended_at ?? undefined,
+    endedBy: row.ended_by ?? undefined,
+    lastMessageAt: row.last_message_at ?? undefined,
+    meta: parseJson(row.meta, {}),
+  };
+}
+
 const MSG_SELECT = `SELECT m.*, (
   SELECT json_group_array(agent_id) FROM message_reads WHERE message_id = m.id
 ) AS read_by_agents FROM messages m`;
@@ -285,9 +367,10 @@ export function upsertAgent(input: RegisterAgentInput): AgentCard {
   // explicitly sends one (including null to clear).
   const labelProvided = Object.prototype.hasOwnProperty.call(input, "label");
   const readyProvided = Object.prototype.hasOwnProperty.call(input, "ready");
+  const instanceProvided = Boolean(input.instanceId);
   const stmt = db.prepare(`
-    INSERT INTO agents (id, name, label, tags, machine, rig, capabilities, ready, status, meta, last_seen, created_at)
-    VALUES ($id, $name, $label, $tags, $machine, $rig, $capabilities, $ready, $status, $meta, $now, $now)
+    INSERT INTO agents (id, name, label, tags, machine, rig, capabilities, ready, status, instance_id, epoch, meta, last_seen, created_at)
+    VALUES ($id, $name, $label, $tags, $machine, $rig, $capabilities, $ready, $status, $instanceId, $initialEpoch, $meta, $now, $now)
     ON CONFLICT(id) DO UPDATE SET
       name = $name,
       label = CASE WHEN $labelProvided = 1 THEN $label ELSE agents.label END,
@@ -297,6 +380,11 @@ export function upsertAgent(input: RegisterAgentInput): AgentCard {
       capabilities = $capabilities,
       ready = CASE WHEN $readyProvided = 1 THEN $ready ELSE agents.ready END,
       status = $status,
+      instance_id = CASE WHEN $instanceProvided = 1 THEN $instanceId ELSE agents.instance_id END,
+      epoch = CASE
+        WHEN $instanceProvided = 1 AND (agents.instance_id IS NULL OR agents.instance_id <> $instanceId) THEN agents.epoch + 1
+        ELSE agents.epoch
+      END,
       meta = $meta,
       last_seen = $now
   `);
@@ -313,6 +401,9 @@ export function upsertAgent(input: RegisterAgentInput): AgentCard {
     $ready: input.ready ? 1 : 0,
     $readyProvided: readyProvided ? 1 : 0,
     $status: input.status ?? "idle",
+    $instanceId: input.instanceId ?? null,
+    $instanceProvided: instanceProvided ? 1 : 0,
+    $initialEpoch: instanceProvided ? 1 : 0,
     $meta: JSON.stringify(input.meta ?? {}),
     $now: now,
   });
@@ -320,6 +411,19 @@ export function upsertAgent(input: RegisterAgentInput): AgentCard {
   return getAgent(input.id)!;
 }
 
+export function validateAgentSession(id: string, guard?: AgentSessionGuard): { ok: boolean; error?: string } {
+  if (!guard || (!guard.instanceId && guard.epoch === undefined)) return { ok: true };
+  const agent = getAgent(id);
+  if (!agent) return { ok: false, error: "agent not found" };
+  if (guard.instanceId && agent.instanceId !== guard.instanceId) {
+    return { ok: false, error: "stale agent instance" };
+  }
+  if (guard.epoch !== undefined && agent.epoch !== guard.epoch) {
+    return { ok: false, error: "stale agent instance" };
+  }
+  return { ok: true };
+}
+
 export function setLabel(id: string, label: string | null): boolean {
   const normalized = label && label.trim() ? label.trim() : null;
   return (
@@ -327,6 +431,12 @@ export function setLabel(id: string, label: string | null): boolean {
   );
 }
 
+export function setTags(id: string, tags: string[]): AgentCard | null {
+  const normalized = [...new Set(tags.map((tag) => tag.trim()).filter(Boolean))];
+  const result = db.prepare("UPDATE agents SET tags = ?, last_seen = ? WHERE id = ?").run(JSON.stringify(normalized), Date.now(), id);
+  return result.changes > 0 ? getAgent(id) : null;
+}
+
 export function getAgent(id: string): AgentCard | null {
   const row = db.prepare("SELECT * FROM agents WHERE id = ?").get(id) as any;
   return row ? rowToAgent(row) : null;
@@ -357,16 +467,20 @@ export function listAgents(filter?: {
   return (db.prepare(sql).all(...params) as any[]).map(rowToAgent);
 }
 
-export function setStatus(id: string, status: AgentCard["status"]): boolean {
+export function setStatus(id: string, status: AgentCard["status"], guard?: AgentSessionGuard): boolean {
+  if (!validateAgentSession(id, guard).ok) return false;
   const now = Date.now();
   const ready = status === "offline" ? 0 : undefined;
   const sql = ready === 0
     ? "UPDATE agents SET status = ?, ready = 0, last_seen = ? WHERE id = ?"
     : "UPDATE agents SET status = ?, last_seen = ? WHERE id = ?";
-  return db.prepare(sql).run(status, now, id).changes > 0;
+  const changed = db.prepare(sql).run(status, now, id).changes > 0;
+  if (changed && status === "offline") closeOpenPairsForAgent(id, now);
+  return changed;
 }
 
-export function markReady(id: string, ready: boolean): boolean {
+export function markReady(id: string, ready: boolean, guard?: AgentSessionGuard): boolean {
+  if (!validateAgentSession(id, guard).ok) return false;
   const now = Date.now();
   return (
     db
@@ -375,7 +489,8 @@ export function markReady(id: string, ready: boolean): boolean {
   );
 }
 
-export function heartbeat(id: string): boolean {
+export function heartbeat(id: string, guard?: AgentSessionGuard): boolean {
+  if (!validateAgentSession(id, guard).ok) return false;
   const result = db
     .prepare("UPDATE agents SET last_seen = ? WHERE id = ?")
     .run(Date.now(), id);
@@ -383,12 +498,14 @@ export function heartbeat(id: string): boolean {
 }
 
 export function reapStaleAgents(ttlMs: number = STALE_TTL_MS): string[] {
-  const cutoff = Date.now() - ttlMs;
+  const now = Date.now();
+  const cutoff = now - ttlMs;
   const rows = db
     .prepare(
       "UPDATE agents SET status = 'offline', ready = 0 WHERE status != 'offline' AND last_seen < ? AND id NOT IN ('user', 'system') RETURNING id"
     )
     .all(cutoff) as any[];
+  for (const row of rows) closeOpenPairsForAgent(row.id, now);
   return rows.map((r: any) => r.id);
 }
 
@@ -401,19 +518,22 @@ export function pruneOfflineAgents(maxOfflineMs: number = DAY_MS): string[] {
       )
       .all(cutoff) as any[];
     if (rows.length === 0) return [];
+    const now = Date.now();
 
     // Release claims held by pruned agents so work becomes claimable again.
     db
       .prepare(
-        "UPDATE messages SET claimed_by = NULL, claimed_at = NULL WHERE claimed_by IN (SELECT id FROM agents WHERE status = 'offline' AND last_seen < ? AND id NOT IN ('user', 'system'))"
+        "UPDATE messages SET claimed_by = NULL, claimed_at = NULL, claim_expires_at = NULL WHERE claimed_by IN (SELECT id FROM agents WHERE status = 'offline' AND last_seen < ? AND id NOT IN ('user', 'system'))"
       )
       .run(cutoff);
 
     db
       .prepare(
-        "UPDATE tasks SET status = 'open', claimed_by = NULL, claimed_at = NULL, updated_at = ? WHERE claimed_by IN (SELECT id FROM agents WHERE status = 'offline' AND last_seen < ? AND id NOT IN ('user', 'system')) AND status IN ('claimed', 'in_progress', 'blocked')"
+        "UPDATE tasks SET status = 'open', claimed_by = NULL, claimed_at = NULL, claim_expires_at = NULL, updated_at = ? WHERE claimed_by IN (SELECT id FROM agents WHERE status = 'offline' AND last_seen < ? AND id NOT IN ('user', 'system')) AND status IN ('claimed', 'in_progress', 'blocked')"
       )
-      .run(Date.now(), cutoff);
+      .run(now, cutoff);
+
+    for (const row of rows) closeOpenPairsForAgent(row.id, now);
 
     db
       .prepare(
@@ -443,8 +563,10 @@ export function deleteAgent(id: string): { ok: boolean; error?: string } {
   const deleted = db.transaction(() => {
     // Release any claims held by this agent so the tasks become claimable again.
     // from_agent is left intact as historical record.
-    db.prepare("UPDATE messages SET claimed_by = NULL, claimed_at = NULL WHERE claimed_by = ?").run(id);
-    db.prepare("UPDATE tasks SET status = 'open', claimed_by = NULL, claimed_at = NULL, updated_at = ? WHERE claimed_by = ? AND status IN ('claimed', 'in_progress', 'blocked')").run(Date.now(), id);
+    const now = Date.now();
+    db.prepare("UPDATE messages SET claimed_by = NULL, claimed_at = NULL, claim_expires_at = NULL WHERE claimed_by = ?").run(id);
+    db.prepare("UPDATE tasks SET status = 'open', claimed_by = NULL, claimed_at = NULL, claim_expires_at = NULL, updated_at = ? WHERE claimed_by = ? AND status IN ('claimed', 'in_progress', 'blocked')").run(now, id);
+    closeOpenPairsForAgent(id, now);
     return db.prepare("DELETE FROM agents WHERE id = ?").run(id).changes > 0;
   })();
   return deleted ? { ok: true } : { ok: false, error: "agent not found" };
@@ -610,7 +732,50 @@ export function listTaskEvents(taskId: number): TaskEvent[] {
   return (db.prepare("SELECT * FROM task_events WHERE task_id = ? ORDER BY id ASC").all(taskId) as any[]).map(rowToTaskEvent);
 }
 
-export function claimTask(taskId: number, agentId: string): { ok: boolean; error?: string; task?: Task } {
+export function releaseExpiredClaims(now: number = Date.now()): { messageIds: number[]; tasks: Task[] } {
+  return db.transaction(() => {
+    const releasableMessageClaim = "claimed_by IS NOT NULL AND (claim_expires_at IS NULL OR claim_expires_at <= ?) AND NOT EXISTS (SELECT 1 FROM tasks t WHERE t.message_id = messages.id AND t.status IN ('done', 'failed', 'canceled'))";
+    const messageRows = db
+      .prepare(`SELECT id FROM messages WHERE ${releasableMessageClaim}`)
+      .all(now) as any[];
+    const taskRows = db
+      .prepare(`${TASK_SELECT} WHERE claimed_by IS NOT NULL AND (claim_expires_at IS NULL OR claim_expires_at <= ?) AND status IN ('claimed', 'in_progress', 'blocked')`)
+      .all(now) as any[];
+
+    if (messageRows.length > 0) {
+      db
+        .prepare(`UPDATE messages SET claimed_by = NULL, claimed_at = NULL, claim_expires_at = NULL WHERE ${releasableMessageClaim}`)
+        .run(now);
+    }
+
+    if (taskRows.length > 0) {
+      db
+        .prepare("UPDATE tasks SET status = 'open', claimed_by = NULL, claimed_at = NULL, claim_expires_at = NULL, updated_at = ? WHERE claimed_by IS NOT NULL AND (claim_expires_at IS NULL OR claim_expires_at <= ?) AND status IN ('claimed', 'in_progress', 'blocked')")
+        .run(now, now);
+
+      for (const row of taskRows) {
+        insertTaskEvent(row.id, {
+          source: "agent-relay",
+          type: "claim.expired",
+          severity: row.severity,
+          title: "Task claim expired",
+          body: `Claim by ${row.claimed_by} expired and was released`,
+          metadata: { agentId: row.claimed_by },
+        }, now);
+      }
+    }
+
+    return {
+      messageIds: messageRows.map((row: any) => row.id),
+      tasks: taskRows.map((row: any) => getTask(row.id)!),
+    };
+  })();
+}
+
+export function claimTask(taskId: number, agentId: string, guard?: AgentSessionGuard): { ok: boolean; error?: string; task?: Task } {
+  releaseExpiredClaims();
+  const session = validateAgentSession(agentId, guard);
+  if (!session.ok) return { ok: false, error: session.error };
   const agent = getAgent(agentId);
   if (!agent) return { ok: false, error: "claiming agent not found" };
   if (agent.status === "offline") return { ok: false, error: "claiming agent is offline" };
@@ -621,10 +786,11 @@ export function claimTask(taskId: number, agentId: string): { ok: boolean; error
   try {
     return db.transaction(() => {
       const now = Date.now();
+      const expiresAt = now + CLAIM_LEASE_MS;
       const result = db.prepare(`
-        UPDATE tasks SET status = 'claimed', claimed_by = ?, claimed_at = ?, updated_at = ?
+        UPDATE tasks SET status = 'claimed', claimed_by = ?, claimed_at = ?, claim_expires_at = ?, updated_at = ?
         WHERE id = ? AND status IN ('open', 'blocked')
-      `).run(agentId, now, now, taskId);
+      `).run(agentId, now, expiresAt, now, taskId);
       if (result.changes === 0) return { ok: false, error: "claim race — already claimed" };
       if (task.messageId) {
         const messageClaim = claimMessageRow(task.messageId, agentId, now);
@@ -646,11 +812,36 @@ export function claimTask(taskId: number, agentId: string): { ok: boolean; error
   }
 }
 
+export function renewTaskClaim(taskId: number, agentId: string, guard?: AgentSessionGuard): { ok: boolean; error?: string; task?: Task } {
+  releaseExpiredClaims();
+  const session = validateAgentSession(agentId, guard);
+  if (!session.ok) return { ok: false, error: session.error };
+  const agent = getAgent(agentId);
+  if (!agent) return { ok: false, error: "claiming agent not found" };
+  if (agent.status === "offline") return { ok: false, error: "claiming agent is offline" };
+  const task = getTask(taskId);
+  if (!task) return { ok: false, error: "task not found" };
+  if (task.claimedBy !== agentId) return { ok: false, error: task.claimedBy ? `claimed by ${task.claimedBy}` : "task is not claimed" };
+  if (!["claimed", "in_progress", "blocked"].includes(task.status)) return { ok: false, error: `task is ${task.status}` };
+
+  const now = Date.now();
+  const expiresAt = now + CLAIM_LEASE_MS;
+  db.prepare("UPDATE tasks SET claim_expires_at = ?, updated_at = ? WHERE id = ? AND claimed_by = ?").run(expiresAt, now, taskId, agentId);
+  if (task.messageId) {
+    db.prepare("UPDATE messages SET claim_expires_at = ? WHERE id = ? AND claimed_by = ?").run(expiresAt, task.messageId, agentId);
+  }
+  return { ok: true, task: getTask(taskId)! };
+}
+
 export function updateTaskStatus(taskId: number, input: TaskStatusInput): { ok: boolean; error?: string; task?: Task; event?: TaskEvent } {
   const task = getTask(taskId);
   if (!task) return { ok: false, error: "task not found" };
   const now = Date.now();
   const agentId = input.agentId ?? task.claimedBy ?? null;
+  if (agentId) {
+    const session = validateAgentSession(agentId, input);
+    if (!session.ok) return { ok: false, error: session.error };
+  }
   const result = db.prepare(`
     UPDATE tasks
     SET status = ?, result = COALESCE(?, result), claimed_by = COALESCE(?, claimed_by),
@@ -659,6 +850,13 @@ export function updateTaskStatus(taskId: number, input: TaskStatusInput): { ok:
     WHERE id = ?
   `).run(input.status, input.result ?? null, agentId, agentId, now, now, now, taskId);
   if (result.changes === 0) return { ok: false, error: "task not found" };
+  if (agentId && ["claimed", "in_progress", "blocked"].includes(input.status)) {
+    const expiresAt = now + CLAIM_LEASE_MS;
+    db.prepare("UPDATE tasks SET claim_expires_at = ? WHERE id = ? AND claimed_by = ?").run(expiresAt, taskId, agentId);
+    if (task.messageId) {
+      db.prepare("UPDATE messages SET claim_expires_at = ? WHERE id = ? AND claimed_by = ?").run(expiresAt, task.messageId, agentId);
+    }
+  }
   const event = insertTaskEvent(taskId, {
     source: input.agentId ?? "agent-relay",
     type: `status:${input.status}`,
@@ -708,15 +906,284 @@ export function listCallbackDeliveries(taskId: number): Array<{
     }));
 }
 
+// --- Pair sessions ---
+
+const OPEN_PAIR_STATUSES = ["pending", "active"] as const;
+const DEFAULT_PAIR_TTL_MS = 5 * 60_000;
+const MAX_PAIR_TTL_MS = DAY_MS;
+
+function expirePendingPairs(now: number = Date.now()): void {
+  db.prepare("UPDATE pairs SET status = 'expired', updated_at = ?, ended_at = ? WHERE status = 'pending' AND expires_at <= ?")
+    .run(now, now, now);
+}
+
+function closeOpenPairsForAgent(agentId: string, now: number = Date.now()): void {
+  db.prepare(`
+    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);
+}
+
+function getOpenPairForAgent(agentId: string): PairSession | null {
+  expirePendingPairs();
+  const row = db.prepare(`
+    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;
+}
+
+function pairParticipant(pair: PairSession, agentId: string): boolean {
+  return pair.requesterId === agentId || pair.targetId === agentId;
+}
+
+function pairPeer(pair: PairSession, agentId: string): string {
+  return pair.requesterId === agentId ? pair.targetId : pair.requesterId;
+}
+
+function agentMatchesPairTarget(agent: AgentCard, target: string): boolean {
+  if (target.startsWith("id:")) return agent.id === target.slice(3);
+  if (target.startsWith("label:")) return agent.label === target.slice(6);
+  if (target.startsWith("tag:")) return agent.tags.includes(target.slice(4));
+  if (target.startsWith("cap:")) return agent.capabilities.includes(target.slice(4));
+  if (target.startsWith("rig:")) return agent.rig === target.slice(4);
+  if (target.startsWith("machine:")) return agent.machine === target.slice(8);
+  return agent.id === target ||
+    agent.label === target ||
+    agent.tags.includes(target) ||
+    agent.capabilities.includes(target) ||
+    agent.rig === target ||
+    agent.name === target;
+}
+
+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 = listAgents().filter((agent) => agent.id !== requesterId && agentMatchesPairTarget(agent, target));
+  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]! };
+}
+
+function pairSystemMessage(pair: PairSession, to: string, event: string, subject: string, body: string): Message {
+  return sendMessage({
+    from: "system",
+    to,
+    type: "system",
+    subject,
+    body,
+    meta: {
+      pairId: pair.id,
+      pairEvent: event,
+      requesterId: pair.requesterId,
+      targetId: pair.targetId,
+      pairStatus: pair.status,
+    },
+  });
+}
+
+export function getPair(id: string): PairSession | null {
+  expirePendingPairs();
+  const row = db.prepare("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 (db.prepare(`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();
+  db.prepare(`
+    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();
+  db.prepare("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();
+  db.prepare("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();
+  db.prepare("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,
+    subject: input.subject ?? `Pair ${pair.id}`,
+    body: input.body,
+    meta: {
+      pairId: pair.id,
+      pairEvent: "message",
+      requesterId: pair.requesterId,
+      targetId: pair.targetId,
+    },
+  });
+  db.prepare("UPDATE pairs SET last_message_at = ?, updated_at = ? WHERE id = ?").run(now, now, id);
+  return { ok: true, pair: getPair(id)!, message };
+}
+
 // --- Messages ---
 
-export function sendMessage(input: SendMessageInput): Message {
+function findMessageByIdempotencyKey(from: string, key: string): Message | null {
+  const row = db
+    .prepare(`${MSG_SELECT} WHERE m.from_agent = ? AND m.idempotency_key = ? LIMIT 1`)
+    .get(from, key) as any;
+  return row ? rowToMessage(row) : null;
+}
+
+export function sendMessageWithResult(input: SendMessageInput): { message: Message; created: boolean } {
   const now = Date.now();
 
   if (!getAgent(input.from)) {
     throw new ValidationError(`sender agent ${input.from} not registered`);
   }
 
+  if (input.idempotencyKey) {
+    const existing = findMessageByIdempotencyKey(input.from, input.idempotencyKey);
+    if (existing) return { message: existing, created: false };
+  }
+
   // Resolve thread: if replying, inherit from parent; reject unknown replyTo
   // rather than silently orphaning the message (leaves thread_id NULL).
   let threadId: number | null = null;
@@ -727,8 +1194,8 @@ export function sendMessage(input: SendMessageInput): Message {
   }
 
   const insert = db.prepare(`
-    INSERT INTO messages (from_agent, to_target, type, channel, subject, body, thread_id, reply_to, claimable, meta, created_at)
-    VALUES ($from, $to, $type, $channel, $subject, $body, $threadId, $replyTo, $claimable, $meta, $now)
+    INSERT INTO messages (from_agent, to_target, type, channel, subject, body, thread_id, reply_to, claimable, idempotency_key, meta, created_at)
+    VALUES ($from, $to, $type, $channel, $subject, $body, $threadId, $replyTo, $claimable, $idempotencyKey, $meta, $now)
   `);
   const setSelfThread = db.prepare("UPDATE messages SET thread_id = ? WHERE id = ?");
 
@@ -743,6 +1210,7 @@ export function sendMessage(input: SendMessageInput): Message {
       $threadId: threadId,
       $replyTo: input.replyTo ?? null,
       $claimable: input.claimable ? 1 : 0,
+      $idempotencyKey: input.idempotencyKey ?? null,
       $meta: JSON.stringify(input.meta ?? {}),
       $now: now,
     });
@@ -751,7 +1219,11 @@ export function sendMessage(input: SendMessageInput): Message {
     return newId;
   })();
 
-  return getMessage(id)!;
+  return { message: getMessage(id)!, created: true };
+}
+
+export function sendMessage(input: SendMessageInput): Message {
+  return sendMessageWithResult(input).message;
 }
 
 export function getThread(messageId: number): Message[] {
@@ -766,16 +1238,20 @@ export function getThread(messageId: number): Message[] {
 }
 
 function claimMessageRow(messageId: number, agentId: string, now: number): { ok: false; error: string } | { ok: true } {
+  const expiresAt = now + CLAIM_LEASE_MS;
   const result = db.prepare(
-    "UPDATE messages SET claimed_by = ?, claimed_at = ? WHERE id = ? AND claimed_by IS NULL"
-  ).run(agentId, now, messageId);
+    "UPDATE messages SET claimed_by = ?, claimed_at = ?, claim_expires_at = ? WHERE id = ? AND claimed_by IS NULL"
+  ).run(agentId, now, expiresAt, messageId);
 
   // Atomic: if changes === 0, someone else claimed it between our read and write
   if (result.changes === 0) return { ok: false, error: "claim race — already claimed" };
   return { ok: true };
 }
 
-export function claimMessage(messageId: number, agentId: string): { ok: boolean; error?: string; task?: Task } {
+export function claimMessage(messageId: number, agentId: string, guard?: AgentSessionGuard): { ok: boolean; error?: string; task?: Task } {
+  releaseExpiredClaims();
+  const session = validateAgentSession(agentId, guard);
+  if (!session.ok) return { ok: false, error: session.error };
   const agent = getAgent(agentId);
   if (!agent) return { ok: false, error: "claiming agent not found" };
   if (agent.status === "offline") return { ok: false, error: "claiming agent is offline" };
@@ -788,6 +1264,7 @@ export function claimMessage(messageId: number, agentId: string): { ok: boolean;
   try {
     return db.transaction(() => {
       const now = Date.now();
+      const expiresAt = now + CLAIM_LEASE_MS;
       const messageClaim = claimMessageRow(messageId, agentId, now);
       if (!messageClaim.ok) return messageClaim;
 
@@ -803,9 +1280,9 @@ export function claimMessage(messageId: number, agentId: string): { ok: boolean;
       }
 
       const taskClaim = db.prepare(`
-        UPDATE tasks SET status = 'claimed', claimed_by = ?, claimed_at = ?, updated_at = ?
+        UPDATE tasks SET status = 'claimed', claimed_by = ?, claimed_at = ?, claim_expires_at = ?, updated_at = ?
         WHERE id = ? AND message_id = ? AND status IN ('open', 'blocked')
-      `).run(agentId, now, now, taskId, messageId);
+      `).run(agentId, now, expiresAt, now, taskId, messageId);
       if (taskClaim.changes === 0) throw new ClaimError("linked task claim race — already claimed");
 
       insertTaskEvent(taskId, {
@@ -825,6 +1302,34 @@ export function claimMessage(messageId: number, agentId: string): { ok: boolean;
   }
 }
 
+export function renewMessageClaim(messageId: number, agentId: string, guard?: AgentSessionGuard): { ok: boolean; error?: string; task?: Task } {
+  releaseExpiredClaims();
+  const session = validateAgentSession(agentId, guard);
+  if (!session.ok) return { ok: false, error: session.error };
+  const agent = getAgent(agentId);
+  if (!agent) return { ok: false, error: "claiming agent not found" };
+  if (agent.status === "offline") return { ok: false, error: "claiming agent is offline" };
+  const msg = getMessage(messageId);
+  if (!msg) return { ok: false, error: "message not found" };
+  if (!msg.claimable) return { ok: false, error: "message is not claimable" };
+  if (msg.claimedBy !== agentId) return { ok: false, error: msg.claimedBy ? `claimed by ${msg.claimedBy}` : "message is not claimed" };
+
+  const now = Date.now();
+  const expiresAt = now + CLAIM_LEASE_MS;
+  let task: Task | undefined;
+  db.transaction(() => {
+    db.prepare("UPDATE messages SET claim_expires_at = ? WHERE id = ? AND claimed_by = ?").run(expiresAt, messageId, agentId);
+    const taskId = typeof msg.meta?.taskId === "number" && Number.isSafeInteger(msg.meta.taskId)
+      ? msg.meta.taskId
+      : null;
+    if (taskId) {
+      db.prepare("UPDATE tasks SET claim_expires_at = ?, updated_at = ? WHERE id = ? AND claimed_by = ?").run(expiresAt, now, taskId, agentId);
+      task = getTask(taskId) ?? undefined;
+    }
+  })();
+  return { ok: true, task };
+}
+
 export function getMessage(id: number): Message | null {
   const row = db.prepare(`${MSG_SELECT} WHERE m.id = ?`).get(id) as any;
   return row ? rowToMessage(row) : null;
@@ -877,9 +1382,10 @@ export function pollMessages(query: PollQuery): Message[] {
   }
   conditions.push(`(${targetClauses.join(" OR ")})`);
 
-  // Hide claimable messages that were claimed by someone else
-  conditions.push(`(claimable = 0 OR claimed_by IS NULL OR claimed_by = ?)`);
-  params.push(query.for);
+  // Hide active claims held by someone else, but let expired claims surface so
+  // another matching agent can recover stuck work.
+  conditions.push(`(claimable = 0 OR claimed_by IS NULL OR claimed_by = ? OR ((claim_expires_at IS NULL OR claim_expires_at <= ?) AND NOT EXISTS (SELECT 1 FROM tasks t WHERE t.message_id = m.id AND t.status IN ('done', 'failed', 'canceled'))))`);
+  params.push(query.for, Date.now());
 
   if (query.sinceId !== undefined) {
     conditions.push("id > ?");
@@ -979,3 +1485,66 @@ export function getStats(): {
 
   return { version: VERSION, agents, online, messages, messagesLast24h, tasks, openTasks };
 }
+
+export function getHealth(now: number = Date.now()): HealthReport {
+  const checks: HealthCheck[] = [];
+
+  try {
+    db.prepare("SELECT 1").get();
+    checks.push({ name: "database", status: "ok" });
+  } catch (e) {
+    checks.push({ name: "database", status: "error", detail: e instanceof Error ? e.message : "database check failed" });
+  }
+
+  const staleLiveAgents = (db
+    .prepare("SELECT COUNT(*) as c FROM agents WHERE status != 'offline' AND last_seen <= ? AND id NOT IN ('user', 'system')")
+    .get(now - STALE_TTL_MS) as any).c as number;
+  checks.push({
+    name: "stale-live-agents",
+    status: staleLiveAgents > 0 ? "warn" : "ok",
+    count: staleLiveAgents,
+    detail: staleLiveAgents > 0 ? `${staleLiveAgents} non-offline agent(s) missed heartbeat TTL` : undefined,
+  });
+
+  const expiredMessageClaims = (db
+    .prepare("SELECT COUNT(*) as c FROM messages WHERE claimed_by IS NOT NULL AND (claim_expires_at IS NULL OR claim_expires_at <= ?) AND NOT EXISTS (SELECT 1 FROM tasks t WHERE t.message_id = messages.id AND t.status IN ('done', 'failed', 'canceled'))")
+    .get(now) as any).c as number;
+  checks.push({
+    name: "expired-message-claims",
+    status: expiredMessageClaims > 0 ? "warn" : "ok",
+    count: expiredMessageClaims,
+    detail: expiredMessageClaims > 0 ? `${expiredMessageClaims} message claim(s) are expired or missing a lease` : undefined,
+  });
+
+  const expiredTaskClaims = (db
+    .prepare("SELECT COUNT(*) as c FROM tasks WHERE claimed_by IS NOT NULL AND (claim_expires_at IS NULL OR claim_expires_at <= ?) AND status IN ('claimed', 'in_progress', 'blocked')")
+    .get(now) as any).c as number;
+  checks.push({
+    name: "expired-task-claims",
+    status: expiredTaskClaims > 0 ? "warn" : "ok",
+    count: expiredTaskClaims,
+    detail: expiredTaskClaims > 0 ? `${expiredTaskClaims} active task claim(s) are expired or missing a lease` : undefined,
+  });
+
+  const offlineClaimedTasks = (db
+    .prepare(`
+      SELECT COUNT(*) as c
+      FROM tasks t
+      JOIN agents a ON a.id = t.claimed_by
+      WHERE t.status IN ('claimed', 'in_progress', 'blocked') AND a.status = 'offline'
+    `)
+    .get() as any).c as number;
+  checks.push({
+    name: "offline-claimed-tasks",
+    status: offlineClaimedTasks > 0 ? "warn" : "ok",
+    count: offlineClaimedTasks,
+    detail: offlineClaimedTasks > 0 ? `${offlineClaimedTasks} active task(s) are claimed by offline agents` : undefined,
+  });
+
+  const status = checks.some((check) => check.status === "error")
+    ? "error"
+    : checks.some((check) => check.status === "warn")
+      ? "degraded"
+      : "ok";
+  return { status, version: VERSION, generatedAt: now, checks };
+}