@levelcode/sdk 0.0.5 → 0.2.0

package/dist/common/src/templates/initial-agents-dir/types/agent-definition.d.ts

@@ -0,0 +1,296 @@
+/**
+ * LevelCode Agent Type Definitions
+ *
+ * This file provides TypeScript type definitions for creating custom LevelCode agents.
+ * Import these types in your agent files to get full type safety and IntelliSense.
+ *
+ * Usage in .agents/your-agent.ts:
+ *   import { AgentDefinition, ToolName, ModelName } from './types/agent-definition'
+ *
+ *   const definition: AgentDefinition = {
+ *     // ... your agent configuration with full type safety ...
+ *   }
+ *
+ *   export default definition
+ */
+export interface AgentDefinition {
+    /** Unique identifier for this agent. Must contain only lowercase letters, numbers, and hyphens, e.g. 'code-reviewer' */
+    id: string;
+    /** Version string (if not provided, will default to '0.0.1' and be bumped on each publish) */
+    version?: string;
+    /** Publisher ID for the agent. Must be provided if you want to publish the agent. */
+    publisher?: string;
+    /** Human-readable name for the agent */
+    displayName: string;
+    /** AI model to use for this agent. Can be any model in OpenRouter: https://openrouter.ai/models */
+    model: ModelName;
+    /**
+     * https://openrouter.ai/docs/use-cases/reasoning-tokens
+     * One of `max_tokens` or `effort` is required.
+     * If `exclude` is true, reasoning will be removed from the response. Default is false.
+     */
+    reasoningOptions?: {
+        enabled?: boolean;
+        exclude?: boolean;
+    } & ({
+        max_tokens: number;
+    } | {
+        effort: 'high' | 'medium' | 'low' | 'minimal' | 'none';
+    });
+    /**
+     * Provider routing options for OpenRouter.
+     * Controls which providers to use and fallback behavior.
+     * See https://openrouter.ai/docs/features/provider-routing
+     */
+    providerOptions?: {
+        /**
+         * List of provider slugs to try in order (e.g. ["anthropic", "openai"])
+         */
+        order?: string[];
+        /**
+         * Whether to allow backup providers when primary is unavailable (default: true)
+         */
+        allow_fallbacks?: boolean;
+        /**
+         * Only use providers that support all parameters in your request (default: false)
+         */
+        require_parameters?: boolean;
+        /**
+         * Control whether to use providers that may store data
+         */
+        data_collection?: 'allow' | 'deny';
+        /**
+         * List of provider slugs to allow for this request
+         */
+        only?: string[];
+        /**
+         * List of provider slugs to skip for this request
+         */
+        ignore?: string[];
+        /**
+         * List of quantization levels to filter by (e.g. ["int4", "int8"])
+         */
+        quantizations?: Array<'int4' | 'int8' | 'fp4' | 'fp6' | 'fp8' | 'fp16' | 'bf16' | 'fp32' | 'unknown'>;
+        /**
+         * Sort providers by price, throughput, or latency
+         */
+        sort?: 'price' | 'throughput' | 'latency';
+        /**
+         * Maximum pricing you want to pay for this request
+         */
+        max_price?: {
+            prompt?: number | string;
+            completion?: number | string;
+            image?: number | string;
+            audio?: number | string;
+            request?: number | string;
+        };
+    };
+    /** MCP servers by name. Names cannot contain `/`. */
+    mcpServers?: Record<string, MCPConfig>;
+    /**
+     * Tools this agent can use.
+     *
+     * By default, all tools are available from any specified MCP server. In
+     * order to limit the tools from a specific MCP server, add the tool name(s)
+     * in the format `'mcpServerName/toolName1'`, `'mcpServerName/toolName2'`,
+     * etc.
+     */
+    toolNames?: (ToolName | (string & {}))[];
+    /** Other agents this agent can spawn, like 'levelcode/file-picker@0.0.1'.
+     *
+     * Use the fully qualified agent id from the agent store, including publisher and version: 'levelcode/file-picker@0.0.1'
+     * (publisher and version are required!)
+     *
+     * Or, use the agent id from a local agent file in your .agents directory: 'file-picker'.
+     */
+    spawnableAgents?: string[];
+    /** The input schema required to spawn the agent. Provide a prompt string and/or a params object or none.
+     * 80% of the time you want just a prompt string with a description:
+     * inputSchema: {
+     *   prompt: { type: 'string', description: 'A description of what info would be helpful to the agent' }
+     * }
+     */
+    inputSchema?: {
+        prompt?: {
+            type: 'string';
+            description?: string;
+        };
+        params?: JsonObjectSchema;
+    };
+    /** How the agent should output a response to its parent (defaults to 'last_message')
+     *
+     * last_message: The last message from the agent, typically after using tools.
+     *
+     * all_messages: All messages from the agent, including tool calls and results.
+     *
+     * structured_output: Make the agent output a JSON object. Can be used with outputSchema or without if you want freeform json output.
+     */
+    outputMode?: 'last_message' | 'all_messages' | 'structured_output';
+    /** JSON schema for structured output (when outputMode is 'structured_output') */
+    outputSchema?: JsonObjectSchema;
+    /** Prompt for when and why to spawn this agent. Include the main purpose and use cases.
+     *
+     * This field is key if the agent is intended to be spawned by other agents. */
+    spawnerPrompt?: string;
+    /** Whether to include conversation history from the parent agent in context.
+     *
+     * Defaults to false.
+     * Use this when the agent needs to know all the previous messages in the conversation.
+     */
+    includeMessageHistory?: boolean;
+    /** Whether to inherit the parent agent's system prompt instead of using this agent's own systemPrompt.
+     *
+     * Defaults to false.
+     * Use this when you want to enable prompt caching by preserving the same system prompt prefix.
+     * Cannot be used together with the systemPrompt field.
+     */
+    inheritParentSystemPrompt?: boolean;
+    /** Background information for the agent. Fairly optional. Prefer using instructionsPrompt for agent instructions. */
+    systemPrompt?: string;
+    /** Instructions for the agent.
+     *
+     * IMPORTANT: Updating this prompt is the best way to shape the agent's behavior.
+     * This prompt is inserted after each user input. */
+    instructionsPrompt?: string;
+    /** Prompt inserted at each agent step.
+     *
+     * Powerful for changing the agent's behavior, but usually not necessary for smart models.
+     * Prefer instructionsPrompt for most instructions. */
+    stepPrompt?: string;
+    /** Programmatically step the agent forward and run tools.
+     *
+     * You can either yield:
+     * - A tool call object with toolName and input properties.
+     * - 'STEP' to run agent's model and generate one assistant message.
+     * - 'STEP_ALL' to run the agent's model until it uses the end_turn tool or stops includes no tool calls in a message.
+     *
+     * Or use 'return' to end the turn.
+     *
+     * Example 1:
+     * function* handleSteps({ agentState, prompt, params, logger }) {
+     *   logger.info('Starting file read process')
+     *   const { toolResult } = yield {
+     *     toolName: 'read_files',
+     *     input: { paths: ['file1.txt', 'file2.txt'] }
+     *   }
+     *   yield 'STEP_ALL'
+     *
+     *   // Optionally do a post-processing step here...
+     *   logger.info('Files read successfully, setting output')
+     *   yield {
+     *     toolName: 'set_output',
+     *     input: {
+     *       output: 'The files were read successfully.',
+     *     },
+     *   }
+     * }
+     *
+     * Example 2:
+     * handleSteps: function* ({ agentState, prompt, params, logger }) {
+     *   while (true) {
+     *     logger.debug('Spawning thinker agent')
+     *     yield {
+     *       toolName: 'spawn_agents',
+     *       input: {
+     *         agents: [
+     *         {
+     *           agent_type: 'thinker',
+     *           prompt: 'Think deeply about the user request',
+     *         },
+     *       ],
+     *     },
+     *   }
+     *   const { stepsComplete } = yield 'STEP'
+     *   if (stepsComplete) break
+     * }
+     * }
+     */
+    handleSteps?: (context: AgentStepContext) => Generator<ToolCall | 'STEP' | 'STEP_ALL' | StepText | GenerateN, void, {
+        agentState: AgentState;
+        toolResult: ToolResultOutput[] | undefined;
+        stepsComplete: boolean;
+        nResponses?: string[];
+    }>;
+}
+export interface AgentState {
+    agentId: string;
+    runId: string;
+    parentId: string | undefined;
+    /** The agent's conversation history: messages from the user and the assistant. */
+    messageHistory: Message[];
+    /** The last value set by the set_output tool. This is a plain object or undefined if not set. */
+    output: Record<string, any> | undefined;
+    /** The system prompt for this agent. */
+    systemPrompt: string;
+    /** The tool definitions for this agent. */
+    toolDefinitions: Record<string, {
+        description: string | undefined;
+        inputSchema: {};
+    }>;
+    /**
+     * The token count from the Anthropic API.
+     * This is updated on every agent step via the /api/v1/token-count endpoint.
+     */
+    contextTokenCount: number;
+}
+/**
+ * Context provided to handleSteps generator function
+ */
+export interface AgentStepContext {
+    agentState: AgentState;
+    prompt?: string;
+    params?: Record<string, any>;
+    logger: Logger;
+}
+export type StepText = {
+    type: 'STEP_TEXT';
+    text: string;
+};
+export type GenerateN = {
+    type: 'GENERATE_N';
+    n: number;
+};
+/**
+ * Tool call object for handleSteps generator
+ */
+export type ToolCall<T extends ToolName = ToolName> = {
+    [K in T]: {
+        toolName: K;
+        input: GetToolParams<K>;
+        includeToolCall?: boolean;
+    };
+}[T];
+/**
+ * File operation tools
+ */
+export type FileEditingTools = 'read_files' | 'write_file' | 'str_replace';
+/**
+ * Code analysis tools
+ */
+export type CodeAnalysisTools = 'code_search' | 'find_files' | 'read_files';
+/**
+ * Terminal and system tools
+ */
+export type TerminalTools = 'run_terminal_command' | 'code_search';
+/**
+ * Web and browser tools
+ */
+export type WebTools = 'web_search' | 'read_docs';
+/**
+ * Agent management tools
+ */
+export type AgentTools = 'spawn_agents';
+/**
+ * Output and control tools
+ */
+export type OutputTools = 'set_output';
+/**
+ * AI models available for agents. Pick from our selection of recommended models or choose any model in OpenRouter.
+ *
+ * See available models at https://openrouter.ai/models
+ */
+export type ModelName = 'openai/gpt-5.1' | 'openai/gpt-5.1-chat' | 'openai/gpt-5-mini' | 'openai/gpt-5-nano' | 'anthropic/claude-sonnet-4.5' | 'anthropic/claude-opus-4.1' | 'google/gemini-2.5-pro' | 'google/gemini-2.5-flash' | 'google/gemini-2.5-flash-lite' | 'google/gemini-2.5-flash-preview-09-2025' | 'google/gemini-2.5-flash-lite-preview-09-2025' | 'x-ai/grok-4-07-09' | 'x-ai/grok-4-fast' | 'x-ai/grok-code-fast-1' | 'qwen/qwen3-max' | 'qwen/qwen3-coder-plus' | 'qwen/qwen3-coder' | 'qwen/qwen3-coder:nitro' | 'qwen/qwen3-coder-flash' | 'qwen/qwen3-235b-a22b-2507' | 'qwen/qwen3-235b-a22b-2507:nitro' | 'qwen/qwen3-235b-a22b-thinking-2507' | 'qwen/qwen3-235b-a22b-thinking-2507:nitro' | 'qwen/qwen3-30b-a3b' | 'qwen/qwen3-30b-a3b:nitro' | 'deepseek/deepseek-chat-v3-0324' | 'deepseek/deepseek-chat-v3-0324:nitro' | 'deepseek/deepseek-r1-0528' | 'deepseek/deepseek-r1-0528:nitro' | 'moonshotai/kimi-k2' | 'moonshotai/kimi-k2:nitro' | 'z-ai/glm-4.6' | 'z-ai/glm-4.6:nitro' | (string & {});
+import type { ToolName, GetToolParams } from './tools';
+import type { Message, ToolResultOutput, JsonObjectSchema, MCPConfig, Logger } from './util-types';
+export type { ToolName, GetToolParams };

