@cognipeer/agent-sdk 0.5.4 → 0.6.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.cts CHANGED
@@ -254,13 +254,55 @@ type AgentOptions = {
254
254
  usageConverter?: (finalMessage: AIMessage, fullState: SmartState, model: any) => any;
255
255
  outputSchema?: ZodSchema<any>;
256
256
  tracing?: TracingConfig;
257
+ /**
258
+ * Unified reasoning configuration. Controls both:
259
+ * - Provider-native reasoning (OpenAI reasoning_effort, Anthropic thinking, Gemini thinkingConfig)
260
+ * - Post-turn reflection (a short textual insight from the model after each tool turn)
261
+ *
262
+ * When omitted or `enabled=false` the agent behaves exactly as before.
263
+ */
264
+ reasoning?: ReasoningConfig;
265
+ };
266
+ type ReasoningLevel = "low" | "medium" | "high";
267
+ type ReflectionCadence = "off" | "every_turn" | "after_tool" | "on_branch";
268
+ type ReflectionConfig = {
269
+ enabled?: boolean;
270
+ cadence?: ReflectionCadence;
271
+ /**
272
+ * - "piggyback" (default) — appends a short user-style "reflect now" message to the existing
273
+ * transcript, reusing provider prompt cache. No tools. Returned text becomes a reflection record.
274
+ * - "separate" — dedicated tool-free call with a compact prompt (cheaper, smaller cache hit).
275
+ */
276
+ mode?: "piggyback" | "separate";
277
+ maxTokens?: number;
278
+ maxChars?: number;
279
+ keepLast?: number;
280
+ /** When true reflection messages are compressible by the summarizer. Default false. */
281
+ summarize?: boolean;
282
+ promptTemplate?: string;
283
+ /** When true emits `reflection` SmartAgent events. Default true. */
284
+ emitEvents?: boolean;
285
+ };
286
+ type NativeReasoningConfig = {
287
+ effort?: "minimal" | "low" | "medium" | "high";
288
+ budgetTokens?: number;
289
+ includeThoughts?: boolean;
290
+ providerExtras?: Record<string, any>;
291
+ };
292
+ type ReasoningConfig = {
293
+ enabled?: boolean;
294
+ level?: ReasoningLevel;
295
+ /** Pass `false` to disable provider-native reasoning while keeping reflection. */
296
+ native?: NativeReasoningConfig | false;
297
+ /** Pass `false` to fully disable reflection. */
298
+ reflection?: ReflectionConfig | false;
257
299
  };
258
300
  type BuiltInRuntimeProfile = "fast" | "balanced" | "deep" | "research";
259
301
  type RuntimeProfile = BuiltInRuntimeProfile | "custom";
260
302
  type SummarizationMode = "incremental" | "full_rewrite";
261
303
  type ContextPolicy = "raw" | "summary_only" | "hybrid";
262
304
  type ToolResponseRetentionPolicy = "keep_full" | "keep_structured" | "summarize_archive" | "drop";
263
- type ToolResponseClassification = "critical" | "small" | "informative" | "verbose" | "redundant";
305
+ type ToolResponseClassification = "critical" | "informative" | "verbose";
264
306
  type PlanningMode = "off" | "todo" | "planner_executor" | "reasoning_then_tools";
265
307
  type ReplanPolicy = "never" | "on_failure" | "on_conflict" | "every_n_steps";
266
308
  type DelegationMode = "off" | "role_based" | "automatic";
@@ -366,32 +408,30 @@ type SmartAgentMemoryConfig = {
366
408
  readPolicy?: MemoryReadPolicy;
367
409
  };
368
410
  type SmartAgentToolResponseConfig = {
369
- /** Upper threshold for marking a response as "verbose" (large). */
411
+ /**
412
+ * Hard cap (in characters) applied at tool execution time to a single response.
413
+ * Anything larger is truncated immediately with a get_tool_response retrieval hint
414
+ * so a single oversized payload cannot blow up the next model call. Critical
415
+ * tools are exempt from this cap.
416
+ */
370
417
  maxToolResponseChars?: number;
371
- /** Upper threshold (in approx. tokens) for marking a response as "verbose". */
418
+ /** Hard cap (approx. tokens) for the same eager truncation rule. */
372
419
  maxToolResponseTokens?: number;
373
- /** Lower threshold for marking a response as "small". 0 disables the small tier. */
374
- smallResponseChars?: number;
375
- /** Policy applied to responses classified as "small". Defaults to keep_full. */
376
- smallResponsePolicy?: ToolResponseRetentionPolicy;
377
- /** Policy applied to mid-sized "informative" responses. */
420
+ /**
421
+ * Retention policy applied to all non-critical tool responses by the summarizer
422
+ * when it fires (context limit reached). Has no effect at execution time.
423
+ * Defaults to "summarize_archive".
424
+ */
378
425
  defaultPolicy?: ToolResponseRetentionPolicy;
379
- /** Policy applied when a response exceeds the verbose thresholds. */
380
- largeResponsePolicy?: ToolResponseRetentionPolicy;
381
- /** Per-tool override map. Wins over size-based classification. */
426
+ /**
427
+ * Per-tool override of the summarizer retention policy. Wins over `defaultPolicy`.
428
+ * Critical tools cannot be reduced regardless of override.
429
+ */
382
430
  toolResponseRetentionByTool?: Record<string, ToolResponseRetentionPolicy>;
383
- /** Tool names always treated as critical (resolved via fallbackPolicy). */
431
+ /** Tool names whose responses are never reduced by the summarizer or hard cap. */
384
432
  criticalTools?: string[];
385
433
  schemaValidation?: "strict" | "warn";
386
434
  retryOnSchemaError?: boolean;
387
- /** Policy applied to critical tools. Should default to keep_full so critical payloads are never reduced. */
388
- fallbackPolicy?: ToolResponseRetentionPolicy;
389
- /**
390
- * Number of most-recent successful tool responses to render at full content
391
- * regardless of their classification. Older responses still follow their
392
- * resolved policy. 0 disables the recency override. Defaults to 2.
393
- */
394
- keepRecentFullCount?: number;
395
435
  };
