create-windy 0.6.11 → 0.6.14

package/template/docs/platform/client-agent-session.md

@@ -0,0 +1,173 @@
+# Governed Client Agent Session
+
+更新时间：2026-08-26。
+
+## 目的与边界
+
+Client Agent Session 是 Windy 为浏览器、桌面壳和扩展等“宿主本地编排模型循环”提供的
+通用治理协议。它不是 PageAgent 专属实现，也不允许下游产品复制 Provider 凭据或
+Agent Server 的 Tool execution grant。下游只负责业务 Composition 和浏览器 binding；
+Windy 拥有会话、模型代理、receipt、终态和审计语义。
+
+生产闭环已经提供：
+
+- `ModuleAiOperationDefinition.clientExecution` 显式 opt-in 与组合门禁；
+- `@southwind-ai/server-sdk` 的宿主 Port 和 `@southwind-ai/ai-client/client-agent` DTO；
+- 单 Run opaque bearer、Actor/Operation/Release/Input/Binding 承诺；
+- `/chat/completions` 请求的 role、字段、model、字节、step 和并发约束；
+- Manifest `providerDataPolicy` envelope allowlist 与 DLP；
+- opaque Provider response receipt、exactly-once finalize/cancel/status/result；
+- Provider 优先结果投影，以及不可冒充 Provider 证明的 `clientProjected` 标记；
+- Actor、binding、权限漂移、TTL 和显式撤销后的 fail-closed 状态机。
+- Windy Server 到 Agent Server 的 internal-token SSE Adapter；Agent Server 固定管理面
+  deployment、物理 model、Provider URL 和 Key；
+- PostgreSQL/Drizzle `client_agent_sessions` 与 `client_agent_receipts` 事务仓储、前向
+  migration 和进程重启恢复；
+- 登录会话撤销、权限漂移、TTL、binding revoke 与 Abort 的联动；
+- `pageAgentClientRun` readiness 协商。只有 Agent Server Provider 与已配对的 Browser
+  Assistant Host Auth Adapter 同时就绪时才返回该 capability。
+
+## Manifest opt-in
+
+只有 `kind=agent`、`providerEgress.mode=configured-endpoint` 且已有
+`providerDataPolicy` 的 Operation 能声明：
+
+```ts
+clientExecution: {
+  mode: "governed-session",
+  maxSteps: 12,
+  maxRequestBytes: 262_144,
+  maxResponseBytes: 262_144,
+  maxConcurrentRequests: 1,
+}
+```
+
+这些上限不能突破 Operation 的输入/输出边界；`maxSteps` 最大 128，并发最大 4。
+Manifest 不声明 Provider URL、物理模型或 Secret。客户端收到的 `modelAlias` 只是本次
+Session 的固定逻辑别名。
+
+## HTTP 契约
+
+创建与 capability 请求使用配对后短期 `bax_` installation session：
+
+```text
+POST /api/agent/client-sessions
+```
+
+请求只包含 `operationKey`、符合 Operation input schema 的 `input`，以及宿主计算的
+`clientBindingDigest`。binding 应覆盖 installation、conversation、tab 和 document
+epoch 或宿主等价的服务切换 epoch；Windy 只保存 digest，不依赖当前浏览网页 origin 的
+人工授权。创建时自动执行 License、Feature、Permission、Scope、
+Provider egress 与 data policy 检查，并返回：
+
+- `clientRunId`、`sessionId`；
+- 受信 `trustedBaseUrl` 和固定 `modelAlias`；
+- steps/request bytes/response bytes/duration/concurrency 上限；
+- `expiresAt` 和 `car_` 前缀的单 Run bearer。
+- `capabilities: ["pageAgentClientRun"]`。
+
+浏览器扩展不需要也不持有宿主 Web cookie。`Authorization: Bearer bax_...` 只由
+Client Agent Host Auth Adapter 在这些 route 上解析，再按 `actorId` 加载 canonical
+Actor、最新 RBAC 与 Scope；普通业务 API 的 Actor resolver 明确拒绝 `bax_` 和 `car_`。
+调用创建前可探测生产 readiness：
+
+```text
+GET /api/agent/client-sessions/capabilities
+```
+
+成功响应为 `{ capabilities: ["pageAgentClientRun"], modelAlias }`。Provider 未配置、
+Agent Server 不可达或未登录时不协商该能力。此流程没有逐动作 approval，也不要求用户
+复制 token；宿主把 grant 只保存在受信内存中。
+
+带 `:sessionId` 的后续 Route 使用 `Authorization: Bearer car_...`，同时通过
+`X-Windy-Host-Authorization: Bearer bax_...` 提供配对 Host Actor，并在
+`x-windy-client-binding-digest` 中重申 binding：
+
+```text
+POST /api/agent/client-sessions/:sessionId/v1/chat/completions
+POST /api/agent/client-sessions/:sessionId/finalize
+POST /api/agent/client-sessions/:sessionId/cancel
+GET  /api/agent/client-sessions/:sessionId
+GET  /api/agent/client-sessions/:sessionId/result
+POST /api/agent/client-sessions/revoke
+```
+
+`trustedBaseUrl` 是带当前 `sessionId` 的 OpenAI-compatible baseURL，例如
+`https://windy.example/api/agent/client-sessions/cas_x/v1/`。PageAgent 只向其
+`chat/completions` 子路径发送请求。`revoke` 使用 `bax_` Host Auth 和
+`{ clientBindingDigest }`，只撤销当前 Actor 的匹配 binding；服务切换、installation
+撤销或宿主 session 关闭时应调用它。登出和登录会话撤销会由平台自动执行 Actor revoke。
+
+bax/car bearer 只匹配 Client Agent Route，不能调用普通业务 API 或 Tool Host。服务端只保存其
+SHA-256 hash。客户端请求只能使用固定 model alias 和允许的 OpenAI-compatible 字段；
+URL、endpoint、未知 body 字段、未知 role、越界 Tool schema 都会被拒绝。
+
+PageAgent Core 1.12.2 的通用 envelope 已锁定：`parallel_tool_calls` 必须为 `false`；
+`tool_choice` 可为 `auto`、`none`，或引用当次 `tools` 中 function 的命名选择（包括
+MacroTool `AgentOutput`）；assistant 历史可携带经校验的 `tool_calls`，后续 tool message
+必须以 `tool_call_id/name` 匹配该调用。并行调用、未知命名 function 或断裂的 tool history
+都会 fail closed。
+
+流式响应转发标准 OpenAI SSE chunk；成功末尾追加
+`event: windy.receipt`，其 data 为 receipt，再发送 `[DONE]`。非流式响应在
+`windy_receipt` 字段和 `x-windy-provider-receipt-id` 响应头返回相同 receipt。Abort 会
+向 Agent Server 和 Provider 传播；取消或撤权后迟到 chunk 不能生成 receipt。
+
+## Receipt 与终态
+
+每次成功 Provider attempt 生成一个 `receipt_` opaque ID，并持有以下不可变绑定：
+
+- Client Run、Actor、Operation、Release、binding digest；
+- attempt 序号、request/response/deployment digest；
+- issuedAt 和可选的服务端 canonical result 投影。
+
+Repository 不保存 raw prompt、Provider response、Secret 或 bearer。HTTP 只公开 receipt
+所需的 opaque ID 与 digest，不公开 Actor、Scope、Release 内部快照。
+
+`finalize` 必须按 attempt 顺序提交本 Run 的完整 receipt 链，且没有在途请求。Gateway
+能够从最终 Provider response 得到 schema-valid 投影时，结果标为
+`provider-observed`；否则可以接受有界、schema-valid 的客户端投影，但必须标为
+`client-projected`，`providerAttested=false`。客户端 DTO 没有 `runtimeVerified` 字段。
+
+完成、取消、撤销和过期都是不可改写终态。重复的相同 finalize 返回同一结果；不同
+finalize、终态后的模型调用和跨 Run/Actor/binding receipt 重放均被拒绝。取消会 abort
+在途 Provider 请求；即使响应随后到达，也不能再追加 receipt 或改变终态。
+
+## 部署与稳定错误
+
+生产 Server 必须配置 `WINDY_PUBLIC_BASE_URL=https://windy.example`。它只用于生成受信
+Windy baseURL，不能指向 Provider。Provider URL、Key、物理 model 和 deployment 只通过
+Agent Server 管理面环境配置；公共 DTO 没有 BYOK 字段，也不支持客户端 model override。
+
+稳定错误 code 为 `INVALID_INPUT`、`FORBIDDEN`、`NOT_FOUND`、`CONFLICT`、
+`LIMIT_EXCEEDED`、`PROVIDER_FAILED`、`INTERNAL_ERROR`。message 使用简体中文安全文案，不透传 Provider
+正文、URL、Key、物理 model 或内部错误。License/Feature/Permission/Scope 不满足统一
+fail closed，不进入人工审批状态机。
+
+PostgreSQL 集成回归使用 `CLIENT_AGENT_TEST_DATABASE_URL`，覆盖并发预留、receipt 原子写入、
+重启恢复与终态不可改写；Agent Server contract 回归覆盖 tool calls、DLP、SSE、Abort 和
+Provider 错误脱敏。
+
+## 升级说明
+
+从不含生产 Client Agent Session 的版本升级时：
+
+1. 先执行标准 `windy update` / migration 流程，确认 migration 0055 已创建 session 与
+   receipt 两张表，0056 已加入 Host Session digest；不要手工回填 token 或 Provider 响应；
+2. Server 配置 `WINDY_PUBLIC_BASE_URL`，生产必须是最终用户可访问的 HTTPS 利剑服务 origin；
+3. Agent Server 继续使用现有 `QWEN_API_URL`、`QWEN_API_KEY`、`QWEN_MODEL` 与 deployment
+   配置，绝不把这些值复制到 Web、扩展或业务模块；
+4. 业务模块仅在目标 Agent Operation 上声明 `clientExecution`，同时保留原
+   Feature/Permission/License/Scope 与 `providerDataPolicy`；
+5. 在 project-owned `client-agent-host-auth-binding.ts` 装配实现
+   `ModuleClientAgentHostAuthAdapter` 的 P-256 pairing/bax Adapter；其 `authenticate` 只返回
+   actor/installation/session 标识，权限仍由 Windy canonical Actor 加载，并通过
+   `bindRevocations` 把 installation/session 撤销推给 Session Service。未装配或未 ready 时
+   不注册/不协商 capability；
+6. 客户端先请求 capabilities；只有出现 `pageAgentClientRun` 才切换 PageAgent 路径，否则
+   保持旧路径或明确不可用；
+7. 服务地址或 installation pairing 切换前调用 binding revoke，清除内存中的 grant；无法
+   联系旧服务时不得复用旧 token，等待其短 TTL 到期。
+
+协议没有 BYOK、用户模型选择、逐动作审批或逐目标网页 origin 授权字段。宿主配对只负责
+识别目标 Windy 服务、当前登录 actor、installation 和撤销边界。

