@tangle-network/agent-gateway 0.8.0 → 0.8.1

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 export { createAgentGateway } from './middleware.js';
-import { G as GatewayConfig, P as PaymentOperationRecoveryResult, a as PaymentRecoveryRecord, M as MppAuthenticatedCredential, A as ApiKeyInfo, b as MppConfig, X as X402Config, c as PaymentRecoveryStore, S as SqlAdapter, C as ChatMessage } from './types-BHISsm7D.js';
-export { d as A2A_ERROR_CODES, e as AgentCapabilities, f as AgentCard, g as AgentCardAuthentication, h as AgentMeta, i as AgentProvider, j as AgentSkill, k as Artifact, l as ChatCompletionChunk, m as ChatCompletionRequest, D as D1DatabaseLike, n as D1StmtLike, o as DataPart, F as FilePart, I as InMemoryPushNotificationStore, p as InMemoryTaskStore, J as JSONRPCErrorResponse, q as JSONRPCRequest, r as JSONRPCResponse, s as JSONRPCSuccessResponse, t as MPP_CHARGE_PROTOCOL_VERSION, u as MemoryPaymentOperations, v as MemoryPaymentOperationsOptions, w as MemoryPaymentRecoveryStore, x as Message, y as MessageSendParams, z as MppChargeLifecycle, B as MppChargeOperation, E as MppChargeOperationState, H as MppChargeRecoveryResult, K as MppChargeRequest, L as PAYMENT_PROTOCOL_VERSION, N as PAYMENT_RECOVERY_VERSION, O as Part, Q as PaymentAuthorizationContext, R as PaymentOperation, T as PaymentOperationNotFound, U as PaymentOperationState, V as PaymentOperations, W as PaymentRecoveryAttribution, Y as PaymentRecoveryConfig, Z as PaymentRecoveryFenceError, _ as PaymentRecoveryState, $ as PaymentRecoveryTarget, a0 as PaymentResult, a1 as PaymentSettlementInput, a2 as PushDeliveryResult, a3 as PushNotificationAuthentication, a4 as PushNotificationConfig, a5 as PushNotificationDeliveryOptions, a6 as PushNotificationStore, a7 as SandboxBox, a8 as SandboxStreamEvent, a9 as SqlPushNotificationStore, aa as SqlTaskStore, ab as StreamingEvent, ac as Task, ad as TaskArtifactUpdateEvent, ae as TaskIdParams, af as TaskPushNotificationConfig, ag as TaskPushNotificationConfigGetParams, ah as TaskState, ai as TaskStatus, aj as TaskStatusUpdateEvent, ak as TaskStore, al as TextPart, am as d1ToSqlAdapter, an as deliverDemoPushNotifications, ao as deliverPushNotifications, ap as mppPaymentOperationId, aq as validatePushNotificationUrl } from './types-BHISsm7D.js';
+import { G as GatewayConfig, P as PaymentOperationRecoveryResult, a as PaymentRecoveryRecord, M as MppAuthenticatedCredential, A as ApiKeyInfo, b as MppConfig, X as X402Config, c as PaymentRecoveryStore, S as SqlAdapter, C as ChatMessage } from './types-oQ58UakD.js';
+export { d as A2A_ERROR_CODES, e as AgentCapabilities, f as AgentCard, g as AgentCardAuthentication, h as AgentMeta, i as AgentProvider, j as AgentSkill, k as ApiKeyGatewayConfig, l as Artifact, m as ChatCompletionChunk, n as ChatCompletionRequest, o as CreateAgentGatewayConfig, D as D1DatabaseLike, p as D1StmtLike, q as DataPart, F as FilePart, I as InMemoryPushNotificationStore, r as InMemoryTaskStore, J as JSONRPCErrorResponse, s as JSONRPCRequest, t as JSONRPCResponse, u as JSONRPCSuccessResponse, v as MPP_CHARGE_PROTOCOL_VERSION, w as MemoryPaymentOperations, x as MemoryPaymentOperationsOptions, y as MemoryPaymentRecoveryStore, z as Message, B as MessageSendParams, E as MppChargeLifecycle, H as MppChargeOperation, K as MppChargeOperationState, L as MppChargeRecoveryResult, N as MppChargeRequest, O as PAYMENT_PROTOCOL_VERSION, Q as PAYMENT_RECOVERY_VERSION, R as Part, T as PaymentAuthorizationContext, U as PaymentOperation, V as PaymentOperationNotFound, W as PaymentOperationState, Y as PaymentOperations, Z as PaymentRecoveryAttribution, _ as PaymentRecoveryConfig, $ as PaymentRecoveryFenceError, a0 as PaymentRecoveryState, a1 as PaymentRecoveryTarget, a2 as PaymentResult, a3 as PaymentSettlementInput, a4 as PushDeliveryResult, a5 as PushNotificationAuthentication, a6 as PushNotificationConfig, a7 as PushNotificationDeliveryOptions, a8 as PushNotificationStore, a9 as SandboxBox, aa as SandboxStreamEvent, ab as SqlPushNotificationStore, ac as SqlTaskStore, ad as StreamingEvent, ae as Task, af as TaskArtifactUpdateEvent, ag as TaskIdParams, ah as TaskPushNotificationConfig, ai as TaskPushNotificationConfigGetParams, aj as TaskState, ak as TaskStatus, al as TaskStatusUpdateEvent, am as TaskStore, an as TextPart, ao as d1ToSqlAdapter, ap as deliverDemoPushNotifications, aq as deliverPushNotifications, ar as mppPaymentOperationId, as as validatePushNotificationUrl } from './types-oQ58UakD.js';
 import { NonceStore } from './nonce-store.js';
 export { AtomicKvNonceClaim, AtomicNonceStore, KvNonceStore, KvNonceStoreOptions, MemoryNonceStore, isAtomicNonceStore } from './nonce-store.js';
 export { CompositeObserver, ConsoleObserver, generateRequestId } from './observer.js';

