@tangle-network/agent-gateway 0.5.0 → 0.7.0

package/src/a2a/jsonrpc.ts

@@ -0,0 +1,65 @@
+/**
+ * JSON-RPC 2.0 envelope parsing + response builders. Keeps the wire
+ * format isolated from the method dispatcher so a fuzz harness can throw
+ * malformed bodies at `parseEnvelope` directly.
+ */
+
+import {
+  A2A_ERROR_CODES,
+  type JSONRPCErrorResponse,
+  type JSONRPCRequest,
+  type JSONRPCSuccessResponse,
+} from './types'
+
+export interface EnvelopeError {
+  /** id is whatever the caller sent (or null when we can't recover it). */
+  id: string | number | null
+  code: number
+  message: string
+}
+
+/**
+ * Parse an inbound body. Returns the request envelope on success OR an
+ * EnvelopeError that the caller renders as a JSONRPCErrorResponse. We never
+ * throw — JSON-RPC says any malformed body becomes a -32700/-32600 response.
+ */
+export function parseEnvelope(raw: unknown): JSONRPCRequest | EnvelopeError {
+  if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+    return {
+      id: null,
+      code: A2A_ERROR_CODES.INVALID_REQUEST,
+      message: 'request must be a JSON object',
+    }
+  }
+  const req = raw as Record<string, unknown>
+  const id = req.id === undefined ? null : (req.id as string | number | null)
+  if (req.jsonrpc !== '2.0') {
+    return { id, code: A2A_ERROR_CODES.INVALID_REQUEST, message: 'jsonrpc field must be "2.0"' }
+  }
+  if (typeof req.method !== 'string' || req.method.length === 0) {
+    return { id, code: A2A_ERROR_CODES.INVALID_REQUEST, message: 'method field required' }
+  }
+  return {
+    jsonrpc: '2.0',
+    id,
+    method: req.method,
+    params: req.params,
+  }
+}
+
+export function ok<T>(id: string | number | null, result: T): JSONRPCSuccessResponse<T> {
+  return { jsonrpc: '2.0', id, result }
+}
+
+export function fail(
+  id: string | number | null,
+  code: number,
+  message: string,
+  data?: unknown,
+): JSONRPCErrorResponse {
+  return {
+    jsonrpc: '2.0',
+    id,
+    error: { code, message, ...(data !== undefined ? { data } : {}) },
+  }
+}

package/src/a2a/push-notifications.ts

