@levelcode/sdk 0.2.2 → 0.2.3

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__/team-api.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>;

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

@@ -0,0 +1,69 @@
+import { z } from 'zod/v4';
+import type { MCPConfig } from '@levelcode/common/types/mcp';
+/**
+ * Schema for the mcp.json file format.
+ * Matches the standard MCP config format used by Claude Code, Cursor, etc.
+ */
+export declare const mcpFileSchema: z.ZodObject<{
+    mcpServers: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodObject<{
+        type: z.ZodDefault<z.ZodEnum<{
+            http: "http";
+            sse: "sse";
+        }>>;
+        url: z.ZodString;
+        params: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+        headers: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodDefault<z.ZodLiteral<"stdio">>;
+        command: z.ZodString;
+        args: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        env: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+    }, z.core.$strict>]>>>;
+}, z.core.$strip>;
+export type MCPFileConfig = z.infer<typeof mcpFileSchema>;
+/**
+ * Loaded MCP configuration with resolved environment variables.
+ */
+export type LoadedMCPConfig = {
+    mcpServers: Record<string, MCPConfig>;
+    /** The file path this config was loaded from */
+    _sourceFilePath: string;
+};
+/**
+ * Load MCP configuration from `mcp.json` files in `.agents` directories.
+ *
+ * By default, searches for mcp.json in:
+ * - `{cwd}/.agents/mcp.json`
+ * - `{cwd}/../.agents/mcp.json`
+ * - `{homedir}/.agents/mcp.json`
+ *
+ * Later directories take precedence, so project MCP servers override global ones.
+ * Environment variable references (e.g., `$API_KEY`) are resolved from process.env.
+ *
+ * @param options.verbose - Whether to log errors during loading
+ * @returns Record of MCP server configurations keyed by server name
+ *
+ * @example
+ * ```typescript
+ * // Load from default locations
+ * const mcpConfig = await loadMCPConfig({ verbose: true })
+ *
+ * // Access MCP servers
+ * for (const [serverName, config] of Object.entries(mcpConfig.mcpServers)) {
+ *   console.log(`MCP server: ${serverName}`)
+ * }
+ * ```
+ */
+export declare function loadMCPConfig(options: {
+    verbose?: boolean;
+}): Promise<LoadedMCPConfig>;
+/**
+ * Synchronously load MCP configuration from `mcp.json` files in `.agents` directories.
+ * This is a sync version for use in contexts where async is not available.
+ *
+ * @param options.verbose - Whether to log errors during loading
+ * @returns Record of MCP server configurations keyed by server name
+ */
+export declare function loadMCPConfigSync(options: {
+    verbose?: boolean;
+}): LoadedMCPConfig;