create-windy 0.6.12 → 0.6.14

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

@@ -0,0 +1,346 @@
+import { randomBytes, randomUUID } from "node:crypto";
+import type { ModuleAiJsonValue } from "@southwind-ai/server-sdk";
+import type {
+  ClientSessionAdmissionPort,
+  ClientSessionAuditPort,
+  ClientSessionCaller,
+  ClientSessionFinalResult,
+  ClientSessionRecord,
+} from "./contracts.js";
+import { digestJson, digestText, validDigest } 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 {
+  consumeClientAgentCompletion,
+  runClientAgentCompletion,
+} from "./completion.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 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;
+  }) {
+    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 {
+      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(
+    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),
+      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);
+    const terminalDigest = digestJson({
+      receiptIds: [...receiptIds],
+      ...(clientResult === undefined ? {} : { result: clientResult }),
+    });
+    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);
+    if (
+      !receipts.length ||
+      receiptIds.length !== receipts.length ||
+      receipts.some((receipt, index) => receipt.receiptId !== receiptIds[index])
+    ) {
+      throw invalid("Finalize 必须提交本 Run 的完整终末 receipt 链");
+    }
+    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 sessionView(completed);
+  }
+
+  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 }),
+    });
+  }
+
+  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/context-memory/attempt-context-contracts.ts

@@ -0,0 +1,60 @@
+import type { ModuleAiJsonValue } from "@southwind-ai/server-sdk";
+import type {
+  ContextSourceReference,
+  ContextVersion,
+} from "./contracts.js";
+
+export type GovernedContextMessageRole =
+  | "system"
+  | "user"
+  | "assistant"
+  | "tool";
+
+export type ContextMessageOriginType =
+  | "instructions"
+  | "user-prompt"
+  | "artifact"
+  | "context-source"
+  | "provider-output"
+  | "tool-receipt";
+
+export interface ContextMessageOrigin {
+  readonly type: ContextMessageOriginType;
+  readonly sourceId: string;
+  readonly sourceVersion: string;
+  readonly digest: string;
+  readonly source?: ContextSourceReference;
+}
+
+export interface GovernedContextMessage {
+  readonly ordinal: number;
+  readonly role: GovernedContextMessageRole;
+  /** Recoverable whitelist projection; binary Artifact content remains a reference. */
+  readonly content: ModuleAiJsonValue;
+  /** SHA-256 of canonical JSON for the exact governed Provider message. */
+  readonly digest: string;
+  /** SHA-256 of the encrypted whitelist recovery projection. */
+  readonly recoveryDigest: string;
+  readonly origins: readonly ContextMessageOrigin[];
+}
+
+export interface ProviderContextEnvelope {
+  readonly deploymentKey: string;
+  readonly model: string;
+  /** SHA-256 of the exact serialized Provider request body. */
+  readonly requestDigest: string;
+  readonly toolsDigest: string;
+  readonly outputSchemaDigest: string;
+}
+
+export interface GovernedContextVersion extends ContextVersion {
+  readonly provider: ProviderContextEnvelope;
+  readonly messages: readonly GovernedContextMessage[];
+  readonly committedAt: string;
+}
+
+export interface PreparedContextSource {
+  readonly reference: ContextSourceReference;
+  readonly role: GovernedContextMessageRole;
+  readonly content: ModuleAiJsonValue;
+}

package/template/apps/server/src/agent/context-memory/authoritative-source-registry.ts

