create-windy 0.4.0 → 0.5.0

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

@@ -0,0 +1,54 @@
+import type {
+  ModuleActor,
+  ModuleDebugSessionProviderV1,
+  ModuleDebugSessionSummaryV1,
+} from "@southwind-ai/server-sdk";
+import {
+  DebugSessionProviderContractError,
+  validateDebugSessionPage,
+} from "./debug-session-validation.js";
+
+const PAGE_SIZE = 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.
+ */
+export async function readAllDebugSessionSummaries(input: {
+  readonly provider: ModuleDebugSessionProviderV1;
+  readonly actor: ModuleActor;
+  readonly operationKey: string;
+  readonly signal: AbortSignal;
+}): Promise<readonly ModuleDebugSessionSummaryV1[]> {
+  const sessions: ModuleDebugSessionSummaryV1[] = [];
+  const sourceIds = new Set<string>();
+  const cursors = new Set<string>();
+  let cursor: string | undefined;
+  for (;;) {
+    input.signal.throwIfAborted();
+    const page = validateDebugSessionPage(
+      await input.provider.list({
+        actor: input.actor,
+        operationKey: input.operationKey,
+        limit: PAGE_SIZE,
+        ...(cursor ? { cursor } : {}),
+        signal: input.signal,
+      }),
+    );
+    for (const session of page.sessions) {
+      if (sourceIds.has(session.sourceId)) invalidProvider();
+      sourceIds.add(session.sourceId);
+      sessions.push(session);
+    }
+    if (!page.truncated) return sessions;
+    const next = page.next;
+    if (!next || cursors.has(next)) invalidProvider();
+    cursors.add(next);
+    cursor = next;
+  }
+}
+
+function invalidProvider(): never {
+  throw new DebugSessionProviderContractError("调试会话 Provider 分页游标无效");
+}

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

@@ -0,0 +1,64 @@
+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";
+
+describe("ADK 调试会话 V1 routes", () => {
+  test("只注册 GET 并在错误响应复用 guard requestId", async () => {
+    const app = new FakeRouteApp();
+    registerDebugSessionRoutesV1(app, {
+      list: async () => {
+        throw new DebugSessionFacadeError(
+          "PROVIDER_UNAVAILABLE",
+          "暂不可用",
+          503,
+        );
+      },
+    } as unknown as DebugSessionFacadeV1);
+    const request = new Request("http://localhost/api/agent/debug/sessions/v1");
+    const guardContext = createRequestGuardContext(request);
+
+    const response = (await app.invoke("GET", "/agent/debug/sessions/v1", {
+      request,
+      guardContext,
+      params: {},
+    })) as Response;
+
+    expect([...app.handlers.keys()]).toEqual([
+      "GET /agent/debug/sessions/v1",
+      "GET /agent/debug/sessions/v1/:sessionId",
+    ]);
+    expect(response.status).toBe(503);
+    expect(response.headers.get("cache-control")).toBe("no-store");
+    expect(await response.json()).toMatchObject({
+      code: "PROVIDER_UNAVAILABLE",
+      requestId: guardContext.requestId,
+      retryable: true,
+    });
+  });
+
+  test("成功响应同样禁止缓存", async () => {
+    const app = new FakeRouteApp();
+    registerDebugSessionRoutesV1(app, {
+      list: async () => ({
+        schemaVersion: 1,
+        sessions: [],
+        truncated: false,
+      }),
+    } as unknown as DebugSessionFacadeV1);
+    const request = new Request("http://localhost/api/agent/debug/sessions/v1");
+
+    const response = (await app.invoke("GET", "/agent/debug/sessions/v1", {
+      request,
+      guardContext: createRequestGuardContext(request),
+      params: {},
+    })) as Response;
+
+    expect(response.status).toBe(200);
+    expect(response.headers.get("cache-control")).toBe("no-store");
+  });
+});

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

