create-windy 0.6.12 → 0.6.14

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

@@ -0,0 +1,299 @@
+import { randomUUID } from "node:crypto";
+import type { ModuleAiJsonValue } from "@southwind-ai/server-sdk";
+import type {
+  ClientAgentProviderPort,
+  ClientSessionAdmissionPort,
+  ClientSessionCaller,
+  ClientSessionRecord,
+  ClientSessionReceiptRecord,
+} from "./contracts.js";
+import { digestJson, digestText } from "./digest.js";
+import {
+  ClientAgentSessionError,
+  clientSessionConflict,
+  clientSessionInvalid,
+} from "./errors.js";
+import { OpenAiChunkAccumulator } from "./openai-stream.js";
+import { attemptKey, publicReceipt } from "./presentation.js";
+import type { ClientSessionRepository } from "./repository.js";
+import {
+  ClientAgentRequestError,
+  parseClientAgentCompletion,
+} from "./request.js";
+import { ProviderInputGovernanceError } from "../provider-input-governance.js";
+
+export type ClientAgentCompletionEvent =
+  | { readonly type: "chunk"; readonly value: ModuleAiJsonValue }
+  | {
+      readonly type: "complete";
+      readonly response: ModuleAiJsonValue;
+      readonly receipt: ReturnType<typeof publicReceipt>;
+    };
+
+export async function consumeClientAgentCompletion(
+  events: AsyncIterable<ClientAgentCompletionEvent>,
+) {
+  for await (const event of events) {
+    if (event.type === "complete") return event;
+  }
+  throw clientSessionConflict("Provider 未返回终末响应");
+}
+
+export async function runClientAgentCompletion(input: {
+  sessionId: string;
+  body: unknown;
+  caller: ClientSessionCaller;
+  signal?: AbortSignal;
+  current: ClientSessionRecord;
+  repository: ClientSessionRepository;
+  admission: ClientSessionAdmissionPort;
+  provider: ClientAgentProviderPort;
+  controllers: Map<string, AbortController>;
+  now: () => number;
+  audit: (
+    record: ClientSessionRecord,
+    outcome: "success" | "failure",
+    metadata: Readonly<Record<string, string | number | boolean>>,
+  ) => Promise<void> | void;
+  revokeAudit: (
+    record: ClientSessionRecord,
+    cause: "authorization-drift" | "ttl",
+  ) => Promise<void> | void;
+}) {
+  const parsed = parseCompletion(input.body, input.current);
+  const reserved = await input.repository.reserveAttempt({
+    sessionId: input.sessionId,
+    tokenHash: digestText(input.caller.token),
+    actorId: input.caller.actorId,
+    clientBindingDigest: input.caller.clientBindingDigest,
+    hostSessionDigest: input.caller.hostSessionDigest,
+    now: input.now(),
+  });
+  if (!reserved) {
+    throw clientSessionConflict("会话并发、步数或状态不允许新的模型调用");
+  }
+  const attempt = reserved.attemptCount;
+  const controller = new AbortController();
+  const key = attemptKey(input.sessionId, attempt);
+  input.controllers.set(key, controller);
+  const abort = () => controller.abort(input.signal?.reason);
+  input.signal?.addEventListener("abort", abort, { once: true });
+  let checking = false;
+  const watcher = setInterval(async () => {
+    if (checking || controller.signal.aborted) return;
+    checking = true;
+    try {
+      const cause =
+        input.current.expiresAt <= input.now()
+          ? "ttl"
+          : (await input.admission.reauthorize(
+                input.current,
+                input.caller.actorId,
+              ))
+            ? undefined
+            : "authorization-drift";
+      if (!cause) return;
+      const status = cause === "ttl" ? "expired" : "revoked";
+      const closed = await input.repository.transition(
+        input.sessionId,
+        "active",
+        status,
+      );
+      if (closed) await input.revokeAudit(closed, cause);
+      controller.abort(cause);
+    } catch {
+      controller.abort("authorization-check-failed");
+    } finally {
+      checking = false;
+    }
+  }, 250);
+  return {
+    stream: parsed.stream,
+    abort: () => controller.abort(),
+    events: completionEvents({
+      ...input,
+      parsed,
+      reserved,
+      attempt,
+      controller,
+      key,
+      abort,
+      watcher,
+    }),
+  };
+}
+
+async function* completionEvents(input: {
+  sessionId: string;
+  signal?: AbortSignal;
+  parsed: ReturnType<typeof parseCompletion>;
+  reserved: ClientSessionRecord;
+  attempt: number;
+  controller: AbortController;
+  key: string;
+  abort: () => void;
+  watcher: ReturnType<typeof setInterval>;
+  repository: ClientSessionRepository;
+  admission: ClientSessionAdmissionPort;
+  provider: ClientAgentProviderPort;
+  controllers: Map<string, AbortController>;
+  now: () => number;
+  audit: (
+    record: ClientSessionRecord,
+    outcome: "success" | "failure",
+    metadata: Readonly<Record<string, string | number | boolean>>,
+  ) => Promise<void> | void;
+}): AsyncGenerator<ClientAgentCompletionEvent> {
+  let settled = false;
+  let audited = false;
+  try {
+    const accumulator = new OpenAiChunkAccumulator(input.reserved.modelAlias);
+    let deploymentDigest: `sha256:${string}` | undefined;
+    let responseBytes = 0;
+    let usage: Readonly<Record<string, number>> = {};
+    for await (const event of input.provider.stream(
+      input.parsed.request,
+      {
+        clientRunId: input.reserved.clientRunId,
+        operationKey: input.reserved.operationKey,
+        deploymentKey: input.reserved.deploymentKey,
+        providerDataPolicy: input.reserved.providerDataPolicy,
+        attempt: input.attempt,
+        maxResponseBytes: input.reserved.limits.maxResponseBytes,
+      },
+      input.controller.signal,
+    )) {
+      if (input.controller.signal.aborted)
+        throw clientSessionConflict("模型调用已取消");
+      if (event.type === "meta") {
+        if (deploymentDigest) throw new Error("Provider meta 重复");
+        deploymentDigest = event.deploymentDigest;
+        continue;
+      }
+      if (!deploymentDigest) throw new Error("Provider meta 缺失");
+      responseBytes += new TextEncoder().encode(
+        JSON.stringify(event.value),
+      ).byteLength;
+      if (responseBytes > input.reserved.limits.maxResponseBytes) {
+        throw new ClientAgentSessionError(
+          "LIMIT_EXCEEDED",
+          "Provider 响应超过会话上限",
+          502,
+        );
+      }
+      accumulator.append(event.value);
+      usage = providerUsage(event.value) ?? usage;
+      if (input.parsed.stream) yield { type: "chunk", value: event.value };
+    }
+    if (!deploymentDigest) throw new Error("Provider meta 缺失");
+    const response = accumulator.result();
+    const receipt: ClientSessionReceiptRecord = {
+      receiptId: `receipt_${randomUUID()}`,
+      clientRunId: input.reserved.clientRunId,
+      actorId: input.reserved.actorId,
+      operationKey: input.reserved.operationKey,
+      releaseId: input.reserved.releaseId,
+      clientBindingDigest: input.reserved.clientBindingDigest,
+      attempt: input.attempt,
+      requestDigest: digestJson(input.parsed.request),
+      responseDigest: digestJson(response),
+      deploymentDigest,
+      issuedAt: input.now(),
+      canonicalResult: await input.admission.projectProviderResult(
+        input.reserved.operationKey,
+        response,
+      ),
+    };
+    if (!(await input.repository.completeAttempt(input.sessionId, receipt))) {
+      throw clientSessionConflict("模型响应到达时会话已关闭");
+    }
+    settled = true;
+    await input.audit(input.reserved, "success", {
+      attempt: input.attempt,
+      requestDigest: receipt.requestDigest,
+      responseDigest: receipt.responseDigest,
+      deploymentDigest: receipt.deploymentDigest,
+      responseBytes,
+      providerPolicy: "enforced",
+      ...usage,
+    });
+    audited = true;
+    yield { type: "complete", response, receipt: publicReceipt(receipt) };
+  } catch (error) {
+    await input.audit(input.reserved, "failure", {
+      attempt: input.attempt,
+      failure:
+        error instanceof ClientAgentSessionError
+          ? error.code
+          : "PROVIDER_FAILED",
+    });
+    audited = true;
+    if (error instanceof ClientAgentSessionError) throw error;
+    throw new ClientAgentSessionError(
+      "PROVIDER_FAILED",
+      input.controller.signal.aborted
+        ? "Provider 调用已取消"
+        : "Provider 调用失败",
+      input.controller.signal.aborted ? 409 : 502,
+    );
+  } finally {
+    if (!settled) {
+      await input.repository.failAttempt(input.sessionId, input.attempt);
+      if (!audited) {
+        await input.audit(input.reserved, "failure", {
+          attempt: input.attempt,
+          failure: input.controller.signal.aborted
+            ? "CANCELLED"
+            : "INTERRUPTED",
+        });
+      }
+    }
+    input.signal?.removeEventListener("abort", input.abort);
+    clearInterval(input.watcher);
+    input.controllers.delete(input.key);
+  }
+}
+
+function providerUsage(
+  value: ModuleAiJsonValue,
+): Readonly<Record<string, number>> | undefined {
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    return undefined;
+  const usage = value.usage;
+  if (!usage || typeof usage !== "object" || Array.isArray(usage))
+    return undefined;
+  const result: Record<string, number> = {};
+  const fields = {
+    inputTokens: usage.prompt_tokens,
+    outputTokens: usage.completion_tokens,
+    totalTokens: usage.total_tokens,
+  };
+  for (const [key, candidate] of Object.entries(fields)) {
+    if (Number.isSafeInteger(candidate) && Number(candidate) >= 0) {
+      result[key] = Number(candidate);
+    }
+  }
+  return result;
+}
+
+function parseCompletion(body: unknown, current: ClientSessionRecord) {
+  try {
+    return parseClientAgentCompletion(body, {
+      modelAlias: current.modelAlias,
+      maxRequestBytes: current.limits.maxRequestBytes,
+      providerDataPolicy: current.providerDataPolicy,
+    });
+  } catch (error) {
+    if (error instanceof ProviderInputGovernanceError) {
+      throw new ClientAgentSessionError(
+        error.code,
+        error.message,
+        error.code === "FORBIDDEN" ? 403 : 400,
+      );
+    }
+    if (error instanceof ClientAgentRequestError) {
+      throw clientSessionInvalid(error.message);
+    }
+    throw error;
+  }
+}

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

