agent-relay-server 0.107.0 → 0.109.0

package/src/services/task-context-hydration.ts

@@ -0,0 +1,361 @@
+// #838 — Spawn-with-task: relay-hydrated task agents (epic #830, the unlock).
+//
+// When a coordinator spawns a worker with `relay_spawn_agent({ taskId, steer? })`, relay
+// assembles the worker's FIRST-TURN context FROM the durable Task (#834) instead of the
+// coordinator hand-writing a 400-word brief. The worker boots already knowing: intent,
+// the linked-issue spec/acceptance (read server-side ONCE via the issue-ref → tracker path,
+// #833 seam), the recorded decisions/rules, the event history (who-did-what), the current
+// attribution, and the latest one-line steer. The worker does NOT use GitHub MCP to read the
+// issue or burn context reconstructing background — the Task (relay) does that here.
+//
+// Two halves, deliberately split so the renderer stays a PURE, unit-testable builder:
+//   - `renderTaskHydration(facets)` — pure: facets → continuation-style brief string.
+//   - `hydrateTaskContext(input)`   — assembler: reads the Task + events + linked-issue spec,
+//                                     classifies the ledger, then calls the pure renderer.
+// `projectTaskHydration(...)` then maps the brief onto the provider-contract spawn channel
+// through the SAME controlled systemPromptAppend / prompt path existing spawn injection uses.
+import { getManifest } from "agent-relay-providers";
+import { getTaskDetail, listTaskEvents, readTaskMemoryEnvelope, ValidationError } from "../db";
+import { getIssueRef } from "../db/issue-refs";
+import { resolveIssueTrackerAdapter, type IssueTrackerIssueDetail } from "../issue-tracker";
+import { renderTemplate } from "../prompt-resolver";
+import { renderContinuation } from "../self-resume";
+import type { SpawnProvider } from "agent-relay-sdk";
+import type { ContinuationDecisionEntry, ContinuationEnvelope, ContinuationLedgerEntry, TaskDetail, TaskEvent, TaskIssueLink } from "../types";
+import type { TaskMemoryEnvelope } from "../db/task-memory";
+
+/** A linked issue's spec resolved server-side (body may be absent if the fetch failed). */
+export interface ResolvedIssueSpec {
+  link: TaskIssueLink;
+  /** Trimmed issue body (intent/spec/acceptance) when the read succeeded. */
+  body?: string;
+  /** Set when the server-side read failed — the brief notes the spec is unavailable. */
+  unavailable?: boolean;
+}
+
+/** Everything the PURE renderer needs — already resolved, no I/O. */
+export interface TaskHydrationFacets {
+  taskId: number;
+  title: string;
+  status: string;
+  stage: string;
+  owner?: string;
+  intent: string;
+  doneWhen?: string;
+  issues: ResolvedIssueSpec[];
+  /** Decisions/rules: discussion + milestone write-throughs and steers (the narrative ledger). */
+  decisions: TaskEvent[];
+  /** Recent who-did-what event stream. */
+  history: TaskEvent[];
+  steer?: string;
+  /** #832 — task-bound memory hydration, using the self-resume continuation envelope renderer. */
+  memory?: string;
+}
+
+// How many trailing history events to surface so the brief stays bounded (the full ledger
+// lives on the Task; the worker can read it via relay_task tools if it needs more).
+const HISTORY_LIMIT = 20;
+// JS-level guard for ASYNC issue fetchers (a future REST adapter, a test stub). The production
+// `gh` path is synchronous and bounded by the subprocess timeout in the GitHub adapter (a JS race
+// can't preempt a blocking spawnSync); this race additionally bounds any async fetcher so a hung
+// read degrades to partial "spec unavailable" instead of stalling the spawn.
+const ISSUE_FETCH_TIMEOUT_MS = 12_000;
+// Issue body excerpt cap — keep the spec readable without dumping a novel into every spawn.
+const ISSUE_BODY_LIMIT = 8_000;
+const TASK_MEMORY_WORKING_STATE_LIMIT = 6_000;
+const TASK_MEMORY_ENTRY_LIMIT = 500;
+const TASK_MEMORY_LEDGER_LIMIT = 12;
+const TASK_MEMORY_DECISION_LIMIT = 12;
+const TASK_MEMORY_SECTION_LIMIT = 16_000;
+
+// Event types that represent a recorded decision/rule rather than raw execution telemetry:
+// the #833 write-through receipts (discussion + milestone) plus relay-recorded steers and the
+// blocker rationale captured when a Task is blocked.
+const DECISION_EVENT_TYPES = new Set(["comment.posted", "milestone.posted"]);
+function isDecisionEvent(event: TaskEvent): boolean {
+  if (DECISION_EVENT_TYPES.has(event.type)) return true;
+  // A `task.updated` that changed the steer (updateDeliverableTask stamps the changed columns
+  // in metadata.fields) is a recorded decision.
+  if (event.type === "task.updated") {
+    const fields = event.metadata?.fields;
+    if (Array.isArray(fields) && fields.includes("latest_steer")) return true;
+  }
+  // A blocked transition carries the human rationale for the block.
+  if (event.type === "status:blocked") return true;
+  return false;
+}
+
+function truncate(value: string, max: number): string {
+  if (value.length <= max) return value;
+  return `${value.slice(0, max)}\n… (truncated; read the full spec on the Task if needed)`;
+}
+
+// --- Prompt-injection containment (#838 review finding 2) ----------------------------------
+// Task intent, issue bodies, steers, titles and event text are UNTRUSTED (an issue body comes
+// from an external tracker; a steer/milestone is agent-authored). Placed raw in the brief — and
+// for Claude in the instruction-bearing systemPromptAppend — such text could impersonate a
+// trusted section header (`Latest steer:`, a fake report-up/profile block) or otherwise read as
+// instructions. We fence every untrusted free-text block between sentinels the content CANNOT
+// forge (any sentinel-looking substring is stripped first), and the template frames everything
+// between the sentinels as DATA, never instructions. Trusted framing (the "do NOT read the
+// tracker" directive, the section labels, the imperative to act on the steer) stays OUTSIDE.
+export const DATA_FENCE_OPEN = "⟦untrusted-task-data⟧";
+export const DATA_FENCE_CLOSE = "⟦∕untrusted-task-data⟧";
+const FENCE_SENTINEL_RE = /⟦∕?untrusted-task-data⟧/g;
+
+function stripSentinels(value: string): string {
+  return value.replace(FENCE_SENTINEL_RE, "");
+}
+
+/** Fence a multi-line untrusted block as DATA. Internal newlines are preserved (safe — the
+ * closing sentinel can't be forged), so issue-spec formatting survives. */
+function fence(value: string): string {
+  const cleaned = stripSentinels(value).trim();
+  return `${DATA_FENCE_OPEN}\n${cleaned || "(empty)"}\n${DATA_FENCE_CLOSE}`;
+}
+
+/** Sanitize untrusted text used INLINE (titles, agent ids, event lines): strip sentinels and
+ * collapse newlines so a multi-line value can't open a forged section header on a fresh line. */
+function inlineSafe(value: string): string {
+  return stripSentinels(value).replace(/[\r\n]+/g, " ⏎ ").trim();
+}
+
+function renderIssue(spec: ResolvedIssueSpec): string {
+  const { link } = spec;
+  const title = link.title ? ` — ${inlineSafe(link.title)}` : "";
+  const header = `- ${inlineSafe(link.repo)}#${inlineSafe(link.externalKey)}${title} (${inlineSafe(link.status)})\n  ${inlineSafe(link.url)}`;
+  if (spec.unavailable) return `${header}\n  (spec unavailable — server-side read failed; the Task intent above still applies)`;
+  if (!spec.body) return `${header}\n  (no issue body)`;
+  return `${header}\n${fence(truncate(spec.body, ISSUE_BODY_LIMIT))}`;
+}
+
+function renderEvent(event: TaskEvent): string {
+  const when = new Date(event.createdAt).toISOString();
+  const body = event.body?.trim();
+  // Event source/title/body are untrusted — render the whole line inline-safe so an injected
+  // milestone/steer body can't break onto a new line that mimics a trusted section header.
+  return `- ${when} · ${inlineSafe(event.source)} · ${inlineSafe(event.title)}${body ? `: ${inlineSafe(body)}` : ""}`;
+}
+
+/**
+ * PURE builder: assemble the continuation-style first-turn brief from already-resolved facets.
+ * Reuses the shared `renderTemplate` util (same DRY seam self-resume's `renderContinuation`
+ * uses) so the brief is overridable via the prompt-template store — no forked renderer.
+ */
+export function renderTaskHydration(facets: TaskHydrationFacets): string {
+  const issues = facets.issues.length ? facets.issues.map(renderIssue).join("\n") : "- none linked";
+  const decisions = facets.decisions.length ? facets.decisions.map(renderEvent).join("\n") : "- none recorded";
+  const history = facets.history.length ? facets.history.map(renderEvent).join("\n") : "- none yet";
+  const memory = facets.memory ? `\n${fence(facets.memory)}\n` : "";
+  return renderTemplate("task.hydration", {
+    taskId: String(facets.taskId),
+    title: inlineSafe(facets.title),
+    status: inlineSafe(facets.status),
+    stage: inlineSafe(facets.stage),
+    owner: facets.owner ? ` · owner: ${inlineSafe(facets.owner)}` : "",
+    intent: fence(facets.intent || "(no intent recorded)"),
+    doneWhen: fence(facets.doneWhen || "(no explicit acceptance recorded)"),
+    issues,
+    decisions,
+    history,
+    memory,
+    steer: fence(facets.steer || "(no steer provided — proceed toward the acceptance above)"),
+  }).trimEnd();
+}
+
+function hasTaskMemory(envelope: TaskMemoryEnvelope): boolean {
+  return Boolean(envelope.workingState.trim()) || envelope.ledger.length > 0 || envelope.decisions.length > 0;
+}
+
+function renderTaskMemory(envelope: TaskMemoryEnvelope): string | undefined {
+  if (!hasTaskMemory(envelope)) return undefined;
+  const rendered = renderContinuation(boundedTaskMemoryEnvelope(envelope), {
+    intro: `Task-bound memory — generation ${envelope.generation}. This is Relay-owned memory bound to Task #${envelope.taskId}; carry these dead ends, decisions, and working state forward.`,
+  });
+  return truncateTaskMemorySection(rendered, TASK_MEMORY_SECTION_LIMIT);
+}
+
+function boundedTaskMemoryEnvelope(envelope: TaskMemoryEnvelope): ContinuationEnvelope {
+  return {
+    ...envelope,
+    workingState: truncateTaskMemoryField(envelope.workingState, TASK_MEMORY_WORKING_STATE_LIMIT, "working state"),
+    ledger: boundedLedger(envelope.ledger),
+    decisions: boundedDecisions(envelope.decisions),
+  };
+}
+
+function boundedLedger(entries: ContinuationLedgerEntry[]): ContinuationLedgerEntry[] {
+  const kept = entries.slice(-TASK_MEMORY_LEDGER_LIMIT).map((entry) => ({
+    ...entry,
+    ruledOut: truncateTaskMemoryField(entry.ruledOut, TASK_MEMORY_ENTRY_LIMIT, "ruled-out entry"),
+    why: entry.why ? truncateTaskMemoryField(entry.why, TASK_MEMORY_ENTRY_LIMIT, "ruled-out rationale") : "",
+  }));
+  const omitted = entries.length - kept.length;
+  if (omitted <= 0) return kept;
+  const firstKept = kept[0] ?? entries[entries.length - 1]!;
+  return [{
+    gen: firstKept.gen,
+    at: firstKept.at,
+    ruledOut: `…${omitted} older ruled-out ${omitted === 1 ? "entry" : "entries"} omitted from hydration; use relay_task_memory_read for the full ledger`,
+    why: "hydration render cap",
+  }, ...kept];
+}
+
+function boundedDecisions(entries: ContinuationDecisionEntry[]): ContinuationDecisionEntry[] {
+  const kept = entries.slice(-TASK_MEMORY_DECISION_LIMIT).map((entry) => ({
+    ...entry,
+    decision: truncateTaskMemoryField(entry.decision, TASK_MEMORY_ENTRY_LIMIT, "decision"),
+    rationale: entry.rationale ? truncateTaskMemoryField(entry.rationale, TASK_MEMORY_ENTRY_LIMIT, "decision rationale") : "",
+  }));
+  const omitted = entries.length - kept.length;
+  if (omitted <= 0) return kept;
+  const firstKept = kept[0] ?? entries[entries.length - 1]!;
+  return [{
+    gen: firstKept.gen,
+    at: firstKept.at,
+    decision: `…${omitted} older ${omitted === 1 ? "decision" : "decisions"} omitted from hydration; use relay_task_memory_read for the full decision log`,
+    rationale: "hydration render cap",
+    by: "relay",
+  }, ...kept];
+}
+
+function truncateTaskMemoryField(value: string, max: number, label: string): string {
+  if (value.length <= max) return value;
+  return `${value.slice(0, max)}\n… (${label} truncated for task-memory hydration; use relay_task_memory_read for the full value)`;
+}
+
+function truncateTaskMemorySection(value: string, max: number): string {
+  if (value.length <= max) return value;
+  return `${value.slice(0, max)}\n… (task memory truncated for hydration; use relay_task_memory_read for the full Task memory)`;
+}
+
+/** Injectable issue-spec reader (defaults to the real issue-ref → tracker path) — for tests. */
+export type IssueDetailFetcher = (link: TaskIssueLink) => Promise<IssueTrackerIssueDetail | null>;
+
+async function defaultFetchIssueDetail(link: TaskIssueLink): Promise<IssueTrackerIssueDetail | null> {
+  const ref = getIssueRef(link.issueRefId);
+  if (!ref) return null;
+  const adapter = resolveIssueTrackerAdapter(ref);
+  if (!adapter.getDetail) return null;
+  return adapter.getDetail(ref);
+}
+
+/** Race an async issue read against a timeout so a hung async fetcher can't stall hydration. */
+function withFetchTimeout(p: Promise<IssueTrackerIssueDetail | null>, timeoutMs: number): Promise<IssueTrackerIssueDetail | null> {
+  return Promise.race([
+    p,
+    new Promise<IssueTrackerIssueDetail | null>((_, reject) => {
+      const t = setTimeout(() => reject(new Error(`issue read exceeded ${timeoutMs}ms`)), timeoutMs);
+      (t as { unref?: () => void }).unref?.();
+    }),
+  ]);
+}
+
+export interface HydrateTaskContextInput {
+  taskId: number;
+  /** Latest one-line steer; overrides the Task's stored `latestSteer` when present. */
+  steer?: string;
+  /** Override the server-side issue read (tests inject a stub; production uses the tracker). */
+  fetchIssueDetail?: IssueDetailFetcher;
+  /** Bound for the async issue read race (defaults to ISSUE_FETCH_TIMEOUT_MS; tests shrink it). */
+  fetchTimeoutMs?: number;
+}
+
+export interface TaskHydrationResult {
+  task: TaskDetail;
+  /** The rendered first-turn brief. */
+  context: string;
+  /** The effective steer (input override else the Task's stored steer). */
+  steer?: string;
+  facets: TaskHydrationFacets;
+}
+
+/**
+ * Assemble a spawned worker's first-turn brief FROM the durable Task. Reads the Task detail,
+ * its event ledger, and each linked issue's spec (server-side, once), classifies the ledger
+ * into decisions vs. history, and renders the brief. A linked-issue read that fails degrades
+ * gracefully (the brief notes the spec is unavailable) — it never fails the spawn.
+ */
+export async function hydrateTaskContext(input: HydrateTaskContextInput): Promise<TaskHydrationResult> {
+  const task = getTaskDetail(input.taskId);
+  if (!task) throw new ValidationError(`task ${input.taskId} not found or not a deliverable task`);
+
+  const events = listTaskEvents(input.taskId);
+  const decisions = events.filter(isDecisionEvent);
+  const history = events.slice(-HISTORY_LIMIT);
+
+  const fetcher = input.fetchIssueDetail ?? defaultFetchIssueDetail;
+  const timeoutMs = input.fetchTimeoutMs ?? ISSUE_FETCH_TIMEOUT_MS;
+  const issues: ResolvedIssueSpec[] = await Promise.all(
+    task.issues.map(async (link): Promise<ResolvedIssueSpec> => {
+      try {
+        const detail = await withFetchTimeout(Promise.resolve(fetcher(link)), timeoutMs);
+        if (!detail) return { link };
+        return { link, body: detail.body };
+      } catch {
+        // Read failed OR timed out (auth/network/rate limit/hang): degrade, never break the spawn.
+        return { link, unavailable: true };
+      }
+    }),
+  );
+
+  const steer = input.steer?.trim() || task.latestSteer;
+  const memory = renderTaskMemory(readTaskMemoryEnvelope(input.taskId));
+  const facets: TaskHydrationFacets = {
+    taskId: task.id,
+    title: task.title,
+    status: task.status,
+    stage: task.deliverableStage ?? "none",
+    ...(task.ownerAgentId ? { owner: task.ownerAgentId } : {}),
+    intent: task.intent ?? task.title,
+    ...(task.doneWhen ? { doneWhen: task.doneWhen } : {}),
+    issues,
+    decisions,
+    history,
+    ...(steer ? { steer } : {}),
+    // #815 seam: when scoped-knowledge chaining lands, this task-local read becomes the
+    // session/task scope in the global→tenant→host→project→role→team→session/task chain.
+    ...(memory ? { memory } : {}),
+  };
+
+  return { task, context: renderTaskHydration(facets), steer, facets };
+}
+
+export interface TaskHydrationProjection {
+  systemPromptAppend?: string;
+  prompt?: string;
+}
+
+function joinBlocks(...parts: Array<string | undefined>): string | undefined {
+  const joined = parts.map((p) => p?.trim()).filter((p): p is string => Boolean(p)).join("\n\n");
+  return joined || undefined;
+}
+
+/**
+ * PURE projection: map the hydration brief onto the provider-contract spawn channel.
+ * Caller-supplied systemPromptAppend/prompt are preserved (appended after the relay material).
+ * The steer used as a first-message kick is sentinel-stripped so it cannot forge the
+ * data fence in the (instruction-bearing) systemPromptAppend brief.
+ */
+export function projectTaskHydration(
+  provider: SpawnProvider | string,
+  context: string,
+  steer: string | undefined,
+  callerSystemPromptAppend: string | undefined,
+  callerPrompt: string | undefined,
+): TaskHydrationProjection {
+  if (taskHydrationChannel(provider) === "append-system-prompt") {
+    return {
+      systemPromptAppend: joinBlocks(context, callerSystemPromptAppend),
+      prompt: joinBlocks(steer ? stripSentinels(steer) : undefined, callerPrompt),
+    };
+  }
+  return {
+    systemPromptAppend: joinBlocks(callerSystemPromptAppend),
+    prompt: joinBlocks(context, callerPrompt),
+  };
+}
+
+function taskHydrationChannel(provider: SpawnProvider | string): "prompt" | "append-system-prompt" {
+  return getManifest(provider)?.launch?.taskHydration?.channel ?? "prompt";
+}

