agent-relay-server 0.20.0 → 0.21.0

package/runner/src/adapter.ts

@@ -159,7 +159,7 @@ export function profileAllowsRelayFeature(config: RunnerSpawnConfig, feature: ke
   return config.agentProfile?.relay?.[feature] !== false;
 }
 
-export const RELAY_CONTEXT = `[agent-relay] You are connected to Agent Relay, a real-time message bus between agents and users. When you receive a relay message: read it, do what it asks, and reply through the relay when a text response is needed. Use agent-relay /react <messageId> <emoji> for lightweight acknowledgement or approval. If Relay MCP tools are available, prefer relay_reply, relay_get_message, relay_get_thread, relay_send_message, relay_upload_artifact, relay_attach_artifact, relay_agent_status, relay_spawn_agent, and relay_shutdown_agent. CLI fallback: agent-relay /reply <messageId> --stdin < response.md; if a delivered message says it was truncated, fetch the full body with: agent-relay get-message <messageId>. For command details, run: agent-relay /guide`;
+export const RELAY_CONTEXT = `[agent-relay] You are connected to Agent Relay, a real-time message bus between agents and users. When you receive a relay message: read it, do what it asks, and reply through the relay when a text response is needed. Use agent-relay /react <messageId> <emoji> for lightweight acknowledgement or approval. If Relay MCP tools are available, prefer relay_reply, relay_get_message, relay_get_thread, relay_send_message, relay_upload_artifact, relay_attach_artifact, relay_agent_status, relay_find_agents, relay_spawn_agent, and relay_shutdown_agent. You never need to know or pass your own agent id — relay fills it from your token; use relay_whoami only if you need to reason about yourself. relay_spawn_agent / relay_shutdown_agent only appear if your profile grants spawning (a live-children quota); when present you can stand up long-living child agents and shut down your own — find them later with relay_find_agents spawnedBy:me. CLI fallback: agent-relay /reply <messageId> --stdin < response.md; if a delivered message says it was truncated, fetch the full body with: agent-relay get-message <messageId>. For command details, run: agent-relay /guide`;
 
 const PROVIDER_MESSAGE_BODY_PREVIEW_CHARS = 4000;
 

package/scripts/install-bin-shim.cjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-const { existsSync, lstatSync, mkdirSync, readFileSync, writeFileSync, chmodSync } = require("node:fs");
+const { existsSync, lstatSync, mkdirSync, readFileSync, writeFileSync, chmodSync, unlinkSync } = require("node:fs");
 const { homedir } = require("node:os");
 const { delimiter, join, relative } = require("node:path");
 
@@ -31,12 +31,24 @@ function pathContains(dir, env) {
   return String(env.PATH || "").split(delimiter).some((entry) => entry === dir);
 }
 
+function pathEntries(env) {
+  return String(env.PATH || "").split(delimiter).filter(Boolean);
+}
+
 function chooseBinDir(env, home) {
   if (env.AGENT_RELAY_USER_BIN_DIR) return env.AGENT_RELAY_USER_BIN_DIR;
   const localBin = join(home, ".local", "bin");
   const bunBin = join(home, ".bun", "bin");
-  if (pathContains(localBin, env)) return localBin;
-  if (pathContains(bunBin, env)) return bunBin;
+  const candidates = new Set([localBin, bunBin]);
+  const entries = pathEntries(env);
+  for (const entry of entries) {
+    if (!candidates.has(entry)) continue;
+    const shimPath = join(entry, "agent-relay");
+    if (existsSync(shimPath) && canOverwriteShim(shimPath)) return entry;
+  }
+  for (const entry of entries) {
+    if (candidates.has(entry)) return entry;
+  }
   return localBin;
 }
 
@@ -82,6 +94,7 @@ function installShim(env = process.env) {
   }
 
   mkdirSync(binDir, { recursive: true });
+  if (existsSync(shimPath) && lstatSync(shimPath).isSymbolicLink()) unlinkSync(shimPath);
   writeFileSync(shimPath, renderShim(cliPath), "utf8");
   chmodSync(shimPath, 0o755);
 

package/src/agent-ref.ts