@@ -0,0 +1,136 @@
+import type {
+  AiClientExecutionPolicy,
+  AiProviderDataPolicy,
+} from "@southwind-ai/modules";
+import type { ModuleAiJsonValue } from "@southwind-ai/server-sdk";
+
+export type ClientSessionTerminalStatus =
+  | "completed"
+  | "cancelled"
+  | "revoked"
+  | "expired";
+export type ClientSessionStatus = "active" | ClientSessionTerminalStatus;
+
+export interface ClientSessionAdmission {
+  readonly actorId: string;
+  readonly operationKey: string;
+  readonly releaseId: string;
+  readonly inputCommitment: `sha256:${string}`;
+  readonly authorizationDigest: `sha256:${string}`;
+  readonly clientBindingDigest: `sha256:${string}`;
+  readonly deploymentKey: string;
+  readonly providerDataPolicy: AiProviderDataPolicy;
+  readonly limits: AiClientExecutionPolicy & {
+    readonly maxDurationSeconds: number;
+  };
+}
+
+export interface ClientSessionReceiptRecord {
+  readonly receiptId: string;
+  readonly clientRunId: string;
+  readonly actorId: string;
+  readonly operationKey: string;
+  readonly releaseId: string;
+  readonly clientBindingDigest: `sha256:${string}`;
+  readonly attempt: number;
+  readonly requestDigest: `sha256:${string}`;
+  readonly responseDigest: `sha256:${string}`;
+  readonly deploymentDigest: `sha256:${string}`;
+  readonly issuedAt: number;
+  readonly canonicalResult?: ModuleAiJsonValue;
+}
+
+export interface ClientSessionFinalResult {
+  readonly clientRunId: string;
+  readonly status: "completed";
+  readonly result: ModuleAiJsonValue;
+  readonly attestation: {
+    readonly source: "provider-observed" | "client-projected";
+    readonly terminalReceiptId: string;
+    readonly providerAttested: boolean;
+    readonly clientProjected: boolean;
+  };
+}
+
+export interface ClientSessionRecord extends ClientSessionAdmission {
+  readonly sessionId: string;
+  readonly clientRunId: string;
+  readonly tokenHash: `sha256:${string}`;
+  readonly hostSessionDigest: `sha256:${string}`;
+  readonly modelAlias: string;
+  readonly createdAt: number;
+  readonly expiresAt: number;
+  readonly status: ClientSessionStatus;
+  readonly attemptCount: number;
+  readonly activeRequests: number;
+  readonly pendingAttempts: readonly number[];
+  readonly receipts: readonly ClientSessionReceiptRecord[];
+  readonly terminalDigest?: `sha256:${string}`;
+  readonly finalResult?: ClientSessionFinalResult;
+}
+
+export interface ClientSessionCaller {
+  readonly token: string;
+  readonly actorId: string;
+  readonly clientBindingDigest: `sha256:${string}`;
+  readonly hostSessionDigest: `sha256:${string}`;
+}
+
+export interface ClientAgentProviderPort {
+  readonly modelAlias: string;
+  ready(signal?: AbortSignal): Promise<boolean>;
+  stream(
+    request: ModuleAiJsonValue,
+    context: {
+      readonly clientRunId: string;
+      readonly operationKey: string;
+      readonly deploymentKey: string;
+      readonly providerDataPolicy: AiProviderDataPolicy;
+      readonly attempt: number;
+      readonly maxResponseBytes: number;
+    },
+    signal: AbortSignal,
+  ): AsyncIterable<
+    | {
+        readonly type: "meta";
+        readonly deploymentDigest: `sha256:${string}`;
+      }
+    | { readonly type: "chunk"; readonly value: ModuleAiJsonValue }
+  >;
+}
+
+export interface ClientSessionAdmissionPort {
+  admit(input: {
+    readonly operationKey: string;
+    readonly input: ModuleAiJsonValue;
+    readonly clientBindingDigest: `sha256:${string}`;
+    readonly actorId: string;
+  }): Promise<ClientSessionAdmission>;
+  reauthorize(session: ClientSessionRecord, actorId: string): Promise<boolean>;
+  validateResult(
+    operationKey: string,
+    result: ModuleAiJsonValue,
+  ): Promise<void> | void;
+  projectProviderResult(
+    operationKey: string,
+    response: ModuleAiJsonValue,
+  ): Promise<ModuleAiJsonValue | undefined> | ModuleAiJsonValue | undefined;
+}
+
+export type ClientSessionAuditAction =
+  | "create"
+  | "provider-attempt"
+  | "finalize"
+  | "cancel"
+  | "revoke";
+
+export interface ClientSessionAuditPort {
+  record(input: {
+    readonly action: ClientSessionAuditAction;
+    readonly actorId: string;
+    readonly clientRunId: string;
+    readonly operationKey: string;
+    readonly outcome: "success" | "failure";
+    readonly metadata: Readonly<Record<string, string | number | boolean>>;
+  }): Promise<void> | void;
+}

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

