create-windy 0.4.1 → 0.5.0

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

@@ -0,0 +1,335 @@
+import { describe, expect, test } from "bun:test";
+import type { ModuleManifest } from "@southwind-ai/modules";
+import {
+  MODULE_DEBUG_SESSION_SCHEMA_VERSION,
+  type ModuleDebugSessionProviderV1,
+} from "@southwind-ai/server-sdk";
+import { featureKey } from "@southwind-ai/shared";
+import {
+  bindModuleUserProjection,
+  createRequestGuardContext,
+  type RequestActor,
+} from "../guards.js";
+import { initializeModuleHosts } from "../module-host.js";
+import { manifest } from "../module-host/test-fixtures.js";
+import { createServerRuntime } from "../runtime.js";
+import {
+  DebugSessionFacadeError,
+  DebugSessionFacadeV1,
+} from "./debug-session-facade.js";
+import { DebugSessionIdCodecV1 } from "./debug-session-id.js";
+
+const OPERATION_KEY = "known.copilot.global";
+const SOURCE_ID = "conversation-private-42";
+
+describe("ADK 调试会话 V1 facade", () => {
+  test("投影真实业务用户并只返回不透明 ID 与有界通用 DTO", async () => {
+    const seenActors: string[] = [];
+    const fixture = await createFixture({
+      list: async ({ actor }) => {
+        seenActors.push(actor.id);
+        return { sessions: [summary()], truncated: false };
+      },
+      get: async ({ actor }) => {
+        seenActors.push(actor.id);
+        return {
+          ...summary(),
+          messages: [
+            {
+              sequence: 1,
+              role: "user",
+              content: "历史问题",
+              createdAt: "2026-07-31T01:00:00.000Z",
+            },
+            {
+              sequence: 2,
+              role: "assistant",
+              content: "历史回答",
+              createdAt: "2026-07-31T01:00:01.000Z",
+            },
+          ],
+        };
+      },
+    });
+
+    const listed = await fixture.facade.list(fixture.context, signal());
+    const id = listed.sessions[0]?.id;
+    expect(id).toMatch(/^wdbg1_/);
+    expect(JSON.stringify(listed)).not.toContain(SOURCE_ID);
+    expect(listed.sessions[0]).toMatchObject({
+      title: "历史研判",
+      scopeLabel: "测试范围",
+      revision: "2",
+    });
+
+    const detail = await fixture.facade.get(
+      id ?? "",
+      fixture.context,
+      signal(),
+    );
+    expect(detail.session.messages.map(({ role }) => role)).toEqual([
+      "user",
+      "assistant",
+    ]);
+    expect(seenActors).toEqual([
+      "user_dev_admin",
+      "user_dev_admin",
+      "user_dev_admin",
+    ]);
+    const audits = fixture.runtime.auditSink
+      .list()
+      .filter(({ action }) => action === "known.copilot.history.read");
+    expect(audits).toHaveLength(2);
+    expect(audits[0]?.metadata).toMatchObject({
+      debugDataActorId: "user_dev_admin",
+      mode: "list",
+    });
+  });
+
+  test("每次详情读取重新 list 授权，未知和非法 ID 同形安全失败", async () => {
+    let visible = true;
+    const fixture = await createFixture({
+      list: async () => ({
+        sessions: visible ? [summary()] : [],
+        truncated: false,
+      }),
+      get: async () => ({ ...summary(), messages: [] }),
+    });
+    const listed = await fixture.facade.list(fixture.context, signal());
+    visible = false;
+
+    await expect(
+      fixture.facade.get(
+        listed.sessions[0]?.id ?? "",
+        fixture.context,
+        signal(),
+      ),
+    ).rejects.toMatchObject({
+      code: "SESSION_NOT_FOUND",
+      status: 404,
+    });
+    await expect(
+      fixture.facade.get(SOURCE_ID, fixture.context, signal()),
+    ).rejects.toMatchObject({
+      code: "INVALID_SESSION_ID",
+      status: 400,
+    });
+  });
+
+  test("分页读完超过 100 条会话且旧会话详情不会被新会话挤出", async () => {
+    const values = Array.from({ length: 101 }, (_, index) => ({
+      sourceId: `conversation-${index}`,
+      title: `历史研判 ${index}`,
+      scopeLabel: "测试范围",
+      updatedAt: new Date(Date.UTC(2026, 6, 31, 1, 0, index)).toISOString(),
+      revision: "1",
+    }));
+    const fixture = await createFixture({
+      list: async ({ limit, cursor }) => {
+        const offset = Number(cursor ?? 0);
+        const sessions = values.slice(offset, offset + limit);
+        const nextOffset = offset + sessions.length;
+        const truncated = nextOffset < values.length;
+        return {
+          sessions,
+          truncated,
+          ...(truncated ? { next: String(nextOffset) } : {}),
+        };
+      },
+      get: async ({ sourceId }) => {
+        const value = values.find((item) => item.sourceId === sourceId);
+        return value ? { ...value, messages: [] } : undefined;
+      },
+    });
+
+    const listed = await fixture.facade.list(fixture.context, signal());
+    expect(listed.sessions).toHaveLength(101);
+    expect(listed.truncated).toBe(false);
+    const oldest = listed.sessions.find(({ title }) => title === "历史研判 0");
+    expect(oldest).toBeDefined();
+    await expect(
+      fixture.facade.get(oldest?.id ?? "", fixture.context, signal()),
+    ).resolves.toMatchObject({
+      session: { title: "历史研判 0" },
+    });
+  });
+
+  test("非调试身份、缺少权限与 Provider 越界响应均 fail closed", async () => {
+    const fixture = await createFixture({
+      list: async () => ({ sessions: [summary()], truncated: false }),
+      get: async () => ({
+        ...summary(),
+        messages: Array.from({ length: 65 }, (_, sequence) => ({
+          sequence,
+          role: "assistant" as const,
+          content: "x",
+          createdAt: "2026-07-31T01:00:01.000Z",
+        })),
+      }),
+    });
+    const listed = await fixture.facade.list(fixture.context, signal());
+
+    await expect(
+      fixture.facade.get(
+        listed.sessions[0]?.id ?? "",
+        fixture.context,
+        signal(),
+      ),
+    ).rejects.toMatchObject({ code: "PROVIDER_UNAVAILABLE", status: 503 });
+
+    const forbidden = await createFixture(
+      {
+        list: async () => ({ sessions: [], truncated: false }),
+        get: async () => undefined,
+      },
+      [],
+    );
+    await expect(
+      forbidden.facade.list(forbidden.context, signal()),
+    ).rejects.toBeInstanceOf(DebugSessionFacadeError);
+
+    const ordinaryContext = createContext(
+      { ...actor(), id: "user_ordinary", type: "user" },
+      false,
+    );
+    await expect(
+      fixture.facade.list(ordinaryContext, signal()),
+    ).rejects.toMatchObject({ code: "FORBIDDEN", status: 403 });
+  });
+});
+
+async function createFixture(
+  methods: Pick<ModuleDebugSessionProviderV1, "list" | "get">,
+  permissionKeys = ["known.copilot.execute"],
+) {
+  const module = debugManifest();
+  const provider: ModuleDebugSessionProviderV1 = {
+    schemaVersion: MODULE_DEBUG_SESSION_SCHEMA_VERSION,
+    key: "known.copilot.history",
+    operationKeys: [OPERATION_KEY],
+    featureKey: "known.copilot",
+    permissionKey: "known.copilot.execute",
+    auditAction: "known.copilot.history.read",
+    ...methods,
+  };
+  const hosts = await initializeModuleHosts({
+    modules: [module],
+    installations: [
+      {
+        manifest: module,
+        setup(host) {
+          host.registerDebugSessionProviders([provider]);
+        },
+      },
+    ],
+  });
+  const base = createServerRuntime(
+    {},
+    {
+      featureCatalog: module.features,
+      licenseResolver: { resolve: () => ({ status: "valid" }) },
+    },
+  );
+  const runtime = {
+    ...base,
+    agentDebugOperationForActor: (actorId: string) =>
+      actorId === "service_adk_debug" ? OPERATION_KEY : undefined,
+  };
+  const context = createContext(actor(permissionKeys), true);
+  return {
+    context,
+    facade: new DebugSessionFacadeV1(
+      hosts,
+      runtime,
+      new DebugSessionIdCodecV1("test-secret-012345678901234567890123456789"),
+    ),
+    runtime,
+  };
+}
+
+function createContext(value: RequestActor, projected: boolean) {
+  const actorValue = projected
+    ? bindModuleUserProjection(value, "user_dev_admin")
+    : value;
+  return createRequestGuardContext(
+    new Request("http://localhost/api/agent/debug/sessions/v1"),
+    {
+      resolveActor: () => actorValue,
+      resolveLicense: () => ({ status: "valid" }),
+      licenseEnforced: false,
+    },
+  );
+}
+
+function actor(
+  permissionKeys: string[] = ["known.copilot.execute"],
+): RequestActor {
+  return {
+    id: "service_adk_debug",
+    type: "service",
+    name: "ADK Debug",
+    roleCodes: ["adk-debug"],
+    permissionKeys,
+  };
+}
+
+function summary() {
+  return {
+    sourceId: SOURCE_ID,
+    title: "历史研判",
+    scopeLabel: "测试范围",
+    updatedAt: "2026-07-31T01:00:01.000Z",
+    revision: "2",
+  };
+}
+
+function signal(): AbortSignal {
+  return new AbortController().signal;
+}
+
+function debugManifest(): ModuleManifest {
+  return manifest("known", {
+    features: [
+      {
+        key: featureKey("known.copilot"),
+        label: "Copilot",
+        module: "known",
+        visible: "visible",
+        enabled: true,
+        stage: "stable",
+      },
+    ],
+    permissions: [
+      {
+        key: "known.copilot.execute",
+        label: "使用 Copilot",
+        module: "known",
+        moduleLabel: "Known",
+        resource: "copilot",
+        resourceLabel: "Copilot",
+        action: "execute",
+      },
+    ],
+    aiOperations: [
+      {
+        key: OPERATION_KEY,
+        kind: "agent",
+        featureKey: "known.copilot",
+        permissionKey: "known.copilot.execute",
+        auditAction: "known.copilot.execute",
+        inputSchemaKey: "known.copilot.input.v1",
+        outputSchemaKey: "known.copilot.output.v1",
+        requiredCapabilities: ["text-generation"],
+        allowedToolKeys: [],
+        dataClassification: "internal",
+        execution: "streaming",
+        limits: {
+          maxDurationSeconds: 60,
+          maxInputBytes: 4096,
+          maxOutputBytes: 4096,
+        },
+      },
+    ],
+    auditActions: ["known.copilot.execute", "known.copilot.history.read"],
+  });
+}

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