@@ -0,0 +1,299 @@
+/**
+ * @stable
+ *
+ * A2A push notifications — a webhook delivery channel that fires when a task
+ * reaches a terminal state (`completed`, `canceled`, `failed`, `rejected`).
+ * The protocol specifies four JSON-RPC methods (`tasks/pushNotificationConfig/`
+ * {set, get, list, delete}) for registering / inspecting / removing configs,
+ * plus the delivery contract: an HTTP POST to the registered URL with the
+ * task envelope as the body and an HMAC-SHA256 signature for verification.
+ *
+ * This is the minimum shape long-horizon agents need. A consumer that finishes
+ * a task in 30 minutes can't keep an SSE stream open against a Worker (CPU
+ * limits) or an unauthenticated browser tab (network drops) — they need a
+ * fire-and-forget endpoint the gateway calls when the task is done.
+ *
+ * Out of scope for the first pass: retries, queue durability, partial-state
+ * notifications. If the webhook returns non-2xx or the request fails, the
+ * gateway logs and moves on — the consumer's endpoint should idempotently
+ * pull state via `tasks/get` rather than rely on at-least-once delivery.
+ *
+ * @example registering a webhook
+ *   {
+ *     "jsonrpc": "2.0", "id": 1, "method": "tasks/pushNotificationConfig/set",
+ *     "params": {
+ *       "taskId": "task_abc",
+ *       "pushNotificationConfig": {
+ *         "id": "cfg_1",
+ *         "url": "https://my-consumer.example.com/agent/done",
+ *         "token": "my-shared-secret-not-the-hmac-secret"
+ *       }
+ *     }
+ *   }
+ *
+ * @example webhook delivery
+ *   POST https://my-consumer.example.com/agent/done
+ *   X-A2A-Notification-Token: my-shared-secret-not-the-hmac-secret
+ *   X-A2A-Signature: sha256=<hex(HMAC-SHA256(webhookSecret, body))>
+ *   Content-Type: application/json
+ *   { "taskId": "task_abc", "state": "completed", "task": { ...full Task... } }
+ */
+
+import type { SqlAdapter } from './task-store-sql'
+import type { Task } from './types'
+
+/**
+ * Authentication metadata for the webhook itself. The A2A spec leaves this
+ * to consumers — the most common shape is a bearer token the gateway sends as
+ * `Authorization: <scheme> <credential>`. We pass it through verbatim.
+ */
+export interface PushNotificationAuthentication {
+  schemes: string[]
+  credentials?: string
+}
+
+/**
+ * Per-task push notification configuration. A task can have multiple configs
+ * (e.g. one for the consumer's own webhook + one for an audit log endpoint).
+ */
+export interface PushNotificationConfig {
+  /** Stable id within the task's config set. Required for get/delete addressing. */
+  id: string
+  /** HTTPS URL the gateway will POST to. */
+  url: string
+  /**
+   * Opaque token the gateway sends back as `X-A2A-Notification-Token` so the
+   * webhook can verify the call originated from a registration the consumer
+   * authorized. Distinct from the HMAC signature (which proves the body
+   * wasn't tampered with) — this proves the registration is recognised.
+   */
+  token?: string
+  /** Optional webhook-side auth metadata. */
+  authentication?: PushNotificationAuthentication
+}
+
+export interface TaskPushNotificationConfig {
+  taskId: string
+  pushNotificationConfig: PushNotificationConfig
+}
+
+/**
+ * Storage for push configs. The default in-memory store is fine for single
+ * Worker instances + tests; production multi-instance deployments need
+ * `SqlPushNotificationStore` (or any other shared-state adapter) so a config
+ * registered on instance A is visible to a delivery firing from instance B.
+ */
+export interface PushNotificationStore {
+  set(taskId: string, config: PushNotificationConfig): Promise<void>
+  get(taskId: string, configId: string): Promise<PushNotificationConfig | undefined>
+  list(taskId: string): Promise<PushNotificationConfig[]>
+  delete(taskId: string, configId: string): Promise<void>
+}
+
+export class InMemoryPushNotificationStore implements PushNotificationStore {
+  private readonly byTask = new Map<string, Map<string, PushNotificationConfig>>()
+
+  async set(taskId: string, config: PushNotificationConfig): Promise<void> {
+    let configs = this.byTask.get(taskId)
+    if (!configs) {
+      configs = new Map()
+      this.byTask.set(taskId, configs)
+    }
+    configs.set(config.id, { ...config })
+  }
+
+  async get(taskId: string, configId: string): Promise<PushNotificationConfig | undefined> {
+    const cfg = this.byTask.get(taskId)?.get(configId)
+    return cfg ? { ...cfg } : undefined
+  }
+
+  async list(taskId: string): Promise<PushNotificationConfig[]> {
+    const configs = this.byTask.get(taskId)
+    if (!configs) return []
+    return [...configs.values()].map((c) => ({ ...c }))
+  }
+
+  async delete(taskId: string, configId: string): Promise<void> {
+    const configs = this.byTask.get(taskId)
+    if (!configs) return
+    configs.delete(configId)
+    if (configs.size === 0) this.byTask.delete(taskId)
+  }
+}
+
+const PUSH_TABLE_DDL = (table: string) => `
+  CREATE TABLE IF NOT EXISTS ${table} (
+    task_id TEXT NOT NULL,
+    config_id TEXT NOT NULL,
+    url TEXT NOT NULL,
+    token TEXT,
+    authentication TEXT,
+    PRIMARY KEY (task_id, config_id)
+  )
+`
+
+/** SQL-backed push config store. Schema: one row per (taskId, configId). */
+export class SqlPushNotificationStore implements PushNotificationStore {
+  constructor(
+    private readonly db: SqlAdapter,
+    private readonly table: string = 'a2a_push_configs',
+  ) {}
+
+  async migrate(): Promise<void> {
+    await this.db.exec(PUSH_TABLE_DDL(this.table))
+  }
+
+  async set(taskId: string, config: PushNotificationConfig): Promise<void> {
+    const auth = config.authentication ? JSON.stringify(config.authentication) : null
+    const updated = await this.db.exec(
+      `UPDATE ${this.table} SET url = ?, token = ?, authentication = ? WHERE task_id = ? AND config_id = ?`,
+      [config.url, config.token ?? null, auth, taskId, config.id],
+    )
+    if (updated.rowsAffected === 0) {
+      await this.db.exec(
+        `INSERT INTO ${this.table} (task_id, config_id, url, token, authentication) VALUES (?, ?, ?, ?, ?)`,
+        [taskId, config.id, config.url, config.token ?? null, auth],
+      )
+    }
+  }
+
+  async get(taskId: string, configId: string): Promise<PushNotificationConfig | undefined> {
+    const rows = await this.db.query<{
+      config_id: string
+      url: string
+      token: string | null
+      authentication: string | null
+    }>(
+      `SELECT config_id, url, token, authentication FROM ${this.table} WHERE task_id = ? AND config_id = ?`,
+      [taskId, configId],
+    )
+    const row = rows[0]
+    if (!row) return undefined
+    return {
+      id: row.config_id,
+      url: row.url,
+      token: row.token ?? undefined,
+      authentication: row.authentication
+        ? (JSON.parse(row.authentication) as PushNotificationAuthentication)
+        : undefined,
+    }
+  }
+
+  async list(taskId: string): Promise<PushNotificationConfig[]> {
+    const rows = await this.db.query<{
+      config_id: string
+      url: string
+      token: string | null
+      authentication: string | null
+    }>(
+      `SELECT config_id, url, token, authentication FROM ${this.table} WHERE task_id = ?`,
+      [taskId],
+    )
+    return rows.map((row) => ({
+      id: row.config_id,
+      url: row.url,
+      token: row.token ?? undefined,
+      authentication: row.authentication
+        ? (JSON.parse(row.authentication) as PushNotificationAuthentication)
+        : undefined,
+    }))
+  }
+
+  async delete(taskId: string, configId: string): Promise<void> {
+    await this.db.exec(
+      `DELETE FROM ${this.table} WHERE task_id = ? AND config_id = ?`,
+      [taskId, configId],
+    )
+  }
+}
+
+/**
+ * Send the webhook for each registered config on a task. Signs the body with
+ * HMAC-SHA256 against `webhookSecret` so the consumer can verify authenticity.
+ * Fire-and-forget per the design note above — the function awaits delivery
+ * (so observability hooks see the result) but does not retry on failure.
+ *
+ * The caller decides *when* to deliver — typically on terminal-state
+ * transitions emitted from `message/send` and `message/stream`.
+ */
+export async function deliverPushNotifications(args: {
+  task: Task
+  store: PushNotificationStore
+  webhookSecret: string | undefined
+  /** Inject for tests. Defaults to global `fetch`. */
+  fetcher?: typeof fetch
+  /** Optional callback so the gateway's observer can log delivery outcomes. */
+  onDelivery?: (result: PushDeliveryResult) => void
+}): Promise<PushDeliveryResult[]> {
+  const fetcher = args.fetcher ?? fetch
+  const configs = await args.store.list(args.task.id)
+  const body = JSON.stringify({
+    taskId: args.task.id,
+    state: args.task.status.state,
+    task: args.task,
+  })
+  const signature = args.webhookSecret
+    ? `sha256=${await hmacSha256Hex(args.webhookSecret, body)}`
+    : undefined
+
+  const results: PushDeliveryResult[] = []
+  for (const config of configs) {
+    const headers: Record<string, string> = { 'Content-Type': 'application/json' }
+    if (config.token) headers['X-A2A-Notification-Token'] = config.token
+    if (signature) headers['X-A2A-Signature'] = signature
+    if (config.authentication?.credentials) {
+      const scheme = config.authentication.schemes[0] ?? 'Bearer'
+      headers.Authorization = `${scheme} ${config.authentication.credentials}`
+    }
+
+    let result: PushDeliveryResult
+    try {
+      const res = await fetcher(config.url, { method: 'POST', headers, body })
+      result = {
+        taskId: args.task.id,
+        configId: config.id,
+        url: config.url,
+        ok: res.ok,
+        status: res.status,
+      }
+    } catch (err) {
+      result = {
+        taskId: args.task.id,
+        configId: config.id,
+        url: config.url,
+        ok: false,
+        error: err instanceof Error ? err.message : String(err),
+      }
+    }
+    args.onDelivery?.(result)
+    results.push(result)
+  }
+  return results
+}
+
+export interface PushDeliveryResult {
+  taskId: string
+  configId: string
+  url: string
+  ok: boolean
+  status?: number
+  error?: string
+}
+
+/**
+ * HMAC-SHA256 via WebCrypto. Works on Workers, Node 19+, Bun, Deno. The
+ * gateway requires WebCrypto for x402 verification already, so this adds no
+ * new platform constraint.
+ */
+async function hmacSha256Hex(secret: string, body: string): Promise<string> {
+  const enc = new TextEncoder()
+  const key = await crypto.subtle.importKey(
+    'raw',
+    enc.encode(secret),
+    { name: 'HMAC', hash: 'SHA-256' },
+    false,
+    ['sign'],
+  )
+  const sig = await crypto.subtle.sign('HMAC', key, enc.encode(body))
+  return [...new Uint8Array(sig)].map((b) => b.toString(16).padStart(2, '0')).join('')
+}

