@ai_mind/dsh-a2a 1.3.0 → 1.4.0

package/README.md

@@ -278,12 +278,48 @@ A2A 创建的 Harness 会话使用 `agent.cwd` 作为工作目录，GUI 按会
 
 ### 会话与并发
 
-- **一个 `contextId` = 一个 Harness Agent 会话**。同一 context 下的多个任务串行执行，保留对话历史；不同 context 并行执行。
+- **同一租户、认证主体和 `contextId` 对应一个持久化 Harness Session**。同一 context 下的多个任务串行执行，保留对话历史；不同 context 并行执行。
 - 创建 Agent 时会挂载 `agent.preset` 指定的 Agent 预设（默认取部署的默认预设），因此 A2A Agent 拥有与 GUI 会话一致的工具与提示词组合，再叠加下面的沙箱与审批策略。
-- 空闲 context 在 `agent.contextIdleTtlMs`（默认 15 分钟）后被回收，Agent 会话随之销毁。
+- 空闲 context 在 `agent.contextIdleTtlMs`（默认 15 分钟）后释放运行中的 Agent；保留绑定与历史。下次通过 `ctx.agents.resume({ resumeSessionId })` 恢复同一 Session，服务重启后也一样。绑定不随任务 TTL 或空闲 TTL 删除。
 - 全局并发上限 `agent.maxConcurrentTasks`（默认 4）；超出的任务最多等待 `agent.queueTimeoutMs`，仍无法开始时进入 `TASK_STATE_REJECTED`。
 - 单回合上限 `agent.turnTimeoutMs`（默认 15 分钟）；超时会取消该回合并返回 `TASK_STATE_FAILED`。
 
