@ryubyte/dsh-a2a 0.1.5 → 0.2.1

package/README.en.md

@@ -9,6 +9,23 @@ It turns a DSH instance into a full A2A peer in both directions:
 - **Client mode (outbound)** — discover a remote agent via its **AgentCard**, map each **skill** to a DSH model tool (`a2a__<name>__<skill>`), and execute remote tasks through A2A **JSON-RPC**.
 - **Server mode (inbound)** — expose this DSH to other agents: `/.well-known/agent-card.json` plus a JSON-RPC endpoint (`SendMessage`, `GetTask`, `ListTasks`, `CancelTask`, `SendStreamingMessage` over SSE) on the DSH webserver.
 
+## Installation
+
+Install into a profile with one command and restart:
+
+    dsh plugin --profile web add @ryubyte/dsh-a2a
+    dsh --profile web
+
+`dsh plugin` installs the package into the profile and auto-registers the
+plugin layer (this package declares `dsh.bundle.patch` in `package.json`) — no
+manual configuration is needed.
+
+## Screenshots
+
+| Connected agents (this DSH as a client) | Public service (this DSH as an agent) |
+|---|---|
+| ![Connected agents panel](docs/screenshots/panel-client.png) | ![Public service panel](docs/screenshots/panel-server.png) |
+
 ## Features
 
 ### Protocol surface (A2A v1.0)
@@ -22,62 +39,34 @@ It turns a DSH instance into a full A2A peer in both directions:
 
 ### Connection dashboard (设置 → A2A 连接)
 
