HTTP Adapter Framework Abstraction

Status: Critical Prerequisite
Priority: Urgent
Complexity: Medium

Overview

HTTP adapters provide framework-agnostic HTTP handling for AgentDock Core, enabling a single codebase to work across different HTTP frameworks like NextJS, Hono, Express, and others. This eliminates code duplication and creates the foundation for Platform Integration.

Current Blocker

The open source client contains NextJS-specific logic that must be duplicated for each framework. Without HTTP adapters:

• Developers using Hono, Express, or other frameworks must rewrite all HTTP handling logic
• Platform Integration (Telegram, WhatsApp, Slack) cannot be implemented
• Each new framework deployment requires custom implementations

Architecture

Component Structure

agentdock-core/src/
├── adapters/
│   ├── index.ts
│   └── http/
│       ├── index.ts           # HTTP adapter exports
│       ├── base.ts            # Base interfaces
│       ├── factory.ts         # createHTTPAdapter()
│       ├── nextjs.ts          # NextJS implementation
│       ├── hono.ts            # Hono implementation
│       └── express.ts         # Express implementation

Core Interface

// Parsed request in framework-agnostic format
interface ParsedHTTPRequest {
  messages: Message[];
  agentId: string;
  sessionId?: string;
  apiKey?: string;
  headers: Record<string, string>;
  params: Record<string, string>;
  body: any;
}

// Base adapter interface
interface HTTPAdapter {
  parseRequest(request: any): Promise<ParsedHTTPRequest>;
  createStreamResponse(stream: ReadableStream): any;
  createErrorResponse(error: Error): any;
  createSuccessResponse(data?: any): any;
}

Factory Function

export function createHTTPAdapter(type: 'nextjs' | 'hono' | 'express'): HTTPAdapter {
  switch (type) {
    case 'nextjs': return new NextJSAdapter();
    case 'hono': return new HonoAdapter();
    case 'express': return new ExpressAdapter();
  }
}

Implementation Plan

Phase 1: Core Infrastructure

• Base interfaces and types
• Factory system with adapter registry
• Generic HTTP adapter for fallback

Phase 2: Framework Adapters

• NextJS adapter (handle NextRequest/NextResponse)
• Hono adapter (handle Context objects)
• Express adapter (handle Request/Response)

Phase 3: Agent Integration

• Unified processing pipeline
• Integration with AgentNode.handleMessage()
• Session and orchestration manager support

Phase 4: Testing & Migration

• Comprehensive testing suite
• Open source client migration
• Documentation and examples

Usage Examples

Open Source Client (Before)

// src/app/api/chat/[agentId]/route.ts - 120+ lines
export async function POST(request: NextRequest) {
  const body = await request.json();
  const agentId = request.nextUrl.pathname.split('/')[3];
  // ... complex NextJS-specific logic
  const agent = new AgentNode(agentId, config);
  const result = await agent.handleMessage(options);
  return new Response(result.fullStream);
}

Open Source Client (After)

// src/app/api/chat/[agentId]/route.ts - 5 lines
export async function POST(request: NextRequest) {
  const adapter = createHTTPAdapter('nextjs');
  return processAgentHTTPRequest(adapter, request, {
    fallbackApiKey: process.env.FALLBACK_API_KEY
  });
}

Other Framework Deployments (New)

// Hono route using same core logic
app.post('/chat/:agentId', async (c) => {
  const adapter = createHTTPAdapter('hono');
  return processAgentHTTPRequest(adapter, c, {
    fallbackApiKey: process.env.FALLBACK_API_KEY
  });
});

// Express route using same core logic
app.post('/chat/:agentId', async (req, res) => {
  const adapter = createHTTPAdapter('express');
  return processAgentHTTPRequest(adapter, { req, res });
});

Integration Details

Unified Processing Pipeline

export async function processAgentHTTPRequest(
  adapter: HTTPAdapter,
  request: any,
  options?: { fallbackApiKey?: string }
) {
  // Parse request using framework adapter
  const parsed = await adapter.parseRequest(request);
  
  // Load agent configuration
  const agentConfig = await loadAgentConfig(parsed.agentId);
  
  // Initialize orchestration
  const orchestrationManager = getOrchestrationManagerInstance();
  await orchestrationManager.ensureStateExists(parsed.sessionId);
  
  // Create and run agent
  const agent = new AgentNode(parsed.agentId, {
    agentConfig,
    apiKey: parsed.apiKey || options?.fallbackApiKey,
    provider: agentConfig.provider
  });
  
  const result = await agent.handleMessage({
    messages: parsed.messages,
    sessionId: parsed.sessionId,
    orchestrationManager
  });
  
  return adapter.createStreamResponse(result.fullStream);
}

