agent-relay-server 0.107.0 → 0.108.0

package/src/mcp-dispatch-tools.ts

@@ -0,0 +1,164 @@
+// #839 — MCP surface for the declarative task dispatcher.
+//
+// `relay_task_dispatch` is the EXPLICIT dispatch entrypoint (the seam the issue asks for):
+// the coordinator declares a Task's work-shape and relay returns a concrete spawn
+// (provider/model/effort) plus the rationale behind it. It does NOT spawn — that stays
+// with the coordinator / #838 (spawn-with-task) — so wiring it can never perturb the live
+// spawn path. When the policy's auto-review threshold is met it also creates the dependent
+// review Task via the #834 dependency API (opt out with createReview:false).
+import { McpNotFoundError } from "./mcp-errors";
+import { ValidationError } from "./db";
+import { authContextFromMcp } from "./services/auth-context";
+import { addTaskEntityDependency, createTaskEntity, getTaskEntity } from "./services/task-entity";
+import { dispatchTask, type DispatchPin } from "./task-dispatcher";
+import { cleanString } from "./validation";
+import {
+  isRecord,
+  isSpawnProvider,
+  SPAWN_PROVIDERS,
+  TASK_DISPATCH_COMPLEXITIES,
+  TASK_DISPATCH_CRITICALITIES,
+  TASK_DISPATCH_FOOTPRINTS,
+  TASK_DISPATCH_TYPES,
+  type TaskDispatch,
+} from "./types";
+
+const DISPATCH_SHAPE_SCHEMA = {
+  type: "object",
+  properties: {
+    complexity: { type: "string", enum: TASK_DISPATCH_COMPLEXITIES },
+    type: { type: "string", enum: TASK_DISPATCH_TYPES },
+    contextFootprint: { type: "string", enum: TASK_DISPATCH_FOOTPRINTS },
+    criticality: { type: "string", enum: TASK_DISPATCH_CRITICALITIES },
+  },
+  additionalProperties: false,
+} as const;
+
+const PIN_SCHEMA = {
+  type: "object",
+  description: "Explicit per-case override; any field set wins over the policy-derived target.",
+  properties: {
+    provider: { type: "string", enum: SPAWN_PROVIDERS },
+    model: { type: "string" },
+    effort: { type: "string" },
+  },
+  additionalProperties: false,
+} as const;
+
+const TASK_ID_PROP = { oneOf: [{ type: "integer", minimum: 1 }, { type: "string" }] } as const;
+
+export const DISPATCH_TOOLS = [
+  {
+    name: "relay_task_dispatch",
+    description:
+      "Map a Task's work-shape ({complexity,type,contextFootprint,criticality}) + live quota/bands onto a concrete spawn (provider/model/effort) with a rationale. Reads a Task's dispatch field (taskId) and/or an inline dispatch override; overridable by an explicit model/provider pin. Returns the decision — it does NOT spawn (that's the coordinator / #838). When the policy's auto-review threshold is met it creates a dependent review Task (opt out with createReview:false).",
+    // Plans a dispatch (read) and may create a dependent review Task (write).
+    requiredScopes: ["task:read", "task:write"],
+    inputSchema: {
+      type: "object",
+      properties: {
+        taskId: TASK_ID_PROP,
+        dispatch: DISPATCH_SHAPE_SCHEMA,
+        pin: PIN_SCHEMA,
+        createReview: { type: "boolean", description: "When a taskId is given and the auto-review threshold is met, create the dependent review Task. Default true." },
+      },
+      additionalProperties: false,
+    },
+  },
+] satisfies Array<{ name: string; description: string; requiredScopes: string[]; inputSchema: Record<string, unknown> }>;
+
+type McpAuthLike = Parameters<typeof authContextFromMcp>[0];
+
+function taskIdArg(value: unknown): number {
+  const n = typeof value === "string" ? Number(value) : value;
+  if (typeof n !== "number" || !Number.isSafeInteger(n) || n < 1) throw new ValidationError("taskId must be a positive integer");
+  return n;
+}
+
+function pinArg(value: unknown): DispatchPin {
+  if (value === undefined || value === null) return {};
+  if (!isRecord(value)) throw new ValidationError("pin must be an object");
+  const pin: DispatchPin = {};
+  if (value.provider !== undefined) {
+    const provider = cleanString(value.provider, "pin.provider", { max: 80 });
+    if (provider) {
+      if (!isSpawnProvider(provider)) throw new ValidationError(`pin.provider must be one of: ${SPAWN_PROVIDERS.join(", ")}`);
+      pin.provider = provider;
+    }
+  }
+  const model = cleanString(value.model, "pin.model", { max: 200 });
+  if (model) pin.model = model;
+  const effort = cleanString(value.effort, "pin.effort", { max: 80 });
+  if (effort) pin.effort = effort;
+  return pin;
+}
+
+function dispatchShapeArg(value: unknown): TaskDispatch | undefined {
+  if (value === undefined || value === null) return undefined;
+  if (!isRecord(value)) throw new ValidationError("dispatch must be an object");
+  return value as TaskDispatch;
+}
+
+// The first dependent Task of the build that is itself a review (dispatch.type='review'), if any.
+// Makes auto-review creation idempotent across repeated dispatches of the same Task.
+function findExistingReviewDependent(dependentIds: number[]): number | undefined {
+  for (const id of dependentIds) {
+    if (getTaskEntity(id)?.dispatch?.type === "review") return id;
+  }
+  return undefined;
+}
+
+export function relayDispatchTool(auth: McpAuthLike, name: string, args: Record<string, unknown>): Record<string, unknown> {
+  const actor = authContextFromMcp(auth).actor.id;
+  if (!isRecord(args)) throw new ValidationError("arguments must be an object");
+  if (name !== "relay_task_dispatch") throw new ValidationError(`unknown tool: ${name}`);
+
+  const hasTaskId = args.taskId !== undefined && args.taskId !== null;
+  const taskId = hasTaskId ? taskIdArg(args.taskId) : undefined;
+  const inlineShape = dispatchShapeArg(args.dispatch);
+
+  let parentTitle: string | undefined;
+  let parentTeamId: string | undefined;
+  let parentDependents: number[] = [];
+  let shape = inlineShape;
+  if (taskId !== undefined) {
+    const task = getTaskEntity(taskId);
+    if (!task) throw new McpNotFoundError("task not found");
+    parentTitle = task.title;
+    parentTeamId = task.teamId;
+    parentDependents = task.dependents;
+    // Inline dispatch (if supplied) overrides the stored work-shape for this call.
+    shape = inlineShape ?? task.dispatch;
+  }
+  if (!shape && !inlineShape) shape = {};
+
+  const decision = dispatchTask(shape, pinArg(args.pin));
+
+  let reviewTaskId: number | undefined;
+  const createReview = args.createReview !== false; // default true
+  if (decision.review && createReview && taskId !== undefined) {
+    // Idempotent: if this build Task already has a review dependent, reuse it rather than
+    // spawning a duplicate on every re-dispatch.
+    const existing = findExistingReviewDependent(parentDependents);
+    if (existing !== undefined) {
+      reviewTaskId = existing;
+    } else {
+      const review = createTaskEntity({
+        title: `Review: ${parentTitle ?? `task #${taskId}`}`,
+        intent: `Adversarial review of task #${taskId}${parentTitle ? ` — ${parentTitle}` : ""}. Triggered: ${decision.review.reason}.`,
+        dispatch: decision.review.dispatch,
+        createdBy: actor,
+        ...(parentTeamId ? { teamId: parentTeamId } : {}),
+      });
+      // The review Task depends on the build Task (build must complete first).
+      addTaskEntityDependency(review.id, taskId, actor);
+      reviewTaskId = review.id;
+    }
+  }
+
+  return {
+    ...(taskId !== undefined ? { taskId } : {}),
+    decision: decision as unknown as Record<string, unknown>,
+    ...(reviewTaskId !== undefined ? { reviewTaskId } : {}),
+  };
+}

