create-windy 0.6.12 → 0.6.15

package/template/apps/server/src/agent/client-session/openai-stream.ts

@@ -0,0 +1,123 @@
+import type { ModuleAiJsonValue } from "@southwind-ai/server-sdk";
+
+interface MutableToolCall {
+  id: string;
+  type: "function";
+  function: { name: string; arguments: string };
+}
+
+interface MutableChoice {
+  index: number;
+  finishReason: string | null;
+  role: string;
+  content: string;
+  toolCalls: MutableToolCall[];
+}
+
+export class OpenAiChunkAccumulator {
+  readonly #choices = new Map<number, MutableChoice>();
+  #id = "";
+  #created: number | undefined;
+  #usage: ModuleAiJsonValue | undefined;
+
+  constructor(private readonly modelAlias: string) {}
+
+  append(value: ModuleAiJsonValue): void {
+    const chunk = record(value, "Provider chunk");
+    if (typeof chunk.id === "string") this.#id = chunk.id;
+    if (typeof chunk.created === "number") this.#created = chunk.created;
+    if (chunk.usage !== undefined) this.#usage = json(chunk.usage);
+    if (!Array.isArray(chunk.choices)) throw new Error("Provider choices 无效");
+    for (const candidate of chunk.choices) this.appendChoice(candidate);
+  }
+
+  result(): ModuleAiJsonValue {
+    const choices = [...this.#choices.values()]
+      .sort((left, right) => left.index - right.index)
+      .map((choice) => ({
+        index: choice.index,
+        message: {
+          role: choice.role || "assistant",
+          content: choice.content || null,
+          ...(choice.toolCalls.length
+            ? {
+                tool_calls: choice.toolCalls.map((tool) => ({
+                  id: tool.id,
+                  type: "function",
+                  function: { ...tool.function },
+                })),
+              }
+            : {}),
+        },
+        finish_reason: choice.finishReason,
+      }));
+    if (!choices.length) throw new Error("Provider 未返回 choice");
+    return {
+      id: this.#id || "windy-client-completion",
+      object: "chat.completion",
+      ...(this.#created === undefined ? {} : { created: this.#created }),
+      model: this.modelAlias,
+      choices,
+      ...(this.#usage === undefined ? {} : { usage: this.#usage }),
+    };
+  }
+
+  private appendChoice(value: unknown): void {
+    const input = record(value, "Provider choice");
+    if (!Number.isSafeInteger(input.index) || Number(input.index) < 0) {
+      throw new Error("Provider choice index 无效");
+    }
+    const index = Number(input.index);
+    const choice = this.#choices.get(index) ?? {
+      index,
+      finishReason: null,
+      role: "assistant",
+      content: "",
+      toolCalls: [],
+    };
+    if (typeof input.finish_reason === "string") {
+      choice.finishReason = input.finish_reason;
+    }
+    if (input.delta !== undefined) this.appendDelta(choice, input.delta);
+    this.#choices.set(index, choice);
+  }
+
+  private appendDelta(choice: MutableChoice, value: unknown): void {
+    const delta = record(value, "Provider delta");
+    if (typeof delta.role === "string") choice.role = delta.role;
+    if (typeof delta.content === "string") choice.content += delta.content;
+    if (!Array.isArray(delta.tool_calls)) return;
+    for (const candidate of delta.tool_calls) {
+      const call = record(candidate, "Provider tool call");
+      if (!Number.isSafeInteger(call.index) || Number(call.index) < 0) {
+        throw new Error("Provider tool call index 无效");
+      }
+      const index = Number(call.index);
+      const current =
+        choice.toolCalls[index] ??
+        (choice.toolCalls[index] = {
+          id: "",
+          type: "function",
+          function: { name: "", arguments: "" },
+        });
+      if (typeof call.id === "string") current.id += call.id;
+      if (call.function === undefined) continue;
+      const fn = record(call.function, "Provider function delta");
+      if (typeof fn.name === "string") current.function.name += fn.name;
+      if (typeof fn.arguments === "string") {
+        current.function.arguments += fn.arguments;
+      }
+    }
+  }
+}
+
+function record(value: unknown, label: string): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`${label} 无效`);
+  }
+  return value as Record<string, unknown>;
+}
+
+function json(value: unknown): ModuleAiJsonValue {
+  return JSON.parse(JSON.stringify(value)) as ModuleAiJsonValue;
+}

package/template/apps/server/src/agent/client-session/presentation.ts

