dsh-a2a-server 0.1.1 → 0.3.0

package/README.zh-CN.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 版本"></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 绑定">
-  <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-129-2EA44F?style=flat" alt="129 项测试">
+  <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.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)
 上的 agent 可以通过 [A2A（Agent2Agent）](https://a2a-protocol.org)协议被访问。它在
-well-known 路径发布 Agent Card，并实现 **v0.3.0 JSON-RPC 绑定**——任何知道本部署
+well-known 路径发布 Agent Card，并实现 **v1.0 JSON-RPC 绑定**——任何知道本部署
 URL 的合规 peer 都能发现这个 agent 并向它提交任务。
 
 本插件**只做入站**：从不主动连接其他 agent，没有 client、没有 peer 目录、没有 A2A
@@ -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`（可选） | 组合层；启用后 `tasks/get` 在任务结算后仍可应答 |
+| `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)。
+
 ## 快速开始
 
 仓库自带的示例组合会运行真实模型并启动一个监听服务。
@@ -88,9 +105,10 @@ 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"}]}}}'
 ```
 
 | 变量 | 默认值 | 含义 |
@@ -98,10 +116,10 @@ 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 |
 
-一次性探针会对运行中的服务执行 48 项检查，任何一项不符即以非零码退出：
+一次性探针会对运行中的服务执行 67 项检查，任何一项不符即以非零码退出：
 
 ```sh
 pnpm probe                                        # 默认 :9922 / demo123
@@ -115,21 +133,42 @@ 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 方法 | v1.0 别名 | 状态 |
+| JSON-RPC 方法 | 状态 |
+| --- | --- |
+| `SendMessage` | 是否等待逐请求协商 |
+| `SendStreamingMessage` | SSE |
+| `GetTask` | 幂等；结算后仍可应答 |
+| `ListTasks` | 游标分页、可过滤；包括保留期内的持久化任务 |
+| `CancelTask` | 取消正在执行的 turn |
+| `SubscribeToTask` | 续订活任务；终态任务返回 `-32004` |
+| `GetExtendedAgentCard` | 已认证 peer 可见的额外 skill；未配置时 `-32007` |
+| `*TaskPushNotificationConfig` | `-32003` |
+
+**只提供 A2A v1.0。** v0.3 的方法名、`kind` 判别字段、小写枚举、嵌套 `file`
+part 是被**删除**而不是做了别名：本服务写出的每一个回包都是 v1.0 JSON，v0.3
+客户端本就读不懂，所以“应答一个 v0.3 请求”只会让故障离成因更远。已退役的方法回
+`-32601` 并直接告知新名字；显式的 `A2A-Version: 0.3` 回 `-32009`
+（`VersionNotSupportedError`）。不带 `A2A-Version` 头的请求按 1.0 处理——这是本接口
+在 Card 上声明的唯一版本。
+
+具体到线上，与 v0.3 的差异：
+
+| 关注点 | v0.3 | 本服务的 v1.0 |
 | --- | --- | --- |
