create-windy 0.4.1 → 0.5.1

package/template/packages/database/drizzle/meta/_journal.json

@@ -316,6 +316,27 @@
       "when": 1785400645941,
       "tag": "0044_sweet_tarantula",
       "breakpoints": true
+    },
+    {
+      "idx": 45,
+      "version": "7",
+      "when": 1785432944198,
+      "tag": "0045_tiny_cassandra_nova",
+      "breakpoints": true
+    },
+    {
+      "idx": 46,
+      "version": "7",
+      "when": 1785437657721,
+      "tag": "0046_tranquil_living_mummy",
+      "breakpoints": true
+    },
+    {
+      "idx": 47,
+      "version": "7",
+      "when": 1785438653330,
+      "tag": "0047_oval_luke_cage",
+      "breakpoints": true
     }
   ]
 }

package/template/packages/database/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@southwind-ai/database",
-  "version": "0.2.3",
+  "version": "0.3.0",
   "license": "UNLICENSED",
   "type": "module",
   "engines": {

package/template/packages/database/src/agent-runtime-schema.test.ts

@@ -4,6 +4,8 @@ import {
   agentEvaluationResults,
   agentOperationReleases,
   agentRunBindings,
+  agentRuntimeReportAttempts,
+  agentRuntimeReportRuns,
   agentRuntimeEvents,
   agentRuntimeRuns,
 } from "./schema/index.js";
@@ -30,8 +32,23 @@ test("Agent Run 固定不可变 Release 并持久化恢复租约", async () => {
     "agent_evaluation_results",
   );
   expect(getTableConfig(agentRunBindings).name).toBe("agent_run_bindings");
+  expect(agentRunBindings.inputDigestCommitment.notNull).toBe(true);
   expect(agentRunBindings.scopeSnapshot.notNull).toBe(true);
   expect(agentRunBindings.authorizationSnapshot.notNull).toBe(true);
+  expect(getTableConfig(agentRuntimeReportRuns).name).toBe(
+    "agent_runtime_report_runs",
+  );
+  expect(agentRuntimeReportRuns.actorId.notNull).toBe(false);
+  expect(getTableConfig(agentRuntimeReportAttempts).name).toBe(
+    "agent_runtime_report_attempts",
+  );
+  expect(agentRuntimeReportAttempts.cachedInputTokens.notNull).toBe(false);
+  expect(agentRuntimeReportAttempts.reasoningTokens.notNull).toBe(false);
+  expect(
+    getTableConfig(agentRuntimeReportAttempts).indexes.some(
+      (index) => index.config.name === "idx_agent_report_attempts_started",
+    ),
+  ).toBe(true);
 
   const migration = await Bun.file(
     new URL("../drizzle/0040_colossal_baron_strucker.sql", import.meta.url),
@@ -51,4 +68,41 @@ test("Agent Run 固定不可变 Release 并持久化恢复租约", async () => {
   expect(bindingMigration).toContain(
     'CREATE UNIQUE INDEX "uk_agent_run_bindings_token"',
   );
+  const inputCommitmentMigration = await Bun.file(
+    new URL("../drizzle/0046_tranquil_living_mummy.sql", import.meta.url),
+  ).text();
+  expect(inputCommitmentMigration).toContain(
+    'ADD COLUMN "input_digest_commitment"',
+  );
+  expect(inputCommitmentMigration).toContain(
+    "DEFAULT repeat('0', 64) NOT NULL",
+  );
+  expect(inputCommitmentMigration).toContain(
+    'ALTER COLUMN "input_digest_commitment" DROP DEFAULT',
+  );
+  const reportMigration = await Bun.file(
+    new URL("../drizzle/0045_tiny_cassandra_nova.sql", import.meta.url),
+  ).text();
+  expect(reportMigration).toContain('CREATE TABLE "agent_runtime_report_runs"');
+  expect(reportMigration).toContain(
+    'CREATE TABLE "agent_runtime_report_attempts"',
+  );
+  expect(reportMigration).toContain(
+    'CREATE UNIQUE INDEX "uk_agent_report_attempts_sequence"',
+  );
+  expect(reportMigration).toContain(
+    'FOREIGN KEY ("run_id") REFERENCES "public"."agent_runtime_report_runs"',
+  );
+  const attemptLifecycleMigration = await Bun.file(
+    new URL("../drizzle/0047_oval_luke_cage.sql", import.meta.url),
+  ).text();
+  expect(attemptLifecycleMigration).toContain(
+    'CREATE INDEX "idx_agent_report_attempts_started"',
+  );
+  expect(attemptLifecycleMigration).toContain(
+    `WHERE "outcome" = 'abandoned' AND "finished_at" IS NULL`,
+  );
+  expect(attemptLifecycleMigration).toContain(
+    "'running', 'completed', 'failed', 'cancelled', 'blocked', 'abandoned'",
+  );
 });

package/template/packages/database/src/schema/agent-runtime.ts

@@ -89,6 +89,117 @@ export const agentRuntimeEvents = pgTable(
   ],
 );
 
+export const agentRuntimeReportRuns = pgTable(
+  "agent_runtime_report_runs",
+  {
+    runId: varchar("run_id", { length: 80 }).primaryKey(),
+    operationKey: varchar("operation_key", { length: 200 }).notNull(),
+    releaseId: varchar("release_id", { length: 80 }).notNull(),
+    traceId: varchar("trace_id", { length: 160 }).notNull(),
+    actorId: varchar("actor_id", { length: 64 }),
+    actorType: varchar("actor_type", { length: 32 }),
+    departmentId: varchar("department_id", { length: 64 }),
+    status: varchar("status", { length: 32 }).notNull(),
+    safeErrorCode: varchar("safe_error_code", { length: 80 }),
+    startedAt: doublePrecision("started_at"),
+    finishedAt: doublePrecision("finished_at"),
+    durationMs: integer("duration_ms"),
+    createdAt: doublePrecision("created_at").notNull(),
+    updatedAt: doublePrecision("updated_at").notNull(),
+    expiresAt: doublePrecision("expires_at").notNull(),
+  },
+  (table) => [
+    index("idx_agent_report_runs_created").on(table.createdAt),
+    index("idx_agent_report_runs_status").on(table.status, table.createdAt),
+    index("idx_agent_report_runs_operation").on(
+      table.operationKey,
+      table.createdAt,
+    ),
+    index("idx_agent_report_runs_actor").on(table.actorId, table.createdAt),
+    index("idx_agent_report_runs_department").on(
+      table.departmentId,
+      table.createdAt,
+    ),
+    index("idx_agent_report_runs_expiry").on(table.expiresAt),
+    check(
+      "ck_agent_report_runs_status",
+      sql`${table.status} in ('accepted', 'running', 'awaiting-approval', 'completed', 'failed', 'cancelled')`,
+    ),
+    check(
+      "ck_agent_report_runs_duration",
+      sql`${table.durationMs} is null or ${table.durationMs} >= 0`,
+    ),
+  ],
+);
+
+export const agentRuntimeReportAttempts = pgTable(
+  "agent_runtime_report_attempts",
+  {
+    attemptId: varchar("attempt_id", { length: 80 }).primaryKey(),
+    runId: varchar("run_id", { length: 80 })
+      .notNull()
+      .references(() => agentRuntimeReportRuns.runId, { onDelete: "cascade" }),
+    sequence: integer("sequence").notNull(),
+    toolRound: integer("tool_round").notNull(),
+    deploymentKey: varchar("deployment_key", { length: 200 }).notNull(),
+    requestedModel: varchar("requested_model", { length: 200 }).notNull(),
+    reportedModel: varchar("reported_model", { length: 200 }),
+    outcome: varchar("outcome", { length: 32 }).notNull(),
+    cacheStatus: varchar("cache_status", { length: 16 }).notNull(),
+    usageSource: varchar("usage_source", { length: 32 }).notNull(),
+    inputTokens: integer("input_tokens"),
+    outputTokens: integer("output_tokens"),
+    cachedInputTokens: integer("cached_input_tokens"),
+    reasoningTokens: integer("reasoning_tokens"),
+    totalTokens: integer("total_tokens"),
+    firstTokenLatencyMs: integer("first_token_latency_ms"),
+    durationMs: integer("duration_ms"),
+    safeErrorCode: varchar("safe_error_code", { length: 80 }),
+    startedAt: doublePrecision("started_at").notNull(),
+    finishedAt: doublePrecision("finished_at"),
+  },
+  (table) => [
+    uniqueIndex("uk_agent_report_attempts_sequence").on(
+      table.runId,
+      table.sequence,
+    ),
+    index("idx_agent_report_attempts_model").on(
+      table.deploymentKey,
+      table.requestedModel,
+      table.startedAt,
+    ),
+    index("idx_agent_report_attempts_outcome").on(
+      table.outcome,
+      table.startedAt,
+    ),
+    index("idx_agent_report_attempts_started").on(table.startedAt),
+    check("ck_agent_report_attempts_sequence", sql`${table.sequence} > 0`),
+    check("ck_agent_report_attempts_tool_round", sql`${table.toolRound} > 0`),
+    check(
+      "ck_agent_report_attempts_outcome",
+      sql`${table.outcome} in ('running', 'completed', 'failed', 'cancelled', 'blocked', 'abandoned')`,
+    ),
+    check(
+      "ck_agent_report_attempts_cache",
+      sql`${table.cacheStatus} in ('hit', 'miss', 'unknown')`,
+    ),
+    check(
+      "ck_agent_report_attempts_usage_source",
+      sql`${table.usageSource} in ('provider-reported', 'estimated', 'unknown')`,
+    ),
+    check(
+      "ck_agent_report_attempts_non_negative",
+      sql`coalesce(${table.inputTokens}, 0) >= 0
+        and coalesce(${table.outputTokens}, 0) >= 0
+        and coalesce(${table.cachedInputTokens}, 0) >= 0
+        and coalesce(${table.reasoningTokens}, 0) >= 0
+        and coalesce(${table.totalTokens}, 0) >= 0
+        and coalesce(${table.firstTokenLatencyMs}, 0) >= 0
+        and coalesce(${table.durationMs}, 0) >= 0`,
+    ),
+  ],
+);
+
 export const agentEvaluationResults = pgTable(
   "agent_evaluation_results",
   {
@@ -127,6 +238,9 @@ export const agentRunBindings = pgTable(
     actorId: varchar("actor_id", { length: 64 }).notNull(),
     idempotencyHash: varchar("idempotency_hash", { length: 64 }).notNull(),
     tokenHash: varchar("token_hash", { length: 64 }).notNull(),
+    inputDigestCommitment: varchar("input_digest_commitment", {
+      length: 64,
+    }).notNull(),
     scopeHash: varchar("scope_hash", { length: 64 }).notNull(),
     scopeSnapshot: jsonb("scope_snapshot")
       .$type<AuthorizationScopeSnapshot>()

package/template/packages/jobs/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@southwind-ai/jobs",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "license": "UNLICENSED",
   "type": "module",
   "engines": {

package/template/packages/modules/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@southwind-ai/modules",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "license": "UNLICENSED",
   "type": "module",
   "engines": {

package/template/packages/modules/src/system-admin-routes.ts

@@ -113,6 +113,16 @@ export const systemAdminRoutes: ModuleManifest["adminRoutes"] = [
     "system.audit",
   ),
   // @windy-module system.audit end
+  // @windy-module system.agent begin
+  route(
+    "system.ai-runtime",
+    "/admin/system/ai-runtime",
+    "AI Runtime 报表",
+    "sidebar",
+    "system.ai-runtime.read",
+    "system.ai-runtime",
+  ),
+  // @windy-module system.agent end
   // @windy-module system.operations begin
   route(
     "system.ops",

package/template/packages/modules/src/system-admin-ui-catalog.ts

@@ -30,7 +30,7 @@ const definitions = [
   ["system.storage", []],
   // @windy-module system.storage end
   // @windy-module system.agent begin
-  ["system.agent", []],
+  ["system.agent", ["system.ai-runtime"]],
   // @windy-module system.agent end
   // @windy-module system.operations begin
   ["system.operations", ["system.ops"]],

package/template/packages/modules/src/system-api-control-plane.ts

@@ -51,6 +51,22 @@ export function systemControlPlaneApiPermissionBindings(): ApiPermissionBinding[
 
 // @windy-module system.agent begin
 function aiRuntimeBindings(): ApiPermissionBinding[] {
+  const reports = (
+    [
+      ["/api/system/ai-runtime/summary", "agent.runtime.report.read"],
+      ["/api/system/ai-runtime/runs", "agent.runtime.report.read"],
+      ["/api/system/ai-runtime/runs/:runId", "agent.runtime.run.read"],
+      ["/api/system/ai-runtime/actors", "agent.runtime.report.read"],
+    ] as const
+  ).map(([path, auditAction]) =>
+    binding(
+      "GET",
+      path,
+      "system.ai-runtime.read",
+      "system.ai-runtime",
+      auditAction,
+    ),
+  );
   const read = [
     "/api/internal/ai/artifacts",
     "/api/document/runs/:runId/events",
@@ -90,7 +106,7 @@ function aiRuntimeBindings(): ApiPermissionBinding[] {
       path.startsWith("/api/internal/"),
     ),
   );
-  return [...read, ...execute];
+  return [...reports, ...read, ...execute];
 }
 // @windy-module system.agent end
 

package/template/packages/modules/src/system-audit-actions.ts

@@ -86,6 +86,16 @@ export const systemAuditActions: ModuleManifest["auditActions"] = [
   "agent.mcp.access",
   "agent.tool.execute",
   "agent.operation.execute",
+  {
+    key: "agent.runtime.report.read",
+    label: "读取 AI Runtime 报表",
+    description: "按当前数据范围读取 Agent Run 聚合、列表或 Actor 目录。",
+  },
+  {
+    key: "agent.runtime.run.read",
+    label: "读取 Agent Run 详情",
+    description: "按当前数据范围读取单个 Agent Run 与模型 Attempt 计量事实。",
+  },
   // @windy-module system.agent end
   "security.denied",
   "system.error",

package/template/packages/modules/src/system-features.ts

@@ -98,6 +98,14 @@ export const systemFeatures: ModuleManifest["features"] = [
     "Agent Tool",
     "让受控 Agent 在权限、Feature 与审计保护下调用平台工具。",
   ),
+  {
+    ...feature(
+      "system.ai-runtime",
+      "AI Runtime 报表",
+      "查看受数据范围约束的 Agent Run、模型用量、缓存与失败事实。",
+    ),
+    dependencies: [featureKey("system.agent")],
+  },
   // @windy-module system.agent end
   // @windy-module system.operations begin
   feature(

package/template/packages/modules/src/system-module-catalog.test.ts

@@ -125,6 +125,41 @@ describe("系统能力模块目录", () => {
     // @windy-module system.data-governance end
   });
 
+  // @windy-module system.agent begin
+  test("AI Runtime 能力与专用审计动作归属 system.agent", () => {
+    const agent = systemModuleManifests().find(
+      ({ name }) => name === "system.agent",
+    );
+    const core = systemModuleManifests().find(({ name }) => name === "system");
+    const auditKeys = (module: NonNullable<typeof agent>) =>
+      module.auditActions.map((action) =>
+        typeof action === "string" ? action : action.key,
+      );
+
+    expect(agent?.features.map(({ key }) => key)).toContain(
+      "system.ai-runtime",
+    );
+    expect(agent?.permissions.map(({ key }) => key)).toContain(
+      "system.ai-runtime.read",
+    );
+    expect(agent?.adminRoutes.map(({ key }) => key)).toContain(
+      "system.ai-runtime",
+    );
+    expect(auditKeys(agent!)).toEqual(
+      expect.arrayContaining([
+        "agent.runtime.report.read",
+        "agent.runtime.run.read",
+      ]),
+    );
+    expect(auditKeys(core!)).not.toEqual(
+      expect.arrayContaining([
+        "agent.runtime.report.read",
+        "agent.runtime.run.read",
+      ]),
+    );
+  });
+  // @windy-module system.agent end
+
   // @windy-module system.data-governance begin
   test("能力声明归属到对应模块而不是继续挂在 system 聚合项", () => {
     const workflow = governanceModuleManifest("system.workflow");

package/template/packages/modules/src/system-module-catalog.ts

@@ -127,8 +127,8 @@ export const systemModuleDefinitions = [
       "system.scheduler",
       "system.workflow",
     ],
-    resources: ["agent"],
-    featureKeys: ["system.agent"],
+    resources: ["agent", "ai-runtime"],
+    featureKeys: ["system.agent", "system.ai-runtime"],
   },
   // @windy-module system.agent end
   // @windy-module system.operations begin
@@ -293,14 +293,20 @@ function createSystemCapabilityModule(
         : [],
     auditActions: isCore
       ? aggregate.auditActions.filter(
-          (action) => auditActionKey(action) !== "system.user-directory.query",
+          (action) =>
+            auditActionKey(action) !== "system.user-directory.query" &&
+            !aiRuntimeAuditActions.has(auditActionKey(action)),
         )
       : definition.name === "system.identity"
         ? aggregate.auditActions.filter(
             (action) =>
               auditActionKey(action) === "system.user-directory.query",
           )
-        : [],
+        : definition.name === "system.agent"
+          ? aggregate.auditActions.filter((action) =>
+              aiRuntimeAuditActions.has(auditActionKey(action)),
+            )
+          : [],
     metadata: {
       kind: "platform-capability",
       ...(definition.runtimeActivation
@@ -310,6 +316,11 @@ function createSystemCapabilityModule(
   };
 }
 
+const aiRuntimeAuditActions = new Set([
+  "agent.runtime.report.read",
+  "agent.runtime.run.read",
+]);
+
 function auditActionKey(
   action: ModuleManifest["auditActions"][number],
 ): string {

package/template/packages/modules/src/system-modules-access.test.ts

@@ -60,5 +60,74 @@ describe("系统模块管理面与 MCP 注册", () => {
       },
     ]);
   });
+
+  test("AI Runtime 报表完整注册 Feature、权限、入口、API 与审计", () => {
+    const manifest = systemFoundationModule();
+    const menus = manifest.menus.flatMap((menu) => menu.children ?? []);
+
+    expect(
+      manifest.features.find(({ key }) => key === "system.ai-runtime"),
+    ).toEqual(
+      expect.objectContaining({
+        dependencies: ["system.agent"],
+      }),
+    );
+    expect(
+      manifest.permissions.find(({ key }) => key === "system.ai-runtime.read"),
+    ).toEqual(
+      expect.objectContaining({
+        resource: "ai-runtime",
+        action: "read",
+        accessRisk: "sensitive-disclosure",
+      }),
+    );
+    expect(
+      manifest.adminRoutes.find(({ key }) => key === "system.ai-runtime"),
+    ).toMatchObject({
+      path: "/admin/system/ai-runtime",
+      permissionKey: "system.ai-runtime.read",
+      featureKey: "system.ai-runtime",
+    });
+    expect(menus.find(({ key }) => key === "system.ai-runtime")).toMatchObject({
+      path: "/admin/system/ai-runtime",
+      permissionKey: "system.ai-runtime.read",
+      featureKey: "system.ai-runtime",
+    });
+
+    const bindings = manifest.apiPermissions.filter(({ path }) =>
+      path.startsWith("/api/system/ai-runtime"),
+    );
+    expect(bindings).toHaveLength(4);
+    expect(
+      bindings.every(
+        ({ method, permissionKey, featureKey }) =>
+          method === "GET" &&
+          permissionKey === "system.ai-runtime.read" &&
+          featureKey === "system.ai-runtime",
+      ),
+    ).toBe(true);
+    expect(bindings).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          path: "/api/system/ai-runtime/runs/:runId",
+          auditAction: "agent.runtime.run.read",
+        }),
+        expect.objectContaining({
+          path: "/api/system/ai-runtime/summary",
+          auditAction: "agent.runtime.report.read",
+        }),
+      ]),
+    );
+    expect(
+      manifest.auditActions.map((action) =>
+        typeof action === "string" ? action : action.key,
+      ),
+    ).toEqual(
+      expect.arrayContaining([
+        "agent.runtime.report.read",
+        "agent.runtime.run.read",
+      ]),
+    );
+  });
   // @windy-module system.agent end
 });

package/template/packages/modules/src/system-modules.ts

@@ -228,6 +228,19 @@ export function systemFoundationModule(): ModuleManifest {
             featureKey: "system.ops",
           },
           // @windy-module system.operations end
+          // @windy-module system.agent begin
+          {
+            key: "system.ai-runtime",
+            title: "AI Runtime 报表",
+            type: "menu",
+            order: 15,
+            visible: true,
+            path: "/admin/system/ai-runtime",
+            icon: "activity",
+            permissionKey: "system.ai-runtime.read",
+            featureKey: "system.ai-runtime",
+          },
+          // @windy-module system.agent end
           // @windy-module system.workflow begin
           {
             key: "system.workflow",

package/template/packages/modules/src/system-permissions.ts

@@ -19,6 +19,7 @@ const systemResourceLabels = {
   license: "许可证管理",
   audit: "审计日志",
   agent: "智能代理",
+  "ai-runtime": "AI Runtime 报表",
   ops: "运维总览",
   scheduler: "定时任务",
   notification: "通知管理",
@@ -122,6 +123,7 @@ export const systemPermissions: ModuleManifest["permissions"] = [
   // @windy-module system.audit end
   // @windy-module system.agent begin
   permission("agent", "read"),
+  permission("ai-runtime", "read", "sensitive-disclosure"),
   // @windy-module system.agent end
   // @windy-module system.operations begin
   permission("ops", "read"),

package/template/packages/server-sdk/index.ts

@@ -17,6 +17,17 @@ export type {
   ModuleBackgroundAiPort,
 } from "./src/background-ai-port.js";
 export { ModuleBackgroundAiError } from "./src/background-ai-port.js";
+export type {
+  ModuleDebugSessionContextV1,
+  ModuleDebugSessionGetInputV1,
+  ModuleDebugSessionListInputV1,
+  ModuleDebugSessionMessageV1,
+  ModuleDebugSessionPageV1,
+  ModuleDebugSessionProviderV1,
+  ModuleDebugSessionSummaryV1,
+  ModuleDebugSessionV1,
+} from "./src/debug-session-provider.js";
+export { MODULE_DEBUG_SESSION_SCHEMA_VERSION } from "./src/debug-session-provider.js";
 export type {
   ModuleAuditEmitter,
   ModuleAuditEmitInput,

package/template/packages/server-sdk/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@southwind-ai/server-sdk",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "license": "UNLICENSED",
   "type": "module",
   "engines": {
@@ -15,6 +15,7 @@
     "src/audit-port.ts",
     "src/background-ai-port.ts",
     "src/data-governance-registration.ts",
+    "src/debug-session-provider.ts",
     "src/durable-handler.ts",
     "src/jobs-port.ts",
     "src/module-host.ts",

package/template/packages/server-sdk/src/ai-operation-port.ts

@@ -18,6 +18,11 @@ export interface ModuleAiOperationPort {
     artifacts?: readonly ModuleAiArtifactRef[];
     idempotencyKey: string;
   }): Promise<ModuleAiRunReceipt>;
+  verifyAgentRun(input: {
+    operationKey: string;
+    runId: string;
+    input: ModuleAiJsonValue;
+  }): Promise<void>;
   startDocument(input: {
     operationKey: string;
     sources: readonly ModuleAiArtifactRef[];

package/template/packages/server-sdk/src/debug-session-provider.ts

@@ -0,0 +1,63 @@
+import type { ModuleActor } from "./actor.js";
+
+export const MODULE_DEBUG_SESSION_SCHEMA_VERSION = 1 as const;
+
+export interface ModuleDebugSessionContextV1 {
+  readonly actor: ModuleActor;
+  readonly operationKey: string;
+  readonly signal: AbortSignal;
+}
+
+export interface ModuleDebugSessionListInputV1 extends ModuleDebugSessionContextV1 {
+  readonly limit: number;
+  /** Provider 私有的不透明 keyset cursor；Host 只原样回传给同一 Provider。 */
+  readonly cursor?: string;
+}
+
+export interface ModuleDebugSessionGetInputV1 extends ModuleDebugSessionContextV1 {
+  readonly sourceId: string;
+}
+
+export interface ModuleDebugSessionSummaryV1 {
+  /** 仅在 Provider 与 Host 之间使用，不会返回给 ADK Web。 */
+  readonly sourceId: string;
+  readonly title: string;
+  readonly scopeLabel?: string;
+  readonly updatedAt: string;
+  readonly revision: string;
+}
+
+export interface ModuleDebugSessionPageV1 {
+  readonly sessions: readonly ModuleDebugSessionSummaryV1[];
+  readonly truncated: boolean;
+  /** truncated=true 时必须提供，用于 Host 继续读取直到完整。 */
+  readonly next?: string;
+}
+
+export interface ModuleDebugSessionMessageV1 {
+  readonly sequence: number;
+  readonly role: "user" | "assistant";
+  readonly content: string;
+  readonly createdAt: string;
+}
+
+export interface ModuleDebugSessionV1 extends ModuleDebugSessionSummaryV1 {
+  readonly messages: readonly ModuleDebugSessionMessageV1[];
+}
+
+/**
+ * 开发期 ADK Web 会话投影。Provider 只读业务事实，Host 负责重新授权、审计、
+ * 有界校验与不透明 ID；V1 不支持业务会话的追加、重命名或删除。
+ */
+export interface ModuleDebugSessionProviderV1 {
+  readonly schemaVersion: typeof MODULE_DEBUG_SESSION_SCHEMA_VERSION;
+  readonly key: string;
+  readonly operationKeys: readonly string[];
+  readonly featureKey: string;
+  readonly permissionKey: string;
+  readonly auditAction: string;
+  list(input: ModuleDebugSessionListInputV1): Promise<ModuleDebugSessionPageV1>;
+  get(
+    input: ModuleDebugSessionGetInputV1,
+  ): Promise<ModuleDebugSessionV1 | undefined>;
+}