create-windy 0.2.8 → 0.2.10

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

@@ -0,0 +1,186 @@
+import type {
+  AgentOperation,
+  StartAgentRunRequest,
+} from "@southwind-ai/agent-contracts";
+import { parseStartAgentRunResponse } from "@southwind-ai/agent-contracts";
+import { AgentClientError, requestError, safeHttpError } from "./error.js";
+import { safeJson } from "./http.js";
+import { HttpAgentRun } from "./run.js";
+import type {
+  AgentCaller,
+  AgentClientOptions,
+  AgentFetch,
+  AgentRun,
+  StartAgentRunOptions,
+} from "./types.js";
+
+export class HttpAgentCaller implements AgentCaller {
+  private readonly baseUrl: URL;
+  private readonly fetch: AgentFetch;
+  private readonly runsPath: string;
+  private readonly maxReconnects: number;
+  private readonly reconnectDelayMs: number;
+  private readonly wait: NonNullable<AgentClientOptions["wait"]>;
+
+  constructor(options: AgentClientOptions) {
+    this.baseUrl = validateBaseUrl(options.baseUrl);
+    this.fetch = options.fetch || globalThis.fetch.bind(globalThis);
+    this.runsPath = options.runsPath || "/api/agent/runs";
+    this.maxReconnects = nonNegativeInteger(
+      options.maxReconnects,
+      3,
+      "maxReconnects",
+    );
+    this.reconnectDelayMs = nonNegativeInteger(
+      options.reconnectDelayMs,
+      250,
+      "reconnectDelayMs",
+    );
+    this.wait = options.wait || wait;
+  }
+
+  async start<Input, Output>(
+    operation: AgentOperation<Input, Output>,
+    input: Input,
+    options: StartAgentRunOptions,
+  ): Promise<AgentRun<Output>> {
+    if (!operation.key.trim()) {
+      throw new AgentClientError(
+        "INVALID_CONFIGURATION",
+        "Agent Operation key 不能为空",
+        false,
+      );
+    }
+    if (!options.idempotencyKey.trim()) {
+      throw new AgentClientError(
+        "INVALID_CONFIGURATION",
+        "幂等键不能为空",
+        false,
+      );
+    }
+
+    const request: StartAgentRunRequest<Input> = {
+      operationKey: operation.key,
+      input,
+    };
+    let response: Response;
+    try {
+      response = await this.fetch(this.endpoint(this.runsPath), {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          "idempotency-key": options.idempotencyKey,
+        },
+        body: JSON.stringify(request),
+        signal: options.signal,
+      });
+    } catch (error) {
+      if (options.signal?.aborted) {
+        throw new AgentClientError(
+          "CANCELLED",
+          "创建 Agent Run 已取消",
+          false,
+          undefined,
+          { cause: error },
+        );
+      }
+      throw requestError(error, "创建 Agent Run");
+    }
+    if (!response.ok) throw await safeHttpError(response, "创建 Agent Run");
+
+    const created = parseCreatedRun(await safeJson(response, "创建 Agent Run"));
+    const eventsUrl = this.endpoint(created.eventsUrl);
+    return new HttpAgentRun<Output>({
+      id: created.runId,
+      eventsUrl,
+      resultUrl: this.endpoint(
+        `${this.runsPath}/${encodeURIComponent(created.runId)}/result`,
+      ),
+      cancelUrl: this.endpoint(
+        `${this.runsPath}/${encodeURIComponent(created.runId)}/cancel`,
+      ),
+      fetch: this.fetch,
+      signal: options.signal,
+      maxReconnects: this.maxReconnects,
+      reconnectDelayMs: this.reconnectDelayMs,
+      wait: this.wait,
+      parseOutput: operation.parseOutput,
+    });
+  }
+
+  private endpoint(path: string): URL {
+    const endpoint = new URL(path, this.baseUrl);
+    if (endpoint.origin !== this.baseUrl.origin) {
+      throw new AgentClientError(
+        "INVALID_RESPONSE",
+        "Agent Server 返回了不受信任的 Endpoint",
+        false,
+      );
+    }
+    return endpoint;
+  }
+}
+
+function parseCreatedRun(value: unknown) {
+  try {
+    return parseStartAgentRunResponse(value);
+  } catch (error) {
+    throw new AgentClientError(
+      "INVALID_RESPONSE",
+      "创建 Agent Run 响应格式无效",
+      false,
+      undefined,
+      { cause: error },
+    );
+  }
+}
+
+function validateBaseUrl(value: string | URL): URL {
+  const url = new URL(value);
+  if (url.protocol !== "http:" && url.protocol !== "https:") {
+    throw new AgentClientError(
+      "INVALID_CONFIGURATION",
+      "Agent Server URL 只允许 HTTP 或 HTTPS",
+      false,
+    );
+  }
+  return url;
+}
+
+function nonNegativeInteger(
+  value: number | undefined,
+  fallback: number,
+  name: string,
+): number {
+  if (value === undefined) return fallback;
+  if (!Number.isSafeInteger(value) || value < 0) {
+    throw new AgentClientError(
+      "INVALID_CONFIGURATION",
+      `${name} 必须是非负安全整数`,
+      false,
+    );
+  }
+  return value;
+}
+
+function wait(milliseconds: number, signal?: AbortSignal): Promise<void> {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(signal.reason);
+      return;
+    }
+    const timer = setTimeout(resolve, milliseconds);
+    signal?.addEventListener(
+      "abort",
+      () => {
+        clearTimeout(timer);
+        reject(signal.reason);
+      },
+      { once: true },
+    );
+  });
+}
+
+export function createAgentCaller(options: AgentClientOptions): AgentCaller {
+  return new HttpAgentCaller(options);
+}

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