396
436
  type SmartAgentCustomProfileConfig = {
397
437
  extends?: BuiltInRuntimeProfile;
@@ -443,6 +483,10 @@ type SmartAgentOptions = {
443
483
  usageConverter?: (finalMessage: AIMessage, fullState: SmartState, model: any) => any;
444
484
  outputSchema?: ZodSchema<any>;
445
485
  tracing?: TracingConfig;
486
+ /**
487
+ * Unified reasoning configuration. Same shape as on `AgentOptions`. See `ReasoningConfig`.
488
+ */
489
+ reasoning?: ReasoningConfig;
446
490
  };
447
491
  type AgentRuntimeConfig = {
448
492
  name?: string;
@@ -741,6 +785,34 @@ type SmartState = AgentState & {
741
785
  adherenceScore?: number;
742
786
  } | null;
743
787
  planVersion?: number;
788
+ /**
789
+ * Post-turn reflection records produced by the reflection node. The SDK keeps the full
790
+ * history here (even when only `keepLast` are re-injected into the prompt) so callers
791
+ * can render them in a task/run timeline.
792
+ */
793
+ reflections?: ReflectionRecord[];
794
+ };
795
+ type ReflectionRecord = {
796
+ id: string;
797
+ turn: number;
798
+ /** Plain-text reflection produced by the model. */
799
+ text: string;
800
+ createdAt: string;
801
+ durationMs?: number;
802
+ /** Index of the last message present when this reflection was taken. */
803
+ anchorMessageIndex?: number;
804
+ /** Trigger cadence that fired this reflection. */
805
+ trigger?: ReflectionCadence;
806
+ /** Token usage for this specific reflection call. */
807
+ usage?: {
808
+ inputTokens?: number;
809
+ outputTokens?: number;
810
+ cachedInputTokens?: number;
811
+ totalTokens?: number;
812
+ reasoningTokens?: number;
813
+ };
814
+ /** Optional tool call ids / names the reflection commented on (for UI linking). */
815
+ toolCallIds?: string[];
744
816
  };
745
817
  type ToolCallEvent = {
746
818
  type: "tool_call";
@@ -920,7 +992,23 @@ type GuardrailEvent = {
920
992
  reason?: string;
921
993
  details?: Record<string, any>;
922
994
  };
923
- type SmartAgentEvent = ToolCallEvent | ToolApprovalEvent | PlanEvent | SummarizationEvent | FinalAnswerEvent | MetadataEvent | HandoffEvent | GuardrailEvent | ProgressEvent | StreamEvent | CancelledEvent;
995
+ type SmartAgentEvent = ToolCallEvent | ToolApprovalEvent | PlanEvent | SummarizationEvent | FinalAnswerEvent | MetadataEvent | HandoffEvent | GuardrailEvent | ProgressEvent | StreamEvent | CancelledEvent | ReflectionEvent;
996
+ type ReflectionEvent = {
997
+ type: "reflection";
998
+ id: string;
999
+ turn: number;
1000
+ text: string;
1001
+ trigger?: ReflectionCadence;
1002
+ durationMs?: number;
1003
+ usage?: {
1004
+ inputTokens?: number;
1005
+ outputTokens?: number;
1006
+ cachedInputTokens?: number;
1007
+ totalTokens?: number;
1008
+ reasoningTokens?: number;
1009
+ };
1010
+ toolCallIds?: string[];
1011
+ };
924
1012
  type CancellationTokenLike = {
925
1013
  readonly isCancellationRequested: boolean;
926
1014
  onCancellationRequested?: (listener: () => void) => {
@@ -1473,6 +1561,28 @@ type ChatCompletionRequest = {
1473
1561
  };
1474
1562
  stream?: boolean;
1475
1563
  extra?: Record<string, any>;
1564
+ /**
1565
+ * Unified native-reasoning request config. Each provider maps this to its
1566
+ * own shape:
1567
+ * - OpenAI o-series: body.reasoning_effort = effort
1568
+ * - OpenAI Responses: body.reasoning = { effort }
1569
+ * - Anthropic: body.thinking = { type: "enabled", budget_tokens }
1570
+ * - Google / Vertex: body.generationConfig.thinkingConfig = { thinkingBudget, includeThoughts }
1571
+ *
1572
+ * Providers silently ignore unsupported fields.
1573
+ */
1574
+ reasoning?: ReasoningRequestConfig;
1575
+ };
1576
+ type ReasoningEffort = "minimal" | "low" | "medium" | "high";
1577
+ type ReasoningRequestConfig = {
1578
+ /** Qualitative effort hint (mapped per-provider). */
1579
+ effort?: ReasoningEffort;
1580
+ /** Explicit per-call token budget for reasoning/thinking. */
1581
+ budgetTokens?: number;
1582
+ /** Whether the provider should expose its reasoning/thought summary to the caller. Default false. */
1583
+ includeThoughts?: boolean;
1584
+ /** Provider-specific passthrough merged on top of the mapped shape. */
1585
+ providerExtras?: Record<string, any>;
1476
1586
  };
1477
1587
  type TokenUsage = {
1478
1588
  inputTokens: number;
@@ -1671,6 +1781,8 @@ type NativeModelOptions = {
1671
1781
  maxTokens?: number;
1672
1782
  /** Provider-specific extras passed on every request */
1673
1783
  extra?: Record<string, any>;
1784
+ /** Unified native reasoning config applied by default (per-call overrides supported). */
1785
+ reasoning?: ReasoningRequestConfig;
1674
1786
  };
1675
1787
  /**
1676
1788
  * Creates a BaseChatModel from a native provider.
@@ -1708,4 +1820,4 @@ declare function fromNativeProvider(provider: BaseProvider, options?: NativeMode
1708
1820
  */
1709
1821
  declare function createProvider(config: ProviderConfig): BaseProvider;
1710
1822
 
1711
- export { type AIMessage, type AgentInstance, type AgentInvokeResult, type AgentLimits, type AgentOptions, type AgentRuleOptions, type AgentRuntimeConfig, type AgentSnapshot, type AgentSnapshotMetadata, type AgentState, AnthropicProvider, type AnthropicProviderConfig, AzureProvider, type AzureProviderConfig, type BaseChatMessage, type BaseChatMessagePart, type BaseChatModel, type BaseMessage, BaseProvider, BedrockProvider, type BedrockProviderConfig, type BuiltInRuntimeProfile, type CancellationTokenLike, type CancelledEvent, type ChatCompletionChunk, type ChatCompletionRequest, type ChatCompletionResponse, type ChildContextPolicy, type CodeDetectionRuleOptions, type CodeGuardrailOptions, type ContextPolicy, type ConversationGuardrail, type CustomRuleCallback, type CustomRuleOptions, DEFAULT_PROFILE_CONFIGS, type DelegationMode, type EvalCase, type EvalCaseResult, type EvalFamily, type EvalHarnessMetrics, type EvalHarnessParams, type EvalHarnessResult, type EvalProfileDescriptor, type EvalProfileTarget, type FinalAnswerEvent, type FinishReason, type GuardrailContext, type GuardrailDisposition, type GuardrailEvent, type GuardrailIncident, type GuardrailOutcome, GuardrailPhase, type GuardrailRule, type HandoffDescriptor, type HandoffEvent, InMemoryMemoryStore, type InvokeConfig, type JsonGuardrailOptions, type JsonSchemaRuleOptions, type MemoryFact, type MemoryProviderKind, type MemoryReadPolicy, type MemoryScope, type MemoryStore, type MemoryWritePolicy, type Message, type MetadataEvent, type ModelCapabilities, NativeJsonSchemaStrategy, type NativeModelOptions, OpenAICompatibleProvider, type OpenAICompatibleProviderConfig, OpenAIProvider, type OpenAIProviderConfig, type PendingToolApproval, type PlanEvent, type PlanStepRecord, type PlanningMode, type ProfileConfig, type ProgressEvent, type ProgressUpdate, type ProviderConfig, ProviderError, type ToolCall as ProviderToolCall, type ToolDefinition as ProviderToolDefinition, type ProviderType, type RegexGuardrailOptions, type RegexRuleOptions, type ReplanPolicy, type ResolvedSmartAgentConfig, type ResolvedTraceConfig, type ResolvedTraceSink, type RestoreSnapshotOptions, type RuntimeProfile, type SerializableSmartState, 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 SummarizationEvent, type SummarizationMode, type SummaryFactItem, type SummaryIntegrityCheck, type TokenUsage, type ToolApprovalEvent, type ToolApprovalResolution, type ToolApprovalStatus, ToolBasedStrategy, type ToolCallEvent, type ToolInterface, type ToolResponseClassification, type ToolResponseRetentionPolicy, 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 TraceToolResultSection, type TracingConfig, type TracingMode, type UnifiedMessage, VertexProvider, type VertexProviderConfig, agentVerdictRule, buildSystemPrompt, captureSnapshot, codePresenceRule, cognipeerSink, countApproxTokens, countMessagesTokens, createAgent, createAgentNode, createCodeGuardrail, createContextSummarizeNode, createContextTools, createGuardrail, createJsonGuardrail, createProvider, createRegexGuardrail, createResolverNode, createSmartAgent, createTool, createToolLimitFinalizeNode, createToolsNode, customCallbackRule, customSink, emptyUsage, evaluateGuardrails, fileSink, formatZodError, fromLangchainModel, fromLangchainTools, fromNativeProvider, generateSpanId, generateTraceId, getModelCapabilities, getNestedValue, getResolvedSmartConfig, httpSink, isSmartModel, jsonSchemaRule, normalizeSmartAgentOptions, otlpSink, readMemoryFacts, regexRule, resolveMemoryStore, resolveStrategy, resolveToolApprovalState, restoreSnapshot, runSmartAgentEvalHarness, startStreamingSession, traceSessionToOtlp, withTools, writeSummaryFactsToMemory };
1823
+ export { type AIMessage, type AgentInstance, type AgentInvokeResult, type AgentLimits, type AgentOptions, type AgentRuleOptions, type AgentRuntimeConfig, type AgentSnapshot, type AgentSnapshotMetadata, type AgentState, AnthropicProvider, type AnthropicProviderConfig, AzureProvider, type AzureProviderConfig, type BaseChatMessage, type BaseChatMessagePart, type BaseChatModel, type BaseMessage, BaseProvider, BedrockProvider, type BedrockProviderConfig, type BuiltInRuntimeProfile, type CancellationTokenLike, type CancelledEvent, type ChatCompletionChunk, type ChatCompletionRequest, type ChatCompletionResponse, type ChildContextPolicy, type CodeDetectionRuleOptions, type CodeGuardrailOptions, type ContextPolicy, type ConversationGuardrail, type CustomRuleCallback, type CustomRuleOptions, DEFAULT_PROFILE_CONFIGS, type DelegationMode, type EvalCase, type EvalCaseResult, type EvalFamily, type EvalHarnessMetrics, type EvalHarnessParams, type EvalHarnessResult, type EvalProfileDescriptor, type EvalProfileTarget, type FinalAnswerEvent, type FinishReason, type GuardrailContext, type GuardrailDisposition, type GuardrailEvent, type GuardrailIncident, type GuardrailOutcome, GuardrailPhase, type GuardrailRule, type HandoffDescriptor, type HandoffEvent, InMemoryMemoryStore, type InvokeConfig, type JsonGuardrailOptions, type JsonSchemaRuleOptions, 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, type PendingToolApproval, type PlanEvent, type PlanStepRecord, type PlanningMode, type ProfileConfig, type ProgressEvent, type ProgressUpdate, type ProviderConfig, ProviderError, type ToolCall as ProviderToolCall, type ToolDefinition as ProviderToolDefinition, type ProviderType, type ReasoningConfig, type ReasoningLevel, type ReflectionCadence, type ReflectionConfig, type ReflectionEvent, type ReflectionRecord, type RegexGuardrailOptions, type RegexRuleOptions, type ReplanPolicy, type ResolvedSmartAgentConfig, type ResolvedTraceConfig, type ResolvedTraceSink, type RestoreSnapshotOptions, type RuntimeProfile, type SerializableSmartState, 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 SummarizationEvent, type SummarizationMode, type SummaryFactItem, type SummaryIntegrityCheck, type TokenUsage, type ToolApprovalEvent, type ToolApprovalResolution, type ToolApprovalStatus, ToolBasedStrategy, type ToolCallEvent, type ToolInterface, type ToolResponseClassification, type ToolResponseRetentionPolicy, 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 TraceToolResultSection, type TracingConfig, type TracingMode, type UnifiedMessage, VertexProvider, type VertexProviderConfig, agentVerdictRule, buildSystemPrompt, captureSnapshot, codePresenceRule, cognipeerSink, countApproxTokens, countMessagesTokens, createAgent, createAgentNode, createCodeGuardrail, createContextSummarizeNode, createContextTools, createGuardrail, createJsonGuardrail, createProvider, createRegexGuardrail, createResolverNode, createSmartAgent, createTool, createToolLimitFinalizeNode, createToolsNode, customCallbackRule, customSink, emptyUsage, evaluateGuardrails, fileSink, formatZodError, fromLangchainModel, fromLangchainTools, fromNativeProvider, generateSpanId, generateTraceId, getModelCapabilities, getNestedValue, getResolvedSmartConfig, httpSink, isSmartModel, jsonSchemaRule, normalizeSmartAgentOptions, otlpSink, readMemoryFacts, regexRule, resolveMemoryStore, resolveStrategy, resolveToolApprovalState, restoreSnapshot, runSmartAgentEvalHarness, startStreamingSession, traceSessionToOtlp, withTools, writeSummaryFactsToMemory };
package/dist/index.d.ts CHANGED
@@ -254,13 +254,55 @@ type AgentOptions = {
254
254
  usageConverter?: (finalMessage: AIMessage, fullState: SmartState, model: any) => any;
255
255
  outputSchema?: ZodSchema<any>;
256
256
  tracing?: TracingConfig;
257
+ /**
258
+ * Unified reasoning configuration. Controls both:
259
+ * - Provider-native reasoning (OpenAI reasoning_effort, Anthropic thinking, Gemini thinkingConfig)
260
+ * - Post-turn reflection (a short textual insight from the model after each tool turn)
261
+ *
262
+ * When omitted or `enabled=false` the agent behaves exactly as before.
263
+ */
264
+ reasoning?: ReasoningConfig;
265
+ };
266
+ type ReasoningLevel = "low" | "medium" | "high";
267
+ type ReflectionCadence = "off" | "every_turn" | "after_tool" | "on_branch";
268
+ type ReflectionConfig = {
269
+ enabled?: boolean;
270
+ cadence?: ReflectionCadence;
271
+ /**
272
+ * - "piggyback" (default) — appends a short user-style "reflect now" message to the existing
273
+ * transcript, reusing provider prompt cache. No tools. Returned text becomes a reflection record.
274
+ * - "separate" — dedicated tool-free call with a compact prompt (cheaper, smaller cache hit).
275
+ */
276
+ mode?: "piggyback" | "separate";
277
+ maxTokens?: number;
278
+ maxChars?: number;
279
+ keepLast?: number;
280
+ /** When true reflection messages are compressible by the summarizer. Default false. */
281
+ summarize?: boolean;
282
+ promptTemplate?: string;
283
+ /** When true emits `reflection` SmartAgent events. Default true. */
284
+ emitEvents?: boolean;
285
+ };
286
+ type NativeReasoningConfig = {
287
+ effort?: "minimal" | "low" | "medium" | "high";
288
+ budgetTokens?: number;
289
+ includeThoughts?: boolean;
290
+ providerExtras?: Record<string, any>;
291
+ };
292
+ type ReasoningConfig = {
293
+ enabled?: boolean;
294
+ level?: ReasoningLevel;
295
+ /** Pass `false` to disable provider-native reasoning while keeping reflection. */
296
+ native?: NativeReasoningConfig | false;
297
+ /** Pass `false` to fully disable reflection. */
298
+ reflection?: ReflectionConfig | false;
257
299
  };
258
300
  type BuiltInRuntimeProfile = "fast" | "balanced" | "deep" | "research";
259
301
  type RuntimeProfile = BuiltInRuntimeProfile | "custom";
260
302
  type SummarizationMode = "incremental" | "full_rewrite";
261
303
  type ContextPolicy = "raw" | "summary_only" | "hybrid";
262
304
  type ToolResponseRetentionPolicy = "keep_full" | "keep_structured" | "summarize_archive" | "drop";
263
- type ToolResponseClassification = "critical" | "small" | "informative" | "verbose" | "redundant";
305
+ type ToolResponseClassification = "critical" | "informative" | "verbose";
264
306
  type PlanningMode = "off" | "todo" | "planner_executor" | "reasoning_then_tools";
265
307
  type ReplanPolicy = "never" | "on_failure" | "on_conflict" | "every_n_steps";
266
308
  type DelegationMode = "off" | "role_based" | "automatic";
@@ -366,32 +408,30 @@ type SmartAgentMemoryConfig = {
366
408
  readPolicy?: MemoryReadPolicy;
367
409
  };
368
410
  type SmartAgentToolResponseConfig = {
369
- /** Upper threshold for marking a response as "verbose" (large). */
411
+ /**
412
+ * Hard cap (in characters) applied at tool execution time to a single response.
413
+ * Anything larger is truncated immediately with a get_tool_response retrieval hint
414
+ * so a single oversized payload cannot blow up the next model call. Critical
415
+ * tools are exempt from this cap.
416
+ */
370
417
  maxToolResponseChars?: number;
371
- /** Upper threshold (in approx. tokens) for marking a response as "verbose". */
418
+ /** Hard cap (approx. tokens) for the same eager truncation rule. */
372
419
  maxToolResponseTokens?: number;
373
- /** Lower threshold for marking a response as "small". 0 disables the small tier. */
374
- smallResponseChars?: number;
375
- /** Policy applied to responses classified as "small". Defaults to keep_full. */
376
- smallResponsePolicy?: ToolResponseRetentionPolicy;
377
- /** Policy applied to mid-sized "informative" responses. */
420
+ /**
421
+ * Retention policy applied to all non-critical tool responses by the summarizer
422
+ * when it fires (context limit reached). Has no effect at execution time.
423
+ * Defaults to "summarize_archive".
424
+ */
378
425
  defaultPolicy?: ToolResponseRetentionPolicy;
379
- /** Policy applied when a response exceeds the verbose thresholds. */
380
- largeResponsePolicy?: ToolResponseRetentionPolicy;
381
- /** Per-tool override map. Wins over size-based classification. */
426
+ /**
427
+ * Per-tool override of the summarizer retention policy. Wins over `defaultPolicy`.
428
+ * Critical tools cannot be reduced regardless of override.
429
+ */
382
430
  toolResponseRetentionByTool?: Record<string, ToolResponseRetentionPolicy>;
383
- /** Tool names always treated as critical (resolved via fallbackPolicy). */
431
+ /** Tool names whose responses are never reduced by the summarizer or hard cap. */
384
432
  criticalTools?: string[];
385
433
  schemaValidation?: "strict" | "warn";
386
434
  retryOnSchemaError?: boolean;
387
- /** Policy applied to critical tools. Should default to keep_full so critical payloads are never reduced. */
388
- fallbackPolicy?: ToolResponseRetentionPolicy;
389
- /**
390
- * Number of most-recent successful tool responses to render at full content
391
- * regardless of their classification. Older responses still follow their
392
- * resolved policy. 0 disables the recency override. Defaults to 2.
393
- */
394
- keepRecentFullCount?: number;
395
435
  };
396
436
  type SmartAgentCustomProfileConfig = {
397
437
  extends?: BuiltInRuntimeProfile;
@@ -443,6 +483,10 @@ type SmartAgentOptions = {
443
483
  usageConverter?: (finalMessage: AIMessage, fullState: SmartState, model: any) => any;
444
484
  outputSchema?: ZodSchema<any>;
445
485
  tracing?: TracingConfig;
486
+ /**
487
+ * Unified reasoning configuration. Same shape as on `AgentOptions`. See `ReasoningConfig`.
488
+ */
489
+ reasoning?: ReasoningConfig;
446
490
  };
447
491
  type AgentRuntimeConfig = {
448
492
  name?: string;
@@ -741,6 +785,34 @@ type SmartState = AgentState & {
741
785
  adherenceScore?: number;
742
786
  } | null;
743
787
  planVersion?: number;
788
+ /**
789
+ * Post-turn reflection records produced by the reflection node. The SDK keeps the full
790
+ * history here (even when only `keepLast` are re-injected into the prompt) so callers
791
+ * can render them in a task/run timeline.
792
+ */
793
+ reflections?: ReflectionRecord[];
794
+ };
795
+ type ReflectionRecord = {
796
+ id: string;
797
+ turn: number;
798
+ /** Plain-text reflection produced by the model. */
799
+ text: string;
800
+ createdAt: string;
801
+ durationMs?: number;
802
+ /** Index of the last message present when this reflection was taken. */
803
+ anchorMessageIndex?: number;
804
+ /** Trigger cadence that fired this reflection. */
805
+ trigger?: ReflectionCadence;
806
+ /** Token usage for this specific reflection call. */
807
+ usage?: {
808
+ inputTokens?: number;
809
+ outputTokens?: number;
810
+ cachedInputTokens?: number;
811
+ totalTokens?: number;
812
+ reasoningTokens?: number;
813
+ };
814
+ /** Optional tool call ids / names the reflection commented on (for UI linking). */
815
+ toolCallIds?: string[];
744
816
  };
745
817
  type ToolCallEvent = {
746
818
  type: "tool_call";
@@ -920,7 +992,23 @@ type GuardrailEvent = {
920
992
  reason?: string;
921
993
  details?: Record<string, any>;
922
994
  };
923
- type SmartAgentEvent = ToolCallEvent | ToolApprovalEvent | PlanEvent | SummarizationEvent | FinalAnswerEvent | MetadataEvent | HandoffEvent | GuardrailEvent | ProgressEvent | StreamEvent | CancelledEvent;
995
+ type SmartAgentEvent = ToolCallEvent | ToolApprovalEvent | PlanEvent | SummarizationEvent | FinalAnswerEvent | MetadataEvent | HandoffEvent | GuardrailEvent | ProgressEvent | StreamEvent | CancelledEvent | ReflectionEvent;
996
+ type ReflectionEvent = {
997
+ type: "reflection";
998
+ id: string;
999
+ turn: number;
1000
+ text: string;
1001
+ trigger?: ReflectionCadence;
1002
+ durationMs?: number;
1003
+ usage?: {
1004
+ inputTokens?: number;
1005
+ outputTokens?: number;
1006
+ cachedInputTokens?: number;
1007
+ totalTokens?: number;
1008
+ reasoningTokens?: number;
1009
+ };
1010
+ toolCallIds?: string[];
1011
+ };
924
1012
  type CancellationTokenLike = {
925
1013
  readonly isCancellationRequested: boolean;
926
1014
  onCancellationRequested?: (listener: () => void) => {
@@ -1473,6 +1561,28 @@ type ChatCompletionRequest = {
1473
1561
  };
1474
1562
  stream?: boolean;
1475
1563
  extra?: Record<string, any>;
1564
+ /**
1565
+ * Unified native-reasoning request config. Each provider maps this to its
1566
+ * own shape:
1567
+ * - OpenAI o-series: body.reasoning_effort = effort
1568
+ * - OpenAI Responses: body.reasoning = { effort }
1569
+ * - Anthropic: body.thinking = { type: "enabled", budget_tokens }
1570
+ * - Google / Vertex: body.generationConfig.thinkingConfig = { thinkingBudget, includeThoughts }
1571
+ *
1572
+ * Providers silently ignore unsupported fields.
1573
+ */
1574
+ reasoning?: ReasoningRequestConfig;
1575
+ };
1576
+ type ReasoningEffort = "minimal" | "low" | "medium" | "high";
1577
+ type ReasoningRequestConfig = {
1578
+ /** Qualitative effort hint (mapped per-provider). */
1579
+ effort?: ReasoningEffort;
1580
+ /** Explicit per-call token budget for reasoning/thinking. */
1581
+ budgetTokens?: number;
1582
+ /** Whether the provider should expose its reasoning/thought summary to the caller. Default false. */
1583
+ includeThoughts?: boolean;
1584
+ /** Provider-specific passthrough merged on top of the mapped shape. */
1585
+ providerExtras?: Record<string, any>;
1476
1586
  };
1477
1587
  type TokenUsage = {
1478
1588
  inputTokens: number;
@@ -1671,6 +1781,8 @@ type NativeModelOptions = {
1671
1781
  maxTokens?: number;
1672
1782
  /** Provider-specific extras passed on every request */
1673
1783
  extra?: Record<string, any>;
1784
+ /** Unified native reasoning config applied by default (per-call overrides supported). */
1785
+ reasoning?: ReasoningRequestConfig;
1674
1786
  };
1675
1787
  /**
1676
1788
  * Creates a BaseChatModel from a native provider.
@@ -1708,4 +1820,4 @@ declare function fromNativeProvider(provider: BaseProvider, options?: NativeMode
1708
1820
  */
1709
1821
  declare function createProvider(config: ProviderConfig): BaseProvider;
1710
1822
 
1711
- export { type AIMessage, type AgentInstance, type AgentInvokeResult, type AgentLimits, type AgentOptions, type AgentRuleOptions, type AgentRuntimeConfig, type AgentSnapshot, type AgentSnapshotMetadata, type AgentState, AnthropicProvider, type AnthropicProviderConfig, AzureProvider, type AzureProviderConfig, type BaseChatMessage, type BaseChatMessagePart, type BaseChatModel, type BaseMessage, BaseProvider, BedrockProvider, type BedrockProviderConfig, type BuiltInRuntimeProfile, type CancellationTokenLike, type CancelledEvent, type ChatCompletionChunk, type ChatCompletionRequest, type ChatCompletionResponse, type ChildContextPolicy, type CodeDetectionRuleOptions, type CodeGuardrailOptions, type ContextPolicy, type ConversationGuardrail, type CustomRuleCallback, type CustomRuleOptions, DEFAULT_PROFILE_CONFIGS, type DelegationMode, type EvalCase, type EvalCaseResult, type EvalFamily, type EvalHarnessMetrics, type EvalHarnessParams, type EvalHarnessResult, type EvalProfileDescriptor, type EvalProfileTarget, type FinalAnswerEvent, type FinishReason, type GuardrailContext, type GuardrailDisposition, type GuardrailEvent, type GuardrailIncident, type GuardrailOutcome, GuardrailPhase, type GuardrailRule, type HandoffDescriptor, type HandoffEvent, InMemoryMemoryStore, type InvokeConfig, type JsonGuardrailOptions, type JsonSchemaRuleOptions, type MemoryFact, type MemoryProviderKind, type MemoryReadPolicy, type MemoryScope, type MemoryStore, type MemoryWritePolicy, type Message, type MetadataEvent, type ModelCapabilities, NativeJsonSchemaStrategy, type NativeModelOptions, OpenAICompatibleProvider, type OpenAICompatibleProviderConfig, OpenAIProvider, type OpenAIProviderConfig, type PendingToolApproval, type PlanEvent, type PlanStepRecord, type PlanningMode, type ProfileConfig, type ProgressEvent, type ProgressUpdate, type ProviderConfig, ProviderError, type ToolCall as ProviderToolCall, type ToolDefinition as ProviderToolDefinition, type ProviderType, type RegexGuardrailOptions, type RegexRuleOptions, type ReplanPolicy, type ResolvedSmartAgentConfig, type ResolvedTraceConfig, type ResolvedTraceSink, type RestoreSnapshotOptions, type RuntimeProfile, type SerializableSmartState, 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 SummarizationEvent, type SummarizationMode, type SummaryFactItem, type SummaryIntegrityCheck, type TokenUsage, type ToolApprovalEvent, type ToolApprovalResolution, type ToolApprovalStatus, ToolBasedStrategy, type ToolCallEvent, type ToolInterface, type ToolResponseClassification, type ToolResponseRetentionPolicy, 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 TraceToolResultSection, type TracingConfig, type TracingMode, type UnifiedMessage, VertexProvider, type VertexProviderConfig, agentVerdictRule, buildSystemPrompt, captureSnapshot, codePresenceRule, cognipeerSink, countApproxTokens, countMessagesTokens, createAgent, createAgentNode, createCodeGuardrail, createContextSummarizeNode, createContextTools, createGuardrail, createJsonGuardrail, createProvider, createRegexGuardrail, createResolverNode, createSmartAgent, createTool, createToolLimitFinalizeNode, createToolsNode, customCallbackRule, customSink, emptyUsage, evaluateGuardrails, fileSink, formatZodError, fromLangchainModel, fromLangchainTools, fromNativeProvider, generateSpanId, generateTraceId, getModelCapabilities, getNestedValue, getResolvedSmartConfig, httpSink, isSmartModel, jsonSchemaRule, normalizeSmartAgentOptions, otlpSink, readMemoryFacts, regexRule, resolveMemoryStore, resolveStrategy, resolveToolApprovalState, restoreSnapshot, runSmartAgentEvalHarness, startStreamingSession, traceSessionToOtlp, withTools, writeSummaryFactsToMemory };
1823
+ export { type AIMessage, type AgentInstance, type AgentInvokeResult, type AgentLimits, type AgentOptions, type AgentRuleOptions, type AgentRuntimeConfig, type AgentSnapshot, type AgentSnapshotMetadata, type AgentState, AnthropicProvider, type AnthropicProviderConfig, AzureProvider, type AzureProviderConfig, type BaseChatMessage, type BaseChatMessagePart, type BaseChatModel, type BaseMessage, BaseProvider, BedrockProvider, type BedrockProviderConfig, type BuiltInRuntimeProfile, type CancellationTokenLike, type CancelledEvent, type ChatCompletionChunk, type ChatCompletionRequest, type ChatCompletionResponse, type ChildContextPolicy, type CodeDetectionRuleOptions, type CodeGuardrailOptions, type ContextPolicy, type ConversationGuardrail, type CustomRuleCallback, type CustomRuleOptions, DEFAULT_PROFILE_CONFIGS, type DelegationMode, type EvalCase, type EvalCaseResult, type EvalFamily, type EvalHarnessMetrics, type EvalHarnessParams, type EvalHarnessResult, type EvalProfileDescriptor, type EvalProfileTarget, type FinalAnswerEvent, type FinishReason, type GuardrailContext, type GuardrailDisposition, type GuardrailEvent, type GuardrailIncident, type GuardrailOutcome, GuardrailPhase, type GuardrailRule, type HandoffDescriptor, type HandoffEvent, InMemoryMemoryStore, type InvokeConfig, type JsonGuardrailOptions, type JsonSchemaRuleOptions, 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, type PendingToolApproval, type PlanEvent, type PlanStepRecord, type PlanningMode, type ProfileConfig, type ProgressEvent, type ProgressUpdate, type ProviderConfig, ProviderError, type ToolCall as ProviderToolCall, type ToolDefinition as ProviderToolDefinition, type ProviderType, type ReasoningConfig, type ReasoningLevel, type ReflectionCadence, type ReflectionConfig, type ReflectionEvent, type ReflectionRecord, type RegexGuardrailOptions, type RegexRuleOptions, type ReplanPolicy, type ResolvedSmartAgentConfig, type ResolvedTraceConfig, type ResolvedTraceSink, type RestoreSnapshotOptions, type RuntimeProfile, type SerializableSmartState, 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 SummarizationEvent, type SummarizationMode, type SummaryFactItem, type SummaryIntegrityCheck, type TokenUsage, type ToolApprovalEvent, type ToolApprovalResolution, type ToolApprovalStatus, ToolBasedStrategy, type ToolCallEvent, type ToolInterface, type ToolResponseClassification, type ToolResponseRetentionPolicy, 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 TraceToolResultSection, type TracingConfig, type TracingMode, type UnifiedMessage, VertexProvider, type VertexProviderConfig, agentVerdictRule, buildSystemPrompt, captureSnapshot, codePresenceRule, cognipeerSink, countApproxTokens, countMessagesTokens, createAgent, createAgentNode, createCodeGuardrail, createContextSummarizeNode, createContextTools, createGuardrail, createJsonGuardrail, createProvider, createRegexGuardrail, createResolverNode, createSmartAgent, createTool, createToolLimitFinalizeNode, createToolsNode, customCallbackRule, customSink, emptyUsage, evaluateGuardrails, fileSink, formatZodError, fromLangchainModel, fromLangchainTools, fromNativeProvider, generateSpanId, generateTraceId, getModelCapabilities, getNestedValue, getResolvedSmartConfig, httpSink, isSmartModel, jsonSchemaRule, normalizeSmartAgentOptions, otlpSink, readMemoryFacts, regexRule, resolveMemoryStore, resolveStrategy, resolveToolApprovalState, restoreSnapshot, runSmartAgentEvalHarness, startStreamingSession, traceSessionToOtlp, withTools, writeSummaryFactsToMemory };