@ai_mind/dsh-a2a 0.0.0-stage → 1.0.0

package/lib/bridge.js

@@ -0,0 +1,518 @@
+/**
+ * DeepSeek Harness agent bridge for A2A execution.
+ *
+ * One A2A `contextId` maps to one long-lived Harness agent 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.
+ *
+ * The bridge deliberately touches only public Harness services (`ctx.agents`,
+ * `ctx.approval`) and the documented `Agent` handle, never package internals.
+ *
+ * @module @ai_mind/dsh-a2a/bridge
+ */
+
+import { mkdir } from 'node:fs/promises'
+import { newId, errorMessage } from './util.js'
+import { withTimeout } from './limits.js'
+
+/** Marker used as the durable source of prompts injected by this plugin. */
+const PROMPT_SOURCE = { kind: 'user' }
+
+/**
+ * Build a Harness user message from a prompt string.
+ *
+ * @param {string} text
+ * @returns {object} a complete Harness `UserMessage`
+ */
+function createUserMessage(text) {
+  return {
+    id: newId(),
+    role: 'user',
+    content: [{ type: 'text', text }],
+    source: PROMPT_SOURCE,
+  }
+}
+
+/** @returns {string} concatenated text of an assistant content-block array */
+function assistantText(content) {
+  if (!Array.isArray(content)) return ''
+  return content
+    .map((block) => (block?.type === 'text' && typeof block.text === 'string' ? block.text : ''))
+    .join('')
+}
+
+function turnEndError(turnEnd) {
+  if (turnEnd === undefined) return undefined
+  switch (turnEnd.kind) {
+    case 'error':
+      return new Error(turnEnd.error?.message ? `Model request failed: ${turnEnd.error.message}` : 'Model request failed')
+    case 'blocked':
+      return new Error('The agent declined to process this request.')
+    case 'interrupted':
+      return new Error('The agent turn was interrupted.')
+    case 'aborted':
+      return new Error('The agent turn was aborted.')
+    default:
+      return undefined
+  }
+}
+
+/** One A2A turn: its live streaming callbacks and its cancellation flag. */
+class Turn {
+  constructor(taskId, { onStart, onDelta, onReset }) {
+    this.taskId = taskId
+    this.onStart = onStart
+    this.onDelta = onDelta
+    this.onReset = onReset
+    this.cancelRequested = false
+    this.running = false
+    this.closed = false
+    this.emitted = ''
+    this.streamedAny = false
+    this.needsReset = false
+    this.finalText = ''
+    this.assistantSeen = false
+    this.turnEnd = undefined
+    this.error = undefined
+  }
+
+  emitDelta(text) {
+    if (this.cancelRequested || text === '') return
+    if (this.needsReset) {
+      this.needsReset = false
+      this.emitted = ''
+      try {
+        this.onReset?.()
+      } catch {
+        /* presentation only */
+      }
+    }
+    this.streamedAny = true
+    this.emitted += text
+    try {
+      this.onDelta?.(text)
+    } catch {
+      /* presentation only */
+    }
+  }
+}
+
+/**
+ * Serial turn runner for one A2A context, owning exactly one Harness agent.
+ */
+class ContextWorker {
+  #runtime
+  #contextId
+  #handle = undefined
+  #agent = undefined
+  #turn = undefined
+  #tail = Promise.resolve()
+  #lastUsed = Date.now()
+  #creating = undefined
+  #disposed = false
+
+  constructor(runtime, contextId) {
+    this.#runtime = runtime
+    this.#contextId = contextId
+  }
+
+  get contextId() {
+    return this.#contextId
+  }
+
+  get disposed() {
+    return this.#disposed
+  }
+
+  get lastUsed() {
+    return this.#lastUsed
+  }
+
+  get busy() {
+    return this.#turn !== undefined
+  }
+
+  touch() {
+    this.#lastUsed = Date.now()
+  }
+
+  /** @returns {Turn} a turn handle that may be cancelled before it starts */
+  createTurn(taskId, callbacks) {
+    return new Turn(taskId, callbacks)
+  }
+
+  /**
+   * Run one turn, waiting for any earlier turn in the same context.
+   *
+   * @param {Turn} turn
+   * @param {{ prompt: string, timeoutMs: number }} options
+   * @returns {Promise<{ canceled: boolean, error?: Error, text: string, turnEnd?: object }>}
+   */
+  async runTurn(turn, { prompt, timeoutMs }) {
+    const previous = this.#tail
+    let release
+    this.#tail = new Promise((resolveTail) => {
+      release = resolveTail
+    })
+    try {
+      await previous.catch(() => {})
+      if (this.#disposed) return { canceled: true, text: '', error: new Error('A2A context was disposed') }
+      if (turn.cancelRequested) return { canceled: true, text: '' }
+      return await this.#runNow(turn, prompt, timeoutMs)
+    } finally {
+      release()
+      this.touch()
+    }
+  }
+
+  async #runNow(turn, prompt, timeoutMs) {
+    this.touch()
+    const agent = await this.#ensureAgent()
+    if (turn.cancelRequested) return { canceled: true, text: '' }
+
+    this.#turn = turn
+    turn.running = true
+    try {
+      try {
+        turn.onStart?.()
+      } catch {
+        /* presentation only */
+      }
+      agent.followup(createUserMessage(prompt))
+      await withTimeout(
+        agent.whenIdle(),
+        timeoutMs,
+        () => {
+          try {
+            agent.cancel({ kind: 'hook', reason: 'A2A turn timeout' })
+          } catch {
+            /* already settled */
+          }
+        },
+        `agent turn exceeded agent.turnTimeoutMs (${timeoutMs} ms)`,
+      )
+    } catch (error) {
+      turn.error ??= error instanceof Error ? error : new Error(errorMessage(error))
+    } finally {
+      turn.running = false
+      turn.closed = true
+      if (this.#turn === turn) this.#turn = undefined
+    }
+
+    if (turn.cancelRequested) {
+      return { canceled: true, text: turn.finalText || turn.emitted, turnEnd: turn.turnEnd }
+    }
+    const failure = turn.error ?? turnEndError(turn.turnEnd)
+    const canceledByAgent =
+      turn.turnEnd?.kind === 'aborted' && (turn.turnEnd.reason?.kind === 'user' || turn.turnEnd.reason?.kind === 'parent')
+    if (canceledByAgent && failure === undefined) {
+      return { canceled: true, text: turn.finalText || turn.emitted, turnEnd: turn.turnEnd }
+    }
+    const text = turn.finalText !== '' ? turn.finalText : turn.emitted
+    return { canceled: false, text, error: failure, turnEnd: turn.turnEnd }
+  }
+
+  #installListeners(agentCtx, agent) {
+    agentCtx.on('agent/assistant-stream', (payload) => {
+      const turn = this.#turn
+      if (turn === undefined || turn.closed) return
+      if (payload?.agent !== undefined && payload.agent !== agent) return
+      const frame = payload?.frame
+      if (frame === undefined || frame === null) return
+      if (frame.type === 'start') {
+        if (turn.streamedAny) turn.needsReset = true
+        turn.streamedAny = false
+        return
+      }
+      if (frame.type !== 'chunk') return
+      const chunk = frame.chunk
+      if (chunk?.type !== 'text-delta') return
+      if (typeof chunk.text === 'string') turn.emitDelta(chunk.text)
+    })
+
+    agentCtx.on('session/event', (session, event) => {
+      const turn = this.#turn
+      if (turn === undefined || turn.closed) return
+      if (session !== agent.session) return
+      if (event?.type === 'assistant/message') {
+        const text = assistantText(event.data?.message?.content)
+        if (text !== '') {
+          turn.finalText = text
+          turn.assistantSeen = true
+        }
+      } else if (event?.type === 'turn/end') {
+        turn.turnEnd = event.data?.reason
+      }
+    })
+
+    agentCtx.on('agent/error', (payload) => {
+      const turn = this.#turn
+      if (turn === undefined || turn.closed) return
+      if (payload?.agent !== undefined && payload.agent !== agent) return
+      const failure = payload?.error
+      turn.error = new Error(failure?.message ? `${failure.code ?? 'AGENT_ERROR'}: ${failure.message}` : 'agent execution failed')
+    })
+  }
+
+  async #ensureAgent() {
+    if (this.#agent !== undefined && !this.#disposed) return this.#agent
+    if (this.#creating !== undefined) return this.#creating
+    this.#creating = this.#createAgent()
+    try {
+      return await this.#creating
+    } finally {
+      this.#creating = undefined
+    }
+  }
+
+  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 mkdir(cwd, { recursive: true })
+    const sessionId = `session-a2a-${newId()}`
+    const agentOptions = runtime.agentOptions()
+    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)}`,
+        )
+      }
+    }
+    let handle
+    try {
+      handle = await runtime.ctx.agents.create({
+        sessionId,
+        meta: { cwd, ...(presetId === undefined ? {} : { agentPreset: presetId }) },
+        ...(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)
+        },
+      })
+    } catch (error) {
+      throw new Error(`cannot create a Harness agent for A2A context ${this.#contextId}: ${errorMessage(error)}`)
+    }
+    this.#handle = handle
+    this.#agent = handle.agent
+    try {
+      runtime.applyAgentPolicy(handle.agent)
+    } catch (error) {
+      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} ` +
+        `(cwd=${cwd}, preset=${presetId ?? 'none'}, sandbox=${config.agent.sandboxMode}, approval=${config.agent.approvalPolicy})`,
+    )
+    return handle.agent
+  }
+
+  /**
+   * Request cancellation of one turn. A queued turn is merely marked so it is
+   * skipped when its slot arrives; only the turn that is actually running may
+   * abort the shared agent, otherwise cancelling one task in a context would
+   * kill its sibling task.
+   */
+  cancel(turn) {
+    if (turn !== undefined) turn.cancelRequested = true
+    if (turn !== undefined && this.#turn === turn) {
+      try {
+        this.#agent?.cancel({ kind: 'user' })
+      } catch (error) {
+        this.#runtime.logger.warn(`[a2a] agent cancel failed: ${errorMessage(error)}`)
+      }
+    }
+  }
+
+  async dispose() {
+    if (this.#disposed) return
+    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)}`)
+    }
+  }
+}
+
+/**
+ * Owns A2A contexts and their Harness agents.
+ */
+export class AgentRuntime {
+  #ctx
+  #config
+  #logger
+  #workers = new Map()
+  #sweepTimer = undefined
+  #disposed = false
+  #stats = { turns: 0, completed: 0, failed: 0, canceled: 0 }
+
+  /**
+   * @param {object} options
+   * @param {object} options.ctx owning Cordis context
+   * @param {Readonly<object>} options.config
+   * @param {{ info: (...args: unknown[]) => void, warn: (...args: unknown[]) => void }} options.logger
+   */
+  constructor({ ctx, config, logger }) {
+    this.#ctx = ctx
+    this.#config = config
+    this.#logger = logger
+  }
+
+  get ctx() {
+    return this.#ctx
+  }
+
+  get config() {
+    return this.#config
+  }
+
+  get logger() {
+    return this.#logger
+  }
+
+  /**
+   * Resolve the model route for a new A2A agent.
+   *
+   * Explicit `agent.provider`/`agent.model` win. Otherwise the deployment's
+   * default model selection is used, exactly like the GUI's new-session flow;
+   * without either, prompt assembly would later fail on `{{model}}`, so the
+   * caller gets an actionable error up front.
+   *
+   * @returns {object} agentOptions limited to configured values
+   */
+  agentOptions() {
+    const options = {}
+    if (this.#config.agent.provider && this.#config.agent.model) {
+      options.provider = this.#config.agent.provider
+      options.model = this.#config.agent.model
+      if (this.#config.agent.reasoningEffort) options.reasoningEffort = this.#config.agent.reasoningEffort
+    } else {
+      const selection = this.#ctx.get?.('agentDefaultModel')?.currentSelection?.()
+      if (selection?.provider && selection?.model) {
+        options.provider = selection.provider
+        options.model = selection.model
+        const effort = this.#config.agent.reasoningEffort ?? selection.reasoningEffort
+        if (effort) options.reasoningEffort = effort
+      } else {
+        throw new Error(
+          'no model is configured for the A2A agent: set agent.provider and agent.model in the plugin config, ' +
+            'or configure a default model for this profile',
+        )
+      }
+    }
+    if (this.#config.agent.maxTokens !== null) options.maxTokens = this.#config.agent.maxTokens
+    return options
+  }
+
+  /** @returns {Promise<string>} the absolute workspace directory for agents */
+  async resolveCwd() {
+    if (this.#config.agent.cwd) return this.#config.agent.cwd
+    const workingDirectory = this.#ctx.get?.('workingDirectory')
+    const fallback = workingDirectory?.defaultDirectory
+    return typeof fallback === 'string' && fallback !== '' ? fallback : process.cwd()
+  }
+
+  /**
+   * Apply the configured sandbox mode and approval policy to a created agent.
+   * The permission-preset listener has already pinned the deployment default,
+   * so this append/override must happen after `agents.create()` resolves.
+   */
+  applyAgentPolicy(agent) {
+    const approval = this.#ctx.get?.('approval')
+    if (approval !== undefined && this.#config.agent.approvalPolicy !== 'inherit') {
+      approval.setPolicy(agent, this.#config.agent.approvalPolicy)
+    }
+    if (this.#config.agent.sandboxMode !== 'inherit') {
+      agent.session.append('sandbox/mode', { mode: this.#config.agent.sandboxMode })
+    }
+  }
+
+  start() {
+    if (this.#sweepTimer !== undefined) return
+    const interval = Math.max(15000, Math.min(60000, this.#config.agent.contextIdleTtlMs || 60000))
+    this.#sweepTimer = setInterval(() => {
+      this.sweepIdleContexts().catch((error) => this.#logger.warn(`[a2a] context sweep failed: ${errorMessage(error)}`))
+    }, interval)
+    this.#sweepTimer.unref?.()
+  }
+
+  /** Dispose contexts that have been idle past the configured TTL. */
+  async sweepIdleContexts(now = Date.now()) {
+    const ttl = this.#config.agent.contextIdleTtlMs
+    if (ttl <= 0) return 0
+    const stale = []
+    for (const worker of this.#workers.values()) {
+      if (worker.busy) continue
+      if (now - worker.lastUsed < ttl) continue
+      stale.push(worker)
+    }
+    for (const worker of stale) {
+      this.#workers.delete(worker.contextId)
+      await worker.dispose()
+    }
+    return stale.length
+  }
+
+  /**
+   * Get or create the worker for one context.
+   *
+   * @param {string} contextId
+   * @returns {ContextWorker}
+   */
+  acquire(contextId) {
+    if (this.#disposed) throw new Error('A2A runtime is shutting down')
+    const key = contextId === '' || contextId === undefined ? `context-${newId()}` : contextId
+    let worker = this.#workers.get(key)
+    if (worker === undefined || worker.disposed) {
+      worker = new ContextWorker(this, key)
+      this.#workers.set(key, worker)
+    }
+    worker.touch()
+    return worker
+  }
+
+  /** Record one finished turn for the health endpoint. */
+  recordOutcome(kind) {
+    this.#stats.turns += 1
+    if (kind === 'completed') this.#stats.completed += 1
+    else if (kind === 'canceled') this.#stats.canceled += 1
+    else this.#stats.failed += 1
+  }
+
+  /** @returns {object} live runtime statistics */
+  stats() {
+    let active = 0
+    for (const worker of this.#workers.values()) if (worker.busy) active += 1
+    return { ...this.#stats, contexts: this.#workers.size, activeContexts: active }
+  }
+
+  async shutdown() {
+    if (this.#disposed) return
+    this.#disposed = true
+    if (this.#sweepTimer !== undefined) {
+      clearInterval(this.#sweepTimer)
+      this.#sweepTimer = undefined
+    }
+    const workers = [...this.#workers.values()]
+    this.#workers.clear()
+    await Promise.allSettled(workers.map((worker) => worker.dispose()))
+  }
+}