-| `message/send` | `SendMessage` | 是否阻塞逐请求协商 |
-| `message/stream` | `SendStreamingMessage` | SSE |
-| `tasks/get` | `GetTask` | 幂等；结算后仍可应答 |
-| `tasks/cancel` | `CancelTask` | 取消正在执行的 turn |
-| `tasks/resubscribe` | `SubscribeToTask` | 续订活任务，或给一帧终态 |
-| `tasks/pushNotificationConfig/*` | `*TaskPushNotificationConfig` | `-32003` |
-| `tasks/list` | `ListTasks` | `-32601` |
-| `agent/getAuthenticatedExtendedCard` | `GetExtendedAgentCard` | `-32601` |
-
-两种方言都接受。v0.3（`message/send`、`"working"`、带 `kind` 的 part）是主线；v1.0
-拼写（`SendMessage`、`TASK_STATE_WORKING`、成员存在式 part）在入站时被归一化，并按请求
-所用的方言渲染回去。
+| 任务引用 | `params.taskId` | `params.id` |
+| `SendMessage` 结果 | 裸 `Task` | `{ "task": … }` |
+| 任务状态 | `"working"` | `"TASK_STATE_WORKING"` |
+| 消息角色 | `"user"` | `"ROLE_USER"` |
+| Part | `{"kind":"text","text":…}` | `{"text":…}`；文件 part 展平为 `url`/`raw`/`filename`/`mediaType` |
+| 流帧 | `{"kind":"status-update",…,"final":true}` | `{"statusUpdate":{…}}`；流关闭即终态信号 |
+| 流首帧 | 一帧非终态 status update | `Task` 对象本身 |
+| 等待控制 | `configuration.blocking` | `configuration.returnImmediately`（语义反转，默认等待） |
+| Card 端点 | `url` + `preferredTransport` | `supportedInterfaces[]`，每条自带 `protocolVersion` |
+| Card 鉴权 | `securitySchemes` + `security` | scheme 包在 `httpAuthSecurityScheme` 里；改用 `securityRequirements` |
+| 扩展 Card | `supportsAuthenticatedExtendedCard` | `capabilities.extendedAgentCard` |
+| A2A 错误细节 | 无 | `error.data[]` 携带 `google.rpc.ErrorInfo`，含 `reason` 与 `domain` |
 
 入站消息可携带 text、file、data 三类 part。file 与 data 会以方括号引用的形式进入模型
 上下文。回复为纯文本。
@@ -145,18 +184,17 @@ node example/probe.mjs http://127.0.0.1:9922 demo123
   config:
     basePath: /a2a
     publicUrl: https://agents.example.com/a2a   # 写入 Card 的对外地址
-    protocolVersion: 0.3.0
     provider: deepseek-official
     model: deepseek-v4-flash
 
     card:
       name: dsh-harness
-      description: 读代码、执行命令、给出结论。
+      description: 读取授权目录中的代码和资料，回答访客问题。
       public: true
       skills:
         - id: general
           name: general
-          description: 通用任务执行。
+          description: 对话与授权目录内的文件读取。
           tags: [coding, research]
       provider:
         organization: Example Inc.
@@ -188,21 +226,26 @@ node example/probe.mjs http://127.0.0.1:9922 demo123
 | --- | --- | --- |
 | `basePath` | `/a2a` | JSON-RPC 路由 |
 | `publicUrl` | 由 `Host` 推导 | 写入 Card 的可路由地址 |
-| `protocolVersion` | `0.3.0` | Card 上声明的协议版本 |
 | `provider` · `model` | — | 本服务创建的每个 agent 使用的模型路由 |
 | `card.public` | `true` | 无需凭据即可获取 Card |
 | `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 名不匹配
@@ -220,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`、
@@ -234,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。
 
 ## 边界
 
@@ -246,14 +297,16 @@ A2A_PEER_ALICE: <32-byte-hex-from-openssl-rand>
 - 只提供 JSONRPC 绑定。不提供 gRPC 与 HTTP+JSON，Card 上如实声明。
 - 未实现推送通知。`push.enabled` 仅决定推送方法返回哪个错误码，Card 上声明
   `pushNotifications: false`。
-- 不支持扩展 Agent Card、`stateTransitionHistory`、协议扩展与 Card 签名。
+- 不支持 `stateTransitionHistory`、协议扩展与 Card 签名。
 - 流式只推送已提交的 assistant 消息，未实现逐 chunk 推送。
-- 无孤儿任务看门狗：卡在非终态的任务会一直保持该状态。
-- 未实现跨会话工具拒绝；隔离依赖 `workspaceMode`。
+- 有并发准入、任务期限及模型调用预算；超时后等待底层适配器完成取消才释放执行名额。
+  不响应取消的适配器仍需进程级监管，这些额度不是按货币计费的预算。
+- 访客仅能使用有目录边界的 `read_file`；改变沙箱模式不会自动开放其他工具。
+  该工具边界不替代针对恶意本机管理员的操作系统隔离。
 - 触及 token 上限的任务结算为 `completed`，真实的 turn 结束原因放在
   `Task.metadata.dsh.stopReason`——A2A 的状态枚举无法表达它。
