dsh-a2a-server 0.1.1 → 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

@@ -15,14 +15,14 @@
 <p align="center">
   <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-v0.3.0%20JSON--RPC-4D6BFE?style=flat" alt="A2A v0.3.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-129-2EA44F?style=flat" alt="129 tests">
+  <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.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)
 agent reachable over the [A2A (Agent2Agent)](https://a2a-protocol.org) protocol. It
-serves an Agent Card at a well-known URI and implements the **v0.3.0 JSON-RPC
+serves an Agent Card at a well-known URI and implements the **v1.0 JSON-RPC
 binding**, so any compliant peer that knows the deployment's URL can discover the
 agent and submit tasks to it.
 
@@ -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 `tasks/get` 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.
@@ -93,9 +115,9 @@ curl -s http://127.0.0.1:9922/.well-known/agent-card.json
 curl -s http://127.0.0.1:9922/a2a \
   -H "authorization: Bearer demo123" \
   -H 'content-type: application/json' \
-  -d '{"jsonrpc":"2.0","id":1,"method":"message/send","params":{
-        "message":{"kind":"message","messageId":"m1","role":"user",
-                   "parts":[{"kind":"text","text":"hello"}]}}}'
+  -H 'a2a-version: 1.0'   -d '{"jsonrpc":"2.0","id":1,"method":"SendMessage","params":{
+        "message":{"messageId":"m1","role":"ROLE_USER",
+                   "parts":[{"text":"hello"}]}}}'
 ```
 
 | Variable | Default | Meaning |
@@ -103,10 +125,10 @@ 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 48 checks against a live server and exits non-zero on any
+A one-shot probe runs 67 checks against a live server and exits non-zero on any
 mismatch:
 
 ```sh