package/src/services/task-entity.ts

@@ -0,0 +1,149 @@
+// #834 — service facade for the durable Task entity. Transports (HTTP routes, MCP tools)
+// call THIS, not the db writers directly (transport-thinness, epic #342): the service owns
+// the db mutation + the SSE emission so the transport stays thin. The kind partition and all
+// validation live in the db layer (src/db/task-entity.ts); this layer adds eventing.
+import {
+  addTaskDependency,
+  addTaskRef,
+  assignTaskAgent,
+  createDeliverableTask,
+  getTaskDetail,
+  listDeliverableTasks,
+  listTaskEvents,
+  recordGate,
+  removeTaskDependency,
+  removeTaskRef,
+  setTaskStage,
+  setTaskStatus,
+  updateDeliverableTask,
+  type AddTaskRefInput,
+  type CreateDeliverableTaskInput,
+  type ListDeliverableTasksFilter,
+  type RecordGateInput,
+  type RemoveTaskRefInput,
+  type SetTaskStageInput,
+  type SetTaskStatusInput,
+  type UpdateDeliverableTaskInput,
+} from "../db";
+import { emitTaskChanged } from "../sse";
+import type { Task, TaskDetail, TaskEvent, TaskGateState } from "../types";
+import { emitTaskSemanticNotification, taskTransitionForStatus } from "./task-semantic-events";
+
+export function createTaskEntity(input: CreateDeliverableTaskInput): TaskDetail {
+  const detail = createDeliverableTask(input);
+  emitTaskChanged(detail, "task.created");
+  emitTaskSemanticNotification({
+    task: detail,
+    transition: "created",
+    actor: input.createdBy,
+    recipients: input.createdBy ? [input.createdBy] : [],
+    occurrenceKey: latestTaskEventOccurrence(detail.id, "task.created"),
+  });
+  return detail;
+}
+
+export function getTaskEntity(id: number): TaskDetail | null {
+  return getTaskDetail(id);
+}
+
+export function listTaskEntities(filter: ListDeliverableTasksFilter = {}): Task[] {
+  return listDeliverableTasks(filter);
+}
+
+export function updateTaskEntity(id: number, input: UpdateDeliverableTaskInput): TaskDetail {
+  const detail = updateDeliverableTask(id, input);
+  emitTaskChanged(detail, "task.updated");
+  return detail;
+}
+
+export function setTaskEntityStatus(id: number, input: SetTaskStatusInput): TaskDetail {
+  const before = getTaskDetail(id);
+  const detail = setTaskStatus(id, input);
+  emitTaskChanged(detail, "task.status");
+  const transition = taskTransitionForStatus(detail.status, detail.blockedBy);
+  if (input.actor !== "task-lifecycle" && transition && shouldEmitStatusTransition(before, detail, transition)) {
+    emitTaskSemanticNotification({
+      task: detail,
+      transition,
+      actor: input.actor,
+      recipients: detail.createdBy ? [detail.createdBy] : [],
+      occurrenceKey: latestTaskEventOccurrence(detail.id, `status:${detail.status}`),
+    });
+  }
+  return detail;
+}
+
+export function setTaskEntityStage(id: number, input: SetTaskStageInput): TaskDetail {
+  const before = getTaskDetail(id);
+  const detail = setTaskStage(id, input);
+  emitTaskChanged(detail, "task.stage");
+  if (input.actor !== "task-lifecycle" && before?.deliverableStage !== "landed-on-main" && detail.deliverableStage === "landed-on-main") {
+    emitTaskSemanticNotification({
+      task: detail,
+      transition: "landed",
+      actor: input.actor,
+      recipients: detail.createdBy ? [detail.createdBy] : [],
+      branch: detail.branch,
+      occurrenceKey: latestTaskEventOccurrence(detail.id, `stage:${detail.deliverableStage}`),
+    });
+  }
+  return detail;
+}
+
+function latestTaskEventOccurrence(taskId: number, type: string): string | undefined {
+  const event = [...taskEntityHistory(taskId)].reverse().find((item) => item.type === type);
+  return event ? `event:${event.id}` : undefined;
+}
+
+function shouldEmitStatusTransition(before: TaskDetail | null, detail: TaskDetail, transition: ReturnType<typeof taskTransitionForStatus>): boolean {
+  if (!transition) return false;
+  if (!before || before.status !== detail.status) return true;
+  if (transition === "needs-decision") {
+    return !before.blockedBy?.some((blocker) => blocker.type === "decision")
+      && detail.blockedBy?.some((blocker) => blocker.type === "decision") === true;
+  }
+  return false;
+}
+
+export function recordTaskEntityGate(id: number, input: RecordGateInput): { gate: TaskGateState; gates: TaskGateState[] } {
+  const gate = recordGate(id, input);
+  const detail = getTaskDetail(id);
+  if (detail) emitTaskChanged(detail, "task.gate");
+  return { gate, gates: detail?.gates ?? [] };
+}
+
+export function addTaskEntityDependency(taskId: number, dependsOnTaskId: number, actor?: string): TaskDetail {
+  addTaskDependency(taskId, dependsOnTaskId, actor);
+  const detail = getTaskDetail(taskId)!;
+  emitTaskChanged(detail, "task.updated");
+  return detail;
+}
+
+export function removeTaskEntityDependency(taskId: number, dependsOnTaskId: number, actor?: string): TaskDetail | null {
+  removeTaskDependency(taskId, dependsOnTaskId, actor);
+  const detail = getTaskDetail(taskId);
+  if (detail) emitTaskChanged(detail, "task.updated");
+  return detail;
+}
+
+export function addTaskEntityRef(id: number, input: AddTaskRefInput): TaskDetail {
+  const detail = addTaskRef(id, input);
+  emitTaskChanged(detail, "task.updated");
+  return detail;
+}
+
+export function removeTaskEntityRef(id: number, input: RemoveTaskRefInput): TaskDetail {
+  const detail = removeTaskRef(id, input);
+  emitTaskChanged(detail, "task.updated");
+  return detail;
+}
+
+export function assignTaskEntityAgent(id: number, agentId: string, role?: string, actor?: string): TaskDetail {
+  const detail = assignTaskAgent(id, agentId, role, actor);
+  emitTaskChanged(detail, "task.updated");
+  return detail;
+}
+
+export function taskEntityHistory(id: number): TaskEvent[] {
+  return listTaskEvents(id);
+}