create-windy 0.6.11 → 0.6.14

package/template/apps/server/src/agent/session-persistence/invalidation-projections.ts

@@ -0,0 +1,229 @@
+import {
+  agentContextSources,
+  agentContextVersions,
+  agentMemoryProjections,
+  agentMemorySources,
+  agentSessions,
+} from "@southwind-ai/database";
+import { and, eq, inArray } from "drizzle-orm";
+import type { NodePgDatabase } from "drizzle-orm/node-postgres";
+import type {
+  SourceInvalidationEnvelopeV1,
+  SourceInvalidationProjectionPort,
+  SourceInvalidationProjectionResult,
+} from "../session-invalidation/contracts.js";
+
+export interface ExternalSourceInvalidationPort {
+  /** session-derived 必须按 scope.sessionId 收敛，禁止降格为普通业务来源删除。 */
+  invalidate(input: {
+    readonly deliveryId: string;
+    readonly envelope: SourceInvalidationEnvelopeV1;
+  }): Promise<SourceInvalidationProjectionResult>;
+}
+
+export class DrizzleContextInvalidationProjection
+  implements SourceInvalidationProjectionPort<"context">
+{
+  readonly target = "context" as const;
+  constructor(private readonly db: NodePgDatabase) {}
+
+  async invalidate(input: {
+    readonly deliveryId: string;
+    readonly envelope: SourceInvalidationEnvelopeV1;
+  }) {
+    if (input.envelope.scope.kind === "authorization") {
+      const sessionIds = await actorSessionIds(
+        this.db,
+        input.envelope.scope.authorization.actorId,
+      );
+      if (!sessionIds.length) return "duplicate" as const;
+      const updated = await this.db
+        .update(agentContextVersions)
+        .set({
+          status: "invalidated",
+          invalidatedAt: Date.parse(input.envelope.occurredAt),
+          invalidationReason: input.envelope.transition.reason,
+        })
+        .where(
+          and(
+            inArray(agentContextVersions.sessionId, sessionIds),
+            eq(agentContextVersions.status, "active"),
+          ),
+        )
+        .returning({ id: agentContextVersions.contextVersionId });
+      return updated.length ? "applied" as const : "duplicate" as const;
+    }
+    if (input.envelope.scope.kind === "session-derived") {
+      const updated = await this.db
+        .update(agentContextVersions)
+        .set({
+          status: "invalidated",
+          invalidatedAt: Date.parse(input.envelope.occurredAt),
+          invalidationReason: input.envelope.transition.reason,
+        })
+        .where(
+          and(
+            eq(
+              agentContextVersions.sessionId,
+              input.envelope.scope.sessionId,
+            ),
+            eq(agentContextVersions.status, "active"),
+          ),
+        )
+        .returning({ id: agentContextVersions.contextVersionId });
+      return updated.length ? "applied" as const : "duplicate" as const;
+    }
+    const source = input.envelope.source;
+    const rows = await this.db
+      .select({ id: agentContextSources.contextVersionId })
+      .from(agentContextSources)
+      .where(
+        and(
+          eq(agentContextSources.sourceModuleKey, source.moduleKey),
+          eq(agentContextSources.sourceKind, source.sourceKind),
+          eq(agentContextSources.sourceId, source.sourceId),
+          eq(agentContextSources.sourceVersion, source.version),
+        ),
+      );
+    if (!rows.length) return "duplicate" as const;
+    const updated = await this.db
+      .update(agentContextVersions)
+      .set({
+        status: "invalidated",
+        invalidatedAt: Date.parse(input.envelope.occurredAt),
+        invalidationReason: input.envelope.transition.reason,
+      })
+      .where(
+        and(
+          inArray(
+            agentContextVersions.contextVersionId,
+            rows.map(({ id }) => id),
+          ),
+          eq(agentContextVersions.status, "active"),
+        ),
+      )
+      .returning({ id: agentContextVersions.contextVersionId });
+    return updated.length ? "applied" as const : "duplicate" as const;
+  }
+}
+
+export class DrizzleMemoryInvalidationProjection
+  implements SourceInvalidationProjectionPort<"memory">
+{
+  readonly target = "memory" as const;
+  constructor(private readonly db: NodePgDatabase) {}
+
+  async invalidate(input: {
+    readonly deliveryId: string;
+    readonly envelope: SourceInvalidationEnvelopeV1;
+  }) {
+    if (input.envelope.scope.kind === "authorization") {
+      const sessionIds = await actorSessionIds(
+        this.db,
+        input.envelope.scope.authorization.actorId,
+      );
+      if (!sessionIds.length) return "duplicate" as const;
+      const updated = await this.db
+        .update(agentMemoryProjections)
+        .set({
+          status: "invalidated",
+          updatedAt: Date.parse(input.envelope.occurredAt),
+        })
+        .where(
+          and(
+            inArray(agentMemoryProjections.derivedFromSessionId, sessionIds),
+            eq(agentMemoryProjections.status, "active"),
+          ),
+        )
+        .returning({ id: agentMemoryProjections.memoryId });
+      return updated.length ? "applied" as const : "duplicate" as const;
+    }
+    if (input.envelope.scope.kind === "session-derived") {
+      const updated = await this.db
+        .update(agentMemoryProjections)
+        .set({
+          status: "invalidated",
+          updatedAt: Date.parse(input.envelope.occurredAt),
+        })
+        .where(
+          and(
+            eq(
+              agentMemoryProjections.derivedFromSessionId,
+              input.envelope.scope.sessionId,
+            ),
+            eq(agentMemoryProjections.status, "active"),
+          ),
+        )
+        .returning({ id: agentMemoryProjections.memoryId });
+      return updated.length ? "applied" as const : "duplicate" as const;
+    }
+    const source = input.envelope.source;
+    const rows = await this.db
+      .select({ id: agentMemorySources.memoryId })
+      .from(agentMemorySources)
+      .where(
+        and(
+          eq(agentMemorySources.sourceModuleKey, source.moduleKey),
+          eq(agentMemorySources.sourceKind, source.sourceKind),
+          eq(agentMemorySources.sourceId, source.sourceId),
+          eq(agentMemorySources.sourceVersion, source.version),
+        ),
+      );
+    if (!rows.length) return "duplicate" as const;
+    const updated = await this.db
+      .update(agentMemoryProjections)
+      .set({
+        status: "invalidated",
+        updatedAt: Date.parse(input.envelope.occurredAt),
+      })
+      .where(
+        and(
+          inArray(
+            agentMemoryProjections.memoryId,
+            rows.map(({ id }) => id),
+          ),
+          eq(agentMemoryProjections.status, "active"),
+        ),
+      )
+      .returning({ id: agentMemoryProjections.memoryId });
+    return updated.length ? "applied" as const : "duplicate" as const;
+  }
+}
+
+export class DelegatingInvalidationProjection<
+  TTarget extends "search" | "embedding",
+> implements SourceInvalidationProjectionPort<TTarget> {
+  constructor(
+    readonly target: TTarget,
+    private readonly delegate: ExternalSourceInvalidationPort,
+  ) {}
+
+  invalidate(input: {
+    readonly deliveryId: string;
+    readonly envelope: SourceInvalidationEnvelopeV1;
+  }) {
+    return this.delegate.invalidate({
+      deliveryId: input.deliveryId,
+      envelope: input.envelope,
+    });
+  }
+}
+
+/** UI reads the governed database projections; no independent cache may bypass them. */
+export class DatabaseBackedUiInvalidationProjection
+  implements SourceInvalidationProjectionPort<"ui">
+{
+  readonly target = "ui" as const;
+
+  async invalidate() {
+    return "applied" as const;
+  }
+}
+
+async function actorSessionIds(db: NodePgDatabase, actorId: string) {
+  const rows = await db
+    .select({ sessionId: agentSessions.sessionId })
+    .from(agentSessions)
+    .where(eq(agentSessions.actorId, actorId));
+  return rows.map(({ sessionId }) => sessionId);
+}

