agoragentic-mcp 1.3.2 → 1.3.3

package/mcp-server.js

@@ -1,52 +1,60 @@
-#!/usr/bin/env node
-'use strict';
-
-const readline = require('readline');
-const crypto = require('crypto');
-const { version: PACKAGE_VERSION } = require('./package.json');
-
+#!/usr/bin/env node
+'use strict';
+
+const readline = require('readline');
+const crypto = require('crypto');
+const { version: PACKAGE_VERSION } = require('./package.json');
+
 const REMOTE_MCP_URL = process.env.AGORAGENTIC_MCP_URL || 'https://agoragentic.com/api/mcp';
 const AGORAGENTIC_BASE = process.env.AGORAGENTIC_BASE_URL || 'https://agoragentic.com';
-const API_KEY = process.env.AGORAGENTIC_API_KEY || '';
+const RAW_API_KEY = process.env.AGORAGENTIC_API_KEY || '';
+const PLACEHOLDER_API_KEYS = new Set([
+    'amk_glama_test_placeholder',
+    'amk_your_key',
+    'amk_your_key_here',
+    'amk_placeholder',
+    'amk_test_placeholder',
+]);
+const API_KEY = PLACEHOLDER_API_KEYS.has(RAW_API_KEY.trim()) ? '' : RAW_API_KEY.trim();
 const ACP_MODE = process.argv.includes('--acp');
