@compilr-dev/sdk 0.1.0

package/dist/presets/coding.js

@@ -0,0 +1,61 @@
+/**
+ * Coding preset — batteries-included for software development
+ */
+import { readFileTool, writeFileTool, editTool, bashTool, bashOutputTool, killShellTool, grepTool, globTool, todoWriteTool, todoReadTool, webFetchTool, suggestTool, } from '@compilr-dev/agents';
+import { allCodingTools, unifiedTools } from '@compilr-dev/agents-coding';
+const CODING_SYSTEM_PROMPT = `You are a skilled software engineer. You help users with coding tasks including:
+- Writing, reviewing, and debugging code
+- Understanding codebases and architecture
+- Running tests, builds, and other development commands
+- Git operations and version control workflows
+- Code analysis and refactoring
+
+Guidelines:
+- Read files before modifying them to understand existing code
+- Prefer editing existing files over creating new ones
+- Run tests after making changes to verify correctness
+- Use git for version control (commit messages should be descriptive)
+- Follow existing code style and patterns in the project
+- Be concise in explanations, detailed in code`;
+/**
+ * All file operation tools
+ */
+export const fileTools = [
+    readFileTool,
+    writeFileTool,
+    editTool,
+    grepTool,
+    globTool,
+];
+/**
+ * All shell tools
+ */
+export const shellTools = [bashTool, bashOutputTool, killShellTool];
+/**
+ * Web tools
+ */
+export const webTools = [webFetchTool];
+/**
+ * Utility tools (always included in coding preset)
+ */
+const utilityTools = [todoWriteTool, todoReadTool, suggestTool];
+/**
+ * All coding preset tools combined
+ */
+const allPresetTools = [
+    ...fileTools,
+    ...shellTools,
+    ...utilityTools,
+    ...allCodingTools,
+    ...unifiedTools,
+];
+/**
+ * Coding preset — full development environment
+ */
+export const codingPreset = {
+    name: 'coding',
+    tools: allPresetTools,
+    systemPrompt: CODING_SYSTEM_PROMPT,
+    defaultPermissions: 'auto',
+};
+export { webTools as codingWebTools };

package/dist/presets/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Preset registry
+ */
+export type { Preset } from './types.js';
+export { codingPreset } from './coding.js';
+export { readOnlyPreset } from './read-only.js';
+import type { Preset } from './types.js';
+/**
+ * Resolve a preset by name or return a custom preset object
+ */
+export declare function resolvePreset(preset: 'coding' | 'read-only' | 'none' | Preset): Preset;

package/dist/presets/index.js

@@ -0,0 +1,32 @@
+/**
+ * Preset registry
+ */
+export { codingPreset } from './coding.js';
+export { readOnlyPreset } from './read-only.js';
+import { codingPreset } from './coding.js';
+import { readOnlyPreset } from './read-only.js';
+/**
+ * Empty preset — no tools, minimal prompt
+ */
+const nonePreset = {
+    name: 'none',
+    tools: [],
+    systemPrompt: 'You are a helpful assistant.',
+    defaultPermissions: 'auto',
+};
+/**
+ * Resolve a preset by name or return a custom preset object
+ */
+export function resolvePreset(preset) {
+    if (typeof preset !== 'string') {
+        return preset;
+    }
+    switch (preset) {
+        case 'coding':
+            return codingPreset;
+        case 'read-only':
+            return readOnlyPreset;
+        case 'none':
+            return nonePreset;
+    }
+}

package/dist/presets/read-only.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Read-only preset — exploration and analysis without side effects
+ */
+import type { Preset } from './types.js';
+/**
+ * Read-only preset — code review, audits, exploration
+ */
+export declare const readOnlyPreset: Preset;

package/dist/presets/read-only.js

