@clinebot/agents 0.0.0

package/dist/types.d.ts

@@ -0,0 +1,826 @@
+/**
+ * Types and Zod Schemas for the Agent Package
+ *
+ * This module defines all TypeScript types and Zod validation schemas
+ * for agent configuration, tools, events, and results.
+ */
+import type { providers as LlmsProviders } from "@clinebot/llms";
+import { type BasicLogger, type Tool, type ToolApprovalRequest, type ToolApprovalResult, type ToolCallRecord, type ToolPolicy } from "@clinebot/shared";
+import { z } from "zod";
+export type { BasicLogger, Tool, ToolApprovalRequest, ToolApprovalResult, ToolCallRecord, ToolContext, ToolPolicy, } from "@clinebot/shared";
+export { ToolCallRecordSchema, ToolContextSchema } from "@clinebot/shared";
+/**
+ * Events emitted during agent execution
+ */
+export type AgentEvent = AgentContentStartEvent | AgentContentEndEvent | AgentIterationStartEvent | AgentIterationEndEvent | AgentUsageEvent | AgentDoneEvent | AgentErrorEvent;
+export type AgentContentType = "text" | "reasoning" | "tool";
+export interface AgentContentStartEvent {
+    type: "content_start";
+    contentType: AgentContentType;
+    /** The text chunk received from the model */
+    text?: string;
+    /** Accumulated text so far in this turn */
+    accumulated?: string;
+    /** The reasoning/thinking text from the model */
+    reasoning?: string;
+    /** Whether this is redacted reasoning */
+    redacted?: boolean;
+    /** Name of the tool being called */
+    toolName?: string;
+    /** Unique identifier for this tool call */
+    toolCallId?: string;
+    /** Input being passed to the tool */
+    input?: unknown;
+}
+export interface AgentContentEndEvent {
+    type: "content_end";
+    contentType: AgentContentType;
+    /** Final text generated for this turn */
+    text?: string;
+    /** Final reasoning/thinking text generated for this turn */
+    reasoning?: string;
+    /** Name of the tool that completed */
+    toolName?: string;
+    /** Unique identifier for this tool call */
+    toolCallId?: string;
+    /** Output from the tool */
+    output?: unknown;
+    /** Error message if the tool failed */
+    error?: string;
+    /** Time taken in milliseconds for tool content */
+    durationMs?: number;
+}
+export interface AgentIterationStartEvent {
+    type: "iteration_start";
+    /** The iteration number (1-based) */
+    iteration: number;
+}
+export interface AgentIterationEndEvent {
+    type: "iteration_end";
+    /** The iteration number that just completed */
+    iteration: number;
+    /** Whether this iteration had any tool calls */
+    hadToolCalls: boolean;
+    /** Number of tool calls in this iteration */
+    toolCallCount: number;
+}
+export interface AgentUsageEvent {
+    type: "usage";
+    /** Number of input tokens for this turn */
+    inputTokens: number;
+    /** Number of output tokens for this turn */
+    outputTokens: number;
+    /** Tokens read from cache */
+    cacheReadTokens?: number;
+    /** Tokens written to cache */
+    cacheWriteTokens?: number;
+    /** Cost for this turn */
+    cost?: number;
+    /** Accumulated totals */
+    totalInputTokens: number;
+    totalOutputTokens: number;
+    totalCost?: number;
+}
+export interface AgentDoneEvent {
+    type: "done";
+    /** The reason the agent stopped */
+    reason: AgentFinishReason;
+    /** Final text output */
+    text: string;
+    /** Total number of iterations */
+    iterations: number;
+}
+export interface AgentErrorEvent {
+    type: "error";
+    /** The error that occurred */
+    error: Error;
+    /** Whether the error is recoverable */
+    recoverable: boolean;
+    /** Current iteration when error occurred */
+    iteration: number;
+}
+/**
+ * Hook error handling behavior.
+ * - "ignore": swallow hook errors and continue agent execution
+ * - "throw": fail agent execution when a hook throws
+ */
+export type HookErrorMode = "ignore" | "throw";
+/**
+ * Common controls supported by lifecycle hooks.
+ */
+export interface AgentHookControl {
+    /**
+     * Cancel the active run after this hook.
+     * When true, finishReason becomes "aborted".
+     */
+    cancel?: boolean;
+    /**
+     * Request explicit approval before executing the active tool call.
+     * Only applied for `onToolCallStart`.
+     */
+    review?: boolean;
+    /**
+     * Optional context appended to the conversation as a user text block.
+     */
+    context?: string;
+    /**
+     * Optional replacement input for the active tool call.
+     * Only applied for `onToolCallStart`.
+     */
+    overrideInput?: unknown;
+    /**
+     * Optional replacement system prompt.
+     * Primarily used by before-agent-start hook stages.
+     */
+    systemPrompt?: string;
+    /**
+     * Optional messages to append before model turn execution.
+     * Primarily used by before-agent-start hook stages.
+     */
+    appendMessages?: LlmsProviders.Message[];
+}
+export interface AgentHookRunStartContext {
+    agentId: string;
+    conversationId: string;
+    parentAgentId: string | null;
+    userMessage: string;
+}
+export interface AgentHookScheduleContext {
+    scheduleId: string;
+    executionId?: string;
+    trigger: "scheduled" | "manual";
+    triggeredAt?: string;
+}
+export interface AgentHookSessionStartContext {
+    agentId: string;
+    conversationId: string;
+    parentAgentId: string | null;
+    schedule?: AgentHookScheduleContext;
+}
+export interface AgentHookRunEndContext {
+    agentId: string;
+    conversationId: string;
+    parentAgentId: string | null;
+    result: AgentResult;
+}
+export interface AgentHookIterationStartContext {
+    agentId: string;
+    conversationId: string;
+    parentAgentId: string | null;
+    iteration: number;
+}
+export interface AgentHookIterationEndContext {
+    agentId: string;
+    conversationId: string;
+    parentAgentId: string | null;
+    iteration: number;
+    hadToolCalls: boolean;
+    toolCallCount: number;
+}
+export interface AgentHookTurnStartContext {
+    agentId: string;
+    conversationId: string;
+    parentAgentId: string | null;
+    iteration: number;
+    messages: LlmsProviders.Message[];
+}
+export interface AgentHookTurnEndContext {
+    agentId: string;
+    conversationId: string;
+    parentAgentId: string | null;
+    iteration: number;
+    turn: ProcessedTurn;
+}
+export interface AgentHookToolCallStartContext {
+    agentId: string;
+    conversationId: string;
+    parentAgentId: string | null;
+    iteration: number;
+    call: PendingToolCall;
+}
+export interface AgentHookToolCallEndContext {
+    agentId: string;
+    conversationId: string;
+    parentAgentId: string | null;
+    iteration: number;
+    record: ToolCallRecord;
+}
+export interface AgentHookErrorContext {
+    agentId: string;
+    conversationId: string;
+    parentAgentId: string | null;
+    iteration: number;
+    error: Error;
+}
+export interface AgentHookSessionShutdownContext {
+    agentId: string;
+    conversationId: string;
+    parentAgentId: string | null;
+    /**
+     * Optional reason for shutdown (e.g. "ctrl_d", "process_exit")
+     */
+    reason?: string;
+}
+export type HookStage = "input" | "runtime_event" | "session_start" | "run_start" | "iteration_start" | "turn_start" | "before_agent_start" | "tool_call_before" | "tool_call_after" | "turn_end" | "iteration_end" | "run_end" | "session_shutdown" | "error";
+export type HookMode = "blocking" | "async";
+export type HookFailureMode = "fail_open" | "fail_closed";
+export interface HookStagePolicy {
+    mode: HookMode;
+    timeoutMs: number;
+    retries: number;
+    retryDelayMs: number;
+    failureMode: HookFailureMode;
+    maxConcurrency: number;
+    queueLimit: number;
+}
+export type HookStagePolicyInput = Partial<HookStagePolicy>;
+export interface HookPolicies {
+    defaultPolicy?: HookStagePolicyInput;
+    stages?: Partial<Record<HookStage, HookStagePolicyInput>>;
+    handlers?: Record<string, HookStagePolicyInput>;
+}
+export interface HookEventEnvelope<TPayload = unknown> {
+    eventId: string;
+    stage: HookStage;
+    createdAt: Date;
+    sequence: number;
+    runId: string;
+    agentId: string;
+    conversationId: string;
+    parentAgentId: string | null;
+    iteration?: number;
+    parentEventId?: string;
+    payload: TPayload;
+}
+export type HookAttemptStatus = "ok" | "timeout" | "error" | "skipped";
+export interface HookHandlerResult {
+    handlerName: string;
+    stage: HookStage;
+    status: HookAttemptStatus;
+    attempts: number;
+    durationMs: number;
+    error?: Error;
+    control?: AgentHookControl;
+}
+export interface HookDispatchResult {
+    event: HookEventEnvelope;
+    queued: boolean;
+    dropped: boolean;
+    control?: AgentHookControl;
+    results: HookHandlerResult[];
+}
+export interface AgentExtensionCommand {
+    name: string;
+    description?: string;
+    handler?: (input: string) => Promise<string> | string;
+}
+export interface AgentExtensionShortcut {
+    name: string;
+    value: string;
+    description?: string;
+}
+export interface AgentExtensionFlag {
+    name: string;
+    description?: string;
+    defaultValue?: boolean | string | number;
+}
+export interface AgentExtensionMessageRenderer {
+    name: string;
+    render: (message: LlmsProviders.Message) => string;
+}
+export interface AgentExtensionProvider {
+    name: string;
+    description?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface AgentExtensionRuntimeEventContext {
+    agentId: string;
+    conversationId: string;
+    parentAgentId: string | null;
+    event: AgentEvent;
+}
+export interface AgentExtensionSessionStartContext {
+    agentId: string;
+    conversationId: string;
+    parentAgentId: string | null;
+    schedule?: AgentHookScheduleContext;
+}
+export interface AgentExtensionSessionShutdownContext {
+    agentId: string;
+    conversationId: string;
+    parentAgentId: string | null;
+    reason?: string;
+}
+export interface AgentExtensionInputContext {
+    agentId: string;
+    conversationId: string;
+    parentAgentId: string | null;
+    mode: "run" | "continue";
+    input: string;
+}
+export interface AgentExtensionBeforeAgentStartContext {
+    agentId: string;
+    conversationId: string;
+    parentAgentId: string | null;
+    iteration: number;
+    systemPrompt: string;
+    messages: LlmsProviders.Message[];
+}
+export interface AgentExtensionBeforeAgentStartControl extends AgentHookControl {
+    systemPrompt?: string;
+    appendMessages?: LlmsProviders.Message[];
+}
+export interface AgentExtensionApi {
+    registerTool: (tool: Tool) => void;
+    registerCommand: (command: AgentExtensionCommand) => void;
+    registerShortcut: (shortcut: AgentExtensionShortcut) => void;
+    registerFlag: (flag: AgentExtensionFlag) => void;
+    registerMessageRenderer: (renderer: AgentExtensionMessageRenderer) => void;
+    registerProvider: (provider: AgentExtensionProvider) => void;
+}
+export type AgentExtensionCapability = "hooks" | "tools" | "commands" | "shortcuts" | "flags" | "message_renderers" | "providers";
+export type AgentExtensionHookStage = "input" | "runtime_event" | "session_start" | "run_start" | "iteration_start" | "turn_start" | "before_agent_start" | "tool_call_before" | "tool_call_after" | "turn_end" | "iteration_end" | "run_end" | "session_shutdown" | "error";
+export interface PluginManifest {
+    capabilities: AgentExtensionCapability[];
+    hookStages?: AgentExtensionHookStage[];
+}
+export interface AgentExtension {
+    name: string;
+    manifest: PluginManifest;
+    setup?: (api: AgentExtensionApi) => void | Promise<void>;
+    onSessionStart?: (ctx: AgentExtensionSessionStartContext) => undefined | AgentHookControl | Promise<undefined | AgentHookControl>;
+    onRunStart?: (ctx: AgentHookRunStartContext) => undefined | AgentHookControl | Promise<undefined | AgentHookControl>;
+    onIterationStart?: (ctx: AgentHookIterationStartContext) => undefined | AgentHookControl | Promise<undefined | AgentHookControl>;
+    onTurnStart?: (ctx: AgentHookTurnStartContext) => undefined | AgentHookControl | Promise<undefined | AgentHookControl>;
+    onInput?: (ctx: AgentExtensionInputContext) => undefined | AgentHookControl | Promise<undefined | AgentHookControl>;
+    onBeforeAgentStart?: (ctx: AgentExtensionBeforeAgentStartContext) => undefined | AgentExtensionBeforeAgentStartControl | Promise<undefined | AgentExtensionBeforeAgentStartControl>;
+    onToolCall?: (ctx: AgentHookToolCallStartContext) => undefined | AgentHookControl | Promise<undefined | AgentHookControl>;
+    onToolResult?: (ctx: AgentHookToolCallEndContext) => undefined | AgentHookControl | Promise<undefined | AgentHookControl>;
+    onAgentEnd?: (ctx: AgentHookTurnEndContext) => undefined | AgentHookControl | Promise<undefined | AgentHookControl>;
+    onIterationEnd?: (ctx: AgentHookIterationEndContext) => void | Promise<void>;
+    onRunEnd?: (ctx: AgentHookRunEndContext) => void | Promise<void>;
+    onSessionShutdown?: (ctx: AgentExtensionSessionShutdownContext) => undefined | AgentHookControl | Promise<undefined | AgentHookControl>;
+    onRuntimeEvent?: (ctx: AgentExtensionRuntimeEventContext) => void | Promise<void>;
+    onError?: (ctx: AgentHookErrorContext) => void | Promise<void>;
+}
+export interface AgentExtensionRegistry {
+    tools: Tool[];
+    commands: AgentExtensionCommand[];
+    shortcuts: AgentExtensionShortcut[];
+    flags: AgentExtensionFlag[];
+    messageRenderers: AgentExtensionMessageRenderer[];
+    providers: AgentExtensionProvider[];
+}
+/**
+ * Lifecycle hooks for observing or influencing agent execution.
+ */
+export interface AgentHooks {
+    onSessionStart?: (ctx: AgentHookSessionStartContext) => undefined | AgentHookControl | Promise<undefined | AgentHookControl>;
+    onRunStart?: (ctx: AgentHookRunStartContext) => undefined | AgentHookControl | Promise<undefined | AgentHookControl>;
+    onRunEnd?: (ctx: AgentHookRunEndContext) => void | Promise<void>;
+    onIterationStart?: (ctx: AgentHookIterationStartContext) => undefined | AgentHookControl | Promise<undefined | AgentHookControl>;
+    onIterationEnd?: (ctx: AgentHookIterationEndContext) => void | Promise<void>;
+    onTurnStart?: (ctx: AgentHookTurnStartContext) => undefined | AgentHookControl | Promise<undefined | AgentHookControl>;
+    onTurnEnd?: (ctx: AgentHookTurnEndContext) => undefined | AgentHookControl | Promise<undefined | AgentHookControl>;
+    onToolCallStart?: (ctx: AgentHookToolCallStartContext) => undefined | AgentHookControl | Promise<undefined | AgentHookControl>;
+    onToolCallEnd?: (ctx: AgentHookToolCallEndContext) => undefined | AgentHookControl | Promise<undefined | AgentHookControl>;
+    onSessionShutdown?: (ctx: AgentHookSessionShutdownContext) => undefined | AgentHookControl | Promise<undefined | AgentHookControl>;
+    onError?: (ctx: AgentHookErrorContext) => void | Promise<void>;
+}
+/**
+ * Reasons why the agent stopped executing
+ */
+export type AgentFinishReason = "completed" | "max_iterations" | "aborted" | "error";
+export declare const AgentFinishReasonSchema: z.ZodEnum<{
+    completed: "completed";
+    max_iterations: "max_iterations";
+    aborted: "aborted";
+    error: "error";
+}>;
+/**
+ * Aggregated token usage and cost information
+ */
+export interface AgentUsage {
+    /** Total input tokens across all iterations */
+    inputTokens: number;
+    /** Total output tokens across all iterations */
+    outputTokens: number;
+    /** Total tokens read from cache */
+    cacheReadTokens?: number;
+    /** Total tokens written to cache */
+    cacheWriteTokens?: number;
+    /** Total cost in dollars */
+    totalCost?: number;
+}
+export declare const AgentUsageSchema: z.ZodObject<{
+    inputTokens: z.ZodNumber;
+    outputTokens: z.ZodNumber;
+    cacheReadTokens: z.ZodOptional<z.ZodNumber>;
+    cacheWriteTokens: z.ZodOptional<z.ZodNumber>;
+    totalCost: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+/**
+ * Result returned from Agent.run()
+ */
+export interface AgentResult {
+    /** Final text output from the agent */
+    text: string;
+    /** Aggregated token usage and cost */
+    usage: AgentUsage;
+    /** Full conversation history */
+    messages: LlmsProviders.Message[];
+    /** All tool calls made during execution */
+    toolCalls: ToolCallRecord[];
+    /** Number of loop iterations */
+    iterations: number;
+    /** Why the agent stopped */
+    finishReason: AgentFinishReason;
+    /** Model information used */
+    model: {
+        id: string;
+        provider: string;
+        info?: LlmsProviders.ModelInfo;
+    };
+    /** Start time of the run */
+    startedAt: Date;
+    /** End time of the run */
+    endedAt: Date;
+    /** Total duration in milliseconds */
+    durationMs: number;
+}
+export declare const AgentResultSchema: z.ZodObject<{
+    text: z.ZodString;
+    usage: z.ZodObject<{
+        inputTokens: z.ZodNumber;
+        outputTokens: z.ZodNumber;
+        cacheReadTokens: z.ZodOptional<z.ZodNumber>;
+        cacheWriteTokens: z.ZodOptional<z.ZodNumber>;
+        totalCost: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>;
+    messages: z.ZodArray<z.ZodCustom<LlmsProviders.Message, LlmsProviders.Message>>;
+    toolCalls: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        input: z.ZodUnknown;
+        output: z.ZodUnknown;
+        error: z.ZodOptional<z.ZodString>;
+        durationMs: z.ZodNumber;
+        startedAt: z.ZodDate;
+        endedAt: z.ZodDate;
+    }, z.core.$strip>>;
+    iterations: z.ZodNumber;
+    finishReason: z.ZodEnum<{
+        completed: "completed";
+        max_iterations: "max_iterations";
+        aborted: "aborted";
+        error: "error";
+    }>;
+    model: z.ZodObject<{
+        id: z.ZodString;
+        provider: z.ZodString;
+        info: z.ZodOptional<z.ZodCustom<{
+            id: string;
+            name?: string | undefined;
+            description?: string | undefined;
+            maxTokens?: number | undefined;
+            contextWindow?: number | undefined;
+            capabilities?: ("reasoning" | "tools" | "temperature" | "images" | "streaming" | "prompt-cache" | "reasoning-effort" | "computer-use" | "global-endpoint" | "structured_output" | "files")[] | undefined;
+            apiFormat?: "default" | "openai-responses" | "r1" | undefined;
+            systemRole?: "system" | "developer" | undefined;
+            temperature?: number | undefined;
+            pricing?: {
+                input?: number | undefined;
+                output?: number | undefined;
+                cacheWrite?: number | undefined;
+                cacheRead?: number | undefined;
+            } | undefined;
+            thinkingConfig?: {
+                maxBudget?: number | undefined;
+                outputPrice?: number | undefined;
+                thinkingLevel?: "low" | "high" | undefined;
+            } | undefined;
+            status?: "active" | "preview" | "deprecated" | "legacy" | undefined;
+            deprecationNotice?: string | undefined;
+            replacedBy?: string | undefined;
+            releaseDate?: string | undefined;
+            deprecationDate?: string | undefined;
+        }, {
+            id: string;
+            name?: string | undefined;
+            description?: string | undefined;
+            maxTokens?: number | undefined;
+            contextWindow?: number | undefined;
+            capabilities?: ("reasoning" | "tools" | "temperature" | "images" | "streaming" | "prompt-cache" | "reasoning-effort" | "computer-use" | "global-endpoint" | "structured_output" | "files")[] | undefined;
+            apiFormat?: "default" | "openai-responses" | "r1" | undefined;
+            systemRole?: "system" | "developer" | undefined;
+            temperature?: number | undefined;
+            pricing?: {
+                input?: number | undefined;
+                output?: number | undefined;
+                cacheWrite?: number | undefined;
+                cacheRead?: number | undefined;
+            } | undefined;
+            thinkingConfig?: {
+                maxBudget?: number | undefined;
+                outputPrice?: number | undefined;
+                thinkingLevel?: "low" | "high" | undefined;
+            } | undefined;
+            status?: "active" | "preview" | "deprecated" | "legacy" | undefined;
+            deprecationNotice?: string | undefined;
+            replacedBy?: string | undefined;
+            releaseDate?: string | undefined;
+            deprecationDate?: string | undefined;
+        }>>;
+    }, z.core.$strip>;
+    startedAt: z.ZodDate;
+    endedAt: z.ZodDate;
+    durationMs: z.ZodNumber;
+}, z.core.$strip>;
+/**
+ * Reasoning effort level for capable models
+ */
+export type ReasoningEffort = "low" | "medium" | "high";
+export declare const ReasoningEffortSchema: z.ZodEnum<{
+    low: "low";
+    high: "high";
+    medium: "medium";
+}>;
+/**
+ * Configuration for creating an Agent
+ */
+export interface AgentConfig {
+    /** Provider ID (e.g., "anthropic", "openai", "gemini") */
+    providerId: string;
+    /** Model ID to use */
+    modelId: string;
+    /** API key for the provider */
+    apiKey?: string;
+    /** Custom base URL for the API */
+    baseUrl?: string;
+    /** Additional headers for API requests */
+    headers?: Record<string, string>;
+    /** Optional provider model catalog overrides */
+    knownModels?: Record<string, LlmsProviders.ModelInfo>;
+    /** Optional pre-resolved provider configuration (includes provider-specific fields like aws/gcp). */
+    providerConfig?: LlmsProviders.ProviderConfig;
+    /**
+     * Optional preloaded conversation history for resume flows.
+     * When provided, start by calling continue() to preserve history.
+     */
+    initialMessages?: LlmsProviders.Message[];
+    /** System prompt for the agent */
+    systemPrompt: string;
+    /** Tools available to the agent */
+    tools: Tool[];
+    /**
+     * Maximum number of loop iterations
+     * If undefined, no iteration cap is enforced.
+     */
+    maxIterations?: number;
+    /**
+     * Maximum number of tool calls to execute concurrently in a single iteration.
+     * @default 8
+     */
+    maxParallelToolCalls?: number;
+    /**
+     * Maximum output tokens per API call
+     */
+    maxTokensPerTurn?: number;
+    /**
+     * After this many consecutive iterations with tool calls,
+     * inject a reminder text block asking the agent to answer if it has enough info.
+     * Set to 0 to disable.
+     * @default 6
+     */
+    reminderAfterIterations?: number;
+    /**
+     * Custom reminder text to inject after reminderAfterIterations.
+     * @default "REMINDER: If you have gathered enough information to answer the user's question, please provide your final answer now without using any more tools."
+     */
+    reminderText?: string;
+    /**
+     * Timeout for each API call in milliseconds
+     * @default 120000 (2 minutes)
+     */
+    apiTimeoutMs?: number;
+    /**
+     * Optional runtime file-content loader used when user files are attached.
+     * When omitted, attached files will be represented as loader errors.
+     */
+    userFileContentLoader?: (path: string) => Promise<string>;
+    /**
+     * Reasoning effort level
+     */
+    reasoningEffort?: ReasoningEffort;
+    /**
+     * Maximum tokens for thinking/reasoning
+     */
+    thinkingBudgetTokens?: number;
+    /**
+     * Enable default thinking/reasoning behavior for supported models.
+     */
+    thinking?: boolean;
+    /**
+     * Callback for agent events (streaming, progress, etc.)
+     */
+    onEvent?: (event: AgentEvent) => void;
+    /**
+     * Lifecycle hooks for observing or influencing agent execution.
+     */
+    hooks?: AgentHooks;
+    /**
+     * Optional parent agent ID for spawned/delegated runs.
+     * Root agents should leave this undefined.
+     */
+    parentAgentId?: string;
+    /**
+     * Extension modules that can intercept lifecycle events and register tools/commands.
+     */
+    extensions?: AgentExtension[];
+    /**
+     * How hook errors should be handled.
+     * @default "ignore"
+     */
+    hookErrorMode?: HookErrorMode;
+    /**
+     * Optional deterministic hook execution policies.
+     */
+    hookPolicies?: HookPolicies;
+    /**
+     * Optional schedule metadata for runs initiated by scheduler services.
+     * Used by session_start lifecycle hooks.
+     */
+    schedule?: AgentHookScheduleContext;
+    /**
+     * Per-tool execution policy. Tool names not listed here default to enabled + autoApprove.
+     */
+    toolPolicies?: Record<string, ToolPolicy>;
+    /**
+     * Optional callback to request client approval when a tool policy disables auto-approval.
+     */
+    requestToolApproval?: (request: ToolApprovalRequest) => Promise<ToolApprovalResult> | ToolApprovalResult;
+    /**
+     * Optional logger for tracing agent loop lifecycle and recoverable failures.
+     */
+    logger?: BasicLogger;
+    /**
+     * Optional guard that runs when the model returns no tool calls.
+     * If it returns a non-empty string, that string is injected as a
+     * system-level nudge and the loop continues instead of completing.
+     * Use this to prevent premature exit when the agent has unfinished
+     * obligations (e.g. in-progress team tasks).
+     */
+    completionGuard?: () => string | undefined;
+    /**
+     * Abort signal for cancellation
+     */
+    abortSignal?: AbortSignal;
+}
+export declare const AgentConfigSchema: z.ZodObject<{
+    providerId: z.ZodString;
+    modelId: z.ZodString;
+    apiKey: z.ZodOptional<z.ZodString>;
+    baseUrl: z.ZodOptional<z.ZodString>;
+    headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    knownModels: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodCustom<{
+        id: string;
+        name?: string | undefined;
+        description?: string | undefined;
+        maxTokens?: number | undefined;
+        contextWindow?: number | undefined;
+        capabilities?: ("reasoning" | "tools" | "temperature" | "images" | "streaming" | "prompt-cache" | "reasoning-effort" | "computer-use" | "global-endpoint" | "structured_output" | "files")[] | undefined;
+        apiFormat?: "default" | "openai-responses" | "r1" | undefined;
+        systemRole?: "system" | "developer" | undefined;
+        temperature?: number | undefined;
+        pricing?: {
+            input?: number | undefined;
+            output?: number | undefined;
+            cacheWrite?: number | undefined;
+            cacheRead?: number | undefined;
+        } | undefined;
+        thinkingConfig?: {
+            maxBudget?: number | undefined;
+            outputPrice?: number | undefined;
+            thinkingLevel?: "low" | "high" | undefined;
+        } | undefined;
+        status?: "active" | "preview" | "deprecated" | "legacy" | undefined;
+        deprecationNotice?: string | undefined;
+        replacedBy?: string | undefined;
+        releaseDate?: string | undefined;
+        deprecationDate?: string | undefined;
+    }, {
+        id: string;
+        name?: string | undefined;
+        description?: string | undefined;
+        maxTokens?: number | undefined;
+        contextWindow?: number | undefined;
+        capabilities?: ("reasoning" | "tools" | "temperature" | "images" | "streaming" | "prompt-cache" | "reasoning-effort" | "computer-use" | "global-endpoint" | "structured_output" | "files")[] | undefined;
+        apiFormat?: "default" | "openai-responses" | "r1" | undefined;
+        systemRole?: "system" | "developer" | undefined;
+        temperature?: number | undefined;
+        pricing?: {
+            input?: number | undefined;
+            output?: number | undefined;
+            cacheWrite?: number | undefined;
+            cacheRead?: number | undefined;
+        } | undefined;
+        thinkingConfig?: {
+            maxBudget?: number | undefined;
+            outputPrice?: number | undefined;
+            thinkingLevel?: "low" | "high" | undefined;
+        } | undefined;
+        status?: "active" | "preview" | "deprecated" | "legacy" | undefined;
+        deprecationNotice?: string | undefined;
+        replacedBy?: string | undefined;
+        releaseDate?: string | undefined;
+        deprecationDate?: string | undefined;
+    }>>>;
+    providerConfig: z.ZodOptional<z.ZodCustom<LlmsProviders.ProviderConfig, LlmsProviders.ProviderConfig>>;
+    initialMessages: z.ZodOptional<z.ZodArray<z.ZodCustom<LlmsProviders.Message, LlmsProviders.Message>>>;
+    systemPrompt: z.ZodString;
+    tools: z.ZodArray<z.ZodCustom<Tool<unknown, unknown>, Tool<unknown, unknown>>>;
+    maxIterations: z.ZodOptional<z.ZodNumber>;
+    maxParallelToolCalls: z.ZodDefault<z.ZodNumber>;
+    maxTokensPerTurn: z.ZodOptional<z.ZodNumber>;
+    apiTimeoutMs: z.ZodDefault<z.ZodNumber>;
+    userFileContentLoader: z.ZodOptional<z.ZodFunction<z.core.$ZodTuple<readonly [z.ZodString], z.core.$ZodFunctionOut>, z.ZodPromise<z.ZodString>>>;
+    reminderAfterIterations: z.ZodDefault<z.ZodNumber>;
+    reminderText: z.ZodOptional<z.ZodString>;
+    reasoningEffort: z.ZodOptional<z.ZodEnum<{
+        low: "low";
+        high: "high";
+        medium: "medium";
+    }>>;
+    thinkingBudgetTokens: z.ZodOptional<z.ZodNumber>;
+    thinking: z.ZodOptional<z.ZodBoolean>;
+    onEvent: z.ZodOptional<z.ZodFunction<z.core.$ZodTuple<readonly [z.ZodCustom<AgentEvent, AgentEvent>], z.core.$ZodFunctionOut>, z.ZodVoid>>;
+    hooks: z.ZodOptional<z.ZodCustom<AgentHooks, AgentHooks>>;
+    parentAgentId: z.ZodOptional<z.ZodString>;
+    extensions: z.ZodOptional<z.ZodArray<z.ZodCustom<AgentExtension, AgentExtension>>>;
+    hookErrorMode: z.ZodDefault<z.ZodEnum<{
+        ignore: "ignore";
+        throw: "throw";
+    }>>;
+    hookPolicies: z.ZodOptional<z.ZodCustom<HookPolicies, HookPolicies>>;
+    toolPolicies: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        enabled: z.ZodOptional<z.ZodBoolean>;
+        autoApprove: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>>;
+    requestToolApproval: z.ZodOptional<z.ZodFunction<z.core.$ZodTuple<readonly [z.ZodObject<{
+        agentId: z.ZodString;
+        conversationId: z.ZodString;
+        iteration: z.ZodNumber;
+        toolCallId: z.ZodString;
+        toolName: z.ZodString;
+        input: z.ZodUnknown;
+        policy: z.ZodDefault<z.ZodObject<{
+            enabled: z.ZodOptional<z.ZodBoolean>;
+            autoApprove: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>], z.core.$ZodFunctionOut>, z.ZodUnion<readonly [z.ZodObject<{
+        approved: z.ZodBoolean;
+        reason: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>, z.ZodPromise<z.ZodObject<{
+        approved: z.ZodBoolean;
+        reason: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>]>>>;
+    logger: z.ZodOptional<z.ZodCustom<BasicLogger, BasicLogger>>;
+    abortSignal: z.ZodOptional<z.ZodCustom<AbortSignal, AbortSignal>>;
+}, z.core.$strip>;
+/**
+ * Pending tool call from the model
+ */
+export interface PendingToolCall {
+    id: string;
+    name: string;
+    input: unknown;
+    signature?: string;
+    review?: boolean;
+}
+/**
+ * Processed response from one turn of the loop
+ */
+export interface ProcessedTurn {
+    /** Text output from the model */
+    text: string;
+    /** Reasoning/thinking content */
+    reasoning?: string;
+    /** Tool calls requested by the model */
+    toolCalls: PendingToolCall[];
+    /** Token usage for this turn */
+    usage: {
+        inputTokens: number;
+        outputTokens: number;
+        cacheReadTokens?: number;
+        cacheWriteTokens?: number;
+        cost?: number;
+    };
+    /** Whether the response was truncated */
+    truncated: boolean;
+    /** Response ID from the API */
+    responseId?: string;
+}
+export type ContentBlock = LlmsProviders.ContentBlock;
+export type Message = LlmsProviders.Message;
+export type ModelInfo = LlmsProviders.ModelInfo;
+export type ToolDefinition = LlmsProviders.ToolDefinition;