-- 任务状态可以跨结算存活，但无法跨进程重启：未组合 session 持久化，重启后 projection
-  没有日志可供冷折叠。
+- 任务结果与空闲会话在保留期内可跨进程重启恢复；中断的任务标记失败，不重放。
+- 每个 context 同时只允许一个任务，并发提交返回 409；messageId 不是提交去重键。
 - `ctx.webServer` 不提供 TLS。任何非回环地址的暴露都应置于反向代理之后。
 - 修改配置会重启插件并取消进行中的任务。
 
@@ -262,8 +315,8 @@ A2A_PEER_ALICE: <32-byte-hex-from-openssl-rand>
 ```
 src/
 ├── protocol/          零依赖库：不碰 Cordis、不碰 HTTP、不碰 harness
-│   ├── wire.ts        A2A 词汇表，统一归一到 v0.3 拼写
-│   ├── normalize.ts   v0.3 <-> v1.0 方言双向翻译
+│   ├── wire.ts        A2A v1.0 词汇表：只有一种形状，不需要翻译
+│   ├── parse.ts       入站解析与方法表
 │   ├── jsonrpc.ts     信封框架与 A2A 错误码
 │   ├── card.ts        Agent Card 构造
 │   └── sse.ts         SSE 帧编码
@@ -273,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 的声明合并
 ```
@@ -286,17 +343,18 @@ src/
 历史。
 
 **驻留是显式管理的。** HTTP 没有连接生命周期，因此每个 `contextId` 对应一个 Activation，
-空闲后被驱逐，持久化的 Session 留在原地。
+空闲后被驱逐。私有 checkpoint 保留任务结果与对话历史，冷恢复时创建新的 harness session。
 
 ## 开发
 
 ```sh
 pnpm install
 pnpm typecheck
-pnpm test       # 9 个文件共 129 项测试
+pnpm test       # 15 个文件共 217 项测试
 pnpm serve      # 启动监听服务
-pnpm probe      # 对运行中的服务执行 48 项检查
+pnpm probe      # 对运行中的服务执行 67 项检查
 pnpm build      # 产出 lib/
+pnpm test:package # 仅声明运行依赖时验证构建产物导入
 ```
 
 端到端测试会启动真实的 Cordis 组合与真实的 agent loop，并通过 HTTP 驱动它；模型使用
@@ -308,13 +366,15 @@ pnpm build      # 产出 lib/
 
 官方项目提供 agent 运行时、插件系统，以及本插件所消费的各个能力接缝。本项目提供：
 
-- 入站的 A2A v0.3.0 JSON-RPC 绑定
-- Agent Card 构造与方言归一化
+- 入站的 A2A v1.0 JSON-RPC 绑定
+- Agent Card 构造与入站请求解析
 - 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"}

package/lib/briefing.js