@@ -0,0 +1,39 @@
+import { createHash, timingSafeEqual } from "node:crypto";
+import type { ModuleAiJsonValue } from "@southwind-ai/server-sdk";
+
+export function digestJson(value: ModuleAiJsonValue): `sha256:${string}` {
+  return digestText(canonicalJson(value));
+}
+
+export function digestText(value: string): `sha256:${string}` {
+  return `sha256:${createHash("sha256").update(value).digest("hex")}`;
+}
+
+export function validDigest(value: unknown): value is `sha256:${string}` {
+  return typeof value === "string" && /^sha256:[a-f0-9]{64}$/u.test(value);
+}
+
+export function sameSecret(left: string, right: string): boolean {
+  const leftBytes = Buffer.from(left);
+  const rightBytes = Buffer.from(right);
+  return (
+    leftBytes.length === rightBytes.length &&
+    timingSafeEqual(leftBytes, rightBytes)
+  );
+}
+
+function canonicalJson(value: ModuleAiJsonValue): string {
+  if (value === null || typeof value !== "object") {
+    if (typeof value === "number" && !Number.isFinite(value)) {
+      throw new TypeError("Client Agent JSON 不能包含非有限数值");
+    }
+    return JSON.stringify(value);
+  }
+  if (Array.isArray(value)) {
+    return `[${value.map(canonicalJson).join(",")}]`;
+  }
+  return `{${Object.keys(value)
+    .sort()
+    .map((key) => `${JSON.stringify(key)}:${canonicalJson(value[key]!)}`)
+    .join(",")}}`;
+}

