create-windy 0.6.12 → 0.6.15

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

@@ -1,41 +1,38 @@
 import { randomUUIDv7 } from "bun";
 import {
-  MODULE_DEBUG_SESSION_SCHEMA_VERSION,
-  type ModuleDebugSessionSummaryV1,
+  MODULE_AGENT_SESSION_SCHEMA_VERSION,
+  type ModuleAgentSessionSummaryV1,
 } from "@southwind-ai/server-sdk";
 import { evaluateAccessGuards } from "../access-guards.js";
 import { auditActor, type RequestGuardContext } from "../guards.js";
 import type {
   InitializedModuleHosts,
-  RegisteredModuleDebugSessionProvider,
+  RegisteredModuleAgentSessionProvider,
 } 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 { AgentSessionIdCodecV1 } from "./agent-session-id.js";
+import { readAllAgentSessionSummaries } from "./agent-session-provider-reader.js";
 import {
-  DebugSessionProviderContractError,
-  validateDebugSessionDetail,
-} from "./debug-session-validation.js";
+  AgentSessionProviderContractError,
+  validateAgentSessionDetail,
+} from "./agent-session-validation.js";
 
 type ServerRuntime = Pick<
   ReturnType<typeof createServerRuntime>,
-  | "agentDebugOperationForActor"
-  | "auditSink"
-  | "recordDecisions"
-  | "resolveFeature"
+  "auditSink" | "recordDecisions" | "resolveFeature"
 >;
 