Framework Implementations

NextJS Adapter:

export class NextJSAdapter implements HTTPAdapter {
  async parseRequest(request: NextRequest): Promise<ParsedHTTPRequest> {
    const body = await request.json();
    return {
      messages: body.messages || [],
      agentId: request.nextUrl.pathname.split('/').pop() || '',
      sessionId: body.sessionId,
      apiKey: request.headers.get('x-api-key') || undefined,
      headers: Object.fromEntries(request.headers.entries()),
      params: {},
      body
    };
  }
  
  createStreamResponse(stream: ReadableStream): Response {
    return new Response(stream, {
      headers: {
        'Content-Type': 'text/plain; charset=utf-8',
        'Cache-Control': 'no-cache'
      }
    });
  }
}

Hono Adapter:

export class HonoAdapter implements HTTPAdapter {
  async parseRequest(c: Context): Promise<ParsedHTTPRequest> {
    const body = await c.req.json();
    return {
      messages: body.messages || [],
      agentId: c.req.param('agentId') || '',
      sessionId: body.sessionId,
      apiKey: c.req.header('x-api-key'),
      headers: Object.fromEntries(c.req.raw.headers.entries()),
      params: c.req.param(),
      body
    };
  }
  
  createStreamResponse(stream: ReadableStream): Response {
    return new Response(stream, {
      headers: {
        'Content-Type': 'text/plain; charset=utf-8',
        'Cache-Control': 'no-cache'
      }
    });
  }
}

Migration Impact

Open Source Client Changes

Files to Remove:

• src/lib/agent-adapter.ts (logic moves to agentdock-core)
• src/lib/orchestration-adapter.ts (logic moves to agentdock-core)

Files to Update:

• src/app/api/chat/[agentId]/route.ts (simplified to 5 lines)
• Any remaining imports from removed files

New Capabilities:

• Foundation for platform webhook routes
• Consistent behavior across frameworks
• Easier testing and debugging

Framework Flexibility Benefits

Before HTTP Adapters:

• Must rewrite all NextJS logic for each framework
• Different error handling and response formats
• Separate maintenance burden per framework

After HTTP Adapters:

• Direct reuse of core logic across all frameworks
• Identical behavior and error handling
• Single codebase works everywhere

Dependencies

Blocks These Features

• Platform Integration - Cannot implement Telegram/WhatsApp/Slack webhooks
• Voice AI Agents - Requires webhook handling for phone integrations
• Alternative Frameworks - Hono, Express, and other deployments need abstraction

Required By These Use Cases

• Platform Integration - Foundation for webhook handling
• Framework Flexibility - Support for Hono, Express, and other frameworks
• Open Source Maintenance - Simplified route updates

Technical Requirements

Must Support

• Streaming responses for agent messages
• Session management integration
• Orchestration state handling
• Error response formatting
• CORS configuration
• Header management

Performance Targets

• Zero latency overhead vs current implementation
• Memory usage identical to current NextJS routes
• Support for concurrent requests

Compatibility

• NextJS 14+ (current open source client)
• Hono (for developers preferring Hono)
• Express 4+ (for developers preferring Express)
• Node.js runtime support

Success Criteria

Code Metrics

• 80% reduction in framework-specific HTTP code
• Single implementation supports 3+ frameworks
• 95% test coverage for all adapters

Development Velocity

• New framework support becomes trivial
• Platform webhook implementation unblocked
• Alternative framework deployments enabled

Maintenance Benefits

• HTTP bugs fixed once, applied everywhere
• Consistent error handling across platforms
• Unified testing strategy

Risk Mitigation

Performance Risk

• Concern: Additional abstraction layer
• Mitigation: Benchmark against current implementation
• Fallback: Direct framework integration if needed

Compatibility Risk

• Concern: Framework version changes
• Mitigation: Comprehensive test suite with CI/CD
• Fallback: Quick adapter updates

Migration Risk

• Concern: Open source client disruption
• Mitigation: Gradual rollout with extensive testing
• Fallback: Immediate rollback capability

Implementation Checklist

Phase 1: Core Infrastructure

• Create adapters/http/base.ts with interfaces
• Implement factory function and registry
• Add comprehensive TypeScript types
• Create generic adapter fallback

Phase 2: Framework Adapters

• NextJS adapter with streaming support
• Hono adapter with Context handling
• Express adapter with middleware support
• Adapter-specific error handling

Phase 3: Integration

• Unified processAgentHTTPRequest() function
• Session manager integration
• Orchestration manager integration
• Error handling and logging

Phase 4: Testing & Migration

• Unit tests for all adapters
• Integration tests with AgentDock Core
• Open source client migration
• Documentation and examples