@levelcode/sdk 0.0.4 → 0.1.0

package/dist/packages/agent-runtime/src/tools/handlers/tool/write-file.d.ts

@@ -0,0 +1,49 @@
+import { processFileBlock } from '../../../process-file-block';
+import type { ClientToolCall, LevelCodeToolCall, LevelCodeToolOutput } from '@levelcode/common/tools/list';
+import type { RequestOptionalFileFn } from '@levelcode/common/types/contracts/client';
+import type { Logger } from '@levelcode/common/types/contracts/logger';
+import type { ParamsExcluding } from '@levelcode/common/types/function-params';
+import type { AgentState } from '@levelcode/common/types/session-state';
+type FileProcessingTools = 'write_file' | 'str_replace' | 'create_plan';
+export type FileProcessing<T extends FileProcessingTools = FileProcessingTools> = {
+    tool: T;
+    path: string;
+    toolCallId: string;
+} & ({
+    content: string;
+    patch?: string;
+    messages: string[];
+} | {
+    error: string;
+});
+export type FileProcessingState = {
+    promisesByPath: Record<string, Promise<FileProcessing>[]>;
+    allPromises: Promise<FileProcessing>[];
+    fileChangeErrors: Extract<FileProcessing, {
+        error: string;
+    }>[];
+    fileChanges: Exclude<FileProcessing, {
+        error: string;
+    }>[];
+    firstFileProcessed: boolean;
+};
+export declare function getFileProcessingValues(state: FileProcessingState): FileProcessingState;
+export declare const handleWriteFile: (params: {
+    previousToolCallFinished: Promise<void>;
+    toolCall: LevelCodeToolCall<"write_file">;
+    agentState: AgentState;
+    clientSessionId: string;
+    fileProcessingState: FileProcessingState;
+    fingerprintId: string;
+    logger: Logger;
+    prompt: string | undefined;
+    userId: string | undefined;
+    userInputId: string;
+    requestClientToolCall: (toolCall: ClientToolCall<"write_file">) => Promise<LevelCodeToolOutput<"write_file">>;
+    requestOptionalFile: RequestOptionalFileFn;
+    writeToClient: (chunk: string) => void;
+} & ParamsExcluding<typeof processFileBlock, "path" | "instructions" | "fingerprintId" | "initialContentPromise" | "newContent" | "messages" | "lastUserPrompt"> & ParamsExcluding<RequestOptionalFileFn, "filePath">) => Promise<{
+    output: LevelCodeToolOutput<"write_file">;
+}>;
+export declare function postStreamProcessing<T extends FileProcessingTools>(toolCall: FileProcessing<T>, fileProcessingState: FileProcessingState, writeToClient: (chunk: string) => void, requestClientToolCall: (toolCall: ClientToolCall<T>) => Promise<LevelCodeToolOutput<T>>): Promise<LevelCodeToolOutput<T>>;
+export {};

package/dist/packages/agent-runtime/src/tools/handlers/tool/write-todos.d.ts

@@ -0,0 +1,9 @@
+import type { LevelCodeToolCall, LevelCodeToolOutput } from '@levelcode/common/tools/list';
+type ToolName = 'write_todos';
+export declare const handleWriteTodos: (params: {
+    previousToolCallFinished: Promise<void>;
+    toolCall: LevelCodeToolCall<ToolName>;
+}) => Promise<{
+    output: LevelCodeToolOutput<ToolName>;
+}>;
+export {};

package/dist/packages/agent-runtime/src/tools/prompts.d.ts

