create-bk-agent 0.23.4 → 0.23.6

package/templates/base/single/src/providers/openai-compatible.ts

@@ -1,104 +0,0 @@
-import OpenAI from 'openai';
-import type { LLMProvider, LLMMessage, LLMStreamCallbacks, ToolDefinition } from '@backendkit-labs/agent-core';
-
-export interface OpenAICompatibleProviderOptions {
-    apiKey: string;
-    baseUrl: string;
-    model: string;
-    maxRetries?: number;
-}
-
-function isRetryable(err: unknown): boolean {
-    if (err && typeof err === 'object' && 'status' in err) {
-        const s = (err as { status: number }).status;
-        return s === 429 || s >= 500;
-    }
-    return false;
-}
-
-const sleep = (ms: number) => new Promise<void>(r => setTimeout(r, ms));
-
-export class OpenAICompatibleProvider implements LLMProvider {
-    private readonly client: OpenAI;
-    private readonly model: string;
-    private readonly maxRetries: number;
-
-    constructor(opts: OpenAICompatibleProviderOptions) {
-        this.client     = new OpenAI({ apiKey: opts.apiKey, baseURL: opts.baseUrl, maxRetries: 0 });
-        this.model      = opts.model;
-        this.maxRetries = opts.maxRetries ?? 3;
-    }
-
-    async chat(messages: LLMMessage[], tools: ToolDefinition[], callbacks: LLMStreamCallbacks): Promise<void> {
-        const oaiTools = tools.map(t => ({
-            type: 'function' as const,
-            function: { name: t.name, description: t.description, parameters: t.parameters },
-        })) as OpenAI.Chat.ChatCompletionTool[];
-
-        let attempt = 0;
-        let emitted = false;
-
-        while (attempt < this.maxRetries) {
-            attempt++;
-            try {
-                await this.stream(messages, oaiTools, {
-                    ...callbacks,
-                    onChunk: (d) => { emitted = true; callbacks.onChunk?.(d); },
-                });
-                return;
-            } catch (err) {
-                if (emitted || !isRetryable(err) || attempt >= this.maxRetries) {
-                    callbacks.onError(err instanceof Error ? err : new Error(String(err)));
-                    return;
-                }
-                await sleep(Math.min(1000 * 2 ** attempt, 16_000));
-            }
-        }
-    }
-
-    private async stream(
-        messages: LLMMessage[],
-        oaiTools: OpenAI.Chat.ChatCompletionTool[],
-        callbacks: LLMStreamCallbacks,
-    ): Promise<void> {
-        const stream = await this.client.chat.completions.create({
-            model: this.model,
-            messages: messages as OpenAI.Chat.ChatCompletionMessageParam[],
-            tools:       oaiTools.length ? oaiTools : undefined,
-            tool_choice: oaiTools.length ? 'auto'   : undefined,
-            stream: true,
-            stream_options: { include_usage: true },
-        });
-
-        let content = '';
-        const toolBuffers = new Map<number, { id: string; name: string; args: string }>();
-
-        for await (const chunk of stream) {
-            if (chunk.usage) callbacks.onMetrics?.(chunk.usage.prompt_tokens, chunk.usage.completion_tokens);
-            const delta = chunk.choices[0]?.delta;
-            if (!delta) continue;
-            if (delta.content) { content += delta.content; callbacks.onChunk?.(delta.content); }
-            if (delta.tool_calls) {
-                for (const tc of delta.tool_calls) {
-                    if (!toolBuffers.has(tc.index)) toolBuffers.set(tc.index, { id: '', name: '', args: '' });
-                    const buf = toolBuffers.get(tc.index)!;
-                    if (tc.id) buf.id = tc.id;
-                    if (tc.function?.name)      buf.name += tc.function.name;
-                    if (tc.function?.arguments) buf.args += tc.function.arguments;
-                }
-            }
-        }
-
-        const toolCalls = [...toolBuffers.entries()]
-            .sort(([a], [b]) => a - b)
-            .map(([, b]) => ({ id: b.id, type: 'function' as const, function: { name: b.name, arguments: b.args } }));
-
-        for (const tc of toolCalls) callbacks.onToolCall?.(tc.function.name, tc.function.arguments, tc.id);
-
-        callbacks.onDone({
-            role: 'assistant',
-            content: content || null,
-            tool_calls: toolCalls.length ? toolCalls : undefined,
-        });
-    }
-}

