botholomew 0.3.0 → 0.3.2

package/src/commands/thread.ts

@@ -0,0 +1,180 @@
+import ansis from "ansis";
+import type { Command } from "commander";
+import type { DbConnection } from "../db/connection.ts";
+import type { Interaction, Thread } from "../db/threads.ts";
+import { deleteThread, getThread, listThreads } from "../db/threads.ts";
+import { logger } from "../utils/logger.ts";
+import { withDb } from "./with-db.ts";
+
+export function registerThreadCommand(program: Command) {
+  const thread = program.command("thread").description("Manage chat threads");
+
+  thread
+    .command("list")
+    .description("List threads")
+    .option("-t, --type <type>", "filter by type (daemon_tick, chat_session)")
+    .option("-l, --limit <n>", "max number of threads", parseInt)
+    .action((opts) =>
+      withDb(program, async (conn) => {
+        const threads = await listThreads(conn, {
+          type: opts.type,
+          limit: opts.limit,
+        });
+
+        if (threads.length === 0) {
+          logger.dim("No threads found.");
+          return;
+        }
+
+        for (const t of threads) {
+          printThread(t);
+        }
+      }),
+    );
+
+  thread
+    .command("view <id>")
+    .description("View thread details and interactions")
+    .option(
+      "--only <roles>",
+      "show only these roles (comma-separated: user,assistant,tool,system)",
+    )
+    .action((id, opts) =>
+      withDb(program, async (conn) => {
+        const resolvedId = await resolveThreadId(conn, id);
+        if (!resolvedId) {
+          logger.error(`Thread not found: ${id}`);
+          process.exit(1);
+        }
+        const result = await getThread(conn, resolvedId);
+        if (!result) {
+          logger.error(`Thread not found: ${id}`);
+          process.exit(1);
+        }
+        const interactions = opts.only
+          ? result.interactions.filter((i) =>
+              (opts.only as string).split(",").includes(i.role),
+            )
+          : result.interactions;
+        printThreadDetail(result.thread, interactions);
+      }),
+    );
+
+  thread
+    .command("delete <id>")
+    .description("Delete a thread and its interactions")
+    .action((id) =>
+      withDb(program, async (conn) => {
+        const resolvedId = await resolveThreadId(conn, id);
+        if (!resolvedId) {
+          logger.error(`Thread not found: ${id}`);
+          process.exit(1);
+        }
+        const deleted = await deleteThread(conn, resolvedId);
+        if (!deleted) {
+          logger.error(`Thread not found: ${id}`);
+          process.exit(1);
+        }
+        logger.success(`Deleted thread: ${resolvedId}`);
+      }),
+    );
+}
+
+async function resolveThreadId(
+  conn: DbConnection,
+  idPrefix: string,
+): Promise<string | null> {
+  if (idPrefix.length >= 36) return idPrefix;
+  const all = await listThreads(conn);
+  const matches = all.filter((t) => t.id.startsWith(idPrefix));
+  if (matches.length === 1) {
+    const match = matches[0] as Thread;
+    return match.id;
+  }
+  if (matches.length === 0) return null;
+  logger.error(
+    `Ambiguous thread prefix "${idPrefix}" matches ${matches.length} threads`,
+  );
+  process.exit(1);
+}
+
+function typeColor(type: Thread["type"]): string {
+  switch (type) {
+    case "daemon_tick":
+      return ansis.magenta(type);
+    case "chat_session":
+      return ansis.cyan(type);
+  }
+}
+
+function statusLabel(thread: Thread): string {
+  return thread.ended_at ? ansis.dim("ended") : ansis.green("active");
+}
+
+function roleColor(role: Interaction["role"]): string {
+  switch (role) {
+    case "user":
+      return ansis.cyan(role);
+    case "assistant":
+      return ansis.green(role);
+    case "system":
+      return ansis.yellow(role);
+    case "tool":
+      return ansis.magenta(role);
+  }
+}
+
+function printThread(t: Thread) {
+  const id = ansis.dim(t.id.slice(0, 8));
+  const title = t.title || ansis.dim("(untitled)");
+  console.log(`  ${id}  ${typeColor(t.type)}  ${statusLabel(t)}  ${title}`);
+}
+
+function printThreadDetail(t: Thread, interactions: Interaction[]) {
+  console.log(ansis.bold(t.title || "(untitled)"));
+  console.log(`  ID:       ${t.id}`);
+  console.log(`  Type:     ${typeColor(t.type)}`);
+  console.log(`  Status:   ${statusLabel(t)}`);
+  if (t.task_id) console.log(`  Task:     ${t.task_id}`);
+  console.log(`  Started:  ${t.started_at.toISOString()}`);
+  console.log(
+    `  Ended:    ${t.ended_at ? t.ended_at.toISOString() : ansis.dim("—")}`,
+  );
+
+  if (interactions.length === 0) {
+    console.log(`\n  ${ansis.dim("No interactions.")}`);
+    return;
+  }
+
+  console.log(`\n  Interactions (${interactions.length}):`);
+  for (const i of interactions) {
+    printInteraction(i);
+  }
+}
+
+function formatTime(date: Date): string {
+  return date
+    .toISOString()
+    .replace("T", " ")
+    .replace(/\.\d{3}Z$/, "");
+}
+
+function printInteraction(i: Interaction) {
+  const seq = ansis.dim(`#${i.sequence}`);
+  const ts = ansis.dim(formatTime(i.created_at));
+  const kind = ansis.dim(`[${i.kind}]`);
+  let preview: string;
+  if (i.kind === "tool_use" && i.tool_name) {
+    preview = ansis.yellow(i.tool_name);
+  } else {
+    const text = i.content.replace(/\n/g, " ");
+    preview = text.length > 120 ? `${text.slice(0, 120)}...` : text;
+  }
+  const extras: string[] = [];
+  if (i.token_count) extras.push(`${i.token_count} tok`);
+  if (i.duration_ms) extras.push(`${i.duration_ms}ms`);
+  const suffix = extras.length > 0 ? `  ${ansis.dim(extras.join(", "))}` : "";
+  console.log(
+    `  ${seq}  ${ts}  ${roleColor(i.role)}  ${kind}  ${preview}${suffix}`,
+  );
+}