@@ -0,0 +1,31 @@
+import { toolParams } from '@levelcode/common/tools/list';
+import z from 'zod/v4';
+import type { SkillsMap } from '@levelcode/common/types/skill';
+import type { CustomToolDefinitions, customToolDefinitionsSchema } from '@levelcode/common/util/file';
+import type { ToolSet } from 'ai';
+/**
+ * Ensures the inputSchema is a Zod schema. If it's a JSON Schema object
+ * (from SDK custom tools that were serialized), converts it to Zod.
+ */
+export declare function ensureZodSchema(schema: z.ZodType | Record<string, unknown>): z.ZodType;
+export declare function buildToolDescription(params: {
+    toolName: string;
+    schema: z.ZodType;
+    description?: string;
+    endsAgentStep: boolean;
+    exampleInputs?: any[];
+}): string;
+export declare const toolDescriptions: Record<keyof typeof toolParams, string>;
+export declare const getToolsInstructions: (tools: readonly string[], additionalToolDefinitions: NonNullable<z.input<typeof customToolDefinitionsSchema>>, options?: {
+    availableSkillsXml?: string;
+}) => string;
+export declare const fullToolList: (toolNames: readonly string[], additionalToolDefinitions: CustomToolDefinitions, options?: {
+    availableSkillsXml?: string;
+}) => string;
+export declare const getShortToolInstructions: (toolNames: readonly string[], additionalToolDefinitions: CustomToolDefinitions) => string;
+export declare function getToolSet(params: {
+    toolNames: string[];
+    additionalToolDefinitions: () => Promise<CustomToolDefinitions>;
+    agentTools: ToolSet;
+    skills: SkillsMap;
+}): Promise<ToolSet>;

package/dist/packages/agent-runtime/src/tools/stream-parser.d.ts

@@ -0,0 +1,33 @@
+import { processStreamWithTools } from '../tool-stream-parser';
+import type { CustomToolCall, ExecuteToolCallParams } from './tool-executor';
+import type { AgentTemplate } from '../templates/types';
+import type { LevelCodeToolCall } from '@levelcode/common/tools/list';
+import type { Logger } from '@levelcode/common/types/contracts/logger';
+import type { ParamsExcluding } from '@levelcode/common/types/function-params';
+import type { Message, ToolMessage } from '@levelcode/common/types/messages/levelcode-message';
+import type { PrintModeEvent } from '@levelcode/common/types/print-mode';
+import type { Subgoal } from '@levelcode/common/types/session-state';
+import type { ProjectFileContext } from '@levelcode/common/util/file';
+export declare function processStream(params: {
+    agentContext: Record<string, Subgoal>;
+    agentTemplate: AgentTemplate;
+    ancestorRunIds: string[];
+    fileContext: ProjectFileContext;
+    fingerprintId: string;
+    fullResponse: string;
+    logger: Logger;
+    messages: Message[];
+    repoId: string | undefined;
+    runId: string;
+    signal: AbortSignal;
+    userId: string | undefined;
+    onCostCalculated: (credits: number) => Promise<void>;
+    onResponseChunk: (chunk: string | PrintModeEvent) => void;
+} & Omit<ExecuteToolCallParams<any>, 'fileProcessingState' | 'fromHandleSteps' | 'fullResponse' | 'input' | 'previousToolCallFinished' | 'state' | 'toolCallId' | 'toolCalls' | 'toolName' | 'toolResults' | 'toolResultsToAddAfterStream'> & ParamsExcluding<typeof processStreamWithTools, 'processors' | 'defaultProcessor' | 'onError' | 'loggerOptions' | 'executeXmlToolCall'>): Promise<{
+    fullResponse: string;
+    fullResponseChunks: string[];
+    hadToolCallError: boolean;
+    messageId: string | null;
+    toolCalls: (CustomToolCall | LevelCodeToolCall)[];
+    toolResults: ToolMessage[];
+}>;

package/dist/packages/agent-runtime/src/tools/tool-executor.d.ts