package/templates/coding/.env.example

@@ -1,8 +0,0 @@
-# LLM provider — pick one
-ANTHROPIC_API_KEY=sk-ant-...
-# OPENAI_API_KEY=sk-...
-# DEEPSEEK_API_KEY=...
-
-# Provider to use: anthropic | openai | deepseek
-LLM_PROVIDER=anthropic
-LLM_MODEL=claude-sonnet-4-6

package/templates/coding/package.json

@@ -1,26 +0,0 @@
-{
-  "name": "my-coding-agent",
-  "version": "0.1.0",
-  "private": true,
-  "description": "Coding assistant agent — edit files, run commands, search code",
-  "main": "dist/index.js",
-  "scripts": {
-    "dev": "ts-node src/index.ts",
-    "build": "tsc",
-    "start": "node dist/index.js",
-    "typecheck": "tsc --noEmit"
-  },
-  "dependencies": {
-    "@backendkit-labs/agent-coding": "^0.28.0",
-    "@backendkit-labs/agent-core": "^0.36.0",
-    "dotenv": "^16.0.0"
-  },
-  "devDependencies": {
-    "@types/node": "^20.0.0",
-    "ts-node": "^10.9.0",
-    "typescript": "^5.4.0"
-  },
-  "engines": {
-    "node": ">=20.0.0"
-  }
-}

package/templates/coding/src/index.ts

@@ -1,42 +0,0 @@
-import 'dotenv/config';
-import * as readline from 'readline';
-import { createCodingEngine, TerminalTransport } from '@backendkit-labs/agent-coding';
-
-// ── Provider setup ────────────────────────────────────────────────────────────
-
-const provider = process.env.LLM_PROVIDER ?? 'anthropic';
-const apiKey   = process.env.ANTHROPIC_API_KEY ?? process.env.OPENAI_API_KEY ?? process.env.LLM_API_KEY ?? '';
-const model    = process.env.LLM_MODEL;
-
-if (!apiKey) {
-    console.error('Missing API key. Set ANTHROPIC_API_KEY or OPENAI_API_KEY in .env');
-    process.exit(1);
-}
-
-// ── Engine ────────────────────────────────────────────────────────────────────
-
-const transport = new TerminalTransport();
-
-const engine = createCodingEngine({
-    providers:       { [provider]: { apiKey, ...(model ? { model } : {}) } },
-    defaultProvider: provider,
-    workingDir:      process.cwd(),
-    appName:         'my-coding-agent',
-    transport,
-});
-
-// ── REPL ──────────────────────────────────────────────────────────────────────
-
-const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-
-function prompt() {
-    rl.question('\n❯ ', async (input) => {
-        const trimmed = input.trim();
-        if (!trimmed || trimmed === '/exit') { rl.close(); return; }
-        await engine.run(trimmed);
-        prompt();
-    });
-}
-
-console.log('Coding agent ready. Type your request or /exit to quit.\n');
-prompt();

package/templates/coding/tsconfig.json

@@ -1,17 +0,0 @@
-{
-  "compilerOptions": {
-    "target": "ES2022",
-    "module": "commonjs",
-    "moduleResolution": "node16",
-    "lib": ["ES2022"],
-    "types": ["node"],
-    "outDir": "dist",
-    "rootDir": "src",
-    "strict": true,
-    "skipLibCheck": true,
-    "esModuleInterop": true,
-    "resolveJsonModule": true
-  },
-  "include": ["src/**/*"],
-  "exclude": ["node_modules", "dist"]
-}

package/templates/domain-agent/.env.example

@@ -1,7 +0,0 @@
-# LLM — any OpenAI-compatible endpoint
-LLM_API_KEY=sk-...
-LLM_BASE_URL=https://api.openai.com/v1
-LLM_MODEL=gpt-4o
-
-# TODO: Add your domain-specific env vars here
-# MY_SERVICE_URL=http://localhost:8080

