@private.me/xdebug

Developer tools for debugging AI agent interactions.

Capture, trace, and analyze execution flow in AI agent systems. xDebug provides error explanation, performance profiling, event capture, and session debugging for systems built with the Private.Me SDK.

Install

npm install @private.me/xdebug

Quickstart (Recommended)

Legal: By using this package, you agree to the Terms of Service. See Privacy Policy.

Error Explainer:

import { explainError, formatExplanation } from '@private.me/xdebug';
import { call } from '@private.me/xbind';

const result = await call('stripe:charge', { amount: 100 });
if (!result.ok) {
  const explanation = explainError(result.error);
  console.log('Why:', explanation.why);
  console.log('Fix:', explanation.how.join('; '));
  console.log(formatExplanation(explanation));
}

Performance Profiler:

import { Profiler } from '@private.me/xdebug';
const profiler = new Profiler();

profiler.start('auth');
await new Promise(r => setTimeout(r, 10)); // simulate work
profiler.end('auth');

const report = profiler.getReport();
report.measurements.forEach(m => {
  console.log(`${m.label}: mean=${m.mean.toFixed(1)}ms p95=${m.p95.toFixed(1)}ms`);
});

Session Debugger:

import { Debugger } from '@private.me/xdebug';
const dbg = new Debugger({ enabled: true, minLevel: 'debug' });

dbg.startSession({
  sessionId: 'sess_123', agentId: 'agent_456',
  environment: 'production', sdkVersion: '1.0.0',
  platform: { os: 'linux', arch: 'x64', runtime: 'node' },
});

dbg.info('auth', 'Login successful', { userId: '123' });
dbg.error('network', 'Timeout', new Error('ETIMEDOUT'));
const errors = dbg.getEvents({ level: 'error' });
const json = dbg.export({ format: 'json' });
dbg.endSession();
dbg.destroy();

CLI Usage

xdebug dev              # Watch current directory
xdebug dev --path ./src # Watch specific directory
xdebug dev --verbose    # Enable verbose logging

Why xDebug?

1. Error Explainer — Convert AgentCallError codes into actionable fixes
2. Performance Profiler — start/end timers, auto-measure, p50/p95/p99 percentiles
3. Session Debugger — Capture events, filter by level/category/time, export to JSON/JSONL/CSV/HTML

API Reference

explainError(error) / formatExplanation(explanation)

Convert AgentCallError into structured error explanation with why, how, examples, docs fields.

Debugger

| Method | Description | | --- | --- | | startSession(context) | Begin debug session | | endSession(status?) | End current session | | info/warn/error/fatal(category, message, ...) | Log events at level | | getEvents(filter?) | Filter by level, category, time range | | export({ format }) | Export as json, jsonl, csv, or html | | clear() / destroy() | Clear events / clean up |

Profiler

| Method | Description | | --- | --- | | start(label) / end(label) | Manual timer | | measure(label, fn) | Auto-measure async function | | getReport() | Stats with mean, min, max, p50, p95, p99 | | isActive(label) / getCount(label) | Timer status |

DevWatcher

| Method | Description | | --- | --- | | start(options?) / stop() | File watching lifecycle | | getMetrics() | Call count, error rate, latency |

Error Structure

All errors use structured error format with actionable messages:

interface ErrorExplanation {
  what: string;          // What happened (plain English)
  why: string;           // Root cause analysis
  how: string[];         // Actionable fix steps
  examples: CodeExample[]; // Code examples showing the fix
  docs: string[];        // Related documentation links
  code: string;          // Error code for reference
}

interface CodeExample {
  title: string;     // Example title
  code: string;      // Code snippet
  language: 'typescript' | 'javascript' | 'json';
}

Troubleshooting

"Timer already running" — Call profiler.isActive(label) before start().

High memory — Set maxEvents or periodically call dbg.export() then dbg.clear().

Network Activity

xDebug performs no network activity. All data is stored locally in memory. The purchase endpoint below is optional (Pro tier upgrade only). No telemetry, no phone-home, no data collection.

Security & Privacy

• Export sanitizes events by default (includeContext: false)
• All storage is local/in-memory, never transmitted
• Event IDs use crypto.getRandomValues() (no Math.random())

Dependencies

• @private.me/shared — Result type and error primitives
• @private.me/xbind — AgentCallError types for error explainer
• chokidar — File watching (CLI only)
• commander — CLI argument parsing

Platform: Node.js 18+ with Web Crypto API

Pricing

| Tier | Operations | Price | | --- | --- | --- | | Free Tier | 100 million operations per month free | No credit card required | | Pro Tier | Unlimited operations | Priority support |

To upgrade: visit private.me/subscribe?product=xdebug or use the API: curl -X POST https://private.me/aci/purchase -d '{"product":"xdebug","tier":"pro"}'

For full pricing details, see pricing-reference.md or visit private.me/pricing.

Support

• Documentation: https://private.me/docs/xdebug
• Issues: [email protected]

License

PROPRIETARY - Standard Clouds, Inc. dba PRIVATE.ME