package/src/a2a/task-store-sql.ts

@@ -0,0 +1,189 @@
+/**
+ * @stable
+ *
+ * Durable `TaskStore` against any SQL store. Adapter-agnostic: callers wire a
+ * `SqlAdapter` against their driver (D1, postgres, sqlite, libSQL, Turso) and
+ * the same store survives gateway restarts so an in-flight task (and its
+ * artifacts) is recoverable after a Worker recycle.
+ *
+ * Schema is one table: tasks keyed by id with the full JSON payload, plus a
+ * secondary index on `context_id` so `tasks/resubscribe` and conversational
+ * lookups by context are O(log n). TTL is enforced at read time the same way
+ * `InMemoryTaskStore` does — the gateway is single-writer per task id so a
+ * stale row is invisible to callers regardless of when the row is physically
+ * deleted.
+ *
+ * Why not bake in a specific driver? Hono workers run on Cloudflare (D1),
+ * Node (pg / sqlite), Bun, Deno. Burning a hard dependency on one client
+ * limits the gateway's reach. The adapter indirection costs ~5 lines per
+ * driver in the consumer's code and keeps the package free of native deps.
+ *
+ * @example D1
+ *   import { SqlTaskStore, d1ToSqlAdapter } from '@tangle-network/agent-gateway'
+ *   const store = new SqlTaskStore(d1ToSqlAdapter(env.DB))
+ *   await store.migrate()
+ *   const gw = createAgentGateway({ ..., a2a: { taskStore: store } })
+ *
+ * @example libSQL / Turso
+ *   import { createClient } from '@libsql/client'
+ *   const client = createClient({ url: process.env.TURSO_URL!, authToken: process.env.TURSO_TOKEN! })
+ *   const libsql: SqlAdapter = {
+ *     exec: async (sql, params = []) => {
+ *       const r = await client.execute({ sql, args: params as never[] })
+ *       return { rowsAffected: Number(r.rowsAffected ?? 0) }
+ *     },
+ *     query: async (sql, params = []) => {
+ *       const r = await client.execute({ sql, args: params as never[] })
+ *       return r.rows as unknown as Record<string, unknown>[]
+ *     },
+ *   }
+ *   const store = new SqlTaskStore(libsql)
+ *   await store.migrate()
+ */
+
+import type { TaskStore } from './task-store'
+import type { Task } from './types'
+
+/**
+ * Minimal SQL driver shape — identical to agent-runtime's `SqlAdapter` so the
+ * same wrapper code works for both packages. Parameter placeholders MUST be
+ * `?` (positional); driver wrappers that use `$1`, `$2`, … should rewrite at
+ * the adapter boundary (see node-postgres example in the durability docs).
+ */
+export interface SqlAdapter {
+  exec(sql: string, params?: readonly unknown[]): Promise<{ rowsAffected: number }>
+  query<TRow = Record<string, unknown>>(
+    sql: string,
+    params?: readonly unknown[],
+  ): Promise<TRow[]>
+}
+
+/**
+ * Adapt a Cloudflare D1 binding to `SqlAdapter`. The package never imports
+ * `@cloudflare/workers-types`; the binding's structural shape lines up via
+ * TypeScript structural compatibility.
+ */
+export function d1ToSqlAdapter(db: D1DatabaseLike): SqlAdapter {
+  return {
+    async exec(sql, params = []) {
+      const stmt = db.prepare(sql)
+      const bound = params.length > 0 ? stmt.bind(...params) : stmt
+      const result = await bound.run()
+      const meta = (result as { meta?: { rows_written?: number; changes?: number } }).meta
+      return { rowsAffected: meta?.rows_written ?? meta?.changes ?? 0 }
+    },
+    async query<TRow>(sql: string, params: readonly unknown[] = []): Promise<TRow[]> {
+      const stmt = db.prepare(sql)
+      const bound = params.length > 0 ? stmt.bind(...params) : stmt
+      const result = await bound.all<TRow>()
+      return result.results ?? []
+    },
+  }
+}
+
+export interface D1DatabaseLike {
+  prepare(sql: string): D1StmtLike
+}
+export interface D1StmtLike {
+  bind(...params: unknown[]): D1StmtLike
+  run(): Promise<unknown>
+  all<TRow = unknown>(): Promise<{ results?: TRow[] }>
+}
+
+const DEFAULT_TTL_MS = 60 * 60 * 1000
+
+const TASKS_TABLE_DDL = (table: string) => `
+  CREATE TABLE IF NOT EXISTS ${table} (
+    id TEXT PRIMARY KEY,
+    context_id TEXT NOT NULL,
+    state TEXT NOT NULL,
+    payload TEXT NOT NULL,
+    updated_at INTEGER NOT NULL
+  )
+`
+const CTX_INDEX_DDL = (table: string) => `
+  CREATE INDEX IF NOT EXISTS idx_${table}_context ON ${table} (context_id, updated_at)
+`
+
+/**
+ * SQL-backed TaskStore. Stores the full Task JSON; reads return a deep clone
+ * so callers never observe shared references. TTL is enforced at read time:
+ * expired rows are filtered out and (best-effort) deleted, matching the
+ * in-memory store's semantics so behavior is portable across both adapters.
+ */
+export class SqlTaskStore implements TaskStore {
+  constructor(
+    private readonly db: SqlAdapter,
+    private readonly opts: { ttlMs?: number; table?: string } = {},
+  ) {}
+
+  private get ttlMs(): number {
+    return this.opts.ttlMs ?? DEFAULT_TTL_MS
+  }
+  private get table(): string {
+    return this.opts.table ?? 'a2a_tasks'
+  }
+
+  /** Idempotent. Call once at deploy. */
+  async migrate(): Promise<void> {
+    await this.db.exec(TASKS_TABLE_DDL(this.table))
+    await this.db.exec(CTX_INDEX_DDL(this.table))
+  }
+
+  async get(id: string): Promise<Task | undefined> {
+    const rows = await this.db.query<{ payload: string; updated_at: number }>(
+      `SELECT payload, updated_at FROM ${this.table} WHERE id = ?`,
+      [id],
+    )
+    const row = rows[0]
+    if (!row) return undefined
+    if (Date.now() - row.updated_at > this.ttlMs) {
+      // Lazy GC. If the delete loses a race with another reader, that reader
+      // observes either the stale-then-deleted task (returning undefined here)
+      // or, after this delete commits, observes undefined directly — either
+      // way callers see consistent "expired" semantics.
+      void this.db.exec(`DELETE FROM ${this.table} WHERE id = ?`, [id])
+      return undefined
+    }
+    return JSON.parse(row.payload) as Task
+  }
+
+  async put(task: Task): Promise<void> {
+    const payload = JSON.stringify(task)
+    const updatedAt = Date.now()
+    // Adapter-agnostic upsert: try update, fall back to insert if no row
+    // existed. Avoids needing ON CONFLICT (postgres) vs INSERT OR REPLACE
+    // (sqlite/libSQL) divergence at the SQL layer.
+    const updated = await this.db.exec(
+      `UPDATE ${this.table} SET context_id = ?, state = ?, payload = ?, updated_at = ? WHERE id = ?`,
+      [task.contextId, task.status.state, payload, updatedAt, task.id],
+    )
+    if (updated.rowsAffected === 0) {
+      await this.db.exec(
+        `INSERT INTO ${this.table} (id, context_id, state, payload, updated_at) VALUES (?, ?, ?, ?, ?)`,
+        [task.id, task.contextId, task.status.state, payload, updatedAt],
+      )
+    }
+  }
+
+  async delete(id: string): Promise<void> {
+    await this.db.exec(`DELETE FROM ${this.table} WHERE id = ?`, [id])
+  }
+
+  /**
+   * Lookup tasks by contextId — used by `tasks/resubscribe` and the multi-turn
+   * dispatcher. Returns most-recent-first. Not part of the base TaskStore
+   * interface since the in-memory store doesn't expose it; consumers that
+   * specifically wire SqlTaskStore can use it for richer queries.
+   */
+  async listByContext(contextId: string): Promise<Task[]> {
+    const rows = await this.db.query<{ payload: string; updated_at: number }>(
+      `SELECT payload, updated_at FROM ${this.table} WHERE context_id = ? ORDER BY updated_at DESC`,
+      [contextId],
+    )
+    const now = Date.now()
+    return rows
+      .filter((r) => now - r.updated_at <= this.ttlMs)
+      .map((r) => JSON.parse(r.payload) as Task)
+  }
+}

