@ai_mind/dsh-a2a 1.0.0 → 1.1.1

package/README.md

@@ -2,7 +2,7 @@
 
 把本机 DeepSeek Harness 智能体暴露为 **A2A（Agent2Agent）v1.0 服务端**的生产级插件。
 
-协议实现基于官方 [`@a2a-js/sdk` 1.3.0](https://www.npmjs.com/package/@a2a-js/sdk)（A2A Protocol Specification v1.0 的官方 TypeScript SDK），本插件负责把它挂到 Harness 的 Web 服务器上，并把 A2A 任务桥接到真实的 Harness Agent：每个 A2A `contextId` 对应一个可复用的 Harness 会话，任务取消、超时、并发上限、沙箱与审批策略都由插件统一管理。
+协议实现基于官方 [`@a2a-js/sdk` 1.3.0](https://www.npmjs.com/package/@a2a-js/sdk)（A2A Protocol Specification v1.0 的官方 TypeScript SDK）。本插件默认复用 Harness Web 的监听端口，也可以配置 `server.port` 让 A2A 在独立端口监听，并把 A2A 任务桥接到真实的 Harness Agent：每个 A2A `contextId` 对应一个可复用的 Harness 会话，任务取消、超时、并发上限、沙箱与审批策略都由插件统一管理。
 
 - 规范：[A2A Protocol v1.0.0](https://a2a-protocol.org/v1.0.0/specification/)
 - 绑定：**JSON-RPC 2.0** + **HTTP+JSON/REST**（gRPC 未暴露，见[已知限制](#已知限制)）
@@ -73,13 +73,13 @@
 3. 验证 Agent Card：
 
    ```bash
-   curl -s http://127.0.0.1:57133/.well-known/agent-card.json | jq .
+   curl -s http://127.0.0.1:41241/.well-known/agent-card.json | jq .
    ```
 
 4. 发一条消息（注意必须带 `A2A-Version: 1.0`）：
 
    ```bash
-   curl -s http://127.0.0.1:57133/a2a \
+   curl -s http://127.0.0.1:41241/a2a \
      -H 'content-type: application/json' \
      -H 'a2a-version: 1.0' \
      -H "authorization: Bearer $A2A_AUTH_TOKEN" \
@@ -100,7 +100,7 @@
 5. 流式调用：
 
    ```bash
-   curl -N http://127.0.0.1:57133/a2a \
+   curl -N http://127.0.0.1:41241/a2a \
      -H 'content-type: application/json' \
      -H 'a2a-version: 1.0' \
      -d '{"jsonrpc":"2.0","id":2,"method":"SendStreamingMessage","params":{"message":{"messageId":"m-2","role":"ROLE_USER","parts":[{"text":"列出当前目录的文件"}]}}}'
@@ -118,7 +118,7 @@
 2. **配置表单**：直接编辑名称、描述、对外地址、挂载路径、流式/推送/扩展卡片、鉴权模式与令牌环境变量、访问令牌（写入后不再回显）、Agent 预设/模型/工作目录/沙箱/审批/并发/超时，以及请求体与任务保留限额。
 3. **保存**：写入 profile 的 `cordis.patch.yml`（`a2a-server` 行），校验通过后插件自动重载；修改挂载路径后刷新页面即可。
 
-配置接口 `GET/PUT <mountPath>/panel/config` 使用 **Harness Web 连接凭据**（不是 A2A token）鉴权：只有能打开 Settings 的已登录浏览器可以读写，远程 A2A 客户端即使知道路径也会收到 401。令牌字段是只写字段，GET 只返回“是否已配置”。
+配置接口 `GET/PUT <mountPath>/panel/config` 始终位于 DSH Web 的 origin（独立端口模式下也不在 A2A 端口上），使用 **Harness Web 连接凭据**（不是 A2A token）鉴权：只有能打开 Settings 的已登录浏览器可以读写，远程 A2A 客户端即使知道路径也会收到 401。令牌字段是只写字段，GET 只返回“是否已配置”。
 
 `lib/client-discovery.js` 会在插件挂载时清掉 DSH client 模块扫描器对“这个包没有浏览器半”的进程级缓存并触发一次重新扫描，因此从旧版本热升级后无需重启即可看到面板；全新启动时该逻辑自动跳过。
 
@@ -129,13 +129,13 @@ A2A 客户端必须发送 `A2A-Version: 1.0`，并带 `Content-Type: application
 ### 1. 发现 Agent Card
 
 ```bash
-curl -s http://127.0.0.1:57133/.well-known/agent-card.json | jq .
+curl -s http://127.0.0.1:41241/.well-known/agent-card.json | jq .
 ```
 
 ### 2. JSON-RPC 发送消息（阻塞）
 
 ```bash
-curl -s http://127.0.0.1:57133/a2a \
+curl -s http://127.0.0.1:41241/a2a \
   -H 'content-type: application/json' \
   -H 'a2a-version: 1.0' \
   -d '{
@@ -155,7 +155,7 @@ curl -s http://127.0.0.1:57133/a2a \
 ### 3. 流式（SSE）
 
 ```bash
-curl -N http://127.0.0.1:57133/a2a \
+curl -N http://127.0.0.1:41241/a2a \
   -H 'content-type: application/json' \
   -H 'a2a-version: 1.0' \
   -d '{"jsonrpc":"2.0","id":2,"method":"SendStreamingMessage","params":{"message":{"messageId":"m-2","role":"ROLE_USER","parts":[{"text":"列出当前目录的文件"}]}}}'
@@ -170,7 +170,7 @@ npm install @a2a-js/sdk
 ```js
 import { ClientFactory, Role } from '@a2a-js/sdk/client'
 
-const client = await new ClientFactory().createFromUrl('http://127.0.0.1:57133')
+const client = await new ClientFactory().createFromUrl('http://127.0.0.1:41241')
 const result = await client.sendMessage({
   message: {
     messageId: crypto.randomUUID(),
@@ -186,7 +186,7 @@ console.log(result)
 ### 5. REST
 
 ```bash
-curl -s http://127.0.0.1:57133/a2a/rest/message:send \
+curl -s http://127.0.0.1:41241/a2a/rest/message:send \
   -H 'content-type: application/a2a+json' \
   -H 'a2a-version: 1.0' \
   -d '{"message":{"messageId":"m-3","role":"ROLE_USER","parts":[{"text":"你好"}]}}' | jq .
@@ -228,6 +228,16 @@ JSON-RPC 方法名：`SendMessage`、`SendStreamingMessage`、`GetTask`、`ListT
 
 凭据来源（可组合）：`auth.clients[{id,token}]`、`auth.tokens[]`、`auth.token`、`auth.tokenEnv`（环境变量，支持逗号/换行分隔多个）。启用鉴权后 Agent Card 会自动声明 `securitySchemes` 与 `securityRequirements`。
 
+内联令牌可以直接写在插件配置里（设置页的「A2A 访问令牌（内联）」字段等价）：
+
+```yaml
+auth:
+  mode: bearer
+  token: 'your-long-random-token'
+```
+
+> 在设置页输入令牌时，如果 `auth.mode` 还是 `none`，保存会自动切换为 `bearer`。令牌不会回显；它会以明文保存在 profile 的 `cordis.patch.yml`（权限 600），生产环境建议改用 `auth.tokenEnv` 或 `auth.clients`。
+
 **每个凭据是一个独立的租户边界**：任务与 Push 配置按凭据 id 隔离，客户端 A 看不到客户端 B 的任务。未鉴权时所有 loopback 调用方共享 `anonymous` 作用域。
 
 ### 默认安全姿态
@@ -285,6 +295,27 @@ agent:
 
 ---
 
+## 独立端口（不与 DSH 复用）
+
+插件配置的默认值是 `server.port: null`：A2A 直接复用 DSH Web 的端口，Agent Card、JSON-RPC、REST 和设置面板共享同一个 origin。本仓库的 bundle patch 为了方便独立部署，默认设为 `127.0.0.1:41241`。需要显式控制时：
+
+```yaml
+server:
+  host: 127.0.0.1
+  port: 41241
+```
+
+此时：
+
+- A2A 在 `http://127.0.0.1:41241/a2a` 单独监听（REST 为 `/a2a/rest`），Agent Card 和 `health` 也在该端口；
+- DSH Web 端口只保留卡片镜像 `/.well-known/agent-card.json`（供设置页发现）和 `<mountPath>/panel` 配置面板（仍使用 GUI 登录凭据，不暴露在 A2A 端口上）；
+- Agent Card 的 `supportedInterfaces` 使用 `http://host:port`；如果前面有反向代理/TLS 终止，设置 `server.publicUrl` 为外部地址；
+- 独立监听本身是 HTTP；公网部署时由反向代理终止 TLS。
+
+本仓库的 `cordis.patch.yml` 默认使用 `127.0.0.1:41241`；修改 `server.port`（或在设置页的“监听端口”保存）后插件会重载并切换监听。若端口被占用，设置页会显示监听错误。
+
+---
+
 ## 配置参考
 
 完整默认值见 [`lib/config.js`](lib/config.js)。所有字段均可在 bundle 行 `config` 中覆盖；未知字段会令插件激活失败（避免拼写错误静默生效）。
@@ -295,7 +326,9 @@ enabled: true
 server:
   mountPath: /a2a
   cardPath: /.well-known/agent-card.json
-  publicUrl: null              # 对外可达的 origin；不填则由 WebServer 的绑定地址推导
+  publicUrl: null              # 对外可达的 origin；独立端口时默认 http://host:port
+  host: 127.0.0.1              # 独立监听的绑定地址（仅 server.port 非 null 时生效）
+  port: null                   # null = 复用 DSH Web 端口；1-65535 = 独立监听
   trustProxy: false            # 反向代理后设为 true，以使用 X-Forwarded-For
   streaming: true
   pushNotifications: true

package/client.js

@@ -40,6 +40,16 @@ window.__ModuleLoader__.load({
       authOn: '已启用',
       version: '协议版本',
       runtime: '运行状态',
+      serverStatus: '监听方式',
+      serverMode: '模式',
+      serverModeShared: '复用 DSH 端口',
+      serverModeStandalone: '独立端口',
+      serverAddress: '地址',
+      serverListening: '监听中',
+      serverListeningYes: '是',
+      serverListeningNo: '否',
+      serverError: '监听错误',
+      serverNotListening: '独立端口未监听成功：请检查端口是否被占用，或修改 server.port。',
       runtimeDenied: '运行状态需要 A2A 凭据，当前页面无权读取；这不影响其他信息。',
       tasks: '任务',
       contexts: '活跃上下文',
@@ -62,11 +72,11 @@ window.__ModuleLoader__.load({
       saveError: '保存失败',
       reload: '重新读取',
       dirty: '有未保存的修改',
-      token: '访问令牌',
-      tokenHint: '写回 profile YAML；推荐改用 auth.tokenEnv 从环境变量读取。',
-      tokenPlaceholder: '留空保持不变',
+      token: 'A2A 访问令牌（内联）',
+      tokenHint: '保存后写入插件配置的 auth.token；如果鉴权模式为 none，会自动切换为 bearer。值不会回显。',
+      tokenPlaceholder: '输入新的访问令牌',
       clearToken: '清除已保存的内联令牌',
-      tokenConfigured: '已配置内联令牌',
+      tokenConfigured: '已配置内联令牌（值不会回显）',
       tokenNotConfigured: '未配置内联令牌',
       tokenEnvConfigured: '环境变量已配置：{name}',
       openCard: '打开 Agent Card',
@@ -83,6 +93,8 @@ window.__ModuleLoader__.load({
       fieldCardDescription: '描述',
       fieldCardVersion: '版本',
       fieldServerPublicUrl: '对外地址',
+      fieldServerHost: '监听地址',
+      fieldServerPort: '监听端口',
       fieldServerMountPath: '挂载路径',
       fieldServerStreaming: '流式 SSE',
       fieldServerPushNotifications: '推送通知',
@@ -139,6 +151,16 @@ window.__ModuleLoader__.load({
       authOn: 'Required',
       version: 'Protocol version',
       runtime: 'Runtime',
+      serverStatus: 'Listener',
+      serverMode: 'Mode',
+      serverModeShared: 'Shared with DSH',
+      serverModeStandalone: 'Dedicated port',
+      serverAddress: 'Address',
+      serverListening: 'Listening',
+      serverListeningYes: 'yes',
+      serverListeningNo: 'no',
+      serverError: 'Listener error',
+      serverNotListening: 'The dedicated listener is not up. Check whether the port is taken or change server.port.',
       runtimeDenied: 'Runtime counters require A2A credentials; the panel cannot read them. Everything else is unaffected.',
       tasks: 'Tasks',
       contexts: 'Active contexts',
@@ -161,11 +183,11 @@ window.__ModuleLoader__.load({
       saveError: 'Save failed',
       reload: 'Reload',
       dirty: 'Unsaved changes',
-      token: 'Access token',
-      tokenHint: 'Stored in the profile YAML. Prefer auth.tokenEnv instead.',
-      tokenPlaceholder: 'Leave empty to keep',
+      token: 'A2A access token (inline)',
+      tokenHint: 'Saved as auth.token in the plugin config. A mode of "none" switches to bearer automatically. The value is never echoed.',
+      tokenPlaceholder: 'Enter a new access token',
       clearToken: 'Clear the saved inline token',
-      tokenConfigured: 'Inline token configured',
+      tokenConfigured: 'Inline token configured (value is never shown)',
       tokenNotConfigured: 'No inline token',
       tokenEnvConfigured: 'Environment variable: {name}',
       openCard: 'Open Agent Card',
@@ -182,6 +204,8 @@ window.__ModuleLoader__.load({
       fieldCardDescription: 'Description',
       fieldCardVersion: 'Version',
       fieldServerPublicUrl: 'Public URL',
+      fieldServerHost: 'Listen host',
+      fieldServerPort: 'Listen port',
       fieldServerMountPath: 'Mount path',
       fieldServerStreaming: 'Streaming SSE',
       fieldServerPushNotifications: 'Push notifications',
@@ -427,15 +451,14 @@ window.__ModuleLoader__.load({
               if (jsonrpc && typeof jsonrpc.url === 'string') {
                 try {
                   const url = new URL(jsonrpc.url, window.location.origin)
-                  const base = `${window.location.origin}${url.pathname.replace(/\/$/, '')}`
-                  try {
-                    const healthResponse = await fetch(`${base}/health`, { cache: 'no-store', signal: controller.signal })
-                    if (healthResponse.ok) health = await healthResponse.json()
-                    else denied = healthResponse.status === 401 || healthResponse.status === 403
-                  } catch {
-                    denied = true
-                  }
-                  panelPath = `${base}/panel/config`
+                  const pathname = url.pathname.replace(/\/$/, '')
+                  // The A2A port owns health; the panel stays on the GUI origin
+                  // so the settings form reuses the browser's Harness session.
+                  const endpointBase = `${url.origin}${pathname}`
+                  const panelBase = `${window.location.origin}${pathname}`
+                  // Prefer the same-origin panel: it carries the health snapshot
+                  // and avoids a cross-origin read on the dedicated A2A port.
+                  panelPath = `${panelBase}/panel/config`
                   try {
                     const panelResponse = await fetch(panelPath, { cache: 'no-store', signal: controller.signal, credentials: 'same-origin' })
                     if (panelResponse.ok) panel = await panelResponse.json()
@@ -445,6 +468,17 @@ window.__ModuleLoader__.load({
                   } catch {
                     panelError = 'error'
                   }
+                  if (panel && panel.health) {
+                    health = panel.health
+                  } else {
+                    try {
+                      const healthResponse = await fetch(`${endpointBase}/health`, { cache: 'no-store', signal: controller.signal })
+                      if (healthResponse.ok) health = await healthResponse.json()
+                      else denied = healthResponse.status === 401 || healthResponse.status === 403
+                    } catch {
+                      /* standalone listener down: the panel status reports it */
+                    }
+                  }
                 } catch {
                   denied = true
                 }
@@ -619,7 +653,7 @@ window.__ModuleLoader__.load({
         const secretBlock = panel
           ? h(
               'div',
-              { className: 'a2aui-group' },
+              { className: 'a2aui-group', key: 'inline-token' },
               h('h5', { className: 'a2aui-group-title' }, t('token')),
               h(
                 'div',
@@ -670,8 +704,8 @@ window.__ModuleLoader__.load({
             ? h(
                 'div',
                 { className: 'a2aui-form' },
-                ...groups.map(([group, fields]) =>
-                  h(
+                ...groups.flatMap(([group, fields]) => {
+                  const node = h(
                     'div',
                     { className: 'a2aui-group', key: group },
                     h('h5', { className: 'a2aui-group-title' }, groupLabel(t, group)),
@@ -683,9 +717,9 @@ window.__ModuleLoader__.load({
                         h('div', null, renderControl(field)),
                       ),
                     ),
-                  ),
-                ),
-                secretBlock,
+                  )
+                  return group === 'auth' ? [node, secretBlock] : [node]
+                }),
                 h(
                   'div',
                   { className: 'a2aui-form-foot' },
@@ -761,6 +795,30 @@ window.__ModuleLoader__.load({
           ),
         )
 
+        const serverInfo = (state.panel && state.panel.server) || (health && health.server) || null
+        const serverSection = serverInfo
+          ? h(
+              'section',
+              { className: 'a2aui-card' },
+              h('h4', { className: 'a2aui-section-title' }, t('serverStatus')),
+              h(
+                'div',
+                { className: 'a2aui-facts' },
+                h('div', { className: 'a2aui-fact' }, h('span', { className: 'a2aui-fact-key' }, t('serverMode')), h('span', { className: 'a2aui-fact-value' }, serverInfo.mode === 'standalone' ? t('serverModeStandalone') : t('serverModeShared'))),
+                serverInfo.mode === 'standalone'
+                  ? h('div', { className: 'a2aui-fact' }, h('span', { className: 'a2aui-fact-key' }, t('serverAddress')), h('span', { className: 'a2aui-fact-value' }, `${serverInfo.host}:${serverInfo.port}`))
+                  : null,
+                h('div', { className: 'a2aui-fact' }, h('span', { className: 'a2aui-fact-key' }, t('serverListening')), h('span', { className: 'a2aui-fact-value' }, serverInfo.listening ? t('serverListeningYes') : t('serverListeningNo'))),
+              ),
+              serverInfo.error
+                ? h('p', { className: 'a2aui-status', 'data-tone': 'error' }, `${t('serverError')}: ${serverInfo.error}`)
+                : null,
+              serverInfo.mode === 'standalone' && serverInfo.listening === false
+                ? h('p', { className: 'a2aui-status', 'data-tone': 'warn' }, t('serverNotListening'))
+                : null,
+            )
+          : null
+
         const runtimeSection = health
           ? h(
               'section',
@@ -830,6 +888,7 @@ window.__ModuleLoader__.load({
           header,
           statusSection,
           endpointSection,
+          serverSection,
           runtimeSection,
           deniedSection,
           configSection,

package/cordis.patch.yml

@@ -1,7 +1,9 @@
 # dsh-a2a bundle patch: mounts the A2A (Agent2Agent) v1.0 server row.
 #
-# Defaults below are safe for a loopback deployment. To expose the agent to
-# other hosts, set `server.publicUrl` and enable `auth` in the profile patch:
+# Defaults below are safe for a loopback deployment. The row listens on its
+# own port (127.0.0.1:41241) so A2A traffic does not share the DSH Web port;
+# set `server.port: null` to reuse the DSH listener again. To expose the agent
+# to other hosts, set `server.publicUrl` and enable `auth` in the profile patch:
 #
 #   - id: a2a-server
 #     name: '@ai_mind/dsh-a2a'
@@ -19,3 +21,6 @@
       name: '@ai_mind/dsh-a2a'
       config:
         enabled: true
+        server:
+          host: 127.0.0.1
+          port: 41241

package/lib/config.js

@@ -9,6 +9,7 @@
  * @module @ai_mind/dsh-a2a/config
  */
 
+import { isIP } from 'node:net'
 import { isPlainObject, deepMerge, deepFreeze } from './util.js'
 
 /** Error raised for an invalid plugin configuration. */
@@ -44,6 +45,8 @@ export const DEFAULT_CONFIG = {
     mountPath: '/a2a',
     cardPath: '/.well-known/agent-card.json',
     publicUrl: null,
+    host: '127.0.0.1',
+    port: null,
     trustProxy: false,
     streaming: true,
     pushNotifications: true,
@@ -350,6 +353,14 @@ export function normalizeConfig(raw) {
   merged.server.mountPath = validatePath(merged.server.mountPath, 'server.mountPath', { reserved: true })
   merged.server.cardPath = validatePath(merged.server.cardPath, 'server.cardPath')
   merged.server.publicUrl = expectNullableString(merged.server.publicUrl, 'server.publicUrl', { allowEmpty: false })
+  merged.server.host = expectString(merged.server.host, 'server.host')
+  if (merged.server.host !== 'localhost' && isIP(merged.server.host) === 0) {
+    fail('server.host', 'must be an IPv4/IPv6 literal or "localhost"')
+  }
+  merged.server.port =
+    merged.server.port === null || merged.server.port === undefined
+      ? null
+      : expectInteger(merged.server.port, 'server.port', { min: 1, max: 65535 })
   if (merged.server.publicUrl !== null) {
     let url
     try {

package/lib/panel.js

@@ -30,6 +30,16 @@ const FIELDS = [
   { path: 'card.description', type: 'textarea', group: 'card' },
   { path: 'card.version', type: 'string', group: 'card' },
   { path: 'server.publicUrl', type: 'string', group: 'server', nullable: true, placeholder: 'https://agent.example.com' },
+  { path: 'server.host', type: 'string', group: 'server', placeholder: '127.0.0.1' },
+  {
+    path: 'server.port',
+    type: 'integer',
+    group: 'server',
+    nullable: true,
+    min: 1,
+    max: 65535,
+    placeholder: '留空 = 复用 DSH 端口',
+  },
   { path: 'server.mountPath', type: 'string', group: 'server' },
   { path: 'server.streaming', type: 'boolean', group: 'server' },
   { path: 'server.pushNotifications', type: 'boolean', group: 'server' },
@@ -187,9 +197,20 @@ function describe(config, entry, warnings) {
  * @param {Readonly<object>} options.config the active normalized config
  * @param {string} options.mountPath A2A mount path (for messages)
  * @param {{ info: Function, warn: Function }} options.logger
+ * @param {() => object} [options.status] live listening-mode description
+ * @param {() => object} [options.health] live health snapshot
  * @returns {import('express').Router}
  */
-export function createPanelRouter({ ctx, config, mountPath, logger }) {
+function safeHealth(health, logger) {
+  try {
+    return health()
+  } catch (error) {
+    logger.warn(`[a2a] panel health snapshot failed: ${errorMessage(error)}`)
+    return null
+  }
+}
+
+export function createPanelRouter({ ctx, config, mountPath, logger, status, health }) {
   const router = express.Router()
   const json = express.json({ limit: 256 * 1024, strict: false })
 
@@ -263,7 +284,14 @@ export function createPanelRouter({ ctx, config, mountPath, logger }) {
     }
     const payload = describe(live, entry, warnings)
     res.setHeader('Cache-Control', 'no-store')
-    res.json({ ok: true, plugin: { name: PLUGIN_NAME, version: '1.0.0' }, mountPath, ...payload })
+    res.json({
+      ok: true,
+      plugin: { name: PLUGIN_NAME, version: '1.1.1' },
+      mountPath,
+      ...payload,
+      ...(typeof status === 'function' ? { server: status() } : {}),
+      ...(typeof health === 'function' ? { health: safeHealth(health, logger) } : {}),
+    })
   })
 
   router.put('/config', json, async (req, res) => {
@@ -314,6 +342,9 @@ export function createPanelRouter({ ctx, config, mountPath, logger }) {
         if (typeof body.token !== 'string') throw new Error('token must be a string')
         if (body.token.trim() === '') throw new Error('token must not be empty')
         setAt(next, 'auth.token', body.token)
+        // A token with auth.mode "none" would be stored but never used. Treat
+        // an explicitly supplied token as the intent to enable bearer auth.
+        if ((next.auth?.mode ?? 'none') === 'none') setAt(next, 'auth.mode', 'bearer')
       }
 
       const normalized = normalizeConfig(next)
@@ -350,7 +381,13 @@ export function createPanelRouter({ ctx, config, mountPath, logger }) {
       /* keep the submitted view when the row is mid-reload */
     }
     logger.info('[a2a] configuration updated from the settings panel')
-    res.json({ ok: true, plugin: { name: PLUGIN_NAME, version: '1.0.0' }, mountPath, ...describe(live, liveEntry, []) })
+    res.json({
+      ok: true,
+      plugin: { name: PLUGIN_NAME, version: '1.1.1' },
+      mountPath,
+      ...describe(live, liveEntry, []),
+      ...(typeof status === 'function' ? { server: status() } : {}),
+    })
   })
 
   return router

package/lib/server.js

@@ -3,12 +3,20 @@
  *
  * The official `@a2a-js/sdk` supplies the protocol engine — task lifecycle,
  * JSON-RPC and HTTP+JSON transports, SSE framing, ProtoJSON codecs, push
- * notifications and Agent Card signing. This module mounts that engine on the
- * Harness Web server and wires it to the local agent runtime.
+ * notifications and Agent Card signing.
+ *
+ * Two listening modes are supported:
+ *   - shared (default): the A2A routes live on the Harness Web server, so the
+ *     endpoint uses the GUI's port and lifecycle;
+ *   - standalone (`server.port` set): a dedicated `node:http` listener owns the
+ *     card and A2A routes on its own host/port, while the Harness Web server
+ *     keeps only the public card mirror and the authenticated settings panel.
  *
  * @module @ai_mind/dsh-a2a/server
  */
 
+import http from 'node:http'
+import { isIP } from 'node:net'
 import express from 'express'
 import { A2A_PROTOCOL_VERSION } from '@a2a-js/sdk'
 import {
@@ -49,9 +57,31 @@ function createLogger(ctx) {
   }
 }
 
-/** Derive the externally visible origin, preferring the configured URL. */
+/** Write an IPv6 host in URL form. */
+function formatUrlHost(host) {
+  return isIP(host) === 6 ? `[${host}]` : host
+}
+
+/**
+ * Derive the externally visible origin.
+ *
+ * `server.publicUrl` always wins. A configured `server.port` selects the
+ * standalone listener's own origin; otherwise the Harness Web server's origin
+ * is used.
+ */
 function resolvePublicBase(config, webServer, logger) {
   if (config.server.publicUrl) return trimTrailingSlash(config.server.publicUrl)
+  if (config.server.port !== null) {
+    const host = config.server.host
+    if (host === '0.0.0.0' || host === '::') {
+      logger.warn(
+        `[a2a] server.host ${host} is a wildcard; advertising a loopback URL. ` +
+          'Set server.publicUrl to the address remote A2A clients should use.',
+      )
+    }
+    const advertised = host === '0.0.0.0' ? '127.0.0.1' : host === '::' ? '::1' : host
+    return `http://${formatUrlHost(advertised)}:${config.server.port}`
+  }
   try {
     const origin = webServer.getOrigin()
     if (typeof origin === 'string' && origin !== '') return trimTrailingSlash(origin)
@@ -134,7 +164,8 @@ function writeError(req, res, { status, code, message, restBinding, rpcCode = -3
 /**
  * One mounted A2A deployment. Mounting is synchronous so route registration
  * can participate in Cordis effects; only request handling touches async
- * agent work.
+ * agent work. The standalone listener is created here and reports its bind
+ * result through {@link A2AService.serverStatus}.
  */
 export class A2AService {
   #ctx
@@ -142,6 +173,7 @@ export class A2AService {
   #logger
   #mounted = undefined
   #unmount = undefined
+  #standalone = undefined
   #disposed = false
 
   /**
@@ -160,16 +192,50 @@ export class A2AService {
   }
 
   /**
-   * Register routes on the Harness Web server.
+   * Describe the active listening mode for health checks and the settings
+   * panel. In shared mode the DSH web server owns the socket, so `listening`
+   * only means the plugin is mounted.
+   *
+   * @returns {{ mode: 'shared'|'standalone', host: string|null, port: number|null, listening: boolean, error: string|null, publicUrl: string|null }}
+   */
+  serverStatus() {
+    const config = this.#config
+    const mounted = this.#mounted
+    if (config.server.port === null) {
+      return {
+        mode: 'shared',
+        host: null,
+        port: null,
+        listening: mounted !== undefined,
+        error: null,
+        publicUrl: mounted?.publicBaseUrl ?? null,
+      }
+    }
+    const state = this.#standalone
+    return {
+      mode: 'standalone',
+      host: config.server.host,
+      port: config.server.port,
+      listening: state?.listening === true,
+      error: state?.error ?? null,
+      publicUrl: mounted?.publicBaseUrl ?? null,
+    }
+  }
+
+  /**
+   * Mount the A2A deployment.
    *
    * @param {object} webServer the `webServer` service
-   * @returns {() => Promise<void>} disposer that unregisters routes and drains work
+   * @returns {() => Promise<void>} disposer that unregisters routes, closes the
+   *   standalone listener and drains work
    */
   mount(webServer) {
     if (this.#mounted !== undefined) throw new Error('a2a: already mounted')
     if (this.#disposed) throw new Error('a2a: service is disposed')
     const config = this.#config
     const logger = this.#logger
+    const mountPath = config.server.mountPath
+    const standalone = config.server.port !== null
 
     const credentials = resolveCredentials(config)
     const publicBaseUrl = resolvePublicBase(config, webServer, logger)
@@ -224,84 +290,59 @@ export class A2AService {
       config,
       credentials,
       logger,
-      isRestBinding: (req) => isRestBinding(req, config.server.mountPath),
-    })
-
-    const app = express()
-    app.disable('x-powered-by')
-    app.set('trust proxy', config.server.trustProxy)
-    app.set('query parser', 'simple')
-
-    app.use(createCors(config))
-    app.use((req, res, next) => {
-      res.setHeader('X-Content-Type-Options', 'nosniff')
-      next()
+      isRestBinding: (req) => isRestBinding(req, mountPath),
     })
-    if (config.server.logRequests) {
-      app.use((req, res, next) => {
-        const started = Date.now()
-        res.on('finish', () => {
-          logger.info(`${req.method} ${req.originalUrl} → ${res.statusCode} (${Date.now() - started}ms)`)
-        })
-        next()
-      })
-    }
-
-    // Parse bodies once with the configured limit. The SDK transports skip
-    // their own `express.json()` because body-parser marks the request parsed.
-    app.use(
-      express.json({
-        limit: config.limits.maxRequestBytes,
-        strict: false,
-        type: [JSON_CONTENT_TYPE, A2A_CONTENT_TYPE],
-      }),
-    )
 
-    const mountPath = config.server.mountPath
-    const jsonRpcRouter = jsonRpcHandler({ requestHandler, userBuilder: authenticator.userBuilder })
-    const restRouter = restHandler({ requestHandler, userBuilder: authenticator.userBuilder })
     const cardRouter = agentCardHandler({
       agentCardProvider: requestHandler,
       cache: { maxAge: config.server.cardCacheSeconds },
     })
-
-    // The Agent Card is discovery metadata and stays public.
-    app.use(config.server.cardPath, cardRouter)
-    // The settings panel is authenticated by the Harness Web connection, not
-    // by the A2A token, and must be mounted before the A2A auth middleware.
-    app.use(`${mountPath}/panel`, createPanelRouter({ ctx: this.#ctx, config, mountPath, logger }))
-    // Everything else below the mount path is the A2A endpoint.
-    app.use(mountPath, authenticator.middleware)
-    app.use(`${mountPath}/rest`, restRouter)
-    app.use(mountPath, jsonRpcRouter)
-
-    app.get(mountPath, (req, res) => {
-      res.setHeader('Allow', 'POST')
-      writeError(req, res, {
-        status: 405,
-        code: 'METHOD_NOT_ALLOWED',
-        message: `The A2A JSON-RPC endpoint only accepts POST; REST clients use ${mountPath}/rest.`,
-        restBinding: false,
-      })
+    const jsonRpcRouter = jsonRpcHandler({ requestHandler, userBuilder: authenticator.userBuilder })
+    const restRouter = restHandler({ requestHandler, userBuilder: authenticator.userBuilder })
+    const healthSnapshot = () =>
+      this.#health({ runtime, executor, taskStore, authenticator, publicBaseUrl, extendedCard })
+    const panelRouter = createPanelRouter({
+      ctx: this.#ctx,
+      config,
+      mountPath,
+      logger,
+      status: () => this.serverStatus(),
+      // The panel is same-origin with the GUI but possibly cross-origin to the
+      // A2A port; return the health snapshot here so the panel does not depend
+      // on CORS being enabled on the standalone listener.
+      health: healthSnapshot,
     })
 
-    if (config.server.health) {
-      app.get(`${mountPath}/health`, (req, res) => {
-        res.setHeader('Cache-Control', 'no-store')
-        res.json(this.#health({ runtime, executor, taskStore, authenticator, publicBaseUrl, extendedCard }))
+    const applyCommon = (app) => {
+      app.disable('x-powered-by')
+      app.set('trust proxy', config.server.trustProxy)
+      app.set('query parser', 'simple')
+      app.use(createCors(config))
+      app.use((req, res, next) => {
+        res.setHeader('X-Content-Type-Options', 'nosniff')
+        next()
       })
+      if (config.server.logRequests) {
+        app.use((req, res, next) => {
+          const started = Date.now()
+          res.on('finish', () => {
+            logger.info(`${req.method} ${req.originalUrl} → ${res.statusCode} (${Date.now() - started}ms)`)
+          })
+          next()
+        })
+      }
+      // Parse bodies once with the configured limit. The SDK transports skip
+      // their own `express.json()` because body-parser marks the request parsed.
+      app.use(
+        express.json({
+          limit: config.limits.maxRequestBytes,
+          strict: false,
+          type: [JSON_CONTENT_TYPE, A2A_CONTENT_TYPE],
+        }),
+      )
     }
 
-    app.use((req, res) => {
-      writeError(req, res, {
-        status: 404,
-        code: 'NOT_FOUND',
-        message: `No A2A route matches ${req.method} ${req.originalUrl}`,
-        restBinding: isRestBinding(req, mountPath),
-      })
-    })
-
-    app.use((error, req, res, next) => {
+    const a2aErrorHandler = (error, req, res, next) => {
       if (res.headersSent) {
         res.end()
         return
@@ -324,9 +365,67 @@ export class A2AService {
         rpcCode: isParseError ? -32700 : isTooLarge ? -32600 : -32603,
       })
       void next
+    }
+
+    const panelErrorHandler = (error, req, res, next) => {
+      if (res.headersSent) {
+        res.end()
+        return
+      }
+      const status =
+        typeof error?.status === 'number' && error.status >= 400 && error.status <= 599 ? error.status : 500
+      if (status >= 500) logger.warn(`[a2a] panel request failed: ${errorMessage(error)}`)
+      res.statusCode = status
+      res.setHeader('Content-Type', JSON_CONTENT_TYPE)
+      res.setHeader('Cache-Control', 'no-store')
+      res.end(
+        JSON.stringify({
+          error: status >= 500 ? 'INTERNAL' : 'INVALID_ARGUMENT',
+          message: error?.type === 'entity.parse.failed' ? 'Invalid JSON payload' : errorMessage(error),
+        }),
+      )
+      void next
+    }
+
+    const a2aApp = express()
+    applyCommon(a2aApp)
+    // The Agent Card is discovery metadata and stays public.
+    a2aApp.use(config.server.cardPath, cardRouter)
+    if (!standalone) {
+      // In shared mode the panel is part of the same app and must precede the
+      // A2A auth middleware.
+      a2aApp.use(`${mountPath}/panel`, panelRouter)
+    }
+    // Everything below the mount path is the A2A endpoint.
+    a2aApp.use(mountPath, authenticator.middleware)
+    a2aApp.use(`${mountPath}/rest`, restRouter)
+    a2aApp.use(mountPath, jsonRpcRouter)
+    a2aApp.get(mountPath, (req, res) => {
+      res.setHeader('Allow', 'POST')
+      writeError(req, res, {
+        status: 405,
+        code: 'METHOD_NOT_ALLOWED',
+        message: `The A2A JSON-RPC endpoint only accepts POST; REST clients use ${mountPath}/rest.`,
+        restBinding: false,
+      })
     })
+    if (config.server.health) {
+      a2aApp.get(`${mountPath}/health`, (req, res) => {
+        res.setHeader('Cache-Control', 'no-store')
+        res.json(healthSnapshot())
+      })
+    }
+    a2aApp.use((req, res) => {
+      writeError(req, res, {
+        status: 404,
+        code: 'NOT_FOUND',
+        message: `No A2A route matches ${req.method} ${req.originalUrl}`,
+        restBinding: isRestBinding(req, mountPath),
+      })
+    })
+    a2aApp.use(a2aErrorHandler)
 
-    const callApp = (req, res) => {
+    const wrap = (app) => (req, res) => {
       try {
         app(req, res)
       } catch (error) {
@@ -340,11 +439,30 @@ export class A2AService {
         }
       }
     }
+    const callA2A = wrap(a2aApp)
+
+    let callPanel
+    if (standalone) {
+      // The settings panel stays on the Harness Web origin so it can reuse the
+      // GUI's authenticated browser session. It is not exposed on the A2A port.
+      const panelApp = express()
+      panelApp.disable('x-powered-by')
+      panelApp.set('trust proxy', config.server.trustProxy)
+      panelApp.use(`${mountPath}/panel`, panelRouter)
+      panelApp.use((req, res) => {
+        res.statusCode = 404
+        res.setHeader('Content-Type', JSON_CONTENT_TYPE)
+        res.end(JSON.stringify({ error: 'NOT_FOUND', message: `No settings panel route matches ${req.url}` }))
+      })
+      panelApp.use(panelErrorHandler)
+      callPanel = wrap(panelApp)
+    }
 
     const routeDisposers = []
-    const registerRoute = (route, label, { optional = false } = {}) => {
+    let standaloneState
+    const registerRoute = (route, handler, label, { optional = false } = {}) => {
       try {
-        routeDisposers.push(webServer.register({ ...route, handler: callApp }))
+        routeDisposers.push(webServer.register({ ...route, handler }))
       } catch (error) {
         if (optional) {
           logger.warn(`[a2a] cannot register ${label} at ${route.path}: ${errorMessage(error)}`)
@@ -354,8 +472,70 @@ export class A2AService {
       }
     }
 
-    registerRoute({ kind: 'exact', path: config.server.cardPath }, 'agent card')
-    registerRoute({ kind: 'prefix', path: mountPath }, 'A2A endpoint')
+    const cleanupAfterFailure = () => {
+      for (const dispose of routeDisposers.splice(0).reverse()) {
+        try {
+          dispose()
+        } catch {
+          /* ignore during rollback */
+        }
+      }
+      if (standaloneState !== undefined) {
+        standaloneState.server.close()
+        standaloneState.server.closeAllConnections?.()
+        this.#standalone = undefined
+      }
+      void executor.dispose().catch((error) => logger.warn(`[a2a] rollback dispose failed: ${errorMessage(error)}`))
+      void runtime.shutdown().catch((error) => logger.warn(`[a2a] rollback shutdown failed: ${errorMessage(error)}`))
+    }
+
+    try {
+      // Discovery stays reachable on the Harness Web origin in both modes: in
+      // shared mode it is the endpoint, and in standalone mode it bootstraps
+      // the settings panel (the card itself points at the dedicated port).
+      registerRoute({ kind: 'exact', path: config.server.cardPath }, callA2A, 'agent card')
+      if (standalone) {
+        registerRoute(
+          { kind: 'prefix', path: `${mountPath}/panel` },
+          callPanel,
+          'settings panel',
+        )
+        const server = http.createServer(callA2A)
+        standaloneState = {
+          server,
+          host: config.server.host,
+          port: config.server.port,
+          listening: false,
+          error: null,
+        }
+        this.#standalone = standaloneState
+        server.on('error', (error) => {
+          standaloneState.error = errorMessage(error)
+          standaloneState.listening = false
+          logger.error(
+            `[a2a] standalone listener ${config.server.host}:${config.server.port} failed: ${errorMessage(error)}`,
+          )
+        })
+        server.on('listening', () => {
+          standaloneState.listening = true
+          standaloneState.error = null
+          logger.info(
+            `[a2a] standalone listener ready on ${formatUrlHost(config.server.host)}:${config.server.port}`,
+          )
+        })
+        try {
+          server.listen(config.server.port, config.server.host)
+        } catch (error) {
+          standaloneState.error = errorMessage(error)
+          logger.error(`[a2a] standalone listener cannot bind: ${errorMessage(error)}`)
+        }
+      } else {
+        registerRoute({ kind: 'prefix', path: mountPath }, callA2A, 'A2A endpoint')
+      }
+    } catch (error) {
+      cleanupAfterFailure()
+      throw error
+    }
 
     const sweepTimer = setInterval(() => {
       try {
@@ -384,11 +564,21 @@ export class A2AService {
     runtime.start()
 
     const startedAt = Date.now()
-    this.#mounted = { startedAt }
-    logger.info(
-      `A2A v${A2A_PROTOCOL_VERSION} server ready: ${publicBaseUrl}${mountPath} (JSON-RPC), ` +
-        `${publicBaseUrl}${mountPath}/rest (HTTP+JSON), card ${publicBaseUrl}${config.server.cardPath}`,
-    )
+    this.#mounted = { startedAt, publicBaseUrl, standalone }
+    if (standalone) {
+      logger.info(
+        `A2A v${A2A_PROTOCOL_VERSION} standalone server: ${publicBaseUrl}${mountPath} (JSON-RPC), ` +
+          `${publicBaseUrl}${mountPath}/rest (HTTP+JSON), card ${publicBaseUrl}${config.server.cardPath}`,
+      )
+      logger.info(
+        `settings panel and card mirror on the Harness Web origin: ${webServer.getOrigin()}${mountPath}/panel/config`,
+      )
+    } else {
+      logger.info(
+        `A2A v${A2A_PROTOCOL_VERSION} server ready (shared port): ${publicBaseUrl}${mountPath} (JSON-RPC), ` +
+          `${publicBaseUrl}${mountPath}/rest (HTTP+JSON), card ${publicBaseUrl}${config.server.cardPath}`,
+      )
+    }
     logger.info(
       `auth=${authenticator.describe().mode} streaming=${config.server.streaming} ` +
         `push=${config.server.pushNotifications} extendedCard=${extendedCard}`,
@@ -406,6 +596,15 @@ export class A2AService {
           logger.warn(`[a2a] route disposal failed: ${errorMessage(error)}`)
         }
       }
+      const state = this.#standalone
+      this.#standalone = undefined
+      if (state !== undefined) {
+        await new Promise((resolve) => {
+          state.server.close(() => resolve())
+          state.server.closeAllConnections?.()
+        })
+        state.listening = false
+      }
       await executor.dispose()
       await runtime.shutdown()
       this.#mounted = undefined
@@ -426,6 +625,7 @@ export class A2AService {
       version: config.card.version,
       publicUrl: publicBaseUrl,
       uptimeSeconds: mounted === undefined ? 0 : Math.round((Date.now() - mounted.startedAt) / 1000),
+      server: this.serverStatus(),
       interfaces: [
         { protocolBinding: 'JSONRPC', url: `${publicBaseUrl}${config.server.mountPath}` },
         { protocolBinding: 'HTTP+JSON', url: `${publicBaseUrl}${config.server.mountPath}/rest` },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai_mind/dsh-a2a",
-  "version": "1.0.0",
+  "version": "1.1.1",
   "description": "Production A2A (Agent2Agent) v1.0 server for DeepSeek Harness agents: JSON-RPC + HTTP+JSON bindings, streaming, tasks, push notifications and signed Agent Cards.",
   "type": "module",
   "license": "MIT",