@ai_mind/dsh-a2a 0.0.0-stage → 1.0.0

package/lib/executor.js

@@ -0,0 +1,357 @@
+/**
+ * A2A `AgentExecutor` implementation backed by the Harness agent runtime.
+ *
+ * Responsibilities:
+ *   - translate the SDK event-bus contract into a well-formed task lifecycle
+ *     (`SUBMITTED` → `WORKING` → terminal state, with streaming artifacts);
+ *   - serialize turns inside one A2A context and bound total concurrency;
+ *   - implement cancellation for both queued and running turns;
+ *   - turn every failure into a `TASK_STATE_FAILED` status carrying a
+ *     human-readable message instead of leaving a task stuck in `WORKING`.
+ *
+ * @module @ai_mind/dsh-a2a/executor
+ */
+
+import { AgentEvent } from '@a2a-js/sdk/server'
+import { Role, TaskState } from '@a2a-js/sdk'
+import { errorMessage, newId, nowIso, truncate } from './util.js'
+import { buildAgentPrompt } from './prompt.js'
+import { Semaphore } from './limits.js'
+
+/** Artifact id used for the assistant's textual answer. */
+const RESPONSE_ARTIFACT_ID = 'response'
+
+/** @returns {object} an A2A `Message` in SDK object form */
+function agentMessage({ taskId, contextId, text }) {
+  return {
+    role: Role.ROLE_AGENT,
+    messageId: newId(),
+    taskId,
+    contextId,
+    parts: [
+      {
+        content: { $case: 'text', value: text },
+        metadata: undefined,
+        filename: '',
+        mediaType: 'text/plain',
+      },
+    ],
+    metadata: {},
+    extensions: [],
+    referenceTaskIds: [],
+  }
+}
+
+/** @returns {object} a text-only A2A artifact */
+function textArtifact(text) {
+  return {
+    artifactId: RESPONSE_ARTIFACT_ID,
+    name: 'response',
+    description: 'Final response from the DeepSeek Harness agent.',
+    parts: [
+      {
+        content: { $case: 'text', value: text },
+        metadata: undefined,
+        filename: '',
+        mediaType: 'text/plain',
+      },
+    ],
+    metadata: undefined,
+    extensions: [],
+  }
+}
+
+/**
+ * A2A executor bridging request events to `AgentRuntime`.
+ */
+export class HarnessAgentExecutor {
+  #runtime
+  #config
+  #logger
+  #semaphore
+  #active = new Map()
+  #taskContexts = new Map()
+  #maxContextEntries
+  #disposed = false
+
+  /**
+   * @param {object} options
+   * @param {import('./bridge.js').AgentRuntime} options.runtime
+   * @param {Readonly<object>} options.config
+   * @param {{ info: (...args: unknown[]) => void, warn: (...args: unknown[]) => void }} options.logger
+   */
+  constructor({ runtime, config, logger }) {
+    this.#runtime = runtime
+    this.#config = config
+    this.#logger = logger
+    this.#semaphore = new Semaphore(config.agent.maxConcurrentTasks)
+    this.#maxContextEntries = Math.max(1000, config.tasks.maxTasks)
+  }
+
+  /** @returns {{ active: number, queued: number, max: number }} */
+  concurrency() {
+    return this.#semaphore.stats()
+  }
+
+  /** Publish one status update, remembering task context ids for cancellation. */
+  #status(eventBus, taskId, contextId, state, messageText) {
+    this.#remember(taskId, contextId)
+    const status = {
+      state,
+      message: messageText === undefined ? undefined : agentMessage({ taskId, contextId, text: messageText }),
+      timestamp: nowIso(),
+    }
+    eventBus.publish(
+      AgentEvent.statusUpdate({
+        taskId,
+        contextId,
+        status,
+        metadata: undefined,
+      }),
+    )
+  }
+
+  #remember(taskId, contextId) {
+    if (contextId === undefined || contextId === '') return
+    if (this.#taskContexts.has(taskId)) {
+      this.#taskContexts.delete(taskId)
+    } else if (this.#taskContexts.size >= this.#maxContextEntries) {
+      const oldest = this.#taskContexts.keys().next().value
+      if (oldest !== undefined) this.#taskContexts.delete(oldest)
+    }
+    this.#taskContexts.set(taskId, contextId)
+  }
+
+  #artifact(eventBus, taskId, contextId, text, { lastChunk, replace }) {
+    eventBus.publish(
+      AgentEvent.artifactUpdate({
+        taskId,
+        contextId,
+        artifact: textArtifact(text),
+        append: !replace,
+        lastChunk,
+        metadata: undefined,
+      }),
+    )
+  }
+
+  /**
+   * Execute one A2A message turn.
+   *
+   * @param {import('@a2a-js/sdk/server').RequestContext} requestContext
+   * @param {import('@a2a-js/sdk/server').ExecutionEventBus} eventBus
+   */
+  async execute(requestContext, eventBus) {
+    const taskId = requestContext.taskId
+    const contextId = requestContext.contextId
+    const userMessage = requestContext.userMessage
+    const existingTask = requestContext.task
+
+    const state = {
+      taskId,
+      contextId,
+      terminal: false,
+      cancelRequested: false,
+      turn: undefined,
+      worker: undefined,
+      emitted: '',
+      settle: undefined,
+    }
+    state.settled = new Promise((resolve) => {
+      state.settle = resolve
+    })
+    this.#active.set(taskId, state)
+    this.#remember(taskId, contextId)
+
+    const claimTerminal = () => {
+      if (state.terminal) return false
+      state.terminal = true
+      return true
+    }
+
+    // Every execution must begin with a Task or Message event.
+    const snapshot =
+      existingTask ??
+      {
+        id: taskId,
+        contextId,
+        status: { state: TaskState.TASK_STATE_SUBMITTED, message: undefined, timestamp: nowIso() },
+        artifacts: [],
+        history: [userMessage],
+        metadata: {},
+      }
+    eventBus.publish(AgentEvent.task(snapshot))
+
+    let permit
+    try {
+      try {
+        permit = await this.#semaphore.acquire({ timeoutMs: this.#config.agent.queueTimeoutMs })
+      } catch (error) {
+        if (claimTerminal()) {
+          this.#status(
+            eventBus,
+            taskId,
+            contextId,
+            TaskState.TASK_STATE_REJECTED,
+            `The A2A server is at capacity (${errorMessage(error)}). Retry later.`,
+          )
+        }
+        this.#runtime.recordOutcome('failed')
+        return
+      }
+
+      if (state.cancelRequested) {
+        if (claimTerminal()) {
+          this.#status(eventBus, taskId, contextId, TaskState.TASK_STATE_CANCELED, 'Task canceled.')
+        }
+        this.#runtime.recordOutcome('canceled')
+        return
+      }
+
+      let prompt
+      try {
+        const cwd = await this.#runtime.resolveCwd()
+        const built = await buildAgentPrompt({
+          message: userMessage,
+          config: this.#config,
+          cwd,
+          logger: this.#logger,
+        })
+        prompt = built.text
+        if (prompt.trim() === '') throw new Error('message contains no usable content parts')
+      } catch (error) {
+        if (claimTerminal()) {
+          this.#status(eventBus, taskId, contextId, TaskState.TASK_STATE_FAILED, `Invalid request: ${errorMessage(error)}`)
+        }
+        this.#runtime.recordOutcome('failed')
+        return
+      }
+
+      const worker = this.#runtime.acquire(contextId)
+      state.worker = worker
+      const turn = worker.createTurn(taskId, {
+        onStart: () => {
+          if (!state.terminal && !state.cancelRequested) {
+            this.#status(eventBus, taskId, contextId, TaskState.TASK_STATE_WORKING)
+          }
+        },
+        onDelta: (text) => {
+          if (state.terminal || state.cancelRequested) return
+          state.emitted += text
+          this.#artifact(eventBus, taskId, contextId, text, { lastChunk: false, replace: false })
+        },
+        onReset: () => {
+          if (state.terminal || state.cancelRequested) return
+          state.emitted = ''
+          this.#artifact(eventBus, taskId, contextId, '', { lastChunk: false, replace: true })
+        },
+      })
+      state.turn = turn
+
+      if (state.cancelRequested) {
+        if (claimTerminal()) {
+          this.#status(eventBus, taskId, contextId, TaskState.TASK_STATE_CANCELED, 'Task canceled.')
+        }
+        this.#runtime.recordOutcome('canceled')
+        return
+      }
+
+      let outcome
+      try {
+        outcome = await worker.runTurn(turn, {
+          prompt,
+          timeoutMs: this.#config.agent.turnTimeoutMs,
+        })
+      } catch (error) {
+        if (claimTerminal()) {
+          this.#status(eventBus, taskId, contextId, TaskState.TASK_STATE_FAILED, errorMessage(error))
+        }
+        this.#runtime.recordOutcome('failed')
+        return
+      }
+
+      if (outcome.canceled || state.cancelRequested) {
+        if (claimTerminal()) {
+          this.#status(eventBus, taskId, contextId, TaskState.TASK_STATE_CANCELED, 'Task canceled.')
+        }
+        this.#runtime.recordOutcome('canceled')
+        return
+      }
+
+      if (outcome.error) {
+        if (claimTerminal()) {
+          this.#status(eventBus, taskId, contextId, TaskState.TASK_STATE_FAILED, truncate(outcome.error.message, 4000))
+        }
+        this.#runtime.recordOutcome('failed')
+        return
+      }
+
+      const text = truncate(outcome.text ?? '', this.#config.limits.maxArtifactChars)
+      if (text !== '' && !state.terminal) {
+        // Consolidate the streamed chunks into one authoritative artifact.
+        this.#artifact(eventBus, taskId, contextId, text, { lastChunk: true, replace: true })
+      }
+      if (claimTerminal()) {
+        this.#status(eventBus, taskId, contextId, TaskState.TASK_STATE_COMPLETED)
+      }
+      this.#runtime.recordOutcome('completed')
+    } catch (error) {
+      this.#logger.warn(`[a2a] task ${taskId} failed unexpectedly: ${errorMessage(error)}`)
+      if (claimTerminal()) {
+        this.#status(eventBus, taskId, contextId, TaskState.TASK_STATE_FAILED, errorMessage(error))
+      }
+      this.#runtime.recordOutcome('failed')
+    } finally {
+      this.#active.delete(taskId)
+      state.settle()
+      permit?.()
+    }
+  }
+
+  /**
+   * Request cancellation of a running or queued turn.
+   *
+   * @param {string} taskId
+   * @param {import('@a2a-js/sdk/server').ExecutionEventBus} eventBus
+   */
+  async cancelTask(taskId, eventBus) {
+    const state = this.#active.get(taskId)
+    if (state === undefined) {
+      // No executor state: the task either finished concurrently or the SDK
+      // is cancelling a task whose execution never started. Publish a
+      // terminal CANCELED status so the SDK's cancel wait always settles.
+      const contextId = this.#taskContexts.get(taskId) ?? ''
+      this.#status(eventBus, taskId, contextId, TaskState.TASK_STATE_CANCELED, 'Task canceled.')
+      return
+    }
+    state.cancelRequested = true
+    if (state.turn !== undefined && state.worker !== undefined) {
+      state.worker.cancel(state.turn)
+    }
+    await Promise.race([state.settled, new Promise((resolve) => setTimeout(resolve, 10000).unref?.())])
+    if (!state.terminal) {
+      state.terminal = true
+      this.#status(eventBus, taskId, state.contextId, TaskState.TASK_STATE_CANCELED, 'Task canceled.')
+    }
+  }
+
+  /** Cancel every in-flight turn during shutdown and release the executor. */
+  async dispose() {
+    this.#disposed = true
+    for (const state of this.#active.values()) {
+      state.cancelRequested = true
+      try {
+        state.worker?.cancel(state.turn)
+      } catch {
+        /* shutting down */
+      }
+    }
+    this.#active.clear()
+    this.#taskContexts.clear()
+  }
+
+  /** @returns {boolean} whether shutdown has begun */
+  get disposed() {
+    return this.#disposed
+  }
+}

