create-windy 0.6.11 → 0.6.14

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

@@ -0,0 +1,349 @@
+import { captureAuthorizationScope } from "../data-access/scope-snapshot.js";
+import type { RequestGuardContext } from "../guards.js";
+import type { MemoryObjectAuthorizationPort } from "./context-memory/contracts.js";
+import {
+  createSessionIdentityFactory,
+  type SessionId,
+} from "./session-log/domain.js";
+import { SessionEventLogService } from "./session-log/service.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 {
+  SessionProjectionSourceAuthorizer,
+  type CurrentSourceAuthorizationPort,
+} from "./session-projection-access.js";
+import {
+  AgentSessionProjectionError,
+  inaccessibleSessionProjection as inaccessible,
+  unavailableSessionProjection as projectionUnavailable,
+} from "./session-projection-errors.js";
+export {
+  AgentSessionProjectionError,
+  isProjectionSourceUnavailable,
+} from "./session-projection-errors.js";
+import type { AuthoritativeSourceAccessPort } from "./session-invalidation/contracts.js";
+import {
+  memoryProjectionScopeId,
+  memoryProjectionSummary,
+  projectAgentSession,
+  projectAgentSessionTimelineEvent,
+  projectableContextVersion,
+  projectableMemory,
+  projectContextValidity,
+} from "./session-projection-view.js";
+
+export class AgentSessionProjectionFacade {
+  readonly #identities = createSessionIdentityFactory();
+  readonly #sourceAuthorization: SessionProjectionSourceAuthorizer;
+
+  constructor(
+    private readonly repository: DrizzleSessionEventRepository,
+    private readonly service: SessionEventLogService,
+    private readonly contexts: DrizzleContextProjectionReader,
+    private readonly memories: DrizzleMemoryProjectionStore,
+    private readonly mutations: DrizzleSessionMutationCoordinator,
+    sourceAccess?: AuthoritativeSourceAccessPort,
+    currentSourceAuthorization?: CurrentSourceAuthorizationPort,
+    private readonly memoryObjectAuthorization?: MemoryObjectAuthorizationPort,
+  ) {
+    this.#sourceAuthorization = new SessionProjectionSourceAuthorizer(
+      sourceAccess,
+      currentSourceAuthorization,
+    );
+  }
+
+  async create(context: RequestGuardContext) {
+    const sessionId = this.#identities.sessionId();
+    return this.service.create({
+      sessionId,
+      createdEventId: this.#identities.eventId(),
+      governance: governance(context),
+    });
+  }
+
+  async list(context: RequestGuardContext) {
+    const current = governance(context);
+    const rows = await this.repository.listForActor(
+      context.actor.id,
+      current.scopeDigest,
+    );
+    return {
+      items: rows.map(projectAgentSession),
+    };
+  }
+
+  async detail(sessionId: string, context: RequestGuardContext) {
+    const session = await this.requireSession(sessionId, context);
+    const events = await this.repository.read({
+      sessionId: session.sessionId,
+      afterSequence: 0,
+      limit: 1_000,
+    });
+    return {
+      session: projectAgentSession(session),
+      timeline: events.map(projectAgentSessionTimelineEvent),
+    };
+  }
+
+  async contextVersions(sessionId: string, context: RequestGuardContext) {
+    const session = await this.requireSession(sessionId, context);
+    const rows = await this.contexts.listForSession(session.sessionId);
+    const visible = rows.filter(projectableContextVersion);
+    await this.#sourceAuthorization.requireAll(
+      visible.flatMap(({ sources }) =>
+        sources.map((source) => ({
+          moduleKey: source.sourceModuleKey,
+          kind: source.sourceKind,
+          id: source.sourceId,
+          version: source.sourceVersion,
+          sequence: source.sourceSequence,
+          digest: source.sourceDigest,
+          valid: source.validityStatus === "valid",
+        })),
+      ),
+      context,
+    );
+    return {
+      items: visible.map((row) => ({
+        contextVersionId: row.contextVersionId,
+        sessionId: row.sessionId,
+        turnId: row.turnId,
+        runId: row.runId,
+        modelAttemptId: row.modelAttemptId,
+        digest: row.digest,
+        createdAt: new Date(row.createdAt).toISOString(),
+        sources: row.sources.map((source) => ({
+          moduleKey: source.sourceModuleKey,
+          kind: source.sourceKind,
+          id: source.sourceId,
+          version: source.sourceVersion,
+          sequence: source.sourceSequence,
+          digest: source.sourceDigest,
+          validity: projectContextValidity(source, row.status),
+        })),
+      })),
+    };
+  }
+
+  async memoryProjections(sessionId: string, context: RequestGuardContext) {
+    const session = await this.requireSession(sessionId, context);
+    let rows;
+    try {
+      rows = await this.memories.listForSession(session.sessionId);
+    } catch {
+      throw projectionUnavailable();
+    }
+    const visible = rows.filter(projectableMemory);
+    await this.requireMemoryAccess(visible, session.headSequence, context);
+    return {
+      items: visible.flatMap(({ projection, status }) => {
+        const source = projection.sources[0];
+        if (!source) return [];
+        return [
+          {
+            memoryId: projection.memoryId,
+            kind: projection.kind,
+            scope: {
+              kind: projection.scope.kind,
+              id: memoryProjectionScopeId(projection),
+            },
+            derivation: {
+              sessionId: projection.derivation.sessionId,
+              throughSequence: projection.derivation.throughSequence,
+            },
+            ...(projection.currentCaseId
+              ? { currentCaseId: projection.currentCaseId }
+              : {}),
+            source: {
+              moduleKey: source.moduleKey,
+              kind: source.kind,
+              id: source.id,
+              version: source.version,
+              sequence: source.sequence,
+              digest: source.digest,
+            },
+            status,
+            ...(projection.expiresAt
+              ? { expiresAt: projection.expiresAt }
+              : {}),
+            summary: memoryProjectionSummary(projection),
+          },
+        ];
+      }),
+    };
+  }
+
+  async checkpoint(
+    sessionId: string,
+    expectedSequence: number,
+    context: RequestGuardContext,
+  ) {
+    const session = await this.requireActiveSession(sessionId, context);
+    return this.service.checkpoint({
+      sessionId: session.sessionId,
+      expectedSequence,
+      checkpointId: this.#identities.checkpointId(),
+      eventId: this.#identities.eventId(),
+    });
+  }
+
+  async replay(
+    sessionId: string,
+    checkpointId: string | undefined,
+    context: RequestGuardContext,
+  ) {
+    const session = await this.requireSession(sessionId, context);
+    const replay = await this.service.replay({
+      sessionId: session.sessionId,
+      ...(checkpointId
+        ? { checkpointId: checkpointId as `session_checkpoint_${string}` }
+        : {}),
+    });
+    const segments = await Promise.all(
+      replay.segments.map(async (segment) => ({
+        ...segment,
+        session: await this.requireSession(segment.sessionId, context),
+      })),
+    );
+    return { ...replay, segments };
+  }
+
+  async fork(
+    sessionId: string,
+    expectedSequence: number,
+    checkpointId: string,
+    context: RequestGuardContext,
+  ) {
+    const parent = await this.requireActiveSession(sessionId, context);
+    return this.service.fork({
+      parentSessionId: parent.sessionId,
+      expectedParentSequence: expectedSequence,
+      checkpointId: checkpointId as `session_checkpoint_${string}`,
+      childSessionId: this.#identities.sessionId(),
+      parentEventId: this.#identities.eventId(),
+      childCreatedEventId: this.#identities.eventId(),
+      governance: governance(context),
+    });
+  }
+
+  async archive(
+    sessionId: string,
+    expectedSequence: number,
+    context: RequestGuardContext,
+  ) {
+    const session = await this.requireActiveSession(sessionId, context);
+    const eventId = this.#identities.eventId();
+    return this.mutations.archive({
+      sessionId: session.sessionId,
+      expectedSequence,
+      eventId,
+    });
+  }
+
+  async deleteMemory(
+    sessionId: string,
+    memoryId: string,
+    context: RequestGuardContext,
+  ) {
+    const session = await this.requireActiveSession(sessionId, context);
+    let row;
+    try {
+      row = await this.memories.readForSession(session.sessionId, memoryId);
+    } catch {
+      throw projectionUnavailable();
+    }
+    if (!row || !projectableMemory(row)) throw inaccessible();
+    await this.requireMemoryAccess([row], session.headSequence, context);
+    try {
+      if (!(await this.mutations.deleteMemory(session.sessionId, memoryId))) {
+        throw inaccessible();
+      }
+    } catch (error) {
+      if (error instanceof AgentSessionProjectionError) throw error;
+      throw projectionUnavailable();
+    }
+    return { deleted: true };
+  }
+
+  private async requireMemoryAccess(
+    rows: Awaited<ReturnType<DrizzleMemoryProjectionStore["listForSession"]>>,
+    sessionHeadSequence: number,
+    context: RequestGuardContext,
+  ) {
+    if (!rows.length) return;
+    if (
+      !this.memoryObjectAuthorization ||
+      rows.some(
+        ({ projection, derivedFromSessionId, derivedThroughSequence }) =>
+          projection.derivation.sessionId !== derivedFromSessionId ||
+          projection.derivation.throughSequence !== derivedThroughSequence ||
+          derivedThroughSequence > sessionHeadSequence,
+      )
+    )
+      throw projectionUnavailable();
+    await this.#sourceAuthorization.requireAll(
+      rows.flatMap(({ projection }) =>
+        projection.sources.map((source) => ({
+          moduleKey: source.moduleKey,
+          kind: source.kind,
+          id: source.id,
+          version: source.version,
+          sequence: source.sequence,
+          digest: source.digest,
+          valid: source.validity.status === "valid",
+        })),
+      ),
+      context,
+    );
+    for (const { projection } of rows) {
+      try {
+        const decision = await this.memoryObjectAuthorization.authorize(
+          projection,
+          context,
+          new AbortController().signal,
+        );
+        if (!decision.allowed || !decision.reason.trim()) {
+          throw projectionUnavailable();
+        }
+      } catch {
+        throw projectionUnavailable();
+      }
+    }
+  }
+
+  private async requireSession(
+    sessionId: string,
+    context: RequestGuardContext,
+  ) {
+    const session = await this.repository.get(sessionId as SessionId);
+    const current = governance(context);
+    if (
+      !session ||
+      session.governance.actorId !== current.actorId ||
+      session.governance.scopeDigest !== current.scopeDigest
+    )
+      throw inaccessible();
+    return session;
+  }
+
+  private async requireActiveSession(
+    sessionId: string,
+    context: RequestGuardContext,
+  ) {
+    const session = await this.requireSession(sessionId, context);
+    if (session.status !== "active") throw inaccessible();
+    return session;
+  }
+}
+
+function governance(context: RequestGuardContext) {
+  return {
+    actorId: context.actor.id,
+    scopeDigest:
+      `sha256:${captureAuthorizationScope(context.actor.scopeContext).hash}` as const,
+  };
+}

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