@@ -0,0 +1,46 @@
+import type {
+  ClientSessionReceiptRecord,
+  ClientSessionRecord,
+} from "./contracts.js";
+
+export function publicLimits(record: ClientSessionRecord) {
+  return {
+    maxSteps: record.limits.maxSteps,
+    maxRequestBytes: record.limits.maxRequestBytes,
+    maxResponseBytes: record.limits.maxResponseBytes,
+    maxDurationSeconds: record.limits.maxDurationSeconds,
+    maxConcurrentRequests: record.limits.maxConcurrentRequests,
+  };
+}
+
+export function publicReceipt(receipt: ClientSessionReceiptRecord) {
+  return {
+    receiptId: receipt.receiptId,
+    clientRunId: receipt.clientRunId,
+    attempt: receipt.attempt,
+    requestDigest: receipt.requestDigest,
+    responseDigest: receipt.responseDigest,
+    deploymentDigest: receipt.deploymentDigest,
+    issuedAt: new Date(receipt.issuedAt).toISOString(),
+  };
+}
+
+export function sessionView(record: ClientSessionRecord) {
+  return {
+    clientRunId: record.clientRunId,
+    sessionId: record.sessionId,
+    operationKey: record.operationKey,
+    status: record.status,
+    attemptCount: record.attemptCount,
+    expiresAt: new Date(record.expiresAt).toISOString(),
+    ...(record.finalResult ? { result: record.finalResult } : {}),
+  };
+}
+
+export function attemptKey(sessionId: string, attempt: number): string {
+  return `${sessionId}\0${attempt}`;
+}
+
+export function ensureTrailingSlash(value: string): string {
+  return value.endsWith("/") ? value : `${value}/`;
+}

package/template/apps/server/src/agent/client-session/remote-provider.test.ts

@@ -0,0 +1,144 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import type { Server } from "bun";
+import { RemoteClientAgentProvider } from "./remote-provider.js";
+
+const digest = `sha256:${"d".repeat(64)}` as const;
+const policy = {
+  inputFields: [],
+  envelopeFields: [
+    {
+      field: "user-prompt" as const,
+      classification: "internal" as const,
+      dlpAction: "redact" as const,
+    },
+  ],
+};
+let servers: Server<unknown>[] = [];
+
+afterEach(() => {
+  for (const server of servers) server.stop(true);
+  servers = [];
+});
+
+describe("Remote Client Agent Provider", () => {
+  test("通过真实 HTTP/SSE 传递 tool call，且不发送客户端 model/URL/Key", async () => {
+    let observed: Record<string, unknown> = {};
+    const server = serve(async (request) => {
+      const url = new URL(request.url);
+      if (url.pathname.endsWith("/health")) {
+        return Response.json({ status: "ready" });
+      }
+      expect(request.headers.get("authorization")).toBe(
+        "Bearer internal-secret",
+      );
+      observed = (await request.json()) as Record<string, unknown>;
+      return sse([
+        `event: windy.meta\ndata: ${JSON.stringify({ deploymentDigest: digest })}\n\n`,
+        `data: ${JSON.stringify({
+          id: "chunk_1",
+          model: "windy-client-agent-v1",
+          choices: [
+            {
+              index: 0,
+              delta: {
+                tool_calls: [
+                  {
+                    index: 0,
+                    id: "call_1",
+                    function: { name: "click", arguments: '{"index":1}' },
+                  },
+                ],
+              },
+            },
+          ],
+        })}\n\n`,
+        "data: [DONE]\n\n",
+      ]);
+    });
+    const provider = remote(server);
+    expect(await provider.ready()).toBe(true);
+    const events = [];
+    for await (const event of provider.stream(
+      {
+        model: "client-cannot-forward-this",
+        messages: [{ role: "user", content: "打开详情" }],
+        tools: [
+          {
+            type: "function",
+            function: {
+              name: "click",
+              parameters: { type: "object" },
+            },
+          },
+        ],
+        stream: true,
+      },
+      context(),
+      new AbortController().signal,
+    )) {
+      events.push(event);
+    }
+
+    expect(events[0]).toEqual({ type: "meta", deploymentDigest: digest });
+    expect(JSON.stringify(events)).toContain("call_1");
+    expect(observed).not.toHaveProperty("model");
+    expect(observed).not.toHaveProperty("providerUrl");
+    expect(observed).not.toHaveProperty("apiKey");
+    expect(observed).toMatchObject({
+      deploymentKey: "ai.openai-compatible",
+      modelAlias: "windy-client-agent-v1",
+      clientRunId: "carun_1",
+    });
+  });
+
+  test("Provider 失败不泄漏响应 secret", async () => {
+    const server = serve(
+      () => new Response("upstream-secret-provider-key", { status: 500 }),
+    );
+    const provider = remote(server);
+    let captured: unknown;
+    try {
+      for await (const _event of provider.stream(
+        { messages: [{ role: "user", content: "hello" }] },
+        context(),
+        new AbortController().signal,
+      )) {
+        // consume
+      }
+    } catch (error) {
+      captured = error;
+    }
+    expect(String(captured)).not.toContain("upstream-secret-provider-key");
+    expect(captured).toMatchObject({ code: "PROVIDER_FAILED" });
+  });
+});
+
+function serve(handler: (request: Request) => Response | Promise<Response>) {
+  const server = Bun.serve({ port: 0, fetch: handler });
+  servers.push(server);
+  return server;
+}
+
+function remote(server: Server<unknown>) {
+  return new RemoteClientAgentProvider({
+    baseUrl: `http://localhost:${server.port}`,
+    internalToken: "internal-secret",
+  });
+}
+
+function context() {
+  return {
+    clientRunId: "carun_1",
+    operationKey: "page.agent",
+    deploymentKey: "ai.openai-compatible",
+    providerDataPolicy: policy,
+    attempt: 1,
+    maxResponseBytes: 65_536,
+  };
+}
+
+function sse(parts: string[]) {
+  return new Response(parts.join(""), {
+    headers: { "content-type": "text/event-stream" },
+  });
+}

