agent-relay-server 0.89.1 → 0.90.0

package/docs/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "Agent Relay API",
-    "version": "0.89.1",
+    "version": "0.90.0",
     "description": "Real-time message bus for inter-agent communication. Agent-first: this spec is designed for machine consumption — agents can self-discover the full API surface via GET /api/spec.",
     "license": {
       "name": "MIT",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-relay-server",
-  "version": "0.89.1",
+  "version": "0.90.0",
   "description": "Lightweight HTTP message relay for inter-agent communication across machines",
   "module": "src/index.ts",
   "type": "module",
@@ -33,7 +33,7 @@
     "CONTRIBUTING.md"
   ],
   "dependencies": {
-    "agent-relay-sdk": "0.2.68",
+    "agent-relay-sdk": "0.2.69",
     "ajv": "^8.20.0"
   },
   "scripts": {

package/src/config-store.ts

@@ -5,6 +5,7 @@ import { DEFAULT_QUOTA_THRESHOLD_CONFIG, validateQuotaThresholdConfig } from "./
 import { DEFAULT_SELF_RESUME_CONFIG, validateSelfResumeConfig } from "./self-resume-config";
 import { TEAM_TEMPLATE_NAMESPACE, validateTeamTemplate } from "./team-template-config";
 import { PROJECT_INSTRUCTION_POLICY_NAMES } from "./project-instructions";
+import { PROJECT_MCP_POLICY_NAMES } from "./project-mcp";
 import { resolveProviderSelection, type ProviderEffort } from "agent-relay-sdk/provider-catalog";
 import { errMessage, isRecord, SPAWN_PROVIDERS, VALID_WORKSPACE_MODES } from "agent-relay-sdk"; import { effectiveProviderCatalogList } from "./provider-catalog-store";
 import type {
@@ -225,6 +226,17 @@ function cleanAgentProfileProjectInstructions(value: unknown): AgentProfile["pro
   return { policy: cleanEnum(policy, "projectInstructions.policy", PROJECT_INSTRUCTION_POLICY_NAMES) as NonNullable<AgentProfile["projectInstructions"]>["policy"] };
 }
 
+// #667 — project `.mcp.json` projection profile default. Mirrors projectInstructions:
+// boolean | { policy } → normalized { policy? } | undefined (OFF).
+function cleanAgentProfileProjectMcp(value: unknown): AgentProfile["projectMcp"] {
+  if (value === undefined || value === null || value === false) return undefined;
+  if (value === true) return {};
+  if (!isRecord(value)) throw new ValidationError("projectMcp must be a boolean or { policy } object");
+  const policy = value.policy;
+  if (policy === undefined || policy === null) return {};
+  return { policy: cleanEnum(policy, "projectMcp.policy", PROJECT_MCP_POLICY_NAMES) as NonNullable<AgentProfile["projectMcp"]>["policy"] };
+}
+
 function agentProfileDefaults(input: Pick<AgentProfile, "name" | "base"> & Partial<AgentProfile>): AgentProfile {
   const isolated = input.base !== "host";
   // "vanilla" (#552) additionally suppresses the REPO instruction cascade
@@ -245,6 +257,7 @@ function agentProfileDefaults(input: Pick<AgentProfile, "name" | "base"> & Parti
       globalInstructions: input.instructions?.globalInstructions ?? (isolated ? "ignore" : "allow"),
     },
     ...(input.projectInstructions ? { projectInstructions: input.projectInstructions } : {}),
+    ...(input.projectMcp ? { projectMcp: input.projectMcp } : {}),
     relay: {
       context: input.relay?.context ?? !isolated,
       skills: input.relay?.skills ?? !isolated,
@@ -319,6 +332,7 @@ function validateAgentProfile(key: string, value: unknown): AgentProfile {
         : cleanEnum(instructions.globalInstructions, "instructions.globalInstructions", VALID_PROFILE_INSTRUCTION_POLICIES),
     },
     projectInstructions: cleanAgentProfileProjectInstructions(value.projectInstructions),
+    projectMcp: cleanAgentProfileProjectMcp(value.projectMcp),
     relay: {
       context: relay.context === undefined ? defaults.relay.context : cleanBoolean(relay.context, "relay.context"),
       skills: relay.skills === undefined ? defaults.relay.skills : cleanBoolean(relay.skills, "relay.skills"),

package/src/db/provider-quotas.ts

@@ -5,6 +5,9 @@ import { parseStringArray } from "./shared.ts";
 import type { AgentCard, ProviderQuotaError, ProviderQuotaMatrix, ProviderQuotaRecord, ProviderQuotaSnapshot, ProviderQuotaUpdateInput, QuotaState } from "../types";
 
 const PROVIDER_QUOTA_STALE_AFTER_MS = 10 * 60_000;
+const QUOTA_UTILIZATION_EPSILON = 1e-9;
+const QUOTA_RESET_BOUNDARY_ADVANCE_MS = 5_000;
+const QUOTA_RESET_UTILIZATION_MAX = 0.01;
 
 export interface ProviderQuotaAdvisoryInput {
   provider: string;
@@ -193,6 +196,30 @@ function quotaWindowKey(window: QuotaState["windows"][number]): string {
   return `${window.name}:${window.unit}`;
 }
 
+function quotaResetBoundaryAdvanced(existing: QuotaState["windows"][number], incoming: QuotaState["windows"][number]): boolean {
+  return quotaResetBoundaryMoved(existing, incoming)
+    && incoming.resetsAt! - existing.resetsAt! > QUOTA_RESET_BOUNDARY_ADVANCE_MS;
+}
+
+function quotaResetBoundaryMoved(existing: QuotaState["windows"][number], incoming: QuotaState["windows"][number]): boolean {
+  return typeof existing.resetsAt === "number"
+    && Number.isFinite(existing.resetsAt)
+    && typeof incoming.resetsAt === "number"
+    && Number.isFinite(incoming.resetsAt)
+    && incoming.resetsAt > existing.resetsAt;
+}
+
+function quotaWindowLooksReset(existing: QuotaState["windows"][number], incoming: QuotaState["windows"][number]): boolean {
+  return incoming.utilization <= QUOTA_RESET_UTILIZATION_MAX
+    && quotaResetBoundaryMoved(existing, incoming);
+}
+
+function quotaWindowUtilizationRegressed(existing: QuotaState["windows"][number], incoming: QuotaState["windows"][number]): boolean {
+  return incoming.utilization + QUOTA_UTILIZATION_EPSILON < existing.utilization
+    && !quotaResetBoundaryAdvanced(existing, incoming)
+    && !quotaWindowLooksReset(existing, incoming);
+}
+
 function publicQuotaState(quota: StoredQuotaState): QuotaState {
   return {
     windows: quota.windows.map((window) => ({ ...window })),
@@ -283,6 +310,10 @@ function mergeQuotaWindows(existing: StoredQuotaState | undefined, incoming: Quo
       mergedTimes.set(key, existingUpdatedAt);
       return window;
     }
+    if (quotaWindowUtilizationRegressed(window, incomingWindow)) {
+      mergedTimes.set(key, existingUpdatedAt);
+      return window;
+    }
     acceptedIncomingWindow = true;
     updatedAt = Math.max(updatedAt, incoming.updatedAt);
     source = incoming.source;
@@ -427,7 +458,7 @@ export function upsertProviderQuota(input: ProviderQuotaUpdateInput, now = Date.
       provider,
       accountKey,
       previousQuota: existingQuota ? publicQuotaState(existingQuota) : undefined,
-      quota: input.quota,
+      quota: publicQuotaState(mergedQuota.quota),
       sourceAgentIds,
       previousAdvisoryState: existing?.quota_advisory_state,
       now,

package/src/mcp/tools-spawn.ts

@@ -4,6 +4,7 @@ import { ShutdownAuthError, ShutdownTargetError, shutdownAgent } from "../servic
 import { buildSpawnTargets } from "../spawn-targets";
 import { McpAuthError, McpNotFoundError } from "../mcp-errors";
 import { parseProjectInstructions, PROJECT_INSTRUCTION_POLICY_NAMES } from "../project-instructions";
+import { parseProjectMcp, PROJECT_MCP_POLICY_NAMES } from "../project-mcp";
 import { countLiveSpawnedAgents, listAgents, listWorkspaces, ValidationError } from "../db";
 import { listCommands } from "../commands-db";
 import { DEFAULT_SPAWN_PROFILE_NAME } from "../config-store";
@@ -34,6 +35,7 @@ export const SPAWN_TOOLS: ToolDefinition[] = [
         expectReply: { type: "boolean", description: "Legacy compatibility flag. Spawned workers now report up automatically: each turn-final response is routed to the spawner by lineage, without a reply obligation or idle nag." },
         systemPromptAppend: { type: "string" },
         projectInstructions: { type: "object", description: "#409 — project instruction projection (default OFF). When set, relay composes a knowledge preamble from the spawn cwd's resolved project (own + inherited entries) and prepends it to systemPromptAppend, instead of relying on host CLAUDE.md. `policy: \"all\"` includes ingested host content; `\"vanilla\"` excludes it (manual+promoted only). Omit to keep current behavior.", properties: { policy: { type: "string", enum: PROJECT_INSTRUCTION_POLICY_NAMES } }, additionalProperties: false },
+        projectMcp: { type: "object", description: "#667 — project `.mcp.json` MCP projection (default OFF). When set, the worker gets the MCP servers committed in the spawn cwd's `.mcp.json` (e.g. an app's playtest/manuscript servers), injected by relay through the controlled `--mcp-config` path that survives `--strict-mcp-config` — sourced from the project, not ambient host MCP, and without triggering Claude's project-trust modal. `policy: \"all\"` (the default) injects every declared server. Omit to keep current host-only behavior.", properties: { policy: { type: "string", enum: PROJECT_MCP_POLICY_NAMES } }, additionalProperties: false },
         profile: { type: "string", description: `Agent profile name to apply (env, instructions, permissions, MCP/skills, spawn quota). Omit to use \`${DEFAULT_SPAWN_PROFILE_NAME}\`.` },
         tags: { type: "array", items: { type: "string" } },
         capabilities: { type: "array", items: { type: "string" } },
@@ -108,6 +110,7 @@ export async function relaySpawnAgent(auth: McpAuthContext, args: Record<string,
     expectReply: typeof args.expectReply === "boolean" ? args.expectReply : undefined,
     systemPromptAppend: optionalString(args.systemPromptAppend, "systemPromptAppend", 64_000),
     projectInstructions: parseProjectInstructions(args.projectInstructions, (m) => new ValidationError(m)),
+    projectMcp: parseProjectMcp(args.projectMcp, (m) => new ValidationError(m)),
     tags: optionalStringArray(args.tags, "tags"),
     capabilities: optionalStringArray(args.capabilities, "capabilities"),
     providerArgs: optionalStringArray(args.providerArgs, "providerArgs"),

package/src/project-mcp.ts

@@ -0,0 +1,52 @@
+// Project `.mcp.json` MCP projection (#667) — the relay-owned, OPT-IN path that hands a
+// spawned worker its spawn-cwd's COMMITTED `.mcp.json` servers, sourced from the PROJECT
+// (in-repo, trusted) rather than ambient host MCP. Sibling seam to project-instructions
+// (#409): same opt-in + projection shape, default OFF.
+//
+// PROVENANCE, NOT TYPE: "vanilla/zero-host-bleed" means relay OWNS provisioning and sources
+// it from the project, never the host. A repo's `.mcp.json` is part of the code the agent
+// works in; it should travel with the repo like it does for a human who clones it.
+//
+// DIVISION OF LABOR: relay only carries the OPT-IN DECISION (this module + the spawn
+// param/profile field). The actual file read + `--mcp-config` injection happens RUNNER-side
+// (launch-assembly.ts → resolveProjectMcpServers), which is the filesystem authority for the
+// spawn cwd (relay may run on a different host than the orchestrator). It composes with #662
+// `--strict-mcp-config` — the controlled inject path strict PRESERVES — and deliberately does
+// NOT enable Claude's ambient project-`.mcp.json` discovery, whose trust modal wedges headless
+// agents (the very reason #662 added strict to all managed launches).
+
+export const PROJECT_MCP_POLICY_NAMES = ["all"] as const;
+export type ProjectMcpPolicyName = (typeof PROJECT_MCP_POLICY_NAMES)[number];
+
+/** Per-spawn projection request. Presence (a non-undefined value) means "inject project
+ * MCP"; absence means OFF. `policy` selects the server set (`all` = every declared server;
+ * the sole value today). */
+export interface ProjectMcpPolicy {
+  policy?: ProjectMcpPolicyName;
+}
+
+/**
+ * Parse a spawn-transport's `projectMcp` wire value into the normalized policy (or
+ * undefined = OFF). Shared by the MCP and HTTP spawn paths so they cannot drift. Mirrors
+ * parseProjectInstructions exactly:
+ *   - undefined / null / false → undefined (OFF)
+ *   - true                     → {} (ON, default policy)
+ *   - { policy }               → validated policy
+ * Throws `onInvalid(message)` for a malformed shape or unknown policy name.
+ */
+export function parseProjectMcp(
+  value: unknown,
+  onInvalid: (message: string) => Error,
+): ProjectMcpPolicy | undefined {
+  if (value === undefined || value === null || value === false) return undefined;
+  if (value === true) return {};
+  if (typeof value !== "object") {
+    throw onInvalid("projectMcp must be a boolean or { policy } object");
+  }
+  const policy = (value as Record<string, unknown>).policy;
+  if (policy === undefined || policy === null) return {};
+  if (typeof policy !== "string" || !PROJECT_MCP_POLICY_NAMES.includes(policy as ProjectMcpPolicyName)) {
+    throw onInvalid(`projectMcp.policy must be one of: ${PROJECT_MCP_POLICY_NAMES.join(", ")}`);
+  }
+  return { policy: policy as ProjectMcpPolicyName };
+}

package/src/quota-advisory.ts

@@ -32,6 +32,7 @@ type AgentRecipientRow = {
 
 const RESET_ROUNDING_PERCENT = 99;
 const QUOTA_THRESHOLD_EPSILON = 1e-9;
+const QUOTA_RESET_BOUNDARY_ADVANCE_MS = 5_000;
 
 export function installQuotaAdvisoryHandler(): void {
   setProviderQuotaAdvisoryHandler(handleProviderQuotaAdvisory);
@@ -46,7 +47,7 @@ function handleProviderQuotaAdvisory(input: ProviderQuotaAdvisoryInput): string
     const previousWindow = input.previousQuota?.windows.find((candidate) => candidate.name === window.name);
     const remaining = quotaRemaining(window.utilization);
     const remainingPercent = percent(remaining);
-    const previous = nextState[window.name];
+    let previous = nextState[window.name];
     const reset = hasLastQuotaAdvisory(previous) && isQuotaReset(remaining, previousWindow, window, config.resetRemaining);
     if (reset) {
       notifyQuotaAdvisory({
@@ -65,8 +66,12 @@ function handleProviderQuotaAdvisory(input: ProviderQuotaAdvisoryInput): string
       continue;
     }
 
+    if (previous && hasLastQuotaAdvisory(previous) && quotaAdvisoryResetBoundaryAdvanced(previous, window)) {
+      delete nextState[window.name];
+      previous = undefined;
+    }
+
     if (remaining - config.warnRemaining > QUOTA_THRESHOLD_EPSILON) {
-      if (previous) delete nextState[window.name];
       continue;
     }
 
@@ -101,6 +106,17 @@ function hasLastQuotaAdvisory(previous: QuotaAdvisoryWindowState | undefined): b
   return previous?.lastQuotaAdvisoryStage !== undefined || previous?.lastQuotaAdvisoryBand !== undefined;
 }
 
+function quotaAdvisoryResetBoundaryAdvanced(
+  previous: QuotaAdvisoryWindowState,
+  window: QuotaState["windows"][number],
+): boolean {
+  return typeof previous.lastResetsAt === "number"
+    && Number.isFinite(previous.lastResetsAt)
+    && typeof window.resetsAt === "number"
+    && Number.isFinite(window.resetsAt)
+    && window.resetsAt - previous.lastResetsAt > QUOTA_RESET_BOUNDARY_ADVANCE_MS;
+}
+
 function lastQuotaAdvisoryStage(
   previous: QuotaAdvisoryWindowState | undefined,
   criticalRemaining: number,

package/src/routes/agents-spawn.ts

@@ -7,6 +7,7 @@ import { cleanMeta, cleanNullableString, cleanString, cleanStringArray, optional
 import { registerAgent } from "../services/register-agent";
 import { spawnAgent, type SpawnAgentInput } from "../services/spawn-agent";
 import { parseProjectInstructions } from "../project-instructions";
+import { parseProjectMcp } from "../project-mcp";
 import { authContextFromRequest } from "../services/auth-context";
 import { listHostDirectories } from "../agent-spawn";
 import { rankRouteCandidates, type RouteAdvisorInput } from "../context-router";
@@ -121,6 +122,7 @@ export const postAgentSpawn: Handler = async (req) => {
       prompt: cleanString(parsed.body.prompt, "prompt", { max: 16000 }),
       systemPromptAppend: cleanString(parsed.body.systemPromptAppend, "systemPromptAppend", { max: 64_000 }),
       projectInstructions: parseProjectInstructions(parsed.body.projectInstructions, (m) => new ValidationError(m)),
+      projectMcp: parseProjectMcp(parsed.body.projectMcp, (m) => new ValidationError(m)),
       tags: cleanStringArray(parsed.body.tags, "tags", { itemMax: 80, maxItems: 50 }),
       capabilities: cleanStringArray(parsed.body.capabilities, "capabilities", { itemMax: 80, maxItems: 50 }),
       providerArgs: cleanStringArray(parsed.body.providerArgs, "providerArgs", { itemMax: 80, maxItems: 50 }),

package/src/routes/provider-quotas.ts

@@ -1,7 +1,8 @@
 import { isRecord } from "agent-relay-sdk";
-import { acquireProviderQuotaLease, getOrchestrator, listProviderQuotas, releaseProviderQuotaLease, upsertProviderQuota } from "../db";
+import { acquireProviderQuotaLease, getOrchestrator, getProviderQuotaLease, listProviderQuotas, releaseProviderQuotaLease, upsertProviderQuota } from "../db";
 import { emitRelayEvent } from "../events";
 import { quotaStateFromUnknown, providerQuotaErrorFromUnknown } from "../quota";
+import { authContextFromRequest } from "../services/auth-context";
 import { cleanString } from "../validation";
 import { authorizeRoute, error, json, parseBody, parseQueryInt, type Handler } from "./_shared";
 import type { ProviderQuotaUpdateInput } from "../types";
@@ -45,6 +46,8 @@ export const postProviderQuotaRoute: Handler = async (req) => {
   if (!parsed.ok) return error(parsed.error, parsed.status);
   const input = cleanProviderQuotaUpdate(parsed.body);
   if (typeof input === "string") return error(input);
+  const providerWriteGate = authorizeProviderQuotaWrite(req, input);
+  if (providerWriteGate) return providerWriteGate;
   const record = upsertProviderQuota(input);
   emitRelayEvent({ type: "provider-quota.updated", source: "server", subject: `${record.provider}:${record.accountKey}`, data: {} });
   return json(record, 201);
@@ -82,12 +85,36 @@ function cleanPublisherLeaseBody(body: unknown): {
 
 const runnerLeaseHolderId = (sourceAgentId: string) => `runner:${sourceAgentId}`;
 
+function authorizeProviderQuotaSourceAgent(req: Request, sourceAgentId: string): Response | null {
+  const ctx = authContextFromRequest(req);
+  if (ctx.component?.role !== "provider") return null;
+  const denied = authorizeRoute(req, { scope: "quota:write" });
+  if (denied) return denied;
+  return ctx.callerAgentId === sourceAgentId ? null : error("forbidden", 403);
+}
+
+function authorizeProviderQuotaWrite(req: Request, input: ProviderQuotaUpdateInput): Response | null {
+  const ctx = authContextFromRequest(req);
+  if (ctx.component?.role !== "provider") return null;
+  if (!input.sourceAgentId) return error("sourceAgentId required for provider quota writer", 403);
+  const denied = authorizeProviderQuotaSourceAgent(req, input.sourceAgentId);
+  if (denied) return denied;
+  const lease = getProviderQuotaLease(input.provider, input.accountKey);
+  const activeLease = lease && lease.expiresAt > Date.now() ? lease : null;
+  if (activeLease?.orchestratorId === runnerLeaseHolderId(input.sourceAgentId)) return null;
+  return json({
+    skipped: true,
+    reason: "provider quota lease not held by source agent",
+    ...(activeLease ? { holder: { orchestratorId: activeLease.orchestratorId, expiresAt: activeLease.expiresAt } } : {}),
+  }, 202);
+}
+
 export const postProviderQuotaPublisherLeaseAcquireRoute: Handler = async (req) => {
   const parsed = await parseBody<unknown>(req);
   if (!parsed.ok) return error(parsed.error, parsed.status);
   const input = cleanPublisherLeaseBody(parsed.body);
   if (typeof input === "string") return error(input);
-  const denied = authorizeRoute(req, { scope: "quota:write", resource: { agentId: input.sourceAgentId } });
+  const denied = authorizeProviderQuotaSourceAgent(req, input.sourceAgentId);
   if (denied) return denied;
   return json(acquireProviderQuotaLease({
     provider: input.provider,
@@ -104,7 +131,7 @@ export const postProviderQuotaPublisherLeaseReleaseRoute: Handler = async (req)
   const input = cleanPublisherLeaseBody(parsed.body);
   if (typeof input === "string") return error(input);
   if (!input.leaseToken) return error("leaseToken required");
-  const denied = authorizeRoute(req, { scope: "quota:write", resource: { agentId: input.sourceAgentId } });
+  const denied = authorizeProviderQuotaSourceAgent(req, input.sourceAgentId);
   if (denied) return denied;
   return json({
     released: releaseProviderQuotaLease({

package/src/services/spawn-agent.ts

@@ -33,6 +33,7 @@ import { runnerRuntimeTokenEnv } from "../runtime-tokens";
 import { selectSpawnOrchestrator } from "../spawn-targets";
 import { DEFAULT_SPAWN_PROFILE_NAME, getAgentProfile } from "../config-store";
 import { composeSpawnInstructionsWithEvents, type ProjectInstructionPolicy } from "../project-instructions";
+import type { ProjectMcpPolicy } from "../project-mcp";
 import { autoSeedProjectForCwd } from "./project";
 import { hasComponentScope, isComponentAuthorizedFor } from "../security";
 import { isPathWithinBase } from "../utils";
@@ -74,6 +75,15 @@ export interface SpawnAgentInput {
    * `vanilla` (manual+promoted; excludes `ingested` host-CLAUDE.md content).
    */
   projectInstructions?: ProjectInstructionPolicy;
+  /**
+   * #667 — project `.mcp.json` MCP projection. When set, the runner reads the spawn cwd's
+   * COMMITTED `.mcp.json` and injects those servers via the controlled `--mcp-config`
+   * (composing with #662 `--strict-mcp-config`), so a worker spawned into a repo gets that
+   * repo's MCP servers — sourced from the project, never ambient host MCP. Additive-from-
+   * empty + opt-in: absent (undefined) = OFF → the launch is byte-identical to today. Sibling
+   * to projectInstructions; carried to the runner on the in-flight `agentProfile.projectMcp`.
+   */
+  projectMcp?: ProjectMcpPolicy;
   /**
    * Legacy report-back contract flag. Spawned children now report up by lineage: their
    * turn-final response is delivered to the spawner automatically, without a reply obligation.
@@ -170,6 +180,14 @@ export async function spawnAgent(input: SpawnAgentInput, ctx: AuthContext): Prom
   const agentProfile = withResolvedProvisioning(getAgentProfile(profileName)?.value, input.provider);
   if (!agentProfile) throw new McpNotFoundError(input.profile ? "agent profile not found" : `default agent profile ${DEFAULT_SPAWN_PROFILE_NAME} not found`);
 
+  // #667 — project `.mcp.json` projection: a per-spawn `projectMcp` overrides the profile
+  // default. The runner does the filesystem read + injection from `agentProfile.projectMcp`
+  // (it owns the spawn cwd), so thread the resolved decision onto the in-flight profile copy
+  // (withResolvedProvisioning returned a fresh object; mutating it never touches the cached
+  // config). Like projectInstructions, an explicit `false` parses to undefined and so cannot
+  // turn a profile default OFF — opt-in is the trust gate, not opt-out.
+  if (input.projectMcp !== undefined) agentProfile.projectMcp = input.projectMcp;
+
   // --- THE GATE (uniform across transports) ---------------------------------
   // Coarse capability: spawning requires command:spawn. The MCP dispatcher already enforced
   // this; the HTTP route did not — asserting here makes it transport-invariant.