package/src/config/schemas.ts

@@ -5,13 +5,15 @@ export interface BotholomewConfig {
   tick_interval_seconds?: number;
   max_tick_duration_seconds?: number;
   system_prompt_override?: string;
+  max_turns?: number;
 }
 
 export const DEFAULT_CONFIG: Required<BotholomewConfig> = {
   anthropic_api_key: "",
   model: "claude-opus-4-20250514",
-  chunker_model: "claude-haiku-4-20250514",
+  chunker_model: "claude-haiku-4-5-20251001",
   tick_interval_seconds: 300,
   max_tick_duration_seconds: 120,
   system_prompt_override: "",
+  max_turns: 0,
 };

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,100 @@
+/**
+ * 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");
+}
+
+export interface MaybeStoreResultOutput {
+  text: string;
+  stored?: { id: string; chars: number; pages: number };
+}
+
+/**
+ * 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,
+): MaybeStoreResultOutput {
+  if (output.length <= MAX_INLINE_CHARS) return { text: output };
+
+  const id = storeLargeResult(toolName, output);
+  const pages = Math.ceil(output.length / PAGE_SIZE_CHARS);
+  return {
+    text: buildResultStub(id, toolName, output),
+    stored: { id, chars: output.length, pages },
+  };
+}
+
+/** 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();
 
@@ -47,7 +49,7 @@ export async function runAgentLoop(input: {
     mcpxClient: input.mcpxClient ?? null,
   };
 
-  const userMessage = `Please work on this task:\n\nName: ${task.name}\nDescription: ${task.description}\nPriority: ${task.priority}\n\nUse the available tools to complete this task, then call complete_task, fail_task, or wait_task to indicate the outcome.`;
+  const userMessage = `Task:\nName: ${task.name}\nDescription: ${task.description}\nPriority: ${task.priority}`;
 
   const messages: MessageParam[] = [{ role: "user", content: userMessage }];
 
@@ -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 maxTurns = config.max_turns;
+  for (let turn = 0; !maxTurns || 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,8 @@ export async function runAgentLoop(input: {
       toolResults.push({
         type: "tool_result",
         tool_use_id: toolUse.id,
-        content: result.output,
+        content: maybeStoreResult(toolUse.name, result.output).text,
+        is_error: result.isError || undefined,
       });
     }
 
@@ -150,6 +162,7 @@ export async function runAgentLoop(input: {
 interface ToolCallResult {
   output: string;
   terminal: boolean;
+  isError: boolean;
   agentResult?: AgentLoopResult;
 }
 
@@ -159,18 +172,30 @@ async function executeToolCall(
 ): Promise<ToolCallResult> {
   const tool = getTool(toolUse.name);
   if (!tool) {
-    return { output: `Unknown tool: ${toolUse.name}`, terminal: false };
+    return {
+      output: `Unknown tool: ${toolUse.name}`,
+      terminal: false,
+      isError: true,
+    };
   }
 
   const parsed = tool.inputSchema.safeParse(toolUse.input);
   if (!parsed.success) {
+    const issues = parsed.error.issues
+      .map((i) => `${i.path.join(".")}: ${i.message}`)
+      .join("; ");
     return {
-      output: `Invalid input: ${JSON.stringify(parsed.error)}`,
+      output: `Invalid input for ${toolUse.name}: ${issues}. Check the tool's expected parameters.`,
       terminal: false,
+      isError: true,
     };
   }
 
   const result = await tool.execute(parsed.data, ctx);
+  const isError =
+    typeof result === "object" && result !== null && "is_error" in result
+      ? (result as { is_error: boolean }).is_error
+      : false;
   const output = typeof result === "string" ? result : JSON.stringify(result);
 
   // Check if this is a terminal tool (complete/fail/wait)
@@ -184,10 +209,11 @@ async function executeToolCall(
       return {
         output,
         terminal: true,
+        isError,
         agentResult: { status, reason: String(reason) },
       };
     }
   }
 
-  return { output, terminal: false };
+  return { output, terminal: false, isError };
 }

package/src/daemon/prompt.ts

@@ -123,13 +123,8 @@ export async function buildSystemPrompt(
   // Instructions
   parts.push("## Instructions");
   parts.push(
-    "You are the Botholomew daemon. You wake up periodically to work through tasks.",
+    "You are Botholomew, a wise-owl daemon that works through tasks. Use available tools to complete your assigned task, then call complete_task, fail_task, or wait_task. Use create_task for subtasks and update_task to refine pending tasks. Batch independent tool calls in a single response for parallel execution.",
   );
-  parts.push("When given a task, use the available tools to complete it.");
-  parts.push(
-    "Always call complete_task, fail_task, or wait_task when you are done.",
-  );
-  parts.push("If you need to create subtasks, use create_task.");
   if (options?.hasMcpTools) {
     parts.push("");
     parts.push("## External Tools (MCP)");

package/src/daemon/tick.ts

@@ -8,6 +8,7 @@ import {
 } from "../db/tasks.ts";
 import { createThread, endThread, logInteraction } from "../db/threads.ts";
 import { logger } from "../utils/logger.ts";
+import { generateThreadTitle } from "../utils/title.ts";
 import { runAgentLoop } from "./llm.ts";
 import { buildSystemPrompt } from "./prompt.ts";
 import { processSchedules } from "./schedules.ts";
@@ -82,6 +83,14 @@ export async function tick(
     });
 
     logger.info(`Task ${task.id} -> ${result.status}`);
+
+    // Generate a descriptive title for the thread
+    void generateThreadTitle(
+      config,
+      conn,
+      threadId,
+      `Task: ${task.name}\nDescription: ${task.description}\nOutcome: ${result.status}${result.reason ? ` — ${result.reason}` : ""}`,
+    );
   } catch (err) {
     await updateTaskStatus(conn, task.id, "failed", String(err));
 

package/src/db/sql/4-unique_context_path.sql

@@ -0,0 +1 @@
+CREATE UNIQUE INDEX IF NOT EXISTS idx_context_items_context_path ON context_items(context_path);

package/src/db/threads.ts

@@ -154,6 +154,14 @@ export async function reopenThread(
   db.query("UPDATE threads SET ended_at = NULL WHERE id = ?1").run(threadId);
 }
 
+export async function updateThreadTitle(
+  db: DbConnection,
+  threadId: string,
+  title: string,
+): Promise<void> {
+  db.query("UPDATE threads SET title = ?2 WHERE id = ?1").run(threadId, title);
+}
+
 export async function getThread(
   db: DbConnection,
   threadId: string,
@@ -175,6 +183,15 @@ export async function getThread(
   };
 }
 
+export async function deleteThread(
+  db: DbConnection,
+  threadId: string,
+): Promise<boolean> {
+  db.query("DELETE FROM interactions WHERE thread_id = ?1").run(threadId);
+  const result = db.query("DELETE FROM threads WHERE id = ?1").run(threadId);
+  return result.changes > 0;
+}
+
 export async function listThreads(
   db: DbConnection,
   filters?: {