package/dist/index.js

@@ -35,7 +35,7 @@ import {
   verifyMpp,
   verifyMppCredential,
   verifyX402
-} from "./chunk-MP6IIAIA.js";
+} from "./chunk-C7Z2BRYV.js";
 import {
   KvNonceStore,
   MemoryNonceStore,

package/dist/middleware.d.ts

@@ -1,6 +1,6 @@
 import * as hono_types from 'hono/types';
 import { Hono } from 'hono';
-import { G as GatewayConfig } from './types-BHISsm7D.js';
+import { o as CreateAgentGatewayConfig } from './types-oQ58UakD.js';
 import './nonce-store.js';
 import './rate-limit.js';
 import './observer-types-A0RtA8uL.js';
@@ -15,7 +15,7 @@ import './observer-types-A0RtA8uL.js';
  *   GET  /:slug/chat/completions  — agent discovery metadata (Tangle-native shape)
  *   POST /:slug/chat/completions  — OpenAI-compatible chat endpoint (paid)
  */
-declare function createAgentGateway(inputConfig: GatewayConfig): Hono<hono_types.BlankEnv, hono_types.BlankSchema, "/">;
+declare function createAgentGateway(inputConfig: CreateAgentGatewayConfig): Hono<hono_types.BlankEnv, hono_types.BlankSchema, "/">;
 /** Public package-boundary version marker for durable payment operations. */
 declare namespace createAgentGateway {
     const paymentProtocolVersion: 2;

package/dist/middleware.js

@@ -1,6 +1,6 @@
 import {
   createAgentGateway
-} from "./chunk-MP6IIAIA.js";
+} from "./chunk-C7Z2BRYV.js";
 import "./chunk-J5SDVHOL.js";
 import "./chunk-GITV7CPT.js";
 import "./chunk-XCTXHZ76.js";

package/dist/{types-BHISsm7D.d.ts → types-oQ58UakD.d.ts}

@@ -939,11 +939,24 @@ interface SandboxBox {
         signal?: AbortSignal;
     }): AsyncIterable<SandboxStreamEvent>;
 }
