@compilr-dev/agents 0.3.13 → 0.3.15

package/dist/guardrails/shell-parser.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Shell command tokenizer for guardrail compound command parsing
+ *
+ * Splits compound shell commands (cmd1 | cmd2 && cmd3) into individual
+ * subcommands so each can be validated independently against guardrails.
+ */
+/**
+ * A parsed subcommand from a compound shell command
+ */
+export interface ShellToken {
+    /** Trimmed subcommand text */
+    command: string;
+    /** Operator that preceded this token (undefined for the first) */
+    operator?: '|' | '&&' | '||' | ';';
+    /** 0-based position in the command sequence */
+    index: number;
+}
+/**
+ * Parse a compound shell command into individual subcommands.
+ *
+ * Handles pipes, logical operators (&&, ||), semicolons, and respects
+ * single-quoted, double-quoted, and backtick-quoted strings.
+ *
+ * @param input - The full command string
+ * @returns Array of parsed subcommand tokens
+ *
+ * @example
+ * ```typescript
+ * parseShellCommand('ls && rm -rf /tmp')
+ * // => [
+ * //   { command: 'ls', index: 0 },
+ * //   { command: 'rm -rf /tmp', operator: '&&', index: 1 }
+ * // ]
+ * ```
+ */
+export declare function parseShellCommand(input: string): ShellToken[];

package/dist/guardrails/shell-parser.js

@@ -0,0 +1,103 @@
+/**
+ * Shell command tokenizer for guardrail compound command parsing
+ *
+ * Splits compound shell commands (cmd1 | cmd2 && cmd3) into individual
+ * subcommands so each can be validated independently against guardrails.
+ */
+/**
+ * Parse a compound shell command into individual subcommands.
+ *
+ * Handles pipes, logical operators (&&, ||), semicolons, and respects
+ * single-quoted, double-quoted, and backtick-quoted strings.
+ *
+ * @param input - The full command string
+ * @returns Array of parsed subcommand tokens
+ *
+ * @example
+ * ```typescript
+ * parseShellCommand('ls && rm -rf /tmp')
+ * // => [
+ * //   { command: 'ls', index: 0 },
+ * //   { command: 'rm -rf /tmp', operator: '&&', index: 1 }
+ * // ]
+ * ```
+ */
+export function parseShellCommand(input) {
+    const tokens = [];
+    let current = '';
+    let quote = null;
+    let i = 0;
+    let operator;
+    while (i < input.length) {
+        const ch = input[i];
+        // Handle escape sequences inside double quotes
+        if (ch === '\\' && quote === '"' && i + 1 < input.length) {
+            current += ch + input[i + 1];
+            i += 2;
+            continue;
+        }
+        // Toggle quote state
+        if ((ch === "'" || ch === '"' || ch === '`') && (quote === null || quote === ch)) {
+            quote = quote === ch ? null : ch;
+            current += ch;
+            i++;
+            continue;
+        }
+        // Only split when outside quotes
+        if (quote === null) {
+            // && operator
+            if (ch === '&' && input[i + 1] === '&') {
+                pushToken(tokens, current, operator);
+                operator = '&&';
+                current = '';
+                i += 2;
+                continue;
+            }
+            // || operator (must check before single |)
+            if (ch === '|' && input[i + 1] === '|') {
+                pushToken(tokens, current, operator);
+                operator = '||';
+                current = '';
+                i += 2;
+                continue;
+            }
+            // | pipe (single)
+            if (ch === '|') {
+                pushToken(tokens, current, operator);
+                operator = '|';
+                current = '';
+                i++;
+                continue;
+            }
+            // ; semicolon
+            if (ch === ';') {
+                pushToken(tokens, current, operator);
+                operator = ';';
+                current = '';
+                i++;
+                continue;
+            }
+        }
+        current += ch;
+        i++;
+    }
+    // Push final segment
+    pushToken(tokens, current, operator);
+    return tokens;
+}
+/**
+ * Push a trimmed, non-empty token onto the array
+ */
+function pushToken(tokens, command, operator) {
+    const trimmed = command.trim();
+    if (trimmed.length === 0)
+        return;
+    const token = {
+        command: trimmed,
+        index: tokens.length,
+    };
+    if (operator !== undefined) {
+        token.operator = operator;
+    }
+    tokens.push(token);
+}

package/dist/guardrails/types.d.ts

