@tangle-network/agent-gateway 0.5.0 → 0.7.0

package/src/index.ts

@@ -57,3 +57,54 @@ export type {
   ChatCompletionRequest,
   ChatCompletionChunk,
 } from './types'
+
+// --- A2A protocol surface (Google Agent-to-Agent) ---
+// Types + task-store adapter. Handlers are wired automatically by
+// createAgentGateway when `GatewayConfig.a2a` (or its default) is honored;
+// consumers only import these to BYO a durable TaskStore (D1, postgres, DO)
+// or to declare richer AgentMeta.skills for the Agent Card.
+export { InMemoryTaskStore, type TaskStore } from './a2a/task-store'
+export {
+  type D1DatabaseLike,
+  type D1StmtLike,
+  d1ToSqlAdapter,
+  type SqlAdapter,
+  SqlTaskStore,
+} from './a2a/task-store-sql'
+export {
+  deliverPushNotifications,
+  InMemoryPushNotificationStore,
+  type PushDeliveryResult,
+  type PushNotificationAuthentication,
+  type PushNotificationConfig,
+  type PushNotificationStore,
+  SqlPushNotificationStore,
+  type TaskPushNotificationConfig,
+} from './a2a/push-notifications'
+export type {
+  AgentCard,
+  AgentCapabilities,
+  AgentCardAuthentication,
+  AgentProvider,
+  AgentSkill,
+  Artifact,
+  DataPart,
+  FilePart,
+  JSONRPCErrorResponse,
+  JSONRPCRequest,
+  JSONRPCResponse,
+  JSONRPCSuccessResponse,
+  Message,
+  MessageSendParams,
+  Part,
+  StreamingEvent,
+  Task,
+  TaskArtifactUpdateEvent,
+  TaskIdParams,
+  TaskPushNotificationConfigGetParams,
+  TaskState,
+  TaskStatus,
+  TaskStatusUpdateEvent,
+  TextPart,
+} from './a2a/types'
+export { A2A_ERROR_CODES } from './a2a/types'

package/src/middleware.ts

@@ -1,16 +1,19 @@
 import { Hono } from 'hono'
-import type {
-  GatewayConfig,
-  ChatCompletionRequest,
-  ChatCompletionChunk,
-  PaymentMethod,
-  ApiKeyInfo,
-} from './types'
-import { verifyX402, verifyMpp, defaultVerifyApiKey } from './verify'
-import { filterConsumerMessagesStrict, redactSystemPromptFromOutput } from './filter'
-import { checkRateLimit, MemoryRateLimitStore, type RateLimitStore } from './rate-limit'
+
+import { createA2AHandlers } from './a2a/handler'
+import { InMemoryTaskStore } from './a2a/task-store'
+import {
+  type AuthorizedRequest,
+  type GatewayState,
+  authenticateAndGuard,
+  dispatchSandboxStream,
+  estimateTokens,
+  settleAndRecord,
+} from './dispatch'
 import { MemoryNonceStore } from './nonce-store'
-import { generateRequestId, type GatewayObserver, type RequestContext } from './observer'
+import { type GatewayObserver, type RequestContext, generateRequestId } from './observer'
+import { MemoryRateLimitStore, type RateLimitStore } from './rate-limit'
+import type { ChatCompletionChunk, ChatCompletionRequest, GatewayConfig } from './types'
 
 /**
  * Create a Hono router that serves the agent gateway.
@@ -19,7 +22,7 @@ import { generateRequestId, type GatewayObserver, type RequestContext } from './
  *   app.route('/v1/agents', createAgentGateway(config))
  *
  * Exposes:
- *   GET  /:slug/chat/completions  — agent discovery metadata
+ *   GET  /:slug/chat/completions  — agent discovery metadata (Tangle-native shape)
  *   POST /:slug/chat/completions  — OpenAI-compatible chat endpoint (paid)
  */
 export function createAgentGateway(config: GatewayConfig) {
@@ -32,12 +35,16 @@ export function createAgentGateway(config: GatewayConfig) {
     )
   }
   const gw = new Hono()