package/template/apps/server/src/agent/session-persistence/payload-codec.ts

@@ -0,0 +1,90 @@
+import {
+  createCipheriv,
+  createDecipheriv,
+  createHash,
+  randomBytes,
+} from "node:crypto";
+
+const aad = Buffer.from("southwind-agent-session-payload-v1");
+const MAX_CIPHER_BYTES = 2 * 1024 * 1024;
+
+export class AgentSessionPayloadCodec {
+  readonly #key: Buffer;
+
+  constructor(secret: string) {
+    if (new TextEncoder().encode(secret).byteLength < 32) {
+      throw new Error("Agent Session 加密 Secret 至少需要 32 字节");
+    }
+    this.#key = createHash("sha256").update(secret).digest();
+  }
+
+  encode(value: unknown): { cipher: string; digest: `sha256:${string}` } {
+    const plaintext = Buffer.from(JSON.stringify(value), "utf8");
+    if (plaintext.byteLength > MAX_CIPHER_BYTES) {
+      throw new AgentSessionPayloadCodecError("Session payload 超过大小限制");
+    }
+    const iv = randomBytes(12);
+    const cipher = createCipheriv("aes-256-gcm", this.#key, iv);
+    cipher.setAAD(aad);
+    const encrypted = Buffer.concat([cipher.update(plaintext), cipher.final()]);
+    return {
+      cipher: [
+        "v1",
+        iv.toString("base64url"),
+        encrypted.toString("base64url"),
+        cipher.getAuthTag().toString("base64url"),
+      ].join("."),
+      digest: digest(plaintext),
+    };
+  }
+
+  decode<T>(value: string, expectedDigest: string): T {
+    try {
+      if (value.length > MAX_CIPHER_BYTES * 2) throw new Error("too large");
+      const [version, ivValue, encryptedValue, tagValue, extra] =
+        value.split(".");
+      if (version !== "v1" || !ivValue || !encryptedValue || !tagValue || extra) {
+        throw new Error("shape");
+      }
+      const decipher = createDecipheriv(
+        "aes-256-gcm",
+        this.#key,
+        decode(ivValue, 12),
+      );
+      decipher.setAAD(aad);
+      decipher.setAuthTag(decode(tagValue, 16));
+      const plaintext = Buffer.concat([
+        decipher.update(decode(encryptedValue)),
+        decipher.final(),
+      ]);
+      if (digest(plaintext) !== expectedDigest) throw new Error("digest");
+      return JSON.parse(plaintext.toString("utf8")) as T;
+    } catch (error) {
+      if (error instanceof AgentSessionPayloadCodecError) throw error;
+      throw new AgentSessionPayloadCodecError("Session payload 无法解密或校验");
+    }
+  }
+}
+
+export class AgentSessionPayloadCodecError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "AgentSessionPayloadCodecError";
+  }
+}
+
+function digest(value: Buffer): `sha256:${string}` {
+  return `sha256:${createHash("sha256").update(value).digest("hex")}`;
+}
+
+function decode(value: string, byteSize?: number): Buffer {
+  if (!/^[A-Za-z0-9_-]+$/.test(value)) throw new Error("base64url");
+  const decoded = Buffer.from(value, "base64url");
+  if (
+    decoded.toString("base64url") !== value ||
+    (byteSize !== undefined && decoded.byteLength !== byteSize)
+  ) {
+    throw new Error("canonical base64url");
+  }
+  return decoded;
+}