@@ -0,0 +1,73 @@
+import type { RequestGuardContext } from "../guards.js";
+import type { RouteApp } from "../system/routes.js";
+import {
+  DebugSessionFacadeError,
+  type DebugSessionFacadeV1,
+} from "./debug-session-facade.js";
+
+interface DebugSessionRouteContext {
+  params: Record<string, string | undefined>;
+  request: Request;
+  guardContext: RequestGuardContext;
+}
+
+export function registerDebugSessionRoutesV1(
+  app: RouteApp,
+  facade: DebugSessionFacadeV1,
+) {
+  app.get("/agent/debug/sessions/v1", async (raw) => {
+    const context = raw as DebugSessionRouteContext;
+    try {
+      return json(
+        await facade.list(context.guardContext, context.request.signal),
+      );
+    } catch (error) {
+      return facadeError(error, context.guardContext.requestId);
+    }
+  });
+  app.get("/agent/debug/sessions/v1/:sessionId", async (raw) => {
+    const context = raw as DebugSessionRouteContext;
+    try {
+      return json(
+        await facade.get(
+          context.params.sessionId ?? "",
+          context.guardContext,
+          context.request.signal,
+        ),
+      );
+    } catch (error) {
+      return facadeError(error, context.guardContext.requestId);
+    }
+  });
+  return app;
+}
+
+function json(body: unknown, status = 200): Response {
+  return Response.json(body, {
+    status,
+    headers: { "cache-control": "no-store" },
+  });
+}
+
+function facadeError(error: unknown, requestId: string): Response {
+  if (error instanceof DebugSessionFacadeError) {
+    return json(
+      {
+        code: error.code,
+        message: error.message,
+        requestId,
+        retryable: error.status >= 500,
+      },
+      error.status,
+    );
+  }
+  return json(
+    {
+      code: "PROVIDER_UNAVAILABLE",
+      message: "调试会话 Provider 暂不可用",
+      requestId,
+      retryable: true,
+    },
+    503,
+  );
+}

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

@@ -0,0 +1,106 @@
+import type {
+  ModuleDebugSessionSummaryV1,
+  ModuleDebugSessionV1,
+} from "@southwind-ai/server-sdk";
+
+const MAX_SESSIONS = 100;
+const MAX_MESSAGES = 64;
+const MAX_MESSAGE_CHARS = 16_000;
+const MAX_TOTAL_MESSAGE_CHARS = 128_000;
+
+export class DebugSessionProviderContractError extends Error {}
+
+export function validateDebugSessionPage(value: {
+  sessions: readonly ModuleDebugSessionSummaryV1[];
+  truncated: boolean;
+  next?: string;
+}): {
+  sessions: readonly ModuleDebugSessionSummaryV1[];
+  truncated: boolean;
+  next?: string;
+} {
+  if (
+    !value ||
+    !Array.isArray(value.sessions) ||
+    typeof value.truncated !== "boolean" ||
+    value.sessions.length > MAX_SESSIONS ||
+    (value.truncated ? !validText(value.next, 2_000) : value.next !== undefined)
+  ) {
+    invalidProvider();
+  }
+  const sourceIds = new Set<string>();
+  for (const session of value.sessions) {
+    validateSummary(session);
+    if (sourceIds.has(session.sourceId)) invalidProvider();
+    sourceIds.add(session.sourceId);
+  }
+  return value;
+}
+
+export function validateDebugSessionDetail(
+  value: ModuleDebugSessionV1,
+  expectedSourceId: string,
+): ModuleDebugSessionV1 {
+  validateSummary(value);
+  if (
+    value.sourceId !== expectedSourceId ||
+    !Array.isArray(value.messages) ||
+    value.messages.length > MAX_MESSAGES
+  ) {
+    invalidProvider();
+  }
+  let previousSequence = -1;
+  let totalChars = 0;
+  for (const message of value.messages) {
+    if (
+      !message ||
+      !Number.isSafeInteger(message.sequence) ||
+      message.sequence <= previousSequence ||
+      (message.role !== "user" && message.role !== "assistant") ||
+      !validText(message.content, MAX_MESSAGE_CHARS, false) ||
+      !validDate(message.createdAt)
+    ) {
+      invalidProvider();
+    }
+    totalChars += message.content.length;
+    previousSequence = message.sequence;
+  }
+  if (totalChars > MAX_TOTAL_MESSAGE_CHARS) invalidProvider();
+  return value;
+}
+
+function validateSummary(value: ModuleDebugSessionSummaryV1): void {
+  if (
+    !value ||
+    !validText(value.sourceId, 200) ||
+    !validText(value.title, 200) ||
+    (value.scopeLabel !== undefined && !validText(value.scopeLabel, 120)) ||
+    !validDate(value.updatedAt) ||
+    !validText(value.revision, 200)
+  ) {
+    invalidProvider();
+  }
+}
+
+function validText(value: unknown, max: number, trim = true): value is string {
+  return (
+    typeof value === "string" &&
+    value.length <= max &&
+    value.trim().length > 0 &&
+    (!trim || value === value.trim())
+  );
+}
+
+function validDate(value: unknown): value is string {
+  return (
+    typeof value === "string" &&
+    value === value.trim() &&
+    value.length <= 40 &&
+    /(?:Z|[+-]\d{2}:\d{2})$/.test(value) &&
+    Number.isFinite(Date.parse(value))
+  );
+}
+
+function invalidProvider(): never {
+  throw new DebugSessionProviderContractError("调试会话 Provider 返回无效数据");
+}

