nolo-cli 0.1.31 → 0.1.33

package/ai/taskRun/taskRunProtocol.ts

@@ -1,897 +0,0 @@
-import { randomUUID } from "node:crypto";
-
-export const TASK_RUN_SCHEMA_VERSION = 1;
-
-export const TASK_RUN_TOOL_ACTIONS = [
-  "readContext",
-  "readTaskContext",
-  "queryReadyWorkItems",
-  "updateWorkItems",
-  "upsertWorkItem",
-  "claimOrDispatch",
-  "claimWorkItem",
-  "recordAgentRun",
-  "openDialog",
-  "recordArtifact",
-  "markBlocked",
-  "setBlocker",
-  "clearBlocker",
-  "requestReview",
-  "recordReview",
-  "submitOutcome",
-  "completeWorkItem",
-  "closeWorkItem",
-] as const;
-
-export type TaskRunToolAction = (typeof TASK_RUN_TOOL_ACTIONS)[number];
-
-export type TaskRunPhase =
-  | "planned"
-  | "running"
-  | "blocked"
-  | "needs_review"
-  | "needs_changes"
-  | "ready_for_alpha"
-  | "alpha_deployed"
-  | "main_approval_required"
-  | "main_ready"
-  | "ready_to_commit"
-  | "completed";
-
-export type TaskRunWorkItem = {
-  id: string;
-  kind?: "work" | "review" | "coordination" | string;
-  title: string;
-  ownerAgent?: string;
-  status:
-    | "pending"
-    | "ready"
-    | "running"
-    | "blocked"
-    | "needs_review"
-    | "needs_changes"
-    | "completed";
-  dependsOn?: string[];
-  parallelGroup?: string;
-  writeScope?: string[];
-  reviewPolicy?: "none" | "after_item" | "after_group" | "before_commit";
-  reviewOfWorkItemId?: string;
-  dialogIds?: string[];
-  artifactRefs?: string[];
-  blockerIds?: string[];
-  outcome?: {
-    summary: string;
-    submittedAt: string;
-    artifactRefs?: string[];
-    closedAt?: string;
-    closeSummary?: string;
-    closeReason?: string;
-  };
-};
-
-export type TaskRunAgentRun = {
-  id: string;
-  agentKey: string;
-  role?: string;
-  workItemId?: string;
-  dialogId?: string;
-  status: "queued" | "running" | "completed" | "failed" | "timed_out";
-  startedAt: string;
-  updatedAt: string;
-  resultSummary?: string;
-  errorCode?: string;
-  toolsUsed?: string[];
-  toolTraceSummary?: {
-    callCount: number;
-    resultCount: number;
-    errorCount: number;
-    rounds: number;
-  };
-};
-
-export type TaskRunArtifact = {
-  id: string;
-  kind: "diff" | "patch" | "commit" | "test" | "screenshot" | "log" | "handoff" | string;
-  ref: string;
-  summary: string;
-  createdAt: string;
-  producerRunId?: string;
-  workItemId?: string;
-};
-
-export type TaskRunDialog = {
-  id: string;
-  purpose: "assignment" | "review" | "status" | "question" | "handoff" | string;
-  participantAgentKeys: string[];
-  workItemIds?: string[];
-  message?: string;
-  status: "open" | "closed";
-  openedAt: string;
-  closedAt?: string;
-};
-
-export type TaskRunEvent = {
-  id: string;
-  type: string;
-  actorId?: string;
-  agentKey?: string;
-  workItemId?: string;
-  dialogId?: string;
-  artifactId?: string;
-  reviewStatus?: TaskRunReview["status"];
-  reason?: string;
-  payload?: Record<string, unknown>;
-  createdAt: string;
-};
-
-export type TaskRunBlocker = {
-  id: string;
-  layer: string;
-  code: string;
-  message: string;
-  createdAt: string;
-  evidence?: string[];
-  resolvedAt?: string;
-};
-
-export type TaskRunReviewFinding = {
-  priority: "P0" | "P1" | "P2" | "P3";
-  summary: string;
-  file?: string;
-  line?: number;
-  workItemId?: string;
-};
-
-export type TaskRunReview = {
-  status: "not_requested" | "requested" | "passed" | "needs_changes" | "blocked";
-  reviewerAgentKey?: string;
-  targetWorkItemId?: string;
-  reviewWorkItemId?: string;
-  dialogId?: string;
-  reviewedArtifactIds?: string[];
-  findings?: TaskRunReviewFinding[];
-  updatedAt: string;
-};
-
-export type TaskRunAutonomy = "manual" | "supervised" | "auto24h";
-
-export type TaskRunBudgetRule = {
-  agentKey?: string;
-  provider?: string;
-  model?: string;
-  customProviderUrl?: string;
-  apiKeyHeader?: string;
-  freeUntil?: string;
-  dailyUsdLimit?: number;
-  hardStopAfter?: string;
-  note?: string;
-};
-
-export type TaskRunCodexPolicy = {
-  mode: "quality_gate_only" | "supervisor" | "allowed";
-  requireFor?: string[];
-  avoidFor?: string[];
-  note?: string;
-};
-
-export type TaskRunCodexUsageSnapshot = {
-  source: "local_codex_session";
-  observedAt?: string;
-  planType?: string;
-  primary?: {
-    usedPercent?: number;
-    windowMinutes?: number;
-    resetsAt?: number;
-  };
-  secondary?: {
-    usedPercent?: number;
-    windowMinutes?: number;
-    resetsAt?: number;
-  };
-  lastTotalTokens?: number;
-  totalTokens?: number;
-};
-
-export type TaskRunControlPolicy = {
-  autonomy?: TaskRunAutonomy;
-  nextWakeAt?: string;
-  pausedReason?: string;
-  runtimeToolPolicy?: Record<string, unknown>;
-  budget?: {
-    dailyUsdLimit?: number;
-    modelBudget?: Record<string, TaskRunBudgetRule>;
-    runnerBudget?: Record<string, TaskRunBudgetRule>;
-  };
-  codexPolicy?: TaskRunCodexPolicy;
-  codexUsageSnapshot?: TaskRunCodexUsageSnapshot;
-};
-
-export type TaskRunContext = {
-  schemaVersion: typeof TASK_RUN_SCHEMA_VERSION;
-  taskRunId: string;
-  taskRowId: string;
-  objective: string;
-  phase: TaskRunPhase;
-  control?: TaskRunControlPolicy;
-  updatedAt: string;
-};
-
-export type TaskRunMeta = {
-  taskRun?: TaskRunContext;
-  workItems?: TaskRunWorkItem[];
-  agentRuns?: TaskRunAgentRun[];
-  artifacts?: TaskRunArtifact[];
-  dialogs?: TaskRunDialog[];
-  taskEvents?: TaskRunEvent[];
-  review?: TaskRunReview;
-  blockers?: TaskRunBlocker[];
-  [key: string]: unknown;
-};
-
-export type TaskRunRowLike = {
-  rowId: string;
-  title?: string;
-  meta?: TaskRunMeta;
-};
-
-export type TaskRunDispatchPlan = {
-  ready: TaskRunWorkItem[];
-  waiting: Array<TaskRunWorkItem & { waitingOn: string[] }>;
-  active: TaskRunWorkItem[];
-  completed: TaskRunWorkItem[];
-};
-
-const createProtocolId = (): string => randomUUID().replace(/-/g, "");
-
-const unique = (values: Array<string | undefined>): string[] => [
-  ...new Set(values.filter((value): value is string => Boolean(value))),
-];
-
-export const DEFAULT_TASK_RUN_CONTROL_POLICY: TaskRunControlPolicy = {
-  autonomy: "supervised",
-  budget: {
-    modelBudget: {
-      projectManager: {
-        agentKey: "agent-b2e06f801f-01MIMO25MONTH00000001PGT4X",
-        provider: "custom",
-        model: "mimo-v2.5-pro",
-        customProviderUrl: "https://token-plan-cn.xiaomimimo.com/v1",
-        apiKeyHeader: "api-key",
-        freeUntil: "2026-05-31",
-        note: "Default PM and execution routing uses the monthly Mimo custom-key pool; medium intelligence, no marginal cost through the current month.",
-      },
-      frontend: {
-        agentKey: "agent-b2e06f801f-01MIMO25MONTH00000001PGT4X",
-        provider: "custom",
-        model: "mimo-v2.5-pro",
-        customProviderUrl: "https://token-plan-cn.xiaomimimo.com/v1",
-        apiKeyHeader: "api-key",
-        freeUntil: "2026-05-31",
-        note: "Frontend implementation uses the monthly Mimo custom-key pool by default; escalate to Codex only for quality gates or hard unblocks.",
-      },
-      mimoCustomKey: {
-        agentKey: "agent-b2e06f801f-01MIMO25MONTH00000001PGT4X",
-        provider: "custom",
-        model: "mimo-v2.5-pro",
-        customProviderUrl: "https://token-plan-cn.xiaomimimo.com/v1",
-        apiKeyHeader: "api-key",
-        freeUntil: "2026-05-31",
-        note: "Use the existing monthly Mimo custom-key agent/config for high-token routine implementation, long-context reads, table/doc processing, and low-risk probes.",
-      },
-    },
-  },
-  codexPolicy: {
-    mode: "quality_gate_only",
-    requireFor: ["supervision", "critical_review", "complex_unblock", "main_or_release_decision"],
-    avoidFor: ["routine_implementation", "first_pass_triage", "formatting", "low_risk_probe"],
-    note: "Codex membership usage is still window-limited, so spend it on supervision and quality gates.",
-  },
-};
-
-const cloneTaskRunControlPolicy = (policy: TaskRunControlPolicy): TaskRunControlPolicy =>
-  JSON.parse(JSON.stringify(policy));
-
-const cloneMeta = (meta: TaskRunMeta | undefined): TaskRunMeta => ({ ...(meta ?? {}) });
-
-const touchTaskRun = (meta: TaskRunMeta, now: string, phase?: TaskRunPhase): void => {
-  if (!meta.taskRun) return;
-  meta.taskRun = {
-    ...meta.taskRun,
-    ...(phase ? { phase } : {}),
-    updatedAt: now,
-  };
-};
-
-const phaseForWorkItemStatus = (status: TaskRunWorkItem["status"]): TaskRunPhase | undefined => {
-  if (status === "running") return "running";
-  if (status === "blocked") return "blocked";
-  if (status === "needs_review") return "needs_review";
-  if (status === "needs_changes") return "needs_changes";
-  return undefined;
-};
-
-const appendTaskRunEvent = (args: {
-  meta: TaskRunMeta;
-  type: string;
-  now: string;
-  createId?: () => string;
-  actorId?: string;
-  agentKey?: string;
-  workItemId?: string;
-  dialogId?: string;
-  artifactId?: string;
-  reviewStatus?: TaskRunReview["status"];
-  reason?: string;
-  payload?: Record<string, unknown>;
-}): TaskRunEvent => {
-  const event: TaskRunEvent = {
-    id: args.createId?.() ?? createProtocolId(),
-    type: args.type,
-    ...(args.actorId ? { actorId: args.actorId } : {}),
-    ...(args.agentKey ? { agentKey: args.agentKey } : {}),
-    ...(args.workItemId ? { workItemId: args.workItemId } : {}),
-    ...(args.dialogId ? { dialogId: args.dialogId } : {}),
-    ...(args.artifactId ? { artifactId: args.artifactId } : {}),
-    ...(args.reviewStatus ? { reviewStatus: args.reviewStatus } : {}),
-    ...(args.reason ? { reason: args.reason } : {}),
-    ...(args.payload ? { payload: args.payload } : {}),
-    createdAt: args.now,
-  };
-  args.meta.taskEvents = [...(args.meta.taskEvents ?? []), event];
-  return event;
-};
-
-export function prepareTaskRunMeta(args: {
-  row: TaskRunRowLike;
-  now?: string;
-  createId?: () => string;
-}): { meta: TaskRunMeta; taskRun: TaskRunContext } {
-  const now = args.now ?? new Date().toISOString();
-  const meta = cloneMeta(args.row.meta);
-  const existing = meta.taskRun;
-  const { allowedActions: _legacyAllowedActions, ...existingTaskRun } = existing ?? {};
-  const taskRun: TaskRunContext = {
-    ...existingTaskRun,
-    schemaVersion: TASK_RUN_SCHEMA_VERSION,
-    taskRunId: existing?.taskRunId ?? `taskrun-${args.row.rowId}-${args.createId?.() ?? createProtocolId()}`,
-    taskRowId: existing?.taskRowId ?? args.row.rowId,
-    objective: existing?.objective ?? args.row.title ?? args.row.rowId,
-    phase: existing?.phase ?? "planned",
-    control: existing?.control ?? cloneTaskRunControlPolicy(DEFAULT_TASK_RUN_CONTROL_POLICY),
-    updatedAt: now,
-  };
-  meta.taskRun = taskRun;
-  return { meta, taskRun };
-}
-
-export function planTaskRunDispatch(meta: TaskRunMeta): TaskRunDispatchPlan {
-  const workItems = meta.workItems ?? [];
-  const completedIds = new Set(workItems.filter((item) => item.status === "completed").map((item) => item.id));
-  const ready: TaskRunWorkItem[] = [];
-  const waiting: Array<TaskRunWorkItem & { waitingOn: string[] }> = [];
-  const active: TaskRunWorkItem[] = [];
-  const completed: TaskRunWorkItem[] = [];
-
-  for (const item of workItems) {
-    if (item.status === "completed") {
-      completed.push(item);
-      continue;
-    }
-    if (item.status === "running" || item.status === "needs_review") {
-      active.push(item);
-      continue;
-    }
-    if (item.status === "blocked") {
-      waiting.push({ ...item, waitingOn: item.blockerIds ?? [] });
-      continue;
-    }
-    if (item.status === "needs_changes") {
-      ready.push(item);
-      continue;
-    }
-    const missingDeps = (item.dependsOn ?? []).filter((depId) => !completedIds.has(depId));
-    if (missingDeps.length > 0) {
-      waiting.push({ ...item, waitingOn: missingDeps });
-      continue;
-    }
-    ready.push(item);
-  }
-
-  return { ready, waiting, active, completed };
-}
-
-export function upsertTaskRunWorkItems(args: {
-  meta: TaskRunMeta;
-  workItems: TaskRunWorkItem[];
-  now?: string;
-}): TaskRunMeta {
-  const now = args.now ?? new Date().toISOString();
-  const meta = cloneMeta(args.meta);
-  const items = [...(meta.workItems ?? [])];
-  for (const input of args.workItems) {
-    const index = items.findIndex((item) => item.id === input.id);
-    const existing = index >= 0 ? items[index] : undefined;
-    const workItem = existing
-      ? {
-          ...existing,
-          ...input,
-          dependsOn: unique([...(existing.dependsOn ?? []), ...(input.dependsOn ?? [])]),
-          writeScope: unique([...(existing.writeScope ?? []), ...(input.writeScope ?? [])]),
-          dialogIds: unique([...(existing.dialogIds ?? []), ...(input.dialogIds ?? [])]),
-          artifactRefs: unique([...(existing.artifactRefs ?? []), ...(input.artifactRefs ?? [])]),
-          blockerIds: unique([...(existing.blockerIds ?? []), ...(input.blockerIds ?? [])]),
-        }
-      : input;
-    if (index >= 0) {
-      items[index] = workItem;
-    } else {
-      items.push(workItem);
-    }
-    appendTaskRunEvent({
-      meta,
-      type: index >= 0 ? "work_item.updated" : "work_item.created",
-      workItemId: workItem.id,
-      now,
-      payload: { status: workItem.status, ownerAgent: workItem.ownerAgent },
-    });
-    touchTaskRun(meta, now, phaseForWorkItemStatus(workItem.status));
-  }
-  meta.workItems = items;
-  return meta;
-}
-
-export function updateTaskRunWorkItem(args: {
-  meta: TaskRunMeta;
-  id: string;
-  status?: TaskRunWorkItem["status"];
-  dialogIds?: string[];
-  artifactRefs?: string[];
-  blockerIds?: string[];
-  now?: string;
-}): { meta: TaskRunMeta; workItem?: TaskRunWorkItem } {
-  const now = args.now ?? new Date().toISOString();
-  const meta = cloneMeta(args.meta);
-  const items = [...(meta.workItems ?? [])];
-  const index = items.findIndex((item) => item.id === args.id);
-  if (index < 0) return { meta };
-  const existing = items[index];
-  const workItem = {
-    ...existing,
-    ...(args.status ? { status: args.status } : {}),
-    dialogIds: unique([...(existing.dialogIds ?? []), ...(args.dialogIds ?? [])]),
-    artifactRefs: unique([...(existing.artifactRefs ?? []), ...(args.artifactRefs ?? [])]),
-    blockerIds: unique([...(existing.blockerIds ?? []), ...(args.blockerIds ?? [])]),
-  };
-  items[index] = workItem;
-  meta.workItems = items;
-  appendTaskRunEvent({
-    meta,
-    type: args.status ? "work_item.status_changed" : "work_item.updated",
-    workItemId: workItem.id,
-    now,
-    payload: {
-      fromStatus: existing.status,
-      toStatus: workItem.status,
-      artifactRefs: args.artifactRefs,
-      blockerIds: args.blockerIds,
-      dialogIds: args.dialogIds,
-    },
-  });
-  touchTaskRun(meta, now, args.status ? phaseForWorkItemStatus(args.status) : undefined);
-  return { meta, workItem };
-}
-
-export function recordTaskRunDialog(args: {
-  meta: TaskRunMeta;
-  purpose: TaskRunDialog["purpose"];
-  participantAgentKeys: string[];
-  workItemIds?: string[];
-  message?: string;
-  now?: string;
-  createId?: () => string;
-}): { meta: TaskRunMeta; dialog: TaskRunDialog } {
-  const now = args.now ?? new Date().toISOString();
-  const meta = cloneMeta(args.meta);
-  const dialog: TaskRunDialog = {
-    id: args.createId?.() ?? createProtocolId(),
-    purpose: args.purpose,
-    participantAgentKeys: unique(args.participantAgentKeys),
-    ...(args.workItemIds?.length ? { workItemIds: unique(args.workItemIds) } : {}),
-    ...(args.message ? { message: args.message } : {}),
-    status: "open",
-    openedAt: now,
-  };
-  meta.dialogs = [...(meta.dialogs ?? []), dialog];
-  appendTaskRunEvent({
-    meta,
-    type: "dialog.opened",
-    dialogId: dialog.id,
-    now,
-    payload: {
-      purpose: dialog.purpose,
-      participantAgentKeys: dialog.participantAgentKeys,
-      workItemIds: dialog.workItemIds,
-    },
-  });
-  let nextMeta = meta;
-  for (const workItemId of dialog.workItemIds ?? []) {
-    nextMeta = updateTaskRunWorkItem({ meta: nextMeta, id: workItemId, dialogIds: [dialog.id], now }).meta;
-  }
-  touchTaskRun(nextMeta, now);
-  return { meta: nextMeta, dialog };
-}
-
-export function recordTaskRunArtifact(args: {
-  meta: TaskRunMeta;
-  artifact: Omit<TaskRunArtifact, "id" | "createdAt">;
-  now?: string;
-  createId?: () => string;
-}): { meta: TaskRunMeta; artifact: TaskRunArtifact } {
-  const now = args.now ?? new Date().toISOString();
-  const meta = cloneMeta(args.meta);
-  const artifact = { id: args.createId?.() ?? createProtocolId(), ...args.artifact, createdAt: now };
-  meta.artifacts = [...(meta.artifacts ?? []), artifact];
-  appendTaskRunEvent({
-    meta,
-    type: "artifact.recorded",
-    artifactId: artifact.id,
-    workItemId: artifact.workItemId,
-    now,
-    payload: { kind: artifact.kind, ref: artifact.ref, summary: artifact.summary },
-  });
-  touchTaskRun(meta, now);
-  return { meta, artifact };
-}
-
-export function recordTaskRunBlocker(args: {
-  meta: TaskRunMeta;
-  blocker: Omit<TaskRunBlocker, "id" | "createdAt">;
-  now?: string;
-  createId?: () => string;
-}): { meta: TaskRunMeta; blocker: TaskRunBlocker } {
-  const now = args.now ?? new Date().toISOString();
-  const meta = cloneMeta(args.meta);
-  const blocker = { id: args.createId?.() ?? createProtocolId(), ...args.blocker, createdAt: now };
-  meta.blockers = [...(meta.blockers ?? []), blocker];
-  appendTaskRunEvent({
-    meta,
-    type: "blocker.recorded",
-    now,
-    payload: { blockerId: blocker.id, layer: blocker.layer, code: blocker.code, message: blocker.message },
-  });
-  touchTaskRun(meta, now, "blocked");
-  return { meta, blocker };
-}
-
-export function clearTaskRunBlocker(args: {
-  meta: TaskRunMeta;
-  blockerId: string;
-  workItemId?: string;
-  now?: string;
-}): { meta: TaskRunMeta; blocker?: TaskRunBlocker; workItem?: TaskRunWorkItem } {
-  const now = args.now ?? new Date().toISOString();
-  const meta = cloneMeta(args.meta);
-  const blockers = [...(meta.blockers ?? [])];
-  const blockerIndex = blockers.findIndex((blocker) => blocker.id === args.blockerId);
-  if (blockerIndex < 0) return { meta };
-  const blocker = { ...blockers[blockerIndex], resolvedAt: now };
-  blockers[blockerIndex] = blocker;
-  meta.blockers = blockers;
-  let workItem: TaskRunWorkItem | undefined;
-  if (args.workItemId) {
-    const items = [...(meta.workItems ?? [])];
-    const itemIndex = items.findIndex((item) => item.id === args.workItemId);
-    if (itemIndex >= 0) {
-      const existing = items[itemIndex];
-      const blockerIds = (existing.blockerIds ?? []).filter((id) => id !== args.blockerId);
-      workItem = {
-        ...existing,
-        blockerIds,
-        ...(existing.status === "blocked" && blockerIds.length === 0 ? { status: "pending" as const } : {}),
-      };
-      items[itemIndex] = workItem;
-      meta.workItems = items;
-    }
-  }
-  appendTaskRunEvent({
-    meta,
-    type: "blocker.cleared",
-    workItemId: args.workItemId,
-    now,
-    payload: { blockerId: blocker.id },
-  });
-  touchTaskRun(meta, now);
-  return { meta, blocker, workItem };
-}
-
-export function recordTaskRunAgentDispatch(args: {
-  meta: TaskRunMeta;
-  workItemId: string;
-  agentKey: string;
-  role?: string;
-  now?: string;
-  createId?: () => string;
-}): { meta: TaskRunMeta; workItem?: TaskRunWorkItem; agentRun?: TaskRunAgentRun } {
-  const now = args.now ?? new Date().toISOString();
-  const updated = updateTaskRunWorkItem({ meta: args.meta, id: args.workItemId, status: "running", now });
-  if (!updated.workItem) return { meta: updated.meta };
-  const agentRun: TaskRunAgentRun = {
-    id: args.createId?.() ?? createProtocolId(),
-    agentKey: args.agentKey,
-    role: args.role,
-    workItemId: args.workItemId,
-    status: "queued",
-    startedAt: now,
-    updatedAt: now,
-  };
-  updated.meta.agentRuns = [...(updated.meta.agentRuns ?? []), agentRun];
-  appendTaskRunEvent({
-    meta: updated.meta,
-    type: "work_item.claimed",
-    agentKey: args.agentKey,
-    workItemId: args.workItemId,
-    now,
-    payload: { agentRunId: agentRun.id, role: args.role },
-  });
-  touchTaskRun(updated.meta, now, "running");
-  return { meta: updated.meta, workItem: updated.workItem, agentRun };
-}
-
-export function recordTaskRunAgentRun(args: {
-  meta: TaskRunMeta;
-  run: Omit<TaskRunAgentRun, "id" | "startedAt" | "updatedAt"> & {
-    id?: string;
-    startedAt?: string;
-  };
-  now?: string;
-  createId?: () => string;
-}): { meta: TaskRunMeta; agentRun: TaskRunAgentRun } {
-  const now = args.now ?? new Date().toISOString();
-  const meta = cloneMeta(args.meta);
-  const agentRuns = [...(meta.agentRuns ?? [])];
-  const id = args.run.id ?? args.createId?.() ?? createProtocolId();
-  const index = agentRuns.findIndex((run) => run.id === id);
-  const existing = index >= 0 ? agentRuns[index] : undefined;
-  const agentRun: TaskRunAgentRun = {
-    ...(existing ?? {
-      id,
-      agentKey: args.run.agentKey,
-      role: args.run.role,
-      startedAt: args.run.startedAt ?? now,
-    }),
-    ...args.run,
-    id,
-    startedAt: existing?.startedAt ?? args.run.startedAt ?? now,
-    updatedAt: now,
-  };
-  if (index >= 0) {
-    agentRuns[index] = agentRun;
-  } else {
-    agentRuns.push(agentRun);
-  }
-  meta.agentRuns = agentRuns;
-  appendTaskRunEvent({
-    meta,
-    type: "agent_run.recorded",
-    agentKey: agentRun.agentKey,
-    workItemId: agentRun.workItemId,
-    dialogId: agentRun.dialogId,
-    now,
-    payload: {
-      agentRunId: agentRun.id,
-      status: agentRun.status,
-      toolsUsed: agentRun.toolsUsed,
-      toolTraceSummary: agentRun.toolTraceSummary,
-    },
-  });
-  touchTaskRun(meta, now, agentRun.status === "running" ? "running" : undefined);
-  return { meta, agentRun };
-}
-
-export function submitTaskRunOutcome(args: {
-  meta: TaskRunMeta;
-  workItemId: string;
-  summary: string;
-  artifactIds?: string[];
-  dialogId?: string;
-  now?: string;
-}): { meta: TaskRunMeta; workItem?: TaskRunWorkItem } {
-  const now = args.now ?? new Date().toISOString();
-  const updated = updateTaskRunWorkItem({
-    meta: args.meta,
-    id: args.workItemId,
-    status: "needs_review",
-    dialogIds: args.dialogId ? [args.dialogId] : undefined,
-    artifactRefs: args.artifactIds,
-    now,
-  });
-  if (!updated.workItem) return updated;
-  const items = [...(updated.meta.workItems ?? [])];
-  const index = items.findIndex((item) => item.id === args.workItemId);
-  const workItem = {
-    ...updated.workItem,
-    outcome: {
-      summary: args.summary,
-      submittedAt: now,
-      ...(args.artifactIds?.length ? { artifactRefs: unique(args.artifactIds) } : {}),
-    },
-  };
-  if (index >= 0) items[index] = workItem;
-  updated.meta.workItems = items;
-  appendTaskRunEvent({
-    meta: updated.meta,
-    type: "work_item.outcome_submitted",
-    workItemId: args.workItemId,
-    dialogId: args.dialogId,
-    now,
-    payload: { summary: args.summary, artifactIds: args.artifactIds },
-  });
-  touchTaskRun(updated.meta, now, "needs_review");
-  return { meta: updated.meta, workItem };
-}
-
-export function closeTaskRunWorkItem(args: {
-  meta: TaskRunMeta;
-  workItemId: string;
-  summary: string;
-  reason?: string;
-  artifactIds?: string[];
-  dialogId?: string;
-  now?: string;
-}): { meta: TaskRunMeta; workItem?: TaskRunWorkItem } {
-  const now = args.now ?? new Date().toISOString();
-  const updated = updateTaskRunWorkItem({
-    meta: args.meta,
-    id: args.workItemId,
-    status: "completed",
-    dialogIds: args.dialogId ? [args.dialogId] : undefined,
-    artifactRefs: args.artifactIds,
-    now,
-  });
-  if (!updated.workItem) return updated;
-  const items = [...(updated.meta.workItems ?? [])];
-  const index = items.findIndex((item) => item.id === args.workItemId);
-  const workItem = {
-    ...updated.workItem,
-    outcome: {
-      ...(updated.workItem.outcome ?? { summary: args.summary, submittedAt: now }),
-      closedAt: now,
-      closeSummary: args.summary,
-      ...(args.reason ? { closeReason: args.reason } : {}),
-      ...(args.artifactIds?.length
-        ? { artifactRefs: unique([...(updated.workItem.outcome?.artifactRefs ?? []), ...args.artifactIds]) }
-        : {}),
-    },
-  };
-  if (index >= 0) items[index] = workItem;
-  updated.meta.workItems = items;
-  appendTaskRunEvent({
-    meta: updated.meta,
-    type: "work_item.closed",
-    workItemId: args.workItemId,
-    dialogId: args.dialogId,
-    now,
-    reason: args.reason,
-    payload: { summary: args.summary, artifactIds: args.artifactIds },
-  });
-  touchTaskRun(updated.meta, now);
-  return { meta: updated.meta, workItem };
-}
-
-export function requestTaskRunReview(args: {
-  meta: TaskRunMeta;
-  reviewerAgentKey: string;
-  targetWorkItemId?: string;
-  artifactIds?: string[];
-  dialogId?: string;
-  message?: string;
-  now?: string;
-  createId?: () => string;
-}): { meta: TaskRunMeta; review: TaskRunReview } {
-  const now = args.now ?? new Date().toISOString();
-  const meta = cloneMeta(args.meta);
-  const reviewWorkItemId = args.targetWorkItemId
-    ? `review-${args.targetWorkItemId}-${args.createId?.() ?? createProtocolId()}`
-    : undefined;
-  let reviewDialogId = args.dialogId;
-  let nextMeta = meta;
-  if (args.targetWorkItemId) {
-    const reviewWorkItem: TaskRunWorkItem = {
-      id: reviewWorkItemId ?? `review-${args.targetWorkItemId}`,
-      kind: "review",
-      title: `Review ${args.targetWorkItemId}`,
-      ownerAgent: args.reviewerAgentKey,
-      status: "ready",
-      dependsOn: [args.targetWorkItemId],
-      reviewPolicy: "none",
-      reviewOfWorkItemId: args.targetWorkItemId,
-      artifactRefs: args.artifactIds,
-    };
-    nextMeta = upsertTaskRunWorkItems({ meta: nextMeta, workItems: [reviewWorkItem], now });
-    if (!reviewDialogId) {
-      const opened = recordTaskRunDialog({
-        meta: nextMeta,
-        purpose: "review",
-        participantAgentKeys: [args.reviewerAgentKey],
-        workItemIds: [args.targetWorkItemId, reviewWorkItem.id],
-        message: args.message ?? `Please review ${args.targetWorkItemId}.`,
-        now,
-        createId: args.createId,
-      });
-      nextMeta = opened.meta;
-      reviewDialogId = opened.dialog.id;
-    }
-  }
-  const review: TaskRunReview = {
-    ...(nextMeta.review ?? { status: "not_requested", updatedAt: now }),
-    status: "requested",
-    reviewerAgentKey: args.reviewerAgentKey,
-    ...(args.targetWorkItemId ? { targetWorkItemId: args.targetWorkItemId } : {}),
-    ...(reviewWorkItemId ? { reviewWorkItemId } : {}),
-    ...(reviewDialogId ? { dialogId: reviewDialogId } : {}),
-    reviewedArtifactIds: unique([...(nextMeta.review?.reviewedArtifactIds ?? []), ...(args.artifactIds ?? [])]),
-    updatedAt: now,
-  };
-  nextMeta.review = review;
-  appendTaskRunEvent({
-    meta: nextMeta,
-    type: "review.requested",
-    workItemId: args.targetWorkItemId,
-    dialogId: reviewDialogId,
-    reviewStatus: "requested",
-    agentKey: args.reviewerAgentKey,
-    now,
-    payload: { artifactIds: args.artifactIds, reviewWorkItemId },
-  });
-  touchTaskRun(nextMeta, now, "needs_review");
-  return { meta: nextMeta, review };
-}
-
-export function recordTaskRunReview(args: {
-  meta: TaskRunMeta;
-  status: Exclude<TaskRunReview["status"], "not_requested" | "requested">;
-  targetWorkItemId?: string;
-  reviewerAgentKey?: string;
-  artifactIds?: string[];
-  dialogId?: string;
-  findings?: TaskRunReviewFinding[];
-  now?: string;
-}): { meta: TaskRunMeta; review: TaskRunReview } {
-  const now = args.now ?? new Date().toISOString();
-  const meta = cloneMeta(args.meta);
-  const review: TaskRunReview = {
-    ...(meta.review ?? { status: "not_requested", updatedAt: now }),
-    status: args.status,
-    ...(args.reviewerAgentKey ? { reviewerAgentKey: args.reviewerAgentKey } : {}),
-    ...(args.targetWorkItemId ? { targetWorkItemId: args.targetWorkItemId } : {}),
-    ...(args.dialogId ? { dialogId: args.dialogId } : {}),
-    reviewedArtifactIds: unique([...(meta.review?.reviewedArtifactIds ?? []), ...(args.artifactIds ?? [])]),
-    findings: args.findings ?? meta.review?.findings,
-    updatedAt: now,
-  };
-  meta.review = review;
-  let nextMeta = meta;
-  const targetWorkItemId = args.targetWorkItemId ?? meta.review?.targetWorkItemId;
-  if ((args.status === "needs_changes" || args.status === "blocked") && targetWorkItemId) {
-    nextMeta = updateTaskRunWorkItem({
-      meta: nextMeta,
-      id: targetWorkItemId,
-      status: args.status,
-      artifactRefs: args.artifactIds,
-      dialogIds: args.dialogId ? [args.dialogId] : undefined,
-      now,
-    }).meta;
-  }
-  appendTaskRunEvent({
-    meta: nextMeta,
-    type: "review.recorded",
-    dialogId: args.dialogId,
-    workItemId: targetWorkItemId,
-    reviewStatus: args.status,
-    agentKey: args.reviewerAgentKey,
-    now,
-    payload: { artifactIds: args.artifactIds, findings: args.findings },
-  });
-  touchTaskRun(nextMeta, now, args.status === "passed" ? "ready_for_alpha" : args.status);
-  return { meta: nextMeta, review };
-}