create-windy 0.6.12 → 0.6.15

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

@@ -0,0 +1,268 @@
+import { describe, expect, test } from "bun:test";
+import type { ModuleAiJsonValue } from "@southwind-ai/server-sdk";
+import {
+  binding,
+  createFixture,
+  providerResponse,
+  validCompletion,
+} from "./service.test-support.js";
+
+const deployment = `sha256:${"d".repeat(64)}` as const;
+
+describe("Governed Client Agent Session", () => {
+  test("Provider 未就绪时不签发 capability 或单 Run token", async () => {
+    await expect(createFixture({ providerReady: false })).rejects.toMatchObject(
+      {
+        code: "PROVIDER_FAILED",
+      },
+    );
+  });
+
+  test("只存 token hash，并拒绝跨 Actor、Run 或 binding 重放", async () => {
+    const fixture = await createFixture();
+    const persisted = await fixture.repository.find(fixture.grant.sessionId);
+    expect(JSON.stringify(persisted)).not.toContain(fixture.grant.accessToken);
+
+    await expect(
+      fixture.service.status(fixture.grant.sessionId, {
+        ...fixture.caller,
+        actorId: "actor-2",
+      }),
+    ).rejects.toMatchObject({ code: "NOT_FOUND" });
+    await expect(
+      fixture.service.status("cas_other", fixture.caller),
+    ).rejects.toMatchObject({ code: "NOT_FOUND" });
+    await expect(
+      fixture.service.status(fixture.grant.sessionId, {
+        ...fixture.caller,
+        clientBindingDigest: `sha256:${"c".repeat(64)}`,
+      }),
+    ).rejects.toMatchObject({ code: "NOT_FOUND" });
+    await expect(
+      fixture.service.status(fixture.grant.sessionId, {
+        ...fixture.caller,
+        hostSessionDigest: `sha256:${"x".repeat(64)}`,
+      }),
+    ).rejects.toMatchObject({ code: "NOT_FOUND" });
+  });
+
+  test("固定 model，拒绝 URL/endpoint 覆盖并执行 envelope DLP", async () => {
+    const fixture = await createFixture();
+    await expect(
+      fixture.complete({ model: "attacker", messages: messages("hello") }),
+    ).rejects.toMatchObject({ code: "INVALID_INPUT" });
+    await expect(
+      fixture.complete({
+        model: "windy-default",
+        messages: messages("hello"),
+        url: "https://evil.example/v1",
+      }),
+    ).rejects.toMatchObject({ code: "INVALID_INPUT" });
+
+    await fixture.complete({
+      model: "windy-default",
+      messages: messages("联系 test@example.com"),
+    });
+    expect(JSON.stringify(fixture.provider.requests[0])).toContain(
+      "[REDACTED]",
+    );
+    expect(JSON.stringify(fixture.provider.requests[0])).not.toContain(
+      "test@example.com",
+    );
+  });
+
+  test("成功 attempt 生成 opaque receipt，finalize 优先使用 Provider 投影且幂等", async () => {
+    const fixture = await createFixture();
+    const completion = await fixture.complete(validCompletion());
+    expect(completion.receipt).toMatchObject({
+      clientRunId: fixture.grant.clientRunId,
+      attempt: 1,
+      deploymentDigest: deployment,
+    });
+    expect(JSON.stringify(completion.receipt)).not.toContain("provider answer");
+
+    const first = await fixture.service.finalize(
+      fixture.grant.sessionId,
+      fixture.caller,
+      [completion.receipt.receiptId],
+      { answer: "伪造客户端结果" },
+    );
+    expect(first.result).toMatchObject({
+      result: { answer: "provider answer" },
+      attestation: {
+        source: "provider-observed",
+        providerAttested: true,
+        clientProjected: false,
+      },
+    });
+    await expect(
+      fixture.service.finalize(
+        fixture.grant.sessionId,
+        fixture.caller,
+        [completion.receipt.receiptId],
+        { answer: "伪造客户端结果" },
+      ),
+    ).resolves.toEqual(first);
+    await expect(
+      fixture.service.finalize(
+        fixture.grant.sessionId,
+        fixture.caller,
+        [completion.receipt.receiptId],
+        { answer: "改写" },
+      ),
+    ).rejects.toMatchObject({ code: "CONFLICT" });
+  });
+
+  test("没有可用 Provider 投影时明确标记 clientProjected", async () => {
+    const fixture = await createFixture({ projectProviderResult: false });
+    const completion = await fixture.complete(validCompletion());
+    const finalized = await fixture.service.finalize(
+      fixture.grant.sessionId,
+      fixture.caller,
+      [completion.receipt.receiptId],
+      { answer: "client answer" },
+    );
+    expect(finalized.result).toMatchObject({
+      attestation: {
+        source: "client-projected",
+        providerAttested: false,
+        clientProjected: true,
+      },
+    });
+    expect(JSON.stringify(finalized)).not.toContain("runtimeVerified");
+  });
+
+  test("并发重复 finalize 收敛为同一个终态结果", async () => {
+    const fixture = await createFixture();
+    const completion = await fixture.complete(validCompletion());
+    const finalize = () =>
+      fixture.service.finalize(
+        fixture.grant.sessionId,
+        fixture.caller,
+        [completion.receipt.receiptId],
+        { answer: "same" },
+      );
+    const [left, right] = await Promise.all([finalize(), finalize()]);
+    expect(left).toEqual(right);
+    expect(left.status).toBe("completed");
+  });
+
+  test("取消会中止在途请求，迟到响应不能产生 receipt 或新状态", async () => {
+    let release!: (value: ModuleAiJsonValue) => void;
+    const fixture = await createFixture({
+      execute: (_request, signal) =>
+        new Promise((resolve) => {
+          release = resolve;
+          signal.addEventListener("abort", () => undefined);
+        }),
+    });
+    const pending = fixture.complete(validCompletion());
+    await tick();
+    const cancelled = await fixture.service.cancel(
+      fixture.grant.sessionId,
+      fixture.caller,
+      "user stopped",
+    );
+    expect(cancelled.status).toBe("cancelled");
+    release(providerResponse());
+    await expect(pending).rejects.toMatchObject({ code: "CONFLICT" });
+    const persisted = await fixture.repository.find(fixture.grant.sessionId);
+    expect(persisted?.receipts).toHaveLength(0);
+    expect(persisted?.status).toBe("cancelled");
+  });
+
+  test("权限漂移、TTL 和显式 revoke 都即时关闭会话", async () => {
+    const drift = await createFixture();
+    drift.admission.allowed = false;
+    await expect(drift.complete(validCompletion())).rejects.toMatchObject({
+      code: "NOT_FOUND",
+    });
+    expect((await drift.repository.find(drift.grant.sessionId))?.status).toBe(
+      "revoked",
+    );
+
+    const expired = await createFixture({ now: 10_000, maxTtlMs: 1 });
+    expired.clock.value = 10_002;
+    await expect(expired.complete(validCompletion())).rejects.toMatchObject({
+      code: "NOT_FOUND",
+    });
+    expect(
+      (await expired.repository.find(expired.grant.sessionId))?.status,
+    ).toBe("expired");
+
+    const revoked = await createFixture();
+    expect(await revoked.service.revokeBinding(binding, "actor-1")).toBe(1);
+    await expect(revoked.complete(validCompletion())).rejects.toMatchObject({
+      code: "CONFLICT",
+    });
+
+    const installation = await createFixture();
+    expect(
+      await installation.service.revokeHostSession(
+        installation.caller.hostSessionDigest,
+        "actor-1",
+      ),
+    ).toBe(1);
+    expect(
+      (await installation.repository.find(installation.grant.sessionId))
+        ?.status,
+    ).toBe("revoked");
+  });
+
+  test("在途流式调用按当前权限漂移自动撤销", async () => {
+    const fixture = await createFixture({
+      execute: (_request, signal) =>
+        new Promise((_resolve, reject) => {
+          signal.addEventListener("abort", () => reject(new Error("aborted")));
+        }),
+    });
+    const pending = fixture.complete(validCompletion());
+    const settled = pending.then(
+      () => undefined,
+      (error: unknown) => error,
+    );
+    await tick();
+    fixture.admission.allowed = false;
+    await new Promise((resolve) => setTimeout(resolve, 300));
+    expect(await settled).toMatchObject({ code: "PROVIDER_FAILED" });
+    expect(
+      (await fixture.repository.find(fixture.grant.sessionId))?.status,
+    ).toBe("revoked");
+  });
+
+  test("强制并发/step 上限，Provider 失败不生成 receipt", async () => {
+    let release!: (value: ModuleAiJsonValue) => void;
+    const fixture = await createFixture({
+      maxSteps: 1,
+      execute: () => new Promise((resolve) => (release = resolve)),
+    });
+    const pending = fixture.complete(validCompletion());
+    await tick();
+    await expect(fixture.complete(validCompletion())).rejects.toMatchObject({
+      code: "CONFLICT",
+    });
+    release(providerResponse());
+    await pending;
+    await expect(fixture.complete(validCompletion())).rejects.toMatchObject({
+      code: "CONFLICT",
+    });
+
+    const failed = await createFixture({
+      execute: () => Promise.reject(new Error("secret provider detail")),
+    });
+    await expect(failed.complete(validCompletion())).rejects.toMatchObject({
+      code: "PROVIDER_FAILED",
+      message: "Provider 调用失败",
+    });
+    expect(
+      (await failed.repository.find(failed.grant.sessionId))?.receipts,
+    ).toHaveLength(0);
+  });
+});
+
+function messages(content: string) {
+  return [{ role: "user", content }];
+}
+function tick() {
+  return new Promise((resolve) => setTimeout(resolve, 0));
+}

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