@@ -0,0 +1,217 @@
+// Shared agent-reference resolution. ONE home for "given a string an agent typed,
+// which agent(s) does it mean?" — so messaging (send/reply) and pairing can never
+// drift apart again (they used to: messaging matched exact id only, pairing had a
+// rich matcher). See #222.
+//
+// A reference can be:
+//   - an explicit selector: id:  label:  name:  tag:  cap:/capability:  machine:  rig:
+//   - a bare exact match on id, label, name, a tag, a capability, or rig
+//   - a unique id *segment* (the "number part" of a session id), e.g. `c14bd37f`
+//
+// Resolution prefers ONLINE agents so a dead twin can't manufacture ambiguity, and
+// never silently picks among several — it reports candidates instead.
+
+import { STALE_TTL_MS } from "./config";
+import type { AgentCard } from "./types";
+
+export interface ResolveOptions {
+  /** Exclude this agent id from matches (e.g. the requester, when pairing). */
+  excludeId?: string;
+  /** Clock injection for tests. */
+  now?: number;
+}
+
+export type ResolveResult =
+  | { status: "resolved"; agent: AgentCard }
+  | { status: "ambiguous"; candidates: AgentCard[] }
+  | { status: "not_found"; offlineMatches: AgentCard[] };
+
+/** Canonical "is this agent reachable right now" predicate. Single source of truth. */
+export function isAgentOnline(agent: AgentCard, now: number = Date.now()): boolean {
+  return agent.status !== "offline" && agent.ready && agent.lastSeen > now - STALE_TTL_MS;
+}
+
+interface Selector {
+  field: "id" | "label" | "name" | "tag" | "capability" | "machine" | "rig";
+  value: string;
+}
+
+const SELECTOR_PREFIXES: Array<[string, Selector["field"]]> = [
+  ["id:", "id"],
+  ["label:", "label"],
+  ["name:", "name"],
+  ["tag:", "tag"],
+  ["capability:", "capability"],
+  ["cap:", "capability"],
+  ["machine:", "machine"],
+  ["rig:", "rig"],
+];
+
+function parseSelector(ref: string): Selector | null {
+  for (const [prefix, field] of SELECTOR_PREFIXES) {
+    if (ref.startsWith(prefix)) return { field, value: ref.slice(prefix.length).trim() };
+  }
+  return null;
+}
+
+function matchesSelector(agent: AgentCard, selector: Selector): boolean {
+  switch (selector.field) {
+    case "id": return agent.id === selector.value;
+    case "label": return agent.label === selector.value;
+    case "name": return agent.name === selector.value;
+    case "tag": return agent.tags.includes(selector.value);
+    case "capability": return agent.capabilities.includes(selector.value);
+    case "machine": return agent.machine === selector.value;
+    case "rig": return agent.rig === selector.value;
+  }
+}
+
+function matchesExact(agent: AgentCard, ref: string): boolean {
+  return (
+    agent.id === ref ||
+    agent.label === ref ||
+    agent.name === ref ||
+    agent.rig === ref ||
+    agent.tags.includes(ref) ||
+    agent.capabilities.includes(ref)
+  );
+}
+
+// A reference matches an id "segment" when it equals — or is a prefix of — one of the
+// id's delimiter-separated tokens. `session-1780922734580/c14bd37f-fe5d` tokenizes to
+// [session, 1780922734580, c14bd37f, fe5d], so `c14bd37f`, `1780`, or `fe5d` all match.
+function idMatchesSegment(id: string, ref: string): boolean {
+  if (!ref) return false;
+  const tokens = id.split(/[-/_:.]+/).filter(Boolean);
+  return tokens.some((token) => token === ref || token.startsWith(ref));
+}
+
+/**
+ * All agents matching `ref`, using tiered logic: explicit selector wins; otherwise an
+ * exact match (id/label/name/tag/cap/rig) is preferred, and only if there are NO exact
+ * matches do we fall back to id-segment matching. No online filtering, no uniqueness —
+ * the caller decides what to do with multiplicity.
+ */
+export function matchAgents(ref: string, agents: AgentCard[], opts: ResolveOptions = {}): AgentCard[] {
+  const trimmed = ref.trim();
+  if (!trimmed) return [];
+  const pool = opts.excludeId ? agents.filter((a) => a.id !== opts.excludeId) : agents;
+
+  const selector = parseSelector(trimmed);
+  if (selector) return selector.value ? pool.filter((a) => matchesSelector(a, selector)) : [];
+
+  const exact = pool.filter((a) => matchesExact(a, trimmed));
+  if (exact.length) return exact;
+  return pool.filter((a) => idMatchesSegment(a.id, trimmed));
+}
+
+/**
+ * Resolve `ref` to a SINGLE agent. Prefers online matches; reports ambiguity rather
+ * than guessing. On not_found, returns any offline matches so callers can say "exists
+ * but offline" instead of "unknown".
+ */
+export function resolveAgentRef(ref: string, agents: AgentCard[], opts: ResolveOptions = {}): ResolveResult {
+  const now = opts.now ?? Date.now();
+  const matches = matchAgents(ref, agents, opts);
+  if (matches.length === 0) return { status: "not_found", offlineMatches: [] };
+
+  const online = matches.filter((a) => isAgentOnline(a, now));
+  if (online.length === 1) return { status: "resolved", agent: online[0]! };
+  if (online.length > 1) return { status: "ambiguous", candidates: online };
+  return { status: "not_found", offlineMatches: matches };
+}
+
+// --- messaging send planning -------------------------------------------------
+
+export interface DeliveryReceipt {
+  /** A live recipient exists right now. */
+  delivered: boolean;
+  /** Whether the sender should expect a reply (false ⇒ don't block waiting). */
+  expectReply: boolean;
+  /** Online recipient agent ids this message will reach. */
+  recipients: string[];
+  /** Durable fan-out target with no online members — held until one appears. */
+  queued?: boolean;
+  /** Human reason when not delivered. */
+  reason?: string;
+}
+
+export type SendPlan =
+  // resolved/fan-out/passthrough carry the (possibly rewritten) canonical `to`
+  | { kind: "direct" | "fanout" | "passthrough"; to: string; receipt: DeliveryReceipt }
+  | { kind: "not_found"; message: string }
+  | { kind: "ambiguous"; message: string; candidates: AgentCard[] };
+
+const FANOUT_PREFIXES = ["tag:", "cap:", "capability:", "label:"];
+const PASSTHROUGH_PREFIXES = ["policy:", "orchestrator:", "pool:"];
+const RESERVED_TARGETS = new Set(["user", "system"]);
+
+function isPseudoAgent(agent: AgentCard): boolean {
+  return agent.id !== "user" && agent.id !== "system" && agent.kind !== "channel" && (agent.meta?.kind as unknown) !== "channel";
+}
+
+function describeAgent(agent: AgentCard): string {
+  return agent.label ? `${agent.id} (${agent.label})` : agent.id;
+}
+
+function ambiguousMessage(ref: string, candidates: AgentCard[]): string {
+  const list = candidates.slice(0, 8).map(describeAgent).join(", ");
+  const more = candidates.length > 8 ? `, +${candidates.length - 8} more` : "";
+  return `agent reference "${ref}" is ambiguous — matches ${candidates.length}: ${list}${more}. Use a full id, label, or a fan-out selector (tag:/cap:/label:).`;
+}
+
+function notFoundMessage(ref: string, agents: AgentCard[]): string {
+  const needle = ref.toLowerCase();
+  const near = agents
+    .filter((a) => isPseudoAgent(a) && (a.id.toLowerCase().includes(needle) || a.label?.toLowerCase().includes(needle)))
+    .slice(0, 3)
+    .map(describeAgent);
+  const hint = near.length ? ` Did you mean: ${near.join(", ")}?` : "";
+  return `no agent matches "${ref}".${hint}`;
+}
+
+/**
+ * Classify a message target and produce a synchronous delivery receipt. Direct targets
+ * are resolved to a canonical agent id (so poll-time matching works) and report whether
+ * a live recipient exists; fan-out targets report how many online members they reach;
+ * reserved/policy targets pass through unchanged.
+ */
+export function planSend(to: string, agents: AgentCard[], now: number = Date.now()): SendPlan {
+  const target = to.trim();
+
+  if (target === "broadcast") {
+    const recipients = agents.filter((a) => isPseudoAgent(a) && isAgentOnline(a, now)).map((a) => a.id);
+    return { kind: "fanout", to: target, receipt: fanoutReceipt(recipients) };
+  }
+  if (FANOUT_PREFIXES.some((p) => target.startsWith(p))) {
+    const recipients = matchAgents(target.replace(/^cap:/, "capability:"), agents)
+      .filter((a) => isAgentOnline(a, now)).map((a) => a.id);
+    return { kind: "fanout", to: target, receipt: fanoutReceipt(recipients) };
+  }
+  if (RESERVED_TARGETS.has(target) || PASSTHROUGH_PREFIXES.some((p) => target.startsWith(p))) {
+    return { kind: "passthrough", to: target, receipt: { delivered: true, expectReply: true, recipients: [target] } };
+  }
+
+  // Direct single-agent reference.
+  const resolved = resolveAgentRef(target, agents, { now });
+  if (resolved.status === "resolved") {
+    return { kind: "direct", to: resolved.agent.id, receipt: { delivered: true, expectReply: true, recipients: [resolved.agent.id] } };
+  }
+  if (resolved.status === "ambiguous") {
+    return { kind: "ambiguous", message: ambiguousMessage(target, resolved.candidates), candidates: resolved.candidates };
+  }
+  // not_found online — maybe it exists but is offline.
+  const offline = resolved.offlineMatches;
+  if (offline.length === 1) {
+    return { kind: "direct", to: offline[0]!.id, receipt: { delivered: false, expectReply: false, recipients: [], reason: "recipient offline" } };
+  }
+  if (offline.length > 1) {
+    return { kind: "ambiguous", message: ambiguousMessage(target, offline), candidates: offline };
+  }
+  return { kind: "not_found", message: notFoundMessage(target, agents) };
+}
+
+function fanoutReceipt(recipients: string[]): DeliveryReceipt {
+  if (recipients.length === 0) return { delivered: false, expectReply: false, recipients: [], queued: true, reason: "no online members — queued" };
+  return { delivered: true, expectReply: true, recipients };
+}