@@ -0,0 +1,108 @@
+/** One automatic briefing loop owned by the online agent, independent of Portal. */
+import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+export const BRIEFING_INTERVAL_MS = 60 * 60 * 1000;
+const CHECK_INTERVAL_MS = 5000;
+/** Retire only the old Portal-generated job for this exact project. */
+export async function retireLegacyBriefing(scheduler, root) {
+    if (!scheduler?.catalog || !scheduler.delete)
+        return;
+    const prefix = `【简报维护任务】受信任的项目范围只有一个：\n  ${root}\n`;
+    for (const task of await scheduler.catalog()) {
+        if (task.title === '简报维护' && task.prompt.startsWith(prefix)
+            && (task.prompt.includes('4. 把简报写入当前工作目录的 handoff.draft.md')
+                || task.prompt.includes('4. 完整生成并检查上述内容后，直接覆盖写入当前工作目录的 handoff.md。'))) {
+            await scheduler.delete({ id: task.id, sessionId: task.sessionId });
+        }
+    }
+}
+export class AutomaticBriefing {
+    options;
+    timer;
+    closed = false;
+    running = false;
+    enabled = true;
+    nextRunAt = 0;
+    stateFile;
+    constructor(options) {
+        this.options = options;
+        mkdirSync(options.stateDirectory, { recursive: true, mode: 0o700 });
+        this.stateFile = join(options.stateDirectory, 'briefing-state.json');
+        try {
+            const state = JSON.parse(readFileSync(this.stateFile, 'utf8'));
+            if (typeof state.enabled !== 'boolean' || !Number.isSafeInteger(state.nextRunAt) || state.nextRunAt < 0)
+                throw new Error('invalid briefing state');
+            this.enabled = state.enabled;
+            this.nextRunAt = state.nextRunAt;
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+    }
+    save() {
+        const temporary = `${this.stateFile}.tmp`;
+        try {
+            writeFileSync(temporary, JSON.stringify({ enabled: this.enabled, nextRunAt: this.nextRunAt }), { mode: 0o600 });
+            renameSync(temporary, this.stateFile);
+        }
+        finally {
+            rmSync(temporary, { force: true });
+        }
+    }
+    readEnabled() {
+        try {
+            const value = JSON.parse(readFileSync(this.options.settingsFile, 'utf8'));
+            if (typeof value.enabled !== 'boolean')
+                throw new Error('invalid automatic briefing setting');
+            return value.enabled;
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return true;
+            throw error;
+        }
+    }
+    /** Polling also observes an off/on switch without restarting the agent. */
+    async tick() {
+        if (this.closed)
+            return;
+        try {
+            const enabled = this.readEnabled();
+            const now = this.options.now?.() ?? Date.now();
+            if (enabled !== this.enabled) {
+                this.enabled = enabled;
+                if (enabled)
+                    this.nextRunAt = now;
+                this.save();
+            }
+            if (!enabled || this.running || now < this.nextRunAt)
+                return;
+            // Persist before paid work: restarting must not immediately repeat a run.
+            this.nextRunAt = now + BRIEFING_INTERVAL_MS;
+            this.save();
+            this.running = true;
+            try {
+                await this.options.run();
+            }
+            finally {
+                this.running = false;
+            }
+        }
+        catch (error) {
+            this.options.warn(`a2a: automatic briefing failed: ${String(error)}`);
+        }
+    }
+    start() {
+        if (this.closed || this.timer)
+            return;
+        this.timer = setInterval(() => { void this.tick(); }, CHECK_INTERVAL_MS);
+        this.timer.unref();
+        void this.tick();
+    }
+    stop() {
+        this.closed = true;
+        clearInterval(this.timer);
+    }
+}
+//# sourceMappingURL=briefing.js.map

package/lib/briefing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"briefing.js","sourceRoot":"","sources":["../src/briefing.ts"],"names":[],"mappings":"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"}

package/lib/config.d.ts

@@ -15,40 +15,39 @@ export interface PeerConfig {
     /** Credential reference name, NOT the token itself. */
     tokenEnv: string;
 }
-/**
- * How peers are kept from reaching each other.
- *
- * DEFERRED — a tool deny-list (`session_search`, `session_event_search`,
- * `session_trace`, `session_event_trace`, `session_event_read`, `list_agents`)
- * plus a named `unsafeAllowCrossSessionSearch` escape hatch for single-peer
- * deployments. Both were designed as defense in depth behind `workspaceMode`,
- * and neither is declared here until it is enforced: a security knob that
- * silently does nothing is worse than no knob at all.
- */
+/** Working directories and the data roots exposed through the scoped reader. */
 export interface IsolationConfig {
     /**
-     * `per-peer` gives each identity its own cwd, which also makes the existing
-     * cwd-equality authority in cross-session tooling isolate them for free.
-     * `shared` is the collaborative posture and must be chosen deliberately.
+     * `per-peer` gives each identity its own cwd. Neither mode is a filesystem
+     * security boundary. read_file enforces its own canonical data-root boundary.
      */
     workspaceMode: 'per-peer' | 'shared';
-    /** Parent directory in `per-peer` mode; the common cwd in `shared` mode. */
+    /** Shared read-only data root; also the cwd parent in `per-peer` mode. */
     workspaceRoot: string;
-    /** Per-peer cwd overrides, e.g. pointing one trusted peer at a real repo. */
+    /** Overrides both a peer's cwd and its authorized read root. */
     peerWorkspaces: Record<string, string>;
 }
