create-windy 0.2.8 → 0.2.10

package/template/packages/agent-client/src/run.ts

@@ -0,0 +1,320 @@
+import {
+  decodeAgentSseFrame,
+  isTerminalAgentEvent,
+  splitAgentSseFrames,
+  type AgentEvent,
+  type TerminalAgentEvent,
+} from "@southwind-ai/agent-contracts";
+import { AgentClientError, requestError, safeHttpError } from "./error.js";
+import { EventQueue } from "./event-queue.js";
+import { safeJson } from "./http.js";
+import type { AgentFetch, AgentRun } from "./types.js";
+
+interface HttpAgentRunOptions<Output> {
+  id: string;
+  eventsUrl: URL;
+  resultUrl: URL;
+  cancelUrl: URL;
+  fetch: AgentFetch;
+  signal?: AbortSignal;
+  maxReconnects: number;
+  reconnectDelayMs: number;
+  wait(milliseconds: number, signal?: AbortSignal): Promise<void>;
+  parseOutput(value: unknown): Output;
+}
+
+type TerminalOutcome =
+  | { terminal: TerminalAgentEvent }
+  | { failure: AgentClientError };
+
+export class HttpAgentRun<Output> implements AgentRun<Output> {
+  readonly id: string;
+  readonly events: AsyncIterable<AgentEvent>;
+
+  private readonly queue: EventQueue<AgentEvent>;
+  private readonly terminalOutcome: Promise<TerminalOutcome>;
+  private resolveTerminal!: (outcome: TerminalOutcome) => void;
+  private pump?: Promise<void>;
+  private resultRequest?: Promise<Output>;
+  private cancelRequest?: Promise<void>;
+  private lastSequence = 0;
+  private terminal?: TerminalAgentEvent;
+
+  constructor(private readonly options: HttpAgentRunOptions<Output>) {
+    this.id = options.id;
+    this.queue = new EventQueue(() => this.ensurePump());
+    this.events = this.queue;
+    this.terminalOutcome = new Promise((resolve) => {
+      this.resolveTerminal = resolve;
+    });
+
+    if (options.signal?.aborted) {
+      void this.cancel("调用方已取消").catch(() => undefined);
+    } else {
+      options.signal?.addEventListener(
+        "abort",
+        () => void this.cancel("调用方已取消").catch(() => undefined),
+        { once: true },
+      );
+    }
+  }
+
+  result(): Promise<Output> {
+    this.ensurePump();
+    this.resultRequest ||= this.resolveResult();
+    return this.resultRequest;
+  }
+
+  cancel(reason?: string): Promise<void> {
+    if (this.terminal) return Promise.resolve();
+    this.cancelRequest ||= this.sendCancel(reason);
+    return this.cancelRequest;
+  }
+
+  private ensurePump(): void {
+    if (this.pump) return;
+    this.pump = this.consumeEvents().catch((error: unknown) => {
+      const failure =
+        error instanceof AgentClientError
+          ? error
+          : requestError(error, "读取 Agent Run 事件", this.id);
+      this.queue.fail(failure);
+      this.resolveTerminal({ failure });
+    });
+  }
+
+  private async consumeEvents(): Promise<void> {
+    let reconnects = 0;
+    while (!this.terminal) {
+      let interruption: AgentClientError | undefined;
+      try {
+        const ended = await this.consumeConnection();
+        if (ended) return;
+      } catch (error) {
+        interruption = this.streamError(error);
+        if (!interruption.retryable) throw interruption;
+      }
+      if (reconnects >= this.options.maxReconnects) {
+        throw (
+          interruption ||
+          new AgentClientError(
+            "STREAM_INTERRUPTED",
+            "Agent Run 事件流在终态前中断",
+            true,
+            this.id,
+          )
+        );
+      }
+      reconnects += 1;
+      try {
+        await this.options.wait(
+          this.options.reconnectDelayMs,
+          this.options.signal,
+        );
+      } catch (error) {
+        throw this.streamError(error);
+      }
+    }
+  }
+
+  private async consumeConnection(): Promise<boolean> {
+    const url = new URL(this.options.eventsUrl);
+    const headers = new Headers({ accept: "text/event-stream" });
+    if (this.lastSequence > 0) {
+      const cursor = String(this.lastSequence);
+      headers.set("last-event-id", cursor);
+      url.searchParams.set("after", cursor);
+    }
+
+    let response: Response;
+    try {
+      response = await this.options.fetch(url, {
+        method: "GET",
+        headers,
+        signal: this.options.signal,
+      });
+    } catch (error) {
+      throw requestError(error, "连接 Agent Run 事件流", this.id);
+    }
+    if (!response.ok) {
+      throw await safeHttpError(response, "连接 Agent Run 事件流", this.id);
+    }
+    if (
+      !response.headers
+        .get("content-type")
+        ?.toLowerCase()
+        .includes("text/event-stream")
+    ) {
+      throw this.protocolViolation("Agent Run 事件响应类型无效");
+    }
+    if (!response.body) {
+      throw this.protocolViolation("Agent Run 事件响应缺少 body");
+    }
+
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    let remainder = "";
+    try {
+      while (true) {
+        const chunk = await reader.read();
+        if (chunk.done) {
+          remainder += decoder.decode();
+          return this.processBuffer(remainder, true);
+        }
+        remainder += decoder.decode(chunk.value, { stream: true });
+        const split = splitAgentSseFrames(remainder);
+        remainder = split.remainder;
+        for (const frame of split.frames) {
+          if (this.processFrame(frame)) {
+            await reader.cancel();
+            return true;
+          }
+        }
+      }
+    } catch (error) {
+      if (error instanceof AgentClientError) throw error;
+      throw requestError(error, "读取 Agent Run 事件流", this.id);
+    } finally {
+      reader.releaseLock();
+    }
+  }
+
+  private processBuffer(buffer: string, final: boolean): boolean {
+    const split = splitAgentSseFrames(buffer);
+    for (const frame of split.frames) {
+      if (this.processFrame(frame)) return true;
+    }
+    if (final && split.remainder.trim()) {
+      // 连接可在 frame 中途断开；恢复时服务端会按 cursor 重放完整事件。
+      return false;
+    }
+    return Boolean(this.terminal);
+  }
+
+  private processFrame(frame: string): boolean {
+    let decoded;
+    try {
+      decoded = decodeAgentSseFrame(frame);
+    } catch (error) {
+      throw this.protocolViolation("Agent Run 事件格式无效", error);
+    }
+    if (decoded.kind === "comment") return false;
+
+    const { id, event } = decoded;
+    if (event.runId !== this.id) {
+      throw this.protocolViolation("Agent Run 事件引用了错误的 Run");
+    }
+    // at-least-once 重放可能包含整个 cursor 前缀；只向调用方发出新 sequence。
+    if (id <= this.lastSequence) return false;
+    if (this.terminal) {
+      throw this.protocolViolation("Agent Run 终态后出现了额外事件");
+    }
+
+    this.lastSequence = id;
+    this.queue.push(event);
+    if (!isTerminalAgentEvent(event)) return false;
+
+    this.terminal = event;
+    this.queue.close();
+    this.resolveTerminal({ terminal: event });
+    return true;
+  }
+
+  private async resolveResult(): Promise<Output> {
+    const outcome = await this.terminalOutcome;
+    if ("failure" in outcome) throw outcome.failure;
+    if (outcome.terminal.type === "run.failed") {
+      throw new AgentClientError(
+        "RUN_FAILED",
+        outcome.terminal.error.message,
+        outcome.terminal.error.retryable,
+        this.id,
+        { agentError: outcome.terminal.error },
+      );
+    }
+    if (outcome.terminal.type === "run.cancelled") {
+      throw new AgentClientError(
+        "RUN_CANCELLED",
+        "Agent Run 已取消",
+        false,
+        this.id,
+      );
+    }
+    return this.fetchResult();
+  }
+
+  private async fetchResult(): Promise<Output> {
+    let response: Response;
+    try {
+      response = await this.options.fetch(this.options.resultUrl, {
+        method: "GET",
+        headers: { accept: "application/json" },
+        signal: this.options.signal,
+      });
+    } catch (error) {
+      throw requestError(error, "读取 Agent Run 结果", this.id);
+    }
+    if (!response.ok) {
+      throw await safeHttpError(response, "读取 Agent Run 结果", this.id);
+    }
+    const value = await safeJson(response, "读取 Agent Run 结果", this.id);
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+      throw this.protocolViolation("Agent Run 结果格式无效");
+    }
+    const record = value as Record<string, unknown>;
+    if (
+      record.runId !== this.id ||
+      record.status !== "completed" ||
+      !Object.hasOwn(record, "output")
+    ) {
+      throw this.protocolViolation("Agent Run 结果字段无效");
+    }
+    try {
+      return this.options.parseOutput(record.output);
+    } catch (error) {
+      throw this.protocolViolation(
+        "Agent Run 输出未通过 Operation 校验",
+        error,
+      );
+    }
+  }
+
+  private async sendCancel(reason?: string): Promise<void> {
+    let response: Response;
+    try {
+      response = await this.options.fetch(this.options.cancelUrl, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(reason?.trim() ? { reason } : {}),
+      });
+    } catch (error) {
+      throw requestError(error, "取消 Agent Run", this.id);
+    }
+    if (!response.ok) {
+      throw await safeHttpError(response, "取消 Agent Run", this.id);
+    }
+  }
+
+  private streamError(error: unknown): AgentClientError {
+    if (this.options.signal?.aborted) {
+      return new AgentClientError(
+        "CANCELLED",
+        "Agent Run 事件读取已取消",
+        false,
+        this.id,
+        { cause: error },
+      );
+    }
+    if (error instanceof AgentClientError) return error;
+    return requestError(error, "读取 Agent Run 事件", this.id);
+  }
+
+  private protocolViolation(
+    message: string,
+    cause?: unknown,
+  ): AgentClientError {
+    return new AgentClientError("PROTOCOL_VIOLATION", message, false, this.id, {
+      cause,
+    });
+  }
+}

