agent-relay-server 0.67.1 → 0.68.1

package/src/db/agent-search.ts

@@ -103,6 +103,7 @@ export interface AgentSearchSort {
   sortBy?: "lastActive" | "created" | "label";
   order?: "asc" | "desc";
   limit?: number;
+  offset?: number;
 }
 
 const AGENT_SEARCH_MAX_LIMIT = 200;
@@ -112,11 +113,8 @@ function searchValues(value: string | string[] | undefined): string[] {
   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[] {
+// Shared clause builder — backs both searchAgents (paginated rows) and countAgents (total).
+function buildWhereClauses(filter: AgentSearchFilter): { clauses: string[]; params: any[] } {
   const clauses: string[] = ["1=1"];
   const params: any[] = [];
   const inList = (column: string, values: string[]) => {
@@ -166,15 +164,31 @@ export function searchAgents(filter: AgentSearchFilter = {}, sort: AgentSearchSo
     if (explicit.length) inList("status", explicit);
   }
 
+  return { clauses, params };
+}
+
+// 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, params } = buildWhereClauses(filter);
   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 ?`;
+  const offset = Math.max(0, sort.offset ?? 0);
+  params.push(limit, offset);
+  const sql = `SELECT * FROM agents WHERE ${clauses.join(" AND ")} ORDER BY ${sortColumn} ${order} LIMIT ? OFFSET ?`;
   return (getDb().query(sql).all(...params) as any[]).map(rowToAgent);
 }
 
+// Total matching row count for the same filter — paired with searchAgents for pagination (#548).
+export function countAgents(filter: AgentSearchFilter = {}): number {
+  const { clauses, params } = buildWhereClauses(filter);
+  const sql = `SELECT COUNT(*) as cnt FROM agents WHERE ${clauses.join(" AND ")}`;
+  return ((getDb().query(sql).get(...params) as { cnt: number } | null)?.cnt) ?? 0;
+}
+
 // 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.

package/src/db/index.ts

@@ -28,3 +28,4 @@ export * from "./teams.ts";
 export * from "./blackboard.ts";
 export * from "./projects.ts";
 export * from "./project-entries.ts";
+export * from "./provisioning-registry.ts";

package/src/db/migrations.ts

@@ -540,6 +540,23 @@ export function applyMigrations(): void {
   if (!agentColNames.includes("lifecycle")) {
     getDb().run("ALTER TABLE agents ADD COLUMN lifecycle TEXT NOT NULL DEFAULT 'persistent'");
   }
+
+  // Relay-owned provisioning registry (#554/#555/#556) — see schema.ts for the
+  // canonical DDL; mirrored here so existing DBs gain the table on upgrade.
+  getDb().run(`
+    CREATE TABLE IF NOT EXISTS provisioning_assets (
+      id TEXT PRIMARY KEY,
+      kind TEXT NOT NULL,
+      name TEXT NOT NULL,
+      provider TEXT NOT NULL DEFAULT 'any',
+      definition TEXT NOT NULL,
+      enabled INTEGER NOT NULL DEFAULT 1,
+      created_at INTEGER NOT NULL,
+      updated_at INTEGER NOT NULL,
+      UNIQUE(kind, name, provider)
+    )
+  `);
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_provisioning_assets_kind ON provisioning_assets(kind, enabled)");
   if (!agentColNames.includes("spawned_by")) {
     getDb().run("ALTER TABLE agents ADD COLUMN spawned_by TEXT");
   }

package/src/db/provisioning-registry.ts

@@ -0,0 +1,278 @@
+import { randomUUID } from "node:crypto";
+import { getDb, ValidationError } from "./connection.ts";
+import { parseJson } from "../utils";
+import { isRecord } from "agent-relay-sdk";
+import type {
+  AgentProfile,
+  AgentProfileAssetRef,
+  AgentProfileProvider,
+  McpAssetDefinition,
+  PluginAssetDefinition,
+  ProvisioningAsset,
+  ProvisioningAssetKind,
+  ProvisioningMcpServer,
+  ResolvedAssetDefinition,
+  ResolvedProvisioning,
+  SkillAssetDefinition,
+  SpawnProvider,
+} from "agent-relay-sdk";
+
+// Relay-owned provisioning registry (#554/#555/#556). One table, one shape across
+// skills/MCP/plugins: named definitions (the materializable content) keyed by
+// (kind, name), selected by a profile's asset refs. The resolver below turns a
+// profile's refs into a concrete ResolvedProvisioning bundle the runner writes into
+// the launch. #557 (per-profile assembly) is meant to be a thin unifier on top, so
+// this stays the single home for asset definition + resolution — not three modules.
+
+const PROVISIONING_ASSET_KINDS = ["skill", "mcp", "plugin"] as const;
+const PROVISIONING_PROVIDERS = ["claude", "codex", "any"] as const;
+
+interface ProvisioningAssetRow {
+  id: string;
+  kind: ProvisioningAssetKind;
+  name: string;
+  provider: AgentProfileProvider;
+  definition: string;
+  enabled: number;
+  created_at: number;
+  updated_at: number;
+}
+
+interface UpsertProvisioningAssetInput {
+  kind: ProvisioningAssetKind;
+  name: string;
+  provider?: AgentProfileProvider;
+  definition: ResolvedAssetDefinition;
+  enabled?: boolean;
+}
+
+function assetId(): string {
+  return `pa_${randomUUID().replace(/-/g, "").slice(0, 16)}`;
+}
+
+function assertKind(kind: ProvisioningAssetKind): void {
+  if (!PROVISIONING_ASSET_KINDS.includes(kind)) {
+    throw new ValidationError(`kind must be one of: ${PROVISIONING_ASSET_KINDS.join(", ")}`);
+  }
+}
+
+function assertProvider(provider: AgentProfileProvider): void {
+  if (!PROVISIONING_PROVIDERS.includes(provider)) {
+    throw new ValidationError(`provider must be one of: ${PROVISIONING_PROVIDERS.join(", ")}`);
+  }
+}
+
+function assertDefinition(kind: ProvisioningAssetKind, definition: ResolvedAssetDefinition): void {
+  if (!isRecord(definition)) throw new ValidationError("definition must be an object");
+  if (definition.kind !== kind) throw new ValidationError(`definition.kind (${definition.kind}) must match asset kind (${kind})`);
+  if (kind === "mcp" && !isRecord((definition as McpAssetDefinition).server)) {
+    throw new ValidationError("mcp definition requires a server object");
+  }
+  if ((kind === "skill" || kind === "plugin")) {
+    const def = definition as SkillAssetDefinition | PluginAssetDefinition;
+    if (!def.files?.length && !def.dir) throw new ValidationError(`${kind} definition requires files or dir`);
+  }
+}
+
+function rowToAsset(row: ProvisioningAssetRow): ProvisioningAsset {
+  return {
+    id: row.id,
+    kind: row.kind,
+    name: row.name,
+    provider: row.provider,
+    definition: parseJson<ResolvedAssetDefinition>(row.definition, { kind: row.kind, name: row.name } as ResolvedAssetDefinition),
+    enabled: row.enabled === 1,
+    createdAt: row.created_at,
+    updatedAt: row.updated_at,
+  };
+}
+
+// Insert or replace a named definition. Keyed by (kind, name, provider) so the same
+// name can carry provider-specific variants (a claude skill vs a codex skill).
+export function upsertProvisioningAsset(input: UpsertProvisioningAssetInput): ProvisioningAsset {
+  assertKind(input.kind);
+  const provider = input.provider ?? "any";
+  assertProvider(provider);
+  const name = input.definition.name || input.name;
+  if (!name) throw new ValidationError("name is required");
+  assertDefinition(input.kind, { ...input.definition, name });
+  const now = Date.now();
+  const existing = getDb()
+    .query("SELECT id, created_at FROM provisioning_assets WHERE kind = ? AND name = ? AND provider = ?")
+    .get(input.kind, name, provider) as { id: string; created_at: number } | undefined;
+  const id = existing?.id ?? assetId();
+  getDb().query(`
+    INSERT INTO provisioning_assets (id, kind, name, provider, definition, enabled, created_at, updated_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+    ON CONFLICT(kind, name, provider) DO UPDATE SET
+      definition = excluded.definition,
+      enabled = excluded.enabled,
+      updated_at = excluded.updated_at
+  `).run(
+    id,
+    input.kind,
+    name,
+    provider,
+    JSON.stringify({ ...input.definition, name }),
+    input.enabled === false ? 0 : 1,
+    existing?.created_at ?? now,
+    now,
+  );
+  return getProvisioningAsset(input.kind, name, provider)!;
+}
+
+export function getProvisioningAsset(
+  kind: ProvisioningAssetKind,
+  name: string,
+  provider: AgentProfileProvider = "any",
+): ProvisioningAsset | null {
+  const row = getDb()
+    .query("SELECT * FROM provisioning_assets WHERE kind = ? AND name = ? AND provider = ?")
+    .get(kind, name, provider) as ProvisioningAssetRow | undefined;
+  return row ? rowToAsset(row) : null;
+}
+
+export function listProvisioningAssets(opts: { kind?: ProvisioningAssetKind; includeDisabled?: boolean } = {}): ProvisioningAsset[] {
+  if (opts.kind) assertKind(opts.kind);
+  const conditions: string[] = [];
+  const params: (string | number)[] = [];
+  if (opts.kind) {
+    conditions.push("kind = ?");
+    params.push(opts.kind);
+  }
+  if (!opts.includeDisabled) conditions.push("enabled = 1");
+  const where = conditions.length ? `WHERE ${conditions.join(" AND ")}` : "";
+  const rows = getDb()
+    .query(`SELECT * FROM provisioning_assets ${where} ORDER BY kind, name, provider`)
+    .all(...params) as ProvisioningAssetRow[];
+  return rows.map(rowToAsset);
+}
+
+export function deleteProvisioningAsset(
+  kind: ProvisioningAssetKind,
+  name: string,
+  provider: AgentProfileProvider = "any",
+): boolean {
+  const result = getDb()
+    .query("DELETE FROM provisioning_assets WHERE kind = ? AND name = ? AND provider = ?")
+    .run(kind, name, provider);
+  return result.changes > 0;
+}
+
+// Resolve a registry ref for a target provider: an exact provider match wins, else
+// the provider-neutral "any" variant. Disabled definitions never resolve.
+function resolveRegistryDefinition(
+  kind: ProvisioningAssetKind,
+  ref: string,
+  provider: SpawnProvider,
+): ResolvedAssetDefinition | null {
+  const specific = getProvisioningAsset(kind, ref, provider);
+  if (specific?.enabled) return specific.definition;
+  const any = getProvisioningAsset(kind, ref, "any");
+  return any?.enabled ? any.definition : null;
+}
+
+// A ref applies to a launch iff it's enabled and its provider scope includes the
+// target ("any"/undefined → all providers).
+function refAppliesToProvider(ref: AgentProfileAssetRef, provider: SpawnProvider): boolean {
+  return ref.enabled && (!ref.provider || ref.provider === "any" || ref.provider === provider);
+}
+
+function inlineFilesFromMeta(meta: Record<string, unknown> | undefined): { path: string; content: string }[] | undefined {
+  const raw = meta?.files;
+  if (!Array.isArray(raw)) return undefined;
+  const files = raw
+    .filter(isRecord)
+    .filter((f) => typeof f.path === "string" && typeof f.content === "string")
+    .map((f) => ({ path: f.path as string, content: f.content as string }));
+  return files.length ? files : undefined;
+}
+
+// Resolve a skill/plugin asset ref into a concrete definition. relay → registry;
+// inline → built from ref.meta (files or dir); repo → a cwd-relative dir token the
+// runner resolves against the launch cwd; provider → skipped (provider built-in).
+function resolveDirAssetRef(
+  kind: "skill" | "plugin",
+  ref: AgentProfileAssetRef,
+  provider: SpawnProvider,
+): SkillAssetDefinition | PluginAssetDefinition | null {
+  if (ref.source === "relay") {
+    const def = resolveRegistryDefinition(kind, ref.ref, provider);
+    return def && def.kind === kind ? def : null;
+  }
+  if (ref.source === "inline") {
+    const files = inlineFilesFromMeta(ref.meta);
+    const dir = typeof ref.meta?.dir === "string" ? ref.meta.dir : undefined;
+    if (!files && !dir) return null;
+    return { kind, name: ref.ref, ...(files ? { files } : {}), ...(dir ? { dir } : {}) };
+  }
+  if (ref.source === "repo") {
+    return { kind, name: ref.ref, dir: ref.ref };
+  }
+  return null;
+}
+
+// A profile.mcp.servers entry is either an inline server spec or a registry
+// reference (`{ source: "relay", ref }`). Returns the concrete server spec.
+function resolveMcpEntry(name: string, value: unknown, provider: SpawnProvider): ProvisioningMcpServer | null {
+  if (!isRecord(value)) return null;
+  if (value.source === "relay" && typeof value.ref === "string") {
+    const def = resolveRegistryDefinition("mcp", value.ref, provider);
+    return def && def.kind === "mcp" ? def.server : null;
+  }
+  if (value.enabled === false) return null;
+  // Inline spec: keep the recognized server fields only.
+  const server: ProvisioningMcpServer = {};
+  if (typeof value.type === "string") server.type = value.type as ProvisioningMcpServer["type"];
+  if (typeof value.command === "string") server.command = value.command;
+  if (Array.isArray(value.args)) server.args = value.args.filter((a): a is string => typeof a === "string");
+  if (isRecord(value.env)) server.env = stringRecord(value.env);
+  if (typeof value.url === "string") server.url = value.url;
+  if (isRecord(value.headers)) server.headers = stringRecord(value.headers);
+  return server.command || server.url ? server : null;
+}
+
+function stringRecord(value: Record<string, unknown>): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const [k, v] of Object.entries(value)) {
+    if (typeof v === "string") out[k] = v;
+  }
+  return out;
+}
+
+// Resolve a profile's declared skill/plugin/MCP refs against the registry into the
+// concrete bundle the runner materializes. Relay-side (needs the DB); the result is
+// attached to the in-flight profile (profile.provisioning) before it's serialized
+// into the spawn env. Pure read — never mutates the registry.
+export function resolveProfileProvisioning(profile: AgentProfile, provider: SpawnProvider): ResolvedProvisioning {
+  const skills: SkillAssetDefinition[] = [];
+  for (const ref of profile.skills ?? []) {
+    if (!refAppliesToProvider(ref, provider)) continue;
+    const def = resolveDirAssetRef("skill", ref, provider);
+    if (def) skills.push(def as SkillAssetDefinition);
+  }
+
+  const plugins: PluginAssetDefinition[] = [];
+  for (const ref of profile.plugins ?? []) {
+    if (!refAppliesToProvider(ref, provider)) continue;
+    const def = resolveDirAssetRef("plugin", ref, provider);
+    if (def) plugins.push(def as PluginAssetDefinition);
+  }
+
+  const mcpServers: Record<string, ProvisioningMcpServer> = {};
+  for (const [name, value] of Object.entries(profile.mcp?.servers ?? {})) {
+    const server = resolveMcpEntry(name, value, provider);
+    if (server) mcpServers[name] = server;
+  }
+
+  return { skills, plugins, mcpServers };
+}
+
+// Attach the resolved bundle to a spawn-bound profile. Returns a shallow copy so the
+// cached config-store value is never mutated. undefined passes through (an unresolved
+// profile name stays undefined so callers' not-found guards still fire); the runner
+// treats an absent and an empty bundle identically.
+export function withResolvedProvisioning(profile: AgentProfile | undefined, provider: SpawnProvider): AgentProfile | undefined {
+  if (!profile) return undefined;
+  return { ...profile, provisioning: resolveProfileProvisioning(profile, provider) };
+}

package/src/db/schema.ts

@@ -878,6 +878,22 @@ export function initDb(path: string = "agent-relay.db"): Database {
     CREATE INDEX IF NOT EXISTS idx_insights_obs_project_signal ON insights_observations(project, signal, created_at DESC);
     CREATE INDEX IF NOT EXISTS idx_insights_obs_signal ON insights_observations(signal, created_at DESC);
     CREATE INDEX IF NOT EXISTS idx_insights_obs_session ON insights_observations(session_id);
+
+    -- Relay-owned provisioning registry (#554/#555/#556): named, materializable
+    -- skill/MCP/plugin definitions a vanilla profile selects by ref. (kind, name,
+    -- provider) is unique so a name can carry provider-specific variants.
+    CREATE TABLE IF NOT EXISTS provisioning_assets (
+      id TEXT PRIMARY KEY,
+      kind TEXT NOT NULL,
+      name TEXT NOT NULL,
+      provider TEXT NOT NULL DEFAULT 'any',
+      definition TEXT NOT NULL,
+      enabled INTEGER NOT NULL DEFAULT 1,
+      created_at INTEGER NOT NULL,
+      updated_at INTEGER NOT NULL,
+      UNIQUE(kind, name, provider)
+    );
+    CREATE INDEX IF NOT EXISTS idx_provisioning_assets_kind ON provisioning_assets(kind, enabled);
   `);
 
   ensureContinuationArchiveSearchSchema();

package/src/managed-policy.ts

@@ -1,4 +1,5 @@
 import { getAgentProfile } from "./config-store";
+import { withResolvedProvisioning } from "./db";
 import { runnerRuntimeTokenEnv } from "./runtime-tokens";
 import { buildSpawnCommand, resolveSpawnModelParams } from "./spawn-command";
 import type { SpawnPolicy, WorkspaceMode } from "./types";
@@ -28,7 +29,7 @@ interface ManagedSpawnContext {
 export function buildManagedSpawnParams(policy: SpawnPolicy, requestId: string, ctx: ManagedSpawnContext): Record<string, unknown> {
   const providerArgs = managedPolicyProviderArgs(policy);
   const prompt = managedPolicyLaunchPrompt(policy);
-  const agentProfile = policy.profile ? getAgentProfile(policy.profile)?.value : undefined;
+  const agentProfile = withResolvedProvisioning(policy.profile ? getAgentProfile(policy.profile)?.value : undefined, policy.provider);
   return buildSpawnCommand({
     provider: policy.provider,
     orchestratorId: policy.orchestratorId,

package/src/mcp/tools-messaging.ts

@@ -4,6 +4,7 @@ import { bytesToStream } from "../http-body";
 import { MAX_BODY_BYTES } from "../config";
 import { getManagedAgentState, getSpawnPolicy, listSpawnPolicies } from "../config-store";
 import {
+  countAgents,
   createArtifact,
   getAgent,
   getArtifact,
@@ -20,6 +21,7 @@ import {
   type AgentSearchFilter,
   type AgentSearchSort,
 } from "../db";
+import type { AgentCard } from "../types";
 import { type DeliveryReceipt } from "../agent-ref";
 import { emitRelayEvent } from "../events";
 import { McpAuthError, McpNotFoundError } from "../mcp-errors";
@@ -31,7 +33,7 @@ import { isRecord } from "agent-relay-sdk";
 import type { ArtifactKind, ArtifactSensitivity, AttachmentRef, Message, SendMessageInput } from "../types";
 import type { McpAuthContext, ToolDefinition } from "./types";
 import { callerAgentId } from "./identity";
-import { enumField, optionalAttachments, optionalBoolean, optionalFutureTimestamp, optionalPositiveInt, optionalRecord, optionalString, positiveId, recordField, stringField } from "./validation";
+import { enumField, optionalAttachments, optionalBoolean, optionalFutureTimestamp, optionalNonNegativeInt, optionalPositiveInt, optionalRecord, optionalString, positiveId, recordField, stringField } from "./validation";
 
 const VALID_ARTIFACT_KINDS = ["image", "audio", "video", "document", "archive", "other"] as const;
 const VALID_ARTIFACT_SENSITIVITIES = ["public", "normal", "sensitive", "secret"] as const;
@@ -165,7 +167,7 @@ export const MESSAGING_TOOLS: ToolDefinition[] = [
   },
   {
     name: "relay_find_agents",
-    description: "Search the fleet for agents by label, capability, provider, tag, machine, status, or kind, sorted by last-active/created/label. Defaults to running agents only. Use this to find a reachable, capable peer before messaging or pairing — instead of dumping the whole roster.",
+    description: "Search the fleet for agents by label, capability, provider, tag, machine, status, or kind, sorted by last-active/created/label. Returns a lean roster summary by default (id, label, status, machine, provider, model, lastSeen, spawnedBy, teamId) — add verbose:true for full agent cards. Defaults to running agents only. Use this to find a reachable, capable peer before messaging or pairing.",
     requiredScopes: ["agents:read", "agent:read"],
     inputSchema: {
       type: "object",
@@ -182,6 +184,8 @@ export const MESSAGING_TOOLS: ToolDefinition[] = [
         sortBy: { type: "string", enum: ["lastActive", "created", "label"] },
         order: { type: "string", enum: ["asc", "desc"] },
         limit: { type: "integer", minimum: 1, maximum: 200 },
+        offset: { type: "integer", minimum: 0, description: "Pagination offset (default 0). Use nextOffset from a prior response to page through results." },
+        verbose: { type: "boolean", description: "Return full agent cards instead of the lean roster summary. Even verbose results are paginated; use offset+limit to page." },
       },
       additionalProperties: false,
     },
@@ -358,7 +362,42 @@ function optionalStringOrArray(value: unknown, field: string): string | string[]
   throw new ValidationError(`${field} must be a string or string array`);
 }
 
+// Hard character cap for the lean list — a fat-card dump was 286K; lean entries are ~200 chars
+// each so 200 entries ≈ 40K, well inside; this guard catches edge cases (#548).
+const FIND_AGENTS_CHAR_CAP = 50_000;
+
+// Fields a coordinator needs to reason about the roster — id, status, routing, parent, team.
+// Drops providerCapabilities (multi-KB), context, meta, tags, capabilities, epoch, etc.
+type AgentRosterEntry = {
+  id: string;
+  label?: string;
+  status: string;
+  machine?: string;
+  provider?: string;
+  model?: string;
+  lastSeen: number;
+  spawnedBy?: string;
+  spawnRequestId?: string;
+  teamId?: string;
+};
+
+function toLeanEntry(agent: AgentCard): AgentRosterEntry {
+  const entry: AgentRosterEntry = { id: agent.id, status: agent.status, lastSeen: agent.lastSeen };
+  if (agent.label) entry.label = agent.label;
+  if (agent.machine) entry.machine = agent.machine;
+  const pc = agent.providerCapabilities;
+  if (pc?.model?.provider) entry.provider = pc.model.provider;
+  if (pc?.model?.id) entry.model = pc.model.id;
+  if (agent.spawnedBy) entry.spawnedBy = agent.spawnedBy;
+  const srId = agent.meta?.spawnRequestId;
+  if (typeof srId === "string") entry.spawnRequestId = srId;
+  if (agent.teamId) entry.teamId = agent.teamId;
+  return entry;
+}
+
 export function relayFindAgents(auth: McpAuthContext, args: Record<string, unknown>): Record<string, unknown> {
+  const verbose = optionalBoolean(args.verbose, "verbose") === true;
+  const offset = optionalNonNegativeInt(args.offset, "offset") ?? 0;
   const spawnedByArg = optionalString(args.spawnedBy, "spawnedBy", 240);
   const spawnedBy = spawnedByArg === "me" ? callerAgentId(auth) ?? "\0unresolved" : spawnedByArg;
   const filter: AgentSearchFilter = {
@@ -376,9 +415,39 @@ export function relayFindAgents(auth: McpAuthContext, args: Record<string, unkno
     sortBy: optionalEnum(args.sortBy, "sortBy", ["lastActive", "created", "label"] as const),
     order: optionalEnum(args.order, "order", ["asc", "desc"] as const),
     limit: optionalPositiveInt(args.limit, "limit"),
+    offset: offset > 0 ? offset : undefined,
   };
+
+  const total = countAgents(filter);
   const agents = searchAgents(filter, sort);
-  return { agents, count: agents.length };
+  const returned = agents.length;
+  const nextOffset = offset + returned < total ? offset + returned : undefined;
+
+  if (verbose) {
+    const result: Record<string, unknown> = { agents, total, count: returned };
+    if (nextOffset != null) result.nextOffset = nextOffset;
+    return result;
+  }
+
+  // Default: lean projection — drop fat blobs, stay within token budget.
+  const lean = agents.map(toLeanEntry);
+  const encoded = JSON.stringify(lean);
+  if (encoded.length <= FIND_AGENTS_CHAR_CAP) {
+    const result: Record<string, unknown> = { agents: lean, total, count: returned };
+    if (nextOffset != null) result.nextOffset = nextOffset;
+    return result;
+  }
+
+  // Hard cap: truncate lean list and emit explicit truncation hint.
+  const safe: AgentRosterEntry[] = [];
+  let size = 0;
+  for (const entry of lean) {
+    const s = JSON.stringify(entry);
+    if (size + s.length > FIND_AGENTS_CHAR_CAP) break;
+    safe.push(entry);
+    size += s.length;
+  }
+  return { agents: safe, total, count: safe.length, truncated: true, nextOffset: offset + safe.length };
 }
 
 function payloadWithAttachments(

package/src/project-instructions.ts

@@ -11,7 +11,7 @@
 // is that lever: the included-source set is a policy PARAMETER, and the `vanilla`
 // policy includes `manual`+`promoted` while excluding `ingested`.
 import { resolveProjectEntries } from "./db";
-import { PROJECT_ENTRY_SOURCES, type Project, type ProjectEntryKind, type ProjectEntrySource, type ResolvedProjectEntry } from "./types";
+import { PROJECT_ENTRY_SOURCES, type AgentProfile, type Project, type ProjectEntryKind, type ProjectEntrySource, type ResolvedProjectEntry } from "./types";
 
 /** Named source policies — THE additive-from-empty lever (#403 decision 4).
  *   `all`     — every source (manual + promoted + ingested host-CLAUDE.md content).
@@ -150,6 +150,46 @@ export function composeProjectInstructions(
   return out;
 }
 
+/**
+ * #557 — THE instruction-sources half of the launch-assembly contract (the relay-side
+ * composer; the runner-side launch-assembly.ts assembles the provisioned skills/plugins/MCP
+ * + vanilla floor). It composes a spawned agent's systemPromptAppend from declared sources,
+ * in precedence order: project knowledge preamble (#409, the project-scoped channel) →
+ * profile system prompt → profile append entries → transient caller/fork context. Composing
+ * from EMPTY and adding (never reading host CLAUDE.md) is the additive-from-empty invariant.
+ *
+ * Returns the joined block, or the caller's own systemPromptAppend untouched when no
+ * profile/project material applies — so a profile-less spawn stays byte-identical.
+ *
+ * ── #559 SEAM ──────────────────────────────────────────────────────────────────────────
+ * Scoped {profile|user} memory does not exist yet (#559 generalizes Projects' anchor to
+ * project|profile|user). When it lands, a profile/user-scoped preamble composes in RIGHT
+ * HERE, beside the project preamble — same `composeProjectInstructions`-shaped renderer over
+ * the {profile|user} scope union, slotted into `appendBlocks` before the profile system
+ * prompt. The runner reports the contributing scopes via AssembledInstructions.scopedKnowledge.
+ * Until #559 lands, the only knowledge scope is the project preamble below — a thin add, not
+ * a refactor.
+ */
+export function composeSpawnInstructions(input: {
+  callerProject?: Pick<Project, "id" | "slug" | "title">;
+  projectInstructions?: ProjectInstructionPolicy;
+  profile?: Pick<AgentProfile, "instructions">;
+  callerSystemPromptAppend?: string;
+}): string | undefined {
+  const appendBlocks: string[] = [];
+  if (input.projectInstructions && input.callerProject) {
+    const block = composeProjectInstructions(input.callerProject, {
+      ...(input.projectInstructions.policy ? { policy: input.projectInstructions.policy } : {}),
+    });
+    if (block.trim()) appendBlocks.push(block);
+  }
+  // [#559 seam] profile/user-scoped knowledge preamble composes in here.
+  if (input.profile?.instructions.system?.trim()) appendBlocks.push(input.profile.instructions.system);
+  appendBlocks.push(...(input.profile?.instructions.append.filter((entry) => entry.trim()) ?? []));
+  if (input.callerSystemPromptAppend?.trim()) appendBlocks.push(input.callerSystemPromptAppend);
+  return appendBlocks.length ? appendBlocks.join("\n\n") : input.callerSystemPromptAppend;
+}
+
 /**
  * Parse a spawn-transport's `projectInstructions` wire value into the normalized policy
  * (or undefined = OFF). Shared by the MCP and HTTP spawn paths so they cannot drift.

package/src/routes/agent-sessions.ts

@@ -1,7 +1,7 @@
 // Auto-split from routes.ts (#299). Domain: agent-sessions.
 import { RELAY_TOKEN_HEADER, isRecord } from "agent-relay-sdk";
 import { VALID_AGENT_ACTIONS, agentControlActionIcon, auditEvent, authAuditMetadata, authorizeRoute, cleanAttachmentRefs, dashboardAttribution, emitCommand, error, json, metaString, parseBody, spawnRequestId, type AgentControlAction, type Handler } from "./_shared";
-import { ValidationError, getAgent, getAgentTimeline, getOrchestrator, markReady, mergeAgentMeta, sendMessage } from "../db";
+import { ValidationError, getAgent, getAgentTimeline, getOrchestrator, markReady, mergeAgentMeta, sendMessage, withResolvedProvisioning } from "../db";
 import { buildManagedSpawnParams } from "../managed-policy";
 import { buildSpawnCommand, generateSpawnRequestId, resolveSpawnModelParams } from "../spawn-command";
 import { cleanString, optionalEnum } from "../validation";
@@ -111,7 +111,7 @@ function restartSpawnParamsForAgent(
   const effort = metaString(agent.meta, "effort") as ProviderEffort | undefined;
   const providerArgs = metaStringArray(agent.meta, "providerArgs");
   const profileName = metaString(agent.meta, "profile");
-  const agentProfile = profileName ? getAgentProfile(profileName)?.value : undefined;
+  const agentProfile = withResolvedProvisioning(profileName ? getAgentProfile(profileName)?.value : undefined, provider);
   const workspaceMode = metaString(agent.meta, "workspaceMode") ?? "inherit";
   const resolvedModel = resolveSpawnModelParams(provider, model, effort, { onError: "passthrough", skipDefaultWhenEmpty: true });
   const params = buildSpawnCommand({