package/template/apps/server/src/agent/session-projection-access.ts

@@ -0,0 +1,155 @@
+import { createHash } from "node:crypto";
+import { captureAuthorizationScope } from "../data-access/scope-snapshot.js";
+import type { RequestActor, RequestGuardContext } from "../guards.js";
+import type {
+  AuthoritativeSourceAccessPort,
+  CausalSourceReference,
+  SourceAuthorizationCoordinate,
+} from "./session-invalidation/contracts.js";
+import { requireAuthoritativeSourceRead } from "./session-invalidation/read-guard.js";
+import {
+  createSourceChainAudit,
+  withSourceChainAudit,
+} from "./session-source-chain-authorizer.js";
+
+export interface CurrentSourceAuthorizationPort {
+  /** Resolve the current canonical authorization generation, never a client claim. */
+  current(
+    context: RequestGuardContext,
+  ): Promise<SourceAuthorizationCoordinate>;
+}
+
+/** Re-resolves the Actor from the canonical user/role repositories per read. */
+export class ResolvingCurrentSourceAuthorizationPort
+  implements CurrentSourceAuthorizationPort
+{
+  constructor(
+    private readonly resolveActor: (
+      actorId: string,
+    ) => Promise<RequestActor | undefined>,
+  ) {}
+
+  async current(
+    context: RequestGuardContext,
+  ): Promise<SourceAuthorizationCoordinate> {
+    const actor = await this.resolveActor(context.actor.id);
+    if (!actor || actor.type === "anonymous") throw unavailable();
+    return authorizationCoordinateForActor(actor);
+  }
+}
+
+export interface ProjectionSourceCoordinate {
+  readonly moduleKey: string;
+  readonly kind: string;
+  readonly id: string;
+  readonly version: string;
+  readonly sequence: number;
+  readonly digest?: string;
+  readonly valid: boolean;
+}
+
+export class SessionProjectionSourceUnavailableError extends Error {
+  readonly code = "SESSION_PROJECTION_UNAVAILABLE" as const;
+
+  constructor() {
+    super("Session 投影暂不可用");
+    this.name = "SessionProjectionSourceUnavailableError";
+  }
+}
+
+/** Authorizes every source before any Context or Memory projection is exposed. */
+export class SessionProjectionSourceAuthorizer {
+  constructor(
+    private readonly sources?: AuthoritativeSourceAccessPort,
+    private readonly authorizations?: CurrentSourceAuthorizationPort,
+  ) {}
+
+  async requireAll(
+    coordinates: readonly ProjectionSourceCoordinate[],
+    context: RequestGuardContext,
+  ): Promise<void> {
+    if (!this.sources || !this.authorizations) throw unavailable();
+    if (!coordinates.length) return;
+    let authorization: SourceAuthorizationCoordinate;
+    try {
+      authorization = await this.authorizations.current(context);
+    } catch {
+      throw unavailable();
+    }
+    const expectedScope = `sha256:${captureAuthorizationScope(
+      context.actor.scopeContext,
+    ).hash}`;
+    if (
+      authorization.actorId !== context.actor.id ||
+      authorization.scopeDigest !== expectedScope ||
+      !Number.isSafeInteger(authorization.generation) ||
+      authorization.generation < 1
+    ) {
+      throw unavailable();
+    }
+    const chainAudit = createSourceChainAudit();
+    for (const coordinate of coordinates) {
+      if (!validCoordinate(coordinate)) throw unavailable();
+      try {
+        await requireAuthoritativeSourceRead(this.sources, withSourceChainAudit({
+          source: causalSource(coordinate),
+          authorization,
+          requestId: context.requestId,
+        }, chainAudit));
+      } catch {
+        throw unavailable();
+      }
+    }
+  }
+}
+
+function causalSource(
+  coordinate: ProjectionSourceCoordinate,
+): CausalSourceReference {
+  return {
+    moduleKey: coordinate.moduleKey,
+    sourceKind: coordinate.kind,
+    sourceId: coordinate.id,
+    version: coordinate.version,
+    sequence: coordinate.sequence,
+    ...(coordinate.digest ? { digest: coordinate.digest } : {}),
+  };
+}
+
+function validCoordinate(value: ProjectionSourceCoordinate): boolean {
+  return (
+    value.valid &&
+    Boolean(value.moduleKey.trim()) &&
+    Boolean(value.kind.trim()) &&
+    Boolean(value.id.trim()) &&
+    Boolean(value.version.trim()) &&
+    Number.isSafeInteger(value.sequence) &&
+    value.sequence > 0
+  );
+}
+
+function unavailable(): SessionProjectionSourceUnavailableError {
+  return new SessionProjectionSourceUnavailableError();
+}
+
+/** A current, server-derived authorization fingerprint represented as a safe integer. */
+export function authorizationCoordinateForActor(
+  actor: RequestActor,
+): SourceAuthorizationCoordinate {
+  const scopeDigest = `sha256:${captureAuthorizationScope(
+    actor.scopeContext,
+  ).hash}`;
+  const fingerprint = JSON.stringify({
+    actorId: actor.id,
+    actorType: actor.type,
+    permissions: [...actor.permissionKeys].sort(),
+    roles: [...actor.roleCodes].sort(),
+    scopeDigest,
+  });
+  const prefix = createHash("sha256").update(fingerprint).digest("hex").slice(0, 13);
+  return {
+    actorId: actor.id,
+    scopeDigest,
+    generation: Math.max(1, Number.parseInt(prefix, 16)),
+  };
+}