package/templates/domain-agent/package.json

@@ -1,27 +0,0 @@
-{
-  "name": "my-domain-agent",
-  "version": "0.1.0",
-  "private": true,
-  "description": "Multi-agent system: orchestrator + domain specialists",
-  "main": "dist/index.js",
-  "scripts": {
-    "dev": "ts-node src/index.ts",
-    "build": "tsc",
-    "start": "node dist/index.js",
-    "typecheck": "tsc --noEmit"
-  },
-  "dependencies": {
-    "@backendkit-labs/agent-core": "^0.36.0",
-    "dotenv": "^16.0.0",
-    "openai": "^4.0.0",
-    "zod": "^4.6.6"
-  },
-  "devDependencies": {
-    "@types/node": "^20.0.0",
-    "ts-node": "^10.9.0",
-    "typescript": "^5.4.0"
-  },
-  "engines": {
-    "node": ">=20.0.0"
-  }
-}

package/templates/domain-agent/src/agents/orchestrator.ts

@@ -1,22 +0,0 @@
-import type { AgentProfile } from '@backendkit-labs/agent-core';
-
-// The orchestrator receives every user request and delegates to the right specialist.
-// It does NOT call tools directly — it uses ask_agent to route work.
-export const ORCHESTRATOR_PROFILE: AgentProfile = {
-    id: 'orchestrator',
-    name: 'Orchestrator',
-    icon: '🎯',
-    description: 'Routes requests to the right specialist agent',
-    delegatesTo: ['specialist-a', 'specialist-b'], // TODO: list your specialists
-    allowedTools: [],
-    systemPrompt: `You are the orchestrator for a TODO: <describe your domain> system.
-
-Your ONLY job is to analyze the user request and delegate to the right specialist via ask_agent.
-Do not attempt to handle requests directly.
-
-Available specialists:
-- specialist-a: TODO describe what this specialist handles
-- specialist-b: TODO describe what this specialist handles
-
-Always delegate. Never answer directly.`,
-};

package/templates/domain-agent/src/agents/specialist-a.ts

@@ -1,17 +0,0 @@
-import type { AgentProfile } from '@backendkit-labs/agent-core';
-
-// TODO: Rename this file and agent to match your domain (e.g. docker-agent.ts, k8s-agent.ts)
-export const SPECIALIST_A_PROFILE: AgentProfile = {
-    id: 'specialist-a',
-    name: 'Specialist A',
-    icon: '🔧',
-    description: 'TODO: describe what this specialist does',
-    delegatesTo: [],
-    allowedTools: [
-        'example_action', // TODO: list the tool names this agent can use
-    ],
-    systemPrompt: `You are a specialist in TODO: <your domain area>.
-
-Use the available tools to complete the task delegated to you.
-Be precise and report results clearly.`,
-};

package/templates/domain-agent/src/agents/specialist-b.ts

@@ -1,16 +0,0 @@
-import type { AgentProfile } from '@backendkit-labs/agent-core';
-
-// TODO: Rename and customize for your second specialist
-export const SPECIALIST_B_PROFILE: AgentProfile = {
-    id: 'specialist-b',
-    name: 'Specialist B',
-    icon: '📊',
-    description: 'TODO: describe what this specialist does',
-    delegatesTo: [],
-    allowedTools: [
-        'example_query', // TODO: list the tool names this agent can use
-    ],
-    systemPrompt: `You are a specialist in TODO: <your domain area>.
-
-Use the available tools to complete the task delegated to you.`,
-};

package/templates/domain-agent/src/config.ts

@@ -1,19 +0,0 @@
-import 'dotenv/config';
-
-export interface Config {
-    llmApiKey: string;
-    llmBaseUrl: string;
-    llmModel: string;
-    // TODO: add your domain-specific config fields
-}
-
-export function loadConfig(): Config {
-    const llmApiKey = process.env.LLM_API_KEY ?? '';
-    if (!llmApiKey) throw new Error('Missing LLM_API_KEY in environment');
-
-    return {
-        llmApiKey,
-        llmBaseUrl: process.env.LLM_BASE_URL ?? 'https://api.openai.com/v1',
-        llmModel:   process.env.LLM_MODEL   ?? 'gpt-4o',
-    };
-}

