create-windy 0.6.12 → 0.6.14

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

@@ -86,6 +86,72 @@ export const systemAuditActions: ModuleManifest["auditActions"] = [
   "agent.mcp.access",
   "agent.tool.execute",
   "agent.operation.execute",
+  {
+    key: "agent.session.read",
+    label: "读取 Agent 长期会话",
+    description: "按当前授权读取 Session、Context 与 Memory 的只读投影。",
+  },
+  {
+    key: "agent.session.create",
+    label: "创建 Agent 长期会话",
+    description: "创建绑定当前 Actor 与数据范围的长期 Session。",
+  },
+  {
+    key: "agent.session.checkpoint",
+    label: "创建 Agent Session Checkpoint",
+    description: "在追加事实序列上创建可验证的恢复锚点。",
+  },
+  {
+    key: "agent.session.replay",
+    label: "回放 Agent Session",
+    description: "只读回放指定 Checkpoint，不重新执行写 Tool。",
+  },
+  {
+    key: "agent.session.fork",
+    label: "分支 Agent Session",
+    description: "从授权 Checkpoint 派生具有显式血缘的新 Session。",
+  },
+  {
+    key: "agent.session.archive",
+    label: "归档 Agent Session",
+    description: "归档长期 Session 并停止新增事实。",
+  },
+  {
+    key: "agent.context-version.create",
+    label: "记录 Agent Context Version",
+    description: "在模型调用前记录实际使用的受治理 Context 来源版本。",
+  },
+  {
+    key: "agent.memory.delete",
+    label: "删除 Agent Memory",
+    description: "删除当前 Actor 有权管理的记忆投影并传播失效。",
+  },
+  {
+    key: "agent.client-session.create",
+    label: "创建 Client Agent Session",
+    description:
+      "创建绑定 Actor、Operation、输入承诺与宿主 binding 的受治理会话。",
+  },
+  {
+    key: "agent.client-session.provider-attempt",
+    label: "执行 Client Agent Provider Attempt",
+    description: "记录受控模型调用的摘要、用量与策略结果。",
+  },
+  {
+    key: "agent.client-session.finalize",
+    label: "完成 Client Agent Session",
+    description: "以本 Run 的终末 receipt 链封存公开结果。",
+  },
+  {
+    key: "agent.client-session.cancel",
+    label: "取消 Client Agent Session",
+    description: "取消会话并阻止迟到 Provider 响应产生新状态。",
+  },
+  {
+    key: "agent.client-session.revoke",
+    label: "撤销 Client Agent Session",
+    description: "因宿主绑定或授权漂移即时撤销会话。",
+  },
   {
     key: "agent.runtime.report.read",
     label: "读取 AI Runtime 报表",
@@ -96,6 +162,53 @@ export const systemAuditActions: ModuleManifest["auditActions"] = [
     label: "读取 Agent Run 详情",
     description: "按当前数据范围读取单个 Agent Run 与模型 Attempt 计量事实。",
   },
+  {
+    key: "agent.workflow.release.publish",
+    label: "发布 Agent Workflow Release",
+    description: "发布由 Definition 与执行坐标共同摘要的不可变 Release。",
+  },
+  {
+    key: "agent.workflow.readiness.read",
+    label: "读取 Agent Workflow 就绪状态",
+    description: "读取冻结模型与价格目录等 Workflow 生产依赖的可用状态。",
+  },
+  {
+    key: "agent.workflow.run.read",
+    label: "读取 Agent Workflow Run",
+    description:
+      "在对象授权与数据范围内读取 Run、Node Run 与 canonical Event。",
+  },
+  {
+    key: "agent.workflow.run.create",
+    label: "创建 Agent Workflow Run",
+    description: "按冻结授权、工具、Workspace、执行策略与预算创建 Run。",
+  },
+  {
+    key: "agent.workflow.run.cancel",
+    label: "取消 Agent Workflow Run",
+    description: "请求取消 Run，并阻止未提交的后续 Node 与副作用。",
+  },
+  {
+    key: "agent.workflow.run.recover",
+    label: "恢复 Agent Workflow Run",
+    description: "重新校验当前授权并协调持久副作用 receipt 后恢复 Run。",
+  },
+  {
+    key: "agent.workflow.run.signal",
+    label: "恢复 Agent Workflow Wait Node",
+    description:
+      "按 Run 对象授权、Scope、Deadline 与幂等坐标提交受治理 Signal。",
+  },
+  {
+    key: "agent.workflow.evaluation.record",
+    label: "记录 Agent Workflow 评测",
+    description: "按单 Agent 与多 Agent 两臂独立证据记录真实评测事实。",
+  },
+  {
+    key: "agent.workflow.artifact.resolve",
+    label: "解析 Agent Workflow 产物",
+    description: "在对象授权与数据范围内解析 Workflow 产物引用。",
+  },
   // @windy-module system.agent end
   "security.denied",
   "system.error",

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

@@ -103,6 +103,14 @@ export const systemFeatures: ModuleManifest["features"] = [
     "Agent Tool",
     "让受控 Agent 在权限、Feature 与审计保护下调用平台工具。",
   ),
+  {
+    ...feature(
+      "system.agent-session",
+      "Agent 长期会话",
+      "恢复受治理的长期 Session，并解释 Context 与 Memory 来源。",
+    ),
+    dependencies: [featureKey("system.agent")],
+  },
   {
     ...feature(
       "system.ai-runtime",
@@ -111,6 +119,15 @@ export const systemFeatures: ModuleManifest["features"] = [
     ),
     dependencies: [featureKey("system.agent")],
   },
+  {
+    ...feature(
+      "system.agent-workflow",
+      "Agent Workflow",
+      "查看和运行具备预算、恢复、委派与持久审计边界的不可变 Agent Workflow Release。",
+    ),
+    dependencies: [featureKey("system.agent")],
+    allowedLicenseVersions: advancedOnly,
+  },
   // @windy-module system.agent end
   // @windy-module system.operations begin
   feature(

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

@@ -2,6 +2,16 @@ import type { ModuleFactory, ModuleManifest } from "./manifest.js";
 import { selectSystemMenus } from "./system-module-menu-selection.js";
 import { systemFoundationModule } from "./system-modules.js";
 import { selectSystemJsonSchemas } from "./system-module-schema-catalog.js";
+// @windy-module system.agent begin
+import { agentAuditActionKeys } from "./system-agent-audit-actions.js";
+// @windy-module system.agent end
+
+const catalogAgentModuleNames = new Set<string>();
+const catalogAgentAuditActionKeys = new Set<string>();
+// @windy-module system.agent begin
+catalogAgentModuleNames.add("system.agent");
+for (const key of agentAuditActionKeys) catalogAgentAuditActionKeys.add(key);
+// @windy-module system.agent end
 
 export interface SystemModuleDefinition {
   name: string;
@@ -119,7 +129,7 @@ export const systemModuleDefinitions = [
   // @windy-module system.agent begin
   {
     name: "system.agent",
-    version: "0.1.1",
+    version: "0.1.2",
     label: "Agent Tool",
     description: "受 Feature、RBAC 和审计保护的 Agent 工具调用。",
     dependencies: [
@@ -129,8 +139,13 @@ export const systemModuleDefinitions = [
       "system.scheduler",
       "system.workflow",
     ],
-    resources: ["agent", "ai-runtime"],
-    featureKeys: ["system.agent", "system.ai-runtime"],
+    resources: ["agent", "agent-session", "agent-workflow", "ai-runtime"],
+    featureKeys: [
+      "system.agent",
+      "system.agent-session",
+      "system.agent-workflow",
+      "system.ai-runtime",
+    ],
   },
   // @windy-module system.agent end
   // @windy-module system.operations begin
@@ -300,16 +315,16 @@ function createSystemCapabilityModule(
       ? aggregate.auditActions.filter(
           (action) =>
             auditActionKey(action) !== "system.user-directory.query" &&
-            !aiRuntimeAuditActions.has(auditActionKey(action)),
+            !catalogAgentAuditActionKeys.has(auditActionKey(action)),
         )
       : definition.name === "system.identity"
         ? aggregate.auditActions.filter(
             (action) =>
               auditActionKey(action) === "system.user-directory.query",
           )
-        : definition.name === "system.agent"
+        : catalogAgentModuleNames.has(definition.name)
           ? aggregate.auditActions.filter((action) =>
-              aiRuntimeAuditActions.has(auditActionKey(action)),
+              catalogAgentAuditActionKeys.has(auditActionKey(action)),
             )
           : [],
     metadata: {
@@ -321,11 +336,6 @@ 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.ts

@@ -241,6 +241,17 @@ export function systemFoundationModule(): ModuleManifest {
           },
           // @windy-module system.operations end
           // @windy-module system.agent begin
+          {
+            key: "system.agent-session",
+            title: "Agent 会话",
+            type: "menu",
+            order: 14,
+            visible: true,
+            path: "/admin/system/agent-sessions",
+            icon: "messages-square",
+            permissionKey: "system.agent-session.read",
+            featureKey: "system.agent-session",
+          },
           {
             key: "system.ai-runtime",
             title: "AI Runtime 报表",
@@ -252,6 +263,17 @@ export function systemFoundationModule(): ModuleManifest {
             permissionKey: "system.ai-runtime.read",
             featureKey: "system.ai-runtime",
           },
+          {
+            key: "system.agent-workflow",
+            title: "Agent Workflow",
+            type: "menu",
+            order: 16,
+            visible: true,
+            path: "/admin/system/agent-workflows",
+            icon: "git-fork",
+            permissionKey: "system.agent-workflow.read",
+            featureKey: "system.agent-workflow",
+          },
           // @windy-module system.agent end
           // @windy-module system.workflow begin
           {

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

@@ -19,8 +19,12 @@ const systemResourceLabels = {
   profile: "个人设置",
   license: "许可证管理",
   audit: "审计日志",
+  // @windy-module system.agent begin
   agent: "智能代理",
+  "agent-session": "Agent 长期会话",
+  "agent-workflow": "Agent Workflow",
   "ai-runtime": "AI Runtime 报表",
+  // @windy-module system.agent end
   ops: "运维总览",
   scheduler: "定时任务",
   notification: "通知管理",
@@ -125,6 +129,10 @@ export const systemPermissions: ModuleManifest["permissions"] = [
   // @windy-module system.audit end
   // @windy-module system.agent begin
   permission("agent", "read"),
+  permission("agent-session", "read"),
+  permission("agent-session", "manage"),
+  permission("agent-workflow", "read", "sensitive-disclosure"),
+  permission("agent-workflow", "manage"),
   permission("ai-runtime", "read", "sensitive-disclosure"),
   // @windy-module system.agent end
   // @windy-module system.operations begin

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

@@ -1,4 +1,15 @@
 export type { ModuleActor } from "./src/actor.js";
+export { pageAgentClientRunCapability } from "./src/client-agent-session.js";
+export type {
+  ModuleClientAgentHostAuthAdapter,
+  ModuleClientAgentHostPrincipal,
+  ModuleClientAgentSessionCreateInput,
+  ModuleClientAgentSessionGrant,
+  ModuleClientAgentSessionPort,
+  ModuleClientAgentSessionReceipt,
+  ModuleClientAgentSessionStatus,
+  ModuleClientAgentSessionView,
+} from "./src/client-agent-session.js";
 export type {
   ModuleAiArtifactPort,
   ModuleAiArtifactRef,
@@ -66,6 +77,18 @@ export type {
   ModuleBackgroundAiPort,
 } from "./src/background-ai-port.js";
 export { ModuleBackgroundAiError } from "./src/background-ai-port.js";
+export type {
+  ModuleAgentSessionContextV1,
+  ModuleAgentSessionGetInputV1,
+  ModuleAgentSessionListInputV1,
+  ModuleAgentSessionMessageV1,
+  ModuleAgentSessionPageV1,
+  ModuleAgentSessionProviderV1,
+  ModuleAgentSessionSummaryV1,
+  ModuleAgentSessionV1,
+} from "./src/agent-session-provider.js";
+export { MODULE_AGENT_SESSION_SCHEMA_VERSION } from "./src/agent-session-provider.js";
+/** @deprecated 请改用 ModuleAgentSession* 类型。 */
 export type {
   ModuleDebugSessionContextV1,
   ModuleDebugSessionGetInputV1,
@@ -76,6 +99,7 @@ export type {
   ModuleDebugSessionSummaryV1,
   ModuleDebugSessionV1,
 } from "./src/debug-session-provider.js";
+/** @deprecated 请改用 MODULE_AGENT_SESSION_SCHEMA_VERSION。 */
 export { MODULE_DEBUG_SESSION_SCHEMA_VERSION } from "./src/debug-session-provider.js";
 export type {
   ModuleAuditEmitter,
@@ -153,6 +177,23 @@ export {
 } from "./src/module-adapter.js";
 export { requireModuleNamespace } from "./src/namespace.js";
 export type { ModuleRequestContext } from "./src/request-context.js";
+export {
+  MODULE_AGENT_SESSION_MEMORY_SCHEMA_VERSION,
+  ModuleAgentSessionMemoryError,
+  requireModuleAgentSessionMemoryPort,
+  type ModuleAgentSessionMemoryPortV1,
+  type ModuleSessionMemoryReceiptV1,
+  type ModuleSessionMemorySourceV1,
+} from "./src/agent-session-memory-port.js";
+export {
+  ModuleAuthoritativeSourceInvalidationUnavailableError,
+  requireModuleAuthoritativeSourceInvalidationPort,
+  type ModuleAuthoritativeSourceCoordinateV1,
+  type ModuleAuthoritativeSourceEventV1,
+  type ModuleAuthoritativeSourceInvalidationPortV1,
+  type ModuleAuthoritativeSourceInvalidationV1,
+  type ModuleSourceInvalidationAppendResultV1,
+} from "./src/agent-source-invalidation-port.js";
 export type {
   ModuleAiScreenshotIntakePortV1,
   ModuleAiScreenshotIntakeCreateV2,
@@ -246,8 +287,10 @@ export type {
   ModuleDocumentOperationPlan,
   ModuleSpeechOperationPlan,
 } from "./src/ai-operation-registration.js";
+// @windy-module system.agent begin
 export {
   defineSystemAgentSupervisorHandler,
   type SystemAgentSupervisorBusinessRelease,
   type SystemAgentSupervisorHandlerOptions,
 } from "./src/system-agent-supervisor.js";
+// @windy-module system.agent end

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

@@ -1,6 +1,6 @@
 {
   "name": "@southwind-ai/server-sdk",
-  "version": "0.4.2",
+  "version": "0.4.4",
   "license": "UNLICENSED",
   "type": "module",
   "engines": {
@@ -26,8 +26,12 @@
     "src/ai-runtime-readiness-validation.ts",
     "src/ai-runtime-readiness-validation-values.ts",
     "src/ai-runtime-readiness-values.ts",
+    "src/agent-session-memory-port.ts",
+    "src/agent-session-provider.ts",
+    "src/agent-source-invalidation-port.ts",
     "src/audit-port.ts",
     "src/background-ai-port.ts",
+    "src/client-agent-session.ts",
     "src/data-governance-registration.ts",
     "src/debug-session-provider.ts",
     "src/durable-handler.ts",

package/template/packages/server-sdk/src/agent-session-memory-port.ts

@@ -0,0 +1,64 @@
+export const MODULE_AGENT_SESSION_MEMORY_SCHEMA_VERSION = 1 as const;
+
+export interface ModuleSessionMemorySourceV1 {
+  readonly kind: string;
+  readonly id: string;
+  readonly version: string;
+  readonly sequence: number;
+  readonly digest: string;
+  readonly checkedAt: string;
+  readonly expiresAt?: string;
+}
+
+interface ModuleSessionMemoryBaseV1 {
+  readonly triggerId: string;
+  readonly sessionId: string;
+  readonly throughSequence: number;
+  readonly sources: readonly ModuleSessionMemorySourceV1[];
+  readonly expiresAt?: string;
+}
+
+export interface ModuleSessionMemoryReceiptV1 {
+  readonly memoryId: string;
+  readonly version: string;
+  readonly digest: string;
+}
+
+/** Current-request-bound trigger seam; the Host supplies Actor, Scope and moduleKey. */
+export interface ModuleAgentSessionMemoryPortV1 {
+  readonly schemaVersion: typeof MODULE_AGENT_SESSION_MEMORY_SCHEMA_VERSION;
+  rememberUserPreference(input: ModuleSessionMemoryBaseV1 & {
+    readonly preferenceKey: string;
+    readonly value: string;
+  }): Promise<ModuleSessionMemoryReceiptV1>;
+  proposeCaseMemory(input: ModuleSessionMemoryBaseV1 & {
+    readonly caseId: string;
+    readonly claim: string;
+    readonly confidence?: number;
+  }): Promise<ModuleSessionMemoryReceiptV1>;
+  referenceVerifiedFact(input: ModuleSessionMemoryBaseV1 & {
+    readonly caseId: string;
+    readonly fact: {
+      readonly resourceType: string;
+      readonly resourceId: string;
+      readonly version: string;
+      readonly digest: string;
+    };
+  }): Promise<ModuleSessionMemoryReceiptV1>;
+}
+
+export class ModuleAgentSessionMemoryError extends Error {
+  readonly code = "AGENT_SESSION_MEMORY_UNAVAILABLE" as const;
+
+  constructor() {
+    super("长期 Session Memory 暂不可用");
+    this.name = "ModuleAgentSessionMemoryError";
+  }
+}
+
+export function requireModuleAgentSessionMemoryPort(
+  port: ModuleAgentSessionMemoryPortV1 | undefined,
+): ModuleAgentSessionMemoryPortV1 {
+  if (!port) throw new ModuleAgentSessionMemoryError();
+  return port;
+}

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

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

package/template/packages/server-sdk/src/agent-source-invalidation-port.ts

@@ -0,0 +1,54 @@
+export interface ModuleAuthoritativeSourceCoordinateV1 {
+  readonly sourceKind: string;
+  readonly sourceId: string;
+  readonly version: string;
+  readonly sequence: number;
+  readonly digest?: string;
+}
+
+export interface ModuleAuthoritativeSourceEventV1 {
+  readonly eventId: string;
+  readonly eventSequence: number;
+  readonly occurredAt: string;
+}
+
+export interface ModuleAuthoritativeSourceInvalidationV1 {
+  readonly source: ModuleAuthoritativeSourceCoordinateV1;
+  readonly event: ModuleAuthoritativeSourceEventV1;
+}
+
+export type ModuleSourceInvalidationAppendResultV1 =
+  | "appended"
+  | "duplicate"
+  | "stale";
+
+/**
+ * Host binds module, Actor, Scope, and the module's current business transaction.
+ * Calls outside that authoritative transaction fail closed.
+ */
+export interface ModuleAuthoritativeSourceInvalidationPortV1 {
+  sourceDeleted(input: ModuleAuthoritativeSourceInvalidationV1):
+    Promise<ModuleSourceInvalidationAppendResultV1>;
+  sourceExpired(input: ModuleAuthoritativeSourceInvalidationV1):
+    Promise<ModuleSourceInvalidationAppendResultV1>;
+  sourceSuperseded(input: ModuleAuthoritativeSourceInvalidationV1):
+    Promise<ModuleSourceInvalidationAppendResultV1>;
+  authorizationRevoked(input: ModuleAuthoritativeSourceInvalidationV1):
+    Promise<ModuleSourceInvalidationAppendResultV1>;
+}
+
+export class ModuleAuthoritativeSourceInvalidationUnavailableError extends Error {
+  readonly code = "SOURCE_INVALIDATION_UNAVAILABLE" as const;
+
+  constructor() {
+    super("权威来源失效写入暂不可用");
+    this.name = "ModuleAuthoritativeSourceInvalidationUnavailableError";
+  }
+}
+
+export function requireModuleAuthoritativeSourceInvalidationPort(
+  port: ModuleAuthoritativeSourceInvalidationPortV1 | undefined,
+) {
+  if (!port) throw new ModuleAuthoritativeSourceInvalidationUnavailableError();
+  return port;
+}

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

@@ -16,6 +16,8 @@ export interface ModuleAiOperationContext {
 export interface ModuleAiOperationPlan {
   readonly instructions: string;
   readonly userPrompt: string;
+  /** Host forwards this trusted business coordinate only for governed Case Memory lookup. */
+  readonly memoryScope?: { readonly caseId: string };
   /**
    * 可选 JSON Schema。宿主只把它交给受控 Runtime，并以 Manifest outputSchemaKey
    * 关联审计；业务不能在此选择模型、Provider 或 Endpoint。

package/template/packages/server-sdk/src/client-agent-session.ts

@@ -0,0 +1,95 @@
+import type { ModuleAiJsonValue } from "./ai-operation-registration.js";
+
+export const pageAgentClientRunCapability = "pageAgentClientRun" as const;
+
+export interface ModuleClientAgentHostPrincipal {
+  readonly actorId: string;
+  readonly installationId: string;
+  readonly sessionId: string;
+}
+
+export interface ModuleClientAgentHostAuthAdapter {
+  ready(signal?: AbortSignal): Promise<boolean>;
+  authenticate(input: {
+    readonly token: string;
+    readonly purpose: "control" | "completion";
+    readonly signal?: AbortSignal;
+  }): Promise<ModuleClientAgentHostPrincipal | undefined>;
+  bindRevocations(
+    revoke: (principal: ModuleClientAgentHostPrincipal) => Promise<void>,
+  ): () => void;
+}
+
+export type ModuleClientAgentSessionStatus =
+  | "active"
+  | "completed"
+  | "cancelled"
+  | "revoked"
+  | "expired";
+
+export interface ModuleClientAgentSessionCreateInput {
+  readonly operationKey: string;
+  readonly input: ModuleAiJsonValue;
+  readonly clientBindingDigest: `sha256:${string}`;
+}
+
+export interface ModuleClientAgentSessionGrant {
+  readonly clientRunId: string;
+  readonly sessionId: string;
+  readonly trustedBaseUrl: string;
+  readonly modelAlias: string;
+  readonly limits: {
+    readonly maxSteps: number;
+    readonly maxRequestBytes: number;
+    readonly maxResponseBytes: number;
+    readonly maxDurationSeconds: number;
+    readonly maxConcurrentRequests: number;
+  };
+  readonly expiresAt: string;
+  readonly accessToken: string;
+  readonly capabilities: readonly [typeof pageAgentClientRunCapability];
+}
+
+export interface ModuleClientAgentSessionReceipt {
+  readonly receiptId: string;
+  readonly attempt: number;
+  readonly requestDigest: `sha256:${string}`;
+  readonly responseDigest: `sha256:${string}`;
+  readonly deploymentDigest: `sha256:${string}`;
+  readonly issuedAt: string;
+}
+
+export interface ModuleClientAgentSessionView {
+  readonly clientRunId: string;
+  readonly sessionId: string;
+  readonly operationKey: string;
+  readonly status: ModuleClientAgentSessionStatus;
+  readonly attemptCount: number;
+  readonly expiresAt: string;
+  readonly result?: ModuleAiJsonValue;
+}
+
+/**
+ * 宿主 Adapter 使用的通用 Client Agent Session port。
+ *
+ * 实现必须把调用绑定到当前 ModuleRequestContext，不接受调用方声明 Actor、权限或 Scope。
+ */
+export interface ModuleClientAgentSessionPort {
+  capabilities(): Promise<{
+    readonly capabilities: readonly [typeof pageAgentClientRunCapability];
+    readonly modelAlias: string;
+  }>;
+  create(
+    input: ModuleClientAgentSessionCreateInput,
+  ): Promise<ModuleClientAgentSessionGrant>;
+  status(sessionId: string): Promise<ModuleClientAgentSessionView>;
+  cancel(
+    sessionId: string,
+    reason?: string,
+  ): Promise<ModuleClientAgentSessionView>;
+  finalize(
+    sessionId: string,
+    receiptIds: readonly string[],
+    result?: ModuleAiJsonValue,
+  ): Promise<ModuleClientAgentSessionView>;
+}