package/lib/files.js

@@ -0,0 +1,52 @@
+/**
+ * Workspace attachment retention.
+ *
+ * Inbound `raw` file parts are written under `<cwd>/<files.directory>/<taskId>`
+ * so the agent's sandboxed tools can read them. Those directories must not
+ * accumulate forever, so the server sweeps ones older than the configured
+ * retention window on the same timer as task retention.
+ *
+ * @module @ai_mind/dsh-a2a/files
+ */
+
+import { readdir, rm, stat } from 'node:fs/promises'
+import { join, resolve, sep } from 'node:path'
+import { errorMessage } from './util.js'
+
+/**
+ * Delete stale task attachment directories.
+ *
+ * @param {object} options
+ * @param {string} options.cwd absolute session workspace
+ * @param {string} options.directory relative inbox directory
+ * @param {number} options.retentionMs maximum age before deletion (0 disables)
+ * @param {{ warn: (...args: unknown[]) => void }} options.logger
+ * @returns {Promise<{ removed: number }>}
+ */
+export async function sweepAttachmentDirectories({ cwd, directory, retentionMs, logger }) {
+  if (retentionMs <= 0) return { removed: 0 }
+  const root = resolve(cwd, directory)
+  if (root !== resolve(cwd) && !root.startsWith(`${resolve(cwd)}${sep}`)) return { removed: 0 }
+  let entries
+  try {
+    entries = await readdir(root, { withFileTypes: true })
+  } catch (error) {
+    if (error?.code !== 'ENOENT') logger.warn(`[a2a] attachment sweep failed: ${errorMessage(error)}`)
+    return { removed: 0 }
+  }
+  const now = Date.now()
+  let removed = 0
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue
+    const path = join(root, entry.name)
+    try {
+      const info = await stat(path)
+      if (now - info.mtimeMs < retentionMs) continue
+      await rm(path, { recursive: true, force: true })
+      removed += 1
+    } catch (error) {
+      logger.warn(`[a2a] cannot remove attachment directory ${path}: ${errorMessage(error)}`)
+    }
+  }
+  return { removed }
+}

