agent-relay-server 0.107.0 → 0.109.0

package/src/db/task-memory.ts

@@ -0,0 +1,180 @@
+// #832 — Task-bound memory: task-local slice of the #815 scoped-knowledge hierarchy.
+//
+// This deliberately mirrors the self-resume continuation envelope primitive:
+// replaceable working state, append-only ruled-out ledger, append-only decisions.
+// When #815 lands, this module is the adapter from durable Task ids into the
+// session/task scope in that chain; do not grow a second memory system beside it.
+import { parseJson } from "../utils";
+import { getDb, ValidationError } from "./connection.ts";
+import { getTaskDetail } from "./task-entity.ts";
+import { isContinuationDecisionEntry, isContinuationLedgerEntry } from "./continuations.ts";
+import type { ContinuationBudget, ContinuationDecisionEntry, ContinuationEnvelope, ContinuationLedgerEntry, TaskDetail } from "../types";
+
+interface TaskMemoryRow {
+  task_id: number;
+  objective: string;
+  generation: number;
+  ledger: string;
+  decisions: string;
+  working_state: string;
+  archive_refs: string;
+  budget: string;
+  created_at: number;
+  updated_at: number;
+}
+
+export type TaskMemoryEnvelope = ContinuationEnvelope & { taskId: number };
+
+export function getTaskMemoryEnvelope(taskId: number): TaskMemoryEnvelope | null {
+  const row = getDb().query("SELECT * FROM task_memories WHERE task_id = ?").get(taskId) as TaskMemoryRow | undefined;
+  return row ? rowToTaskMemoryEnvelope(row) : null;
+}
+
+export function readTaskMemoryEnvelope(taskId: number): TaskMemoryEnvelope {
+  const task = requireTask(taskId);
+  return getTaskMemoryEnvelope(taskId) ?? emptyTaskMemoryEnvelope(task, Date.now());
+}
+
+export function replaceTaskMemoryWorkingState(input: { taskId: number; workingState: string; now?: number }): TaskMemoryEnvelope {
+  const existing = ensureTaskMemoryEnvelope(input.taskId, input.now);
+  const workingState = input.workingState.trim();
+  if (!workingState) throw new ValidationError("workingState required");
+  const now = input.now ?? Date.now();
+  getDb().query(`
+    UPDATE task_memories
+    SET generation = ?, working_state = ?, budget = ?, updated_at = ?
+    WHERE task_id = ?
+  `).run(existing.generation + 1, workingState, JSON.stringify(nextBudget(existing, now)), now, input.taskId);
+  return readTaskMemoryEnvelope(input.taskId);
+}
+
+export function appendTaskMemoryRuledOut(input: {
+  taskId: number;
+  entries: Array<string | { ruledOut: string; why?: string }>;
+  now?: number;
+}): TaskMemoryEnvelope {
+  const existing = ensureTaskMemoryEnvelope(input.taskId, input.now);
+  if (!Array.isArray(input.entries) || input.entries.length === 0) throw new ValidationError("ruledOut must contain at least one entry");
+  const now = input.now ?? Date.now();
+  const generation = existing.generation + 1;
+  const entries = input.entries.map((entry, index) => ruledOutEntry(entry, index, generation, now));
+  getDb().query(`
+    UPDATE task_memories
+    SET generation = ?, ledger = ?, budget = ?, updated_at = ?
+    WHERE task_id = ?
+  `).run(generation, JSON.stringify([...existing.ledger, ...entries]), JSON.stringify(nextBudget(existing, now)), now, input.taskId);
+  return readTaskMemoryEnvelope(input.taskId);
+}
+
+export function appendTaskMemoryDecision(input: {
+  taskId: number;
+  decision: string;
+  rationale?: string;
+  by?: string;
+  now?: number;
+}): TaskMemoryEnvelope {
+  const existing = ensureTaskMemoryEnvelope(input.taskId, input.now);
+  const decision = input.decision.trim();
+  if (!decision) throw new ValidationError("decision required");
+  const rationale = input.rationale?.trim() ?? "";
+  const now = input.now ?? Date.now();
+  const entry: ContinuationDecisionEntry = {
+    gen: existing.generation + 1,
+    decision,
+    rationale,
+    ...(input.by?.trim() ? { by: input.by.trim() } : {}),
+    at: now,
+  };
+  getDb().query(`
+    UPDATE task_memories
+    SET generation = ?, decisions = ?, budget = ?, updated_at = ?
+    WHERE task_id = ?
+  `).run(entry.gen, JSON.stringify([...existing.decisions, entry]), JSON.stringify(nextBudget(existing, now)), now, input.taskId);
+  return readTaskMemoryEnvelope(input.taskId);
+}
+
+function ensureTaskMemoryEnvelope(taskId: number, now = Date.now()): TaskMemoryEnvelope {
+  const existing = getTaskMemoryEnvelope(taskId);
+  if (existing) return existing;
+  const task = requireTask(taskId);
+  const empty = emptyTaskMemoryEnvelope(task, now);
+  getDb().query(`
+    INSERT INTO task_memories (task_id, objective, generation, ledger, decisions, working_state, archive_refs, budget, created_at, updated_at)
+    VALUES (?, ?, 0, '[]', '[]', '', '[]', ?, ?, ?)
+  `).run(taskId, empty.objective, JSON.stringify(empty.budget), now, now);
+  return readTaskMemoryEnvelope(taskId);
+}
+
+function requireTask(taskId: number): TaskDetail {
+  const task = getTaskDetail(taskId);
+  if (!task) throw new ValidationError(`task ${taskId} not found or not a deliverable task`);
+  return task;
+}
+
+function emptyTaskMemoryEnvelope(task: TaskDetail, now: number): TaskMemoryEnvelope {
+  return {
+    taskId: task.id,
+    agentId: `task:${task.id}`,
+    objective: `Task #${task.id}: ${task.title}`,
+    generation: 0,
+    ledger: [],
+    decisions: [],
+    workingState: "",
+    archiveRefs: [],
+    budget: emptyBudget(),
+    createdAt: now,
+    updatedAt: now,
+  };
+}
+
+function rowToTaskMemoryEnvelope(row: TaskMemoryRow): TaskMemoryEnvelope {
+  return {
+    taskId: row.task_id,
+    agentId: `task:${row.task_id}`,
+    objective: row.objective,
+    generation: row.generation,
+    ledger: parseJson<ContinuationLedgerEntry[]>(row.ledger, []).filter(isContinuationLedgerEntry),
+    decisions: parseJson<ContinuationDecisionEntry[]>(row.decisions, []).filter(isContinuationDecisionEntry),
+    workingState: row.working_state,
+    archiveRefs: parseJson<string[]>(row.archive_refs, []).filter((value): value is string => typeof value === "string"),
+    budget: parseJson<ContinuationBudget>(row.budget, emptyBudget()),
+    createdAt: row.created_at,
+    updatedAt: row.updated_at,
+  };
+}
+
+function ruledOutEntry(
+  value: string | { ruledOut: string; why?: string },
+  index: number,
+  generation: number,
+  now: number,
+): ContinuationLedgerEntry {
+  if (typeof value !== "string" && (typeof value !== "object" || value === null || Array.isArray(value))) {
+    throw new ValidationError(`ruledOut[${index}] must be a string or object`);
+  }
+  const ruledOut = typeof value === "string" ? value.trim() : value.ruledOut?.trim();
+  if (!ruledOut) throw new ValidationError(`ruledOut[${index}] required`);
+  const why = typeof value === "string" ? "" : value.why?.trim() ?? "";
+  return { gen: generation, ruledOut, why, at: now };
+}
+
+function nextBudget(existing: TaskMemoryEnvelope, now: number): ContinuationBudget {
+  return {
+    ...existing.budget,
+    spent: {
+      ...existing.budget.spent,
+      generations: existing.generation + 1,
+      wallClockMs: Math.max(0, existing.budget.spent.wallClockMs) + Math.max(0, now - existing.updatedAt),
+    },
+  };
+}
+
+function emptyBudget(): ContinuationBudget {
+  return {
+    maxGenerations: 0,
+    maxWallClockMs: 0,
+    maxTokens: 0,
+    hardStopMultiplier: 1,
+    spent: { generations: 0, wallClockMs: 0, tokens: 0 },
+  };
+}