@@ -94,6 +94,14 @@ export interface GuardrailResult {
      * The input that triggered the guardrail
      */
     input?: unknown;
+    /**
+     * The specific subcommand that triggered (compound commands only)
+     */
+    subcommand?: string;
+    /**
+     * 0-based index of the subcommand in the compound command
+     */
+    subcommandIndex?: number;
 }
 /**
  * Context passed to guardrail handlers

package/dist/index.d.ts

@@ -60,9 +60,11 @@ export type { TokenUsage, UsageRecord, UsageStats, TokenBudgetConfig, BudgetStat
 export { HooksManager } from './hooks/index.js';
 export type { HooksManagerOptions } from './hooks/index.js';
 export type { HooksConfig, HookRegistrationOptions, HookContext, IterationHookContext, LLMHookContext, AfterLLMHookContext, ToolHookContext, AfterToolHookContext, ErrorHookContext, BeforeIterationHook, AfterIterationHook, BeforeLLMHook, AfterLLMHook, BeforeToolHook, AfterToolHook, OnErrorHook, BeforeLLMHookResult, BeforeToolHookResult, AfterToolHookResult, ErrorHookResult, RegisteredHook, HookEventType, HookEvent, HookEventHandler, } from './hooks/index.js';
-export { TracingManager, createTracingHooks, createLoggingHooks, mergeHooks, createStructuredLogger, createNoopLogger, createBufferedLogger, createTracingLogger, formatDuration, formatBytes, redactSensitive, createOTelExporter, createConsoleExporter, createBatchExporter, createMultiExporter, OTelNotInstalledError, isOTelNotInstalledError, SemanticAttributes, } from './tracing/index.js';
-export type { Span, SpanStatus, SpanKind, SpanAttributes, SpanContext, SpanEvent, AttributeValue, Trace, TracingManagerOptions, StartSpanOptions, EndSpanOptions, TracingHooksConfig, TracingEvent, TracingEventHandler, OTelExporter, OTelSDK, OTelTracer, OTelSpan, LogLevel, LogEntry, StructuredLogger, StructuredLoggerOptions, TracingHookContext, TracingManagerInterface, } from './tracing/index.js';
+export { TracingManager, createTracingHooks, createLoggingHooks, mergeHooks, createStructuredLogger, createNoopLogger, createBufferedLogger, createTracingLogger, formatDuration, formatBytes, redactSensitive, createOTelExporter, createConsoleExporter, createBatchExporter, createMultiExporter, OTelNotInstalledError, isOTelNotInstalledError, createOTelHooks, GenAIAttributes, AgentAttributes, PROVIDER_TO_SYSTEM, SemanticAttributes, } from './tracing/index.js';
+export type { Span, SpanStatus, SpanKind, SpanAttributes, SpanContext, SpanEvent, AttributeValue, Trace, TracingManagerOptions, StartSpanOptions, EndSpanOptions, TracingHooksConfig, TracingEvent, TracingEventHandler, OTelExporter, OTelSDK, OTelTracer, OTelSpan, OTelHooksConfig, LogLevel, LogEntry, StructuredLogger, StructuredLoggerOptions, TracingHookContext, TracingManagerInterface, } from './tracing/index.js';
 export { TokenBucketRateLimiter, createRateLimiter, createNoopRateLimiter, RateLimitExceededError, isRateLimitExceededError, withRetry, createRetryWithRateLimit, RetryPresets, RetryStats, RateLimitedProvider, wrapWithRateLimit, ProviderRateLimits, } from './rate-limit/index.js';
 export type { RateLimiterConfig, RateLimiterStats, RetryConfig, RateLimitRetryConfig, AcquireResult, RateLimiter, } from './rate-limit/index.js';
 export { RehearsalManager, createRehearsalManager, GitRehearsalAnalyzer, createGitAnalyzer, FileRehearsalAnalyzer, createFileAnalyzer, } from './rehearsal/index.js';
 export type { ImpactSeverity, RehearsalRecommendation, OperationCategory, AffectedFile, RehearsalImpact, RehearsalResult, RehearsalContext, RehearsalAnalyzer, RehearsalManagerOptions, RehearsalEventType, RehearsalEvent, RehearsalEventHandler, } from './rehearsal/index.js';
+export { estimateEffort, DEFAULT_WEIGHTS, EFFORT_ORDER } from './episodes/index.js';
+export type { Effort, WorkEpisode, EffortSignals, EffortWeights, EffortSummary, ProjectWorkSummary, EpisodeStore, } from './episodes/index.js';

package/dist/index.js

@@ -83,8 +83,10 @@ TracingManager,
 createTracingHooks, createLoggingHooks, mergeHooks, 
 // Structured logging
 createStructuredLogger, createNoopLogger, createBufferedLogger, createTracingLogger, formatDuration, formatBytes, redactSensitive, 
-// OpenTelemetry integration
+// OpenTelemetry integration (post-hoc exporter)
 createOTelExporter, createConsoleExporter, createBatchExporter, createMultiExporter, OTelNotInstalledError, isOTelNotInstalledError, 
+// OpenTelemetry native hooks
+createOTelHooks, GenAIAttributes, AgentAttributes, PROVIDER_TO_SYSTEM, 
 // Semantic conventions
 SemanticAttributes, } from './tracing/index.js';
 // Rate Limiting & Retry
@@ -97,3 +99,5 @@ withRetry, createRetryWithRateLimit, RetryPresets, RetryStats,
 RateLimitedProvider, wrapWithRateLimit, ProviderRateLimits, } from './rate-limit/index.js';
 // Rehearsal - Impact analysis for destructive operations
 export { RehearsalManager, createRehearsalManager, GitRehearsalAnalyzer, createGitAnalyzer, FileRehearsalAnalyzer, createFileAnalyzer, } from './rehearsal/index.js';
+// Episodes - Work history tracking with effort estimation
+export { estimateEffort, DEFAULT_WEIGHTS, EFFORT_ORDER } from './episodes/index.js';

package/dist/mcp/client.js

@@ -20,15 +20,17 @@ async function getMCPSDK() {
         return sdkCache;
     try {
         // Dynamic imports to keep SDK optional
-        const [clientModule, stdioModule, httpModule] = await Promise.all([
+        const [clientModule, stdioModule, httpModule, typesModule] = await Promise.all([
             import('@modelcontextprotocol/sdk/client/index.js'),
             import('@modelcontextprotocol/sdk/client/stdio.js'),
             import('@modelcontextprotocol/sdk/client/streamableHttp.js'),
+            import('@modelcontextprotocol/sdk/types.js'),
         ]);
         sdkCache = {
             Client: clientModule.Client,
             StdioClientTransport: stdioModule.StdioClientTransport,
             StreamableHTTPClientTransport: httpModule.StreamableHTTPClientTransport,
+            ToolListChangedNotificationSchema: typesModule.ToolListChangedNotificationSchema,
         };
         // Non-null assertion safe: we just assigned sdkCache above
         return sdkCache;
@@ -112,6 +114,7 @@ export class MCPClient {
                     args: this.config.stdio.args,
                     env: this.config.stdio.env,
                     cwd: this.config.stdio.cwd,
+                    stderr: 'pipe', // Capture stderr to prevent bleeding into host terminal
                 });
             }
             else if (this.config.transport === 'http' && this.config.http) {
@@ -123,7 +126,8 @@ export class MCPClient {
                 version: this.config.clientVersion ?? '1.0.0',
             });
             // Set up notification handler for tools changed
-            this.client.setNotificationHandler('notifications/tools/list_changed', () => {
+            // SDK 1.26+ requires Zod schema instead of string for notification handlers
+            this.client.setNotificationHandler(sdk.ToolListChangedNotificationSchema, () => {
                 this.cachedTools = null; // Invalidate cache
                 this.emit({ type: 'tools_changed', serverName: this.name });
             });

package/dist/providers/gemini-native.js

@@ -199,9 +199,16 @@ export class GeminiNativeProvider {
                 case 'tool_result': {
                     // Convert to functionResponse
                     // block.content is a JSON string from the agent - parse it for the API
+                    // Gemini requires response to be a Struct (object), never a string
                     let responseData;
                     try {
-                        responseData = JSON.parse(block.content);
+                        const parsed = JSON.parse(block.content);
+                        // Ensure we always have an object — parse may return a string
+                        // (double-encoded JSON) or a primitive
+                        responseData =
+                            typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)
+                                ? parsed
+                                : { result: parsed };
                     }
                     catch {
                         // If not valid JSON, wrap the string in a result object

package/dist/tools/builtin/glob.js

@@ -33,6 +33,7 @@ const DEFAULT_EXCLUDE_DIRS = [
  */
 export const globTool = defineTool({
     name: 'glob',
+    readonly: true,
     description: 'Find files matching glob patterns. ' +
         'Supports common patterns like **/*.ts for recursive matching. ' +
         'Returns a list of matching file paths.',
@@ -222,6 +223,7 @@ function patternToRegex(pattern) {
 export function createGlobTool(options) {
     return defineTool({
         name: 'glob',
+        readonly: true,
         description: 'Find files matching glob patterns. ' +
             'Supports common patterns like **/*.ts for recursive matching. ' +
             'Returns a list of matching file paths.',

package/dist/tools/builtin/grep.js

@@ -34,6 +34,7 @@ const DEFAULT_EXCLUDE_DIRS = [
  */
 export const grepTool = defineTool({
     name: 'grep',
+    readonly: true,
     description: 'Search for patterns in files using regular expressions. ' +
         'Can search a single file or recursively through directories. ' +
         'Returns matching lines with optional context.',
@@ -319,6 +320,7 @@ function formatMatches(matches, options) {
 export function createGrepTool(options) {
     return defineTool({
         name: 'grep',
+        readonly: true,
         description: 'Search for patterns in files using regular expressions. ' +
             'Can search a single file or recursively through directories. ' +
             'Returns matching lines with optional context.',

package/dist/tools/builtin/read-file.js

@@ -18,6 +18,7 @@ const DEFAULT_MAX_CONTENT_SIZE = 100 * 1024;
  */
 export const readFileTool = defineTool({
     name: 'read_file',
+    readonly: true,
     description: 'Read the contents of a file. Returns the file content as text. ' +
         'Use maxLines and startLine to read specific portions of large files.',
     inputSchema: {
@@ -137,6 +138,7 @@ function formatSize(bytes) {
 export function createReadFileTool(options) {
     return defineTool({
         name: 'read_file',
+        readonly: true,
         description: 'Read the contents of a file. Returns the file content as text. ' +
             'Use maxLines and startLine to read specific portions of large files.',
         inputSchema: {

package/dist/tools/builtin/todo.d.ts

@@ -38,6 +38,11 @@ export interface TodoItem {
      * If undefined/null, the task is unassigned
      */
     owner?: string;
+    /**
+     * 1-based task numbers this task is blocked by.
+     * References positions in the todo array.
+     */
+    blockedBy?: number[];
     /**
      * Creation timestamp
      */
@@ -60,6 +65,7 @@ export interface TodoWriteInput {
         activeForm?: string;
         priority?: number;
         owner?: string;
+        blockedBy?: number[];
     }>;
 }
 /**
@@ -110,6 +116,7 @@ export declare class TodoStore {
         activeForm?: string;
         priority?: number;
         owner?: string;
+        blockedBy?: number[];
     }>): void;
     /**
      * Add a single todo
@@ -120,6 +127,7 @@ export declare class TodoStore {
         activeForm?: string;
         priority?: number;
         owner?: string;
+        blockedBy?: number[];
     }): TodoItem;
     /**
      * Update a todo by ID

package/dist/tools/builtin/todo.js

@@ -64,6 +64,7 @@ export class TodoStore {
                 activeForm: todo.activeForm,
                 priority: todo.priority,
                 owner: todo.owner,
+                blockedBy: todo.blockedBy,
                 createdAt: now,
                 updatedAt: now,
             });
@@ -82,6 +83,7 @@ export class TodoStore {
             activeForm: todo.activeForm,
             priority: todo.priority,
             owner: todo.owner,
+            blockedBy: todo.blockedBy,
             createdAt: now,
             updatedAt: now,
         };
@@ -158,7 +160,8 @@ export const todoWriteTool = defineTool({
     name: 'todo_write',
     description: 'Update the SESSION todo list (shown in CLI footer). These are ephemeral tasks for the current session only - ' +
         'NOT persistent backlog items. For persistent project backlog, use workitem_* tools. ' +
-        'Provide the complete list to replace current todos.',
+        'Provide the complete list to replace current todos. ' +
+        'Use blockedBy to declare task dependencies (1-based positions in the array).',
     inputSchema: {
         type: 'object',
         properties: {
@@ -189,6 +192,11 @@ export const todoWriteTool = defineTool({
                             type: 'string',
                             description: 'Owner agent ID (e.g., "dev", "pm", "arch"). Omit for unassigned tasks.',
                         },
+                        blockedBy: {
+                            type: 'array',
+                            items: { type: 'number' },
+                            description: 'Array of 1-based task numbers this task depends on (e.g., [3, 4] means blocked by task #3 and #4)',
+                        },
                     },
                     required: ['content', 'status'],
                 },
@@ -220,6 +228,7 @@ export const todoWriteTool = defineTool({
  */
 export const todoReadTool = defineTool({
     name: 'todo_read',
+    readonly: true,
     description: 'Get the SESSION todo list (shown in CLI footer). These are ephemeral session tasks - ' +
         'for persistent project backlog, use workitem_query. Optionally filter by status or owner.',
     inputSchema: {
@@ -268,6 +277,7 @@ export const todoReadTool = defineTool({
                 activeForm: t.activeForm,
                 priority: t.priority,
                 owner: t.owner,
+                blockedBy: t.blockedBy,
             })),
             counts,
             total: todos.length,
@@ -282,7 +292,8 @@ export function createTodoTools(store) {
     const todoWrite = defineTool({
         name: 'todo_write',
         description: 'Update the SESSION todo list (shown in CLI footer). These are ephemeral tasks for the current session only - ' +
-            'NOT persistent backlog items. For persistent project backlog, use workitem_* tools.',
+            'NOT persistent backlog items. For persistent project backlog, use workitem_* tools. ' +
+            'Use blockedBy to declare task dependencies (1-based positions in the array).',
         inputSchema: {
             type: 'object',
             properties: {
@@ -297,6 +308,11 @@ export function createTodoTools(store) {
                             activeForm: { type: 'string' },
                             priority: { type: 'number' },
                             owner: { type: 'string' },
+                            blockedBy: {
+                                type: 'array',
+                                items: { type: 'number' },
+                                description: '1-based task numbers this task depends on',
+                            },
                         },
                         required: ['content', 'status'],
                     },
@@ -325,6 +341,7 @@ export function createTodoTools(store) {
     });
     const todoRead = defineTool({
         name: 'todo_read',
+        readonly: true,
         description: 'Get the SESSION todo list (shown in CLI footer). These are ephemeral session tasks - ' +
             'for persistent project backlog, use workitem_query.',
         inputSchema: {
@@ -368,6 +385,7 @@ export function createTodoTools(store) {
                     activeForm: t.activeForm,
                     priority: t.priority,
                     owner: t.owner,
+                    blockedBy: t.blockedBy,
                 })),
                 counts,
                 total: todos.length,

package/dist/tools/builtin/web-fetch.js

@@ -17,6 +17,7 @@ const DEFAULT_MAX_SIZE = 100 * 1024;
  */
 export const webFetchTool = defineTool({
     name: 'web_fetch',
+    readonly: true,
     description: 'Fetch content from a URL. Returns the page content as text. ' +
         'Use for retrieving documentation, API responses, or web pages. ' +
         'HTTP URLs are automatically upgraded to HTTPS.',
@@ -168,6 +169,7 @@ export function createWebFetchTool(options) {
     const { defaultTimeout = DEFAULT_TIMEOUT, defaultMaxSize = DEFAULT_MAX_SIZE, blockedDomains = [], allowedDomains, customHeaders = {}, } = options ?? {};
     return defineTool({
         name: 'web_fetch',
+        readonly: true,
         description: 'Fetch content from a URL. Returns the page content as text. ' +
             'Use for retrieving documentation, API responses, or web pages. ' +
             'HTTP URLs are automatically upgraded to HTTPS.',

package/dist/tools/define.d.ts

@@ -35,6 +35,13 @@ export interface DefineToolOptions<T extends object> {
      * Default: false (normal visibility)
      */
     silent?: boolean;
+    /**
+     * If true, this tool performs no side effects (only reads data).
+     * Read-only tools are automatically batched for parallel execution
+     * even in a mixed batch with write tools.
+     * Default: false
+     */
+    readonly?: boolean;
 }
 /**
  * Define a tool with type-safe input handling

package/dist/tools/define.js

@@ -34,6 +34,7 @@ export function defineTool(options) {
         execute: options.execute,
         parallel: options.parallel,
         silent: options.silent,
+        readonly: options.readonly,
     };
 }
 /**

package/dist/tools/types.d.ts

@@ -78,6 +78,13 @@ export interface Tool<T = object> {
      * Default: false (normal visibility)
      */
     silent?: boolean;
+    /**
+     * If true, this tool performs no side effects (only reads data).
+     * Read-only tools are automatically batched for parallel execution
+     * even in a mixed batch with write tools.
+     * Default: false
+     */
+    readonly?: boolean;
 }
 /**
  * Fallback handler for tools not found in the primary registry.

package/dist/tracing/index.d.ts

@@ -47,5 +47,8 @@ export { TracingManager } from './manager.js';
 export { createTracingHooks, createLoggingHooks, mergeHooks } from './hooks.js';
 export { createStructuredLogger, createNoopLogger, createBufferedLogger, createTracingLogger, formatDuration, formatBytes, redactSensitive, } from './logging.js';
 export { createOTelExporter, createConsoleExporter, createBatchExporter, createMultiExporter, OTelNotInstalledError, isOTelNotInstalledError, } from './otel.js';
+export { createOTelHooks } from './otel-hooks.js';
+export type { OTelHooksConfig } from './otel-hooks.js';
+export { GenAIAttributes, AgentAttributes, PROVIDER_TO_SYSTEM } from './otel-attributes.js';
 export type { Span, SpanStatus, SpanKind, SpanAttributes, SpanContext, SpanEvent, AttributeValue, Trace, TracingManagerOptions, StartSpanOptions, EndSpanOptions, TracingHooksConfig, TracingEvent, TracingEventHandler, OTelExporter, OTelSDK, OTelTracer, OTelSpan, LogLevel, LogEntry, StructuredLogger, StructuredLoggerOptions, TracingHookContext, TracingManagerInterface, } from './types.js';
 export { SemanticAttributes } from './types.js';

package/dist/tracing/index.js

@@ -49,7 +49,10 @@ export { TracingManager } from './manager.js';
 export { createTracingHooks, createLoggingHooks, mergeHooks } from './hooks.js';
 // Structured logging
 export { createStructuredLogger, createNoopLogger, createBufferedLogger, createTracingLogger, formatDuration, formatBytes, redactSensitive, } from './logging.js';
-// OpenTelemetry integration
+// OpenTelemetry integration (post-hoc exporter)
 export { createOTelExporter, createConsoleExporter, createBatchExporter, createMultiExporter, OTelNotInstalledError, isOTelNotInstalledError, } from './otel.js';
+// OpenTelemetry native hooks (real-time instrumentation)
+export { createOTelHooks } from './otel-hooks.js';
+export { GenAIAttributes, AgentAttributes, PROVIDER_TO_SYSTEM } from './otel-attributes.js';
 // Semantic conventions
 export { SemanticAttributes } from './types.js';

package/dist/tracing/otel-attributes.d.ts

@@ -0,0 +1,59 @@
+/**
+ * OpenTelemetry Semantic Convention Attributes
+ *
+ * Constants following the official OpenTelemetry gen_ai semantic conventions
+ * for LLM observability, plus agent-specific attributes.
+ *
+ * @see https://opentelemetry.io/docs/specs/semconv/gen-ai/
+ */
+/**
+ * gen_ai.* semantic convention attributes for LLM operations
+ */
+export declare const GenAIAttributes: {
+    /** The AI system (e.g. 'anthropic', 'openai', 'google') */
+    readonly SYSTEM: "gen_ai.system";
+    /** The operation name (e.g. 'chat') */
+    readonly OPERATION_NAME: "gen_ai.operation.name";
+    /** The model requested */
+    readonly REQUEST_MODEL: "gen_ai.request.model";
+    /** Max tokens requested */
+    readonly REQUEST_MAX_TOKENS: "gen_ai.request.max_tokens";
+    /** Temperature requested */
+    readonly REQUEST_TEMPERATURE: "gen_ai.request.temperature";
+    /** The model actually used in the response */
+    readonly RESPONSE_MODEL: "gen_ai.response.model";
+    /** Finish reasons (e.g. ['stop'], ['tool_calls']) */
+    readonly RESPONSE_FINISH_REASON: "gen_ai.response.finish_reasons";
+    /** Input token count */
+    readonly USAGE_INPUT_TOKENS: "gen_ai.usage.input_tokens";
+    /** Output token count */
+    readonly USAGE_OUTPUT_TOKENS: "gen_ai.usage.output_tokens";
+};
+/**
+ * Agent-specific attributes for iteration and tool tracking
+ */
+export declare const AgentAttributes: {
+    /** Session ID for the agent run */
+    readonly SESSION_ID: "agent.session_id";
+    /** Current iteration number (1-indexed) */
+    readonly ITERATION_NUMBER: "agent.iteration.number";
+    /** Maximum allowed iterations */
+    readonly ITERATION_MAX: "agent.iteration.max";
+    /** Tool name being executed */
+    readonly TOOL_NAME: "agent.tool.name";
+    /** Whether the tool executed successfully */
+    readonly TOOL_SUCCESS: "agent.tool.success";
+    /** Tool execution duration in milliseconds */
+    readonly TOOL_DURATION_MS: "agent.tool.duration_ms";
+    /** Number of tool calls in the iteration */
+    readonly TOOL_CALL_COUNT: "agent.tool_call_count";
+    /** Number of messages in the conversation */
+    readonly MESSAGE_COUNT: "agent.message_count";
+    /** Whether the iteration completed with text (no tool calls) */
+    readonly COMPLETED_WITH_TEXT: "agent.completed_with_text";
+};
+/**
+ * Maps provider names (as used in the agents library) to gen_ai.system values
+ * following OpenTelemetry semantic conventions.
+ */
+export declare const PROVIDER_TO_SYSTEM: Record<string, string>;

package/dist/tracing/otel-attributes.js

@@ -0,0 +1,71 @@
+/**
+ * OpenTelemetry Semantic Convention Attributes
+ *
+ * Constants following the official OpenTelemetry gen_ai semantic conventions
+ * for LLM observability, plus agent-specific attributes.
+ *
+ * @see https://opentelemetry.io/docs/specs/semconv/gen-ai/
+ */
+/**
+ * gen_ai.* semantic convention attributes for LLM operations
+ */
+export const GenAIAttributes = {
+    /** The AI system (e.g. 'anthropic', 'openai', 'google') */
+    SYSTEM: 'gen_ai.system',
+    /** The operation name (e.g. 'chat') */
+    OPERATION_NAME: 'gen_ai.operation.name',
+    /** The model requested */
+    REQUEST_MODEL: 'gen_ai.request.model',
+    /** Max tokens requested */
+    REQUEST_MAX_TOKENS: 'gen_ai.request.max_tokens',
+    /** Temperature requested */
+    REQUEST_TEMPERATURE: 'gen_ai.request.temperature',
+    /** The model actually used in the response */
+    RESPONSE_MODEL: 'gen_ai.response.model',
+    /** Finish reasons (e.g. ['stop'], ['tool_calls']) */
+    RESPONSE_FINISH_REASON: 'gen_ai.response.finish_reasons',
+    /** Input token count */
+    USAGE_INPUT_TOKENS: 'gen_ai.usage.input_tokens',
+    /** Output token count */
+    USAGE_OUTPUT_TOKENS: 'gen_ai.usage.output_tokens',
+};
+/**
+ * Agent-specific attributes for iteration and tool tracking
+ */
+export const AgentAttributes = {
+    /** Session ID for the agent run */
+    SESSION_ID: 'agent.session_id',
+    /** Current iteration number (1-indexed) */
+    ITERATION_NUMBER: 'agent.iteration.number',
+    /** Maximum allowed iterations */
+    ITERATION_MAX: 'agent.iteration.max',
+    /** Tool name being executed */
+    TOOL_NAME: 'agent.tool.name',
+    /** Whether the tool executed successfully */
+    TOOL_SUCCESS: 'agent.tool.success',
+    /** Tool execution duration in milliseconds */
+    TOOL_DURATION_MS: 'agent.tool.duration_ms',
+    /** Number of tool calls in the iteration */
+    TOOL_CALL_COUNT: 'agent.tool_call_count',
+    /** Number of messages in the conversation */
+    MESSAGE_COUNT: 'agent.message_count',
+    /** Whether the iteration completed with text (no tool calls) */
+    COMPLETED_WITH_TEXT: 'agent.completed_with_text',
+};
+/**
+ * Maps provider names (as used in the agents library) to gen_ai.system values
+ * following OpenTelemetry semantic conventions.
+ */
+export const PROVIDER_TO_SYSTEM = {
+    claude: 'anthropic',
+    openai: 'openai',
+    gemini: 'google',
+    'gemini-native': 'google',
+    ollama: 'ollama',
+    groq: 'groq',
+    together: 'together_ai',
+    fireworks: 'fireworks_ai',
+    openrouter: 'openrouter',
+    perplexity: 'perplexity',
+    mock: 'mock',
+};