companionbot 0.1.1 → 0.2.1

package/dist/agents/index.js

@@ -0,0 +1,4 @@
+/**
+ * Sub-agent 시스템 - 복잡한 작업을 독립적인 agent에게 위임
+ */
+export { setAgentBot, spawnAgent, listAgents, cancelAgent, getAgent } from "./manager.js";

package/dist/agents/manager.js

@@ -0,0 +1,171 @@
+/**
+ * AgentManager - Sub-agent 생성 및 관리
+ *
+ * 각 sub-agent는:
+ * - 별도의 Claude API 호출로 독립 실행
+ * - 메인 conversation과 별개의 context
+ * - 비동기로 실행, 완료 시 callback
+ */
+import Anthropic from "@anthropic-ai/sdk";
+import { randomUUID } from "crypto";
+// Agent 저장소
+const agents = new Map();
+// Bot 인스턴스 (결과 전송용)
+let botInstance = null;
+// Anthropic 클라이언트
+let anthropic = null;
+function getClient() {
+    if (!anthropic) {
+        anthropic = new Anthropic();
+    }
+    return anthropic;
+}
+/**
+ * Bot 인스턴스 설정 (시작 시 호출)
+ */
+export function setAgentBot(bot) {
+    botInstance = bot;
+}
+/**
+ * Sub-agent 생성 및 실행
+ */
+export async function spawnAgent(task, chatId) {
+    const id = randomUUID().slice(0, 8);
+    const agent = {
+        id,
+        task,
+        status: "running",
+        chatId,
+        createdAt: new Date(),
+    };
+    agents.set(id, agent);
+    // 비동기로 agent 실행 (await 하지 않음)
+    runAgent(agent).catch((err) => {
+        console.error(`[Agent ${id}] Error:`, err);
+    });
+    return id;
+}
+/**
+ * Agent 실행 (내부 함수)
+ */
+async function runAgent(agent) {
+    const client = getClient();
+    const systemPrompt = `You are a sub-agent assistant. Your job is to complete a specific task and report the result concisely.
+
+TASK: ${agent.task}
+
+Guidelines:
+- Focus only on the given task
+- Be concise but thorough
+- Report results clearly
+- If you cannot complete the task, explain why
+
+Complete the task and provide your final answer.`;
+    try {
+        console.log(`[Agent ${agent.id}] Starting: ${agent.task.slice(0, 50)}...`);
+        const response = await client.messages.create({
+            model: "claude-sonnet-4-20250514",
+            max_tokens: 2048,
+            system: systemPrompt,
+            messages: [
+                {
+                    role: "user",
+                    content: `Please complete this task: ${agent.task}`,
+                },
+            ],
+        });
+        // 결과 추출
+        const textBlock = response.content.find((block) => block.type === "text");
+        const result = textBlock?.text ?? "No response generated.";
+        // Agent 상태 업데이트
+        agent.status = "completed";
+        agent.completedAt = new Date();
+        agent.result = result;
+        console.log(`[Agent ${agent.id}] Completed`);
+        // 결과를 원래 chat에 전송
+        await sendAgentResult(agent);
+    }
+    catch (error) {
+        agent.status = "failed";
+        agent.completedAt = new Date();
+        agent.error = error instanceof Error ? error.message : String(error);
+        console.error(`[Agent ${agent.id}] Failed:`, agent.error);
+        // 실패도 알림
+        await sendAgentResult(agent);
+    }
+}
+/**
+ * Agent 결과를 chat에 전송
+ */
+async function sendAgentResult(agent) {
+    if (!botInstance) {
+        console.warn("[Agent] No bot instance, cannot send result");
+        return;
+    }
+    let message;
+    if (agent.status === "completed") {
+        message = `🤖 **Sub-agent 완료** (${agent.id})\n\n📋 Task: ${agent.task.slice(0, 100)}${agent.task.length > 100 ? "..." : ""}\n\n✅ Result:\n${agent.result}`;
+    }
+    else if (agent.status === "failed") {
+        message = `🤖 **Sub-agent 실패** (${agent.id})\n\n📋 Task: ${agent.task.slice(0, 100)}${agent.task.length > 100 ? "..." : ""}\n\n❌ Error: ${agent.error}`;
+    }
+    else if (agent.status === "cancelled") {
+        message = `🤖 **Sub-agent 취소됨** (${agent.id})`;
+    }
+    else {
+        return; // running 상태면 전송 안 함
+    }
+    try {
+        await botInstance.api.sendMessage(agent.chatId, message);
+    }
+    catch (err) {
+        console.error(`[Agent ${agent.id}] Failed to send result:`, err);
+    }
+}
+/**
+ * Agent 목록 조회
+ */
+export function listAgents(chatId) {
+    const allAgents = Array.from(agents.values());
+    if (chatId !== undefined) {
+        return allAgents.filter((a) => a.chatId === chatId);
+    }
+    return allAgents;
+}
+/**
+ * Agent 취소
+ */
+export function cancelAgent(agentId) {
+    const agent = agents.get(agentId);
+    if (!agent) {
+        return false;
+    }
+    if (agent.status !== "running") {
+        return false; // 이미 완료된 agent는 취소 불가
+    }
+    // 실제로 실행 중인 API 호출을 취소할 수는 없지만
+    // 상태를 cancelled로 표시하고 결과 전송 시 무시되도록 함
+    agent.status = "cancelled";
+    agent.completedAt = new Date();
+    console.log(`[Agent ${agentId}] Cancelled`);
+    return true;
+}
+/**
+ * Agent 상태 조회
+ */
+export function getAgent(agentId) {
+    return agents.get(agentId);
+}
+/**
+ * 오래된 agent 정리 (1시간 이상)
+ */
+export function cleanupOldAgents() {
+    const oneHourAgo = Date.now() - 60 * 60 * 1000;
+    for (const [id, agent] of agents.entries()) {
+        if (agent.completedAt && agent.completedAt.getTime() < oneHourAgo) {
+            agents.delete(id);
+        }
+    }
+}
+// 10분마다 정리
+setInterval(cleanupOldAgents, 10 * 60 * 1000);