@@ -0,0 +1,44 @@
+/**
+ * Read-only preset — exploration and analysis without side effects
+ */
+import { readFileTool, grepTool, globTool } from '@compilr-dev/agents';
+import { gitStatusTool, gitDiffTool, gitLogTool, gitBlameTool, gitFileHistoryTool, findDefinitionTool, findReferencesTool, findTodosTool, } from '@compilr-dev/agents-coding';
+import { unifiedTools } from '@compilr-dev/agents-coding';
+const READ_ONLY_SYSTEM_PROMPT = `You are a code analysis assistant. You can read and explore code but cannot modify files or run commands.
+
+Your capabilities:
+- Read and search files (read_file, grep, glob)
+- Explore git history (git_log, git_diff, git_status, git_blame)
+- Analyze code structure (find_definition, find_references, find_todos)
+- Multi-language code analysis (TypeScript, Python, Go)
+
+Guidelines:
+- Provide thorough analysis with specific file and line references
+- Explain code patterns, architecture decisions, and potential issues
+- When reviewing changes, focus on correctness, security, and maintainability`;
+/**
+ * Read-only preset — code review, audits, exploration
+ */
+export const readOnlyPreset = {
+    name: 'read-only',
+    tools: [
+        // File reading
+        readFileTool,
+        grepTool,
+        globTool,
+        // Git (read-only operations)
+        gitStatusTool,
+        gitDiffTool,
+        gitLogTool,
+        gitBlameTool,
+        gitFileHistoryTool,
+        // Code search
+        findDefinitionTool,
+        findReferencesTool,
+        findTodosTool,
+        // Unified analysis
+        ...unifiedTools,
+    ],
+    systemPrompt: READ_ONLY_SYSTEM_PROMPT,
+    defaultPermissions: 'read-only',
+};

package/dist/presets/types.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Preset interface for domain-specific agent configurations
+ */
+import type { ToolDefinition } from '@compilr-dev/agents';
+/**
+ * Loosened tool type that accepts any input generic.
+ * Required because Tool<T> is contravariant in T (handler parameter),
+ * so Tool<SpecificInput> is not assignable to Tool<object>.
+ */
+export interface AnyTool {
+    definition: ToolDefinition;
+    execute: (...args: never[]) => Promise<unknown>;
+    parallel?: boolean;
+    silent?: boolean;
+    readonly?: boolean;
+}
+/**
+ * A preset bundles tools, a system prompt, and default settings
+ * for a specific domain (coding, read-only, custom, etc.)
+ */
+export interface Preset {
+    /** Unique name for this preset */
+    name: string;
+    /** Tools included in this preset */
+    tools: AnyTool[];
+    /** System prompt for the agent */
+    systemPrompt: string;
+    /** Default permission mode */
+    defaultPermissions?: 'auto' | 'read-only';
+}

package/dist/presets/types.js

@@ -0,0 +1,4 @@
+/**
+ * Preset interface for domain-specific agent configurations
+ */
+export {};

package/dist/provider.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Provider resolution — auto-detect from env vars or explicit config
+ */
+import type { LLMProvider } from '@compilr-dev/agents';
+import type { ProviderType } from './config.js';
+/**
+ * Detect the provider type from environment variables.
+ * Returns the first match in priority order, or undefined if none found.
+ */
+export declare function detectProviderFromEnv(): ProviderType | undefined;
+/**
+ * Create an LLM provider from a provider type string.
+ */
+export declare function createProviderFromType(type: ProviderType, options?: {
+    model?: string;
+    apiKey?: string;
+    baseUrl?: string;
+    siteName?: string;
+}): LLMProvider;
+/**
+ * Resolve a provider from config.
+ * Priority: explicit LLMProvider > explicit type > env var auto-detection.
+ */
+export declare function resolveProvider(config?: {
+    provider?: ProviderType | LLMProvider;
+    model?: string;
+    apiKey?: string;
+}): LLMProvider;

package/dist/provider.js