package/src/mcp-notification-subscription-tools.ts

@@ -16,11 +16,14 @@ import {
 } from "./db/notification-subscriptions";
 import { ValidationError } from "./db";
 import { McpAuthError, McpNotFoundError } from "./mcp-errors";
-import { authContextFromMcp } from "./services/auth-context";
+import { authContextFromMcp, type AuthContext } from "./services/auth-context";
+import { getTaskEntity } from "./services/task-entity";
 import { cleanString } from "./validation";
 import { NOTIFICATION_TYPES, type NotificationScope, type NotificationType } from "./notification-types";
 import { previewNotificationRouting, whyNotified } from "./notification-router";
 
+const TASK_NOTIFICATION_TYPES = ["task.created", "task.started", "task.blocked", "task.needs_decision", "task.landed", "task.closed"] as const satisfies readonly NotificationType[];
+
 export const NOTIFICATION_SUBSCRIPTION_TOOLS = [
   {
     name: "relay_subscribe",
@@ -32,6 +35,7 @@ export const NOTIFICATION_SUBSCRIPTION_TOOLS = [
         type: { type: "string", enum: NOTIFICATION_SUBSCRIPTION_TYPES },
         mode: { type: "string", enum: NOTIFICATION_SUBSCRIPTION_MODES, description: "Default opt_in. mute and opt_out suppress matching default deliveries." },
         scope: { type: "object", description: "Optional partial notification scope match, such as { teamId } or { repoRoot }." },
+        taskId: { type: "integer", minimum: 1, description: "Subscribe to semantic transitions for one durable Task." },
         streams: { type: "array", items: { type: "string", enum: CHILD_STREAMS }, description: "Child streams to opt into. responses is always on and is not persisted." },
         childAgentId: { type: "string", description: "Limit child stream subscriptions to one spawned child." },
         teamId: { type: "string", description: "Limit child stream subscriptions to children on a team." },
@@ -51,6 +55,7 @@ export const NOTIFICATION_SUBSCRIPTION_TOOLS = [
         type: { type: "string", enum: NOTIFICATION_SUBSCRIPTION_TYPES },
         mode: { type: "string", enum: NOTIFICATION_SUBSCRIPTION_MODES },
         scope: { type: "object" },
+        taskId: { type: "integer", minimum: 1 },
         streams: { type: "array", items: { type: "string", enum: CHILD_STREAMS } },
         childAgentId: { type: "string" },
         teamId: { type: "string" },
@@ -105,7 +110,8 @@ export function relayNotificationSubscriptionTool(
   name: string,
   args: Record<string, unknown>,
 ): Record<string, unknown> {
-  const agentId = callerAgentId(auth);
+  const ctx = authContextFromMcp(auth);
+  const agentId = callerAgentId(ctx);
   if (name === "relay_subscribe") {
     if (Object.prototype.hasOwnProperty.call(args, "streams")) {
       const scope = cleanChildStreamScope(args, agentId);
@@ -127,6 +133,17 @@ export function relayNotificationSubscriptionTool(
         },
       };
     }
+    if (Object.prototype.hasOwnProperty.call(args, "taskId")) {
+      const scope = taskScope(ctx, args.taskId, args.scope);
+      const mode = cleanModeOrDefault(args.mode);
+      const subscriptions = TASK_NOTIFICATION_TYPES.map((type) => addSubscription({
+        agentId,
+        type,
+        mode,
+        scopeMatch: scope,
+      }));
+      return { subscriptions, taskFilter: scope };
+    }
     if (args.type === undefined || args.type === null) throw new ValidationError("type or streams required");
     const subscription = addSubscription({
       agentId,
@@ -153,6 +170,22 @@ export function relayNotificationSubscriptionTool(
       }
       return { removed, responsesAlwaysOn: true };
     }
+    if (Object.prototype.hasOwnProperty.call(args, "taskId")) {
+      const scope = taskScope(ctx, args.taskId, args.scope);
+      const types = args.type === undefined || args.type === null
+        ? TASK_NOTIFICATION_TYPES
+        : [cleanSubscriptionType(args.type)];
+      let removed = 0;
+      for (const type of types) {
+        removed += removeSubscription({
+          agentId,
+          type,
+          mode: args.mode === undefined || args.mode === null ? undefined : cleanSubscriptionMode(args.mode),
+          scopeMatch: scope,
+        });
+      }
+      return { removed };
+    }
     const type = args.type === undefined || args.type === null ? undefined : cleanSubscriptionType(args.type);
     if (!id && !type) throw new ValidationError("id or type required");
     const removed = removeSubscription({
@@ -191,8 +224,7 @@ export function relayNotificationSubscriptionTool(
   throw new ValidationError(`unknown tool: ${name}`);
 }
 
-function callerAgentId(auth: McpAuthLike): string {
-  const ctx = authContextFromMcp(auth);
+function callerAgentId(ctx: AuthContext): string {
   if (!ctx.callerAgentId) throw new McpAuthError("notification subscriptions require a single caller agent identity");
   return ctx.callerAgentId;
 }
@@ -222,6 +254,32 @@ function cleanMessageId(value: unknown): number {
   return value;
 }
 
+function cleanPositiveInteger(value: unknown, field: string): number {
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value <= 0) {
+    throw new ValidationError(`${field} must be a positive integer`);
+  }
+  return value;
+}
+
+function taskScope(ctx: AuthContext, taskIdValue: unknown, explicitScope: unknown): Partial<NotificationScope> {
+  const taskId = cleanPositiveInteger(taskIdValue, "taskId");
+  assertTaskReadable(ctx, taskId);
+  const scope = cleanScope(explicitScope) ?? {};
+  if (scope.taskId && scope.taskId !== String(taskId)) throw new ValidationError("scope.taskId must match taskId");
+  return { ...scope, taskId: String(taskId) };
+}
+
+function assertTaskReadable(ctx: AuthContext, taskId: number): void {
+  if (!hasTaskReadScope(ctx)) throw new McpAuthError("task subscription requires task:read");
+  if (!getTaskEntity(taskId)) throw new McpNotFoundError("task not found");
+}
+
+function hasTaskReadScope(ctx: AuthContext): boolean {
+  const scopes = ctx.scopes ?? [];
+  if (scopes.includes("*") || scopes.includes("admin:*")) return true;
+  return scopes.includes("task:read") || scopes.includes("task:write") || scopes.includes("task:*");
+}
+
 function cleanChildStreams(value: unknown): ChildStream[] {
   if (!Array.isArray(value) || value.length === 0) throw new ValidationError("streams must be a non-empty array");
   return [...new Set(value.map(cleanChildStream))];

package/src/mcp-plan-tools.ts

@@ -4,6 +4,7 @@ import { authContextFromMcp } from "./services/auth-context";
 import {
   addPlanEdge,
   addPlanNode,
+  bindPlanNodeToTask,
   createPlan,
   deletePlanGraph,
   getPlanGraph,
@@ -14,6 +15,16 @@ import {
 import { isRecord } from "agent-relay-sdk";
 
 const PLAN_STATUSES = ["pending", "in-progress", "landed", "blocked"] as const;
+// #836: refs.taskId binds a plan node to a durable Task (the node then projects its
+// label/scopeBlurb/status from that Task — no double-bookkeeping); refs.issueId links a GitHub issue.
+const PLAN_NODE_REFS_SCHEMA = {
+  type: "object",
+  properties: {
+    taskId: { oneOf: [{ type: "string" }, { type: "integer", minimum: 1 }] },
+    issueId: { type: "string" },
+  },
+  additionalProperties: false,
+} as const;
 const PLAN_NODE_SCHEMA = {
   type: "object",
   properties: {
@@ -28,6 +39,7 @@ const PLAN_NODE_SCHEMA = {
     lane: { type: "string" },
     status: { type: "string", enum: PLAN_STATUSES },
     statusSource: { type: "string", enum: ["manual", "bound"] },
+    refs: PLAN_NODE_REFS_SCHEMA,
     blackboardRefs: { type: "array", items: { type: "string" } },
   },
   required: ["id", "label"],
@@ -76,6 +88,7 @@ export const PLAN_TOOLS = [
         lane: { oneOf: [{ type: "string" }, { type: "null" }] },
         status: { type: "string", enum: PLAN_STATUSES },
         statusSource: { type: "string", enum: ["manual", "bound"] },
+        refs: { oneOf: [PLAN_NODE_REFS_SCHEMA, { type: "null" }] },
         blackboardRefs: { oneOf: [{ type: "array", items: { type: "string" } }, { type: "null" }] },
       },
       required: ["planId", "nodeId"],
@@ -86,13 +99,19 @@ export const PLAN_TOOLS = [
   { name: "relay_plan_remove_node", description: "Remove a node and its connected edges from a plan DAG.", requiredScopes: ["plans:write"], inputSchema: { type: "object", properties: { planId: { type: "string" }, nodeId: { type: "string" } }, required: ["planId", "nodeId"], additionalProperties: false } },
   { name: "relay_plan_remove_edge", description: "Remove a dependency edge from a plan DAG.", requiredScopes: ["plans:write"], inputSchema: { type: "object", properties: { planId: { type: "string" }, from: { type: "string" }, to: { type: "string" } }, required: ["planId", "from", "to"], additionalProperties: false } },
   { name: "relay_plan_delete", description: "Delete a persisted plan DAG and archive its latest version.", requiredScopes: ["plans:write"], inputSchema: { type: "object", properties: { planId: { type: "string" } }, required: ["planId"], additionalProperties: false } },
+  {
+    name: "relay_plan_bind_node",
+    description: "Bind a plan node to a durable Task (#836). Pass taskId to link an existing deliverable Task, or omit it to mint one from the node's label/scopeBlurb/status. The bound node then projects its label/scopeBlurb/status from the Task — one object, no double-bookkeeping — and edges between bound nodes become task→task dependencies.",
+    requiredScopes: ["plans:write"],
+    inputSchema: { type: "object", properties: { planId: { type: "string" }, nodeId: { type: "string" }, taskId: { type: "integer", minimum: 1 } }, required: ["planId", "nodeId"], additionalProperties: false },
+  },
   {
     name: "relay_plan_get",
-    description: "Fetch a plan by planId, teamId, or by threadId/channel.",
+    description: "Fetch a plan by planId, teamId, or by threadId/channel. Bound nodes project from their Task. Pass view:'tasks' with a teamId to get the pure task-backed DAG synthesized from deliverable Tasks + task_dependencies (no plan row required).",
     requiredScopes: ["plans:read"],
     inputSchema: {
       type: "object",
-      properties: { planId: { type: "string" }, teamId: { type: "string" }, threadId: { oneOf: [{ type: "string" }, { type: "integer", minimum: 1 }] }, channel: { type: "string" } },
+      properties: { planId: { type: "string" }, teamId: { type: "string" }, threadId: { oneOf: [{ type: "string" }, { type: "integer", minimum: 1 }] }, channel: { type: "string" }, view: { type: "string", enum: ["plan", "tasks"] } },
       additionalProperties: false,
     },
   },
@@ -117,8 +136,16 @@ export function relayPlanTool(auth: McpAuthLike, name: string, args: Record<stri
   if (name === "relay_plan_remove_node") return removePlanNode(stringArg(args.planId, "planId"), stringArg(args.nodeId, "nodeId"), ctx) as unknown as Record<string, unknown>;
   if (name === "relay_plan_remove_edge") return removePlanEdge(stringArg(args.planId, "planId"), { from: args.from, to: args.to }, ctx) as unknown as Record<string, unknown>;
   if (name === "relay_plan_delete") return deletePlanGraph(stringArg(args.planId, "planId"), ctx);
+  if (name === "relay_plan_bind_node") {
+    return bindPlanNodeToTask(
+      stringArg(args.planId, "planId"),
+      stringArg(args.nodeId, "nodeId"),
+      { ...(typeof args.taskId === "number" ? { taskId: args.taskId } : {}) },
+      ctx,
+    ) as unknown as Record<string, unknown>;
+  }
   if (name === "relay_plan_get") {
-    const plan = getPlanGraph({ planId: args.planId, teamId: args.teamId, threadId: args.threadId, channel: args.channel });
+    const plan = getPlanGraph({ planId: args.planId, teamId: args.teamId, threadId: args.threadId, channel: args.channel, view: args.view });
     if (!plan) throw new McpNotFoundError("plan not found");
     return plan as unknown as Record<string, unknown>;
   }

package/src/mcp-release-tools.ts

@@ -0,0 +1,33 @@
+import { ValidationError } from "./db";
+import { releaseReadinessReport } from "./services/release-readiness";
+import { cleanString } from "./validation";
+import { isRecord } from "./types";
+
+export const RELEASE_TOOLS = [
+  {
+    name: "relay_release_readiness",
+    description: "Report landed-on-main deliverable Tasks that have not yet deployed/released, with linked issues, commit refs, and a conservative suggested release bump.",
+    requiredScopes: ["task:read"],
+    inputSchema: {
+      type: "object",
+      properties: {
+        teamId: { type: "string" },
+        limit: { type: "integer", minimum: 1, maximum: 500 },
+      },
+      additionalProperties: false,
+    },
+  },
+] satisfies Array<{ name: string; description: string; requiredScopes: string[]; inputSchema: Record<string, unknown> }>;
+
+export function relayReleaseTool(name: string, args: Record<string, unknown>): Record<string, unknown> {
+  if (name !== "relay_release_readiness") throw new ValidationError(`unknown tool: ${name}`);
+  if (!isRecord(args)) throw new ValidationError("arguments must be an object");
+  const limit = args.limit === undefined ? undefined : Number(args.limit);
+  if (limit !== undefined && (!Number.isSafeInteger(limit) || limit < 1 || limit > 500)) {
+    throw new ValidationError("limit must be between 1 and 500");
+  }
+  return releaseReadinessReport({
+    teamId: cleanString(args.teamId, "teamId", { max: 200 }),
+    limit,
+  }) as unknown as Record<string, unknown>;
+}

package/src/mcp-task-memory-tools.ts

@@ -0,0 +1,132 @@
+import { stringValue } from "agent-relay-sdk";
+import {
+  appendTaskMemoryDecision,
+  appendTaskMemoryRuledOut,
+  deliverableTaskIdsByOwnerAgent,
+  deliverableTaskIdsBySpawnRequestId,
+  getAgent,
+  readTaskMemoryEnvelope,
+  replaceTaskMemoryWorkingState,
+  ValidationError,
+} from "./db";
+import { McpAuthError } from "./mcp-errors";
+import { callerAgentId } from "./mcp/identity";
+import { optionalPositiveInt, stringField } from "./mcp/validation";
+import { renderContinuation } from "./self-resume";
+import type { McpAuthContext, ToolDefinition } from "./mcp/types";
+
+const TASK_ID_PROP = { type: "integer", minimum: 1, description: "Task id. Optional when the caller is bound to exactly one Task." } as const;
+
+export const TASK_MEMORY_TOOLS = [
+  {
+    name: "relay_task_memory_read",
+    description: "Read the task-bound continuation envelope for a durable Task. If taskId is omitted, resolves the caller's bound Task; if provided, the Task must still be bound to the caller unless the caller has an admin scope.",
+    requiredScopes: ["task:read"],
+    inputSchema: { type: "object", properties: { taskId: TASK_ID_PROP }, additionalProperties: false },
+  },
+  {
+    name: "relay_task_memory_replace_working_state",
+    description: "Replace the caller-bound Task's current working-state memory. This is replaceable; later writes overwrite it.",
+    requiredScopes: ["task:write"],
+    inputSchema: {
+      type: "object",
+      properties: { taskId: TASK_ID_PROP, workingState: { type: "string" } },
+      required: ["workingState"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "relay_task_memory_append_ruled_out",
+    description: "Append dead ends to the caller-bound Task's ruled-out ledger. Append-only: existing entries cannot be edited through this tool.",
+    requiredScopes: ["task:write"],
+    inputSchema: {
+      type: "object",
+      properties: {
+        taskId: TASK_ID_PROP,
+        ruledOut: {
+          type: "array",
+          items: {
+            oneOf: [
+              { type: "string" },
+              { type: "object", properties: { ruledOut: { type: "string" }, why: { type: "string" } }, required: ["ruledOut"], additionalProperties: false },
+            ],
+          },
+        },
+      },
+      required: ["ruledOut"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "relay_task_memory_append_decision",
+    description: "Append a decision to the caller-bound Task's decision log. Append-only: use this for durable choices a retry agent must inherit.",
+    requiredScopes: ["task:write"],
+    inputSchema: {
+      type: "object",
+      properties: { taskId: TASK_ID_PROP, decision: { type: "string" }, rationale: { type: "string" } },
+      required: ["decision"],
+      additionalProperties: false,
+    },
+  },
+] satisfies ToolDefinition[];
+
+export function relayTaskMemoryTool(auth: McpAuthContext, name: string, args: Record<string, unknown>): Record<string, unknown> {
+  const taskId = resolveTaskId(auth, args);
+  if (name === "relay_task_memory_read") return response(readTaskMemoryEnvelope(taskId));
+  if (name === "relay_task_memory_replace_working_state") {
+    return response(replaceTaskMemoryWorkingState({
+      taskId,
+      workingState: stringField(args.workingState, "workingState", { required: true, maxBytes: 1_000_000 }),
+    }));
+  }
+  if (name === "relay_task_memory_append_ruled_out") {
+    if (!Array.isArray(args.ruledOut)) throw new ValidationError("ruledOut must be an array");
+    return response(appendTaskMemoryRuledOut({ taskId, entries: args.ruledOut as Array<string | { ruledOut: string; why?: string }> }));
+  }
+  if (name === "relay_task_memory_append_decision") {
+    return response(appendTaskMemoryDecision({
+      taskId,
+      decision: stringField(args.decision, "decision", { required: true, maxBytes: 64_000 }),
+      rationale: stringField(args.rationale, "rationale", { maxBytes: 64_000 }),
+      by: callerAgentId(auth) ?? auth.actor,
+    }));
+  }
+  throw new ValidationError(`unknown tool: ${name}`);
+}
+
+function resolveTaskId(auth: McpAuthContext, args: Record<string, unknown>): number {
+  const explicit = optionalPositiveInt(args.taskId, "taskId");
+  const ids = boundTaskIds(auth);
+  if (explicit !== undefined) {
+    // Deliberate privileged escape hatch: admin/server tooling can inspect or repair any
+    // task memory row, but ordinary provider tokens must be bound to the explicit task id.
+    if (hasTaskMemoryAdminScope(auth) || ids.has(explicit)) return explicit;
+    throw new McpAuthError("taskId is not bound to the caller");
+  }
+  if (ids.size === 1) return [...ids][0]!;
+  if (ids.size === 0) throw new McpAuthError("caller is not bound to a Task");
+  throw new McpAuthError("caller is bound to multiple Tasks; pass taskId explicitly");
+}
+
+function boundTaskIds(auth: McpAuthContext): Set<number> {
+  const agentId = callerAgentId(auth);
+  if (!agentId) return new Set();
+  const ids = new Set<number>(deliverableTaskIdsByOwnerAgent(agentId));
+  const spawnRequestId = stringValue(getAgent(agentId)?.meta?.spawnRequestId);
+  if (spawnRequestId) {
+    for (const id of deliverableTaskIdsBySpawnRequestId(spawnRequestId)) ids.add(id);
+  }
+  return ids;
+}
+
+function hasTaskMemoryAdminScope(auth: McpAuthContext): boolean {
+  return auth.scopes.includes("*") || auth.scopes.includes("admin:*") || auth.scopes.includes("system:admin") || auth.scopes.includes("task:admin");
+}
+
+function response(envelope: ReturnType<typeof readTaskMemoryEnvelope>): Record<string, unknown> {
+  return {
+    taskId: envelope.taskId,
+    memory: envelope,
+    rendered: renderContinuation(envelope, { intro: `Task-bound memory — generation ${envelope.generation}.` }),
+  };
+}