@@ -0,0 +1,215 @@
+import type { RequestGuardContext } from "../guards.js";
+import type { RouteApp } from "../system/routes.js";
+import type { SessionAppendResult, SessionForkResult } from "./session-log/repository.js";
+import {
+  AgentSessionProjectionError,
+  AgentSessionProjectionFacade,
+  isProjectionSourceUnavailable,
+} from "./session-projection-facade.js";
+import {
+  projectAgentSession,
+  projectAgentSessionTimelineEvent,
+} from "./session-projection-view.js";
+
+interface RouteContext {
+  body?: unknown;
+  params: Record<string, string | undefined>;
+  guardContext: RequestGuardContext;
+}
+
+export function registerAgentSessionProjectionRoutes(
+  app: RouteApp,
+  facade: AgentSessionProjectionFacade,
+) {
+  app.get("/agent/harness/sessions", (raw) => {
+    const context = raw as RouteContext;
+    return respond(() => facade.list(context.guardContext));
+  });
+  app.post("/agent/harness/sessions", (raw) => {
+    const context = raw as RouteContext;
+    return respond(async () => projectAppend(await facade.create(context.guardContext)));
+  });
+  app.get("/agent/harness/sessions/:sessionId", (raw) => {
+    const context = raw as RouteContext;
+    return respond(() =>
+      facade.detail(required(context.params.sessionId), context.guardContext),
+    );
+  });
+  app.get("/agent/harness/sessions/:sessionId/context-versions", (raw) => {
+    const context = raw as RouteContext;
+    return respond(() =>
+      facade.contextVersions(
+        required(context.params.sessionId),
+        context.guardContext,
+      ),
+    );
+  });
+  app.get("/agent/harness/sessions/:sessionId/memories", (raw) => {
+    const context = raw as RouteContext;
+    return respond(() =>
+      facade.memoryProjections(
+        required(context.params.sessionId),
+        context.guardContext,
+      ),
+    );
+  });
+  app.post("/agent/harness/sessions/:sessionId/checkpoints", (raw) => {
+    const context = raw as RouteContext;
+    return respond(async () =>
+      projectAppend(
+        await facade.checkpoint(
+          required(context.params.sessionId),
+          expectedSequence(context.body),
+          context.guardContext,
+        ),
+      ),
+    );
+  });
+  app.post("/agent/harness/sessions/:sessionId/replay", (raw) => {
+    const context = raw as RouteContext;
+    return respond(async () => {
+      const body = record(context.body);
+      const replay = await facade.replay(
+        required(context.params.sessionId),
+        optionalString(body.checkpointId),
+        context.guardContext,
+      );
+      return {
+        mode: replay.mode,
+        sideEffectPolicy: replay.sideEffectPolicy,
+        sessionId: replay.sessionId,
+        segments: replay.segments.map((segment) => ({
+          session: projectAgentSession(segment.session),
+          events: segment.events.map(projectAgentSessionTimelineEvent),
+        })),
+      };
+    });
+  });
+  app.post("/agent/harness/sessions/:sessionId/forks", (raw) => {
+    const context = raw as RouteContext;
+    return respond(async () => {
+      const body = record(context.body);
+      return projectFork(
+        await facade.fork(
+          required(context.params.sessionId),
+          positiveInteger(body.expectedSequence, "expectedSequence"),
+          requiredString(body.checkpointId, "checkpointId"),
+          context.guardContext,
+        ),
+      );
+    });
+  });
+  app.post("/agent/harness/sessions/:sessionId/archive", (raw) => {
+    const context = raw as RouteContext;
+    return respond(async () =>
+      projectAppend(
+        await facade.archive(
+          required(context.params.sessionId),
+          expectedSequence(context.body),
+          context.guardContext,
+        ),
+      ),
+    );
+  });
+  app.delete("/agent/harness/sessions/:sessionId/memories/:memoryId", (raw) => {
+    const context = raw as RouteContext;
+    return respond(() =>
+      facade.deleteMemory(
+        required(context.params.sessionId),
+        required(context.params.memoryId),
+        context.guardContext,
+      ),
+    );
+  });
+}
+
+function projectAppend(result: SessionAppendResult) {
+  return {
+    session: projectAgentSession(result.session),
+    events: result.events.map(projectAgentSessionTimelineEvent),
+    replayed: result.replayed,
+  };
+}
+
+function projectFork(result: SessionForkResult) {
+  return {
+    parent: projectAgentSession(result.parent),
+    child: projectAgentSession(result.child),
+    parentEvent: projectAgentSessionTimelineEvent(result.parentEvent),
+    childEvent: projectAgentSessionTimelineEvent(result.childEvent),
+    replayed: result.replayed,
+  };
+}
+
+async function respond(action: () => Promise<unknown>) {
+  try {
+    return await action();
+  } catch (error) {
+    if (isProjectionSourceUnavailable(error)) {
+      return Response.json(
+        {
+          code: "SESSION_PROJECTION_UNAVAILABLE",
+          message: "Session 投影暂不可用",
+        },
+        { status: 503 },
+      );
+    }
+    if (error instanceof AgentSessionProjectionError) {
+      return Response.json(
+        {
+          code: error.code,
+          message:
+            error.status === 404
+              ? "Session 不存在或不可访问"
+              : "Session 投影暂不可用",
+        },
+        { status: error.status },
+      );
+    }
+    if (error instanceof SessionInputError) {
+      return Response.json(
+        { code: "INVALID_INPUT", message: error.message },
+        { status: 400 },
+      );
+    }
+    return Response.json(
+      { code: "SESSION_UNAVAILABLE", message: "Session 服务暂不可用" },
+      { status: 503 },
+    );
+  }
+}
+
+function expectedSequence(body: unknown) {
+  return positiveInteger(record(body).expectedSequence, "expectedSequence");
+}
+
+function record(value: unknown): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new SessionInputError("请求必须是 JSON object");
+  }
+  return value as Record<string, unknown>;
+}
+
+function positiveInteger(value: unknown, name: string) {
+  if (!Number.isSafeInteger(value) || (value as number) < 1) {
+    throw new SessionInputError(`${name} 无效`);
+  }
+  return value as number;
+}
+
+function requiredString(value: unknown, name: string) {
+  if (typeof value !== "string" || !value.trim()) {
+    throw new SessionInputError(`${name} 无效`);
+  }
+  return value;
+}
+
+function optionalString(value: unknown) {
+  return value === undefined ? undefined : requiredString(value, "checkpointId");
+}
+
+function required(value: string | undefined) {
+  return requiredString(value, "resourceId");
+}
+
+class SessionInputError extends Error {}

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

