@lelemondev/sdk 0.7.0 → 0.8.0

package/dist/hono.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/core/config.ts","../src/integrations/hono.ts"],"names":[],"mappings":";;AA2FA,eAAsB,KAAA,GAAuB;AAI7C;;;ACZO,SAAS,gBAAA,GAAmC;AACjD,EAAA,OAAO,OAAO,GAAG,IAAA,KAAS;AACxB,IAAA,MAAM,IAAA,EAAK;AAGX,IAAA,IAAI,CAAA,CAAE,cAAc,SAAA,EAAW;AAC7B,MAAA,CAAA,CAAE,YAAA,CAAa,SAAA,CAAU,KAAA,EAAO,CAAA;AAAA,IAClC,CAAA,MAAO;AAEL,MAAA,KAAA,EAAM,CAAE,MAAM,MAAM;AAAA,MAAC,CAAC,CAAA;AAAA,IACxB;AAAA,EACF,CAAA;AACF","file":"hono.mjs","sourcesContent":["/**\n * Global Configuration\n *\n * Manages SDK configuration and transport instance.\n */\n\nimport type { LelemonConfig } from './types';\nimport { Transport } from './transport';\nimport { setDebug, info, warn, debug } from './logger';\n\n// ─────────────────────────────────────────────────────────────\n// Global State\n// ─────────────────────────────────────────────────────────────\n\nlet globalConfig: LelemonConfig = {};\nlet globalTransport: Transport | null = null;\nlet initialized = false;\n\n// ─────────────────────────────────────────────────────────────\n// Configuration\n// ─────────────────────────────────────────────────────────────\n\nconst DEFAULT_ENDPOINT = 'https://www.lelemon.dev';\n\n/**\n * Initialize the SDK\n * Call once at app startup\n */\nexport function init(config: LelemonConfig = {}): void {\n  globalConfig = config;\n\n  // Configure debug mode\n  if (config.debug) {\n    setDebug(true);\n  }\n\n  info('Initializing SDK', {\n    endpoint: config.endpoint ?? DEFAULT_ENDPOINT,\n    debug: config.debug ?? false,\n    disabled: config.disabled ?? false,\n  });\n\n  globalTransport = createTransport(config);\n  initialized = true;\n\n  // Log status after transport is created\n  if (globalTransport.isEnabled()) {\n    info('SDK initialized - tracing enabled');\n  } else {\n    debug('SDK initialized - tracing disabled (no API key or explicitly disabled)');\n  }\n}\n\n/**\n * Get current config\n */\nexport function getConfig(): LelemonConfig {\n  return globalConfig;\n}\n\n/**\n * Check if SDK is initialized\n */\nexport function isInitialized(): boolean {\n  return initialized;\n}\n\n/**\n * Check if SDK is enabled\n */\nexport function isEnabled(): boolean {\n  return getTransport().isEnabled();\n}\n\n// ─────────────────────────────────────────────────────────────\n// Transport\n// ─────────────────────────────────────────────────────────────\n\n/**\n * Get or create transport instance\n */\nexport function getTransport(): Transport {\n  if (!globalTransport) {\n    globalTransport = createTransport(globalConfig);\n  }\n  return globalTransport;\n}\n\n/**\n * Flush all pending traces\n */\nexport async function flush(): Promise<void> {\n  if (globalTransport) {\n    await globalTransport.flush();\n  }\n}\n\n/**\n * Create transport instance\n */\nfunction createTransport(config: LelemonConfig): Transport {\n  const apiKey = config.apiKey ?? getEnvVar('LELEMON_API_KEY');\n\n  if (!apiKey && !config.disabled) {\n    warn('No API key provided. Set apiKey in init() or LELEMON_API_KEY env var. Tracing disabled.');\n  }\n\n  return new Transport({\n    apiKey: apiKey ?? '',\n    endpoint: config.endpoint ?? DEFAULT_ENDPOINT,\n    debug: config.debug ?? false,\n    disabled: config.disabled ?? !apiKey,\n    batchSize: config.batchSize,\n    flushIntervalMs: config.flushIntervalMs,\n    requestTimeoutMs: config.requestTimeoutMs,\n  });\n}\n\n/**\n * Get environment variable (works in Node and edge)\n */\nfunction getEnvVar(name: string): string | undefined {\n  if (typeof process !== 'undefined' && process.env) {\n    return process.env[name];\n  }\n  return undefined;\n}\n","/**\n * Hono Integration\n *\n * Middleware for Hono framework (Cloudflare Workers, Deno, Bun, Node.js).\n * Uses executionCtx.waitUntil() when available for non-blocking flush.\n *\n * @example\n * import { Hono } from 'hono';\n * import { createMiddleware } from '@lelemondev/sdk/hono';\n *\n * const app = new Hono();\n * app.use(createMiddleware());\n */\n\nimport { flush } from '../core/config';\n\n// ─────────────────────────────────────────────────────────────\n// Types (minimal to avoid requiring hono as dependency)\n// ─────────────────────────────────────────────────────────────\n\n/**\n * Execution context for edge runtimes (Cloudflare Workers, Deno Deploy)\n */\nexport interface ExecutionContext {\n  waitUntil(promise: Promise<unknown>): void;\n  passThroughOnException(): void;\n}\n\n/**\n * Minimal Hono context type (avoids requiring hono as dependency)\n */\nexport interface HonoContext {\n  req: {\n    raw: Request;\n    [key: string]: unknown;\n  };\n  res: Response | undefined;\n  executionCtx?: ExecutionContext;\n  [key: string]: unknown;\n}\n\n/**\n * Hono next function type\n */\nexport type HonoNextFunction = () => Promise<void>;\n\n/**\n * Hono middleware function type\n *\n * @param c - Hono context object\n * @param next - Next function to continue middleware chain\n */\nexport type HonoMiddleware = (c: HonoContext, next: HonoNextFunction) => Promise<void>;\n\n// ─────────────────────────────────────────────────────────────\n// Middleware\n// ─────────────────────────────────────────────────────────────\n\n/**\n * Create Hono middleware for automatic trace flushing\n *\n * On Cloudflare Workers/Deno Deploy: uses executionCtx.waitUntil() for non-blocking flush\n * On Node.js/Bun: flushes after response (fire-and-forget)\n *\n * @returns Hono middleware function\n *\n * @example\n * import { Hono } from 'hono';\n * import { createMiddleware } from '@lelemondev/sdk/hono';\n *\n * const app = new Hono();\n *\n * // Global middleware\n * app.use(createMiddleware());\n *\n * app.post('/chat', async (c) => {\n *   const openai = observe(new OpenAI());\n *   const result = await openai.chat.completions.create({...});\n *   return c.json(result);\n * });\n *\n * export default app;\n */\nexport function createMiddleware(): HonoMiddleware {\n  return async (c, next) => {\n    await next();\n\n    // Use waitUntil if available (Cloudflare Workers, Deno Deploy)\n    if (c.executionCtx?.waitUntil) {\n      c.executionCtx.waitUntil(flush());\n    } else {\n      // Fire-and-forget for Node.js/Bun\n      flush().catch(() => {});\n    }\n  };\n}\n"]}
+{"version":3,"sources":["../src/core/config.ts","../src/integrations/hono.ts"],"names":["flush","createMiddleware","c","next"],"mappings":";AA2FA,eAAsBA,CAAAA,EAAuB,CAI7C,CCZO,SAASC,CAAAA,EAAmC,CACjD,OAAO,MAAOC,EAAGC,CAAAA,GAAS,CACxB,MAAMA,CAAAA,GAGFD,CAAAA,CAAE,YAAA,EAAc,SAAA,CAClBA,CAAAA,CAAE,aAAa,SAAA,CAAUF,CAAAA,EAAO,CAAA,CAGhCA,GAAM,CAAE,KAAA,CAAM,IAAM,CAAC,CAAC,EAE1B,CACF","file":"hono.mjs","sourcesContent":["/**\n * Global Configuration\n *\n * Manages SDK configuration and transport instance.\n */\n\nimport type { LelemonConfig } from './types';\nimport { Transport } from './transport';\nimport { setDebug, info, warn, debug } from './logger';\n\n// ─────────────────────────────────────────────────────────────\n// Global State\n// ─────────────────────────────────────────────────────────────\n\nlet globalConfig: LelemonConfig = {};\nlet globalTransport: Transport | null = null;\nlet initialized = false;\n\n// ─────────────────────────────────────────────────────────────\n// Configuration\n// ─────────────────────────────────────────────────────────────\n\nconst DEFAULT_ENDPOINT = 'https://www.lelemon.dev';\n\n/**\n * Initialize the SDK\n * Call once at app startup\n */\nexport function init(config: LelemonConfig = {}): void {\n  globalConfig = config;\n\n  // Configure debug mode\n  if (config.debug) {\n    setDebug(true);\n  }\n\n  info('Initializing SDK', {\n    endpoint: config.endpoint ?? DEFAULT_ENDPOINT,\n    debug: config.debug ?? false,\n    disabled: config.disabled ?? false,\n  });\n\n  globalTransport = createTransport(config);\n  initialized = true;\n\n  // Log status after transport is created\n  if (globalTransport.isEnabled()) {\n    info('SDK initialized - tracing enabled');\n  } else {\n    debug('SDK initialized - tracing disabled (no API key or explicitly disabled)');\n  }\n}\n\n/**\n * Get current config\n */\nexport function getConfig(): LelemonConfig {\n  return globalConfig;\n}\n\n/**\n * Check if SDK is initialized\n */\nexport function isInitialized(): boolean {\n  return initialized;\n}\n\n/**\n * Check if SDK is enabled\n */\nexport function isEnabled(): boolean {\n  return getTransport().isEnabled();\n}\n\n// ─────────────────────────────────────────────────────────────\n// Transport\n// ─────────────────────────────────────────────────────────────\n\n/**\n * Get or create transport instance\n */\nexport function getTransport(): Transport {\n  if (!globalTransport) {\n    globalTransport = createTransport(globalConfig);\n  }\n  return globalTransport;\n}\n\n/**\n * Flush all pending traces\n */\nexport async function flush(): Promise<void> {\n  if (globalTransport) {\n    await globalTransport.flush();\n  }\n}\n\n/**\n * Create transport instance\n */\nfunction createTransport(config: LelemonConfig): Transport {\n  const apiKey = config.apiKey ?? getEnvVar('LELEMON_API_KEY');\n\n  if (!apiKey && !config.disabled) {\n    warn('No API key provided. Set apiKey in init() or LELEMON_API_KEY env var. Tracing disabled.');\n  }\n\n  return new Transport({\n    apiKey: apiKey ?? '',\n    endpoint: config.endpoint ?? DEFAULT_ENDPOINT,\n    debug: config.debug ?? false,\n    disabled: config.disabled ?? !apiKey,\n    batchSize: config.batchSize,\n    flushIntervalMs: config.flushIntervalMs,\n    requestTimeoutMs: config.requestTimeoutMs,\n  });\n}\n\n/**\n * Get environment variable (works in Node and edge)\n */\nfunction getEnvVar(name: string): string | undefined {\n  if (typeof process !== 'undefined' && process.env) {\n    return process.env[name];\n  }\n  return undefined;\n}\n","/**\n * Hono Integration\n *\n * Middleware for Hono framework (Cloudflare Workers, Deno, Bun, Node.js).\n * Uses executionCtx.waitUntil() when available for non-blocking flush.\n *\n * @example\n * import { Hono } from 'hono';\n * import { createMiddleware } from '@lelemondev/sdk/hono';\n *\n * const app = new Hono();\n * app.use(createMiddleware());\n */\n\nimport { flush } from '../core/config';\n\n// ─────────────────────────────────────────────────────────────\n// Types (minimal to avoid requiring hono as dependency)\n// ─────────────────────────────────────────────────────────────\n\n/**\n * Execution context for edge runtimes (Cloudflare Workers, Deno Deploy)\n */\nexport interface ExecutionContext {\n  waitUntil(promise: Promise<unknown>): void;\n  passThroughOnException(): void;\n}\n\n/**\n * Minimal Hono context type (avoids requiring hono as dependency)\n */\nexport interface HonoContext {\n  req: {\n    raw: Request;\n    [key: string]: unknown;\n  };\n  res: Response | undefined;\n  executionCtx?: ExecutionContext;\n  [key: string]: unknown;\n}\n\n/**\n * Hono next function type\n */\nexport type HonoNextFunction = () => Promise<void>;\n\n/**\n * Hono middleware function type\n *\n * @param c - Hono context object\n * @param next - Next function to continue middleware chain\n */\nexport type HonoMiddleware = (c: HonoContext, next: HonoNextFunction) => Promise<void>;\n\n// ─────────────────────────────────────────────────────────────\n// Middleware\n// ─────────────────────────────────────────────────────────────\n\n/**\n * Create Hono middleware for automatic trace flushing\n *\n * On Cloudflare Workers/Deno Deploy: uses executionCtx.waitUntil() for non-blocking flush\n * On Node.js/Bun: flushes after response (fire-and-forget)\n *\n * @returns Hono middleware function\n *\n * @example\n * import { Hono } from 'hono';\n * import { createMiddleware } from '@lelemondev/sdk/hono';\n *\n * const app = new Hono();\n *\n * // Global middleware\n * app.use(createMiddleware());\n *\n * app.post('/chat', async (c) => {\n *   const openai = observe(new OpenAI());\n *   const result = await openai.chat.completions.create({...});\n *   return c.json(result);\n * });\n *\n * export default app;\n */\nexport function createMiddleware(): HonoMiddleware {\n  return async (c, next) => {\n    await next();\n\n    // Use waitUntil if available (Cloudflare Workers, Deno Deploy)\n    if (c.executionCtx?.waitUntil) {\n      c.executionCtx.waitUntil(flush());\n    } else {\n      // Fire-and-forget for Node.js/Bun\n      flush().catch(() => {});\n    }\n  };\n}\n"]}

