create-windy 0.6.12 → 0.6.15

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

@@ -1,5 +1,8 @@
 import type { ApiPermissionBinding } from "@southwind-ai/shared";
 import { binding } from "./system-api-binding.js";
+// @windy-module system.agent begin
+import { systemAiControlPlaneBindings } from "./system-ai-api-bindings.js";
+// @windy-module system.agent end
 
 /**
  * 不走资源 CRUD 的平台入口仍必须进入 Manifest。
@@ -12,7 +15,7 @@ export function systemControlPlaneApiPermissionBindings(): ApiPermissionBinding[
     ...runtimeBindings(),
     ...sessionBindings(),
     // @windy-module system.agent begin
-    ...aiRuntimeBindings(),
+    ...systemAiControlPlaneBindings(),
     // @windy-module system.agent end
     // @windy-module system.license begin
     binding(
@@ -86,83 +89,6 @@ 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",
-    "/api/document/runs/:runId/result",
-    "/api/speech/runs/:runId/events",
-    "/api/speech/runs/:runId/result",
-    "/api/speech/runs/:runId/artifact",
-    "/api/embeddings/runs/:runId/events",
-    "/api/embeddings/runs/:runId/result",
-    "/api/internal/embeddings/runs/:runId/artifacts/:itemId",
-    "/api/agent/runs/:runId/events",
-    "/api/agent/runs/:runId/result",
-  ].map((path) =>
-    binding(
-      "GET",
-      path,
-      "system.agent.read",
-      "system.agent",
-      "data.read",
-      path.startsWith("/api/internal/"),
-    ),
-  );
-  const execute = [
-    "/api/document/runs",
-    "/api/document/runs/:runId/cancel",
-    "/api/speech/runs",
-    "/api/speech/runs/:runId/cancel",
-    "/api/embeddings",
-    "/api/embeddings/runs",
-    "/api/embeddings/runs/:runId/cancel",
-    "/api/agent/runs",
-    "/api/agent/runs/:runId/cancel",
-    "/api/agent/runs/:runId/attach",
-    "/api/agent/screenshots",
-    "/api/agent/screenshots/:token/cancel",
-    "/api/internal/agent/tools/execute",
-  ].map((path) =>
-    binding(
-      "POST",
-      path,
-      "system.agent.read",
-      "system.agent",
-      "agent.operation.execute",
-      path.startsWith("/api/internal/"),
-    ),
-  );
-  const uploads = ["/api/agent/screenshots/:token"].map((path) =>
-    binding(
-      "PUT",
-      path,
-      "system.agent.read",
-      "system.agent",
-      "agent.operation.execute",
-    ),
-  );
-  return [...reports, ...read, ...execute, ...uploads];
-}
-// @windy-module system.agent end
-
 function runtimeBindings(): ApiPermissionBinding[] {
   return ["/api/live", "/api/ready", "/api/health", "/api/metrics"].map(
     (path) =>

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,68 @@ 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 产物引用。",
+  },
+  {
+    key: "agent.workflow.client-artifact.claim",
+    label: "领取 Client Agent Workflow 任务",
+    description: "按当前宿主身份领取已持久化且受 fence 约束的浏览器任务。",
+  },
+  {
+    key: "agent.workflow.client-artifact.advance",
+    label: "推进 Client Agent Workflow 任务",
+    description: "校验完整 Provider receipt 链并封存 Durable Artifact。",
+  },
+  {
+    key: "agent.workflow.client-artifact.cancel",
+    label: "取消 Client Agent Workflow 任务",
+    description: "取消当前领取代次并拒绝迟到结果写入。",
+  },
   // @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,40 @@
 export type { ModuleActor } from "./src/actor.js";
+export { pageAgentClientRunCapability } from "./src/client-agent-session.js";
+export type {
+  ModuleClientAgentHostAuthAdapter,
+  ModuleClientAgentHostAuthPurpose,
+  ModuleClientAgentHostPrincipal,
+  ModuleClientAgentSessionCreateInput,
+  ModuleClientAgentSessionGrant,
+  ModuleClientAgentSessionPort,
+  ModuleClientAgentSessionReceipt,
+  ModuleClientAgentSessionStatus,
+  ModuleClientAgentSessionView,
+} from "./src/client-agent-session.js";
+// @windy-module system.agent begin
+export {
+  CLIENT_AGENT_WORKFLOW_ARTIFACT_BINDING_LIMITS,
+  CLIENT_AGENT_WORKFLOW_ARTIFACT_TASK_KEY,
+  CLIENT_AGENT_WORKFLOW_ARTIFACT_WORK_ID_PREFIX,
+  CLIENT_AGENT_WORKFLOW_SCOPE_CONTAINMENT_CONTRACT_VERSION,
+} from "./src/client-agent-workflow-artifact.js";
+export type {
+  ModuleClientAgentWorkflowArtifactBeginSpec,
+  ModuleClientAgentWorkflowArtifactCommand,
+  ModuleClientAgentWorkflowArtifactPolicy,
+  ModuleClientAgentWorkflowArtifactPort,
+  ModuleClientAgentWorkflowArtifactProjectBinding,
+  ModuleClientAgentWorkflowArtifactSafeCode,
+  ModuleClientAgentWorkflowArtifactStatus,
+  ModuleClientAgentWorkflowArtifactSummary,
+  ModuleClientAgentWorkflowArtifactTerminalResultAuthority,
+  ModuleClientAgentWorkflowClientTaskAuthority,
+  ModuleClientAgentWorkflowExecutionTask,
+  ModuleClientAgentWorkflowTaskInputArtifact,
+  ModuleClientAgentWorkflowProjectLaunchAuthority,
+  ModuleClientAgentWorkflowArtifactView,
+} from "./src/client-agent-workflow-artifact.js";
+// @windy-module system.agent end
 export type {
   ModuleAiArtifactPort,
   ModuleAiArtifactRef,
@@ -66,6 +102,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 +124,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,
@@ -126,6 +175,33 @@ export type {
   ModuleDurableHandlerDefinition,
   ModuleDurableStoragePort,
 } from "./src/durable-handler.js";
+// @windy-module system.agent begin
+export {
+  ModuleWorkflowInputArtifactUnavailableError,
+  ModuleWorkflowInputMaterializationError,
+  requireModuleWorkflowInputArtifactPublicationPortV1,
+  type ModuleWorkflowInputArtifactPublicationPortV1,
+  type ModuleWorkflowInputArtifactPublicationV1,
+  type ModuleWorkflowInputArtifactSourceV1,
+  type ModuleWorkflowInputJsonArtifactV1,
+  type ModuleWorkflowInputResourceArtifactV1,
+  type ModuleWorkflowInputMaterializationHandleV1,
+  type ModuleWorkflowInputMaterializationPortV1,
+  type ModuleWorkflowInputMaterializationSourceV1,
+  type ModuleWorkflowInputMaterializationViewV1,
+  moduleWorkflowInputMaterializationHandlerKey,
+} from "./src/workflow-input-artifact-port.js";
+export {
+  MODULE_WORKFLOW_INPUT_MATERIALIZATION_LIMITS_V1,
+  parseModuleWorkflowInputJsonArtifactV1,
+  parseModuleWorkflowInputJsonValueV1,
+  parseModuleWorkflowInputMaterializationBeginV1,
+  parseModuleWorkflowInputMaterializationPayloadV1,
+  parseModuleWorkflowInputMaterializationSourceV1,
+  parseModuleWorkflowInputResourceArtifactV1,
+} from "./src/workflow-input-artifact-validation.js";
+export { defineModuleWorkflowInputMaterializationHandlerV1 } from "./src/workflow-input-materialization-handler.js";
+// @windy-module system.agent end
 export type {
   GovernedExportRenderedArtifact,
   GovernedExportWatermarkContext,
@@ -153,6 +229,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 +339,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.5",
   "license": "UNLICENSED",
   "type": "module",
   "engines": {
@@ -26,8 +26,13 @@
     "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/client-agent-workflow-artifact.ts",
     "src/data-governance-registration.ts",
     "src/debug-session-provider.ts",
     "src/durable-handler.ts",
@@ -48,6 +53,9 @@
     "src/task-registration.ts",
     "src/tool-registration.ts",
     "src/tool-host-port.ts",
+    "src/workflow-input-artifact-port.ts",
+    "src/workflow-input-artifact-validation.ts",
+    "src/workflow-input-materialization-handler.ts",
     "src/user-directory-port.ts",
     "contracts/**/*.json"
   ],

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;
+}