@@ -0,0 +1,88 @@
+/**
+ * Provider resolution — auto-detect from env vars or explicit config
+ */
+import { createClaudeProvider, createOpenAIProvider, createGeminiNativeProvider, createOllamaProvider, createTogetherProvider, createGroqProvider, createFireworksProvider, createPerplexityProvider, createOpenRouterProvider, } from '@compilr-dev/agents';
+/**
+ * Environment variable → provider mapping (checked in priority order)
+ */
+const ENV_PROVIDER_MAP = [
+    { envVar: 'ANTHROPIC_API_KEY', type: 'claude' },
+    { envVar: 'OPENAI_API_KEY', type: 'openai' },
+    { envVar: 'GOOGLE_AI_API_KEY', type: 'gemini' },
+    { envVar: 'GEMINI_API_KEY', type: 'gemini' },
+    { envVar: 'TOGETHER_API_KEY', type: 'together' },
+    { envVar: 'GROQ_API_KEY', type: 'groq' },
+    { envVar: 'FIREWORKS_API_KEY', type: 'fireworks' },
+    { envVar: 'PERPLEXITY_API_KEY', type: 'perplexity' },
+    { envVar: 'OPENROUTER_API_KEY', type: 'openrouter' },
+];
+/**
+ * Detect the provider type from environment variables.
+ * Returns the first match in priority order, or undefined if none found.
+ */
+export function detectProviderFromEnv() {
+    for (const { envVar, type } of ENV_PROVIDER_MAP) {
+        if (process.env[envVar]) {
+            return type;
+        }
+    }
+    return undefined;
+}
+/**
+ * Create an LLM provider from a provider type string.
+ */
+export function createProviderFromType(type, options) {
+    const { model, apiKey, baseUrl, siteName } = options ?? {};
+    switch (type) {
+        case 'claude':
+            return createClaudeProvider({ model, apiKey });
+        case 'openai':
+            return createOpenAIProvider({ model, apiKey });
+        case 'gemini':
+            return createGeminiNativeProvider({ model, apiKey });
+        case 'ollama':
+            return createOllamaProvider({ model, baseUrl });
+        case 'together':
+            return createTogetherProvider({ model, apiKey });
+        case 'groq':
+            return createGroqProvider({ model, apiKey });
+        case 'fireworks':
+            return createFireworksProvider({ model, apiKey });
+        case 'perplexity':
+            return createPerplexityProvider({ model, apiKey });
+        case 'openrouter':
+            return createOpenRouterProvider({ model, apiKey, siteName });
+        case 'custom':
+            // Custom endpoints use OpenAI-compatible format
+            return createOpenAIProvider({ model, apiKey });
+    }
+}
+/**
+ * Resolve a provider from config.
+ * Priority: explicit LLMProvider > explicit type > env var auto-detection.
+ */
+export function resolveProvider(config) {
+    // Already an LLMProvider instance
+    if (config?.provider && typeof config.provider !== 'string') {
+        return config.provider;
+    }
+    // Explicit provider type
+    if (config?.provider && typeof config.provider === 'string') {
+        return createProviderFromType(config.provider, {
+            model: config.model,
+            apiKey: config.apiKey,
+        });
+    }
+    // Auto-detect from env
+    const detected = detectProviderFromEnv();
+    if (detected) {
+        return createProviderFromType(detected, {
+            model: config?.model,
+            apiKey: config?.apiKey,
+        });
+    }
+    throw new Error('No LLM provider configured. Either:\n' +
+        '  1. Set an API key env var (ANTHROPIC_API_KEY, OPENAI_API_KEY, etc.)\n' +
+        '  2. Pass provider type: createCompilrAgent({ provider: "claude" })\n' +
+        '  3. Pass a provider instance: createCompilrAgent({ provider: myProvider })');
+}

package/dist/team.d.ts