-  const maxLen = config.maxMessageLength ?? 8000
   const rateLimitStore: RateLimitStore = config.rateLimitStore ?? new MemoryRateLimitStore()
-  const globalRateLimit = config.rateLimit ?? { limit: 60, windowSeconds: 60 }
-  const nonceStore = config.nonceStore ?? new MemoryNonceStore()
-  const requiredScope = config.requiredScope ?? 'chat'
-  const obs: GatewayObserver | undefined = config.observer
+  const state: GatewayState = {
+    rateLimitStore,
+    nonceStore: config.nonceStore ?? new MemoryNonceStore(),
+    globalRateLimit: config.rateLimit ?? { limit: 60, windowSeconds: 60 },
+    requiredScope: config.requiredScope ?? 'chat',
+    maxLen: config.maxMessageLength ?? 8000,
+    obs: config.observer,
+  }
+  const obs: GatewayObserver | undefined = state.obs
 
   // --- Discovery endpoint (no auth) ---
 
@@ -84,24 +91,22 @@ export function createAgentGateway(config: GatewayConfig) {
 
   gw.post('/:slug/chat/completions', async (c) => {
     const slug = c.req.param('slug')
-    const startMs = Date.now()
-    const requestId = generateRequestId()
-    const ctx: RequestContext = { requestId, agentSlug: slug, startMs }
-
-    await obs?.onRequestStart?.(ctx)
 
-    // 1. Resolve agent
-    const agent = await config.resolveAgent(slug)
-    if (!agent) {
-      return c.json({ error: { message: 'Agent not found', type: 'not_found' } }, 404)
-    }
-
-    // 2. Body size limit (before parsing — DoS prevention)
-    const contentLength = parseInt(c.req.header('Content-Length') ?? '0', 10)
+    // Body size limit (before parsing — DoS prevention).
+    const contentLength = Number.parseInt(c.req.header('Content-Length') ?? '0', 10)
     if (contentLength > 65536) {
-      await obs?.onBodyTooLarge?.(ctx, contentLength)
+      const requestId = generateRequestId()
+      await obs?.onBodyTooLarge?.(
+        { requestId, agentSlug: slug, startMs: Date.now() },
+        contentLength,
+      )
       return c.json(
-        { error: { message: 'Request body too large (max 64KB)', type: 'invalid_request' } },
+        {
+          error: {
+            message: 'Request body too large (max 64KB)',
+            type: 'invalid_request',
+          },
+        },
         413,
       )
     }
@@ -113,277 +118,117 @@ export function createAgentGateway(config: GatewayConfig) {
       return c.json({ error: { message: 'Invalid JSON', type: 'invalid_request' } }, 400)
     }
     if (!body.messages?.length) {
-      return c.json({ error: { message: 'messages array required', type: 'invalid_request' } }, 400)
-    }
-
-    // 3. Authenticate — x402 SpendAuth, MPP, or API key
-    const spendAuthHeader = c.req.header('X-Payment-Signature')
-    const authHeader = c.req.header('Authorization') ?? ''
-    let consumerId: string | null = null
-    let paymentMethod: PaymentMethod = 'none'
-    let keyInfo: ApiKeyInfo | null = null
-
-    if (spendAuthHeader) {
-      const signer = await verifyX402(spendAuthHeader, config.x402, nonceStore)
-      if (!signer) {
-        await obs?.onAuthFailure?.(ctx, { method: 'x402', code: 'invalid_spend_auth', httpStatus: 402 })
-        return c.json(
-          { error: { message: 'Invalid X-Payment-Signature', type: 'authentication_error', code: 'invalid_spend_auth' } },
-          { status: 402, headers: { 'X-Payment-Required': 'spendauth', 'X-Request-Id': requestId } },
-        )
-      }
-      consumerId = signer
-      paymentMethod = 'x402'
-    } else if (config.mpp && authHeader.toLowerCase().startsWith('payment ')) {
-      const signer = await verifyMpp(authHeader, config.mpp, config.x402)
-      if (!signer) {
-        const realm = config.mpp.realm
-        const method = config.mpp.method ?? 'blueprintevm'
-        await obs?.onAuthFailure?.(ctx, { method: 'mpp', code: 'invalid_mpp_credential', httpStatus: 401 })
-        return c.json(
-          { error: { message: 'Invalid Payment credential', type: 'authentication_error', code: 'invalid_mpp_credential' } },
-          { status: 401, headers: { 'WWW-Authenticate': `Payment realm="${realm}", method="${method}"`, 'X-Request-Id': requestId } },
-        )
-      }
-      consumerId = signer
-      paymentMethod = 'mpp'
-    } else if (authHeader.startsWith('Bearer ')) {
-      const verify = config.verifyApiKey ?? defaultVerifyApiKey
-      const key = await verify(authHeader)
-      if (!key) {
-        await obs?.onAuthFailure?.(ctx, { method: 'apikey', code: 'invalid_api_key', httpStatus: 401 })
-        return c.json(
-          { error: { message: 'Invalid API key', type: 'authentication_error' } },
-          { status: 401, headers: { 'X-Request-Id': requestId } },
-        )
-      }
-
-      // Scope enforcement — API key must include the required scope
-      if (key.scopes && key.scopes.length > 0 && !key.scopes.includes(requiredScope)) {
-        await obs?.onAuthFailure?.(ctx, { method: 'apikey', code: 'insufficient_scope', httpStatus: 403 })
-        return c.json(
-          { error: { message: `API key missing required scope: ${requiredScope}`, type: 'forbidden', code: 'insufficient_scope' } },
-          { status: 403, headers: { 'X-Request-Id': requestId } },
-        )
-      }
-
-      consumerId = key.consumerId
-      paymentMethod = 'apikey'
-      keyInfo = key
-    } else {
-      // No payment — return 402 with instructions
-      await obs?.onAuthFailure?.(ctx, { method: 'none', code: 'payment_required', httpStatus: 402 })
-      const methods: string[] = ['x402']
-      if (config.mpp) methods.push('mpp')
-      methods.push('api_key')
-
-      const headers: Record<string, string> = {
-        'X-Payment-Required': methods.join(', '),
-        'X-Request-Id': requestId,
-      }
-      if (config.mpp) {
-        headers['WWW-Authenticate'] = `Payment realm="${config.mpp.realm}", method="${config.mpp.method ?? 'blueprintevm'}"`
-      }
-
-      return c.json({
-        error: {
-          message: 'Payment required',
-          type: 'payment_required',
-          payment_methods: methods,
-          x402: {
-            operator: config.x402.operatorAddress,
-            chain_id: config.x402.chainId,
-            credits_address: config.x402.creditsAddress,
-            estimated_amount_per_request: '20000',
-          },
-          ...(config.mpp ? {
-            mpp: { realm: config.mpp.realm, method: config.mpp.method ?? 'blueprintevm' },
-          } : {}),
-          api_key: {
-            purchase_url: config.baseUrl ? `${config.baseUrl}/agents/${slug}/api-keys` : undefined,
-          },
-        },
-      }, { status: 402, headers })
-    }
-
-    await obs?.onPaymentVerified?.(ctx, { method: paymentMethod, consumerId: consumerId!, keyId: keyInfo?.keyId })
-
-    // 4. Rate limit — per-key override or global
-    const effectiveRateLimit = keyInfo?.rateLimitPerMinute
-      ? { limit: keyInfo.rateLimitPerMinute, windowSeconds: 60 }
-      : globalRateLimit
-
-    const rl = await checkRateLimit(consumerId!, effectiveRateLimit, rateLimitStore)
-    if (!rl.allowed) {
-      await obs?.onRateLimited?.(ctx, { consumerId: consumerId!, retryAfterSeconds: rl.retryAfterSeconds ?? 60 })
       return c.json(
-        { error: { message: 'Rate limit exceeded', type: 'rate_limit_error', retry_after: rl.retryAfterSeconds } },
-        { status: 429, headers: { 'Retry-After': String(rl.retryAfterSeconds ?? 60), 'X-Request-Id': requestId } },
+        { error: { message: 'messages array required', type: 'invalid_request' } },
+        400,
       )
     }
 
-    // 5. Filter messages — injection detection + sanitization
-    const { messages: filtered, injectionWarnings } = filterConsumerMessagesStrict(body.messages, maxLen)
+    const guard = await authenticateAndGuard(c, slug, body.messages, config, state)
+    if (guard instanceof Response) return guard
+    const authz = guard
 
-    if (injectionWarnings.length > 0) {
-      await obs?.onInjectionDetected?.(ctx, {
-        consumerId: consumerId!,
-        patterns: injectionWarnings,
-        blocked: !!config.blockInjection,
-      })
+    return streamChatCompletions(c, authz, config, obs)
+  })
 
-      if (config.blockInjection) {
-        return c.json(
-          { error: { message: 'Request rejected: potential prompt injection detected', type: 'content_policy_violation' } },
-          { status: 400, headers: { 'X-Request-Id': requestId } },
-        )
-      }
-      // In non-blocking mode, continue but the warning is logged for auditing
-    }
+  // --- A2A protocol surface (Google Agent-to-Agent, JSON-RPC 2.0 + AgentCard) ---
+  // Mounted alongside the OpenAI-compat routes so a single agent speaks both.
+  // Both surfaces share authenticateAndGuard + dispatchSandboxStream +
+  // settleAndRecord, so every security and billing guarantee applies uniformly
+  // regardless of which protocol the caller used.
+  const taskStore = config.a2a?.taskStore ?? new InMemoryTaskStore()
+  const pushStore = config.a2a?.pushStore
+  const a2a = createA2AHandlers({ config, state, taskStore, pushStore })
+  gw.get('/:slug/.well-known/agent.json', a2a.handleAgentCard)
+  gw.post('/:slug', a2a.handleJsonRpc)
 
-    const userMessage = filtered
-      .filter((m) => m.role === 'user')
-      .map((m) => m.content)
-      .join('\n\n')
+  return gw
+}
 