package/src/automations.ts

@@ -14,7 +14,7 @@ import {
 } from "./db";
 import { createCommand } from "./commands-db";
 import { cleanEnum, cleanString, cleanStringArray, optionalEnum } from "./validation";
-import { getAgentProfile, getSpawnPolicy } from "./config-store";
+import { getAgentProfile, getSpawnPolicy, spawnGrantForProfile } from "./config-store";
 import { buildSpawnCommand, resolveSpawnModelParams } from "./spawn-command";
 import { resolveProviderSelection, type ProviderEffort, VALID_EFFORTS } from "agent-relay-sdk/provider-catalog";
 import { errMessage, VALID_WORKSPACE_MODES } from "agent-relay-sdk";
@@ -511,6 +511,7 @@ function dispatchOnDemandAutomation(
 ): AutomationDispatchResult {
   if (!orchestrator.providers.includes(policy.provider)) throw new ValidationError(`orchestrator ${orchestrator.id} does not have provider available: ${policy.provider}`);
   const agentProfile = policy.profile ? getAgentProfile(policy.profile)?.value : undefined;
+  const grant = spawnGrantForProfile(policy.profile);
   const label = automationRunLabel(automation.id, run.id);
   const command = createCommand({
     type: "agent.spawn",
@@ -535,6 +536,8 @@ function dispatchOnDemandAutomation(
         provider: policy.provider,
         label,
         createdBy: "automation",
+        canSpawn: grant.canSpawn,
+        maxSpawnedAgents: grant.maxSpawnedAgents,
       }),
     }),
   });