@@ -0,0 +1,88 @@
+import {
+  parseAgentError,
+  type AgentError,
+} from "@southwind-ai/agent-contracts";
+
+export type AgentClientErrorCode =
+  | "INVALID_CONFIGURATION"
+  | "INVALID_RESPONSE"
+  | "RUN_REJECTED"
+  | "RUN_FAILED"
+  | "RUN_CANCELLED"
+  | "STREAM_INTERRUPTED"
+  | "PROTOCOL_VIOLATION"
+  | "REQUEST_FAILED"
+  | "CANCELLED";
+
+export class AgentClientError extends Error {
+  constructor(
+    readonly code: AgentClientErrorCode,
+    message: string,
+    readonly retryable: boolean,
+    readonly runId?: string,
+    options?: ErrorOptions & { agentError?: AgentError },
+  ) {
+    super(message, options);
+    this.name = "AgentClientError";
+    this.agentError = options?.agentError;
+  }
+
+  readonly agentError?: AgentError;
+}
+
+export async function safeHttpError(
+  response: Response,
+  action: string,
+  runId?: string,
+): Promise<AgentClientError> {
+  const agentError = await safeAgentError(response);
+  return new AgentClientError(
+    response.status === 429 ? "RUN_REJECTED" : "REQUEST_FAILED",
+    agentError?.message || `${action}失败（HTTP ${response.status}）`,
+    agentError?.retryable ??
+      (response.status === 408 ||
+        response.status === 425 ||
+        response.status === 429 ||
+        response.status >= 500),
+    runId,
+    agentError ? { agentError } : undefined,
+  );
+}
+
+export function requestError(
+  error: unknown,
+  action: string,
+  runId?: string,
+): AgentClientError {
+  if (error instanceof AgentClientError) return error;
+  if (isAbortError(error)) {
+    return new AgentClientError("CANCELLED", `${action}已取消`, false, runId, {
+      cause: error,
+    });
+  }
+  return new AgentClientError("REQUEST_FAILED", `${action}失败`, true, runId, {
+    cause: error,
+  });
+}
+
+function isAbortError(error: unknown): boolean {
+  return error instanceof DOMException && error.name === "AbortError";
+}
+
+async function safeAgentError(
+  response: Response,
+): Promise<AgentError | undefined> {
+  if (
+    !response.headers
+      .get("content-type")
+      ?.toLowerCase()
+      .includes("application/json")
+  ) {
+    return undefined;
+  }
+  try {
+    return parseAgentError(await response.json());
+  } catch {
+    return undefined;
+  }
+}

package/template/packages/agent-client/src/event-queue.ts

