botholomew 0.3.1 → 0.3.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "botholomew",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "An AI agent for knowledge work",
   "type": "module",
   "bin": {
@@ -17,7 +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'",
+    "dev:demo": "bun run src/cli.ts chat -p 'learn everything you can about me from the connected MCP services and then save what you'\\''ve learned about me to context'",
     "test": "bun test",
     "build": "bun build --compile --minify --sourcemap --external react-devtools-core ./src/cli.ts --outfile dist/botholomew",
     "lint": "tsc --noEmit && biome check ."

package/src/chat/agent.ts

@@ -79,10 +79,20 @@ export async function buildChatSystemPrompt(
   return parts.join("\n");
 }
 
+export interface ToolEndMeta {
+  largeResult?: { id: string; chars: number; pages: number };
+}
+
 export interface ChatTurnCallbacks {
   onToken: (text: string) => void;
-  onToolStart: (name: string, input: string) => void;
-  onToolEnd: (name: string, output: string) => void;
+  onToolStart: (id: string, name: string, input: string) => void;
+  onToolEnd: (
+    id: string,
+    name: string,
+    output: string,
+    isError: boolean,
+    meta?: ToolEndMeta,
+  ) => void;
 }
 
 /**
@@ -111,9 +121,9 @@ export async function runChatTurn(input: {
     config.anthropic_api_key,
     config.model,
   );
-  const maxTurns = 10;
+  const maxTurns = config.max_turns;
 
-  for (let turn = 0; turn < maxTurns; turn++) {
+  for (let turn = 0; !maxTurns || turn < maxTurns; turn++) {
     const startTime = Date.now();
 
     fitToContextWindow(messages, systemPrompt, maxInputTokens);
@@ -127,12 +137,24 @@ export async function runChatTurn(input: {
 
     // Collect the full response
     let assistantText = "";
+    const earlyReportedToolIds = new Set<string>();
 
     stream.on("text", (text) => {
       assistantText += text;
       callbacks.onToken(text);
     });
 
+    stream.on("contentBlock", (block) => {
+      if (block.type === "tool_use") {
+        earlyReportedToolIds.add(block.id);
+        callbacks.onToolStart(
+          block.id,
+          block.name,
+          JSON.stringify(block.input),
+        );
+      }
+    });
+
     const response = await stream.finalMessage();
     const durationMs = Date.now() - startTime;
     const tokenCount =
@@ -166,7 +188,9 @@ export async function runChatTurn(input: {
     // Log all tool_use entries and notify UI
     for (const toolUse of toolUseBlocks) {
       const toolInput = JSON.stringify(toolUse.input);
-      callbacks.onToolStart(toolUse.name, toolInput);
+      if (!earlyReportedToolIds.has(toolUse.id)) {
+        callbacks.onToolStart(toolUse.id, toolUse.name, toolInput);
+      }
 
       await logInteraction(conn, threadId, {
         role: "assistant",
@@ -183,18 +207,28 @@ export async function runChatTurn(input: {
         const start = Date.now();
         const result = await executeChatToolCall(toolUse, toolCtx);
         const durationMs = Date.now() - start;
-        callbacks.onToolEnd(toolUse.name, result);
-        return { toolUse, result, durationMs };
+        const stored = maybeStoreResult(toolUse.name, result.output);
+        const meta: ToolEndMeta | undefined = stored.stored
+          ? { largeResult: stored.stored }
+          : undefined;
+        callbacks.onToolEnd(
+          toolUse.id,
+          toolUse.name,
+          result.output,
+          result.isError,
+          meta,
+        );
+        return { toolUse, result, durationMs, stored };
       }),
     );
 
     // Log results and collect tool_result messages
     const toolResults: ToolResultBlockParam[] = [];
-    for (const { toolUse, result, durationMs } of execResults) {
+    for (const { toolUse, result, durationMs, stored } of execResults) {
       await logInteraction(conn, threadId, {
         role: "tool",
         kind: "tool_result",
-        content: result,
+        content: result.output,
         toolName: toolUse.name,
         durationMs,
       });
@@ -202,7 +236,8 @@ export async function runChatTurn(input: {
       toolResults.push({
         type: "tool_result",
         tool_use_id: toolUse.id,
-        content: maybeStoreResult(toolUse.name, result),
+        content: stored.text,
+        is_error: result.isError || undefined,
       });
     }
 
@@ -214,21 +249,32 @@ export async function runChatTurn(input: {
 async function executeChatToolCall(
   toolUse: ToolUseBlock,
   ctx: ToolContext,
-): Promise<string> {
+): Promise<{ output: string; isError: boolean }> {
   const tool = getTool(toolUse.name);
-  if (!tool) return `Unknown tool: ${toolUse.name}`;
+  if (!tool) return { output: `Unknown tool: ${toolUse.name}`, isError: true };
   if (!CHAT_TOOL_NAMES.has(tool.name))
-    return `Tool not available in chat mode: ${tool.name}`;
+    return {
+      output: `Tool not available in chat mode: ${tool.name}`,
+      isError: true,
+    };
 
   const parsed = tool.inputSchema.safeParse(toolUse.input);
   if (!parsed.success) {
-    return `Invalid input: ${JSON.stringify(parsed.error)}`;
+    return {
+      output: `Invalid input: ${JSON.stringify(parsed.error)}`,
+      isError: true,
+    };
   }
 
   try {
     const result = await tool.execute(parsed.data, ctx);
-    return typeof result === "string" ? result : JSON.stringify(result);
+    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);
+    return { output, isError };
   } catch (err) {
-    return `Tool error: ${err}`;
+    return { output: `Tool error: ${err}`, isError: true };
   }
 }

package/src/chat/session.ts

@@ -14,6 +14,7 @@ import {
 } from "../db/threads.ts";
 import { createMcpxClient } from "../mcpx/client.ts";
 import type { ToolContext } from "../tools/tool.ts";
+import { generateThreadTitle } from "../utils/title.ts";
 import {
   buildChatSystemPrompt,
   type ChatTurnCallbacks,
@@ -60,21 +61,23 @@ export async function startChatSession(
     await reopenThread(conn, threadId);
 
     // Rebuild message history from interactions
+    let firstUserMessage: string | undefined;
     for (const interaction of result.interactions) {
       if (interaction.kind !== "message") continue;
       if (interaction.role === "user") {
+        if (!firstUserMessage) firstUserMessage = interaction.content;
         messages.push({ role: "user", content: interaction.content });
       } else if (interaction.role === "assistant") {
         messages.push({ role: "assistant", content: interaction.content });
       }
     }
+
+    // Backfill title for threads that still have the default
+    if (result.thread.title === "New chat" && firstUserMessage) {
+      void generateThreadTitle(config, conn, threadId, firstUserMessage);
+    }
   } else {
-    threadId = await createThread(
-      conn,
-      "chat_session",
-      undefined,
-      "Interactive chat",
-    );
+    threadId = await createThread(conn, "chat_session", undefined, "New chat");
   }
 
   const systemPrompt = await buildChatSystemPrompt(projectDir);
@@ -118,6 +121,16 @@ export async function sendMessage(
 
   session.messages.push({ role: "user", content: userMessage });
 
+  // Auto-generate title after first user message in a new thread
+  if (session.messages.length === 1) {
+    void generateThreadTitle(
+      session.config,
+      session.conn,
+      session.threadId,
+      userMessage,
+    );
+  }
+
   await runChatTurn({
     messages: session.messages,
     systemPrompt: session.systemPrompt,

package/src/cli.ts

@@ -11,6 +11,7 @@ import { registerMcpxCommand } from "./commands/mcpx.ts";
 import { registerPrepareCommand } from "./commands/prepare.ts";
 import { registerScheduleCommand } from "./commands/schedule.ts";
 import { registerTaskCommand } from "./commands/task.ts";
+import { registerThreadCommand } from "./commands/thread.ts";
 import { registerToolCommands } from "./commands/tools.ts";
 import { registerUpgradeCommand } from "./commands/upgrade.ts";
 import { maybeCheckForUpdate } from "./update/background.ts";
@@ -33,6 +34,7 @@ program
 registerInitCommand(program);
 registerDaemonCommand(program);
 registerTaskCommand(program);
+registerThreadCommand(program);
 registerScheduleCommand(program);
 registerChatCommand(program);
 registerContextCommand(program);

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/daemon/large-results.ts

@@ -71,15 +71,27 @@ export function buildResultStub(
   ].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): string {
-  if (output.length <= MAX_INLINE_CHARS) return output;
+export function maybeStoreResult(
+  toolName: string,
+  output: string,
+): MaybeStoreResultOutput {
+  if (output.length <= MAX_INLINE_CHARS) return { text: output };
 
   const id = storeLargeResult(toolName, output);
-  return buildResultStub(id, 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) */

package/src/daemon/llm.ts

@@ -49,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 }];
 
