a2acalling 0.5.3 → 0.5.4

package/README.md

@@ -208,6 +208,7 @@ Dashboard/API log routes:
 - `GET /api/a2a/dashboard/logs`
 - `GET /api/a2a/dashboard/logs/trace/:traceId`
 - `GET /api/a2a/dashboard/logs/stats`
+- `GET /api/a2a/dashboard/debug/call?trace_id=<id>` (or `conversation_id=<id>`)
 
 Useful filters for `/api/a2a/dashboard/logs`:
 
@@ -221,6 +222,24 @@ Example:
 curl "http://localhost:3001/api/a2a/dashboard/logs?trace_id=trace_abc123&error_code=TOKEN_INVALID_OR_EXPIRED"
 ```
 
+### Incoming Call Debug
+
+Every `/api/a2a/invoke` and `/api/a2a/end` response now returns:
+- `trace_id` (generated when caller does not send one)
+- `request_id` (generated when caller does not send one)
+
+To inspect one call, use the dashboard debug endpoint:
+
+```bash
+curl -H "x-admin-token: $A2A_ADMIN_TOKEN" \
+  "http://localhost:3001/api/a2a/dashboard/debug/call?trace_id=<trace_id>"
+```
+
+For each call you get:
+- `summary` (event count, first/last seen, duration, and IDs involved)
+- `errors` and `error_codes` for fast triage
+- `logs` (ordered timeline events from that trace)
+
 ## 📡 Protocol
 
 Tokens use the `a2a://` URI scheme:

package/docs/protocol.md

@@ -56,6 +56,8 @@ Headers:
 ```
 Authorization: Bearer fed_abc123xyz
 Content-Type: application/json
+x-trace-id: trace_... (optional)
+x-request-id: req_... (optional)
 ```
 
 Request body:
@@ -76,6 +78,8 @@ Success response:
 ```json
 {
   "success": true,
+  "trace_id": "trace_...",
+  "request_id": "req_...",
   "conversation_id": "conv_123456",
   "response": "The agent's response text",
   "can_continue": true,
@@ -114,6 +118,8 @@ Success response:
 ```json
 {
   "success": true,
+  "trace_id": "trace_...",
+  "request_id": "req_...",
   "conversation_id": "conv_123456",
   "status": "concluded",
   "summary": "Optional summary text"
@@ -143,6 +149,7 @@ Dashboard API endpoints:
 - `GET /api/a2a/dashboard/logs`
 - `GET /api/a2a/dashboard/logs/trace/:traceId`
 - `GET /api/a2a/dashboard/logs/stats`
+- `GET /api/a2a/dashboard/debug/call?trace_id=<id>`
 
 Example filters for `/logs`: `trace_id`, `conversation_id`, `token_id`, `error_code`, `status_code`, `component`, `event`, `level`, `search`, `from`, `to`.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "a2acalling",
-  "version": "0.5.3",
+  "version": "0.5.4",
   "description": "Agent-to-agent calling for OpenClaw - A2A agent communication",
   "main": "src/index.js",
   "bin": {

package/scripts/install-openclaw.js

@@ -77,6 +77,53 @@ function loadOpenClawConfig() {
   }
 }
 
+function normalizeDashboardPluginEntry(rawEntry, backendUrl) {
+  const issues = [];
+  const normalized = {
+    enabled: true,
+    config: {}
+  };
+  const entry = (rawEntry && typeof rawEntry === 'object') ? rawEntry : {};
+
+  const legacyBackendUrl = (typeof entry.backendUrl === 'string' && entry.backendUrl.trim())
+    ? entry.backendUrl.trim()
+    : null;
+  const rawConfig = (entry.config && typeof entry.config === 'object') ? entry.config : null;
+
+  if (!entry || typeof entry !== 'object') {
+    issues.push('plugin entry is missing or invalid');
+  }
+
+  if (entry && typeof entry.enabled === 'boolean') {
+    normalized.enabled = entry.enabled;
+  }
+
+  if (rawConfig) {
+    normalized.config = { ...rawConfig };
+  } else if (entry.config !== undefined) {
+    issues.push('plugin entry has non-object config; replacing with empty object');
+  }
+
+  if (legacyBackendUrl) {
+    issues.push(`legacy key detected: plugins.entries.${DASHBOARD_PLUGIN_ID}.backendUrl (using backendUrl migration)`);
+    normalized.config.backendUrl = backendUrl || legacyBackendUrl;
+  } else if (typeof normalized.config.backendUrl === 'string' && normalized.config.backendUrl.trim()) {
+    normalized.config.backendUrl = normalized.config.backendUrl.trim();
+  } else if (typeof backendUrl === 'string' && backendUrl.trim()) {
+    normalized.config.backendUrl = backendUrl.trim();
+  } else {
+    issues.push('backendUrl could not be determined; plugin may fail to route dashboard traffic');
+  }
+
+  return {
+    normalized,
+    issues,
+    changed: issues.length > 0,
+    legacyBackendUrl,
+    summary: `a2a-dashboard-proxy config => ${normalized.enabled ? 'enabled' : 'disabled'}, backendUrl=${normalized.config.backendUrl || 'missing'}`
+  };
+}
+
 function writeOpenClawConfig(config) {
   const backupPath = `${OPENCLAW_CONFIG}.backup.${Date.now()}`;
   fs.copyFileSync(OPENCLAW_CONFIG, backupPath);
@@ -573,20 +620,17 @@ async function install() {
       config.plugins = config.plugins || {};
       config.plugins.entries = config.plugins.entries || {};
       const rawEntry = config.plugins.entries[DASHBOARD_PLUGIN_ID];
-      const existingEntry = (rawEntry && typeof rawEntry === 'object') ? rawEntry : {};
-      const existingConfig = (existingEntry.config && typeof existingEntry.config === 'object')
-        ? existingEntry.config
-        : {};
-      if (typeof existingEntry.backendUrl === 'string' && existingEntry.backendUrl) {
-        log(`Migrated legacy plugin key plugins.entries.${DASHBOARD_PLUGIN_ID}.backendUrl -> plugins.entries.${DASHBOARD_PLUGIN_ID}.config.backendUrl`);
+      const audit = normalizeDashboardPluginEntry(rawEntry, backendUrl);
+      for (const issue of audit.issues) {
+        warn(`a2a-dashboard-proxy config issue: ${issue}`);
       }
-      config.plugins.entries[DASHBOARD_PLUGIN_ID] = {
-        enabled: true,
-        config: {
-          ...existingConfig,
-          backendUrl
-        }
-      };
+      if (audit.legacyBackendUrl) {
+        warn(`Auto-fixing legacy key: plugins.entries.${DASHBOARD_PLUGIN_ID}.backendUrl`);
+      }
+      if (audit.changed) {
+        log(`Migrated dashboard plugin config: ${audit.summary}`);
+      }
+      config.plugins.entries[DASHBOARD_PLUGIN_ID] = audit.normalized;
       configUpdated = true;
       log(`Configured gateway plugin entry: ${DASHBOARD_PLUGIN_ID}`);
     }

package/src/lib/runtime-adapter.js

@@ -34,6 +34,15 @@ function cleanText(value, maxLength = 300) {
     .slice(0, maxLength);
 }
 
+function normalizeCommandText(command) {
+  return String(command || '').trim().slice(0, 160);
+}
+
+function payloadAuditLength(payload) {
+  const raw = JSON.stringify(payload || {});
+  return Number.isFinite(raw?.length) ? raw.length : 0;
+}
+
 function toBool(value, fallback = true) {
   if (value === undefined || value === null || value === '') {
     return fallback;
@@ -326,6 +335,21 @@ function createRuntimeAdapter(options = {}) {
       caller: caller || {},
       context: context || {}
     };
+    const traceId = context?.traceId || context?.trace_id;
+    const requestId = context?.requestId || context?.request_id;
+    const conversationId = context?.conversationId || context?.conversation_id;
+    const startAt = Date.now();
+
+    logger.debug('Invoking generic agent command', {
+      event: 'generic_agent_command_start',
+      traceId,
+      requestId,
+      conversationId,
+      data: {
+        command: normalizeCommandText(genericAgentCommand),
+        payload_bytes: payloadAuditLength(payload)
+      }
+    });
 
     if (genericAgentCommand) {
       try {
@@ -333,6 +357,17 @@ function createRuntimeAdapter(options = {}) {
           timeoutMs: context?.timeoutMs || 65000
         });
         const text = parseCommandTextOutput(output);
+        logger.debug('Generic agent command completed', {
+          event: 'generic_agent_command_complete',
+          traceId,
+          requestId,
+          conversationId,
+          data: {
+            command: normalizeCommandText(genericAgentCommand),
+            duration_ms: Date.now() - startAt,
+            output_length: String(output || '').length
+          }
+        });
         if (text) {
           return text;
         }
@@ -340,13 +375,17 @@ function createRuntimeAdapter(options = {}) {
         runtimeError = err.message;
         logger.error('Generic agent command failed', {
           event: 'generic_agent_command_failed',
-          traceId: context?.traceId,
-          conversationId: context?.conversationId,
+          traceId,
+          requestId,
+          conversationId,
           error_code: 'GENERIC_AGENT_COMMAND_FAILED',
           hint: 'Verify A2A_AGENT_COMMAND exits 0 and returns valid text/JSON response.',
           error: err,
           data: {
-            command_present: Boolean(genericAgentCommand)
+            command_present: Boolean(genericAgentCommand),
+            command: normalizeCommandText(genericAgentCommand),
+            payload_bytes: payloadAuditLength(payload),
+            duration_ms: Date.now() - startAt
           }
         });
       }
@@ -366,11 +405,26 @@ function createRuntimeAdapter(options = {}) {
       messages,
       caller: callerInfo || {}
     };
+    const traceId = callerInfo?.trace_id || callerInfo?.traceId;
+    const requestId = callerInfo?.request_id || callerInfo?.requestId;
+    const conversationId = callerInfo?.conversation_id || callerInfo?.conversationId;
+    const startAt = Date.now();
 
     if (genericSummaryCommand) {
       try {
         const output = runCommand(genericSummaryCommand, payload, { timeoutMs: 35000 });
         const parsed = parseSummaryOutput(output);
+        logger.debug('Generic summary command completed', {
+          event: 'generic_summary_command_complete',
+          traceId,
+          requestId,
+          conversationId,
+          data: {
+            command: normalizeCommandText(genericSummaryCommand),
+            payload_bytes: payloadAuditLength(payload),
+            output_length: String(output || '').length
+          }
+        });
         if (parsed && parsed.summary) {
           return parsed;
         }
@@ -378,13 +432,17 @@ function createRuntimeAdapter(options = {}) {
         reason = err.message;
         logger.error('Generic summary command failed', {
           event: 'generic_summary_command_failed',
-          traceId: callerInfo?.trace_id || callerInfo?.traceId,
-          conversationId: callerInfo?.conversation_id || callerInfo?.conversationId,
+          traceId,
+          requestId,
+          conversationId,
           error_code: 'GENERIC_SUMMARY_COMMAND_FAILED',
           hint: 'Verify A2A_SUMMARY_COMMAND returns JSON with summary field or plain text.',
           error: err,
           data: {
-            command_present: Boolean(genericSummaryCommand)
+            command_present: Boolean(genericSummaryCommand),
+            command: normalizeCommandText(genericSummaryCommand),
+            payload_bytes: payloadAuditLength(payload),
+            duration_ms: Date.now() - startAt
           }
         });
       }
@@ -397,19 +455,47 @@ function createRuntimeAdapter(options = {}) {
     if (!genericNotifyCommand) {
       return;
     }
+    const traceId = payload?.trace_id || payload?.traceId;
+    const requestId = payload?.request_id || payload?.requestId;
+    const conversationId = payload?.conversationId;
+    const startAt = Date.now();
+    logger.debug('Invoking generic notify command', {
+      event: 'generic_notify_command_start',
+      traceId,
+      requestId,
+      conversationId,
+      data: {
+        command: normalizeCommandText(genericNotifyCommand),
+        payload_bytes: payloadAuditLength(payload)
+      }
+    });
     try {
       runCommand(genericNotifyCommand, payload, { timeoutMs: 10000 });
+      logger.debug('Generic notify command completed', {
+        event: 'generic_notify_command_complete',
+        traceId,
+        requestId,
+        conversationId,
+        data: {
+          command: normalizeCommandText(genericNotifyCommand),
+          duration_ms: Date.now() - startAt
+        }
+      });
     } catch (err) {
       logger.error('Generic notify command failed', {
         event: 'generic_notify_command_failed',
-        traceId: payload?.trace_id || payload?.traceId,
-        conversationId: payload?.conversationId,
+        traceId,
+        requestId,
+        conversationId,
         tokenId: payload?.token?.id,
         error_code: 'GENERIC_NOTIFY_COMMAND_FAILED',
         hint: 'Validate A2A_NOTIFY_COMMAND and downstream notifier transport availability.',
         error: err,
         data: {
-          command_present: Boolean(genericNotifyCommand)
+          command_present: Boolean(genericNotifyCommand),
+          command: normalizeCommandText(genericNotifyCommand),
+          payload_bytes: payloadAuditLength(payload),
+          duration_ms: Date.now() - startAt
         }
       });
     }
@@ -417,24 +503,65 @@ function createRuntimeAdapter(options = {}) {
 
   async function runTurn({ sessionId, prompt, message, caller, context = {}, timeoutMs }) {
     const traceId = context?.traceId || context?.trace_id;
+    const requestId = context?.requestId || context?.request_id;
+    const conversationId = context?.conversationId || context?.conversation_id;
     if (modeInfo.mode !== 'openclaw') {
       return runGenericTurn({ message, caller, context });
     }
 
+    const startAt = Date.now();
+    logger.debug('Invoking openclaw turn', {
+      event: 'openclaw_turn_start',
+      traceId,
+      requestId,
+      conversationId,
+      data: {
+        session_id: sessionId,
+        timeout_ms: timeoutMs
+      }
+    });
+
     try {
-      return await runOpenClawTurn({ sessionId, prompt, timeoutMs });
+      const response = await runOpenClawTurn({ sessionId, prompt, timeoutMs });
+      logger.debug('OpenClaw turn completed', {
+        event: 'openclaw_turn_complete',
+        traceId,
+        requestId,
+        conversationId,
+        data: {
+          session_id: sessionId,
+          duration_ms: Date.now() - startAt
+        }
+      });
+      return response;
     } catch (err) {
       if (!failoverEnabled) {
+        logger.error('OpenClaw turn failed', {
+          event: 'openclaw_turn_failed',
+          traceId,
+          requestId,
+          conversationId,
+          error_code: 'OPENCLAW_TURN_FAILED',
+          hint: 'Inspect OpenClaw CLI output, timeout settings, and environment PATH.',
+          error: err,
+          data: {
+            session_id: sessionId,
+            timeout_ms: timeoutMs,
+            duration_ms: Date.now() - startAt
+          }
+        });
         throw err;
       }
       logger.warn('OpenClaw runtime failed, switching to generic fallback', {
         event: 'openclaw_turn_failed_fallback',
         traceId,
-        conversationId: context?.conversationId,
+        requestId,
+        conversationId,
         error_code: 'OPENCLAW_TURN_FAILED_FALLBACK',
         hint: 'Inspect OpenClaw CLI health or set A2A_RUNTIME=generic for explicit fallback mode.',
         error: err,
         data: {
+          duration_ms: Date.now() - startAt,
           failover_enabled: failoverEnabled
         }
       });
@@ -448,9 +575,23 @@ function createRuntimeAdapter(options = {}) {
   }
 
   async function summarize({ sessionId, prompt, messages, callerInfo, traceId, conversationId }) {
+    const effectiveTraceId = traceId || callerInfo?.trace_id || callerInfo?.traceId;
+    const requestId = callerInfo?.request_id || callerInfo?.requestId;
+    const effectiveConversationId = conversationId || callerInfo?.conversation_id || callerInfo?.conversationId;
     if (modeInfo.mode !== 'openclaw') {
       return runGenericSummary({ messages, callerInfo });
     }
+    const startAt = Date.now();
+    logger.debug('Invoking openclaw summary', {
+      event: 'openclaw_summary_start',
+      traceId: effectiveTraceId,
+      requestId,
+      conversationId: effectiveConversationId,
+      data: {
+        session_id: sessionId,
+        message_count: Array.isArray(messages) ? messages.length : 0
+      }
+    });
 
     try {
       const result = await runOpenClawSummary({
@@ -459,8 +600,28 @@ function createRuntimeAdapter(options = {}) {
         timeoutMs: 35000
       });
       if (result && result.summary) {
+        logger.debug('OpenClaw summary completed', {
+          event: 'openclaw_summary_complete',
+          traceId: effectiveTraceId,
+          requestId,
+          conversationId: effectiveConversationId,
+          data: {
+            session_id: sessionId,
+            duration_ms: Date.now() - startAt
+          }
+        });
         return result;
       }
+      logger.warn('OpenClaw summary returned empty output; using generic fallback', {
+        event: 'openclaw_summary_empty',
+        traceId: effectiveTraceId,
+        requestId,
+        conversationId: effectiveConversationId,
+        data: {
+          session_id: sessionId,
+          duration_ms: Date.now() - startAt
+        }
+      });
       return runGenericSummary({
         messages,
         callerInfo,
@@ -468,16 +629,32 @@ function createRuntimeAdapter(options = {}) {
       });
     } catch (err) {
       if (!failoverEnabled) {
+        logger.error('OpenClaw summary failed', {
+          event: 'openclaw_summary_failed',
+          traceId: effectiveTraceId,
+          requestId,
+          conversationId: effectiveConversationId,
+          error_code: 'OPENCLAW_SUMMARY_FAILED',
+          hint: 'Inspect summary message length, timeout configuration, and CLI stderr output.',
+          error: err,
+          data: {
+            session_id: sessionId,
+            duration_ms: Date.now() - startAt
+          }
+        });
         throw err;
       }
       logger.warn('OpenClaw summary failed, using generic fallback', {
         event: 'openclaw_summary_failed_fallback',
-        traceId: traceId || callerInfo?.trace_id || callerInfo?.traceId,
-        conversationId: conversationId || callerInfo?.conversation_id || callerInfo?.conversationId,
+        traceId: effectiveTraceId,
+        requestId,
+        conversationId: effectiveConversationId,
         error_code: 'OPENCLAW_SUMMARY_FAILED_FALLBACK',
         hint: 'Inspect OpenClaw summary session output and summarizer prompt input.',
         error: err,
         data: {
+          session_id: sessionId,
+          duration_ms: Date.now() - startAt,
           failover_enabled: failoverEnabled
         }
       });
@@ -490,6 +667,7 @@ function createRuntimeAdapter(options = {}) {
   }
 
   async function notify({ level, token, caller, message, conversationId, traceId }) {
+    const requestId = token?.request_id || token?.requestId || null;
     const payload = {
       mode: 'a2a-notify',
       level,
@@ -497,9 +675,19 @@ function createRuntimeAdapter(options = {}) {
       caller: caller || null,
       message,
       conversationId,
-      traceId
+      traceId,
+      requestId
     };
 
+    logger.debug('Owner notify requested', {
+      event: 'notify_requested',
+      traceId,
+      requestId,
+      conversationId,
+      tokenId: token?.id,
+      data: { level }
+    });
+
     if (modeInfo.mode !== 'openclaw') {
       return runGenericNotify(payload);
     }
@@ -510,9 +698,20 @@ function createRuntimeAdapter(options = {}) {
 
     const callerName = caller?.name || 'Unknown';
     const callerOwner = caller?.owner ? ` (${caller.owner})` : '';
+    const notifyStart = Date.now();
 
     try {
       await runOpenClawNotify({ callerName, callerOwner, message: message || '' });
+      logger.debug('OpenClaw notify completed', {
+        event: 'openclaw_notify_complete',
+        traceId,
+        requestId,
+        conversationId,
+        tokenId: token?.id,
+        data: {
+          duration_ms: Date.now() - notifyStart
+        }
+      });
     } catch (err) {
       if (!failoverEnabled) {
         throw err;
@@ -520,15 +719,24 @@ function createRuntimeAdapter(options = {}) {
       logger.warn('OpenClaw notify failed, running generic notifier', {
         event: 'openclaw_notify_failed_fallback',
         traceId,
+        requestId,
         conversationId,
         tokenId: token?.id,
         error_code: 'OPENCLAW_NOTIFY_FAILED_FALLBACK',
         hint: 'Check OpenClaw messaging channel config and notify permissions.',
         error: err,
         data: {
-          failover_enabled: failoverEnabled
+          failover_enabled: failoverEnabled,
+          duration_ms: Date.now() - notifyStart
         }
       });
+      logger.debug('OpenClaw notify fallback to generic notifier', {
+        event: 'openclaw_notify_generic_fallback',
+        traceId,
+        requestId,
+        conversationId,
+        tokenId: token?.id
+      });
       await runGenericNotify(payload);
     }
   }

package/src/routes/a2a.js

@@ -74,6 +74,32 @@ function resolveTraceId(req) {
   return createTraceId('a2a');
 }
 
+function resolveRequestId(req) {
+  const headerRequestId = req.headers['x-request-id'];
+  if (typeof headerRequestId === 'string' && headerRequestId.trim()) {
+    return headerRequestId.trim().slice(0, 120);
+  }
+  return createTraceId('req');
+}
+
+function extractClientHost(req) {
+  const forwarded = req.headers['x-forwarded-for'];
+  if (typeof forwarded === 'string' && forwarded.trim()) {
+    return forwarded.split(',')[0].trim();
+  }
+  return req.ip || null;
+}
+
+function normalizeRequestMetadata(req) {
+  const body = req && typeof req.body === 'object' && req.body ? req.body : {};
+  return {
+    has_message: typeof body.message === 'string',
+    has_caller: Boolean(body.caller && typeof body.caller === 'object'),
+    has_context: Boolean(body.context && typeof body.context === 'object'),
+    timeout_seconds: body.timeout_seconds
+  };
+}
+
 function checkRateLimit(tokenId, limits = { minute: 10, hour: 100, day: 1000 }) {
   const now = Date.now();
   const minute = Math.floor(now / 60000);
@@ -177,14 +203,25 @@ function createRoutes(options = {}) {
   router.post('/invoke', async (req, res) => {
     const startedAt = Date.now();
     const traceId = resolveTraceId(req);
-    const reqLogger = logger.child({ traceId, event: 'invoke' });
+    const requestId = resolveRequestId(req);
+    const reqLogger = logger.child({ traceId, requestId, event: 'invoke' });
+    const withTracePayload = (payload) => ({ ...payload, trace_id: traceId, request_id: requestId });
     res.set('x-trace-id', traceId);
+    res.set('x-request-id', requestId);
     reqLogger.info('Received invoke request', {
       data: {
         ip: req.ip,
+        request_id: requestId,
+        client_host: extractClientHost(req),
+        forwarded_for: req.headers['x-forwarded-for'] || null,
+        user_agent: req.headers['user-agent'] || null,
         has_auth_header: Boolean(req.headers.authorization)
       }
     });
+    reqLogger.debug('Invoke request metadata', {
+      event: 'invoke_request_metadata',
+      data: normalizeRequestMetadata(req)
+    });
 
     // Extract token
     const authHeader = req.headers.authorization;
@@ -194,11 +231,11 @@ function createRoutes(options = {}) {
         status_code: 401,
         hint: 'Send Authorization: Bearer <a2a_token>.'
       });
-      return res.status(401).json({ 
+      return res.status(401).json(withTracePayload({ 
         success: false, 
         error: 'missing_token', 
         message: 'Authorization header required' 
-      });
+      }));
     }
 
     const token = authHeader.slice(7);
@@ -213,11 +250,11 @@ function createRoutes(options = {}) {
         status_code: 401,
         hint: 'Create a fresh invite token and retry with the new bearer token.'
       });
-      return res.status(401).json({ 
+      return res.status(401).json(withTracePayload({ 
         success: false, 
         error: 'unauthorized', 
         message: 'Invalid or expired token' 
-      });
+      }));
     }
 
     // Check rate limit
@@ -233,11 +270,11 @@ function createRoutes(options = {}) {
         }
       });
       res.set('Retry-After', rateCheck.retryAfter);
-      return res.status(429).json({ 
+      return res.status(429).json(withTracePayload({ 
         success: false, 
         error: rateCheck.error, 
         message: rateCheck.message 
-      });
+      }));
     }
 
     // Extract and validate request
@@ -250,11 +287,11 @@ function createRoutes(options = {}) {
         status_code: 400,
         hint: 'Include a non-empty string field `message` in the request body.'
       });
-      return res.status(400).json({ 
+      return res.status(400).json(withTracePayload({ 
         success: false, 
         error: 'missing_message', 
         message: 'Message is required' 
-      });
+      }));
     }
 
     // Validate message length
@@ -269,11 +306,11 @@ function createRoutes(options = {}) {
           message_length: typeof message === 'string' ? message.length : null
         }
       });
-      return res.status(400).json({
+      return res.status(400).json(withTracePayload({
         success: false,
         error: 'invalid_message',
         message: `Message must be a string under ${MAX_MESSAGE_LENGTH} characters`
-      });
+      }));
     }
 
     // Validate and bound timeout
@@ -299,7 +336,8 @@ function createRoutes(options = {}) {
       disclosure: validation.disclosure,
       caller: sanitizedCaller,
       conversation_id: conversation_id || `conv_${Date.now()}_${crypto.randomBytes(6).toString('hex')}`,
-      trace_id: traceId
+      trace_id: traceId,
+      request_id: requestId
     };
 
     // Track conversation if store available
@@ -317,7 +355,8 @@ function createRoutes(options = {}) {
         if (monitor) {
           monitor.trackActivity(a2aContext.conversation_id, {
             ...sanitizedCaller,
-            trace_id: traceId
+            trace_id: traceId,
+            request_id: requestId
           });
         }
         
@@ -377,7 +416,8 @@ function createRoutes(options = {}) {
           message,
           response: response.text,
           conversation_id: a2aContext.conversation_id,
-          trace_id: traceId
+          trace_id: traceId,
+          request_id: requestId
         }).catch(err => {
           reqLogger.error('Failed to notify owner', {
             conversationId: a2aContext.conversation_id,
@@ -395,6 +435,7 @@ function createRoutes(options = {}) {
       reqLogger.info('Invoke request completed', {
         conversationId: a2aContext.conversation_id,
         tokenId: validation.id,
+        requestId,
         data: {
           duration_ms: Date.now() - startedAt,
           message_length: message.length,
@@ -404,6 +445,8 @@ function createRoutes(options = {}) {
 
       res.json({
         success: true,
+        trace_id: traceId,
+        request_id: requestId,
         conversation_id: a2aContext.conversation_id,
         response: response.text,
         can_continue: response.canContinue !== false,
@@ -422,11 +465,11 @@ function createRoutes(options = {}) {
           duration_ms: Date.now() - startedAt
         }
       });
-      res.status(500).json({
+      res.status(500).json(withTracePayload({
         success: false,
         error: 'internal_error',
         message: 'Failed to process message'
-      });
+      }));
     }
   });
 
@@ -437,8 +480,20 @@ function createRoutes(options = {}) {
   router.post('/end', async (req, res) => {
     const startedAt = Date.now();
     const traceId = resolveTraceId(req);
-    const reqLogger = logger.child({ traceId, event: 'end' });
+    const requestId = resolveRequestId(req);
+    const reqLogger = logger.child({ traceId, requestId, event: 'end' });
+    const withTracePayload = (payload) => ({ ...payload, trace_id: traceId, request_id: requestId });
     res.set('x-trace-id', traceId);
+    res.set('x-request-id', requestId);
+    reqLogger.info('Received end request', {
+      data: {
+        request_id: requestId,
+        ip: req.ip,
+        client_host: extractClientHost(req),
+        has_auth_header: Boolean(req.headers.authorization),
+        has_conversation_id: Boolean(req.body && req.body.conversation_id)
+      }
+    });
 
     // Extract token
     const authHeader = req.headers.authorization;
@@ -448,11 +503,11 @@ function createRoutes(options = {}) {
         status_code: 401,
         hint: 'Send Authorization: Bearer <a2a_token>.'
       });
-      return res.status(401).json({ 
+      return res.status(401).json(withTracePayload({ 
         success: false, 
         error: 'unauthorized', 
         message: 'Authorization header required' 
-      });
+      }));
     }
 
     const token = authHeader.slice(7);
@@ -463,11 +518,11 @@ function createRoutes(options = {}) {
         status_code: 401,
         hint: 'Use a currently valid invite token for conversation end calls.'
       });
-      return res.status(401).json({ 
+      return res.status(401).json(withTracePayload({ 
         success: false, 
         error: 'unauthorized', 
         message: 'Invalid or expired token' 
-      });
+      }));
     }
 
     const { conversation_id } = req.body;
@@ -478,16 +533,16 @@ function createRoutes(options = {}) {
         status_code: 400,
         hint: 'Provide `conversation_id` returned from /invoke.'
       });
-      return res.status(400).json({
+      return res.status(400).json(withTracePayload({
         success: false,
         error: 'missing_conversation_id',
         message: 'conversation_id is required'
-      });
+      }));
     }
 
     const convStore = getConversationStore();
     if (!convStore) {
-      return res.json({ success: true, message: 'Conversation storage not enabled' });
+      return res.json(withTracePayload({ success: true, message: 'Conversation storage not enabled' }));
     }
 
     try {
@@ -508,7 +563,8 @@ function createRoutes(options = {}) {
           type: 'conversation_concluded',
           token: validation,
           conversation: conv,
-          trace_id: traceId
+          trace_id: traceId,
+          request_id: requestId
         }).catch(err => {
           reqLogger.error('Failed to notify owner after conversation end', {
             conversationId: conversation_id,
@@ -526,6 +582,7 @@ function createRoutes(options = {}) {
       reqLogger.info('End request completed', {
         conversationId: conversation_id,
         tokenId: validation.id,
+        requestId,
         data: {
           duration_ms: Date.now() - startedAt,
           status: result.success ? 'concluded' : 'unchanged'
@@ -534,6 +591,8 @@ function createRoutes(options = {}) {
 
       res.json({
         success: true,
+        trace_id: traceId,
+        request_id: requestId,
         conversation_id,
         status: 'concluded',
         summary: result.summary
@@ -550,11 +609,11 @@ function createRoutes(options = {}) {
           duration_ms: Date.now() - startedAt
         }
       });
-      res.status(500).json({
+      res.status(500).json(withTracePayload({
         success: false,
         error: 'internal_error',
         message: 'Failed to end conversation'
-      });
+      }));
     }
   });
 

package/src/routes/dashboard.js

@@ -185,6 +185,69 @@ function ensureDashboardAccess(req, res, next) {
   return res.status(401).json({ success: false, error: 'unauthorized', message: 'Admin token required' });
 }
 
+function summarizeDebugLogs(logs) {
+  if (!Array.isArray(logs) || logs.length === 0) {
+    return {
+      event_count: 0,
+      events: [],
+      timestamps: [],
+      error_count: 0,
+      warning_count: 0
+    };
+  }
+
+  const normalized = logs.slice().sort((a, b) => {
+    const aTime = Number(new Date(a.timestamp));
+    const bTime = Number(new Date(b.timestamp));
+    if (Number.isNaN(aTime) && Number.isNaN(bTime)) return 0;
+    if (Number.isNaN(aTime)) return 1;
+    if (Number.isNaN(bTime)) return -1;
+    return aTime - bTime;
+  });
+
+  const firstTimestamp = normalized[0]?.timestamp || null;
+  const lastTimestamp = normalized[normalized.length - 1]?.timestamp || null;
+  const firstMs = firstTimestamp ? Number(new Date(firstTimestamp)) : null;
+  const lastMs = lastTimestamp ? Number(new Date(lastTimestamp)) : null;
+
+  return {
+    event_count: normalized.length,
+    events: normalized.map(row => row.event).filter(Boolean),
+    timestamps: normalized.map(row => row.timestamp),
+    first_seen: firstTimestamp,
+    last_seen: lastTimestamp,
+    timeline_ms: Number.isFinite(firstMs) && Number.isFinite(lastMs) && lastMs >= firstMs
+      ? lastMs - firstMs
+      : null,
+    trace_ids: [...new Set(normalized.map(row => row.trace_id).filter(Boolean))],
+    conversation_ids: [...new Set(normalized.map(row => row.conversation_id).filter(Boolean))],
+    token_ids: [...new Set(normalized.map(row => row.token_id).filter(Boolean))],
+    request_ids: [...new Set(normalized.map(row => row.request_id).filter(Boolean))],
+    error_count: normalized.filter(row => row.level === 'error').length,
+    warning_count: normalized.filter(row => row.level === 'warn').length,
+    hints: [...new Set(normalized
+      .filter(row => row.hint)
+      .map(row => String(row.hint)))]
+  };
+}
+
+function findErrorHints(logs) {
+  const hints = new Map();
+  for (const row of logs) {
+    if (!row.error_code) continue;
+    if (!hints.has(row.error_code)) {
+      hints.set(row.error_code, {
+        error_code: row.error_code,
+        status_code: row.status_code,
+        count: 0
+      });
+    }
+    const existing = hints.get(row.error_code);
+    existing.count += 1;
+  }
+  return Array.from(hints.values());
+}
+
 function createDashboardApiRouter(options = {}) {
   const router = express.Router();
   const context = buildContext(options);
@@ -239,6 +302,65 @@ function createDashboardApiRouter(options = {}) {
     return res.json({ success: true, stats });
   });
 
+  router.get('/debug/call', (req, res) => {
+    const traceId = sanitizeString(req.query.trace_id || req.query.traceId || '', 120);
+    const conversationId = sanitizeString(req.query.conversation_id || req.query.conversationId || '', 120);
+    const limit = Math.min(1000, Math.max(1, Number.parseInt(req.query.limit || '500', 10) || 500));
+
+    if (!traceId && !conversationId) {
+      return res.status(400).json({
+        success: false,
+        error: 'missing_scope',
+        message: 'Provide trace_id or conversation_id.'
+      });
+    }
+
+    const logs = traceId
+      ? context.logger.getTrace(traceId, { limit })
+      : context.logger.list({
+        limit,
+        conversationId,
+        sort_desc: false
+      });
+
+    if (!Array.isArray(logs) || logs.length === 0) {
+      return res.status(404).json({
+        success: false,
+        error: 'no_logs_found',
+        message: traceId ? 'No logs for trace_id' : 'No logs for conversation_id'
+      });
+    }
+
+    const summary = summarizeDebugLogs(logs);
+    const errors = logs.filter(row => row.level === 'error' || row.level === 'warn').slice(0, 20);
+    const callSignature = {
+      trace_ids: summary.trace_ids,
+      conversation_ids: summary.conversation_ids,
+      token_ids: summary.token_ids,
+      request_ids: summary.request_ids
+    };
+
+    return res.json({
+      success: true,
+      summary: {
+        ...summary,
+        ...callSignature,
+        errors: errors.map(row => ({
+          id: row.id,
+          timestamp: row.timestamp,
+          level: row.level,
+          event: row.event,
+          message: row.message,
+          error_code: row.error_code,
+          status_code: row.status_code,
+          hint: row.hint
+        })),
+        error_codes: findErrorHints(logs)
+      },
+      logs: summary.timeline_ms === null ? logs : logs
+    });
+  });
+
   router.get('/contacts', (req, res) => {
     const contacts = context.tokenStore.listRemotes();
     const contactIndex = buildContactIndex(contacts);

package/src/server.js

@@ -454,8 +454,10 @@ async function callAgent(message, a2aContext) {
   const tierInfo = a2aContext.tier || 'public';
   const conversationId = a2aContext.conversation_id || `conv_${Date.now()}`;
   const traceId = a2aContext.trace_id || null;
+  const requestId = a2aContext.request_id || null;
   const callLogger = logger.child({
     traceId,
+    requestId,
     conversationId,
     tokenId: a2aContext.token_id
   });
@@ -528,20 +530,21 @@ async function callAgent(message, a2aContext) {
       }
     });
 
-    const rawResponse = await runtime.runTurn({
-      sessionId,
-      prompt,
-      message,
-      caller: a2aContext.caller || {},
-      timeoutMs: 65000,
-      context: {
-        conversationId,
-        tier: tierInfo,
-        ownerName: agentContext.owner,
-        allowedTopics: a2aContext.allowed_topics || [],
-        traceId
-      }
-    });
+      const rawResponse = await runtime.runTurn({
+        sessionId,
+        prompt,
+        message,
+        caller: a2aContext.caller || {},
+        timeoutMs: 65000,
+        context: {
+          conversationId,
+          tier: tierInfo,
+          ownerName: agentContext.owner,
+          allowedTopics: a2aContext.allowed_topics || [],
+          traceId,
+          requestId
+        }
+      });
 
     if (collabMode !== 'adaptive') {
       return rawResponse;
@@ -595,7 +598,7 @@ async function callAgent(message, a2aContext) {
       }
     });
 
-    return cleanResponse || '[Sub-agent returned empty response]';
+      return cleanResponse || '[Sub-agent returned empty response]';
     
   } catch (err) {
     callLogger.error('Runtime turn handling failed; using fallback response', {