package/template/apps/server/src/agent/client-session/drizzle-repository.integration.test.ts

@@ -0,0 +1,170 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { resolve } from "node:path";
+import { drizzle } from "drizzle-orm/node-postgres";
+import { migrate } from "drizzle-orm/node-postgres/migrator";
+import { Pool } from "pg";
+import type {
+  ClientSessionReceiptRecord,
+  ClientSessionRecord,
+} from "./contracts.js";
+import { DrizzleClientSessionRepository } from "./drizzle-repository.js";
+
+const databaseUrl = process.env.CLIENT_AGENT_TEST_DATABASE_URL;
+const describePostgres = databaseUrl ? describe : describe.skip;
+const binding = `sha256:${"b".repeat(64)}` as const;
+const hostSession = `sha256:${"e".repeat(64)}` as const;
+const tokenHash = `sha256:${"t".repeat(64)}` as const;
+
+describePostgres("PostgreSQL Client Agent Session repository", () => {
+  let pool: Pool;
+
+  beforeAll(async () => {
+    pool = new Pool({ connectionString: databaseUrl });
+    await migrate(drizzle(pool), {
+      migrationsFolder: resolve(
+        import.meta.dir,
+        "../../../../../packages/database/drizzle",
+      ),
+      migrationsSchema: "public",
+      migrationsTable: "__client_agent_test_migrations",
+    });
+    await pool.query(
+      "truncate table client_agent_receipts, client_agent_sessions",
+    );
+  });
+
+  afterAll(async () => {
+    await pool?.end();
+  });
+
+  test("重启恢复 session/receipt，且并发预留与终态保持原子", async () => {
+    const first = new DrizzleClientSessionRepository(drizzle(pool));
+    await first.create(session());
+    const [accepted, denied] = await Promise.all([
+      first.reserveAttempt(caller()),
+      first.reserveAttempt(caller()),
+    ]);
+    expect([accepted, denied].filter(Boolean)).toHaveLength(1);
+    expect([accepted, denied].filter((value) => !value)).toHaveLength(1);
+
+    const restarted = new DrizzleClientSessionRepository(drizzle(pool));
+    expect(await restarted.find("cas_1")).toMatchObject({
+      clientRunId: "carun_1",
+      attemptCount: 1,
+      activeRequests: 1,
+      tokenHash,
+    });
+    expect(await restarted.recoverInterrupted(2_500)).toBe(1);
+    expect(await restarted.find("cas_1")).toMatchObject({
+      activeRequests: 0,
+      pendingAttempts: [],
+      attemptCount: 1,
+    });
+    expect(
+      await restarted.reserveAttempt({ ...caller(), actorId: "actor-2" }),
+    ).toBeUndefined();
+    expect(
+      await restarted.reserveAttempt({
+        ...caller(),
+        hostSessionDigest: `sha256:${"x".repeat(64)}`,
+      }),
+    ).toBeUndefined();
+    expect(await restarted.reserveAttempt(caller())).toMatchObject({
+      attemptCount: 2,
+      activeRequests: 1,
+    });
+
+    const completed = await restarted.completeAttempt("cas_1", receipt());
+    expect(completed?.receipts).toHaveLength(1);
+    const afterReceipt = new DrizzleClientSessionRepository(drizzle(pool));
+    expect((await afterReceipt.find("cas_1"))?.receipts[0]).toEqual(receipt());
+
+    const terminal = await afterReceipt.transition(
+      "cas_1",
+      "active",
+      "completed",
+      {
+        terminalDigest: `sha256:${"f".repeat(64)}`,
+        finalResult: {
+          clientRunId: "carun_1",
+          status: "completed",
+          result: { answer: "完成" },
+          attestation: {
+            source: "provider-observed",
+            terminalReceiptId: "receipt_1",
+            providerAttested: true,
+            clientProjected: false,
+          },
+        },
+      },
+    );
+    expect(terminal?.status).toBe("completed");
+    expect(
+      await afterReceipt.transition("cas_1", "active", "cancelled"),
+    ).toBeUndefined();
+    expect((await first.find("cas_1"))?.finalResult?.result).toEqual({
+      answer: "完成",
+    });
+  });
+});
+
+function session(): ClientSessionRecord {
+  return {
+    sessionId: "cas_1",
+    clientRunId: "carun_1",
+    actorId: "actor-1",
+    operationKey: "support.answer",
+    releaseId: "release-1",
+    tokenHash,
+    inputCommitment: `sha256:${"i".repeat(64)}`,
+    authorizationDigest: `sha256:${"a".repeat(64)}`,
+    clientBindingDigest: binding,
+    hostSessionDigest: hostSession,
+    deploymentKey: "ai.openai-compatible",
+    providerDataPolicy: { inputFields: [], envelopeFields: [] },
+    limits: {
+      mode: "governed-session",
+      maxSteps: 4,
+      maxRequestBytes: 16_384,
+      maxResponseBytes: 16_384,
+      maxConcurrentRequests: 1,
+      maxDurationSeconds: 60,
+    },
+    modelAlias: "windy-client-agent-v1",
+    createdAt: 1_000,
+    expiresAt: 61_000,
+    status: "active",
+    attemptCount: 0,
+    activeRequests: 0,
+    pendingAttempts: [],
+    receipts: [],
+  };
+}
+
+function caller() {
+  return {
+    sessionId: "cas_1",
+    tokenHash,
+    actorId: "actor-1",
+    clientBindingDigest: binding,
+    hostSessionDigest: hostSession,
+    now: 2_000,
+  };
+}
+
+function receipt(): ClientSessionReceiptRecord {
+  return {
+    receiptId: "receipt_1",
+    clientRunId: "carun_1",
+    actorId: "actor-1",
+    operationKey: "support.answer",
+    releaseId: "release-1",
+    clientBindingDigest: binding,
+    attempt: 2,
+    requestDigest: `sha256:${"q".repeat(64)}`,
+    responseDigest: `sha256:${"r".repeat(64)}`,
+    deploymentDigest: `sha256:${"d".repeat(64)}`,
+    issuedAt: 3_000,
+    canonicalResult: { answer: "完成" },
+  };
+}