agent-relay-server 0.96.0 → 0.98.0

package/src/agent-busy-health.ts

@@ -5,14 +5,13 @@ import {
   STUCK_BUSY_STARTUP_MS,
   STUCK_BUSY_TRANSPORT_STALE_MS,
 } from "./config";
-import { isRecord, stringValue } from "agent-relay-sdk";
+import { isRecord, stringValue, type LivenessSignal } from "agent-relay-sdk";
 import type { AgentCard } from "./types";
 
 type BusyHealthKind = "provider-turn" | "startup" | "reconnect" | "shutdown";
 
 interface ActiveWorkLike {
   id?: unknown;
-  kind?: unknown;
   label?: unknown;
   startedAt?: unknown;
 }
@@ -22,18 +21,19 @@ export interface AgentBusyHealth {
   kind: BusyHealthKind;
   thresholdMs: number;
   activeWorkId?: string;
-  activeWorkKind?: string;
   activeWorkLabel?: string;
   activeWorkStartedAt: number;
   activeWorkAgeMs: number;
-  lastProviderEventAt?: number;
-  lastProviderEventAgeMs?: number;
-  /** Most recent of lastProviderEventAt and any fresh lifecycle/timeline transition (e.g. `compacting`). */
+  /** Most recent forward-progress timestamp from the contract LivenessSignal (provider tokens,
+   *  a lifecycle/timeline transition, or live tool/subprocess work), floored at the work start. */
   lastProgressAt: number;
-  /** Most recent transport liveness signal (server frame / heartbeat ack); undefined when the runner reports no transport. */
-  transportLiveAt?: number;
-  /** Age of the transport liveness signal; +Infinity when transport is unknown (treated as dead). */
+  /** Most recent transport-liveness timestamp: LivenessSignal.transportLiveAt folded with the
+   *  server-stamped agent.lastSeen as the floor. Always set. */
+  transportLiveAt: number;
+  /** Age of the most recent transport-liveness signal. */
   transportStaleForMs: number;
+  /** True while the contract reports live tool/subprocess work (vetoes stuck-busy). */
+  hasLiveWork: boolean;
   staleForMs: number;
 }
 
@@ -45,34 +45,35 @@ function activeWork(agent: AgentCard): ActiveWorkLike[] {
   return Array.isArray(agent.meta?.activeWork) ? agent.meta.activeWork as ActiveWorkLike[] : [];
 }
 