@@ -0,0 +1,10 @@
+/**
+ * CompilrTeam — multi-agent coordinator
+ *
+ * v0.1: Sequential delegation — coordinator decides which agent handles each step
+ */
+import type { TeamConfig, CompilrTeam as ICompilrTeam } from './config.js';
+/**
+ * Create a multi-agent team
+ */
+export declare function createTeam(config: TeamConfig): ICompilrTeam;

package/dist/team.js

@@ -0,0 +1,168 @@
+/**
+ * CompilrTeam — multi-agent coordinator
+ *
+ * v0.1: Sequential delegation — coordinator decides which agent handles each step
+ */
+import { createCompilrAgent } from './agent.js';
+/**
+ * Role-based system prompt fragments
+ */
+const ROLE_PROMPTS = {
+    architect: 'You are a software architect. Focus on high-level design, system architecture, ' +
+        'API contracts, and technical decisions. Break down complex tasks into smaller pieces.',
+    developer: 'You are a software developer. Focus on writing clean, correct, well-tested code. ' +
+        'Follow existing patterns and conventions in the codebase.',
+    tester: 'You are a QA engineer. Focus on writing tests, finding edge cases, and verifying ' +
+        'correctness. Run tests after changes and report failures clearly.',
+    reviewer: 'You are a code reviewer. Focus on code quality, security, performance, and ' +
+        'maintainability. Provide specific, actionable feedback.',
+};
+/**
+ * Default coordinator prompt
+ */
+const DEFAULT_COORDINATOR_PROMPT = 'You are a team coordinator. Analyze the task and delegate to the appropriate team member. ' +
+    'Synthesize their results into a coherent response.';
+/**
+ * Merge usage info
+ */
+function mergeUsage(a, b) {
+    return {
+        inputTokens: a.inputTokens + b.inputTokens,
+        outputTokens: a.outputTokens + b.outputTokens,
+        totalTokens: a.totalTokens + b.totalTokens,
+    };
+}
+/**
+ * CompilrTeam implementation — sequential delegation
+ */
+class CompilrTeamImpl {
+    agents = new Map();
+    coordinator;
+    agentConfigs;
+    constructor(config) {
+        this.agentConfigs = config.agents;
+        // Create coordinator agent
+        this.coordinator = createCompilrAgent({
+            ...config,
+            systemPrompt: config.coordinatorPrompt ?? DEFAULT_COORDINATOR_PROMPT,
+            maxIterations: config.maxIterations ?? 10,
+        });
+        // Create team agents
+        for (const [name, agentConfig] of Object.entries(config.agents)) {
+            const systemPrompt = agentConfig.systemPrompt ?? (agentConfig.role ? ROLE_PROMPTS[agentConfig.role] : undefined);
+            const agent = createCompilrAgent({
+                provider: agentConfig.provider ?? config.provider,
+                model: agentConfig.model ?? config.model,
+                apiKey: config.apiKey,
+                preset: config.preset,
+                cwd: config.cwd,
+                systemPrompt: systemPrompt ?? false,
+                maxIterations: agentConfig.maxIterations ?? 30,
+                tools: agentConfig.toolFilter ? { filter: agentConfig.toolFilter } : config.tools,
+                hooks: config.hooks,
+                guardrails: config.guardrails,
+            });
+            this.agents.set(name, agent);
+        }
+    }
+    async run(message, options) {
+        const agentResults = {};
+        let totalUsage = { inputTokens: 0, outputTokens: 0, totalTokens: 0 };
+        // Simple sequential delegation: run each agent on the full task
+        // (v0.1 — future versions will use coordinator for routing)
+        for (const [name, agent] of this.agents) {
+            const role = this.agentConfigs[name].role ?? 'general';
+            const agentMessage = `[You are the ${role} on this team]\n\n${message}`;
+            options?.onEvent?.({
+                type: 'subagent_start',
+                name,
+                task: message,
+            });
+            const result = await agent.run(agentMessage, {
+                signal: options?.signal,
+                maxIterations: options?.maxIterations,
+                toolFilter: options?.toolFilter,
+            });
+            agentResults[name] = result;
+            totalUsage = mergeUsage(totalUsage, result.usage);
+            options?.onEvent?.({
+                type: 'subagent_end',
+                name,
+                result: {
+                    response: result.response,
+                    toolCalls: result.toolCalls.length,
+                    iterations: result.iterations,
+                },
+            });
+        }
+        // Synthesize results via coordinator
+        const synthesis = `Team results for task: "${message}"\n\n` +
+            Object.entries(agentResults)
+                .map(([name, r]) => `## ${name}\n${r.response}`)
+                .join('\n\n') +
+            '\n\nPlease synthesize these results into a final coherent response.';
+        const coordResult = await this.coordinator.run(synthesis, {
+            signal: options?.signal,
+        });
+        totalUsage = mergeUsage(totalUsage, coordResult.usage);
+        return {
+            response: coordResult.response,
+            agentResults,
+            usage: totalUsage,
+        };
+    }
+    async *stream(message, options) {
+        const events = [];
+        let notifyNewEvent;
+        const finished = { value: false };
+        const onEvent = (event) => {
+            events.push(event);
+            notifyNewEvent?.();
+        };
+        const markDone = () => {
+            finished.value = true;
+            notifyNewEvent?.();
+        };
+        const runPromise = this.run(message, {
+            ...options,
+            onEvent: onEvent,
+        })
+            .then((result) => {
+            events.push({ type: 'team_done', response: result.response });
+            markDone();
+        })
+            .catch(markDone);
+        for (;;) {
+            if (events.length > 0) {
+                const event = events.shift();
+                if (event) {
+                    yield event;
+                }
+            }
+            else if (finished.value) {
+                break;
+            }
+            else {
+                await new Promise((r) => {
+                    notifyNewEvent = r;
+                });
+            }
+        }
+        await runPromise;
+    }
+    getAgent(name) {
+        return this.agents.get(name);
+    }
+    abort() {
+        for (const agent of this.agents.values()) {
+            agent.abort();
+        }
+        this.coordinator.abort();
+    }
+}
+/**
+ * Create a multi-agent team
+ */
+export function createTeam(config) {
+    return new CompilrTeamImpl(config);
+}

