agent-relay-server 0.33.0 → 0.33.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-relay-server",
-  "version": "0.33.0",
+  "version": "0.33.1",
   "description": "Lightweight HTTP message relay for inter-agent communication across machines",
   "module": "src/index.ts",
   "type": "module",

package/src/channel-target.ts

@@ -0,0 +1,24 @@
+import type { ChannelRouteTarget } from "./types";
+
+// Canonical parser for a channel route-target address — the `pool:` / `policy:` /
+// `label:` / `tag:` / `cap:` / `orchestrator:` / `broadcast` wire form. Single
+// source of truth: both the routes POST path (routeTargetFromAddress) and the db
+// legacy-target path (routeTargetFromLegacyTarget) call this, so they can't drift.
+//
+// They DID drift — the db copy silently dropped `policy:`, so a `policy:`
+// configured agent target parsed to { type: "agent", id: "policy:foo" } and never
+// routed (surfaced in #299, fixed with the db split #298). Keep this the only
+// place that maps an address string to a ChannelRouteTarget.
+//
+// Pure and non-throwing: it always returns a typed target. Callers apply their
+// own policy on top (e.g. the routes path rejects `orchestrator:` as unsupported).
+export function parseChannelRouteTarget(target: string): ChannelRouteTarget {
+  if (target.startsWith("pool:")) return { type: "pool", id: target.slice("pool:".length) };
+  if (target.startsWith("policy:")) return { type: "policy", id: target.slice("policy:".length) };
+  if (target.startsWith("label:")) return { type: "label", id: target.slice("label:".length) };
+  if (target.startsWith("tag:")) return { type: "tag", id: target.slice("tag:".length) };
+  if (target.startsWith("cap:")) return { type: "capability", id: target.slice("cap:".length) };
+  if (target === "broadcast") return { type: "broadcast" };
+  if (target.startsWith("orchestrator:")) return { type: "orchestrator", id: target.slice("orchestrator:".length) };
+  return { type: "agent", id: target };
+}

package/src/db/activity.ts

