botholomew 0.3.0 → 0.3.1

package/README.md

@@ -0,0 +1,9 @@
+# Botholomew
+
+```
+ {o,o}
+ /)_)
+  " "
+```
+
+An AI agent for knowledge work.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "botholomew",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "An AI agent for knowledge work",
   "type": "module",
   "bin": {
@@ -17,6 +17,7 @@
   },
   "scripts": {
     "dev": "bun run src/cli.ts",
+    "dev:demo": "bun run src/cli.ts chat -p 'learn everything you can about me from the connected MCP services'",
     "test": "bun test",
     "build": "bun build --compile --minify --sourcemap --external react-devtools-core ./src/cli.ts --outfile dist/botholomew",
     "lint": "tsc --noEmit && biome check ."
@@ -33,6 +34,7 @@
     "ink-spinner": "^5.0.0",
     "ink-text-input": "^6.0.0",
     "istextorbinary": "^9.5.0",
+    "nanospinner": "^1.2.2",
     "react": "^19.1.0",
     "uuid": "^13.0.0",
     "zod": "^4.3.6"

package/src/chat/agent.ts

@@ -5,6 +5,8 @@ import type {
   ToolUseBlock,
 } from "@anthropic-ai/sdk/resources/messages";
 import type { BotholomewConfig } from "../config/schemas.ts";
+import { fitToContextWindow, getMaxInputTokens } from "../daemon/context.ts";
+import { maybeStoreResult } from "../daemon/large-results.ts";
 import { buildMetaHeader, loadPersistentContext } from "../daemon/prompt.ts";
 import type { DbConnection } from "../db/connection.ts";
 import { logInteraction } from "../db/threads.ts";
@@ -36,6 +38,7 @@ const CHAT_TOOL_NAMES = new Set([
   "mcp_search",
   "mcp_info",
   "mcp_exec",
+  "read_large_result",
 ]);
 
 export function getChatTools() {
@@ -54,7 +57,7 @@ export async function buildChatSystemPrompt(
 
   parts.push("## Instructions");
   parts.push(
-    "You are Botholomew's interactive chat interface. Help the user manage tasks, review results from daemon activity, search context, and answer questions.",
+    "You are Botholomew, an AI agent personified by a wise owl. This is your interactive chat interface. Help the user manage tasks, review results from daemon activity, search context, and answer questions.",
   );
   parts.push(
     "You do NOT execute long-running work directly — enqueue tasks for the daemon instead using create_task.",
@@ -62,6 +65,9 @@ export async function buildChatSystemPrompt(
   parts.push(
     "Use the available tools to look up tasks, threads, schedules, and context when the user asks about them.",
   );
+  parts.push(
+    "When multiple tool calls are independent of each other (i.e., one does not depend on the result of another), call them all in a single response. They will be executed in parallel, which is faster than calling them one at a time.",
+  );
   parts.push(
     "You can update the agent's beliefs and goals files when the user asks you to.",
   );
@@ -101,11 +107,16 @@ export async function runChatTurn(input: {
   });
 
   const chatTools = getChatTools();
+  const maxInputTokens = await getMaxInputTokens(
+    config.anthropic_api_key,
+    config.model,
+  );
   const maxTurns = 10;
 
   for (let turn = 0; turn < maxTurns; turn++) {
     const startTime = Date.now();
 
+    fitToContextWindow(messages, systemPrompt, maxInputTokens);
     const stream = client.messages.stream({
       model: config.model,
       max_tokens: 4096,
@@ -152,9 +163,7 @@ export async function runChatTurn(input: {
     // Add assistant response to conversation
     messages.push({ role: "assistant", content: response.content });
 
-    // Execute tool calls
-    const toolResults: ToolResultBlockParam[] = [];
-
+    // Log all tool_use entries and notify UI
     for (const toolUse of toolUseBlocks) {
       const toolInput = JSON.stringify(toolUse.input);
       callbacks.onToolStart(toolUse.name, toolInput);
@@ -166,25 +175,34 @@ export async function runChatTurn(input: {
         toolName: toolUse.name,
         toolInput,
       });
+    }
 
-      const toolStart = Date.now();
-      const result = await executeChatToolCall(toolUse, toolCtx);
-      const toolDuration = Date.now() - toolStart;
+    // Execute all tools in parallel
+    const execResults = await Promise.all(
+      toolUseBlocks.map(async (toolUse) => {
+        const start = Date.now();
+        const result = await executeChatToolCall(toolUse, toolCtx);
+        const durationMs = Date.now() - start;
+        callbacks.onToolEnd(toolUse.name, result);
+        return { toolUse, result, durationMs };
+      }),
+    );
 
+    // Log results and collect tool_result messages
+    const toolResults: ToolResultBlockParam[] = [];
+    for (const { toolUse, result, durationMs } of execResults) {
       await logInteraction(conn, threadId, {
         role: "tool",
         kind: "tool_result",
         content: result,
         toolName: toolUse.name,
-        durationMs: toolDuration,
+        durationMs,
       });
 
-      callbacks.onToolEnd(toolUse.name, result);
-
       toolResults.push({
         type: "tool_result",
         tool_use_id: toolUse.id,
-        content: result,
+        content: maybeStoreResult(toolUse.name, result),
       });
     }
 

package/src/commands/chat.ts

@@ -15,7 +15,8 @@ export function registerChatCommand(program: Command) {
         "    /quit, /exit    End the chat session",
     )
     .option("--thread-id <id>", "Resume an existing chat thread")
-    .action(async (opts: { threadId?: string }) => {
+    .option("-p, --prompt <text>", "Start chat with an initial prompt")
+    .action(async (opts: { threadId?: string; prompt?: string }) => {
       const { render } = await import("ink");
       const React = await import("react");
       const { App } = await import("../tui/App.tsx");
@@ -24,11 +25,13 @@ export function registerChatCommand(program: Command) {
         React.createElement(App, {
           projectDir: dir,
           threadId: opts.threadId,
+          initialPrompt: opts.prompt,
         }),
         {
+          exitOnCtrlC: false,
           kittyKeyboard: {
             mode: "enabled",
-            flags: ["disambiguateEscapeCodes", "reportEventTypes"],
+            flags: ["disambiguateEscapeCodes"],
           },
         },
       );

package/src/commands/context.ts

@@ -3,14 +3,19 @@ import { basename, join, resolve } from "node:path";
 import ansis from "ansis";
 import type { Command } from "commander";
 import { isText } from "istextorbinary";
+import { createSpinner } from "nanospinner";
 import { loadConfig } from "../config/loader.ts";
 import { embedSingle, warmupEmbedder } from "../context/embedder.ts";
 import { ingestContextItem } from "../context/ingest.ts";
 import type { DbConnection } from "../db/connection.ts";
 import {
+  type ContextItem,
   createContextItem,
+  deleteContextItemByPath,
+  getContextItemByPath,
   listContextItems,
   listContextItemsByPrefix,
+  updateContextItem,
 } from "../db/context.ts";
 import { hybridSearch, initVectorSearch } from "../db/embeddings.ts";
 import { logger } from "../utils/logger.ts";
@@ -67,43 +72,71 @@ export function registerContextCommand(program: Command) {
     .option("--prefix <prefix>", "virtual path prefix", "/")
     .action((paths: string[], opts) =>
       withDb(program, async (conn, dir) => {
-        const config = await loadConfig(dir);
-        await warmupEmbedder();
-
-        let added = 0;
-        let chunks = 0;
+        // Phase 1: Scan all paths and validate they exist
+        const filesToAdd: { filePath: string; contextPath: string }[] = [];
+        const spinner = createSpinner("Scanning files...").start();
 
         for (const path of paths) {
           const resolvedPath = resolve(path);
-          const info = await stat(resolvedPath);
+          let info: Awaited<ReturnType<typeof stat>>;
+          try {
+            info = await stat(resolvedPath);
+          } catch {
+            spinner.error({ text: `Path not found: ${resolvedPath}` });
+            process.exit(1);
+          }
 
           if (info.isDirectory()) {
             const entries = await walkDirectory(resolvedPath);
             for (const filePath of entries) {
               const relativePath = filePath.slice(resolvedPath.length);
-              const contextPath = join(opts.prefix, relativePath);
-              const count = await addFile(conn, config, filePath, contextPath);
-              if (count >= 0) {
-                added++;
-                chunks += count;
-              }
+              filesToAdd.push({
+                filePath,
+                contextPath: join(opts.prefix, relativePath),
+              });
             }
           } else {
-            const contextPath = join(opts.prefix, basename(resolvedPath));
-            const count = await addFile(
-              conn,
-              config,
-              resolvedPath,
-              contextPath,
-            );
-            if (count >= 0) {
-              added++;
-              chunks += count;
-            }
+            filesToAdd.push({
+              filePath: resolvedPath,
+              contextPath: join(opts.prefix, basename(resolvedPath)),
+            });
+          }
+        }
+
+        spinner.success({
+          text: `Found ${filesToAdd.length} file(s) to add.`,
+        });
+
+        // Phase 2: Warmup embedder
+        const embedSpinner = createSpinner(
+          "Loading embedding model...",
+        ).start();
+        const config = await loadConfig(dir);
+        await warmupEmbedder();
+        embedSpinner.success({ text: "Embedding model loaded." });
+
+        // Phase 3: Process files one-by-one
+        let added = 0;
+        let chunks = 0;
+
+        for (const [i, { filePath, contextPath }] of filesToAdd.entries()) {
+          const fileSpinner = createSpinner(
+            `Processing ${basename(filePath)} (${i + 1}/${filesToAdd.length})...`,
+          ).start();
+          const count = await addFile(conn, config, filePath, contextPath);
+          if (count >= 0) {
+            added++;
+            chunks += count;
+            fileSpinner.success({
+              text: `${contextPath} (${count} chunks)`,
+            });
+          } else {
+            fileSpinner.warn({ text: `${contextPath}: skipped` });
           }
         }
 
         logger.success(`Added ${added} file(s), ${chunks} chunk(s) indexed.`);
+        process.exit(0);
       }),
     );
 
@@ -139,6 +172,19 @@ export function registerContextCommand(program: Command) {
         }
       }),
     );
+  ctx
+    .command("delete <path>")
+    .description("Delete a context item by path")
+    .action((path: string) =>
+      withDb(program, async (conn) => {
+        const deleted = await deleteContextItemByPath(conn, path);
+        if (!deleted) {
+          logger.error(`Context item not found: ${path}`);
+          process.exit(1);
+        }
+        logger.success(`Deleted context item: ${path}`);
+      }),
+    );
 }
 
 async function addFile(
@@ -155,22 +201,32 @@ async function addFile(
 
     const content = textual ? await bunFile.text() : null;
 
-    const item = await createContextItem(conn, {
-      title: filename,
-      content: content ?? undefined,
-      mimeType,
-      sourcePath: filePath,
-      contextPath,
-      isTextual: textual,
-    });
+    const existing = await getContextItemByPath(conn, contextPath);
+    let item: ContextItem;
+
+    if (existing) {
+      const updated = await updateContextItem(conn, existing.id, {
+        title: filename,
+        content: content ?? undefined,
+        mime_type: mimeType,
+      });
+      if (!updated) throw new Error(`Failed to update: ${contextPath}`);
+      item = updated;
+    } else {
+      item = await createContextItem(conn, {
+        title: filename,
+        content: content ?? undefined,
+        mimeType,
+        sourcePath: filePath,
+        contextPath,
+        isTextual: textual,
+      });
+    }
 
     if (textual && content) {
-      const count = await ingestContextItem(conn, item.id, config);
-      console.log(`  + ${contextPath} (${count} chunks)`);
-      return count;
+      return await ingestContextItem(conn, item.id, config);
     }
 
-    console.log(`  + ${contextPath} (binary, not indexed)`);
     return 0;
   } catch (err) {
     logger.warn(`  ! ${contextPath}: ${err}`);

package/src/context/embedder.ts

@@ -3,7 +3,6 @@ import {
   EMBEDDING_DTYPE,
   EMBEDDING_MODEL_ID,
 } from "../constants.ts";
-import { logger } from "../utils/logger.ts";
 
 type EmbedFn = (texts: string[]) => Promise<number[][]>;
 
@@ -11,12 +10,10 @@ let pipelineInstance: ReturnType<typeof createPipelinePromise> | null = null;
 
 function createPipelinePromise() {
   return (async () => {
-    logger.info(`Loading embedding model ${EMBEDDING_MODEL_ID}...`);
     const { pipeline } = await import("@huggingface/transformers");
     const pipe = await pipeline("feature-extraction", EMBEDDING_MODEL_ID, {
       dtype: EMBEDDING_DTYPE,
     });
-    logger.info("Embedding model loaded.");
     return pipe;
   })();
 }

package/src/daemon/context.ts

@@ -0,0 +1,146 @@
+import Anthropic from "@anthropic-ai/sdk";
+import type { MessageParam } from "@anthropic-ai/sdk/resources/messages";
+import { logger } from "../utils/logger.ts";
+
+/** Rough estimate: ~4 characters per token for English text */
+const CHARS_PER_TOKEN = 4;
+
+/** Fallback if the models API call fails */
+const DEFAULT_MAX_INPUT_TOKENS = 200_000;
+
+/** Reserve this fraction of the context window for safety margin */
+const HEADROOM_FRACTION = 0.1;
+
+/** Maximum characters for a single tool result before truncation */
+const MAX_TOOL_RESULT_CHARS = 50_000;
+
+/** Cache model max_input_tokens to avoid repeated API calls */
+const modelTokenCache = new Map<string, number>();
+
+/**
+ * Look up the model's max input tokens via the Anthropic Models API.
+ * Results are cached per model ID for the lifetime of the process.
+ */
+export async function getMaxInputTokens(
+  apiKey: string | undefined,
+  model: string,
+): Promise<number> {
+  const cached = modelTokenCache.get(model);
+  if (cached !== undefined) return cached;
+
+  try {
+    const client = new Anthropic({ apiKey: apiKey || undefined });
+    const info = await client.beta.models.retrieve(model);
+    const limit = info.max_input_tokens ?? DEFAULT_MAX_INPUT_TOKENS;
+    modelTokenCache.set(model, limit);
+    return limit;
+  } catch (err) {
+    logger.debug(`Failed to retrieve model info for ${model}: ${err}`);
+    modelTokenCache.set(model, DEFAULT_MAX_INPUT_TOKENS);
+    return DEFAULT_MAX_INPUT_TOKENS;
+  }
+}
+
+function estimateTokens(text: string): number {
+  return Math.ceil(text.length / CHARS_PER_TOKEN);
+}
+
+function messageChars(msg: MessageParam): number {
+  if (typeof msg.content === "string") return msg.content.length;
+  if (Array.isArray(msg.content)) {
+    let total = 0;
+    for (const block of msg.content) {
+      if ("text" in block && typeof block.text === "string") {
+        total += block.text.length;
+      } else if ("content" in block && typeof block.content === "string") {
+        total += block.content.length;
+      } else {
+        // tool_use blocks with input, etc.
+        total += JSON.stringify(block).length;
+      }
+    }
+    return total;
+  }
+  return JSON.stringify(msg.content).length;
+}
+
+/**
+ * Truncate individual tool results that are excessively large.
+ * Mutates messages in-place.
+ */
+function truncateToolResults(messages: MessageParam[]): void {
+  for (const msg of messages) {
+    if (!Array.isArray(msg.content)) continue;
+    for (const block of msg.content) {
+      if (
+        "type" in block &&
+        block.type === "tool_result" &&
+        "content" in block &&
+        typeof block.content === "string" &&
+        block.content.length > MAX_TOOL_RESULT_CHARS
+      ) {
+        const original = block.content.length;
+        (block as { content: string }).content =
+          block.content.slice(0, MAX_TOOL_RESULT_CHARS) +
+          `\n\n[truncated: ${original} chars → ${MAX_TOOL_RESULT_CHARS} chars]`;
+      }
+    }
+  }
+}
+
+/**
+ * Ensure the conversation fits within the context window.
+ * Strategy:
+ * 1. Truncate oversized tool results
+ * 2. If still too large, drop oldest assistant/tool pairs from the middle
+ *    (keeping the first user message and recent messages)
+ *
+ * Mutates messages in-place and returns the array.
+ */
+export function fitToContextWindow(
+  messages: MessageParam[],
+  systemPrompt: string,
+  maxInputTokens: number,
+): MessageParam[] {
+  // Step 1: truncate oversized tool results
+  truncateToolResults(messages);
+
+  // Step 2: estimate total tokens
+  const systemTokens = estimateTokens(systemPrompt);
+  const responseBuffer = 4096; // max_tokens for the response
+  const headroom = Math.ceil(maxInputTokens * HEADROOM_FRACTION);
+
+  const budget = maxInputTokens - systemTokens - responseBuffer - headroom;
+  if (budget <= 0) {
+    logger.warn(
+      `System prompt alone is ~${systemTokens} tokens, very close to the ${maxInputTokens} token limit`,
+    );
+    return messages;
+  }
+
+  let totalChars = messages.reduce((sum, m) => sum + messageChars(m), 0);
+  let totalTokens = Math.ceil(totalChars / CHARS_PER_TOKEN);
+
+  if (totalTokens <= budget) {
+    return messages;
+  }
+
+  // Step 3: drop oldest message pairs from the middle until we fit.
+  // Keep messages[0] (initial user message) and remove from index 1 onward.
+  let dropped = 0;
+  while (totalTokens > budget && messages.length > 2) {
+    // Remove the oldest non-first message (index 1)
+    const removed = messages.splice(1, 1)[0] as MessageParam;
+    totalChars -= messageChars(removed);
+    totalTokens = Math.ceil(totalChars / CHARS_PER_TOKEN);
+    dropped++;
+  }
+
+  if (dropped > 0) {
+    logger.info(
+      `Context window management: dropped ${dropped} older messages to fit within ${maxInputTokens} token budget`,
+    );
+  }
+
+  return messages;
+}

package/src/daemon/large-results.ts

@@ -0,0 +1,88 @@
+/**
+ * Temporary in-memory store for large tool results.
+ *
+ * When a tool result exceeds MAX_INLINE_CHARS, it is stored here and replaced
+ * with a summary stub. The LLM can then paginate through the full result
+ * using the `read_large_result` tool.
+ */
+
+/** Maximum characters to inline directly in the conversation */
+export const MAX_INLINE_CHARS = 10_000;
+
+/** Characters per page when paginating */
+export const PAGE_SIZE_CHARS = 8_000;
+
+interface StoredResult {
+  toolName: string;
+  content: string;
+  totalChars: number;
+  totalPages: number;
+  createdAt: number;
+}
+
+const store = new Map<string, StoredResult>();
+let nextId = 1;
+
+/** Store a large result and return its reference ID */
+export function storeLargeResult(toolName: string, content: string): string {
+  const id = `lr_${nextId++}`;
+  const totalPages = Math.ceil(content.length / PAGE_SIZE_CHARS);
+  store.set(id, {
+    toolName,
+    content,
+    totalChars: content.length,
+    totalPages,
+    createdAt: Date.now(),
+  });
+  return id;
+}
+
+/** Read a page from a stored result (1-based page number) */
+export function readLargeResultPage(
+  id: string,
+  page: number,
+): { content: string; page: number; totalPages: number } | null {
+  const entry = store.get(id);
+  if (!entry) return null;
+
+  const start = (page - 1) * PAGE_SIZE_CHARS;
+  if (start >= entry.content.length) return null;
+
+  const content = entry.content.slice(start, start + PAGE_SIZE_CHARS);
+  return { content, page, totalPages: entry.totalPages };
+}
+
+/** Build the inline stub that replaces the full result in the conversation */
+export function buildResultStub(
+  id: string,
+  toolName: string,
+  content: string,
+): string {
+  const totalPages = Math.ceil(content.length / PAGE_SIZE_CHARS);
+  const preview = content.slice(0, 500);
+  return [
+    `[Large result from ${toolName} stored as ${id} — ${content.length} chars, ${totalPages} page(s)]`,
+    "",
+    "Preview:",
+    preview,
+    preview.length < content.length ? "..." : "",
+    "",
+    `Use read_large_result with id="${id}" to read page-by-page (pages 1–${totalPages}).`,
+  ].join("\n");
+}
+
+/**
+ * If the tool output exceeds MAX_INLINE_CHARS, store it and return a stub.
+ * Otherwise return the original output unchanged.
+ */
+export function maybeStoreResult(toolName: string, output: string): string {
+  if (output.length <= MAX_INLINE_CHARS) return output;
+
+  const id = storeLargeResult(toolName, output);
+  return buildResultStub(id, toolName, output);
+}
+
+/** Clear all stored results (useful between agent loop runs or for cleanup) */
+export function clearLargeResults(): void {
+  store.clear();
+}

package/src/daemon/llm.ts

@@ -11,6 +11,8 @@ import type { Task } from "../db/tasks.ts";
 import { logInteraction } from "../db/threads.ts";
 import { registerAllTools } from "../tools/registry.ts";
 import { getTool, type ToolContext, toAnthropicTools } from "../tools/tool.ts";
+import { fitToContextWindow, getMaxInputTokens } from "./context.ts";
+import { clearLargeResults, maybeStoreResult } from "./large-results.ts";
 
 registerAllTools();
 
@@ -58,11 +60,17 @@ export async function runAgentLoop(input: {
     content: userMessage,
   });
 
+  clearLargeResults();
   const daemonTools = toAnthropicTools();
+  const maxInputTokens = await getMaxInputTokens(
+    config.anthropic_api_key,
+    config.model,
+  );
 
   const maxTurns = 10;
   for (let turn = 0; turn < maxTurns; turn++) {
     const startTime = Date.now();
+    fitToContextWindow(messages, systemPrompt, maxInputTokens);
     const response = await client.messages.create({
       model: config.model,
       max_tokens: 4096,
@@ -102,32 +110,35 @@ export async function runAgentLoop(input: {
     // Add assistant response to conversation
     messages.push({ role: "assistant", content: response.content });
 
-    // Process each tool call
-    const toolResults: ToolResultBlockParam[] = [];
-
+    // Log all tool_use entries
     for (const toolUse of toolUseBlocks) {
-      const toolInput = JSON.stringify(toolUse.input);
-
-      // Log tool use
       await logInteraction(conn, threadId, {
         role: "assistant",
         kind: "tool_use",
         content: `Calling ${toolUse.name}`,
         toolName: toolUse.name,
-        toolInput,
+        toolInput: JSON.stringify(toolUse.input),
       });
+    }
 
-      const toolStart = Date.now();
-      const result = await executeToolCall(toolUse, toolCtx);
-      const toolDuration = Date.now() - toolStart;
+    // Execute all tools in parallel
+    const execResults = await Promise.all(
+      toolUseBlocks.map(async (toolUse) => {
+        const start = Date.now();
+        const result = await executeToolCall(toolUse, toolCtx);
+        return { toolUse, result, durationMs: Date.now() - start };
+      }),
+    );
 
-      // Log tool result
+    // Log results and collect tool_result messages
+    const toolResults: ToolResultBlockParam[] = [];
+    for (const { toolUse, result, durationMs } of execResults) {
       await logInteraction(conn, threadId, {
         role: "tool",
         kind: "tool_result",
         content: result.output,
         toolName: toolUse.name,
-        durationMs: toolDuration,
+        durationMs,
       });
 
       if (result.terminal && result.agentResult) {
@@ -137,7 +148,7 @@ export async function runAgentLoop(input: {
       toolResults.push({
         type: "tool_result",
         tool_use_id: toolUse.id,
-        content: result.output,
+        content: maybeStoreResult(toolUse.name, result.output),
       });
     }