实现 Agent Loop

// src/context.tsexport interface ContextKindMap {  harness_feedback: true;}// src/types.tsexport interface StopReasonMap {  blocked_plan: true;}

import type { ModelRequest } from "./context.js";import type { ModelTurn } from "./model.js";import type { Planner } from "./planner.js";import type { TraceSink } from "./trace.js";import type { ToolRegistry } from "./tool-registry.js";import type { StopReason } from "./types.js";export type AgentLoopEvent =  | { type: "run_started"; runId: string }  | { type: "model_started"; step: number }  | { type: "model_completed"; step: number }  | { type: "plan_revised"; version: number; reason: string }  | { type: "run_stopped"; reason: StopReason };export interface FunctionCallOutput {  type: "function_call_output";  call_id: string;  output: string;}export interface ModelDriver {  start(options: {    request: ModelRequest;    tools: ReturnType<ToolRegistry["definitions"]>;  }): Promise<ModelTurn>;  continue(options: {    previousResponseId: string;    instructions: string;    continuationContext: ModelRequest["input"];    outputs: FunctionCallOutput[];    tools: ReturnType<ToolRegistry["definitions"]>;  }): Promise<ModelTurn>;}export interface AgentLoopOptions {  cwd: string;  skillsDirectory: string;  maxSteps: number;  maxToolCalls: number;  toolTimeoutMs: number;  model: ModelDriver;  planner: Planner;  tools: ToolRegistry;  trace: TraceSink;  signal?: AbortSignal;  onEvent?: (event: AgentLoopEvent) => void;}

await client.responses.create({  previous_response_id: options.previousResponseId,  instructions: options.instructions,  input: [...options.outputs, ...options.continuationContext],  tools: options.tools,});

WHILE status is running  GUARD: cancelled? model budget exhausted?  PLAN: select the next dependency-ready step; replan only after invalidating evidence  ASSEMBLE: build goal + criteria + active step + selected context  DECIDE: call model once  IF model requested tools    GUARD: enough tool-call budget for the whole batch?    FOR EACH tool call      ACT: validate, authorize, execute with timeout      OBSERVE: store result and preserve call_id    CONTINUE with all function_call_output items  ELSE IF model returned non-empty final text    COMPLETE only if the plan and every acceptance criterion are complete    OTHERWISE reject early completion and continue  ELSE    FAIL with invalid_model_output