package/dist/agents/types.js

@@ -0,0 +1,4 @@
+/**
+ * Sub-agent 시스템 타입 정의
+ */
+export {};

package/dist/cli/setup.js

@@ -4,9 +4,11 @@ async function showStatus() {
     console.log("\n=== CompanionBot 설정 상태 ===\n");
     const telegram = await getSecret("telegram-token");
     const anthropic = await getSecret("anthropic-api-key");
+    const brave = await getSecret("brave-api-key");
     const workspaceReady = await isWorkspaceInitialized();
     console.log(`Telegram Bot Token: ${telegram ? "✓ 설정됨" : "✗ 미설정"}`);
     console.log(`Anthropic API Key:  ${anthropic ? "✓ 설정됨" : "✗ 미설정"}`);
+    console.log(`Brave API Key:      ${brave ? "✓ 설정됨" : "✗ 미설정 (선택)"}`);
     console.log(`워크스페이스:       ${workspaceReady ? "✓ 초기화됨" : "✗ 미초기화"}`);
     if (workspaceReady) {
         console.log(`  경로: ${getWorkspacePath()}`);
@@ -29,6 +31,14 @@ async function setupAnthropic(key) {
     await setSecret("anthropic-api-key", key.trim());
     console.log("✓ Anthropic API Key가 OS 키체인에 저장되었습니다.");
 }
+async function setupBrave(key) {
+    if (!key.trim()) {
+        console.log("Error: API 키를 입력해주세요.");
+        return;
+    }
+    await setSecret("brave-api-key", key.trim());
+    console.log("✓ Brave API Key가 OS 키체인에 저장되었습니다.");
+}
 async function main() {
     const args = process.argv.slice(2);
     const command = args[0];
@@ -51,6 +61,13 @@ async function main() {
             }
             await setupAnthropic(value);
             break;
+        case "brave":
+            if (!value) {
+                console.log("사용법: npm run setup brave <API_KEY>");
+                return;
+            }
+            await setupBrave(value);
+            break;
         case "delete":
             if (value === "telegram") {
                 await deleteSecret("telegram-token");
@@ -60,8 +77,12 @@ async function main() {
                 await deleteSecret("anthropic-api-key");
                 console.log("✓ Anthropic API Key 삭제됨");
             }
+            else if (value === "brave") {
+                await deleteSecret("brave-api-key");
+                console.log("✓ Brave API Key 삭제됨");
+            }
             else {
-                console.log("사용법: npm run setup delete <telegram|anthropic>");
+                console.log("사용법: npm run setup delete <telegram|anthropic|brave>");
             }
             break;
         case "init":
@@ -91,12 +112,13 @@ async function main() {
 CompanionBot 설정
 
 사용법:
-  npm run setup status                      현재 설정 상태 확인
-  npm run setup telegram <TOKEN>            Telegram Bot Token 설정
-  npm run setup anthropic <API_KEY>         Anthropic API Key 설정
-  npm run setup delete <telegram|anthropic> 키 삭제
-  npm run setup init                        워크스페이스 초기화
-  npm run setup reset workspace             워크스페이스 리셋
+  npm run setup status                              현재 설정 상태 확인
+  npm run setup telegram <TOKEN>                    Telegram Bot Token 설정
+  npm run setup anthropic <API_KEY>                 Anthropic API Key 설정
+  npm run setup brave <API_KEY>                     Brave API Key 설정 (선택, 웹 검색용)
+  npm run setup delete <telegram|anthropic|brave>   키 삭제
+  npm run setup init                                워크스페이스 초기화
+  npm run setup reset workspace                     워크스페이스 리셋
       `);
     }
 }

package/dist/telegram/bot.js

@@ -2,6 +2,7 @@ import { Bot } from "grammy";
 import { setBotInstance, restoreReminders } from "../reminders/index.js";
 import { setBriefingBot, restoreBriefings } from "../briefing/index.js";
 import { setHeartbeatBot, restoreHeartbeats } from "../heartbeat/index.js";
+import { setAgentBot } from "../agents/index.js";
 import { registerCommands, registerMessageHandlers } from "./handlers/index.js";
 // Re-export for external use
 export { invalidateWorkspaceCache } from "./utils/index.js";
@@ -19,6 +20,8 @@ export function createBot(token) {
     // Heartbeat 초기화
     setHeartbeatBot(bot);
     restoreHeartbeats().catch((err) => console.error("Failed to restore heartbeats:", err));
+    // Sub-agent 시스템 초기화
+    setAgentBot(bot);
     // 에러 핸들링
     bot.catch((err) => {
         console.error("Bot error:", err);

package/dist/tools/index.js

@@ -1,8 +1,9 @@
 import * as fs from "fs/promises";
 import * as fsSync from "fs";
 import * as path from "path";
-import { exec } from "child_process";
+import { exec, spawn } from "child_process";
 import { promisify } from "util";
+import { randomUUID } from "crypto";
 import { MODELS } from "../ai/claude.js";
 import { getCurrentChatId, setModel, getModel } from "../session/state.js";
 import { getWorkspacePath, saveWorkspaceFile, appendToMemory, deleteBootstrap, } from "../workspace/index.js";
@@ -11,7 +12,21 @@ import { createReminder, deleteReminder, getReminders, parseTimeExpression, } fr
 import { isCalendarConfigured, getEvents, addEvent, deleteEvent, formatEvent, parseDateExpression, } from "../calendar/index.js";
 import { setHeartbeatConfig, getHeartbeatConfig, disableHeartbeat, runHeartbeatNow, } from "../heartbeat/index.js";
 import { setBriefingConfig, getBriefingConfig, disableBriefing, sendBriefingNow, } from "../briefing/index.js";
+import { spawnAgent, listAgents, cancelAgent, } from "../agents/index.js";
+import * as cheerio from "cheerio";
 const execAsync = promisify(exec);
+// 메모리에 세션 저장
+const sessions = new Map();
+// Output buffer 최대 크기 (라인 수)
+const MAX_OUTPUT_LINES = 1000;
+function appendOutput(session, data) {
+    const lines = data.split("\n");
+    session.outputBuffer.push(...lines);
+    // 버퍼 크기 제한
+    if (session.outputBuffer.length > MAX_OUTPUT_LINES) {
+        session.outputBuffer = session.outputBuffer.slice(-MAX_OUTPUT_LINES);
+    }
+}
 // 홈 디렉토리
 const home = process.env.HOME || "";
 // 허용된 디렉토리 (보안을 위해 제한)
@@ -118,7 +133,13 @@ export const tools = [
     },
     {
         name: "run_command",
-        description: "Run a shell command. Use with caution. Only for safe commands like git status, npm run, etc.",
+        description: `Run a shell command. Use with caution. Only for safe commands like git status, npm run, etc.
+
+When background=true:
+- Command runs in detached mode
+- Returns a session ID immediately
+- Use list_sessions, get_session_log, kill_session to manage
+- Useful for long-running commands (npm run dev, servers, etc.)`,
         input_schema: {
             type: "object",
             properties: {
@@ -130,10 +151,70 @@ export const tools = [
                     type: "string",
                     description: "The working directory to run the command in (optional)",
                 },
+                background: {
+                    type: "boolean",
+                    description: "Run in background and return session ID (default: false)",
+                },
+                timeout: {
+                    type: "number",
+                    description: "Timeout in seconds for foreground commands (default: 30)",
+                },
             },
             required: ["command"],
         },
     },
+    {
+        name: "list_sessions",
+        description: "List all background command sessions. Shows running and recently completed sessions.",
+        input_schema: {
+            type: "object",
+            properties: {
+                status: {
+                    type: "string",
+                    enum: ["all", "running", "completed"],
+                    description: "Filter by status (default: all)",
+                },
+            },
+            required: [],
+        },
+    },
+    {
+        name: "get_session_log",
+        description: "Get the output log of a background session.",
+        input_schema: {
+            type: "object",
+            properties: {
+                session_id: {
+                    type: "string",
+                    description: "The session ID to get logs from",
+                },
+                tail: {
+                    type: "number",
+                    description: "Number of lines from the end (default: 50)",
+                },
+            },
+            required: ["session_id"],
+        },
+    },
+    {
+        name: "kill_session",
+        description: "Kill a running background session.",
+        input_schema: {
+            type: "object",
+            properties: {
+                session_id: {
+                    type: "string",
+                    description: "The session ID to kill",
+                },
+                signal: {
+                    type: "string",
+                    enum: ["SIGTERM", "SIGKILL", "SIGINT"],
+                    description: "Signal to send (default: SIGTERM)",
+                },
+            },
+            required: ["session_id"],
+        },
+    },
     {
         name: "change_model",
         description: `Change the AI model for this conversation. Use this when the user asks to switch models, or when you determine a different model would be better suited for the task.
@@ -399,6 +480,101 @@ Use this when the user says things like:
             required: [],
         },
     },
+    // ============== Sub-Agent 도구 ==============
+    {
+        name: "spawn_agent",
+        description: `Create a sub-agent to handle a complex or time-consuming task independently.
+
+The sub-agent will:
+- Run in the background with its own Claude API context
+- Complete the task independently
+- Report results back to this chat when done
+
+Use this for:
+- Tasks that require deep focus or analysis
+- Long-running research or summarization
+- Work that can be done in parallel while you handle other things
+
+Example: "서브에이전트한테 이 코드 분석 시켜줘"`,
+        input_schema: {
+            type: "object",
+            properties: {
+                task: {
+                    type: "string",
+                    description: "Detailed description of the task for the sub-agent",
+                },
+            },
+            required: ["task"],
+        },
+    },
+    {
+        name: "list_agents",
+        description: "List all sub-agents and their status (running, completed, failed, cancelled).",
+        input_schema: {
+            type: "object",
+            properties: {},
+            required: [],
+        },
+    },
+    {
+        name: "cancel_agent",
+        description: "Cancel a running sub-agent by its ID.",
+        input_schema: {
+            type: "object",
+            properties: {
+                agent_id: {
+                    type: "string",
+                    description: "The sub-agent ID to cancel",
+                },
+            },
+            required: ["agent_id"],
+        },
+    },
+    // ============== 웹 검색/가져오기 ==============
+    {
+        name: "web_search",
+        description: `Search the web using Brave Search API. Use when the user asks to search for information online.
+
+Examples:
+- "최신 뉴스 검색해줘" → query: "최신 뉴스"
+- "React 19 새로운 기능" → query: "React 19 new features"`,
+        input_schema: {
+            type: "object",
+            properties: {
+                query: {
+                    type: "string",
+                    description: "Search query",
+                },
+                count: {
+                    type: "number",
+                    description: "Number of results to return (default: 5, max: 20)",
+                },
+            },
+            required: ["query"],
+        },
+    },
+    {
+        name: "web_fetch",
+        description: `Fetch and extract readable content from a URL. Use when you need to read the content of a web page.
+
+Examples:
+- "이 링크 내용 요약해줘" → url: "https://..."
+- "이 기사 읽어줘" → url: "https://..."`,
+        input_schema: {
+            type: "object",
+            properties: {
+                url: {
+                    type: "string",
+                    description: "The URL to fetch",
+                },
+                maxChars: {
+                    type: "number",
+                    description: "Maximum characters to return (default: 5000)",
+                },
+            },
+            required: ["url"],
+        },
+    },
 ];
 // Tool 실행 함수
 export async function executeTool(name, input) {
@@ -434,6 +610,8 @@ export async function executeTool(name, input) {
             case "run_command": {
                 const command = input.command;
                 const cwd = input.cwd || path.join(home, "Documents");
+                const background = input.background || false;
+                const timeout = (input.timeout || 30) * 1000;
                 // 화이트리스트 방식: 허용된 명령어만 실행
                 const ALLOWED_COMMANDS = [
                     "git", "npm", "npx", "node", "ls", "pwd", "cat", "head", "tail",
@@ -455,18 +633,66 @@ export async function executeTool(name, input) {
                 if (dangerousArgs.some(arg => parts.includes(arg))) {
                     return `Error: Dangerous argument detected.`;
                 }
-                try {
-                    // 환경 변수는 필요한 것만 화이트리스트로 전달 (민감 정보 노출 방지)
-                    const safeEnv = {
-                        PATH: process.env.PATH || "",
-                        HOME: process.env.HOME || "",
-                        USER: process.env.USER || "",
-                        LANG: process.env.LANG || "en_US.UTF-8",
-                        TERM: process.env.TERM || "xterm",
+                // 환경 변수는 필요한 것만 화이트리스트로 전달 (민감 정보 노출 방지)
+                const safeEnv = {
+                    PATH: process.env.PATH || "",
+                    HOME: process.env.HOME || "",
+                    USER: process.env.USER || "",
+                    LANG: process.env.LANG || "en_US.UTF-8",
+                    TERM: process.env.TERM || "xterm",
+                };
+                // Background 실행
+                if (background) {
+                    const sessionId = randomUUID().slice(0, 8);
+                    const child = spawn("sh", ["-c", command], {
+                        cwd,
+                        env: safeEnv,
+                        detached: true,
+                        stdio: ["ignore", "pipe", "pipe"],
+                    });
+                    const session = {
+                        id: sessionId,
+                        pid: child.pid,
+                        command,
+                        cwd,
+                        startTime: new Date(),
+                        outputBuffer: [],
+                        process: child,
+                        status: "running",
                     };
+                    // stdout/stderr 캡처
+                    child.stdout?.on("data", (data) => {
+                        appendOutput(session, data.toString());
+                    });
+                    child.stderr?.on("data", (data) => {
+                        appendOutput(session, `[stderr] ${data.toString()}`);
+                    });
+                    // 프로세스 종료 핸들링
+                    child.on("close", (code) => {
+                        session.endTime = new Date();
+                        session.exitCode = code;
+                        session.status = code === 0 ? "completed" : "error";
+                    });
+                    child.on("error", (err) => {
+                        session.status = "error";
+                        appendOutput(session, `[error] ${err.message}`);
+                    });
+                    // unref로 부모 프로세스와 분리
+                    child.unref();
+                    sessions.set(sessionId, session);
+                    return `Background session started.
+Session ID: ${sessionId}
+PID: ${child.pid}
+Command: ${command}
+CWD: ${cwd}
+
+Use list_sessions to see all sessions, get_session_log to view output, kill_session to terminate.`;
+                }
+                // Foreground 실행 (기존 방식)
+                try {
                     const { stdout, stderr } = await execAsync(command, {
                         cwd,
-                        timeout: 30000,
+                        timeout,
                         env: safeEnv,
                     });
                     return stdout || stderr || "Command executed (no output)";
@@ -475,6 +701,87 @@ export async function executeTool(name, input) {
                     return `Error: ${error instanceof Error ? error.message : String(error)}`;
                 }
             }
+            case "list_sessions": {
+                const statusFilter = input.status || "all";
+                const sessionList = [];
+                for (const [id, session] of sessions) {
+                    // 상태 필터링
+                    if (statusFilter !== "all") {
+                        if (statusFilter === "running" && session.status !== "running")
+                            continue;
+                        if (statusFilter === "completed" && session.status === "running")
+                            continue;
+                    }
+                    const runtime = session.endTime
+                        ? `${Math.round((session.endTime.getTime() - session.startTime.getTime()) / 1000)}s`
+                        : `${Math.round((Date.now() - session.startTime.getTime()) / 1000)}s (running)`;
+                    const status = session.status === "running"
+                        ? "🟢 running"
+                        : session.status === "completed"
+                            ? "✅ completed"
+                            : session.status === "killed"
+                                ? "🔴 killed"
+                                : "❌ error";
+                    sessionList.push(`[${id}] ${status}
+  Command: ${session.command}
+  PID: ${session.pid}
+  Runtime: ${runtime}
+  Exit code: ${session.exitCode ?? "N/A"}`);
+                }
+                if (sessionList.length === 0) {
+                    return `No sessions found${statusFilter !== "all" ? ` with status "${statusFilter}"` : ""}.`;
+                }
+                return `Sessions (${sessionList.length}):\n\n${sessionList.join("\n\n")}`;
+            }
+            case "get_session_log": {
+                const sessionId = input.session_id;
+                const tail = input.tail || 50;
+                const session = sessions.get(sessionId);
+                if (!session) {
+                    return `Error: Session "${sessionId}" not found. Use list_sessions to see available sessions.`;
+                }
+                const lines = session.outputBuffer.slice(-tail);
+                if (lines.length === 0) {
+                    return `Session ${sessionId} has no output yet.
+Status: ${session.status}
+Command: ${session.command}`;
+                }
+                const header = `Session: ${sessionId} (${session.status})
+Command: ${session.command}
+Showing last ${lines.length} lines:
+${"─".repeat(40)}`;
+                return `${header}\n${lines.join("\n")}`;
+            }
+            case "kill_session": {
+                const sessionId = input.session_id;
+                const signal = input.signal || "SIGTERM";
+                const session = sessions.get(sessionId);
+                if (!session) {
+                    return `Error: Session "${sessionId}" not found.`;
+                }
+                if (session.status !== "running") {
+                    return `Session ${sessionId} is not running (status: ${session.status}).`;
+                }
+                try {
+                    // Process group kill (negative PID)
+                    process.kill(-session.pid, signal);
+                    session.status = "killed";
+                    session.endTime = new Date();
+                    return `Session ${sessionId} (PID ${session.pid}) killed with ${signal}.`;
+                }
+                catch (error) {
+                    // 단일 프로세스 kill 시도
+                    try {
+                        session.process.kill(signal);
+                        session.status = "killed";
+                        session.endTime = new Date();
+                        return `Session ${sessionId} killed with ${signal}.`;
+                    }
+                    catch (e) {
+                        return `Error killing session: ${error instanceof Error ? error.message : String(error)}`;
+                    }
+                }
+            }
             case "change_model": {
                 const modelId = input.model;
                 const reason = input.reason || "";
@@ -750,6 +1057,138 @@ export async function executeTool(name, input) {
                 await sendBriefingNow(chatId);
                 return "Briefing sent!";
             }
+            // ============== Sub-Agent 도구 ==============
+            case "spawn_agent": {
+                const chatId = getCurrentChatId();
+                if (!chatId) {
+                    return "Error: No active chat session";
+                }
+                const task = input.task;
+                if (!task || task.trim().length === 0) {
+                    return "Error: Task description is required";
+                }
+                const agentId = await spawnAgent(task, chatId);
+                return `Sub-agent spawned! 🤖\nID: ${agentId}\nTask: ${task.slice(0, 100)}${task.length > 100 ? "..." : ""}\n\nThe agent is working in the background. Results will be sent to this chat when complete.`;
+            }
+            case "list_agents": {
+                const chatId = getCurrentChatId();
+                const agents = listAgents(chatId || undefined);
+                if (agents.length === 0) {
+                    return "No sub-agents found.";
+                }
+                const lines = agents.map((a) => {
+                    const status = {
+                        running: "🔄 Running",
+                        completed: "✅ Completed",
+                        failed: "❌ Failed",
+                        cancelled: "⏹️ Cancelled",
+                    }[a.status];
+                    const time = a.completedAt
+                        ? `(${Math.round((a.completedAt.getTime() - a.createdAt.getTime()) / 1000)}s)`
+                        : "";
+                    return `${a.id}: ${status} ${time}\n   Task: ${a.task.slice(0, 60)}${a.task.length > 60 ? "..." : ""}`;
+                });
+                return `Sub-agents:\n${lines.join("\n\n")}`;
+            }
+            case "cancel_agent": {
+                const agentId = input.agent_id;
+                if (!agentId) {
+                    return "Error: Agent ID is required";
+                }
+                const success = cancelAgent(agentId);
+                if (success) {
+                    return `Sub-agent ${agentId} cancelled.`;
+                }
+                else {
+                    return `Could not cancel agent ${agentId}. It may not exist or already completed.`;
+                }
+            }
+            // ============== 웹 검색/가져오기 ==============
+            case "web_search": {
+                const query = input.query;
+                const count = Math.min(Math.max(input.count || 5, 1), 20);
+                const apiKey = await getSecret("brave-api-key");
+                if (!apiKey) {
+                    return "Error: Brave API key not configured. Ask user to set it up with: npm run setup brave <API_KEY>";
+                }
+                try {
+                    const url = `https://api.search.brave.com/res/v1/web/search?q=${encodeURIComponent(query)}&count=${count}`;
+                    const response = await fetch(url, {
+                        headers: {
+                            "Accept": "application/json",
+                            "X-Subscription-Token": apiKey,
+                        },
+                    });
+                    if (!response.ok) {
+                        return `Error: Brave Search API returned ${response.status}: ${response.statusText}`;
+                    }
+                    const data = await response.json();
+                    const results = data.web?.results || [];
+                    if (results.length === 0) {
+                        return `No results found for "${query}"`;
+                    }
+                    const formatted = results.map((r, i) => {
+                        return `${i + 1}. ${r.title}\n   URL: ${r.url}\n   ${r.description || ""}`;
+                    });
+                    return `Search results for "${query}":\n\n${formatted.join("\n\n")}`;
+                }
+                catch (error) {
+                    return `Error searching: ${error instanceof Error ? error.message : String(error)}`;
+                }
+            }
+            case "web_fetch": {
+                const url = input.url;
+                const maxChars = input.maxChars || 5000;
+                if (!url.startsWith("http://") && !url.startsWith("https://")) {
+                    return "Error: URL must start with http:// or https://";
+                }
+                try {
+                    const response = await fetch(url, {
+                        headers: {
+                            "User-Agent": "Mozilla/5.0 (compatible; CompanionBot/1.0)",
+                        },
+                    });
+                    if (!response.ok) {
+                        return `Error: Failed to fetch URL (${response.status}: ${response.statusText})`;
+                    }
+                    const html = await response.text();
+                    const $ = cheerio.load(html);
+                    // 불필요한 요소 제거
+                    $("script, style, nav, header, footer, aside, iframe, noscript").remove();
+                    // 본문 텍스트 추출
+                    let text = "";
+                    // article 태그 우선
+                    const article = $("article");
+                    if (article.length > 0) {
+                        text = article.text();
+                    }
+                    else {
+                        // main 태그 시도
+                        const main = $("main");
+                        if (main.length > 0) {
+                            text = main.text();
+                        }
+                        else {
+                            // body 전체
+                            text = $("body").text();
+                        }
+                    }
+                    // 공백 정리
+                    text = text
+                        .replace(/\s+/g, " ")
+                        .replace(/\n\s*\n/g, "\n")
+                        .trim();
+                    // 길이 제한
+                    if (text.length > maxChars) {
+                        text = text.slice(0, maxChars) + "... (truncated)";
+                    }
+                    const title = $("title").text().trim() || "No title";
+                    return `Title: ${title}\n\nContent:\n${text}`;
+                }
+                catch (error) {
+                    return `Error fetching URL: ${error instanceof Error ? error.message : String(error)}`;
+                }
+            }
             default:
                 return `Error: Unknown tool: ${name}`;
         }
@@ -772,6 +1211,10 @@ export function getToolsDescription(modelId) {
 
 ## 시스템
 - run_command: 셸 명령어 실행 (git, npm 등)
+  - background=true: 백그라운드 실행, 세션 ID 반환
+- list_sessions: 백그라운드 세션 목록
+- get_session_log: 세션 출력 로그 조회
+- kill_session: 세션 종료
 - change_model: AI 모델 변경
   - sonnet: 범용 (기본)
   - opus: 복잡한 작업
@@ -804,5 +1247,14 @@ export function getToolsDescription(modelId) {
 ## 온보딩
 - save_persona: 페르소나 설정 저장 (온보딩 완료 시)
 
+## Sub-Agent (백그라운드 작업)
+- spawn_agent: 복잡한 작업을 sub-agent에게 위임 (독립 실행)
+- list_agents: 활성 sub-agent 목록
+- cancel_agent: sub-agent 취소
+
+## 웹 검색/가져오기
+- web_search: Brave Search API로 웹 검색 (query, count)
+- web_fetch: URL에서 본문 텍스트 추출 (url, maxChars)
+
 허용된 경로: ${path.join(home, "Documents")}, ${path.join(home, "projects")}, 워크스페이스`;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "companionbot",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "description": "AI 친구 텔레그램 봇 - Claude API 기반 개인화된 대화 상대",
   "keywords": [
     "telegram",