@@ -0,0 +1,87 @@
+import type { AgentTemplate } from '../templates/types';
+import type { FileProcessingState } from './handlers/tool/write-file';
+import type { ToolName } from '@levelcode/common/tools/constants';
+import type { LevelCodeToolCall } from '@levelcode/common/tools/list';
+import type { AgentRuntimeDeps, AgentRuntimeScopedDeps } from '@levelcode/common/types/contracts/agent-runtime';
+import type { Logger } from '@levelcode/common/types/contracts/logger';
+import type { ToolMessage } from '@levelcode/common/types/messages/levelcode-message';
+import type { PrintModeEvent } from '@levelcode/common/types/print-mode';
+import type { AgentTemplateType, AgentState, Subgoal } from '@levelcode/common/types/session-state';
+import type { CustomToolDefinitions, ProjectFileContext } from '@levelcode/common/util/file';
+import type { ToolCallPart, ToolSet } from 'ai';
+export type CustomToolCall = {
+    toolName: string;
+    input: Record<string, unknown>;
+} & Omit<ToolCallPart, 'type'>;
+export type ToolCallError = {
+    toolName?: string;
+    input: Record<string, unknown>;
+    error: string;
+} & Pick<LevelCodeToolCall, 'toolCallId'>;
+export declare function parseRawToolCall<T extends ToolName = ToolName>(params: {
+    rawToolCall: {
+        toolName: T;
+        toolCallId: string;
+        input: Record<string, unknown>;
+    };
+}): LevelCodeToolCall<T> | ToolCallError;
+export type ExecuteToolCallParams<T extends string = ToolName> = {
+    toolName: T;
+    input: Record<string, unknown>;
+    autoInsertEndStepParam?: boolean;
+    excludeToolFromMessageHistory?: boolean;
+    agentContext: Record<string, Subgoal>;
+    agentState: AgentState;
+    agentStepId: string;
+    ancestorRunIds: string[];
+    agentTemplate: AgentTemplate;
+    clientSessionId: string;
+    fileContext: ProjectFileContext;
+    fileProcessingState: FileProcessingState;
+    fingerprintId: string;
+    fromHandleSteps?: boolean;
+    fullResponse: string;
+    localAgentTemplates: Record<string, AgentTemplate>;
+    logger: Logger;
+    previousToolCallFinished: Promise<void>;
+    prompt: string | undefined;
+    repoId: string | undefined;
+    repoUrl: string | undefined;
+    runId: string;
+    signal: AbortSignal;
+    system: string;
+    tools: ToolSet;
+    toolCallId: string | undefined;
+    toolCalls: (LevelCodeToolCall | CustomToolCall)[];
+    toolResults: ToolMessage[];
+    toolResultsToAddAfterStream: ToolMessage[];
+    skipDirectResultPush?: boolean;
+    userId: string | undefined;
+    userInputId: string;
+    fetch: typeof globalThis.fetch;
+    onCostCalculated: (credits: number) => Promise<void>;
+    onResponseChunk: (chunk: string | PrintModeEvent) => void;
+} & AgentRuntimeDeps & AgentRuntimeScopedDeps;
+export declare function executeToolCall<T extends ToolName>(params: ExecuteToolCallParams<T>): Promise<void>;
+export declare function parseRawCustomToolCall(params: {
+    customToolDefs: CustomToolDefinitions;
+    rawToolCall: {
+        toolName: string;
+        toolCallId: string;
+        input: Record<string, unknown>;
+    };
+    autoInsertEndStepParam?: boolean;
+}): CustomToolCall | ToolCallError;
+export declare function executeCustomToolCall(params: ExecuteToolCallParams<string>): Promise<void>;
+/**
+ * Checks if a tool name matches a spawnable agent and returns the transformed
+ * spawn_agents input if so. Returns null if not an agent tool call.
+ */
+export declare function tryTransformAgentToolCall(params: {
+    toolName: string;
+    input: Record<string, unknown>;
+    spawnableAgents: AgentTemplateType[];
+}): {
+    toolName: 'spawn_agents';
+    input: Record<string, unknown>;
+} | null;

package/dist/packages/agent-runtime/src/util/agent-output.d.ts

@@ -0,0 +1,3 @@
+import type { AgentTemplate } from '@levelcode/common/types/agent-template';
+import type { AgentState, AgentOutput } from '@levelcode/common/types/session-state';
+export declare function getAgentOutput(agentState: AgentState, agentTemplate: AgentTemplate): AgentOutput;

package/dist/packages/agent-runtime/src/util/messages.d.ts