package/template/packages/agent-client/src/types.ts

@@ -0,0 +1,35 @@
+import type { AgentEvent, AgentOperation } from "@southwind-ai/agent-contracts";
+
+export interface StartAgentRunOptions {
+  idempotencyKey: string;
+  signal?: AbortSignal;
+}
+
+export interface AgentRun<Output> {
+  readonly id: string;
+  readonly events: AsyncIterable<AgentEvent>;
+  result(): Promise<Output>;
+  cancel(reason?: string): Promise<void>;
+}
+
+export interface AgentCaller {
+  start<Input, Output>(
+    operation: AgentOperation<Input, Output>,
+    input: Input,
+    options: StartAgentRunOptions,
+  ): Promise<AgentRun<Output>>;
+}
+
+export type AgentFetch = (
+  input: string | URL | Request,
+  init?: RequestInit,
+) => Promise<Response>;
+
+export interface AgentClientOptions {
+  baseUrl: string | URL;
+  fetch?: AgentFetch;
+  runsPath?: string;
+  maxReconnects?: number;
+  reconnectDelayMs?: number;
+  wait?: (milliseconds: number, signal?: AbortSignal) => Promise<void>;
+}

package/template/packages/agent-client/tsconfig.json

@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "target": "esnext",
+    "module": "esnext",
+    "lib": ["esnext", "dom"],
+    "moduleResolution": "bundler",
+    "baseUrl": ".",
+    "paths": {
+      "@southwind-ai/agent-contracts": ["../agent-contracts/index.ts"],
+      "@southwind-ai/storage": ["../storage/index.ts"]
+    },
+    "strict": true,
+    "noImplicitAny": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "outDir": "dist",
+    "types": ["bun"]
+  },
+  "include": ["src/**/*", "index.ts"],
+  "exclude": ["node_modules", "dist"]
+}

