create-windy 0.6.11 → 0.6.14

package/template/apps/server/src/agent/session-log/in-memory-repository.ts

@@ -0,0 +1,340 @@
+import {
+  assertGovernance,
+  assertId,
+  assertSequence,
+  assertSessionRecord,
+  assertTimestamp,
+  type SessionCheckpoint,
+  type SessionCheckpointId,
+  type SessionId,
+  type SessionRecord,
+} from "./domain.js";
+import {
+  assertPendingSessionEvent,
+  assertSessionEventEnvelope,
+  SESSION_EVENT_SCHEMA_VERSION,
+  type PendingSessionEvent,
+  type SessionEventEnvelope,
+} from "./events.js";
+import {
+  SessionRepositoryConflict,
+  type ArchiveSessionInput,
+  type AppendSessionEventsInput,
+  type CreateCheckpointInput,
+  type CreateSessionInput,
+  type ForkSessionInput,
+  type SessionAppendResult,
+  type SessionEventRepository,
+  type SessionForkResult,
+} from "./repository.js";
+
+export class InMemorySessionEventRepository implements SessionEventRepository {
+  readonly #sessions = new Map<SessionId, SessionRecord>();
+  readonly #events = new Map<SessionId, SessionEventEnvelope[]>();
+  readonly #eventIds = new Map<string, SessionEventEnvelope>();
+  readonly #checkpoints = new Map<SessionCheckpointId, SessionCheckpoint>();
+
+  async create(input: CreateSessionInput): Promise<SessionAppendResult> {
+    validateCreate(input);
+    const existing = this.#sessions.get(input.sessionId);
+    if (existing) {
+      const replay = this.replayEvents(input.sessionId, [input.createdEvent]);
+      if (replay) return result(existing, replay, true);
+      throw new SessionRepositoryConflict("SESSION_EXISTS");
+    }
+    this.assertEventIdsAvailable([input.createdEvent]);
+    const event = envelope(input.sessionId, 1, input.createdEvent);
+    const session: SessionRecord = {
+      sessionId: input.sessionId,
+      governance: structuredClone(input.governance),
+      status: "active",
+      headSequence: 1,
+      createdAt: input.createdAt,
+      updatedAt: input.createdEvent.occurredAt,
+      ...(input.lineage ? { lineage: structuredClone(input.lineage) } : {}),
+    };
+    assertSessionRecord(session);
+    this.#sessions.set(session.sessionId, session);
+    this.#events.set(session.sessionId, [event]);
+    this.#eventIds.set(event.eventId, event);
+    return result(session, [event], false);
+  }
+
+  async get(sessionId: SessionId): Promise<SessionRecord | undefined> {
+    return cloneOptional(this.#sessions.get(sessionId));
+  }
+
+  async read(input: {
+    sessionId: SessionId;
+    afterSequence: number;
+    throughSequence?: number;
+    limit: number;
+  }): Promise<readonly SessionEventEnvelope[]> {
+    assertSequence(input.afterSequence, true);
+    if (
+      !Number.isSafeInteger(input.limit) ||
+      input.limit < 1 ||
+      input.limit > 1_000
+    ) throw new Error("Session Event 读取上限无效");
+    if (input.throughSequence !== undefined) {
+      assertSequence(input.throughSequence, true);
+      if (input.throughSequence < input.afterSequence) return [];
+    }
+    return (this.#events.get(input.sessionId) ?? [])
+      .filter(
+        ({ sequence }) =>
+          sequence > input.afterSequence &&
+          (input.throughSequence === undefined ||
+            sequence <= input.throughSequence),
+      )
+      .slice(0, input.limit)
+      .map(clone);
+  }
+
+  async findEvent(sessionId: SessionId, eventId: string) {
+    const event = this.#eventIds.get(eventId);
+    return event?.sessionId === sessionId ? clone(event) : undefined;
+  }
+
+  async append(input: AppendSessionEventsInput): Promise<SessionAppendResult> {
+    if (!input.events.length) throw new Error("Session append 不能为空");
+    input.events.forEach(assertPendingSessionEvent);
+    const session = this.requireActive(input.sessionId);
+    const replay = this.replayEvents(input.sessionId, input.events);
+    if (replay) return result(session, replay, true);
+    if (session.headSequence !== input.expectedSequence) {
+      throw new SessionRepositoryConflict("SEQUENCE_CONFLICT");
+    }
+    this.assertEventIdsAvailable(input.events);
+    const appended = input.events.map((event, index) =>
+      envelope(input.sessionId, input.expectedSequence + index + 1, event),
+    );
+    const updated = advance(session, appended);
+    this.#sessions.set(session.sessionId, updated);
+    this.#events.get(session.sessionId)!.push(...appended);
+    for (const event of appended) this.#eventIds.set(event.eventId, event);
+    return result(updated, appended, false);
+  }
+
+  async checkpoint(input: CreateCheckpointInput) {
+    const session = this.requireActive(input.sessionId);
+    if (
+      input.checkpoint.sessionId !== input.sessionId ||
+      input.checkpoint.throughSequence !== input.expectedSequence ||
+      input.event.data.type !== "checkpoint.created" ||
+      input.event.data.checkpointId !== input.checkpoint.checkpointId
+    ) throw new SessionRepositoryConflict("CHECKPOINT_CONFLICT");
+    const existing = this.#checkpoints.get(input.checkpoint.checkpointId);
+    if (existing) {
+      const replay = this.replayEvents(input.sessionId, [input.event]);
+      if (replay && same(existing, input.checkpoint)) {
+        return result(session, replay, true);
+      }
+      throw new SessionRepositoryConflict("CHECKPOINT_CONFLICT");
+    }
+    const appended = await this.append({
+      sessionId: input.sessionId,
+      expectedSequence: input.expectedSequence,
+      events: [input.event],
+    });
+    this.#checkpoints.set(input.checkpoint.checkpointId, clone(input.checkpoint));
+    return appended;
+  }
+
+  async getCheckpoint(checkpointId: SessionCheckpointId) {
+    return cloneOptional(this.#checkpoints.get(checkpointId));
+  }
+
+  async fork(input: ForkSessionInput): Promise<SessionForkResult> {
+    const parent = this.requireActive(input.parentSessionId);
+    const checkpoint = this.#checkpoints.get(input.checkpointId);
+    validateCreate(input.child);
+    if (
+      !checkpoint ||
+      checkpoint.sessionId !== parent.sessionId ||
+      input.parentEvent.data.type !== "fork.created" ||
+      input.parentEvent.data.childSessionId !== input.child.sessionId ||
+      input.child.lineage?.parentSessionId !== parent.sessionId ||
+      input.child.lineage.checkpointId !== checkpoint.checkpointId ||
+      input.child.lineage.parentSequence !== checkpoint.throughSequence
+    ) throw new SessionRepositoryConflict("FORK_CONFLICT");
+    if (this.#sessions.has(input.child.sessionId)) {
+      const parentReplay = this.replayEvents(parent.sessionId, [input.parentEvent]);
+      const childReplay = this.replayEvents(
+        input.child.sessionId,
+        [input.child.createdEvent],
+      );
+      const child = this.#sessions.get(input.child.sessionId)!;
+      if (parentReplay && childReplay) {
+        return forkResult(parent, child, parentReplay[0]!, childReplay[0]!, true);
+      }
+      throw new SessionRepositoryConflict("FORK_CONFLICT");
+    }
+    if (parent.headSequence !== input.expectedParentSequence) {
+      throw new SessionRepositoryConflict("SEQUENCE_CONFLICT");
+    }
+    this.assertEventIdsAvailable([input.parentEvent, input.child.createdEvent]);
+    const parentEvent = envelope(
+      parent.sessionId,
+      parent.headSequence + 1,
+      input.parentEvent,
+    );
+    const childEvent = envelope(input.child.sessionId, 1, input.child.createdEvent);
+    const updatedParent = advance(parent, [parentEvent]);
+    const child: SessionRecord = {
+      sessionId: input.child.sessionId,
+      governance: structuredClone(input.child.governance),
+      status: "active",
+      headSequence: 1,
+      createdAt: input.child.createdAt,
+      updatedAt: input.child.createdEvent.occurredAt,
+      lineage: structuredClone(input.child.lineage!),
+    };
+    assertSessionRecord(child);
+    this.#sessions.set(parent.sessionId, updatedParent);
+    this.#sessions.set(child.sessionId, child);
+    this.#events.get(parent.sessionId)!.push(parentEvent);
+    this.#events.set(child.sessionId, [childEvent]);
+    this.#eventIds.set(parentEvent.eventId, parentEvent);
+    this.#eventIds.set(childEvent.eventId, childEvent);
+    return forkResult(updatedParent, child, parentEvent, childEvent, false);
+  }
+
+  async archive(input: ArchiveSessionInput): Promise<SessionAppendResult> {
+    const existing = this.#sessions.get(input.sessionId);
+    if (existing?.status === "archived") {
+      const replay = this.replayEvents(input.sessionId, [input.event]);
+      if (replay) return result(existing, replay, true);
+    }
+    const session = this.requireActive(input.sessionId);
+    if (input.event.data.type !== "session.archived") {
+      throw new SessionRepositoryConflict("EVENT_ID_CONFLICT");
+    }
+    const appended = await this.append({
+      sessionId: input.sessionId,
+      expectedSequence: input.expectedSequence,
+      events: [input.event],
+    });
+    const archived = { ...appended.session, status: "archived" as const };
+    this.#sessions.set(session.sessionId, archived);
+    return { ...appended, session: clone(archived) };
+  }
+
+  private requireActive(sessionId: SessionId): SessionRecord {
+    const session = this.#sessions.get(sessionId);
+    if (!session) throw new SessionRepositoryConflict("SESSION_NOT_FOUND");
+    if (session.status !== "active") {
+      throw new SessionRepositoryConflict("SESSION_NOT_ACTIVE");
+    }
+    return session;
+  }
+
+  private replayEvents(
+    sessionId: SessionId,
+    pending: readonly PendingSessionEvent[],
+  ) {
+    const existing = pending.map(({ eventId }) => this.#eventIds.get(eventId));
+    if (existing.every(Boolean)) {
+      const resolved = existing as SessionEventEnvelope[];
+      if (
+        resolved.every(
+          (event, index) =>
+            event.sessionId === sessionId && samePending(event, pending[index]!),
+        )
+      ) return resolved.map(clone);
+      throw new SessionRepositoryConflict("EVENT_ID_CONFLICT");
+    }
+    if (existing.some(Boolean)) {
+      throw new SessionRepositoryConflict("EVENT_ID_CONFLICT");
+    }
+    return undefined;
+  }
+
+  private assertEventIdsAvailable(events: readonly PendingSessionEvent[]) {
+    const ids = new Set<string>();
+    for (const event of events) {
+      if (ids.has(event.eventId) || this.#eventIds.has(event.eventId)) {
+        throw new SessionRepositoryConflict("EVENT_ID_CONFLICT");
+      }
+      ids.add(event.eventId);
+    }
+  }
+}
+
+function validateCreate(input: CreateSessionInput): void {
+  assertId(input.sessionId, "session_", "Session");
+  assertGovernance(input.governance);
+  assertTimestamp(input.createdAt, "Session createdAt");
+  assertPendingSessionEvent(input.createdEvent);
+  const data = input.createdEvent.data;
+  if (
+    data.type !== "session.created" ||
+    !same(data.governance, input.governance) ||
+    !same(data.lineage, input.lineage)
+  ) throw new Error("Session 首事件与身份不一致");
+}
+
+function envelope(
+  sessionId: SessionId,
+  sequence: number,
+  pending: PendingSessionEvent,
+): SessionEventEnvelope {
+  const event = {
+    ...clone(pending),
+    sessionId,
+    sequence,
+    schemaVersion: SESSION_EVENT_SCHEMA_VERSION,
+  };
+  assertSessionEventEnvelope(event);
+  return event;
+}
+
+function advance(session: SessionRecord, events: readonly SessionEventEnvelope[]) {
+  const updated: SessionRecord = {
+    ...session,
+    headSequence: events.at(-1)!.sequence,
+    updatedAt: events.at(-1)!.occurredAt,
+  };
+  assertSessionRecord(updated);
+  return updated;
+}
+
+function result(
+  session: SessionRecord,
+  events: readonly SessionEventEnvelope[],
+  replayed: boolean,
+): SessionAppendResult {
+  return { session: clone(session), events: events.map(clone), replayed };
+}
+
+function forkResult(
+  parent: SessionRecord,
+  child: SessionRecord,
+  parentEvent: SessionEventEnvelope,
+  childEvent: SessionEventEnvelope,
+  replayed: boolean,
+): SessionForkResult {
+  return {
+    parent: clone(parent),
+    child: clone(child),
+    parentEvent: clone(parentEvent),
+    childEvent: clone(childEvent),
+    replayed,
+  };
+}
+
+function samePending(left: SessionEventEnvelope, right: PendingSessionEvent) {
+  return left.occurredAt === right.occurredAt && same(left.data, right.data);
+}
+
+function same(left: unknown, right: unknown): boolean {
+  return JSON.stringify(left) === JSON.stringify(right);
+}
+
+function clone<T>(value: T): T {
+  return structuredClone(value);
+}
+
+function cloneOptional<T>(value: T | undefined): T | undefined {
+  return value === undefined ? undefined : clone(value);
+}

package/template/apps/server/src/agent/session-log/lifecycle.ts

@@ -0,0 +1,67 @@
+import {
+  createSessionIdentityFactory,
+  type SessionEventId,
+  type SessionId,
+  type SessionIdentityFactory,
+} from "./domain.js";
+import {
+  SESSION_EVENT_SCHEMA_VERSION,
+  type SessionEventEnvelope,
+} from "./events.js";
+import { assertSessionEventHistory } from "./history.js";
+import type { SessionEventRepository } from "./repository.js";
+
+export class SessionLifecycleService {
+  constructor(
+    private readonly repository: SessionEventRepository,
+    private readonly identities: SessionIdentityFactory =
+      createSessionIdentityFactory(),
+    private readonly now: () => Date = () => new Date(),
+  ) {}
+
+  async archive(input: {
+    readonly sessionId: SessionId;
+    readonly expectedSequence: number;
+    readonly eventId?: SessionEventId;
+    readonly reason: "user-request" | "retention-policy" | "source-deleted";
+  }) {
+    const occurredAt = this.now().toISOString();
+    const event = {
+      eventId: input.eventId ?? this.identities.eventId(),
+      occurredAt,
+      data: { type: "session.archived" as const, reason: input.reason },
+    };
+    const history = await this.readAll(input.sessionId, input.expectedSequence);
+    assertSessionEventHistory([
+      ...history,
+      {
+        ...event,
+        sessionId: input.sessionId,
+        sequence: input.expectedSequence + 1,
+        schemaVersion: SESSION_EVENT_SCHEMA_VERSION,
+      },
+    ]);
+    return this.repository.archive({
+      sessionId: input.sessionId,
+      expectedSequence: input.expectedSequence,
+      event,
+    });
+  }
+
+  private async readAll(sessionId: SessionId, throughSequence: number) {
+    const events: SessionEventEnvelope[] = [];
+    let afterSequence = 0;
+    while (afterSequence < throughSequence) {
+      const page = await this.repository.read({
+        sessionId,
+        afterSequence,
+        throughSequence,
+        limit: 1_000,
+      });
+      if (!page.length) break;
+      events.push(...page);
+      afterSequence = page.at(-1)!.sequence;
+    }
+    return events;
+  }
+}

package/template/apps/server/src/agent/session-log/replay-policy.ts

@@ -0,0 +1,76 @@
+import type { ModuleAiJsonValue } from "@southwind-ai/server-sdk";
+import type {
+  SessionEventId,
+  SessionId,
+  Sha256Digest,
+} from "./domain.js";
+import type { SessionEventEnvelope } from "./events.js";
+
+export interface ReadOnlySessionReplay {
+  readonly mode: "read-only";
+  readonly sideEffectPolicy: "recorded-only";
+  readonly sessionId: SessionId;
+  readonly segments: readonly {
+    readonly sessionId: SessionId;
+    readonly throughSequence: number;
+    readonly events: readonly SessionEventEnvelope[];
+  }[];
+}
+
+export interface WriteToolReexecutionAuthorization {
+  readonly authorizationReceiptId: string;
+  readonly approvalRequired: boolean;
+}
+
+export interface WriteToolReexecutionApproval {
+  readonly approvalReceiptId: string;
+}
+
+export interface WriteToolCommandReceipt {
+  readonly commandReceiptId: string;
+  readonly resultDigest: Sha256Digest;
+}
+
+/**
+ * Implementations must evaluate current RBAC/Feature/License/object scope,
+ * persist approval and command receipts, and replay each requestId/idempotencyKey
+ * pair to the same receipt after restart.
+ */
+export interface WriteToolReexecutionPort {
+  authorizeCurrent(input: {
+    readonly requestId: SessionEventId;
+    readonly actorId: string;
+    readonly sessionId: SessionId;
+    readonly sourceEvent: SessionEventEnvelope;
+    readonly toolKey: string;
+    readonly arguments: ModuleAiJsonValue;
+  }): Promise<WriteToolReexecutionAuthorization>;
+  requireCurrentApproval(input: {
+    readonly requestId: SessionEventId;
+    readonly actorId: string;
+    readonly sessionId: SessionId;
+    readonly toolKey: string;
+    readonly authorizationReceiptId: string;
+  }): Promise<WriteToolReexecutionApproval>;
+  executeIdempotent(input: {
+    readonly requestId: SessionEventId;
+    readonly actorId: string;
+    readonly sessionId: SessionId;
+    readonly toolKey: string;
+    readonly arguments: ModuleAiJsonValue;
+    readonly idempotencyKey: string;
+    readonly authorizationReceiptId: string;
+    readonly approvalReceiptId?: string;
+  }): Promise<WriteToolCommandReceipt>;
+}
+
+export interface ReexecuteWriteToolInput {
+  readonly mode: "reexecute-write";
+  readonly sessionId: SessionId;
+  readonly expectedSequence: number;
+  readonly sourceEventId: SessionEventId;
+  readonly reexecutionEventId: SessionEventId;
+  readonly actorId: string;
+  readonly idempotencyKey: string;
+  readonly arguments: ModuleAiJsonValue;
+}

package/template/apps/server/src/agent/session-log/repository.ts

@@ -0,0 +1,103 @@
+import type {
+  SessionCheckpoint,
+  SessionCheckpointId,
+  SessionGovernanceBinding,
+  SessionId,
+  SessionLineage,
+  SessionRecord,
+} from "./domain.js";
+import type {
+  PendingSessionEvent,
+  SessionEventEnvelope,
+} from "./events.js";
+
+export interface CreateSessionInput {
+  readonly sessionId: SessionId;
+  readonly governance: SessionGovernanceBinding;
+  readonly createdAt: string;
+  readonly lineage?: SessionLineage;
+  readonly createdEvent: PendingSessionEvent;
+}
+
+export interface AppendSessionEventsInput {
+  readonly sessionId: SessionId;
+  readonly expectedSequence: number;
+  readonly events: readonly PendingSessionEvent[];
+}
+
+export interface CreateCheckpointInput {
+  readonly sessionId: SessionId;
+  readonly expectedSequence: number;
+  readonly checkpoint: SessionCheckpoint;
+  readonly event: PendingSessionEvent;
+}
+
+export interface ArchiveSessionInput {
+  readonly sessionId: SessionId;
+  readonly expectedSequence: number;
+  readonly event: PendingSessionEvent;
+}
+
+export interface ForkSessionInput {
+  readonly parentSessionId: SessionId;
+  readonly expectedParentSequence: number;
+  readonly checkpointId: SessionCheckpointId;
+  readonly child: CreateSessionInput;
+  readonly parentEvent: PendingSessionEvent;
+}
+
+export interface SessionAppendResult {
+  readonly session: SessionRecord;
+  readonly events: readonly SessionEventEnvelope[];
+  readonly replayed: boolean;
+}
+
+export interface SessionForkResult {
+  readonly parent: SessionRecord;
+  readonly child: SessionRecord;
+  readonly parentEvent: SessionEventEnvelope;
+  readonly childEvent: SessionEventEnvelope;
+  readonly replayed: boolean;
+}
+
+/**
+ * Persistence implementations must make each mutating method one transaction.
+ * append uses headSequence as CAS; eventId makes a retried committed append safe.
+ */
+export interface SessionEventRepository {
+  create(input: CreateSessionInput): Promise<SessionAppendResult>;
+  get(sessionId: SessionId): Promise<SessionRecord | undefined>;
+  read(input: {
+    readonly sessionId: SessionId;
+    readonly afterSequence: number;
+    readonly throughSequence?: number;
+    readonly limit: number;
+  }): Promise<readonly SessionEventEnvelope[]>;
+  findEvent(
+    sessionId: SessionId,
+    eventId: string,
+  ): Promise<SessionEventEnvelope | undefined>;
+  append(input: AppendSessionEventsInput): Promise<SessionAppendResult>;
+  checkpoint(input: CreateCheckpointInput): Promise<SessionAppendResult>;
+  getCheckpoint(
+    checkpointId: SessionCheckpointId,
+  ): Promise<SessionCheckpoint | undefined>;
+  fork(input: ForkSessionInput): Promise<SessionForkResult>;
+  archive(input: ArchiveSessionInput): Promise<SessionAppendResult>;
+}
+
+export type SessionRepositoryConflictCode =
+  | "SESSION_EXISTS"
+  | "SESSION_NOT_FOUND"
+  | "SESSION_NOT_ACTIVE"
+  | "SEQUENCE_CONFLICT"
+  | "EVENT_ID_CONFLICT"
+  | "CHECKPOINT_CONFLICT"
+  | "FORK_CONFLICT";
+
+export class SessionRepositoryConflict extends Error {
+  constructor(readonly code: SessionRepositoryConflictCode) {
+    super(code);
+    this.name = "SessionRepositoryConflict";
+  }
+}