agent-relay-server 0.70.1 → 0.71.0

package/docs/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "Agent Relay API",
-    "version": "0.70.1",
+    "version": "0.71.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.70.1",
+  "version": "0.71.0",
   "description": "Lightweight HTTP message relay for inter-agent communication across machines",
   "module": "src/index.ts",
   "type": "module",

package/src/config-store.ts

@@ -49,16 +49,18 @@ const VALID_PROFILE_FILESYSTEM_SCOPES = ["repo", "workspace", "host"] as const;
 const VALID_PERMISSION_MODES = ["open", "guarded", "read-only"] as const;
 const VALID_POLICY_MODES = ["always-on", "on-demand"] as const;
 const VALID_MANAGED_STATUSES = ["stopped", "starting", "running", "stopping", "backoff", "failed"] as const;
+export const DEFAULT_SPAWN_PROFILE_NAME = "default-relay";
 const COORDINATION_CHARTER = "Coordination charter: stay at helicopter altitude; delegate implementation to spawned workers; write briefs, maintain the blackboard and plan DAG; coordinate, review, and release; do not drift into mechanical edits when a worker can do them; protect your context for coordination.";
 const OPS_ASSISTANT_BRIEF = [
   "Ops-assistant standing brief: execute mechanical operations on your coordinator's behalf: test suites, release commands such as `bun run release`, smoke and verification probes, gates, and host/version/status checks.",
+  "When running a self-verifying long script, especially `bun run release` (gates -> CI-watch -> deploy -> host-verify, then one final result), run it and wait for completion. Do not poll, monitor, tail logs, run parallel status/version checks, or otherwise babysit it while it runs. Trust the script; act only on its final result.",
   "Hold and apply session-local ops conventions the coordinator gives you. Report crisp outcomes only: command/gate, pass/fail, commit/version/host evidence, and the next blocker when one exists. Do not dump logs unless asked.",
   "Do not make strategy, design, scope, or release-timing calls. Escalate those decisions to your spawn-parent. Report operational results to your spawn-parent by default and keep their context clean.",
 ].join("\n");