-
+
 const ACP_TOOLS = [
-    {
-        name: 'agoragentic_execute',
-        description: 'Route a task through Agent OS execute() with provider selection, fallback, receipts, and settlement.',
-    },
-    {
-        name: 'agoragentic_match',
-        description: 'Preview routed providers before execution.',
-    },
-    {
-        name: 'agoragentic_quote',
-        description: 'Create a bounded quote before paid execution.',
-    },
-    {
-        name: 'agoragentic_status',
-        description: 'Inspect execution status for an invocation.',
-    },
-    {
-        name: 'agoragentic_receipt',
-        description: 'Fetch normalized receipt and settlement metadata.',
-    },
-    {
-        name: 'agoragentic_browse_services',
-        description: 'Browse stable x402 edge resources.',
-    },
-    {
-        name: 'agoragentic_call_service',
-        description: 'Call a stable x402 edge resource after payment challenge handling.',
-    },
-    {
-        name: 'agoragentic_edge_receipt',
-        description: 'Inspect x402 edge receipt metadata.',
-    },
-    {
-        name: 'agoragentic_x402_test',
-        description: 'Exercise the free x402 pipeline canary.',
-    },
+    {
+        name: 'agoragentic_execute',
+        description: 'Route a task through Agent OS execute() with provider selection, fallback, receipts, and settlement.',
+    },
+    {
+        name: 'agoragentic_match',
+        description: 'Preview routed providers before execution.',
+    },
+    {
+        name: 'agoragentic_quote',
+        description: 'Create a bounded quote before paid execution.',
+    },
+    {
+        name: 'agoragentic_status',
+        description: 'Inspect execution status for an invocation.',
+    },
+    {
+        name: 'agoragentic_receipt',
+        description: 'Fetch normalized receipt and settlement metadata.',
+    },
+    {
+        name: 'agoragentic_browse_services',
+        description: 'Browse stable x402 edge resources.',
+    },
+    {
+        name: 'agoragentic_call_service',
+        description: 'Call a stable x402 edge resource after payment challenge handling.',
+    },
+    {
+        name: 'agoragentic_edge_receipt',
+        description: 'Inspect x402 edge receipt metadata.',
+    },
+    {
+        name: 'agoragentic_x402_test',
+        description: 'Exercise the free x402 pipeline canary.',
+    },
 ];
 
 function buildJsonContent(data) {
@@ -108,65 +116,128 @@ function buildFallbackToolList() {
     return [
         {
             name: 'agoragentic_register',
-            description: 'Register an agent with Agoragentic and receive an API key for routed execution.',
+            description:
+                'Register a new agent with the Agoragentic marketplace and receive an API key. ' +
+                'Use this as the first step before calling agoragentic_execute, agoragentic_match, or agoragentic_execute_status. ' +
+                'This tool is idempotent: registering the same agent name returns the existing API key. ' +
+                'No AGORAGENTIC_API_KEY environment variable is required to call this tool. ' +
+                'Side effects: creates a persistent agent record on the Agoragentic server if one does not exist. ' +
+                'Returns JSON with fields: ok (boolean), api_key (string), agent_id (string), and wallet address. ' +
+                'On error, returns JSON with ok:false and an error message string.',
             inputSchema: {
                 type: 'object',
                 properties: {
-                    name: { type: 'string', description: 'Agent name' },
-                    agent_name: { type: 'string', description: 'Agent name, compatibility alias' },
-                    intent: { type: 'string', description: 'buyer, seller, or both', default: 'buyer' },
-                    description: { type: 'string', description: 'Short agent description' },
+                    name: { type: 'string', description: 'Human-readable agent name, e.g. "my-research-agent"' },
+                    agent_name: { type: 'string', description: 'Alias for the name field (backward compatibility). Prefer using name instead.' },
+                    intent: {
+                        type: 'string',
+                        enum: ['buyer', 'seller', 'both'],
+                        description: 'Agent marketplace role: "buyer" to consume services, "seller" to provide them, or "both"',
+                        default: 'buyer',
+                    },
+                    description: { type: 'string', description: 'One-line summary of what this agent does, e.g. "Summarizes web pages on demand"' },
                 },
             },
         },
         {
             name: 'agoragentic_search',
-            description: 'Search public Agoragentic marketplace capabilities.',
+            description:
+                'Search the public Agoragentic marketplace for available agent capabilities and services. ' +
+                'Use this to discover what services exist before calling agoragentic_execute or agoragentic_match. ' +
+                'This is a read-only operation with no side effects and no USDC spend. ' +
+                'No AGORAGENTIC_API_KEY is required. ' +
+                'Returns JSON with an array of matching capabilities, each containing id, name, description, category, and price_usdc. ' +
+                'Returns an empty array when no capabilities match the query.',
             inputSchema: {
                 type: 'object',
                 properties: {
-                    query: { type: 'string', description: 'Search query' },
-                    category: { type: 'string', description: 'Optional category filter' },
-                    limit: { type: 'number', description: 'Maximum results to return', default: 10 },
+                    query: { type: 'string', description: 'Free-text search query, e.g. "text summarization" or "web scraping"' },
+                    category: { type: 'string', description: 'Filter results by category slug, e.g. "ai-ml", "data", or "web". Omit to search all categories.' },
+                    limit: { type: 'number', description: 'Maximum number of results to return (1\u2013100)', default: 10 },
                 },
             },
         },
         {
             name: 'agoragentic_match',
-            description: 'Preview Router / Marketplace provider matches for a task. No spend.',
+            description:
+                'Preview which providers the Agoragentic Router would select for a given task, without executing or spending USDC. ' +
+                'Use this before agoragentic_execute to compare providers, check pricing, and verify availability. ' +
+                'This is a read-only, non-destructive operation with no side effects. ' +
+                'Requires the AGORAGENTIC_API_KEY environment variable to be set. Returns ok:false with error "missing_api_key" if the key is absent. ' +
+                'Returns JSON with matched providers including their trust scores, estimated cost in USDC, and routing rationale.',
             inputSchema: {
                 type: 'object',
                 properties: {
-                    task: { type: 'string', description: 'Task to route' },
-                    max_cost: { type: 'number', description: 'Maximum USDC price per call' },
-                    category: { type: 'string', description: 'Optional category filter' },
-                    prefer_trusted: { type: 'boolean', description: 'Prefer trusted providers', default: true },
+                    task: { type: 'string', description: 'Natural-language task description to match against providers, e.g. "summarize this article"' },
+                    max_cost: { type: 'number', description: 'Maximum acceptable USDC price per call. Providers above this price are excluded from results.' },
+                    category: { type: 'string', description: 'Optional category filter to narrow provider matches, e.g. "ai-ml"' },
+                    prefer_trusted: { type: 'boolean', description: 'When true, rank verified and trusted providers higher in results', default: true },
                 },
                 required: ['task'],
             },
         },
         {
             name: 'agoragentic_execute',
-            description: 'Execute a task through the hosted Agoragentic Router / Marketplace. May spend according to listing price and account balance.',
+            description:
+                'Execute a task through the Agoragentic Router / Marketplace. The Router selects a provider, invokes it, and returns the result with a receipt. ' +
+                'IMPORTANT: This tool MAY SPEND USDC from the authenticated agent wallet based on the matched provider listing price. ' +
+                'This tool is NOT idempotent \u2014 each call creates a new invocation and may incur a charge. ' +
+                'Prefer agoragentic_match first to preview providers and pricing without spending. ' +
+                'Use agoragentic_search to discover available capabilities before executing. ' +
+                'Do NOT call this tool for read-only discovery; use agoragentic_search or agoragentic_match instead. ' +
+                'Requires the AGORAGENTIC_API_KEY environment variable. Returns ok:false with error "missing_api_key" if the key is absent. ' +
+                'On success, returns JSON with: invocation_id (string), output (provider result object), cost_usdc (number), provider_id (string), and receipt metadata. ' +
+                'On failure, returns JSON with ok:false, a status code, and error details describing routing or provider errors.',
             inputSchema: {
                 type: 'object',
                 properties: {
-                    task: { type: 'string', description: 'Task to execute' },
-                    input: { type: 'object', description: 'Provider input payload', default: {} },
-                    constraints: { type: 'object', description: 'Routing and budget constraints', default: {} },
-                    quote_id: { type: 'string', description: 'Optional quote ID' },
-                    intent_contract_id: { type: 'string', description: 'Optional Agent OS intent contract ID' },
+                    task: {
+                        type: 'string',
+                        description: 'Natural-language task for the Router to match and execute, e.g. "summarize this article" or "scrape https://example.com"',
+                    },
+                    input: {
+                        type: 'object',
+                        description:
+                            'Structured input payload forwarded to the matched provider. Shape depends on the provider API. ' +
+                            'Example: {"text": "Hello world", "max_sentences": 3}',
+                        default: {},
+                    },
+                    constraints: {
+                        type: 'object',
+                        description:
+                            'Optional routing and budget constraints. Supported fields: max_cost (number, maximum USDC per call), ' +
+                            'provider_id (string, pin to a specific provider), category (string). ' +
+                            'Example: {"max_cost": 0.05, "category": "ai-ml"}',
+                        default: {},
+                    },
+                    quote_id: {
+                        type: 'string',
+                        description: 'ID from a prior agoragentic_quote call to lock in a pre-agreed price. Omit for standard dynamic pricing.',
+                    },
+                    intent_contract_id: {
+                        type: 'string',
+                        description: 'Agent OS intent contract ID for auditable intent-to-execution tracking. Omit if not using intent contracts.',
+                    },
                 },
                 required: ['task'],
             },
         },
         {
             name: 'agoragentic_execute_status',
-            description: 'Read status, output, cost, and receipt metadata for a routed execution.',
+            description:
+                'Check the status, output, cost, and receipt of a previous agoragentic_execute invocation. ' +
+                'Use this to poll for results of async executions or to retrieve receipt metadata after completion. ' +
+                'This is a read-only operation with no side effects and no USDC spend. ' +
+                'Requires the AGORAGENTIC_API_KEY environment variable. Returns ok:false with error "missing_api_key" if the key is absent. ' +
+                'Returns JSON with: status ("pending", "completed", or "failed"), output (provider result), cost_usdc, provider_id, receipt_id, and timestamps. ' +
+                'Returns ok:false with error "invalid_invocation_id" if the ID is empty or contains disallowed characters.',
             inputSchema: {
                 type: 'object',
                 properties: {
-                    invocation_id: { type: 'string', description: 'Invocation ID from agoragentic_execute' },
+                    invocation_id: {
+                        type: 'string',
+                        description: 'The invocation_id string returned by a prior agoragentic_execute call, e.g. "inv_abc123def456"',
+                    },
                 },
                 required: ['invocation_id'],
             },
@@ -185,6 +256,8 @@ function mergeFallbackTools(remoteTools = []) {
     return merged;
 }
 
+const FALLBACK_TOOL_NAMES = new Set(buildFallbackToolList().map((tool) => tool.name));
+
 async function executeFallbackTool(name, args = {}) {
     if (name === 'agoragentic_register') {
         const agentName = args.agent_name || args.name || 'mcp-agent';
@@ -246,51 +319,51 @@ async function executeFallbackTool(name, args = {}) {
         tool: name,
     });
 }
-
-function buildRemoteTransport() {
-    const { StreamableHTTPClientTransport } = require('@modelcontextprotocol/sdk/client/streamableHttp.js');
-    const headers = {};
-    if (API_KEY) {
-        headers.Authorization = `Bearer ${API_KEY}`;
-    }
-
-    return new StreamableHTTPClientTransport(new URL(REMOTE_MCP_URL), {
-        requestInit: {
-            headers,
-        },
-    });
-}
-
-async function connectRemoteClient() {
-    const { Client } = require('@modelcontextprotocol/sdk/client/index.js');
-    const transport = buildRemoteTransport();
-    const client = new Client(
-        { name: 'agoragentic-mcp', version: PACKAGE_VERSION },
-        { capabilities: { tools: {}, resources: {}, prompts: {} } }
-    );
-
-    client.onerror = (error) => {
-        if (!error) return;
-        const message = error instanceof Error ? error.message : String(error);
-        console.error(`[agoragentic-mcp] remote client error: ${message}`);
-    };
-
-    await client.connect(transport);
-    return { client, transport };
-}
-
-async function runMcpRelay() {
-    const { Server } = require('@modelcontextprotocol/sdk/server/index.js');
-    const { StdioServerTransport } = require('@modelcontextprotocol/sdk/server/stdio.js');
-    const {
-        CallToolRequestSchema,
-        ListToolsRequestSchema,
-        ListResourcesRequestSchema,
-        ReadResourceRequestSchema,
-        ListPromptsRequestSchema,
-        GetPromptRequestSchema,
-    } = require('@modelcontextprotocol/sdk/types.js');
-
+
+function buildRemoteTransport() {
+    const { StreamableHTTPClientTransport } = require('@modelcontextprotocol/sdk/client/streamableHttp.js');
+    const headers = {};
+    if (API_KEY) {
+        headers.Authorization = `Bearer ${API_KEY}`;
+    }
+
+    return new StreamableHTTPClientTransport(new URL(REMOTE_MCP_URL), {
+        requestInit: {
+            headers,
+        },
+    });
+}
+
+async function connectRemoteClient() {
+    const { Client } = require('@modelcontextprotocol/sdk/client/index.js');
+    const transport = buildRemoteTransport();
+    const client = new Client(
+        { name: 'agoragentic-mcp', version: PACKAGE_VERSION },
+        { capabilities: { tools: {}, resources: {}, prompts: {} } }
+    );
+
+    client.onerror = (error) => {
+        if (!error) return;
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(`[agoragentic-mcp] remote client error: ${message}`);
+    };
+
+    await client.connect(transport);
+    return { client, transport };
+}
+
+async function runMcpRelay() {
+    const { Server } = require('@modelcontextprotocol/sdk/server/index.js');
+    const { StdioServerTransport } = require('@modelcontextprotocol/sdk/server/stdio.js');
+    const {
+        CallToolRequestSchema,
+        ListToolsRequestSchema,
+        ListResourcesRequestSchema,
+        ReadResourceRequestSchema,
+        ListPromptsRequestSchema,
+        GetPromptRequestSchema,
+    } = require('@modelcontextprotocol/sdk/types.js');
+
     const server = new Server(
         { name: 'agoragentic', version: PACKAGE_VERSION },
         { capabilities: { tools: {}, resources: {}, prompts: {} } }
@@ -306,8 +379,23 @@ async function runMcpRelay() {
 
     if (remoteSession) {
         const { client } = remoteSession;
+        let remoteToolNames = null;
+
+        async function listRemoteTools(params = {}) {
+            const result = await client.listTools(params);
+            remoteToolNames = new Set((result.tools || []).map((tool) => tool.name));
+            return result;
+        }
+
+        async function hasRemoteTool(name) {
+            if (!remoteToolNames) {
+                await listRemoteTools();
+            }
+            return remoteToolNames.has(name);
+        }
+
         server.setRequestHandler(ListToolsRequestSchema, async (request) => {
-            const result = await client.listTools(request.params);
+            const result = await listRemoteTools(request.params);
             return {
                 ...result,
                 tools: mergeFallbackTools(result.tools),
@@ -315,11 +403,7 @@ async function runMcpRelay() {
         });
 
         server.setRequestHandler(CallToolRequestSchema, async (request) => {
-            if (
-                request.params.name === 'agoragentic_match' ||
-                request.params.name === 'agoragentic_execute' ||
-                request.params.name === 'agoragentic_execute_status'
-            ) {
+            if (FALLBACK_TOOL_NAMES.has(request.params.name) && !(await hasRemoteTool(request.params.name))) {
                 return executeFallbackTool(request.params.name, request.params.arguments || {});
             }
             return client.callTool(request.params);
@@ -365,10 +449,10 @@ async function runMcpRelay() {
             throw new Error('Prompts are unavailable while the remote Agoragentic MCP relay is unreachable.');
         });
     }
-
-    const stdio = new StdioServerTransport();
-    await server.connect(stdio);
-
+
+    const stdio = new StdioServerTransport();
+    await server.connect(stdio);
+
     const shutdown = async (signal) => {
         console.error(`[agoragentic-mcp] shutting down on ${signal}`);
         if (remoteSession) {
@@ -385,242 +469,242 @@ async function runMcpRelay() {
         }
         process.exit(0);
     };
-
-    process.on('SIGINT', () => {
-        void shutdown('SIGINT');
-    });
-    process.on('SIGTERM', () => {
-        void shutdown('SIGTERM');
-    });
-
+
+    process.on('SIGINT', () => {
+        void shutdown('SIGINT');
+    });
+    process.on('SIGTERM', () => {
+        void shutdown('SIGTERM');
+    });
+
     if (remoteSession) {
         console.error(`[agoragentic-mcp] stdio relay ${PACKAGE_VERSION} connected to ${REMOTE_MCP_URL}`);
     } else {
         console.error(`[agoragentic-mcp] stdio fallback ${PACKAGE_VERSION} using ${AGORAGENTIC_BASE}`);
     }
 }
-
-function buildAcpInitializeResult() {
-    return {
-        protocolVersion: 1,
-        agentInfo: {
-            name: 'Agoragentic Agent OS',
-            version: PACKAGE_VERSION,
-            description:
-                'Agent OS integrations for deployed agents and swarms: execute-first routing, receipts, x402 edge calls, and Base USDC settlement.',
-            homepage: 'https://agoragentic.com',
-        },
-        agentCapabilities: {
-            tools: true,
-            streaming: false,
-            resources: false,
-            prompts: false,
-            loadSession: false,
-            promptCapabilities: {
-                image: false,
-            },
-        },
-        authMethods: [
-            {
-                type: 'env',
-                name: 'AGORAGENTIC_API_KEY',
-                configured: Boolean(API_KEY),
-                required: false,
-                instructions:
-                    'Optional for public discovery and x402 edge calls. Required for authenticated execute/match/status/receipt. Create one with POST /api/quickstart and intent=buyer|seller|both.',
-            },
-        ],
-    };
-}
-
-function buildAcpResponse(id, result) {
-    return {
-        jsonrpc: '2.0',
-        id,
-        result,
-    };
-}
-
-function buildAcpError(id, code, message, data) {
-    return {
-        jsonrpc: '2.0',
-        id,
-        error: data ? { code, message, data } : { code, message },
-    };
-}
-
-function writeAcpMessage(message) {
-    process.stdout.write(`${JSON.stringify(message)}\n`);
-}
-
-function buildAcpSessionId() {
-    return `sess_${crypto.randomBytes(12).toString('hex')}`;
-}
-
-function extractAcpPromptText(content) {
-    if (typeof content === 'string') return content;
-    if (!Array.isArray(content)) return '';
-    return content
-        .map((part) => {
-            if (!part || typeof part !== 'object') return '';
-            if (part.type === 'text' && typeof part.text === 'string') return part.text;
-            return '';
-        })
-        .filter(Boolean)
-        .join('\n');
-}
-
-function buildAcpPromptReply(promptText) {
-    const suffix = promptText ? ` Prompt received: ${promptText.slice(0, 240)}` : '';
-    return [
-        'Agoragentic ACP adapter is a tool bridge, not a code-editing chat agent.',
-        'Use tools/list, then tools/call with agoragentic_execute, agoragentic_match, agoragentic_quote, agoragentic_receipt, or stable x402 service tools.',
-        suffix,
-    ]
-        .filter(Boolean)
-        .join(' ');
-}
-
-async function runAcpAdapter() {
-    const rl = readline.createInterface({
-        input: process.stdin,
-        crlfDelay: Infinity,
-        terminal: false,
-    });
-
-    let remoteSession = null;
-    const acpSessions = new Map();
-
-    async function getRemoteSession() {
-        if (!remoteSession) {
-            remoteSession = await connectRemoteClient();
-        }
-        return remoteSession;
-    }
-
-    async function shutdownRemote() {
-        if (!remoteSession) return;
-        try {
-            await remoteSession.transport.terminateSession();
-        } catch {
-            // Ignore session teardown failures during local shutdown.
-        }
-        try {
-            await remoteSession.transport.close();
-        } catch {
-            // Ignore transport close failures during local shutdown.
-        }
-        remoteSession = null;
-    }
-
-    process.on('SIGINT', () => {
-        void shutdownRemote().finally(() => process.exit(0));
-    });
-    process.on('SIGTERM', () => {
-        void shutdownRemote().finally(() => process.exit(0));
-    });
-
-    console.error(`[agoragentic-mcp] ACP adapter ${PACKAGE_VERSION} ready`);
-
-    for await (const line of rl) {
-        if (!line.trim()) continue;
-
-        let request;
-        try {
-            request = JSON.parse(line);
-        } catch (error) {
-            writeAcpMessage(buildAcpError(null, -32700, 'Invalid JSON-RPC payload'));
-            continue;
-        }
-
-        const hasId = Object.prototype.hasOwnProperty.call(request, 'id');
-        const id = hasId ? request.id : null;
-
-        function writeResponse(message) {
-            if (hasId) writeAcpMessage(message);
-        }
-
-        try {
-            if (request.method === 'initialize') {
-                writeResponse(buildAcpResponse(id, buildAcpInitializeResult()));
-            } else if (request.method === 'session/new') {
-                const sessionId = buildAcpSessionId();
-                acpSessions.set(sessionId, {
-                    cwd: request.params?.cwd || process.cwd(),
-                    createdAt: new Date().toISOString(),
-                    cancelled: false,
-                });
-                writeResponse(buildAcpResponse(id, { sessionId }));
-            } else if (request.method === 'session/prompt') {
-                const sessionId = request.params?.sessionId;
-                if (!sessionId || !acpSessions.has(sessionId)) {
-                    writeResponse(buildAcpError(id, -32602, 'Unknown or missing ACP sessionId'));
-                    continue;
-                }
-
-                const session = acpSessions.get(sessionId);
-                session.cancelled = false;
-                const promptText = extractAcpPromptText(request.params?.content);
-                const reply = buildAcpPromptReply(promptText);
-
-                writeAcpMessage({
-                    jsonrpc: '2.0',
-                    method: 'session/update',
-                    params: {
-                        sessionId,
-                        update: {
-                            sessionUpdate: 'agent_message_chunk',
-                            content: {
-                                type: 'text',
-                                text: reply,
-                            },
-                        },
-                    },
-                });
-                writeResponse(buildAcpResponse(id, { stopReason: session.cancelled ? 'cancelled' : 'end_turn' }));
-            } else if (request.method === 'session/cancel') {
-                const sessionId = request.params?.sessionId;
-                if (sessionId && acpSessions.has(sessionId)) {
-                    acpSessions.get(sessionId).cancelled = true;
-                }
-                writeResponse(buildAcpResponse(id, { ok: true }));
-            } else if (request.method === 'tools/list') {
-                writeResponse(buildAcpResponse(id, { tools: ACP_TOOLS }));
-            } else if (request.method === 'tools/call') {
-                const { client } = await getRemoteSession();
-                const result = await client.callTool(request.params || {});
-                writeResponse(buildAcpResponse(id, result));
-            } else if (request.method === 'shutdown') {
-                await shutdownRemote();
-                writeResponse(buildAcpResponse(id, { ok: true }));
-            } else {
-                writeResponse(
-                    buildAcpError(id, -32601, 'Unsupported ACP method', {
-                        supported_methods: [
-                            'initialize',
-                            'session/new',
-                            'session/prompt',
-                            'session/cancel',
-                            'tools/list',
-                            'tools/call',
-                            'shutdown',
-                        ],
-                    })
-                );
-            }
-        } catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
-            writeResponse(buildAcpError(id, -32000, message));
-        }
-    }
-
-    await shutdownRemote();
-}
-
-const entrypoint = ACP_MODE ? runAcpAdapter : runMcpRelay;
-
-entrypoint().catch((error) => {
-    const message = error instanceof Error ? error.stack || error.message : String(error);
-    console.error(`[agoragentic-mcp] fatal: ${message}`);
-    process.exit(1);
-});
+
+function buildAcpInitializeResult() {
+    return {
+        protocolVersion: 1,
+        agentInfo: {
+            name: 'Agoragentic Agent OS',
+            version: PACKAGE_VERSION,
+            description:
+                'Agent OS integrations for deployed agents and swarms: execute-first routing, receipts, x402 edge calls, and Base USDC settlement.',
+            homepage: 'https://agoragentic.com',
+        },
+        agentCapabilities: {
+            tools: true,
+            streaming: false,
+            resources: false,
+            prompts: false,
+            loadSession: false,
+            promptCapabilities: {
+                image: false,
+            },
+        },
+        authMethods: [
+            {
+                type: 'env',
+                name: 'AGORAGENTIC_API_KEY',
+                configured: Boolean(API_KEY),
+                required: false,
+                instructions:
+                    'Optional for public discovery and x402 edge calls. Required for authenticated execute/match/status/receipt. Create one with POST /api/quickstart and intent=buyer|seller|both.',
+            },
+        ],
+    };
+}
+
+function buildAcpResponse(id, result) {
+    return {
+        jsonrpc: '2.0',
+        id,
+        result,
+    };
+}
+
+function buildAcpError(id, code, message, data) {
+    return {
+        jsonrpc: '2.0',
+        id,
+        error: data ? { code, message, data } : { code, message },
+    };
+}
+
+function writeAcpMessage(message) {
+    process.stdout.write(`${JSON.stringify(message)}\n`);
+}
+
+function buildAcpSessionId() {
+    return `sess_${crypto.randomBytes(12).toString('hex')}`;
+}
+
+function extractAcpPromptText(content) {
+    if (typeof content === 'string') return content;
+    if (!Array.isArray(content)) return '';
+    return content
+        .map((part) => {
+            if (!part || typeof part !== 'object') return '';
+            if (part.type === 'text' && typeof part.text === 'string') return part.text;
+            return '';
+        })
+        .filter(Boolean)
+        .join('\n');
+}
+
+function buildAcpPromptReply(promptText) {
+    const suffix = promptText ? ` Prompt received: ${promptText.slice(0, 240)}` : '';
+    return [
+        'Agoragentic ACP adapter is a tool bridge, not a code-editing chat agent.',
+        'Use tools/list, then tools/call with agoragentic_execute, agoragentic_match, agoragentic_quote, agoragentic_receipt, or stable x402 service tools.',
+        suffix,
+    ]
+        .filter(Boolean)
+        .join(' ');
+}
+
+async function runAcpAdapter() {
+    const rl = readline.createInterface({
+        input: process.stdin,
+        crlfDelay: Infinity,
+        terminal: false,
+    });
+
+    let remoteSession = null;
+    const acpSessions = new Map();
+
+    async function getRemoteSession() {
+        if (!remoteSession) {
+            remoteSession = await connectRemoteClient();
+        }
+        return remoteSession;
+    }
+
+    async function shutdownRemote() {
+        if (!remoteSession) return;
+        try {
+            await remoteSession.transport.terminateSession();
+        } catch {
+            // Ignore session teardown failures during local shutdown.
+        }
+        try {
+            await remoteSession.transport.close();
+        } catch {
+            // Ignore transport close failures during local shutdown.
+        }
+        remoteSession = null;
+    }
+
+    process.on('SIGINT', () => {
+        void shutdownRemote().finally(() => process.exit(0));
+    });
+    process.on('SIGTERM', () => {
+        void shutdownRemote().finally(() => process.exit(0));
+    });
+
+    console.error(`[agoragentic-mcp] ACP adapter ${PACKAGE_VERSION} ready`);
+
+    for await (const line of rl) {
+        if (!line.trim()) continue;
+
+        let request;
+        try {
+            request = JSON.parse(line);
+        } catch (error) {
+            writeAcpMessage(buildAcpError(null, -32700, 'Invalid JSON-RPC payload'));
+            continue;
+        }
+
+        const hasId = Object.prototype.hasOwnProperty.call(request, 'id');
+        const id = hasId ? request.id : null;
+
+        function writeResponse(message) {
+            if (hasId) writeAcpMessage(message);
+        }
+
+        try {
+            if (request.method === 'initialize') {
+                writeResponse(buildAcpResponse(id, buildAcpInitializeResult()));
+            } else if (request.method === 'session/new') {
+                const sessionId = buildAcpSessionId();
+                acpSessions.set(sessionId, {
+                    cwd: request.params?.cwd || process.cwd(),
+                    createdAt: new Date().toISOString(),
+                    cancelled: false,
+                });
+                writeResponse(buildAcpResponse(id, { sessionId }));
+            } else if (request.method === 'session/prompt') {
+                const sessionId = request.params?.sessionId;
+                if (!sessionId || !acpSessions.has(sessionId)) {
+                    writeResponse(buildAcpError(id, -32602, 'Unknown or missing ACP sessionId'));
+                    continue;
+                }
+
+                const session = acpSessions.get(sessionId);
+                session.cancelled = false;
+                const promptText = extractAcpPromptText(request.params?.content);
+                const reply = buildAcpPromptReply(promptText);
+
+                writeAcpMessage({
+                    jsonrpc: '2.0',
+                    method: 'session/update',
+                    params: {
+                        sessionId,
+                        update: {
+                            sessionUpdate: 'agent_message_chunk',
+                            content: {
+                                type: 'text',
+                                text: reply,
+                            },
+                        },
+                    },
+                });
+                writeResponse(buildAcpResponse(id, { stopReason: session.cancelled ? 'cancelled' : 'end_turn' }));
+            } else if (request.method === 'session/cancel') {
+                const sessionId = request.params?.sessionId;
+                if (sessionId && acpSessions.has(sessionId)) {
+                    acpSessions.get(sessionId).cancelled = true;
+                }
+                writeResponse(buildAcpResponse(id, { ok: true }));
+            } else if (request.method === 'tools/list') {
+                writeResponse(buildAcpResponse(id, { tools: ACP_TOOLS }));
+            } else if (request.method === 'tools/call') {
+                const { client } = await getRemoteSession();
+                const result = await client.callTool(request.params || {});
+                writeResponse(buildAcpResponse(id, result));
+            } else if (request.method === 'shutdown') {
+                await shutdownRemote();
+                writeResponse(buildAcpResponse(id, { ok: true }));
+            } else {
+                writeResponse(
+                    buildAcpError(id, -32601, 'Unsupported ACP method', {
+                        supported_methods: [
+                            'initialize',
+                            'session/new',
+                            'session/prompt',
+                            'session/cancel',
+                            'tools/list',
+                            'tools/call',
+                            'shutdown',
+                        ],
+                    })
+                );
+            }
+        } catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            writeResponse(buildAcpError(id, -32000, message));
+        }
+    }
+
+    await shutdownRemote();
+}
+
+const entrypoint = ACP_MODE ? runAcpAdapter : runMcpRelay;
+
+entrypoint().catch((error) => {
+    const message = error instanceof Error ? error.stack || error.message : String(error);
+    console.error(`[agoragentic-mcp] fatal: ${message}`);
+    process.exit(1);
+});