@@ -0,0 +1,68 @@
+import type { System } from '../llm-api/claude';
+import type { Logger } from '@levelcode/common/types/contracts/logger';
+import type { Message } from '@levelcode/common/types/messages/levelcode-message';
+import type { TextPart, ImagePart } from '@levelcode/common/types/messages/content-part';
+export declare function messagesWithSystem(params: {
+    messages: Message[];
+    system: System;
+}): Message[];
+export declare function asUserMessage(str: string): string;
+/**
+ * Combines prompt, params, and content into a unified message content structure.
+ * Always wraps the first text part in <user_message> tags for consistent XML framing.
+ * If you need a specific text part wrapped, put it first or pre-wrap it yourself before calling.
+ */
+export declare function buildUserMessageContent(prompt: string | undefined, params: Record<string, any> | undefined, content?: Array<TextPart | ImagePart>): Array<TextPart | ImagePart>;
+export declare function parseUserMessage(str: string): string | undefined;
+export declare function withSystemInstructionTags(str: string): string;
+export declare function withSystemTags(str: string): string;
+export declare function castAssistantMessage(message: Message): Message | null;
+/**
+ * Trims messages from the beginning to fit within token limits while preserving
+ * important content. Also simplifies terminal command outputs to save tokens.
+ *
+ * The function:
+ * 1. Processes messages from newest to oldest
+ * 2. Simplifies terminal command outputs after keeping N most recent ones
+ * 3. Stops adding messages when approaching token limit
+ *
+ * @param messages - Array of messages to trim
+ * @param systemTokens - Number of tokens used by system prompt
+ * @param maxTotalTokens - Maximum total tokens allowed, defaults to 200k
+ * @returns Trimmed array of messages that fits within token limit
+ */
+export declare function trimMessagesToFitTokenLimit(params: {
+    messages: Message[];
+    systemTokens: number;
+    maxTotalTokens?: number;
+    logger: Logger;
+}): Message[];
+export declare function getMessagesSubset(params: {
+    messages: Message[];
+    otherTokens: number;
+    logger: Logger;
+}): Message[];
+export declare function expireMessages(messages: Message[], endOf: 'agentStep' | 'userPrompt'): Message[];
+/**
+ * Removes tool calls from the message history that don't have corresponding tool responses.
+ * This is important when passing message history to spawned agents, as unfinished tool calls
+ * will cause issues with the LLM expecting tool responses.
+ *
+ * The function:
+ * 1. Collects all toolCallIds from tool response messages
+ * 2. Filters assistant messages to remove tool-call content parts without responses
+ * 3. Removes assistant messages that become empty after filtering
+ */
+export declare function filterUnfinishedToolCalls(messages: Message[]): Message[];
+export declare function getEditedFiles(params: {
+    messages: Message[];
+    logger: Logger;
+}): string[];
+export declare function getPreviouslyReadFiles(params: {
+    messages: Message[];
+    logger: Logger;
+}): {
+    path: string;
+    content: string;
+    referencedBy?: Record<string, string[]>;
+}[];

package/dist/packages/agent-runtime/src/util/parse-tool-calls-from-text.d.ts

@@ -0,0 +1,38 @@
+export type ParsedToolCallFromText = {
+    type: 'tool_call';
+    toolName: string;
+    input: Record<string, unknown>;
+};
+export type ParsedTextSegment = {
+    type: 'text';
+    text: string;
+};
+export type ParsedSegment = ParsedToolCallFromText | ParsedTextSegment;
+/**
+ * Parses text containing tool calls in the <levelcode_tool_call> XML format,
+ * returning interleaved text and tool call segments in order.
+ *
+ * Example input:
+ * ```
+ * Some text before
+ * <levelcode_tool_call>
+ * {
+ *   "cb_tool_name": "read_files",
+ *   "paths": ["file.ts"]
+ * }
+ * </levelcode_tool_call>
+ * Some text after
+ * ```
+ *
+ * @param text - The text containing tool calls in XML format
+ * @returns Array of segments (text and tool calls) in order of appearance
+ */
+export declare function parseTextWithToolCalls(text: string): ParsedSegment[];
+/**
+ * Parses tool calls from text in the <levelcode_tool_call> XML format.
+ * This is a convenience function that returns only tool calls (no text segments).
+ *
+ * @param text - The text containing tool calls in XML format
+ * @returns Array of parsed tool calls with toolName and input
+ */
+export declare function parseToolCallsFromText(text: string): Omit<ParsedToolCallFromText, 'type'>[];