package/dist/tools.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Tool assembly — merge preset tools with user configuration
+ */
+import type { ToolConfig } from './config.js';
+import type { Preset, AnyTool } from './presets/types.js';
+/**
+ * Assemble the final tool list from a preset and user config.
+ *
+ * Priority:
+ * 1. If `filter` is set, only include those tools from the preset
+ * 2. Otherwise, use boolean flags to toggle tool groups
+ * 3. Custom tools are always appended
+ */
+export declare function assembleTools(preset: Preset, toolConfig?: ToolConfig): AnyTool[];
+/**
+ * Deduplicate tools by name (last wins)
+ */
+export declare function deduplicateTools(tools: AnyTool[]): AnyTool[];

package/dist/tools.js

@@ -0,0 +1,95 @@
+/**
+ * Tool assembly — merge preset tools with user configuration
+ */
+import { fileTools, shellTools, codingWebTools } from './presets/coding.js';
+import { allCodingTools, unifiedTools } from '@compilr-dev/agents-coding';
+/**
+ * Tool names for file operations
+ */
+const FILE_TOOL_NAMES = new Set(fileTools.map((t) => t.definition.name));
+/**
+ * Tool names for shell operations
+ */
+const SHELL_TOOL_NAMES = new Set(shellTools.map((t) => t.definition.name));
+/**
+ * Tool names for coding operations (git, runners, analysis)
+ */
+const CODING_TOOL_NAMES = new Set([...allCodingTools, ...unifiedTools].map((t) => t.definition.name));
+/**
+ * Tool names for web operations
+ */
+const WEB_TOOL_NAMES = new Set(codingWebTools.map((t) => t.definition.name));
+/**
+ * Assemble the final tool list from a preset and user config.
+ *
+ * Priority:
+ * 1. If `filter` is set, only include those tools from the preset
+ * 2. Otherwise, use boolean flags to toggle tool groups
+ * 3. Custom tools are always appended
+ */
+export function assembleTools(preset, toolConfig) {
+    const presetTools = preset.tools;
+    // If no config, return all preset tools
+    if (!toolConfig) {
+        return [...presetTools];
+    }
+    // If filter (allowlist) is specified, it takes precedence over flags
+    if (toolConfig.filter) {
+        const allowSet = new Set(toolConfig.filter);
+        const filtered = presetTools.filter((t) => allowSet.has(t.definition.name));
+        return [...filtered, ...(toolConfig.custom ?? [])];
+    }
+    // Apply boolean flags to filter preset tools
+    const result = [];
+    for (const tool of presetTools) {
+        const name = tool.definition.name;
+        if (FILE_TOOL_NAMES.has(name)) {
+            if (toolConfig.files !== false) {
+                result.push(tool);
+            }
+            continue;
+        }
+        if (SHELL_TOOL_NAMES.has(name)) {
+            if (toolConfig.shell !== false) {
+                result.push(tool);
+            }
+            continue;
+        }
+        if (CODING_TOOL_NAMES.has(name)) {
+            if (toolConfig.coding !== false) {
+                result.push(tool);
+            }
+            continue;
+        }
+        if (WEB_TOOL_NAMES.has(name)) {
+            if (toolConfig.web === true) {
+                result.push(tool);
+            }
+            continue;
+        }
+        // Utility tools (todo, suggest) — always include
+        result.push(tool);
+    }
+    // If web tools were requested but not in the preset, add them
+    if (toolConfig.web === true) {
+        const hasWeb = result.some((t) => WEB_TOOL_NAMES.has(t.definition.name));
+        if (!hasWeb) {
+            result.push(...codingWebTools);
+        }
+    }
+    // Append custom tools
+    if (toolConfig.custom) {
+        result.push(...toolConfig.custom);
+    }
+    return result;
+}
+/**
+ * Deduplicate tools by name (last wins)
+ */
+export function deduplicateTools(tools) {
+    const seen = new Map();
+    for (const tool of tools) {
+        seen.set(tool.definition.name, tool);
+    }
+    return [...seen.values()];
+}

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@compilr-dev/sdk",
+  "version": "0.1.0",
+  "description": "Universal agent runtime for building AI-powered applications",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist",
+    "lint": "eslint src/",
+    "lint:fix": "eslint src/ --fix",
+    "format": "prettier --write \"src/**/*.ts\"",
+    "format:check": "prettier --check \"src/**/*.ts\"",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "prepublishOnly": "npm run clean && npm run lint && npm run test && npm run build",
+    "typecheck": "tsc --noEmit"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/compilr-dev/sdk.git"
+  },
+  "keywords": [
+    "ai",
+    "agents",
+    "sdk",
+    "llm",
+    "claude",
+    "openai",
+    "gemini",
+    "runtime",
+    "multi-llm",
+    "anthropic"
+  ],
+  "author": "Carmelo Scozzola",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/compilr-dev/sdk/issues"
+  },
+  "homepage": "https://github.com/compilr-dev/sdk#readme",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@compilr-dev/agents": "^0.3.14",
+    "@compilr-dev/agents-coding": "^1.0.2"
+  },
+  "devDependencies": {
+    "@anthropic-ai/sdk": "^0.78.0",
+    "@eslint/js": "^9.39.1",
+    "@types/node": "^25.2.3",
+    "@vitest/coverage-v8": "^4.0.18",
+    "eslint": "^9.39.1",
+    "prettier": "^3.7.1",
+    "typescript": "^5.3.0",
+    "typescript-eslint": "^8.48.0",
+    "vitest": "^4.0.18"
+  }
+}