package/template/docs/platform/embedding-ai-runtime.md

@@ -0,0 +1,94 @@
+# Embedding AI Runtime
+
+Windy 提供受治理的文本与图片 Embedding 调用边界，不提供业务向量库。业务模块仍负责向量表、索引版本、增量更新、案件权限过滤、重建和排序。
+
+## 调用链
+
+业务模块在 Manifest 注册 `kind=embedding` Operation，同时声明稳定的 Feature、Permission、License、审计动作、数据分类、输入模态、能力和预算。模块 `setup(host)` 通过 `prepareEmbedding` 生成领域选项；浏览器只调用同源 `/api/embeddings`。
+
+文本经过 Provider 数据字段治理后进入 Runtime。图片必须是当前 Actor 有权读取的 `ArtifactRef`；平台重新签发短时引用，Runtime 校验大小、哈希、MIME 和像素预算，移除元数据后才交给内网 Adapter。业务代码不能提交文件路径、任意 URL 或 Base64。
+
+`POST /api/embeddings/runs` 创建持久 Run；轮询 events/result 或取消时都会重新验证当前 Actor、Module、Feature、Permission、License 和 scope。图片 Run 在 worker 实际读图前仅以 `runId/itemId` 回调 Server；Server 从持久绑定恢复密封引用、重建当前 Guard 并刷新读取授权。客户端与 Embedding Runtime 都不能提交 Actor、scope 或新的 Artifact token。授权、资源完整性或部署限制发生漂移时，该操作 fail-closed。
+
+```ts
+const operation = {
+  key: "analysis.embedding.multimodal",
+  kind: "embedding",
+  featureKey: "analysis.embedding",
+  permissionKey: "analysis.embedding.execute",
+  licenseFeatureKey: "analysis.embedding",
+  auditAction: "analysis.embedding.execute",
+  dataClassification: "sensitive",
+  inputModalities: ["text", "image"],
+  outputModalities: ["embedding"],
+  requiredCapabilities: ["embedding.text", "embedding.image"],
+  limits: {
+    maxDurationSeconds: 60,
+    maxInputBytes: 20_000_000,
+    maxOutputBytes: 20_000_000,
+    maxUnits: 64,
+    maxArtifacts: 16,
+    maxPixelsPerArtifact: 20_000_000,
+  },
+};
+```
+
+## 固定输出契约
+
+每个批次返回稳定 `batchId`、逐项输入 SHA-256 和向量，以及由 Runtime 配置固定的：
+
+- `deploymentAlias`
+- `model`
+- `version`
+- `dimensions`
+- `normalized`
+
+Runtime 拒绝 ID/顺序漂移、维度漂移、非有限数值和与归一化声明不一致的向量。Adapter 响应不能覆盖上述部署元数据。这些字段使业务索引可重现、可判断何时需要重建。
+
+## 部署
+
+Adapter URL 只允许本机、Compose 服务名、`.internal` 或私网 IP。平台不允许把敏感输入发往任意公网端点。
+
+```dotenv
+EMBEDDING_SERVER_URL=http://embedding-server:8092
+EMBEDDING_ARTIFACT_URL=http://server:9747/api/internal/ai/artifacts
+EMBEDDING_RUN_ARTIFACT_URL=http://server:9747/api/internal/embeddings/runs
+EMBEDDING_ADAPTER_URL=http://embedding-adapter:9000
+EMBEDDING_ADAPTER_TOKEN=
+EMBEDDING_DEPLOYMENT_KEY=local-embedding
+EMBEDDING_DEPLOYMENT_IDENTITY=windy-deployment-v1_<uuidv4>
+EMBEDDING_RELEASE_DIGEST=sha256:<64位小写十六进制>
+EMBEDDING_OFFERS_DIGEST=sha256:<64位小写十六进制>
+EMBEDDING_DEPLOYMENT_ALIAS=intranet-multimodal-v1
+EMBEDDING_MODEL=local-model
+EMBEDDING_MODEL_VERSION=2026-07
+EMBEDDING_DIMENSIONS=1024
+EMBEDDING_NORMALIZED=true
+EMBEDDING_CAPABILITIES=embedding.text,embedding.image
+EMBEDDING_MAX_UNITS=256
+EMBEDDING_RUN_ENCRYPTION_SECRET=至少32字符的独立密钥
+EMBEDDING_MAX_CONCURRENT_RUNS=1
+EMBEDDING_MAX_QUEUE_DEPTH=0
+EMBEDDING_READINESS_TIMEOUT_SECONDS=5
+EMBEDDING_READINESS_TTL_SECONDS=60
+EMBEDDING_RUN_TERMINAL_TTL_SECONDS=604800
+```
+
+启动可选服务：
+
+```bash
+bun run dev:embedding
+```
+
+健康端点需要内部 Bearer Token，只在 `/v1/embedding/readiness` 真实探测 Adapter、
+重算完整原子 offers 与 release digest，并与配置 pin 完全一致时发布 readiness V1。
+可用 `python -m southwind_embedding_server.pin_cli` 从同一真实探测事实计算部署 pins；
+命令只输出 pins，不写 `.env`。Host 在业务 prepare、Artifact/Run 创建前固定
+deployment pin，Remote 与 Embedding Runtime 在实际调用前再次核对。未配置 Adapter、
+缺失 pin、探测失败或部署漂移时返回 503，不回退到假向量或其它模型。
+
+## 错误与审计
+
+稳定错误码包括 `INVALID_INPUT`、`FORBIDDEN`、`CAPABILITY_UNAVAILABLE`、`BUDGET_EXCEEDED`、`OUTPUT_VALIDATION_FAILED` 和 `RUNTIME_UNAVAILABLE`。错误响应不透传 Adapter 正文。
+
+成功审计记录 Operation、Actor、批次、输入数量、部署别名、模型版本、维度和归一化状态，不记录原文、图片或向量。

