create-windy 0.6.12 → 0.6.15

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

@@ -0,0 +1,349 @@
+import {
+  assertDigest,
+  createSessionIdentityFactory,
+  SessionDomainError,
+  type SessionCheckpoint,
+  type SessionCheckpointId,
+  type SessionEventId,
+  type SessionGovernanceBinding,
+  type SessionId,
+  type SessionIdentityFactory,
+} from "./domain.js";
+import {
+  SESSION_EVENT_SCHEMA_VERSION,
+  type PendingSessionEvent,
+  type SessionEventData,
+  type SessionEventEnvelope,
+} from "./events.js";
+import { assertSessionEventHistory } from "./history.js";
+import {
+  assertCheckpointDigest,
+  digestSessionFacts,
+} from "./checkpoint-digest.js";
+import type { SessionEventRepository } from "./repository.js";
+import type {
+  ReadOnlySessionReplay,
+  ReexecuteWriteToolInput,
+  WriteToolReexecutionPort,
+} from "./replay-policy.js";
+const READ_PAGE_SIZE = 1_000;
+const MAX_EVENTS = 100_000;
+const MAX_LINEAGE_DEPTH = 32;
+export class SessionEventLogService {
+  constructor(
+    private readonly repository: SessionEventRepository,
+    private readonly writeTools?: WriteToolReexecutionPort,
+    private readonly identities: SessionIdentityFactory =
+      createSessionIdentityFactory(),
+    private readonly now: () => Date = () => new Date(),
+  ) {}
+  newEvent(data: SessionEventData): PendingSessionEvent {
+    return {
+      eventId: this.identities.eventId(),
+      occurredAt: this.now().toISOString(),
+      data,
+    };
+  }
+  async create(input: {
+    readonly sessionId: SessionId;
+    readonly createdEventId: SessionEventId;
+    readonly governance: SessionGovernanceBinding;
+  }) {
+    const occurredAt = this.now().toISOString();
+    return this.repository.create({
+      sessionId: input.sessionId,
+      governance: input.governance,
+      createdAt: occurredAt,
+      createdEvent: {
+        eventId: input.createdEventId,
+        occurredAt,
+        data: { type: "session.created", governance: input.governance },
+      },
+    });
+  }
+
+  async append(input: {
+    readonly sessionId: SessionId;
+    readonly expectedSequence: number;
+    readonly events: readonly PendingSessionEvent[];
+  }) {
+    const existingById = await Promise.all(
+      input.events.map(({ eventId }) =>
+        this.repository.findEvent(input.sessionId, eventId),
+      ),
+    );
+    if (existingById.some(Boolean)) return this.repository.append(input);
+    const existing = await this.readAll(input.sessionId);
+    const pending = input.events.map((event, index) => ({
+      ...structuredClone(event),
+      schemaVersion: SESSION_EVENT_SCHEMA_VERSION,
+      sessionId: input.sessionId,
+      sequence: input.expectedSequence + index + 1,
+    }));
+    assertSessionEventHistory([...existing, ...pending]);
+    return this.repository.append(input);
+  }
+
+  async checkpoint(input: {
+    readonly sessionId: SessionId;
+    readonly expectedSequence: number;
+    readonly checkpointId: SessionCheckpointId;
+    readonly eventId: SessionEventId;
+  }) {
+    const events = await this.readAll(input.sessionId, input.expectedSequence);
+    if (events.at(-1)?.sequence !== input.expectedSequence) {
+      throw new SessionDomainError("Checkpoint sequence 与 Session 不一致");
+    }
+    const factDigest = digestSessionFacts(events);
+    const createdAt = this.now().toISOString();
+    const checkpoint: SessionCheckpoint = {
+      checkpointId: input.checkpointId,
+      sessionId: input.sessionId,
+      throughSequence: input.expectedSequence,
+      factDigest,
+      createdAt,
+    };
+    const event: PendingSessionEvent = {
+      eventId: input.eventId,
+      occurredAt: createdAt,
+      data: {
+        type: "checkpoint.created",
+        checkpointId: input.checkpointId,
+        throughSequence: input.expectedSequence,
+        factDigest,
+      },
+    };
+    assertSessionEventHistory([
+      ...events,
+      toEnvelope(input.sessionId, input.expectedSequence + 1, event),
+    ]);
+    return this.repository.checkpoint({
+      sessionId: input.sessionId,
+      expectedSequence: input.expectedSequence,
+      checkpoint,
+      event,
+    });
+  }
+
+  async fork(input: {
+    readonly parentSessionId: SessionId;
+    readonly expectedParentSequence: number;
+    readonly checkpointId: SessionCheckpointId;
+    readonly childSessionId: SessionId;
+    readonly parentEventId: SessionEventId;
+    readonly childCreatedEventId: SessionEventId;
+    readonly governance: SessionGovernanceBinding;
+  }) {
+    const parent = await this.repository.get(input.parentSessionId);
+    const checkpoint = await this.repository.getCheckpoint(input.checkpointId);
+    if (!parent || !checkpoint || checkpoint.sessionId !== parent.sessionId) {
+      throw new SessionDomainError("Fork Checkpoint 不存在");
+    }
+    if (parent.governance.actorId !== input.governance.actorId) {
+      throw new SessionDomainError("Fork 不能改变 Session Actor");
+    }
+    const occurredAt = this.now().toISOString();
+    const lineage = {
+      parentSessionId: parent.sessionId,
+      checkpointId: checkpoint.checkpointId,
+      parentSequence: checkpoint.throughSequence,
+    };
+    return this.repository.fork({
+      parentSessionId: parent.sessionId,
+      expectedParentSequence: input.expectedParentSequence,
+      checkpointId: checkpoint.checkpointId,
+      parentEvent: {
+        eventId: input.parentEventId,
+        occurredAt,
+        data: {
+          type: "fork.created",
+          checkpointId: checkpoint.checkpointId,
+          childSessionId: input.childSessionId,
+          parentSequence: checkpoint.throughSequence,
+        },
+      },
+      child: {
+        sessionId: input.childSessionId,
+        governance: input.governance,
+        createdAt: occurredAt,
+        lineage,
+        createdEvent: {
+          eventId: input.childCreatedEventId,
+          occurredAt,
+          data: { type: "session.created", governance: input.governance, lineage },
+        },
+      },
+    });
+  }
+
+  async replay(input: {
+    readonly sessionId: SessionId;
+    readonly checkpointId?: SessionCheckpointId;
+  }): Promise<ReadOnlySessionReplay> {
+    let throughSequence: number | undefined;
+    let requestedCheckpoint: SessionCheckpoint | undefined;
+    if (input.checkpointId) {
+      const checkpoint = await this.repository.getCheckpoint(input.checkpointId);
+      if (!checkpoint || checkpoint.sessionId !== input.sessionId) {
+        throw new SessionDomainError("Replay Checkpoint 不存在");
+      }
+      requestedCheckpoint = checkpoint;
+      throughSequence = checkpoint.throughSequence;
+    }
+    const segments = await this.lineageSegments(
+      input.sessionId,
+      throughSequence,
+      new Set(),
+      0,
+    );
+    if (requestedCheckpoint) {
+      assertCheckpointDigest(requestedCheckpoint, segments.at(-1)?.events ?? []);
+    }
+    return {
+      mode: "read-only",
+      sideEffectPolicy: "recorded-only",
+      sessionId: input.sessionId,
+      segments,
+    };
+  }
+
+  async reexecuteWriteTool(input: ReexecuteWriteToolInput) {
+    if (!this.writeTools) throw new SessionDomainError("写 Tool 重新执行不可用");
+    if (!input.idempotencyKey.trim()) {
+      throw new SessionDomainError("写 Tool 重新执行必须提供幂等键");
+    }
+    const existing = await this.repository.findEvent(
+      input.sessionId,
+      input.reexecutionEventId,
+    );
+    if (existing) {
+      if (
+        existing.data.type === "write-tool.reexecuted" &&
+        existing.data.sourceEventId === input.sourceEventId
+      ) return { event: existing, replayed: true };
+      throw new SessionDomainError("重新执行 Event identity 冲突");
+    }
+    const source = await this.repository.findEvent(
+      input.sessionId,
+      input.sourceEventId,
+    );
+    if (
+      !source ||
+      source.data.type !== "tool.execution-recorded" ||
+      source.data.effect !== "write"
+    ) throw new SessionDomainError("来源 Event 不是写 Tool 事实");
+    const authorization = await this.writeTools.authorizeCurrent({
+      requestId: input.reexecutionEventId,
+      actorId: input.actorId,
+      sessionId: input.sessionId,
+      sourceEvent: source,
+      toolKey: source.data.toolKey,
+      arguments: input.arguments,
+    });
+    const approval = authorization.approvalRequired
+      ? await this.writeTools.requireCurrentApproval({
+          requestId: input.reexecutionEventId,
+          actorId: input.actorId,
+          sessionId: input.sessionId,
+          toolKey: source.data.toolKey,
+          authorizationReceiptId: authorization.authorizationReceiptId,
+        })
+      : undefined;
+    const receipt = await this.writeTools.executeIdempotent({
+      requestId: input.reexecutionEventId,
+      actorId: input.actorId,
+      sessionId: input.sessionId,
+      toolKey: source.data.toolKey,
+      arguments: input.arguments,
+      idempotencyKey: input.idempotencyKey,
+      authorizationReceiptId: authorization.authorizationReceiptId,
+      ...(approval ? { approvalReceiptId: approval.approvalReceiptId } : {}),
+    });
+    assertDigest(receipt.resultDigest, "写 Tool 结果 digest");
+    const appended = await this.append({
+      sessionId: input.sessionId,
+      expectedSequence: input.expectedSequence,
+      events: [{
+        eventId: input.reexecutionEventId,
+        occurredAt: this.now().toISOString(),
+        data: {
+          type: "write-tool.reexecuted",
+          sourceEventId: source.eventId,
+          toolKey: source.data.toolKey,
+          idempotencyKey: input.idempotencyKey,
+          authorizationReceiptId: authorization.authorizationReceiptId,
+          ...(approval ? { approvalReceiptId: approval.approvalReceiptId } : {}),
+          commandReceiptId: receipt.commandReceiptId,
+          resultDigest: receipt.resultDigest,
+        },
+      }],
+    });
+    return { event: appended.events[0]!, replayed: appended.replayed };
+  }
+
+  private async lineageSegments(
+    sessionId: SessionId,
+    throughSequence: number | undefined,
+    seen: Set<SessionId>,
+    depth: number,
+  ): Promise<ReadOnlySessionReplay["segments"]> {
+    if (depth >= MAX_LINEAGE_DEPTH || seen.has(sessionId)) {
+      throw new SessionDomainError("Session Fork 血缘无效或过深");
+    }
+    seen.add(sessionId);
+    const session = await this.repository.get(sessionId);
+    if (!session) throw new SessionDomainError("Session 不存在");
+    const inherited = session.lineage
+      ? await this.lineageSegments(
+          session.lineage.parentSessionId,
+          session.lineage.parentSequence,
+          seen,
+          depth + 1,
+        )
+      : [];
+    if (session.lineage) {
+      const checkpoint = await this.repository.getCheckpoint(
+        session.lineage.checkpointId,
+      );
+      if (
+        !checkpoint ||
+        checkpoint.sessionId !== session.lineage.parentSessionId ||
+        checkpoint.throughSequence !== session.lineage.parentSequence
+      ) throw new SessionDomainError("Session Fork Checkpoint 血缘无效");
+      assertCheckpointDigest(checkpoint, inherited.at(-1)?.events ?? []);
+    }
+    const events = await this.readAll(sessionId, throughSequence);
+    assertSessionEventHistory(events);
+    return [
+      ...inherited,
+      {
+        sessionId,
+        throughSequence: events.at(-1)?.sequence ?? 0,
+        events,
+      },
+    ];
+  }
+
+  private async readAll(sessionId: SessionId, throughSequence?: number) {
+    const events: SessionEventEnvelope[] = [];
+    while (events.length < MAX_EVENTS) {
+      const page = await this.repository.read({
+        sessionId,
+        afterSequence: events.at(-1)?.sequence ?? 0,
+        ...(throughSequence === undefined ? {} : { throughSequence }),
+        limit: READ_PAGE_SIZE,
+      });
+      events.push(...page);
+      if (page.length < READ_PAGE_SIZE) return events;
+    }
+    throw new SessionDomainError("Session Event 数量超过读取上限");
+  }
+}
+
+function toEnvelope(
+  sessionId: SessionId,
+  sequence: number,
+  event: PendingSessionEvent,
+): SessionEventEnvelope {
+  return { ...event, sessionId, sequence, schemaVersion: SESSION_EVENT_SCHEMA_VERSION };
+}

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