package/dist/common/src/templates/initial-agents-dir/types/tools.d.ts

@@ -0,0 +1,308 @@
+/**
+ * Union type of all available tool names
+ */
+export type ToolName = 'add_message' | 'ask_user' | 'code_search' | 'end_turn' | 'find_files' | 'glob' | 'list_directory' | 'lookup_agent_info' | 'propose_str_replace' | 'propose_write_file' | 'read_docs' | 'read_files' | 'read_subtree' | 'run_file_change_hooks' | 'run_terminal_command' | 'set_messages' | 'set_output' | 'skill' | 'spawn_agents' | 'str_replace' | 'suggest_followups' | 'task_completed' | 'think_deeply' | 'web_search' | 'write_file' | 'write_todos';
+/**
+ * Map of tool names to their parameter types
+ */
+export interface ToolParamsMap {
+    add_message: AddMessageParams;
+    ask_user: AskUserParams;
+    code_search: CodeSearchParams;
+    end_turn: EndTurnParams;
+    find_files: FindFilesParams;
+    glob: GlobParams;
+    list_directory: ListDirectoryParams;
+    lookup_agent_info: LookupAgentInfoParams;
+    propose_str_replace: ProposeStrReplaceParams;
+    propose_write_file: ProposeWriteFileParams;
+    read_docs: ReadDocsParams;
+    read_files: ReadFilesParams;
+    read_subtree: ReadSubtreeParams;
+    run_file_change_hooks: RunFileChangeHooksParams;
+    run_terminal_command: RunTerminalCommandParams;
+    set_messages: SetMessagesParams;
+    set_output: SetOutputParams;
+    skill: SkillParams;
+    spawn_agents: SpawnAgentsParams;
+    str_replace: StrReplaceParams;
+    suggest_followups: SuggestFollowupsParams;
+    task_completed: TaskCompletedParams;
+    think_deeply: ThinkDeeplyParams;
+    web_search: WebSearchParams;
+    write_file: WriteFileParams;
+    write_todos: WriteTodosParams;
+}
+/**
+ * Add a new message to the conversation history. To be used for complex requests that can't be solved in a single step, as you may forget what happened!
+ */
+export interface AddMessageParams {
+    role: 'user' | 'assistant';
+    content: string;
+}
+/**
+ * Ask the user multiple choice questions and pause execution until they respond.
+ */
+export interface AskUserParams {
+    /** List of multiple choice questions to ask the user */
+    questions: {
+        /** The question to ask the user */
+        question: string;
+        /** Short label (max 12 chars) displayed as a chip/tag */
+        header?: string;
+        /** Array of answer options with label and optional description (minimum 2) */
+        options: {
+            /** The display text for this option */
+            label: string;
+            /** Explanation shown when option is focused */
+            description?: string;
+        }[];
+        /** If true, allows selecting multiple options (checkbox). If false, single selection only (radio). */
+        multiSelect?: boolean;
+        /** Validation rules for "Other" text input */
+        validation?: {
+            /** Maximum length for "Other" text input */
+            maxLength?: number;
+            /** Minimum length for "Other" text input */
+            minLength?: number;
+            /** Regex pattern for "Other" text input */
+            pattern?: string;
+            /** Custom error message when pattern fails */
+            patternError?: string;
+        };
+    }[];
+}
+/**
+ * Search for string patterns in the project's files. This tool uses ripgrep (rg), a fast line-oriented search tool. Use this tool only when read_files is not sufficient to find the files you need.
+ */
+export interface CodeSearchParams {
+    /** The pattern to search for. */
+    pattern: string;
+    /** Optional ripgrep flags to customize the search (e.g., "-i" for case-insensitive, "-g *.ts -g *.js" for TypeScript and JavaScript files only, "-g !*.test.ts" to exclude Typescript test files,  "-A 3" for 3 lines after match, "-B 2" for 2 lines before match). */
+    flags?: string;
+    /** Optional working directory to search within, relative to the project root. Defaults to searching the entire project. */
+    cwd?: string;
+    /** Maximum number of results to return per file. Defaults to 15. There is also a global limit of 250 results across all files. */
+    maxResults?: number;
+}
+/**
+ * End your turn, regardless of any new tool results that might be coming. This will allow the user to type another prompt.
+ */
+export interface EndTurnParams {
+}
+/**
+ * Find several files related to a brief natural language description of the files or the name of a function or class you are looking for.
+ */
+export interface FindFilesParams {
+    /** A brief natural language description of the files or the name of a function or class you are looking for. It's also helpful to mention a directory or two to look within. */
+    prompt: string;
+}
+/**
+ * Search for files matching a glob pattern. Returns matching file paths sorted by modification time.
+ */
+export interface GlobParams {
+    /** Glob pattern to match files against (e.g., *.js, src/glob/*.ts, glob/test/glob/*.go). */
+    pattern: string;
+    /** Optional working directory to search within, relative to project root. If not provided, searches from project root. */
+    cwd?: string;
+}
+/**
+ * List files and directories in the specified path. Returns separate arrays of file names and directory names.
+ */
+export interface ListDirectoryParams {
+    /** Directory path to list, relative to the project root. */
+    path: string;
+}
+/**
+ * Retrieve information about an agent by ID
+ */
+export interface LookupAgentInfoParams {
+    /** Agent ID (short local or full published format) */
+    agentId: string;
+}
+/**
+ * Propose string replacements in a file without actually applying them.
+ */
+export interface ProposeStrReplaceParams {
+    /** The path to the file to edit. */
+    path: string;
+    /** Array of replacements to make. */
+    replacements: {
+        /** The string to replace. This must be an *exact match* of the string you want to replace, including whitespace and punctuation. */
+        old: string;
+        /** The string to replace the corresponding old string with. Can be empty to delete. */
+        new: string;
+        /** Whether to allow multiple replacements of old string. */
+        allowMultiple?: boolean;
+    }[];
+}
+/**
+ * Propose creating or editing a file without actually applying the changes.
+ */
+export interface ProposeWriteFileParams {
+    /** Path to the file relative to the **project root** */
+    path: string;
+    /** What the change is intended to do in only one sentence. */
+    instructions: string;
+    /** Edit snippet to apply to the file. */
+    content: string;
+}
+/**
+ * Fetch up-to-date documentation for libraries and frameworks using Context7 API.
+ */
+export interface ReadDocsParams {
+    /** The library or framework name (e.g., "Next.js", "MongoDB", "React"). Use the official name as it appears in documentation if possible. Only public libraries available in Context7's database are supported, so small or private libraries may not be available. */
+    libraryTitle: string;
+    /** Specific topic to focus on (e.g., "routing", "hooks", "authentication") */
+    topic: string;
+    /** Optional maximum number of tokens to return. Defaults to 20000. Values less than 10000 are automatically increased to 10000. */
+    max_tokens?: number;
+}
+/**
+ * Read the multiple files from disk and return their contents. Use this tool to read as many files as would be helpful to answer the user's request.
+ */
+export interface ReadFilesParams {
+    /** List of file paths to read. */
+    paths: string[];
+}
+/**
+ * Read one or more directory subtrees (as a blob including subdirectories, file names, and parsed variables within each source file) or return parsed variable names for files. If no paths are provided, returns the entire project tree.
+ */
+export interface ReadSubtreeParams {
+    /** List of paths to directories or files. Relative to the project root. If omitted, the entire project tree is used. */
+    paths?: string[];
+    /** Maximum token budget for the subtree blob; the tree will be truncated to fit within this budget by first dropping file variables and then removing the most-nested files and directories. */
+    maxTokens?: number;
+}
+/**
+ * Parameters for run_file_change_hooks tool
+ */
+export interface RunFileChangeHooksParams {
+    /** List of file paths that were changed and should trigger file change hooks */
+    files: string[];
+}
+/**
+ * Execute a CLI command from the **project root** (different from the user's cwd).
+ */
+export interface RunTerminalCommandParams {
+    /** CLI command valid for user's OS. */
+    command: string;
+    /** Either SYNC (waits, returns output) or BACKGROUND (runs in background). Default SYNC */
+    process_type?: 'SYNC' | 'BACKGROUND';
+    /** The working directory to run the command in. Default is the project root. */
+    cwd?: string;
+    /** Set to -1 for no timeout. Does not apply for BACKGROUND commands. Default 30 */
+    timeout_seconds?: number;
+}
+/**
+ * Set the conversation history to the provided messages.
+ */
+export interface SetMessagesParams {
+    messages: any;
+}
+/**
+ * JSON object to set as the agent output. This completely replaces any previous output. If the agent was spawned, this value will be passed back to its parent. If the agent has an outputSchema defined, the output will be validated against it.
+ */
+export interface SetOutputParams {
+}
+/**
+ * Load a skill's full instructions when relevant to the current task. Skills are loaded on-demand - only load them when you need their specific guidance.
+ */
+export interface SkillParams {
+    /** The name of the skill to load */
+    name: string;
+}
+/**
+ * Spawn multiple agents and send a prompt and/or parameters to each of them. These agents will run in parallel. Note that that means they will run independently. If you need to run agents sequentially, use spawn_agents with one agent at a time instead.
+ */
+export interface SpawnAgentsParams {
+    agents: {
+        /** Agent to spawn */
+        agent_type: string;
+        /** Prompt to send to the agent */
+        prompt?: string;
+        /** Parameters object for the agent (if any) */
+        params?: Record<string, any>;
+    }[];
+}
+/**
+ * Replace strings in a file with new strings.
+ */
+export interface StrReplaceParams {
+    /** The path to the file to edit. */
+    path: string;
+    /** Array of replacements to make. */
+    replacements: {
+        /** The string to replace. This must be an *exact match* of the string you want to replace, including whitespace and punctuation. */
+        old: string;
+        /** The string to replace the corresponding old string with. Can be empty to delete. */
+        new: string;
+        /** Whether to allow multiple replacements of old string. */
+        allowMultiple?: boolean;
+    }[];
+}
+/**
+ * Suggest clickable followup prompts to the user.
+ */
+export interface SuggestFollowupsParams {
+    /** List of suggested followup prompts the user can click to send */
+    followups: {
+        /** The full prompt text to send as a user message when clicked */
+        prompt: string;
+        /** Short display label for the card (defaults to truncated prompt if not provided) */
+        label?: string;
+    }[];
+}
+/**
+ * Signal that the task is complete. Use this tool when:
+- The user's request is completely fulfilled
+- You need clarification from the user before continuing
+- You are stuck or need help from the user to continue
+
+This tool explicitly marks the end of your work on the current task.
+ */
+export interface TaskCompletedParams {
+}
+/**
+ * Deeply consider complex tasks by brainstorming approaches and tradeoffs step-by-step.
+ */
+export interface ThinkDeeplyParams {
+    /** Detailed step-by-step analysis. Initially keep each step concise (max ~5-7 words per step). */
+    thought: string;
+}
+/**
+ * Search the web for current information using Linkup API.
+ */
+export interface WebSearchParams {
+    /** The search query to find relevant web content */
+    query: string;
+    /** Search depth - 'standard' for quick results, 'deep' for more comprehensive search. Default is 'standard'. */
+    depth?: 'standard' | 'deep';
+}
+/**
+ * Create or edit a file with the given content.
+ */
+export interface WriteFileParams {
+    /** Path to the file relative to the **project root** */
+    path: string;
+    /** What the change is intended to do in only one sentence. */
+    instructions: string;
+    /** Edit snippet to apply to the file. */
+    content: string;
+}
+/**
+ * Write a todo list to track tasks for multi-step implementations. Use this frequently to maintain an updated step-by-step plan.
+ */
+export interface WriteTodosParams {
+    /** List of todos with their completion status. Add ALL of the applicable tasks to the list, so you don't forget to do anything. Try to order the todos the same way you will complete them. Do not mark todos as completed if you have not completed them yet! */
+    todos: {
+        /** Description of the task */
+        task: string;
+        /** Whether the task is completed */
+        completed: boolean;
+    }[];
+}
+/**
+ * Get parameters type for a specific tool
+ */
+export type GetToolParams<T extends ToolName> = ToolParamsMap[T];