@@ -0,0 +1,137 @@
+import type {
+  ContextSourceValidity,
+  MemoryProjection,
+} from "./context-memory/contracts.js";
+import type { SessionRecord } from "./session-log/domain.js";
+import type { SessionEventEnvelope } from "./session-log/events.js";
+import {
+  DrizzleContextProjectionReader,
+  DrizzleMemoryProjectionStore,
+} from "./session-persistence/drizzle-context-memory.js";
+
+export function projectAgentSession(session: SessionRecord) {
+  return {
+    sessionId: session.sessionId,
+    status: session.status,
+    headSequence: session.headSequence,
+    updatedAt: session.updatedAt,
+    ...(session.lineage
+      ? {
+          lineage: {
+            parentSessionId: session.lineage.parentSessionId,
+            parentCheckpointId: session.lineage.checkpointId,
+            parentSequence: session.lineage.parentSequence,
+          },
+        }
+      : {}),
+  };
+}
+
+export function projectAgentSessionTimelineEvent(
+  event: SessionEventEnvelope,
+) {
+  const data = event.data;
+  return {
+    sequence: event.sequence,
+    type: data.type,
+    occurredAt: event.occurredAt,
+    summary: timelineSummary(data.type),
+    ...("runId" in data && data.runId ? { runId: data.runId } : {}),
+    ...("turnId" in data ? { turnId: data.turnId } : {}),
+    ...("stepId" in data ? { stepId: data.stepId } : {}),
+  };
+}
+
+export function projectContextValidity(
+  source: {
+    validityStatus: string;
+    validityReason: string | null;
+    checkedAt: number;
+    expiresAt: number | null;
+  },
+  contextStatus: string,
+): ContextSourceValidity {
+  return {
+    status:
+      contextStatus === "invalidated"
+        ? "invalid"
+        : (source.validityStatus as "valid" | "invalid"),
+    checkedAt: new Date(source.checkedAt).toISOString(),
+    ...(source.expiresAt
+      ? { expiresAt: new Date(source.expiresAt).toISOString() }
+      : {}),
+    ...(source.validityReason
+      ? {
+          reason: source.validityReason as ContextSourceValidity["reason"],
+        }
+      : {}),
+  };
+}
+
+export function memoryProjectionScopeId(projection: MemoryProjection) {
+  if (projection.scope.kind === "session") return projection.scope.sessionId;
+  if (projection.scope.kind === "user") return projection.scope.actorId;
+  return projection.scope.caseId;
+}
+
+export function memoryProjectionSummary(projection: MemoryProjection) {
+  if (projection.kind === "session-summary") {
+    return `会话摘要投影，覆盖至事件 #${projection.coveredThroughSequence}`;
+  }
+  if (projection.kind === "case-memory-candidate") {
+    return `案件记忆候选，核验状态：${projection.reviewStatus}`;
+  }
+  return `${projection.kind} 受控投影`;
+}
+
+export function projectableContextVersion(
+  row: Awaited<
+    ReturnType<DrizzleContextProjectionReader["listForSession"]>
+  >[number],
+) {
+  return (
+    row.status === "active" &&
+    row.sources.length > 0 &&
+    row.sources.every(
+      (source) =>
+        source.validityStatus === "valid" &&
+        (source.expiresAt === null || source.expiresAt > Date.now()),
+    )
+  );
+}
+
+export function projectableMemory(
+  row: Awaited<
+    ReturnType<DrizzleMemoryProjectionStore["listForSession"]>
+  >[number],
+) {
+  const { projection } = row;
+  return (
+    row.status === "active" &&
+    projection.validity.status === "valid" &&
+    (!projection.expiresAt || Date.parse(projection.expiresAt) > Date.now()) &&
+    projection.sources.length > 0 &&
+    projection.sources.every(
+      (source) =>
+        source.validity.status === "valid" &&
+        (!source.validity.expiresAt ||
+          Date.parse(source.validity.expiresAt) > Date.now()),
+    )
+  );
+}
+
+function timelineSummary(type: SessionEventEnvelope["data"]["type"]) {
+  return ({
+    "session.created": "Session 已创建",
+    "session.archived": "Session 已归档",
+    "turn.started": "Turn 已开始",
+    "turn.completed": "Turn 已结束",
+    "run.linked": "Run 已关联",
+    "step.started": "Step 已开始",
+    "step.completed": "Step 已结束",
+    "tool.execution-recorded": "Tool 执行事实已记录",
+    "checkpoint.created": "Checkpoint 已创建",
+    "fork.created": "Fork 已创建",
+    "write-tool.reexecuted": "写 Tool 已经显式授权重新执行",
+  } satisfies Record<SessionEventEnvelope["data"]["type"], string>)[type];
+}