@@ -0,0 +1,282 @@
+import { describe, expect, test } from "bun:test";
+import type { ModuleAiJsonValue } from "@southwind-ai/server-sdk";
+import {
+  SessionDomainError,
+  type SessionCheckpointId,
+  type SessionEventId,
+  type SessionId,
+  type SessionStepId,
+  type SessionTurnId,
+  type Sha256Digest,
+} from "./domain.js";
+import type { PendingSessionEvent, SessionEventData } from "./events.js";
+import { InMemorySessionEventRepository } from "./in-memory-repository.js";
+import {
+  SessionRepositoryConflict,
+  type SessionEventRepository,
+} from "./repository.js";
+import type { WriteToolReexecutionPort } from "./replay-policy.js";
+import { SessionEventLogService } from "./service.js";
+
+const DIGEST = `sha256:${"a".repeat(64)}` as Sha256Digest;
+const RESULT_DIGEST = `sha256:${"b".repeat(64)}` as Sha256Digest;
+const SESSION = "session_root" as SessionId;
+const CHILD = "session_child" as SessionId;
+const TURN = "session_turn_1" as SessionTurnId;
+const STEP = "session_step_1" as SessionStepId;
+const CHECKPOINT = "session_checkpoint_1" as SessionCheckpointId;
+const governance = { actorId: "actor-1", scopeDigest: DIGEST } as const;
+
+describe("Session Event Log contract", () => {
+  test("append 使用 expected sequence CAS，event identity 可安全重试", async () => {
+    const repository = new InMemorySessionEventRepository();
+    await create(repository);
+    const started = event("2", {
+      type: "turn.started",
+      turnId: TURN,
+      cause: "user-input",
+      input: reference("question"),
+    });
+    const first = await repository.append({
+      sessionId: SESSION,
+      expectedSequence: 1,
+      events: [started],
+    });
+    expect(first.events[0]?.sequence).toBe(2);
+    expect(
+      await repository.append({
+        sessionId: SESSION,
+        expectedSequence: 1,
+        events: [started],
+      }),
+    ).toMatchObject({ replayed: true });
+    await expect(
+      repository.append({
+        sessionId: SESSION,
+        expectedSequence: 1,
+        events: [
+          event("3", {
+            type: "turn.started",
+            turnId: "session_turn_2" as SessionTurnId,
+            cause: "steering",
+            input: reference("steering"),
+          }),
+        ],
+      }),
+    ).rejects.toMatchObject({
+      code: "SEQUENCE_CONFLICT",
+    } satisfies Partial<SessionRepositoryConflict>);
+  });
+
+  test("checkpoint/fork 保留血缘，replay 永远只读且不复制父事件", async () => {
+    const repository = new InMemorySessionEventRepository();
+    const service = fixedService(repository);
+    await service.create({
+      sessionId: SESSION,
+      createdEventId: id("1"),
+      governance,
+    });
+    await service.append({
+      sessionId: SESSION,
+      expectedSequence: 1,
+      events: [
+        event("2", {
+          type: "turn.started",
+          turnId: TURN,
+          cause: "user-input",
+          input: reference("question"),
+        }),
+        event("3", {
+          type: "turn.completed",
+          turnId: TURN,
+          outcome: "completed",
+          result: reference("answer"),
+        }),
+      ],
+    });
+    await service.checkpoint({
+      sessionId: SESSION,
+      expectedSequence: 3,
+      checkpointId: CHECKPOINT,
+      eventId: id("4"),
+    });
+    await service.fork({
+      parentSessionId: SESSION,
+      expectedParentSequence: 4,
+      checkpointId: CHECKPOINT,
+      childSessionId: CHILD,
+      parentEventId: id("5"),
+      childCreatedEventId: id("6"),
+      governance,
+    });
+    const replay = await service.replay({ sessionId: CHILD });
+    expect(replay).toMatchObject({
+      mode: "read-only",
+      sideEffectPolicy: "recorded-only",
+      sessionId: CHILD,
+    });
+    expect(replay.segments.map(({ sessionId }) => sessionId)).toEqual([
+      SESSION,
+      CHILD,
+    ]);
+    expect(replay.segments[0]?.throughSequence).toBe(3);
+    expect(replay.segments[1]?.events[0]?.data.type).toBe("session.created");
+  });
+
+  test("replay 不执行写 Tool；显式重执行重新授权、审批、幂等并记录 receipt", async () => {
+    const repository = new InMemorySessionEventRepository();
+    const calls: string[] = [];
+    const writeTools = writeToolPort(calls);
+    const service = fixedService(repository, writeTools);
+    await service.create({
+      sessionId: SESSION,
+      createdEventId: id("1"),
+      governance,
+    });
+    await service.append({
+      sessionId: SESSION,
+      expectedSequence: 1,
+      events: toolTurn(),
+    });
+    const replay = await service.replay({ sessionId: SESSION });
+    expect(replay.sideEffectPolicy).toBe("recorded-only");
+    expect(calls).toEqual([]);
+    const result = await service.reexecuteWriteTool({
+      mode: "reexecute-write",
+      sessionId: SESSION,
+      expectedSequence: 6,
+      sourceEventId: id("4"),
+      reexecutionEventId: id("7"),
+      actorId: "actor-1",
+      idempotencyKey: "explicit-reexecution-1",
+      arguments: { targetId: "case-1" },
+    });
+    expect(calls).toEqual(["authorize", "approve", "execute"]);
+    expect(result.event.data).toMatchObject({
+      type: "write-tool.reexecuted",
+      commandReceiptId: "command-receipt-1",
+      approvalReceiptId: "approval-receipt-1",
+    });
+  });
+
+  test("原始推理字段不能进入 Session Event", async () => {
+    const repository = new InMemorySessionEventRepository();
+    await create(repository);
+    await expect(
+      repository.append({
+        sessionId: SESSION,
+        expectedSequence: 1,
+        events: [
+          event("2", {
+            type: "turn.started",
+            turnId: TURN,
+            cause: "user-input",
+            input: reference("question"),
+            reasoning: "private",
+          } as unknown as SessionEventData),
+        ],
+      }),
+    ).rejects.toBeInstanceOf(SessionDomainError);
+  });
+});
+
+async function create(repository: SessionEventRepository) {
+  return repository.create({
+    sessionId: SESSION,
+    governance,
+    createdAt: "2026-08-27T00:00:00.000Z",
+    createdEvent: event("1", { type: "session.created", governance }),
+  });
+}
+
+function fixedService(
+  repository: SessionEventRepository,
+  writeTools?: WriteToolReexecutionPort,
+) {
+  return new SessionEventLogService(
+    repository,
+    writeTools,
+    undefined,
+    () => new Date("2026-08-27T00:00:00.000Z"),
+  );
+}
+
+function event(suffix: string, data: SessionEventData): PendingSessionEvent {
+  return {
+    eventId: id(suffix),
+    occurredAt: "2026-08-27T00:00:00.000Z",
+    data,
+  };
+}
+
+function id(suffix: string) {
+  return `session_event_${suffix}` as SessionEventId;
+}
+
+function reference(sourceId: string) {
+  return {
+    sourceType: "governed-content",
+    sourceId,
+    sourceVersion: "1",
+    contentDigest: DIGEST,
+  } as const;
+}
+
+function toolTurn(): PendingSessionEvent[] {
+  return [
+    event("2", {
+      type: "turn.started",
+      turnId: TURN,
+      cause: "user-input",
+      input: reference("question"),
+    }),
+    event("3", {
+      type: "step.started",
+      turnId: TURN,
+      stepId: STEP,
+      kind: "tool-call",
+    }),
+    event("4", {
+      type: "tool.execution-recorded",
+      turnId: TURN,
+      stepId: STEP,
+      toolCallId: "tool-call-1",
+      toolKey: "case.update",
+      effect: "write",
+      idempotencyKey: "original-1",
+      commandReceiptId: "original-command-receipt",
+      resultDigest: RESULT_DIGEST,
+    }),
+    event("5", {
+      type: "step.completed",
+      turnId: TURN,
+      stepId: STEP,
+      outcome: "completed",
+      resultDigest: RESULT_DIGEST,
+    }),
+    event("6", {
+      type: "turn.completed",
+      turnId: TURN,
+      outcome: "completed",
+      result: reference("answer"),
+    }),
+  ];
+}
+
+function writeToolPort(calls: string[]): WriteToolReexecutionPort {
+  return {
+    async authorizeCurrent() {
+      calls.push("authorize");
+      return { authorizationReceiptId: "authorization-receipt-1", approvalRequired: true };
+    },
+    async requireCurrentApproval() {
+      calls.push("approve");
+      return { approvalReceiptId: "approval-receipt-1" };
+    },
+    async executeIdempotent(input: { arguments: ModuleAiJsonValue }) {
+      calls.push("execute");
+      expect(input.arguments).toEqual({ targetId: "case-1" });
+      return { commandReceiptId: "command-receipt-1", resultDigest: RESULT_DIGEST };
+    },
+  };
+}