-    if (!userMessage) {
-      return c.json({ error: { message: 'No user message provided', type: 'invalid_request' } }, 400)
-    }
+/**
+ * Drain the sandbox stream into an OpenAI-shaped SSE response, settle the
+ * payment, fire observer hooks. Identical pre-refactor behavior, just lifted
+ * out of the handler so the A2A wrapper can reach the same dispatch path
+ * without duplicating it.
+ */
+function streamChatCompletions(
+  c: import('hono').Context,
+  authz: AuthorizedRequest,
+  config: GatewayConfig,
+  obs: GatewayObserver | undefined,
+): Response {
+  const { agent, consumerId, paymentMethod, requestId, userMessage, rateLimitRemaining } = authz
+  const inputTokens = estimateTokens(userMessage)
+  let outputTokens = 0
+  const ctx: RequestContext = {
+    requestId,
+    agentSlug: agent.slug,
+    startMs: authz.startMs,
+  }
 
-    // 5b. Optional host authorization. Runs after payment/rate-limit
-    // checks and before sandbox allocation.
-    if (config.authorizeConsumer) {
-      const authz = await config.authorizeConsumer(agent, {
-        method: paymentMethod,
-        consumerId: consumerId!,
-        keyId: keyInfo?.keyId,
-        requestId,
-      })
-      if (!authz.allow) {
-        return c.json(
-          {
-            error: {
-              message: authz.reason,
-              type: 'authorization_denied',
-              code: authz.code,
-            },
-          },
-          { status: 403, headers: { 'X-Request-Id': requestId } },
-        )
+  const stream = new ReadableStream({
+    async start(controller) {
+      const encoder = new TextEncoder()
+      const sendChunk = (delta: string) => {
+        outputTokens += estimateTokens(delta)
+        const chunk: ChatCompletionChunk = {
+          id: `chatcmpl-${Date.now()}`,
+          object: 'chat.completion.chunk',
+          created: Math.floor(Date.now() / 1000),
+          model: agent.slug,
+          choices: [{ index: 0, delta: { content: delta }, finish_reason: null }],
+        }
+        controller.enqueue(encoder.encode(`data: ${JSON.stringify(chunk)}\n\n`))
       }
-    }
-
-    // 6. Get sandbox and stream response with output filtering
-    const inputTokens = Math.ceil(userMessage.length / 4)
-    let outputTokens = 0
 
-    const stream = new ReadableStream({
-      async start(controller) {
-        const encoder = new TextEncoder()
-        const sendChunk = (rawDelta: string) => {
-          // Redact system prompt leakage from output
-          const delta = redactSystemPromptFromOutput(rawDelta, agent.systemPrompt)
-          outputTokens += Math.ceil(delta.length / 4)
-          const chunk: ChatCompletionChunk = {
-            id: `chatcmpl-${Date.now()}`,
-            object: 'chat.completion.chunk',
-            created: Math.floor(Date.now() / 1000),
-            model: agent.slug,
-            choices: [{ index: 0, delta: { content: delta }, finish_reason: null }],
-          }
-          controller.enqueue(encoder.encode(`data: ${JSON.stringify(chunk)}\n\n`))
+      try {
+        for await (const delta of dispatchSandboxStream(agent, userMessage, consumerId, config)) {
+          sendChunk(delta)
         }
 
-        try {
-          const box = await config.getSandbox(agent)
-          const promptStream = box.streamPrompt(userMessage, {
-            sessionId: `consumer:${consumerId}`,
-            systemPrompt: agent.systemPrompt,
-          })
-
-          for await (const event of promptStream) {
-            if (
-              event.type === 'message.part.updated' &&
-              event.data?.part?.type === 'text' &&
-              event.data.delta
-            ) {
-              sendChunk(event.data.delta)
-            }
-          }
-
-          // Final chunk
-          const done: ChatCompletionChunk = {
-            id: `chatcmpl-${Date.now()}`,
-            object: 'chat.completion.chunk',
-            created: Math.floor(Date.now() / 1000),
-            model: agent.slug,
-            choices: [{ index: 0, delta: {}, finish_reason: 'stop' }],
-          }
-          controller.enqueue(encoder.encode(`data: ${JSON.stringify(done)}\n\n`))
-          controller.enqueue(encoder.encode('data: [DONE]\n\n'))
-
-          // 7. Record usage + settle payment
-          const totalCost = (inputTokens + outputTokens) * agent.pricePerTokenUsd
-          const ownerEarned = totalCost * (1 - agent.platformFeePercent)
-          const platformFee = totalCost * agent.platformFeePercent
-
-          const usageEvent = {
-            requestId: ctx.requestId,
-            agentId: agent.id,
-            agentSlug: agent.slug,
-            consumerId: consumerId!,
-            paymentMethod,
-            inputTokens,
-            outputTokens,
-            totalCostUsd: totalCost,
-            ownerEarnedUsd: ownerEarned,
-            platformFeeUsd: platformFee,
-            durationMs: Date.now() - startMs,
-          }
-
-          await config.recordUsage(usageEvent)
-          await obs?.onRequestComplete?.(ctx, usageEvent)
-
-          if (config.settlePayment) {
-            await config.settlePayment(
-              { method: paymentMethod, consumerId: consumerId!, requestId: ctx.requestId },
-              totalCost,
-            ).catch(async err => {
-              const msg = err instanceof Error ? err.message : String(err)
-              console.error(`[agent-gateway] settlement failed for ${consumerId}: ${msg}`)
-              await obs?.onSettlementError?.(ctx, { consumerId: consumerId!, method: paymentMethod, errorMessage: msg })
-            })
-          }
-        } catch (err) {
-          // Sanitize error — never expose stack traces or internal paths
-          const rawMessage = err instanceof Error ? err.message : String(err)
-          const safeMessage =
-            rawMessage.includes('/') || rawMessage.includes('\\')
-              ? 'Internal agent error'
-              : rawMessage
-          await obs?.onStreamError?.(ctx, { consumerId: consumerId!, errorMessage: rawMessage })
-          controller.enqueue(
-            encoder.encode(`data: ${JSON.stringify({ error: { message: safeMessage, type: 'server_error' } })}\n\n`),
-          )
-        } finally {
-          controller.close()
+        const done: ChatCompletionChunk = {
+          id: `chatcmpl-${Date.now()}`,
+          object: 'chat.completion.chunk',
+          created: Math.floor(Date.now() / 1000),
+          model: agent.slug,
+          choices: [{ index: 0, delta: {}, finish_reason: 'stop' }],
         }
-      },
-    })
-
-    return new Response(stream, {
-      headers: {
-        'Content-Type': 'text/event-stream',
-        'Cache-Control': 'no-cache',
-        'X-Request-Id': requestId,
-        'X-Agent-Slug': agent.slug,
-        'X-Agent-Hosting': agent.sandboxEndpoint ? 'sovereign' : 'centralized',
-        'X-Payment-Method': paymentMethod,
-        'X-Payment-Settled': paymentMethod === 'x402' ? 'pending' : 'true',
-        ...(rl.remaining !== undefined ? { 'X-RateLimit-Remaining': String(rl.remaining) } : {}),
-      },
-    })
+        controller.enqueue(encoder.encode(`data: ${JSON.stringify(done)}\n\n`))
+        controller.enqueue(encoder.encode('data: [DONE]\n\n'))
+
+        await settleAndRecord(agent, authz, inputTokens, outputTokens, config, obs)
+      } catch (err) {
+        const rawMessage = err instanceof Error ? err.message : String(err)
+        // Never expose stack traces / absolute paths from sandbox internals.
+        const safeMessage =
+          rawMessage.includes('/') || rawMessage.includes('\\')
+            ? 'Internal agent error'
+            : rawMessage
+        await obs?.onStreamError?.(ctx, { consumerId, errorMessage: rawMessage })
+        controller.enqueue(
+          encoder.encode(
+            `data: ${JSON.stringify({ error: { message: safeMessage, type: 'server_error' } })}\n\n`,
+          ),
+        )
+      } finally {
+        controller.close()
+      }
+    },
   })
 
-  return gw
+  return new Response(stream, {
+    headers: {
+      'Content-Type': 'text/event-stream',
+      'Cache-Control': 'no-cache',
+      'X-Request-Id': requestId,
+      'X-Agent-Slug': agent.slug,
+      'X-Agent-Hosting': agent.sandboxEndpoint ? 'sovereign' : 'centralized',
+      'X-Payment-Method': paymentMethod,
+      'X-Payment-Settled': paymentMethod === 'x402' ? 'pending' : 'true',
+      ...(rateLimitRemaining !== undefined
+        ? { 'X-RateLimit-Remaining': String(rateLimitRemaining) }
+        : {}),
+    },
+  })
 }
+

package/src/types.ts

@@ -21,6 +21,52 @@ export interface AgentMeta {
   remoteBearerToken: string | null
   /** Whether agent is published and accepting requests */
   enabled: boolean
+  /**
+   * CLI harness backend that runs this agent inside the sandbox sidecar.
+   *
+   * When set, the host's `getSandbox()` SHOULD return a `SandboxBox`
+   * whose `streamPrompt` POSTs to the sidecar's
+   * `POST /agent/invoke/chat/completions` endpoint with
+   * `model: "<harness>/<harnessModel>"` — that endpoint runs the
+   * harness against the sandbox workspace and streams OpenAI-shape
+   * `chat.completion.chunk` frames back.
+   *
+   * When unset (legacy / template mode), the host's `streamPrompt`
+   * falls back to the template's own `/api/chat/completions` (proxied
+   * via the sidecar's `/agent/invoke`).
+   *
+   * Known harnesses (registered in agent-dev-container's
+   * cli-agent-bindings.ts): opencode, claude-code, codex, kimi-code,
+   * amp, factory-droids, pi, hermes, openclaw, forge, acp, cursor.
+   * Aliases the sidecar canonicalizes: claude → claude-code,
+   * kimi → kimi-code, factory → factory-droids.
+   */
+  harness?: string
+  /**
+   * Model identifier to pass after the harness in the
+   * `<harness>/<model>` slash form. Format is harness-specific:
+   *   claude-code:   "sonnet", "opus", or a versioned id like
+   *                  "claude-sonnet-4-20250514"
+   *   opencode:      "anthropic/claude-sonnet-4-5", "openai/gpt-4o", …
+   *                  (opencode embeds provider before model)
+   *   codex:         "gpt-5-codex"
+   *   kimi-code:     "kimi-for-coding"
+   *
+   * Only meaningful when `harness` is set; ignored otherwise.
+   */
+  harnessModel?: string
+  /**
+   * Optional human description surfaced in the A2A Agent Card. Defaults to
+   * `"{slug} agent"` when absent.
+   */
+  description?: string
+  /**
+   * Optional A2A skill descriptors. Each entry advertises what the agent
+   * can do so non-Tangle A2A clients can select agents by capability. When
+   * absent, the gateway synthesizes a single default `chat` skill from
+   * `slug` + `description`.
+   */
+  skills?: import('./a2a/types').AgentSkill[]
 }
 
 // --- Payment ---
@@ -107,6 +153,15 @@ export interface SandboxStreamEvent {
     part?: { type?: string; text?: string }
     delta?: string
     finalText?: string
+    /**
+     * Optional sandbox-side signal that the agent has paused and is waiting
+     * for additional input from the caller. The A2A gateway translates this
+     * into an `input-required` task status; the caller can then submit a
+     * follow-up `message/send` with the same `taskId` to continue. Ignored
+     * by the OpenAI-compat path. Carry an optional `prompt` to surface to
+     * the caller (rendered as the input-required message body).
+     */
+    inputRequired?: { prompt?: string }
   }
 }
 
@@ -184,6 +239,46 @@ export interface GatewayConfig {
    * ConsoleObserver / CompositeObserver implementations.
    */
   observer?: import('./observer').GatewayObserver
+
+  /**
+   * A2A protocol configuration. When set, the gateway exposes the A2A
+   * surface alongside its OpenAI-compatible endpoints:
+   *   GET  /:slug/.well-known/agent.json   — AgentCard discovery
+   *   POST /:slug                          — JSON-RPC 2.0 endpoint
+   *     methods: message/send, message/stream, tasks/get, tasks/cancel
+   * Auth + rate-limit + injection-filter + authorization all share the
+   * same pipeline as the OpenAI-compat path. `taskStore` defaults to
+   * `InMemoryTaskStore`; swap in D1/postgres/DO for durable deployments.
+   */
+  a2a?: {
+    /**
+     * Where tasks live. Defaults to `InMemoryTaskStore`; swap in
+     * `SqlTaskStore` (D1, postgres, sqlite, libSQL) for durability across
+     * gateway restarts.
+     */
+    taskStore?: import('./a2a/task-store').TaskStore
+    /**
+     * Where push notification configs live. When set, the gateway advertises
+     * `capabilities.pushNotifications: true` and exposes the four
+     * `tasks/pushNotificationConfig/*` JSON-RPC methods. Defaults to
+     * undefined (push support disabled), so the agent card honestly reflects
+     * what the gateway will actually do.
+     */
+    pushStore?: import('./a2a/push-notifications').PushNotificationStore
+    /**
+     * Shared HMAC secret used to sign webhook deliveries (`X-A2A-Signature:
+     * sha256=<hex>`). The consumer's webhook verifies the body against this
+     * secret to confirm the call originated from this gateway. Required when
+     * `pushStore` is set; without it, deliveries fire unsigned and a
+     * malicious party that knows the webhook URL can forge deliveries.
+     */
+    webhookSecret?: string
+    /**
+     * Optional fetcher override for webhook delivery. Defaults to global
+     * `fetch`. Override for tests or to wire a queue-backed sender.
+     */
+    pushFetcher?: typeof fetch
+  }
 }
 
 // --- Chat completion types (OpenAI-compatible) ---