@@ -0,0 +1,62 @@
+export class EventQueue<T> implements AsyncIterable<T> {
+  private readonly values: T[] = [];
+  private readonly waiters: Array<{
+    resolve(result: IteratorResult<T>): void;
+    reject(error: unknown): void;
+  }> = [];
+  private closed = false;
+  private failure?: unknown;
+  private claimed = false;
+
+  constructor(private readonly onClaim: () => void) {}
+
+  push(value: T): void {
+    if (this.closed) return;
+    const waiter = this.waiters.shift();
+    if (waiter) {
+      waiter.resolve({ value, done: false });
+      return;
+    }
+    this.values.push(value);
+  }
+
+  close(): void {
+    if (this.closed) return;
+    this.closed = true;
+    for (const waiter of this.waiters.splice(0)) {
+      waiter.resolve({ value: undefined, done: true });
+    }
+  }
+
+  fail(error: unknown): void {
+    if (this.closed) return;
+    this.failure = error;
+    this.closed = true;
+    for (const waiter of this.waiters.splice(0)) waiter.reject(error);
+  }
+
+  [Symbol.asyncIterator](): AsyncIterator<T> {
+    if (this.claimed) {
+      throw new TypeError("Agent Run events 只能消费一次");
+    }
+    this.claimed = true;
+    this.onClaim();
+    return {
+      next: () => this.next(),
+    };
+  }
+
+  private next(): Promise<IteratorResult<T>> {
+    const value = this.values.shift();
+    if (value !== undefined) {
+      return Promise.resolve({ value, done: false });
+    }
+    if (this.failure !== undefined) return Promise.reject(this.failure);
+    if (this.closed) {
+      return Promise.resolve({ value: undefined, done: true });
+    }
+    return new Promise((resolve, reject) => {
+      this.waiters.push({ resolve, reject });
+    });
+  }
+}

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

@@ -0,0 +1,19 @@
+import { AgentClientError } from "./error.js";
+
+export async function safeJson(
+  response: Response,
+  action: string,
+  runId?: string,
+): Promise<unknown> {
+  try {
+    return await response.json();
+  } catch (error) {
+    throw new AgentClientError(
+      "INVALID_RESPONSE",
+      `${action}响应不是合法 JSON`,
+      false,
+      runId,
+      { cause: error },
+    );
+  }
+}

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

