多 Agent 协作

export type AgentRoleId = "researcher" | "implementer" | "verifier";export interface AgentRole {  id: AgentRoleId;  promptFragment: string;  allowedTools: string[];  maxEffect: Exclude<ToolEffect, "external">;  budgetCeiling: Pick<AgentBudget, "maxSteps" | "maxToolCalls">;}const rank: Record<ToolEffect, number> = { read: 0, write: 1, execute: 2, external: 3 };export function restrictRegistry(registry: ToolRegistry, role: AgentRole): ToolRegistry {  const names = registry.definitions()    .filter((tool) => role.allowedTools.includes(tool.name) && rank[tool.effect] <= rank[role.maxEffect])    .map((tool) => tool.name);  return registry.subset(names);}

export type AgentHandoffStatus =  "recorded" | "running" | "completed" | "failed" | "cancelled" | "manual_reconciliation";export interface AgentHandoff {  handoffId: string;  parentRunId: string;  childRunId: string;  parentStepId: string;  role: AgentRoleId;  task: string;  allowedTools: string[];  budget: AgentBudget;  idempotencyKey: string;  status: AgentHandoffStatus;  recordedAt: string;}

export type DurableEvent =  // 第 16 章已有成员  | { type: "handoff_recorded"; handoff: AgentHandoff }  | { type: "handoff_result"; handoffId: string; status: AgentHandoffStatus; budgetUsed: AgentBudget; evidence: string[] }  | { type: "handoff_conflict"; handoffId: string; conflicting: string[] };export interface StopReasonMap { manual_reconciliation: true; handoff_blocked: true; }

export async function recordHandoff(options: {  parent: DurableAgentState; request: HandoffRequest; store: RunStore; lease: RunLease; clock: Clock;}): Promise<AgentHandoff> {  const idempotencyKey = `${options.parent.runId}:${options.request.stepId}:${options.request.role.id}`;  const existing = findHandoffByKey(options.parent.events, idempotencyKey);  if (existing) return existing;  const handoff: AgentHandoff = {    handoffId: crypto.randomUUID(), parentRunId: options.parent.runId,    childRunId: childRunIdFor(idempotencyKey), parentStepId: options.request.stepId,    role: options.request.role.id, task: options.request.task, idempotencyKey,    allowedTools: options.request.role.allowedTools, status: "recorded",    budget: sliceBudget(options.parent.budget, options.request.role, options.request.budgetRequest),    recordedAt: options.clock.now().toISOString(),  };  await appendHandoffEvent({ state: options.parent, lease: options.lease, store: options.store, handoff });  return handoff;}

export function reserveBudget(parent: AgentBudget, slice: AgentBudget): AgentBudget {  const next: AgentBudget = { ...parent, modelSteps: parent.modelSteps + slice.maxSteps, toolCalls: parent.toolCalls + slice.maxToolCalls };  if (next.modelSteps > next.maxSteps || next.toolCalls > next.maxToolCalls) throw new Error("budget_exhausted");  return next;}

export interface PlanStep {  handoff?: { role: AgentRoleId; task: string; budgetRequest: AgentBudget } | undefined;}// runAgentLoop 的循环体内，selectNextStep 之后：if (activeStep?.handoff) {  const handoff = await recordHandoff({ parent: state, request: { stepId: activeStep.id, ...activeStep.handoff }, store, lease, clock });  const outcome = await runHandoff({ handoff, role, parentState: state, parentRuntime, store, clock });  state = applyHandoffOutcome(state, outcome); // 写入 observation 与父 TaskPlan 证据  previousResponseId = undefined;  pendingOutputs = [];  continue;}

export async function runHandoff(options: HandoffRunOptions): Promise<HandoffOutcome> {  const { store, handoff, role, parentState, parentRuntime } = options;  const childLease = await store.acquireLease(handoff.childRunId, crypto.randomUUID(), 30_000);  const childState = createInitialState(handoff.task, parentRuntime.cwd);  childState.runId = handoff.childRunId;  childState.budget = { ...handoff.budget, modelSteps: 0, toolCalls: 0 };  const childRuntime: AgentRuntime = {    ...parentRuntime,    tools: restrictRegistry(parentRuntime.tools, role),    store,    trace: parentRuntime.trace,  };  const result: AgentResult = await runAgentLoopFromState(childState, childRuntime);  await appendHandoffResult({ state: parentState, lease: options.parentLease, store, handoff, result });  await store.releaseLease(childLease);  return toOutcome(handoff, result);}

export interface HandoffOutcome {  handoffId: string; childRunId: string; parentStepId: string; role: AgentRoleId;  status: AgentHandoffStatus; budgetUsed: AgentBudget; evidence: string[];  criteria: Record<string, "passed" | "failed" | "unknown">;}export function mergeHandoffOutcomes(plan: TaskPlan, outcomes: HandoffOutcome[]) {  let merged = plan;  const conflicts: HandoffConflict[] = [];  const ordered = [...outcomes].toSorted(compareOutcome);  for (const outcome of ordered) {    merged = applyCriterionEvidence(merged, outcome.criteria, outcome.evidence);    merged = appendEvidence(merged, outcome.parentStepId, outcome);  }  for (const conflict of detectCriterionConflicts(ordered)) {    conflicts.push(conflict);    merged = blockStep(merged, conflict.stepId, "manual_reconciliation");  }  return { plan: merged, conflicts };}

describe("handoff", () => {  it("records handoff_recorded before the child run starts", async () => {    const fixture = createHandoffFixture();    await fixture.runParent();    expect(fixture.indexOf("handoff_recorded")).toBeLessThan(fixture.indexOf("run_started"));  });  it("never lets parallel children exceed the parent budget", async () => {    const result = await runParallelHandoffs(parentState, [request(4), request(4), request(4)]);    expect(result.state.budget.modelSteps).toBeLessThanOrEqual(parentState.budget.maxSteps);    expect(result.stopReason).toBe("max_steps");  });  it("keeps budget evidence when a child fails", async () => {    const outcome = await runFailingChild();    expect(outcome.budgetUsed.modelSteps).toBeGreaterThan(0);    expect(findEvent(parentRunId, "handoff_result")).toMatchObject({ status: "failed" });  });  it("merges outcomes independently of completion order", () => {    const forward = mergeHandoffOutcomes(plan, outcomes);    const backward = mergeHandoffOutcomes(plan, [...outcomes].reverse());    expect(backward.plan).toEqual(forward.plan);    expect(backward.conflicts).toEqual(forward.conflicts);  });  it("keeps both sides of a conflict and asks for manual reconciliation", () => {    const merged = mergeHandoffOutcomes(plan, [      outcome("verifier-a", { "tests-pass": "passed" }),      outcome("verifier-b", { "tests-pass": "failed" }),    ]);    expect(merged.conflicts).toHaveLength(1);    expect(merged.plan.steps[0]?.status).toBe("blocked");  });  it("denies a tool outside the role", async () => {    const child = await runChildWithRole("researcher", "apply_patch");    expect(child.trace.readRun(child.childRunId)).toContainEqual(expect.objectContaining({ errorCode: "policy_denied" }));  });  it("reconciles a handoff recorded before the child started", async () => {    const fixture = createHandoffFixture("after_handoff_recorded");    await expect(fixture.startParent()).rejects.toThrow("simulated_crash");    const result = await resumeAgentRun(fixture.parentRunId, fixture.restartedRuntime());    expect(result.stopReason).toBe("final_answer");    expect(fixture.childStartCount()).toBe(1);    expect(fixture.eventSequences()).toEqual(fixture.contiguousSequences());  });});