@@ -121,22 +143,44 @@ 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 | v1.0 alias | Status |
+| JSON-RPC method | Status |
+| --- | --- |
+| `SendMessage` | Waiting negotiated per request |
+| `SendStreamingMessage` | SSE |
+| `GetTask` | Idempotent; answers after settlement |
+| `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 |
+| `*TaskPushNotificationConfig` | `-32003` |
+
+**Only A2A v1.0 is served.** The v0.3 method names, `kind` discriminators,
+lowercase enums, and nested `file` parts are gone rather than aliased: every
+reply this server writes is v1.0 JSON, which a v0.3 client could not read, so
+answering a v0.3 request would fail further from its cause than refusing it. A
+retired method answers `-32601` naming its replacement, and an explicit
+`A2A-Version: 0.3` answers `-32009` (`VersionNotSupportedError`). A request with
+no `A2A-Version` header is served as 1.0 — the only version this interface
+declares on its card.
+
+What that means concretely, against v0.3:
+
+| Concern | v0.3 | v1.0 as served here |
 | --- | --- | --- |
-| `message/send` | `SendMessage` | Blocking negotiated per request |
-| `message/stream` | `SendStreamingMessage` | SSE |
-| `tasks/get` | `GetTask` | Idempotent; answers after settlement |
-| `tasks/cancel` | `CancelTask` | Cancels the running turn |
-| `tasks/resubscribe` | `SubscribeToTask` | Live stream, or one terminal frame |
-| `tasks/pushNotificationConfig/*` | `*TaskPushNotificationConfig` | `-32003` |
-| `tasks/list` | `ListTasks` | `-32601` |
-| `agent/getAuthenticatedExtendedCard` | `GetExtendedAgentCard` | `-32601` |
-
-Both dialects are accepted. v0.3 (`message/send`, `"working"`, `kind`-tagged
-parts) is the mainline; the v1.0 spellings (`SendMessage`, `TASK_STATE_WORKING`,
-member-presence parts) are normalized inbound and rendered back in whichever
-dialect the request used.
+| Task reference | `params.taskId` | `params.id` |
+| `SendMessage` result | bare `Task` | `{ "task": … }` |
+| Task state | `"working"` | `"TASK_STATE_WORKING"` |
+| Message role | `"user"` | `"ROLE_USER"` |
+| Part | `{"kind":"text","text":…}` | `{"text":…}`; file parts flatten to `url`/`raw`/`filename`/`mediaType` |
+| Stream frame | `{"kind":"status-update",…,"final":true}` | `{"statusUpdate":{…}}`; the stream's close is the terminal signal |
+| Stream opening | a non-final status update | the `Task` object itself |
+| Wait control | `configuration.blocking` | `configuration.returnImmediately` (inverted; blocking is the default) |
+| Card endpoint | `url` + `preferredTransport` | `supportedInterfaces[]`, each carrying its own `protocolVersion` |
+| Card auth | `securitySchemes` + `security` | schemes wrapped in `httpAuthSecurityScheme`; `securityRequirements` |
+| Extended card | `supportsAuthenticatedExtendedCard` | `capabilities.extendedAgentCard` |
+| A2A error detail | none | `error.data[]` carrying a `google.rpc.ErrorInfo` with `reason` and `domain` |
 
 Inbound messages may carry text, file, and data parts. File and data parts are
 rendered into the model's context as bracketed references. Replies are text.
@@ -153,19 +197,23 @@ another peer answers exactly as an absent one.
   config:
     basePath: /a2a
     publicUrl: https://agents.example.com/a2a   # advertised on the card
-    protocolVersion: 0.3.0
     provider: deepseek-official
     model: deepseek-v4-flash
 
     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: Explains project documentation from the authorized directory.
+          tags: [internal]
       provider:
         organization: Example Inc.
         url: https://example.com
@@ -196,21 +244,36 @@ another peer answers exactly as an absent one.
 | --- | --- | --- |
 | `basePath` | `/a2a` | JSON-RPC route |
 | `publicUrl` | derived from `Host` | Routable URL published on the card |
-| `protocolVersion` | `0.3.0` | Version advertised on the card |
 | `provider` · `model` | — | Model route for every agent this server creates |
 | `card.public` | `true` | Serve the card without a credential |
 | `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 states no preference |
-| `blockTimeoutMs` | `60000` | After which a blocking request is declined |
+| `sendMode` | `block` | Default when the client sends no `returnImmediately` |
+| `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
@@ -229,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
@@ -245,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
 
@@ -257,17 +339,23 @@ single repository; under it, files written by one peer are readable by another.
 - JSONRPC binding only. gRPC and HTTP+JSON are not served, and the card says so.
 - Push notifications are not implemented. `push.enabled` selects which error the
   push methods return; the card advertises `pushNotifications: false`.
-- No extended Agent Card, `stateTransitionHistory`, protocol extensions, or card
-  signatures.
+- 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.
@@ -277,8 +365,8 @@ single repository; under it, files written by one peer are readable by another.
 ```
 src/
 ├── protocol/          dependency-free library: no Cordis, no HTTP, no harness
-│   ├── wire.ts        the A2A vocabulary, normalized to v0.3 spelling
-│   ├── normalize.ts   v0.3 <-> v1.0 dialect translation, both directions
+│   ├── wire.ts        the A2A v1.0 vocabulary: one shape, no translation
+│   ├── parse.ts       inbound parsing and the method table
 │   ├── jsonrpc.ts     framing and the A2A error codes
 │   ├── card.ts        Agent Card construction
 │   └── sse.ts         SSE frame encoding
@@ -288,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
 ```
@@ -303,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       # 129 tests across 9 files
+pnpm test       # protocol, lifecycle, security and workspace-read regressions
 pnpm serve      # a listening server
-pnpm probe      # 48 checks against a running 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
@@ -327,13 +421,16 @@ Built against [deepseek-ai/deepseek-harness](https://github.com/deepseek-ai/deep
 The official project supplies the agent runtime, the plugin system, and the
 capability seams this plugin consumes. This project supplies:
 
-- The A2A v0.3.0 JSON-RPC binding, served inbound
-- Agent Card construction and dialect normalization
+- The A2A v1.0 JSON-RPC binding, served inbound
+- Agent Card construction and inbound request parsing
 - Mapping between A2A tasks and harness turns
 - 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