+/** One declared skill, as it appears on the Agent Card. */
+export interface SkillConfig {
+    id: string;
+    name: string;
+    description: string;
+    tags: string[];
+}
 /** Agent Card content and exposure. */
 export interface CardConfig {
     name: string;
     description: string;
     /** Serve the card without a credential, as discovery expects. */
     public: boolean;
-    skills: {
-        id: string;
-        name: string;
-        description: string;
-        tags: string[];
-    }[];
+    skills: SkillConfig[];
+    /**
+     * Skills revealed only through `GetExtendedAgentCard`, after a peer has
+     * authenticated. Declaring any turns on `capabilities.extendedAgentCard`;
+     * leaving this empty means the deployment has no extended card, and the
+     * method answers with the spec's own ExtendedAgentCardNotConfiguredError.
+     */
+    extendedSkills: SkillConfig[];
     provider?: {
         organization: string;
         url: string;
@@ -73,11 +72,32 @@ export interface PushConfig {
      */
     enabled: boolean;
 }
+/**
+ * The host's background briefing, injected when a visitor's context opens.
+ *
+ * The files are read once per Activation (best effort: an absent file is the
+ * normal "nothing to hand over" case) and merged into the context's FIRST
+ * visitor message rather than sent as their own turn — one model call is
+ * spared, and the turn counters stay about the visitor's messages only.
+ */
+export interface PreambleConfig {
+    /** Publication-safe paths relative to the workspace root; absolute paths pass through. */
+    files: string[];
+}
+/** Local-only monitoring surface credentials. */
+export interface AdminConfig {
+    /**
+     * Credential REFERENCE name holding the admin token, NOT the token itself.
+     * Empty or absent means the monitoring surface stays unmounted.
+     */
+    tokenEnv: string;
+    /** Local named pipe / Unix socket. Never served on the public HTTP carrier. */
+    socketPath?: string;
+}
 /** The whole plugin configuration. */
 export interface A2AServerConfig {
     basePath: string;
     publicUrl?: string;
-    protocolVersion: string;
     /**
      * Provider route for every agent this server creates. Optional so another
      * `agent/request` listener may supply the target instead; a runnable
@@ -95,7 +115,34 @@ export interface A2AServerConfig {
     blockTimeoutMs: number;
     contextIdleTtlMs: number;
     maxResidentContexts: number;
+    maxConcurrentTasks: number;
+    maxConcurrentTasksPerPeer: number;
+    maxTasksPerPeerPerDay: number;
+    taskTimeoutMs: number;
+    maxModelCallsPerTask: number;
+    maxOutputTokens: number;
+    maxInputChars: number;
+    maxOutputChars: number;
+    streamHeartbeatMs: number;
+    maxStreamsPerTask: number;
+    maxStreamBufferBytes: number;
+    storage: {
+        directory?: string;
+        retentionMs: number;
+        maxContexts: number;
+        maxContextBytes: number;
+    };
     isolation: IsolationConfig;
+    preamble: PreambleConfig;
+    /** Optional Portal-managed automatic updates; omission leaves the transport inert. */
+    briefing?: {
+        settingsFile: string;
+        prompt: string;
+    };
+    /**
+     * Enables owner RPC and monitoring on private local IPC, never public HTTP.
+     */
+    admin?: AdminConfig;
     push: PushConfig;
 }
 export declare const Config: Schema<A2AServerConfig>;