@clinebot/agents 0.0.0

package/src/types.ts

@@ -0,0 +1,966 @@
+/**
+ * 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,
+	ToolCallRecordSchema,
+	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";
+
+// =============================================================================
+// Agent Events
+// =============================================================================
+
+/**
+ * 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;
+}
+
+// =============================================================================
+// Hooks
+// =============================================================================
+
+/**
+ * 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[];
+}
+
+// =============================================================================
+// Extensions
+// =============================================================================
+
+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>;
+}
+
+// =============================================================================
+// Agent Finish Reasons
+// =============================================================================
+
+/**
+ * Reasons why the agent stopped executing
+ */
+export type AgentFinishReason =
+	| "completed" // Normal completion (no more tool calls)
+	| "max_iterations" // Hit the maximum iteration limit
+	| "aborted" // User or system aborted
+	| "error"; // Unrecoverable error occurred
+
+export const AgentFinishReasonSchema = z.enum([
+	"completed",
+	"max_iterations",
+	"aborted",
+	"error",
+]);
+
+// =============================================================================
+// Agent Usage
+// =============================================================================
+
+/**
+ * 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 const AgentUsageSchema = z.object({
+	inputTokens: z.number(),
+	outputTokens: z.number(),
+	cacheReadTokens: z.number().optional(),
+	cacheWriteTokens: z.number().optional(),
+	totalCost: z.number().optional(),
+});
+
+// =============================================================================
+// Agent Result
+// =============================================================================
+
+/**
+ * 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 const AgentResultSchema = z.object({
+	text: z.string(),
+	usage: AgentUsageSchema,
+	messages: z.array(z.custom<LlmsProviders.Message>()),
+	toolCalls: z.array(ToolCallRecordSchema),
+	iterations: z.number(),
+	finishReason: AgentFinishReasonSchema,
+	model: z.object({
+		id: z.string(),
+		provider: z.string(),
+		info: z.custom<LlmsProviders.ModelInfo>().optional(),
+	}),
+	startedAt: z.date(),
+	endedAt: z.date(),
+	durationMs: z.number(),
+});
+
+// =============================================================================
+// Agent Configuration
+// =============================================================================
+
+/**
+ * Reasoning effort level for capable models
+ */
+export type ReasoningEffort = "low" | "medium" | "high";
+
+export const ReasoningEffortSchema = z.enum(["low", "medium", "high"]);
+
+/**
+ * Configuration for creating an Agent
+ */
+export interface AgentConfig {
+	// -------------------------------------------------------------------------
+	// Provider Settings
+	// -------------------------------------------------------------------------
+
+	/** 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[];
+
+	// -------------------------------------------------------------------------
+	// Agent Behavior
+	// -------------------------------------------------------------------------
+
+	/** 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 Settings (for capable models)
+	// -------------------------------------------------------------------------
+
+	/**
+	 * Reasoning effort level
+	 */
+	reasoningEffort?: ReasoningEffort;
+	/**
+	 * Maximum tokens for thinking/reasoning
+	 */
+	thinkingBudgetTokens?: number;
+	/**
+	 * Enable default thinking/reasoning behavior for supported models.
+	 */
+	thinking?: boolean;
+
+	// -------------------------------------------------------------------------
+	// Callbacks
+	// -------------------------------------------------------------------------
+
+	/**
+	 * 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;
+
+	// -------------------------------------------------------------------------
+	// Completion Guard
+	// -------------------------------------------------------------------------
+
+	/**
+	 * 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;
+
+	// -------------------------------------------------------------------------
+	// Cancellation
+	// -------------------------------------------------------------------------
+
+	/**
+	 * Abort signal for cancellation
+	 */
+	abortSignal?: AbortSignal;
+}
+
+export const AgentConfigSchema = z.object({
+	// Provider Settings
+	providerId: z.string(),
+	modelId: z.string(),
+	apiKey: z.string().optional(),
+	baseUrl: z.string().url().optional(),
+	headers: z.record(z.string(), z.string()).optional(),
+	knownModels: z
+		.record(z.string(), z.custom<LlmsProviders.ModelInfo>())
+		.optional(),
+	providerConfig: z.custom<LlmsProviders.ProviderConfig>().optional(),
+	initialMessages: z.array(z.custom<LlmsProviders.Message>()).optional(),
+
+	// Agent Behavior
+	systemPrompt: z.string(),
+	tools: z.array(z.custom<Tool>()),
+	maxIterations: z.number().positive().optional(),
+	maxParallelToolCalls: z.number().int().positive().default(8),
+	maxTokensPerTurn: z.number().positive().optional(),
+	apiTimeoutMs: z.number().positive().default(120000),
+	userFileContentLoader: z
+		.function()
+		.input([z.string()])
+		.output(z.promise(z.string()))
+		.optional(),
+	reminderAfterIterations: z.number().nonnegative().default(6),
+	reminderText: z.string().optional(),
+
+	// Reasoning Settings
+	reasoningEffort: ReasoningEffortSchema.optional(),
+	thinkingBudgetTokens: z.number().positive().optional(),
+	thinking: z.boolean().optional(),
+
+	// Callbacks
+	onEvent: z
+		.function()
+		.input([z.custom<AgentEvent>()])
+		.output(z.void())
+		.optional(),
+	hooks: z.custom<AgentHooks>().optional(),
+	parentAgentId: z.string().optional(),
+	extensions: z.array(z.custom<AgentExtension>()).optional(),
+	hookErrorMode: z.enum(["ignore", "throw"]).default("ignore"),
+	hookPolicies: z.custom<HookPolicies>().optional(),
+	toolPolicies: z
+		.record(
+			z.string(),
+			z.object({
+				enabled: z.boolean().optional(),
+				autoApprove: z.boolean().optional(),
+			}),
+		)
+		.optional(),
+	requestToolApproval: z
+		.function()
+		.input([
+			z.object({
+				agentId: z.string(),
+				conversationId: z.string(),
+				iteration: z.number(),
+				toolCallId: z.string(),
+				toolName: z.string(),
+				input: z.unknown(),
+				policy: z
+					.object({
+						enabled: z.boolean().optional(),
+						autoApprove: z.boolean().optional(),
+					})
+					.default({}),
+			}),
+		])
+		.output(
+			z.union([
+				z.object({
+					approved: z.boolean(),
+					reason: z.string().optional(),
+				}),
+				z.promise(
+					z.object({
+						approved: z.boolean(),
+						reason: z.string().optional(),
+					}),
+				),
+			]),
+		)
+		.optional(),
+	logger: z.custom<BasicLogger>().optional(),
+
+	// Cancellation
+	abortSignal: z.custom<AbortSignal>().optional(),
+});
+
+// =============================================================================
+// Internal Types
+// =============================================================================
+
+/**
+ * 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;
+}
+
+// =============================================================================
+// Re-exports from providers for convenience
+// =============================================================================
+
+export type ContentBlock = LlmsProviders.ContentBlock;
+export type Message = LlmsProviders.Message;
+export type ModelInfo = LlmsProviders.ModelInfo;
+export type ToolDefinition = LlmsProviders.ToolDefinition;