package/dist/index.d.mts

@@ -17,7 +17,7 @@ interface LelemonConfig {
     /** Request timeout in ms (default: 10000) */
     requestTimeoutMs?: number;
 }
-type ProviderName = 'openai' | 'anthropic' | 'gemini' | 'bedrock' | 'openrouter' | 'unknown';
+type ProviderName = 'openai' | 'anthropic' | 'gemini' | 'bedrock' | 'openrouter' | 'agent' | 'unknown';
 interface ObserveOptions {
     /** Session ID to group related calls */
     sessionId?: string;
@@ -28,7 +28,7 @@ interface ObserveOptions {
     /** Tags for filtering */
     tags?: string[];
 }
-type SpanType = 'llm' | 'tool' | 'retrieval' | 'custom';
+type SpanType = 'llm' | 'agent' | 'tool' | 'retrieval' | 'embedding' | 'guardrail' | 'rerank' | 'custom';
 interface CaptureSpanOptions {
     /** Span type */
     type: SpanType;
@@ -71,40 +71,132 @@ declare function isEnabled(): boolean;
 declare function flush(): Promise<void>;
 
 /**
- * Observe Function
+ * Trace Context Module
  *
- * Main entry point for wrapping LLM clients with automatic tracing.
- */
-
-/**
- * Wrap an LLM client with automatic tracing
- *
- * @param client - OpenAI, Anthropic, or Bedrock client instance
- * @param options - Optional context (sessionId, userId, etc.)
- * @returns The wrapped client with the same type
+ * Provides AsyncLocalStorage-based context for grouping spans under a parent trace.
+ * Supports hierarchical tracing where:
+ * - trace() creates a root "agent" span
+ * - LLM calls become children of the root
+ * - Tool calls become children of the LLM that triggered them (via toolCallId linking)
  *
  * @example
- * import { observe } from '@lelemondev/sdk';
- * import OpenAI from 'openai';
+ * ```typescript
+ * import { trace, span } from '@lelemondev/sdk';
+ *
+ * await trace({ name: 'sales-agent', input: userMessage }, async () => {
+ *   const response = await client.send(new ConverseCommand({...}));
+ *   // Tools automatically linked to their parent LLM via toolCallId
+ *   return response;
+ * });
+ * ```
+ */
+interface TraceContext {
+    /** Unique trace ID (shared by all spans in this trace) */
+    traceId: string;
+    /** Root span ID (the agent/workflow span) */
+    rootSpanId: string;
+    /** Current span ID (for nesting - LLM calls become children of this) */
+    currentSpanId: string;
+    /** Parent span ID (for nested trace() calls) */
+    parentSpanId?: string;
+    /** Trace name */
+    name: string;
+    /** Start time in ms */
+    startTime: number;
+    /** Input data */
+    input?: unknown;
+    /** Trace metadata */
+    metadata?: Record<string, unknown>;
+    /** Trace tags */
+    tags?: string[];
+    /** Map of toolCallId → llmSpanId for linking tool spans to their parent LLM */
+    pendingToolCalls: Map<string, string>;
+}
+interface TraceOptions {
+    /** Name for the trace (e.g., 'sales-agent', 'rag-query') */
+    name: string;
+    /** Input data for the trace */
+    input?: unknown;
+    /** Custom metadata */
+    metadata?: Record<string, unknown>;
+    /** Tags for filtering */
+    tags?: string[];
+}
+interface SpanOptions {
+    /** Span type */
+    type: 'retrieval' | 'embedding' | 'tool' | 'guardrail' | 'rerank' | 'custom';
+    /** Span name (e.g., 'pinecone-search', 'cohere-rerank') */
+    name: string;
+    /** Input data */
+    input?: unknown;
+    /** Output data */
+    output?: unknown;
+    /** Duration in milliseconds (optional, will be set automatically if not provided) */
+    durationMs?: number;
+    /** Status */
+    status?: 'success' | 'error';
+    /** Error message if status is 'error' */
+    errorMessage?: string;
+    /** Tool call ID (links this tool span to the LLM that requested it) */
+    toolCallId?: string;
+    /** Custom metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Get the current trace context, if any
+ */
+declare function getTraceContext(): TraceContext | undefined;
+/**
+ * Execute a function within a trace context.
+ * Creates a root "agent" span that contains all LLM calls and tool executions.
+ * The result of the function becomes the output of the root span.
  *
- * const openai = observe(new OpenAI());
+ * @example Simple usage (just name)
+ * ```typescript
+ * await trace('sales-agent', async () => {
+ *   await client.send(new ConverseCommand({...}));
+ *   return finalResponse;
+ * });
+ * ```
  *
- * // All calls are now automatically traced
- * const response = await openai.chat.completions.create({...});
+ * @example With options
+ * ```typescript
+ * await trace({ name: 'rag-query', input: question, tags: ['production'] }, async () => {
+ *   const docs = await search(question);
+ *   span({ type: 'retrieval', name: 'pinecone', output: { count: docs.length } });
+ *   return client.send(new ConverseCommand({...}));
+ * });
+ * ```
  */
-declare function observe<T>(client: T, options?: ObserveOptions): T;
+declare function trace<T>(nameOrOptions: string | TraceOptions, fn: () => Promise<T>): Promise<T>;
 /**
- * Create a scoped observe function with preset context
+ * Manually capture a span for non-LLM operations (retrieval, embedding, tool, etc.)
+ * Must be called within a trace() block.
  *
- * @example
- * const observeWithSession = createObserve({
- *   sessionId: 'session-123',
- *   userId: 'user-456',
+ * @example Tool with toolCallId (links to parent LLM)
+ * ```typescript
+ * span({
+ *   type: 'tool',
+ *   name: 'query_database',
+ *   toolCallId: 'tooluse_abc123',  // Links to LLM that requested this
+ *   input: { sql: 'SELECT ...' },
+ *   output: { rows: [...] },
+ *   durationMs: 15,
  * });
+ * ```
  *
- * const openai = observeWithSession(new OpenAI());
+ * @example Retrieval without toolCallId
+ * ```typescript
+ * span({
+ *   type: 'retrieval',
+ *   name: 'pinecone-search',
+ *   input: { topK: 5 },
+ *   output: { count: 10 },
+ *   durationMs: 50,
+ * });
+ * ```
  */
-declare function createObserve(defaultOptions: ObserveOptions): <T>(client: T, options?: ObserveOptions) => T;
+declare function span(options: SpanOptions): void;
 
 /**
  * Capture Module
@@ -139,4 +231,4 @@ declare function createObserve(defaultOptions: ObserveOptions): <T>(client: T, o
  */
 declare function captureSpan(options: CaptureSpanOptions): void;
 
-export { type CaptureSpanOptions, type LelemonConfig, type ObserveOptions, type ProviderName, type SpanType, captureSpan, createObserve, flush, init, isEnabled, observe };
+export { type CaptureSpanOptions, type LelemonConfig, type ObserveOptions, type ProviderName, type SpanOptions, type SpanType, type TraceContext, type TraceOptions, captureSpan, flush, getTraceContext, init, isEnabled, span, trace };

package/dist/index.d.ts

@@ -17,7 +17,7 @@ interface LelemonConfig {
     /** Request timeout in ms (default: 10000) */
     requestTimeoutMs?: number;
 }
-type ProviderName = 'openai' | 'anthropic' | 'gemini' | 'bedrock' | 'openrouter' | 'unknown';
+type ProviderName = 'openai' | 'anthropic' | 'gemini' | 'bedrock' | 'openrouter' | 'agent' | 'unknown';
 interface ObserveOptions {
     /** Session ID to group related calls */
     sessionId?: string;
@@ -28,7 +28,7 @@ interface ObserveOptions {
     /** Tags for filtering */
     tags?: string[];
 }
-type SpanType = 'llm' | 'tool' | 'retrieval' | 'custom';
+type SpanType = 'llm' | 'agent' | 'tool' | 'retrieval' | 'embedding' | 'guardrail' | 'rerank' | 'custom';
 interface CaptureSpanOptions {
     /** Span type */
     type: SpanType;
@@ -71,40 +71,132 @@ declare function isEnabled(): boolean;
 declare function flush(): Promise<void>;
 
 /**
- * Observe Function
+ * Trace Context Module
  *
- * Main entry point for wrapping LLM clients with automatic tracing.
- */
-
-/**
- * Wrap an LLM client with automatic tracing
- *
- * @param client - OpenAI, Anthropic, or Bedrock client instance
- * @param options - Optional context (sessionId, userId, etc.)
- * @returns The wrapped client with the same type
+ * Provides AsyncLocalStorage-based context for grouping spans under a parent trace.
+ * Supports hierarchical tracing where:
+ * - trace() creates a root "agent" span
+ * - LLM calls become children of the root
+ * - Tool calls become children of the LLM that triggered them (via toolCallId linking)
  *
  * @example
- * import { observe } from '@lelemondev/sdk';
- * import OpenAI from 'openai';
+ * ```typescript
+ * import { trace, span } from '@lelemondev/sdk';
+ *
+ * await trace({ name: 'sales-agent', input: userMessage }, async () => {
+ *   const response = await client.send(new ConverseCommand({...}));
+ *   // Tools automatically linked to their parent LLM via toolCallId
+ *   return response;
+ * });
+ * ```
+ */
+interface TraceContext {
+    /** Unique trace ID (shared by all spans in this trace) */
+    traceId: string;
+    /** Root span ID (the agent/workflow span) */
+    rootSpanId: string;
+    /** Current span ID (for nesting - LLM calls become children of this) */
+    currentSpanId: string;
+    /** Parent span ID (for nested trace() calls) */
+    parentSpanId?: string;
+    /** Trace name */
+    name: string;
+    /** Start time in ms */
+    startTime: number;
+    /** Input data */
+    input?: unknown;
+    /** Trace metadata */
+    metadata?: Record<string, unknown>;
+    /** Trace tags */
+    tags?: string[];
+    /** Map of toolCallId → llmSpanId for linking tool spans to their parent LLM */
+    pendingToolCalls: Map<string, string>;
+}
+interface TraceOptions {
+    /** Name for the trace (e.g., 'sales-agent', 'rag-query') */
+    name: string;
+    /** Input data for the trace */
+    input?: unknown;
+    /** Custom metadata */
+    metadata?: Record<string, unknown>;
+    /** Tags for filtering */
+    tags?: string[];
+}
+interface SpanOptions {
+    /** Span type */
+    type: 'retrieval' | 'embedding' | 'tool' | 'guardrail' | 'rerank' | 'custom';
+    /** Span name (e.g., 'pinecone-search', 'cohere-rerank') */
+    name: string;
+    /** Input data */
+    input?: unknown;
+    /** Output data */
+    output?: unknown;
+    /** Duration in milliseconds (optional, will be set automatically if not provided) */
+    durationMs?: number;
+    /** Status */
+    status?: 'success' | 'error';
+    /** Error message if status is 'error' */
+    errorMessage?: string;
+    /** Tool call ID (links this tool span to the LLM that requested it) */
+    toolCallId?: string;
+    /** Custom metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Get the current trace context, if any
+ */
+declare function getTraceContext(): TraceContext | undefined;
+/**
+ * Execute a function within a trace context.
+ * Creates a root "agent" span that contains all LLM calls and tool executions.
+ * The result of the function becomes the output of the root span.
  *
- * const openai = observe(new OpenAI());
+ * @example Simple usage (just name)
+ * ```typescript
+ * await trace('sales-agent', async () => {
+ *   await client.send(new ConverseCommand({...}));
+ *   return finalResponse;
+ * });
+ * ```
  *
- * // All calls are now automatically traced
- * const response = await openai.chat.completions.create({...});
+ * @example With options
+ * ```typescript
+ * await trace({ name: 'rag-query', input: question, tags: ['production'] }, async () => {
+ *   const docs = await search(question);
+ *   span({ type: 'retrieval', name: 'pinecone', output: { count: docs.length } });
+ *   return client.send(new ConverseCommand({...}));
+ * });
+ * ```
  */
-declare function observe<T>(client: T, options?: ObserveOptions): T;
+declare function trace<T>(nameOrOptions: string | TraceOptions, fn: () => Promise<T>): Promise<T>;
 /**
- * Create a scoped observe function with preset context
+ * Manually capture a span for non-LLM operations (retrieval, embedding, tool, etc.)
+ * Must be called within a trace() block.
  *
- * @example
- * const observeWithSession = createObserve({
- *   sessionId: 'session-123',
- *   userId: 'user-456',
+ * @example Tool with toolCallId (links to parent LLM)
+ * ```typescript
+ * span({
+ *   type: 'tool',
+ *   name: 'query_database',
+ *   toolCallId: 'tooluse_abc123',  // Links to LLM that requested this
+ *   input: { sql: 'SELECT ...' },
+ *   output: { rows: [...] },
+ *   durationMs: 15,
  * });
+ * ```
  *
- * const openai = observeWithSession(new OpenAI());
+ * @example Retrieval without toolCallId
+ * ```typescript
+ * span({
+ *   type: 'retrieval',
+ *   name: 'pinecone-search',
+ *   input: { topK: 5 },
+ *   output: { count: 10 },
+ *   durationMs: 50,
+ * });
+ * ```
  */
-declare function createObserve(defaultOptions: ObserveOptions): <T>(client: T, options?: ObserveOptions) => T;
+declare function span(options: SpanOptions): void;
 
 /**
  * Capture Module
@@ -139,4 +231,4 @@ declare function createObserve(defaultOptions: ObserveOptions): <T>(client: T, o
  */
 declare function captureSpan(options: CaptureSpanOptions): void;
 
-export { type CaptureSpanOptions, type LelemonConfig, type ObserveOptions, type ProviderName, type SpanType, captureSpan, createObserve, flush, init, isEnabled, observe };
+export { type CaptureSpanOptions, type LelemonConfig, type ObserveOptions, type ProviderName, type SpanOptions, type SpanType, type TraceContext, type TraceOptions, captureSpan, flush, getTraceContext, init, isEnabled, span, trace };