@ai_mind/dsh-a2a 0.0.0-stage → 1.0.0

package/lib/server.js

@@ -0,0 +1,456 @@
+/**
+ * A2A server assembly: Agent Card, transports, authentication and DSH routes.
+ *
+ * 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.
+ *
+ * @module @ai_mind/dsh-a2a/server
+ */
+
+import express from 'express'
+import { A2A_PROTOCOL_VERSION } from '@a2a-js/sdk'
+import {
+  DefaultPushNotificationSender,
+  DefaultRequestHandler,
+  InMemoryPushNotificationStore,
+} from '@a2a-js/sdk/server'
+import { agentCardHandler, jsonRpcHandler, restHandler } from '@a2a-js/sdk/server/express'
+import { buildAgentCard, buildExtendedCard, createCardSigner, isAuthEnabled } from './card.js'
+import { createAuthenticator } from './auth.js'
+import { createPanelRouter } from './panel.js'
+import { A2ATaskStore, GuardedPushNotificationStore } from './store.js'
+import { HarnessAgentExecutor } from './executor.js'
+import { AgentRuntime } from './bridge.js'
+import { errorMessage, trimTrailingSlash } from './util.js'
+import { sweepAttachmentDirectories } from './files.js'
+import { resolveCredentials } from './config.js'
+
+const JSON_CONTENT_TYPE = 'application/json'
+const A2A_CONTENT_TYPE = 'application/a2a+json'
+
+/** Minimal structured logger over the Cordis logger. */
+function createLogger(ctx) {
+  const render = (args) => ['[a2a]', ...args.map((value) => (typeof value === 'string' ? value : errorMessage(value)))].join(' ')
+  const emit = (level, args) => {
+    try {
+      const logger = ctx.logger
+      if (typeof logger?.[level] === 'function') logger[level](render(args))
+      else if (typeof logger?.log === 'function') logger.log(render(args))
+    } catch {
+      /* logging must never fail a request */
+    }
+  }
+  return {
+    info: (...args) => emit('info', args),
+    warn: (...args) => emit('warn', args),
+    error: (...args) => emit('error', args),
+  }
+}
+
+/** Derive the externally visible origin, preferring the configured URL. */
+function resolvePublicBase(config, webServer, logger) {
+  if (config.server.publicUrl) return trimTrailingSlash(config.server.publicUrl)
+  try {
+    const origin = webServer.getOrigin()
+    if (typeof origin === 'string' && origin !== '') return trimTrailingSlash(origin)
+  } catch {
+    /* not listening yet; fall through */
+  }
+  const port = Number(webServer.port)
+  if (Number.isInteger(port) && port > 0) {
+    logger.warn(`[a2a] webServer.getOrigin() unavailable; advertising http://127.0.0.1:${port}`)
+    return `http://127.0.0.1:${port}`
+  }
+  logger.warn('[a2a] cannot determine a public origin; set server.publicUrl in the plugin config')
+  return 'http://127.0.0.1'
+}
+
+/** @returns {boolean} whether the request targets the REST binding. */
+function isRestBinding(req, mountPath) {
+  const path = String(req.originalUrl ?? req.url ?? '')
+  return path.startsWith(`${mountPath}/rest`)
+}
+
+/** Build the CORS middleware for the configured policy. */
+function createCors(config) {
+  const cors = config.server.cors
+  return (req, res, next) => {
+    if (!cors.enabled) {
+      next()
+      return
+    }
+    const origin = req.headers.origin
+    const wildcard = cors.origins.includes('*')
+    const allowed = wildcard ? '*' : origin !== undefined && cors.origins.includes(origin) ? origin : null
+    if (allowed !== null) {
+      res.setHeader('Access-Control-Allow-Origin', allowed)
+      if (!wildcard) res.setHeader('Vary', 'Origin')
+      if (cors.allowCredentials) res.setHeader('Access-Control-Allow-Credentials', 'true')
+      res.setHeader('Access-Control-Expose-Headers', 'A2A-Extensions, A2A-Version, ETag')
+    }
+    if (req.method === 'OPTIONS') {
+      if (allowed !== null) {
+        res.setHeader('Access-Control-Allow-Methods', 'GET, POST, DELETE, OPTIONS')
+        res.setHeader(
+          'Access-Control-Allow-Headers',
+          `authorization, content-type, a2a-version, a2a-extensions, ${config.auth.headerName}`,
+        )
+        res.setHeader('Access-Control-Max-Age', String(cors.maxAgeSeconds))
+      }
+      res.statusCode = 204
+      res.end()
+      return
+    }
+    next()
+  }
+}
+
+/** Write one error body in the shape of the binding the caller used. */
+function writeError(req, res, { status, code, message, restBinding, rpcCode = -32603 }) {
+  if (res.headersSent) {
+    res.end()
+    return
+  }
+  res.statusCode = status
+  res.setHeader('Content-Type', restBinding ? A2A_CONTENT_TYPE : JSON_CONTENT_TYPE)
+  res.setHeader('Cache-Control', 'no-store')
+  const details = [
+    {
+      '@type': 'type.googleapis.com/google.rpc.ErrorInfo',
+      reason: code,
+      domain: 'a2a-protocol.org',
+      metadata: { path: String(req.originalUrl ?? req.url ?? '') },
+    },
+  ]
+  if (restBinding) {
+    res.end(JSON.stringify({ error: { code: status, status: code, message, details } }))
+  } else {
+    res.end(JSON.stringify({ jsonrpc: '2.0', id: null, error: { code: rpcCode, message, data: details } }))
+  }
+}
+
+/**
+ * One mounted A2A deployment. Mounting is synchronous so route registration
+ * can participate in Cordis effects; only request handling touches async
+ * agent work.
+ */
+export class A2AService {
+  #ctx
+  #config
+  #logger
+  #mounted = undefined
+  #unmount = undefined
+  #disposed = false
+
+  /**
+   * @param {object} ctx owning Cordis context
+   * @param {Readonly<object>} config normalized configuration
+   */
+  constructor(ctx, config) {
+    this.#ctx = ctx
+    this.#config = config
+    this.#logger = createLogger(ctx)
+  }
+
+  /** @returns {object} the structured logger used by every component */
+  get logger() {
+    return this.#logger
+  }
+
+  /**
+   * Register routes on the Harness Web server.
+   *
+   * @param {object} webServer the `webServer` service
+   * @returns {() => Promise<void>} disposer that unregisters routes 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 credentials = resolveCredentials(config)
+    const publicBaseUrl = resolvePublicBase(config, webServer, logger)
+    const authEnabled = isAuthEnabled(config, credentials)
+    let extendedCard = config.server.extendedCard
+    if (extendedCard && !authEnabled) {
+      logger.warn(
+        '[a2a] server.extendedCard requires authentication; the extended Agent Card stays disabled because auth.mode is "none"',
+      )
+      extendedCard = false
+    }
+
+    const effective = {
+      ...config,
+      server: { ...config.server, extendedCard, pushNotifications: config.server.pushNotifications },
+    }
+
+    const cardOptions = { publicBaseUrl, credentials }
+    const baseCard = buildAgentCard(effective, cardOptions)
+    const extendedAgentCard = buildExtendedCard(effective, cardOptions)
+    const signer = createCardSigner(config)
+
+    const runtime = new AgentRuntime({ ctx: this.#ctx, config, logger })
+    const executor = new HarnessAgentExecutor({ runtime, config, logger })
+    const taskStore = new A2ATaskStore({ ...config.tasks, logger })
+
+    const pushStore = config.server.pushNotifications
+      ? new GuardedPushNotificationStore(new InMemoryPushNotificationStore(), {
+          allowPrivateTargets: config.push.allowPrivateTargets,
+          maxConfigsPerTask: 10,
+          logger,
+        })
+      : undefined
+    const pushSender =
+      pushStore === undefined
+        ? undefined
+        : new DefaultPushNotificationSender(pushStore, { timeout: config.push.timeoutMs })
+
+    const requestHandler = new DefaultRequestHandler(
+      baseCard,
+      taskStore,
+      executor,
+      undefined,
+      pushStore,
+      pushSender,
+      extendedCard ? async () => extendedAgentCard : undefined,
+      signer ?? undefined,
+      { validateInputModes: true },
+    )
+
+    const authenticator = createAuthenticator({
+      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()
+    })
+    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,
+      })
+    })
+
+    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 }))
+      })
+    }
+
+    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) => {
+      if (res.headersSent) {
+        res.end()
+        return
+      }
+      const status =
+        typeof error?.status === 'number' && error.status >= 400 && error.status <= 599 ? error.status : 500
+      const restBinding = isRestBinding(req, mountPath)
+      if (status >= 500) logger.warn(`[a2a] request failed: ${errorMessage(error)}`)
+      const isParseError = error?.type === 'entity.parse.failed'
+      const isTooLarge = error?.type === 'entity.too.large'
+      writeError(req, res, {
+        status: isTooLarge ? 413 : isParseError ? 400 : status,
+        code: isTooLarge ? 'RESOURCE_EXHAUSTED' : isParseError ? 'INVALID_ARGUMENT' : status >= 500 ? 'INTERNAL' : 'INVALID_ARGUMENT',
+        message: isTooLarge
+          ? `Request body exceeds limits.maxRequestBytes (${config.limits.maxRequestBytes} bytes)`
+          : isParseError
+            ? 'Invalid JSON payload'
+            : errorMessage(error),
+        restBinding,
+        rpcCode: isParseError ? -32700 : isTooLarge ? -32600 : -32603,
+      })
+      void next
+    })
+
+    const callApp = (req, res) => {
+      try {
+        app(req, res)
+      } catch (error) {
+        logger.warn(`[a2a] transport failure: ${errorMessage(error)}`)
+        if (!res.headersSent) {
+          res.statusCode = 500
+          res.setHeader('Content-Type', JSON_CONTENT_TYPE)
+          res.end(JSON.stringify({ error: { code: 500, status: 'INTERNAL', message: 'internal error' } }))
+        } else if (!res.writableEnded) {
+          res.end()
+        }
+      }
+    }
+
+    const routeDisposers = []
+    const registerRoute = (route, label, { optional = false } = {}) => {
+      try {
+        routeDisposers.push(webServer.register({ ...route, handler: callApp }))
+      } catch (error) {
+        if (optional) {
+          logger.warn(`[a2a] cannot register ${label} at ${route.path}: ${errorMessage(error)}`)
+          return
+        }
+        throw new Error(`a2a: cannot register ${label} at ${route.path}: ${errorMessage(error)}`)
+      }
+    }
+
+    registerRoute({ kind: 'exact', path: config.server.cardPath }, 'agent card')
+    registerRoute({ kind: 'prefix', path: mountPath }, 'A2A endpoint')
+
+    const sweepTimer = setInterval(() => {
+      try {
+        taskStore.sweep()
+      } catch (error) {
+        logger.warn(`[a2a] task sweep failed: ${errorMessage(error)}`)
+      }
+      if (config.files.enabled) {
+        runtime
+          .resolveCwd()
+          .then((cwd) =>
+            sweepAttachmentDirectories({
+              cwd,
+              directory: config.files.directory,
+              retentionMs: config.files.retentionMs,
+              logger,
+            }),
+          )
+          .then(({ removed }) => {
+            if (removed > 0) logger.info(`removed ${removed} stale attachment director${removed === 1 ? 'y' : 'ies'}`)
+          })
+          .catch((error) => logger.warn(`[a2a] attachment sweep failed: ${errorMessage(error)}`))
+      }
+    }, config.tasks.sweepIntervalMs)
+    sweepTimer.unref?.()
+    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}`,
+    )
+    logger.info(
+      `auth=${authenticator.describe().mode} streaming=${config.server.streaming} ` +
+        `push=${config.server.pushNotifications} extendedCard=${extendedCard}`,
+    )
+
+    let released = false
+    const unmount = async () => {
+      if (released) return
+      released = true
+      clearInterval(sweepTimer)
+      for (const dispose of routeDisposers.splice(0).reverse()) {
+        try {
+          dispose()
+        } catch (error) {
+          logger.warn(`[a2a] route disposal failed: ${errorMessage(error)}`)
+        }
+      }
+      await executor.dispose()
+      await runtime.shutdown()
+      this.#mounted = undefined
+      this.#unmount = undefined
+      logger.info('[a2a] server stopped')
+    }
+    this.#unmount = unmount
+    return unmount
+  }
+
+  #health({ runtime, executor, taskStore, authenticator, publicBaseUrl, extendedCard }) {
+    const config = this.#config
+    const mounted = this.#mounted
+    return {
+      status: 'ok',
+      protocolVersion: A2A_PROTOCOL_VERSION,
+      name: config.card.name,
+      version: config.card.version,
+      publicUrl: publicBaseUrl,
+      uptimeSeconds: mounted === undefined ? 0 : Math.round((Date.now() - mounted.startedAt) / 1000),
+      interfaces: [
+        { protocolBinding: 'JSONRPC', url: `${publicBaseUrl}${config.server.mountPath}` },
+        { protocolBinding: 'HTTP+JSON', url: `${publicBaseUrl}${config.server.mountPath}/rest` },
+      ],
+      capabilities: {
+        streaming: config.server.streaming,
+        pushNotifications: config.server.pushNotifications,
+        extendedAgentCard: extendedCard,
+      },
+      auth: authenticator.describe(),
+      signing: config.signing.enabled
+        ? { enabled: true, algorithm: config.signing.algorithm, keyId: config.signing.keyId }
+        : { enabled: false },
+      tasks: taskStore.stats(),
+      agents: runtime.stats(),
+      concurrency: executor.concurrency(),
+    }
+  }
+
+  /** Release service-wide resources. Safe to call multiple times. */
+  async dispose() {
+    if (this.#disposed) return
+    this.#disposed = true
+    const unmount = this.#unmount
+    this.#unmount = undefined
+    if (unmount !== undefined) await unmount()
+  }
+}