-function hasLiveToolOrSubprocessWork(works: ActiveWorkLike[]): boolean {
-  return works.some((work) => {
-    const kind = stringValue(work.kind);
-    return Boolean(kind && kind !== "provider-turn");
-  });
-}
-
-// #713 — most recent transport-liveness timestamp the runner reported on meta.transport
-// (`lastServerFrameAt` / `lastHeartbeatAckAt`). A current value proves the runner→server link is
-// alive, which means the agent is NOT wedged regardless of provider-token silence. Returns undefined
-// when no transport block is present (older runners / pre-transport meta) — the caller treats that as
-// "can't prove alive" so a genuine wedge with no transport still fires.
-function transportLiveAt(agent: AgentCard): number | undefined {
-  const transport = isRecord(agent.meta?.transport) ? agent.meta.transport : undefined;
-  if (!transport) return undefined;
-  const frame = numberValue(transport.lastServerFrameAt);
-  const ack = numberValue(transport.lastHeartbeatAckAt);
-  if (frame === undefined && ack === undefined) return undefined;
-  return Math.max(frame ?? 0, ack ?? 0);
+// The work record that drives the busy AGE — the earliest-started one. Read only for the age
+// threshold + display (id/label); the busy KIND comes from lifecycle markers (below) and the
+// live-work question comes from LivenessSignal.hasLiveWork. We deliberately never enumerate
+// `activeWork[].kind` here — that interpretation now lives behind the contract (#746).
+function oldestWork(works: ActiveWorkLike[]): { work?: ActiveWorkLike; startedAt?: number } {
+  let best: ActiveWorkLike | undefined;
+  let bestAt: number | undefined;
+  for (const work of works) {
+    const at = numberValue(work.startedAt);
+    if (at === undefined) continue;
+    if (bestAt === undefined || at < bestAt) {
+      best = work;
+      bestAt = at;
+    }
+  }
+  return { work: best ?? works[0], startedAt: bestAt };
 }
 
-// #713 — timestamp of the latest lifecycle/timeline transition (e.g. Claude `compacting`/`compacted`)
-// the runner published on meta.timelineEvent. These mark active progress through a lifecycle even when
-// no provider tokens flow, so they count as progress against the no-progress threshold.
-function timelineProgressAt(agent: AgentCard): number | undefined {
-  const event = isRecord(agent.meta?.timelineEvent) ? agent.meta.timelineEvent : undefined;
-  if (!event) return undefined;
-  return numberValue(event.timestamp);
+// The ONLY runtime-liveness input the server reads: the normalized contract verdict the runner
+// (per-provider adapter) ships on the card. Replaces the six raw `meta` reads (#713/#724) the
+// stuck-busy detector used to re-derive. Returns undefined for cards from a pre-contract runner;
+// the caller then degrades gracefully to the server-stamped lastSeen + work-start floors.
+function readLiveness(agent: AgentCard): LivenessSignal | undefined {
+  const raw = agent.meta?.liveness;
+  if (!isRecord(raw)) return undefined;
+  const transportLiveAt = numberValue(raw.transportLiveAt);
+  const lastProgressAt = numberValue(raw.lastProgressAt);
+  if (transportLiveAt === undefined || lastProgressAt === undefined) return undefined;
+  return { transportLiveAt, lastProgressAt, hasLiveWork: raw.hasLiveWork === true };
 }
 
 function thresholdFor(kind: BusyHealthKind): number {
@@ -82,65 +83,65 @@ function thresholdFor(kind: BusyHealthKind): number {
   return STUCK_BUSY_PROVIDER_TURN_MS;
 }
 
-function classifyBusy(agent: AgentCard, now: number): { kind: BusyHealthKind; work?: ActiveWorkLike; startedAt: number } | null {
+// Busy KIND classification — driven by provider-agnostic lifecycle markers (lifecycleAction /
+// ready), NOT by provider runtime signals. The active-work set contributes only the start
+// timestamp (age) and display id/label.
+function classifyBusy(agent: AgentCard): { kind: BusyHealthKind; work?: ActiveWorkLike; startedAt: number } | null {
   if (agent.status !== "busy") return null;
-  const works = activeWork(agent);
-  const providerTurn = works.find((item) => item.kind === "provider-turn");
-  if (providerTurn) {
-    return { kind: "provider-turn", work: providerTurn, startedAt: numberValue(providerTurn.startedAt) ?? agent.lastSeen };
-  }
-
+  const oldest = oldestWork(activeWork(agent));
   const lifecycleAction = stringValue(agent.meta?.lifecycleAction) ?? "";
   const lifecycleActionAt = numberValue(agent.meta?.lifecycleActionAt);
   if (lifecycleAction.includes("shutdown") || lifecycleAction === "killing") {
-    return { kind: "shutdown", work: works[0], startedAt: lifecycleActionAt ?? numberValue(works[0]?.startedAt) ?? agent.lastSeen };
+    return { kind: "shutdown", work: oldest.work, startedAt: lifecycleActionAt ?? oldest.startedAt ?? agent.lastSeen };
   }
   if (lifecycleAction.includes("reconnect") || lifecycleAction === "resuming") {
-    return { kind: "reconnect", work: works[0], startedAt: lifecycleActionAt ?? numberValue(works[0]?.startedAt) ?? agent.lastSeen };
+    return { kind: "reconnect", work: oldest.work, startedAt: lifecycleActionAt ?? oldest.startedAt ?? agent.lastSeen };
   }
   if (!agent.ready) {
-    return { kind: "startup", work: works[0], startedAt: numberValue(agent.meta?.startedAt) ?? agent.createdAt };
+    return { kind: "startup", work: oldest.work, startedAt: numberValue(agent.meta?.startedAt) ?? agent.createdAt };
   }
-  return works[0] ? { kind: "provider-turn", work: works[0], startedAt: numberValue(works[0].startedAt) ?? agent.lastSeen } : null;
+  return oldest.work ? { kind: "provider-turn", work: oldest.work, startedAt: oldest.startedAt ?? agent.lastSeen } : null;
 }
 
 export function deriveAgentBusyHealth(agent: AgentCard, now: number = Date.now()): AgentBusyHealth | undefined {
-  const classified = classifyBusy(agent, now);
+  const classified = classifyBusy(agent);
   if (!classified) return undefined;
-  const works = activeWork(agent);
   const thresholdMs = thresholdFor(classified.kind);
   const activeWorkStartedAt = Math.max(0, classified.startedAt);
   const activeWorkAgeMs = Math.max(0, now - activeWorkStartedAt);
-  const lastProviderEventAt = numberValue(agent.meta?.lastProviderEventAt);
-  // Progress = provider tokens OR any lifecycle/timeline transition (e.g. native compaction). #713: a
-  // fresh `compacting` event means the worker is actively progressing even with zero provider tokens.
-  const lastProgressAt = Math.max(lastProviderEventAt ?? activeWorkStartedAt, timelineProgressAt(agent) ?? 0);
+
+  const liveness = readLiveness(agent);
+  // transportLiveAt: fold the server-stamped lastSeen as the FLOOR. The runner ships the max of
+  // its own frame/heartbeat-ack timestamps; the server can't expect the runner to know lastSeen,
+  // so a fresh heartbeat on EITHER side proves the link is alive. This is the #713/#724 veto:
+  // provider-token silence alone never trips stuck-busy while transport is demonstrably live.
+  const transportLiveAt = Math.max(liveness?.transportLiveAt ?? 0, agent.lastSeen);
+  const transportStaleForMs = Math.max(0, now - transportLiveAt);
+  // lastProgressAt floored at the work start so the no-progress age can't predate the turn.
+  const lastProgressAt = Math.max(liveness?.lastProgressAt ?? 0, activeWorkStartedAt);
   const staleForMs = Math.max(0, now - lastProgressAt);
-  // #713: transport heartbeat liveness. A current server-frame/heartbeat-ack proves the runner→server
-  // link is alive ⇒ the agent is NOT wedged, no matter how long provider tokens have been silent
-  // (long turns, extended thinking, native compaction). Unknown transport ⇒ +Infinity (can't prove
-  // alive), so a genuine wedge whose runner has stopped reporting still trips.
-  const liveAt = transportLiveAt(agent);
-  const transportStaleForMs = liveAt === undefined ? Number.POSITIVE_INFINITY : Math.max(0, now - liveAt);
+  const hasLiveWork = liveness?.hasLiveWork ?? false;
+
+  // Threshold policy only — no provider knowledge, no raw-signal interpretation.
   const stuck =
-    !hasLiveToolOrSubprocessWork(works) &&
+    !hasLiveWork &&
     activeWorkAgeMs >= thresholdMs &&
     staleForMs >= thresholdMs &&
     transportStaleForMs >= STUCK_BUSY_TRANSPORT_STALE_MS;
+
   const work = classified.work;
   return {
     status: stuck ? "stuck-busy" : "ok",
     kind: classified.kind,
     thresholdMs,
     ...(stringValue(work?.id) ? { activeWorkId: stringValue(work?.id) } : {}),
-    ...(stringValue(work?.kind) ? { activeWorkKind: stringValue(work?.kind) } : {}),
     ...(stringValue(work?.label) ? { activeWorkLabel: stringValue(work?.label) } : {}),
     activeWorkStartedAt,
     activeWorkAgeMs,
-    ...(lastProviderEventAt !== undefined ? { lastProviderEventAt, lastProviderEventAgeMs: Math.max(0, now - lastProviderEventAt) } : {}),
     lastProgressAt,
-    ...(liveAt !== undefined ? { transportLiveAt: liveAt } : {}),
+    transportLiveAt,
     transportStaleForMs,
+    hasLiveWork,
     staleForMs,
   };
 }

package/src/codex-wham-quota.ts

@@ -1,15 +1,16 @@
 import { readFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join } from "node:path";
-import { resolveStableCodexQuotaIdentity } from "agent-relay-sdk/provider-quota";
-import { quotaStateFromProbeMetrics } from "agent-relay-sdk/context-probe";
+import { codexWhamResetCredits, codexWhamUsageQuotaState, resolveStableCodexQuotaIdentity } from "agent-relay-sdk/provider-quota";
 import { errMessage, isRecord, stringValue } from "agent-relay-sdk";
 import { codexWhamQuotaEnabled } from "./config";
 import { upsertProviderQuota } from "./db";
 import { emitRelayEvent } from "./events";
 import { getProviderQuotaConfig } from "./provider-quota-config-store";
-import type { CodexResetCredits, ProviderQuotaError, QuotaState } from "./types";
-import type { ContextProbeMetrics } from "agent-relay-sdk";
+import type { ProviderQuotaError } from "./types";
+
+// Re-export for callers that import the parsing functions from this module (e.g. tests).
+export { codexWhamUsageQuotaState, codexWhamResetCredits } from "agent-relay-sdk/provider-quota";
 
 const WHAM_API_BASE = "https://chatgpt.com/backend-api";
 const WHAM_USAGE_PATH = "/wham/usage";
@@ -75,43 +76,6 @@ export async function collectCodexWhamQuota(options: {
   }
 }
 
-export function codexWhamUsageQuotaState(payload: unknown, now = Date.now()): QuotaState | undefined {
-  if (!isRecord(payload) || !isRecord(payload.rate_limit)) return undefined;
-  const windows = [
-    codexWhamWindow("primary", payload.rate_limit.primary_window, now),
-    codexWhamWindow("secondary", payload.rate_limit.secondary_window, now),
-  ].filter((window): window is NonNullable<ContextProbeMetrics["quotaWindows"]>[number] => Boolean(window));
-  if (windows.length !== 2) return undefined;
-  const quota = quotaStateFromProbeMetrics({
-    agentId: "codex-wham-quota",
-    contextPercent: 0,
-    quotaWindows: windows,
-    source: "api",
-    confidence: "reported",
-    timestamp: now,
-  });
-  // quotaStateFromProbeMetrics always maps source to "probe"; override to "ingest" so the
-  // per-window source precedence in mergeQuotaWindows knows WHAM is authoritative over probe.
-  return quota ? { ...quota, source: "ingest" as const } : undefined;
-}
-
-export function codexWhamResetCredits(usagePayload: unknown, creditEventsPayload: unknown, now = Date.now()): CodexResetCredits | undefined {
-  if (!isRecord(usagePayload) || !isRecord(usagePayload.credits)) return undefined;
-  const balance = numberValue(usagePayload.credits.balance);
-  if (balance === undefined) return undefined;
-  const events = isRecord(creditEventsPayload) && Array.isArray(creditEventsPayload.data)
-    ? creditEventsPayload.data.length
-    : undefined;
-  return {
-    balance,
-    ...(typeof usagePayload.credits.has_credits === "boolean" ? { hasCredits: usagePayload.credits.has_credits } : {}),
-    ...(typeof usagePayload.credits.unlimited === "boolean" ? { unlimited: usagePayload.credits.unlimited } : {}),
-    ...(typeof usagePayload.credits.overage_limit_reached === "boolean" ? { overageLimitReached: usagePayload.credits.overage_limit_reached } : {}),
-    ...(events !== undefined ? { creditUsageEvents: events } : {}),
-    updatedAt: now,
-  };
-}
-
 function defaultCodexAuthPath(): string {
   return join(process.env.CODEX_HOME ?? join(homedir(), ".codex"), "auth.json");
 }
@@ -149,41 +113,6 @@ async function fetchWhamJson(path: string, auth: CodexWhamAuth, fetchImpl: typeo
   return response.json();
 }
 
-function codexWhamWindow(name: "primary" | "secondary", value: unknown, now: number): NonNullable<ContextProbeMetrics["quotaWindows"]>[number] | undefined {
-  if (!isRecord(value)) return undefined;
-  const used = numberValue(value.used_percent);
-  if (used === undefined) return undefined;
-  const resetsAt = resetAtMs(value.reset_at) ?? resetAfterSecondsToMs(value.reset_after_seconds, now);
-  return {
-    name,
-    utilization: used > 1 ? used / 100 : used,
-    ...(resetsAt !== undefined ? { resetsAt } : {}),
-    unit: "%",
-  };
-}
-
-function resetAtMs(value: unknown): number | undefined {
-  const number = numberValue(value);
-  if (number !== undefined) return number < 10_000_000_000 ? number * 1000 : number;
-  if (typeof value !== "string" || !value.trim()) return undefined;
-  const parsed = Date.parse(value);
-  return Number.isFinite(parsed) ? parsed : undefined;
-}
-
-function resetAfterSecondsToMs(value: unknown, now: number): number | undefined {
-  const seconds = numberValue(value);
-  return seconds === undefined ? undefined : now + Math.max(0, seconds) * 1000;
-}
-
-function numberValue(value: unknown): number | undefined {
-  if (typeof value === "number" && Number.isFinite(value)) return value;
-  if (typeof value === "string" && value.trim()) {
-    const parsed = Number(value);
-    return Number.isFinite(parsed) ? parsed : undefined;
-  }
-  return undefined;
-}
-
 class CodexWhamHttpError extends Error {
   constructor(readonly status: number) {
     super(`Codex WHAM quota endpoint returned HTTP ${status}`);

package/src/compaction-watch.ts

@@ -39,9 +39,9 @@ function commandKind(type: string): WatchKind | undefined {
   return undefined;
 }
 
-function agentProvider(agent: AgentCard | null): string | undefined {
-  const value = agent?.meta?.provider;
-  return typeof value === "string" && value.trim() ? value : undefined;
+function agentHasTmuxSession(agent: AgentCard | null): boolean {
+  const session = agent?.meta?.tmuxSession;
+  return typeof session === "string" && session.trim().length > 0;
 }
 
 export class CompactionWatch {
@@ -70,13 +70,14 @@ export class CompactionWatch {
   }
 
   // Arm a watch when a context command's keystrokes are confirmed delivered.
-  // Only Claude agents go through the blind tmux-inject path that this guards;
-  // other providers compact via APIs with their own reliable status.
+  // Only agents with a tmux session go through the blind keystroke-inject path;
+  // API-based providers (Codex app-server) compact reliably without this guard.
+  // The adapter exposes the tmux-inject path implicitly via meta.tmuxSession (#743).
   noteCommandSucceeded(type: string, commandId: string, target: string): void {
     const kind = commandKind(type);
     if (!kind) return;
     const agent = getAgent(target);
-    if (agentProvider(agent) !== "claude") return;
+    if (!agentHasTmuxSession(agent)) return;
     const armedAt = this.now();
     this.pending.set(target, { agentId: target, commandId, kind, armedAt, deadline: armedAt + this.stallMs });
   }

package/src/db/provider-quota-burn.ts

@@ -4,24 +4,12 @@ const QUOTA_BURN_MIN_SAMPLE_SPAN_MS = 10 * 60_000;
 
 type QuotaWindow = QuotaState["windows"][number];
 
-function normalizeProvider(value: string): string {
-  return value.trim().toLowerCase();
-}
-
-function quotaWindowRole(provider: string, windowName: string): ProviderQuotaBurnRole | undefined {
-  const normalizedProvider = normalizeProvider(provider);
-  if (normalizedProvider === "codex") {
-    if (windowName === "primary") return "5h";
-    if (windowName === "secondary") return "7d";
-    return undefined;
-  }
-  if (normalizedProvider === "claude") {
-    if (windowName === "five_hour") return "5h";
-    if (windowName === "seven_day" || windowName === "seven_day_sonnet" || windowName === "seven_day_opus") return "7d";
-    return undefined;
-  }
+// Provider-agnostic: window role is expressed by name only. Each adapter uses the
+// conventional names (five_hour/primary → 5h, seven_day*/secondary → 7d); the server
+// never branches on provider identity to resolve a role (#742 / #725 §4.3).
+function quotaWindowRole(windowName: string): ProviderQuotaBurnRole | undefined {
   if (windowName === "five_hour" || windowName === "primary") return "5h";
-  if (windowName === "seven_day" || windowName === "secondary") return "7d";
+  if (windowName === "seven_day" || windowName === "seven_day_sonnet" || windowName === "seven_day_opus" || windowName === "secondary") return "7d";
   return undefined;
 }
 
@@ -58,7 +46,7 @@ function deriveProviderQuotaBurnWindow(input: {
   now: number;
   resetBoundaryToleranceMs: number;
 }): ProviderQuotaBurnWindow | undefined {
-  const role = quotaWindowRole(input.provider, input.currentWindow.name);
+  const role = quotaWindowRole(input.currentWindow.name);
   if (!role) return undefined;
   const low = lowConfidenceBurnWindow(role, input.currentWindow);
   const resetAt = finiteResetBoundary(input.currentWindow);

package/src/db/provider-quotas.ts

@@ -370,12 +370,11 @@ function mergeQuotaWindows(existing: StoredQuotaState | undefined, incoming: Quo
     if (!incomingWindow) {
       mergedTimes.set(key, existingUpdatedAt); mergedSources.set(key, existingSource); return window;
     }
-    // Per-window source precedence is symmetric in BOTH directions (#712, #716):
-    // - A higher-priority existing value is kept even against a newer lower-priority reading.
-    // - A higher-priority incoming value (e.g. authoritative WHAM `ingest`) overrides the stored
-    //   value outright, bypassing the timestamp + regression guards below. Those guards exist to
-    //   reject a noisy lower-or-equal source's improbable swing (a wedged probe self-report) — they
-    //   must NOT block authoritative data correcting a stale probe that pinned the window high.
+    // Per-window source precedence: #712/#716 are handled by the symmetric three-way split below.
+    // Higher existing → keep (no regression check needed; lower-priority input simply loses).
+    // Higher incoming → accept (no regression check needed; higher-priority source is authoritative).
+    // Same priority  → apply the regression guard (rejects improbable utilization drops from noisy
+    //                  same-quality sources, e.g. a wedged probe self-report; #725 §4.3).
     const existingPriority = quotaSourcePriority(existingSource);
     const incomingPriority = quotaSourcePriority(incoming.source);
     if (existingPriority > incomingPriority) {

package/src/lifecycle-manager.ts

@@ -622,8 +622,10 @@ export function __resetLifecycleManager(): void {
   singleton = null;
 }
 
-function managedModelUnavailableMessage(policy: SpawnPolicy, error: string, exited?: ManagedSessionExitDiagnostics): string | null {
-  if (policy.provider !== "claude" && exited?.provider !== "claude") return null;
+function managedModelUnavailableMessage(_policy: SpawnPolicy, error: string, exited?: ManagedSessionExitDiagnostics): string | null {
+  // extractClaudeModelUnavailableMessage returns null for text that doesn't match
+  // the Claude-specific error pattern, so this is safe to call unconditionally —
+  // no provider=== branch needed here; the parser is the gate (#743).
   return extractClaudeModelUnavailableMessage([
     error,
     exited?.lastError,

package/src/maintenance/jobs.ts

@@ -83,7 +83,7 @@ function isManagedBusyWatchCandidate(agent: ReturnType<typeof listAgents>[number
 
 function stuckBusyBody(agentId: string, health: NonNullable<ReturnType<typeof deriveAgentBusyHealth>>): string {
   const staleMinutes = Math.max(1, Math.floor(health.staleForMs / 60_000));
-  const work = health.activeWorkLabel || health.activeWorkKind || health.activeWorkId || health.kind;
+  const work = health.activeWorkLabel || health.activeWorkId || health.kind;
   return `Agent \`${agentId}\` appears stuck busy in ${work} for ${staleMinutes} min with no provider progress. Use interrupt first if available; restart or shutdown if the turn is wedged.`;
 }
 

package/src/mcp/tools-spawn.ts

@@ -1,4 +1,4 @@
-import { spawnAgent, type SpawnAgentInput } from "../services/spawn-agent";
+import { spawnAgent, summarizeSpawnCommandForCaller, type SpawnAgentInput } from "../services/spawn-agent";
 import { authContextFromMcp } from "../services/auth-context";
 import { ShutdownAuthError, ShutdownTargetError, shutdownAgent } from "../services/shutdown-agent";
 import { buildSpawnTargets } from "../spawn-targets";
@@ -162,7 +162,18 @@ export async function relaySpawnAgent(auth: McpAuthContext, args: Record<string,
     resumeWorkspace: parseResumeWorkspace(args.resumeWorkspace),
   };
   const result = await spawnAgent(input, authContextFromMcp(auth));
-  return { ...result };
+  // #734 — return the lean shape callers need (spawnRequestId + agentId for idempotency/shutdown)
+  // plus a sanitized command summary. The full resolved provisioning already went to the
+  // orchestrator on the dispatched command; echoing it here blows the MCP result token cap.
+  return {
+    ok: result.ok,
+    spawnRequestId: result.spawnRequestId,
+    orchestratorId: result.orchestratorId,
+    provider: result.provider,
+    agentId: result.agentId,
+    registered: result.registered,
+    command: summarizeSpawnCommandForCaller(result.command),
+  };
 }
 
 export function relaySpawnTargets(auth: McpAuthContext): Record<string, unknown> {

package/src/mcp-team-template-tools.ts

@@ -2,6 +2,7 @@ import { APPROVAL_MODES, VALID_AGENT_LIFECYCLES, VALID_WORKSPACE_MODES } from "a
 import { McpAuthError } from "./mcp-errors";
 import { authContextFromMcp } from "./services/auth-context";
 import { deleteTeamTemplate, getTeamTemplate, instantiateTeamTemplate, listTeamTemplates, saveTeamTemplate } from "./services/team-templates";
+import { summarizeSpawnCommandForCaller } from "./services/spawn-agent";
 import { ValidationError } from "./db";
 
 const COMPOSITION_ENTRY_SCHEMA = {
@@ -123,7 +124,13 @@ export async function relayTeamTemplateTool(auth: McpAuthLike, name: string, arg
   }
   if (name === "relay_team_spawn_from_template") {
     requireScope(auth, "teams:write");
-    return await instantiateTeamTemplate({ ...args, slug: slugArg(args) }, authContextFromMcp(auth)) as unknown as Record<string, unknown>;
+    const instantiated = await instantiateTeamTemplate({ ...args, slug: slugArg(args) }, authContextFromMcp(auth));
+    // #734 — each spawned result echoes its full resolved agentProfile; strip the heavy inlined
+    // provisioning file contents (multiplied by N spawned agents here) before returning to the caller.
+    return {
+      ...instantiated,
+      spawned: instantiated.spawned.map((s) => ({ ...s, command: summarizeSpawnCommandForCaller(s.command) })),
+    } as unknown as Record<string, unknown>;
   }
   throw new ValidationError(`unknown tool: ${name}`);
 }

package/src/notification-types.ts

@@ -25,7 +25,8 @@ export type NotificationType =
   | "workspace.stranded_escalation"
   | "workspace.auto_abandoned"
   | "workspace.review_request"
-  | "workspace.review_changes_requested";
+  | "workspace.review_changes_requested"
+  | "routing.policy.changed";
 
 /**
  * The entities a notification is ABOUT: routing inputs (#442) and explainability subjects (#446).
@@ -94,6 +95,7 @@ export const DEFAULT_TTL_MS: Record<NotificationType, number | null> = {
   "workspace.auto_abandoned": null,
   "workspace.review_request": null,
   "workspace.review_changes_requested": null,
+  "routing.policy.changed": 15 * MINUTES,
 };
 
 export const NOTIFICATION_TYPES = Object.keys(DEFAULT_TTL_MS) as NotificationType[];

package/src/routes/agents-spawn.ts

@@ -5,7 +5,7 @@ import { VALID_AGENT_STATUSES, error, json, parseBody, type Handler } from "./_s
 import { ValidationError, listAgents } from "../db";
 import { cleanMeta, cleanNullableString, cleanString, cleanStringArray, optionalEnum } from "../validation";
 import { registerAgent } from "../services/register-agent";
-import { spawnAgent, type SpawnAgentInput } from "../services/spawn-agent";
+import { spawnAgent, summarizeSpawnCommandForCaller, type SpawnAgentInput } from "../services/spawn-agent";
 import { parseProjectInstructions } from "../project-instructions";
 import { parseProjectMcp } from "../project-mcp";
 import { parseProjectSettings } from "../project-settings";
@@ -153,7 +153,9 @@ export const postAgentSpawn: Handler = async (req) => {
       waitForRegistrationMs: 0,
     };
     const result = await spawnAgent(input, authContextFromRequest(req));
-    return json({ ok: true, orchestratorId: result.orchestratorId, provider: result.provider, command: result.command }, 202);
+    // #734 — the dispatched command carries the full resolved agentProfile to the orchestrator;
+    // strip the heavy inlined provisioning file contents from the echoed-back summary.
+    return json({ ok: true, orchestratorId: result.orchestratorId, provider: result.provider, command: summarizeSpawnCommandForCaller(result.command) }, 202);
   } catch (e) {
     if (e instanceof McpAuthError) return error(e.message, 403);
     if (e instanceof McpNotFoundError) return error(e.message, 404);

package/src/routes/index.ts

@@ -8,6 +8,7 @@ import { deleteAutomationById, getAutomationById, getAutomationRuns, getAutomati
 import { deleteCommandById, deleteProviderModelRoute, getProviderConfigRoute, getProviderConfigsRoute, getProvidersRoute, patchProviderModelRoute, postProviderConfigTestRoute, putProviderConfigRoute, putProviderModelRoute } from "./provider-config";
 import { getProviderQuotasRoute, postProviderQuotaLeaseAcquireRoute, postProviderQuotaLeaseReleaseRoute, postProviderQuotaPublisherLeaseAcquireRoute, postProviderQuotaPublisherLeaseReleaseRoute, postProviderQuotaRoute } from "./provider-quotas";
 import { getProviderQuotaConfigRoute, getProviderQuotaConfigsRoute, putProviderQuotaConfigRoute } from "./provider-quota-config";
+import { getRoutingPolicyRoute, putRoutingPolicyRoute } from "./routing-policy";
 import { deleteProvisioningCapabilityRoute, getProvisioningCapabilitiesRoute, getProvisioningCapabilityRoute, patchProvisioningCapabilityRoute, patchProvisioningVariantRoute, postProvisioningCapabilityRoute, postProvisioningVariantImportRoute, postProvisioningVariantMcpRoute, postProvisioningVariantUpdateRoute, postProvisioningVariantValidateRoute } from "./provisioning-registry";
 import { getTeamsConfigRoute, putTeamsConfigRoute } from "./teams-config";
 import { deleteConfigKey, getConfigKey, getConfigKeyHistory, getConfigNamespace, putConfigKey } from "./config";
@@ -281,6 +282,8 @@ const routes: Route[] = [
   route("GET", "/api/providers/quota-config", getProviderQuotaConfigsRoute),
   route("GET", "/api/providers/:provider/quota-config", getProviderQuotaConfigRoute),
   route("PUT", "/api/providers/:provider/quota-config", putProviderQuotaConfigRoute),
+  route("GET", "/api/routing-policy", getRoutingPolicyRoute),
+  route("PUT", "/api/routing-policy", putRoutingPolicyRoute),
   route("PUT", "/api/providers/:provider/models/:alias", putProviderModelRoute),
   route("PATCH", "/api/providers/:provider/models/:alias", patchProviderModelRoute),
   route("DELETE", "/api/providers/:provider/models/:alias", deleteProviderModelRoute),

package/src/routes/routing-policy.ts

@@ -0,0 +1,25 @@
+// Routing-policy routes (#728). GET/PUT for the relay-owned routing-policy document.
+// GET: agent:read (coordinators read the policy to apply rules).
+// PUT: settings:write:routing (admin writes).
+import { ValidationError } from "../db";
+import { error, json, parseBody, type Handler } from "./_shared";
+import { getRoutingPolicy, setRoutingPolicy } from "../routing-policy-store";
+import { isRecord } from "agent-relay-sdk";
+import { cleanString } from "../validation";
+
+export const getRoutingPolicyRoute: Handler = () => {
+  return json(getRoutingPolicy());
+};
+
+export const putRoutingPolicyRoute: Handler = async (req) => {
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  try {
+    const updatedBy = isRecord(parsed.body) ? cleanString(parsed.body.updatedBy, "updatedBy", { max: 200 }) : undefined;
+    const policy = setRoutingPolicy(parsed.body, { updatedBy });
+    return json(policy);
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    throw e;
+  }
+};