package/templates/domain-agent/src/engine.ts

@@ -1,49 +0,0 @@
-import {
-    AgentEngine,
-    AgentRegistry,
-    ToolRegistry,
-    ProviderRegistry,
-    CallbackTransport,
-} from '@backendkit-labs/agent-core';
-import { OpenAICompatibleProvider } from './providers/openai-compatible';
-import { loadConfig } from './config';
-import { ORCHESTRATOR_PROFILE } from './agents/orchestrator';
-import { SPECIALIST_A_PROFILE } from './agents/specialist-a';
-import { SPECIALIST_B_PROFILE } from './agents/specialist-b';
-import { exampleAction, exampleQuery } from './tools/example-tools';
-
-export function createDomainEngine(transport: CallbackTransport): AgentEngine {
-    const config = loadConfig();
-
-    const tools = new ToolRegistry();
-    tools
-        .register(exampleAction)
-        .register(exampleQuery);
-    // TODO: register more tools
-
-    const agents = new AgentRegistry();
-    agents
-        .register(ORCHESTRATOR_PROFILE)
-        .register(SPECIALIST_A_PROFILE)
-        .register(SPECIALIST_B_PROFILE);
-    // TODO: register more specialists
-
-    const providers = new ProviderRegistry();
-    providers.register('default', new OpenAICompatibleProvider({
-        apiKey:  config.llmApiKey,
-        baseUrl: config.llmBaseUrl,
-        model:   config.llmModel,
-    }));
-
-    return new AgentEngine({
-        model:          { provider: 'default', id: config.llmModel },
-        agents,
-        tools,
-        providers,
-        defaultProvider:  'default',
-        defaultAgentId:   'orchestrator',
-        transport,
-        maxIterations:    30,
-        iterationMode:    'auto',
-    });
-}

package/templates/domain-agent/src/index.ts

@@ -1,27 +0,0 @@
-import * as readline from 'readline';
-import { CallbackTransport } from '@backendkit-labs/agent-core';
-import { createDomainEngine } from './engine';
-
-const transport = new CallbackTransport((event) => {
-    if (event.type === 'token')       process.stdout.write(event.content);
-    if (event.type === 'tool_call')   console.log(`\n⚙  ${event.name}`);
-    if (event.type === 'agent_switch') console.log(`\n→ ${event.to_name ?? event.to}`);
-    if (event.type === 'block_end')   console.log();
-    if (event.type === 'error')       console.error(`\nError: ${event.message}`);
-});
-
-const engine = createDomainEngine(transport);
-
-const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-
-function prompt() {
-    rl.question('\n> ', async (input) => {
-        const trimmed = input.trim();
-        if (!trimmed || trimmed === '/exit') { rl.close(); return; }
-        await engine.run(trimmed);
-        prompt();
-    });
-}
-
-console.log('Domain agent ready. Type your request or /exit to quit.\n');
-prompt();

package/templates/domain-agent/src/providers/openai-compatible.ts

