dsh-bailinghub 0.4.0 → 0.6.0

package/docs/SESSION_TOOL_REUSE.md

@@ -0,0 +1,213 @@
+# Reuse business tools across user turns
+
+This feature lets a conversation reuse recently discovered complete tool declarations while the same runtime and Session remain alive. For example, a user can find a shop product and ask for its details in the next message without another capability search.
+
+Reusing a declaration does not reuse an earlier execution context or operation.
+The next turn prepares current rules, context, authorization and a new run for
+the intended target before a new business operation can execute.
+
+This feature is opt-in with `toolLifecycle: 'session'`; default `active_turn` behavior is unchanged. Use DSH 0.6.0 with SDK 0.6.0 and Core 0.8.0 for the complete release set.
+
+## Enable it in the host
+
+Pass the lifecycle option when creating the Agent Client plugin, alongside the
+host's existing stores and transport options:
+
+```js
+import { createAgentClientPlugin } from 'dsh-bailinghub'
+
+const plugin = createAgentClientPlugin({
+  ...existingHostOptions,
+  toolLifecycle: 'session',
+})
+```
+
+Omitting the option, or setting `toolLifecycle: 'active_turn'`, preserves the
+existing lifecycle: tools are retained through searches within one user turn,
+then the next turn discovers its usable tools again. The default plugin entry
+point and existing configuration files keep that behavior. This is a host
+integration option, not an extra setting an ordinary user must manage.
+
+The host must keep the same real DSH Session and runtime between messages. A new
+Session, recreated runtime or host restart begins with an empty declaration
+cache. Restoring the persistent original-invocation journal does not restore
+cached tools; the two mechanisms have separate purposes.
+
+## Two lifetimes
+
+| Item | Lifetime and meaning |
+| --- | --- |
+| `toolset.lifetime=active_turn` | Current execution registrations and target preparation belong to this user turn |
+| `toolset.reuse=session_runtime` | This host enabled declaration reuse between turns of the same living Session |
+| `cache.lifetime=session_runtime` | Cached declarations may survive turn completion, but are not current permission or an active business run |
+| Current run and context | Created lazily for the selected target in the current turn; never carried over as authority |
+| Original invocation | Keeps its original authorization, arguments, run and ID for recovery, independently of the tool cache |
+
+There is no fixed “rediscover every N messages” rule. Each turn must prepare a
+target when business work is first needed. Existing identity, permission and
+capability-revision checks still apply to execution. An unchanged, valid cached
+declaration can be reused; a changed revision, missing entry or invalidated
+declaration requires the current authoritative declaration.
+
+The cache retains at most **64 target-tool pairs across the entire Session** and
+at most **2 MiB of declaration and cache metadata JSON**. The full-schema prompt
+window is **12 tools across targets**. These are cache and presentation budgets,
+not limits on operations, messages, products or task duration. A declaration for
+two separately authorized targets consumes two cache entries, even when their
+parameters are identical. Recent use influences bounded eviction.
+
+Only normalized declarations and trusted target/revision bindings are cached.
+Previous run context, credentials, invocation arguments and business results are
+not stored in this cache. All cache entries are memory-only in this phase.
+
+## How the model should use tools
+
+The existing `search_business_capabilities` tool is also the preparation and
+schema-retrieval entry point in session mode. It accepts an optional exact
+`tool_name`; use the `original_name` from `cached_tools`, not a generated alias,
+an account display name or a guessed capability name.
+
+1. Select the intended `authorization_ref` from the current Session's scope.
+   It is required for multi-target preparation, including two accounts in the
+   same system. A single-target Session can omit it.
+2. Check `targets[].preparation_state`. Use `search_business_capabilities` with
+   a short target-specific `query` and `tool_name` when reusing an exact known
+   tool. Keep the query within 500 characters and avoid unrelated target data.
+3. Read the returned `contexts` and complete `tool_schemas` before deciding on
+   the business call. Preparation explicitly reports
+   `business_operation_performed=false`; it is not a business receipt.
+4. Call a ready tool using its current schema and selected target. It can be
+   called repeatedly within the turn without repeating capability search.
+5. For a new kind of task, omit `tool_name` and search with a relevant query.
+   A broad query still requests ranked discovery; caching does not convert it
+   into a promise to enumerate the entire catalog.
+
+If a ready tool's full schema is outside the presentation window, use the exact
+`tool_name` to bring its declaration back into the window. The declaration can
+come from local cache, while normal scope validation may still make requests.
+The model must not guess fields or rely on an old schema that it cannot inspect.
+
+An exact valid cache hit avoids an additional `searchCapabilities` request. The
+first preparation of a target still calls `startTurn` for current context; Core
+may perform its existing bounded internal discovery there. This is reduced
+duplicate discovery, not a promise of zero network requests or zero server-side
+retrieval.
+
+## Reading the returned state
+
+Both model-facing preparation results and the read-only host method
+`runtime.getSessionToolState(sessionId)` expose the following distinctions:
+
+| Field | Meaning |
+| --- | --- |
+| `targets[].preparation_state=not_prepared` | Selected target has no current-turn run yet; cached tools are not evidence that it is absent or expired |
+| `targets[].preparation_state=ready` | Target has current-turn context and an active run; individual tool validity still matters |
+| `active_tools` | Tools ready for business dispatch with the listed current-turn authorizations |
+| `cached_tools` | Cached names and target bindings; `prepared_authorization_refs` identifies which targets are prepared |
+| `cached_tools[].state=cached_unverified` | At least one associated target still needs current-turn preparation |
+| `visible_tools` | Ready tools in the current full-schema presentation window |
+| `cache.tool_count`, `limit` | Stored target-tool pair count and shared cache ceiling |
+| `cache.bytes`, `byte_limit` | Retained JSON bytes and byte ceiling |
+| `toolset.cached_count` | Shared cached tool-name view; it can differ from the target-tool pair count |
+| `authorizations[].source=cache` | Exact declaration was available after target preparation; no extra search request was needed |
+| `authorizations[].source=discovery` | A current capability search was required |
+| `authorizations[].requested_tool_available=false` | The requested exact tool was not obtained; inspect the returned declarations and feedback instead of calling it blindly |
+
+State can be `inactive` or `blocked`; neither permits dispatch. A prepared target
+does not imply that every possible tool in its business system is available.
+Discovery counts keep the separate meanings defined in
+[capability feedback](CAPABILITY_FEEDBACK.md#search-result-meanings).
+
+## If the model directly calls an unprepared cached tool
+
+The retained name has a preparation guard. If the target is not ready, the guard
+prepares that exact target and declaration, then returns context and schema with
+`business_operation_performed=false`. It does **not** execute the requested
+business arguments. The model must read the result and decide on a new tool call
+using the current instructions and schema.
+
+The original guard call ID stays attached to preparation. Replaying that same
+call ID returns its preparation result, rather than turning the old attempt into
+a write after preparation finishes. A later business call needs its own genuine
+model-issued call ID. Hosts must not silently replay or re-label the first call
+as an operation, and must not display a successful preparation as “product
+updated.” A failed preparation remains a failure or unavailable result.
+
+This guard is a fallback. Providing the preparation guidance and current state
+to the model before it acts is the normal path and avoids unnecessary surprise.
+Calls that enter concurrently before preparation finishes remain preparation-only.
+The host must return preparation to the model before requesting the next business
+decision. Do not queue a previously planned write behind preparation and silently
+issue it under a new call ID. The runtime cannot establish that a custom host has
+actually shown a response to the model merely by observing a later request.
+
+## Example: shop and inventory conversation
+
+In the first message, the user asks to find a shop product. The Agent selects the
+shop authorization, searches product capabilities and calls the query tool.
+
+In the next message, the user asks for that product's details. The Agent sees
+the cached original tool name, prepares it for the same shop authorization,
+reads current shop context and uses the returned schema. If the declaration is
+still valid, no additional capability-search request is needed. The new query
+uses the new turn's run, not the previous product-query run.
+
+The user then asks to check warehouse stock. The Agent selects the separately
+authorized inventory target and discovers its capabilities. Matching tool names
+or product identifiers do not establish a cross-system relationship; the Agent
+must use the business systems' verified identifiers and declared relationships.
+Returning to a still-ready shop tool in the same turn requires no new search.
+
+Simply saying “thanks” does not prepare either system or create business runs.
+Scope validation, controlled system metadata or archive negotiation may still
+occur under their existing contracts; no tool cache restores historical writes.
+
+## Invalidation and original-operation recovery
+
+The original complete selected scope is revalidated. Revocation or a changed
+binding blocks the scope; it never falls back to a default account, another
+Agent Session or the surviving subset. Target keys include the trusted original
+binding, so same-named tools cannot acquire a different target from display text.
+
+Current capability revision changes discard the affected target's old cache.
+A same-revision, same-name contradictory declaration is quarantined rather than
+silently replacing its meaning. Known conflicts survive tool eviction and local
+invalidation; an authoritative new revision can clear them. Cache or metadata
+budget pressure cannot expand authorization or establish that a missing tool
+never existed. Re-discover only within the original selected target.
+
+An operation already issued is different from a missing declaration. Awaiting
+approval or uncertain outcomes keep the original invocation ID and run link.
+Use `resume_governed_tool_invocation` for the original operation; never create a
+replacement write after preparing tools. `inspect_original` means stop automatic
+retries and inspect the original outcome. See
+[durable invocation recovery](INVOCATION_RECOVERY.md).
+
+Cancellation and ended turns continue to reject late tool activation. Cache
+reuse does not weaken local storage errors, archive ACK/CAS, original-run audit
+links, attachment identity or existing business approval rules.
+Temporary target-preparation transport failures can be retried in the same
+runtime and user turn. The retry preserves the original turn ID and initial
+target-specific input, including after a lost response. A cancelled preparation
+keeps its late run link without reopening that target in the ended attempt; a
+later user turn can prepare the original target again.
+
+## Host acceptance checklist
+
+- Preserve the real Session, fixed scope, original call IDs and existing stores;
+  enable session mode explicitly with the exact candidate.
+- Keep preparation state, current context, `tool_schemas`,
+  `business_operation_performed`, structured feedback and original invocation IDs
+  in the model-visible tool result. A terse success badge alone is insufficient.
+- Dispatch through the native tool registry, including cached preparation guards
+  and valid tools outside the schema window. Do not filter by only the latest
+  search result or `visible_tools`.
+- Verify consecutive-message reuse, same-system accounts and cross-system
+  same-name tools, changed declarations, revocation, cache eviction, ordinary
+  chat without business runs, cancellation and preparation call-ID replay.
+- Verify original-operation recovery independently: no repeated business write,
+  no target substitution and no loss of the original execution record.
+
+The business backend continues to own each capability's parameters, validation,
+permissions and approval requirements. No new business API or consumer UI setting
+is required for this opt-in DSH lifecycle.

package/docs/TASK_CONTROL.md

@@ -0,0 +1,183 @@
+# 宿主任务关联与只读回执
+
+配套版本：Core 0.8.0 / SDK 0.6.0 / DSH 0.6.0。新能力需部署方升级并按宿主契约接入；业务权限、审批和原身份约束保持。
+
+## 宿主接口
+
+任务由受控管理端建立；DSH 和模型不创建任务、扩大预算、暂停、继续或取消任务。
+模型工具不接受 task ID。宿主先按原流程选择完整授权集合，再绑定管理端返回的 task：
+
+```js
+import {
+  createAgentClientPlugin, createFileSessionScopeStore,
+  createFileInvocationStore, createFileSessionTaskStore,
+} from 'dsh-bailinghub'
+
+const plugin = createAgentClientPlugin({
+  scopeStore: createFileSessionScopeStore({ directory: '/host/session-scopes' }),
+  invocationStore: createFileInvocationStore({ directory: '/host/invocations' }),
+  taskStore: createFileSessionTaskStore({ directory: '/host/session-tasks' }),
+  toolLifecycle: 'session',
+})
+
+// runtime 来自 ctx.get('bailingHubAgentClient')；session 是真实宿主 Session。
+await runtime.setSessionScope(session.id, { connectionKeys: originalSelectedKeys })
+const coordinates = await runtime.getSessionTaskCoordinates(session)
+// 仅 ready 时，将原成员坐标提供给受控管理端。它们不是执行许可。
+// 管理端建立任务并返回 confirmedTaskId；普通聊天不需要建立任务。
+await runtime.setSessionTaskBinding(session, { taskId: confirmedTaskId })
+const state = await runtime.getSessionTaskState(session)
+// 重开：先恢复原 scope，再恢复 task；这些操作不创建 run 或继续业务调用。
+await runtime.restoreSessionScope(session.id)
+await runtime.restoreSessionTaskBinding(session)
+await runtime.restoreSessionInvocations(session.id)
+```
+
+三个 task 方法也接受原 Session ID 字符串。set 只接受 `{ taskId }`，不接受本地策略、预算或成员替换。
+默认插件使用 DSH_HOME 下的私有 sidecar；注入自定义 scopeStore 的宿主必须明确注入 taskStore 和 invocationStore。
+内存适配器仅用于测试，不提供跨进程持久化。存储目录 0700、文件 0600，原子写入、锁和 revision CAS 与既有 journal 一致。
+
+### 没有进行中的对话轮次，也能核对或继续原调用
+
+例如，商城商品上架正在等待审批，用户关闭客户端后重新打开会话。面板可以直接“核对结果”，
+不必伪造一条用户消息或让模型重新执行上架。用户明确点击“继续原调用”时，才考虑继续原操作。
+
+```js
+// session 必须是真实、保留原 events/unsavedEvents 的宿主 Session，不接受 ID 字符串。
+const inspected = await runtime.inspectSessionInvocation(session, originalInvocationId, { signal })
+// 仅在用户明确要求继续时调用。不要把此方法用于自动轮询。
+const continued = await runtime.resumeSessionInvocation(session, originalInvocationId, { signal })
+```
+
+仅接受原 invocation ID 和可选 AbortSignal，不接受新目标、参数、run 或 task。
+原 ID 来自受保护的持久 invocation store，不能从聊天正文补造记录。
+两种动作均重验整组选定身份、固定范围、原 journal、task 与 CAS；不创建业务 run，不注入工具，
+不改变会话范围或原审批规则。没有 task 的旧 v1 记录仍保持无 task，不能据此跳过后来生效的受管要求。
+
+| 动作 | 行为 |
+| --- | --- |
+| `inspectSessionInvocation` | 只读原服务端 receipt；即使审批已通过也不执行。暂停或取消的原任务仍可核对原结果。 |
+| `resumeSessionInvocation` | 先核对原 receipt。只有明确 `not_dispatched`、无派发 journal 且状态可继续，才发送最多一次原 resume POST。后续等待使用 GET。 |
+| 已派发、结果未知、缺少结果 | 只核对原结果，不新造调用；未知结果不能因“继续”按钮变成替代写入。 |
+| 当前任务暂停、取消或被阻断 | 核对仍按权限进行；继续受原任务门禁限制。额度与并发限制由 Core 在实际派发时权威判断。 |
+
+结果 envelope：`schema=bailing.agent-session-invocation-action.v1`，含 `operation`、`invocation_id`、
+`state`、`resume_dispatched`。`ready` 表示本次核对/继续接口正常返回，**不代表业务成功或整个任务完成**。
+读取 `receipt.result.state` 判断原业务结果；`receipt.result=null` 必须保持结果未确认。
+`resume_dispatched=true` 表示运行时已将原 resume 请求提交给 SDK，不保证 Hub 已接收或业务已执行；
+随后读取的 receipt 本身仍是只读。身份校验可能按 SDK 原规则刷新凭据，这不属于业务派发。
+成功可能含 `result`（原 POST 回应）、`receipt`（其后的核对）、`next_action` 和 `retry_after_ms`。
+未确定结果时继续用 inspect 原 ID；无隐式轮询、定时自动继续或替代 invocation。
+
+失败返回 `blocked / unavailable / unsupported / storage_error / recovery_gap / cancelled`，
+附 `reason` 与现有 `bailing.agent-feedback.v1`，不同时返回可操作的成功结果。
+本地保存失败、`unsavedEvents` 和已确认历史缺口优先；已发出请求后出现这些错误，
+`feedback.dispatch=unknown`，不能把它解释为“业务肯定没执行”。宿主显示主错误并保留原调用 ID。
+网络恢复后可在同一 runtime 重试核对；明确原身份改变仍整组阻断，不退默认目标或剩余授权。
+
+重开时只读加载原本地 outbox 以判断已保存历史，不创建归档、补原文或同步正文。
+只读 GET 中相同限流结果保留原绝对等待截止；新的 POST 限流结果可以建立新的等待窗口。
+宿主和模型对同一 Session / invocation 共享运行时串行控制；跨进程仍依赖原 journal CAS 和 Core 原 ID 幂等规则。
+面板 AbortSignal 与对话轮次分开，关闭 Session/runtime 会取消相关面板动作。迟到响应至多保存原调用事实，
+不会复活工具或恢复已取消任务。宿主应在面板操作取消时 abort，不能把旧响应写入另一个会话。
+
+旧 SDK/Core 不支持只读 receipt 时明确 `unsupported`，不会将读取降级为 resume。
+缺少持久 invocation store 不猜补原绑定。原“填写草稿 → 用户发送 → 模型工具”流程继续可用。
+
+### 读取原任务坐标
+
+例如，同一会话已选择商城和库存系统的授权，宿主需要让管理端建立一个累计预算任务。
+调用 `getSessionTaskCoordinates(session)` 即可获得原会话、原 Agent Session、接入方和 workspace，
+不必读取 `sessionScopes.snapshot()` / `sessionTasks.conversationId()` 或自己计算会话标识。
+该方法也接受原 Session ID 字符串；推荐传入真实 Session，以同步检查已知的 `unsavedEvents` 和可见历史缺口。
+
+成功结果为：
+
+```js
+{
+  schema: 'bailing.agent-session-task-coordinates.v1',
+  state: 'ready', availability: 'supported',
+  sessionId: 'original-host-session-id',
+  clientConversationId: 'dsh.conversation.…',
+  scopeRevision: 2, scopeLocked: false,
+  members: [{
+    connectionKey: 'conn_…',
+    agentSessionId: 'original-agent-session-uuid',
+    clientAppId: 'shop_app', workspace: 'shop'
+  }],
+  snapshot_is_dispatch_permission: false
+}
+```
+
+- 单授权、同系统多授权、同 Hub 跨系统使用同一结构；只返回当前已选成员，不含地址、凭据、名称、正文、参数或工具清单。
+- 每次重新核验完整原范围及任务协议；已绑定时同时核对原任务成员。临时失败可在同一 runtime 上重试，不能取剩余子集或默认授权。
+- 读取不保存、锁定或修复 sidecar，不建立任务、run，不搜索、调用、查询回执或继续业务操作。授权探针由 SDK 按已有机制维护凭据；“只读”不禁止正常凭据刷新。
+- 草稿可读但保持未锁定；重开未锁定草稿仍须显式重新确认。已开始且持久保存的原范围按原规则恢复，缺失记录不猜补。异步改选、持久 CAS 变化会使本次读取失败。
+- `scopeRevision` 只描述读取时的范围修订，不能当成 task 的 `scope_hash`。绑定仍通过 `setSessionTaskBinding` 重新验证，不能直接写 sidecar。
+- 暂停或取消任务的坐标仍可能为 ready；它不表示任务可执行，也不表示宿主允许此时绑定。首消息前才允许绑定等产品规则由宿主判断，不由投影隐式改变。
+
+非 ready 结果**不含** `sessionId/clientConversationId/scopeRevision/scopeLocked/members`，不能沿用界面缓存的旧坐标：
+
+| state | 含义与处理 |
+| --- | --- |
+| `inactive` | 未选或显式空范围，reason 为 `SESSION_SCOPE_UNSELECTED` / `SESSION_SCOPE_CHAT_ONLY`；availability=`not_checked`，零 Hub 请求 |
+| `unsupported` | SDK/Core 明确不支持任务协议；`TASK_UNSUPPORTED` 等，检查配套；不破坏普通未受管多授权流程 |
+| `unavailable` | 临时网络失败、429/5xx 或原身份尚未完成验证；保持原范围，恢复连接后重试只读方法 |
+| `blocked` | 原身份撤销/改绑、范围待确认、CAS 冲突、任务成员不匹配或未分类错误；按 reason/feedback 处理，禁止自动换授权 |
+| `storage_error` | scope/task 持久读取失败或已知未保存消息、invocation、归档；优先解决原存储，不能清队列或创建替代调用 |
+| `recovery_gap` | 当前可见历史尚未被原 outbox 完整覆盖；保留原事件并沿现有恢复流程核对 |
+
+错误沿用 `bailing.agent-feedback.v1`，`operation=task_coordinates`、`dispatch=not_dispatched`，
+提供安全的 `code/category/retryable/next_action`，不要求解析错误文本。
+CAS 的 `SCOPE_STORE_CONFLICT` / `TASK_STORE_CONFLICT` 与读盘失败的 `*_STORE_UNAVAILABLE` 分开；
+`SESSION_SCOPE_CONFLICT` 表示读取期间范围变化。已知本地存储错误优先于网络及 unsupported，随后才是 recovery_gap。
+原 journal/outbox 的持久恢复仍需宿主正常调用既有恢复接口；本投影不代替恢复，也不证明尚未装载的本地存储完整。
+
+旧版本缺少此方法时，宿主只将任务坐标功能显示为 unsupported，保留普通会话，不能回退读取内部协调器。
+此宿主坐标方法本身不新增业务后端要求；完整版本按配套升级指南执行 Core、SDK 和 DSH 升级。
+它没有新增面板直接 inspect/resume 方法，现有“填入草稿→用户发送→原模型工具”流程继续有效。
+
+set 会锁定已选 scope，逐个查询所有原成员，并核对同 Hub、原 Agent Session、client、workspace、conversation、完整 member_count、scope_hash 和不可变工具集合。
+任一成员失效、缺失、换绑或跨 Hub 都不能用剩余子集执行。暂时失败保留原关联，恢复仍验证整组。
+已绑定任务不可切换或删除；已有非受管业务 run 的 Session 不能中途改绑。
+任务确认失败后也不能静默降级成未受管调用。CAS 或保存回执失败保持阻断，restore 只重验或保存同一原关联，不自动创建任务或执行请求。
+
+## 执行和恢复
+
+受管 Session 对实际使用目标按需 startTurn，宿主 options 注入原 taskBinding，SDK 验证 Core 回显。
+聊天、目录加载、task 查询、重开、缓存恢复都不会自动创建任务或业务 run。
+受管 Session 保留最多 64 条声明与 12 条完整 schema 窗口；下一轮只准备实际目标，声明有效时无需再次远端搜索。
+缓存或 task 快照都不是派发许可，每笔业务仍由 Core 原子裁决。
+同一受管操作合并重复身份探针：每次实际 invoke/resume 前仍验证全部原成员和最新任务状态，GET/restore 也重新验证。
+若继续操作需要等待，等待结束后重新验证；同 runtime 断网后必须重验原组才能恢复，不跨操作缓存授权证明。
+固定原绑定可复用协议支持证明；不缓存任务状态、成员身份、unsupported 或未绑定任务时的 required/optional 判定。
+
+- `inspect_governed_tool_invocation` 仅接受原 invocation_id，读取 SDK GET receipt，并与可信 journal 的 run、工具、route、task 和完整原 scope 比对。没有可靠 journal 时不能根据聊天文本猜补身份。
+- 受管后台等待只用 inspect，审批已批准也不会触发 POST resume。
+- `resume_governed_tool_invocation` 表示明确继续原操作；每次显式动作只发一次原 resume，后续等待用 GET。任务暂停、取消、到期或预算拒绝不会给出重新搜索、换授权或换调用 ID 的建议。
+- 取消不回滚已经产生的业务效果。迟到回执仍可保存原事实，但不能恢复已结束轮次的工具或触发后续派发。
+- 旧 Core 的明确 unsupported 且 optional 流程继续原有行为；网络失败不是 unsupported。required 时缺 task 或不兼容 SDK 会阻断，不能降级。
+
+`getSessionTaskState` 同时提供 task_state、控制 revision、计量 counters、policy、协议 availability、local 和 unsavedRecords。
+计量是唯一写 invocation，不是成功数、商品数或附件数；object_metering 明确 unsupported。
+`state` 优先保留 storage_error 和 recovery_gap，因此它可能与 task_state=cancelled 并存；local 保留各存储状态、unsavedEvents 和 unsavedInvocations。
+`getSessionToolState` 和工具准备结果包含同一紧凑 task 摘要，不重新下载任务列表。
+
+## 升级与回滚
+
+既有 journal v1 仍可读取；第一次正常写入升级为 v2。旧条目保持没有 task，不推断归属；新条目的 taskBinding 不可改绑。
+任务 sidecar 使用 `bailing.agent-session-task.v1`，只保存原 scope 指纹、原成员坐标和 task 引用，不保存凭据、聊天或业务参数。
+
+运行前备份 task、scope、invocation 和会话归档存储。包含受管任务或 v2 journal 的 Session 不应回退给不识别它们的旧宿主。
+Core 的 managed enrollment 是粘性的；回退客户端、删 sidecar 或换任务都不能用来解除服务端 task 要求。
+未受管旧 Session 不需要自动创建任务或补写旧条目。部署与数据库升级顺序见配套升级指南。
+
+## 合成验证
+
+```sh
+BAILINGHUB_SDK_DIST=/absolute/path/to/paired-sdk/dist/sdk.js npm run verify
+```
+
+集成测试使用真实 DSH Session、真实配套 SDK 和 loopback HTTP，隔离临时文件存储。
+覆盖跨轮缓存、lazy run、整组检查、required/optional、CAS 失败和丢失保存回执、完整重开、暂停/取消、显式继续、只读 receipt、身份串换、迟到响应和存储优先级。
+它证明 DSH/SDK 接线，不替代真实 Core 数据库事务/HTTP 派发验收，也不涉及真实业务写入。

package/docs/UPGRADE_v0.6.0.en.md

@@ -0,0 +1,71 @@
+# Paired upgrade guide for 0.6.0: longer tasks and attachment delivery
+
+Upgrade Core 0.7.0 / SDK 0.5.0 / DSH 0.5.0 to Core 0.8.0 / SDK 0.6.0 / DSH 0.6.0 using the deployment-specific release procedure. Preserve original configuration and persistent records.
+
+## Choose the required features
+
+| Need | Core | SDK / DSH and host | Business backend |
+| --- | --- | --- | --- |
+| Configure Hub tool limits | New Core, migration 061 and policies | Paired packages for retry guidance and original-call recovery | Keep APIs/declarations; backend limits remain independent |
+| Use generated or explicitly selected images | New Core, 060, storage and workspace switch | New SDK, controlled source and durable upload store in the DSH host | Existing URL APIs work; asset IDs/imports remain business operations |
+| Switch tools within a turn | Paired Core for full discovery feedback | New DSH merges valid tools | No new requirement |
+| Reuse declarations across messages | Current-turn preparation and permission checks remain | Opt into `toolLifecycle: 'session'` and handle preparation | No new requirement |
+| Inspect/recover after reopening | New read-only receipt API | New SDK/DSH, durable invocation store and panel methods | Original invocation and approval rules remain |
+| Task budgets, concurrency and pause | New Core, 062 and administrator-created tasks | Paired packages, task store and complete original-scope verification | Counts invocations, not products or monetary impact |
+
+Other MCP hosts and adapters do not gain these integrations automatically. Ordinary unenrolled authorizations retain their existing flow. Unsupported interfaces must not cause fallback to a broader or default authorization.
+
+## 1. Preserve original state
+
+Back up the database, configuration, encryption material, storage settings and objects. Original argument snapshots use a key derived from the instance's `server.token`. Do not combine a normal upgrade with an unplanned rotation: an old snapshot that cannot be decrypted must block recovery rather than be reconstructed.
+
+Hosts retain secure credentials, connection instance keys, real Sessions, fixed scopes, events, archive outbox/ACK/CAS, upload and invocation journals, and task bindings. Protect these private stores; do not commit or publish them. An upgrade should not recreate authorizations or conversations.
+
+## 2. Upgrade Core and apply migrations
+
+Use final released artifacts and the deployment-specific upgrade procedure. Check the intended database, then run the official migration runner (`npm run db:init` for a source installation) for all unapplied files before starting the new service. Startup does not migrate implicitly.
+
+| New since Core 0.7.0 | Purpose |
+| --- | --- |
+| `060_agent_artifacts.sql` | Original image-upload receipts; binary objects stay in operator storage |
+| `061_tool_rate_limit_policies.sql` | Provider defaults and per-tool overrides; existing null settings inherit declarations |
+| `062_agent_task_control.sql` | Six tables for task bindings, enforcement, invocations and budgets/permits |
+
+Verify the migration ledger and readiness. Do not manually replay applied SQL. Older baselines also need their missing earlier migrations. Existing candidate deployments must compare migration records and checksums rather than recreate tables.
+
+Persistent task control needs the corresponding MySQL repository. Embedded hosts lacking optional support report unsupported. A configured managed flow must block on missing tables or database failure, not fall back to unrestricted dispatch.
+
+## 3. Upgrade the actual SDK, DSH and host
+
+The released DSH must depend on the exact paired SDK, with a matching lockfile. Editing the source manifest alone does not upgrade a desktop Profile or packaged application. Verify actual consumer resolution and nested copies. An earlier same-numbered candidate is identified by hash; it is not the public 0.5.0 package.
+
+- Cross-turn reuse: enable `toolLifecycle: 'session'`, preserve the real Session/runtime and handle preparation with current schemas. `active_turn` remains the default. Restart empties the declaration cache; the separate invocation journal can still recover original operations.
+- Recovery and panels: persist `invocationStore`; use `inspectSessionInvocation` / `resumeSessionInvocation` with the original real Session, ID and cancellation signal. Reads never invoke resume. Null results stay unconfirmed; storage errors and history gaps cannot display stale success.
+- Tasks: persist `taskStore`, obtain original coordinates with `getSessionTaskCoordinates` and bind the administrator-created task. Restore original scope/task/journal. The model does not choose task IDs.
+- Images: connect a controlled `artifactSource` and durable `artifactStore`. Register only files approved for business use in the current conversation. Ordinary chat attachments are not synchronized automatically. The model chooses neither buckets nor arbitrary local paths.
+
+Do not reconstruct missing historical bindings or arguments from text. Old SDK/Core versions without read-only receipts report unsupported; inspection must not fall back to resume.
+
+## 4. Enable features with a small validation scope
+
+Configure Media Storage, then select it under Agent Clients → Connection Configuration → Tools and Approval → Generated Image Upload. Objects are public in the first phase; use an image suitable for public display.
+
+Configure provider-wide, default per-tool and individual override limits under Tool Providers → Edit → Governance. A provider gate value of `0` disables only that layer. Client-app, per-tool and backend gates remain independent. The same provider/tool shares its counter across conversations.
+
+Create and bind a task using dedicated test authorizations. **Enrollment persists a requirement on each original Agent Session, including its other conversations and older entry points. Cancellation does not remove the marker.** Check all relevant hosts before enrolling ordinary authorizations. A task write budget of `0` means read-only; `null` means no cumulative write cap.
+
+## Observable checks
+
+1. Ordinary chat does not create business runs just to restore tools or inspect a panel. Unselected targets receive no requests.
+2. Query a shop product, inspect inventory and return to the product: targets remain correct; valid tools are reused or prepared with complete schemas.
+3. Upload a public test image, obtain a ready URL and recover the same upload. The business action using that URL has its own result or approval.
+4. In a synthetic task, counts survive turn changes; pause stops new dispatch permits while original outcomes remain readable.
+5. Reopen a conversation with trustworthy persisted invocations: inspect sends no business action; explicit continuation retains the original ID. Unknown writes are not replaced. Cancelling a wait is not displayed as withdrawing a business request.
+
+Synthetic and automated checks do not replace each deployer's actual client acceptance. Focus on the enabled features and final artifacts rather than repeating unrelated tests.
+
+## Rollback and limits
+
+Before task enrollment, assess rollback against new persistent records and interfaces and retain migration tables/ledger. **Once enforcement markers exist, do not revert to a Core/host that ignores them or delete markers to remove control.** Pause managed dispatch and inspect in-flight calls first; prefer a forward fix. Restoring a backup requires separately reconciling business effects since that backup. Database restoration is not business rollback.
+
+Task quotas exclude host-local tools, model inference, attachment uploads and chat archives. They do not measure product count, money or field impact. Cross-Hub tasks, full-plan automatic restart and compensation are not provided. Some host attachment-source listing errors can still surface as `unknown_failure`; they must not be displayed as an empty list. Per-item upload errors and already-ready URLs remain separate.

package/docs/UPGRADE_v0.6.0.md

@@ -0,0 +1,73 @@
+# 长任务与附件空间：配套升级指南
+
+本指南从 Core 0.7.0 / SDK 0.5.0 / DSH 0.5.0 升级到 Core 0.8.0 / SDK 0.6.0 / DSH 0.6.0。按部署方式使用正式版本，保留原配置和持久记录。
+
+## 先确定需要哪部分
+
+| 需求 | Core | SDK / DSH 与宿主 | 业务后端 |
+| --- | --- | --- | --- |
+| 调整中枢工具限额 | 新 Core、061；后台设置策略 | 配套版本可展示准确等待与原调用恢复 | 原 API/声明可沿用；业务自有限流不由中枢关闭 |
+| 生成或指定图片后用于业务 | 新 Core、060、存储及工作空间开关 | 新 SDK；DSH 宿主接文件目录和持久上传记录 | 已接收 URL 的能力可沿用；素材 ID/转存由业务系统提供 |
+| 一轮内来回切换工具 | 配套版本用于完整发现反馈 | 新 DSH 自动合并仍有效工具 | 无新增要求 |
+| 跨用户消息复用工具声明 | 沿用现有每轮准备和权限检查 | 新 DSH；宿主显式 `toolLifecycle: 'session'` 并处理准备结果 | 无新增要求 |
+| 重开后恢复原调用及只读面板 | 新 Core 的只读 receipt | 新 SDK/DSH、持久 invocationStore、正式面板接口 | 原调用/审批规则保持 |
+| 任务累计预算、并发和暂停 | 新 Core、062；管理端按需创建任务 | 新 SDK/DSH、taskStore、完整原范围核验与绑定 | 计量为调用次数；不新增商品数/金额保护承诺 |
+
+新包不会自动让其他 MCP 客户端、生态适配器或业务后端取得这些宿主能力。普通未纳入任务的授权可继续原流程；新接口不支持时要明确报告，不能扩大授权或换默认连接。
+
+## 第一步：保留原状态
+
+中枢备份数据库、运行配置与密钥、存储配置和文件对象。限流恢复的原参数快照由实例 `server.token` 派生密钥加密：不要在同一次普通升级中无计划地轮换它。令牌轮换后，旧快照不能解密时应阻断恢复，不能重新猜参数。
+
+客户端保留安全凭据、连接实例标识、真实 Session、固定范围、原事件、归档 outbox/ACK/CAS、上传和原调用账本，以及已有任务关联。保护原私有存储位置，不把这些内容提交源码或当作示例数据；升级不应重新授权或重建全部会话。
+
+## 第二步：升级中枢并迁移
+
+使用最终正式发行制品，按部署方式准备代码和回滚材料。确认目标数据库后，用正式迁移器（源码安装入口为 `npm run db:init`）应用全部未执行迁移，再启动新版本。启动本身不隐式迁移。
+
+| 相对 Core 0.7.0 的迁移 | 保存内容 |
+| --- | --- |
+| `060_agent_artifacts.sql` | 图片上传回执与原上传关联；二进制在部署方存储中 |
+| `061_tool_rate_limit_policies.sql` | 工具源默认及单工具覆盖策略；历史空值继承原声明 |
+| `062_agent_task_control.sql` | 六张任务关联、强制标记、调用及额度/许可记录表 |
+
+检查迁移账本与就绪状态。已经应用的文件不要手工重跑；从更旧版本升级时还要应用其缺少的前序迁移。已有候选部署应按账本和文件摘要核对，不重复建表。
+
+当前任务持久控制需要相应 MySQL 仓储。缺少可选接口的嵌入式 Host 应报告不支持；一旦配置为受管模式，缺表或数据库故障必须阻断，不能静默回到无限制执行。
+
+## 第三步：升级实际 SDK / DSH 和宿主
+
+DSH 正式依赖必须精确指向同批 SDK，lock 也应匹配。仅改工程 `package.json` 不足以证明桌面客户端、用户 Profile 或打包产物已升级：核对实际解析来源，检查是否存在嵌套旧 SDK。早期同版本候选按哈希识别，不能把候选 0.5.0 当成公开 0.5.0。
+
+宿主按需接入：
+
+- 跨轮复用：开启 `toolLifecycle: 'session'`，保留真实 Session/runtime，使用当前 schema 并处理“尚未准备”。默认 `active_turn` 保持。工具缓存重启后为空，不影响另一份原调用账本的持久恢复。
+- 恢复与面板：持久 `invocationStore`；使用正式 `inspectSessionInvocation` / `resumeSessionInvocation`，传原 Session、原 ID 和取消信号。读取不会调用 resume。空结果保持未确认，存储错误或历史缺口不能显示旧成功。
+- 任务：持久 `taskStore`，通过 `getSessionTaskCoordinates` 提交原坐标，再绑定管理端返回的任务，恢复时保留原范围、task 和 journal。任务 ID 不交给模型选择。
+- 图片：受控 `artifactSource`、持久 `artifactStore`，只登记当前会话获准用于业务的文件。普通聊天附件不自动同步，模型不选择桶或本机任意路径。
+
+旧记录缺少可信原绑定或参数时，不从正文补齐。旧 SDK/Core 明确不支持只读回执时，界面显示 unsupported，不用 resume 代替查询。
+
+## 第四步：按需启用，先小范围验证
+
+存储：先在“媒体存储”配置，再到“智能体客户端 → 配置接入 → 工具与审批 → 生成图片上传”启用指定存储。首期公开读取；准备一张可公开的测试图片即可。
+
+限额：在“工具源 → 编辑 → 治理”设置工具源总闸、单工具默认与覆盖策略。总闸的 `0` 只关闭该层，不会关闭单工具、接入方或业务系统自有限流。相同工具源/工具的不同会话共享计数。
+
+任务：用专用测试授权，通过管理端创建任务并绑定。**纳入任务会为原 Agent Session 保存持续强制标记，影响它的其他会话及旧入口；取消任务不会删除标记。** 先确认所有相关宿主兼容，再决定是否纳入日常授权。任务写额度 `0` 表示只读，`null` 表示没有累计写上限，不能混淆。
+
+## 如何确认成功
+
+1. 只聊天时不因恢复缓存或面板而创建业务 run；未选授权不接收请求。
+2. 查询商品、查看库存，再回到商品查询，目标正确，旧有效工具可复用；需要准备时能取得完整参数说明。
+3. 上传公开用途测试图片后得到 ready URL，恢复时仍是原上传；业务侧使用 URL 的成功、审批或失败单独显示。
+4. 在专用合成任务中核对累计调用数；切换轮次不重置，暂停后不授予新派发许可，原结果仍可查询。
+5. 关闭并重开有可信原调用记录的会话，核对不派发；明确继续仍是同一原调用。结果未知不产生替代写，取消等待不被显示为“已撤回业务”。
+
+合成与自动化通过不能替代各部署方的实际客户端验收。无需为了每次升级重新执行无关场景；重点检查本次启用的能力与最终安装包。
+
+## 回退与限制
+
+尚未启用任务时，仍需根据新增持久记录和接口评估回退，保留新增表与账本，不能简单删表降级。**一旦存在任务强制标记，不应回到不理解它的旧 Core/宿主，也不通过删标记解除控制。** 出现问题先暂停受管派发并核对原在途调用，优先修复前进；完整恢复备份需要单独核对备份后已发生的业务效果，不能把数据库恢复当成业务回滚。
+
+任务不包含本地工具、模型推理、图片上传或聊天归档的资源额度，不自动度量商品数、金额或字段影响；没有跨 Hub、整项计划自动恢复或自动补偿。附件列表的某些宿主源错误仍可能显示 `unknown_failure`，宿主不能将其展示为空目录；上传逐项错误和已成功 URL 保持独立。

package/lib/artifact-store.js

@@ -0,0 +1,56 @@
+import { randomUUID } from 'node:crypto'
+import { constants } from 'node:fs'
+import { lstat, mkdir, open, link, unlink } from 'node:fs/promises'
+import { resolve, join } from 'node:path'
+
+const error = () => Object.assign(new Error('Artifact recovery metadata could not be saved or restored.'), { code: 'storage_error' })
+const fileName = id => { if (!/^[a-f0-9]{64}$/.test(id)) throw error(); return `${id}.json` }
+function checked(value, id) {
+  const json = JSON.stringify(value)
+  if (json.length > 16384 || value?.uploadId !== id || !value.metadata || !value.binding || !value.artifactRef || !value.sessionId) throw error()
+  return JSON.parse(json)
+}
+/** Test/ephemeral hosts only. Production hosts must persist the immutable recovery record. */
+export function createMemoryArtifactStore() {
+  const records = new Map()
+  return { async get(id) { return structuredClone(records.get(id) ?? null) }, async reserve(value) {
+    if (!records.has(value.uploadId)) records.set(value.uploadId, checked(value, value.uploadId))
+    return structuredClone(records.get(value.uploadId))
+  } }
+}
+/** Atomic write-once receipts; no credentials or file bytes. Keep this directory across restarts. */
+export function createFileArtifactStore({ directory } = {}) {
+  if (typeof directory !== 'string' || !directory) throw error()
+  const root = resolve(directory)
+  async function prepare() {
+    await mkdir(root, { recursive: true, mode: 0o700 })
+    const stat = await lstat(root)
+    if (!stat.isDirectory() || (process.platform !== 'win32' && (stat.mode & 0o777) !== 0o700)) throw error()
+  }
+  async function get(id) {
+    try {
+      await prepare()
+      let handle
+      try { handle = await open(join(root, fileName(id)), constants.O_RDONLY | constants.O_NOFOLLOW) }
+      catch (e) { if (e.code === 'ENOENT') return null; throw e }
+      try {
+        const stat = await handle.stat()
+        if (!stat.isFile() || stat.size > 16384 || (process.platform !== 'win32' && (stat.mode & 0o777) !== 0o600)) throw error()
+        return checked(JSON.parse(await handle.readFile('utf8')), id)
+      } finally { await handle.close() }
+    } catch { throw error() }
+  }
+  return { get, async reserve(value) {
+    const data = checked(value, value.uploadId)
+    let temporary
+    try {
+      await prepare()
+      temporary = join(root, `${randomUUID()}.tmp`)
+      const handle = await open(temporary, 'wx', 0o600)
+      try { await handle.writeFile(JSON.stringify(data)); await handle.sync() } finally { await handle.close() }
+      try { await link(temporary, join(root, fileName(value.uploadId))) } catch (e) { if (e.code !== 'EEXIST') throw e }
+      if (process.platform !== 'win32') { const dir = await open(root, 'r'); try { await dir.sync() } finally { await dir.close() } }
+      return await get(value.uploadId)
+    } catch { throw error() } finally { if (temporary) await unlink(temporary).catch(() => {}) }
+  } }
+}