package/src/a2a/task-store.ts

@@ -0,0 +1,53 @@
+/**
+ * Task persistence behind the JSON-RPC dispatcher. Default adapter is in
+ * memory with a 1-hour TTL — adequate for tests, scratch, and Workers with
+ * a short-lived process. Production deployments wire their own
+ * `TaskStore` (D1, postgres, Durable Object) via `GatewayConfig.a2a`.
+ */
+
+import type { Task } from './types'
+
+export interface TaskStore {
+  get(id: string): Promise<Task | undefined>
+  put(task: Task): Promise<void>
+  delete(id: string): Promise<void>
+}
+
+const DEFAULT_TTL_MS = 60 * 60 * 1000
+
+export class InMemoryTaskStore implements TaskStore {
+  private readonly entries = new Map<string, { task: Task; expiresAt: number }>()
+
+  constructor(private readonly ttlMs: number = DEFAULT_TTL_MS) {}
+
+  async get(id: string): Promise<Task | undefined> {
+    this.gc()
+    const entry = this.entries.get(id)
+    if (!entry) return undefined
+    return clone(entry.task)
+  }
+
+  async put(task: Task): Promise<void> {
+    this.gc()
+    this.entries.set(task.id, { task: clone(task), expiresAt: Date.now() + this.ttlMs })
+  }
+
+  async delete(id: string): Promise<void> {
+    this.entries.delete(id)
+  }
+
+  /**
+   * Sweep expired tasks. Called inline on every read/write — cheap for the
+   * Map sizes this is designed for (10s–1000s of concurrent tasks).
+   */
+  private gc(): void {
+    const now = Date.now()
+    for (const [id, entry] of this.entries) {
+      if (entry.expiresAt <= now) this.entries.delete(id)
+    }
+  }
+}
+
+function clone<T>(value: T): T {
+  return JSON.parse(JSON.stringify(value)) as T
+}