package/dist/packages/agent-runtime/src/util/render-read-files-result.d.ts

@@ -0,0 +1,15 @@
+export interface TokenCallerMap {
+    [filePath: string]: {
+        [token: string]: string[];
+    };
+}
+export declare function renderReadFilesResult(files: {
+    path: string;
+    content: string;
+}[], tokenCallers: TokenCallerMap): {
+    path: string;
+    content: string;
+    referencedBy: {
+        [token: string]: string[];
+    };
+}[];

package/dist/packages/agent-runtime/src/util/simplify-tool-results.d.ts

@@ -0,0 +1,7 @@
+import type { LevelCodeToolOutput } from '@levelcode/common/tools/list';
+import type { Logger } from '@levelcode/common/types/contracts/logger';
+export declare function simplifyReadFileResults(messageContent: LevelCodeToolOutput<'read_files'>): LevelCodeToolOutput<'read_files'>;
+export declare function simplifyTerminalCommandResults(params: {
+    messageContent: LevelCodeToolOutput<'run_terminal_command'>;
+    logger: Logger;
+}): LevelCodeToolOutput<'run_terminal_command'>;

package/dist/packages/agent-runtime/src/util/stream-xml-parser.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Stateful stream XML parser that extracts tool calls from <levelcode_tool_call> XML
+ * and filters them out of the text stream.
+ *
+ * Handles partial tags at chunk boundaries using a stateful approach.
+ */
+export type ParsedToolCall = {
+    toolName: string;
+    input: Record<string, unknown>;
+};
+export type StreamParserState = {
+    /** Buffer for holding partial content when inside a tool call tag or at boundaries */
+    buffer: string;
+    /** Whether we're currently inside a tool call tag */
+    insideToolCall: boolean;
+};
+export type ParseResult = {
+    /** Filtered text with tool call XML removed */
+    filteredText: string;
+    /** Tool calls extracted from this chunk */
+    toolCalls: ParsedToolCall[];
+};
+/**
+ * Creates initial parser state
+ */
+export declare function createStreamParserState(): StreamParserState;
+/**
+ * Parses a stream chunk, extracting tool calls and filtering out the XML.
+ *
+ * @param chunk - The incoming text chunk
+ * @param state - Mutable parser state (updated in place)
+ * @returns Filtered text and any extracted tool calls
+ */
+export declare function parseStreamChunk(chunk: string, state: StreamParserState): ParseResult;

package/dist/packages/agent-runtime/src/util/token-counter.d.ts

@@ -0,0 +1,3 @@
+export declare function countTokens(text: string): number;
+export declare function countTokensJson(text: string | object): number;
+export declare function countTokensForFiles(files: Record<string, string | null>): Record<string, number>;

package/dist/packages/code-map/src/index.d.ts

@@ -0,0 +1,3 @@
+import './types';
+export * from './parse';
+export * from './languages';

package/dist/packages/code-map/src/init-node.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Initialize web-tree-sitter for Node.js environments with proper WASM file location
+ */
+export declare function initTreeSitterForNode(): Promise<void>;

package/dist/packages/code-map/src/languages.d.ts