@@ -0,0 +1,231 @@
+import { describe, expect, test } from "bun:test";
+import {
+  defineAgentOperation,
+  type AgentEvent,
+} from "@southwind-ai/agent-contracts";
+import { createAgentCaller } from "../index.js";
+import type { AgentFetch } from "./types.js";
+
+const operation = defineAgentOperation<null, string>("agent.test", (value) => {
+  if (typeof value !== "string") throw new TypeError("string required");
+  return value;
+});
+
+describe("Agent Run protocol safety", () => {
+  test("拒绝跨源 eventsUrl", async () => {
+    const fake = plannedFetch([
+      () =>
+        json({
+          runId: "run-origin",
+          status: "accepted",
+          eventsUrl: "https://evil.example/events",
+        }),
+    ]);
+
+    await expect(start(fake.fetch, "origin")).rejects.toMatchObject({
+      code: "INVALID_RESPONSE",
+      retryable: false,
+    });
+    expect(fake.calls).toBe(1);
+  });
+
+  test("跨 chunk 解析 heartbeat 和事件 frame", async () => {
+    const started = frame({
+      type: "run.started",
+      runId: "run-chunks",
+      sequence: 1,
+    });
+    const completed = frame({
+      type: "run.completed",
+      runId: "run-chunks",
+      sequence: 2,
+    });
+    const fake = plannedFetch([
+      () =>
+        json({
+          runId: "run-chunks",
+          status: "accepted",
+          eventsUrl: "/events",
+        }),
+      () =>
+        sse([
+          ": heart",
+          "beat\n\n" + started.slice(0, 9),
+          started.slice(9) + completed.slice(0, 17),
+          completed.slice(17),
+        ]),
+      () => json({ runId: "run-chunks", status: "completed", output: "ok" }),
+    ]);
+    const run = await start(fake.fetch, "chunks");
+    const events = collect(run.events);
+
+    await expect(run.result()).resolves.toBe("ok");
+    expect((await events).map(({ type }) => type)).toEqual([
+      "run.started",
+      "run.completed",
+    ]);
+  });
+
+  test("run.failed 返回 canonical 安全错误且不请求 result", async () => {
+    const fake = plannedFetch([
+      () =>
+        json({
+          runId: "run-failed",
+          status: "accepted",
+          eventsUrl: "/events",
+        }),
+      () =>
+        sse([
+          frame({
+            type: "run.failed",
+            runId: "run-failed",
+            sequence: 1,
+            error: {
+              code: "PROVIDER_UNAVAILABLE",
+              message: "模型服务暂不可用",
+              requestId: "request-failed",
+              retryable: true,
+            },
+          }),
+        ]),
+    ]);
+    const run = await start(fake.fetch, "failed");
+
+    await expect(run.result()).rejects.toMatchObject({
+      code: "RUN_FAILED",
+      message: "模型服务暂不可用",
+      retryable: true,
+      agentError: {
+        code: "PROVIDER_UNAVAILABLE",
+        requestId: "request-failed",
+      },
+    });
+    expect(fake.calls).toBe(2);
+  });
+
+  test("run.cancelled 返回唯一取消终态且不请求 result", async () => {
+    const fake = plannedFetch([
+      () =>
+        json({
+          runId: "run-cancelled",
+          status: "accepted",
+          eventsUrl: "/events",
+        }),
+      () =>
+        sse([
+          frame({
+            type: "run.cancelled",
+            runId: "run-cancelled",
+            sequence: 1,
+          }),
+        ]),
+    ]);
+    const run = await start(fake.fetch, "cancelled");
+    const events = collect(run.events);
+
+    await expect(run.result()).rejects.toMatchObject({
+      code: "RUN_CANCELLED",
+      retryable: false,
+    });
+    expect((await events).map(({ type }) => type)).toEqual(["run.cancelled"]);
+    expect(fake.calls).toBe(2);
+  });
+
+  test.each([
+    {
+      name: "content-type",
+      response: () =>
+        new Response("not sse", {
+          headers: { "content-type": "text/plain" },
+        }),
+    },
+    {
+      name: "sequence",
+      response: () =>
+        sse([
+          'id: 2\nevent: run.started\ndata: {"type":"run.started","runId":"run-invalid","sequence":1}\n\n',
+        ]),
+    },
+    {
+      name: "runId",
+      response: () =>
+        sse([
+          frame({
+            type: "run.started",
+            runId: "another-run",
+            sequence: 1,
+          }),
+        ]),
+    },
+  ])("非法 $name 以协议错误终止且不重试", async ({ response }) => {
+    const fake = plannedFetch([
+      () =>
+        json({
+          runId: "run-invalid",
+          status: "accepted",
+          eventsUrl: "/events",
+        }),
+      response,
+    ]);
+    const run = await start(fake.fetch, `invalid-${response.name}`);
+
+    await expect(run.result()).rejects.toMatchObject({
+      code: "PROTOCOL_VIOLATION",
+      retryable: false,
+    });
+    expect(fake.calls).toBe(2);
+  });
+});
+
+function start(fetch: AgentFetch, idempotencyKey: string) {
+  return createAgentCaller({
+    baseUrl: "https://agent.internal",
+    fetch,
+    reconnectDelayMs: 0,
+    wait: async () => undefined,
+  }).start(operation, null, { idempotencyKey });
+}
+
+function plannedFetch(plans: Array<() => Response>): {
+  fetch: AgentFetch;
+  readonly calls: number;
+} {
+  let calls = 0;
+  return {
+    fetch: async () => {
+      const plan = plans[calls++];
+      if (!plan) throw new Error("unexpected fetch");
+      return plan();
+    },
+    get calls() {
+      return calls;
+    },
+  };
+}
+
+function json(value: unknown): Response {
+  return Response.json(value);
+}
+
+function sse(chunks: string[]): Response {
+  const encoder = new TextEncoder();
+  return new Response(
+    new ReadableStream<Uint8Array>({
+      start(controller) {
+        for (const chunk of chunks) controller.enqueue(encoder.encode(chunk));
+        controller.close();
+      },
+    }),
+    { headers: { "content-type": "text/event-stream" } },
+  );
+}
+
+function frame(event: AgentEvent): string {
+  return `id: ${event.sequence}\nevent: ${event.type}\ndata: ${JSON.stringify(event)}\n\n`;
+}
+
+async function collect(events: AsyncIterable<AgentEvent>) {
+  const collected: AgentEvent[] = [];
+  for await (const event of events) collected.push(event);
+  return collected;
+}