create-windy 0.6.14 → 0.6.16

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

@@ -1,31 +1,25 @@
-import { randomBytes, randomUUID } from "node:crypto";
 import type { ModuleAiJsonValue } from "@southwind-ai/server-sdk";
 import type {
   ClientSessionAdmissionPort,
+  ClientSessionAttemptAuthorityChecker,
   ClientSessionAuditPort,
   ClientSessionCaller,
-  ClientSessionFinalResult,
   ClientSessionRecord,
 } from "./contracts.js";
-import { digestJson, digestText, validDigest } from "./digest.js";
+import { digestText } from "./digest.js";
 import type { ClientSessionRepository } from "./repository.js";
 import { clientAgentCapabilities } from "./capabilities.js";
 import { authorizeClientSession } from "./authorization.js";
 import { abortClientSession, auditRevokedSessions } from "./revocation.js";
-import {
-  ensureTrailingSlash,
-  publicLimits,
-  sessionView,
-} from "./presentation.js";
-import {
-  ClientAgentSessionError,
-  clientSessionConflict as conflict,
-  clientSessionInvalid as invalid,
-} from "./errors.js";
+import { sessionView } from "./presentation.js";
+import { clientSessionConflict as conflict } from "./errors.js";
 import {
   consumeClientAgentCompletion,
   runClientAgentCompletion,
 } from "./completion.js";