@@ -0,0 +1,316 @@
+import type { ModuleAiJsonValue } from "@southwind-ai/server-sdk";
+import type {
+  ClientSessionAdmissionPort,
+  ClientSessionAttemptAuthorityChecker,
+  ClientSessionAuditPort,
+  ClientSessionCaller,
+  ClientSessionRecord,
+} from "./contracts.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 { 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>;
+  constructor(
+    private readonly repository: ClientSessionRepository,
+    private readonly admission: ClientSessionAdmissionPort,
+    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,
+  ) {
+    const url = new URL(trustedBaseUrl);
+    if (url.protocol !== "https:" && url.hostname !== "localhost") {
+      throw new Error("Client Agent trusted baseURL 必须使用 HTTPS");
+    }
+    if (url.username || url.password || url.search || url.hash) {
+      throw new Error("Client Agent trusted baseURL 不能包含凭据或参数");
+    }
+    this.#recovery = repository.recoverInterrupted(this.now());
+  }
+
+  async capabilities(signal?: AbortSignal) {
+    await this.#recovery;
+    return clientAgentCapabilities(this.provider, signal);
+  }
+
+  async create(input: {
+    operationKey: string;
+    input: ModuleAiJsonValue;
+    clientBindingDigest: string;
+    hostSessionDigest: `sha256:${string}`;
+    actorId: string;
+  }) {
+    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);
+      },
+    });
+  }
+
+  async complete(
+    sessionId: string,
+    body: unknown,
+    caller: ClientSessionCaller,
+    signal?: AbortSignal,
+  ) {
+    return consumeClientAgentCompletion(
+      (await this.startCompletion(sessionId, body, caller, signal)).events,
+    );
+  }
+  async startCompletion(
+    sessionId: string,
+    body: unknown,
+    caller: ClientSessionCaller,
+    signal?: AbortSignal,
+  ) {
+    await this.#recovery;
+    return runClientAgentCompletion({
+      sessionId,
+      body,
+      caller,
+      signal,
+      current: await this.authorize(sessionId, caller, true),
+      attemptAuthority: this.attemptAuthority,
+      repository: this.repository,
+      admission: this.admission,
+      provider: this.provider,
+      controllers: this.#attemptControllers,
+      now: this.now,
+      audit: (record, outcome, metadata) =>
+        this.recordAudit("provider-attempt", record, outcome, metadata),
+      revokeAudit: (record, cause) =>
+        this.recordAudit("revoke", record, "success", { cause }),
+    });
+  }
+
+  async finalize(
+    sessionId: string,
+    caller: ClientSessionCaller,
+    receiptIds: readonly string[],
+    clientResult?: ModuleAiJsonValue,
+  ) {
+    await this.#recovery;
+    const record = await this.authorize(sessionId, caller, false);
+    return finalizeClientSession({
+      record,
+      repository: this.repository,
+      admission: this.admission,
+      receiptIds,
+      clientResult,
+      audit: (completed, metadata) =>
+        this.recordAudit("finalize", completed, "success", metadata),
+    });
+  }
+
+  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 (
+      !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 conflict("Workflow Client Agent Session 绑定已失效");
+    }
+    return finalizeClientSession({
+      record,
+      repository: this.repository,
+      admission: this.admission,
+      receiptIds,
+      clientResult,
+      canonicalizeResult,
+      audit: (completed, metadata) =>
+        this.recordAudit("finalize", completed, "success", metadata),
+    });
+  }
+
+  async cancel(
+    sessionId: string,
+    caller: ClientSessionCaller,
+    reason?: string,
+  ) {
+    await this.#recovery;
+    const record = await this.authorize(sessionId, caller, false);
+    if (record.status === "cancelled") return sessionView(record);
+    if (record.status !== "active") throw conflict("终态会话不可取消");
+    abortClientSession(this.#attemptControllers, sessionId);
+    const cancelled = await this.repository.transition(
+      sessionId,
+      "active",
+      "cancelled",
+      {
+        terminalDigest: digestText(`cancel\0${reason?.slice(0, 200) ?? ""}`),
+      },
+    );
+    if (!cancelled) {
+      const concurrent = await this.repository.find(sessionId);
+      if (concurrent?.status === "cancelled") return sessionView(concurrent);
+      throw conflict("取消与其它终态操作冲突");
+    }
+    await this.recordAudit("cancel", cancelled, "success", {
+      reasonDigest: digestText(reason?.slice(0, 200) ?? ""),
+    });
+    return sessionView(cancelled);
+  }
+
+  async status(sessionId: string, caller: ClientSessionCaller) {
+    await this.#recovery;
+    return sessionView(await this.authorize(sessionId, caller, false));
+  }
+
+  async revokeActor(actorId: string): Promise<number> {
+    await this.#recovery;
+    return auditRevokedSessions({
+      records: await this.repository.revokeActor(actorId),
+      cause: "actor",
+      controllers: this.#attemptControllers,
+      audit: (record, cause) =>
+        this.recordAudit("revoke", record, "success", { cause }),
+    });
+  }
+
+  async revokeBinding(
+    bindingDigest: `sha256:${string}`,
+    actorId: string,
+  ): Promise<number> {
+    await this.#recovery;
+    return auditRevokedSessions({
+      records: await this.repository.revokeBinding(bindingDigest, actorId),
+      cause: "binding",
+      controllers: this.#attemptControllers,
+      audit: (record, cause) =>
+        this.recordAudit("revoke", record, "success", { cause }),
+    });
+  }
+
+  async revokeHostSession(
+    hostSessionDigest: `sha256:${string}`,
+    actorId: string,
+  ): Promise<number> {
+    await this.#recovery;
+    return auditRevokedSessions({
+      records: await this.repository.revokeHostSession(
+        hostSessionDigest,
+        actorId,
+      ),
+      cause: "host-session",
+      controllers: this.#attemptControllers,
+      audit: (record, cause) =>
+        this.recordAudit("revoke", record, "success", { cause }),
+    });
+  }
+
+  /** 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,
+    requireActive: boolean,
+  ): Promise<ClientSessionRecord> {
+    return authorizeClientSession({
+      sessionId,
+      caller,
+      requireActive,
+      repository: this.repository,
+      admission: this.admission,
+      now: this.now,
+      abort: () => abortClientSession(this.#attemptControllers, sessionId),
+      audit: (record, cause) =>
+        this.recordAudit("revoke", record, "success", { cause }),
+    });
+  }
+
+  private recordAudit(
+    action: Parameters<ClientSessionAuditPort["record"]>[0]["action"],
+    record: ClientSessionRecord,
+    outcome: "success" | "failure",
+    metadata: Readonly<Record<string, string | number | boolean>>,
+  ) {
+    return this.audit.record({
+      action,
+      actorId: record.actorId,
+      clientRunId: record.clientRunId,
+      operationKey: record.operationKey,
+      outcome,
+      metadata,
+    });
+  }
+}

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