package/template/packages/agent-contracts/index.ts

@@ -0,0 +1,7 @@
+export * from "./src/errors.js";
+export * from "./src/events.js";
+export * from "./src/operation.js";
+export * from "./src/runs.js";
+export * from "./src/sse.js";
+export * from "./src/usage.js";
+export { AgentContractParseError } from "./src/validation.js";

package/template/packages/agent-contracts/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@southwind-ai/agent-contracts",
+  "version": "0.1.0",
+  "license": "UNLICENSED",
+  "type": "module",
+  "engines": {
+    "bun": ">=1.3.0"
+  },
+  "files": [
+    "index.ts",
+    "src/**/*.ts",
+    "!src/**/*.test.ts"
+  ],
+  "scripts": {
+    "test": "bun test",
+    "typecheck": "tsc --noEmit --project tsconfig.json"
+  },
+  "exports": {
+    ".": "./index.ts"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/template/packages/agent-contracts/src/contracts.test.ts

@@ -0,0 +1,213 @@
+import { describe, expect, test } from "bun:test";
+import {
+  AgentContractParseError,
+  agentErrorCodes,
+  decodeAgentSseFrame,
+  defineAgentOperation,
+  isAgentEvent,
+  isTerminalAgentEvent,
+  isTerminalAgentRunStatus,
+  parseAgentError,
+  parseAgentEvent,
+  parseStartAgentRunResponse,
+  parseAgentUsage,
+  splitAgentSseFrames,
+  type AgentEvent,
+} from "../index.js";
+
+const error = {
+  code: "RUNTIME_UNAVAILABLE",
+  message: "运行时不可用",
+  requestId: "request-1",
+  retryable: true,
+} as const;
+
+const events: AgentEvent[] = [
+  { type: "run.started", runId: "run-1", sequence: 1 },
+  { type: "output.delta", runId: "run-1", sequence: 2, text: "你好" },
+  {
+    type: "tool.requested",
+    runId: "run-1",
+    sequence: 3,
+    toolCallId: "call-1",
+    toolKey: "work-order.ticket.read",
+  },
+  {
+    type: "approval.required",
+    runId: "run-1",
+    sequence: 4,
+    workItemId: "work-1",
+  },
+  {
+    type: "tool.completed",
+    runId: "run-1",
+    sequence: 5,
+    toolCallId: "call-1",
+  },
+  {
+    type: "usage.reported",
+    runId: "run-1",
+    sequence: 6,
+    usage: { source: "provider-reported", inputTokens: 10 },
+  },
+  { type: "run.completed", runId: "run-1", sequence: 7 },
+  { type: "run.failed", runId: "run-2", sequence: 1, error },
+  { type: "run.cancelled", runId: "run-3", sequence: 1 },
+];
+
+describe("Agent contract", () => {
+  test("Operation 运行时只保留稳定 key", () => {
+    const operation = defineAgentOperation<{ id: string }, { text: string }>(
+      "work-order.ticket.summarize",
+      (value) => {
+        if (
+          !value ||
+          typeof value !== "object" ||
+          !("text" in value) ||
+          typeof value.text !== "string"
+        ) {
+          throw new TypeError("输出格式无效");
+        }
+        return { text: value.text };
+      },
+    );
+    expect(operation.key).toBe("work-order.ticket.summarize");
+    expect(operation.parseOutput({ text: "摘要" })).toEqual({ text: "摘要" });
+    expect(() => operation.parseOutput({ content: "未校验输出" })).toThrow(
+      "输出格式无效",
+    );
+    expect(() => defineAgentOperation(" ", operation.parseOutput)).toThrow();
+  });
+
+  test("解析创建 Run 响应并拒绝未知状态或缺失字段", () => {
+    expect(
+      parseStartAgentRunResponse({
+        runId: "run-1",
+        status: "accepted",
+        eventsUrl: "/api/agent/runs/run-1/events",
+      }),
+    ).toEqual({
+      runId: "run-1",
+      status: "accepted",
+      eventsUrl: "/api/agent/runs/run-1/events",
+    });
+    expect(() =>
+      parseStartAgentRunResponse({
+        runId: "run-1",
+        status: "queued",
+        eventsUrl: "/api/agent/runs/run-1/events",
+      }),
+    ).toThrow(AgentContractParseError);
+    expect(() =>
+      parseStartAgentRunResponse({
+        runId: "run-1",
+        status: "accepted",
+      }),
+    ).toThrow(AgentContractParseError);
+  });
+
+  test("解析全部 canonical event", () => {
+    for (const event of events) {
+      expect(parseAgentEvent(event)).toEqual(event);
+      expect(isAgentEvent(event)).toBe(true);
+    }
+  });
+
+  test("拒绝未知、缺字段和非法 sequence", () => {
+    expect(() =>
+      parseAgentEvent({ type: "provider.delta", runId: "run-1", sequence: 1 }),
+    ).toThrow(AgentContractParseError);
+    expect(() =>
+      parseAgentEvent({ type: "output.delta", runId: "run-1", sequence: 1 }),
+    ).toThrow(AgentContractParseError);
+    expect(() =>
+      parseAgentEvent({
+        type: "run.started",
+        runId: "run-1",
+        sequence: 0,
+      }),
+    ).toThrow(AgentContractParseError);
+    expect(isAgentEvent(null)).toBe(false);
+  });
+
+  test("unknown 用量不会伪装为零", () => {
+    expect(parseAgentUsage({ source: "unknown" })).toEqual({
+      source: "unknown",
+    });
+    expect(() =>
+      parseAgentUsage({ source: "unknown", inputTokens: 0 }),
+    ).toThrow(AgentContractParseError);
+    expect(() => parseAgentUsage({ source: "estimated" })).toThrow(
+      AgentContractParseError,
+    );
+    expect(
+      parseAgentUsage({ source: "estimated", firstTokenLatencyMs: 0 }),
+    ).toEqual({ source: "estimated", firstTokenLatencyMs: 0 });
+  });
+
+  test("稳定错误码全部可解析并拒绝未知错误", () => {
+    for (const code of agentErrorCodes) {
+      expect(parseAgentError({ ...error, code }).code).toBe(code);
+    }
+    expect(() => parseAgentError({ ...error, code: "PROVIDER_BODY" })).toThrow(
+      AgentContractParseError,
+    );
+  });
+
+  test("terminal status 与 event 判断完整", () => {
+    expect(isTerminalAgentRunStatus("accepted")).toBe(false);
+    expect(isTerminalAgentRunStatus("running")).toBe(false);
+    expect(isTerminalAgentRunStatus("awaiting-approval")).toBe(false);
+    expect(isTerminalAgentRunStatus("completed")).toBe(true);
+    expect(isTerminalAgentRunStatus("failed")).toBe(true);
+    expect(isTerminalAgentRunStatus("cancelled")).toBe(true);
+    expect(events.filter(isTerminalAgentEvent).map(({ type }) => type)).toEqual(
+      ["run.completed", "run.failed", "run.cancelled"],
+    );
+  });
+});
+
+describe("Agent SSE", () => {
+  test("拆分跨 chunk 缓冲并保留尾部", () => {
+    const result = splitAgentSseFrames(
+      ": heartbeat\r\n\r\nid: 1\nevent: run.started\ndata: {",
+    );
+    expect(result).toEqual({
+      frames: [": heartbeat"],
+      remainder: "id: 1\nevent: run.started\ndata: {",
+    });
+  });
+
+  test("解码 heartbeat 与 canonical event", () => {
+    expect(decodeAgentSseFrame(": heartbeat")).toEqual({
+      kind: "comment",
+      comment: "heartbeat",
+    });
+    const event = events[1]!;
+    const frame = `id: 2\nevent: output.delta\ndata: ${JSON.stringify(event)}`;
+    expect(decodeAgentSseFrame(frame)).toEqual({
+      kind: "event",
+      id: 2,
+      event,
+    });
+  });
+
+  test("拒绝损坏或不一致的 SSE frame", () => {
+    expect(() => decodeAgentSseFrame("event: run.started")).toThrow(
+      AgentContractParseError,
+    );
+    expect(() =>
+      decodeAgentSseFrame(
+        'id: 2\nevent: run.started\ndata: {"type":"run.started","runId":"run-1","sequence":1}',
+      ),
+    ).toThrow(AgentContractParseError);
+    expect(() =>
+      decodeAgentSseFrame(
+        'id: 1\nevent: output.delta\ndata: {"type":"run.started","runId":"run-1","sequence":1}',
+      ),
+    ).toThrow(AgentContractParseError);
+    expect(() =>
+      decodeAgentSseFrame("id: 1\nevent: run.started\ndata: not-json"),
+    ).toThrow(AgentContractParseError);
+  });
+});

package/template/packages/agent-contracts/src/errors.ts

@@ -0,0 +1,51 @@
+import {
+  AgentContractParseError,
+  booleanAt,
+  recordAt,
+  stringAt,
+} from "./validation.js";
+
+export const agentErrorCodes = [
+  "OPERATION_NOT_FOUND",
+  "OPERATION_DISABLED",
+  "INVALID_INPUT",
+  "FORBIDDEN",
+  "LICENSE_NOT_ALLOWED",
+  "RUNTIME_UNAVAILABLE",
+  "MODEL_ROUTE_UNAVAILABLE",
+  "PROVIDER_UNAVAILABLE",
+  "RATE_LIMITED",
+  "BUDGET_EXCEEDED",
+  "TOOL_DENIED",
+  "APPROVAL_REQUIRED",
+  "OUTPUT_VALIDATION_FAILED",
+  "RUN_CONFLICT",
+  "RUN_TIMEOUT",
+  "RUN_CANCELLED",
+  "STREAM_INTERRUPTED",
+] as const;
+
+export type AgentErrorCode = (typeof agentErrorCodes)[number];
+
+export interface AgentError {
+  code: AgentErrorCode;
+  message: string;
+  requestId: string;
+  retryable: boolean;
+}
+
+const errorCodeSet: ReadonlySet<string> = new Set(agentErrorCodes);
+
+export function parseAgentError(input: unknown): AgentError {
+  const record = recordAt(input, "error");
+  const code = stringAt(record, "code", "error");
+  if (!errorCodeSet.has(code)) {
+    throw new AgentContractParseError("error.code", "错误码无效");
+  }
+  return {
+    code: code as AgentErrorCode,
+    message: stringAt(record, "message", "error"),
+    requestId: stringAt(record, "requestId", "error"),
+    retryable: booleanAt(record, "retryable", "error"),
+  };
+}