package/template/apps/server/src/agent/client-session/remote-provider.ts

@@ -0,0 +1,216 @@
+import type { ModuleAiJsonValue } from "@southwind-ai/server-sdk";
+import type { ClientAgentProviderPort } from "./contracts.js";
+import { ClientAgentSessionError } from "./errors.js";
+import { validDigest } from "./digest.js";
+
+export interface RemoteClientAgentProviderOptions {
+  readonly baseUrl: string;
+  readonly internalToken: string;
+  readonly modelAlias?: string;
+}
+
+export class RemoteClientAgentProvider implements ClientAgentProviderPort {
+  readonly modelAlias: string;
+  readonly #baseUrl: string;
+
+  constructor(private readonly options: RemoteClientAgentProviderOptions) {
+    this.#baseUrl = normalizeInternalUrl(options.baseUrl);
+    this.modelAlias = options.modelAlias ?? "windy-client-agent-v1";
+    if (!options.internalToken.trim()) {
+      throw new Error("Agent Server 内部 Token 不能为空");
+    }
+  }
+
+  async ready(signal?: AbortSignal): Promise<boolean> {
+    try {
+      const response = await fetch(
+        `${this.#baseUrl}/api/internal/client-agent/health`,
+        {
+          headers: { authorization: `Bearer ${this.options.internalToken}` },
+          signal,
+        },
+      );
+      if (!response.ok) return false;
+      const value = record(await response.json());
+      return value.status === "ready";
+    } catch {
+      return false;
+    }
+  }
+
+  async *stream(
+    request: ModuleAiJsonValue,
+    context: Parameters<ClientAgentProviderPort["stream"]>[1],
+    signal: AbortSignal,
+  ): ReturnType<ClientAgentProviderPort["stream"]> {
+    const body = completionBody(request, context, this.modelAlias);
+    let response: Response;
+    try {
+      response = await fetch(
+        `${this.#baseUrl}/api/internal/client-agent/chat/completions`,
+        {
+          method: "POST",
+          headers: {
+            authorization: `Bearer ${this.options.internalToken}`,
+            "content-type": "application/json",
+            accept: "text/event-stream",
+          },
+          body: JSON.stringify(body),
+          signal,
+        },
+      );
+    } catch {
+      throw providerFailure(signal);
+    }
+    if (!response.ok) throw await remoteError(response);
+    if (!response.body) {
+      throw new ClientAgentSessionError(
+        "PROVIDER_FAILED",
+        "Agent Server 未返回响应流",
+        502,
+      );
+    }
+    for await (const frame of sseFrames(response.body, signal)) {
+      if (frame.data === "[DONE]") return;
+      const value = parseJson(frame.data);
+      if (frame.event === "windy.error") throw remoteStreamError(value);
+      if (frame.event === "windy.meta") {
+        const meta = record(value);
+        if (!validDigest(meta.deploymentDigest)) {
+          throw new Error("Agent Server deployment digest 无效");
+        }
+        yield { type: "meta", deploymentDigest: meta.deploymentDigest };
+        continue;
+      }
+      yield { type: "chunk", value };
+    }
+  }
+}
+
+function completionBody(
+  value: ModuleAiJsonValue,
+  context: Parameters<ClientAgentProviderPort["stream"]>[1],
+  modelAlias: string,
+) {
+  const request = record(value);
+  return {
+    clientRunId: context.clientRunId,
+    operationKey: context.operationKey,
+    deploymentKey: context.deploymentKey,
+    modelAlias,
+    attempt: context.attempt,
+    messages: request.messages,
+    ...(request.tools === undefined ? {} : { tools: request.tools }),
+    ...(request.tool_choice === undefined
+      ? {}
+      : { toolChoice: request.tool_choice }),
+    parallelToolCalls: false,
+    providerDataPolicy: context.providerDataPolicy,
+    maxResponseBytes: context.maxResponseBytes,
+  };
+}
+
+async function* sseFrames(
+  body: ReadableStream<Uint8Array>,
+  signal: AbortSignal,
+) {
+  const reader = body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+  try {
+    while (true) {
+      if (signal.aborted) throw providerFailure(signal);
+      const { done, value } = await reader.read();
+      buffer += decoder
+        .decode(value, { stream: !done })
+        .replaceAll("\r\n", "\n");
+      let boundary = buffer.indexOf("\n\n");
+      while (boundary >= 0) {
+        const raw = buffer.slice(0, boundary);
+        buffer = buffer.slice(boundary + 2);
+        const frame = parseFrame(raw);
+        if (frame) yield frame;
+        boundary = buffer.indexOf("\n\n");
+      }
+      if (done) break;
+    }
+  } finally {
+    await reader.cancel().catch(() => undefined);
+    reader.releaseLock();
+  }
+  if (buffer.trim()) throw new Error("Agent Server SSE 截断");
+}
+
+function parseFrame(raw: string): { event?: string; data: string } | undefined {
+  let event: string | undefined;
+  const data: string[] = [];
+  for (const line of raw.split("\n")) {
+    if (line.startsWith("event:")) event = line.slice(6).trim();
+    if (line.startsWith("data:")) data.push(line.slice(5).trimStart());
+  }
+  return data.length
+    ? { ...(event ? { event } : {}), data: data.join("\n") }
+    : undefined;
+}
+
+async function remoteError(
+  response: Response,
+): Promise<ClientAgentSessionError> {
+  const text = (await response.text()).slice(0, 16_384);
+  try {
+    return remoteStreamError(JSON.parse(text) as ModuleAiJsonValue);
+  } catch {
+    return new ClientAgentSessionError(
+      "PROVIDER_FAILED",
+      response.status === 429 ? "模型服务限流" : "Agent Server 调用失败",
+      response.status === 429 ? 429 : 502,
+    );
+  }
+}
+
+function remoteStreamError(value: ModuleAiJsonValue): ClientAgentSessionError {
+  const error = record(value);
+  const allowed = new Set(["FORBIDDEN", "RATE_LIMITED", "BUDGET_EXCEEDED"]);
+  const code =
+    typeof error.code === "string" && allowed.has(error.code)
+      ? error.code
+      : "PROVIDER_FAILED";
+  const publicCode = code === "FORBIDDEN" ? "FORBIDDEN" : "PROVIDER_FAILED";
+  return new ClientAgentSessionError(
+    publicCode,
+    code === "FORBIDDEN"
+      ? "模型请求被数据策略拒绝"
+      : code === "RATE_LIMITED"
+        ? "模型服务限流"
+        : code === "BUDGET_EXCEEDED"
+          ? "模型调用预算不足"
+          : "模型服务暂不可用",
+    code === "FORBIDDEN" ? 403 : code === "RATE_LIMITED" ? 429 : 502,
+  );
+}
+
+function providerFailure(signal: AbortSignal): ClientAgentSessionError {
+  return new ClientAgentSessionError(
+    "PROVIDER_FAILED",
+    signal.aborted ? "Provider 调用已取消" : "Agent Server 不可用",
+    signal.aborted ? 409 : 502,
+  );
+}
+
+function parseJson(value: string): ModuleAiJsonValue {
+  return JSON.parse(value) as ModuleAiJsonValue;
+}
+
+function record(value: unknown): Record<string, ModuleAiJsonValue> {
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    throw new Error("响应无效");
+  return value as Record<string, ModuleAiJsonValue>;
+}
+
+function normalizeInternalUrl(value: string): string {
+  const url = new URL(value);
+  if (!url.hostname || url.username || url.password || url.search || url.hash) {
+    throw new Error("Agent Server URL 无效");
+  }
+  return url.toString().replace(/\/$/u, "");
+}