-- **Outbound agents** — remote agents this DSH connects to (name, connection state, AgentCard URL, skill/tool counts, last activity), each with **Reconnect / Enable / Disable / Delete** controls. When adding an agent you can supply an optional **Bearer token** — it is sent as `Authorization: Bearer …` on both the AgentCard fetch and every JSON-RPC call, and persisted alongside the agent in `a2a.json`.
-- **Inbound peers** — who is calling this DSH (label, source address, first/last seen, task count, streaming flag), with a close control.
-- **A2A server** — inbound server status with an online/offline toggle, endpoint and skill overview; it also shows **who executes inbound tasks** (custom executor / this DSH's agent session / none) and an **inbound auth** control to set or clear the shared Bearer token that gates the endpoint (persisted to `a2a.json`, effective immediately).
-- The panel refreshes every 3 s; `/a2a/api` serves a JSON snapshot and control endpoints, fenced to loopback/same-origin (the token value is never returned in the snapshot — only whether one is configured).
-
-### Runtime configuration (a2a.json)
-
-Configuration is driven by **`a2a.json`** (per profile, UI-editable) — manage
-agents without touching the composition. The file is resolved from the active
-profile, not the launch directory: the plugin parses `--profile <name>` from
-the process command line (the `dsh web` alias is recognized as the `web`
-profile too) and reads/writes `~/.dsh/profiles/<name>/a2a.json`.
-
-## Screenshots
-
-| Outbound agents (who this DSH connects to) | Inbound peers (who calls this DSH) |
-|---|---|
-| ![Outbound agents dashboard](docs/screenshots/dashboard-outbound.png) | ![Inbound peers dashboard](docs/screenshots/dashboard-inbound.png) |
+The panel is split into two tabs by **role**, and **everything is configurable in the UI — no need to hand-edit `a2a.json`**:
 
-| Inbound with a live record | A2A server status panel |
-|---|---|
-| ![Inbound peer record](docs/screenshots/server-inbound.png) | ![A2A server status](docs/screenshots/server-serve.png) |
-
-## Installation
+**"Connected agents" (this DSH as a client, outbound)**
 
-### Option 1: from npm (recommended)
+- Lists connected remote agents (name, connection state, AgentCard URL, skill/tool counts, last activity); expand to see each skill's name/tags/description. Each agent has **Reconnect / Settings / Disable / Delete** controls (a disabled agent shows as a greyed-out placeholder card whose control becomes **Enable**).
+- **Settings** — edit that agent's **timeout (timeoutMs)**, **skill mapping (mapSkills)**, and **Bearer token** in place; saving reconnects with the new config to apply it.
+- **Add agent** — enter an AgentCard URL (optional Bearer token) → "Import" to preview the remote name/description/skills → "Connect". Config is written back to `a2a.json`.
 
-Once published to npm, install into the target profile with one command and
-restart:
+**"Public service" (this DSH as an agent, inbound)**
 
-    dsh plugin --profile <profile> add @ryubyte/dsh-a2a
-    dsh --profile <profile>
-
-`dsh plugin` installs the package into the profile and auto-registers the
-plugin layer (this package declares `dsh.bundle.patch` in `package.json`) — no
-manual configuration is needed.
-
-### Option 2: from the repository (development)
-
-For hacking on the code, requires Node.js >= 22:
-
-    # 1. Clone the repo
-    git clone https://github.com/ryubyte/dsh-a2a.git
-    cd dsh-a2a
-
-    # 2. Install deps and build
-    npm install
-    npm run build
-
-    # 3. Link into the target profile
-    dsh plugin --profile <profile> add link:$(pwd)
+- **Visual identity editing** — read-only view of the service name/description/version, endpoint, Agent Card URL (one-click copy) and Skills; click "Edit" to change these fields in place and **fully add/edit/remove Skills**, saving rebuilds the AgentCard immediately (no restart).
+- **Guided setup** — on a fresh install (no `a2a.json`), this tab shows a form pre-filled with sensible defaults; tweak as needed and click "Create & go online" to publish the service — one step generates `a2a.json` and starts serving.
+- **Online / offline** toggle; shows **who executes inbound tasks** (custom executor / this DSH's agent session / none).
+- **Inbound auth** — set or clear the shared Bearer token that gates the endpoint (persisted to `a2a.json`, effective immediately).
+- **Inbound peers** — who is calling this DSH (label, source address, first/last seen, task count, streaming flag), with a close control.
+- The panel refreshes every 3 s; `/a2a/api` serves a JSON snapshot and control endpoints, fenced to loopback/same-origin (the token value is never returned in the snapshot — only whether one is configured).
 
-    # 4. Restart
-    dsh --profile <profile>
+### Runtime configuration (a2a.json)
 
-After changing source, re-run `npm run build` and restart.
+Configuration is driven by **`a2a.json`** (per profile, fully manageable from the
+UI) — manage agents and the public service without touching the composition. The
+file is resolved from the active profile, not the launch directory: the plugin
+parses `--profile <name>` from the process command line (the `dsh web` alias is
+recognized as the `web` profile too) and reads/writes
+`~/.dsh/profiles/<name>/a2a.json` — configs the UI generates on first use also
+land in that profile directory, so they are read no matter which working
+directory you launch from. Hand-writing `a2a.json` is still supported (below),
+but **a new user can do everything through the UI**.
 
 ## Usage
 
@@ -100,9 +89,10 @@ Declare agents to connect to in the profile's `a2a.json`:
 }
 ```
 
-Alternatively, in the Web GUI go to 设置 → A2A 连接 → 添加 Agent, paste an
-AgentCard URL to import and connect — the config is written back to
-`a2a.json`.
+Alternatively, in the Web GUI go to 设置 → A2A 连接 → "Connected agents" → Add
+agent, paste an AgentCard URL to import and connect — the config is written back
+to `a2a.json`. After connecting, the agent's "Settings" lets you adjust its
+timeout, skill mapping, and token.
 
 Once connected, the remote agent's skills appear as model tools:
 `a2a__<name>__<skill>`.
@@ -113,14 +103,19 @@ different local sessions are isolated into separate conversations.
 
 ### 2. Expose this DSH as an A2A agent (inbound)
 
-Enable server mode in `a2a.json`:
+> **Recommended: use the UI.** Open 设置 → A2A 连接 → "Public service"; a fresh
+> install shows a pre-filled form — tweak a few fields and click "Create & go
+> online". No hand-written JSON required. The config below is the equivalent
+> for reference or scripted deployment.
+
+Or enable server mode manually in `a2a.json`:
 
 ```jsonc
 {
   "mode": "server",
   "server": {
     "enabled": true,             // explicitly turn the inbound server on
-    // "baseUrl": "http://127.0.0.1:3080",   // optional; default: derive from webServer
+    // "baseUrl": omit to auto-infer (see below); set only behind a proxy / public domain
     "agentName": "My DSH Agent",
     "agentDescription": "A DSH agent over A2A v1.0",
     "agentVersion": "0.1.0",
@@ -131,14 +126,18 @@ Enable server mode in `a2a.json`:
 }
 ```
 
-Other A2A clients discover this DSH via
+When `baseUrl` is left empty (or cleared in the UI), the AgentCard auto-infers the webServer's **real listen address**, so it never advertises a stale port; set it explicitly only when this DSH sits behind a reverse proxy or public domain whose external address differs from the local listener.
+
+> **About `mode`**: `mode` (`client` / `server` / `both`) selects which half mounts at startup, defaulting to `client`. It is **optional** — `server.enabled: true` or the presence of `agents` turns on the respective half, so an `a2a.json` generated through the UI usually **omits `mode`** and relies on those fields. Writing `mode` by hand is clearer but equivalent.
+
+Other A2A clients discover this DSH via the auto-inferred
 `http://<host>:<port>/.well-known/agent-card.json` and call the `/a2a` endpoint.
 
 #### Who executes an inbound task (executor precedence)
 
 On each inbound task the server picks an executor in this order:
 
-1. **Explicit `execute`** (injected programmatically) — yours wins.
+1. **Explicit `execute`** (injected via composition config) — yours wins.
 2. **This DSH's own agent session** (the default, when an agent loop is
    present) — **one session per A2A `contextId`**: the first task for a context
    `ctx.agents.create()`s a session (later tasks for the same context reuse it,
@@ -173,37 +172,6 @@ On each inbound task the server picks an executor in this order:
 > a `/bin/sh -c` command — trusted clients only. For production put a TLS
 > reverse proxy in front and set `authToken` as needed.
 
-### 3. Programmatic use
-
-```ts
-import { A2AClient, A2AServer, TaskStore } from '@ryubyte/dsh-a2a';
-
-// outbound: connect to a remote agent
-const client = await A2AClient.connect('https://agent.example.com');
-const { task } = await client.sendMessage({
-  messageId: crypto.randomUUID(),
-  role: 'ROLE_USER',
-  parts: [{ text: 'Draft a report' }],
-});
-for await (const ev of client.streamMessage({ messageId: crypto.randomUUID(), role: 'ROLE_USER', parts: [{ text: 'hi' }] })) {
-  // ev.statusUpdate | ev.artifactUpdate | ev.task | ev.message
-}
-
-// inbound: wire a custom executor to your own agent loop
-const store = new TaskStore();
-const server = new A2AServer({
-  baseUrl: 'http://127.0.0.1:3080',
-  agentName: 'My DSH',
-  agentDescription: '...',
-  agentVersion: '1.0.0',
-  execute: async ({ message }) => ({
-    messageId: crypto.randomUUID(),
-    role: 'ROLE_AGENT',
-    parts: [{ text: await myAgentRun(message.parts) }],
-  }),
-}, store);
-```
-
 ## Directory structure
 
     src/
@@ -260,12 +228,4 @@ const server = new A2AServer({
   webserver binds loopback by default, so put a TLS reverse proxy in front
   before exposing beyond localhost.
 - Bearer tokens — both the outbound per-agent token and the inbound endpoint
-  `authToken` — are stored in plaintext in `a2a.json`; secure the file yourself.
-
-## Development
-
-```bash
-npm install
-npm run build    # tsc(types) + tsdown(lib) + wrap client → lib/client.js
-npm test         # node:test + tsx (unit/integration) + client-bundle smoke
-```
+  `authToken` — are stored in plaintext in `a2a.json`; secure the file yourself.

package/README.md

@@ -9,6 +9,21 @@
 - **Client 模式（出站）**——通过远程 Agent 的 **AgentCard** 发现它，把每个 **skill** 映射为 DSH 模型工具（`a2a__<name>__<skill>`），通过 A2A **JSON-RPC** 执行远程任务。
 - **Server 模式（入站）**——把本 DSH 暴露给其他 Agent：在 DSH webserver 上提供 `/.well-known/agent-card.json` 与 JSON-RPC 端点（`SendMessage`、`GetTask`、`ListTasks`、`CancelTask`、基于 SSE 的 `SendStreamingMessage`）。
 
+## 安装
+
+一行命令装进 profile，重启即生效：
+
+    dsh plugin --profile web add @ryubyte/dsh-a2a
+    dsh --profile web
+
+`dsh plugin` 会把包装进 profile 并自动加入插件层（本包在 package.json 里声明了 `dsh.bundle.patch`），无需手动改任何配置。
+
+## 截图
+
+| 连接的 Agent（本 DSH 作为客户端） | 对外服务（本 DSH 作为 Agent） |
+|---|---|
+| ![连接的 Agent 面板](docs/screenshots/panel-client.png) | ![对外服务面板](docs/screenshots/panel-server.png) |
+
 ## 功能
 
 ### 协议能力（A2A v1.0）
@@ -22,55 +37,26 @@
 
 ### 连接面板（设置 → A2A 连接）
 
-- **出站 Agent**：列出本 DSH 连接的远程 Agent（名称、连接状态、AgentCard URL、技能/工具数、最近活动），每个 Agent 支持 **重连 / 启用 / 禁用 / 删除**。添加 Agent 时可填 **Bearer Token**（可选），导入与后续 JSON-RPC 调用都会带上 `Authorization: Bearer …`，并随 Agent 一起持久化到 `a2a.json`。
-- **入站连接**：谁在调用本 DSH（来源、地址、首/末次连接、任务数、流式标记），支持关闭。
-- **A2A 服务**：入站服务的运行状态，上线 / 下线开关，端点与技能一览；并显示 **入站任务由谁执行**（自定义 executor / 本 DSH agent 会话 / 未配置），以及 **入站鉴权** 开关——可设置或清除保护入站端点的共享 Bearer Token（持久化到 `a2a.json`，实时生效）。
-- 面板每 3 秒自动刷新；`/a2a/api` 提供 JSON 快照与控制接口，受 loopback/same-origin 保护（token 值不会通过快照回传，只暴露「是否已配置」）。
-
-### 运行时配置（a2a.json）
-
-配置以 **`a2a.json`（按 profile 存放，UI 可编辑）为准**，无需改动组合配置即可管理 Agent。文件定位不依赖启动目录：插件解析进程命令行里的 `--profile <name>`（`dsh web` 别名同样识别为 `web` profile），读写 `~/.dsh/profiles/<name>/a2a.json`。
-
-## 截图
+面板按**角色**分为两个 tab，**全部配置都可在 UI 里完成，无需手改 `a2a.json`**：
 
-| 出站 Agent（本 DSH 连接了谁） | 入站连接（谁在调用本 DSH） |
-|---|---|
-| ![出站 Agent 面板](docs/screenshots/dashboard-outbound.png) | ![入站连接面板](docs/screenshots/dashboard-inbound.png) |
-
-| 含真实记录的入站 | A2A 服务状态面板 |
-|---|---|
-| ![入站连接记录](docs/screenshots/server-inbound.png) | ![A2A 服务状态](docs/screenshots/server-serve.png) |
-
-## 安装
+**「连接的 Agent」（本 DSH 作为客户端，出站）**
 
-### 方式一：从 npm 安装（推荐）
+- 列出已连接的远程 Agent（名称、连接状态、AgentCard URL、技能/工具数、最近活动），展开可看每个 skill 的名称/标签/描述；每个 Agent 支持 **重连 / 设置 / 禁用 / 删除**（已禁用的 Agent 显示为灰化占位卡，操作按钮变为 **启用**）。
+- **设置**：就地编辑该 Agent 的 **超时（timeoutMs）**、**技能拆分（mapSkills）**、**Bearer Token**，保存后自动以新配置重连生效。
+- **添加 Agent**：填 AgentCard URL（可选 Bearer Token）→「导入」预览远端名称/描述/技能 →「连接」。配置写回 `a2a.json`。
 
-插件发布到 npm 后，一行命令装进目标 profile，重启即生效：
+**「对外服务」（本 DSH 作为 Agent 对外，入站）**
 
-    dsh plugin --profile <profile> add @ryubyte/dsh-a2a
-    dsh --profile <profile>
-
-`dsh plugin` 会把包装进 profile 并自动加入插件层（本包在 package.json 里声明了 `dsh.bundle.patch`），无需手动改任何配置。
-
-### 方式二：从仓库安装（开发调试）
-
-用于改代码调试，需要 Node.js >= 22 与 pnpm：
-
-    # 1. 克隆仓库
-    git clone https://github.com/ryubyte/dsh-a2a.git
-    cd dsh-a2a
-
-    # 2. 安装依赖并构建
-    npm install
-    npm run build
-
-    # 3. 链接进目标 profile
-    dsh plugin --profile <profile> add link:$(pwd)
+- **服务身份可视化编辑**：只读展示服务名/描述/版本、端点、Agent Card URL（一键复制）与 Skills；点「编辑」就地改这些字段并**完整增删改 Skills**，保存即时重建 AgentCard 生效（无需重启）。
+- **引导式初始化**：全新安装（无 `a2a.json`）时，本页显示预填好合理默认值的表单，用户按需修改后点「创建并上线」即可发布服务——一步生成 `a2a.json` 并启动。
+- **上线 / 下线** 开关；显示 **入站任务由谁执行**（自定义 executor / 本 DSH agent 会话 / 未配置）。
+- **入站鉴权**：设置或清除保护入站端点的共享 Bearer Token（持久化到 `a2a.json`，实时生效）。
+- **入站连接**：谁在调用本 DSH（来源、地址、首/末次连接、任务数、流式标记），支持关闭。
+- 面板每 3 秒自动刷新；`/a2a/api` 提供 JSON 快照与控制接口，受 loopback/same-origin 保护（token 值不会通过快照回传，只暴露「是否已配置」）。
 
-    # 4. 重启
-    dsh --profile <profile>
+### 运行时配置（a2a.json）
 
-改完源码后重跑 `npm run build` 再重启即可。
+配置以 **`a2a.json`（按 profile 存放，可完全通过 UI 管理）为准**，无需改动组合配置即可管理 Agent 与对外服务。文件定位不依赖启动目录：插件解析进程命令行里的 `--profile <name>`（`dsh web` 别名同样识别为 `web` profile），读写 `~/.dsh/profiles/<name>/a2a.json`——UI 首次生成的配置也会写到该 profile 目录，从任意工作目录启动都能读到。手写 `a2a.json` 仍然支持（见下文），但**新用户完全靠 UI 即可完成配置与上线**。
 
 ## 使用
 
@@ -93,7 +79,7 @@
 }
 ```
 
-也可以在 Web GUI「设置 → A2A 连接 → 添加 Agent」里输入 AgentCard URL 导入并连接，配置会写回 `a2a.json`。
+也可以在 Web GUI「设置 → A2A 连接 →『连接的 Agent』→ 添加 Agent」里输入 AgentCard URL 导入并连接，配置会写回 `a2a.json`；连接后点该 Agent 的「设置」还能调整超时、技能拆分与 Token。
 
 连接成功后，对方 Agent 的 skills 会作为模型工具出现：`a2a__<name>__<skill>`。
 
@@ -101,14 +87,16 @@
 
 ### 2. 对外提供 A2A 服务（入站）
 
-同样在 `a2a.json` 里开启 server 模式：
+> **推荐：直接用 UI。** 打开「设置 → A2A 连接 →『对外服务』」，全新安装会显示预填好的表单，改几个字段后点「创建并上线」即可——无需手写下面的 JSON。以下为等价的手写配置，供了解字段或脚本化部署时参考。
+
+也可以在 `a2a.json` 里手动开启 server 模式：
 
 ```jsonc
 {
   "mode": "server",
   "server": {
     "enabled": true,             // 显式开启入站服务
-    // "baseUrl": "http://127.0.0.1:3080",   // 可选；默认从 webServer 监听地址推导
+    // "baseUrl": 省略即自动推导（见下），仅反向代理/公网域名时才需显式设置
     "agentName": "My DSH Agent",
     "agentDescription": "A DSH agent over A2A v1.0",
     "agentVersion": "0.1.0",
@@ -119,13 +107,17 @@
 }
 ```
 
-之后其他 A2A 客户端通过 `http://<host>:<port>/.well-known/agent-card.json` 发现本 DSH，通过 `/a2a` 端点调用。
+`baseUrl` 留空（或在 UI 里清空）时，AgentCard 会按 webServer 的**真实监听地址**自动推导，不会公布过期端口；仅当本 DSH 位于反向代理或公网域名之后、对外地址与本地监听不同时，才需要显式填写。
+
+> **关于 `mode`**：`mode`（`client` / `server` / `both`）控制启动时挂载哪一半，缺省为 `client`。它是**可选**的——`server.enabled: true` 或存在 `agents` 就会分别启用对应半区，所以通过 UI 生成的 `a2a.json` 通常**不写 `mode`**，仅靠这些字段隐式推导行为。手写时显式写 `mode` 更直观，二者等价。
+
+之后其他 A2A 客户端通过自动推导出的 `http://<host>:<port>/.well-known/agent-card.json` 发现本 DSH，通过 `/a2a` 端点调用。
 
 #### 入站任务由谁执行（executor 优先级）
 
 server 模式收到任务后，按以下优先级选择 executor：
 
-1. **显式 `execute`**（编程接入时注入）—— 用你的。
+1. **显式 `execute`**（通过 composition 配置注入）—— 用你的。
 2. **本 DSH 的 agent 会话**（默认，当 agent 循环就位时）—— 按 A2A `contextId` **一个对话一个会话**：某 `contextId` 首个任务 `ctx.agents.create()` 建会话（后续同 `contextId` 复用同一会话，历史累积；进程重启后按需 `resume`），把消息作为 `next-turn` 唤醒项发给它，等 `whenIdle()`，取最新 assistant 回复作为 A2A artifact。同一 `contextId` 的并发任务按序串行，不同 `contextId` 并行。会话不逐任务释放（否则无法累积上下文），插件卸载/下线时统一释放。开 server 即可「接收并处理任务」，无需写代码。
 3. **`notConfiguredExecutor`**（兜底）—— 既没注入 `execute`、composition 里又没有可用 agent 循环（如仅 dsh-base 的最小 profile）时，返回「no executor configured — inject one」，**不执行任何命令**。
 
@@ -137,37 +129,6 @@ server 模式收到任务后，按以下优先级选择 executor：
 >
 > 本机自测也可显式传入 `shellExecutor`（把 prompt 当作 shell 命令执行，仅限可信客户端）；生产请置于 TLS 反向代理之后并按需配 `authToken`。
 
-### 3. 编程接入
-
-```ts
-import { A2AClient, A2AServer, TaskStore } from '@ryubyte/dsh-a2a';
-
-// 出站：连接远程 Agent
-const client = await A2AClient.connect('https://agent.example.com');
-const { task } = await client.sendMessage({
-  messageId: crypto.randomUUID(),
-  role: 'ROLE_USER',
-  parts: [{ text: 'Draft a report' }],
-});
-for await (const ev of client.streamMessage({ messageId: crypto.randomUUID(), role: 'ROLE_USER', parts: [{ text: 'hi' }] })) {
-  // ev.statusUpdate | ev.artifactUpdate | ev.task | ev.message
-}
-
-// 入站：自定义 executor 接入 DSH agent 循环
-const store = new TaskStore();
-const server = new A2AServer({
-  baseUrl: 'http://127.0.0.1:3080',
-  agentName: 'My DSH',
-  agentDescription: '...',
-  agentVersion: '1.0.0',
-  execute: async ({ message }) => ({
-    messageId: crypto.randomUUID(),
-    role: 'ROLE_AGENT',
-    parts: [{ text: await myAgentRun(message.parts) }],
-  }),
-}, store);
-```
-
 ## 目录结构
 
     src/
@@ -203,11 +164,3 @@ const server = new A2AServer({
 - 入站服务的执行策略见[入站任务由谁执行](#入站任务由谁执行executor-优先级)：有 agent 循环时默认由本 DSH 会话执行（绑定工作目录 cwd），否则（且未注入 executor）**拒绝执行**并返回「no executor configured」。`shellExecutor` 仅限本地自测。无论哪种 executor，都切勿向不受信网络暴露 server 模式（默认无鉴权，除非配置 `authToken`）。
 - A2A 规范要求生产 `AgentInterface.url` 使用 HTTPS；DSH webServer 默认仅绑 loopback，对外暴露前需自行加 TLS。
 - Bearer token（出站按 Agent 配置的、入站保护端点的 `authToken`）均明文存于 `a2a.json`，请自行保证该文件权限。
-
-## 开发
-
-```bash
-npm install
-npm run build    # tsc(types) + tsdown(lib) + wrap client → lib/client.js
-npm test         # node:test + tsx（单元 / 集成）+ client-bundle smoke
-```