+/** Authenticated request identity supplied when the host resolves a sandbox. */
+interface GatewaySandboxContext {
+    consumerId: string;
+    paymentMethod: PaymentMethod;
+    keyInfo: ApiKeyInfo | null;
+    requestId: string;
+    messages: ChatMessage[];
+    /** Stable UI conversation id when `conversationMode` is `thread`. */
+    threadId?: string;
+}
 interface GatewayConfig {
     /** Resolve agent metadata by slug. Return null if not found or not published. */
     resolveAgent: (slug: string) => Promise<AgentMeta | null>;
-    /** Get a sandbox instance for the agent. Called after payment is verified. */
-    getSandbox: (agent: AgentMeta) => Promise<SandboxBox>;
+    /**
+     * Get the agent execution adapter after payment is verified.
+     * Hosts that use agent-app can drive their normal persisted chat route here.
+     */
+    getSandbox: (agent: AgentMeta, context?: GatewaySandboxContext) => Promise<SandboxBox>;
     /**
      * Optional host authorization hook fired after payment verification
      * and before sandbox resolution. Use it for per-agent allowlists,
@@ -954,6 +967,8 @@ interface GatewayConfig {
         consumerId: string;
         keyId?: string;
         requestId: string;
+        /** Requested stable conversation id, after syntax validation. */
+        threadId?: string;
     }) => Promise<{
         allow: true;
     } | {
@@ -993,6 +1008,14 @@ interface GatewayConfig {
     settlePayment?: (payment: PaymentResult, cost: number) => Promise<void>;
     /** Base URL for API key purchase links (e.g. "https://film.tangle.tools") */
     baseUrl?: string;
+    /** Public API key prefix shown by discovery. Defaults to `sk_agent_`. */
+    apiKeyPrefix?: string;
+    /**
+     * `consumer` keeps the historical session per API consumer.
+     * `thread` accepts `X-Tangle-Thread-Id` or creates one per request and returns
+     * it in the response, so a host can display the same conversation.
+     */
+    conversationMode?: 'consumer' | 'thread';
     /** Max message length in chars (default: 8000) */
     maxMessageLength?: number;
     /** Maximum output token request the gateway accepts. Defaults to 4096. */
@@ -1090,6 +1113,14 @@ interface GatewayConfig {
         pushUrlValidator?: (url: URL) => boolean | Promise<boolean>;
     };
 }
+/** API-key-only gateway input. Payment transports stay disabled. */
+type ApiKeyGatewayConfig = Omit<GatewayConfig, 'mpp' | 'verifyApiKey' | 'x402'> & {
+    mpp?: never;
+    verifyApiKey: NonNullable<GatewayConfig['verifyApiKey']>;
+    x402?: never;
+};
+/** Configuration accepted by `createAgentGateway`. */
+type CreateAgentGatewayConfig = GatewayConfig | ApiKeyGatewayConfig;
 interface ChatMessage {
     role: 'system' | 'user' | 'assistant' | 'tool';
     content: string;
@@ -1116,4 +1147,4 @@ interface ChatCompletionChunk {
     }>;
 }
 
-export { type PaymentRecoveryTarget as $, type ApiKeyInfo as A, type MppChargeOperation as B, type ChatMessage as C, type D1DatabaseLike as D, type MppChargeOperationState as E, type FilePart as F, type GatewayConfig as G, type MppChargeRecoveryResult as H, InMemoryPushNotificationStore as I, type JSONRPCErrorResponse as J, type MppChargeRequest as K, PAYMENT_PROTOCOL_VERSION as L, type MppAuthenticatedCredential as M, PAYMENT_RECOVERY_VERSION as N, type Part as O, type PaymentOperationRecoveryResult as P, type PaymentAuthorizationContext as Q, type PaymentOperation as R, type SqlAdapter as S, type PaymentOperationNotFound as T, type PaymentOperationState as U, type PaymentOperations as V, type PaymentRecoveryAttribution as W, type X402Config as X, type PaymentRecoveryConfig as Y, PaymentRecoveryFenceError as Z, type PaymentRecoveryState as _, type PaymentRecoveryRecord as a, type PaymentResult as a0, type PaymentSettlementInput as a1, type PushDeliveryResult as a2, type PushNotificationAuthentication as a3, type PushNotificationConfig as a4, type PushNotificationDeliveryOptions as a5, type PushNotificationStore as a6, type SandboxBox as a7, type SandboxStreamEvent as a8, SqlPushNotificationStore as a9, SqlTaskStore as aa, type StreamingEvent as ab, type Task as ac, type TaskArtifactUpdateEvent as ad, type TaskIdParams as ae, type TaskPushNotificationConfig as af, type TaskPushNotificationConfigGetParams as ag, type TaskState as ah, type TaskStatus as ai, type TaskStatusUpdateEvent as aj, type TaskStore as ak, type TextPart as al, d1ToSqlAdapter as am, deliverDemoPushNotifications as an, deliverPushNotifications as ao, mppPaymentOperationId as ap, validatePushNotificationUrl as aq, type MppConfig as b, type PaymentRecoveryStore as c, A2A_ERROR_CODES as d, type AgentCapabilities as e, type AgentCard as f, type AgentCardAuthentication as g, type AgentMeta as h, type AgentProvider as i, type AgentSkill as j, type Artifact as k, type ChatCompletionChunk as l, type ChatCompletionRequest as m, type D1StmtLike as n, type DataPart as o, InMemoryTaskStore as p, type JSONRPCRequest as q, type JSONRPCResponse as r, type JSONRPCSuccessResponse as s, MPP_CHARGE_PROTOCOL_VERSION as t, MemoryPaymentOperations as u, type MemoryPaymentOperationsOptions as v, MemoryPaymentRecoveryStore as w, type Message as x, type MessageSendParams as y, type MppChargeLifecycle as z };
+export { PaymentRecoveryFenceError as $, type ApiKeyInfo as A, type MessageSendParams as B, type ChatMessage as C, type D1DatabaseLike as D, type MppChargeLifecycle as E, type FilePart as F, type GatewayConfig as G, type MppChargeOperation as H, InMemoryPushNotificationStore as I, type JSONRPCErrorResponse as J, type MppChargeOperationState as K, type MppChargeRecoveryResult as L, type MppAuthenticatedCredential as M, type MppChargeRequest as N, PAYMENT_PROTOCOL_VERSION as O, type PaymentOperationRecoveryResult as P, PAYMENT_RECOVERY_VERSION as Q, type Part as R, type SqlAdapter as S, type PaymentAuthorizationContext as T, type PaymentOperation as U, type PaymentOperationNotFound as V, type PaymentOperationState as W, type X402Config as X, type PaymentOperations as Y, type PaymentRecoveryAttribution as Z, type PaymentRecoveryConfig as _, type PaymentRecoveryRecord as a, type PaymentRecoveryState as a0, type PaymentRecoveryTarget as a1, type PaymentResult as a2, type PaymentSettlementInput as a3, type PushDeliveryResult as a4, type PushNotificationAuthentication as a5, type PushNotificationConfig as a6, type PushNotificationDeliveryOptions as a7, type PushNotificationStore as a8, type SandboxBox as a9, type SandboxStreamEvent as aa, SqlPushNotificationStore as ab, SqlTaskStore as ac, type StreamingEvent as ad, type Task as ae, type TaskArtifactUpdateEvent as af, type TaskIdParams as ag, type TaskPushNotificationConfig as ah, type TaskPushNotificationConfigGetParams as ai, type TaskState as aj, type TaskStatus as ak, type TaskStatusUpdateEvent as al, type TaskStore as am, type TextPart as an, d1ToSqlAdapter as ao, deliverDemoPushNotifications as ap, deliverPushNotifications as aq, mppPaymentOperationId as ar, validatePushNotificationUrl as as, type GatewaySandboxContext as at, type MppConfig as b, type PaymentRecoveryStore as c, A2A_ERROR_CODES as d, type AgentCapabilities as e, type AgentCard as f, type AgentCardAuthentication as g, type AgentMeta as h, type AgentProvider as i, type AgentSkill as j, type ApiKeyGatewayConfig as k, type Artifact as l, type ChatCompletionChunk as m, type ChatCompletionRequest as n, type CreateAgentGatewayConfig as o, type D1StmtLike as p, type DataPart as q, InMemoryTaskStore as r, type JSONRPCRequest as s, type JSONRPCResponse as t, type JSONRPCSuccessResponse as u, MPP_CHARGE_PROTOCOL_VERSION as v, MemoryPaymentOperations as w, type MemoryPaymentOperationsOptions as x, MemoryPaymentRecoveryStore as y, type Message as z };

package/dist/types.d.ts

@@ -1,4 +1,4 @@
-export { h as AgentMeta, A as ApiKeyInfo, l as ChatCompletionChunk, m as ChatCompletionRequest, C as ChatMessage, G as GatewayConfig, b as MppConfig, a0 as PaymentResult, a7 as SandboxBox, a8 as SandboxStreamEvent, X as X402Config } from './types-BHISsm7D.js';
+export { h as AgentMeta, k as ApiKeyGatewayConfig, A as ApiKeyInfo, m as ChatCompletionChunk, n as ChatCompletionRequest, C as ChatMessage, o as CreateAgentGatewayConfig, G as GatewayConfig, at as GatewaySandboxContext, b as MppConfig, a2 as PaymentResult, a9 as SandboxBox, aa as SandboxStreamEvent, X as X402Config } from './types-oQ58UakD.js';
 import './nonce-store.js';
 import './rate-limit.js';
 export { a as GatewayUsageEvent, P as PaymentMethod, c as SandboxExecutionBudget, S as SandboxUsageReceipt } from './observer-types-A0RtA8uL.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-gateway",
-  "version": "0.8.0",
+  "version": "0.8.1",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/tangle-network/agent-gateway.git"

package/src/dispatch-authorization.ts

@@ -19,6 +19,7 @@ import {
   defaultVerifyApiKey,
   isApiKeyAuthEnabled,
   isMppAuthEnabled,
+  isX402AuthEnabled,
   mppPaymentPayload,
   mppPaymentCredential,
   verifyMppCredential,
@@ -48,6 +49,18 @@ export async function authenticateAndGuard(
   const ctx: RequestContext = { requestId, agentSlug: slug, startMs }
   await state.obs?.onRequestStart?.(ctx)
 
+  let threadId: string | undefined
+  if (config.conversationMode === 'thread') {
+    const requestedThreadId = c.req.header('X-Tangle-Thread-Id')?.trim()
+    if (requestedThreadId && !/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(requestedThreadId)) {
+      return c.json(
+        { error: { message: 'Invalid X-Tangle-Thread-Id', type: 'invalid_request' } },
+        { status: 400, headers: { 'X-Request-Id': requestId } },
+      )
+    }
+    threadId = requestedThreadId || requestId
+  }
+
   const agent = await config.resolveAgent(slug)
   if (!agent || !agent.enabled) {
     return c.json({ error: { message: 'Agent not found', type: 'not_found' } }, 404)
@@ -83,10 +96,14 @@ export async function authenticateAndGuard(
     messages,
     state.maxLen,
   )
-  const userMessage = filtered
+  const userMessages = filtered
     .filter((m) => m.role === 'user')
-    .map((m) => m.content)
-    .join('\n\n')
+  // A thread-backed host already owns the persisted history. Send only the
+  // new turn to avoid storing the caller's full history as one new user row.
+  // Keep the historical concatenation for the default consumer session.
+  const userMessage = config.conversationMode === 'thread'
+    ? userMessages[userMessages.length - 1]?.content ?? ''
+    : userMessages.map((m) => m.content).join('\n\n')
   if (!userMessage) {
     return c.json(
       { error: { message: 'No user message provided', type: 'invalid_request' } },
@@ -176,6 +193,12 @@ export async function authenticateAndGuard(
   let mppPaymentIdentity: string | undefined
 
   if (spendAuthHeader) {
+    if (!isX402AuthEnabled(config)) {
+      return c.json(
+        { error: { message: 'x402 authentication is not configured', type: 'authentication_error' } },
+        { status: 401, headers: { 'X-Request-Id': requestId } },
+      )
+    }
     const signer = await verifyX402(
       spendAuthHeader,
       config.x402,
@@ -301,7 +324,8 @@ export async function authenticateAndGuard(
       code: 'payment_required',
       httpStatus: 402,
     })
-    const methods: string[] = ['x402']
+    const methods: string[] = []
+    if (isX402AuthEnabled(config)) methods.push('x402')
     if (isMppAuthEnabled(config)) methods.push('mpp')
     if (isApiKeyAuthEnabled(config)) methods.push('api_key')
     const headers: Record<string, string> = {
@@ -318,14 +342,18 @@ export async function authenticateAndGuard(
           message: 'Payment required',
           type: 'payment_required',
           payment_methods: methods,
-          x402: {
-            operator: config.x402.operatorAddress,
-            chain_id: config.x402.chainId,
-            credits_address: config.x402.creditsAddress,
-            required_amount: requiredPaymentAmount.toString(),
-            currency_decimals: config.x402.currencyDecimals ?? 6,
-            max_output_tokens: maxOutputTokens,
-          },
+          ...(isX402AuthEnabled(config)
+            ? {
+                x402: {
+                  operator: config.x402.operatorAddress,
+                  chain_id: config.x402.chainId,
+                  credits_address: config.x402.creditsAddress,
+                  required_amount: requiredPaymentAmount.toString(),
+                  currency_decimals: config.x402.currencyDecimals ?? 6,
+                  max_output_tokens: maxOutputTokens,
+                },
+              }
+            : {}),
           ...(isMppAuthEnabled(config) && config.mpp
             ? { mpp: { realm: config.mpp.realm, method: config.mpp.method ?? 'blueprintevm' } }
             : {}),
@@ -399,6 +427,7 @@ export async function authenticateAndGuard(
       consumerId: consumerId,
       keyId: keyInfo?.keyId,
       requestId,
+      ...(threadId ? { threadId } : {}),
     })
     if (!authz.allow) {
       return c.json(
@@ -422,6 +451,8 @@ export async function authenticateAndGuard(
     userMessage,
     rateLimitRemaining: rl.remaining,
     requestId,
+    messages: filtered,
+    ...(threadId ? { threadId } : {}),
     startMs,
     maxOutputTokens,
     executionBudget,

package/src/dispatch-sandbox.ts

@@ -7,6 +7,7 @@ import {
 import type {
   AgentMeta,
   GatewayConfig,
+  GatewaySandboxContext,
   SandboxExecutionBudget,
   SandboxStreamEvent,
   SandboxUsageReceipt,
@@ -58,9 +59,10 @@ export async function* dispatchSandboxStreamRich(
   onSandboxStart?: () => void | Promise<void>,
   maxInputTokens?: number,
   onExecutionHeartbeat?: () => Promise<void>,
+  sandboxContext?: GatewaySandboxContext,
 ): AsyncIterable<A2ADispatchEvent> {
   if (signal?.aborted) return
-  const box = await config.getSandbox(agent)
+  const box = await config.getSandbox(agent, sandboxContext)
   if (signal?.aborted) return
   const outputLimit = maxOutputTokens ?? config.defaultOutputTokens ?? 1024
   if (!Number.isSafeInteger(outputLimit) || outputLimit <= 0) {

package/src/dispatch-types.ts

@@ -7,6 +7,7 @@ import type { PaymentSettlementBasis } from './payment-recovery'
 import type {
   AgentMeta,
   ApiKeyInfo,
+  ChatMessage,
   PaymentMethod,
   SandboxExecutionBudget,
   SandboxUsageReceipt,
@@ -37,6 +38,8 @@ export interface AuthorizedRequest {
   userMessage: string
   rateLimitRemaining: number | undefined
   requestId: string
+  messages?: ChatMessage[]
+  threadId?: string
   startMs: number
   maxOutputTokens: number
   executionBudget: SandboxExecutionBudget

package/src/index.ts

@@ -111,6 +111,8 @@ export type {
   SandboxUsageReceipt,
   SandboxStreamEvent,
   SandboxBox,
+  ApiKeyGatewayConfig,
+  CreateAgentGatewayConfig,
   GatewayConfig,
   ChatMessage,
   ChatCompletionRequest,

package/src/middleware.ts

@@ -23,8 +23,13 @@ import {
   assertPaymentRecoveryConfig,
 } from './payment-recovery'
 import { MemoryRateLimitStore, type RateLimitStore } from './rate-limit'
-import type { ChatCompletionChunk, ChatCompletionRequest, GatewayConfig } from './types'
-import { isApiKeyAuthEnabled, isMppAuthEnabled } from './verify'
+import type {
+  ChatCompletionChunk,
+  ChatCompletionRequest,
+  CreateAgentGatewayConfig,
+  GatewayConfig,
+} from './types'
+import { isApiKeyAuthEnabled, isMppAuthEnabled, isX402AuthEnabled } from './verify'
 
 /**
  * Create a Hono router that serves the agent gateway.
@@ -36,13 +41,19 @@ import { isApiKeyAuthEnabled, isMppAuthEnabled } from './verify'
  *   GET  /:slug/chat/completions  — agent discovery metadata (Tangle-native shape)
  *   POST /:slug/chat/completions  — OpenAI-compatible chat endpoint (paid)
  */
-export function createAgentGateway(inputConfig: GatewayConfig) {
-  let config = inputConfig
+export function createAgentGateway(inputConfig: CreateAgentGatewayConfig) {
+  let config: GatewayConfig = inputConfig.x402
+    ? inputConfig
+    : {
+        ...inputConfig,
+        x402: { operatorAddress: '', chainId: 0 },
+      }
   // Production gateways must verify x402 signatures. Tests and local
   // dev can opt into the explicit demo path.
-  if (!config.x402.verifySigner && !config.x402.demoMode) {
+  if (!isX402AuthEnabled(config) && !config.verifyApiKey) {
     throw new Error(
-      'createAgentGateway: x402.verifySigner is required in production. ' +
+      'createAgentGateway: verifySigner is required in production unless verifyApiKey is configured; ' +
+        'configure x402.verifySigner or verifyApiKey. ' +
         'For tests, set x402.demoMode: true explicitly.',
     )
   }
@@ -185,14 +196,15 @@ export function createAgentGateway(inputConfig: GatewayConfig) {
     const agent = await config.resolveAgent(slug)
     if (!agent || !agent.enabled) return c.json({ error: 'Agent not found or not published' }, 404)
 
-    const paymentMethods: Array<Record<string, unknown>> = [
-      {
+    const paymentMethods: Array<Record<string, unknown>> = []
+    if (isX402AuthEnabled(config)) {
+      paymentMethods.push({
         type: 'x402',
         operator: config.x402.operatorAddress,
         chain_id: config.x402.chainId,
         credits_contract: config.x402.creditsAddress,
-      },
-    ]
+      })
+    }
     if (isMppAuthEnabled(config)) {
       paymentMethods.push({
         type: 'mpp',
@@ -200,7 +212,9 @@ export function createAgentGateway(inputConfig: GatewayConfig) {
         method: config.mpp!.method ?? 'blueprintevm',
       })
     }
-    if (isApiKeyAuthEnabled(config)) paymentMethods.push({ type: 'api_key', prefix: 'sk_agent_' })
+    if (isApiKeyAuthEnabled(config)) {
+      paymentMethods.push({ type: 'api_key', prefix: config.apiKeyPrefix ?? 'sk_agent_' })
+    }
 
     return c.json({
       slug: agent.slug,
@@ -412,7 +426,7 @@ function streamChatCompletions(
           consumerId,
           config,
           abortController.signal,
-          undefined,
+          authz.threadId,
           maxOutputTokens,
           () => beginPaymentExecution(authz, config),
           authz.paymentOperation !== undefined || authz.mppChargeOperation !== undefined,
@@ -422,6 +436,14 @@ function streamChatCompletions(
           },
           authz.executionBudget.maxInputTokens,
           () => renewPaymentExecution(authz, config),
+          {
+            consumerId,
+            paymentMethod,
+            keyInfo: authz.keyInfo,
+            requestId,
+            messages: authz.messages ?? [],
+            ...(authz.threadId ? { threadId: authz.threadId } : {}),
+          },
         )) {
           if (event.kind === 'text') {
             sendChunk(event.delta)
@@ -499,6 +521,7 @@ function streamChatCompletions(
       'X-Request-Id': requestId,
       'X-Agent-Slug': agent.slug,
       'X-Agent-Hosting': agent.sandboxEndpoint ? 'sovereign' : 'centralized',
+      ...(authz.threadId ? { 'X-Tangle-Thread-Id': authz.threadId } : {}),
       'X-Payment-Method': paymentMethod,
       'X-Payment-Settled': paymentMethod === 'x402' || authz.paymentOperation ? 'pending' : 'true',
       ...(authz.mppChargeOperation

package/src/types.ts

@@ -225,14 +225,28 @@ export interface SandboxBox {
   ): AsyncIterable<SandboxStreamEvent>
 }
 
+/** Authenticated request identity supplied when the host resolves a sandbox. */
+export interface GatewaySandboxContext {
+  consumerId: string
+  paymentMethod: PaymentMethod
+  keyInfo: ApiKeyInfo | null
+  requestId: string
+  messages: ChatMessage[]
+  /** Stable UI conversation id when `conversationMode` is `thread`. */
+  threadId?: string
+}
+
 // --- Gateway config ---
 
 export interface GatewayConfig {
   /** Resolve agent metadata by slug. Return null if not found or not published. */
   resolveAgent: (slug: string) => Promise<AgentMeta | null>
 
-  /** Get a sandbox instance for the agent. Called after payment is verified. */
-  getSandbox: (agent: AgentMeta) => Promise<SandboxBox>
+  /**
+   * Get the agent execution adapter after payment is verified.
+   * Hosts that use agent-app can drive their normal persisted chat route here.
+   */
+  getSandbox: (agent: AgentMeta, context?: GatewaySandboxContext) => Promise<SandboxBox>
 
   /**
    * Optional host authorization hook fired after payment verification
@@ -241,7 +255,14 @@ export interface GatewayConfig {
    */
   authorizeConsumer?: (
     agent: AgentMeta,
-    consumer: { method: PaymentMethod; consumerId: string; keyId?: string; requestId: string },
+    consumer: {
+      method: PaymentMethod
+      consumerId: string
+      keyId?: string
+      requestId: string
+      /** Requested stable conversation id, after syntax validation. */
+      threadId?: string
+    },
   ) => Promise<{ allow: true } | { allow: false; reason: string; code: string }>
 
   /**
@@ -283,6 +304,16 @@ export interface GatewayConfig {
   /** Base URL for API key purchase links (e.g. "https://film.tangle.tools") */
   baseUrl?: string
 
+  /** Public API key prefix shown by discovery. Defaults to `sk_agent_`. */
+  apiKeyPrefix?: string
+
+  /**
+   * `consumer` keeps the historical session per API consumer.
+   * `thread` accepts `X-Tangle-Thread-Id` or creates one per request and returns
+   * it in the response, so a host can display the same conversation.
+   */
+  conversationMode?: 'consumer' | 'thread'
+
   /** Max message length in chars (default: 8000) */
   maxMessageLength?: number
 
@@ -392,6 +423,16 @@ export interface GatewayConfig {
   }
 }
 
+/** API-key-only gateway input. Payment transports stay disabled. */
+export type ApiKeyGatewayConfig = Omit<GatewayConfig, 'mpp' | 'verifyApiKey' | 'x402'> & {
+  mpp?: never
+  verifyApiKey: NonNullable<GatewayConfig['verifyApiKey']>
+  x402?: never
+}
+
+/** Configuration accepted by `createAgentGateway`. */
+export type CreateAgentGatewayConfig = GatewayConfig | ApiKeyGatewayConfig
+
 // --- Chat completion types (OpenAI-compatible) ---
 
 export interface ChatMessage {

package/src/verify.ts

@@ -108,6 +108,13 @@ export function isApiKeyAuthEnabled(
   return config.verifyApiKey !== undefined || config.x402.demoMode === true
 }
 
+/** x402 is advertised only when the gateway can authenticate it. */
+export function isX402AuthEnabled(
+  config: Pick<GatewayConfig, 'x402'>,
+): boolean {
+  return config.x402.verifySigner !== undefined || config.x402.demoMode === true
+}
+
 /** MPP is enabled only when authentication and method settlement are complete. */
 export function isMppAuthEnabled(
   config: Pick<GatewayConfig, 'mpp' | 'x402'>,