kernelbot 1.0.0

package/.env.example

@@ -0,0 +1,2 @@
+ANTHROPIC_API_KEY=sk-ant-...
+TELEGRAM_BOT_TOKEN=123456:ABC-DEF...

package/README.md

@@ -0,0 +1,138 @@
+# KernelBot
+
+AI engineering agent — a Telegram bot backed by Claude Sonnet with full OS control via tool use.
+
+Send a message in Telegram, and KernelBot will read files, write code, run commands, and respond with the results. It's your personal engineering assistant with direct access to your machine.
+
+## How It Works
+
+```
+You (Telegram) → KernelBot → Claude Sonnet (Anthropic API)
+                                    ↕
+                              OS Tools (shell, files, directories)
+```
+
+KernelBot runs a **tool-use loop**: Claude decides which tools to call, KernelBot executes them on your OS, feeds results back, and Claude continues until the task is done. One message can trigger dozens of tool calls autonomously.
+
+## Tools
+
+| Tool              | Description                                         |
+| ----------------- | --------------------------------------------------- |
+| `execute_command` | Run any shell command (git, npm, python, etc.)      |
+| `read_file`       | Read file contents with optional line limits        |
+| `write_file`      | Write/create files, auto-creates parent directories |
+| `list_directory`  | List directory contents, optionally recursive       |
+
+## Installation
+
+```bash
+npm install -g kernelbot
+```
+
+This installs the `kernelbot` command globally.
+
+## Quick Start
+
+```bash
+# Interactive setup — creates .env and config.yaml
+kernelbot init
+
+# Verify everything works
+kernelbot check
+
+# Launch the bot
+kernelbot start
+```
+
+## Commands
+
+| Command                   | Description                                               |
+| ------------------------- | --------------------------------------------------------- |
+| `kernelbot start`         | Start the Telegram bot                                    |
+| `kernelbot run "prompt"`  | One-off agent call without Telegram (for testing/scripts) |
+| `kernelbot check`         | Validate config and test API connections                  |
+| `kernelbot init`          | Interactive setup wizard                                  |
+
+## Configuration
+
+KernelBot looks for `config.yaml` in the current directory or `~/.kernelbot/`. Secrets are loaded from `.env`.
+
+### `.env`
+
+```
+ANTHROPIC_API_KEY=sk-ant-...
+TELEGRAM_BOT_TOKEN=123456:ABC-DEF...
+```
+
+### `config.yaml`
+
+```yaml
+bot:
+  name: KernelBot
+
+anthropic:
+  model: claude-sonnet-4-20250514
+  max_tokens: 8192
+  temperature: 0.3
+  max_tool_depth: 25 # max tool calls per message
+
+telegram:
+  allowed_users: [] # empty = allow all (dev mode)
+  # allowed_users: [123456789]  # lock to specific Telegram user IDs
+
+security:
+  blocked_paths: # paths the agent cannot touch
+    - /etc/shadow
+    - /etc/passwd
+
+logging:
+  level: info
+  max_file_size: 5242880 # 5 MB
+
+conversation:
+  max_history: 50 # messages per chat
+```
+
+## Security
+
+- **User allowlist** — restrict bot access to specific Telegram user IDs. Empty list = dev mode (anyone can use it).
+- **Blocked paths** — files/directories the agent is forbidden from reading or writing (e.g., `/etc/shadow`, SSH keys).
+- **Audit logging** — every tool call is logged to `kernel-audit.log` with user, tool, params, result, and duration. Secrets in params are automatically redacted.
+- **Command timeout** — shell commands are killed after 30 seconds by default.
+
+## Project Structure
+
+```
+KernelBot/
+├── bin/
+│   └── kernel.js           # CLI entry point
+├── src/
+│   ├── agent.js            # Sonnet tool-use loop
+│   ├── bot.js              # Telegram bot (polling, auth, message handling)
+│   ├── conversation.js     # Per-chat conversation history
+│   ├── prompts/
+│   │   └── system.js       # System prompt
+│   ├── security/
+│   │   ├── auth.js         # User allowlist
+│   │   └── audit.js        # Tool call audit logging
+│   ├── tools/
+│   │   ├── os.js           # OS tool definitions + handlers
+│   │   └── index.js        # Tool registry + dispatcher
+│   └── utils/
+│       ├── config.js       # Config loading (yaml + env + defaults)
+│       ├── display.js      # CLI display (logo, spinners, banners)
+│       └── logger.js       # Winston logger
+├── config.example.yaml
+├── .env.example
+└── package.json
+```
+
+## Requirements
+
+- Node.js 18+
+- [Anthropic API key](https://console.anthropic.com/)
+- [Telegram Bot Token](https://t.me/BotFather)
+
+## Author
+
+Abdullah Al-Tahrei

package/bin/kernel.js

@@ -0,0 +1,197 @@
+#!/usr/bin/env node
+
+// Suppress punycode deprecation warning from transitive deps
+process.removeAllListeners('warning');
+process.on('warning', (w) => { if (w.name !== 'DeprecationWarning' || !w.message.includes('punycode')) console.warn(w); });
+
+import { Command } from 'commander';
+import { createInterface } from 'readline';
+import { writeFileSync, existsSync } from 'fs';
+import { loadConfig } from '../src/utils/config.js';
+import { createLogger, getLogger } from '../src/utils/logger.js';
+import {
+  showLogo,
+  showStartupCheck,
+  showStartupComplete,
+  showError,
+} from '../src/utils/display.js';
+import { createAuditLogger } from '../src/security/audit.js';
+import { ConversationManager } from '../src/conversation.js';
+import { Agent } from '../src/agent.js';
+import { startBot } from '../src/bot.js';
+import Anthropic from '@anthropic-ai/sdk';
+
+const program = new Command();
+
+program
+  .name('kernelbot')
+  .description('KernelBot — AI engineering agent with full OS control')
+  .version('1.0.0');
+
+// ─── kernel start ────────────────────────────────────────────
+program
+  .command('start')
+  .description('Start KernelBot Telegram bot')
+  .action(async () => {
+    showLogo();
+
+    const config = loadConfig();
+    createLogger(config);
+    createAuditLogger();
+    const logger = getLogger();
+
+    // Startup checks
+    const checks = [];
+
+    checks.push(
+      await showStartupCheck('Configuration loaded', async () => {
+        if (!config.anthropic.api_key) throw new Error('ANTHROPIC_API_KEY not set');
+        if (!config.telegram.bot_token) throw new Error('TELEGRAM_BOT_TOKEN not set');
+      }),
+    );
+
+    checks.push(
+      await showStartupCheck('Anthropic API connection', async () => {
+        const client = new Anthropic({ apiKey: config.anthropic.api_key });
+        await client.messages.create({
+          model: config.anthropic.model,
+          max_tokens: 16,
+          messages: [{ role: 'user', content: 'ping' }],
+        });
+      }),
+    );
+
+    if (checks.some((c) => !c)) {
+      showError('Startup checks failed. Fix the issues above and try again.');
+      process.exit(1);
+    }
+
+    const conversationManager = new ConversationManager(config);
+    const agent = new Agent({ config, conversationManager });
+
+    startBot(config, agent);
+    showStartupComplete();
+  });
+
+// ─── kernel run ──────────────────────────────────────────────
+program
+  .command('run')
+  .description('Run a one-off prompt through the agent (no Telegram)')
+  .argument('<prompt>', 'The prompt to send')
+  .action(async (prompt) => {
+    const config = loadConfig();
+    createLogger(config);
+    createAuditLogger();
+
+    if (!config.anthropic.api_key) {
+      showError('ANTHROPIC_API_KEY not set. Run `kernelbot init` first.');
+      process.exit(1);
+    }
+
+    const conversationManager = new ConversationManager(config);
+    const agent = new Agent({ config, conversationManager });
+
+    const reply = await agent.processMessage('cli', prompt, {
+      id: 'cli',
+      username: 'cli',
+    });
+
+    console.log('\n' + reply);
+  });
+
+// ─── kernel check ────────────────────────────────────────────
+program
+  .command('check')
+  .description('Validate configuration and test API connections')
+  .action(async () => {
+    showLogo();
+
+    const config = loadConfig();
+    createLogger(config);
+
+    await showStartupCheck('Configuration file', async () => {
+      // loadConfig already succeeded if we got here
+    });
+
+    await showStartupCheck('ANTHROPIC_API_KEY', async () => {
+      if (!config.anthropic.api_key) throw new Error('Not set');
+    });
+
+    await showStartupCheck('TELEGRAM_BOT_TOKEN', async () => {
+      if (!config.telegram.bot_token) throw new Error('Not set');
+    });
+
+    await showStartupCheck('Anthropic API connection', async () => {
+      const client = new Anthropic({ apiKey: config.anthropic.api_key });
+      await client.messages.create({
+        model: config.anthropic.model,
+        max_tokens: 16,
+        messages: [{ role: 'user', content: 'ping' }],
+      });
+    });
+
+    await showStartupCheck('Telegram Bot API', async () => {
+      const res = await fetch(
+        `https://api.telegram.org/bot${config.telegram.bot_token}/getMe`,
+      );
+      const data = await res.json();
+      if (!data.ok) throw new Error(data.description || 'Invalid token');
+    });
+
+    console.log('\nAll checks complete.');
+  });
+
+// ─── kernel init ─────────────────────────────────────────────
+program
+  .command('init')
+  .description('Interactive setup: create .env and config.yaml')
+  .action(async () => {
+    showLogo();
+
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    const ask = (q) => new Promise((res) => rl.question(q, res));
+
+    const apiKey = await ask('Anthropic API key: ');
+    const botToken = await ask('Telegram Bot Token: ');
+    const userId = await ask('Your Telegram User ID (leave blank for dev mode): ');
+
+    rl.close();
+
+    // Write .env
+    const envContent = `ANTHROPIC_API_KEY=${apiKey}\nTELEGRAM_BOT_TOKEN=${botToken}\n`;
+    writeFileSync('.env', envContent);
+
+    // Write config.yaml
+    const allowedUsers =
+      userId.trim() ? `\n  allowed_users:\n    - ${userId.trim()}` : '\n  allowed_users: []';
+
+    const configContent = `bot:
+  name: KernelBot
+
+anthropic:
+  model: claude-sonnet-4-20250514
+  max_tokens: 8192
+  temperature: 0.3
+  max_tool_depth: 25
+
+telegram:${allowedUsers}
+
+security:
+  blocked_paths:
+    - /etc/shadow
+    - /etc/passwd
+
+logging:
+  level: info
+  max_file_size: 5242880
+
+conversation:
+  max_history: 50
+`;
+    writeFileSync('config.yaml', configContent);
+
+    console.log('\nCreated .env and config.yaml');
+    console.log('Run `kernelbot check` to verify, then `kernelbot start` to launch.');
+  });
+
+program.parse();

package/config.example.yaml

@@ -0,0 +1,30 @@
+# KernelBot Configuration
+# Copy to config.yaml and adjust as needed.
+
+bot:
+  name: KernelBot
+  description: AI engineering agent with full OS control
+
+anthropic:
+  model: claude-sonnet-4-20250514
+  max_tokens: 8192
+  temperature: 0.3
+  max_tool_depth: 25
+
+telegram:
+  # List Telegram user IDs allowed to interact. Empty = allow all (dev mode).
+  allowed_users: []
+
+security:
+  blocked_paths:
+    - /etc/shadow
+    - /etc/passwd
+    - ~/.ssh/id_rsa
+    - ~/.ssh/id_ed25519
+
+logging:
+  level: info
+  max_file_size: 5242880  # 5 MB
+
+conversation:
+  max_history: 50

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "kernelbot",
+  "version": "1.0.0",
+  "description": "KernelBot — AI engineering agent with full OS control",
+  "type": "module",
+  "author": "Abdullah Al-Tahrei <abdullah@altaheri.me>",
+  "bin": {
+    "kernelbot": "./bin/kernel.js"
+  },
+  "scripts": {
+    "start": "node bin/kernel.js start"
+  },
+  "keywords": [
+    "ai",
+    "agent",
+    "telegram",
+    "anthropic",
+    "tools"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.39.0",
+    "chalk": "^5.4.1",
+    "commander": "^13.1.0",
+    "dotenv": "^16.4.7",
+    "js-yaml": "^4.1.0",
+    "node-telegram-bot-api": "^0.66.0",
+    "ora": "^8.1.1",
+    "boxen": "^8.0.1",
+    "uuid": "^11.1.0",
+    "winston": "^3.17.0"
+  }
+}

package/src/agent.js

@@ -0,0 +1,94 @@
+import Anthropic from '@anthropic-ai/sdk';
+import { toolDefinitions, executeTool } from './tools/index.js';
+import { getSystemPrompt } from './prompts/system.js';
+import { getLogger } from './utils/logger.js';
+
+export class Agent {
+  constructor({ config, conversationManager }) {
+    this.config = config;
+    this.conversationManager = conversationManager;
+    this.client = new Anthropic({ apiKey: config.anthropic.api_key });
+    this.systemPrompt = getSystemPrompt(config);
+  }
+
+  async processMessage(chatId, userMessage, user) {
+    const logger = getLogger();
+    const { model, max_tokens, temperature, max_tool_depth } = this.config.anthropic;
+
+    // Add user message to persistent history
+    this.conversationManager.addMessage(chatId, 'user', userMessage);
+
+    // Build working messages from history
+    const messages = [...this.conversationManager.getHistory(chatId)];
+
+    for (let depth = 0; depth < max_tool_depth; depth++) {
+      logger.debug(`Agent loop iteration ${depth + 1}/${max_tool_depth}`);
+
+      const response = await this.client.messages.create({
+        model,
+        max_tokens,
+        temperature,
+        system: this.systemPrompt,
+        tools: toolDefinitions,
+        messages,
+      });
+
+      if (response.stop_reason === 'end_turn') {
+        const textBlocks = response.content
+          .filter((b) => b.type === 'text')
+          .map((b) => b.text);
+        const reply = textBlocks.join('\n');
+
+        // Save assistant reply to persistent history
+        this.conversationManager.addMessage(chatId, 'assistant', reply);
+        return reply;
+      }
+
+      if (response.stop_reason === 'tool_use') {
+        // Push assistant response as-is (contains tool_use blocks)
+        messages.push({ role: 'assistant', content: response.content });
+
+        // Execute each tool_use block
+        const toolResults = [];
+        for (const block of response.content) {
+          if (block.type !== 'tool_use') continue;
+
+          logger.info(`Tool call: ${block.name}`);
+
+          const result = await executeTool(block.name, block.input, {
+            config: this.config,
+            user,
+          });
+
+          toolResults.push({
+            type: 'tool_result',
+            tool_use_id: block.id,
+            content: JSON.stringify(result),
+          });
+        }
+
+        // Push all tool results as a single user message
+        messages.push({ role: 'user', content: toolResults });
+        continue;
+      }
+
+      // Unexpected stop reason
+      logger.warn(`Unexpected stop_reason: ${response.stop_reason}`);
+      const fallbackText = response.content
+        .filter((b) => b.type === 'text')
+        .map((b) => b.text)
+        .join('\n');
+      if (fallbackText) {
+        this.conversationManager.addMessage(chatId, 'assistant', fallbackText);
+        return fallbackText;
+      }
+      return 'Something went wrong — unexpected response from the model.';
+    }
+
+    const depthWarning =
+      `Reached maximum tool depth (${max_tool_depth}). Stopping to prevent infinite loops. ` +
+      `Please try again with a simpler request.`;
+    this.conversationManager.addMessage(chatId, 'assistant', depthWarning);
+    return depthWarning;
+  }
+}

package/src/bot.js

@@ -0,0 +1,81 @@
+import TelegramBot from 'node-telegram-bot-api';
+import { isAllowedUser, getUnauthorizedMessage } from './security/auth.js';
+import { getLogger } from './utils/logger.js';
+
+function splitMessage(text, maxLength = 4096) {
+  if (text.length <= maxLength) return [text];
+
+  const chunks = [];
+  let remaining = text;
+  while (remaining.length > 0) {
+    if (remaining.length <= maxLength) {
+      chunks.push(remaining);
+      break;
+    }
+    // Try to split at a newline near the limit
+    let splitAt = remaining.lastIndexOf('\n', maxLength);
+    if (splitAt < maxLength / 2) splitAt = maxLength;
+    chunks.push(remaining.slice(0, splitAt));
+    remaining = remaining.slice(splitAt);
+  }
+  return chunks;
+}
+
+export function startBot(config, agent) {
+  const logger = getLogger();
+  const bot = new TelegramBot(config.telegram.bot_token, { polling: true });
+
+  logger.info('Telegram bot started with polling');
+
+  bot.on('message', async (msg) => {
+    if (!msg.text) return; // ignore non-text
+
+    const chatId = msg.chat.id;
+    const userId = msg.from.id;
+    const username = msg.from.username || msg.from.first_name || 'unknown';
+
+    // Auth check
+    if (!isAllowedUser(userId, config)) {
+      logger.warn(`Unauthorized access attempt from ${username} (${userId})`);
+      await bot.sendMessage(chatId, getUnauthorizedMessage());
+      return;
+    }
+
+    logger.info(`Message from ${username} (${userId}): ${msg.text.slice(0, 100)}`);
+
+    // Show typing and keep refreshing it
+    const typingInterval = setInterval(() => {
+      bot.sendChatAction(chatId, 'typing').catch(() => {});
+    }, 4000);
+    bot.sendChatAction(chatId, 'typing').catch(() => {});
+
+    try {
+      const reply = await agent.processMessage(chatId, msg.text, {
+        id: userId,
+        username,
+      });
+
+      clearInterval(typingInterval);
+
+      const chunks = splitMessage(reply || 'Done.');
+      for (const chunk of chunks) {
+        try {
+          await bot.sendMessage(chatId, chunk, { parse_mode: 'Markdown' });
+        } catch {
+          // Fallback to plain text if Markdown fails
+          await bot.sendMessage(chatId, chunk);
+        }
+      }
+    } catch (err) {
+      clearInterval(typingInterval);
+      logger.error(`Error processing message: ${err.message}`);
+      await bot.sendMessage(chatId, `Error: ${err.message}`);
+    }
+  });
+
+  bot.on('polling_error', (err) => {
+    logger.error(`Telegram polling error: ${err.message}`);
+  });
+
+  return bot;
+}

package/src/conversation.js

@@ -0,0 +1,36 @@
+export class ConversationManager {
+  constructor(config) {
+    this.maxHistory = config.conversation.max_history;
+    this.conversations = new Map();
+  }
+
+  getHistory(chatId) {
+    if (!this.conversations.has(chatId)) {
+      this.conversations.set(chatId, []);
+    }
+    return this.conversations.get(chatId);
+  }
+
+  addMessage(chatId, role, content) {
+    const history = this.getHistory(chatId);
+    history.push({ role, content });
+
+    // Trim to max history
+    while (history.length > this.maxHistory) {
+      history.shift();
+    }
+
+    // Ensure conversation starts with user role
+    while (history.length > 0 && history[0].role !== 'user') {
+      history.shift();
+    }
+  }
+
+  clear(chatId) {
+    this.conversations.delete(chatId);
+  }
+
+  clearAll() {
+    this.conversations.clear();
+  }
+}

package/src/prompts/system.js

@@ -0,0 +1,19 @@
+import { toolDefinitions } from '../tools/index.js';
+
+export function getSystemPrompt(config) {
+  const toolList = toolDefinitions.map((t) => `- ${t.name}: ${t.description}`).join('\n');
+
+  return `You are ${config.bot.name}, an AI engineering agent with full OS control.
+
+You have access to the following tools to interact with the operating system:
+${toolList}
+
+Guidelines:
+- Use tools proactively to complete tasks. Don't just describe what you would do — do it.
+- When a task requires multiple steps, execute them in sequence using tools.
+- If a command fails, analyze the error and try an alternative approach.
+- Be concise in your responses. Show what you did and the result.
+- When writing code, write complete, working files — not snippets.
+- For destructive operations (deleting files, overwriting data), confirm with the user first unless they've explicitly asked for it.
+- If you're unsure about something, read the relevant files first before making changes.`;
+}

package/src/security/audit.js

@@ -0,0 +1,58 @@
+import winston from 'winston';
+
+const SECRET_PATTERNS = /token|key|secret|password|api_key/i;
+
+function redactSecrets(obj) {
+  if (obj === null || obj === undefined) return obj;
+  if (typeof obj === 'string') return obj;
+  if (typeof obj !== 'object') return obj;
+
+  const redacted = Array.isArray(obj) ? [...obj] : { ...obj };
+  for (const k of Object.keys(redacted)) {
+    if (SECRET_PATTERNS.test(k)) {
+      redacted[k] = '[REDACTED]';
+    } else if (typeof redacted[k] === 'object') {
+      redacted[k] = redactSecrets(redacted[k]);
+    }
+  }
+  return redacted;
+}
+
+function truncate(str, max = 500) {
+  if (typeof str !== 'string') str = JSON.stringify(str);
+  if (!str) return '';
+  return str.length > max ? str.slice(0, max) + '...[truncated]' : str;
+}
+
+let auditLogger = null;
+
+export function createAuditLogger() {
+  auditLogger = winston.createLogger({
+    level: 'info',
+    format: winston.format.combine(
+      winston.format.timestamp(),
+      winston.format.json(),
+    ),
+    transports: [
+      new winston.transports.File({
+        filename: 'kernel-audit.log',
+        maxsize: 5_242_880,
+        maxFiles: 3,
+      }),
+    ],
+  });
+  return auditLogger;
+}
+
+export function logToolCall({ user, tool, params, output, success, duration }) {
+  if (!auditLogger) return;
+
+  auditLogger.info('tool_call', {
+    user,
+    tool,
+    params: redactSecrets(params),
+    output: truncate(output),
+    success,
+    duration_ms: duration,
+  });
+}

package/src/security/auth.js

@@ -0,0 +1,9 @@
+export function isAllowedUser(userId, config) {
+  const allowed = config.telegram.allowed_users;
+  if (!allowed || allowed.length === 0) return true; // dev mode
+  return allowed.includes(userId);
+}
+
+export function getUnauthorizedMessage() {
+  return 'Access denied. You are not authorized to use this bot.';
+}

package/src/tools/index.js

@@ -0,0 +1,38 @@
+import { definitions as osDefinitions, handlers as osHandlers } from './os.js';
+import { logToolCall } from '../security/audit.js';
+
+export const toolDefinitions = [...osDefinitions];
+
+const handlerMap = { ...osHandlers };
+
+export async function executeTool(name, params, context) {
+  const handler = handlerMap[name];
+  if (!handler) {
+    return { error: `Unknown tool: ${name}` };
+  }
+
+  const start = Date.now();
+  let output;
+  let success = true;
+
+  try {
+    output = await handler(params, context);
+    if (output?.error) success = false;
+  } catch (err) {
+    output = { error: err.message };
+    success = false;
+  }
+
+  const duration = Date.now() - start;
+
+  logToolCall({
+    user: context.user,
+    tool: name,
+    params,
+    output,
+    success,
+    duration,
+  });
+
+  return output;
+}

package/src/tools/os.js

@@ -0,0 +1,201 @@
+import { exec } from 'child_process';
+import { readFileSync, writeFileSync, mkdirSync, readdirSync, statSync } from 'fs';
+import { dirname, resolve, join } from 'path';
+import { homedir } from 'os';
+
+function expandPath(p) {
+  if (p.startsWith('~')) return join(homedir(), p.slice(1));
+  return resolve(p);
+}
+
+function isBlocked(filePath, config) {
+  const expanded = expandPath(filePath);
+  const blockedPaths = config.security?.blocked_paths || [];
+  return blockedPaths.some((bp) => expanded.startsWith(expandPath(bp)));
+}
+
+export const definitions = [
+  {
+    name: 'execute_command',
+    description:
+      'Execute a shell command and return its stdout and stderr. Use for running programs, scripts, git commands, package managers, etc.',
+    input_schema: {
+      type: 'object',
+      properties: {
+        command: {
+          type: 'string',
+          description: 'The shell command to execute',
+        },
+        timeout_seconds: {
+          type: 'number',
+          description: 'Max execution time in seconds (default 30)',
+          default: 30,
+        },
+      },
+      required: ['command'],
+    },
+  },
+  {
+    name: 'read_file',
+    description: 'Read the contents of a file. Returns the text content and total line count.',
+    input_schema: {
+      type: 'object',
+      properties: {
+        path: {
+          type: 'string',
+          description: 'Absolute or relative file path',
+        },
+        max_lines: {
+          type: 'number',
+          description: 'Maximum number of lines to return (default: all)',
+        },
+      },
+      required: ['path'],
+    },
+  },
+  {
+    name: 'write_file',
+    description:
+      'Write content to a file. Creates parent directories if they do not exist. Overwrites existing content.',
+    input_schema: {
+      type: 'object',
+      properties: {
+        path: {
+          type: 'string',
+          description: 'Absolute or relative file path',
+        },
+        content: {
+          type: 'string',
+          description: 'The content to write',
+        },
+      },
+      required: ['path', 'content'],
+    },
+  },
+  {
+    name: 'list_directory',
+    description:
+      'List files and subdirectories in a directory. Returns entries with name and type.',
+    input_schema: {
+      type: 'object',
+      properties: {
+        path: {
+          type: 'string',
+          description: 'Directory path',
+        },
+        recursive: {
+          type: 'boolean',
+          description: 'Whether to list recursively (default false)',
+          default: false,
+        },
+      },
+      required: ['path'],
+    },
+  },
+];
+
+function listRecursive(dirPath, base = '') {
+  const entries = [];
+  for (const entry of readdirSync(dirPath, { withFileTypes: true })) {
+    const rel = base ? `${base}/${entry.name}` : entry.name;
+    const type = entry.isDirectory() ? 'directory' : 'file';
+    entries.push({ name: rel, type });
+    if (entry.isDirectory()) {
+      entries.push(...listRecursive(join(dirPath, entry.name), rel));
+    }
+  }
+  return entries;
+}
+
+export const handlers = {
+  execute_command: async (params, context) => {
+    const { command, timeout_seconds = 30 } = params;
+    const { config } = context;
+    const blockedPaths = config.security?.blocked_paths || [];
+
+    // Simple check: if the command references a blocked path, reject
+    for (const bp of blockedPaths) {
+      const expanded = expandPath(bp);
+      if (command.includes(expanded)) {
+        return { error: `Blocked: command references restricted path ${bp}` };
+      }
+    }
+
+    return new Promise((res) => {
+      const child = exec(
+        command,
+        { timeout: timeout_seconds * 1000, maxBuffer: 10 * 1024 * 1024 },
+        (error, stdout, stderr) => {
+          if (error && error.killed) {
+            return res({ error: `Command timed out after ${timeout_seconds}s` });
+          }
+          res({
+            stdout: stdout || '',
+            stderr: stderr || '',
+            exit_code: error ? error.code ?? 1 : 0,
+          });
+        },
+      );
+    });
+  },
+
+  read_file: async (params, context) => {
+    const { path: filePath, max_lines } = params;
+    if (isBlocked(filePath, context.config)) {
+      return { error: `Blocked: access to ${filePath} is restricted` };
+    }
+
+    try {
+      const content = readFileSync(expandPath(filePath), 'utf-8');
+      const lines = content.split('\n');
+      const total_lines = lines.length;
+
+      if (max_lines && max_lines < total_lines) {
+        return { content: lines.slice(0, max_lines).join('\n'), total_lines };
+      }
+      return { content, total_lines };
+    } catch (err) {
+      return { error: err.message };
+    }
+  },
+
+  write_file: async (params, context) => {
+    const { path: filePath, content } = params;
+    if (isBlocked(filePath, context.config)) {
+      return { error: `Blocked: access to ${filePath} is restricted` };
+    }
+
+    try {
+      const expanded = expandPath(filePath);
+      mkdirSync(dirname(expanded), { recursive: true });
+      writeFileSync(expanded, content, 'utf-8');
+      return { success: true, path: expanded };
+    } catch (err) {
+      return { error: err.message };
+    }
+  },
+
+  list_directory: async (params, context) => {
+    const { path: dirPath, recursive = false } = params;
+    if (isBlocked(dirPath, context.config)) {
+      return { error: `Blocked: access to ${dirPath} is restricted` };
+    }
+
+    try {
+      const expanded = expandPath(dirPath);
+      if (recursive) {
+        return { entries: listRecursive(expanded) };
+      }
+
+      const entries = readdirSync(expanded, { withFileTypes: true }).map(
+        (entry) => ({
+          name: entry.name,
+          type: entry.isDirectory() ? 'directory' : 'file',
+        }),
+      );
+      return { entries };
+    } catch (err) {
+      return { error: err.message };
+    }
+  },
+};

package/src/utils/config.js

@@ -0,0 +1,88 @@
+import { readFileSync, existsSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+import yaml from 'js-yaml';
+import dotenv from 'dotenv';
+
+const DEFAULTS = {
+  bot: {
+    name: 'KernelBot',
+    description: 'AI engineering agent with full OS control',
+  },
+  anthropic: {
+    model: 'claude-sonnet-4-20250514',
+    max_tokens: 8192,
+    temperature: 0.3,
+    max_tool_depth: 25,
+  },
+  telegram: {
+    allowed_users: [],
+  },
+  security: {
+    blocked_paths: [
+      '/etc/shadow',
+      '/etc/passwd',
+      '~/.ssh/id_rsa',
+      '~/.ssh/id_ed25519',
+    ],
+  },
+  logging: {
+    level: 'info',
+    max_file_size: 5_242_880,
+  },
+  conversation: {
+    max_history: 50,
+  },
+};
+
+function deepMerge(target, source) {
+  const result = { ...target };
+  for (const key of Object.keys(source)) {
+    if (
+      source[key] &&
+      typeof source[key] === 'object' &&
+      !Array.isArray(source[key]) &&
+      target[key] &&
+      typeof target[key] === 'object' &&
+      !Array.isArray(target[key])
+    ) {
+      result[key] = deepMerge(target[key], source[key]);
+    } else {
+      result[key] = source[key];
+    }
+  }
+  return result;
+}
+
+function findConfigFile() {
+  const cwdPath = join(process.cwd(), 'config.yaml');
+  if (existsSync(cwdPath)) return cwdPath;
+
+  const homePath = join(homedir(), '.kernelbot', 'config.yaml');
+  if (existsSync(homePath)) return homePath;
+
+  return null;
+}
+
+export function loadConfig() {
+  dotenv.config();
+
+  let fileConfig = {};
+  const configPath = findConfigFile();
+  if (configPath) {
+    const raw = readFileSync(configPath, 'utf-8');
+    fileConfig = yaml.load(raw) || {};
+  }
+
+  const config = deepMerge(DEFAULTS, fileConfig);
+
+  // Overlay env vars for secrets
+  if (process.env.ANTHROPIC_API_KEY) {
+    config.anthropic.api_key = process.env.ANTHROPIC_API_KEY;
+  }
+  if (process.env.TELEGRAM_BOT_TOKEN) {
+    config.telegram.bot_token = process.env.TELEGRAM_BOT_TOKEN;
+  }
+
+  return Object.freeze(config);
+}

package/src/utils/display.js

@@ -0,0 +1,64 @@
+import chalk from 'chalk';
+import ora from 'ora';
+import boxen from 'boxen';
+
+const LOGO = `
+ ██╗  ██╗███████╗██████╗ ███╗   ██╗███████╗██╗     ██████╗  ██████╗ ████████╗
+ ██║ ██╔╝██╔════╝██╔══██╗████╗  ██║██╔════╝██║     ██╔══██╗██╔═══██╗╚══██╔══╝
+ █████╔╝ █████╗  ██████╔╝██╔██╗ ██║█████╗  ██║     ██████╔╝██║   ██║   ██║
+ ██╔═██╗ ██╔══╝  ██╔══██╗██║╚██╗██║██╔══╝  ██║     ██╔══██╗██║   ██║   ██║
+ ██║  ██╗███████╗██║  ██║██║ ╚████║███████╗███████╗██████╔╝╚██████╔╝   ██║
+ ╚═╝  ╚═╝╚══════╝╚═╝  ╚═╝╚═╝  ╚═══╝╚══════╝╚══════╝╚═════╝  ╚═════╝    ╚═╝
+`;
+
+export function showLogo() {
+  console.log(chalk.cyan(LOGO));
+  console.log(chalk.dim('  AI Engineering Agent\n'));
+}
+
+export async function showStartupCheck(label, checkFn) {
+  const spinner = ora({ text: label, color: 'cyan' }).start();
+  try {
+    await checkFn();
+    spinner.succeed(chalk.green(label));
+    return true;
+  } catch (err) {
+    spinner.fail(chalk.red(`${label} — ${err.message}`));
+    return false;
+  }
+}
+
+export function showStartupComplete() {
+  console.log(
+    boxen(chalk.green.bold('KernelBot is live'), {
+      padding: 1,
+      margin: { top: 1 },
+      borderStyle: 'round',
+      borderColor: 'green',
+    }),
+  );
+}
+
+export function showSuccess(msg) {
+  console.log(
+    boxen(chalk.green(msg), {
+      padding: 1,
+      borderStyle: 'round',
+      borderColor: 'green',
+    }),
+  );
+}
+
+export function showError(msg) {
+  console.log(
+    boxen(chalk.red(msg), {
+      padding: 1,
+      borderStyle: 'round',
+      borderColor: 'red',
+    }),
+  );
+}
+
+export function createSpinner(text) {
+  return ora({ text, color: 'cyan' });
+}

package/src/utils/logger.js

@@ -0,0 +1,40 @@
+import winston from 'winston';
+
+let logger = null;
+
+export function createLogger(config) {
+  const { level, max_file_size } = config.logging;
+
+  logger = winston.createLogger({
+    level,
+    format: winston.format.combine(
+      winston.format.timestamp(),
+      winston.format.errors({ stack: true }),
+    ),
+    transports: [
+      new winston.transports.Console({
+        format: winston.format.combine(
+          winston.format.colorize(),
+          winston.format.printf(({ level, message, timestamp }) => {
+            return `[KernelBot] ${level}: ${message}`;
+          }),
+        ),
+      }),
+      new winston.transports.File({
+        filename: 'kernel.log',
+        maxsize: max_file_size,
+        maxFiles: 3,
+        format: winston.format.json(),
+      }),
+    ],
+  });
+
+  return logger;
+}
+
+export function getLogger() {
+  if (!logger) {
+    throw new Error('Logger not initialized. Call createLogger(config) first.');
+  }
+  return logger;
+}