package/src/cli.ts

@@ -49,6 +49,8 @@ import { shellQuote } from "agent-relay-sdk/shell-utils";
 import { errMessage, RELAY_TOKEN_HEADER } from "agent-relay-sdk";
 import type { WorkspaceDepsRefreshResult } from "agent-relay-sdk";
 
+export const WORKSPACE_USAGE = "Usage: agent-relay workspace <status|diagnostics|ready|land|claim|release|list|cleanup-stale|deps> [--id ID] [--strategy ...] [--purpose TEXT] [--repo PATH] [--check] [--execute] [--json]";
+
 const HELP = `
 agent-relay ${VERSION}
 
@@ -68,7 +70,7 @@ Usage:
   agent-relay context-probe [print-status-line] [--wrap COMMAND] [--agent-id ID] [--state-dir DIR] [--standalone]
   agent-relay token <create|list|revoke|verify> [options]
   agent-relay pair <target|create|status|accept|reject|hangup|send> [options]
-  agent-relay workspace <status|diagnostics|ready|land|claim|release|list|cleanup-stale|deps> [--id ID] [--strategy …] [--purpose TEXT] [--repo PATH] [--check] [--execute] [--json]
+  agent-relay workspace <status|diagnostics|ready|land|claim|release|list|cleanup-stale|deps> [--id ID] [--strategy ...] [--purpose TEXT] [--repo PATH] [--check] [--execute] [--json]
   agent-relay steward <queue|inspect|checks> [WORKSPACE_ID] [--repo PATH] [--json]
   agent-relay message <target> <body> [options]
   agent-relay get-message <messageId> [--json|--body]
@@ -1577,8 +1579,12 @@ function formatDepsRefresh(result: WorkspaceDepsRefreshResult, checkOnly: boolea
 async function handleWorkspaceCommand(args: string[]): Promise<void> {
   const action = args[0];
   const valid = new Set(["status", "ready", "land", "list", "diagnostics", "diag", "claim", "release", "cleanup-stale", "deps"]);
+  if (action === "--help" || action === "-h" || action === "help") {
+    console.log(WORKSPACE_USAGE);
+    return;
+  }
   if (!action || !valid.has(action)) {
-    throw new Error("Usage: agent-relay workspace <status|diagnostics|ready|land|claim|release|list|cleanup-stale|deps> [--id ID] [--strategy …] [--purpose TEXT] [--repo PATH] [--check] [--execute] [--json]");
+    throw new Error(WORKSPACE_USAGE);
   }
 
   let id = currentWorkspaceId();

package/src/config-store.ts

@@ -173,6 +173,20 @@ function cleanJsonRecord(value: unknown, field: string): Record<string, unknown>
   return value;
 }
 
+function cleanAgentProfileProviderOptions(value: unknown): Record<string, unknown> {
+  const options = cleanJsonRecord(value, "providerOptions");
+  if (options.codex === undefined || options.codex === null) return options;
+  if (!isRecord(options.codex)) throw new ValidationError("providerOptions.codex must be an object");
+  const codex = { ...options.codex };
+  if ("toolOutputTokenLimit" in codex && codex.toolOutputTokenLimit !== null) {
+    codex.toolOutputTokenLimit = cleanNumber(codex.toolOutputTokenLimit, "providerOptions.codex.toolOutputTokenLimit", {
+      min: 1_000,
+      max: 200_000,
+    });
+  }
+  return { ...options, codex };
+}
+
 function cleanBoolean(value: unknown, field: string): boolean {
   if (typeof value !== "boolean") throw new ValidationError(`${field} must be a boolean`);
   return value;
@@ -221,6 +235,7 @@ function agentProfileDefaults(input: Pick<AgentProfile, "name" | "base"> & Parti
     },
     env: input.env ?? {},
     providerOptions: input.providerOptions ?? {},
+    ...(input.maxSpawnedAgents === undefined ? {} : { maxSpawnedAgents: input.maxSpawnedAgents }),
   };
 }
 
@@ -295,7 +310,10 @@ function validateAgentProfile(key: string, value: unknown): AgentProfile {
         : cleanEnum(permissions.filesystem, "permissions.filesystem", VALID_PROFILE_FILESYSTEM_SCOPES),
     },
     env: cleanStringRecord(value.env, "env"),
-    providerOptions: cleanJsonRecord(value.providerOptions, "providerOptions"),
+    providerOptions: cleanAgentProfileProviderOptions(value.providerOptions),
+    maxSpawnedAgents: value.maxSpawnedAgents === undefined || value.maxSpawnedAgents === null
+      ? undefined
+      : cleanNumber(value.maxSpawnedAgents, "maxSpawnedAgents", { min: 0, max: 100 }),
   });
 }
 
@@ -657,6 +675,22 @@ export function getAgentProfile(name: string): ConfigEntry<AgentProfile> | null
   return getConfig<AgentProfile>(AGENT_PROFILE_NAMESPACE, name);
 }
 
+/**
+ * Resolve the spawn grant for a named profile (#221). `canSpawn` gates whether the agent's
+ * runtime token gets the `command:spawn`/`command:shutdown` scope; `maxSpawnedAgents` is the
+ * live-children quota baked into the token. Unknown/absent profile or `0` → no spawn (strict
+ * default). Callers pass `agentInitiated: true` for agent-requested spawns to force the child
+ * to NEVER be spawn-capable (no grandchildren), regardless of the child's profile.
+ */
+export function spawnGrantForProfile(
+  profileName: string | undefined,
+  agentInitiated = false,
+): { canSpawn: boolean; maxSpawnedAgents: number } {
+  if (agentInitiated) return { canSpawn: false, maxSpawnedAgents: 0 };
+  const n = profileName ? (getAgentProfile(profileName)?.value.maxSpawnedAgents ?? 0) : 0;
+  return { canSpawn: n > 0, maxSpawnedAgents: n };
+}
+
 export function listAgentProfiles(): ConfigEntry<AgentProfile>[] {
   const custom = listConfig<AgentProfile>(AGENT_PROFILE_NAMESPACE);
   return [

package/src/context-router.ts

@@ -1,4 +1,5 @@
 import type { AgentCard } from "./types";
+import { matchAgents } from "./agent-ref";
 
 export interface RouteAdvisorInput {
   text?: string;
@@ -39,7 +40,7 @@ function routeEligible(agent: AgentCard, input: RouteAdvisorInput, maxUtilizatio
   if (agent.id === "user" || agent.id === "system" || agent.kind === "channel") return false;
   if (agent.meta?.kind === "channel" || agent.tags.includes("channel")) return false;
   if (agent.status === "offline" || agent.status === "stale") return false;
-  if (input.target && !agentMatchesTarget(agent, input.target)) return false;
+  if (input.target && !matchesRouteTarget(agent, input.target)) return false;
   if (input.capabilities?.length && !input.capabilities.every((cap) => agent.capabilities.includes(cap))) return false;
   if (input.tags?.length && !input.tags.every((tag) => agent.tags.includes(tag))) return false;
   if (maxUtilization !== undefined && (agent.context?.utilization ?? 0) > maxUtilization) return false;
@@ -67,11 +68,10 @@ function scoreAgent(agent: AgentCard, input: RouteAdvisorInput, terms: Set<strin
   };
 }
 
-function agentMatchesTarget(agent: AgentCard, target: string): boolean {
-  if (target === "broadcast") return true;
-  if (target.startsWith("tag:")) return agent.tags.includes(target.slice(4));
-  if (target.startsWith("cap:")) return agent.capabilities.includes(target.slice(4));
-  return agent.id === target || agent.label === target;
+// Broadcast matches every candidate; everything else delegates to the shared resolver
+// (src/agent-ref.ts) so routing accepts the same ref forms as messaging and pairing.
+function matchesRouteTarget(agent: AgentCard, target: string): boolean {
+  return target === "broadcast" || matchAgents(target, [agent]).length > 0;
 }
 
 function termsFromText(text: string | undefined): Set<string> {
@@ -100,7 +100,7 @@ function affinityScore(agent: AgentCard, input: RouteAdvisorInput): number {
   }
   if (input.target) {
     possible++;
-    score += agentMatchesTarget(agent, input.target) ? 1 : 0;
+    score += matchesRouteTarget(agent, input.target) ? 1 : 0;
   }
   return possible === 0 ? 0.5 : score / possible;
 }

package/src/db.ts

@@ -74,6 +74,7 @@ import type {
   WorkspaceStatus,
 } from "./types";
 import { STALE_TTL_MS, DAY_MS, CLAIM_LEASE_MS, POOL_CLAIM_LEASE_MS, WORKSPACE_MERGE_LEASE_MS } from "./config";
+import { matchAgents } from "./agent-ref";
 
 let db: Database;
 const CONTEXT_SNAPSHOT_DEBOUNCE_MS = 60_000;
@@ -210,6 +211,7 @@ export function initDb(path: string = "agent-relay.db"): Database {
       provider_capabilities TEXT,
       context_state TEXT,
       meta TEXT NOT NULL DEFAULT '{}',
+      spawned_by TEXT,
       last_seen INTEGER NOT NULL,
       created_at INTEGER NOT NULL
     );
@@ -1047,6 +1049,9 @@ export function initDb(path: string = "agent-relay.db"): Database {
   if (!agentColNames.includes("context_state")) {
     db.run("ALTER TABLE agents ADD COLUMN context_state TEXT");
   }
+  if (!agentColNames.includes("spawned_by")) {
+    db.run("ALTER TABLE agents ADD COLUMN spawned_by TEXT");
+  }
   db.run(`
     CREATE TABLE IF NOT EXISTS context_snapshots (
       id INTEGER PRIMARY KEY AUTOINCREMENT,
@@ -1245,6 +1250,7 @@ function rowToAgent(row: any): AgentCard {
     providerCapabilities: parseJson<ProviderCapabilities | undefined>(row.provider_capabilities, undefined),
     context: parseJson<ContextState | undefined>(row.context_state, undefined),
     meta: parseJson(row.meta, {}),
+    spawnedBy: row.spawned_by ?? undefined,
     lastSeen: row.last_seen,
     createdAt: row.created_at,
   };
@@ -1747,8 +1753,8 @@ export function upsertAgent(input: RegisterAgentInput): AgentCard {
   const readyProvided = Object.prototype.hasOwnProperty.call(input, "ready");
   const instanceProvided = Boolean(input.instanceId);
   const stmt = db.query(`
-    INSERT INTO agents (id, name, kind, label, tags, machine, rig, capabilities, ready, status, instance_id, epoch, provider_capabilities, context_state, meta, last_seen, created_at)
-    VALUES ($id, $name, $kind, $label, $tags, $machine, $rig, $capabilities, $ready, $status, $instanceId, $initialEpoch, $providerCapabilities, $contextState, $meta, $now, $now)
+    INSERT INTO agents (id, name, kind, label, tags, machine, rig, capabilities, ready, status, instance_id, epoch, provider_capabilities, context_state, meta, spawned_by, last_seen, created_at)
+    VALUES ($id, $name, $kind, $label, $tags, $machine, $rig, $capabilities, $ready, $status, $instanceId, $initialEpoch, $providerCapabilities, $contextState, $meta, $spawnedBy, $now, $now)
     ON CONFLICT(id) DO UPDATE SET
       name = $name,
       kind = $kind,
@@ -1767,6 +1773,7 @@ export function upsertAgent(input: RegisterAgentInput): AgentCard {
       provider_capabilities = coalesce($providerCapabilities, agents.provider_capabilities),
       context_state = coalesce($contextState, agents.context_state),
       meta = $meta,
+      spawned_by = coalesce($spawnedBy, agents.spawned_by),
       last_seen = $now
   `);
 
@@ -1789,6 +1796,7 @@ export function upsertAgent(input: RegisterAgentInput): AgentCard {
     $providerCapabilities: input.providerCapabilities ? JSON.stringify(input.providerCapabilities) : null,
     $contextState: input.context ? JSON.stringify(input.context) : null,
     $meta: JSON.stringify(input.meta ?? {}),
+    $spawnedBy: input.spawnedBy ?? null,
     $now: now,
   });
   if (input.context) recordContextSnapshot(input.id, input.context, now);
@@ -1858,6 +1866,106 @@ export function listAgents(filter?: {
   return (db.query(sql).all(...params) as any[]).map(rowToAgent);
 }
 
+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;
+}
+
+const AGENT_SEARCH_MAX_LIMIT = 200;
+
+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 db.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 (db.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.
+export function countLiveSpawnedAgents(parentId: string, now: number = Date.now()): number {
+  const row = db.query(
+    "SELECT count(*) AS n FROM agents WHERE spawned_by = ? AND status NOT IN ('offline', 'stale') AND ready = 1 AND last_seen > ?",
+  ).get(parentId, now - STALE_TTL_MS) as { n: number };
+  return row.n;
+}
+
 export function setStatus(id: string, status: AgentCard["status"], guard?: AgentSessionGuard): boolean {
   if (!validateAgentSession(id, guard).ok) return false;
   const now = Date.now();
@@ -2350,17 +2458,6 @@ export function pruneOfflineAgents(maxOfflineMs: number = DAY_MS): string[] {
   })();
 }
 
-export function findAgentsByCapability(capability: string, onlineOnly = true): AgentCard[] {
-  let sql = `SELECT * FROM agents WHERE EXISTS (SELECT 1 FROM json_each(capabilities) WHERE value = ?)`;
-  const params: any[] = [capability];
-  if (onlineOnly) {
-    sql += ` AND status != 'offline' AND last_seen > ?`;
-    params.push(Date.now() - STALE_TTL_MS);
-  }
-  sql += " ORDER BY last_seen DESC";
-  return (db.query(sql).all(...params) as any[]).map(rowToAgent);
-}
-
 export function deleteAgent(id: string): { ok: boolean; error?: string } {
   if (id === "user" || id === "system") {
     return { ok: false, error: "built-in agent cannot be deleted" };
@@ -3023,21 +3120,6 @@ 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;
@@ -3048,7 +3130,7 @@ function resolvePairTarget(target: string, requesterId: string): {
   matches?: AgentCard[];
   busy?: Array<{ agent: AgentCard; pair: PairSession }>;
 } {
-  const matches = listAgents().filter((agent) => agent.id !== requesterId && agentMatchesPairTarget(agent, target));
+  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);