@cognipeer/agent-sdk 0.9.1 → 0.9.3

package/dist/index.d.cts

@@ -1194,7 +1194,58 @@ type TraceMetadataSection = {
     label: string;
     data: Record<string, any>;
 };
-type TraceDataSection = TraceMessageSection | TraceToolCallSection | TraceToolResultSection | TraceToolResponseSection | TraceSummarySection | TraceMetadataSection;
+/** One tool of the menu offered to the model on a single call. */
+type TraceToolDefinition = {
+    name: string;
+    description?: string;
+    /** JSON-schema `parameters` object (flat, no $ref wrapper). */
+    parameters?: Record<string, any>;
+    /** Set when `parameters` was dropped to fit the section size budget. */
+    truncated?: boolean;
+};
+/**
+ * The tool MENU bound to one model call ("which tools was the model offered
+ * on this turn?"). Rides on the `ai_call` event — never per session, because
+ * the menu can change between calls. Matches the Cognipeer console ingest
+ * contract for section kind `tool_definitions`.
+ */
+type TraceToolDefinitionsSection = {
+    id?: string;
+    kind: "tool_definitions";
+    label: string;
+    tools: TraceToolDefinition[];
+    /** Set when the tool list itself was truncated to fit the size budget. */
+    truncated?: boolean;
+};
+/**
+ * The structured-output contract bound to one model call — the other half of
+ * the request that decides the SHAPE of the answer (the tool menu being the
+ * first half). Without it a trace cannot distinguish "the model chose to write
+ * prose" from "nothing ever asked it for JSON", and any replay of the call
+ * (evaluation, prompt optimization) silently runs under a looser contract than
+ * production did.
+ *
+ * Rides on the `ai_call` event, never per session: a run can enforce a schema
+ * on its final turn only, and each call records the contract it actually sent.
+ */
+type TraceResponseFormatSection = {
+    id?: string;
+    kind: "response_format";
+    label: string;
+    /** `json_schema` | `json_object` | `text` — the wire `response_format.type`. */
+    type: string;
+    /** Which strategy produced it: native `response_format` or the `response` tool. */
+    strategy?: "native" | "tool_based";
+    /** `json_schema.name` when the provider takes a named schema. */
+    schemaName?: string;
+    /** `json_schema.strict` — whether the provider enforces the schema. */
+    strict?: boolean;
+    /** The JSON Schema as sent. Dropped (with `truncated`) when over budget. */
+    schema?: Record<string, any>;
+    /** Set when `schema` was dropped to fit the section size budget. */
+    truncated?: boolean;
+};
+type TraceDataSection = TraceMessageSection | TraceToolCallSection | TraceToolResultSection | TraceToolResponseSection | TraceSummarySection | TraceMetadataSection | TraceToolDefinitionsSection | TraceResponseFormatSection;
 type TraceEventRecord = {
     sessionId: string;
     id: string;
@@ -1217,6 +1268,21 @@ type TraceEventRecord = {
     outputTokens?: number;
     totalTokens?: number;
     cachedInputTokens?: number;
+    /**
+     * Reasoning tokens billed inside `outputTokens` (a SUBSET of it, matching
+     * OpenAI's `completion_tokens_details.reasoning_tokens`). Recorded because
+     * on a reasoning model they are routinely most of the output bill while
+     * being invisible in the response text — a spend investigation that only
+     * sees `outputTokens` cannot explain where the money went.
+     */
+    reasoningTokens?: number;
+    /**
+     * Why the model stopped: `stop` | `tool_calls` | `length` | `content_filter`
+     * | `error`. `length` is the single most common explanation for a truncated
+     * or unparseable structured response, and without it that failure is
+     * indistinguishable from a model that simply answered badly.
+     */
+    finishReason?: string;
     requestBytes?: number;
     responseBytes?: number;
     model?: string;
@@ -2649,7 +2715,6 @@ declare class NativeJsonSchemaStrategy implements StructuredOutputStrategy {
     readonly kind: "native";
     private resolveJsonPointer;
     private unwrapRootObjectSchema;
-    private normalizeOpenAIStrictSchema;
     /**
      * Convert a Zod schema to the JSON Schema object used in response_format.
      */
@@ -2914,6 +2979,26 @@ declare function traceSessionToOtlp(session: TraceSessionFile): Record<string, u
 declare function generateTraceId(): string;
 /** Generate an OTel span ID (16 hex chars / 64-bit). */
 declare function generateSpanId(): string;
+/**
+ * Build the `tool_definitions` section for one model call, or undefined when
+ * nothing usable was supplied. Exported for provider/node code that assembles
+ * sections itself.
+ */
+declare function buildToolDefinitionsSection(toolDefinitions: Array<{
+    name: string;
+    description?: string;
+    parameters?: Record<string, any>;
+}>): TraceToolDefinitionsSection | undefined;
+/**
+ * Build the `response_format` section for one model call, or undefined when
+ * nothing usable was supplied.
+ *
+ * Accepts either the invoke-options wrapper produced by
+ * `NativeJsonSchemaStrategy.buildResponseFormat()` (`{ response_format: {…} }`)
+ * or a bare `response_format` object, so callers can pass whatever they hold.
+ * Exported for provider/node code that assembles sections itself.
+ */
+declare function buildResponseFormatSection(responseFormat: Record<string, any> | undefined, strategy?: "native" | "tool_based"): TraceResponseFormatSection | undefined;
 /**
  * Start a streaming trace session. Should be called before recording events in streaming mode.
  * This sends the session start to the remote endpoint immediately.
@@ -3429,4 +3514,4 @@ declare function fromNativeProvider(provider: BaseProvider, options?: NativeMode
  */
 declare function createProvider(config: ProviderConfig): BaseProvider;
 
-export { type AIMessage, ASK_USER_TOOL_NAME, type AgentInstance, type AgentInvokeResult, type AgentLimits, type AgentOptions, type AgentRuleOptions, type AgentRuntimeConfig, type AgentSnapshot, type AgentSnapshotMetadata, type AgentState, AnthropicProvider, type AnthropicProviderConfig, type AudioContent, AzureProvider, type AzureProviderConfig, type BaseChatMessage, type BaseChatMessagePart, type BaseChatModel, type BaseMessage, BaseProvider, BedrockProvider, type BedrockProviderConfig, type BuildChildConfig, type BuiltInRuntimeProfile, CCRStore, CONTEXT_PILOT_JSON_MARKER_KEY, CONTROL_PLANE_TOOL_NAMES, type CancellationTokenLike, type CancelledEvent, type ChatCompletionChunk, type ChatCompletionRequest, type ChatCompletionResponse, type ChildContextPolicy, type CodeDetectionRuleOptions, type CodeGuardrailOptions, type CompressToolOutputParams, type ContextPilotCCRConfig, type ContextPilotCacheAlignmentConfig, type ContextPilotCompressionConfig, type ContextPilotCompressionStats, type ContextPilotCompressorKind, type ContextPilotConfig, type ContextPilotDedupConfig, type ContextPilotDiffCompressionConfig, type ContextPilotJsonCompressionConfig, type ContextPilotLogCompressionConfig, type ContextPilotResult, type ContextPilotRuntime, type ContextPilotSearchCompressionConfig, type ContextPilotTextCompressionConfig, type ContextPolicy, type ContextToolsStateRef, type ConversationGuardrail, type CustomRuleCallback, type CustomRuleOptions, DEFAULT_MAX_TOOL_INPUT_FIELD_CHARS, DEFAULT_PROFILE_CONFIGS, DEFAULT_SKILL_POLICY, DEFAULT_SUBAGENT_POLICY, DEFAULT_SUBAGENT_TOOL_NAMES, DEFAULT_TOOL_INPUT_DIGEST_HEAD_CHARS, DELEGATION_TOOL_NAMES, DedupTracker, type DelegationEventStamp, type DelegationMode, type EvalCase, type EvalCaseResult, type EvalFamily, type EvalHarnessMetrics, type EvalHarnessParams, type EvalHarnessResult, type EvalProfileDescriptor, type EvalProfileTarget, type FileContent, type FinalAnswerEvent, type FinishReason, type GuardrailContext, type GuardrailDisposition, type GuardrailEvent, type GuardrailIncident, type GuardrailOutcome, GuardrailPhase, type GuardrailRule, type HandoffDescriptor, type HandoffEvent, type HumanInTheLoopAskUserConfig, type HumanInTheLoopOptions, type HumanInTheLoopRuntimeConfig, type ImageContent, InMemoryMemoryStore, type InvokeConfig, type JsonGuardrailOptions, type JsonSchemaRuleOptions, type LoadSkillsOptions, type MemoryFact, type MemoryProviderKind, type MemoryReadPolicy, type MemoryScope, type MemoryStore, type MemoryWritePolicy, type Message, type MetadataEvent, type ModelCapabilities, NativeJsonSchemaStrategy, type NativeModelOptions, type NativeReasoningConfig, OpenAICompatibleProvider, type OpenAICompatibleProviderConfig, OpenAIProvider, type OpenAIProviderConfig, PREOPEN_TOOL_CALL_PREFIX, type PendingToolApproval, type PendingUserQuestion, type PlanEvent, type PlanStepRecord, type PlanningMode, type PreopenSkillsResult, type ProfileConfig, type ProgressEvent, type ProgressUpdate, type PromptHooks, type ProviderConfig, ProviderError, type ToolCall as ProviderToolCall, type ToolDefinition as ProviderToolDefinition, type ProviderType, type ReasoningConfig, type ReasoningLevel, type ReflectionCadence, type ReflectionConfig, type ReflectionEvent, type ReflectionHookContext, type ReflectionRecord, type RegexGuardrailOptions, type RegexRuleOptions, type ReplanPolicy, type ResolvedContextPilotConfig, type ResolvedSmartAgentConfig, type ResolvedTraceConfig, type ResolvedTraceSink, type RestoreSnapshotOptions, type RuntimeProfile, SMALL_TIER_SKILL_POLICY, type SerializableSmartState, type Skill, type SkillDisclosure, type SkillExecutionContext, type SkillFrontmatter, type SkillFs, type SkillModelTier, type SkillPolicy, type SkillRegistryRef, type SkillToolDeps, type SkillToolHeader, type SmartAgentBudgetConfig, type SmartAgentContextConfig, type SmartAgentCustomProfileConfig, type SmartAgentDelegationConfig, type SmartAgentEvent, type SmartAgentInstance, type SmartAgentLimits, type SmartAgentMemoryConfig, type SmartAgentOptions, type SmartAgentPlanningConfig, type SmartAgentSummarizationConfig, type SmartAgentToolResponseConfig, type SmartAgentTracingConfig, type SmartModel, type SmartState, type SmartToolFn, type SnapshotOptions, type SnapshotRuntimeHint, type StreamChunk, type StreamEvent, type StructuredOutputError, type StructuredOutputFieldError, StructuredOutputManager, type StructuredOutputManagerConfig, type StructuredOutputResult, type StructuredOutputStrategy, type StructuredSummary, type SubagentDef, type SubagentEvent, type SubagentMode, type SubagentPendingRecord, type SubagentPolicy, type SubagentRegistryRef, type SubagentResult, type SubagentToolDeps, type SubagentToolNames, type SummarizationEvent, type SummarizationMode, type SummaryFactItem, type SummaryIntegrityCheck, TOOL_INPUT_DIGEST_KEY, type TextContent, type TokenCounter, type TokenUsage, type ToolApprovalEvent, type ToolApprovalResolution, type ToolApprovalStatus, ToolBasedStrategy, type ToolCachePolicy, type ToolCallEvent, type ToolInputDigestOptions, type ToolInputDigestResult, type ToolInputRetentionPolicy, type ToolInterface, type ToolResponseClassification, type ToolResponseRetentionPolicy, type ToolRetentionDeclarations, type ToolRetentionSpec, type ToolRetryPolicy, type TraceDataSection, type TraceErrorRecord, type TraceEventRecord, type TraceMessageSection, type TraceMetadataSection, type TraceSessionConfigSnapshot, type TraceSessionFile, type TraceSessionStatus, type TraceSessionSummary, type TraceSinkCognipeerConfig, type TraceSinkConfig, type TraceSinkCustomConfig, type TraceSinkFileConfig, type TraceSinkHttpConfig, type TraceSinkOtlpConfig, type TraceSinkSnapshot, type TraceSummarySection, type TraceToolCallSection, type TraceToolDetails, type TraceToolResponseSection, type TraceToolResultSection, type TracingConfig, type TracingMode, type UnifiedMessage, type UserQuestionAnswer, type UserQuestionAnswerSet, type UserQuestionEvent, type UserQuestionItem, type UserQuestionOption, type UserQuestionResolution, type UserQuestionStatus, VertexProvider, type VertexProviderConfig, type VolatileContentFinding, type VolatileContentPattern, agentVerdictRule, appendBoundTools, buildSkillHeaderBlock, buildSubagentCatalogBlock, buildSystemPrompt, canOpenSkill, canSpawn, captureSnapshot, codePresenceRule, coerceToolArgs, cognipeerSink, collectToolRetentionDeclarations, composeToolSets, compressDiffOutput, compressJsonOutput, compressLogOutput, compressSearchOutput, compressTextOutput, compressToolOutput, countApproxTokens, countMessagesTokens, createAgent, createAgentNode, createAskUserQuestionTool, createBindSkillToolsTool, createCodeGuardrail, createContextPilotRuntime, createContextSummarizeNode, createContextTools, createDelegateTool, createGetToolResponseTool, createGuardrail, createJsonGuardrail, createManageTodoTool, createOpenSkillTool, createParallelTool, createProvider, createRegexGuardrail, createResolverNode, createSearchSkillsTool, createSkillRegistryRef, createSkillTools, createSmartAgent, createSpawnTool, createSubagentRegistryRef, createSubagentTools, createTool, createToolLimitFinalizeNode, createToolsNode, customCallbackRule, customSink, dedupeToolsByName, defaultTokenCounter, detectTextFormat, detectVolatileContent, digestToolInputArguments, digestToolInputValue, emptyUsage, evaluateGuardrails, extractLatestUserQuery, fileSink, findSubagent, formatZodError, fromLangchainModel, fromLangchainTools, fromNativeProvider, generateSpanId, generateTraceId, getModelCapabilities, getNestedValue, getResolvedSmartConfig, getTokenCounter, hasToolResponseRecoveryReference, httpSink, isSmartModel, jsonSchemaRule, loadSkillsFromDisk, normalizeSmartAgentOptions, otlpSink, parseSkillFrontmatter, preopenSkills, preopenToolCallId, readMemoryFacts, regexRule, resolveAvailableSkills, resolveAvailableSubagents, resolveInputRetention, resolveMemoryStore, resolveReasoning, resolveStrategy, resolveSubagentTools, resolveSummarizationRetention, resolveToolApprovalState, resolveUserQuestionState, restoreSnapshot, runSmartAgentEvalHarness, scoreItemsByRelevance, searchSkills, seedChildMessages, selectTopIndicesInOrder, setTokenCounter, startStreamingSession, summarizeObject, tokenize, traceSessionToOtlp, validateReasoningConfig, validateToolArgs, withTools, withinDepth, writeSummaryFactsToMemory };
+export { type AIMessage, ASK_USER_TOOL_NAME, type AgentInstance, type AgentInvokeResult, type AgentLimits, type AgentOptions, type AgentRuleOptions, type AgentRuntimeConfig, type AgentSnapshot, type AgentSnapshotMetadata, type AgentState, AnthropicProvider, type AnthropicProviderConfig, type AudioContent, AzureProvider, type AzureProviderConfig, type BaseChatMessage, type BaseChatMessagePart, type BaseChatModel, type BaseMessage, BaseProvider, BedrockProvider, type BedrockProviderConfig, type BuildChildConfig, type BuiltInRuntimeProfile, CCRStore, CONTEXT_PILOT_JSON_MARKER_KEY, CONTROL_PLANE_TOOL_NAMES, type CancellationTokenLike, type CancelledEvent, type ChatCompletionChunk, type ChatCompletionRequest, type ChatCompletionResponse, type ChildContextPolicy, type CodeDetectionRuleOptions, type CodeGuardrailOptions, type CompressToolOutputParams, type ContextPilotCCRConfig, type ContextPilotCacheAlignmentConfig, type ContextPilotCompressionConfig, type ContextPilotCompressionStats, type ContextPilotCompressorKind, type ContextPilotConfig, type ContextPilotDedupConfig, type ContextPilotDiffCompressionConfig, type ContextPilotJsonCompressionConfig, type ContextPilotLogCompressionConfig, type ContextPilotResult, type ContextPilotRuntime, type ContextPilotSearchCompressionConfig, type ContextPilotTextCompressionConfig, type ContextPolicy, type ContextToolsStateRef, type ConversationGuardrail, type CustomRuleCallback, type CustomRuleOptions, DEFAULT_MAX_TOOL_INPUT_FIELD_CHARS, DEFAULT_PROFILE_CONFIGS, DEFAULT_SKILL_POLICY, DEFAULT_SUBAGENT_POLICY, DEFAULT_SUBAGENT_TOOL_NAMES, DEFAULT_TOOL_INPUT_DIGEST_HEAD_CHARS, DELEGATION_TOOL_NAMES, DedupTracker, type DelegationEventStamp, type DelegationMode, type EvalCase, type EvalCaseResult, type EvalFamily, type EvalHarnessMetrics, type EvalHarnessParams, type EvalHarnessResult, type EvalProfileDescriptor, type EvalProfileTarget, type FileContent, type FinalAnswerEvent, type FinishReason, type GuardrailContext, type GuardrailDisposition, type GuardrailEvent, type GuardrailIncident, type GuardrailOutcome, GuardrailPhase, type GuardrailRule, type HandoffDescriptor, type HandoffEvent, type HumanInTheLoopAskUserConfig, type HumanInTheLoopOptions, type HumanInTheLoopRuntimeConfig, type ImageContent, InMemoryMemoryStore, type InvokeConfig, type JsonGuardrailOptions, type JsonSchemaRuleOptions, type LoadSkillsOptions, type MemoryFact, type MemoryProviderKind, type MemoryReadPolicy, type MemoryScope, type MemoryStore, type MemoryWritePolicy, type Message, type MetadataEvent, type ModelCapabilities, NativeJsonSchemaStrategy, type NativeModelOptions, type NativeReasoningConfig, OpenAICompatibleProvider, type OpenAICompatibleProviderConfig, OpenAIProvider, type OpenAIProviderConfig, PREOPEN_TOOL_CALL_PREFIX, type PendingToolApproval, type PendingUserQuestion, type PlanEvent, type PlanStepRecord, type PlanningMode, type PreopenSkillsResult, type ProfileConfig, type ProgressEvent, type ProgressUpdate, type PromptHooks, type ProviderConfig, ProviderError, type ToolCall as ProviderToolCall, type ToolDefinition as ProviderToolDefinition, type ProviderType, type ReasoningConfig, type ReasoningLevel, type ReflectionCadence, type ReflectionConfig, type ReflectionEvent, type ReflectionHookContext, type ReflectionRecord, type RegexGuardrailOptions, type RegexRuleOptions, type ReplanPolicy, type ResolvedContextPilotConfig, type ResolvedSmartAgentConfig, type ResolvedTraceConfig, type ResolvedTraceSink, type RestoreSnapshotOptions, type RuntimeProfile, SMALL_TIER_SKILL_POLICY, type SerializableSmartState, type Skill, type SkillDisclosure, type SkillExecutionContext, type SkillFrontmatter, type SkillFs, type SkillModelTier, type SkillPolicy, type SkillRegistryRef, type SkillToolDeps, type SkillToolHeader, type SmartAgentBudgetConfig, type SmartAgentContextConfig, type SmartAgentCustomProfileConfig, type SmartAgentDelegationConfig, type SmartAgentEvent, type SmartAgentInstance, type SmartAgentLimits, type SmartAgentMemoryConfig, type SmartAgentOptions, type SmartAgentPlanningConfig, type SmartAgentSummarizationConfig, type SmartAgentToolResponseConfig, type SmartAgentTracingConfig, type SmartModel, type SmartState, type SmartToolFn, type SnapshotOptions, type SnapshotRuntimeHint, type StreamChunk, type StreamEvent, type StructuredOutputError, type StructuredOutputFieldError, StructuredOutputManager, type StructuredOutputManagerConfig, type StructuredOutputResult, type StructuredOutputStrategy, type StructuredSummary, type SubagentDef, type SubagentEvent, type SubagentMode, type SubagentPendingRecord, type SubagentPolicy, type SubagentRegistryRef, type SubagentResult, type SubagentToolDeps, type SubagentToolNames, type SummarizationEvent, type SummarizationMode, type SummaryFactItem, type SummaryIntegrityCheck, TOOL_INPUT_DIGEST_KEY, type TextContent, type TokenCounter, type TokenUsage, type ToolApprovalEvent, type ToolApprovalResolution, type ToolApprovalStatus, ToolBasedStrategy, type ToolCachePolicy, type ToolCallEvent, type ToolInputDigestOptions, type ToolInputDigestResult, type ToolInputRetentionPolicy, type ToolInterface, type ToolResponseClassification, type ToolResponseRetentionPolicy, type ToolRetentionDeclarations, type ToolRetentionSpec, type ToolRetryPolicy, type TraceDataSection, type TraceErrorRecord, type TraceEventRecord, type TraceMessageSection, type TraceMetadataSection, type TraceSessionConfigSnapshot, type TraceSessionFile, type TraceSessionStatus, type TraceSessionSummary, type TraceSinkCognipeerConfig, type TraceSinkConfig, type TraceSinkCustomConfig, type TraceSinkFileConfig, type TraceSinkHttpConfig, type TraceSinkOtlpConfig, type TraceSinkSnapshot, type TraceSummarySection, type TraceToolCallSection, type TraceToolDefinition, type TraceToolDefinitionsSection, type TraceToolDetails, type TraceToolResponseSection, type TraceToolResultSection, type TracingConfig, type TracingMode, type UnifiedMessage, type UserQuestionAnswer, type UserQuestionAnswerSet, type UserQuestionEvent, type UserQuestionItem, type UserQuestionOption, type UserQuestionResolution, type UserQuestionStatus, VertexProvider, type VertexProviderConfig, type VolatileContentFinding, type VolatileContentPattern, agentVerdictRule, appendBoundTools, buildResponseFormatSection, buildSkillHeaderBlock, buildSubagentCatalogBlock, buildSystemPrompt, buildToolDefinitionsSection, canOpenSkill, canSpawn, captureSnapshot, codePresenceRule, coerceToolArgs, cognipeerSink, collectToolRetentionDeclarations, composeToolSets, compressDiffOutput, compressJsonOutput, compressLogOutput, compressSearchOutput, compressTextOutput, compressToolOutput, countApproxTokens, countMessagesTokens, createAgent, createAgentNode, createAskUserQuestionTool, createBindSkillToolsTool, createCodeGuardrail, createContextPilotRuntime, createContextSummarizeNode, createContextTools, createDelegateTool, createGetToolResponseTool, createGuardrail, createJsonGuardrail, createManageTodoTool, createOpenSkillTool, createParallelTool, createProvider, createRegexGuardrail, createResolverNode, createSearchSkillsTool, createSkillRegistryRef, createSkillTools, createSmartAgent, createSpawnTool, createSubagentRegistryRef, createSubagentTools, createTool, createToolLimitFinalizeNode, createToolsNode, customCallbackRule, customSink, dedupeToolsByName, defaultTokenCounter, detectTextFormat, detectVolatileContent, digestToolInputArguments, digestToolInputValue, emptyUsage, evaluateGuardrails, extractLatestUserQuery, fileSink, findSubagent, formatZodError, fromLangchainModel, fromLangchainTools, fromNativeProvider, generateSpanId, generateTraceId, getModelCapabilities, getNestedValue, getResolvedSmartConfig, getTokenCounter, hasToolResponseRecoveryReference, httpSink, isSmartModel, jsonSchemaRule, loadSkillsFromDisk, normalizeSmartAgentOptions, otlpSink, parseSkillFrontmatter, preopenSkills, preopenToolCallId, readMemoryFacts, regexRule, resolveAvailableSkills, resolveAvailableSubagents, resolveInputRetention, resolveMemoryStore, resolveReasoning, resolveStrategy, resolveSubagentTools, resolveSummarizationRetention, resolveToolApprovalState, resolveUserQuestionState, restoreSnapshot, runSmartAgentEvalHarness, scoreItemsByRelevance, searchSkills, seedChildMessages, selectTopIndicesInOrder, setTokenCounter, startStreamingSession, summarizeObject, tokenize, traceSessionToOtlp, validateReasoningConfig, validateToolArgs, withTools, withinDepth, writeSummaryFactsToMemory };

package/dist/index.d.ts

@@ -1194,7 +1194,58 @@ type TraceMetadataSection = {
     label: string;
     data: Record<string, any>;
 };
-type TraceDataSection = TraceMessageSection | TraceToolCallSection | TraceToolResultSection | TraceToolResponseSection | TraceSummarySection | TraceMetadataSection;
+/** One tool of the menu offered to the model on a single call. */
+type TraceToolDefinition = {
+    name: string;
+    description?: string;
+    /** JSON-schema `parameters` object (flat, no $ref wrapper). */
+    parameters?: Record<string, any>;
+    /** Set when `parameters` was dropped to fit the section size budget. */
+    truncated?: boolean;
+};
+/**
+ * The tool MENU bound to one model call ("which tools was the model offered
+ * on this turn?"). Rides on the `ai_call` event — never per session, because
+ * the menu can change between calls. Matches the Cognipeer console ingest
+ * contract for section kind `tool_definitions`.
+ */
+type TraceToolDefinitionsSection = {
+    id?: string;
+    kind: "tool_definitions";
+    label: string;
+    tools: TraceToolDefinition[];
+    /** Set when the tool list itself was truncated to fit the size budget. */
+    truncated?: boolean;
+};
+/**
+ * The structured-output contract bound to one model call — the other half of
+ * the request that decides the SHAPE of the answer (the tool menu being the
+ * first half). Without it a trace cannot distinguish "the model chose to write
+ * prose" from "nothing ever asked it for JSON", and any replay of the call
+ * (evaluation, prompt optimization) silently runs under a looser contract than
+ * production did.
+ *
+ * Rides on the `ai_call` event, never per session: a run can enforce a schema
+ * on its final turn only, and each call records the contract it actually sent.
+ */
+type TraceResponseFormatSection = {
+    id?: string;
+    kind: "response_format";
+    label: string;
+    /** `json_schema` | `json_object` | `text` — the wire `response_format.type`. */
+    type: string;
+    /** Which strategy produced it: native `response_format` or the `response` tool. */
+    strategy?: "native" | "tool_based";
+    /** `json_schema.name` when the provider takes a named schema. */
+    schemaName?: string;
+    /** `json_schema.strict` — whether the provider enforces the schema. */
+    strict?: boolean;
+    /** The JSON Schema as sent. Dropped (with `truncated`) when over budget. */
+    schema?: Record<string, any>;
+    /** Set when `schema` was dropped to fit the section size budget. */
+    truncated?: boolean;
+};
+type TraceDataSection = TraceMessageSection | TraceToolCallSection | TraceToolResultSection | TraceToolResponseSection | TraceSummarySection | TraceMetadataSection | TraceToolDefinitionsSection | TraceResponseFormatSection;
 type TraceEventRecord = {
     sessionId: string;
     id: string;
@@ -1217,6 +1268,21 @@ type TraceEventRecord = {
     outputTokens?: number;
     totalTokens?: number;
     cachedInputTokens?: number;
+    /**
+     * Reasoning tokens billed inside `outputTokens` (a SUBSET of it, matching
+     * OpenAI's `completion_tokens_details.reasoning_tokens`). Recorded because
+     * on a reasoning model they are routinely most of the output bill while
+     * being invisible in the response text — a spend investigation that only
+     * sees `outputTokens` cannot explain where the money went.
+     */
+    reasoningTokens?: number;
+    /**
+     * Why the model stopped: `stop` | `tool_calls` | `length` | `content_filter`
+     * | `error`. `length` is the single most common explanation for a truncated
+     * or unparseable structured response, and without it that failure is
+     * indistinguishable from a model that simply answered badly.
+     */
+    finishReason?: string;
     requestBytes?: number;
     responseBytes?: number;
     model?: string;
@@ -2649,7 +2715,6 @@ declare class NativeJsonSchemaStrategy implements StructuredOutputStrategy {
     readonly kind: "native";
     private resolveJsonPointer;
     private unwrapRootObjectSchema;
-    private normalizeOpenAIStrictSchema;
     /**
      * Convert a Zod schema to the JSON Schema object used in response_format.
      */
@@ -2914,6 +2979,26 @@ declare function traceSessionToOtlp(session: TraceSessionFile): Record<string, u
 declare function generateTraceId(): string;
 /** Generate an OTel span ID (16 hex chars / 64-bit). */
 declare function generateSpanId(): string;
+/**
+ * Build the `tool_definitions` section for one model call, or undefined when
+ * nothing usable was supplied. Exported for provider/node code that assembles
+ * sections itself.
+ */
+declare function buildToolDefinitionsSection(toolDefinitions: Array<{
+    name: string;
+    description?: string;
+    parameters?: Record<string, any>;
+}>): TraceToolDefinitionsSection | undefined;
+/**
+ * Build the `response_format` section for one model call, or undefined when
+ * nothing usable was supplied.
+ *
+ * Accepts either the invoke-options wrapper produced by
+ * `NativeJsonSchemaStrategy.buildResponseFormat()` (`{ response_format: {…} }`)
+ * or a bare `response_format` object, so callers can pass whatever they hold.
+ * Exported for provider/node code that assembles sections itself.
+ */
+declare function buildResponseFormatSection(responseFormat: Record<string, any> | undefined, strategy?: "native" | "tool_based"): TraceResponseFormatSection | undefined;
 /**
  * Start a streaming trace session. Should be called before recording events in streaming mode.
  * This sends the session start to the remote endpoint immediately.
@@ -3429,4 +3514,4 @@ declare function fromNativeProvider(provider: BaseProvider, options?: NativeMode
  */
 declare function createProvider(config: ProviderConfig): BaseProvider;
 
-export { type AIMessage, ASK_USER_TOOL_NAME, type AgentInstance, type AgentInvokeResult, type AgentLimits, type AgentOptions, type AgentRuleOptions, type AgentRuntimeConfig, type AgentSnapshot, type AgentSnapshotMetadata, type AgentState, AnthropicProvider, type AnthropicProviderConfig, type AudioContent, AzureProvider, type AzureProviderConfig, type BaseChatMessage, type BaseChatMessagePart, type BaseChatModel, type BaseMessage, BaseProvider, BedrockProvider, type BedrockProviderConfig, type BuildChildConfig, type BuiltInRuntimeProfile, CCRStore, CONTEXT_PILOT_JSON_MARKER_KEY, CONTROL_PLANE_TOOL_NAMES, type CancellationTokenLike, type CancelledEvent, type ChatCompletionChunk, type ChatCompletionRequest, type ChatCompletionResponse, type ChildContextPolicy, type CodeDetectionRuleOptions, type CodeGuardrailOptions, type CompressToolOutputParams, type ContextPilotCCRConfig, type ContextPilotCacheAlignmentConfig, type ContextPilotCompressionConfig, type ContextPilotCompressionStats, type ContextPilotCompressorKind, type ContextPilotConfig, type ContextPilotDedupConfig, type ContextPilotDiffCompressionConfig, type ContextPilotJsonCompressionConfig, type ContextPilotLogCompressionConfig, type ContextPilotResult, type ContextPilotRuntime, type ContextPilotSearchCompressionConfig, type ContextPilotTextCompressionConfig, type ContextPolicy, type ContextToolsStateRef, type ConversationGuardrail, type CustomRuleCallback, type CustomRuleOptions, DEFAULT_MAX_TOOL_INPUT_FIELD_CHARS, DEFAULT_PROFILE_CONFIGS, DEFAULT_SKILL_POLICY, DEFAULT_SUBAGENT_POLICY, DEFAULT_SUBAGENT_TOOL_NAMES, DEFAULT_TOOL_INPUT_DIGEST_HEAD_CHARS, DELEGATION_TOOL_NAMES, DedupTracker, type DelegationEventStamp, type DelegationMode, type EvalCase, type EvalCaseResult, type EvalFamily, type EvalHarnessMetrics, type EvalHarnessParams, type EvalHarnessResult, type EvalProfileDescriptor, type EvalProfileTarget, type FileContent, type FinalAnswerEvent, type FinishReason, type GuardrailContext, type GuardrailDisposition, type GuardrailEvent, type GuardrailIncident, type GuardrailOutcome, GuardrailPhase, type GuardrailRule, type HandoffDescriptor, type HandoffEvent, type HumanInTheLoopAskUserConfig, type HumanInTheLoopOptions, type HumanInTheLoopRuntimeConfig, type ImageContent, InMemoryMemoryStore, type InvokeConfig, type JsonGuardrailOptions, type JsonSchemaRuleOptions, type LoadSkillsOptions, type MemoryFact, type MemoryProviderKind, type MemoryReadPolicy, type MemoryScope, type MemoryStore, type MemoryWritePolicy, type Message, type MetadataEvent, type ModelCapabilities, NativeJsonSchemaStrategy, type NativeModelOptions, type NativeReasoningConfig, OpenAICompatibleProvider, type OpenAICompatibleProviderConfig, OpenAIProvider, type OpenAIProviderConfig, PREOPEN_TOOL_CALL_PREFIX, type PendingToolApproval, type PendingUserQuestion, type PlanEvent, type PlanStepRecord, type PlanningMode, type PreopenSkillsResult, type ProfileConfig, type ProgressEvent, type ProgressUpdate, type PromptHooks, type ProviderConfig, ProviderError, type ToolCall as ProviderToolCall, type ToolDefinition as ProviderToolDefinition, type ProviderType, type ReasoningConfig, type ReasoningLevel, type ReflectionCadence, type ReflectionConfig, type ReflectionEvent, type ReflectionHookContext, type ReflectionRecord, type RegexGuardrailOptions, type RegexRuleOptions, type ReplanPolicy, type ResolvedContextPilotConfig, type ResolvedSmartAgentConfig, type ResolvedTraceConfig, type ResolvedTraceSink, type RestoreSnapshotOptions, type RuntimeProfile, SMALL_TIER_SKILL_POLICY, type SerializableSmartState, type Skill, type SkillDisclosure, type SkillExecutionContext, type SkillFrontmatter, type SkillFs, type SkillModelTier, type SkillPolicy, type SkillRegistryRef, type SkillToolDeps, type SkillToolHeader, type SmartAgentBudgetConfig, type SmartAgentContextConfig, type SmartAgentCustomProfileConfig, type SmartAgentDelegationConfig, type SmartAgentEvent, type SmartAgentInstance, type SmartAgentLimits, type SmartAgentMemoryConfig, type SmartAgentOptions, type SmartAgentPlanningConfig, type SmartAgentSummarizationConfig, type SmartAgentToolResponseConfig, type SmartAgentTracingConfig, type SmartModel, type SmartState, type SmartToolFn, type SnapshotOptions, type SnapshotRuntimeHint, type StreamChunk, type StreamEvent, type StructuredOutputError, type StructuredOutputFieldError, StructuredOutputManager, type StructuredOutputManagerConfig, type StructuredOutputResult, type StructuredOutputStrategy, type StructuredSummary, type SubagentDef, type SubagentEvent, type SubagentMode, type SubagentPendingRecord, type SubagentPolicy, type SubagentRegistryRef, type SubagentResult, type SubagentToolDeps, type SubagentToolNames, type SummarizationEvent, type SummarizationMode, type SummaryFactItem, type SummaryIntegrityCheck, TOOL_INPUT_DIGEST_KEY, type TextContent, type TokenCounter, type TokenUsage, type ToolApprovalEvent, type ToolApprovalResolution, type ToolApprovalStatus, ToolBasedStrategy, type ToolCachePolicy, type ToolCallEvent, type ToolInputDigestOptions, type ToolInputDigestResult, type ToolInputRetentionPolicy, type ToolInterface, type ToolResponseClassification, type ToolResponseRetentionPolicy, type ToolRetentionDeclarations, type ToolRetentionSpec, type ToolRetryPolicy, type TraceDataSection, type TraceErrorRecord, type TraceEventRecord, type TraceMessageSection, type TraceMetadataSection, type TraceSessionConfigSnapshot, type TraceSessionFile, type TraceSessionStatus, type TraceSessionSummary, type TraceSinkCognipeerConfig, type TraceSinkConfig, type TraceSinkCustomConfig, type TraceSinkFileConfig, type TraceSinkHttpConfig, type TraceSinkOtlpConfig, type TraceSinkSnapshot, type TraceSummarySection, type TraceToolCallSection, type TraceToolDetails, type TraceToolResponseSection, type TraceToolResultSection, type TracingConfig, type TracingMode, type UnifiedMessage, type UserQuestionAnswer, type UserQuestionAnswerSet, type UserQuestionEvent, type UserQuestionItem, type UserQuestionOption, type UserQuestionResolution, type UserQuestionStatus, VertexProvider, type VertexProviderConfig, type VolatileContentFinding, type VolatileContentPattern, agentVerdictRule, appendBoundTools, buildSkillHeaderBlock, buildSubagentCatalogBlock, buildSystemPrompt, canOpenSkill, canSpawn, captureSnapshot, codePresenceRule, coerceToolArgs, cognipeerSink, collectToolRetentionDeclarations, composeToolSets, compressDiffOutput, compressJsonOutput, compressLogOutput, compressSearchOutput, compressTextOutput, compressToolOutput, countApproxTokens, countMessagesTokens, createAgent, createAgentNode, createAskUserQuestionTool, createBindSkillToolsTool, createCodeGuardrail, createContextPilotRuntime, createContextSummarizeNode, createContextTools, createDelegateTool, createGetToolResponseTool, createGuardrail, createJsonGuardrail, createManageTodoTool, createOpenSkillTool, createParallelTool, createProvider, createRegexGuardrail, createResolverNode, createSearchSkillsTool, createSkillRegistryRef, createSkillTools, createSmartAgent, createSpawnTool, createSubagentRegistryRef, createSubagentTools, createTool, createToolLimitFinalizeNode, createToolsNode, customCallbackRule, customSink, dedupeToolsByName, defaultTokenCounter, detectTextFormat, detectVolatileContent, digestToolInputArguments, digestToolInputValue, emptyUsage, evaluateGuardrails, extractLatestUserQuery, fileSink, findSubagent, formatZodError, fromLangchainModel, fromLangchainTools, fromNativeProvider, generateSpanId, generateTraceId, getModelCapabilities, getNestedValue, getResolvedSmartConfig, getTokenCounter, hasToolResponseRecoveryReference, httpSink, isSmartModel, jsonSchemaRule, loadSkillsFromDisk, normalizeSmartAgentOptions, otlpSink, parseSkillFrontmatter, preopenSkills, preopenToolCallId, readMemoryFacts, regexRule, resolveAvailableSkills, resolveAvailableSubagents, resolveInputRetention, resolveMemoryStore, resolveReasoning, resolveStrategy, resolveSubagentTools, resolveSummarizationRetention, resolveToolApprovalState, resolveUserQuestionState, restoreSnapshot, runSmartAgentEvalHarness, scoreItemsByRelevance, searchSkills, seedChildMessages, selectTopIndicesInOrder, setTokenCounter, startStreamingSession, summarizeObject, tokenize, traceSessionToOtlp, validateReasoningConfig, validateToolArgs, withTools, withinDepth, writeSummaryFactsToMemory };
+export { type AIMessage, ASK_USER_TOOL_NAME, type AgentInstance, type AgentInvokeResult, type AgentLimits, type AgentOptions, type AgentRuleOptions, type AgentRuntimeConfig, type AgentSnapshot, type AgentSnapshotMetadata, type AgentState, AnthropicProvider, type AnthropicProviderConfig, type AudioContent, AzureProvider, type AzureProviderConfig, type BaseChatMessage, type BaseChatMessagePart, type BaseChatModel, type BaseMessage, BaseProvider, BedrockProvider, type BedrockProviderConfig, type BuildChildConfig, type BuiltInRuntimeProfile, CCRStore, CONTEXT_PILOT_JSON_MARKER_KEY, CONTROL_PLANE_TOOL_NAMES, type CancellationTokenLike, type CancelledEvent, type ChatCompletionChunk, type ChatCompletionRequest, type ChatCompletionResponse, type ChildContextPolicy, type CodeDetectionRuleOptions, type CodeGuardrailOptions, type CompressToolOutputParams, type ContextPilotCCRConfig, type ContextPilotCacheAlignmentConfig, type ContextPilotCompressionConfig, type ContextPilotCompressionStats, type ContextPilotCompressorKind, type ContextPilotConfig, type ContextPilotDedupConfig, type ContextPilotDiffCompressionConfig, type ContextPilotJsonCompressionConfig, type ContextPilotLogCompressionConfig, type ContextPilotResult, type ContextPilotRuntime, type ContextPilotSearchCompressionConfig, type ContextPilotTextCompressionConfig, type ContextPolicy, type ContextToolsStateRef, type ConversationGuardrail, type CustomRuleCallback, type CustomRuleOptions, DEFAULT_MAX_TOOL_INPUT_FIELD_CHARS, DEFAULT_PROFILE_CONFIGS, DEFAULT_SKILL_POLICY, DEFAULT_SUBAGENT_POLICY, DEFAULT_SUBAGENT_TOOL_NAMES, DEFAULT_TOOL_INPUT_DIGEST_HEAD_CHARS, DELEGATION_TOOL_NAMES, DedupTracker, type DelegationEventStamp, type DelegationMode, type EvalCase, type EvalCaseResult, type EvalFamily, type EvalHarnessMetrics, type EvalHarnessParams, type EvalHarnessResult, type EvalProfileDescriptor, type EvalProfileTarget, type FileContent, type FinalAnswerEvent, type FinishReason, type GuardrailContext, type GuardrailDisposition, type GuardrailEvent, type GuardrailIncident, type GuardrailOutcome, GuardrailPhase, type GuardrailRule, type HandoffDescriptor, type HandoffEvent, type HumanInTheLoopAskUserConfig, type HumanInTheLoopOptions, type HumanInTheLoopRuntimeConfig, type ImageContent, InMemoryMemoryStore, type InvokeConfig, type JsonGuardrailOptions, type JsonSchemaRuleOptions, type LoadSkillsOptions, type MemoryFact, type MemoryProviderKind, type MemoryReadPolicy, type MemoryScope, type MemoryStore, type MemoryWritePolicy, type Message, type MetadataEvent, type ModelCapabilities, NativeJsonSchemaStrategy, type NativeModelOptions, type NativeReasoningConfig, OpenAICompatibleProvider, type OpenAICompatibleProviderConfig, OpenAIProvider, type OpenAIProviderConfig, PREOPEN_TOOL_CALL_PREFIX, type PendingToolApproval, type PendingUserQuestion, type PlanEvent, type PlanStepRecord, type PlanningMode, type PreopenSkillsResult, type ProfileConfig, type ProgressEvent, type ProgressUpdate, type PromptHooks, type ProviderConfig, ProviderError, type ToolCall as ProviderToolCall, type ToolDefinition as ProviderToolDefinition, type ProviderType, type ReasoningConfig, type ReasoningLevel, type ReflectionCadence, type ReflectionConfig, type ReflectionEvent, type ReflectionHookContext, type ReflectionRecord, type RegexGuardrailOptions, type RegexRuleOptions, type ReplanPolicy, type ResolvedContextPilotConfig, type ResolvedSmartAgentConfig, type ResolvedTraceConfig, type ResolvedTraceSink, type RestoreSnapshotOptions, type RuntimeProfile, SMALL_TIER_SKILL_POLICY, type SerializableSmartState, type Skill, type SkillDisclosure, type SkillExecutionContext, type SkillFrontmatter, type SkillFs, type SkillModelTier, type SkillPolicy, type SkillRegistryRef, type SkillToolDeps, type SkillToolHeader, type SmartAgentBudgetConfig, type SmartAgentContextConfig, type SmartAgentCustomProfileConfig, type SmartAgentDelegationConfig, type SmartAgentEvent, type SmartAgentInstance, type SmartAgentLimits, type SmartAgentMemoryConfig, type SmartAgentOptions, type SmartAgentPlanningConfig, type SmartAgentSummarizationConfig, type SmartAgentToolResponseConfig, type SmartAgentTracingConfig, type SmartModel, type SmartState, type SmartToolFn, type SnapshotOptions, type SnapshotRuntimeHint, type StreamChunk, type StreamEvent, type StructuredOutputError, type StructuredOutputFieldError, StructuredOutputManager, type StructuredOutputManagerConfig, type StructuredOutputResult, type StructuredOutputStrategy, type StructuredSummary, type SubagentDef, type SubagentEvent, type SubagentMode, type SubagentPendingRecord, type SubagentPolicy, type SubagentRegistryRef, type SubagentResult, type SubagentToolDeps, type SubagentToolNames, type SummarizationEvent, type SummarizationMode, type SummaryFactItem, type SummaryIntegrityCheck, TOOL_INPUT_DIGEST_KEY, type TextContent, type TokenCounter, type TokenUsage, type ToolApprovalEvent, type ToolApprovalResolution, type ToolApprovalStatus, ToolBasedStrategy, type ToolCachePolicy, type ToolCallEvent, type ToolInputDigestOptions, type ToolInputDigestResult, type ToolInputRetentionPolicy, type ToolInterface, type ToolResponseClassification, type ToolResponseRetentionPolicy, type ToolRetentionDeclarations, type ToolRetentionSpec, type ToolRetryPolicy, type TraceDataSection, type TraceErrorRecord, type TraceEventRecord, type TraceMessageSection, type TraceMetadataSection, type TraceSessionConfigSnapshot, type TraceSessionFile, type TraceSessionStatus, type TraceSessionSummary, type TraceSinkCognipeerConfig, type TraceSinkConfig, type TraceSinkCustomConfig, type TraceSinkFileConfig, type TraceSinkHttpConfig, type TraceSinkOtlpConfig, type TraceSinkSnapshot, type TraceSummarySection, type TraceToolCallSection, type TraceToolDefinition, type TraceToolDefinitionsSection, type TraceToolDetails, type TraceToolResponseSection, type TraceToolResultSection, type TracingConfig, type TracingMode, type UnifiedMessage, type UserQuestionAnswer, type UserQuestionAnswerSet, type UserQuestionEvent, type UserQuestionItem, type UserQuestionOption, type UserQuestionResolution, type UserQuestionStatus, VertexProvider, type VertexProviderConfig, type VolatileContentFinding, type VolatileContentPattern, agentVerdictRule, appendBoundTools, buildResponseFormatSection, buildSkillHeaderBlock, buildSubagentCatalogBlock, buildSystemPrompt, buildToolDefinitionsSection, canOpenSkill, canSpawn, captureSnapshot, codePresenceRule, coerceToolArgs, cognipeerSink, collectToolRetentionDeclarations, composeToolSets, compressDiffOutput, compressJsonOutput, compressLogOutput, compressSearchOutput, compressTextOutput, compressToolOutput, countApproxTokens, countMessagesTokens, createAgent, createAgentNode, createAskUserQuestionTool, createBindSkillToolsTool, createCodeGuardrail, createContextPilotRuntime, createContextSummarizeNode, createContextTools, createDelegateTool, createGetToolResponseTool, createGuardrail, createJsonGuardrail, createManageTodoTool, createOpenSkillTool, createParallelTool, createProvider, createRegexGuardrail, createResolverNode, createSearchSkillsTool, createSkillRegistryRef, createSkillTools, createSmartAgent, createSpawnTool, createSubagentRegistryRef, createSubagentTools, createTool, createToolLimitFinalizeNode, createToolsNode, customCallbackRule, customSink, dedupeToolsByName, defaultTokenCounter, detectTextFormat, detectVolatileContent, digestToolInputArguments, digestToolInputValue, emptyUsage, evaluateGuardrails, extractLatestUserQuery, fileSink, findSubagent, formatZodError, fromLangchainModel, fromLangchainTools, fromNativeProvider, generateSpanId, generateTraceId, getModelCapabilities, getNestedValue, getResolvedSmartConfig, getTokenCounter, hasToolResponseRecoveryReference, httpSink, isSmartModel, jsonSchemaRule, loadSkillsFromDisk, normalizeSmartAgentOptions, otlpSink, parseSkillFrontmatter, preopenSkills, preopenToolCallId, readMemoryFacts, regexRule, resolveAvailableSkills, resolveAvailableSubagents, resolveInputRetention, resolveMemoryStore, resolveReasoning, resolveStrategy, resolveSubagentTools, resolveSummarizationRetention, resolveToolApprovalState, resolveUserQuestionState, restoreSnapshot, runSmartAgentEvalHarness, scoreItemsByRelevance, searchSkills, seedChildMessages, selectTopIndicesInOrder, setTokenCounter, startStreamingSession, summarizeObject, tokenize, traceSessionToOtlp, validateReasoningConfig, validateToolArgs, withTools, withinDepth, writeSummaryFactsToMemory };