create-windy 0.6.12 → 0.6.14

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 返回无效数据",
+  );
 }

package/template/apps/server/src/agent/client-session/authorization.ts

@@ -0,0 +1,47 @@
+import type {
+  ClientSessionAdmissionPort,
+  ClientSessionCaller,
+  ClientSessionRecord,
+} from "./contracts.js";
+import { digestText, sameSecret } from "./digest.js";
+import { clientSessionConflict, clientSessionHidden } from "./errors.js";
+import type { ClientSessionRepository } from "./repository.js";
+
+export async function authorizeClientSession(input: {
+  sessionId: string;
+  caller: ClientSessionCaller;
+  requireActive: boolean;
+  repository: ClientSessionRepository;
+  admission: ClientSessionAdmissionPort;
+  now(): number;
+  abort(): void;
+  audit(record: ClientSessionRecord, cause: string): Promise<void> | void;
+}): Promise<ClientSessionRecord> {
+  const record = await input.repository.find(input.sessionId);
+  if (
+    !record ||
+    !sameSecret(record.tokenHash, digestText(input.caller.token)) ||
+    record.actorId !== input.caller.actorId ||
+    !sameSecret(record.clientBindingDigest, input.caller.clientBindingDigest) ||
+    !sameSecret(record.hostSessionDigest, input.caller.hostSessionDigest)
+  ) {
+    throw clientSessionHidden();
+  }
+  if (record.expiresAt <= input.now()) {
+    if (record.status === "active") {
+      input.abort();
+      await input.repository.transition(input.sessionId, "active", "expired");
+    }
+    throw clientSessionHidden();
+  }
+  if (!(await input.admission.reauthorize(record, input.caller.actorId))) {
+    input.abort();
+    await input.repository.transition(input.sessionId, "active", "revoked");
+    await input.audit(record, "authorization-drift");
+    throw clientSessionHidden();
+  }
+  if (input.requireActive && record.status !== "active") {
+    throw clientSessionConflict("会话已关闭");
+  }
+  return (await input.repository.find(input.sessionId)) ?? record;
+}

package/template/apps/server/src/agent/client-session/bootstrap.ts

@@ -0,0 +1,96 @@
+import type { ModuleManifest } from "@southwind-ai/modules";
+import type { ModuleClientAgentHostAuthAdapter } from "@southwind-ai/server-sdk";
+import type { NodePgDatabase } from "drizzle-orm/node-postgres";
+import type { RequestActor } from "../../guards.js";
+import type { InitializedModuleHosts } from "../../module-host.js";
+import type { createServerRuntime } from "../../runtime.js";
+import type { RouteApp } from "../../system/routes.js";
+import {
+  createManifestAuthorizedRouteApp,
+  type StaticRouteAuthorizer,
+} from "../../module-host/static-route-authorization.js";
+import { registerUnavailableClientAgentSessionRoutes } from "../unavailable-routes.js";
+import { DrizzleClientSessionRepository } from "./drizzle-repository.js";
+import { ManifestClientSessionAdmission } from "./manifest-admission.js";
+import { RemoteClientAgentProvider } from "./remote-provider.js";
+import { InMemoryClientSessionRepository } from "./repository.js";
+import { registerGovernedClientAgentSessionRoutes } from "./routes.js";
+import { RuntimeClientSessionAudit } from "./runtime-audit.js";
+import { GovernedClientAgentSessionService } from "./service.js";
+import {
+  createClientAgentHostAuthRouteApp,
+  hostSessionDigest,
+} from "./host-auth.js";
+
+export function createClientAgentSessionRuntime(input: {
+  app: RouteApp;
+  modules: readonly ModuleManifest[];
+  hosts: InitializedModuleHosts;
+  runtime: ReturnType<typeof createServerRuntime>;
+  db?: NodePgDatabase;
+  agentServerUrl: string;
+  internalToken: string;
+  hostAuth?: ModuleClientAgentHostAuthAdapter;
+  routeAuthorizer: StaticRouteAuthorizer;
+  resolveActor(actorId: string): Promise<RequestActor | undefined>;
+}) {
+  if (!input.hostAuth) {
+    registerUnavailableClientAgentSessionRoutes(
+      createManifestAuthorizedRouteApp(input.app, input.routeAuthorizer),
+    );
+    return { service: undefined, dispose: undefined };
+  }
+  const service = new GovernedClientAgentSessionService(
+    input.db
+      ? new DrizzleClientSessionRepository(input.db)
+      : new InMemoryClientSessionRepository(),
+    new ManifestClientSessionAdmission(
+      input.modules,
+      input.hosts,
+      input.runtime,
+      async (actorId) => {
+        const request = new Request(
+          "http://client-agent.internal/authorization",
+        );
+        const actor = await input.resolveActor(actorId);
+        return actor
+          ? input.runtime.createGuardContextForActor(request, actor)
+          : input.runtime.createGuardContext(request);
+      },
+    ),
+    new RemoteClientAgentProvider({
+      baseUrl: input.agentServerUrl,
+      internalToken: input.internalToken,
+    }),
+    new RuntimeClientSessionAudit(input.runtime),
+    trustedBaseUrl(),
+  );
+  const hostApp = createClientAgentHostAuthRouteApp({
+    app: input.app,
+    adapter: input.hostAuth,
+    runtime: input.runtime,
+    resolveActor: input.resolveActor,
+  });
+  registerGovernedClientAgentSessionRoutes(
+    createManifestAuthorizedRouteApp(hostApp, input.routeAuthorizer),
+    service,
+  );
+  const unbind = input.hostAuth.bindRevocations(async (principal) => {
+    await service.revokeHostSession(
+      hostSessionDigest(principal),
+      principal.actorId,
+    );
+  });
+  return { service, dispose: unbind };
+}
+
+function trustedBaseUrl(): string {
+  const configured = process.env.WINDY_PUBLIC_BASE_URL?.trim();
+  if (!configured && process.env.NODE_ENV === "production") {
+    throw new Error("Client Agent Session 缺少 WINDY_PUBLIC_BASE_URL");
+  }
+  return new URL(
+    "/api/agent/client-sessions/",
+    configured || "http://localhost:9747",
+  ).toString();
+}

package/template/apps/server/src/agent/client-session/capabilities.ts

@@ -0,0 +1,19 @@
+import type { ClientAgentProviderPort } from "./contracts.js";
+import { ClientAgentSessionError } from "./errors.js";
+
+export async function clientAgentCapabilities(
+  provider: ClientAgentProviderPort,
+  signal?: AbortSignal,
+) {
+  if (!(await provider.ready(signal))) {
+    throw new ClientAgentSessionError(
+      "PROVIDER_FAILED",
+      "Client Agent Provider 尚未就绪",
+      503,
+    );
+  }
+  return {
+    capabilities: ["pageAgentClientRun"] as const,
+    modelAlias: provider.modelAlias,
+  };
+}