package/lib/limits.js

@@ -0,0 +1,133 @@
+/**
+ * Concurrency primitives used by the executor.
+ *
+ * @module @ai_mind/dsh-a2a/limits
+ */
+
+/**
+ * A FIFO counting semaphore with optional acquisition timeout and abort.
+ *
+ * A waiter that times out or aborts is removed from the queue, so a late
+ * release can never hand a permit to an abandoned request.
+ */
+export class Semaphore {
+  #max
+  #active = 0
+  #queue = []
+
+  /** @param {number} max maximum simultaneous holders */
+  constructor(max) {
+    this.#max = Math.max(1, max)
+  }
+
+  /** @returns {{ active: number, queued: number, max: number }} */
+  stats() {
+    return { active: this.#active, queued: this.#queue.length, max: this.#max }
+  }
+
+  /**
+   * Acquire one permit.
+   *
+   * @param {{ timeoutMs?: number, signal?: AbortSignal }} [options]
+   * @returns {Promise<() => void>} an idempotent release function
+   * @throws when the wait times out or the signal aborts
+   */
+  acquire(options = {}) {
+    const { timeoutMs = 0, signal } = options
+    if (signal?.aborted) return Promise.reject(signal.reason ?? new Error('aborted'))
+
+    if (this.#active < this.#max) {
+      this.#active += 1
+      return Promise.resolve(this.#makeRelease())
+    }
+
+    return new Promise((resolve, reject) => {
+      const waiter = { resolve, reject, timer: undefined, onAbort: undefined, done: false }
+
+      const cleanup = () => {
+        if (waiter.timer !== undefined) clearTimeout(waiter.timer)
+        if (waiter.onAbort !== undefined) signal?.removeEventListener('abort', waiter.onAbort)
+      }
+
+      const remove = () => {
+        const index = this.#queue.indexOf(waiter)
+        if (index !== -1) this.#queue.splice(index, 1)
+      }
+
+      waiter.fail = (error) => {
+        if (waiter.done) return
+        waiter.done = true
+        cleanup()
+        remove()
+        reject(error)
+      }
+
+      waiter.grant = () => {
+        if (waiter.done) return
+        waiter.done = true
+        cleanup()
+        this.#active += 1
+        resolve(this.#makeRelease())
+      }
+
+      if (timeoutMs > 0) {
+        waiter.timer = setTimeout(() => {
+          waiter.fail(new Error('timed out waiting for an execution slot'))
+        }, timeoutMs)
+        waiter.timer.unref?.()
+      }
+      if (signal !== undefined) {
+        waiter.onAbort = () => waiter.fail(signal.reason ?? new Error('aborted'))
+        signal.addEventListener('abort', waiter.onAbort, { once: true })
+      }
+
+      this.#queue.push(waiter)
+    })
+  }
+
+  #makeRelease() {
+    let released = false
+    return () => {
+      if (released) return
+      released = true
+      this.#active = Math.max(0, this.#active - 1)
+      const next = this.#queue.shift()
+      if (next !== undefined) next.grant()
+    }
+  }
+}
+
+/**
+ * Race a promise against a timeout. `onTimeout` runs before the rejection so
+ * callers can cancel underlying work.
+ *
+ * @template T
+ * @param {Promise<T>} promise
+ * @param {number} ms
+ * @param {() => void} [onTimeout]
+ * @param {string} [message]
+ * @returns {Promise<T>}
+ */
+export function withTimeout(promise, ms, onTimeout, message = 'operation timed out') {
+  if (ms <= 0) return promise
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      try {
+        onTimeout?.()
+      } finally {
+        reject(new Error(message))
+      }
+    }, ms)
+    timer.unref?.()
+    promise.then(
+      (value) => {
+        clearTimeout(timer)
+        resolve(value)
+      },
+      (error) => {
+        clearTimeout(timer)
+        reject(error)
+      },
+    )
+  })
+}