package/template/apps/server/src/agent/drizzle-run-binding-repository.ts

@@ -85,6 +85,7 @@ function values(binding: AgentRunBinding) {
     actorId: binding.actorId,
     idempotencyHash: binding.idempotencyHash,
     tokenHash: binding.tokenHash,
+    inputDigestCommitment: binding.inputDigestCommitment,
     scopeHash: binding.scopeHash,
     scopeSnapshot: binding.scopeSnapshot,
     authorizationSnapshot: binding.authorizationSnapshot,
@@ -103,6 +104,7 @@ function map(row: typeof agentRunBindings.$inferSelect): AgentRunBinding {
     actorId: row.actorId,
     idempotencyHash: row.idempotencyHash,
     tokenHash: row.tokenHash,
+    inputDigestCommitment: row.inputDigestCommitment,
     scopeHash: row.scopeHash,
     scopeSnapshot: row.scopeSnapshot,
     authorizationSnapshot: row.authorizationSnapshot,

package/template/apps/server/src/agent/provider-input-governance.test.ts

@@ -2,6 +2,7 @@ import { describe, expect, test } from "bun:test";
 import type { AiProviderDataPolicy } from "@southwind-ai/modules";
 import {
   governProviderInput,
+  projectProviderInput,
   ProviderInputGovernanceError,
 } from "./provider-input-governance.js";
 
@@ -48,6 +49,23 @@ describe("Provider 输入字段治理", () => {
     expect(JSON.stringify(governed)).not.toContain("case-secret");
   });
 
+  test("承诺视图保留 allowlist 原值且不与脱敏占位符碰撞", () => {
+    expect(
+      projectProviderInput(
+        {
+          question: "联系 13800138000",
+          internalCaseId: "case-secret",
+        },
+        policy,
+      ),
+    ).toEqual({ question: "联系 13800138000" });
+    expect(
+      projectProviderInput({ question: "联系 [REDACTED]" }, policy),
+    ).not.toEqual(
+      projectProviderInput({ question: "联系 13800138000" }, policy),
+    );
+  });
+
   test.each([
     "password=do-not-send",
     "Bearer abcdefghijklmnop",

package/template/apps/server/src/agent/provider-input-governance.ts

@@ -25,6 +25,32 @@ const dlpPatterns = [
 export function governProviderInput(
   input: ModuleAiJsonValue,
   policy: AiProviderDataPolicy,
+): ModuleAiJsonValue {
+  return selectProviderInput(input, policy, (value, action) =>
+    governValue(value, action),
+  );
+}
+
+/**
+ * Build the stable execution-relevant input view without applying lossy DLP.
+ *
+ * Run attestation commits this view so exact caller input remains
+ * distinguishable even when two values redact to the same provider payload.
+ */
+export function projectProviderInput(
+  input: ModuleAiJsonValue,
+  policy: AiProviderDataPolicy,
+): ModuleAiJsonValue {
+  return selectProviderInput(input, policy, (value) => cloneValue(value));
+}
+
+function selectProviderInput(
+  input: ModuleAiJsonValue,
+  policy: AiProviderDataPolicy,
+  transform: (
+    value: ModuleAiJsonValue,
+    action: AiProviderDlpAction,
+  ) => ModuleAiJsonValue,
 ): ModuleAiJsonValue {
   if (!isRecord(input)) {
     throw new ProviderInputGovernanceError(
@@ -37,11 +63,21 @@ export function governProviderInput(
     const segments = parseJsonPointer(rule.jsonPointer);
     const result = readPath(input, segments);
     if (!result.found) continue;
-    writePath(governed, segments, governValue(result.value, rule.dlpAction));
+    writePath(governed, segments, transform(result.value, rule.dlpAction));
   }
   return governed;
 }
 
+function cloneValue(value: ModuleAiJsonValue): ModuleAiJsonValue {
+  if (Array.isArray(value)) return value.map(cloneValue);
+  if (isRecord(value)) {
+    return Object.fromEntries(
+      Object.entries(value).map(([key, item]) => [key, cloneValue(item)]),
+    );
+  }
+  return value;
+}
+
 function governValue(
   value: ModuleAiJsonValue,
   action: AiProviderDlpAction,

package/template/apps/server/src/agent/remote-runtime.test.ts

@@ -105,6 +105,11 @@ describe("RemoteAgentRuntime", () => {
       executionGrant: "grant_1",
       release: runtimeRelease(),
       traceId: "trace_request_1",
+      reporting: {
+        actorId: "user_1",
+        actorType: "user",
+        departmentId: "dept_1",
+      },
     };
     const runtime = new RemoteAgentRuntime({
       baseUrl: server.url.toString(),
@@ -128,6 +133,7 @@ describe("RemoteAgentRuntime", () => {
       toolNetworkPolicy: { mode: "forbidden" },
       release: operation.release,
       traceId: operation.traceId,
+      reporting: operation.reporting,
     });
     expect(
       (received as { limits: Record<string, unknown> }).limits,
@@ -185,6 +191,7 @@ describe("RemoteAgentRuntime", () => {
       executionGrant: "grant_1",
       release: runtimeRelease(),
       traceId: "trace_request_vision",
+      reporting: { actorId: "user_1", actorType: "user" },
     };
 
     await expect(

package/template/apps/server/src/agent/remote-runtime.ts

@@ -64,6 +64,7 @@ export class RemoteAgentRuntime implements AgentRuntimePort {
       executionGrant: request.executionGrant,
       release: request.release,
       traceId: request.traceId,
+      reporting: request.reporting,
       toolHostUrl: this.options.toolHostUrl,
     };
     const response = await this.request("/api/agent/runs", {

package/template/apps/server/src/agent/run-authorization.test.ts

@@ -20,6 +20,7 @@ describe("Agent Run 持久授权绑定", () => {
       operationKey: "business.answer",
       releaseId: "release-1",
       idempotencyKey: "request-1",
+      input: { question: "same" },
       authorizationSnapshot: snapshot,
       context: context("actor-1", "role-1"),
     });
@@ -30,6 +31,7 @@ describe("Agent Run 持久授权绑定", () => {
       operationKey: "business.answer",
       releaseId: "release-1",
       idempotencyKey: "request-1",
+      input: { question: "same" },
       authorizationSnapshot: snapshot,
       context: context("actor-1", "role-1"),
     });
@@ -52,6 +54,7 @@ describe("Agent Run 持久授权绑定", () => {
       operationKey: "business.answer",
       releaseId: "release-1",
       idempotencyKey: "request-fast-tool",
+      input: { question: "fast" },
       authorizationSnapshot: snapshot,
       context: context("actor-1", "role-1"),
     });
@@ -75,6 +78,7 @@ describe("Agent Run 持久授权绑定", () => {
       operationKey: "business.answer",
       releaseId: "release-1",
       idempotencyKey: "request-denied",
+      input: { question: "denied" },
       authorizationSnapshot: snapshot,
       context: context("actor-1", "role-1"),
     });
@@ -102,6 +106,100 @@ describe("Agent Run 持久授权绑定", () => {
       message: "Agent Run 不存在或不可访问",
     });
   });
+
+  test("输入对象键序不影响承诺，但相同幂等键不能绑定不同输入", async () => {
+    const store = new AgentRunAuthorizationStore(
+      new InMemoryAgentRunBindingRepository(),
+      secret,
+    );
+    const currentContext = context("actor-1", "role-1");
+    const first = await store.issue({
+      operationKey: "business.answer",
+      releaseId: "release-1",
+      idempotencyKey: "request-input",
+      input: { question: "same", nested: { b: 2, a: 1 } },
+      authorizationSnapshot: snapshot,
+      context: currentContext,
+    });
+    await store.bind(first, "run-input");
+
+    await expect(
+      store.issue({
+        operationKey: "business.answer",
+        releaseId: "release-1",
+        idempotencyKey: "request-input",
+        input: { nested: { a: 1, b: 2 }, question: "same" },
+        authorizationSnapshot: snapshot,
+        context: currentContext,
+      }),
+    ).resolves.toMatchObject({ token: first.token });
+    await expect(
+      store.issue({
+        operationKey: "business.answer",
+        releaseId: "release-1",
+        idempotencyKey: "request-input",
+        input: { question: "different" },
+        authorizationSnapshot: snapshot,
+        context: currentContext,
+      }),
+    ).rejects.toMatchObject({ message: "Agent Run 不存在或不可访问" });
+    await expect(
+      store.verifyRunInput(
+        "business.answer",
+        "run-input",
+        { nested: { b: 2, a: 1 }, question: "same" },
+        currentContext,
+      ),
+    ).resolves.toBeDefined();
+    await expect(
+      store.verifyRunInput(
+        "business.answer",
+        "run-input",
+        { question: "different" },
+        currentContext,
+      ),
+    ).rejects.toMatchObject({ message: "Agent Run 不存在或不可访问" });
+  });
+
+  test("升级前绑定保留普通授权，但零值承诺不能通过输入验证", async () => {
+    const sourceStore = new AgentRunAuthorizationStore(
+      new InMemoryAgentRunBindingRepository(),
+      secret,
+    );
+    const currentContext = context("actor-1", "role-1");
+    const issued = await sourceStore.issue({
+      operationKey: "business.answer",
+      releaseId: "release-1",
+      idempotencyKey: "legacy-binding",
+      input: { question: "legacy" },
+      authorizationSnapshot: snapshot,
+      context: currentContext,
+    });
+    const repository = new InMemoryAgentRunBindingRepository();
+    await repository.createOrGet({
+      ...issued.binding,
+      runId: "run-legacy",
+      boundAt: Date.now(),
+      inputDigestCommitment: "0".repeat(64),
+    });
+    const upgradedStore = new AgentRunAuthorizationStore(repository, secret);
+
+    await expect(
+      upgradedStore.authorizeBrowser(
+        "business.answer",
+        "run-legacy",
+        currentContext,
+      ),
+    ).resolves.toBeDefined();
+    await expect(
+      upgradedStore.verifyRunInput(
+        "business.answer",
+        "run-legacy",
+        { question: "legacy" },
+        currentContext,
+      ),
+    ).rejects.toMatchObject({ message: "Agent Run 不存在或不可访问" });
+  });
 });
 
 function context(actorId: string, roleId: string) {

package/template/apps/server/src/agent/run-authorization.ts

@@ -2,10 +2,15 @@ import { createHash, createHmac } from "node:crypto";
 import { captureAuthorizationScope } from "../data-access/scope-snapshot.js";
 import type { RequestGuardContext } from "../guards.js";
 import type { AgentRunAuthorizationSnapshot } from "@southwind-ai/shared";
+import type { ModuleAiJsonValue } from "@southwind-ai/server-sdk";
 import type {
   AgentRunBinding,
   AgentRunBindingRepository,
 } from "./run-binding-repository.js";
+import {
+  commitAgentRunInput,
+  sameInputCommitment,
+} from "./run-input-commitment.js";
 
 export interface AgentExecutionAuthorization {
   readonly binding: AgentRunBinding;
@@ -28,6 +33,7 @@ export class AgentRunAuthorizationStore {
     operationKey: string;
     releaseId: string;
     idempotencyKey: string;
+    input: ModuleAiJsonValue;
     authorizationSnapshot: AgentRunAuthorizationSnapshot;
     context: RequestGuardContext;
   }): Promise<AgentExecutionAuthorization> {
@@ -41,12 +47,18 @@ export class AgentRunAuthorizationStore {
     ].join("\u0000");
     const idempotencyHash = this.hmac(`idempotency\u0000${coordinate}`);
     const token = `grant_${this.hmac(`token\u0000${coordinate}`)}`;
+    const tokenHash = sha256(token);
     const candidate: AgentRunBinding = {
       bindingId: `binding_${idempotencyHash.slice(0, 40)}`,
       operationKey: input.operationKey,
       actorId: input.context.actor.id,
       idempotencyHash,
-      tokenHash: sha256(token),
+      tokenHash,
+      inputDigestCommitment: commitAgentRunInput(
+        this.secret,
+        tokenHash,
+        input.input,
+      ),
       scopeHash: scope.hash,
       scopeSnapshot: scope.snapshot,
       authorizationSnapshot: structuredClone(input.authorizationSnapshot),
@@ -117,6 +129,24 @@ export class AgentRunAuthorizationStore {
     return binding;
   }
 
+  async verifyRunInput(
+    operationKey: string,
+    runId: string,
+    input: ModuleAiJsonValue,
+    context: RequestGuardContext,
+  ) {
+    const binding = await this.authorizeBrowser(operationKey, runId, context);
+    const commitment = commitAgentRunInput(
+      this.secret,
+      binding.tokenHash,
+      input,
+    );
+    if (!sameInputCommitment(binding.inputDigestCommitment, commitment)) {
+      throw new AgentRunAuthorizationError();
+    }
+    return binding;
+  }
+
   assertCurrentScope(
     binding: AgentRunBinding,
     context: RequestGuardContext,
@@ -151,6 +181,7 @@ function sameAuthorization(
     existing.operationKey === candidate.operationKey &&
     existing.actorId === candidate.actorId &&
     existing.tokenHash === candidate.tokenHash &&
+    existing.inputDigestCommitment === candidate.inputDigestCommitment &&
     existing.scopeHash === candidate.scopeHash &&
     sameSnapshot(
       existing.authorizationSnapshot,

package/template/apps/server/src/agent/run-binding-repository.ts

@@ -10,6 +10,7 @@ export interface AgentRunBinding {
   readonly actorId: string;
   readonly idempotencyHash: string;
   readonly tokenHash: string;
+  readonly inputDigestCommitment: string;
   readonly scopeHash: string;
   readonly scopeSnapshot: AuthorizationScopeSnapshot;
   readonly authorizationSnapshot: AgentRunAuthorizationSnapshot;

package/template/apps/server/src/agent/run-contracts.ts

@@ -38,6 +38,11 @@ export interface AgentRuntimeOperation {
   executionGrant: string;
   release: AgentRuntimeRelease;
   traceId: string;
+  reporting: {
+    actorId: string;
+    actorType: "anonymous" | "user" | "service";
+    departmentId?: string;
+  };
 }
 
 export interface AgentRuntimeRelease {