create-windy 0.6.14 → 0.6.16

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

@@ -3,6 +3,7 @@ import type { ModuleAiJsonValue } from "@southwind-ai/server-sdk";
 import type {
   ClientAgentProviderPort,
   ClientSessionAdmissionPort,
+  ClientSessionAttemptAuthorityChecker,
   ClientSessionCaller,
   ClientSessionRecord,
   ClientSessionReceiptRecord,
@@ -21,6 +22,11 @@ import {
   parseClientAgentCompletion,
 } from "./request.js";
 import { ProviderInputGovernanceError } from "../provider-input-governance.js";
+import {
+  enforceClientSessionAttemptAuthority,
+  enforceClientSessionProviderBoundary,
+  type ClientSessionAttemptRevocationCause,
+} from "./attempt-authority.js";
 
 export type ClientAgentCompletionEvent =
   | { readonly type: "chunk"; readonly value: ModuleAiJsonValue }
@@ -45,6 +51,7 @@ export async function runClientAgentCompletion(input: {
   caller: ClientSessionCaller;
   signal?: AbortSignal;
   current: ClientSessionRecord;
+  attemptAuthority: ClientSessionAttemptAuthorityChecker;
   repository: ClientSessionRepository;
   admission: ClientSessionAdmissionPort;
   provider: ClientAgentProviderPort;
@@ -57,10 +64,18 @@ export async function runClientAgentCompletion(input: {
   ) => Promise<void> | void;
   revokeAudit: (
     record: ClientSessionRecord,
-    cause: "authorization-drift" | "ttl",
+    cause: ClientSessionAttemptRevocationCause,
   ) => Promise<void> | void;
 }) {
   const parsed = parseCompletion(input.body, input.current);
+  const workflowOwned = await enforceClientSessionAttemptAuthority({
+    checker: input.attemptAuthority,
+    record: input.current,
+    repository: input.repository,
+    ...(input.signal ? { signal: input.signal } : {}),
+    workflowOwned: false,
+    audit: input.revokeAudit,
+  });
   const reserved = await input.repository.reserveAttempt({
     sessionId: input.sessionId,
     tokenHash: digestText(input.caller.token),
@@ -83,24 +98,16 @@ export async function runClientAgentCompletion(input: {
     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);
+      await enforceClientSessionProviderBoundary({
+        admission: input.admission,
+        checker: input.attemptAuthority,
+        record: reserved,
+        repository: input.repository,
+        now: input.now(),
+        signal: controller.signal,
+        workflowOwned,
+        audit: input.revokeAudit,
+      });
     } catch {
       controller.abort("authorization-check-failed");
     } finally {
@@ -112,6 +119,7 @@ export async function runClientAgentCompletion(input: {
     abort: () => controller.abort(),
     events: completionEvents({
       ...input,
+      workflowOwned,
       parsed,
       reserved,
       attempt,
@@ -135,6 +143,8 @@ async function* completionEvents(input: {
   watcher: ReturnType<typeof setInterval>;
   repository: ClientSessionRepository;
   admission: ClientSessionAdmissionPort;
+  attemptAuthority: ClientSessionAttemptAuthorityChecker;
+  workflowOwned: boolean;
   provider: ClientAgentProviderPort;
   controllers: Map<string, AbortController>;
   now: () => number;
@@ -143,6 +153,10 @@ async function* completionEvents(input: {
     outcome: "success" | "failure",
     metadata: Readonly<Record<string, string | number | boolean>>,
   ) => Promise<void> | void;
+  revokeAudit: (
+    record: ClientSessionRecord,
+    cause: ClientSessionAttemptRevocationCause,
+  ) => Promise<void> | void;
 }): AsyncGenerator<ClientAgentCompletionEvent> {
   let settled = false;
   let audited = false;
@@ -151,6 +165,17 @@ async function* completionEvents(input: {
     let deploymentDigest: `sha256:${string}` | undefined;
     let responseBytes = 0;
     let usage: Readonly<Record<string, number>> = {};
+    await enforceClientSessionProviderBoundary({
+      admission: input.admission,
+      checker: input.attemptAuthority,
+      record: input.reserved,
+      repository: input.repository,
+      attempt: input.attempt,
+      now: input.now(),
+      signal: input.controller.signal,
+      workflowOwned: input.workflowOwned,
+      audit: input.revokeAudit,
+    });
     for await (const event of input.provider.stream(
       input.parsed.request,
       {
@@ -187,6 +212,21 @@ async function* completionEvents(input: {
     }
     if (!deploymentDigest) throw new Error("Provider meta 缺失");
     const response = accumulator.result();
+    await enforceClientSessionProviderBoundary({
+      admission: input.admission,
+      checker: input.attemptAuthority,
+      record: input.reserved,
+      repository: input.repository,
+      attempt: input.attempt,
+      now: input.now(),
+      signal: input.controller.signal,
+      workflowOwned: input.workflowOwned,
+      audit: input.revokeAudit,
+    });
+    const canonicalResult = await input.admission.projectProviderResult(
+      input.reserved.operationKey,
+      response,
+    );
     const receipt: ClientSessionReceiptRecord = {
       receiptId: `receipt_${randomUUID()}`,
       clientRunId: input.reserved.clientRunId,
@@ -199,12 +239,23 @@ async function* completionEvents(input: {
       responseDigest: digestJson(response),
       deploymentDigest,
       issuedAt: input.now(),
-      canonicalResult: await input.admission.projectProviderResult(
-        input.reserved.operationKey,
-        response,
-      ),
+      canonicalResult,
     };
-    if (!(await input.repository.completeAttempt(input.sessionId, receipt))) {
+    const committed = await input.repository.completeAttempt(
+      input.sessionId,
+      receipt,
+    );
+    if (!committed) {
+      if (input.workflowOwned) {
+        await enforceClientSessionAttemptAuthority({
+          checker: input.attemptAuthority,
+          record: input.reserved,
+          repository: input.repository,
+          signal: input.controller.signal,
+          workflowOwned: true,
+          audit: input.revokeAudit,
+        });
+      }
       throw clientSessionConflict("模型响应到达时会话已关闭");
     }
     settled = true;

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

@@ -76,6 +76,28 @@ export interface ClientSessionCaller {
   readonly hostSessionDigest: `sha256:${string}`;
 }
 
+export type ClientSessionAttemptAuthorityDecision =
+  | "ordinary"
+  | "current"
+  | "revoked";
+
+export interface ClientSessionAttemptAuthorityFacts {
+  readonly sessionId: string;
+  readonly clientRunId: string;
+  readonly actorId: string;
+  readonly operationKey: string;
+  readonly clientBindingDigest: `sha256:${string}`;
+  readonly hostSessionDigest: `sha256:${string}`;
+}
+
+/** Host checker 必须从 canonical Workflow/command/fence 事实判定，不接受浏览器声明。 */
+export interface ClientSessionAttemptAuthorityChecker {
+  check(
+    facts: ClientSessionAttemptAuthorityFacts,
+    signal?: AbortSignal,
+  ): Promise<ClientSessionAttemptAuthorityDecision>;
+}
+
 export interface ClientAgentProviderPort {
   readonly modelAlias: string;
   ready(signal?: AbortSignal): Promise<boolean>;
@@ -105,6 +127,7 @@ export interface ClientSessionAdmissionPort {
     readonly input: ModuleAiJsonValue;
     readonly clientBindingDigest: `sha256:${string}`;
     readonly actorId: string;
+    readonly launchAuthority: "direct" | "workflow-artifact";
   }): Promise<ClientSessionAdmission>;
   reauthorize(session: ClientSessionRecord, actorId: string): Promise<boolean>;
   validateResult(

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

@@ -0,0 +1,103 @@
+import { randomBytes, randomUUID } from "node:crypto";
+import type { ModuleAiJsonValue } from "@southwind-ai/server-sdk";
+import type {
+  ClientAgentProviderPort,
+  ClientSessionAdmissionPort,
+  ClientSessionRecord,
+} from "./contracts.js";
+import { digestText, validDigest } from "./digest.js";
+import { ClientAgentSessionError, clientSessionInvalid } from "./errors.js";
+import { ensureTrailingSlash, publicLimits } from "./presentation.js";
+import type { ClientSessionRepository } from "./repository.js";
+
+export async function createClientAgentSession(input: {
+  readonly request: {
+    operationKey: string;
+    input: ModuleAiJsonValue;
+    clientBindingDigest: string;
+    hostSessionDigest: `sha256:${string}`;
+    actorId: string;
+  };
+  readonly launchAuthority: "direct" | "workflow-artifact";
+  readonly recovery: Promise<number>;
+  readonly provider: ClientAgentProviderPort;
+  readonly admission: ClientSessionAdmissionPort;
+  readonly repository: ClientSessionRepository;
+  readonly trustedBaseUrl: string;
+  readonly now: () => number;
+  readonly maxTtlMs: number;
+  readonly audit: (
+    record: ClientSessionRecord,
+    metadata: Readonly<Record<string, string>>,
+  ) => Promise<void>;
+}) {
+  await input.recovery;
+  if (!(await input.provider.ready())) {
+    throw new ClientAgentSessionError(
+      "PROVIDER_FAILED",
+      "Client Agent Provider 尚未就绪",
+      503,
+    );
+  }
+  const request = input.request;
+  if (
+    !validDigest(request.clientBindingDigest) ||
+    !validDigest(request.hostSessionDigest) ||
+    !request.actorId.trim()
+  ) {
+    throw clientSessionInvalid("Client Agent binding 或 Actor 无效");
+  }
+  const admission = await input.admission.admit({
+    operationKey: request.operationKey,
+    input: request.input,
+    actorId: request.actorId,
+    clientBindingDigest: request.clientBindingDigest,
+    launchAuthority: input.launchAuthority,
+  });
+  if (
+    admission.actorId !== request.actorId ||
+    admission.operationKey !== request.operationKey ||
+    admission.clientBindingDigest !== request.clientBindingDigest
+  ) {
+    throw new Error("Client Agent admission 返回了不一致的绑定");
+  }
+  const createdAt = input.now();
+  const expiresAt =
+    createdAt +
+    Math.min(admission.limits.maxDurationSeconds * 1_000, input.maxTtlMs);
+  const accessToken = `car_${randomBytes(32).toString("base64url")}`;
+  const record: ClientSessionRecord = {
+    ...admission,
+    sessionId: `cas_${randomUUID()}`,
+    clientRunId: `carun_${randomUUID()}`,
+    tokenHash: digestText(accessToken),
+    hostSessionDigest: request.hostSessionDigest,
+    modelAlias: input.provider.modelAlias,
+    createdAt,
+    expiresAt,
+    status: "active",
+    attemptCount: 0,
+    activeRequests: 0,
+    pendingAttempts: [],
+    receipts: [],
+  };
+  await input.repository.create(record);
+  await input.audit(record, {
+    inputCommitment: record.inputCommitment,
+    authorizationDigest: record.authorizationDigest,
+    bindingDigest: record.clientBindingDigest,
+  });
+  return {
+    clientRunId: record.clientRunId,
+    sessionId: record.sessionId,
+    trustedBaseUrl: new URL(
+      `${encodeURIComponent(record.sessionId)}/v1/`,
+      ensureTrailingSlash(input.trustedBaseUrl),
+    ).toString(),
+    modelAlias: record.modelAlias,
+    limits: publicLimits(record),
+    expiresAt: new Date(record.expiresAt).toISOString(),
+    accessToken,
+    capabilities: ["pageAgentClientRun"] as const,
+  };
+}

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

@@ -5,6 +5,16 @@ export function digestJson(value: ModuleAiJsonValue): `sha256:${string}` {
   return digestText(canonicalJson(value));
 }
 
+export function clientSessionTerminalDigest(
+  receiptIds: readonly string[],
+  clientResult?: ModuleAiJsonValue,
+): `sha256:${string}` {
+  return digestJson({
+    receiptIds: [...receiptIds],
+    ...(clientResult === undefined ? {} : { result: clientResult }),
+  });
+}
+
 export function digestText(value: string): `sha256:${string}` {
   return `sha256:${createHash("sha256").update(value).digest("hex")}`;
 }
@@ -22,7 +32,7 @@ export function sameSecret(left: string, right: string): boolean {
   );
 }
 
-function canonicalJson(value: ModuleAiJsonValue): string {
+export function canonicalJson(value: ModuleAiJsonValue): string {
   if (value === null || typeof value !== "object") {
     if (typeof value === "number" && !Number.isFinite(value)) {
       throw new TypeError("Client Agent JSON 不能包含非有限数值");

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

@@ -0,0 +1,150 @@
+import {
+  clientAgentReceipts,
+  clientAgentSessions,
+} from "@southwind-ai/database";
+import type { ModuleAiJsonValue } from "@southwind-ai/server-sdk";
+import { asc, eq } from "drizzle-orm";
+import type { NodePgDatabase } from "drizzle-orm/node-postgres";
+import type {
+  ClientSessionAdmission,
+  ClientSessionFinalResult,
+  ClientSessionReceiptRecord,
+  ClientSessionRecord,
+  ClientSessionStatus,
+} from "./contracts.js";
+
+type SessionRow = typeof clientAgentSessions.$inferSelect;
+type ReceiptRow = typeof clientAgentReceipts.$inferSelect;
+
+export async function findClientSessionRecord(
+  db: NodePgDatabase,
+  sessionId: string,
+) {
+  const [row] = await db
+    .select()
+    .from(clientAgentSessions)
+    .where(eq(clientAgentSessions.sessionId, sessionId))
+    .limit(1);
+  return row ? hydrateClientSessionRecord(db, row) : undefined;
+}
+
+export async function hydrateClientSessionRecord(
+  db: NodePgDatabase,
+  row: SessionRow,
+) {
+  const receipts = await db
+    .select()
+    .from(clientAgentReceipts)
+    .where(eq(clientAgentReceipts.sessionId, row.sessionId))
+    .orderBy(asc(clientAgentReceipts.attempt));
+  return mapClientSessionRecord(row, receipts.map(mapReceipt));
+}
+
+export function clientSessionValues(record: ClientSessionRecord) {
+  const admission: ClientSessionAdmission = {
+    actorId: record.actorId,
+    operationKey: record.operationKey,
+    releaseId: record.releaseId,
+    inputCommitment: record.inputCommitment,
+    authorizationDigest: record.authorizationDigest,
+    clientBindingDigest: record.clientBindingDigest,
+    deploymentKey: record.deploymentKey,
+    providerDataPolicy: record.providerDataPolicy,
+    limits: record.limits,
+  };
+  return {
+    sessionId: record.sessionId,
+    clientRunId: record.clientRunId,
+    actorId: record.actorId,
+    operationKey: record.operationKey,
+    releaseId: record.releaseId,
+    tokenHash: record.tokenHash,
+    clientBindingDigest: record.clientBindingDigest,
+    hostSessionDigest: record.hostSessionDigest,
+    modelAlias: record.modelAlias,
+    status: record.status,
+    attemptCount: record.attemptCount,
+    activeRequests: record.activeRequests,
+    pendingAttempts: [...record.pendingAttempts],
+    admissionJson: admission as unknown as Record<string, unknown>,
+    terminalDigest: record.terminalDigest,
+    finalResultJson: record.finalResult as Record<string, unknown> | undefined,
+    createdAt: record.createdAt,
+    expiresAt: record.expiresAt,
+  };
+}
+
+export function mapClientSessionRecord(
+  row: SessionRow,
+  receipts: readonly ClientSessionReceiptRecord[],
+): ClientSessionRecord {
+  const admission = row.admissionJson as unknown as ClientSessionAdmission;
+  return {
+    ...admission,
+    sessionId: row.sessionId,
+    clientRunId: row.clientRunId,
+    actorId: row.actorId,
+    operationKey: row.operationKey,
+    releaseId: row.releaseId,
+    tokenHash: row.tokenHash as `sha256:${string}`,
+    clientBindingDigest: row.clientBindingDigest as `sha256:${string}`,
+    hostSessionDigest: row.hostSessionDigest as `sha256:${string}`,
+    modelAlias: row.modelAlias,
+    status: row.status as ClientSessionStatus,
+    attemptCount: row.attemptCount,
+    activeRequests: row.activeRequests,
+    pendingAttempts: row.pendingAttempts,
+    receipts,
+    createdAt: row.createdAt,
+    expiresAt: row.expiresAt,
+    ...(row.terminalDigest
+      ? { terminalDigest: row.terminalDigest as `sha256:${string}` }
+      : {}),
+    ...(row.finalResultJson
+      ? {
+          finalResult:
+            row.finalResultJson as unknown as ClientSessionFinalResult,
+        }
+      : {}),
+  };
+}
+
+export function clientSessionReceiptValues(
+  sessionId: string,
+  receipt: ClientSessionReceiptRecord,
+) {
+  return {
+    receiptId: receipt.receiptId,
+    sessionId,
+    clientRunId: receipt.clientRunId,
+    actorId: receipt.actorId,
+    operationKey: receipt.operationKey,
+    releaseId: receipt.releaseId,
+    clientBindingDigest: receipt.clientBindingDigest,
+    attempt: receipt.attempt,
+    requestDigest: receipt.requestDigest,
+    responseDigest: receipt.responseDigest,
+    deploymentDigest: receipt.deploymentDigest,
+    canonicalResultJson: receipt.canonicalResult,
+    issuedAt: receipt.issuedAt,
+  };
+}
+
+function mapReceipt(row: ReceiptRow): ClientSessionReceiptRecord {
+  return {
+    receiptId: row.receiptId,
+    clientRunId: row.clientRunId,
+    actorId: row.actorId,
+    operationKey: row.operationKey,
+    releaseId: row.releaseId,
+    clientBindingDigest: row.clientBindingDigest as `sha256:${string}`,
+    attempt: row.attempt,
+    requestDigest: row.requestDigest as `sha256:${string}`,
+    responseDigest: row.responseDigest as `sha256:${string}`,
+    deploymentDigest: row.deploymentDigest as `sha256:${string}`,
+    issuedAt: row.issuedAt,
+    ...(row.canonicalResultJson === null
+      ? {}
+      : { canonicalResult: row.canonicalResultJson as ModuleAiJsonValue }),
+  };
+}

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

@@ -8,6 +8,7 @@ import type {
   ClientSessionRecord,
 } from "./contracts.js";
 import { DrizzleClientSessionRepository } from "./drizzle-repository.js";
+import { ClientSessionAttemptAuthorityBinding } from "./attempt-authority.js";
 
 const databaseUrl = process.env.CLIENT_AGENT_TEST_DATABASE_URL;
 const describePostgres = databaseUrl ? describe : describe.skip;
@@ -38,7 +39,25 @@ describePostgres("PostgreSQL Client Agent Session repository", () => {
   });
 
   test("重启恢复 session/receipt，且并发预留与终态保持原子", async () => {
-    const first = new DrizzleClientSessionRepository(drizzle(pool));
+    let transactionAuthorityChecks = 0;
+    const commitNow = 3_000;
+    const authority = new ClientSessionAttemptAuthorityBinding();
+    authority.bind({
+      async check() {
+        return "ordinary";
+      },
+      async checkTransaction(transaction, _facts, now) {
+        expect(transaction).toBeDefined();
+        expect(now).toBe(commitNow);
+        transactionAuthorityChecks += 1;
+        return "ordinary";
+      },
+    });
+    const first = new DrizzleClientSessionRepository(
+      drizzle(pool),
+      authority,
+      () => commitNow,
+    );
     await first.create(session());
     const [accepted, denied] = await Promise.all([
       first.reserveAttempt(caller()),
@@ -47,7 +66,11 @@ describePostgres("PostgreSQL Client Agent Session repository", () => {
     expect([accepted, denied].filter(Boolean)).toHaveLength(1);
     expect([accepted, denied].filter((value) => !value)).toHaveLength(1);
 
-    const restarted = new DrizzleClientSessionRepository(drizzle(pool));
+    const restarted = new DrizzleClientSessionRepository(
+      drizzle(pool),
+      authority,
+      () => commitNow,
+    );
     expect(await restarted.find("cas_1")).toMatchObject({
       clientRunId: "carun_1",
       attemptCount: 1,
@@ -75,8 +98,12 @@ describePostgres("PostgreSQL Client Agent Session repository", () => {
     });
 
     const completed = await restarted.completeAttempt("cas_1", receipt());
+    expect(transactionAuthorityChecks).toBe(1);
     expect(completed?.receipts).toHaveLength(1);
-    const afterReceipt = new DrizzleClientSessionRepository(drizzle(pool));
+    const afterReceipt = new DrizzleClientSessionRepository(
+      drizzle(pool),
+      authority,
+    );
     expect((await afterReceipt.find("cas_1"))?.receipts[0]).toEqual(receipt());
 
     const terminal = await afterReceipt.transition(