import { buildModelRequest, summarizeSources } from "./context.js";import { checkCompletion } from "./completion.js";import { executeToolCall } from "./execute-tool.js";import {  allCriteriaPassed,  applyCriterionEvidence,  assertEvidenceComesFromObservations,  completeStep,  createInitialPlan,  planAsContextSource,  reconcilePlan,  selectNextStep,  startStep,} from "./plan.js";import { createInitialState, transitionState } from "./state.js";import { waitForUserInput } from "./interaction.js";import { discoverSkills, skillCatalogAsContextSource } from "./skill-catalog.js";import type { AgentResult, AgentState, StopReason } from "./types.js";export async function runAgentLoop(  task: string,  options: AgentLoopOptions,): Promise<AgentResult> {  let state = createInitialState(task, options.cwd, {    maxSteps: options.maxSteps,    maxToolCalls: options.maxToolCalls,  });  state.skills.catalog = await discoverSkills(options.skillsDirectory);  const toolDefinitions = options.tools.definitions();  state.plan = await createInitialPlan(    task,    summarizeSources(state.contextSources),    options.tools.names(),    options.planner,  );  let previousResponseId: string | undefined;  let pendingOutputs: FunctionCallOutput[] = [];  emitLoopEvent(options, state, { type: "run_started", runId: state.runId });  while (state.status === "running") {    if (options.signal?.aborted) return stop(state, "cancelled", options);    if (state.budget.modelSteps >= state.budget.maxSteps) {      return stop(state, "max_steps", options);    }    let activeStep = state.plan.steps.find((step) => step.id === state.activeStepId);    if (!activeStep) {      activeStep = selectNextStep(state.plan);      if (activeStep) {        state.plan = startStep(state.plan, activeStep.id);        state.activeStepId = activeStep.id;        activeStep = state.plan.steps.find((step) => step.id === activeStep?.id);      } else if (state.plan.steps.some((step) => step.status !== "completed")) {        return stop(state, "blocked_plan", options);      }    }    const request = buildModelRequest({      task: state.task,      cwd: state.cwd,      toolNames: options.tools.names(),      sources: [        ...state.contextSources,        planAsContextSource(state.plan, activeStep),        skillCatalogAsContextSource(state.skills.catalog),        ...Object.values(state.skills.activeSkills).map((skill) => ({          id: `skill:${skill.name}`,          kind: "skill_instructions" as const,          label: skill.name,          content: skill.instructions,          priority: 96,        })),        ...Object.values(state.skills.activeSkills).flatMap((skill) =>          Object.entries(skill.loadedResources).map(([path, content]) => ({            id: `skill-resource:${skill.name}:${path}`,            kind: "skill_resource" as const,            label: `${skill.name}/${path}`,            content,            priority: 94,          })),        ),      ],    });    state.budget.modelSteps += 1;    const modelStepCount = state.budget.modelSteps;    emitLoopEvent(options, state, { type: "model_started", step: modelStepCount });    let turn: ModelTurn;    try {      turn = previousResponseId        ? await options.model.continue({            previousResponseId,            instructions: request.instructions,            // Harness feedback and current plan are sent on every continuation.            continuationContext: request.input,            outputs: pendingOutputs,            tools: toolDefinitions,          })        : await options.model.start({ request, tools: toolDefinitions });    } catch (error) {      state.steps.push({        number: state.steps.length + 1,        kind: "model",        summary: error instanceof Error ? error.message : String(error),      });      return stop(state, "model_error", options);    }    state.steps.push({      number: state.steps.length + 1,      kind: "model",      summary: turn.toolCalls.length > 0 ? "模型请求工具" : "模型返回文本",    });    emitLoopEvent(options, state, { type: "model_completed", step: modelStepCount });    if (turn.userInputRequest) {      state = waitForUserInput(state, turn.userInputRequest);      emitLoopEvent(options, state, { type: "run_stopped", reason: "user_input_required" });      return {        status: "waiting",        answer: "",        stopReason: "user_input_required",        state,      };    }    if (turn.toolCalls.length === 0) {      const answer = turn.finalText.trim();      if (!answer) return stop(state, "invalid_model_output", options);      const planCompleted = state.plan.steps.every((step) => step.status === "completed");      const completionError = await checkCompletion(state);      if (!planCompleted || !allCriteriaPassed(state.plan) || completionError) {        state.contextSources.push({          id: "completion-rejected-" + modelStepCount,          kind: "harness_feedback",          label: "completion rejected",          content: completionError ?? "继续执行：计划或验收条件尚未完成。",          priority: 100,        });        previousResponseId = undefined;        pendingOutputs = [];        continue;      }      state.messages.push({ role: "assistant", content: answer });      state = transitionState(state, "completed", "final_answer");      emitLoopEvent(options, state, { type: "run_stopped", reason: "final_answer" });      return {        status: "completed",        answer,        stopReason: "final_answer",        state,      };    }    if (state.budget.toolCalls + turn.toolCalls.length > state.budget.maxToolCalls) {      return stop(state, "max_tool_calls", options);    }    if (!activeStep) return stop(state, "blocked_plan", options);    const outputs: FunctionCallOutput[] = [];    const observations: string[] = [];    for (const call of turn.toolCalls) {      if (options.signal?.aborted) return stop(state, "cancelled", options);      const result = await executeToolCall({        call,        registry: options.tools,        cwd: state.cwd,        timeoutMs: options.toolTimeoutMs,      });      state.budget.toolCalls += 1;      if (result.type === "waiting") {        state = transitionState(state, "waiting", result.reason);        emitLoopEvent(options, state, { type: "run_stopped", reason: result.reason });        return {          status: "waiting",          answer: "",          stopReason: result.reason,          state,        };      }      state.steps.push({        number: state.steps.length + 1,        kind: "tool",        summary: call.name,      });      state.contextSources.push({        id: call.callId,        kind: "tool_observation",        label: call.name,        content: result.output,        priority: 80,      });      outputs.push({        type: "function_call_output",        call_id: call.callId,        output: result.output,      });      observations.push(result.output);    }    const progress = await options.planner.evaluate({      step: activeStep,      observations,    });    assertEvidenceComesFromObservations(progress.evidence, observations);    state.plan = applyCriterionEvidence(state.plan, progress.passedCriteria, observations);    if (progress.completed) {      state.plan = completeStep(state.plan, activeStep.id, progress.evidence.join("\n"));      state.activeStepId = undefined;    }    if (progress.replanReason) {      const draft = await options.planner.revise({        current: state.plan,        reason: progress.replanReason,        observations,      });      state.plan = reconcilePlan(state.plan, draft, progress.replanReason);      state.planHistory.push({        version: state.plan.version,        reason: progress.replanReason,        changedAt: new Date().toISOString(),      });      emitLoopEvent(options, state, {        type: "plan_revised",        version: state.plan.version,        reason: progress.replanReason,      });      state.activeStepId = undefined;    }    previousResponseId = turn.responseId;    pendingOutputs = outputs;  }  return stop(state, "invalid_model_output", options);}function stop(  state: AgentState,  reason: StopReason,  options: AgentLoopOptions,): AgentResult {  const status = reason === "cancelled" ? "cancelled" : reason === "blocked_plan" ? "blocked" : "failed";  const stopped = transitionState(state, status, reason);  emitLoopEvent(options, stopped, { type: "run_stopped", reason });  return { status: stopped.status, answer: "", stopReason: reason, state: stopped };}function emitLoopEvent(  options: AgentLoopOptions,  state: AgentState,  event: AgentLoopEvent,): void {  const failedStop = event.type === "run_stopped" && event.reason !== "final_answer";  const blockedStop =    event.type === "run_stopped" &&    ["approval_required", "user_input_required", "blocked_plan", "cancelled"].includes(      event.reason,    );  options.trace.record({    runId: state.runId,    type: event.type,    startedAt: new Date().toISOString(),    outcome: event.type.endsWith("started")      ? "started"      : blockedStop        ? "blocked"        : failedStop          ? "failed"          : "passed",    ...(failedStop ? { errorCode: event.reason } : {}),  });  options.onEvent?.(event);}

import { describe, expect, it, vi } from "vitest";import { runAgentLoop } from "../src/agent-loop.js";import { InMemoryTraceSink } from "../src/trace.js";it("runs model → tool → observation → model → final", async () => {  const start = vi.fn().mockResolvedValue({    responseId: "response-1",    finalText: "",    toolCalls: [      { callId: "call-1", name: "read_file", argumentsJson: '{"path":"package.json"}' },    ],  });  const continueTurn = vi.fn().mockResolvedValue({    responseId: "response-2",    finalText: "package.json defines the project scripts.",    toolCalls: [],  });  const result = await runAgentLoop("Explain package.json", {    cwd: "/workspace",    skillsDirectory: "/workspace/skills",    maxSteps: 4,    maxToolCalls: 4,    toolTimeoutMs: 1_000,    model: { start, continue: continueTurn },    planner: createFakePlanner(),    tools: createFakeRegistry(),    trace: new InMemoryTraceSink(),  });  expect(result.stopReason).toBe("final_answer");  expect(result.state.steps.map((step) => step.kind)).toEqual(["model", "tool", "model"]);  expect(continueTurn).toHaveBeenCalledWith(    expect.objectContaining({      previousResponseId: "response-1",      outputs: [        expect.objectContaining({          type: "function_call_output",          call_id: "call-1",        }),      ],      continuationContext: expect.anything(),    }),  );});