@@ -1,104 +0,0 @@
-import OpenAI from 'openai';
-import type { LLMProvider, LLMMessage, LLMStreamCallbacks, ToolDefinition } from '@backendkit-labs/agent-core';
-
-export interface OpenAICompatibleProviderOptions {
-    apiKey: string;
-    baseUrl: string;
-    model: string;
-    maxRetries?: number;
-}
-
-function isRetryable(err: unknown): boolean {
-    if (err && typeof err === 'object' && 'status' in err) {
-        const s = (err as { status: number }).status;
-        return s === 429 || s >= 500;
-    }
-    return false;
-}
-
-const sleep = (ms: number) => new Promise<void>(r => setTimeout(r, ms));
-
-export class OpenAICompatibleProvider implements LLMProvider {
-    private readonly client: OpenAI;
-    private readonly model: string;
-    private readonly maxRetries: number;
-
-    constructor(opts: OpenAICompatibleProviderOptions) {
-        this.client     = new OpenAI({ apiKey: opts.apiKey, baseURL: opts.baseUrl, maxRetries: 0 });
-        this.model      = opts.model;
-        this.maxRetries = opts.maxRetries ?? 3;
-    }
-
-    async chat(messages: LLMMessage[], tools: ToolDefinition[], callbacks: LLMStreamCallbacks): Promise<void> {
-        const oaiTools = tools.map(t => ({
-            type: 'function' as const,
-            function: { name: t.name, description: t.description, parameters: t.parameters },
-        })) as OpenAI.Chat.ChatCompletionTool[];
-
-        let attempt = 0;
-        let emitted = false;
-
-        while (attempt < this.maxRetries) {
-            attempt++;
-            try {
-                await this.stream(messages, oaiTools, {
-                    ...callbacks,
-                    onChunk: (d) => { emitted = true; callbacks.onChunk?.(d); },
-                });
-                return;
-            } catch (err) {
-                if (emitted || !isRetryable(err) || attempt >= this.maxRetries) {
-                    callbacks.onError(err instanceof Error ? err : new Error(String(err)));
-                    return;
-                }
-                await sleep(Math.min(1000 * 2 ** attempt, 16_000));
-            }
-        }
-    }
-
-    private async stream(
-        messages: LLMMessage[],
-        oaiTools: OpenAI.Chat.ChatCompletionTool[],
-        callbacks: LLMStreamCallbacks,
-    ): Promise<void> {
-        const stream = await this.client.chat.completions.create({
-            model: this.model,
-            messages: messages as OpenAI.Chat.ChatCompletionMessageParam[],
-            tools:       oaiTools.length ? oaiTools : undefined,
-            tool_choice: oaiTools.length ? 'auto'   : undefined,
-            stream: true,
-            stream_options: { include_usage: true },
-        });
-
-        let content = '';
-        const toolBuffers = new Map<number, { id: string; name: string; args: string }>();
-
-        for await (const chunk of stream) {
-            if (chunk.usage) callbacks.onMetrics?.(chunk.usage.prompt_tokens, chunk.usage.completion_tokens);
-            const delta = chunk.choices[0]?.delta;
-            if (!delta) continue;
-            if (delta.content) { content += delta.content; callbacks.onChunk?.(delta.content); }
-            if (delta.tool_calls) {
-                for (const tc of delta.tool_calls) {
-                    if (!toolBuffers.has(tc.index)) toolBuffers.set(tc.index, { id: '', name: '', args: '' });
-                    const buf = toolBuffers.get(tc.index)!;
-                    if (tc.id) buf.id = tc.id;
-                    if (tc.function?.name)      buf.name += tc.function.name;
-                    if (tc.function?.arguments) buf.args += tc.function.arguments;
-                }
-            }
-        }
-
-        const toolCalls = [...toolBuffers.entries()]
-            .sort(([a], [b]) => a - b)
-            .map(([, b]) => ({ id: b.id, type: 'function' as const, function: { name: b.name, arguments: b.args } }));
-
-        for (const tc of toolCalls) callbacks.onToolCall?.(tc.function.name, tc.function.arguments, tc.id);
-
-        callbacks.onDone({
-            role: 'assistant',
-            content: content || null,
-            tool_calls: toolCalls.length ? toolCalls : undefined,
-        });
-    }
-}

package/templates/domain-agent/src/tools/example-tools.ts

@@ -1,28 +0,0 @@
-import { defineTool, z } from '@backendkit-labs/agent-core';
-
-// TODO: Replace these with tools that call your actual domain SDK/API
-
-export const exampleAction = defineTool({
-    name: 'example_action',
-    description: 'TODO: describe what this tool does',
-    input: z.object({
-        target: z.string().describe('Target to act on'),
-        // TODO: add more parameters
-    }),
-    execute: async ({ target }) => {
-        // TODO: implement the actual action
-        return `Action executed on: ${target}`;
-    },
-});
-
-export const exampleQuery = defineTool({
-    name: 'example_query',
-    description: 'TODO: describe what this query returns',
-    input: z.object({
-        filter: z.string().optional().describe('Optional filter'),
-    }),
-    execute: async ({ filter }) => {
-        // TODO: implement the actual query
-        return JSON.stringify({ results: [], filter });
-    },
-});