package/template/apps/server/src/agent/session-projection-bootstrap.ts

@@ -0,0 +1,87 @@
+import type { NodePgDatabase } from "drizzle-orm/node-postgres";
+import type { RouteApp } from "../system/routes.js";
+import { SessionEventLogService } from "./session-log/service.js";
+import { PersistentAgentRunSessionLink } from "./session-run-link.js";
+import {
+  DrizzleContextProjectionReader,
+  DrizzleMemoryProjectionStore,
+} from "./session-persistence/drizzle-context-memory.js";
+import { DrizzleSessionMutationCoordinator } from "./session-persistence/drizzle-session-mutations.js";
+import { DrizzleSessionEventRepository } from "./session-persistence/drizzle-session-repository.js";
+import { DrizzleSessionRunProjectionReceiptStore } from "./session-persistence/drizzle-run-projection-receipt.js";
+import { AgentSessionPayloadCodec } from "./session-persistence/payload-codec.js";
+import { AgentSessionProjectionFacade } from "./session-projection-facade.js";
+import { registerAgentSessionProjectionRoutes } from "./session-projection-routes.js";
+import type { CurrentSourceAuthorizationPort } from "./session-projection-access.js";
+import type { AuthoritativeSourceAccessPort } from "./session-invalidation/contracts.js";
+import type { MemoryObjectAuthorizationPort } from "./context-memory/contracts.js";
+
+const paths = [
+  "/agent/harness/sessions",
+  "/agent/harness/sessions/:sessionId",
+  "/agent/harness/sessions/:sessionId/context-versions",
+  "/agent/harness/sessions/:sessionId/memories",
+] as const;
+
+export function registerAgentSessionProjectionRuntime(
+  app: RouteApp,
+  db: NodePgDatabase | undefined,
+  secret: string,
+  options: {
+    readonly sourceAccess?: AuthoritativeSourceAccessPort;
+    readonly currentSourceAuthorization?: CurrentSourceAuthorizationPort;
+    readonly memoryObjectAuthorization?: MemoryObjectAuthorizationPort;
+  } = {},
+) {
+  if (!db) {
+    registerUnavailable(app);
+    return undefined;
+  }
+  const codec = new AgentSessionPayloadCodec(secret);
+  const repository = new DrizzleSessionEventRepository(db, codec);
+  const memories = new DrizzleMemoryProjectionStore(db, codec);
+  const projectionReceipts = new DrizzleSessionRunProjectionReceiptStore(db);
+  const facade = new AgentSessionProjectionFacade(
+    repository,
+    new SessionEventLogService(repository),
+    new DrizzleContextProjectionReader(db),
+    memories,
+    new DrizzleSessionMutationCoordinator(db, codec),
+    options.sourceAccess,
+    options.currentSourceAuthorization,
+    options.memoryObjectAuthorization,
+  );
+  registerAgentSessionProjectionRoutes(app, facade);
+  return {
+    facade,
+    sessionLog: new SessionEventLogService(repository),
+    projectionReceipts,
+    runLink: new PersistentAgentRunSessionLink(
+      repository,
+      new SessionEventLogService(repository),
+      projectionReceipts,
+    ),
+  };
+}
+
+function registerUnavailable(app: RouteApp) {
+  for (const path of paths) app.get(path, unavailable);
+  app.post("/agent/harness/sessions", unavailable);
+  for (const action of ["checkpoints", "replay", "forks", "archive"] as const) {
+    app.post(`/agent/harness/sessions/:sessionId/${action}`, unavailable);
+  }
+  app.delete(
+    "/agent/harness/sessions/:sessionId/memories/:memoryId",
+    unavailable,
+  );
+}
+
+function unavailable() {
+  return Response.json(
+    {
+      code: "SESSION_PERSISTENCE_UNAVAILABLE",
+      message: "长期 Agent Session 需要 PostgreSQL 持久化",
+    },
+    { status: 503 },
+  );
+}

package/template/apps/server/src/agent/session-projection-errors.ts

@@ -0,0 +1,22 @@
+import { SessionProjectionSourceUnavailableError } from "./session-projection-access.js";
+
+export class AgentSessionProjectionError extends Error {
+  constructor(
+    readonly code: "SESSION_NOT_FOUND" | "SESSION_PROJECTION_UNAVAILABLE",
+    readonly status: 404 | 503,
+  ) {
+    super(code);
+  }
+}
+
+export function inaccessibleSessionProjection() {
+  return new AgentSessionProjectionError("SESSION_NOT_FOUND", 404);
+}
+
+export function unavailableSessionProjection() {
+  return new SessionProjectionSourceUnavailableError();
+}
+
+export function isProjectionSourceUnavailable(error: unknown): boolean {
+  return error instanceof SessionProjectionSourceUnavailableError;
+}