@@ -0,0 +1,36 @@
+import './types';
+import { Language, Parser, Query } from 'web-tree-sitter';
+export interface LanguageConfig {
+    extensions: string[];
+    wasmFile: string;
+    queryPathOrContent: string;
+    parser?: Parser;
+    query?: Query;
+    language?: Language;
+}
+export interface RuntimeLanguageLoader {
+    loadLanguage(wasmFile: string): Promise<Language>;
+    initParser(): Promise<void>;
+}
+export declare const WASM_FILES: {
+    readonly 'tree-sitter-c-sharp.wasm': "tree-sitter-c-sharp.wasm";
+    readonly 'tree-sitter-cpp.wasm': "tree-sitter-cpp.wasm";
+    readonly 'tree-sitter-go.wasm': "tree-sitter-go.wasm";
+    readonly 'tree-sitter-java.wasm': "tree-sitter-java.wasm";
+    readonly 'tree-sitter-javascript.wasm': "tree-sitter-javascript.wasm";
+    readonly 'tree-sitter-python.wasm': "tree-sitter-python.wasm";
+    readonly 'tree-sitter-ruby.wasm': "tree-sitter-ruby.wasm";
+    readonly 'tree-sitter-rust.wasm': "tree-sitter-rust.wasm";
+    readonly 'tree-sitter-tsx.wasm': "tree-sitter-tsx.wasm";
+    readonly 'tree-sitter-typescript.wasm': "tree-sitter-typescript.wasm";
+};
+export declare const languageTable: LanguageConfig[];
+/**
+ * Set a custom WASM directory for loading tree-sitter WASM files.
+ * This can be useful for custom packaging or deployment scenarios.
+ */
+export declare function setWasmDir(dir: string): void;
+export declare function getWasmDir(): string | undefined;
+export declare function findLanguageConfigByExtension(filePath: string): LanguageConfig | undefined;
+export declare function createLanguageConfig(filePath: string, runtimeLoader: RuntimeLanguageLoader): Promise<LanguageConfig | undefined>;
+export declare function getLanguageConfig(filePath: string): Promise<LanguageConfig | undefined>;

package/dist/packages/code-map/src/parse.d.ts

@@ -0,0 +1,21 @@
+import type { LanguageConfig } from './languages';
+export declare const DEBUG_PARSING = false;
+export interface TokenCallerMap {
+    [filePath: string]: {
+        [token: string]: string[];
+    };
+}
+export interface FileTokenData {
+    tokenScores: {
+        [filePath: string]: {
+            [token: string]: number;
+        };
+    };
+    tokenCallers: TokenCallerMap;
+}
+export declare function getFileTokenScores(projectRoot: string, filePaths: string[], readFile?: (filePath: string) => string | null): Promise<FileTokenData>;
+export declare function parseTokens(filePath: string, languageConfig: LanguageConfig, readFile?: (filePath: string) => string | null): {
+    numLines: number;
+    identifiers: string[];
+    calls: string[];
+};

package/dist/packages/code-map/src/types.d.ts

@@ -0,0 +1,8 @@
+declare module '@vscode/tree-sitter-wasm/wasm/*.wasm' {
+    const content: string;
+    export default content;
+}
+declare module '*.scm' {
+    const content: string;
+    export default content;
+}

package/dist/packages/code-map/src/utils.d.ts

@@ -0,0 +1 @@
+export declare function getDirnameDynamically(): string | undefined;

package/dist/sdk/src/__tests__/client.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/sdk/src/__tests__/code-search.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/sdk/src/__tests__/credentials.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/sdk/src/__tests__/database.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/sdk/src/__tests__/env.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/sdk/src/__tests__/error-utils.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/sdk/src/__tests__/initial-session-state.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/sdk/src/__tests__/knowledge-file-selection.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/sdk/src/__tests__/load-agents.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/sdk/src/__tests__/load-mcp-config.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/sdk/src/__tests__/model-provider.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/sdk/src/__tests__/read-files.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/sdk/src/__tests__/run-cancellation.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/sdk/src/__tests__/run-file-filter.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/sdk/src/__tests__/run-handle-event.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/sdk/src/__tests__/run.integration.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/sdk/src/__tests__/user-knowledge-files.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/sdk/src/__tests__/validate-agents.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/sdk/src/agents/load-agents.d.ts