@@ -0,0 +1,127 @@
+import type {
+  AuthoritativeSourceAccessDecision,
+  AuthoritativeSourceAccessPort,
+  AuthoritativeSourceAccessQuery,
+  SourceInvalidationAppendResult,
+  SourceInvalidationEnvelopeV1,
+} from "../session-invalidation/contracts.js";
+import {
+  createModuleAuthoritativeInvalidationProducer,
+  ModuleAuthoritativeInvalidationUnavailableError,
+  type ModuleAuthoritativeInvalidationHostBinding,
+  type ModuleAuthoritativeInvalidationProducerPort,
+} from "../session-invalidation/module-authoritative-producer.js";
+import type { NodePgDatabase } from "drizzle-orm/node-postgres";
+
+export interface ModuleSourceInvalidationTransactionAdapter {
+  /** Returns only the module's current authoritative business transaction. */
+  currentDatabase(): NodePgDatabase | undefined;
+}
+
+export interface ModuleAuthoritativeSourceAdapterRegistration {
+  readonly moduleKey: string;
+  /** Must resolve the owning module's current object and authorization state. */
+  readonly access: AuthoritativeSourceAccessPort;
+  /** Required for ModuleRequestContext lifecycle writes; absence fails closed. */
+  readonly invalidationTransaction?: ModuleSourceInvalidationTransactionAdapter;
+}
+
+/**
+ * Immutable startup registry for module-owned object authorization.
+ * Missing or duplicate adapters never fall back to a projection or a fake grant.
+ */
+export class ModuleAuthoritativeSourceAccessRegistry
+  implements AuthoritativeSourceAccessPort
+{
+  readonly #adapters: ReadonlyMap<string, AuthoritativeSourceAccessPort>;
+  readonly #transactions: ReadonlyMap<
+    string,
+    ModuleSourceInvalidationTransactionAdapter
+  >;
+
+  constructor(
+    registrations: readonly ModuleAuthoritativeSourceAdapterRegistration[],
+  ) {
+    const adapters = new Map<string, AuthoritativeSourceAccessPort>();
+    const transactions = new Map<
+      string,
+      ModuleSourceInvalidationTransactionAdapter
+    >();
+    for (const registration of registrations) {
+      const moduleKey = registration.moduleKey.trim();
+      if (!moduleKey || adapters.has(moduleKey)) {
+        throw new Error("权威来源 Adapter 注册无效或重复");
+      }
+      adapters.set(moduleKey, registration.access);
+      if (registration.invalidationTransaction) {
+        transactions.set(moduleKey, registration.invalidationTransaction);
+      }
+    }
+    this.#adapters = adapters;
+    this.#transactions = transactions;
+  }
+
+  async authorizeCurrent(
+    query: AuthoritativeSourceAccessQuery,
+  ): Promise<AuthoritativeSourceAccessDecision> {
+    const adapter = this.#adapters.get(query.source.moduleKey);
+    if (!adapter) return denied();
+    try {
+      return await adapter.authorizeCurrent(query);
+    } catch {
+      return denied();
+    }
+  }
+
+  /** Host-only binding: business code receives a producer with immutable module identity. */
+  bindInvalidationProducer(
+    binding: ModuleAuthoritativeInvalidationHostBinding,
+  ): ModuleAuthoritativeInvalidationProducerPort {
+    const moduleKey = binding.moduleKey.trim();
+    if (!this.#adapters.has(moduleKey)) {
+      throw new Error("权威来源 Adapter 未注册");
+    }
+    return createModuleAuthoritativeInvalidationProducer({
+      ...binding,
+      moduleKey,
+    });
+  }
+
+  /** Host-only: resolves the current module transaction at append time. */
+  bindTransactionalInvalidationProducer(binding: {
+    readonly moduleKey: string;
+    readonly authorization: NonNullable<
+      ModuleAuthoritativeInvalidationHostBinding["authorization"]
+    >;
+    readonly appendInTransaction: (
+      db: NodePgDatabase,
+      envelope: SourceInvalidationEnvelopeV1,
+    ) => Promise<SourceInvalidationAppendResult>;
+  }): ModuleAuthoritativeInvalidationProducerPort {
+    const moduleKey = binding.moduleKey.trim();
+    const transaction = this.#transactions.get(moduleKey);
+    if (!this.#adapters.has(moduleKey) || !transaction) {
+      throw new ModuleAuthoritativeInvalidationUnavailableError();
+    }
+    return createModuleAuthoritativeInvalidationProducer({
+      moduleKey,
+      authorization: binding.authorization,
+      append: {
+        append: (envelope) => {
+          let db: NodePgDatabase | undefined;
+          try {
+            db = transaction.currentDatabase();
+          } catch {
+            throw new ModuleAuthoritativeInvalidationUnavailableError();
+          }
+          if (!db) throw new ModuleAuthoritativeInvalidationUnavailableError();
+          return binding.appendInTransaction(db, envelope);
+        },
+      },
+    });
+  }
+}
+
+function denied(): AuthoritativeSourceAccessDecision {
+  return { outcome: "denied", reason: "object-forbidden" };
+}

package/template/apps/server/src/agent/context-memory/context-builder.test.ts