package/src/a2a/translate.ts

@@ -0,0 +1,77 @@
+/**
+ * A2A Message ↔ inner-agent (text-only) translation. Both directions are
+ * intentionally narrow: callers send text parts, the inner sandbox produces
+ * text. Data + file parts are rejected with `CONTENT_TYPE_NOT_SUPPORTED`
+ * rather than silently dropped — the protocol's whole point is letting the
+ * caller know exactly what an agent does and doesn't accept.
+ */
+
+import { A2A_ERROR_CODES, type Artifact, type Message } from './types'
+
+export interface ExtractedText {
+  text: string
+}
+
+export interface ExtractError {
+  error: { code: number; message: string }
+}
+
+/**
+ * Pull `text` out of a Message's parts. Concatenates multi-text-part messages
+ * with two newlines, mirroring the OpenAI-compat path's join of `user`
+ * messages. Returns an A2A error code on any non-text part — text-only is the
+ * declared capability of every agent this gateway fronts.
+ */
+export function extractTextFromMessage(message: Message): ExtractedText | ExtractError {
+  if (!message || message.kind !== 'message') {
+    return {
+      error: {
+        code: A2A_ERROR_CODES.INVALID_PARAMS,
+        message: 'params.message must be an A2A Message ({ kind: "message", role, parts, messageId })',
+      },
+    }
+  }
+  if (!Array.isArray(message.parts) || message.parts.length === 0) {
+    return {
+      error: {
+        code: A2A_ERROR_CODES.INVALID_PARAMS,
+        message: 'message.parts must be a non-empty array',
+      },
+    }
+  }
+  const texts: string[] = []
+  for (const part of message.parts) {
+    if (part.kind === 'text') {
+      if (typeof part.text !== 'string') {
+        return {
+          error: {
+            code: A2A_ERROR_CODES.INVALID_PARAMS,
+            message: 'text part .text must be a string',
+          },
+        }
+      }
+      texts.push(part.text)
+    } else {
+      return {
+        error: {
+          code: A2A_ERROR_CODES.CONTENT_TYPE_NOT_SUPPORTED,
+          message: `part.kind '${(part as { kind: string }).kind}' not supported; this agent accepts text parts only`,
+        },
+      }
+    }
+  }
+  return { text: texts.join('\n\n') }
+}
+
+/**
+ * Wrap the agent's final response text as an A2A Artifact for the task's
+ * `artifacts` field. `name='response'` is the convention for the primary
+ * model output across A2A reference servers.
+ */
+export function responseTextToArtifact(text: string, artifactId: string): Artifact {
+  return {
+    artifactId,
+    name: 'response',
+    parts: [{ kind: 'text', text }],
+  }
+}