agent-relay-server 0.109.0 → 0.110.0

package/src/services/spawn-agent.ts

@@ -25,7 +25,9 @@
 // deliberately out of scope here — this slice converges the two external TRANSPORTS.
 import type { SpawnProvider } from "agent-relay-sdk";
 import { DEFAULT_USER_ID, errMessage, isRecord, stringValue } from "agent-relay-sdk";
-import { assignTaskAgent, countLiveSpawnedAgents, createActivityEvent, ensureTeam, getAgent, listAgents, listWorkspaces, recordTaskSpawnRequested, resolveAgentOwnership, resolveProjectForCwd, resolveScopedAnchor, setAgentTeam, ValidationError, withResolvedProvisioning } from "../db";
+import { statSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { countLiveSpawnedAgents, createActivityEvent, ensureTeam, getAgent, getTaskDetail, listAgents, listProjects, listWorkspaces, recordTaskSpawnRequested, resolveAgentOwnership, resolveProjectForCwd, resolveScopedAnchor, rootsForProject, setAgentTeam, ValidationError, withResolvedProvisioning } from "../db";
 import { createCommand } from "../commands-db";
 import { emitCommandEvent } from "../command-events";
 import { buildSpawnCommand, generateSpawnRequestId, resolveSpawnModelParams } from "../spawn-command";
@@ -39,6 +41,7 @@ import type { ProjectSkillsPolicy } from "../project-skills";
 import { applyDefaultSharedMcp, type SharedMcpSpawnOverride } from "../shared-mcp";
 import { autoSeedProjectForCwd } from "./project";
 import { hydrateTaskContext, projectTaskHydration } from "./task-context-hydration";
+import { recordTaskEntityDispatchDecision } from "./task-entity";
 import { dispatchTask } from "../task-dispatcher";
 import { hasComponentScope, isComponentAuthorizedFor } from "../security";
 import { isPathWithinBase } from "../utils";
@@ -51,6 +54,60 @@ import { TERMINAL_WORKSPACE_STATUSES } from "../workspace-phase";
 /** The spawn scope every transport must hold (admin `*` / `admin:*` pass; `system` bypasses). */
 const SPAWN_SCOPE = "command:spawn";
 
+function hasGitMarker(dir: string): boolean {
+  try {
+    const marker = statSync(`${dir}/.git`);
+    return marker.isDirectory() || marker.isFile();
+  } catch {
+    return false;
+  }
+}
+
+function findGitRepoRoot(cwd: string): string | null {
+  if (!cwd.trim()) return null;
+  let current = resolve(cwd);
+  try {
+    const stat = statSync(current);
+    if (!stat.isDirectory()) current = dirname(current);
+  } catch {
+    return null;
+  }
+  for (;;) {
+    if (hasGitMarker(current)) return current;
+    const parent = dirname(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+}
+
+function assertIsolatedSpawnHasGitRepo(cwd: string): void {
+  if (findGitRepoRoot(cwd)) return;
+  throw new ValidationError(`workspaceMode "isolated" requires a git repo, but ${cwd} is not one. Pass an explicit cwd under a repo, or use workspaceMode "shared"/"inherit".`);
+}
+
+function taskLinkedRepoCwd(taskId: number, callerCwd?: string): string {
+  const task = getTaskDetail(taskId);
+  if (!task) throw new ValidationError(`task ${taskId} not found or not a deliverable task`);
+  const repos = [...new Set(task.issues.map((issue) => issue.repo).filter((repo): repo is string => Boolean(repo)))];
+  if (repos.length === 0) {
+    throw new ValidationError(`task ${taskId} has no linked issue repo; pass cwd/orchestratorId explicitly`);
+  }
+  const candidates = listProjects()
+    .filter((project) => project.issueRepo && repos.includes(project.issueRepo))
+    .flatMap((project) => rootsForProject(project.id).map((root) => ({ project, root })));
+  if (candidates.length === 0) {
+    throw new ValidationError(`task ${taskId} links repo ${repos.join(", ")} but no Relay project root is registered for it; pass cwd/orchestratorId explicitly or add a project root`);
+  }
+  const matchingCallerRoot = callerCwd
+    ? candidates
+      .filter((candidate) => isPathWithinBase(callerCwd, candidate.root.rootPath))
+      .sort((a, b) => b.root.rootPath.length - a.root.rootPath.length)[0]
+    : undefined;
+  if (matchingCallerRoot) return matchingCallerRoot.root.rootPath;
+  if (candidates.length === 1) return candidates[0]!.root.rootPath;
+  throw new ValidationError(`task ${taskId} links repo ${repos.join(", ")} with multiple registered roots; pass cwd explicitly`);
+}
+
 /**
  * A normalized spawn request — every transport validates its own wire shape (enums,
  * lengths) and hands the service this. Caller-context defaults (cwd, approvalMode,
@@ -177,6 +234,19 @@ function canSpawn(ctx: AuthContext): boolean {
   return ctx.scopes.includes(SPAWN_SCOPE);
 }
 
+function agentIdFromTaskCreator(createdBy: string | undefined): string | undefined {
+  const raw = createdBy?.trim();
+  if (!raw) return undefined;
+  const candidates = [raw, raw.startsWith("agent:") ? raw.slice("agent:".length) : undefined].filter((value): value is string => Boolean(value));
+  return candidates.find((candidate) => getAgent(candidate)) ?? undefined;
+}
+
+function taskSpawnLabel(task: { id: number; title: string } | undefined, fallback?: string): string | undefined {
+  if (fallback || !task) return fallback;
+  const label = `task-${task.id}: ${task.title.trim() || "untitled"}`;
+  return label.length <= 120 ? label : `${label.slice(0, 117)}...`;
+}
+
 /**
  * Spawn a provider agent. Transport-agnostic: every gate + side effect lives here so the
  * MCP and HTTP paths cannot drift. Throws `McpAuthError` (→403) on a gate denial,
@@ -189,22 +259,30 @@ export async function spawnAgent(input: SpawnAgentInput, ctx: AuthContext): Prom
   // the #221 gate AND the #328/#331/#324 caller-context inheritance — one lookup, reused.
   const callerId = ctx.callerAgentId;
   const caller: AgentCard | undefined = (callerId ? getAgent(callerId) : undefined) ?? undefined;
+  const linkedTask = input.taskId !== undefined ? getTaskDetail(input.taskId) ?? undefined : undefined;
+  const taskCreatorAgentId = !callerId ? agentIdFromTaskCreator(linkedTask?.createdBy) : undefined;
+  const lineageAgentId = callerId ?? taskCreatorAgentId;
+  const lineageAgent: AgentCard | undefined = (lineageAgentId ? getAgent(lineageAgentId) : undefined) ?? undefined;
+  const callerCwd = stringValue(caller?.meta?.cwd) ?? stringValue(lineageAgent?.meta?.cwd);
+  const taskDefaultCwd = input.taskId !== undefined && !input.orchestratorId && !input.cwd
+    ? taskLinkedRepoCwd(input.taskId, callerCwd)
+    : undefined;
+  const requestedCwd = input.cwd ?? taskDefaultCwd;
 
   // #255/#328 — bias the host to the caller's own machine when neither an explicit
   // orchestratorId nor a cwd pins it, so an agent spawning a helper lands on its own host.
-  const orchestrator = selectSpawnOrchestrator(input.provider, input.orchestratorId, input.cwd, caller?.machine);
+  const orchestrator = selectSpawnOrchestrator(input.provider, input.orchestratorId, requestedCwd, caller?.machine ?? lineageAgent?.machine);
 
   // #308 §3 — an explicit cwd must resolve within the TARGET host's base dir (a path valid on
   // your host may not exist on a different orchestrator).
-  if (input.cwd && !isPathWithinBase(input.cwd, orchestrator.baseDir)) {
-    throw new ValidationError(`cwd '${input.cwd}' is not within ${orchestrator.id} (host ${orchestrator.hostname})'s base dir '${orchestrator.baseDir}' — a path valid on your host may not exist on the target. Pass a cwd under that base dir, or omit cwd to default to it.`);
+  if (requestedCwd && !isPathWithinBase(requestedCwd, orchestrator.baseDir)) {
+    throw new ValidationError(`cwd '${requestedCwd}' is not within ${orchestrator.id} (host ${orchestrator.hostname})'s base dir '${orchestrator.baseDir}' — a path valid on your host may not exist on the target. Pass a cwd under that base dir, or omit cwd to default to it.`);
   }
   // #328 — default cwd to the caller's OWN repo (so "spawn a helper for my current task" Just
   // Works, esp. isolated mode which needs a git repo), but only when it resolves within the
   // target host's base. Precedence: explicit cwd > caller cwd > base dir.
-  const callerCwd = stringValue(caller?.meta?.cwd);
   const inheritedCwd = callerCwd && isPathWithinBase(callerCwd, orchestrator.baseDir) ? callerCwd : undefined;
-  const resolvedCwd = input.cwd || inheritedCwd || orchestrator.baseDir;
+  const resolvedCwd = requestedCwd || inheritedCwd || orchestrator.baseDir;
 
   // #838 — spawn-with-task hydration. When a taskId is given, relay assembles the worker's
   // first-turn context FROM the durable Task (intent + linked-issue spec/acceptance + recorded
@@ -234,9 +312,11 @@ export async function spawnAgent(input: SpawnAgentInput, ctx: AuthContext): Prom
   // and a no-taskId spawn is untouched — the coupling is opt-in, not hard-wired.
   let dispatchModel = input.model;
   let dispatchEffort = input.effort;
+  let taskDispatchDecision: ReturnType<typeof dispatchTask> | undefined;
   if (hydratedTask && !input.model && !input.effort && hydratedTask.task.dispatch) {
     try {
       const decision = dispatchTask(hydratedTask.task.dispatch, { provider: input.provider });
+      taskDispatchDecision = decision;
       dispatchModel = decision.target.model ?? dispatchModel;
       dispatchEffort = decision.target.effort ?? dispatchEffort;
     } catch (err) {
@@ -245,18 +325,23 @@ export async function spawnAgent(input: SpawnAgentInput, ctx: AuthContext): Prom
   }
 
   const modelParams = resolveSpawnModelParams(input.provider, dispatchModel, dispatchEffort);
+  const resolvedLabel = taskSpawnLabel(linkedTask, input.label);
 
   // #331 — default the child's approval mode to the CALLER's, not a hardcoded `guarded` (a
   // headless `guarded` child wedges on its first tool-call approval prompt). Explicit always
   // wins and can NARROW a child; non-agent callers keep the safe `guarded` default.
-  const callerApprovalMode = caller?.meta?.approvalMode as SpawnApprovalMode | undefined;
-  const approvalMode = input.approvalMode ?? callerApprovalMode ?? "guarded";
+  const callerApprovalMode = (caller?.meta?.approvalMode ?? lineageAgent?.meta?.approvalMode) as SpawnApprovalMode | undefined;
+  const approvalMode = input.approvalMode ?? callerApprovalMode ?? (input.taskId !== undefined ? "open" : "guarded");
 
   // #324 — agent-initiated spawns (a real caller behind the token) default to `isolated` (a
   // branch worker that auto-lands); non-agent callers (admin/dashboard) keep the orchestrator's
-  // `inherit` fallback. Explicit wins.
-  const workspaceMode = input.workspaceMode ?? (callerId ? ("isolated" as WorkspaceMode) : undefined);
+  // `inherit` fallback. Task-triggered spawns are coordinator work and should get an isolated
+  // branch unless explicitly narrowed.
+  const workspaceMode = input.workspaceMode ?? (callerId || input.taskId !== undefined ? ("isolated" as WorkspaceMode) : undefined);
   const lifecycle = input.lifecycle ?? "persistent";
+  if (workspaceMode === "isolated" && (input.taskId !== undefined || input.workspaceMode === "isolated")) {
+    assertIsolatedSpawnHasGitRepo(resolvedCwd);
+  }
 
   const spawnRequestId = input.spawnRequestId ?? generateSpawnRequestId();
 
@@ -344,9 +429,9 @@ export async function spawnAgent(input: SpawnAgentInput, ctx: AuthContext): Prom
 
   // Provenance actor: the resolved caller agent when known, else the transport's label, else
   // the raw token actor. Recorded in the command payload, the token mint, and the audit row.
-  const requestedBy = callerId ?? input.requestedBy ?? ctx.actor.id;
-  const callerTeam = callerId ? (caller?.teamId ? { id: caller.teamId } : ensureTeam(callerId)) : undefined;
-  if (callerId && callerTeam && !caller?.teamId) setAgentTeam(callerId, callerTeam.id);
+  const requestedBy = callerId ?? taskCreatorAgentId ?? input.requestedBy ?? ctx.actor.id;
+  const callerTeam = lineageAgentId ? (lineageAgent?.teamId ? { id: lineageAgent.teamId } : ensureTeam(lineageAgentId)) : undefined;
+  if (lineageAgentId && callerTeam && !lineageAgent?.teamId) setAgentTeam(lineageAgentId, callerTeam.id);
 
   // #405 — durable project binding: the project whose registered root contains the spawn cwd.
   // Stamped on the child token's constraints (identity-only, like teamId) so callerProject(auth)
@@ -374,7 +459,7 @@ export async function spawnAgent(input: SpawnAgentInput, ctx: AuthContext): Prom
   // Both resolve null until someone has actually written to them, so a fresh deployment stays
   // byte-identical. Injection of their active (promoted) entries happens in the composer.
   const profileAnchor = resolveScopedAnchor("profile", profileName);
-  const operatorId = callerId ? resolveAgentOwnership(callerId).ownerUserId : DEFAULT_USER_ID;
+  const operatorId = lineageAgentId ? resolveAgentOwnership(lineageAgentId).ownerUserId : DEFAULT_USER_ID;
   const userAnchor = resolveScopedAnchor("user", operatorId);
   const composedInstructions = composeSpawnInstructionsWithEvents({
     ...(callerProject ? { callerProject } : {}),
@@ -382,7 +467,7 @@ export async function spawnAgent(input: SpawnAgentInput, ctx: AuthContext): Prom
     ...(profileAnchor ? { profileAnchor } : {}),
     ...(userAnchor ? { userAnchor } : {}),
     ...(agentProfile ? { profile: agentProfile } : {}),
-    ...(callerId ? { spawnedBy: callerId } : {}),
+    ...(lineageAgentId ? { spawnedBy: lineageAgentId } : {}),
     ...(resolvedSystemPromptAppend ? { callerSystemPromptAppend: resolvedSystemPromptAppend } : {}),
   });
   const systemPromptAppend = composedInstructions.systemPromptAppend;
@@ -395,9 +480,10 @@ export async function spawnAgent(input: SpawnAgentInput, ctx: AuthContext): Prom
     orchestratorId: orchestrator.id,
     cwd: resolvedCwd,
     provider: input.provider,
-    label: input.label,
+    label: resolvedLabel,
     policyName: input.policyName,
     spawnRequestId,
+    taskId: input.taskId,
     createdBy: requestedBy,
     // Thread the resolved profile into the mint so the spawn grant (command:spawn/shutdown +
     // maxSpawnedAgents quota) is honored — parity with the HTTP path (agent-sessions.ts). #349
@@ -405,7 +491,7 @@ export async function spawnAgent(input: SpawnAgentInput, ctx: AuthContext): Prom
     // (P0 regression #364). For an agent caller, agentInitiated still forces a non-spawn-capable
     // child regardless of profile (no grandchildren).
     profile: profileName,
-    ...(callerId ? { agentInitiated: true, spawnedBy: callerId } : {}),
+    ...(lineageAgentId ? { agentInitiated: true, spawnedBy: lineageAgentId } : {}),
     ...(callerTeam ? { teamId: callerTeam.id } : {}),
     ...(callerProject ? { projectId: callerProject.id } : {}),
   });
@@ -426,7 +512,7 @@ export async function spawnAgent(input: SpawnAgentInput, ctx: AuthContext): Prom
       cwd: resolvedCwd,
       ...(workspaceMode ? { workspaceMode } : {}),
       lifecycle,
-      label: input.label,
+      label: resolvedLabel,
       profile: profileName,
       agentProfile,
       tags: input.tags ?? [],
@@ -440,6 +526,7 @@ export async function spawnAgent(input: SpawnAgentInput, ctx: AuthContext): Prom
       landStrategy: input.landStrategy,
       autoMerge: input.autoMerge,
       reviewer: input.reviewer,
+      taskId: input.taskId,
       resumeWorkspace: input.resumeWorkspace,
       ...(expectReply ? { expectReply } : {}),
       policyName: input.policyName,
@@ -451,7 +538,7 @@ export async function spawnAgent(input: SpawnAgentInput, ctx: AuthContext): Prom
       orchestratorId: orchestrator.id,
       // #308 — stamp the spawning parent so a FAILED agent.spawn command (child never registers,
       // so there's no agent row to resolve `spawnedBy` from) can be routed back to it.
-      ...(callerId ? { extra: { spawnedBy: callerId } } : {}),
+      ...(lineageAgentId ? { extra: { spawnedBy: lineageAgentId } } : {}),
     }),
   });
   emitCommandEvent(command, "command.requested");
@@ -472,7 +559,7 @@ export async function spawnAgent(input: SpawnAgentInput, ctx: AuthContext): Prom
       approvalMode,
       lifecycle,
       workspaceMode: workspaceMode ?? null,
-      label: input.label ?? null,
+      label: resolvedLabel ?? null,
       commandId: command.id,
       spawnRequestId,
       requestedVia: input.requestedVia ?? null,
@@ -486,6 +573,13 @@ export async function spawnAgent(input: SpawnAgentInput, ctx: AuthContext): Prom
   // drive one-shot reap. Best-effort: an attribution write never fails the spawn.
   if (input.taskId !== undefined) {
     try {
+      if (taskDispatchDecision) {
+        recordTaskEntityDispatchDecision(input.taskId, {
+          decision: taskDispatchDecision,
+          source: "spawn",
+          actor: requestedBy,
+        });
+      }
       recordTaskSpawnRequested(input.taskId, {
         spawnRequestId,
         provider: input.provider,
@@ -502,16 +596,6 @@ export async function spawnAgent(input: SpawnAgentInput, ctx: AuthContext): Prom
   const waitMs = Math.min(input.waitForRegistrationMs ?? 0, 30_000);
   const agentId = waitMs > 0 ? await waitForSpawnedAgent(spawnRequestId, waitMs) : null;
 
-  // #838 — once the child's id is known (waitForRegistrationMs > 0), stamp it as the Task owner
-  // via the #834 attribution API. Fire-and-forget spawns resolve the id later; #831 closes that
-  // gap by reading the spawn_requested event above. Best-effort, never fails the spawn.
-  if (input.taskId !== undefined && agentId) {
-    try {
-      assignTaskAgent(input.taskId, agentId, "worker", requestedBy);
-    } catch (err) {
-      console.warn(`task ${input.taskId} owner attribution skipped: ${errMessage(err)}`);
-    }
-  }
   return {
     ok: true,
     spawnRequestId,

package/src/services/task-entity.ts

@@ -11,6 +11,7 @@ import {
   listDeliverableTasks,
   listTaskEvents,
   recordGate,
+  recordTaskDispatchDecision,
   removeTaskDependency,
   removeTaskRef,
   setTaskStage,
@@ -19,6 +20,7 @@ import {
   type AddTaskRefInput,
   type CreateDeliverableTaskInput,
   type ListDeliverableTasksFilter,
+  type RecordTaskDispatchDecisionInput,
   type RecordGateInput,
   type RemoveTaskRefInput,
   type SetTaskStageInput,
@@ -144,6 +146,12 @@ export function assignTaskEntityAgent(id: number, agentId: string, role?: string
   return detail;
 }
 
+export function recordTaskEntityDispatchDecision(id: number, input: RecordTaskDispatchDecisionInput): TaskDetail {
+  const detail = recordTaskDispatchDecision(id, input);
+  emitTaskChanged(detail, "task.dispatch");
+  return detail;
+}
+
 export function taskEntityHistory(id: number): TaskEvent[] {
   return listTaskEvents(id);
 }

package/src/spawn-command.ts

@@ -100,6 +100,8 @@ interface BuildSpawnCommandOptions {
   landStrategy?: WorkspaceLandingPolicy;
   autoMerge?: WorkspaceAutoMergePolicy;
   reviewer?: string;
+  /** #838 — durable Task this worker was spawned to execute. */
+  taskId?: number;
   /**
    * #413 — when true, the child registering with this spawnRequestId gets a pending reply
    * obligation back to its spawner, so the Stop hook refuses to let it idle until it delivers
@@ -160,6 +162,7 @@ export function buildSpawnCommand(opts: BuildSpawnCommandOptions): Record<string
     ...def(opts.landStrategy, "landStrategy"),
     ...def(opts.autoMerge, "autoMerge"),
     ...def(opts.reviewer, "reviewer"),
+    ...def(opts.taskId, "taskId"),
     ...def(opts.expectReply, "expectReply"),
     ...def(opts.headless, "headless"),
     ...def(opts.policyName, "policyName"),