-export interface DebugSessionSummaryDtoV1 {
+export interface AgentSessionSummaryDtoV1 {
   readonly id: string;
+  readonly operationKey: string;
   readonly title: string;
   readonly scopeLabel?: string;
   readonly updatedAt: string;
   readonly revision: string;
 }
 
-export interface DebugSessionDetailDtoV1 extends DebugSessionSummaryDtoV1 {
+export interface AgentSessionDetailDtoV1 extends AgentSessionSummaryDtoV1 {
   readonly messages: readonly {
     sequence: number;
     role: "user" | "assistant";
@@ -44,7 +41,7 @@ export interface DebugSessionDetailDtoV1 extends DebugSessionSummaryDtoV1 {
   }[];
 }
 
-export class DebugSessionFacadeError extends Error {
+export class AgentSessionFacadeError extends Error {
   constructor(
     readonly code:
       | "FORBIDDEN"
@@ -59,11 +56,11 @@ export class DebugSessionFacadeError extends Error {
   }
 }
 
-export class DebugSessionFacadeV1 {
+export class AgentSessionFacadeV1 {
   constructor(
     private readonly hosts: InitializedModuleHosts,
     private readonly runtime: ServerRuntime,
-    private readonly ids: DebugSessionIdCodecV1,
+    private readonly ids: AgentSessionIdCodecV1,
   ) {}
 
   async list(context: RequestGuardContext, signal: AbortSignal) {
@@ -72,7 +69,7 @@ export class DebugSessionFacadeV1 {
     const results = await Promise.all(
       authorized.map(async (entry) => {
         try {
-          const sessions = await readAllDebugSessionSummaries({
+          const sessions = await readAllAgentSessionSummaries({
             provider: entry.provider,
             actor,
             operationKey: entry.operationKey,
@@ -97,7 +94,7 @@ export class DebugSessionFacadeV1 {
           Date.parse(right.updatedAt) - Date.parse(left.updatedAt),
       );
     return {
-      schemaVersion: MODULE_DEBUG_SESSION_SCHEMA_VERSION,
+      schemaVersion: MODULE_AGENT_SESSION_SCHEMA_VERSION,
       sessions: projected,
       truncated: false,
     };
@@ -109,9 +106,9 @@ export class DebugSessionFacadeV1 {
     signal: AbortSignal,
   ) {
     if (!this.ids.isWellFormed(sessionId)) {
-      throw new DebugSessionFacadeError(
+      throw new AgentSessionFacadeError(
         "INVALID_SESSION_ID",
-        "调试会话 ID 无效",
+        "Agent 会话 ID 无效",
         400,
       );
     }
@@ -119,9 +116,9 @@ export class DebugSessionFacadeV1 {
     const actor = toModuleActor(context.actor);
     let providerFailed = false;
     for (const entry of authorized) {
-      let summaries: readonly ModuleDebugSessionSummaryV1[];
+      let summaries: readonly ModuleAgentSessionSummaryV1[];
       try {
-        summaries = await readAllDebugSessionSummaries({
+        summaries = await readAllAgentSessionSummaries({
           provider: entry.provider,
           actor,
           operationKey: entry.operationKey,
@@ -143,7 +140,7 @@ export class DebugSessionFacadeV1 {
             signal,
           });
           if (!detail) break;
-          const validated = validateDebugSessionDetail(
+          const validated = validateAgentSessionDetail(
             detail,
             summary.sourceId,
           );
@@ -155,11 +152,11 @@ export class DebugSessionFacadeV1 {
             validated.messages.length,
           );
           return {
-            schemaVersion: MODULE_DEBUG_SESSION_SCHEMA_VERSION,
+            schemaVersion: MODULE_AGENT_SESSION_SCHEMA_VERSION,
             session: {
               ...this.project(entry, actor.id, validated),
               messages: validated.messages,
-            } satisfies DebugSessionDetailDtoV1,
+            } satisfies AgentSessionDetailDtoV1,
           };
         } catch (error) {
           providerFailed = true;
@@ -169,24 +166,17 @@ export class DebugSessionFacadeV1 {
       }
     }
     if (providerFailed) throw providerUnavailable();
-    throw new DebugSessionFacadeError(
+    throw new AgentSessionFacadeError(
       "SESSION_NOT_FOUND",
-      "调试会话不存在或不可访问",
+      "Agent 会话不存在或不可访问",
       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 authorized: AuthorizedProvider[] = [];
+    for (const entry of this.hosts.agentSessionProviders) {
+      const { moduleName, provider } = entry;
       const manifest = this.hosts.manifestOf(moduleName);
       const feature = manifest.features.find(
         ({ key }) => key === provider.featureKey,
@@ -195,22 +185,26 @@ export class DebugSessionFacadeV1 {
         permission: { permissionKey: provider.permissionKey },
         feature,
       });
-      if (!access.decision.allowed) {
-        throw new DebugSessionFacadeError(
-          "FORBIDDEN",
-          "调试会话访问被拒绝",
-          403,
-        );
+      if (!access.decision.allowed) continue;
+      for (const operationKey of provider.operationKeys) {
+        authorized.push({ ...entry, operationKey });
       }
     }
-    return candidates.map((entry) => ({ ...entry, operationKey }));
+    if (!authorized.length) {
+      throw new AgentSessionFacadeError(
+        "FORBIDDEN",
+        "Agent 会话访问被拒绝",
+        403,
+      );
+    }
+    return authorized;
   }
 
   private project(
     entry: AuthorizedProvider,
     actorId: string,
-    summary: ModuleDebugSessionSummaryV1,
-  ): DebugSessionSummaryDtoV1 {
+    summary: ModuleAgentSessionSummaryV1,
+  ): AgentSessionSummaryDtoV1 {
     return {
       id: this.ids.issue({
         actorId,
@@ -218,6 +212,7 @@ export class DebugSessionFacadeV1 {
         providerKey: entry.provider.key,
         sourceId: summary.sourceId,
       }),
+      operationKey: entry.operationKey,
       title: summary.title,
       ...(summary.scopeLabel ? { scopeLabel: summary.scopeLabel } : {}),
       updatedAt: summary.updatedAt,
@@ -238,13 +233,12 @@ export class DebugSessionFacadeV1 {
       outcome: "success",
       actor: auditActor(context),
       target: {
-        type: "agent-debug-session",
+        type: "agent-session",
         id: sessionId ?? entry.provider.key,
       },
       module: entry.moduleName,
       requestId: context.requestId,
       metadata: {
-        ...debugActorAuditMetadata(context.actor),
         mode,
         resultCount,
       },
@@ -265,13 +259,12 @@ export class DebugSessionFacadeV1 {
       outcome: "failure",
       actor: auditActor(context),
       target: {
-        type: "agent-debug-session-provider",
+        type: "agent-session-provider",
         id: entry.provider.key,
       },
       module: entry.moduleName,
       requestId: context.requestId,
       metadata: {
-        ...debugActorAuditMetadata(context.actor),
         mode,
         phase,
         failureCode: providerFailureCode(error),
@@ -281,22 +274,22 @@ export class DebugSessionFacadeV1 {
   }
 }
 
-type AuthorizedProvider = RegisteredModuleDebugSessionProvider & {
+type AuthorizedProvider = RegisteredModuleAgentSessionProvider & {
   readonly operationKey: string;
 };
 
 function providerFailureCode(
   error: unknown,
 ): "PROVIDER_INVALID" | "PROVIDER_UNAVAILABLE" {
-  return error instanceof DebugSessionProviderContractError
+  return error instanceof AgentSessionProviderContractError
     ? "PROVIDER_INVALID"
     : "PROVIDER_UNAVAILABLE";
 }
 
-function providerUnavailable(): DebugSessionFacadeError {
-  return new DebugSessionFacadeError(
+function providerUnavailable(): AgentSessionFacadeError {
+  return new AgentSessionFacadeError(
     "PROVIDER_UNAVAILABLE",
-    "调试会话 Provider 暂不可用",
+    "Agent 会话 Provider 暂不可用",
     503,
   );
 }

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

@@ -1,9 +1,9 @@
 import { describe, expect, test } from "bun:test";
-import { DebugSessionIdCodecV1 } from "./debug-session-id.js";
+import { AgentSessionIdCodecV1 } from "./agent-session-id.js";
 
-describe("ADK 调试会话不透明 ID", () => {
+describe("Agent 会话不透明 ID", () => {
   test("稳定绑定业务用户、Operation、Provider 与 sourceId", () => {
-    const codec = new DebugSessionIdCodecV1(
+    const codec = new AgentSessionIdCodecV1(
       "test-secret-012345678901234567890123456789",
     );
     const identity = {
@@ -28,8 +28,8 @@ describe("ADK 调试会话不透明 ID", () => {
   });
 
   test("短 Secret 与可逆业务 ID fail closed", () => {
-    expect(() => new DebugSessionIdCodecV1("short")).toThrow("至少 32");
-    const codec = new DebugSessionIdCodecV1(
+    expect(() => new AgentSessionIdCodecV1("short")).toThrow("至少 32");
+    const codec = new AgentSessionIdCodecV1(
       "test-secret-012345678901234567890123456789",
     );
     expect(codec.isWellFormed("private-conversation-id")).toBeFalse();

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

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

package/template/apps/server/src/agent/{debug-session-provider-reader.ts → agent-session-provider-reader.ts}

@@ -1,33 +1,33 @@
 import type {
   ModuleActor,
-  ModuleDebugSessionProviderV1,
-  ModuleDebugSessionSummaryV1,
+  ModuleAgentSessionProviderV1,
+  ModuleAgentSessionSummaryV1,
 } from "@southwind-ai/server-sdk";
 import {
-  DebugSessionProviderContractError,
-  validateDebugSessionPage,
-} from "./debug-session-validation.js";
+  AgentSessionProviderContractError,
+  validateAgentSessionPage,
+} from "./agent-session-validation.js";
 
 const PAGE_SIZE = 100;
+const MAX_PAGES = 100;
 
 /**
- * Drain one Provider with bounded keyset pages. The native ADK session API has
- * no pagination surface, so returning a partial page would make older sessions
- * permanently undiscoverable.
+ * Drain one Provider with bounded keyset pages so older sessions remain
+ * discoverable even when a Provider page is smaller than the Host projection.
  */
-export async function readAllDebugSessionSummaries(input: {
-  readonly provider: ModuleDebugSessionProviderV1;
+export async function readAllAgentSessionSummaries(input: {
+  readonly provider: ModuleAgentSessionProviderV1;
   readonly actor: ModuleActor;
   readonly operationKey: string;
   readonly signal: AbortSignal;
-}): Promise<readonly ModuleDebugSessionSummaryV1[]> {
-  const sessions: ModuleDebugSessionSummaryV1[] = [];
+}): Promise<readonly ModuleAgentSessionSummaryV1[]> {
+  const sessions: ModuleAgentSessionSummaryV1[] = [];
   const sourceIds = new Set<string>();
   const cursors = new Set<string>();
   let cursor: string | undefined;
-  for (;;) {
+  for (let pageNumber = 0; pageNumber < MAX_PAGES; pageNumber += 1) {
     input.signal.throwIfAborted();
-    const page = validateDebugSessionPage(
+    const page = validateAgentSessionPage(
       await input.provider.list({
         actor: input.actor,
         operationKey: input.operationKey,
@@ -47,8 +47,11 @@ export async function readAllDebugSessionSummaries(input: {
     cursors.add(next);
     cursor = next;
   }
+  invalidProvider();
 }
 
 function invalidProvider(): never {
-  throw new DebugSessionProviderContractError("调试会话 Provider 分页游标无效");
+  throw new AgentSessionProviderContractError(
+    "Agent 会话 Provider 分页游标无效",
+  );
 }

package/template/apps/server/src/agent/{debug-session-routes.test.ts → agent-session-routes.test.ts}

@@ -2,35 +2,35 @@ import { describe, expect, test } from "bun:test";
 import { createRequestGuardContext } from "../guards.js";
 import { FakeRouteApp } from "../system/route-test-app.js";
 import {
-  DebugSessionFacadeError,
-  type DebugSessionFacadeV1,
-} from "./debug-session-facade.js";
-import { registerDebugSessionRoutesV1 } from "./debug-session-routes.js";
+  AgentSessionFacadeError,
+  type AgentSessionFacadeV1,
+} from "./agent-session-facade.js";
+import { registerAgentSessionRoutesV1 } from "./agent-session-routes.js";
 
-describe("ADK 调试会话 V1 routes", () => {
+describe("Agent 会话 V1 routes", () => {
   test("只注册 GET 并在错误响应复用 guard requestId", async () => {
     const app = new FakeRouteApp();
-    registerDebugSessionRoutesV1(app, {
+    registerAgentSessionRoutesV1(app, {
       list: async () => {
-        throw new DebugSessionFacadeError(
+        throw new AgentSessionFacadeError(
           "PROVIDER_UNAVAILABLE",
           "暂不可用",
           503,
         );
       },
-    } as unknown as DebugSessionFacadeV1);
-    const request = new Request("http://localhost/api/agent/debug/sessions/v1");
+    } as unknown as AgentSessionFacadeV1);
+    const request = new Request("http://localhost/api/agent/sessions/v1");
     const guardContext = createRequestGuardContext(request);
 
-    const response = (await app.invoke("GET", "/agent/debug/sessions/v1", {
+    const response = (await app.invoke("GET", "/agent/sessions/v1", {
       request,
       guardContext,
       params: {},
     })) as Response;
 
     expect([...app.handlers.keys()]).toEqual([
-      "GET /agent/debug/sessions/v1",
-      "GET /agent/debug/sessions/v1/:sessionId",
+      "GET /agent/sessions/v1",
+      "GET /agent/sessions/v1/:sessionId",
     ]);
     expect(response.status).toBe(503);
     expect(response.headers.get("cache-control")).toBe("no-store");
@@ -43,16 +43,16 @@ describe("ADK 调试会话 V1 routes", () => {
 
   test("成功响应同样禁止缓存", async () => {
     const app = new FakeRouteApp();
-    registerDebugSessionRoutesV1(app, {
+    registerAgentSessionRoutesV1(app, {
       list: async () => ({
         schemaVersion: 1,
         sessions: [],
         truncated: false,
       }),
-    } as unknown as DebugSessionFacadeV1);
-    const request = new Request("http://localhost/api/agent/debug/sessions/v1");
+    } as unknown as AgentSessionFacadeV1);
+    const request = new Request("http://localhost/api/agent/sessions/v1");
 
-    const response = (await app.invoke("GET", "/agent/debug/sessions/v1", {
+    const response = (await app.invoke("GET", "/agent/sessions/v1", {
       request,
       guardContext: createRequestGuardContext(request),
       params: {},

package/template/apps/server/src/agent/{debug-session-routes.ts → agent-session-routes.ts}

@@ -1,22 +1,22 @@
 import type { RequestGuardContext } from "../guards.js";
 import type { RouteApp } from "../system/routes.js";
 import {
-  DebugSessionFacadeError,
-  type DebugSessionFacadeV1,
-} from "./debug-session-facade.js";
+  AgentSessionFacadeError,
+  type AgentSessionFacadeV1,
+} from "./agent-session-facade.js";
 
-interface DebugSessionRouteContext {
+interface AgentSessionRouteContext {
   params: Record<string, string | undefined>;
   request: Request;
   guardContext: RequestGuardContext;
 }
 
-export function registerDebugSessionRoutesV1(
+export function registerAgentSessionRoutesV1(
   app: RouteApp,
-  facade: DebugSessionFacadeV1,
+  facade: AgentSessionFacadeV1,
 ) {
-  app.get("/agent/debug/sessions/v1", async (raw) => {
-    const context = raw as DebugSessionRouteContext;
+  app.get("/agent/sessions/v1", async (raw) => {
+    const context = raw as AgentSessionRouteContext;
     try {
       return json(
         await facade.list(context.guardContext, context.request.signal),
@@ -25,8 +25,8 @@ export function registerDebugSessionRoutesV1(
       return facadeError(error, context.guardContext.requestId);
     }
   });
-  app.get("/agent/debug/sessions/v1/:sessionId", async (raw) => {
-    const context = raw as DebugSessionRouteContext;
+  app.get("/agent/sessions/v1/:sessionId", async (raw) => {
+    const context = raw as AgentSessionRouteContext;
     try {
       return json(
         await facade.get(
@@ -50,7 +50,7 @@ function json(body: unknown, status = 200): Response {
 }
 
 function facadeError(error: unknown, requestId: string): Response {
-  if (error instanceof DebugSessionFacadeError) {
+  if (error instanceof AgentSessionFacadeError) {
     return json(
       {
         code: error.code,
@@ -64,7 +64,7 @@ function facadeError(error: unknown, requestId: string): Response {
   return json(
     {
       code: "PROVIDER_UNAVAILABLE",
-      message: "调试会话 Provider 暂不可用",
+      message: "Agent 会话 Provider 暂不可用",
       requestId,
       retryable: true,
     },

package/template/apps/server/src/agent/{debug-session-validation.ts → agent-session-validation.ts}

@@ -1,6 +1,6 @@
 import type {
-  ModuleDebugSessionSummaryV1,
-  ModuleDebugSessionV1,
+  ModuleAgentSessionSummaryV1,
+  ModuleAgentSessionV1,
 } from "@southwind-ai/server-sdk";
 
 const MAX_SESSIONS = 100;
@@ -8,14 +8,14 @@ const MAX_MESSAGES = 64;
 const MAX_MESSAGE_CHARS = 16_000;
 const MAX_TOTAL_MESSAGE_CHARS = 128_000;
 
-export class DebugSessionProviderContractError extends Error {}
+export class AgentSessionProviderContractError extends Error {}
 
-export function validateDebugSessionPage(value: {
-  sessions: readonly ModuleDebugSessionSummaryV1[];
+export function validateAgentSessionPage(value: {
+  sessions: readonly ModuleAgentSessionSummaryV1[];
   truncated: boolean;
   next?: string;
 }): {
-  sessions: readonly ModuleDebugSessionSummaryV1[];
+  sessions: readonly ModuleAgentSessionSummaryV1[];
   truncated: boolean;
   next?: string;
 } {
@@ -37,10 +37,10 @@ export function validateDebugSessionPage(value: {
   return value;
 }
 
-export function validateDebugSessionDetail(
-  value: ModuleDebugSessionV1,
+export function validateAgentSessionDetail(
+  value: ModuleAgentSessionV1,
   expectedSourceId: string,
-): ModuleDebugSessionV1 {
+): ModuleAgentSessionV1 {
   validateSummary(value);
   if (
     value.sourceId !== expectedSourceId ||
@@ -69,7 +69,7 @@ export function validateDebugSessionDetail(
   return value;
 }
 
-function validateSummary(value: ModuleDebugSessionSummaryV1): void {
+function validateSummary(value: ModuleAgentSessionSummaryV1): void {
   if (
     !value ||
     !validText(value.sourceId, 200) ||
@@ -102,5 +102,7 @@ function validDate(value: unknown): value is string {
 }
 
 function invalidProvider(): never {
-  throw new DebugSessionProviderContractError("调试会话 Provider 返回无效数据");
+  throw new AgentSessionProviderContractError(
+    "Agent 会话 Provider 返回无效数据",
+  );
 }