@compilr-dev/agents 0.3.14 → 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/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.js

@@ -228,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: {
@@ -340,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: {

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',
+};

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

@@ -0,0 +1,61 @@
+/**
+ * Native OpenTelemetry Hooks
+ *
+ * Creates real OTel spans during agent execution with proper context propagation
+ * and gen_ai semantic conventions. Unlike the post-hoc `createOTelExporter()`,
+ * these hooks create spans in real time with correct parent-child relationships.
+ *
+ * Requires `@opentelemetry/api` (regular dependency, no-ops without SDK registered).
+ *
+ * @example
+ * ```typescript
+ * import { createOTelHooks } from '@compilr-dev/agents';
+ *
+ * const hooks = createOTelHooks({
+ *   providerName: 'claude',
+ *   tracerName: 'my-agent',
+ * });
+ *
+ * const agent = new Agent({ provider, hooks });
+ * ```
+ */
+import type { HooksConfig } from '../hooks/types.js';
+/**
+ * Configuration for OTel hooks
+ */
+export interface OTelHooksConfig {
+    /** Tracer name (default: '@compilr-dev/agents') */
+    tracerName?: string;
+    /** Tracer version */
+    tracerVersion?: string;
+    /** Provider name for gen_ai.system mapping (e.g. 'claude', 'openai') */
+    providerName?: string;
+    /** Trace iteration spans (default: true) */
+    traceIterations?: boolean;
+    /** Trace LLM call spans (default: true) */
+    traceLLM?: boolean;
+    /** Trace tool execution spans (default: true) */
+    traceTools?: boolean;
+    /** Include input/output content in span attributes (default: false) */
+    includeIO?: boolean;
+    /** Truncate attribute values at this length (default: 1000) */
+    truncateAt?: number;
+}
+/**
+ * Create native OpenTelemetry hooks for agent instrumentation.
+ *
+ * These hooks create real OTel spans during execution, as opposed to the
+ * post-hoc `createOTelExporter()` which recreates spans after the fact.
+ *
+ * Span hierarchy:
+ * ```
+ * agent.iteration [INTERNAL]
+ *   ├── gen_ai.chat [CLIENT]           (gen_ai.system, tokens, model)
+ *   ├── agent.tool.read_file [INTERNAL] (tool.name, success, duration)
+ *   └── agent.tool.bash [INTERNAL]
+ * ```
+ *
+ * @param config - Optional configuration
+ * @returns HooksConfig ready to pass to Agent constructor
+ */
+export declare function createOTelHooks(config?: OTelHooksConfig): HooksConfig;