package/templates/domain-agent/tsconfig.json

@@ -1,17 +0,0 @@
-{
-  "compilerOptions": {
-    "target": "ES2022",
-    "module": "commonjs",
-    "moduleResolution": "node16",
-    "lib": ["ES2022"],
-    "types": ["node"],
-    "outDir": "dist",
-    "rootDir": "src",
-    "strict": true,
-    "skipLibCheck": true,
-    "esModuleInterop": true,
-    "resolveJsonModule": true
-  },
-  "include": ["src/**/*"],
-  "exclude": ["node_modules", "dist"]
-}

package/templates/mcp-server/package.json

@@ -1,30 +0,0 @@
-{
-  "name": "my-mcp-server",
-  "version": "0.1.0",
-  "private": true,
-  "description": "MCP server — expose agent tools via Model Context Protocol",
-  "main": "dist/server.js",
-  "bin": {
-    "my-mcp-server": "./dist/server.js"
-  },
-  "scripts": {
-    "dev": "ts-node src/server.ts",
-    "build": "tsc",
-    "start": "node dist/server.js",
-    "typecheck": "tsc --noEmit"
-  },
-  "dependencies": {
-    "@backendkit-labs/agent-core": "^0.36.0",
-    "@modelcontextprotocol/sdk": "^1.12.0",
-    "dotenv": "^16.0.0",
-    "zod": "^4.6.6"
-  },
-  "devDependencies": {
-    "@types/node": "^20.0.0",
-    "ts-node": "^10.9.0",
-    "typescript": "^5.4.0"
-  },
-  "engines": {
-    "node": ">=20.0.0"
-  }
-}

package/templates/mcp-server/src/server.ts

@@ -1,40 +0,0 @@
-#!/usr/bin/env node
-import 'dotenv/config';
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { z } from 'zod';
-import { exampleHandler, exampleInputSchema } from './tools/example';
-
-// ── MCP Server ────────────────────────────────────────────────────────────────
-
-const server = new McpServer({
-    name: 'my-mcp-server',
-    version: '0.1.0',
-});
-
-// ── Register tools ────────────────────────────────────────────────────────────
-
-// @ts-expect-error: MCP SDK + zod generic depth limit, safe at runtime
-server.tool(
-    'example_query',
-    'TODO: describe what this tool does',
-    exampleInputSchema.shape,
-    async (args: z.infer<typeof exampleInputSchema>) => ({
-        content: [{ type: 'text' as const, text: await exampleHandler(args) }],
-    }),
-);
-
-// TODO: register more tools following the same pattern:
-// server.tool('tool_name', 'description', schema.shape, handler)
-
-// ── Transport: stdio (for Claude Desktop / Cursor / VS Code) ─────────────────
-
-const transport = new StdioServerTransport();
-await server.connect(transport);
-
-// To use this server, add it to your MCP client config:
-// {
-//   "mcpServers": {
-//     "my-server": { "command": "npx", "args": ["my-mcp-server"] }
-//   }
-// }

package/templates/mcp-server/src/tools/example.ts

@@ -1,10 +0,0 @@
-import { z } from 'zod';
-
-export const exampleInputSchema = z.object({
-    query: z.string().describe('The query to process'),
-});
-
-export async function exampleHandler({ query }: z.infer<typeof exampleInputSchema>): Promise<string> {
-    // TODO: implement your tool logic
-    return `Result for: ${query}`;
-}

package/templates/mcp-server/tsconfig.json

@@ -1,16 +0,0 @@
-{
-  "compilerOptions": {
-    "target": "ES2022",
-    "module": "commonjs",
-    "moduleResolution": "node16",
-    "lib": ["ES2022"],
-    "types": ["node"],
-    "outDir": "dist",
-    "rootDir": "src",
-    "strict": true,
-    "skipLibCheck": true,
-    "esModuleInterop": true
-  },
-  "include": ["src/**/*"],
-  "exclude": ["node_modules", "dist"]
-}