-const BUILT_IN_AGENT_PROFILE_NAMES = new Set(["default-relay", "minimal", "isolated-research", "vanilla", "lean-worker", "coordinator", "ops-assistant", "worker", "reviewer"]);
+const BUILT_IN_AGENT_PROFILE_NAMES = new Set([DEFAULT_SPAWN_PROFILE_NAME, "minimal", "isolated-research", "vanilla", "lean-worker", "coordinator", "ops-assistant", "worker", "reviewer"]);
 
 const BUILT_IN_AGENT_PROFILES: AgentProfile[] = [
-  agentProfileDefaults({ name: "default-relay", description: "Relay-aware spawned agent with bundled Relay context, skills, plugins, and status integration.", base: "host" }),
+  agentProfileDefaults({ name: DEFAULT_SPAWN_PROFILE_NAME, description: "Relay-aware spawned agent with bundled Relay context, skills, plugins, and status integration.", base: "host" }),
   agentProfileDefaults({ name: "minimal", description: "Repo-focused spawned agent with Relay affordances disabled and host/global extras avoided where supported.", base: "minimal" }),
   agentProfileDefaults({ name: "isolated-research", description: "Strict profile for autonomous research runs: repo context only, no Relay prompt surface, no global extras where supported.", base: "isolated" }),
   agentProfileDefaults({ name: "vanilla", description: "Zero host bleed (#552): isolated provider home with host plugins, skills, hooks, MCP, and the CLAUDE.md/AGENTS.md cascade (repo + global) all suppressed at launch. Relay provisions any surface explicitly per profile.", base: "vanilla" }),

package/src/mcp/tools-spawn.ts

@@ -5,6 +5,7 @@ import { buildSpawnTargets } from "../spawn-targets";
 import { McpAuthError, McpNotFoundError } from "../mcp-errors";
 import { parseProjectInstructions, PROJECT_INSTRUCTION_POLICY_NAMES } from "../project-instructions";
 import { ValidationError } from "../db";
+import { DEFAULT_SPAWN_PROFILE_NAME } from "../config-store";
 import { optionalEnum } from "../validation";
 import { APPROVAL_MODES, SPAWN_PROVIDERS, VALID_AGENT_LIFECYCLES, VALID_EFFORTS, VALID_WORKSPACE_MODES } from "agent-relay-sdk";
 import type { ProviderEffort } from "agent-relay-sdk/provider-catalog";
@@ -16,7 +17,7 @@ import { enumField, optionalNonNegativeInt, optionalPositiveInt, optionalString,
 export const SPAWN_TOOLS: ToolDefinition[] = [
   {
     name: "relay_spawn_agent",
-    description: "Spawn a long-living provider agent through Relay's orchestrator, optionally handing it its first task via `prompt` in the same call. Defaults to your own host (override with orchestratorId) and returns the resolved agent id once it registers. Gated: requires the command:spawn scope, granted only to agents whose profile sets maxSpawnedAgents>0, up to that live-children quota. Spawned agents cannot themselves spawn (no grandchildren).",
+    description: `Spawn a long-living provider agent through Relay's orchestrator, optionally handing it its first task via \`prompt\` in the same call. Defaults to your own host (override with orchestratorId), applies profile \`${DEFAULT_SPAWN_PROFILE_NAME}\` when profile is omitted, and returns the resolved agent id once it registers. Gated: requires the command:spawn scope, granted only to agents whose profile sets maxSpawnedAgents>0, up to that live-children quota. Spawned agents cannot themselves spawn (no grandchildren).`,
     requiredScopes: ["command:spawn"],
     inputSchema: {
       type: "object",
@@ -32,7 +33,7 @@ export const SPAWN_TOOLS: ToolDefinition[] = [
         expectReply: { type: "boolean", description: "Require the worker to report back: it gets a pending reply obligation to you and CANNOT go idle until it delivers its result (which routes to your inbox and wakes you). Defaults true when you pass a prompt — set false for a true fire-and-forget worker that needn't report (e.g. one that only lands a branch)." },
         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 },
-        profile: { type: "string", description: "Agent profile name to apply (env, instructions, permissions, MCP/skills, spawn quota)." },
+        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" } },
         providerArgs: { type: "array", items: { type: "string" } },

package/src/services/issue-lifecycle.ts

@@ -62,7 +62,7 @@ type LandIssueRefSource = "association" | "commit" | "backlink";
 
 type CloseIssueLifecycleResult =
   | { issueRef: IssueRef; action: "closed"; source: LandIssueRefSource; landKey: string }
-  | { issueRef: IssueRef; action: "skipped"; reason: "already-closed" | "already-processed"; landKey: string }
+  | { issueRef: IssueRef; action: "skipped"; reason: "already-closed" | "already-processed" | "open-sub-issues"; landKey: string }
   | { issueRef: IssueRef; action: "failed"; error: string; landKey: string };
 
 type ReopenIssueLifecycleResult =
@@ -208,6 +208,16 @@ function closeAuditComment(input: LandedIssueLifecycleInput): string {
   return `Closed by \`${commit}\` on merge to \`main\` - reopen if release surfaces more work.`;
 }
 
+function issueLabel(ref: IssueRef, parent: IssueRef): string {
+  return ref.repo === parent.repo ? `#${ref.externalKey}` : `${ref.repo}#${ref.externalKey}`;
+}
+
+function backlinkProgressComment(input: LandedIssueLifecycleInput, parent: IssueRef, openSubIssues: IssueRef[]): string {
+  const commit = input.mergedSha ? input.mergedSha.slice(0, 12) : input.workspace.branch ?? input.workspace.id;
+  const childList = openSubIssues.map((ref) => issueLabel(ref, parent)).join(", ");
+  return `Linked landed slice \`${commit}\` to this parent issue, but Agent Relay left it open because these sub-issues are still open: ${childList}.`;
+}
+
 async function reconcileClosedIssueRefBeforeSkip(issueRef: IssueRef, opts: IssueLifecycleOptions): Promise<{
   issueRef: IssueRef;
   liveStatus?: IssueRef["status"];
@@ -240,6 +250,19 @@ async function closeIssueRefForLand(
     if (reconciled.liveStatus !== "open") return { issueRef: latest, action: "skipped", reason: "already-closed", landKey: key };
   }
 
+  const openSubIssues = source === "backlink"
+    ? listIssuesForEntity("epic", latest.id).map((item) => item.issueRef).filter((ref) => ref.status === "open")
+    : [];
+  if (openSubIssues.length > 0) {
+    const comment = backlinkProgressComment(input, latest, openSubIssues);
+    try {
+      await adapterFor(latest, opts).comment(latest, comment);
+    } catch (error) {
+      logFailure(opts, `issue lifecycle epic backlink comment failed for ${latest.id} on ${key}: ${errMessage(error)}`);
+    }
+    return { issueRef: latest, action: "skipped", reason: "open-sub-issues", landKey: key };
+  }
+
   const comment = closeAuditComment(input);
   try {
     await adapterFor(latest, opts).close(latest, { comment, labels: ["fixed"] });

package/src/services/spawn-agent.ts

@@ -31,7 +31,7 @@ import { emitCommandEvent } from "../command-events";
 import { buildSpawnCommand, generateSpawnRequestId, resolveSpawnModelParams } from "../spawn-command";
 import { runnerRuntimeTokenEnv } from "../runtime-tokens";
 import { selectSpawnOrchestrator } from "../spawn-targets";
-import { getAgentProfile } from "../config-store";
+import { DEFAULT_SPAWN_PROFILE_NAME, getAgentProfile } from "../config-store";
 import { composeSpawnInstructions, type ProjectInstructionPolicy } from "../project-instructions";
 import { autoSeedProjectForCwd } from "./project";
 import { hasComponentScope, isComponentAuthorizedFor } from "../security";
@@ -167,10 +167,11 @@ export async function spawnAgent(input: SpawnAgentInput, ctx: AuthContext): Prom
   const spawnRequestId = input.spawnRequestId ?? generateSpawnRequestId();
 
   // Resolve + validate the named agent profile server-side (was HTTP-only; the MCP path passed
-  // the name through unvalidated). Both transports now 404 on an unknown profile and ship the
-  // resolved value to the orchestrator.
-  const agentProfile = withResolvedProvisioning(input.profile ? getAgentProfile(input.profile)?.value : undefined, input.provider);
-  if (input.profile && !agentProfile) throw new McpNotFoundError("agent profile not found");
+  // the name through unvalidated). Omitted profile uses Relay's spawn default so coordinator
+  // spawns still get the bundled Relay context/affordances. Explicit profile always wins.
+  const profileName = input.profile ?? DEFAULT_SPAWN_PROFILE_NAME;
+  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`);
 
   // --- THE GATE (uniform across transports) ---------------------------------
   // Coarse capability: spawning requires command:spawn. The MCP dispatcher already enforced
@@ -247,7 +248,7 @@ export async function spawnAgent(input: SpawnAgentInput, ctx: AuthContext): Prom
     // dropped this when it unified the spawn service, silently un-spawning every default-spawner
     // (P0 regression #364). For an agent caller, agentInitiated still forces a non-spawn-capable
     // child regardless of profile (no grandchildren).
-    profile: input.profile || undefined,
+    profile: profileName,
     ...(callerId ? { agentInitiated: true, spawnedBy: callerId } : {}),
     ...(callerTeam ? { teamId: callerTeam.id } : {}),
     ...(callerProject ? { projectId: callerProject.id } : {}),
@@ -270,7 +271,7 @@ export async function spawnAgent(input: SpawnAgentInput, ctx: AuthContext): Prom
       ...(workspaceMode ? { workspaceMode } : {}),
       lifecycle,
       label: input.label,
-      profile: input.profile || undefined,
+      profile: profileName,
       agentProfile,
       tags: input.tags ?? [],
       capabilities: input.capabilities ?? [],

package/src/spawn-targets.ts

@@ -1,5 +1,5 @@
 import { countLiveSpawnedAgents, getAgent, getOrchestrator, listOrchestrators, ValidationError } from "./db";
-import { listAgentProfiles } from "./config-store";
+import { DEFAULT_SPAWN_PROFILE_NAME, listAgentProfiles } from "./config-store";
 import { effectiveProviderCatalogList } from "./provider-catalog-store";
 import { isPathWithinBase } from "./utils";
 import { McpNotFoundError } from "./mcp-errors";
@@ -39,7 +39,7 @@ export function buildSpawnTargets(input: { callerId?: string; quota: number }):
       })),
     profiles: spawnProfilesSummary(),
     guidance:
-      "Default to your own host (isSelf:true); only set orchestratorId to spawn onto another host that runs a provider/model yours doesn't. Omitting model/effort uses the provider default (marked below). Prefer a named profile over assembling raw knobs; set spawnRequestId for idempotency. After spawning you'll be pushed agent.ready / agent.exited / agent.spawn_failed — don't block-poll.",
+      `Default to your own host (isSelf:true); only set orchestratorId to spawn onto another host that runs a provider/model yours doesn't. Omitting profile applies ${DEFAULT_SPAWN_PROFILE_NAME}; omitting model/effort uses the provider default (marked below). Prefer a named profile over assembling raw knobs; set spawnRequestId for idempotency. After spawning you'll be pushed agent.ready / agent.exited / agent.spawn_failed — don't block-poll.`,
   };
 }
 
@@ -109,7 +109,7 @@ export function spawnCapablePrimer(input: { canSpawn: boolean; quota?: number })
     `You can spawn long-living child agents${quotaLabel}. Shut your own down with relay_shutdown_agent.`,
     "- BEFORE spawning, call relay_spawn_targets: it returns the LIVE matrix of hosts × providers × models × per-model effort, your remaining quota, and named profiles. Don't guess — that tool is the discovery path.",
     "- Default to your OWN host. Only set orchestratorId to spawn onto another host when it runs a provider/model yours doesn't, or the work must run there.",
-    "- Prefer a named profile (profile: \"<name>\") over hand-assembling provider+model+effort+approvalMode. Omitting model/effort uses the provider default. Lean to the cheapest provider/model/effort that fits; escalate only for complex work.",
+    `- Prefer a named profile (profile: "<name>") over hand-assembling provider+model+effort+approvalMode. Omitting profile applies ${DEFAULT_SPAWN_PROFILE_NAME}; omitting model/effort uses the provider default. Lean to the cheapest provider/model/effort that fits; escalate only for complex work.`,
     "- Set spawnRequestId for idempotency so a retried spawn doesn't double-create.",
     "- Spawn is fire-and-forget: pass waitForRegistrationMs:0 and keep working — you'll be PUSHED agent.ready when the child is genuinely ready (past onboarding), or agent.spawn_failed / agent.exited otherwise. Don't block-poll.",
     "- Spawned children cannot themselves spawn (no grandchildren).",