create-windy 0.6.14 → 0.6.16

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

@@ -2,24 +2,33 @@ import {
   clientAgentReceipts,
   clientAgentSessions,
 } from "@southwind-ai/database";
-import type { ModuleAiJsonValue } from "@southwind-ai/server-sdk";
-import { and, asc, eq, sql } from "drizzle-orm";
+import { and, eq, sql } from "drizzle-orm";
 import type { NodePgDatabase } from "drizzle-orm/node-postgres";
 import type {
-  ClientSessionAdmission,
-  ClientSessionFinalResult,
   ClientSessionReceiptRecord,
   ClientSessionRecord,
   ClientSessionStatus,
 } from "./contracts.js";
 import { receiptMatches, type ClientSessionRepository } from "./repository.js";
 import { sameSecret } from "./digest.js";
-
-type SessionRow = typeof clientAgentSessions.$inferSelect;
-type ReceiptRow = typeof clientAgentReceipts.$inferSelect;
+import {
+  clientSessionAttemptAuthorityFacts,
+  type ClientSessionAttemptAuthorityBinding,
+} from "./attempt-authority.js";
+import {
+  clientSessionReceiptValues as receiptValues,
+  clientSessionValues as sessionValues,
+  findClientSessionRecord as findRecord,
+  hydrateClientSessionRecord as hydrateRecord,
+  mapClientSessionRecord as mapRecord,
+} from "./drizzle-records.js";
 
 export class DrizzleClientSessionRepository implements ClientSessionRepository {
-  constructor(private readonly db: NodePgDatabase) {}
+  constructor(
+    private readonly db: NodePgDatabase,
+    private readonly attemptAuthority?: ClientSessionAttemptAuthorityBinding,
+    private readonly now: () => number = Date.now,
+  ) {}
 
   async recoverInterrupted(now: number): Promise<number> {
     return this.db.transaction(async (transaction) => {
@@ -101,6 +110,12 @@ export class DrizzleClientSessionRepository implements ClientSessionRepository {
       ) {
         return undefined;
       }
+      const authority = await this.attemptAuthority?.checkTransaction(
+        db,
+        clientSessionAttemptAuthorityFacts(record),
+        this.now(),
+      );
+      if (authority === "revoked") return undefined;
       await db
         .insert(clientAgentReceipts)
         .values(receiptValues(sessionId, receipt));
@@ -219,127 +234,3 @@ export class DrizzleClientSessionRepository implements ClientSessionRepository {
     });
   }
 }
-
-async function findRecord(db: NodePgDatabase, sessionId: string) {
-  const [row] = await db
-    .select()
-    .from(clientAgentSessions)
-    .where(eq(clientAgentSessions.sessionId, sessionId))
-    .limit(1);
-  return row ? hydrateRecord(db, row) : undefined;
-}
-
-async function hydrateRecord(db: NodePgDatabase, row: SessionRow) {
-  const receipts = await db
-    .select()
-    .from(clientAgentReceipts)
-    .where(eq(clientAgentReceipts.sessionId, row.sessionId))
-    .orderBy(asc(clientAgentReceipts.attempt));
-  return mapRecord(row, receipts.map(mapReceipt));
-}
-
-function sessionValues(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,
-  };
-}
-
-function mapRecord(
-  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,
-        }
-      : {}),
-  };
-}
-
-function receiptValues(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/finalization.ts

@@ -0,0 +1,99 @@
+import type { ModuleAiJsonValue } from "@southwind-ai/server-sdk";
+import type {
+  ClientSessionAdmissionPort,
+  ClientSessionFinalResult,
+  ClientSessionRecord,
+} from "./contracts.js";
+import { clientSessionTerminalDigest } from "./digest.js";
+import {
+  clientSessionConflict as conflict,
+  clientSessionInvalid as invalid,
+} from "./errors.js";
+import { sessionView } from "./presentation.js";
+import type { ClientSessionRepository } from "./repository.js";
+
+export async function finalizeClientSession(input: {
+  record: ClientSessionRecord;
+  repository: ClientSessionRepository;
+  admission: ClientSessionAdmissionPort;
+  receiptIds: readonly string[];
+  clientResult?: ModuleAiJsonValue;
+  canonicalizeResult?: (
+    proposedResult: ModuleAiJsonValue,
+  ) => Promise<ModuleAiJsonValue>;
+  audit(
+    record: ClientSessionRecord,
+    metadata: Readonly<Record<string, string | number | boolean>>,
+  ): Promise<void> | void;
+}) {
+  const terminalDigest = clientSessionTerminalDigest(
+    input.receiptIds,
+    input.clientResult,
+  );
+  if (input.record.status === "completed") {
+    if (input.record.terminalDigest === terminalDigest) {
+      return sessionView(input.record);
+    }
+    throw conflict("会话已完成，终态不可改写");
+  }
+  if (input.record.status !== "active" || input.record.activeRequests) {
+    throw conflict("会话当前不能 finalize");
+  }
+  const receipts = [...input.record.receipts].sort(
+    (left, right) => left.attempt - right.attempt,
+  );
+  if (
+    !receipts.length ||
+    input.receiptIds.length !== receipts.length ||
+    receipts.some(
+      (receipt, index) => receipt.receiptId !== input.receiptIds[index],
+    )
+  ) {
+    throw invalid("Finalize 必须提交本 Run 的完整终末 receipt 链");
+  }
+  const terminal = receipts.at(-1)!;
+  const projected = terminal.canonicalResult;
+  const proposedResult = projected ?? input.clientResult;
+  if (proposedResult === undefined) throw invalid("Finalize 缺少可公开结果");
+  await input.admission.validateResult(
+    input.record.operationKey,
+    proposedResult,
+  );
+  const result = input.canonicalizeResult
+    ? await input.canonicalizeResult(proposedResult)
+    : proposedResult;
+  await input.admission.validateResult(input.record.operationKey, result);
+  const finalResult: ClientSessionFinalResult = {
+    clientRunId: input.record.clientRunId,
+    status: "completed",
+    result,
+    attestation: {
+      source:
+        projected === undefined ? "client-projected" : "provider-observed",
+      terminalReceiptId: terminal.receiptId,
+      providerAttested: projected !== undefined,
+      clientProjected: projected === undefined,
+    },
+  };
+  const completed = await input.repository.transition(
+    input.record.sessionId,
+    "active",
+    "completed",
+    { terminalDigest, finalResult },
+  );
+  if (!completed) {
+    const concurrent = await input.repository.find(input.record.sessionId);
+    if (
+      concurrent?.status === "completed" &&
+      concurrent.terminalDigest === terminalDigest
+    ) {
+      return sessionView(concurrent);
+    }
+    throw conflict("Finalize 与其它终态操作冲突");
+  }
+  await input.audit(completed, {
+    terminalReceiptId: terminal.receiptId,
+    clientProjected: projected === undefined,
+  });
+  return sessionView(completed);
+}

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

@@ -39,11 +39,22 @@ export function createClientAgentHostAuthRouteApp(input: {
         };
         if (!(await input.adapter.ready(context.request.signal)))
           throw unavailable();
-        const principal = await input.adapter.authenticate({
-          token: hostToken(context.request, path),
-          purpose: isCompletion(path) ? "completion" : "control",
-          signal: context.request.signal,
-        });
+        const purpose = isCompletion(path) ? "completion" : "control";
+        const token = hostToken(context.request);
+        const principal = token
+          ? await input.adapter.authenticate({
+              token,
+              purpose,
+              signal: context.request.signal,
+            })
+          : context.guardContext.actor.type !== "anonymous"
+            ? await input.adapter.authenticateCurrentSession?.({
+                request: context.request,
+                actorId: context.guardContext.actor.id,
+                purpose,
+                signal: context.request.signal,
+              })
+            : undefined;
         const actor = principal
           ? await input.resolveActor(principal.actorId)
           : undefined;
@@ -84,12 +95,13 @@ export function createClientAgentHostAuthRouteApp(input: {
   };
 }
 
-function hostToken(request: Request, path: string): string {
-  const header = path.includes(":sessionId")
-    ? request.headers.get("x-windy-host-authorization")
-    : request.headers.get("authorization");
+function hostToken(request: Request): string | undefined {
+  const header =
+    request.headers.get("x-windy-host-authorization") ??
+    request.headers.get("authorization");
   const token = header?.match(/^Bearer\s+(.+)$/iu)?.[1];
-  if (!token?.startsWith("bax_")) throw hidden();
+  if (!token || token.startsWith("car_")) return undefined;
+  if (!token.startsWith("bax_")) throw hidden();
   return token;
 }
 

package/template/apps/server/src/agent/client-session/host-revocation-composition.test.ts

@@ -0,0 +1,77 @@
+import { expect, test } from "bun:test";
+import type {
+  ModuleClientAgentHostAuthAdapter,
+  ModuleClientAgentHostPrincipal,
+} from "@southwind-ai/server-sdk";
+import { bindClientAgentHostRevocations } from "./host-revocation-composition.js";
+
+test("单监听 Host Auth Adapter 通过 Composition fan-out 撤销 Session 与 Workflow", async () => {
+  let listener:
+    | ((principal: ModuleClientAgentHostPrincipal) => Promise<void> | void)
+    | undefined;
+  const adapter = {
+    ready: async () => true,
+    authenticate: async () => undefined,
+    bindRevocations(next) {
+      listener = next;
+      return () => {
+        listener = undefined;
+      };
+    },
+  } satisfies ModuleClientAgentHostAuthAdapter;
+  const calls: string[] = [];
+  const dispose = bindClientAgentHostRevocations({
+    adapter,
+    revokeSessionHost: async () => {
+      calls.push("session");
+    },
+    revokeWorkflowHost: async () => {
+      calls.push("workflow");
+    },
+  });
+
+  await listener?.({
+    actorId: "actor-1",
+    installationId: "installation-1",
+    sessionId: "host-session-1",
+  });
+  expect(calls).toEqual(["session", "workflow"]);
+  dispose?.();
+  expect(listener).toBeUndefined();
+});
+
+test("Session 撤销失败时仍尝试 Workflow 撤销并汇总失败", async () => {
+  let listener:
+    | ((principal: ModuleClientAgentHostPrincipal) => Promise<void> | void)
+    | undefined;
+  const adapter = {
+    ready: async () => true,
+    authenticate: async () => undefined,
+    bindRevocations(next) {
+      listener = next;
+      return () => {
+        listener = undefined;
+      };
+    },
+  } satisfies ModuleClientAgentHostAuthAdapter;
+  const calls: string[] = [];
+  bindClientAgentHostRevocations({
+    adapter,
+    revokeSessionHost: async () => {
+      calls.push("session");
+      throw new Error("session revoke failed");
+    },
+    revokeWorkflowHost: async () => {
+      calls.push("workflow");
+    },
+  });
+
+  await expect(
+    listener?.({
+      actorId: "actor-1",
+      installationId: "installation-1",
+      sessionId: "host-session-1",
+    }),
+  ).rejects.toBeInstanceOf(AggregateError);
+  expect(calls).toEqual(["session", "workflow"]);
+});

package/template/apps/server/src/agent/client-session/host-revocation-composition.ts

@@ -0,0 +1,28 @@
+import type {
+  ModuleClientAgentHostAuthAdapter,
+  ModuleClientAgentHostPrincipal,
+} from "@southwind-ai/server-sdk";
+
+export function bindClientAgentHostRevocations(input: {
+  adapter?: ModuleClientAgentHostAuthAdapter;
+  revokeSessionHost?(
+    principal: ModuleClientAgentHostPrincipal,
+  ): Promise<unknown>;
+  revokeWorkflowHost?(
+    principal: ModuleClientAgentHostPrincipal,
+  ): Promise<unknown>;
+}) {
+  return input.adapter?.bindRevocations(async (principal) => {
+    const errors: unknown[] = [];
+    for (const revoke of [input.revokeSessionHost, input.revokeWorkflowHost]) {
+      try {
+        await revoke?.(principal);
+      } catch (error) {
+        errors.push(error);
+      }
+    }
+    if (errors.length) {
+      throw new AggregateError(errors, "Client Agent Host 撤销未完全收敛");
+    }
+  });
+}

package/template/apps/server/src/agent/client-session/launch-authority.contract.test.ts

@@ -0,0 +1,21 @@
+import { expect, test } from "bun:test";
+import { createFixture } from "./service.test-support.js";
+import { binding, hostSession } from "./service.test-support.js";
+
+test("普通 Client Session create 不能启动 workflow-only Operation", async () => {
+  const fixture = await createFixture();
+  const input = {
+    operationKey: "analysis.page-agent",
+    input: { question: "绕过 Workflow" },
+    clientBindingDigest: binding,
+    hostSessionDigest: hostSession,
+    actorId: "actor-1",
+  } as const;
+
+  await expect(fixture.service.create(input)).rejects.toMatchObject({
+    code: "FORBIDDEN",
+  });
+  await expect(fixture.service.createWorkflow(input)).resolves.toMatchObject({
+    capabilities: ["pageAgentClientRun"],
+  });
+});

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

@@ -63,8 +63,19 @@ export class ManifestClientSessionAdmission implements ClientSessionAdmissionPor
     input: ModuleAiJsonValue;
     clientBindingDigest: `sha256:${string}`;
     actorId: string;
+    launchAuthority: "direct" | "workflow-artifact";
   }) {
     const operation = this.operation(input.operationKey);
+    if (
+      (operation.definition.clientExecution!.launchAuthority ?? "direct") !==
+      input.launchAuthority
+    ) {
+      throw new ClientAgentSessionError(
+        "FORBIDDEN",
+        "Operation 不允许从当前入口启动 Client Agent Session",
+        403,
+      );
+    }
     const context = await this.resolveContext(input.actorId);
     await this.authorize(operation, context, input.actorId);
     const inputBytes = new TextEncoder().encode(

package/template/apps/server/src/agent/client-session/service.test-support.ts

@@ -2,6 +2,7 @@ import type { ModuleAiJsonValue } from "@southwind-ai/server-sdk";
 import type {
   ClientAgentProviderPort,
   ClientSessionAdmissionPort,
+  ClientSessionAttemptAuthorityChecker,
   ClientSessionAuditPort,
   ClientSessionCaller,
   ClientSessionRecord,
@@ -10,6 +11,7 @@ import { digestJson } from "./digest.js";
 import { ClientAgentSessionError } from "./errors.js";
 import { InMemoryClientSessionRepository } from "./repository.js";
 import { GovernedClientAgentSessionService } from "./service.js";
+import { ClientSessionAttemptAuthorityBinding } from "./attempt-authority.js";
 
 export const binding = `sha256:${"b".repeat(64)}` as const;
 export const hostSession = `sha256:${"e".repeat(64)}` as const;
@@ -26,6 +28,7 @@ export async function createFixture(
       signal: AbortSignal,
     ) => Promise<ModuleAiJsonValue>;
     providerReady?: boolean;
+    attemptAuthority?: ClientSessionAttemptAuthorityChecker;
   } = {},
 ) {
   const clock = { value: options.now ?? 1_000 };
@@ -39,6 +42,10 @@ export async function createFixture(
     options.providerReady ?? true,
   );
   const audits: Parameters<ClientSessionAuditPort["record"]>[0][] = [];
+  const attemptAuthority = new ClientSessionAttemptAuthorityBinding();
+  if (options.attemptAuthority) {
+    attemptAuthority.bind(options.attemptAuthority);
+  }
   const service = new GovernedClientAgentSessionService(
     repository,
     admission,
@@ -49,6 +56,7 @@ export async function createFixture(
       },
     },
     "https://windy.example/api/agent/client-sessions/",
+    attemptAuthority,
     () => clock.value,
     options.maxTtlMs,
   );
@@ -70,6 +78,7 @@ export async function createFixture(
     repository,
     admission,
     provider,
+    attemptAuthority,
     audits,
     grant,
     caller,
@@ -90,7 +99,19 @@ class FakeAdmission implements ClientSessionAdmissionPort {
     input: ModuleAiJsonValue;
     clientBindingDigest: `sha256:${string}`;
     actorId: string;
+    launchAuthority: "direct" | "workflow-artifact";
   }) {
+    const expectedAuthority: "direct" | "workflow-artifact" =
+      input.operationKey === "analysis.page-agent"
+        ? "workflow-artifact"
+        : "direct";
+    if (input.launchAuthority !== expectedAuthority) {
+      throw new ClientAgentSessionError(
+        "FORBIDDEN",
+        "launch authority mismatch",
+        403,
+      );
+    }
     return {
       actorId: input.actorId,
       operationKey: input.operationKey,
@@ -121,6 +142,7 @@ class FakeAdmission implements ClientSessionAdmissionPort {
       },
       limits: {
         mode: "governed-session" as const,
+        launchAuthority: expectedAuthority,
         maxSteps: this.maxSteps,
         maxRequestBytes: 16_384,
         maxResponseBytes: 16_384,