@@ -0,0 +1,160 @@
+import { describe, expect, test } from "bun:test";
+import { buildScopeContext } from "../../data-access/context.js";
+import type { RequestGuardContext } from "../../guards.js";
+import { ContextBuilder, contextDigest } from "./context-builder.js";
+import type {
+  ContextBuildRequest,
+  ContextSourcePort,
+  ContextVersion,
+} from "./contracts.js";
+import { sha256, stableDigest } from "./digest.js";
+
+describe("Context Builder", () => {
+  test("每次 Model attempt 先记录不可变 Context Version", async () => {
+    const recorded: ContextVersion[] = [];
+    const source: ContextSourcePort = {
+      resolve: async (request) => ({
+        role: "system",
+        reference: {
+          ...request,
+          version: "event-sequence-7",
+          sequence: 7,
+          digest: stableDigest({ role: "system", content: "已授权内容" }),
+          validity: {
+            status: "valid",
+            checkedAt: "2026-08-27T00:00:00.000Z",
+          },
+        },
+        content: "已授权内容",
+      }),
+    };
+    const builder = new ContextBuilder(
+      source,
+      {
+        record: async (version) => {
+          expect(Object.isFrozen(version)).toBeTrue();
+          recorded.push(version);
+        },
+      },
+      {
+        now: () => new Date("2026-08-27T00:00:01.000Z"),
+        idFactory: () => "context-1",
+      },
+    );
+    const request = buildRequest();
+    const built = await builder.build(request, new AbortController().signal);
+
+    expect(recorded).toHaveLength(1);
+    expect(built.version).toEqual(recorded[0]!);
+    expect(built.version.sources).toEqual([
+      {
+        moduleKey: "system.agent",
+        kind: "recent-event",
+        id: "event-7",
+        version: "event-sequence-7",
+        sequence: 7,
+        digest: stableDigest({ role: "system", content: "已授权内容" }),
+        validity: {
+          status: "valid",
+          checkedAt: "2026-08-27T00:00:00.000Z",
+        },
+      },
+    ]);
+    expect(built.version.digest).toBe(
+      contextDigest(request, built.version.sources),
+    );
+    expect(Object.isFrozen(built)).toBeTrue();
+    expect(Object.isFrozen(built.sources[0]!.reference.validity)).toBeTrue();
+  });
+
+  test("来源内容摘要不匹配或已过期时拒绝生成版本", async () => {
+    let records = 0;
+    const builder = new ContextBuilder(
+      {
+        resolve: async (request) => ({
+          role: "system",
+          reference: {
+            ...request,
+            version: "v1",
+            sequence: 1,
+            digest: sha256("另一份内容"),
+            validity: {
+              status: "valid",
+              checkedAt: "2026-08-27T00:00:00.000Z",
+              expiresAt: "2026-08-27T00:00:01.000Z",
+            },
+          },
+          content: "实际内容",
+        }),
+      },
+      { record: async () => void (records += 1) },
+      { now: () => new Date("2026-08-27T00:00:02.000Z") },
+    );
+
+    await expect(
+      builder.build(buildRequest(), new AbortController().signal),
+    ).rejects.toMatchObject({ code: "SOURCE_INVALID" });
+    expect(records).toBe(0);
+  });
+
+  test("Session 事实源写入失败时不向 Model 暴露未记录 Context", async () => {
+    const builder = new ContextBuilder(
+      {
+        resolve: async (request) => ({
+          role: "system",
+          reference: {
+            ...request,
+            version: "v1",
+            sequence: 1,
+            digest: stableDigest({ role: "system", content: "内容" }),
+            validity: {
+              status: "valid",
+              checkedAt: "2026-08-27T00:00:00.000Z",
+            },
+          },
+          content: "内容",
+        }),
+      },
+      { record: async () => Promise.reject(new Error("store down")) },
+    );
+
+    await expect(
+      builder.build(buildRequest(), new AbortController().signal),
+    ).rejects.toMatchObject({ code: "SOURCE_UNAVAILABLE" });
+  });
+});
+
+function buildRequest(): ContextBuildRequest {
+  return {
+    sessionId: "session-1",
+    turnId: "turn-1",
+    runId: "run-1",
+    modelAttemptId: "attempt-1",
+    guardContext: guardContext(),
+    sources: [
+      { moduleKey: "system.agent", kind: "recent-event", id: "event-7" },
+    ],
+  };
+}
+
+function guardContext(): RequestGuardContext {
+  return {
+    requestId: "request-1",
+    startedAt: "2026-08-27T00:00:00.000Z",
+    actor: {
+      id: "actor-1",
+      type: "user",
+      name: "办案人员",
+      roleCodes: ["operator"],
+      permissionKeys: ["system.agent-session.read"],
+      scopeContext: buildScopeContext("actor-1", "department-1", [
+        {
+          id: "role-1",
+          code: "operator",
+          dataScope: "self",
+          departmentIds: [],
+        },
+      ]),
+    },
+  };
+}