@@ -0,0 +1,106 @@
+import type { AgentDefinition } from '@levelcode/common/templates/initial-agents-dir/types/agent-definition';
+/**
+ * Agent definition with source file path metadata.
+ */
+export type LoadedAgentDefinition = AgentDefinition & {
+    /** The file path this agent was loaded from */
+    _sourceFilePath: string;
+};
+/**
+ * Loaded agent definitions keyed by agent ID.
+ */
+export type LoadedAgents = Record<string, LoadedAgentDefinition>;
+/**
+ * Resolves environment variable references in MCP server configs.
+ * Values starting with `$` are treated as env var references (e.g., `'$NOTION_TOKEN'`).
+ *
+ * @param env - The env object from MCP config with possible $VAR_NAME references
+ * @param agentId - The agent ID for error messages
+ * @param mcpServerName - The MCP server name for error messages
+ * @returns Resolved env object with all $VAR_NAME values replaced with actual values
+ * @throws Error if a referenced environment variable is missing
+ */
+export declare function resolveMcpEnv(env: Record<string, string> | undefined, agentId: string, mcpServerName: string): Record<string, string>;
+/**
+ * Resolves all MCP server env references in an agent definition.
+ * Mutates the mcpServers object to replace $VAR_NAME references with resolved values.
+ *
+ * @param agent - The agent definition to process
+ * @throws Error if any referenced environment variable is missing
+ */
+export declare function resolveAgentMcpEnv(agent: AgentDefinition): void;
+/**
+ * Validation error for an agent that failed validation.
+ */
+export type AgentValidationError = {
+    /** The agent's ID */
+    agentId: string;
+    /** The source file path where the agent was loaded from */
+    filePath: string;
+    /** The validation error message */
+    message: string;
+};
+/**
+ * Result returned by loadLocalAgents when validate: true.
+ * Contains both the valid agents and any validation errors.
+ */
+export type LoadLocalAgentsResult = {
+    /** Valid agent definitions that passed validation */
+    agents: LoadedAgents;
+    /** Validation errors for agents that failed validation */
+    validationErrors: AgentValidationError[];
+};
+/**
+ * Load agent definitions from `.agents` directories.
+ *
+ * By default, searches for agents in:
+ * - `{cwd}/.agents`
+ * - `{cwd}/../.agents`
+ * - `{homedir}/.agents`
+ *
+ * Agent files can be `.ts`, `.tsx`, `.js`, `.mjs`, or `.cjs`.
+ * TypeScript files are loaded natively by Bun's runtime.
+ *
+ * @param options.agentsPath - Optional path to a specific agents directory
+ * @param options.verbose - Whether to log errors during loading
+ * @param options.validate - Whether to validate agents after loading
+ * @returns When validate is false/omitted: Record of agent definitions keyed by agent ID.
+ *          When validate is true: Object with valid agents and validation errors.
+ *
+ * @example
+ * ```typescript
+ * // Load from default locations
+ * const agents = await loadLocalAgents({ verbose: true })
+ *
+ * // Load from a specific directory
+ * const agents = await loadLocalAgents({ agentsPath: './my-agents' })
+ *
+ * // Load and validate agents - returns both valid agents and errors
+ * const { agents, validationErrors } = await loadLocalAgents({ validate: true })
+ * if (validationErrors.length > 0) {
+ *   console.error('Some agents failed validation:', validationErrors)
+ * }
+ *
+ * // Access source file path for debugging
+ * for (const agent of Object.values(agents)) {
+ *   console.log(`${agent.id} loaded from ${agent._sourceFilePath}`)
+ * }
+ *
+ * // Use with client.run()
+ * const result = await client.run({
+ *   agent: 'my-agent',
+ *   agentDefinitions: Object.values(agents),
+ *   prompt: 'Hello',
+ * })
+ * ```
+ */
+export declare function loadLocalAgents(options: {
+    agentsPath?: string;
+    verbose?: boolean;
+    validate: true;
+}): Promise<LoadLocalAgentsResult>;
+export declare function loadLocalAgents(options: {
+    agentsPath?: string;
+    verbose?: boolean;
+    validate?: false;
+}): Promise<LoadedAgents>;