+### 持久化部署与升级
+
+运行时要求 Harness 的 `agents.resume` 与持久化 `sessionPersistence.flush` API。缺少服务时任务失败，不降级到易失会话。创建 Session 和完成每轮后使用公共 `flush()` 确认落盘；该 API 是服务级屏障，会刷新同一 Harness 中其他活跃 Session，因此磁盘故障可能同时影响多个任务。
+
+```yaml
+agent:
+  contextStorePath: /var/lib/dsh-a2a/context-bindings
+```
+
+- 绑定目录默认是 `<解析后的 agent.cwd>/.a2a-contexts`。生产应显式指定固定的绝对持久路径，独立于工作目录、发布目录和临时容器。修改 cwd 或切换挂载点时，不可遗漏原绑定目录。
+- **绑定目录与 Harness Session 持久化目录必须一起保留/备份**。绑定记录使用原子创建、文件/目录 fsync，目录默认权限 `0700`、文件 `0600`；文件名是 scope 与 context 的哈希，不保存 token 或对话正文。需要支持硬链接和 fsync 的本地文件系统。
+- 认证主体采用服务端 `auth.clients[].id`（或配置推导出的凭据 ID），再与 SDK 的 tenant、认证状态一起隔离。同一凭据下不同终端可恢复同一 context；不同用户不可共享同一个 client ID。轮换 token 时保留 client ID；重排 `auth.tokens` 可能改变自动生成的主体 ID，建议使用命名 clients。`auth.mode: none` 下所有匿名调用共享匿名主体，不提供用户隔离。
+- 同一运行时内同 scope/context 串行；创建、排队和存储刷新期间不做空闲释放。不同进程/运行时竞争同一 Session 时依赖 Harness 的独占写所有权，冲突请求失败并可在原持有者释放后重试，不进行分布式排队。多副本须共享同一绑定及 Session 后端且保证后端所有权语义，不能各挂一套独立目录。
+- 绑定已存在但损坏、Session 缺失、存储不可用、preset 无法挂载或恢复失败时，任务进入 `TASK_STATE_FAILED`，`status.message.parts[].text` 包含 `A2A_HISTORY_UNAVAILABLE`。不会自动删除绑定、替换 Session 或清空历史。首次绑定落盘后、首次 Session 创建前崩溃，也遵守此规则；保留该预留记录而不是猜测它未承载过历史。
+- 故障恢复：先停止对应流量并备份两个目录，恢复丢失的 Session 后以原 context 重试。若能确认某预留记录从未成功创建 Session，可由维护者通过 Harness 在记录的**相同 Session ID** 下创建空 Session（使用记录中的 cwd/preset），然后重试。无法确认时不删除/改写绑定；保留记录，明确告知用户原历史不可恢复，由用户另开新对话。当前没有自动修复/重置接口。
+- 绑定没有自动保留期。运维清理需按会话删除策略协调两份存储；单独删绑定会让服务器把再次到来的 context 视为首次使用，不能靠 Session ID 自动重建它。
+
+**旧版本迁移边界：** 旧代码只在内存记录 context，随机 Session ID 的 metadata 只有 cwd/preset，没有 context 或认证主体。已回收或进程已退出的旧映射无法自动恢复；即使原 Session 日志还在，也不能靠内容猜测归属。若升级前能在可信运行时/日志中取得精确的 `(tenant, authenticated, client ID, contextId) → Session ID`，且已验证 Session 所有权和日志完整，维护者可离线导入 v1 绑定（格式见 `lib/context-bindings.js`，键通过其 `contextKey()` 生成），保留原 cwd/preset。没有该证据的旧对话只能从新映射开始，**不承诺自动继承旧历史**。应在升级前向用户说明，避免把新建空 Session 误称为历史恢复。
+
+### 手机与其他 A2A 客户端契约
+
+保持 A2A 1.0 `SendMessage`/`SendStreamingMessage` 契约：同一对话复用 contextId、每条消息使用新 messageId、仅发送本轮内容；普通任务完成后创建新 task，只有协议允许续接的非终态 task 才传旧 taskId。服务端通过 Session 事件恢复模型输入，不要求客户端回传整段历史。切换认证主体或 tenant 会进入隔离会话；客户端应持久化 contextId 及其 endpoint/身份归属。
+
+历史恢复失败时保持原 contextId，不自动重置或以历史全文重放。建议显示失败状态中的 `A2A_HISTORY_UNAVAILABLE` 提示并让用户重试/联系维护者。这不新增请求字段；现有手机版本可继续使用。服务端 task 查询仍是有限保留的内存存储，Session 恢复不意味着旧 task 在重启后可查询。
+
+### 本地恢复验证
+
+```sh
+npm test
+DSH_NODE_MODULES="$HOME/.dsh/profiles/node_modules" npm run test:harness
+# 从 ai-mind-mobile 仓库执行：
+DSH_NODE_MODULES="$HOME/.dsh/profiles/node_modules" npm --prefix ../ai-mind-dsh-a2a run test:harness
+```
+
+`DSH_NODE_MODULES` 应指向待部署 Harness 的实际 node_modules，缺省会明确报错，不静默跳过。本机验证使用 Node 25.8.0、Harness `0.2.1-rc.2`。测试在临时目录构建真实 Cordis、AgentLoop、Session 和 JSONL 存储；只有模型适配器是无状态暗号回忆 oracle。它从真正传入适配器的 `request.messages` 查找随机标记，不持有上轮记忆。检查连续追问、TTL、整套 Harness 重建、真实子进程直接退出、主体/租户隔离、排队/回收竞争、重复写所有权及历史缺失。断言包含 Session ID、用户与助手历史和回忆输出；不需要模型凭据，不读取在线会话，不等同于实际云端模型效果或线上事故归因。
+
 ### 提示词与附件
 
 - `text` 部分拼接为提示词；`data` 部分以 JSON 代码块注入；`url` 部分以引用形式注入。
@@ -415,6 +451,7 @@ agent:
   queueTimeoutMs: 60000
   turnTimeoutMs: 900000
   contextIdleTtlMs: 900000
+  contextStorePath: null        # 绝对持久目录；默认 <cwd>/.a2a-contexts；生产务必固定路径
 
 limits:
   maxRequestBytes: 8388608

package/lib/bridge.js

