create-windy 0.6.12 → 0.6.15

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

@@ -0,0 +1,285 @@
+import type { AgentWorkflowNode } from "@southwind-ai/shared";
+import { CLIENT_AGENT_WORKFLOW_ARTIFACT_WORK_ID_PREFIX } from "@southwind-ai/server-sdk";
+import type { DurableJobService } from "../../jobs/service.js";
+import { hashAuthorizationScope } from "../../data-access/scope-snapshot.js";
+import { digestJson } from "../client-session/digest.js";
+import { DrizzleAgentWorkflowRepository } from "../../agent-workflow/drizzle-repository.js";
+import { ReceiptAgentWorkflowNodeInputPort } from "../../agent-workflow/node-input-receipt-port.js";
+import { schedulerAdapterContext } from "../../agent-workflow/scheduler-context.js";
+import {
+  clientWorkflowBindingCommitment,
+  ClientAgentWorkflowArtifactBindingRegistry,
+} from "./binding-registry.js";
+import { assertClientAgentWorkflowReleaseBinding } from "./release-binding.js";
+import {
+  clientAgentWorkflowArtifactTaskKey,
+  type ClientAgentWorkflowBeginFacts,
+} from "./contracts.js";
+import { requireClientWorkflowFrozenScope } from "./scope-authority.js";
+
+export interface ClientAgentWorkflowJobPayload {
+  readonly commandId: string;
+  readonly runId: string;
+  readonly nodeRunId: string;
+  readonly effectGeneration?: number;
+  readonly requestDigest?: string;
+}
+
+type WorkflowSnapshot = NonNullable<
+  Awaited<ReturnType<DrizzleAgentWorkflowRepository["getSnapshot"]>>
+>;
+
+export class ClientAgentWorkflowFactsLoader {
+  readonly #inputs = new ReceiptAgentWorkflowNodeInputPort();
+
+  constructor(
+    private readonly workflows: DrizzleAgentWorkflowRepository,
+    private readonly jobs: DurableJobService,
+    private readonly bindings: ClientAgentWorkflowArtifactBindingRegistry,
+  ) {}
+
+  async load(input: {
+    jobId: string;
+    payload: ClientAgentWorkflowJobPayload;
+    signal: AbortSignal;
+  }): Promise<ClientAgentWorkflowBeginFacts> {
+    const [snapshot, job] = await Promise.all([
+      this.workflows.getSnapshot(input.payload.runId),
+      this.jobs.get(input.jobId),
+    ]);
+    if (!snapshot || !job) throw invalid("WORKFLOW_FACTS_NOT_FOUND");
+    const release = await this.workflows.getRelease(snapshot.run.releaseId);
+    const nodeRun = snapshot.nodeRuns.find(
+      ({ nodeRunId }) => nodeRunId === input.payload.nodeRunId,
+    );
+    const command = snapshot.sideEffects.find(
+      ({ commandId }) => commandId === input.payload.commandId,
+    );
+    const node = release?.definition.nodes.find(
+      ({ id }) => id === nodeRun?.nodeId,
+    );
+    if (!release || !nodeRun || !command || !node) {
+      throw invalid("WORKFLOW_COORDINATE_NOT_FOUND");
+    }
+    assertJobAndFence({ input, snapshot, job, nodeRun, command, node });
+    const binding = this.bindings.require(
+      release.definition.workflowKey,
+      node.id,
+    );
+    assertClientAgentWorkflowReleaseBinding(release, binding);
+    const context = schedulerAdapterContext({
+      snapshot,
+      release,
+      nodeRun,
+      node,
+      signal: input.signal,
+    });
+    const value = await this.#inputs.readJson({
+      context,
+      ...(node.inputSchemaKey ? { schemaKey: node.inputSchemaKey } : {}),
+    });
+    const record: ClientAgentWorkflowBeginFacts["record"] = {
+      workId: workflowWorkId(command.commandId),
+      commandId: command.commandId,
+      durableJobId: input.jobId,
+      runId: snapshot.run.runId,
+      nodeRunId: nodeRun.nodeRunId,
+      effectKind: "job",
+      taskKey: clientAgentWorkflowArtifactTaskKey,
+      operationKey: binding.operationKey,
+      bindingDigest: digestJson(clientWorkflowBindingCommitment(binding)),
+      actorId: snapshot.run.actorId,
+      scopeDigest: requireDigest(snapshot.run.scopeDigest),
+      authorizationSnapshotDigest: requireDigest(
+        command.authorizationSnapshotDigest,
+      ),
+      runPolicyDigest: requireDigest(command.runPolicyDigest),
+      requestDigest: requireDigest(command.requestDigest),
+      inputDigest: digestJson(value),
+      effectGeneration: command.generation,
+      effectFenceTokenDigest: requireDigest(command.fenceTokenDigest),
+      status: "pending",
+      claimGeneration: 0,
+      historySequence: 0,
+      version: 1,
+      createdAt: Date.now(),
+      updatedAt: Date.now(),
+    };
+    return {
+      input: value,
+      inputArtifacts: context.inputArtifacts,
+      binding,
+      frozenScope: requireClientWorkflowFrozenScope(record, job),
+      record,
+    };
+  }
+
+  async loadTerminal(input: {
+    record: ClientAgentWorkflowBeginFacts["record"];
+    signal: AbortSignal;
+  }): Promise<
+    Pick<
+      ClientAgentWorkflowBeginFacts,
+      "binding" | "input" | "inputArtifacts" | "frozenScope"
+    >
+  > {
+    const [snapshot, job] = await Promise.all([
+      this.workflows.getSnapshot(input.record.runId),
+      this.jobs.get(input.record.durableJobId),
+    ]);
+    if (!snapshot || !job) throw invalid("WORKFLOW_FACTS_NOT_FOUND");
+    const release = await this.workflows.getRelease(snapshot.run.releaseId);
+    const nodeRun = snapshot.nodeRuns.find(
+      ({ nodeRunId }) => nodeRunId === input.record.nodeRunId,
+    );
+    const command = snapshot.sideEffects.find(
+      ({ commandId }) => commandId === input.record.commandId,
+    );
+    const node = release?.definition.nodes.find(
+      ({ id }) => id === nodeRun?.nodeId,
+    );
+    if (!release || !nodeRun || !command || !node) {
+      throw invalid("WORKFLOW_COORDINATE_NOT_FOUND");
+    }
+    const binding = this.bindings.require(
+      release.definition.workflowKey,
+      node.id,
+    );
+    assertClientAgentWorkflowReleaseBinding(release, binding);
+    const context = schedulerAdapterContext({
+      snapshot,
+      release,
+      nodeRun,
+      node,
+      signal: input.signal,
+    });
+    const value = await this.#inputs.readJson({
+      context,
+      ...(node.inputSchemaKey ? { schemaKey: node.inputSchemaKey } : {}),
+    });
+    assertTerminalIdentity({
+      record: input.record,
+      snapshot,
+      release,
+      nodeRun,
+      command,
+      node,
+      binding,
+      inputDigest: digestJson(value),
+    });
+    return {
+      binding,
+      input: value,
+      inputArtifacts: context.inputArtifacts,
+      frozenScope: requireClientWorkflowFrozenScope(input.record, job),
+    };
+  }
+}
+
+function assertJobAndFence(input: {
+  input: {
+    jobId: string;
+    payload: ClientAgentWorkflowJobPayload;
+  };
+  snapshot: WorkflowSnapshot;
+  job: NonNullable<Awaited<ReturnType<DurableJobService["get"]>>>;
+  nodeRun: WorkflowSnapshot["nodeRuns"][number];
+  command: WorkflowSnapshot["sideEffects"][number];
+  node: AgentWorkflowNode;
+}) {
+  const { payload } = input.input;
+  const { job } = input.job;
+  if (
+    job.id !== input.input.jobId ||
+    job.handlerKey !== clientAgentWorkflowArtifactTaskKey ||
+    job.requestedBy !== input.snapshot.run.actorId ||
+    !job.authorizationScope ||
+    `sha256:${hashAuthorizationScope(job.authorizationScope)}` !==
+      input.snapshot.run.scopeDigest ||
+    input.node.type !== "job" ||
+    input.node.taskKey !== clientAgentWorkflowArtifactTaskKey ||
+    input.nodeRun.nodeType !== "job" ||
+    input.nodeRun.runId !== input.snapshot.run.runId ||
+    input.command.runId !== input.snapshot.run.runId ||
+    input.command.nodeRunId !== input.nodeRun.nodeRunId ||
+    input.command.effectKind !== "job" ||
+    input.command.status !== "dispatched" ||
+    input.command.generation < 1 ||
+    !input.command.fenceTokenDigest ||
+    input.command.authorizationSnapshotDigest !==
+      input.snapshot.run.authorizationSnapshotDigest ||
+    input.command.runPolicyDigest !==
+      input.snapshot.run.executionPolicyDigest ||
+    (payload.effectGeneration !== undefined &&
+      payload.effectGeneration !== input.command.generation) ||
+    (payload.requestDigest !== undefined &&
+      payload.requestDigest !== input.command.requestDigest)
+  ) {
+    throw invalid("WORKFLOW_EFFECT_FENCE_INVALID");
+  }
+}
+
+function assertTerminalIdentity(input: {
+  record: ClientAgentWorkflowBeginFacts["record"];
+  snapshot: WorkflowSnapshot;
+  release: NonNullable<
+    Awaited<ReturnType<DrizzleAgentWorkflowRepository["getRelease"]>>
+  >;
+  nodeRun: WorkflowSnapshot["nodeRuns"][number];
+  command: WorkflowSnapshot["sideEffects"][number];
+  node: AgentWorkflowNode;
+  binding: ClientAgentWorkflowBeginFacts["binding"];
+  inputDigest: `sha256:${string}`;
+}) {
+  const { record, snapshot, release, nodeRun, command, node, binding } = input;
+  if (
+    snapshot.run.releaseId !== release.releaseId ||
+    snapshot.run.runId !== record.runId ||
+    snapshot.run.actorId !== record.actorId ||
+    snapshot.run.scopeDigest !== record.scopeDigest ||
+    snapshot.run.authorizationSnapshotDigest !==
+      record.authorizationSnapshotDigest ||
+    snapshot.run.executionPolicyDigest !== record.runPolicyDigest ||
+    !["running", "waiting", "completed"].includes(snapshot.run.status) ||
+    nodeRun.nodeRunId !== record.nodeRunId ||
+    nodeRun.runId !== record.runId ||
+    nodeRun.nodeId !== binding.nodeId ||
+    nodeRun.nodeType !== "job" ||
+    !["running", "waiting", "completed"].includes(nodeRun.status) ||
+    node.type !== "job" ||
+    node.taskKey !== clientAgentWorkflowArtifactTaskKey ||
+    command.commandId !== record.commandId ||
+    command.runId !== record.runId ||
+    command.nodeRunId !== record.nodeRunId ||
+    command.effectKind !== record.effectKind ||
+    command.effectKey !== node.id ||
+    command.adapter.kind !== "durable-job" ||
+    !["dispatched", "committed", "reconciled"].includes(command.status) ||
+    command.generation !== record.effectGeneration ||
+    command.requestDigest !== record.requestDigest ||
+    command.fenceTokenDigest !== record.effectFenceTokenDigest ||
+    command.authorizationSnapshotDigest !==
+      record.authorizationSnapshotDigest ||
+    command.runPolicyDigest !== record.runPolicyDigest ||
+    record.taskKey !== clientAgentWorkflowArtifactTaskKey ||
+    record.operationKey !== binding.operationKey ||
+    record.bindingDigest !==
+      digestJson(clientWorkflowBindingCommitment(binding)) ||
+    record.inputDigest !== input.inputDigest
+  ) {
+    throw invalid("WORKFLOW_TERMINAL_IDENTITY_INVALID");
+  }
+}
+
+function workflowWorkId(commandId: string) {
+  return `${CLIENT_AGENT_WORKFLOW_ARTIFACT_WORK_ID_PREFIX}${digestJson({ commandId }).slice("sha256:".length, 53)}`;
+}
+
+function requireDigest(value: string | undefined): `sha256:${string}` {
+  if (!value?.startsWith("sha256:")) throw invalid("DIGEST_INVALID");
+  return value as `sha256:${string}`;
+}
+
+function invalid(code: string) {
+  return new Error(code);
+}

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: [],
+        },
+      ]),
+    },
+  };
+}