@@ -0,0 +1,194 @@
+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 { getDb } from "./connection.ts";
+import { rowToActivityEvent } from "./mappers.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 function listActivityEvents(input: {
+  operatorId?: string;
+  agentId?: string;
+  limit?: number;
+  since?: number;
+} = {}): ActivityEvent[] {
+  const conditions: string[] = [];
+  const params: any[] = [];
+  if (input.operatorId) {
+    conditions.push("operator_id = ?");
+    params.push(input.operatorId);
+  }
+  if (input.agentId) {
+    conditions.push("agent_id = ?");
+    params.push(input.agentId);
+  }
+  if (input.since !== undefined) {
+    conditions.push("created_at >= ?");
+    params.push(input.since);
+  }
+  const where = conditions.length ? `WHERE ${conditions.join(" AND ")}` : "";
+  params.push(input.limit ?? 200);
+  return (getDb().query(
+    `SELECT * FROM activity_events ${where} ORDER BY created_at DESC, id DESC LIMIT ?`,
+  ).all(...params) as any[]).map(rowToActivityEvent);
+}
+
+export interface AgentTimelineEntry {
+  ts: number;
+  source: "activity" | "command" | "delivery";
+  kind: string;
+  title: string;
+  detail?: string;
+  metadata?: Record<string, unknown>;
+}
+
+// One unified, newest-first stream of everything that happened to an agent —
+// lifecycle transitions, liveness mismatches, commands + outcomes, and delivery
+// attempts — joined by agentId and (for managed agents) policyName. Backs the
+// agent-drawer timeline without new write paths.
+export function getAgentTimeline(agentId: string, opts: { limit?: number; since?: number } = {}): AgentTimelineEntry[] {
+  const limit = opts.limit ?? 200;
+  const since = opts.since;
+  const entries: AgentTimelineEntry[] = [];
+
+  for (const ev of listActivityEvents({ agentId, limit, since })) {
+    entries.push({ ts: ev.createdAt, source: "activity", kind: ev.kind, title: ev.title, detail: ev.body, metadata: ev.metadata });
+  }
+
+  // Managed agents: include policy-scoped lifecycle transitions recorded before
+  // the agent registered (agent_id null), correlated via metadata.policyName.
+  const managed = getDb().query("SELECT policy_name FROM managed_agent_state WHERE agent_id = ? LIMIT 1").get(agentId) as { policy_name?: string } | undefined;
+  if (managed?.policy_name) {
+    const rows = (since !== undefined
+      ? getDb().query("SELECT * FROM activity_events WHERE agent_id IS NULL AND json_extract(metadata, '$.policyName') = ? AND created_at >= ? ORDER BY created_at DESC LIMIT ?").all(managed.policy_name, since, limit)
+      : getDb().query("SELECT * FROM activity_events WHERE agent_id IS NULL AND json_extract(metadata, '$.policyName') = ? ORDER BY created_at DESC LIMIT ?").all(managed.policy_name, limit)) as any[];
+    for (const ev of rows.map(rowToActivityEvent)) {
+      entries.push({ ts: ev.createdAt, source: "activity", kind: ev.kind, title: ev.title, detail: ev.body, metadata: ev.metadata });
+    }
+  }
+
+  // Commands targeting this agent (spawn/shutdown/restart/compact) with outcome.
+  const cmds = (since !== undefined
+    ? getDb().query("SELECT id, type, status, result, correlation_id, created_at, updated_at FROM commands WHERE target = ? AND updated_at >= ? ORDER BY updated_at DESC LIMIT ?").all(agentId, since, limit)
+    : getDb().query("SELECT id, type, status, result, correlation_id, created_at, updated_at FROM commands WHERE target = ? ORDER BY updated_at DESC LIMIT ?").all(agentId, limit)) as any[];
+  for (const c of cmds) {
+    entries.push({ ts: c.updated_at ?? c.created_at, source: "command", kind: c.type, title: `${c.type} · ${c.status}`, detail: c.result ?? undefined, metadata: { id: c.id, status: c.status, correlationId: c.correlation_id ?? undefined } });
+  }
+
+  // Delivery attempts involving this agent (failures, retries, poison).
+  const attempts = (since !== undefined
+    ? getDb().query("SELECT * FROM message_delivery_attempts WHERE agent_id = ? AND created_at >= ? ORDER BY created_at DESC LIMIT ?").all(agentId, since, limit)
+    : getDb().query("SELECT * FROM message_delivery_attempts WHERE agent_id = ? ORDER BY created_at DESC LIMIT ?").all(agentId, limit)) as any[];
+  for (const row of attempts) {
+    entries.push({ ts: row.created_at, source: "delivery", kind: `delivery.${row.action}`, title: `delivery ${row.status}`, detail: row.error ?? undefined, metadata: { messageId: row.message_id, status: row.status, poisonReason: row.poison_reason ?? undefined } });
+  }
+
+  entries.sort((a, b) => b.ts - a.ts);
+  return entries.slice(0, limit);
+}
+
+export function createActivityEvent(input: ActivityEventInput): ActivityEvent {
+  if (input.clientId) {
+    const existing = getDb().query("SELECT * FROM activity_events WHERE client_id = ?").get(input.clientId) as any | undefined;
+    if (existing) return rowToActivityEvent(existing);
+  }
+  const now = Date.now();
+  const result = getDb().query(`
+    INSERT INTO activity_events (
+      operator_id, client_id, kind, title, body, meta_text, icon, view, peer_id,
+      message_id, pair_id, task_id, agent_id, metadata, created_at
+    )
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `).run(
+    input.operatorId ?? null,
+    input.clientId ?? null,
+    input.kind,
+    input.title,
+    input.body ?? null,
+    input.meta ?? null,
+    input.icon ?? null,
+    input.view ?? null,
+    input.peer ?? null,
+    input.messageId ?? null,
+    input.pairId ?? null,
+    input.taskId ?? null,
+    input.agentId ?? null,
+    JSON.stringify(input.metadata ?? {}),
+    now,
+  );
+  return rowToActivityEvent(getDb().query("SELECT * FROM activity_events WHERE id = ?").get(Number(result.lastInsertRowid)));
+}
+

package/src/db/agent-search.ts