+import { finalizeClientSession } from "./finalization.js";
+import { createClientAgentSession } from "./creation.js";
+
 export class GovernedClientAgentSessionService {
   readonly #attemptControllers = new Map<string, AbortController>();
   readonly #recovery: Promise<number>;
@@ -35,6 +29,7 @@ export class GovernedClientAgentSessionService {
     private readonly provider: import("./contracts.js").ClientAgentProviderPort,
     private readonly audit: ClientSessionAuditPort,
     private readonly trustedBaseUrl: string,
+    private readonly attemptAuthority: ClientSessionAttemptAuthorityChecker,
     private readonly now: () => number = Date.now,
     private readonly maxTtlMs = 5 * 60_000,
   ) {
@@ -60,73 +55,44 @@ export class GovernedClientAgentSessionService {
     hostSessionDigest: `sha256:${string}`;
     actorId: string;
   }) {
-    await this.#recovery;
-    if (!(await this.provider.ready())) {
-      throw new ClientAgentSessionError(
-        "PROVIDER_FAILED",
-        "Client Agent Provider 尚未就绪",
-        503,
-      );
-    }
-    if (
-      !validDigest(input.clientBindingDigest) ||
-      !validDigest(input.hostSessionDigest) ||
-      !input.actorId.trim()
-    ) {
-      throw invalid("Client Agent binding 或 Actor 无效");
-    }
-    const admission = await this.admission.admit({
-      operationKey: input.operationKey,
-      input: input.input,
-      actorId: input.actorId,
-      clientBindingDigest: input.clientBindingDigest,
-    });
-    if (
-      admission.actorId !== input.actorId ||
-      admission.operationKey !== input.operationKey ||
-      admission.clientBindingDigest !== input.clientBindingDigest
-    ) {
-      throw new Error("Client Agent admission 返回了不一致的绑定");
-    }
-    const createdAt = this.now();
-    const expiresAt =
-      createdAt +
-      Math.min(admission.limits.maxDurationSeconds * 1_000, this.maxTtlMs);
-    const accessToken = `car_${randomBytes(32).toString("base64url")}`;
-    const record: ClientSessionRecord = {
-      ...admission,
-      sessionId: `cas_${randomUUID()}`,
-      clientRunId: `carun_${randomUUID()}`,
-      tokenHash: digestText(accessToken),
-      hostSessionDigest: input.hostSessionDigest,
-      modelAlias: this.provider.modelAlias,
-      createdAt,
-      expiresAt,
-      status: "active",
-      attemptCount: 0,
-      activeRequests: 0,
-      pendingAttempts: [],
-      receipts: [],
-    };
-    await this.repository.create(record);
-    await this.recordAudit("create", record, "success", {
-      inputCommitment: record.inputCommitment,
-      authorizationDigest: record.authorizationDigest,
-      bindingDigest: record.clientBindingDigest,
+    return this.createWithAuthority(input, "direct");
+  }
+
+  /** 仅供固定 Workflow Artifact service 使用；路由不得暴露。 */
+  async createWorkflow(input: {
+    operationKey: string;
+    input: ModuleAiJsonValue;
+    clientBindingDigest: string;
+    hostSessionDigest: `sha256:${string}`;
+    actorId: string;
+  }) {
+    return this.createWithAuthority(input, "workflow-artifact");
+  }
+
+  private async createWithAuthority(
+    input: {
+      operationKey: string;
+      input: ModuleAiJsonValue;
+      clientBindingDigest: string;
+      hostSessionDigest: `sha256:${string}`;
+      actorId: string;
+    },
+    launchAuthority: "direct" | "workflow-artifact",
+  ) {
+    return createClientAgentSession({
+      request: input,
+      launchAuthority,
+      recovery: this.#recovery,
+      provider: this.provider,
+      admission: this.admission,
+      repository: this.repository,
+      trustedBaseUrl: this.trustedBaseUrl,
+      now: this.now,
+      maxTtlMs: this.maxTtlMs,
+      audit: async (record, metadata) => {
+        await this.recordAudit("create", record, "success", metadata);
+      },
     });
-    return {
-      clientRunId: record.clientRunId,
-      sessionId: record.sessionId,
-      trustedBaseUrl: new URL(
-        `${encodeURIComponent(record.sessionId)}/v1/`,
-        ensureTrailingSlash(this.trustedBaseUrl),
-      ).toString(),
-      modelAlias: record.modelAlias,
-      limits: publicLimits(record),
-      expiresAt: new Date(record.expiresAt).toISOString(),
-      accessToken,
-      capabilities: ["pageAgentClientRun"] as const,
-    };
   }
 
   async complete(
@@ -152,6 +118,7 @@ export class GovernedClientAgentSessionService {
       caller,
       signal,
       current: await this.authorize(sessionId, caller, true),
+      attemptAuthority: this.attemptAuthority,
       repository: this.repository,
       admission: this.admission,
       provider: this.provider,
@@ -172,66 +139,49 @@ export class GovernedClientAgentSessionService {
   ) {
     await this.#recovery;
     const record = await this.authorize(sessionId, caller, false);
-    const terminalDigest = digestJson({
-      receiptIds: [...receiptIds],
-      ...(clientResult === undefined ? {} : { result: clientResult }),
+    return finalizeClientSession({
+      record,
+      repository: this.repository,
+      admission: this.admission,
+      receiptIds,
+      clientResult,
+      audit: (completed, metadata) =>
+        this.recordAudit("finalize", completed, "success", metadata),
     });
-    if (record.status === "completed") {
-      if (record.terminalDigest === terminalDigest) return sessionView(record);
-      throw conflict("会话已完成，终态不可改写");
-    }
-    if (record.status !== "active" || record.activeRequests) {
-      throw conflict("会话当前不能 finalize");
-    }
-    const receipts = [...record.receipts].sort((a, b) => a.attempt - b.attempt);
+  }
+
+  async finalizeWorkflow(
+    sessionId: string,
+    caller: Omit<ClientSessionCaller, "token">,
+    receiptIds: readonly string[],
+    clientResult: ModuleAiJsonValue | undefined,
+    canonicalizeResult: (
+      proposedResult: ModuleAiJsonValue,
+    ) => Promise<ModuleAiJsonValue>,
+  ) {
+    await this.#recovery;
+    const record = await this.repository.find(sessionId);
     if (
-      !receipts.length ||
-      receiptIds.length !== receipts.length ||
-      receipts.some((receipt, index) => receipt.receiptId !== receiptIds[index])
+      !record ||
+      record.actorId !== caller.actorId ||
+      record.clientBindingDigest !== caller.clientBindingDigest ||
+      record.hostSessionDigest !== caller.hostSessionDigest ||
+      (record.status !== "completed" &&
+        (record.status !== "active" || record.expiresAt <= this.now())) ||
+      !(await this.admission.reauthorize(record, caller.actorId))
     ) {
-      throw invalid("Finalize 必须提交本 Run 的完整终末 receipt 链");
+      throw conflict("Workflow Client Agent Session 绑定已失效");
     }
-    const terminal = receipts.at(-1)!;
-    const projected = terminal.canonicalResult;
-    const result = projected ?? clientResult;
-    if (result === undefined) throw invalid("Finalize 缺少可公开结果");
-    await this.admission.validateResult(record.operationKey, result);
-    const finalResult: ClientSessionFinalResult = {
-      clientRunId: 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 this.repository.transition(
-      sessionId,
-      "active",
-      "completed",
-      {
-        terminalDigest,
-        finalResult,
-      },
-    );
-    if (!completed) {
-      const concurrent = await this.repository.find(sessionId);
-      if (
-        concurrent?.status === "completed" &&
-        concurrent.terminalDigest === terminalDigest
-      ) {
-        return sessionView(concurrent);
-      }
-      throw conflict("Finalize 与其它终态操作冲突");
-    }
-    await this.recordAudit("finalize", completed, "success", {
-      terminalReceiptId: terminal.receiptId,
-      clientProjected: projected === undefined,
+    return finalizeClientSession({
+      record,
+      repository: this.repository,
+      admission: this.admission,
+      receiptIds,
+      clientResult,
+      canonicalizeResult,
+      audit: (completed, metadata) =>
+        this.recordAudit("finalize", completed, "success", metadata),
     });
-    return sessionView(completed);
   }
 
   async cancel(
@@ -310,6 +260,26 @@ export class GovernedClientAgentSessionService {
     });
   }
 
+  /** Host-internal revocation for a fenced Workflow claim; no browser token is accepted. */
+  async revokeSession(sessionId: string, cause: string) {
+    await this.#recovery;
+    const record = await this.repository.find(sessionId);
+    if (!record || record.status === "revoked") return;
+    if (record.status !== "active") return;
+    abortClientSession(this.#attemptControllers, sessionId);
+    const revoked = await this.repository.transition(
+      sessionId,
+      "active",
+      "revoked",
+      { terminalDigest: digestText(`revoke\0${cause.slice(0, 120)}`) },
+    );
+    if (revoked) {
+      await this.recordAudit("revoke", revoked, "success", {
+        cause: cause.slice(0, 120),
+      });
+    }
+  }
+
   private async authorize(
     sessionId: string,
     caller: ClientSessionCaller,

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

@@ -0,0 +1,23 @@
+import { describe, expect, test } from "bun:test";
+import { clientSessionTerminalDigest } from "./digest.js";
+
+describe("Client Session terminal digest", () => {
+  test("canonical result key 顺序不改变 digest，receipt 顺序仍参与绑定", () => {
+    const left = clientSessionTerminalDigest(["receipt_1", "receipt_2"], {
+      answer: "done",
+      evidence: { b: 2, a: 1 },
+    });
+    const same = clientSessionTerminalDigest(["receipt_1", "receipt_2"], {
+      evidence: { a: 1, b: 2 },
+      answer: "done",
+    });
+    const reordered = clientSessionTerminalDigest(["receipt_2", "receipt_1"], {
+      answer: "done",
+      evidence: { a: 1, b: 2 },
+    });
+
+    expect(left).toBe(same);
+    expect(left).toMatch(/^sha256:[a-f0-9]{64}$/u);
+    expect(reordered).not.toBe(left);
+  });
+});

package/template/apps/server/src/agent/client-workflow-artifact/active-blob-references.ts

@@ -0,0 +1,8 @@
+import type { NodePgDatabase } from "drizzle-orm/node-postgres";
+import { DrizzleClientAgentWorkflowArtifactRepository } from "./drizzle-repository.js";
+
+export function clientWorkflowArtifactActiveBlobReferences(
+  db: NodePgDatabase | undefined,
+) {
+  return db ? [new DrizzleClientAgentWorkflowArtifactRepository(db)] : [];
+}

package/template/apps/server/src/agent/client-workflow-artifact/artifact-builder.ts

@@ -0,0 +1,60 @@
+import { createHash } from "node:crypto";
+import type { ModuleAiJsonValue } from "@southwind-ai/server-sdk";
+import { artifactRef, type BlobStore } from "@southwind-ai/storage";
+import { canonicalJson, digestJson } from "../client-session/digest.js";
+import type {
+  ClientAgentWorkflowArtifactBinding,
+  ClientAgentWorkflowArtifactRecord,
+} from "./contracts.js";
+import { ClientAgentWorkflowArtifactError } from "./error.js";
+
+export function clientWorkflowTerminalReceipt(
+  record: ClientAgentWorkflowArtifactRecord,
+  historyHeadDigest: string,
+) {
+  return `cawr_${digestJson({
+    workId: record.workId,
+    claimGeneration: record.claimGeneration,
+    historyHeadDigest,
+  }).slice("sha256:".length, 53)}`;
+}
+
+export async function storeClientWorkflowArtifact(input: {
+  blobs: BlobStore;
+  result: ModuleAiJsonValue;
+  binding: ClientAgentWorkflowArtifactBinding;
+  terminalReceiptDigest: `sha256:${string}`;
+}) {
+  const bytes = new TextEncoder().encode(canonicalJson(input.result));
+  if (bytes.byteLength > input.binding.artifact.maxByteSize) {
+    throw new ClientAgentWorkflowArtifactError(
+      "ARTIFACT_TOO_LARGE",
+      "Client Agent Workflow 产物超过策略上限",
+      413,
+    );
+  }
+  const sha256 = createHash("sha256").update(bytes).digest("hex");
+  if (!input.blobs.putOnce) {
+    throw new ClientAgentWorkflowArtifactError(
+      "ARTIFACT_STORE_UNAVAILABLE",
+      "Client Agent Workflow 稳定产物存储未装配",
+      503,
+    );
+  }
+  const stableRef = artifactRef(
+    `blob_${input.terminalReceiptDigest.slice("sha256:".length, 39)}`,
+  );
+  const stored = await input.blobs.putOnce({
+    ref: stableRef,
+    body: new Blob([bytes]).stream(),
+    expectedByteSize: bytes.byteLength,
+    expectedContentHash: { algorithm: "sha256", value: sha256 },
+  });
+  return {
+    artifactRef: stored.ref,
+    filename: input.binding.artifact.filename,
+    contentType: input.binding.artifact.contentType,
+    byteSize: stored.byteSize,
+    sha256,
+  };
+}

package/template/apps/server/src/agent/client-workflow-artifact/authority-current.ts

@@ -0,0 +1,59 @@
+import {
+  agentWorkflowNodeRuns,
+  agentWorkflowRuns,
+  agentWorkflowSideEffectCommands,
+} from "@southwind-ai/database";
+import { eq } from "drizzle-orm";
+import type { NodePgDatabase } from "drizzle-orm/node-postgres";
+import type { ClientAgentWorkflowArtifactRecord } from "./contracts.js";
+
+export async function clientWorkflowAuthorityCurrent(
+  db: NodePgDatabase,
+  record: ClientAgentWorkflowArtifactRecord,
+  now: number,
+) {
+  const [command] = await db
+    .select()
+    .from(agentWorkflowSideEffectCommands)
+    .where(eq(agentWorkflowSideEffectCommands.commandId, record.commandId))
+    .for("update")
+    .limit(1);
+  if (!command) return false;
+  const [run] = await db
+    .select()
+    .from(agentWorkflowRuns)
+    .where(eq(agentWorkflowRuns.runId, record.runId))
+    .for("update")
+    .limit(1);
+  if (!run) return false;
+  const [nodeRun] = await db
+    .select()
+    .from(agentWorkflowNodeRuns)
+    .where(eq(agentWorkflowNodeRuns.nodeRunId, record.nodeRunId))
+    .for("update")
+    .limit(1);
+  return Boolean(
+    nodeRun &&
+    command.status === "dispatched" &&
+    command.runId === record.runId &&
+    command.nodeRunId === record.nodeRunId &&
+    command.effectKind === record.effectKind &&
+    command.adapterKind === "durable-job" &&
+    command.generation === record.effectGeneration &&
+    command.requestDigest === record.requestDigest &&
+    command.fenceTokenDigest === record.effectFenceTokenDigest &&
+    command.authorizationSnapshotDigest ===
+      record.authorizationSnapshotDigest &&
+    command.runPolicyDigest === record.runPolicyDigest &&
+    ["accepted", "running", "waiting"].includes(run.status) &&
+    !run.cancellationRequestedAt &&
+    run.deadlineAt > now &&
+    run.actorId === record.actorId &&
+    run.scopeDigest === record.scopeDigest &&
+    run.authorizationSnapshotDigest === record.authorizationSnapshotDigest &&
+    run.executionPolicyDigest === record.runPolicyDigest &&
+    nodeRun.runId === record.runId &&
+    nodeRun.nodeType === "job" &&
+    ["running", "waiting"].includes(nodeRun.status),
+  );
+}

package/template/apps/server/src/agent/client-workflow-artifact/binding-registry.test.ts

@@ -0,0 +1,189 @@
+import { expect, test } from "bun:test";
+import {
+  CLIENT_AGENT_WORKFLOW_ARTIFACT_BINDING_LIMITS as limits,
+  type ModuleClientAgentWorkflowArtifactProjectBinding,
+} from "@southwind-ai/server-sdk";
+import {
+  clientWorkflowBindingCommitment,
+  ClientAgentWorkflowArtifactBindingRegistry,
+} from "./binding-registry.js";
+
+test("Composition 启动时拒绝超出 DB/DTO 边界与路径型文件名", () => {
+  for (const binding of [
+    value({ workflowKey: "w".repeat(limits.workflowKey + 1) }),
+    value({ nodeId: "n".repeat(limits.nodeId + 1) }),
+    value({ operationKey: "o".repeat(limits.operationKey + 1) }),
+    value({ releaseDigest: `sha256:${"d".repeat(65)}` }),
+    value({
+      terminalResultAuthority: {
+        ...value().terminalResultAuthority,
+        version: "v".repeat(limits.terminalAuthorityVersion + 1),
+      },
+    }),
+    value({
+      terminalResultAuthority: {
+        ...value().terminalResultAuthority,
+        digest: `sha256:${"e".repeat(65)}`,
+      },
+    }),
+    value({
+      artifact: {
+        ...value().artifact,
+        kind: "k".repeat(limits.artifactKind + 1),
+      },
+    }),
+    value({
+      artifact: {
+        ...value().artifact,
+        filename: `${"f".repeat(limits.artifactFilename)}x`,
+      },
+    }),
+    value({
+      artifact: {
+        ...value().artifact,
+        retentionPolicyKey: "r".repeat(limits.retentionPolicyKey + 1),
+      },
+    }),
+    value({
+      artifact: { ...value().artifact, maxByteSize: limits.maxByteSize + 1 },
+    }),
+    value({ artifact: { ...value().artifact, filename: "nested/out.json" } }),
+    value({ artifact: { ...value().artifact, filename: "nested\\out.json" } }),
+    value({ workflowKey: "workflow\0key" }),
+    value({ nodeId: "page-agent\0artifact" }),
+    value({ operationKey: "analysis\0page-agent" }),
+    value({ releaseDigest: `sha256:${"d".repeat(63)}\0` }),
+    value({
+      artifact: { ...value().artifact, kind: "analysis\0report" },
+    }),
+    invalidContentTypeBinding(),
+    value({
+      artifact: { ...value().artifact, filename: "analysis\0.json" },
+    }),
+    value({
+      artifact: {
+        ...value().artifact,
+        retentionPolicyKey: "analysis\0case-artifact",
+      },
+    }),
+  ]) {
+    expect(
+      () => new ClientAgentWorkflowArtifactBindingRegistry([binding]),
+    ).toThrow("CLIENT_AGENT_WORKFLOW_BINDING_INVALID");
+  }
+});
+
+function invalidContentTypeBinding(): ModuleClientAgentWorkflowArtifactProjectBinding {
+  const binding = value();
+  Object.defineProperty(binding.artifact, "contentType", {
+    value: "application/json\0",
+    enumerable: true,
+  });
+  return binding;
+}
+
+test("每个 Workflow 只允许一个固定 PageAgent Job binding", () => {
+  expect(
+    () =>
+      new ClientAgentWorkflowArtifactBindingRegistry([
+        value(),
+        value({ nodeId: "other-node" }),
+      ]),
+  ).toThrow("CLIENT_AGENT_WORKFLOW_BINDING_DUPLICATE");
+});
+
+test("binding commitment 只承诺 authority version 与 digest", () => {
+  const first = value();
+  const second = value({
+    terminalResultAuthority: {
+      ...first.terminalResultAuthority,
+      async canonicalize() {
+        return { changed: true };
+      },
+    },
+    clientTaskAuthority: {
+      version: "sharp.client-task.v1",
+      digest: `sha256:${"f".repeat(64)}`,
+      async build({ workflowInput }) {
+        return { taskKey: "sharp.full-review", input: workflowInput };
+      },
+    },
+    launchAuthority: {
+      version: "sharp.workflow-launch.v1",
+      digest: `sha256:${"a".repeat(64)}`,
+      async authorizeRelease() {},
+      async authorizeRun({ actorId }) {
+        return {
+          authorizationScope: {
+            tenantId: "single-tenant",
+            actorId,
+            grants: [{ scope: "self" }],
+            roleIds: ["role-analyst"],
+          },
+        };
+      },
+    },
+  });
+  expect(clientWorkflowBindingCommitment(first)).toEqual(
+    clientWorkflowBindingCommitment(second),
+  );
+  expect(clientWorkflowBindingCommitment(first)).not.toEqual(
+    clientWorkflowBindingCommitment(
+      value({
+        terminalResultAuthority: {
+          ...first.terminalResultAuthority,
+          version: "sharp.analysis-result.v2",
+        },
+      }),
+    ),
+  );
+});
+
+function value(
+  patch: Partial<ModuleClientAgentWorkflowArtifactProjectBinding> = {},
+): ModuleClientAgentWorkflowArtifactProjectBinding {
+  return {
+    workflowKey: "analysis.cross-case.full-review",
+    nodeId: "page-agent-artifact",
+    operationKey: "analysis.cross-case.page-agent",
+    releaseDigest: `sha256:${"d".repeat(64)}`,
+    scopeContainmentContractVersion: 1,
+    terminalResultAuthority: {
+      version: "sharp.analysis-result.v1",
+      digest: `sha256:${"e".repeat(64)}`,
+      async canonicalize({ proposedResult }) {
+        return proposedResult;
+      },
+    },
+    clientTaskAuthority: {
+      version: "sharp.client-task.v1",
+      digest: `sha256:${"f".repeat(64)}`,
+      async build({ workflowInput }) {
+        return { taskKey: "sharp.full-review", input: workflowInput };
+      },
+    },
+    launchAuthority: {
+      version: "sharp.workflow-launch.v1",
+      digest: `sha256:${"a".repeat(64)}`,
+      async authorizeRelease() {},
+      async authorizeRun({ actorId }) {
+        return {
+          authorizationScope: {
+            tenantId: "single-tenant",
+            actorId,
+            grants: [{ scope: "self" }],
+            roleIds: ["role-analyst"],
+          },
+        };
+      },
+    },
+    artifact: {
+      kind: "analysis-report",
+      contentType: "application/json",
+      filename: "analysis.json",
+      retentionPolicyKey: "analysis.case-artifact",
+      maxByteSize: 4 * 1024 * 1024,
+    },
+    ...patch,
+  };
+}