dsh-a2a-server 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -0,0 +1,39 @@
+# Changelog
+
+[English](CHANGELOG.md) · [简体中文](CHANGELOG.zh-CN.md)
+
+## 0.4.0 (2026-11-04)
+
+- Exclude nested `node_modules` from Microsandbox public projections without following dependency links or changing host projects. Other links, private imports and Docker mounts remain strictly checked.
+
+- Add owner-only local IPC `prepare-stop` to drain tasks and persist guest disks before Portal/CLI terminates the backend. Real-model Relay testing exposed lost recent writes when Windows terminated the process tree without this step.
+
+- Add automatically prepared Microsandbox 0.7.11 execution: one VM per authenticated visitor, read-only public projections and independent persistent private disks.
+- Pause after 30 idle seconds and stop after 10 idle minutes; serialize visitor tools, bound resident VMs, preserve files on stop/restart and recover abandoned instances.
+- Keep conversations and credentials outside guest mounts. Migrate old private files outside public roots; reject links and unsafe directory layouts. Only read_file remains exposed to visitors.
+- Verify native Python mutation boundaries, lifecycle, restart persistence, automatic preparation and Portal startup progress. See [isolation guide](docs/visitor-isolation.en.md).
+
+## 0.3.0
+
+Requires DeepSeek Harness `>=0.2.1-rc.2 <0.3.0` and speaks A2A 1.0 JSON-RPC.
+
+- Restrict visitors to chat and `read_file` within the owner's selected data directory. Block path escapes, links, private plugin state and other tools; separate public prompt context from the owner's runtime context.
+- Move owner RPC and monitoring to authenticated local IPC. Public HTTP accepts visitor credentials only. An empty `trustedPeers` list denies all visitors.
+- Bound concurrent tasks, daily admission, execution time, model calls, outputs and stream buffers. Prevent concurrent tasks in one context from mixing answers; clean up disconnected SSE subscriptions.
+- Persist task results and idle conversation history across eviction and restart within the retention window. Fail interrupted work without replaying it.
+- Add the optional Portal-configured automatic briefing loop: default-on hourly updates, a persistent switch, restart-safe timing, and direct publication to `.hop/handoff.md`.
+- Declare required runtime packages and verify imports without development dependencies. Preserve the guard against malformed Unicode from upstream streaming decoders.
+
+Validation: 217 tests in 15 files, TypeScript checking, build and declared-runtime package import check. Models are deterministic test adapters; real-model and cross-network deployment verification remain separate.
+
+### Upgrade
+
+Stop the agent, update dsh if needed, then install into the existing profile:
+
+```sh
+dsh plugin --profile YOUR_PROFILE add dsh-a2a-server@0.3.0
+```
+
+Replace `YOUR_PROFILE` with the saved profile name and restart the agent. Upgrade the companion [Talk2MyAgent Portal](https://github.com/huangjuhua-aigc/Talk2MyAgent) for the private management endpoint and automatic briefing settings. Do not recreate an existing profile with `--from-default-profile` during an upgrade.
+
+Old HTTP owner/monitoring integrations must migrate to local IPC. Review visitor admission and the selected data directory before exposing the service. [Migration details](https://github.com/huangjuhua-aigc/dsh-a2a/blob/main/docs/public-access-hardening.en.md).

package/CHANGELOG.zh-CN.md

@@ -0,0 +1,39 @@
+# 更新日志
+
+[English](CHANGELOG.md) · [简体中文](CHANGELOG.zh-CN.md)
+
+## 0.4.0（2026-11-04）
+
+- Microsandbox 公共资料副本排除各层级的 `node_modules`，不跟随依赖链接，也不修改宿主项目。其他链接、私有文件导入和 Docker 挂载仍保持严格检查。
+
+- 增加仅本机主人可用的 `prepare-stop`，收尾任务并停止沙箱、保留磁盘后，Portal/CLI 才结束后端。真实模型中继测试发现，Windows 直接结束进程树会丢失尚未写盘的近期文件，现已修复正常停止流程。
+
+- 自动准备 Microsandbox 0.7.11；每位已认证访客独立 VM，公共资料副本只读、私有磁盘可读写并持久保存。
+- 工具完成后空闲 30 秒暂停、10 分钟停止；同访客工具串行，限制驻留数量，停止/重启保留文件，并回收遗留实例。
+- 聊天记录和凭据不挂入沙箱；旧私有文件迁出公共目录，拒绝链接及不安全目录结构。访客仍只开放 read_file。
+- 增加真实 Python 隔离、生命周期、重启持久化、自动准备与 Portal 启动进度测试，详见[隔离指南](docs/visitor-isolation.md)。
+
+## 0.3.0
+
+要求 DeepSeek Harness `>=0.2.1-rc.2 <0.3.0`，使用 A2A 1.0 JSON-RPC。
+
+- 访客可以聊天，并通过 `read_file` 读取主人指定的资料目录。拦截路径越界、链接、插件私有状态及其他工具；公共模型提示与主人运行时上下文分离。
+- 主人 RPC 和监控迁到需要认证的本机 IPC；公网 HTTP 仅接受访客凭据。空白名单 `trustedPeers: []` 拒绝全部访客。
+- 限制并发、每日任务数、执行时限、模型调用、输出和流缓冲；同一 context 的并发请求不会串答，SSE 断开后释放订阅。
+- 在保留期内持久化任务结果与空闲对话，支持驱逐和重启后的恢复。重启中断的任务标记失败，不自动重放。
+- 增加由 Portal 配置的自动简报循环：默认每小时更新、一个持久化开关、重启去重，完成后直接写入 `.hop/handoff.md`。
+- 补齐运行依赖声明，验证脱离开发依赖后可导入。保留上游流式解码异常的 Unicode 防护。
+
+验证：15 个文件共 217 项测试、类型检查、构建和仅使用声明运行依赖的包导入检查。测试使用确定性模型；真实模型与跨网络部署需要单独验收。
+
+### 升级
+
+停止 agent，必要时升级 dsh，然后更新原有 profile 中的插件：
+
+```sh
+dsh plugin --profile YOUR_PROFILE add dsh-a2a-server@0.3.0
+```
+
+将 `YOUR_PROFILE` 替换为已保存的 profile 名称，安装后重新启动。配套 [Talk2MyAgent Portal](https://github.com/huangjuhua-aigc/Talk2MyAgent) 也需要更新，以使用私有管理入口和自动简报开关。升级已有 profile 时不要再次使用 `--from-default-profile`。
+
+原来的 HTTP 主人/监控调用必须迁移至本机 IPC。部署前检查访客许可与资料目录，详见[迁移指南](https://github.com/huangjuhua-aigc/dsh-a2a/blob/main/docs/public-access-hardening.md)。

package/README.md

@@ -16,8 +16,8 @@
   <a href="https://www.npmjs.com/package/dsh-a2a-server"><img src="https://img.shields.io/npm/v/dsh-a2a-server?style=flat&label=npm&color=CB3837" alt="npm version"></a>
   <a href="https://github.com/huangjuhua-aigc/dsh-a2a/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-2EA44F?style=flat" alt="MIT License"></a>
   <img src="https://img.shields.io/badge/A2A-v1.0%20JSON--RPC-4D6BFE?style=flat" alt="A2A v1.0 JSON-RPC binding">
-  <img src="https://img.shields.io/badge/DSH-0.1.0--rc.6-4493F8?style=flat" alt="Built against DSH 0.1.0-rc.6">
-  <img src="https://img.shields.io/badge/tests-167-2EA44F?style=flat" alt="167 tests">
+  <img src="https://img.shields.io/badge/DSH-0.2.1--rc.2-4493F8?style=flat" alt="Built against DSH 0.2.1-rc.2">
+  <img src="https://img.shields.io/badge/tests-217-2EA44F?style=flat" alt="217 tests">
 </p>
 
 `dsh-a2a-server` makes a [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)
@@ -30,14 +30,21 @@ The plugin is **inbound only**: it never connects to another agent. There is no
 client, no peer directory, and no A2A subagent provider. It is a transport
 adapter over `ctx.agents`, not a capability seam.
 
+For a local configuration UI and cross-network access, use the companion
+[Talk2MyAgent setup guide](https://github.com/huangjuhua-aigc/Talk2MyAgent/blob/main/README.en.md).
+See the [deployment and migration guide](https://github.com/huangjuhua-aigc/dsh-a2a/blob/main/docs/public-access-hardening.en.md)
+for visitor permissions, automatic briefings, private owner access and Tailscale.
+
 ## Install
 
 ```sh
-dsh plugin --profile web add dsh-a2a-server
+dsh plugin --profile web add dsh-a2a-server@0.4.0
 ```
 
 `dsh plugin` forwards to pnpm inside the profile directory and appends this
 bundle to `dsh.profile.bundles`, because the package declares `dsh.bundle`.
+Since DSH v0.2.1-alpha.1, `--profile` must come before any pnpm arguments —
+the forms above already do.
 
 To work from a checkout instead, point it at the directory:
 
@@ -50,13 +57,28 @@ dsh plugin --profile web add ./path/to/dsh-a2a-server
 | `ctx.agents` | `dsh-base` |
 | `ctx.credentials` | `dsh-base` |
 | `ctx.webServer` | **`dsh-web-app`** |
-| `ctx.sessionProjections` (optional) | composition; enables `GetTask` after settlement |
+| `ctx.tools` and `ctx.systemPrompt` | required visitor tool and prompt isolation services |
+| `ctx.sessionProjections` (optional) | composition; exposes task lifecycle projections |
 
-The plugin stays PENDING until the three required services exist. `ctx.webServer`
+The plugin stays PENDING until all required services exist. `ctx.webServer`
 ships in `dsh-web-app` rather than `dsh-base`, so a `headless` profile needs
 `@deepseek-ai/dsh-host-webserver` mounted before this bundle serves anything.
 `dsh --profile <name> --dump-config` prints the composed rows.
 
+### Upgrading to 0.4.0
+
+Version 0.4.0 requires DSH `>=0.2.1-rc.2 <0.3.0`. Stop the agent, install
+`dsh-a2a-server@0.4.0` into its existing profile, then restart it. Owner RPC and
+monitoring now use authenticated local IPC; update the companion Portal as well.
+Visitors retain chat and scoped workspace reads, while other tools are denied.
+An empty `trustedPeers: []` denies all visitors. Task results persist across
+restart within the configured retention window.
+
+The current [Talk2MyAgent Portal](https://github.com/huangjuhua-aigc/Talk2MyAgent)
+configures default-on hourly briefings with one persistent switch. The plugin
+alone does not enable automatic briefing without its `briefing` configuration.
+Portal automatically prepares Microsandbox for per-visitor isolation. Public data is copied read-only, excluding `node_modules`; private files persist on independent visitor disks. Idle VMs pause after 30 seconds and stop after 10 minutes. Existing standalone configurations keep their selected execution mode; installing the plugin alone does not enable a VM. See the [sandbox guide](docs/visitor-isolation.en.md) and [0.4.0 release notes](https://github.com/huangjuhua-aigc/dsh-a2a/blob/main/CHANGELOG.md).
+
 ## Quick start
 
 The bundled example composition runs a real model and a listening server.
@@ -103,7 +125,7 @@ curl -s http://127.0.0.1:9922/a2a \
 | `A2A_PEERS` | `alice` | `name[:token]` list; a token is required for each |
 | `A2A_PORT` | `9900` | Listening port |
 | `A2A_SEND_MODE` | `block` | `block` or `immediate` |
-| `A2A_WORKSPACE_ROOT` | temp dir | Parent of the per-peer working directories |
+| `A2A_WORKSPACE_ROOT` | temp dir | Shared public data; visitor workspaces live outside this root |
 | `DEEPSEEK_MODEL` | `deepseek-v4-flash` | Model id requested from the adapter |
 
 A one-shot probe runs 67 checks against a live server and exits non-zero on any
@@ -121,13 +143,15 @@ node example/probe.mjs http://127.0.0.1:9922 demo123
 | `/.well-known/agent-card.json` | GET | Public by default |
 | `/.well-known/agent.json` | GET | Public by default |
 | `{basePath}` (default `/a2a`) | POST | Bearer required |
+| `{basePath}/admin/contexts[/<id>]` | GET | Local IPC only + admin token; never registered on public HTTP |
+| `{basePath}/admin/prepare-stop` | POST | Local IPC + admin token; drain tasks and stop sandboxes before terminating DSH |
 
 | JSON-RPC method | Status |
 | --- | --- |
 | `SendMessage` | Waiting negotiated per request |
 | `SendStreamingMessage` | SSE |
 | `GetTask` | Idempotent; answers after settlement |
-| `ListTasks` | Cursor-paginated, filterable, resident contexts only |
+| `ListTasks` | Cursor-paginated, filterable, live and retained tasks |
 | `CancelTask` | Cancels the running turn |
 | `SubscribeToTask` | Live stream; `-32004` on a terminal task |
 | `GetExtendedAgentCard` | Extra skills for an authenticated peer; `-32007` when unconfigured |
@@ -179,17 +203,17 @@ another peer answers exactly as an absent one.
 
     card:
       name: dsh-harness
-      description: Reads code, runs commands, reports findings.
+      description: Answers questions using code and text in the authorized directory.
       public: true
       skills:
         - id: general
           name: general
-          description: General-purpose task execution.
+          description: Chat and scoped file reading.
           tags: [coding, research]
       extendedSkills:                             # authenticated peers only
         - id: internal
           name: internal diagnostics
-          description: Reports harness internals.
+          description: Explains project documentation from the authorized directory.
           tags: [internal]
       provider:
         organization: Example Inc.
@@ -226,16 +250,33 @@ another peer answers exactly as an absent one.
 | `card.skills` | `[]` | Declared skills; falls back to one `general` entry |
 | `card.extendedSkills` | `[]` | Skills revealed only through `GetExtendedAgentCard` |
 | `peers` | `{}` | Identity → credential **reference name** |
-| `trustedPeers` | all authenticated | Allow-list of identities that may run tasks |
+| `trustedPeers` | all authenticated | Access allow-list for conversation and scoped file reads; `[]` denies everyone |
 | `rateLimitPerMinute` | `60` | Sliding window per identity |
 | `maxContextTurns` | `5` | Messages accepted per context before `rejected` |
 | `sendMode` | `block` | Default when the client sends no `returnImmediately` |
-| `blockTimeoutMs` | `60000` | After which a blocking request is declined |
+| `blockTimeoutMs` | `60000` | Maximum blocking wait; returns the current task on timeout so the client can poll |
 | `contextIdleTtlMs` | `1800000` | Idle time before a context's agent is released |
 | `maxResidentContexts` | `64` | Ceiling on resident contexts |
-| `isolation.workspaceMode` | `per-peer` | `per-peer` or `shared` |
-| `isolation.workspaceRoot` | — | Required; parent directory or shared cwd |
-| `isolation.peerWorkspaces` | `{}` | Per-identity working-directory override |
+| `maxConcurrentTasks` / `maxConcurrentTasksPerPeer` | `8` / `2` | Atomic task admission; excess requests receive 429 |
+| `maxTasksPerPeerPerDay` | `200` | Persisted task allowance per identity per UTC day |
+| `taskTimeoutMs` | `120000` | Cancels execution when its deadline expires |
+| `maxModelCallsPerTask` / `maxOutputTokens` | `8` / `4096` | Model request and per-request output limits |
+| `maxInputChars` / `maxOutputChars` | `32000` / `64000` | Input/output text limits |
+| `streamHeartbeatMs` / `maxStreamsPerTask` | `15000` / `4` | Heartbeat interval and subscription cap |
+| `maxStreamBufferBytes` | `262144` | Disconnect a stream whose buffered frame exceeds the cap |
+| `storage.directory` | `~/.dsh-a2a/<deployment-key>` | Private checkpoints; one process per directory |
+| `storage.retentionMs` / `storage.maxContexts` | `86400000` / `256` | Retention after last activity, and maximum stored contexts |
+| `storage.maxContextBytes` | `4000000` | Maximum checkpoint bytes per context |
+| `isolation.workspaceMode` | `per-peer` | Legacy migration field; visitors now have an external private cwd |
+| `isolation.workspaceRoot` | — | Required; shared public read-only data root |
+| `isolation.peerWorkspaces` | `{}` | Legacy per-identity read-root override |
+| `isolation.privateRoot` | deployment-specific home directory | Private workspace parent, outside public data |
+| `isolation.execution` | `read-only` | Select `microsandbox` for per-visitor VMs (Portal default); legacy `docker` also supported |
+| `preamble.files` | `[".hop/handoff.md"]` | Host briefing files (**agent-level**: resolved against the workspace root and shared by every visitor; absolute paths pass through), merged into each context's first message; absent files are skipped |
+| `briefing.prompt` | — | Optional single-update instruction executed as the bounded local owner at startup and hourly; configured by Portal, requires owner administration |
+| `briefing.settingsFile` | — | Absolute path to a JSON `{ "enabled": boolean }` preference; absent file means enabled, observed every 5 seconds. Disabling preserves the current briefing and lets active work finish; restart timing is persisted |
+| `admin.tokenEnv` | — | Credential reference for local owner and monitoring requests; rejected by public RPC |
+| `admin.socketPath` | deployment-specific | Windows named pipe or private Unix socket for owner RPC and monitoring |
 | `push.enabled` | `false` | Reserved; see [Boundaries](#boundaries) |
 
 Configuration is refused at load when `isolation.workspaceRoot` is absent, a peer
@@ -254,7 +295,8 @@ peers:
 
 ```yaml
 # ~/.dsh/.credentials.yaml
-A2A_PEER_ALICE: <32-byte-hex-from-openssl-rand>
+refs:
+  A2A_PEER_ALICE: <32-byte-hex-from-openssl-rand>
 ```
 
 `ctx.credentials` resolves the reference per request across four layers — the
@@ -270,11 +312,28 @@ identities.
 | --- | --- | --- |
 | Model context | One peer's conversation cannot enter another's model request | Separate `contextId` → separate Session → separate log |
 | Protocol access | A peer cannot read, continue, or cancel another's context or task | Ownership by authenticated identity |
-| Tooling | A peer's agent cannot use tools to read another peer's session | `workspaceMode: per-peer` |
-
-`per-peer` (the default) derives each identity's `cwd` from `workspaceRoot`.
-`shared` places every peer in one directory, which suits peers collaborating on a
-single repository; under it, files written by one peer are readable by another.
+| Tooling | Only the scoped `read_file` is available; no writes, shell, network or cross-session tools | Inherited-tool masking, scoped reader, and execution guard |
+| Prompt context | Public agents have a dedicated system prompt and suppress optional host runtime context | Scoped complete prompt and context suppression |
+
+Visitor working directories now live outside `workspaceRoot`. The selected root
+contains public data; `read_file` defaults to it and accepts `root: "workspace"`
+for the current visitor's files. Portal automatically prepares Microsandbox:
+one VM per visitor, read-only public projections and persistent private disks.
+Idle VMs pause after 30 seconds and stop after 10 minutes, retaining files.
+Backend conversation storage is not mounted. See [setup and limits](docs/visitor-isolation.en.md).
+
+`read_file({"path":"."})` lists the root's entries. A file path reads UTF-8 text;
+`offset` (1-based) and `limit` page lines or directory entries. Reads are bounded
+to 2 MiB files, 32,000 returned characters and 500 lines/entries per call; directory
+scans cover at most 1,000 entries. Binary/office-document extraction is not yet
+implemented. Canonical path checks refuse escapes; symlinks, junctions, hard
+links and Windows alternate data streams are rejected. No shell is invoked.
+`preamble.files` continues to provide an optional opening briefing.
+
+Owner RPC uses the same `/a2a` path on **local IPC**, authenticated with the admin
+token. It retains the standard caretaker preset. The public HTTP listener accepts
+only visitor credentials and never mounts the monitoring API. See the
+[migration and deployment notes](https://github.com/huangjuhua-aigc/dsh-a2a/blob/main/docs/public-access-hardening.en.md).
 
 ## Boundaries
 
@@ -285,13 +344,20 @@ single repository; under it, files written by one peer are readable by another.
 - No `stateTransitionHistory`, protocol extensions, or card signatures.
 - Streaming emits committed assistant messages. Per-chunk streaming is not
   implemented.
-- No orphan-task watchdog: a task wedged non-terminal stays that way.
-- Cross-session tool denial is not implemented; isolation rests on
-  `workspaceMode`.
+- Execution deadlines cancel the agent. Admission remains occupied until the
+  underlying adapter finishes cancellation; an adapter ignoring AbortSignal
+  needs process-level supervision. These limits are not a currency budget.
+- Only rooted `read_file` is enabled for visitors. Other tools require separate
+  capability work; changing the sandbox mode does not grant those tools. This
+  application-level file reader is not an OS sandbox against a malicious local
+  administrator mutating the filesystem.
 - A token ceiling settles a task as `completed`; the real turn ending travels in
   `Task.metadata.dsh.stopReason`, which A2A's state enum cannot express.
-- Task state survives settlement but not a process restart: session persistence
-  is not composed, so the projection has no log to cold-fold after a reboot.
+- Task results and idle conversation history survive eviction/restart within
+  the retention window. Interrupted tasks become failed and are never replayed.
+  Cold restoration creates a new harness session behind the stable contextId.
+- One task may run per context; concurrent submissions receive 409. Message IDs
+  are not deduplication keys: proxies must not blindly retry submissions.
 - `ctx.webServer` provides no TLS. Any non-loopback exposure belongs behind a
   reverse proxy.
 - A configuration change restarts the plugin and cancels in-flight tasks.
@@ -312,6 +378,10 @@ src/
 ├── tasks.ts           task slots and the three-stage turn correlation
 ├── projection.ts      the a2aTask fold over the session log
 ├── security.ts        authentication, rate limiting, defanging, redaction
+├── workspace-read.ts  bounded read_file within the authorized data root
+├── management.ts      private owner RPC and monitoring over local IPC
+├── state.ts           durable task and conversation checkpoints
+├── briefing.ts        hourly briefing updates and persistent scheduling
 ├── config.ts          schema plus the cross-field checks that fail at load
 └── types.ts           declaration merges into SessionEventMap / MessageSourceMap
 ```
@@ -327,17 +397,19 @@ carries the committed output, so the fold serves the answer without reaching
 back into message history.
 
 **Residency is explicit.** HTTP has no connection lifetime, so each `contextId`
-maps to an Activation evicted when idle, leaving the durable Session behind.
+maps to an Activation evicted when idle. Private checkpoints retain task results
+and conversation history; cold restoration creates a new harness session.
 
 ## Development
 
 ```sh
 pnpm install
 pnpm typecheck
-pnpm test       # 167 tests across 10 files
+pnpm test       # protocol, lifecycle, security and workspace-read regressions
 pnpm serve      # a listening server
 pnpm probe      # 67 checks against a running server
 pnpm build      # emit lib/
+pnpm test:package # verify imports with only declared runtime packages
 ```
 
 The end-to-end suites boot a real Cordis composition with a real agent loop and
@@ -357,7 +429,10 @@ capability seams this plugin consumes. This project supplies:
 - Per-peer authentication, isolation, and workspace policy
 
 The harness is pre-release and does not promise compatibility across renames or
-repackaging, so peer dependencies are pinned exactly to `0.1.0-rc.6`.
+repackaging, so compatibility is declared through `engines.dsh`
+(`>=0.2.1-rc.2 <0.3.0`) plus range-bounded `@deepseek-ai/dsh-*` peer
+dependencies: an install preflight refuses any combination the plugin was not
+built against, and the range admits every 0.2.x patch that follows.
 
 ## Community
 
@@ -373,3 +448,21 @@ If the code has expired, open an issue and we will refresh it.
 ## License
 
 MIT
+## Public relay integration
+
+Talk2MyAgent Portal now supports automatic relay registration, a background Connector, publication controls and visitor invitations. This plugin continues to provide the local A2A service with its existing workspace and briefing rules. Relay is deployed independently. See [implementation and tests](docs/a2a-relay-implementation.zh-CN.md) and [Portal English guide](https://github.com/huangjuhua-aigc/Talk2MyAgent/blob/main/docs/relay.en.md).
+
+### Relay integration test
+
+`tests/relay.integration.spec.ts` is skipped unless **both** variables point at local checkouts:
+
+- `A2A_RELAY_SOURCE` — the [a2a-relay-server](https://github.com/huangjuhua-aigc/a2a-relay-server) repository root
+- `A2A_CONNECTOR_SOURCE` — Talk2MyAgent's `packages/a2a-connector` directory (run `pnpm install` in Talk2MyAgent first)
+
+```sh
+A2A_RELAY_SOURCE=/path/to/a2a-relay-server \
+A2A_CONNECTOR_SOURCE=/path/to/Talk2MyAgent/packages/a2a-connector \
+pnpm vitest run tests/relay.integration.spec.ts
+```
+
+It uses a stub model, temporary data and dynamic ports; no API key or DSH install is needed.

package/README.zh-CN.md

@@ -16,8 +16,8 @@
   <a href="https://www.npmjs.com/package/dsh-a2a-server"><img src="https://img.shields.io/npm/v/dsh-a2a-server?style=flat&label=npm&color=CB3837" alt="npm 版本"></a>
   <a href="https://github.com/huangjuhua-aigc/dsh-a2a/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-2EA44F?style=flat" alt="MIT License"></a>
   <img src="https://img.shields.io/badge/A2A-v1.0%20JSON--RPC-4D6BFE?style=flat" alt="A2A v1.0 JSON-RPC 绑定">
-  <img src="https://img.shields.io/badge/DSH-0.1.0--rc.6-4493F8?style=flat" alt="基于 DSH 0.1.0-rc.6 构建">
-  <img src="https://img.shields.io/badge/tests-167-2EA44F?style=flat" alt="167 项测试">
+  <img src="https://img.shields.io/badge/DSH-0.2.1--rc.2-4493F8?style=flat" alt="基于 DSH 0.2.1-rc.2 构建">
+  <img src="https://img.shields.io/badge/tests-217-2EA44F?style=flat" alt="217 项测试">
 </p>
 
 `dsh-a2a-server` 让 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)
@@ -30,12 +30,16 @@ subagent provider。它是 `ctx.agents` 之上的传输适配层，不是能力
 
 ## 安装
 
+需要本机配置界面或跨网络访问时，先看配套 [Talk2MyAgent 使用说明](https://github.com/huangjuhua-aigc/Talk2MyAgent)。
+访客读取权限、自动简报、主人 IPC 与 Tailscale 部署详见[部署与迁移指南](https://github.com/huangjuhua-aigc/dsh-a2a/blob/main/docs/public-access-hardening.md)。
+
 ```sh
-dsh plugin --profile web add dsh-a2a-server
+dsh plugin --profile web add dsh-a2a-server@0.4.0
 ```
 
 `dsh plugin` 会在 profile 目录里转发给 pnpm，并把这个 bundle 追加进
-`dsh.profile.bundles`——因为包中声明了 `dsh.bundle`。
+`dsh.profile.bundles`——因为包中声明了 `dsh.bundle`。自 DSH v0.2.1-alpha.1 起，
+`--profile` 必须放在所有 pnpm 参数之前——上面的写法已经是正确的。
 
 若想直接使用本地检出，把路径指过去即可：
 
@@ -48,12 +52,27 @@ dsh plugin --profile web add ./path/to/dsh-a2a-server
 | `ctx.agents` | `dsh-base` |
 | `ctx.credentials` | `dsh-base` |
 | `ctx.webServer` | **`dsh-web-app`** |
-| `ctx.sessionProjections`（可选） | 组合层；启用后 `GetTask` 在任务结算后仍可应答 |
+| `ctx.tools` 和 `ctx.systemPrompt` | 必需的访客工具及提示词隔离服务 |
+| `ctx.sessionProjections`（可选） | 组合层；提供任务生命周期投影 |
 
-三个必需服务齐备之前，插件保持 PENDING。`ctx.webServer` 由 `dsh-web-app` 提供而不在
+必需服务齐备之前，插件保持 PENDING。`ctx.webServer` 由 `dsh-web-app` 提供而不在
 `dsh-base` 中，因此 `headless` profile 需要先挂载 `@deepseek-ai/dsh-host-webserver`。
 `dsh --profile <name> --dump-config` 可以打印组合出来的配置行。
 
+### 升级到 0.4.0
+
+0.4.0 适配 DSH `>=0.2.1-rc.2 <0.3.0`。先停止 agent，将
+`dsh-a2a-server@0.4.0` 安装到原有 profile，再重新启动；配套 Portal 也需更新。
+主人 RPC 和监控已改为需要认证的本机 IPC，公网 HTTP 不接受主人凭据。
+访客可聊天并读取授权目录，其他工具关闭；空白名单 `trustedPeers: []` 拒绝所有访客。
+任务结果与空闲会话在保留期内可跨驱逐和重启恢复。
+
+新版 [Talk2MyAgent Portal](https://github.com/huangjuhua-aigc/Talk2MyAgent) 默认开启每小时简报更新，
+用一个开关控制，完成后直接写入 `.hop/handoff.md`。单独安装协议插件而未配置 `briefing`
+不会自动执行简报任务。
+
+Portal 自动准备 Microsandbox，为每位访客提供独立沙箱。公共资料使用只读副本并排除 `node_modules`，私有文件保存在独立持久磁盘；空闲 30 秒暂停、10 分钟停止。独立 DSH 的旧配置保留原执行模式，安装插件本身不会自动启用 VM。详见[沙箱指南](docs/visitor-isolation.md)和 [0.4.0 发布说明](https://github.com/huangjuhua-aigc/dsh-a2a/blob/main/CHANGELOG.zh-CN.md)。
+
 ## 快速开始
 
 仓库自带的示例组合会运行真实模型并启动一个监听服务。
@@ -99,7 +118,7 @@ curl -s http://127.0.0.1:9922/a2a \
 | `A2A_PEERS` | `alice` | `名字[:token]` 列表；每个 peer 都必须有 token |
 | `A2A_PORT` | `9900` | 监听端口 |
 | `A2A_SEND_MODE` | `block` | `block` 或 `immediate` |
-| `A2A_WORKSPACE_ROOT` | 临时目录 | per-peer 工作目录的父目录 |
+| `A2A_WORKSPACE_ROOT` | 临时目录 | 公共资料目录；访客工作区在此目录之外 |
 | `DEEPSEEK_MODEL` | `deepseek-v4-flash` | 向适配器请求的模型 id |
 
 一次性探针会对运行中的服务执行 67 项检查，任何一项不符即以非零码退出：
@@ -116,13 +135,15 @@ node example/probe.mjs http://127.0.0.1:9922 demo123
 | `/.well-known/agent-card.json` | GET | 默认公开 |
 | `/.well-known/agent.json` | GET | 默认公开 |
 | `{basePath}`（默认 `/a2a`） | POST | 必须携带 Bearer |
+| `{basePath}/admin/contexts[/<id>]` | GET | 仅本机 IPC + admin token，公网 HTTP 不挂载 |
+| `{basePath}/admin/prepare-stop` | POST | 仅本机 IPC + admin token；收尾任务、停止沙箱后确认可结束 DSH |
 
 | JSON-RPC 方法 | 状态 |
 | --- | --- |
 | `SendMessage` | 是否等待逐请求协商 |
 | `SendStreamingMessage` | SSE |
 | `GetTask` | 幂等；结算后仍可应答 |
-| `ListTasks` | 游标分页、可过滤；仅覆盖常驻的 context |
+| `ListTasks` | 游标分页、可过滤；包括保留期内的持久化任务 |
 | `CancelTask` | 取消正在执行的 turn |
 | `SubscribeToTask` | 续订活任务；终态任务返回 `-32004` |
 | `GetExtendedAgentCard` | 已认证 peer 可见的额外 skill；未配置时 `-32007` |
@@ -171,12 +192,12 @@ part 是被**删除**而不是做了别名：本服务写出的每一个回包
 
     card:
       name: dsh-harness
-      description: 读代码、执行命令、给出结论。
+      description: 读取授权目录中的代码和资料，回答访客问题。
       public: true
       skills:
         - id: general
           name: general
-          description: 通用任务执行。
+          description: 对话与授权目录内的文件读取。
           tags: [coding, research]
       provider:
         organization: Example Inc.
@@ -213,16 +234,23 @@ part 是被**删除**而不是做了别名：本服务写出的每一个回包
 | `card.skills` | `[]` | 声明的 skills；为空时回退到一条 `general` |
 | `card.extendedSkills` | `[]` | 只对已认证 peer 经 `GetExtendedAgentCard` 公开的 skills |
 | `peers` | `{}` | 身份 → 凭据**引用名** |
-| `trustedPeers` | 全部已认证身份 | 允许执行任务的身份白名单 |
+| `trustedPeers` | 全部已认证身份 | 对话与受限文件读取白名单；`[]` 拒绝所有访客 |
 | `rateLimitPerMinute` | `60` | 按身份的滑动窗口 |
 | `maxContextTurns` | `5` | 单个 context 接受的消息数上限，超出后 `rejected` |
 | `sendMode` | `block` | 客户端未表态时的默认行为 |
-| `blockTimeoutMs` | `60000` | 超过后拒绝继续阻塞 |
+| `blockTimeoutMs` | `60000` | 最长阻塞等待；到期返回任务当前状态，客户端可继续查询 |
 | `contextIdleTtlMs` | `1800000` | context 的 agent 被释放前的空闲时长 |
 | `maxResidentContexts` | `64` | 常驻 context 数量上限 |
-| `isolation.workspaceMode` | `per-peer` | `per-peer` 或 `shared` |
-| `isolation.workspaceRoot` | — | 必填；父目录或共享 cwd |
-| `isolation.peerWorkspaces` | `{}` | 按身份覆盖工作目录 |
+| `isolation.workspaceMode` | `per-peer` | 旧配置迁移字段；访客均使用外置私有 cwd |
+| `isolation.workspaceRoot` | — | 必填；只放公共资料 |
+| `isolation.peerWorkspaces` | `{}` | 旧版按访客覆盖读取根目录 |
+| `isolation.privateRoot` | 用户主目录下按部署分隔 | 公共资料之外的私有工作区父目录 |
+| `isolation.execution` | `read-only` | 设为 `microsandbox` 使用独立访客 VM（Portal 默认）；兼容 `docker` |
+| `preamble.files` | `[".hop/handoff.md"]` | 主人背景简报文件（**agent 级**：相对工作区根目录解析，全体访客共用一份；绝对路径直通），合并进每个 context 的首条访客消息；文件不存在则跳过 |
+| `briefing.prompt` | — | 可选的单次简报更新指令，由 Portal 配置，通过有执行预算的主人 agent 每小时运行 |
+| `briefing.settingsFile` | — | 绝对路径；读取 `{ "enabled": boolean }` 设置，缺省开启，每 5 秒检查 |
+| `admin.tokenEnv` | — | 本机主人 RPC 和监控的凭据引用，公网 RPC 拒绝此凭据 |
+| `admin.socketPath` | 按部署生成 | Windows 命名管道或私有 Unix socket |
 | `push.enabled` | `false` | 保留字段，见[边界](#边界) |
 
 以下情况在加载期即被拒绝：缺少 `isolation.workspaceRoot`；peer 名不匹配
@@ -240,7 +268,8 @@ peers:
 
 ```yaml
 # ~/.dsh/.credentials.yaml
-A2A_PEER_ALICE: <32-byte-hex-from-openssl-rand>
+refs:
+  A2A_PEER_ALICE: <32-byte-hex-from-openssl-rand>
 ```
 
 `ctx.credentials` 在每次请求时跨四层解析该引用——进程环境、托管文档、`<cwd>/.env`、
@@ -254,11 +283,18 @@ A2A_PEER_ALICE: <32-byte-hex-from-openssl-rand>
 | --- | --- | --- |
 | 模型上下文 | 一个 peer 的对话不会进入另一个 peer 的模型请求 | 不同 `contextId` → 不同 Session → 不同 log |
 | 协议访问 | peer 无法读取、续接或取消他人的 context 与任务 | 按认证身份判定归属 |
-| 工具层 | peer 的 agent 无法借工具读取他人的 session | `workspaceMode: per-peer` |
+| 工具层 | 仅提供受控 `read_file`，不开放写入、命令、联网或跨会话工具 | 屏蔽继承工具、专用读取工具、执行校验 |
+| 提示词 | 访客不继承可选的主人个性化提示与运行时上下文 | 独立的公共系统提示词 |
+
+访客 cwd 现在放在 `workspaceRoot` 之外。所选目录只放公共资料，`read_file` 默认读取它，
+传入 `root: "workspace"` 则读取自己的私有工作区。Portal 自动准备 Microsandbox，每位访客独立 VM，
+公共资料副本只读、自己的持久化磁盘可写；空闲 30 秒暂停、10 分钟停止，文件保留，不挂后端聊天记录。
+详见[安装、迁移与隔离边界](docs/visitor-isolation.md)。
 
-`per-peer`（默认）依据 `workspaceRoot` 为每个身份派生独立 `cwd`。`shared` 则把所有 peer
-放进同一个目录，适用于协作维护同一个仓库的场景；此模式下一个 peer 写入的文件对其他 peer
-可读。
+`read_file({"path":"."})` 列出资料目录；文件支持 UTF-8 文本，按 `offset`/`limit`
+分页。单文件上限 2 MiB，单次最多 32000 字符、500 行/项，目录扫描最多 1000 项。
+拒绝越界、符号链接/junction、硬链接和 Windows ADS。主人维护能力使用独立本机 IPC，
+保留可信管理工具，不能从公网入口调用。资源配额的完整配置表见英文 README。
 
 ## 边界
 
@@ -268,12 +304,14 @@ A2A_PEER_ALICE: <32-byte-hex-from-openssl-rand>
   `pushNotifications: false`。
 - 不支持 `stateTransitionHistory`、协议扩展与 Card 签名。
 - 流式只推送已提交的 assistant 消息，未实现逐 chunk 推送。
-- 无孤儿任务看门狗：卡在非终态的任务会一直保持该状态。
-- 未实现跨会话工具拒绝；隔离依赖 `workspaceMode`。
+- 有并发准入、任务期限及模型调用预算；超时后等待底层适配器完成取消才释放执行名额。
+  不响应取消的适配器仍需进程级监管，这些额度不是按货币计费的预算。
+- 访客仅能使用有目录边界的 `read_file`；改变沙箱模式不会自动开放其他工具。
+  该工具边界不替代针对恶意本机管理员的操作系统隔离。
 - 触及 token 上限的任务结算为 `completed`，真实的 turn 结束原因放在
   `Task.metadata.dsh.stopReason`——A2A 的状态枚举无法表达它。
-- 任务状态可以跨结算存活，但无法跨进程重启：未组合 session 持久化，重启后 projection
-  没有日志可供冷折叠。
+- 任务结果与空闲会话在保留期内可跨进程重启恢复；中断的任务标记失败，不重放。
+- 每个 context 同时只允许一个任务，并发提交返回 409；messageId 不是提交去重键。
 - `ctx.webServer` 不提供 TLS。任何非回环地址的暴露都应置于反向代理之后。
 - 修改配置会重启插件并取消进行中的任务。
 
@@ -293,6 +331,10 @@ src/
 ├── tasks.ts           任务槽位与三段式 turn 关联
 ├── projection.ts      在 session log 上折叠出的 a2aTask 读模型
 ├── security.ts        认证、限流、注入去势、外发脱敏
+├── workspace-read.ts  授权目录内受限的 read_file
+├── management.ts      本机 IPC 主人 RPC 与监控
+├── state.ts           持久化任务及对话 checkpoint
+├── briefing.ts        每小时简报更新与持久化调度
 ├── config.ts          schema，以及加载期就会拒绝的跨字段校验
 └── types.ts           向 SessionEventMap / MessageSourceMap 的声明合并
 ```
@@ -306,17 +348,18 @@ src/
 历史。
 
 **驻留是显式管理的。** HTTP 没有连接生命周期，因此每个 `contextId` 对应一个 Activation，
-空闲后被驱逐，持久化的 Session 留在原地。
+空闲后被驱逐。私有 checkpoint 保留任务结果与对话历史，冷恢复时创建新的 harness session。
 
 ## 开发
 
 ```sh
 pnpm install
 pnpm typecheck
-pnpm test       # 10 个文件共 167 项测试
+pnpm test       # 15 个文件共 217 项测试
 pnpm serve      # 启动监听服务
 pnpm probe      # 对运行中的服务执行 67 项检查
 pnpm build      # 产出 lib/
+pnpm test:package # 仅声明运行依赖时验证构建产物导入
 ```
 
 端到端测试会启动真实的 Cordis 组合与真实的 agent loop，并通过 HTTP 驱动它；模型使用
@@ -333,8 +376,10 @@ pnpm build      # 产出 lib/
 - A2A task 与 harness turn 之间的映射
 - 按 peer 的认证、隔离与工作目录策略
 
-harness 处于 pre-release 阶段，不承诺跨重命名或重新打包的兼容性，因此 peer 依赖精确锁定
-在 `0.1.0-rc.6`。
+harness 处于 pre-release 阶段，不承诺跨重命名或重新打包的兼容性，因此兼容性通过
+`engines.dsh`（`>=0.2.1-rc.2 <0.3.0`）加上按 range 声明的 `@deepseek-ai/dsh-*`
+peer 依赖来表达：安装预检会拒绝任何插件未曾适配过的组合，而这个 range 也放行后续
+所有的 0.2.x 补丁版本。
 
 ## 社区交流
 
@@ -349,3 +394,21 @@ harness 处于 pre-release 阶段，不承诺跨重命名或重新打包的兼
 ## 许可
 
 MIT
+## 公网中继集成
+
+Talk2MyAgent Portal 已实现自动注册 Relay、后台 Connector、发布开关和访客邀请。插件仍提供本地 A2A 接口，文件权限和公开简报逻辑保持原样。中继服务单独部署；实现状态与测试命令见 [中继实现记录](docs/a2a-relay-implementation.zh-CN.md)。
+
+### 中继集成测试
+
+`tests/relay.integration.spec.ts` 需要**同时**设置以下两个变量才会运行，否则跳过：
+
+- `A2A_RELAY_SOURCE`：[a2a-relay-server](https://github.com/huangjuhua-aigc/a2a-relay-server) 仓库根目录
+- `A2A_CONNECTOR_SOURCE`：Talk2MyAgent 的 `packages/a2a-connector` 目录（先在 Talk2MyAgent 执行 `pnpm install`）
+
+```sh
+A2A_RELAY_SOURCE=/path/to/a2a-relay-server \
+A2A_CONNECTOR_SOURCE=/path/to/Talk2MyAgent/packages/a2a-connector \
+pnpm vitest run tests/relay.integration.spec.ts
+```
+
+测试使用桩模型、临时数据和动态端口，无需 API 密钥或安装 DSH。