@@ -0,0 +1,174 @@
+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 { getDb } from "./connection.ts";
+import { rowToAgent } from "./mappers.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 interface AgentSearchFilter {
+  /** Substring match on label OR name (case-insensitive). */
+  label?: string;
+  /** One or more capabilities (OR within the field), via json_each(capabilities). */
+  capability?: string | string[];
+  /** One or more tags (OR within the field), via json_each(tags). */
+  tag?: string | string[];
+  /** Real model provider — providerCapabilities.model.provider (e.g. "claude", "codex"). */
+  provider?: string | string[];
+  machine?: string | string[];
+  /** provider/orchestrator/channel/etc. */
+  kind?: string | string[];
+  /** Specific status(es), the "running" shorthand (live + ready + fresh), or "all". */
+  status?: string | string[];
+  /** Exact parent agent id — backs the `spawnedBy:` / `spawnedBy:me` fleet filter (#221). */
+  spawnedBy?: string;
+}
+
+export interface AgentSearchSort {
+  sortBy?: "lastActive" | "created" | "label";
+  order?: "asc" | "desc";
+  limit?: number;
+}
+
+export const AGENT_SEARCH_MAX_LIMIT = 200;
+
+export function searchValues(value: string | string[] | undefined): string[] {
+  if (value == null) return [];
+  return (Array.isArray(value) ? value : [value]).filter((v): v is string => typeof v === "string" && v.length > 0);
+}
+
+// Unified fleet search: all filters optional and AND-combined; array values OR within a
+// field. One parameterized query (no JS post-filter, no injection). Backs relay_find_agents
+// (#219) and the running-only relay_agent_status default (#218). "running" mirrors the
+// canonical liveness predicate (see getDb().ts delivery/steward checks + isAgentOnline).
+export function searchAgents(filter: AgentSearchFilter = {}, sort: AgentSearchSort = {}): AgentCard[] {
+  const clauses: string[] = ["1=1"];
+  const params: any[] = [];
+  const inList = (column: string, values: string[]) => {
+    clauses.push(`${column} IN (${values.map(() => "?").join(",")})`);
+    params.push(...values);
+  };
+
+  if (filter.label) {
+    clauses.push("(label LIKE ? OR name LIKE ?)");
+    params.push(`%${filter.label}%`, `%${filter.label}%`);
+  }
+  const caps = searchValues(filter.capability);
+  if (caps.length) {
+    clauses.push(`EXISTS (SELECT 1 FROM json_each(capabilities) WHERE value IN (${caps.map(() => "?").join(",")}))`);
+    params.push(...caps);
+  }
+  const tags = searchValues(filter.tag);
+  if (tags.length) {
+    clauses.push(`EXISTS (SELECT 1 FROM json_each(tags) WHERE value IN (${tags.map(() => "?").join(",")}))`);
+    params.push(...tags);
+  }
+  const providers = searchValues(filter.provider);
+  if (providers.length) {
+    clauses.push(`json_extract(provider_capabilities, '$.model.provider') IN (${providers.map(() => "?").join(",")})`);
+    params.push(...providers);
+  }
+  const machines = searchValues(filter.machine);
+  if (machines.length) inList("machine", machines);
+  const kinds = searchValues(filter.kind);
+  if (kinds.length) inList("kind", kinds);
+  if (filter.spawnedBy) {
+    clauses.push("spawned_by = ?");
+    params.push(filter.spawnedBy);
+  }
+
+  const statuses = searchValues(filter.status);
+  if (!statuses.includes("all")) {
+    if (statuses.includes("running")) {
+      clauses.push("status NOT IN ('offline', 'stale') AND ready = 1 AND last_seen > ?");
+      params.push(Date.now() - STALE_TTL_MS);
+    }
+    const explicit = statuses.filter((s) => s !== "running" && s !== "all");
+    if (explicit.length) inList("status", explicit);
+  }
+
+  const sortColumn = sort.sortBy === "created" ? "created_at" : sort.sortBy === "label" ? "label COLLATE NOCASE" : "last_seen";
+  const order = sort.order === "asc" ? "ASC" : "DESC";
+  const limit = Math.max(1, Math.min(sort.limit ?? 50, AGENT_SEARCH_MAX_LIMIT));
+  params.push(limit);
+
+  const sql = `SELECT * FROM agents WHERE ${clauses.join(" AND ")} ORDER BY ${sortColumn} ${order} LIMIT ?`;
+  return (getDb().query(sql).all(...params) as any[]).map(rowToAgent);
+}
+
+// Count of a parent's currently-LIVE children — the spawn quota numerator (#221). "Live"
+// mirrors the running predicate (not offline/stale, ready, fresh); a child that exits frees
+// a slot. Uncapped COUNT (unlike searchAgents' LIMIT) so the quota is exact at any fleet size.