create-windy 0.6.11 → 0.6.14

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

@@ -0,0 +1,240 @@
+import Ajv, { type ValidateFunction } from "ajv";
+import type { ModuleManifest } from "@southwind-ai/modules";
+import type { ModuleAiJsonValue } from "@southwind-ai/server-sdk";
+import { evaluateAccessGuards } from "../../access-guards.js";
+import { captureAuthorizationScope } from "../../data-access/scope-snapshot.js";
+import type { RequestGuardContext } from "../../guards.js";
+import type { InitializedModuleHosts } from "../../module-host.js";
+import type { createServerRuntime } from "../../runtime.js";
+import {
+  governProviderInput,
+  projectProviderInput,
+  ProviderInputGovernanceError,
+} from "../provider-input-governance.js";
+import {
+  buildRegisteredOperations,
+  type RegisteredOperation,
+} from "../run-operation-registry.js";
+import type {
+  ClientSessionAdmissionPort,
+  ClientSessionRecord,
+} from "./contracts.js";
+import { digestJson, sameSecret } from "./digest.js";
+import { ClientAgentSessionError } from "./errors.js";
+
+type ServerRuntime = Pick<
+  ReturnType<typeof createServerRuntime>,
+  "recordDecisions" | "resolveFeature"
+>;
+
+export class ManifestClientSessionAdmission implements ClientSessionAdmissionPort {
+  readonly #operations: Map<string, RegisteredOperation>;
+  readonly #inputValidators = new Map<string, ValidateFunction>();
+  readonly #validators = new Map<string, ValidateFunction>();
+
+  constructor(
+    modules: readonly ModuleManifest[],
+    hosts: InitializedModuleHosts,
+    private readonly runtime: ServerRuntime,
+    private readonly resolveContext: (
+      actorId: string,
+    ) => Promise<RequestGuardContext>,
+  ) {
+    this.#operations = buildRegisteredOperations(modules, hosts);
+    const ajv = new Ajv({ allErrors: true, strict: true });
+    const schemas = new Map(
+      modules.flatMap(({ jsonSchemas }) =>
+        (jsonSchemas ?? []).map(({ key, schema }) => [key, schema] as const),
+      ),
+    );
+    for (const [key, operation] of this.#operations) {
+      const inputSchema = schemas.get(operation.definition.inputSchemaKey);
+      if (inputSchema) {
+        this.#inputValidators.set(key, ajv.compile(inputSchema));
+      }
+      if (operation.outputSchema) {
+        this.#validators.set(key, ajv.compile(operation.outputSchema));
+      }
+    }
+  }
+
+  async admit(input: {
+    operationKey: string;
+    input: ModuleAiJsonValue;
+    clientBindingDigest: `sha256:${string}`;
+    actorId: string;
+  }) {
+    const operation = this.operation(input.operationKey);
+    const context = await this.resolveContext(input.actorId);
+    await this.authorize(operation, context, input.actorId);
+    const inputBytes = new TextEncoder().encode(
+      JSON.stringify(input.input),
+    ).byteLength;
+    if (
+      inputBytes > operation.definition.limits.maxInputBytes ||
+      !this.#inputValidators.get(input.operationKey)?.(input.input)
+    ) {
+      throw new ClientAgentSessionError(
+        "INVALID_INPUT",
+        "Client Agent 输入不符合 Operation schema 或字节上限",
+        400,
+      );
+    }
+    const policy = operation.definition.providerDataPolicy!;
+    try {
+      governProviderInput(input.input, policy);
+    } catch (error) {
+      if (error instanceof ProviderInputGovernanceError) {
+        throw new ClientAgentSessionError(
+          error.code,
+          error.message,
+          error.code === "FORBIDDEN" ? 403 : 400,
+        );
+      }
+      throw error;
+    }
+    return {
+      actorId: input.actorId,
+      operationKey: input.operationKey,
+      releaseId: operation.release.releaseId,
+      inputCommitment: digestJson(projectProviderInput(input.input, policy)),
+      authorizationDigest: authorizationDigest(context, operation),
+      clientBindingDigest: input.clientBindingDigest,
+      deploymentKey: configuredDeploymentKey(operation),
+      providerDataPolicy: policy,
+      limits: {
+        ...operation.definition.clientExecution!,
+        maxDurationSeconds: operation.definition.limits.maxDurationSeconds,
+      },
+    };
+  }
+
+  async reauthorize(
+    session: ClientSessionRecord,
+    actorId: string,
+  ): Promise<boolean> {
+    try {
+      const operation = this.operation(session.operationKey);
+      if (operation.release.releaseId !== session.releaseId) return false;
+      const context = await this.resolveContext(actorId);
+      await this.authorize(operation, context, actorId);
+      return sameSecret(
+        authorizationDigest(context, operation),
+        session.authorizationDigest,
+      );
+    } catch {
+      return false;
+    }
+  }
+
+  validateResult(operationKey: string, result: ModuleAiJsonValue): void {
+    const validate = this.#validators.get(operationKey);
+    if (!validate || !validate(result)) {
+      throw new ClientAgentSessionError(
+        "INVALID_INPUT",
+        "Client Agent 公开结果不符合 Operation output schema",
+        400,
+      );
+    }
+  }
+
+  projectProviderResult(
+    operationKey: string,
+    response: ModuleAiJsonValue,
+  ): ModuleAiJsonValue | undefined {
+    const content = firstAssistantContent(response);
+    if (content === undefined) return undefined;
+    const candidates: ModuleAiJsonValue[] = [];
+    try {
+      candidates.push(JSON.parse(content) as ModuleAiJsonValue);
+    } catch {
+      candidates.push({ text: content });
+    }
+    const validate = this.#validators.get(operationKey);
+    return candidates.find((candidate) => validate?.(candidate));
+  }
+
+  private operation(operationKey: string): RegisteredOperation {
+    const operation = this.#operations.get(operationKey);
+    if (
+      !operation ||
+      operation.definition.kind !== "agent" ||
+      !operation.definition.clientExecution ||
+      operation.definition.providerEgress?.mode !== "configured-endpoint" ||
+      !operation.definition.providerDataPolicy
+    ) {
+      throw new ClientAgentSessionError(
+        "FORBIDDEN",
+        "Operation 未开放 Client Agent Session",
+        403,
+      );
+    }
+    return operation;
+  }
+
+  private async authorize(
+    operation: RegisteredOperation,
+    context: RequestGuardContext,
+    actorId: string,
+  ): Promise<void> {
+    if (context.actor.id !== actorId || context.actor.type === "anonymous") {
+      throw new ClientAgentSessionError("FORBIDDEN", "Actor 认证失效", 403);
+    }
+    const decision = await evaluateAccessGuards(this.runtime, context, {
+      permission: { permissionKey: operation.definition.permissionKey },
+      feature: operation.feature,
+    });
+    if (!decision.decision.allowed) {
+      throw new ClientAgentSessionError(
+        "FORBIDDEN",
+        "无权执行 Client Agent Operation",
+        403,
+      );
+    }
+  }
+}
+
+function configuredDeploymentKey(operation: RegisteredOperation): string {
+  const egress = operation.definition.providerEgress;
+  if (egress?.mode !== "configured-endpoint") {
+    throw new ClientAgentSessionError(
+      "FORBIDDEN",
+      "Operation 未配置 Provider Deployment",
+      403,
+    );
+  }
+  return egress.deploymentKey;
+}
+
+function authorizationDigest(
+  context: RequestGuardContext,
+  operation: RegisteredOperation,
+): `sha256:${string}` {
+  return digestJson({
+    actorId: context.actor.id,
+    permissionKey: operation.definition.permissionKey,
+    featureKey: operation.definition.featureKey,
+    permissionKeys: [...context.actor.permissionKeys].sort(),
+    scopeHash: captureAuthorizationScope(context.actor.scopeContext).hash,
+    licenseVersion: context.license?.versionKey ?? null,
+    licenseStatus: context.license?.status ?? null,
+    releaseId: operation.release.releaseId,
+  });
+}
+
+function firstAssistantContent(
+  response: ModuleAiJsonValue,
+): string | undefined {
+  if (!isRecord(response) || !Array.isArray(response.choices)) return undefined;
+  const first = response.choices[0];
+  if (!isRecord(first) || !isRecord(first.message)) return undefined;
+  return typeof first.message.content === "string"
+    ? first.message.content
+    : undefined;
+}
+
+function isRecord(
+  value: ModuleAiJsonValue,
+): value is Record<string, ModuleAiJsonValue> {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}

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" },
+  });
+}