package/template/docs/platform/platform-authentication.md

@@ -99,14 +99,11 @@ Server 会幂等创建默认开发管理员和 `developer` 角色；仅当默认
 
 Web 不提供默认开发 Token。只有 Vite 开发模式同时设置 `VITE_DEV_AUTH_BYPASS=1` 和非空 `VITE_DEV_ADMIN_TOKEN` 时，前端才会携带显式 Bearer Token，并在登录页和应用壳持续显示警告；生产构建无条件忽略这两个变量。完成一次真实密码登录后，当前页面生命周期内会停用开发 Token，后续请求只使用 Cookie。
 
-选择 Agent 模块的新项目会在本机 `.env` 自动生成独立随机
-`ADK_DEBUG_PLATFORM_TOKEN`。只有 `bun run dev:adk-web` 加载的开发 Compose Wrapper
-会把它作为 `WINDY_ADK_DEBUG_TOKEN` 注入 Server，并注入 localhost-only ADK Web；它
-不会复用 `WINDY_DEV_ADMIN_TOKEN`，也不会启用固定 `dev-admin-token` 或 `user:` 直通。
-Server 仅在 canonical Agent Run 路径和只读
-`GET /api/agent/debug/sessions/v1/**` 路径把它解析成 `service_adk_debug`，权限收敛为
-项目选择的 Operation 与 allowed Tools 权限闭包。该 Token 不进入 Web、Agent
-Server、Provider 或生产 Compose；非 development Server 即使误配也会拒绝。
+Agent Runtime 调试与历史会话读取复用 Windy 主站的真实登录身份，不创建第二种调试
+Token、专用服务身份或开发认证旁路。`GET /api/agent/sessions/v1/**` 按 Provider 所绑定
+Operation 的 Feature、Permission 与当前 Actor 数据范围逐次授权；主站 Runtime Report
+继续要求 `system.ai-runtime.read`。这些接口不接受 `WINDY_DEV_ADMIN_TOKEN` 以外的新型
+Bearer 方案，也不会把内部服务 Token 下发给浏览器。
 
 未配置 `DATABASE_URL` 时不会注册真实登录 API；只允许显式的非生产开发直通，不存在内存生产账号或默认生产密码。
 

