@ryubyte/dsh-a2a 0.1.3 → 0.1.4

package/README.en.md

@@ -17,14 +17,15 @@ It turns a DSH instance into a full A2A peer in both directions:
 - **Unary**: `SendMessage`, `GetTask`, `ListTasks`, `CancelTask`, `GetExtendedAgentCard`
 - **Streaming**: `SendStreamingMessage` (SSE) / `SubscribeToTask`, with `TaskStatusUpdateEvent` + `TaskArtifactUpdateEvent`
 - **Task lifecycle**: `SUBMITTED → WORKING → COMPLETED / FAILED / CANCELED / REJECTED / INPUT_REQUIRED / AUTH_REQUIRED`
+- **Auth**: outbound sends a per-agent Bearer token (`Authorization: Bearer …`); inbound can protect the endpoint with a shared Bearer token — when set, the AgentCard declares a `bearerAuth` scheme and requests without/with a wrong token get 401 (both unary calls and the SSE stream)
 - **Types**: `Task`, `Message`, `Part` (text/raw/url/data), `Artifact`, `AgentCard`, security schemes, extensions
 
 ### 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.
+- **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.
-- The panel refreshes every 3 s; `/a2a/api` serves a JSON snapshot and control endpoints, fenced to loopback/same-origin.
+- **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)
 
@@ -105,6 +106,10 @@ AgentCard URL to import and connect — the config is written back to
 Once connected, the remote agent's skills appear as model tools:
 `a2a__<name>__<skill>`.
 
+A local agent session's repeated tool calls to a given remote agent reuse one
+A2A `contextId`, so they land in the same remote session with cross-turn memory;
+different local sessions are isolated into separate conversations.
+
 ### 2. Expose this DSH as an A2A agent (inbound)
 
 Enable server mode in `a2a.json`:
@@ -128,9 +133,44 @@ Enable server mode in `a2a.json`:
 Other A2A clients discover this DSH via
 `http://<host>:<port>/.well-known/agent-card.json` and call the `/a2a` endpoint.
 