@@ -1,11 +1,11 @@
 /**
  * DeepSeek Harness agent bridge for A2A execution.
  *
- * One A2A `contextId` maps to one long-lived Harness agent session, so several
+ * One scoped A2A `contextId` durably maps to one Harness session, so several
  * single-turn A2A tasks that share a context keep their conversation state.
  * Turns inside a context run serially; distinct contexts run concurrently up
  * to the configured limit. Idle contexts are disposed after
- * `agent.contextIdleTtlMs` so a busy A2A endpoint cannot leak sessions.
+ * `agent.contextIdleTtlMs`; the next turn resumes their persisted history.
  *
  * The bridge deliberately touches only public Harness services (`ctx.agents`,
  * `ctx.approval`) and the documented `Agent` handle, never package internals.
@@ -14,8 +14,10 @@
  */
 
 import { mkdir } from 'node:fs/promises'
+import { join } from 'node:path'
 import { newId, errorMessage } from './util.js'
 import { withTimeout } from './limits.js'
+import { ContextBindings, contextKey } from './context-bindings.js'
 
 /** Marker used as the durable source of prompts injected by this plugin. */
 const PROMPT_SOURCE = { kind: 'user' }
@@ -112,10 +114,14 @@ class ContextWorker {
   #lastUsed = Date.now()
   #creating = undefined
   #disposed = false
+  #pending = 0
+  #disposal
+  #predecessor
 
-  constructor(runtime, contextId) {
+  constructor(runtime, contextId, predecessor) {
     this.#runtime = runtime
     this.#contextId = contextId
+    this.#predecessor = predecessor
   }
 
   get contextId() {
@@ -131,7 +137,7 @@ class ContextWorker {
   }
 
   get busy() {
-    return this.#turn !== undefined
+    return this.#pending > 0
   }
 
   touch() {
@@ -151,6 +157,7 @@ class ContextWorker {
    * @returns {Promise<{ canceled: boolean, error?: Error, text: string, turnEnd?: object }>}
    */
   async runTurn(turn, { prompt, timeoutMs }) {
+    this.#pending += 1
     const previous = this.#tail
     let release
     this.#tail = new Promise((resolveTail) => {
@@ -162,6 +169,7 @@ class ContextWorker {
       if (turn.cancelRequested) return { canceled: true, text: '' }
       return await this.#runNow(turn, prompt, timeoutMs)
     } finally {
+      this.#pending -= 1
       release()
       this.touch()
     }
@@ -170,7 +178,7 @@ class ContextWorker {
   async #runNow(turn, prompt, timeoutMs) {
     this.touch()
     const agent = await this.#ensureAgent()
-    if (turn.cancelRequested) return { canceled: true, text: '' }
+    if (turn.cancelRequested || this.#disposed) return { canceled: true, text: '' }
 
     this.#turn = turn
     turn.running = true
@@ -204,6 +212,12 @@ class ContextWorker {
     if (turn.cancelRequested) {
       return { canceled: true, text: turn.finalText || turn.emitted, turnEnd: turn.turnEnd }
     }
+    // whenIdle is a loop barrier, not a storage durability barrier.
+    try {
+      await this.#runtime.persistence().flush()
+    } catch (error) {
+      turn.error = new Error(`A2A_HISTORY_UNAVAILABLE: cannot persist conversation: ${errorMessage(error)}`)
+    }
     const failure = turn.error ?? turnEndError(turn.turnEnd)
     const canceledByAgent =
       turn.turnEnd?.kind === 'aborted' && (turn.turnEnd.reason?.kind === 'user' || turn.turnEnd.reason?.kind === 'parent')
@@ -270,41 +284,54 @@ class ContextWorker {
   async #createAgent() {
     const runtime = this.#runtime
     const config = runtime.config
-    const cwd = await runtime.resolveCwd()
-    if (typeof cwd !== 'string' || !cwd.startsWith('/')) {
-      throw new Error(`A2A agent cwd must be an absolute path, got ${JSON.stringify(cwd)}`)
+    await this.#predecessor
+    runtime.persistence()
+    if (typeof runtime.ctx.agents.resume !== 'function') {
+      throw new Error('A2A_HISTORY_UNAVAILABLE: Harness agents.resume is required')
     }
-    await mkdir(cwd, { recursive: true })
-    const workspace = await runtime.ensureWorkspace(cwd)
-    const sessionId = `session-a2a-${newId()}`
     const agentOptions = runtime.agentOptions()
+    const bindings = await runtime.bindings()
     const presets = runtime.ctx.get?.('agentPresets')
-    let presetId
-    if (presets !== undefined) {
-      try {
-        presetId = (await presets.resolve(runtime.config.agent.preset ?? undefined)).id
-      } catch (error) {
-        throw new Error(
-          `cannot resolve the agent preset ${JSON.stringify(runtime.config.agent.preset ?? 'default')}: ${errorMessage(error)}`,
-        )
-      }
+    const { binding, fresh } = await bindings.reserve(this.#contextId, async () => {
+      const cwd = await runtime.resolveCwd()
+      if (typeof cwd !== 'string' || !cwd.startsWith('/')) throw new Error('A2A agent cwd must be an absolute path')
+      await mkdir(cwd, { recursive: true })
+      let presetId
+      if (presets !== undefined) presetId = (await presets.resolve(config.agent.preset ?? undefined)).id
+      return { sessionId: `session-a2a-${newId()}`, cwd, presetId: presetId ?? null }
+    })
+    const { sessionId, cwd, presetId } = binding
+    if (presetId !== null && presets === undefined) {
+      throw new Error('A2A_HISTORY_UNAVAILABLE: original agent preset service is unavailable')
     }
+    const workspace = await runtime.ensureWorkspace(cwd)
     let handle
     try {
-      handle = await runtime.ctx.agents.create({
-        sessionId,
-        meta: { cwd, ...(presetId === undefined ? {} : { agentPreset: presetId }) },
+      handle = await runtime.ctx.agents[fresh ? 'create' : 'resume']({
+        ...(fresh
+          ? { sessionId, meta: { cwd, ...(presetId === null ? {} : { agentPreset: presetId }) } }
+          : { resumeSessionId: sessionId }),
         ...(Object.keys(agentOptions).length > 0 ? { agentOptions } : {}),
         setup: async (agentCtx, agent) => {
           this.#installListeners(agentCtx, agent)
           // Mounting the preset composes the same tools, prompt sections and
           // hooks a GUI session receives; without it an A2A agent would run
           // with only the root composition's bare tool set.
-          if (presets !== undefined && presetId !== undefined) await presets.mount(agentCtx, presetId)
+          if (presets !== undefined && presetId !== null) await presets.mount(agentCtx, presetId)
         },
       })
     } catch (error) {
-      throw new Error(`cannot create a Harness agent for A2A context ${this.#contextId}: ${errorMessage(error)}`)
+      throw new Error(`A2A_HISTORY_UNAVAILABLE: cannot ${fresh ? 'create' : 'resume'} Harness session ${sessionId}: ${errorMessage(error)}`)
+    }
+    // Never acknowledge a session until it is durably materialized.
+    try {
+      if (handle.agent.id !== sessionId || handle.agent.session.id !== sessionId) {
+        throw new Error('Harness returned a different session identity')
+      }
+      await runtime.persistence().flush()
+    } catch (error) {
+      await handle.dispose().catch(() => {})
+      throw new Error(`A2A_HISTORY_UNAVAILABLE: ${errorMessage(error)}`)
     }
     this.#handle = handle
     this.#agent = handle.agent
@@ -321,7 +348,7 @@ class ContextWorker {
       runtime.logger.warn(`[a2a] could not apply agent policy: ${errorMessage(error)}`)
     }
     runtime.logger.info(
-      `[a2a] created agent session ${handle.agent.id} for context ${this.#contextId} ` +
+      `[a2a] ${fresh ? 'created' : 'resumed'} agent session ${handle.agent.id} for context ${this.#contextId} ` +
         `(cwd=${cwd}, preset=${presetId ?? 'none'}, sandbox=${config.agent.sandboxMode}, approval=${config.agent.approvalPolicy})`,
     )
     return handle.agent
@@ -344,19 +371,19 @@ class ContextWorker {
     }
   }
 
-  async dispose() {
-    if (this.#disposed) return
+  dispose() {
+    if (this.#disposal) return this.#disposal
     this.#disposed = true
-    const handle = this.#handle
-    this.#handle = undefined
-    this.#agent = undefined
-    if (handle === undefined) return
-    try {
-      await handle.dispose()
-      this.#runtime.logger.info(`[a2a] disposed agent session for context ${this.#contextId}`)
-    } catch (error) {
-      this.#runtime.logger.warn(`[a2a] agent dispose failed for context ${this.#contextId}: ${errorMessage(error)}`)
-    }
+    if (this.#turn) this.cancel(this.#turn)
+    this.#disposal = (async () => {
+      // Includes queued work and in-flight factory setup, which busy used to miss.
+      await this.#tail
+      const handle = this.#handle
+      this.#handle = undefined
+      this.#agent = undefined
+      if (handle) await handle.dispose()
+    })()
+    return this.#disposal
   }
 }
 
@@ -370,6 +397,7 @@ export class AgentRuntime {
   #workers = new Map()
   #sweepTimer = undefined
   #workspacePromise = undefined
+  #bindingsPromise
   #disposed = false
   #stats = { turns: 0, completed: 0, failed: 0, canceled: 0 }
 
@@ -397,6 +425,20 @@ export class AgentRuntime {
     return this.#logger
   }
 
+  persistence() {
+    const persistence = this.#ctx.get?.('sessionPersistence')
+    if (typeof persistence?.flush !== 'function') {
+      throw new Error('A2A_HISTORY_UNAVAILABLE: durable Harness sessionPersistence is required')
+    }
+    return persistence
+  }
+
+  bindings() {
+    return this.#bindingsPromise ??= (async () => new ContextBindings(
+      this.#config.agent.contextStorePath ?? join(await this.resolveCwd(), '.a2a-contexts'),
+    ))()
+  }
+
   /**
    * Resolve the model route for a new A2A agent.
    *
@@ -509,25 +551,29 @@ export class AgentRuntime {
       if (now - worker.lastUsed < ttl) continue
       stale.push(worker)
     }
+    let disposed = 0
     for (const worker of stale) {
-      this.#workers.delete(worker.contextId)
+      if (worker.disposed || worker.busy || now - worker.lastUsed < ttl) continue
       await worker.dispose()
+      disposed += 1
+      if (this.#workers.get(worker.contextId) === worker) this.#workers.delete(worker.contextId)
     }
-    return stale.length
+    return disposed
   }
 
   /**
    * Get or create the worker for one context.
    *
    * @param {string} contextId
+   * @param {object} [callContext] SDK-authenticated owner and tenant (never message metadata)
    * @returns {ContextWorker}
    */
-  acquire(contextId) {
+  acquire(contextId, callContext) {
     if (this.#disposed) throw new Error('A2A runtime is shutting down')
-    const key = contextId === '' || contextId === undefined ? `context-${newId()}` : contextId
+    const key = contextKey(contextId === '' || contextId === undefined ? `context-${newId()}` : contextId, callContext)
     let worker = this.#workers.get(key)
     if (worker === undefined || worker.disposed) {
-      worker = new ContextWorker(this, key)
+      worker = new ContextWorker(this, key, worker?.dispose())
       this.#workers.set(key, worker)
     }
     worker.touch()
@@ -558,6 +604,9 @@ export class AgentRuntime {
     }
     const workers = [...this.#workers.values()]
     this.#workers.clear()
-    await Promise.allSettled(workers.map((worker) => worker.dispose()))
+    const results = await Promise.allSettled(workers.map((worker) => worker.dispose()))
+    for (const result of results) {
+      if (result.status === 'rejected') this.#logger.warn(`[a2a] agent dispose failed: ${errorMessage(result.reason)}`)
+    }
   }
 }

package/lib/config.js

@@ -103,6 +103,7 @@ export const DEFAULT_CONFIG = {
     queueTimeoutMs: 60000,
     turnTimeoutMs: 900000,
     contextIdleTtlMs: 900000,
+    contextStorePath: null,
   },
   limits: {
     maxRequestBytes: 8 * 1024 * 1024,
@@ -464,6 +465,10 @@ export function normalizeConfig(raw) {
   if (merged.agent.cwd !== null && !merged.agent.cwd.startsWith('/')) {
     fail('agent.cwd', 'must be an absolute path')
   }
+  merged.agent.contextStorePath = expectNullableString(merged.agent.contextStorePath, 'agent.contextStorePath')
+  if (merged.agent.contextStorePath !== null && !merged.agent.contextStorePath.startsWith('/')) {
+    fail('agent.contextStorePath', 'must be an absolute path')
+  }
   merged.agent.workspaceTitle = expectNullableString(merged.agent.workspaceTitle, 'agent.workspaceTitle', {
     allowEmpty: false,
   })

package/lib/context-bindings.js

@@ -0,0 +1,54 @@
+/** Durable, immutable context -> Harness session identities. No TTL: TTL only evicts live agents. */
+import { createHash, randomUUID } from 'node:crypto'
+import { mkdir, open, readFile, link, unlink } from 'node:fs/promises'
+import { join } from 'node:path'
+
+export function contextKey(contextId, context) {
+  // Length-delimited encoding prevents separator collisions. Never trust message metadata.
+  return createHash('sha256').update(JSON.stringify([
+    context?.tenant ?? '', context?.user?.isAuthenticated === true,
+    context?.user?.userName ?? '', contextId,
+  ])).digest('hex')
+}
+
+export class ContextBindings {
+  constructor(directory) { this.directory = directory }
+
+  async reserve(key, create) {
+    const path = join(this.directory, `${key}.json`)
+    const read = async () => {
+      const binding = JSON.parse(await readFile(path, 'utf8'))
+      if (binding.version !== 1 || binding.key !== key ||
+          !/^session-a2a-[a-zA-Z0-9-]+$/.test(binding.sessionId) ||
+          typeof binding.cwd !== 'string' || !binding.cwd.startsWith('/') ||
+          !(binding.presetId === null || typeof binding.presetId === 'string')) {
+        throw new Error('invalid context binding')
+      }
+      return { binding, fresh: false }
+    }
+    try {
+      try { return await read() } catch (error) { if (error.code !== 'ENOENT') throw error }
+      await mkdir(this.directory, { recursive: true, mode: 0o700 })
+      const binding = { ...await create(), version: 1, key }
+      const temporary = join(this.directory, `.${key}-${randomUUID()}.tmp`)
+      try {
+        const file = await open(temporary, 'wx', 0o600)
+        try {
+          await file.writeFile(JSON.stringify(binding) + '\n')
+          await file.sync()
+        } finally { await file.close() }
+        // Atomic create-if-absent, including competing runtimes/processes. A loser
+        // must resume the winner's ID; Harness enforces exclusive session ownership.
+        try { await link(temporary, path) } catch (error) {
+          if (error.code === 'EEXIST') return await read()
+          throw error
+        }
+        const directory = await open(this.directory, 'r')
+        try { await directory.sync() } finally { await directory.close() }
+        return { binding, fresh: true }
+      } finally { await unlink(temporary).catch(error => { if (error.code !== 'ENOENT') throw error }) }
+    } catch (error) {
+      throw new Error(`A2A_HISTORY_UNAVAILABLE: context binding cannot be loaded or stored: ${error.message}`, { cause: error })
+    }
+  }
+}

package/lib/executor.js

@@ -227,7 +227,7 @@ export class HarnessAgentExecutor {
         return
       }
 
-      const worker = this.#runtime.acquire(contextId)
+      const worker = this.#runtime.acquire(contextId, requestContext.context)
       state.worker = worker
       const turn = worker.createTurn(taskId, {
         onStart: () => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai_mind/dsh-a2a",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "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",
@@ -48,7 +48,8 @@
     "express": "^5.1.0"
   },
   "scripts": {
-    "test": "node --test test/*.test.js"
+    "test": "node --test test/*.test.js",
+    "test:harness": "node --test test/integration/*.test.js"
   },
   "engines": {
     "node": ">=20"