dsh-a2a-server 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+[English](CHANGELOG.md) · [简体中文](CHANGELOG.zh-CN.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,28 @@
+# 更新日志
+
+[English](CHANGELOG.md) · [简体中文](CHANGELOG.zh-CN.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.3.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 from 0.2.x
+
+Version 0.3.0 requires DSH `>=0.2.1-rc.2 <0.3.0`. Stop the agent, install
+`dsh-a2a-server@0.3.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.
+See the [0.3.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 | Authorized visitor data root and parent of per-peer working directories |
 | `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,14 @@ 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 |
 
 | 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 +202,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 +249,31 @@ 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 |
+| `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` | `per-peer` or `shared` |
-| `isolation.workspaceRoot` | — | Required; parent directory or shared cwd |
-| `isolation.peerWorkspaces` | `{}` | Per-identity working-directory override |
+| `isolation.workspaceRoot` | — | Required; authorized shared read-only data root and parent directory or shared cwd |
+| `isolation.peerWorkspaces` | `{}` | Per-identity cwd and authorized read-root override |
+| `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 +292,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 +309,29 @@ 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` |
+| 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 |
 
 `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.
+`shared` places every peer in one directory. These are working-directory choices,
+not filesystem sandboxes. `read_file` reads from the owner-selected
+`workspaceRoot`; a `peerWorkspaces` override restricts that peer to the overridden
+directory. Relative tool paths resolve from this **data root**, not the per-peer
+cwd. These files are available to admitted visitors, so choose the data root
+accordingly. The A2A checkpoint directory is always excluded.
+
+`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 +342,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 +376,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 +395,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 +427,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
 

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.3.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,25 @@ 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.2.x 升级
+
+0.3.0 适配 DSH `>=0.2.1-rc.2 <0.3.0`。先停止 agent，将
+`dsh-a2a-server@0.3.0` 安装到原有 profile，再重新启动；配套 Portal 也需更新。
+主人 RPC 和监控已改为需要认证的本机 IPC，公网 HTTP 不接受主人凭据。
+访客可聊天并读取授权目录，其他工具关闭；空白名单 `trustedPeers: []` 拒绝所有访客。
+任务结果与空闲会话在保留期内可跨驱逐和重启恢复。
+
+新版 [Talk2MyAgent Portal](https://github.com/huangjuhua-aigc/Talk2MyAgent) 默认开启每小时简报更新，
+用一个开关控制，完成后直接写入 `.hop/handoff.md`。单独安装协议插件而未配置 `briefing`
+不会自动执行简报任务。详见 [0.3.0 发布说明](https://github.com/huangjuhua-aigc/dsh-a2a/blob/main/CHANGELOG.zh-CN.md)。
+
 ## 快速开始
 
 仓库自带的示例组合会运行真实模型并启动一个监听服务。
@@ -99,7 +116,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` | 临时目录 | 访客授权资料目录，同时作为 per-peer 工作目录的父目录 |
 | `DEEPSEEK_MODEL` | `deepseek-v4-flash` | 向适配器请求的模型 id |
 
 一次性探针会对运行中的服务执行 67 项检查，任何一项不符即以非零码退出：
@@ -116,13 +133,14 @@ 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 不挂载 |
 
 | JSON-RPC 方法 | 状态 |
 | --- | --- |
 | `SendMessage` | 是否等待逐请求协商 |
 | `SendStreamingMessage` | SSE |
 | `GetTask` | 幂等；结算后仍可应答 |
-| `ListTasks` | 游标分页、可过滤；仅覆盖常驻的 context |
+| `ListTasks` | 游标分页、可过滤；包括保留期内的持久化任务 |
 | `CancelTask` | 取消正在执行的 turn |
 | `SubscribeToTask` | 续订活任务；终态任务返回 `-32004` |
 | `GetExtendedAgentCard` | 已认证 peer 可见的额外 skill；未配置时 `-32007` |
@@ -171,12 +189,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 +231,21 @@ 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.workspaceRoot` | — | 必填；授权资料目录，同时作为访客 cwd 的父目录或共享 cwd |
+| `isolation.peerWorkspaces` | `{}` | 按身份覆盖工作目录和授权读取范围 |
+| `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 +263,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 +278,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`，不开放写入、命令、联网或跨会话工具 | 屏蔽继承工具、专用读取工具、执行校验 |
+| 提示词 | 访客不继承可选的主人个性化提示与运行时上下文 | 独立的公共系统提示词 |
+
+`per-peer`（默认）依据 `workspaceRoot` 为每个身份派生独立 `cwd`；`shared` 使用同一个目录。
+这只是工作目录策略，不是文件系统沙箱。`read_file` 的读取范围默认是用户选择的
+`workspaceRoot`，有 `peerWorkspaces` 覆盖时限制为该访客的专属目录。工具相对路径从
+这个资料目录解析；插件私有状态目录始终排除。
 
-`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 +299,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 +326,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 +343,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 +371,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 补丁版本。
 
 ## 社区交流
 

package/cordis.patch.yml

@@ -7,12 +7,15 @@
 # REQUIRES ctx.webServer, which ships in `dsh-web-app`, NOT in `dsh-base`. On a
 # profile without it this row loads but stays PENDING (Cordis holds a plugin
 # whose injected services are absent), so nothing serves and nothing errors.
+#
+# NOTE: keep this file plain YAML — the installer's package validation parses
+# it with a strict loader that rejects `!!js` expressions, even though the
+# runtime overlay loader accepts them.
 - insert:
     - id: a2a-server
       name: dsh-a2a-server
       config:
         basePath: /a2a
-        protocolVersion: '0.3.0'
         card:
           name: dsh-harness
           description: A DeepSeek Harness agent reachable over A2A.
@@ -20,11 +23,12 @@
           skills: []
         peers: {}
         isolation:
-          # Default posture is isolation: each peer gets its own working
-          # directory, which also makes the cwd-equality authority in
-          # cross-session tooling separate peers for free. A deployment whose
-          # peers collaborate on one repository must say so explicitly.
+          # Each peer gets its own working directory. This is not a filesystem
+          # sandbox: read_file separately restricts reads to the selected root,
+          # or to a peerWorkspaces override. Other visitor tools are disabled.
+          # This placeholder is overridden by any real deployment layer (the
+          # console's overlay sets it per agent); supply an absolute path.
           workspaceMode: per-peer
-          workspaceRoot: !!js `${process.env.DSH_HOME ?? process.env.HOME}/a2a-workspaces`
+          workspaceRoot: /srv/dsh/a2a
         push:
           enabled: false

package/lib/briefing.d.ts

@@ -0,0 +1,39 @@
+export declare const BRIEFING_INTERVAL_MS: number;
+interface LegacyBriefingScheduler {
+    catalog(): Promise<Array<{
+        id: string;
+        sessionId: string;
+        title: string;
+        prompt: string;
+    }>>;
+    delete(request: {
+        id: string;
+        sessionId: string;
+    }): Promise<unknown>;
+}
+/** Retire only the old Portal-generated job for this exact project. */
+export declare function retireLegacyBriefing(scheduler: LegacyBriefingScheduler | undefined, root: string): Promise<void>;
+export declare class AutomaticBriefing {
+    private readonly options;
+    private timer;
+    private closed;
+    private running;
+    private enabled;
+    private nextRunAt;
+    private readonly stateFile;
+    constructor(options: {
+        settingsFile: string;
+        stateDirectory: string;
+        run: () => Promise<void>;
+        warn: (message: string) => void;
+        now?: () => number;
+    });
+    private save;
+    private readEnabled;
+    /** Polling also observes an off/on switch without restarting the agent. */
+    tick(): Promise<void>;
+    start(): void;
+    stop(): void;
+}
+export {};
+//# sourceMappingURL=briefing.d.ts.map

package/lib/briefing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"briefing.d.ts","sourceRoot":"","sources":["../src/briefing.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,oBAAoB,QAAiB,CAAA;AAGlD,UAAU,uBAAuB;IAC/B,OAAO,IAAI,OAAO,CAAC,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC,CAAA;IAC3F,MAAM,CAAC,OAAO,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;CACrE;AAED,uEAAuE;AACvE,wBAAsB,oBAAoB,CAAC,SAAS,EAAE,uBAAuB,GAAG,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAUtH;AAED,qBAAa,iBAAiB;IAQhB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAPpC,OAAO,CAAC,KAAK,CAA4C;IACzD,OAAO,CAAC,MAAM,CAAQ;IACtB,OAAO,CAAC,OAAO,CAAQ;IACvB,OAAO,CAAC,OAAO,CAAO;IACtB,OAAO,CAAC,SAAS,CAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAQ;gBAEL,OAAO,EAAE;QACpC,YAAY,EAAE,MAAM,CAAA;QACpB,cAAc,EAAE,MAAM,CAAA;QACtB,GAAG,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;QACxB,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAA;QAC/B,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;KACnB;IAWD,OAAO,CAAC,IAAI;IAQZ,OAAO,CAAC,WAAW;IAWnB,2EAA2E;IACrE,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAmB3B,KAAK,IAAI,IAAI;IAOb,IAAI,IAAI,IAAI;CAIb"}