-> Note: the default inbound executor runs shell commands — fine for local
-> testing only; for production, inject a constrained executor
-> programmatically (see below) and put a TLS reverse proxy in front.
+#### 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.
+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,
+   so history accumulates; a restarted process `resume`s it on demand), sends
+   the message as a `next-turn` waking item, awaits `whenIdle()`, and takes the
+   latest assistant reply as the A2A artifact. Concurrent tasks for one context
+   are serialized; distinct contexts run in parallel. Sessions are not disposed
+   per task (that would defeat context accumulation) — all are disposed on
+   plugin unload/disable. Turning on server mode is enough — no code.
+3. **`notConfiguredExecutor`** (fallback) — when nothing is injected *and* no
+   usable agent loop is composed (e.g. a bare dsh-base profile), it returns
+   "no executor configured — inject one" and **runs nothing**.
+
+> On "present": `ctx.agents` (the registry) existing ≠ being able to create an
+> agent. `create()` needs a factory registered by an agent-loop plugin; without
+> it `create()` rejects and the DSH agent executor surfaces that as a readable
+> error rather than throwing. So a minimal profile still needs an explicit
+> executor.
+>
+> Session ↔ cwd: a DSH session validates `cwd` as an absolute path and freezes
+> it into the session header at creation. Inbound sessions use a **dedicated**
+> cwd `<profile>/.a2a-sessions` (kept separate from the profile root so they
+> don't crowd your interactive sessions). They appear in the session list's
+> "Ungrouped" bucket, each named `A2A: <first-prompt summary>` (inbound messages
+> carry a plugin source, which DSH's automatic titling ignores, so we name it
+> explicitly). Naming is cosmetic — failures are logged, never failing the task.
+>
+> Cancellation: `CancelTask` aborts the running task's executor signal, actually
+> stopping the agent turn (not just flipping task status).
+>
+> For local testing you may still pass `shellExecutor`, which runs the prompt as
+> 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
 
@@ -206,14 +246,17 @@ const server = new A2AServer({
 
 - The dashboard API (`/a2a/api`) listens on loopback / same-origin only; it
   carries no secrets and exists for operator visibility.
-- The default inbound executor runs shell commands directly (`/bin/sh -c`), not
-  an LLM agent; replace it with a constrained executor (e.g. DSH's
-  sandbox/approval pipeline) in production.
+- Inbound execution follows the [executor precedence](#who-executes-an-inbound-task-executor-precedence):
+  with an agent loop present it defaults to this DSH's own cwd-bound
+  session; otherwise (and with nothing injected) it **refuses** and returns
+  "no executor configured". `shellExecutor` is local-testing only. Whatever the
+  executor, never expose server mode to untrusted networks (no auth by default
+  unless you set `authToken`).
 - The A2A spec requires HTTPS for production `AgentInterface.url`; DSH's
   webserver binds loopback by default, so put a TLS reverse proxy in front
   before exposing beyond localhost.
-- Outbound bearer tokens are stored in plaintext in `a2a.json`; secure the file
-  yourself.
+- 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
 

package/README.md

@@ -17,14 +17,15 @@
 - **单次调用**：`SendMessage`、`GetTask`、`ListTasks`、`CancelTask`、`GetExtendedAgentCard`
 - **流式**：`SendStreamingMessage`（SSE）/ `SubscribeToTask`，含 `TaskStatusUpdateEvent` + `TaskArtifactUpdateEvent`
 - **任务生命周期**：`SUBMITTED → WORKING → COMPLETED / FAILED / CANCELED / REJECTED / INPUT_REQUIRED / AUTH_REQUIRED`
+- **鉴权**：出站按 Agent 配置 Bearer Token（`Authorization: Bearer …`）；入站可选共享 Bearer Token 保护端点——配置后 AgentCard 声明 `bearerAuth` 安全方案，未带/错误 token 的请求返回 401（单次调用与 SSE 流均生效）
 - **类型**：`Task`、`Message`、`Part`（text/raw/url/data）、`Artifact`、`AgentCard`、安全方案、扩展
 
 ### 连接面板（设置 → A2A 连接）
 
-- **出站 Agent**：列出本 DSH 连接的远程 Agent（名称、连接状态、AgentCard URL、技能/工具数、最近活动），每个 Agent 支持 **重连 / 启用 / 禁用 / 删除**。
+- **出站 Agent**：列出本 DSH 连接的远程 Agent（名称、连接状态、AgentCard URL、技能/工具数、最近活动），每个 Agent 支持 **重连 / 启用 / 禁用 / 删除**。添加 Agent 时可填 **Bearer Token**（可选），导入与后续 JSON-RPC 调用都会带上 `Authorization: Bearer …`，并随 Agent 一起持久化到 `a2a.json`。
 - **入站连接**：谁在调用本 DSH（来源、地址、首/末次连接、任务数、流式标记），支持关闭。
-- **A2A 服务**：入站服务的运行状态，上线 / 下线开关，端点与技能一览。
-- 面板每 3 秒自动刷新；`/a2a/api` 提供 JSON 快照与控制接口，受 loopback/same-origin 保护。
+- **A2A 服务**：入站服务的运行状态，上线 / 下线开关，端点与技能一览；并显示 **入站任务由谁执行**（自定义 executor / 本 DSH agent 会话 / 未配置），以及 **入站鉴权** 开关——可设置或清除保护入站端点的共享 Bearer Token（持久化到 `a2a.json`，实时生效）。
+- 面板每 3 秒自动刷新；`/a2a/api` 提供 JSON 快照与控制接口，受 loopback/same-origin 保护（token 值不会通过快照回传，只暴露「是否已配置」）。
 
 ### 运行时配置（a2a.json）
 
@@ -96,6 +97,8 @@
 
 连接成功后，对方 Agent 的 skills 会作为模型工具出现：`a2a__<name>__<skill>`。
 
+同一个本地 agent 会话对某远程 Agent 的多次工具调用会复用同一个 A2A `contextId`，因此在远端落到同一会话、具备跨轮记忆；不同本地会话相互隔离，各自独立对话。
+
 ### 2. 对外提供 A2A 服务（入站）
 
 同样在 `a2a.json` 里开启 server 模式：
@@ -118,7 +121,21 @@
 
 之后其他 A2A 客户端通过 `http://<host>:<port>/.well-known/agent-card.json` 发现本 DSH，通过 `/a2a` 端点调用。
 
-> 注：默认入站 executor 会执行 shell 命令，仅适合本机自测；生产部署请通过编程方式注入受限 executor（见下文），并置于 TLS 反向代理之后。
+#### 入站任务由谁执行（executor 优先级）
+
+server 模式收到任务后，按以下优先级选择 executor：
+
+1. **显式 `execute`**（编程接入时注入）—— 用你的。
+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」，**不执行任何命令**。
+
+> 关于「就位」：`ctx.agents`（registry）存在 ≠ 能创建 agent。`create()` 需要 agent-loop 插件注册的 factory；缺 factory 时 `create()` 会 reject，此时 DSH agent executor 会把它作为可读错误返回（而非抛出）。因此最小 profile 仍需显式注入 executor。
+>
+> 会话与工作区：DSH 会话在创建时把 `cwd` 校验为绝对路径并冻结进会话头。入站会话用**专用目录** `<profile>/.a2a-sessions` 作为 cwd（与 profile 根分开，避免入站会话挤占你的交互会话）。它们出现在会话列表的「未分组」里，并按首条消息摘要命名为 `A2A: <摘要>`（入站消息带 plugin 来源，DSH 的自动标题只认 human 消息，故显式命名）。命名是装饰性的，失败只记日志、绝不影响任务。
+>
+> 取消：`CancelTask` 会 abort 正在运行任务的 executor 信号，真正中止 agent 回合（不只是改任务状态）。
+>
+> 本机自测也可显式传入 `shellExecutor`（把 prompt 当作 shell 命令执行，仅限可信客户端）；生产请置于 TLS 反向代理之后并按需配 `authToken`。
 
 ### 3. 编程接入
 
@@ -183,9 +200,9 @@ const server = new A2AServer({
 ## 已知限制
 
 - 面板 API（`/a2a/api`）只监听 loopback / same-origin，供运维可见性使用，不承载机密。
-- 默认入站 executor 直接执行 shell 命令（`/bin/sh -c`），非 LLM 代理；生产环境必须替换为受限 executor（如 DSH sandbox / 审批管线）。
+- 入站服务的执行策略见[入站任务由谁执行](#入站任务由谁执行executor-优先级)：有 agent 循环时默认由本 DSH 会话执行（绑定工作目录 cwd），否则（且未注入 executor）**拒绝执行**并返回「no executor configured」。`shellExecutor` 仅限本地自测。无论哪种 executor，都切勿向不受信网络暴露 server 模式（默认无鉴权，除非配置 `authToken`）。
 - A2A 规范要求生产 `AgentInterface.url` 使用 HTTPS；DSH webServer 默认仅绑 loopback，对外暴露前需自行加 TLS。
-- 出站的 bearer token 明文存于 `a2a.json`，请自行保证该文件权限。
+- Bearer token（出站按 Agent 配置的、入站保护端点的 `authToken`）均明文存于 `a2a.json`，请自行保证该文件权限。
 
 ## 开发
 

package/lib/client.js

@@ -54,6 +54,10 @@ window.__ModuleLoader__.load({
 			const [tab, setTab] = (0, react.useState)("out");
 			/** connection ids whose skill list is expanded in the outbound tab. */
 			const [expanded, setExpanded] = (0, react.useState)(/* @__PURE__ */ new Set());
+			/** Optional bearer token for the add-agent form (outbound). */
+			const [addToken, setAddToken] = (0, react.useState)("");
+			/** Inbound authToken input (serve tab); empty string means "clear". */
+			const [authInput, setAuthInput] = (0, react.useState)("");
 			const refresh = async () => {
 				try {
 					setError(null);
@@ -101,7 +105,8 @@ window.__ModuleLoader__.load({
 						headers: { "content-type": "application/json" },
 						body: JSON.stringify({
 							action: "discover-agent",
-							agentCardUrl: u
+							agentCardUrl: u,
+							bearerToken: addToken.trim() || void 0
 						})
 					})).json();
 					if (!body.ok || !body.message) {
@@ -118,9 +123,13 @@ window.__ModuleLoader__.load({
 			const doConnect = async () => {
 				if (!discovered) return;
 				const n = discovered.name.trim() || "remote";
-				await act("add-agent", n, { agentCardUrl: discovered.agentCardUrl });
+				await act("add-agent", n, {
+					agentCardUrl: discovered.agentCardUrl,
+					bearerToken: addToken.trim() || void 0
+				});
 				if (!busy) {
 					setAddUrl("");
+					setAddToken("");
 					setDiscovered(null);
 				}
 			};
@@ -196,7 +205,25 @@ window.__ModuleLoader__.load({
 					flex: 1,
 					minWidth: 260
 				}
-			}), actionBtn("导入", false, () => void doDiscover(), discovering || !addUrl.trim())), discovering ? (0, react.createElement)("div", { style: {
+			}), actionBtn("导入", false, () => void doDiscover(), discovering || !addUrl.trim())), (0, react.createElement)("div", { style: {
+				display: "flex",
+				alignItems: "center",
+				gap: 8,
+				flexWrap: "wrap"
+			} }, (0, react.createElement)("input", {
+				type: "password",
+				placeholder: "Bearer Token(可选,发送为 Authorization: Bearer …)",
+				value: addToken,
+				onChange: (e) => setAddToken(e.target.value),
+				style: {
+					...inputStyle,
+					flex: 1,
+					minWidth: 260
+				}
+			})), (0, react.createElement)("div", { style: {
+				fontSize: 11.5,
+				color: "var(--dsw-alias-label-tertiary, #999)"
+			} }, "若远程 Agent 需要鉴权,填入 token;导入与后续调用都会带上。token 会明文存入 a2a.json。"), discovering ? (0, react.createElement)("div", { style: {
 				fontSize: 13,
 				color: "var(--dsw-alias-label-tertiary, #999)"
 			} }, "正在读取 Agent Card…") : discovered ? (0, react.createElement)("div", { style: {
@@ -243,7 +270,7 @@ window.__ModuleLoader__.load({
 				display: "flex",
 				gap: 8,
 				marginTop: 2
-			} }, actionBtn("连接", true, () => void doConnect(), busy === "add-agent"), actionBtn("取消", false, () => {
+			} }, actionBtn("连接", true, () => void doConnect(), busy?.startsWith("add-agent:") ?? false), actionBtn("取消", false, () => {
 				setDiscovered(null);
 				setAddUrl("");
 			}, false))) : (0, react.createElement)("div", { style: {
@@ -263,7 +290,7 @@ window.__ModuleLoader__.load({
 			} }, sec("A2A 服务（本 DSH 作为 Agent 对外）", 0), stateDot(serve.enabled ? "connected" : "disconnected"), (0, react.createElement)("span", { style: {
 				fontSize: 12.5,
 				color: serve.enabled ? "#2e7d32" : "#9e9e9e"
-			} }, serve.enabled ? "运行中" : "已下线"), (0, react.createElement)("span", { style: { marginLeft: "auto" } }, serve.enabled ? actionBtn("下线", false, () => void act("server-disable", ""), busy === "server-disable") : actionBtn("上线", true, () => void act("server-enable", ""), busy === "server-enable"))), (0, react.createElement)("div", { style: {
+			} }, serve.enabled ? "运行中" : "已下线"), (0, react.createElement)("span", { style: { marginLeft: "auto" } }, serve.enabled ? actionBtn("下线", false, () => void act("server-disable", ""), busy === "server-disable:") : actionBtn("上线", true, () => void act("server-enable", ""), busy === "server-enable:"))), (0, react.createElement)("div", { style: {
 				display: "flex",
 				flexDirection: "column",
 				gap: 6
@@ -301,13 +328,7 @@ window.__ModuleLoader__.load({
 					fontSize: 12.5,
 					color: "var(--dsw-alias-label-primary, #222)"
 				}
-			}, `• ${s.name}${s.description ? ` — ${s.description}` : ""}`))) : null), serve.enabled && !serve.customExecutor ? (0, react.createElement)("div", { style: {
-				fontSize: 12,
-				color: "var(--dsw-warning, #b26a00)",
-				background: "rgba(178,106,0,.08)",
-				borderRadius: 6,
-				padding: "6px 10px"
-			} }, "⚠ 默认 executor 会执行 shell 命令。生产环境请通过配置指定受限的 execute 实现。") : null) : null, tab === "in" ? (0, react.createElement)("div", { style: {
+			}, `• ${s.name}${s.description ? ` — ${s.description}` : ""}`))) : null), serve.enabled ? executorNote(serve) : null, serve.enabled ? authControl(serve, busy, act, authInput, setAuthInput) : null) : null, tab === "in" ? (0, react.createElement)("div", { style: {
 				display: "flex",
 				flexDirection: "column",
 				gap: 10
@@ -557,6 +578,83 @@ window.__ModuleLoader__.load({
 				}
 			}, label);
 		}
+		/**
+		* A semantically-correct note about how inbound tasks are executed. Dispatches
+		* on the `executor` field; falls back to the legacy `customExecutor` boolean
+		* for snapshots from an older host that didn't send `executor`.
+		*/
+		function executorNote(serve) {
+			const kind = serve.executor ?? (serve.customExecutor ? "custom" : void 0);
+			if (kind === "custom") return null;
+			if (kind === "dsh-agent") return (0, react.createElement)("div", { style: {
+				fontSize: 12,
+				color: "var(--dsw-alias-label-secondary, #666)",
+				background: "rgba(74,125,255,.08)",
+				borderRadius: 6,
+				padding: "6px 10px"
+			} }, "ℹ 入站任务由本 DSH 的 agent 会话执行,按 A2A contextId 一个对话一个会话。");
+			if (kind === "none") return (0, react.createElement)("div", { style: {
+				fontSize: 12,
+				color: "var(--dsw-warning, #b26a00)",
+				background: "rgba(178,106,0,.08)",
+				borderRadius: 6,
+				padding: "6px 10px"
+			} }, "⚠ 未配置 executor,且未检测到可用的 agent 循环:入站任务会被拒绝。通过配置注入 execute,或加载 agent-loop 插件。");
+			return null;
+		}
+		/**
+		* Inbound bearer-token control for the serve tab: shows whether the endpoint is
+		* token-gated, and lets the operator set or clear the shared token. The token
+		* value is never read back from the host — only whether one is configured.
+		*/
+		function authControl(serve, busy, act, authInput, setAuthInput) {
+			return (0, react.createElement)("div", { style: {
+				display: "flex",
+				flexDirection: "column",
+				gap: 6,
+				marginTop: 4
+			} }, (0, react.createElement)("div", { style: {
+				display: "flex",
+				alignItems: "center",
+				gap: 8
+			} }, (0, react.createElement)("span", { style: {
+				fontSize: 12.5,
+				fontWeight: 600,
+				color: "var(--dsw-alias-label-primary, #222)"
+			} }, "入站鉴权"), stateDot(serve.authConfigured ? "connected" : "disabled"), (0, react.createElement)("span", { style: {
+				fontSize: 12,
+				color: serve.authConfigured ? "#2e7d32" : "#9e9e9e"
+			} }, serve.authConfigured ? "已启用 Bearer 鉴权" : "未鉴权(任何客户端可调用)")), (0, react.createElement)("div", { style: {
+				display: "flex",
+				alignItems: "center",
+				gap: 8,
+				flexWrap: "wrap"
+			} }, (0, react.createElement)("input", {
+				type: "password",
+				placeholder: serve.authConfigured ? "输入新 token 以替换" : "设置 Bearer Token 以开启鉴权",
+				value: authInput,
+				onChange: (e) => setAuthInput(e.target.value),
+				style: {
+					padding: "4px 8px",
+					fontSize: 13,
+					borderRadius: 6,
+					border: "1px solid var(--dsw-alias-border-l2, rgba(127,127,127,.3))",
+					background: "var(--dsw-alias-fill-l1, rgba(127,127,127,.06))",
+					color: "var(--dsw-alias-label-primary, #222)",
+					flex: 1,
+					minWidth: 220
+				}
+			}), actionBtn("保存", true, () => {
+				act("set-server-auth", "", { authToken: authInput.trim() });
+				setAuthInput("");
+			}, busy === "set-server-auth:" || !authInput.trim()), serve.authConfigured ? actionBtn("清除", false, () => {
+				act("set-server-auth", "", { authToken: "" });
+				setAuthInput("");
+			}, busy === "set-server-auth:") : null), (0, react.createElement)("div", { style: {
+				fontSize: 11.5,
+				color: "var(--dsw-alias-label-tertiary, #999)"
+			} }, "token 会明文存入 a2a.json,重启后仍生效。设置后,入站 JSON-RPC 请求需带 Authorization: Bearer <token>。"));
+		}
 		function inboundRow(p, busy, act) {
 			return (0, react.createElement)("tr", { key: p.id }, (0, react.createElement)("td", { style: tdStyle }, p.label), (0, react.createElement)("td", { style: {
 				...tdStyle,