@@ -0,0 +1,302 @@
+import { randomUUIDv7 } from "bun";
+import {
+  MODULE_DEBUG_SESSION_SCHEMA_VERSION,
+  type ModuleDebugSessionSummaryV1,
+} from "@southwind-ai/server-sdk";
+import { evaluateAccessGuards } from "../access-guards.js";
+import { auditActor, type RequestGuardContext } from "../guards.js";
+import type {
+  InitializedModuleHosts,
+  RegisteredModuleDebugSessionProvider,
+} from "../module-host.js";
+import { toModuleActor } from "../module-host.js";
+import type { createServerRuntime } from "../runtime.js";
+import { debugActorAuditMetadata } from "./run-debug-authorization.js";
+import { DebugSessionIdCodecV1 } from "./debug-session-id.js";
+import { readAllDebugSessionSummaries } from "./debug-session-provider-reader.js";
+import {
+  DebugSessionProviderContractError,
+  validateDebugSessionDetail,
+} from "./debug-session-validation.js";
+
+type ServerRuntime = Pick<
+  ReturnType<typeof createServerRuntime>,
+  | "agentDebugOperationForActor"
+  | "auditSink"
+  | "recordDecisions"
+  | "resolveFeature"
+>;
+
+export interface DebugSessionSummaryDtoV1 {
+  readonly id: string;
+  readonly title: string;
+  readonly scopeLabel?: string;
+  readonly updatedAt: string;
+  readonly revision: string;
+}
+
+export interface DebugSessionDetailDtoV1 extends DebugSessionSummaryDtoV1 {
+  readonly messages: readonly {
+    sequence: number;
+    role: "user" | "assistant";
+    content: string;
+    createdAt: string;
+  }[];
+}
+
+export class DebugSessionFacadeError extends Error {
+  constructor(
+    readonly code:
+      | "FORBIDDEN"
+      | "INVALID_SESSION_ID"
+      | "SESSION_NOT_FOUND"
+      | "PROVIDER_INVALID"
+      | "PROVIDER_UNAVAILABLE",
+    message: string,
+    readonly status: number,
+  ) {
+    super(message);
+  }
+}
+
+export class DebugSessionFacadeV1 {
+  constructor(
+    private readonly hosts: InitializedModuleHosts,
+    private readonly runtime: ServerRuntime,
+    private readonly ids: DebugSessionIdCodecV1,
+  ) {}
+
+  async list(context: RequestGuardContext, signal: AbortSignal) {
+    const authorized = await this.authorizedProviders(context);
+    const actor = toModuleActor(context.actor);
+    const results = await Promise.all(
+      authorized.map(async (entry) => {
+        try {
+          const sessions = await readAllDebugSessionSummaries({
+            provider: entry.provider,
+            actor,
+            operationKey: entry.operationKey,
+            signal,
+          });
+          this.audit(entry, context, "list", undefined, sessions.length);
+          return { ok: true as const, entry, sessions };
+        } catch (error) {
+          this.auditFailure(entry, context, "list", "list", error);
+          return { ok: false as const };
+        }
+      }),
+    );
+    if (results.some((result) => !result.ok)) throw providerUnavailable();
+    const projected = results
+      .flatMap((result) => (result.ok ? [result] : []))
+      .flatMap(({ entry, sessions }) =>
+        sessions.map((session) => this.project(entry, actor.id, session)),
+      )
+      .sort(
+        (left, right) =>
+          Date.parse(right.updatedAt) - Date.parse(left.updatedAt),
+      );
+    return {
+      schemaVersion: MODULE_DEBUG_SESSION_SCHEMA_VERSION,
+      sessions: projected,
+      truncated: false,
+    };
+  }
+
+  async get(
+    sessionId: string,
+    context: RequestGuardContext,
+    signal: AbortSignal,
+  ) {
+    if (!this.ids.isWellFormed(sessionId)) {
+      throw new DebugSessionFacadeError(
+        "INVALID_SESSION_ID",
+        "调试会话 ID 无效",
+        400,
+      );
+    }
+    const authorized = await this.authorizedProviders(context);
+    const actor = toModuleActor(context.actor);
+    let providerFailed = false;
+    for (const entry of authorized) {
+      let summaries: readonly ModuleDebugSessionSummaryV1[];
+      try {
+        summaries = await readAllDebugSessionSummaries({
+          provider: entry.provider,
+          actor,
+          operationKey: entry.operationKey,
+          signal,
+        });
+      } catch (error) {
+        providerFailed = true;
+        this.auditFailure(entry, context, "get", "list", error);
+        continue;
+      }
+      for (const summary of summaries) {
+        const projected = this.project(entry, actor.id, summary);
+        if (projected.id !== sessionId) continue;
+        try {
+          const detail = await entry.provider.get({
+            actor,
+            operationKey: entry.operationKey,
+            sourceId: summary.sourceId,
+            signal,
+          });
+          if (!detail) break;
+          const validated = validateDebugSessionDetail(
+            detail,
+            summary.sourceId,
+          );
+          this.audit(
+            entry,
+            context,
+            "get",
+            sessionId,
+            validated.messages.length,
+          );
+          return {
+            schemaVersion: MODULE_DEBUG_SESSION_SCHEMA_VERSION,
+            session: {
+              ...this.project(entry, actor.id, validated),
+              messages: validated.messages,
+            } satisfies DebugSessionDetailDtoV1,
+          };
+        } catch (error) {
+          providerFailed = true;
+          this.auditFailure(entry, context, "get", "get", error);
+          break;
+        }
+      }
+    }
+    if (providerFailed) throw providerUnavailable();
+    throw new DebugSessionFacadeError(
+      "SESSION_NOT_FOUND",
+      "调试会话不存在或不可访问",
+      404,
+    );
+  }
+
+  private async authorizedProviders(context: RequestGuardContext) {
+    const operationKey = this.runtime.agentDebugOperationForActor(
+      context.actor.id,
+    );
+    if (!operationKey) {
+      throw new DebugSessionFacadeError("FORBIDDEN", "调试会话访问被拒绝", 403);
+    }
+    const candidates = this.hosts.debugSessionProviders.filter(({ provider }) =>
+      provider.operationKeys.includes(operationKey),
+    );
+    for (const { moduleName, provider } of candidates) {
+      const manifest = this.hosts.manifestOf(moduleName);
+      const feature = manifest.features.find(
+        ({ key }) => key === provider.featureKey,
+      );
+      const access = await evaluateAccessGuards(this.runtime, context, {
+        permission: { permissionKey: provider.permissionKey },
+        feature,
+      });
+      if (!access.decision.allowed) {
+        throw new DebugSessionFacadeError(
+          "FORBIDDEN",
+          "调试会话访问被拒绝",
+          403,
+        );
+      }
+    }
+    return candidates.map((entry) => ({ ...entry, operationKey }));
+  }
+
+  private project(
+    entry: AuthorizedProvider,
+    actorId: string,
+    summary: ModuleDebugSessionSummaryV1,
+  ): DebugSessionSummaryDtoV1 {
+    return {
+      id: this.ids.issue({
+        actorId,
+        operationKey: entry.operationKey,
+        providerKey: entry.provider.key,
+        sourceId: summary.sourceId,
+      }),
+      title: summary.title,
+      ...(summary.scopeLabel ? { scopeLabel: summary.scopeLabel } : {}),
+      updatedAt: summary.updatedAt,
+      revision: summary.revision,
+    };
+  }
+
+  private audit(
+    entry: AuthorizedProvider,
+    context: RequestGuardContext,
+    mode: "list" | "get",
+    sessionId: string | undefined,
+    resultCount: number,
+  ): void {
+    this.runtime.auditSink.recordEvent({
+      id: randomUUIDv7(),
+      action: entry.provider.auditAction,
+      outcome: "success",
+      actor: auditActor(context),
+      target: {
+        type: "agent-debug-session",
+        id: sessionId ?? entry.provider.key,
+      },
+      module: entry.moduleName,
+      requestId: context.requestId,
+      metadata: {
+        ...debugActorAuditMetadata(context.actor),
+        mode,
+        resultCount,
+      },
+      occurredAt: new Date().toISOString(),
+    });
+  }
+
+  private auditFailure(
+    entry: AuthorizedProvider,
+    context: RequestGuardContext,
+    mode: "list" | "get",
+    phase: "list" | "get",
+    error: unknown,
+  ): void {
+    this.runtime.auditSink.recordEvent({
+      id: randomUUIDv7(),
+      action: entry.provider.auditAction,
+      outcome: "failure",
+      actor: auditActor(context),
+      target: {
+        type: "agent-debug-session-provider",
+        id: entry.provider.key,
+      },
+      module: entry.moduleName,
+      requestId: context.requestId,
+      metadata: {
+        ...debugActorAuditMetadata(context.actor),
+        mode,
+        phase,
+        failureCode: providerFailureCode(error),
+      },
+      occurredAt: new Date().toISOString(),
+    });
+  }
+}
+
+type AuthorizedProvider = RegisteredModuleDebugSessionProvider & {
+  readonly operationKey: string;
+};
+
+function providerFailureCode(
+  error: unknown,
+): "PROVIDER_INVALID" | "PROVIDER_UNAVAILABLE" {
+  return error instanceof DebugSessionProviderContractError
+    ? "PROVIDER_INVALID"
+    : "PROVIDER_UNAVAILABLE";
+}
+
+function providerUnavailable(): DebugSessionFacadeError {
+  return new DebugSessionFacadeError(
+    "PROVIDER_UNAVAILABLE",
+    "调试会话 Provider 暂不可用",
+    503,
+  );
+}

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