package/template/package.json

@@ -20,7 +20,6 @@
     "dev:speech": "PLATFORM_ENABLE_AI=true SPEECH_SERVER_URL=http://speech-server:8091 docker compose --profile agent --profile speech up --build",
     "speech:pins": "bun run scripts/provision-speech-readiness.ts",
     "dev:embedding": "PLATFORM_ENABLE_AI=true EMBEDDING_SERVER_URL=http://embedding-server:8092 docker compose --profile agent --profile embedding up --build",
-    "dev:adk-web": "bun run scripts/dev-adk-web.ts",
     "dev:search": "OPENSEARCH_URL=http://opensearch:9200 docker compose --profile search up --build",
     "dev:license": "bun run --cwd apps/license dev",
     "dev:license:docker": "docker compose --profile license up license",

package/template/packages/ai-client/index.ts

@@ -1,4 +1,5 @@
 export * from "./src/agent/index.js";
+export * from "./src/client-agent/index.js";
 export type { ArtifactRef } from "./src/artifact-ref.js";
 export * from "./src/document/index.js";
 export * from "./src/embedding/index.js";

package/template/packages/ai-client/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@southwind-ai/ai-client",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "license": "UNLICENSED",
   "type": "module",
   "engines": {
@@ -18,6 +18,7 @@
   "exports": {
     ".": "./index.ts",
     "./agent": "./src/agent/index.ts",
+    "./client-agent": "./src/client-agent/index.ts",
     "./contracts": "./src/agent/contracts/index.ts",
     "./document": "./src/document/index.ts",
     "./embedding": "./src/embedding/index.ts",

package/template/packages/ai-client/src/agent/client/client.ts

@@ -74,6 +74,7 @@ export class HttpAgentCaller implements AgentCaller {
       ...(options.screenshotIntakeToken
         ? { screenshotIntakeToken: options.screenshotIntakeToken }
         : {}),
+      ...(options.sessionId ? { sessionId: options.sessionId } : {}),
     };
     let response: Response;
     try {
@@ -103,6 +104,7 @@ export class HttpAgentCaller implements AgentCaller {
     const created = parseCreatedRun(await safeJson(response, "创建 Agent Run"));
     return this.createRun(operation, created.runId, created.eventsUrl, {
       signal: options.signal,
+      sessionId: options.sessionId,
     });
   }
 
@@ -120,7 +122,11 @@ export class HttpAgentCaller implements AgentCaller {
         {
           method: "POST",
           headers: { "content-type": "application/json" },
-          body: JSON.stringify({ operationKey: operation.key, cursor }),
+          body: JSON.stringify({
+            operationKey: operation.key,
+            cursor,
+            ...(options.sessionId ? { sessionId: options.sessionId } : {}),
+          }),
           signal: options.signal,
         },
       );
@@ -154,6 +160,7 @@ export class HttpAgentCaller implements AgentCaller {
       signal: options.signal,
       initialSequence: cursor,
       initialTerminal: attached.terminalEvent,
+      sessionId: options.sessionId,
     });
   }
 
@@ -173,9 +180,15 @@ export class HttpAgentCaller implements AgentCaller {
       signal?: AbortSignal;
       initialSequence?: number;
       initialTerminal?: TerminalAgentEvent;
+      sessionId?: string;
     },
   ): AgentRun<Output> {
-    const operationQuery = `operationKey=${encodeURIComponent(operation.key)}`;
+    const operationQuery = [
+      `operationKey=${encodeURIComponent(operation.key)}`,
+      ...(state.sessionId
+        ? [`sessionId=${encodeURIComponent(state.sessionId)}`]
+        : []),
+    ].join("&");
     return new HttpAgentRun<Output>({
       id: runId,
       eventsUrl: this.endpoint(eventsPath),

package/template/packages/ai-client/src/agent/client/run-protocol.test.ts

@@ -29,17 +29,31 @@ describe("Agent Run protocol safety", () => {
     expect(fake.calls).toBe(1);
   });
 
-  test("跨 chunk 解析 heartbeat 和事件 frame", async () => {
-    const started = frame({
-      type: "run.started",
-      runId: "run-chunks",
-      sequence: 1,
-    });
-    const completed = frame({
-      type: "run.completed",
-      runId: "run-chunks",
-      sequence: 2,
-    });
+  test("从 sequence 0 跨 chunk 解码完整 canonical 事件流", async () => {
+    const canonicalEvents: AgentEvent[] = [
+      { type: "run.started", runId: "run-chunks", sequence: 1 },
+      {
+        type: "input.prepared",
+        runId: "run-chunks",
+        sequence: 2,
+        artifactCount: 0,
+        inputModalities: ["text"],
+      },
+      {
+        type: "output.delta",
+        runId: "run-chunks",
+        sequence: 3,
+        text: "完成",
+      },
+      {
+        type: "usage.reported",
+        runId: "run-chunks",
+        sequence: 4,
+        usage: { source: "unknown" },
+      },
+      { type: "run.completed", runId: "run-chunks", sequence: 5 },
+    ];
+    const stream = `: heartbeat\n\n${canonicalEvents.map(frame).join("")}`;
     const fake = plannedFetch([
       () =>
         json({
@@ -47,23 +61,21 @@ describe("Agent Run protocol safety", () => {
           status: "accepted",
           eventsUrl: "/events",
         }),
-      () =>
-        sse([
-          ": heart",
-          "beat\n\n" + started.slice(0, 9),
-          started.slice(9) + completed.slice(0, 17),
-          completed.slice(17),
-        ]),
+      (input, init) => {
+        const url = new URL(
+          input instanceof Request ? input.url : input.toString(),
+        );
+        expect(url.searchParams.has("after")).toBe(false);
+        expect(new Headers(init?.headers).has("last-event-id")).toBe(false);
+        return sse([stream.slice(0, 8), stream.slice(8, 41), stream.slice(41)]);
+      },
       () => json({ runId: "run-chunks", status: "completed", output: "ok" }),
     ]);
     const run = await start(fake.fetch, "chunks");
     const events = collect(run.events);
 
     await expect(run.result()).resolves.toBe("ok");
-    expect((await events).map(({ type }) => type)).toEqual([
-      "run.started",
-      "run.completed",
-    ]);
+    expect(await events).toEqual(canonicalEvents);
   });
 
   test("run.failed 返回 canonical 安全错误且不请求 result", async () => {
@@ -186,16 +198,18 @@ function start(fetch: AgentFetch, idempotencyKey: string) {
   }).start(operation, null, { idempotencyKey });
 }
 
-function plannedFetch(plans: Array<() => Response>): {
+function plannedFetch(
+  plans: Array<(...args: Parameters<AgentFetch>) => Response>,
+): {
   fetch: AgentFetch;
   readonly calls: number;
 } {
   let calls = 0;
   return {
-    fetch: async () => {
+    fetch: async (...args) => {
       const plan = plans[calls++];
       if (!plan) throw new Error("unexpected fetch");
-      return plan();
+      return plan(...args);
     },
     get calls() {
       return calls;

package/template/packages/ai-client/src/agent/client/types.ts

@@ -7,11 +7,15 @@ export interface StartAgentRunOptions {
   artifacts?: readonly ArtifactRef[];
   /** Host-issued one-shot screenshot intake; never an Artifact URL or Run owner. */
   screenshotIntakeToken?: string;
+  /** 可选的长期 Session；服务端会重新校验当前 Actor 与授权范围。 */
+  sessionId?: string;
   signal?: AbortSignal;
 }
 
 export interface AttachAgentRunOptions {
   cursor?: number;
+  /** 恢复长期 Session 关联；服务端仍会校验 Run、Actor 与 Scope。 */
+  sessionId?: string;
   signal?: AbortSignal;
 }
 

package/template/packages/ai-client/src/agent/contracts/contracts.test.ts

@@ -24,34 +24,41 @@ const error = {
 
 const events: AgentEvent[] = [
   { type: "run.started", runId: "run-1", sequence: 1 },
-  { type: "output.delta", runId: "run-1", sequence: 2, text: "你好" },
+  {
+    type: "input.prepared",
+    runId: "run-1",
+    sequence: 2,
+    artifactCount: 1,
+    inputModalities: ["text", "image"],
+  },
+  { type: "output.delta", runId: "run-1", sequence: 3, text: "你好" },
   {
     type: "tool.requested",
     runId: "run-1",
-    sequence: 3,
+    sequence: 4,
     toolCallId: "call-1",
     toolKey: "work-order.ticket.read",
   },
   {
     type: "approval.required",
     runId: "run-1",
-    sequence: 4,
+    sequence: 5,
     workItemId: "work-1",
     toolCallId: "tool-call-1",
   },
   {
     type: "tool.completed",
     runId: "run-1",
-    sequence: 5,
+    sequence: 6,
     toolCallId: "call-1",
   },
   {
     type: "usage.reported",
     runId: "run-1",
-    sequence: 6,
+    sequence: 7,
     usage: { source: "provider-reported", inputTokens: 10 },
   },
-  { type: "run.completed", runId: "run-1", sequence: 7 },
+  { type: "run.completed", runId: "run-1", sequence: 8 },
   { type: "run.failed", runId: "run-2", sequence: 1, error },
   { type: "run.cancelled", runId: "run-3", sequence: 1 },
 ];
@@ -121,6 +128,41 @@ describe("Agent contract", () => {
     expect(() =>
       parseAgentEvent({ type: "output.delta", runId: "run-1", sequence: 1 }),
     ).toThrow(AgentContractParseError);
+    expect(() =>
+      parseAgentEvent({
+        type: "input.prepared",
+        runId: "run-1",
+        sequence: 2,
+        inputModalities: ["text"],
+      }),
+    ).toThrow(AgentContractParseError);
+    expect(() =>
+      parseAgentEvent({
+        type: "input.prepared",
+        runId: "run-1",
+        sequence: 2,
+        artifactCount: -1,
+        inputModalities: ["text"],
+      }),
+    ).toThrow(AgentContractParseError);
+    expect(() =>
+      parseAgentEvent({
+        type: "input.prepared",
+        runId: "run-1",
+        sequence: 2,
+        artifactCount: 0,
+        inputModalities: ["binary"],
+      }),
+    ).toThrow(AgentContractParseError);
+    expect(() =>
+      parseAgentEvent({
+        type: "input.prepared",
+        runId: "run-1",
+        sequence: 2,
+        artifactCount: 0,
+        inputModalities: [],
+      }),
+    ).toThrow(AgentContractParseError);
     expect(() =>
       parseAgentEvent({
         type: "run.started",
@@ -185,7 +227,7 @@ describe("Agent SSE", () => {
       comment: "heartbeat",
     });
     const event = events[1]!;
-    const frame = `id: 2\nevent: output.delta\ndata: ${JSON.stringify(event)}`;
+    const frame = `id: 2\nevent: input.prepared\ndata: ${JSON.stringify(event)}`;
     expect(decodeAgentSseFrame(frame)).toEqual({
       kind: "event",
       id: 2,