@@ -67,8 +67,8 @@ export async function runAgentLoop(input: {
     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({
@@ -148,7 +148,8 @@ export async function runAgentLoop(input: {
       toolResults.push({
         type: "tool_result",
         tool_use_id: toolUse.id,
-        content: maybeStoreResult(toolUse.name, result.output),
+        content: maybeStoreResult(toolUse.name, result.output).text,
+        is_error: result.isError || undefined,
       });
     }
 
@@ -161,6 +162,7 @@ export async function runAgentLoop(input: {
 interface ToolCallResult {
   output: string;
   terminal: boolean;
+  isError: boolean;
   agentResult?: AgentLoopResult;
 }
 
@@ -170,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)
@@ -195,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,15 +123,7 @@ export async function buildSystemPrompt(
   // Instructions
   parts.push("## Instructions");
   parts.push(
-    "You are the Botholomew daemon, personified by a wise owl. You wake up periodically to work through tasks.",
-  );
-  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.");
-  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. Only sequence tool calls when a later call depends on an earlier result.",
+    "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.",
   );
   if (options?.hasMcpTools) {
     parts.push("");

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/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?: {

package/src/init/templates.ts

@@ -42,6 +42,7 @@ export const DEFAULT_CONFIG = {
   model: "claude-opus-4-20250514",
   tick_interval_seconds: 300,
   max_tick_duration_seconds: 120,
+  max_turns: 0,
 };
 
 export const DEFAULT_MCPX_SERVERS = {

package/src/tools/context/read-large-result.ts

@@ -11,6 +11,7 @@ const outputSchema = z.object({
   content: z.string(),
   page: z.number(),
   totalPages: z.number(),
+  is_error: z.boolean(),
 });
 
 export const readLargeResultTool = {
@@ -27,6 +28,6 @@ export const readLargeResultTool = {
         `No result found for id="${input.id}" page=${input.page}. The id may be invalid or the page may be out of range.`,
       );
     }
-    return result;
+    return { ...result, is_error: false };
   },
 } satisfies ToolDefinition<typeof inputSchema, typeof outputSchema>;

package/src/tools/context/search.ts

@@ -19,6 +19,7 @@ const outputSchema = z.object({
     }),
   ),
   count: z.number(),
+  is_error: z.boolean(),
 });
 
 export const searchContextTool = {
@@ -41,6 +42,7 @@ export const searchContextTool = {
         content_preview: (item.content ?? "").slice(0, 500),
       })),
       count: items.length,
+      is_error: false,
     };
   },
 } satisfies ToolDefinition<typeof inputSchema, typeof outputSchema>;

package/src/tools/context/update-beliefs.ts

@@ -19,6 +19,7 @@ const inputSchema = z.object({
 const outputSchema = z.object({
   message: z.string(),
   path: z.string(),
+  is_error: z.boolean(),
 });
 
 export const updateBeliefsTool = {
@@ -49,6 +50,7 @@ export const updateBeliefsTool = {
     return {
       message: "Updated beliefs.md",
       path: filePath,
+      is_error: false,
     };
   },
 } satisfies ToolDefinition<typeof inputSchema, typeof outputSchema>;