@@ -0,0 +1,37 @@
+import { describe, expect, test } from "bun:test";
+import { DebugSessionIdCodecV1 } from "./debug-session-id.js";
+
+describe("ADK 调试会话不透明 ID", () => {
+  test("稳定绑定业务用户、Operation、Provider 与 sourceId", () => {
+    const codec = new DebugSessionIdCodecV1(
+      "test-secret-012345678901234567890123456789",
+    );
+    const identity = {
+      actorId: "user_dev_admin",
+      operationKey: "known.copilot.global",
+      providerKey: "known.copilot.history",
+      sourceId: "private-conversation-id",
+    };
+    const issued = codec.issue(identity);
+
+    expect(codec.issue(identity)).toBe(issued);
+    expect(issued).not.toContain(identity.sourceId);
+    expect(codec.isWellFormed(issued)).toBeTrue();
+    for (const changed of [
+      { ...identity, actorId: "user_other" },
+      { ...identity, operationKey: "known.copilot.case" },
+      { ...identity, providerKey: "known.other.history" },
+      { ...identity, sourceId: "other-conversation" },
+    ]) {
+      expect(codec.issue(changed)).not.toBe(issued);
+    }
+  });
+
+  test("短 Secret 与可逆业务 ID fail closed", () => {
+    expect(() => new DebugSessionIdCodecV1("short")).toThrow("至少 32");
+    const codec = new DebugSessionIdCodecV1(
+      "test-secret-012345678901234567890123456789",
+    );
+    expect(codec.isWellFormed("private-conversation-id")).toBeFalse();
+  });
+});

package/template/apps/server/src/agent/debug-session-id.ts

@@ -0,0 +1,37 @@
+import { createHmac } from "node:crypto";
+
+export const DEBUG_SESSION_ID_PREFIX = "wdbg1_";
+
+export interface DebugSessionIdentityV1 {
+  readonly actorId: string;
+  readonly operationKey: string;
+  readonly providerKey: string;
+  readonly sourceId: string;
+}
+
+export class DebugSessionIdCodecV1 {
+  constructor(private readonly secret: string) {
+    if (Buffer.byteLength(secret) < 32) {
+      throw new Error("调试会话 ID Secret 必须至少 32 字节");
+    }
+  }
+
+  issue(identity: DebugSessionIdentityV1): string {
+    const digest = createHmac("sha256", this.secret)
+      .update(
+        JSON.stringify([
+          1,
+          identity.actorId,
+          identity.operationKey,
+          identity.providerKey,
+          identity.sourceId,
+        ]),
+      )
+      .digest("base64url");
+    return `${DEBUG_SESSION_ID_PREFIX}${digest}`;
+  }
+
+  isWellFormed(value: string): boolean {
+    return /^wdbg1_[A-Za-z0-9_-]{43}$/.test(value);
+  }
+}