@ai_mind/dsh-a2a 0.0.0-stage → 1.0.0

package/lib/panel.js

@@ -0,0 +1,357 @@
+/**
+ * In-panel configuration API for the A2A settings page.
+ *
+ * The browser panel is authenticated by the DSH connection (the same signed
+ * credential the GUI uses), never by the A2A token: an operator who can open
+ * Settings may edit the plugin, while a remote A2A client cannot. Writes go
+ * through the Host `configEditor` service, which validates, persists to the
+ * profile patch, and reconciles the Loader row.
+ *
+ * Secrets are write-only: the current inline token is reported as a boolean,
+ * never returned, and `signing.privateKeyPem` is not exposed at all.
+ *
+ * @module @ai_mind/dsh-a2a/panel
+ */
+
+import express from 'express'
+import { normalizeConfig, resolveCredentials } from './config.js'
+import { errorMessage, isLoopbackAddress, isPlainObject } from './util.js'
+
+const PLUGIN_NAME = '@ai_mind/dsh-a2a'
+const PLUGIN_ROW_NAME = '@ai_mind/dsh-a2a'
+const PLUGIN_ROW_ID = 'a2a-server'
+
+/**
+ * Editable fields, grouped for the settings panel. Labels are supplied by the
+ * client locale keyed on `path`.
+ */
+const FIELDS = [
+  { path: 'card.name', type: 'string', group: 'card' },
+  { 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.mountPath', type: 'string', group: 'server' },
+  { path: 'server.streaming', type: 'boolean', group: 'server' },
+  { path: 'server.pushNotifications', type: 'boolean', group: 'server' },
+  { path: 'server.extendedCard', type: 'boolean', group: 'server' },
+  { path: 'auth.mode', type: 'enum', options: ['none', 'bearer', 'apiKey'], group: 'auth' },
+  { path: 'auth.tokenEnv', type: 'string', group: 'auth', nullable: true, placeholder: 'A2A_AUTH_TOKEN' },
+  { path: 'auth.allowRemoteUnauthenticated', type: 'boolean', group: 'auth' },
+  { path: 'agent.cwd', type: 'string', group: 'agent', nullable: true, placeholder: '/srv/a2a-workspace' },
+  { path: 'agent.preset', type: 'string', group: 'agent', nullable: true },
+  { path: 'agent.provider', type: 'string', group: 'agent', nullable: true },
+  { path: 'agent.model', type: 'string', group: 'agent', nullable: true },
+  { path: 'agent.reasoningEffort', type: 'string', group: 'agent', nullable: true },
+  {
+    path: 'agent.sandboxMode',
+    type: 'enum',
+    options: ['inherit', 'read-only', 'workspace-write', 'danger-full-access'],
+    group: 'agent',
+  },
+  { path: 'agent.approvalPolicy', type: 'enum', options: ['inherit', 'ask', 'never'], group: 'agent' },
+  { path: 'agent.maxConcurrentTasks', type: 'integer', group: 'agent', min: 1, max: 64 },
+  { path: 'agent.queueTimeoutMs', type: 'integer', group: 'agent', min: 0, max: 3600000 },
+  { path: 'agent.turnTimeoutMs', type: 'integer', group: 'agent', min: 1000, max: 86400000 },
+  { path: 'limits.maxRequestBytes', type: 'integer', group: 'limits', min: 1024, max: 268435456 },
+  { path: 'limits.maxFileBytes', type: 'integer', group: 'limits', min: 0, max: 268435456 },
+  { path: 'tasks.ttlMs', type: 'integer', group: 'limits', min: 0, max: 2592000000 },
+  { path: 'tasks.maxTasks', type: 'integer', group: 'limits', min: 1, max: 100000 },
+  { path: 'push.allowPrivateTargets', type: 'boolean', group: 'limits' },
+]
+
+const FIELD_BY_PATH = new Map(FIELDS.map((field) => [field.path, field]))
+
+function readAt(source, path) {
+  let cursor = source
+  for (const part of path.split('.')) {
+    if (!isPlainObject(cursor)) return undefined
+    cursor = cursor[part]
+  }
+  return cursor
+}
+
+function setAt(target, path, value) {
+  const parts = path.split('.')
+  let cursor = target
+  for (const part of parts.slice(0, -1)) {
+    if (!isPlainObject(cursor[part])) cursor[part] = {}
+    cursor = cursor[part]
+  }
+  cursor[parts[parts.length - 1]] = value
+}
+
+function deleteAt(target, path) {
+  const parts = path.split('.')
+  let cursor = target
+  for (const part of parts.slice(0, -1)) {
+    if (!isPlainObject(cursor) || !isPlainObject(cursor[part])) return
+    cursor = cursor[part]
+  }
+  delete cursor[parts[parts.length - 1]]
+}
+
+/** Merge values over `inherited` while preserving unrelated override keys. */
+function mergeConfig(inherited, override) {
+  const base = structuredClone(inherited ?? {})
+  if (!isPlainObject(override)) return base
+  const merge = (target, patch) => {
+    for (const [key, value] of Object.entries(patch)) {
+      if (isPlainObject(value) && isPlainObject(target[key])) merge(target[key], value)
+      else target[key] = structuredClone(value)
+    }
+  }
+  merge(base, override)
+  return base
+}
+
+/**
+ * Coerce one submitted value to the declared field type.
+ *
+ * @param {{ path: string, type: string, options?: string[], nullable?: boolean, min?: number, max?: number }} field
+ * @param {unknown} raw
+ * @returns {unknown} the coerced value, or `null` to unset the field
+ */
+function coerceField(field, raw) {
+  const label = field.path
+  if (raw === null || raw === undefined) {
+    if (field.nullable) return null
+    throw new Error(`${label} must not be empty`)
+  }
+  switch (field.type) {
+    case 'string':
+    case 'textarea': {
+      if (typeof raw !== 'string') throw new Error(`${label} must be a string`)
+      const value = raw.trim()
+      if (value === '') {
+        if (field.nullable) return null
+        throw new Error(`${label} must not be empty`)
+      }
+      return raw
+    }
+    case 'integer': {
+      const value = typeof raw === 'number' ? raw : Number(raw)
+      if (!Number.isInteger(value)) throw new Error(`${label} must be an integer`)
+      if (field.min !== undefined && value < field.min) throw new Error(`${label} must be >= ${field.min}`)
+      if (field.max !== undefined && value > field.max) throw new Error(`${label} must be <= ${field.max}`)
+      return value
+    }
+    case 'boolean': {
+      if (typeof raw !== 'boolean') throw new Error(`${label} must be a boolean`)
+      return raw
+    }
+    case 'enum': {
+      if (typeof raw !== 'string' || !field.options.includes(raw)) {
+        throw new Error(`${label} must be one of ${field.options.join(', ')}`)
+      }
+      return raw
+    }
+    default:
+      throw new Error(`${label} has an unsupported field type`)
+  }
+}
+
+/** Build the GET payload: declared fields, values, secret presence. */
+function describe(config, entry, warnings) {
+  if (!isPlainObject(config)) return { fields: [], secrets: { inline: false, tokenEnv: null }, warnings }
+  const fields = FIELDS.map((field) => {
+    const value = readAt(config, field.path)
+    return {
+      path: field.path,
+      type: field.type,
+      group: field.group,
+      ...(field.options === undefined ? {} : { options: field.options }),
+      ...(field.nullable === undefined ? {} : { nullable: field.nullable }),
+      ...(field.min === undefined ? {} : { min: field.min }),
+      ...(field.max === undefined ? {} : { max: field.max }),
+      ...(field.placeholder === undefined ? {} : { placeholder: field.placeholder }),
+      value: value === undefined ? null : value,
+    }
+  })
+  return {
+    entryId: entry?.options?.id ?? PLUGIN_ROW_ID,
+    fields,
+    secrets: {
+      inline: typeof config.auth?.token === 'string' && config.auth.token !== '',
+      tokenEnv: typeof config.auth?.tokenEnv === 'string' ? config.auth.tokenEnv : null,
+      clientCount: Array.isArray(config.auth?.clients) ? config.auth.clients.length : 0,
+    },
+    warnings,
+  }
+}
+
+/**
+ * Create the `/panel/config` router.
+ *
+ * @param {object} options
+ * @param {object} options.ctx owning Cordis context
+ * @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
+ * @returns {import('express').Router}
+ */
+export function createPanelRouter({ ctx, config, mountPath, logger }) {
+  const router = express.Router()
+  const json = express.json({ limit: 256 * 1024, strict: false })
+
+  /** @returns {boolean} true when the request was rejected and already answered */
+  function authorize(req, res) {
+    const connection = ctx.get?.('connection')
+    if (connection !== undefined && typeof connection.requestRejection === 'function') {
+      try {
+        const rejection = connection.requestRejection({ headers: req.headers })
+        if (rejection !== undefined) {
+          res.status(rejection).json({
+            error: rejection === 401 ? 'UNAUTHENTICATED' : 'FORBIDDEN',
+            message: 'This endpoint requires the authenticated Harness Web session.',
+          })
+          return true
+        }
+        return false
+      } catch (error) {
+        logger.warn(`[a2a] panel authorization failed: ${errorMessage(error)}`)
+        res.status(403).json({ error: 'FORBIDDEN', message: 'Cannot verify the Harness Web session.' })
+        return true
+      }
+    }
+    if (!isLoopbackAddress(req.socket?.remoteAddress ?? '')) {
+      res.status(403).json({ error: 'FORBIDDEN', message: 'Configuration editing is limited to the local Harness host.' })
+      return true
+    }
+    return false
+  }
+
+  function editor() {
+    return ctx.get?.('configEditor')
+  }
+
+  function locateEntry(configEditor) {
+    const entries = configEditor.entries()
+    return (
+      entries.find((entry) => entry.options?.name === PLUGIN_ROW_NAME) ??
+      entries.find((entry) => entry.options?.name === PLUGIN_NAME) ??
+      entries.find((entry) => entry.options?.id === PLUGIN_ROW_ID)
+    )
+  }
+
+  router.get('/config', (req, res) => {
+    if (authorize(req, res)) return
+    const configEditor = editor()
+    if (configEditor === undefined) {
+      res.status(501).json({ error: 'UNAVAILABLE', message: 'Configuration editing requires the Harness config editor.' })
+      return
+    }
+    let entry
+    try {
+      entry = locateEntry(configEditor)
+    } catch (error) {
+      res.status(500).json({ error: 'INTERNAL', message: errorMessage(error) })
+      return
+    }
+    if (entry === undefined) {
+      res.status(404).json({ error: 'NOT_FOUND', message: `No active ${PLUGIN_NAME} row is managed by this profile.` })
+      return
+    }
+    let live = config
+    try {
+      live = normalizeConfig(entry.options?.config ?? {})
+    } catch (error) {
+      logger.warn(`[a2a] live config is invalid, showing the active snapshot: ${errorMessage(error)}`)
+    }
+    const warnings = []
+    if (live.server.extendedCard && !resolveCredentials(live).length) {
+      warnings.push('extendedCard is disabled at mount unless authentication is configured.')
+    }
+    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 })
+  })
+
+  router.put('/config', json, async (req, res) => {
+    if (authorize(req, res)) return
+    const configEditor = editor()
+    if (configEditor === undefined) {
+      res.status(501).json({ error: 'UNAVAILABLE', message: 'Configuration editing requires the Harness config editor.' })
+      return
+    }
+    let entry
+    let layers
+    try {
+      entry = locateEntry(configEditor)
+      layers = configEditor.configuration().find((item) => item.entry === entry)
+    } catch (error) {
+      res.status(500).json({ error: 'INTERNAL', message: errorMessage(error) })
+      return
+    }
+    if (entry === undefined || layers === undefined) {
+      res.status(404).json({ error: 'NOT_FOUND', message: `No active ${PLUGIN_NAME} row is managed by this profile.` })
+      return
+    }
+
+    const body = req.body
+    if (!isPlainObject(body) || (!isPlainObject(body.values) && body.token === undefined && body.clearToken !== true)) {
+      res.status(400).json({ error: 'INVALID_ARGUMENT', message: 'Expected { values, token?, clearToken? }.' })
+      return
+    }
+
+    const next = mergeConfig(layers.inherited, layers.override)
+    try {
+      for (const [path, raw] of Object.entries(body.values ?? {})) {
+        const field = FIELD_BY_PATH.get(path)
+        if (field === undefined) throw new Error(`unknown configuration field "${path}"`)
+        const value = coerceField(field, raw)
+        if (value === null) {
+          deleteAt(next, path)
+          const inheritedValue = readAt(layers.inherited, path)
+          if (inheritedValue !== undefined) setAt(next, path, structuredClone(inheritedValue))
+        } else {
+          setAt(next, path, value)
+        }
+      }
+
+      if (body.clearToken === true) {
+        deleteAt(next, 'auth.token')
+      } else if (body.token !== undefined) {
+        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)
+      }
+
+      const normalized = normalizeConfig(next)
+      const credentials = resolveCredentials(normalized)
+      if (normalized.auth.mode !== 'none' && credentials.length === 0) {
+        throw new Error(
+          normalized.auth.tokenEnv
+            ? `auth.tokenEnv "${normalized.auth.tokenEnv}" is empty; set the environment variable or provide a token`
+            : 'auth.mode requires auth.token, auth.tokens, auth.clients or auth.tokenEnv',
+        )
+      }
+    } catch (error) {
+      res.status(400).json({ error: 'INVALID_ARGUMENT', message: errorMessage(error) })
+      return
+    }
+
+    try {
+      await configEditor.edit(entry, () => next)
+    } catch (error) {
+      logger.warn(`[a2a] config edit failed: ${errorMessage(error)}`)
+      res.status(409).json({ error: 'CONFLICT', message: errorMessage(error) })
+      return
+    }
+
+    // The row may have been replaced while reconciling; read the live config
+    // back rather than echoing our submitted draft.
+    let live = next
+    let liveEntry = entry
+    try {
+      const fresh = locateEntry(configEditor)
+      if (fresh !== undefined) liveEntry = fresh
+      live = normalizeConfig(fresh?.options?.config ?? next)
+    } catch {
+      /* 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, []) })
+  })
+
+  return router
+}

package/lib/prompt.js

@@ -0,0 +1,161 @@
+/**
+ * Convert an inbound A2A message into one DeepSeek Harness prompt.
+ *
+ * Text parts become prompt text, structured `data` parts become fenced JSON,
+ * URL parts are referenced verbatim, and `raw` file parts are written into the
+ * session workspace so the agent's sandboxed tools can read them.
+ *
+ * @module @ai_mind/dsh-a2a/prompt
+ */
+
+import { mkdir, writeFile } from 'node:fs/promises'
+import { join, resolve, sep } from 'node:path'
+import { newId, safeFileName, truncate } from './util.js'
+
+/** Common media types mapped to a file extension for materialized files. */
+const MEDIA_EXTENSIONS = {
+  'text/plain': '.txt',
+  'text/markdown': '.md',
+  'text/csv': '.csv',
+  'application/json': '.json',
+  'application/pdf': '.pdf',
+  'application/zip': '.zip',
+  'image/png': '.png',
+  'image/jpeg': '.jpg',
+  'image/webp': '.webp',
+  'image/gif': '.gif',
+  'audio/mpeg': '.mp3',
+  'audio/wav': '.wav',
+  'video/mp4': '.mp4',
+}
+
+function extensionFor(mediaType) {
+  if (typeof mediaType !== 'string') return ''
+  const base = mediaType.split(';', 1)[0].trim().toLowerCase()
+  return MEDIA_EXTENSIONS[base] ?? ''
+}
+
+function decodeRawValue(value) {
+  if (typeof value === 'string') return Buffer.from(value, 'base64')
+  if (Buffer.isBuffer(value)) return value
+  if (value instanceof Uint8Array) return Buffer.from(value)
+  throw new Error('file part has an unsupported raw value')
+}
+
+/**
+ * Ensure `child` resolves inside `parent`.
+ *
+ * @param {string} parent absolute directory
+ * @param {string} child candidate path
+ * @returns {string}
+ */
+function assertInside(parent, child) {
+  const root = resolve(parent)
+  const target = resolve(child)
+  if (target !== root && !target.startsWith(`${root}${sep}`)) {
+    throw new Error('resolved attachment path escapes the workspace directory')
+  }
+  return target
+}
+
+/**
+ * Build the prompt for one A2A message.
+ *
+ * @param {object} options
+ * @param {object} options.message A2A `Message` in SDK object form
+ * @param {Readonly<object>} options.config normalized plugin configuration
+ * @param {string} options.cwd absolute workspace directory for this session
+ * @param {{ warn: (...args: unknown[]) => void }} options.logger
+ * @returns {Promise<{ text: string, files: { name: string, path: string, mediaType: string, bytes: number }[] }>}
+ */
+export async function buildAgentPrompt({ message, config, cwd, logger }) {
+  const blocks = []
+  const files = []
+  const parts = Array.isArray(message?.parts) ? message.parts : []
+  let rawIndex = 0
+
+  for (const part of parts) {
+    const content = part?.content
+    if (content === undefined || content === null) continue
+    switch (content.$case) {
+      case 'text': {
+        const value = typeof content.value === 'string' ? content.value : ''
+        if (value.trim() !== '') blocks.push(value)
+        break
+      }
+      case 'data': {
+        let rendered
+        try {
+          rendered = JSON.stringify(content.value, null, 2)
+        } catch {
+          rendered = String(content.value)
+        }
+        blocks.push(['```json', rendered, '```'].join('\n'))
+        break
+      }
+      case 'url': {
+        const label = part.filename ? ` "${part.filename}"` : ''
+        const type = part.mediaType ? ` (${part.mediaType})` : ''
+        blocks.push(`[Attached file${label}${type}]: ${content.value}`)
+        break
+      }
+      case 'raw': {
+        rawIndex += 1
+        const bytes = decodeRawValue(content.value)
+        if (bytes.byteLength > config.limits.maxFileBytes) {
+          throw new Error(
+            `file attachment is ${bytes.byteLength} bytes, exceeding limits.maxFileBytes (${config.limits.maxFileBytes})`,
+          )
+        }
+        if (!config.files.enabled) {
+          blocks.push(
+            `[Attached file${part.filename ? ` "${part.filename}"` : ''} was received but files.enabled is false; contents were not written to disk]`,
+          )
+          break
+        }
+        const extension = extensionFor(part.mediaType)
+        const baseName = part.filename ? safeFileName(part.filename) : `attachment-${rawIndex}${extension}`
+        const directoryName = safeFileName(message?.taskId || newId(), 'task')
+        const directory = assertInside(cwd, join(cwd, config.files.directory, directoryName))
+        const uniquePrefix = `${String(rawIndex).padStart(2, '0')}-`
+        const target = assertInside(cwd, join(directory, `${uniquePrefix}${baseName}`))
+        await mkdir(directory, { recursive: true })
+        await writeFile(target, bytes, { mode: 0o600 })
+        files.push({
+          name: baseName,
+          path: target,
+          mediaType: part.mediaType ?? 'application/octet-stream',
+          bytes: bytes.byteLength,
+        })
+        logger.info(`[a2a] materialized attachment ${target} (${bytes.byteLength} bytes)`)
+        blocks.push(
+          `[Attached file "${baseName}" (${part.mediaType ?? 'application/octet-stream'}) is available at: ${target}]`,
+        )
+        break
+      }
+      default:
+        break
+    }
+  }
+
+  if (blocks.length === 0) {
+    throw new Error('message contains no usable text, data, URL or raw file parts')
+  }
+
+  const text = truncate(blocks.join('\n\n'), config.limits.maxPromptChars)
+  return { text, files }
+}
+
+/**
+ * @param {object} message A2A `Message` in SDK object form
+ * @returns {string} concatenated text parts only, for status messages/logging
+ */
+export function messageText(message) {
+  if (!Array.isArray(message?.parts)) return ''
+  return message.parts
+    .map((part) => (part?.content?.$case === 'text' ? part.content.value : ''))
+    .filter(Boolean)
+    .join(' ')
+    .trim()
+}
+