@cognipeer/agent-sdk 0.1.1 → 0.2.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { ToolInterface as ToolInterface$1 } from '@langchain/core/tools';
-import { ZodSchema } from 'zod';
+import { ZodSchema, z } from 'zod';
+import { JSONSchema7 } from 'json-schema';
 
 interface BaseChatMessagePart {
     type?: string;
@@ -35,22 +35,6 @@ declare function isSmartModel(m: any): m is SmartModel;
 declare function withTools(model: SmartModel, tools: any[]): BaseChatModel;
 declare function fromLangchainModel(lcModel: any): BaseChatModel;
 
-type SmartToolFn = (args: any) => Promise<any> | any;
-declare function createSmartTool({ name, description, schema, func, }: {
-    name: string;
-    description?: string;
-    schema: ZodSchema;
-    func: SmartToolFn;
-}): ToolInterface$1;
-declare function createTool({ name, description, schema, func, }: {
-    name: string;
-    description?: string;
-    schema: ZodSchema;
-    func: SmartToolFn;
-}): ToolInterface$1;
-
-declare function buildSystemPrompt(extra?: string, planning?: boolean, name?: string): string;
-
 type ImageURL = {
     url: string;
     detail?: 'auto' | 'low' | 'high';
@@ -75,6 +59,9 @@ interface ToolInterface<TInput = any, TOutput = any, TCallOptions = any> {
     invoke?: (input: TInput, config?: TCallOptions) => Promise<TOutput> | TOutput;
     call?: (input: TInput, config?: TCallOptions) => Promise<TOutput> | TOutput;
     schema?: any;
+    needsApproval?: boolean;
+    approvalPrompt?: string;
+    approvalDefaults?: any;
     [key: string]: any;
 }
 type RunnableConfig = {
@@ -92,47 +79,289 @@ type AIMessage = BaseMessage & {
     role: 'assistant';
 };
 type Message = BaseMessage;
-type SmartAgentLimits = {
+declare enum GuardrailPhase {
+    Request = "request",
+    Response = "response"
+}
+type GuardrailDisposition = "block" | "warn" | "allow";
+type GuardrailContext = {
+    phase: GuardrailPhase;
+    messages: Message[];
+    latestMessage?: Message;
+    state: SmartState;
+    runtime?: AgentRuntimeConfig;
+    options: SmartAgentOptions;
+};
+type GuardrailRuleResult = {
+    passed: boolean;
+    reason?: string;
+    details?: Record<string, any>;
+    disposition?: GuardrailDisposition;
+};
+type GuardrailRule = {
+    id?: string;
+    title?: string;
+    description?: string;
+    evaluate: (context: GuardrailContext) => Promise<GuardrailRuleResult> | GuardrailRuleResult;
+    metadata?: Record<string, any>;
+};
+type GuardrailIncident = {
+    guardrailId?: string;
+    guardrailTitle?: string;
+    ruleId?: string;
+    ruleTitle?: string;
+    phase: GuardrailPhase;
+    reason?: string;
+    details?: Record<string, any>;
+    disposition: GuardrailDisposition;
+};
+type ConversationGuardrail = {
+    id?: string;
+    title?: string;
+    description?: string;
+    appliesTo: GuardrailPhase[];
+    rules: GuardrailRule[];
+    haltOnViolation?: boolean;
+    onViolation?: (incident: GuardrailIncident, context: GuardrailContext) => Promise<GuardrailDisposition | void> | GuardrailDisposition | void;
+    metadata?: Record<string, any>;
+};
+type GuardrailOutcome = {
+    ok: boolean;
+    incidents: GuardrailIncident[];
+};
+type AgentLimits = {
     maxToolCalls?: number;
-    toolOutputTokenLimit?: number;
-    contextTokenLimit?: number;
-    summaryTokenLimit?: number;
-    summary_token_limit?: number;
-    maxToken?: number;
     maxParallelTools?: number;
 };
+type SmartAgentLimits = AgentLimits;
+type TraceSinkFileConfig = {
+    type: "file";
+    path?: string;
+};
+type TraceSinkCustomConfig = {
+    type: "custom";
+    onEvent?: (event: TraceEventRecord) => void | Promise<void>;
+    onSession?: (session: TraceSessionFile) => void | Promise<void>;
+};
+type TraceSinkCognipeerConfig = {
+    type: "cognipeer";
+    apiKey: string;
+    url?: string;
+};
+type TraceSinkHttpConfig = {
+    type: "http";
+    url: string;
+    headers?: Record<string, string>;
+};
+type TraceSinkConfig = TraceSinkFileConfig | TraceSinkCustomConfig | TraceSinkCognipeerConfig | TraceSinkHttpConfig;
+type TracingConfig = {
+    enabled: boolean;
+    logData?: boolean;
+    sink?: TraceSinkConfig;
+};
+type SmartAgentTracingConfig = TracingConfig;
+type AgentOptions = {
+    name?: string;
+    version?: string;
+    model: any;
+    tools?: Array<ToolInterface<any, any, any>>;
+    guardrails?: ConversationGuardrail[];
+    handoffs?: HandoffDescriptor[];
+    limits?: AgentLimits;
+    usageConverter?: (finalMessage: AIMessage, fullState: SmartState, model: any) => any;
+    outputSchema?: ZodSchema<any>;
+    tracing?: TracingConfig;
+};
 type SmartAgentOptions = {
     name?: string;
+    version?: string;
     model: any;
     tools?: Array<ToolInterface<any, any, any>>;
-    handoffs?: HandoffDescriptor<any, any, any>[];
-    limits?: SmartAgentLimits;
-    summarization?: boolean;
+    guardrails?: ConversationGuardrail[];
+    handoffs?: HandoffDescriptor[];
+    limits?: AgentLimits;
+    summarization?: boolean | {
+        enable: boolean;
+        maxTokens: number;
+    };
     systemPrompt?: string;
     useTodoList?: boolean;
     usageConverter?: (finalMessage: AIMessage, fullState: SmartState, model: any) => any;
-    debug?: {
-        enabled: boolean;
-        path?: string;
-        callback?: (entry: {
-            sessionId: string;
-            stepIndex: number;
-            fileName: string;
-            markdown: string;
-        }) => void;
-    };
     outputSchema?: ZodSchema<any>;
+    tracing?: TracingConfig;
 };
 type AgentRuntimeConfig = {
     name?: string;
+    version?: string;
     model: any;
     tools: Array<ToolInterface<any, any, any>>;
+    guardrails?: ConversationGuardrail[];
     systemPrompt?: string;
-    limits?: SmartAgentLimits;
+    limits?: AgentLimits;
     useTodoList?: boolean;
     outputSchema?: ZodSchema<any>;
+    tracing?: TracingConfig;
+};
+type TraceMessageSection = {
+    id?: string;
+    kind: "message";
+    label: string;
+    role: string;
+    content: string;
+    metadata?: Record<string, any>;
+};
+type TraceToolCallSection = {
+    id?: string;
+    kind: "tool_call";
+    label: string;
+    tool: string;
+    arguments?: any;
+};
+type TraceToolResultItem = {
+    title?: string;
+    url?: string;
+    snippet?: string;
+    [key: string]: any;
+};
+type TraceToolResultSection = {
+    id?: string;
+    kind: "tool_result";
+    label: string;
+    tool: string;
+    summary?: string;
+    items?: TraceToolResultItem[];
+    output?: any;
+};
+type TraceToolResponseSection = {
+    id?: string;
+    kind: "tool_response";
+    label: string;
+    tool: string;
+    summary?: string;
+    items?: TraceToolResultItem[];
+    output?: any;
+};
+type TraceSummarySection = {
+    id?: string;
+    kind: "summary";
+    label: string;
+    content: string;
+};
+type TraceMetadataSection = {
+    id?: string;
+    kind: "metadata";
+    label: string;
+    data: Record<string, any>;
+};
+type TraceDataSection = TraceMessageSection | TraceToolCallSection | TraceToolResultSection | TraceToolResponseSection | TraceSummarySection | TraceMetadataSection;
+type TraceEventRecord = {
+    sessionId: string;
+    id: string;
+    type: string;
+    label: string;
+    sequence: number;
+    timestamp: string;
+    actor?: {
+        scope?: string;
+        name?: string;
+        role?: string;
+        version?: string;
+    };
+    status: "success" | "error" | "skipped" | "retry";
+    durationMs?: number;
+    inputTokens?: number;
+    outputTokens?: number;
+    totalTokens?: number;
+    cachedInputTokens?: number;
+    requestBytes?: number;
+    responseBytes?: number;
+    model?: string;
+    provider?: string;
+    toolExecutionId?: string;
+    retryOf?: string;
+    error?: {
+        message: string;
+        stack?: string;
+    } | null;
+    data?: {
+        sections: TraceDataSection[];
+    };
+    debug?: Record<string, any>;
+};
+type TraceErrorRecord = {
+    eventId: string;
+    message: string;
+    stack?: string;
+    type?: string;
+    timestamp?: string;
+};
+type TraceSessionSummary = {
+    totalDurationMs: number;
+    totalInputTokens: number;
+    totalOutputTokens: number;
+    totalCachedInputTokens: number;
+    totalBytesIn: number;
+    totalBytesOut: number;
+    eventCounts: Record<string, number>;
+};
+type TraceSessionStatus = "in_progress" | "success" | "error" | "partial";
+type TraceSinkSnapshot = {
+    type: "file";
+    path: string;
+} | {
+    type: "custom";
+} | {
+    type: "cognipeer";
+    url: string;
+} | {
+    type: "http";
+    url: string;
 };
-type HandoffDescriptor<TIn = any, TOut = any, TParsed = any> = {
+type TraceSessionConfigSnapshot = {
+    enabled: boolean;
+    logData: boolean;
+    sink: TraceSinkSnapshot;
+};
+type TraceSessionFile = {
+    sessionId: string;
+    startedAt: string;
+    endedAt?: string;
+    durationMs?: number;
+    agent?: {
+        name?: string;
+        version?: string;
+        model?: string;
+        provider?: string;
+    };
+    config: TraceSessionConfigSnapshot;
+    summary: TraceSessionSummary;
+    events: TraceEventRecord[];
+    status: TraceSessionStatus;
+    errors: TraceErrorRecord[];
+};
+type ResolvedTraceSink = {
+    type: "file";
+    baseDir: string;
+} | {
+    type: "custom";
+    onEvent?: (event: TraceEventRecord) => void | Promise<void>;
+    onSession?: (session: TraceSessionFile) => void | Promise<void>;
+} | {
+    type: "cognipeer";
+    url: string;
+    apiKey: string;
+} | {
+    type: "http";
+    url: string;
+    headers?: Record<string, string>;
+};
+type ResolvedTraceConfig = {
+    enabled: boolean;
+    mode: "batched";
+    logData: boolean;
+    sink: ResolvedTraceSink;
+};
+type HandoffDescriptor<TParsed = any> = {
     type: "handoff";
     toolName: string;
     description: string;
@@ -141,10 +370,9 @@ type HandoffDescriptor<TIn = any, TOut = any, TParsed = any> = {
         __runtime: AgentRuntimeConfig;
     };
 };
-type SmartState = {
+type AgentState = {
     messages: Message[];
     agent?: AgentRuntimeConfig;
-    summaries?: string[];
     toolHistory?: Array<{
         executionId: string;
         toolName: string;
@@ -158,6 +386,31 @@ type SmartState = {
         tool_call_id?: string;
         fromCache?: boolean;
     }>;
+    toolCache?: Record<string, any>;
+    toolCallCount?: number;
+    metadata?: Record<string, any>;
+    ctx?: Record<string, any>;
+    pendingApprovals?: PendingToolApproval[];
+    usage?: {
+        perRequest: Array<{
+            id: string;
+            modelName: string;
+            usage: any;
+            timestamp: string;
+            turn: number;
+            cachedInput?: number;
+        }>;
+        totals: Record<string, {
+            input: number;
+            output: number;
+            total: number;
+            cachedInput: number;
+        }>;
+    };
+    guardrailResult?: GuardrailOutcome;
+};
+type SmartState = AgentState & {
+    summaries?: string[];
     toolHistoryArchived?: Array<{
         executionId: string;
         toolName: string;
@@ -171,8 +424,6 @@ type SmartState = {
         tool_call_id?: string;
         fromCache?: boolean;
     }>;
-    toolCache?: Record<string, any>;
-    toolCallCount?: number;
     plan?: {
         version: number;
         steps: Array<{
@@ -183,24 +434,6 @@ type SmartState = {
         lastUpdated?: string;
     } | null;
     planVersion?: number;
-    metadata?: Record<string, any>;
-    ctx?: Record<string, any>;
-    usage?: {
-        perRequest: Array<{
-            id: string;
-            modelName: string;
-            usage: any;
-            timestamp: string;
-            turn: number;
-            cachedInput?: number;
-        }>;
-        totals: Record<string, {
-            input: number;
-            output: number;
-            total: number;
-            cachedInput: number;
-        }>;
-    };
 };
 type ToolCallEvent = {
     type: "tool_call";
@@ -249,9 +482,86 @@ type HandoffEvent = {
     to?: string;
     toolName: string;
 };
-type SmartAgentEvent = ToolCallEvent | PlanEvent | SummarizationEvent | FinalAnswerEvent | MetadataEvent | HandoffEvent;
+type ToolApprovalStatus = "pending" | "approved" | "rejected" | "executed";
+type PendingToolApproval = {
+    id: string;
+    toolCallId: string;
+    toolName: string;
+    args: any;
+    status: ToolApprovalStatus;
+    requestedAt: string;
+    decidedAt?: string;
+    decidedBy?: string;
+    comment?: string;
+    approvedArgs?: any;
+    resolvedAt?: string;
+    executionId?: string;
+    metadata?: Record<string, any>;
+};
+type ToolApprovalResolution = {
+    id: string;
+    approved: boolean;
+    approvedArgs?: any;
+    decidedBy?: string;
+    comment?: string;
+};
+type ToolApprovalEvent = {
+    type: "tool_approval";
+    status: "pending" | "approved" | "rejected";
+    id: string;
+    toolName: string;
+    toolCallId?: string;
+    args?: any;
+    decidedBy?: string;
+    comment?: string;
+};
+type GuardrailEvent = {
+    type: "guardrail";
+    phase: GuardrailPhase;
+    guardrailId?: string;
+    guardrailTitle?: string;
+    ruleId?: string;
+    ruleTitle?: string;
+    disposition: GuardrailDisposition;
+    reason?: string;
+    details?: Record<string, any>;
+};
+type SmartAgentEvent = ToolCallEvent | ToolApprovalEvent | PlanEvent | SummarizationEvent | FinalAnswerEvent | MetadataEvent | HandoffEvent | GuardrailEvent;
 type InvokeConfig = RunnableConfig & {
     onEvent?: (event: SmartAgentEvent) => void;
+    onStateChange?: (state: SmartState) => boolean;
+    checkpointReason?: string;
+};
+type SnapshotRuntimeHint = {
+    name?: string;
+    version?: string;
+    tools?: string[];
+};
+type SerializableSmartState = Omit<SmartState, "agent"> & {
+    agent?: undefined;
+};
+type AgentSnapshotMetadata = {
+    createdAt: string;
+    tag?: string;
+    paused?: {
+        stage?: string;
+        iteration?: number;
+        reason?: string;
+    } | null;
+};
+type AgentSnapshot = {
+    state: SerializableSmartState;
+    runtimeHint?: SnapshotRuntimeHint;
+    metadata: AgentSnapshotMetadata;
+};
+type SnapshotOptions = {
+    tag?: string;
+    includeRuntimeHint?: boolean;
+};
+type RestoreSnapshotOptions = {
+    agent?: AgentRuntimeConfig;
+    ctx?: Record<string, any>;
+    mergeCtx?: boolean;
 };
 type AgentInvokeResult<TOutput = unknown> = {
     content: string;
@@ -262,8 +572,11 @@ type AgentInvokeResult<TOutput = unknown> = {
     messages: Message[];
     state?: SmartState;
 };
-type SmartAgentInstance<TOutput = unknown> = {
+type AgentInstance<TOutput = unknown> = {
     invoke: (input: SmartState, config?: InvokeConfig) => Promise<AgentInvokeResult<TOutput>>;
+    snapshot: (state: SmartState, options?: SnapshotOptions) => AgentSnapshot;
+    resume: (snapshot: AgentSnapshot, config?: InvokeConfig, restoreOptions?: RestoreSnapshotOptions) => Promise<AgentInvokeResult<TOutput>>;
+    resolveToolApproval: (state: SmartState, resolution: ToolApprovalResolution) => SmartState;
     asTool: (opts: {
         toolName: string;
         description?: string;
@@ -273,15 +586,23 @@ type SmartAgentInstance<TOutput = unknown> = {
         toolName?: string;
         description?: string;
         schema?: ZodSchema<any>;
-    }) => HandoffDescriptor<any, any, TOutput>;
+    }) => HandoffDescriptor<TOutput>;
     __runtime: AgentRuntimeConfig;
 };
-type AgentLimits = SmartAgentLimits;
-type AgentOptions = SmartAgentOptions;
-type AgentState = SmartState;
-type AgentEvent = SmartAgentEvent;
-type AgentResult<T = unknown> = AgentInvokeResult<T>;
-type AgentInstance<T = unknown> = SmartAgentInstance<T>;
+type SmartAgentInstance<TOutput = unknown> = AgentInstance<TOutput>;
+
+type SmartToolFn = (args: any) => Promise<any> | any;
+declare function createTool({ name, description, schema, func, needsApproval, approvalPrompt, approvalDefaults, }: {
+    name: string;
+    description?: string;
+    schema: ZodSchema;
+    func: SmartToolFn;
+    needsApproval?: boolean;
+    approvalPrompt?: string;
+    approvalDefaults?: any;
+}): ToolInterface;
+
+declare function buildSystemPrompt(extra?: string, planning?: boolean, name?: string): string;
 
 declare function createAgent<TOutput = unknown>(opts: AgentOptions & {
     outputSchema?: ZodSchema<TOutput>;
@@ -289,24 +610,35 @@ declare function createAgent<TOutput = unknown>(opts: AgentOptions & {
 
 declare function createAgentNode(opts: SmartAgentOptions): (state: SmartState) => Promise<Partial<SmartState>>;
 
-declare function createToolsNode(initialTools: Array<ToolInterface$1<any, any, any>>, opts?: SmartAgentOptions): (state: SmartState) => Promise<any>;
+declare function createToolsNode(initialTools: Array<ToolInterface<any, any, any>>, opts?: SmartAgentOptions): (state: SmartState) => Promise<any>;
 
 declare function createResolverNode(): (state: SmartState) => Promise<SmartState>;
 
 declare function createToolLimitFinalizeNode(_opts: SmartAgentOptions): (state: SmartState) => Promise<Partial<SmartState>>;
 
+/**
+ * Creates the summarization node.
+ *
+ * Logic:
+ * 1. Check if summarization is enabled.
+ * 2. Convert current conversation history into a text suitable for summarization.
+ * 3. Invoke the model to generate a summary of the conversation.
+ * 4. Rewrite the message history:
+ *    - All tool messages (role='tool') have their content replaced with "SUMMARIZED".
+ *    - A new assistant message calling 'summarize_context' is appended.
+ *    - A new tool message with the summary content is appended.
+ */
 declare function createContextSummarizeNode(opts: SmartAgentOptions): (state: SmartState) => Promise<Partial<SmartState>>;
 
 type TokenLimits = {
     contextTokenLimit: number;
     summaryTokenLimit: number;
 };
-declare function applyTokenLimits({ state, model, limits, }: {
+declare function applyTokenLimits({ state, limits, }: {
     state: {
         messages: Message[];
         summaries?: string[];
     };
-    model: any;
     limits: {
         contextTokenLimit: number;
         summaryTokenLimit: number;
@@ -327,47 +659,145 @@ declare function createContextTools(stateRef: {
     outputSchema?: any;
 }): any[];
 
-type DebugSession = {
-    sessionId: string;
-    baseDir: string;
-    sessionDir: string;
-    stepIndex: number;
-    callback?: (entry: {
-        sessionId: string;
-        stepIndex: number;
-        fileName: string;
-        markdown: string;
-        messages: Message[];
-        usage?: any;
-        modelName?: string;
-        limits?: any;
-        tools?: any[];
-    }) => void;
-};
-declare function resolveLogsBaseDir(customPath?: string): string;
-declare function createDebugSession(opts: SmartAgentOptions): DebugSession | undefined;
-declare function bumpStep(session: DebugSession): number;
-type UsageLike = any;
-declare function getModelName(model: any): string | undefined;
-declare function serializeAgentTools(tools: any[]): any[];
-declare function formatMarkdown(params: {
-    modelName: string | undefined;
-    date: string;
-    limits?: any;
-    usage?: UsageLike;
-    tools?: any[];
-    messages: Message[];
-}): string;
-declare function writeStepMarkdown(session: DebugSession, fileName: string, markdown: string, payload?: {
-    messages: Message[];
-    usage?: any;
-    modelName?: string;
-    limits?: any;
-    tools?: any[];
-}): Promise<void>;
-
-declare function createSmartAgent<TOutput = unknown>(opts: AgentOptions & {
+declare function createSmartAgent<TOutput = unknown>(opts: SmartAgentOptions & {
     outputSchema?: ZodSchema<TOutput>;
-}): AgentInstance<TOutput>;
+}): SmartAgentInstance<TOutput>;
+
+type GuardrailEvaluationParams = {
+    guardrails?: ConversationGuardrail[];
+    phase: GuardrailPhase;
+    state: SmartState;
+    runtime: AgentRuntimeConfig;
+    options: SmartAgentOptions;
+    emit?: (event: SmartAgentEvent) => void;
+};
+declare function evaluateGuardrails(params: GuardrailEvaluationParams): Promise<GuardrailOutcome>;
+type CreateGuardrailOptions = {
+    id?: string;
+    title?: string;
+    description?: string;
+    appliesTo?: GuardrailPhase[];
+    checks: GuardrailRule[];
+    haltOnViolation?: boolean;
+    onViolation?: ConversationGuardrail["onViolation"];
+    metadata?: Record<string, any>;
+};
+declare function createGuardrail(options: CreateGuardrailOptions): ConversationGuardrail;
+
+type RegexRuleOptions = {
+    id?: string;
+    title?: string;
+    description?: string;
+    pattern: RegExp | string;
+    flags?: string;
+    matchDisposition?: GuardrailDisposition;
+    selector?: (context: GuardrailContext) => string;
+    allowIfMatch?: boolean;
+    failureMessage?: string;
+};
+declare function regexRule(options: RegexRuleOptions): GuardrailRule;
+type JsonSchemaRuleOptions = {
+    id?: string;
+    title?: string;
+    description?: string;
+    schema: JSONSchema7 | z.ZodTypeAny;
+    selector?: (context: GuardrailContext) => string;
+    disposition?: GuardrailDisposition;
+    allowOnParseError?: boolean;
+};
+declare function jsonSchemaRule(options: JsonSchemaRuleOptions): GuardrailRule;
+type CodeDetectionRuleOptions = {
+    id?: string;
+    title?: string;
+    description?: string;
+    selector?: (context: GuardrailContext) => string;
+    disposition?: GuardrailDisposition;
+    allowList?: Array<RegExp | string>;
+};
+declare function codePresenceRule(options?: CodeDetectionRuleOptions): GuardrailRule;
+declare const guardianSchema: z.ZodObject<{
+    allow: z.ZodBoolean;
+    disposition: z.ZodOptional<z.ZodEnum<["allow", "warn", "block"]>>;
+    reason: z.ZodOptional<z.ZodString>;
+    details: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+}, "strip", z.ZodTypeAny, {
+    allow: boolean;
+    disposition?: "block" | "warn" | "allow" | undefined;
+    reason?: string | undefined;
+    details?: Record<string, any> | undefined;
+}, {
+    allow: boolean;
+    disposition?: "block" | "warn" | "allow" | undefined;
+    reason?: string | undefined;
+    details?: Record<string, any> | undefined;
+}>;
+type AgentRuleOptions = {
+    id?: string;
+    title?: string;
+    description?: string;
+    agent: SmartAgentInstance<z.infer<typeof guardianSchema>>;
+    systemPrompt?: string;
+    payloadBuilder?: (context: GuardrailContext) => string;
+    dispositionFallback?: GuardrailDisposition;
+};
+declare function agentVerdictRule(options: AgentRuleOptions): GuardrailRule;
+type CustomRuleCallback = (context: GuardrailContext) => boolean | {
+    allow: boolean;
+    reason?: string;
+    disposition?: GuardrailDisposition;
+    details?: Record<string, any>;
+} | Promise<boolean | {
+    allow: boolean;
+    reason?: string;
+    disposition?: GuardrailDisposition;
+    details?: Record<string, any>;
+}>;
+type CustomRuleOptions = {
+    id?: string;
+    title?: string;
+    description?: string;
+    callback: CustomRuleCallback;
+    defaultDisposition?: GuardrailDisposition;
+};
+declare function customCallbackRule(options: CustomRuleOptions): GuardrailRule;
+
+type GuardrailPresetBase = {
+    guardrailId?: string;
+    guardrailTitle?: string;
+    guardrailDescription?: string;
+    phases?: GuardrailPhase[];
+    haltOnViolation?: boolean;
+    onViolation?: ConversationGuardrail["onViolation"];
+    metadata?: Record<string, any>;
+};
+type RegexGuardrailOptions = GuardrailPresetBase & {
+    rule?: Omit<RegexRuleOptions, "pattern">;
+};
+declare function createRegexGuardrail(pattern: RegExp | string, options?: RegexGuardrailOptions): ConversationGuardrail;
+type JsonGuardrailOptions = GuardrailPresetBase & {
+    rule?: Omit<JsonSchemaRuleOptions, "schema">;
+};
+declare function createJsonGuardrail(schema: JsonSchemaRuleOptions["schema"], options?: JsonGuardrailOptions): ConversationGuardrail;
+type CodeGuardrailOptions = GuardrailPresetBase & {
+    rule?: CodeDetectionRuleOptions;
+};
+declare function createCodeGuardrail(options?: CodeGuardrailOptions): ConversationGuardrail;
+
+declare function captureSnapshot(state: SmartState, options?: SnapshotOptions): AgentSnapshot;
+declare function restoreSnapshot(snapshot: AgentSnapshot, restoreOptions?: RestoreSnapshotOptions): SmartState;
+
+declare function resolveToolApprovalState(state: SmartState, resolution: ToolApprovalResolution): SmartState;
+
+declare function fromLangchainTools<T extends ToolInterface = ToolInterface>(tools: any[]): T[];
+
+declare function fileSink(path?: string): TraceSinkConfig;
+type CustomSinkArg = ((event: TraceEventRecord) => void | Promise<void>) | {
+    onEvent?: (event: TraceEventRecord) => void | Promise<void>;
+    onSession?: (session: TraceSessionFile) => void | Promise<void>;
+};
+declare function customSink(handler: CustomSinkArg): TraceSinkConfig;
+declare function cognipeerSink(apiKey: string): TraceSinkConfig;
+declare function cognipeerSink(url: string | undefined, apiKey: string): TraceSinkConfig;
+declare function httpSink(url: string, headers?: Record<string, string>): TraceSinkConfig;
 
-export { type AgentEvent, type AgentInstance, type AgentInvokeResult, type AgentLimits, type AgentOptions, type AgentResult, type AgentState, type BaseChatMessage, type BaseChatMessagePart, type BaseChatModel, type DebugSession, type InvokeConfig, type SmartAgentInstance, type SmartAgentLimits, type SmartAgentOptions, type SmartModel, type SmartState, type SmartToolFn, type TokenLimits, applyTokenLimits, buildSystemPrompt, bumpStep, countApproxTokens, createAgent, createAgentNode, createContextSummarizeNode, createContextTools, createDebugSession, createResolverNode, createSmartAgent, createSmartTool, createTool, createToolLimitFinalizeNode, createToolsNode, formatMarkdown, fromLangchainModel, getModelName, isSmartModel, resolveLogsBaseDir, serializeAgentTools, withTools, writeStepMarkdown };
+export { type AIMessage, type AgentInstance, type AgentInvokeResult, type AgentLimits, type AgentOptions, type AgentRuleOptions, type AgentRuntimeConfig, type AgentSnapshot, type AgentSnapshotMetadata, type AgentState, type BaseChatMessage, type BaseChatMessagePart, type BaseChatModel, type BaseMessage, type CodeDetectionRuleOptions, type CodeGuardrailOptions, type ConversationGuardrail, type CustomRuleCallback, type CustomRuleOptions, type GuardrailContext, type GuardrailDisposition, type GuardrailEvent, type GuardrailIncident, type GuardrailOutcome, GuardrailPhase, type GuardrailRule, type HandoffDescriptor, type InvokeConfig, type JsonGuardrailOptions, type JsonSchemaRuleOptions, type Message, type PendingToolApproval, type RegexGuardrailOptions, type RegexRuleOptions, type ResolvedTraceConfig, type ResolvedTraceSink, type RestoreSnapshotOptions, type SerializableSmartState, type SmartAgentEvent, type SmartAgentInstance, type SmartAgentLimits, type SmartAgentOptions, type SmartAgentTracingConfig, type SmartModel, type SmartState, type SmartToolFn, type SnapshotOptions, type SnapshotRuntimeHint, type TokenLimits, type ToolApprovalEvent, type ToolApprovalResolution, type ToolInterface, 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 TraceSinkSnapshot, type TraceSummarySection, type TraceToolCallSection, type TraceToolResultSection, type TracingConfig, agentVerdictRule, applyTokenLimits, buildSystemPrompt, captureSnapshot, codePresenceRule, cognipeerSink, countApproxTokens, createAgent, createAgentNode, createCodeGuardrail, createContextSummarizeNode, createContextTools, createGuardrail, createJsonGuardrail, createRegexGuardrail, createResolverNode, createSmartAgent, createTool, createToolLimitFinalizeNode, createToolsNode, customCallbackRule, customSink, evaluateGuardrails, fileSink, fromLangchainModel, fromLangchainTools, httpSink, isSmartModel, jsonSchemaRule, regexRule, resolveToolApprovalState, restoreSnapshot, withTools };