package/src/db/tasks.ts

@@ -19,7 +19,7 @@ import { messageTaskClosed } from "./claim-sql.ts";
 import { ClaimError, getDb } from "./connection.ts";
 import { rowToTask, rowToTaskEvent } from "./mappers.ts";
 import { claimMessageRow } from "./message-claims.ts";
-import { TASK_SELECT, insertTaskEvent } from "./task-core.ts";
+import { TASK_SELECT, insertTaskEvent, claimTaskWhere, DELIVERABLE_TASK_KIND } from "./task-core.ts";
 import { settleSingleTargetOnDemandTasks } from "./task-maintenance.ts";
 import { renderTemplate } from "../prompt-resolver";
 import type {
@@ -85,7 +85,7 @@ import type {
   WorkspaceStatus,
 } from "../types";
 
-export { TASK_SELECT, insertTaskEvent } from "./task-core.ts";
+export { TASK_SELECT, insertTaskEvent, claimTaskWhere, CLAIM_TASK_KIND, DELIVERABLE_TASK_KIND } from "./task-core.ts";
 
 export function findOpenTaskByDedupe(source: string, dedupeKey: string): Task | null {
   const row = getDb()
@@ -112,9 +112,16 @@ export function getTask(id: number): Task | null {
   return row ? rowToTask(row) : null;
 }
 
-export function listTasks(filter?: { status?: string; source?: string; target?: string; limit?: number }): Task[] {
+export function listTasks(filter?: { status?: string; source?: string; target?: string; kind?: "claim" | "deliverable" | "all"; limit?: number }): Task[] {
   const conditions: string[] = [];
   const params: any[] = [];
+  // Default to the claim lane so legacy queues/views (dashboard work queue, GET /api/tasks)
+  // never get polluted by durable deliverable Tasks (#834). Pass kind:'all' to span both.
+  const kind = filter?.kind ?? "claim";
+  if (kind !== "all") {
+    conditions.push("kind = ?");
+    params.push(kind);
+  }
   if (filter?.status) {
     conditions.push("status = ?");
     params.push(filter.status);
@@ -165,7 +172,7 @@ export function releaseExpiredClaims(now: number = Date.now()): { messageIds: nu
       .query(`SELECT id FROM messages WHERE ${releasableMessageClaim}`)
       .all(now) as any[];
     const taskRows = getDb()
-      .query(`${TASK_SELECT} WHERE claimed_by IS NOT NULL AND (claim_expires_at IS NULL OR claim_expires_at <= ?) AND status IN ('claimed', 'in_progress', 'blocked')`)
+      .query(`${TASK_SELECT} WHERE ${claimTaskWhere()} AND claimed_by IS NOT NULL AND (claim_expires_at IS NULL OR claim_expires_at <= ?) AND status IN ('claimed', 'in_progress', 'blocked')`)
       .all(now) as any[];
 
     if (messageRows.length > 0) {
@@ -176,7 +183,7 @@ export function releaseExpiredClaims(now: number = Date.now()): { messageIds: nu
 
     if (taskRows.length > 0) {
       getDb()
-        .query("UPDATE tasks SET status = 'open', claimed_by = NULL, claimed_at = NULL, claim_expires_at = NULL, updated_at = ? WHERE claimed_by IS NOT NULL AND (claim_expires_at IS NULL OR claim_expires_at <= ?) AND status IN ('claimed', 'in_progress', 'blocked')")
+        .query(`UPDATE tasks SET status = 'open', claimed_by = NULL, claimed_at = NULL, claim_expires_at = NULL, updated_at = ? WHERE ${claimTaskWhere()} AND claimed_by IS NOT NULL AND (claim_expires_at IS NULL OR claim_expires_at <= ?) AND status IN ('claimed', 'in_progress', 'blocked')`)
         .run(now, now);
 
       for (const row of taskRows) {
@@ -201,14 +208,14 @@ export function releaseExpiredClaims(now: number = Date.now()): { messageIds: nu
 export function orphanTasksForAgent(agentId: string, now: number = Date.now()): Task[] {
   return getDb().transaction(() => {
     const rows = getDb()
-      .query(`${TASK_SELECT} WHERE claimed_by = ? AND status IN ('claimed', 'in_progress')`)
+      .query(`${TASK_SELECT} WHERE ${claimTaskWhere()} AND claimed_by = ? AND status IN ('claimed', 'in_progress')`)
       .all(agentId) as any[];
     if (rows.length === 0) return [];
 
     getDb().query(`
       UPDATE tasks
       SET status = 'orphaned', updated_at = ?, last_seen_at = ?
-      WHERE claimed_by = ? AND status IN ('claimed', 'in_progress')
+      WHERE ${claimTaskWhere()} AND claimed_by = ? AND status IN ('claimed', 'in_progress')
     `).run(now, now, agentId);
 
     for (const row of rows) {
@@ -231,14 +238,14 @@ export function releaseOrphanedTasks(graceMs = 120_000, now: number = Date.now()
     const cutoff = now - graceMs;
     settleSingleTargetOnDemandTasks("status = 'orphaned' AND claimed_by IS NOT NULL AND updated_at <= ?", [cutoff], now, "orphan-grace-elapsed");
     const rows = getDb()
-      .query(`${TASK_SELECT} WHERE status = 'orphaned' AND claimed_by IS NOT NULL AND updated_at <= ?`)
+      .query(`${TASK_SELECT} WHERE ${claimTaskWhere()} AND status = 'orphaned' AND claimed_by IS NOT NULL AND updated_at <= ?`)
       .all(cutoff) as any[];
     if (rows.length === 0) return [];
 
     getDb().query(`
       UPDATE tasks
       SET status = 'open', claimed_by = NULL, claimed_at = NULL, claim_expires_at = NULL, updated_at = ?
-      WHERE status = 'orphaned' AND claimed_by IS NOT NULL AND updated_at <= ?
+      WHERE ${claimTaskWhere()} AND status = 'orphaned' AND claimed_by IS NOT NULL AND updated_at <= ?
     `).run(now, cutoff);
 
     for (const row of rows) {
@@ -265,6 +272,8 @@ export function claimTask(taskId: number, agentId: string, guard?: AgentSessionG
   if (agent.status === "offline") return { ok: false, error: "claiming agent is offline" };
   const task = getTask(taskId);
   if (!task) return { ok: false, error: "task not found" };
+  // Fence: deliverable Tasks are never claimable through the claim-lease lane (#834).
+  if (task.kind === DELIVERABLE_TASK_KIND) return { ok: false, error: "task is not claimable" };
   if (!["open", "blocked"].includes(task.status)) return { ok: false, error: `task is ${task.status}` };
 
   try {
@@ -273,7 +282,7 @@ export function claimTask(taskId: number, agentId: string, guard?: AgentSessionG
       const expiresAt = now + CLAIM_LEASE_MS;
       const result = getDb().query(`
         UPDATE tasks SET status = 'claimed', claimed_by = ?, claimed_at = ?, claim_expires_at = ?, updated_at = ?
-        WHERE id = ? AND status IN ('open', 'blocked')
+        WHERE id = ? AND ${claimTaskWhere()} AND status IN ('open', 'blocked')
       `).run(agentId, now, expiresAt, now, taskId);
       if (result.changes === 0) return { ok: false, error: "claim race — already claimed" };
       if (task.messageId) {
@@ -305,6 +314,7 @@ export function renewTaskClaim(taskId: number, agentId: string, guard?: AgentSes
   if (agent.status === "offline") return { ok: false, error: "claiming agent is offline" };
   const task = getTask(taskId);
   if (!task) return { ok: false, error: "task not found" };
+  if (task.kind === DELIVERABLE_TASK_KIND) return { ok: false, error: "task is not claimable" };
   if (task.claimedBy !== agentId) return { ok: false, error: task.claimedBy ? `claimed by ${task.claimedBy}` : "task is not claimed" };
   if (!["claimed", "in_progress", "blocked"].includes(task.status)) return { ok: false, error: `task is ${task.status}` };
 
@@ -320,6 +330,10 @@ export function renewTaskClaim(taskId: number, agentId: string, guard?: AgentSes
 export function updateTaskStatus(taskId: number, input: TaskStatusInput): { ok: boolean; error?: string; task?: Task; event?: TaskEvent } {
   const task = getTask(taskId);
   if (!task) return { ok: false, error: "task not found" };
+  // Fence: the claim-lane status updater writes `claimed_by`; deliverable Tasks must never
+  // be mutated here. They transition through setTaskStatus (src/db/task-entity.ts), which
+  // never touches claimed_by. (#834)
+  if (task.kind === DELIVERABLE_TASK_KIND) return { ok: false, error: "deliverable task: use the task-entity status API" };
   const now = Date.now();
   const agentId = input.agentId ?? task.claimedBy ?? null;
   if (agentId) {

package/src/issue-tracker/adapter.ts

@@ -5,6 +5,15 @@ export interface IssueTrackerStatus {
   title: string;
 }
 
+// #838 — the linked-issue spec read used by relay to hydrate a spawned Task agent's
+// first-turn context server-side ONCE (so the worker never burns its own context reading
+// the issue tracker). Extends the status read with the issue BODY (intent/spec/acceptance).
+export interface IssueTrackerIssueDetail {
+  status: IssueRefStatus;
+  title: string;
+  body: string;
+}
+
 export interface IssueTrackerCloseOptions {
   comment?: string;
   labels?: string[];
@@ -26,9 +35,15 @@ export interface IssueTrackerIssueSummary {
 export interface IssueTrackerAdapter {
   resolveLink(ref: IssueRef): string;
   getStatus(ref: IssueRef): Promise<IssueTrackerStatus>;
+  /** #838 — read the issue's full spec (title + body) for relay-side Task hydration. Optional:
+   * adapters that cannot fetch a body degrade gracefully (hydration falls back to title+url). */
+  getDetail?(ref: IssueRef): Promise<IssueTrackerIssueDetail>;
   listOpenSubIssues?(ref: IssueRef): Promise<IssueTrackerIssueSummary[]>;
   close(ref: IssueRef, options?: IssueTrackerCloseOptions): Promise<void>;
   reopen(ref: IssueRef, options?: IssueTrackerReopenOptions): Promise<void>;
   comment(ref: IssueRef, body: string): Promise<void>;
+  // List existing comment bodies on the issue. Used to RECONCILE a Task comment-through after
+  // a post-before-finalize crash (#833): match the relay marker rather than blindly re-post.
+  listComments?(ref: IssueRef): Promise<string[]>;
   applyLabels(ref: IssueRef, labels: string[]): Promise<void>;
 }

package/src/issue-tracker/github.ts

@@ -1,8 +1,10 @@
 import type { IssueRef, IssueRefStatus } from "../types";
-import type { IssueTrackerAdapter, IssueTrackerCloseOptions, IssueTrackerIssueSummary, IssueTrackerReopenOptions, IssueTrackerStatus } from "./adapter";
+import type { IssueTrackerAdapter, IssueTrackerCloseOptions, IssueTrackerIssueDetail, IssueTrackerIssueSummary, IssueTrackerReopenOptions, IssueTrackerStatus } from "./adapter";
 
 export const GITHUB_FIXED_LABEL = "fixed";
 const GITHUB_CREDENTIAL_REQUIREMENT = "GitHub issue tracker adapter requires gh authenticated with a token that has issues:write scope";
+// #838 — hard bound on the spawn-time issue read so hydration never stalls the spawn.
+const ISSUE_DETAIL_READ_TIMEOUT_MS = 10_000;
 
 type GitHubApiMethod = "GET" | "PATCH" | "POST";
 
@@ -10,6 +12,10 @@ export interface GitHubApiRequest {
   method: GitHubApiMethod;
   path: string;
   body?: Record<string, unknown>;
+  /** #838 — bound the spawned `gh` subprocess so a hung/slow call can't stall the caller
+   * (e.g. relay_spawn_agent hydration). On timeout the process is killed and the call throws,
+   * which the hydration path catches and degrades to partial "spec unavailable". */
+  timeoutMs?: number;
 }
 
 type GitHubApi = (request: GitHubApiRequest) => Promise<unknown>;
@@ -18,6 +24,7 @@ interface GitHubIssuePayload {
   state?: unknown;
   title?: unknown;
   html_url?: unknown;
+  body?: unknown;
 }
 
 interface GitHubSubIssueNode {
@@ -76,16 +83,20 @@ async function ghApi(request: GitHubApiRequest): Promise<unknown> {
   // auth backed by a GitHub token with `issues:write` scope.
   const args = ["gh", "api", "--method", request.method, request.path, "--header", "Accept: application/vnd.github+json"];
   appendBodyArgs(args, request.body);
+  // `Bun.spawnSync` blocks the event loop synchronously, so a JS-level timeout race can't preempt
+  // a hung `gh`; the subprocess `timeout` (kills with SIGTERM on expiry) is the only effective bound.
   const proc = Bun.spawnSync(args, {
     stdin: "ignore",
     stdout: "pipe",
     stderr: "pipe",
     env: process.env,
+    ...(request.timeoutMs ? { timeout: request.timeoutMs } : {}),
   });
   const stdout = textFromBytes(proc.stdout).trim();
   if (proc.exitCode !== 0) {
     const stderr = textFromBytes(proc.stderr).trim();
-    throw new Error(`${GITHUB_CREDENTIAL_REQUIREMENT}; gh api failed: ${stderr || stdout || `exit ${proc.exitCode}`}`);
+    const timedOut = request.timeoutMs && (proc.signalCode === "SIGTERM" || proc.exitCode === null);
+    throw new Error(`${GITHUB_CREDENTIAL_REQUIREMENT}; gh api ${timedOut ? `timed out after ${request.timeoutMs}ms` : "failed"}: ${stderr || stdout || `exit ${proc.exitCode}`}`);
   }
   if (!stdout) return {};
   try {
@@ -152,6 +163,19 @@ class GitHubIssueTrackerAdapter implements IssueTrackerAdapter {
     return { status: statusFromState(issue.state), title: titleFromIssue(issue) };
   }
 
+  // #838 — same GET as getStatus, but also surfaces the issue body (intent/spec/acceptance) so
+  // relay can hydrate a spawned Task agent server-side. ONE issue read at spawn time; the worker
+  // never touches the issue tracker itself. Bounded by a timeout so a hung `gh` degrades the
+  // hydration to partial "spec unavailable" rather than stalling relay_spawn_agent.
+  async getDetail(ref: IssueRef): Promise<IssueTrackerIssueDetail> {
+    const issue = await this.api({ method: "GET", path: githubIssuePath(ref), timeoutMs: ISSUE_DETAIL_READ_TIMEOUT_MS }) as GitHubIssuePayload;
+    return {
+      status: statusFromState(issue.state),
+      title: titleFromIssue(issue),
+      body: typeof issue.body === "string" ? issue.body.trim() : "",
+    };
+  }
+
   async listOpenSubIssues(ref: IssueRef): Promise<IssueTrackerIssueSummary[]> {
     assertGitHubIssueRef(ref);
     const [owner, repo] = ref.repo.split("/") as [string, string];
@@ -203,6 +227,20 @@ class GitHubIssueTrackerAdapter implements IssueTrackerAdapter {
     await this.api({ method: "POST", path: `${githubIssuePath(ref)}/comments`, body: { body: trimmed } });
   }
 
+  async listComments(ref: IssueRef): Promise<string[]> {
+    const out: string[] = [];
+    for (let page = 1; page <= 10; page++) {
+      const batch = await this.api({ method: "GET", path: `${githubIssuePath(ref)}/comments?per_page=100&page=${page}` });
+      if (!Array.isArray(batch) || batch.length === 0) break;
+      for (const node of batch) {
+        const body = node && typeof node === "object" ? (node as { body?: unknown }).body : undefined;
+        if (typeof body === "string") out.push(body);
+      }
+      if (batch.length < 100) break;
+    }
+    return out;
+  }
+
   async applyLabels(ref: IssueRef, labels: string[]): Promise<void> {
     const cleaned = uniqueLabels(labels);
     if (cleaned.length === 0) return;

package/src/issue-tracker/index.ts

@@ -1,6 +1,7 @@
 export type {
   IssueTrackerAdapter,
   IssueTrackerCloseOptions,
+  IssueTrackerIssueDetail,
   IssueTrackerIssueSummary,
   IssueTrackerReopenOptions,
   IssueTrackerStatus,

package/src/mcp/index.ts

@@ -5,6 +5,11 @@ import { spawnCapablePrimer } from "../spawn-targets";
 import { McpAuthError, McpNotFoundError } from "../mcp-errors";
 import { createActivityEvent, ValidationError } from "../db";
 import { PLAN_TOOLS, relayPlanTool } from "../mcp-plan-tools";
+import { TASK_TOOLS, relayTaskTool } from "../mcp-task-tools";
+import { TASK_MEMORY_TOOLS, relayTaskMemoryTool } from "../mcp-task-memory-tools";
+import { DISPATCH_TOOLS, relayDispatchTool } from "../mcp-dispatch-tools";
+import { TASK_WEAVE_TOOLS, relayTaskWeaveTool } from "../mcp-task-weave-tools";
+import { RELEASE_TOOLS, relayReleaseTool } from "../mcp-release-tools";
 import { TEAM_TOOLS, relayTeamTool } from "../mcp-team-tools";
 import { BLACKBOARD_TOOLS, relayBlackboardTool } from "../mcp-blackboard-tools";
 import { PROJECT_TOOLS, relayProjectTool } from "../mcp-project-tools"; import { MEMORY_TOOLS, relayMemoryTool } from "../mcp-memory-tools"; import { ISSUE_REF_TOOLS, relayIssueRefTool } from "../mcp-issue-ref-tools"; import { ISSUE_ASSOCIATION_TOOLS, relayIssueAssociationTool } from "../mcp-issue-association-tools"; import { ISSUE_ACTIVITY_TOOLS, relayIssueActivityTool } from "../mcp-issue-activity-tools"; import { ISSUE_LIFECYCLE_TOOLS, relayIssueLifecycleTool } from "../mcp-issue-lifecycle-tools";
@@ -32,7 +37,7 @@ const TOOLS: ToolDefinition[] = [
   AGENT_ACTION_TOOL,
   ...WORKSPACE_TOOLS,
   ...MERGE_TOOLS, ...TEAM_TOOLS,
-  ...PLAN_TOOLS, ...ISSUE_REF_TOOLS, ...ISSUE_ASSOCIATION_TOOLS, ...ISSUE_ACTIVITY_TOOLS, ...ISSUE_LIFECYCLE_TOOLS,
+  ...PLAN_TOOLS, ...TASK_TOOLS, ...TASK_MEMORY_TOOLS, ...DISPATCH_TOOLS, ...TASK_WEAVE_TOOLS, ...RELEASE_TOOLS, ...ISSUE_REF_TOOLS, ...ISSUE_ASSOCIATION_TOOLS, ...ISSUE_ACTIVITY_TOOLS, ...ISSUE_LIFECYCLE_TOOLS,
   ...BLACKBOARD_TOOLS,
   ...PROJECT_TOOLS,
   ...MEMORY_TOOLS,
@@ -50,6 +55,7 @@ export const RELAY_TOOL_GROUPS: Record<string, readonly string[]> = {
   workspace: ["relay_workspace_status", "relay_workspace_ready", "relay_workspace_deps", "relay_workspace_list", "relay_workspace_claim", "relay_workspace_release", "relay_workspace_land", "relay_merge_pause", "relay_merge_pauses", "relay_merge_renew", "relay_merge_resume"],
   "spawn-lifecycle": ["relay_spawn_agent", "relay_spawn_targets", "relay_my_agents", "relay_shutdown_agent", "relay_agent_action", "relay_agent_status", "relay_agent_crash_report", "relay_schedule_timer", "relay_list_timers", "relay_cancel_timer"],
   plans: ["relay_plan_create", "relay_plan_add_node", "relay_plan_update_node", "relay_plan_add_edge", "relay_plan_remove_node", "relay_plan_remove_edge", "relay_plan_delete", "relay_plan_get"],
+  tasks: ["relay_task_create", "relay_task_get", "relay_task_list", "relay_task_update", "relay_task_set_status", "relay_task_set_stage", "relay_task_record_gate", "relay_task_add_dependency", "relay_task_remove_dependency", "relay_task_add_ref", "relay_task_remove_ref", "relay_task_assign_agent", "relay_task_history", "relay_task_memory_read", "relay_task_memory_replace_working_state", "relay_task_memory_append_ruled_out", "relay_task_memory_append_decision", "relay_task_dispatch", "relay_task_comment", "relay_task_close_bridge", "relay_release_readiness"],
   teams: ["relay_team_get", "relay_team_set_brief", "relay_team_claim", "relay_team_dissolve"],
   blackboard: ["relay_blackboard_write", "relay_blackboard_get", "relay_blackboard_read", "relay_blackboard_search", "relay_blackboard_retract"],
   project: ["relay_project_list", "relay_project_get", "relay_project_add_root", "relay_project_write_entry", "relay_project_read", "relay_project_search", "relay_project_retract", "relay_project_add_edge", "relay_project_remove_edge", "relay_project_promote_entry", "relay_project_ingest_claudemd"],
@@ -167,6 +173,11 @@ async function callTool(auth: McpAuthContext, params: unknown): Promise<Record<s
     else if (name === "relay_workspace_land") result = relayWorkspaceMutation(auth, "merge", args);
     else if (name.startsWith("relay_merge_")) result = relayMergeTool(auth, name, args); else if (name.startsWith("relay_team_")) result = await relayTeamTool(auth, name, args);
     else if (name.startsWith("relay_plan_")) result = relayPlanTool(auth, name, args);
+    else if (name.startsWith("relay_task_memory_")) result = relayTaskMemoryTool(auth, name, args);
+    else if (name === "relay_task_dispatch") result = relayDispatchTool(auth, name, args);
+    else if (name === "relay_task_comment" || name === "relay_task_close_bridge") result = await relayTaskWeaveTool(auth, name, args);
+    else if (name === "relay_release_readiness") result = relayReleaseTool(name, args);
+    else if (name.startsWith("relay_task_")) result = relayTaskTool(auth, name, args);
     else if (name.startsWith("relay_blackboard_")) result = relayBlackboardTool(auth, name, args);
     else if (name.startsWith("relay_project_")) result = relayProjectTool(auth, name, args); else if (name.startsWith("relay_memory_")) result = relayMemoryTool(auth, name, args); else if (name.startsWith("relay_issue_ref_")) result = relayIssueRefTool(auth, name, args); else if (name.startsWith("relay_issue_association_")) result = relayIssueAssociationTool(auth, name, args); else if (name.startsWith("relay_issue_activity_")) result = relayIssueActivityTool(auth, name, args); else if (name.startsWith("relay_issue_lifecycle_")) result = await relayIssueLifecycleTool(auth, name, args);
     else if (name === "relay_subscribe" || name === "relay_unsubscribe" || name === "relay_list_subscriptions" || name === "relay_why_notified" || name === "relay_notification_preview") result = relayNotificationSubscriptionTool(auth, name, args);

package/src/mcp/tools-spawn.ts

@@ -37,6 +37,8 @@ export const SPAWN_TOOLS: ToolDefinition[] = [
         effort: { type: "string", enum: VALID_EFFORTS },
         approvalMode: { type: "string", enum: APPROVAL_MODES, description: "Permission posture for the worker. Defaults to YOUR OWN approval mode when omitted (a headless `guarded` worker wedges on the first approval prompt), so a coordinator running `open` spawns workers that can act autonomously. Pass an explicit value to narrow a child (e.g. `read-only` reviewer)." },
         prompt: { type: "string", description: "Initial task/message delivered to the agent on launch — spawn and hand it its first instruction in one call (no separate follow-up message needed)." },
+        taskId: { type: "integer", minimum: 1, description: "#838 — spawn the worker bound to a durable Task. Relay hydrates the worker's FIRST-TURN context FROM the Task (intent + linked-issue spec/acceptance + recorded decisions + history + attribution), resolved server-side ONCE, so you do NOT hand-write a long brief and the worker does NOT read the issue tracker. Records the spawn on the Task for attribution. Pair with `steer` for the one-line actionable instruction. When model/effort are omitted, relay MAY resolve them from the Task's dispatch work-shape." },
+        steer: { type: "string", description: "#838 — the latest one-line steer: the actionable instruction layered over the hydrated Task context (used with `taskId`). Overrides the Task's stored latest steer for this spawn." },
         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 },
@@ -143,6 +145,8 @@ export async function relaySpawnAgent(auth: McpAuthContext, args: Record<string,
     policyName: optionalString(args.policyName, "policyName", 120),
     profile: optionalString(args.profile, "profile", 120),
     prompt: optionalString(args.prompt, "prompt", 16_000),
+    taskId: optionalPositiveInt(args.taskId, "taskId"),
+    steer: optionalString(args.steer, "steer", 16_000),
     expectReply: typeof args.expectReply === "boolean" ? args.expectReply : undefined,
     systemPromptAppend: optionalString(args.systemPromptAppend, "systemPromptAppend", 64_000),
     projectInstructions: parseProjectInstructions(args.projectInstructions, (m) => new ValidationError(m)),