botholomew 0.18.4 → 0.18.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "botholomew",
-  "version": "0.18.4",
+  "version": "0.18.5",
   "description": "An autonomous AI agent for knowledge work — works your task queue while you sleep.",
   "type": "module",
   "bin": {

package/src/tools/registry.ts

@@ -40,6 +40,7 @@ import { searchThreadsTool } from "./thread/search.ts";
 import { viewThreadTool } from "./thread/view.ts";
 import { registerTool } from "./tool.ts";
 // Util tools
+import { readLargeResultTool } from "./util/read_large_result.ts";
 import { sleepTool } from "./util/sleep.ts";
 // Worker tools
 import { spawnWorkerTool } from "./worker/spawn.ts";
@@ -95,6 +96,7 @@ export function registerAllTools(): void {
 
   // Util
   registerTool(sleepTool);
+  registerTool(readLargeResultTool);
 
   // Worker
   registerTool(spawnWorkerTool);

package/src/tools/util/read_large_result.ts

@@ -0,0 +1,84 @@
+import { z } from "zod";
+import {
+  PAGE_SIZE_CHARS,
+  peekLargeResult,
+  readLargeResultPage,
+} from "../../worker/large-results.ts";
+import type { ToolDefinition } from "../tool.ts";
+
+const ID_PATTERN = /^lr_\d+$/;
+
+const inputSchema = z.object({
+  id: z
+    .string()
+    .regex(ID_PATTERN)
+    .describe(
+      'Large-result id from the "Paginated for LLM" stub, e.g. "lr_1".',
+    ),
+  page: z
+    .number()
+    .int()
+    .min(1)
+    .default(1)
+    .describe(
+      `1-based page number. Each page is ~${PAGE_SIZE_CHARS} chars. Start at 1; the response includes total_pages so you know when to stop.`,
+    ),
+});
+
+const outputSchema = z.object({
+  content: z.string(),
+  id: z.string(),
+  page: z.number(),
+  total_pages: z.number(),
+  total_chars: z.number(),
+  is_error: z.boolean(),
+  error_type: z.string().optional(),
+  next_action_hint: z.string().optional(),
+});
+
+export const readLargeResultTool = {
+  name: "read_large_result",
+  description: `[[ bash equivalent command: sed -n '<page>p' ]] Read one page of a large tool result that was cached because its inline payload exceeded the response budget. Use the id from the "Paginated for LLM" stub. Pages are 1-based and ~${PAGE_SIZE_CHARS} chars each; loop from page=1 to total_pages.`,
+  group: "util",
+  inputSchema,
+  outputSchema,
+  execute: async (input, _ctx): Promise<z.infer<typeof outputSchema>> => {
+    const meta = peekLargeResult(input.id);
+    if (!meta) {
+      return {
+        content: "",
+        id: input.id,
+        page: input.page,
+        total_pages: 0,
+        total_chars: 0,
+        is_error: true,
+        error_type: "unknown_id",
+        next_action_hint:
+          "Large-result entries live only for the current worker tick or chat session and are cleared between worker tasks. Re-run the originating tool to regenerate the result.",
+      };
+    }
+
+    const result = readLargeResultPage(input.id, input.page);
+    if (!result) {
+      return {
+        content: "",
+        id: input.id,
+        page: input.page,
+        total_pages: meta.totalPages,
+        total_chars: meta.totalChars,
+        is_error: true,
+        error_type: "page_out_of_range",
+        next_action_hint: `page=${input.page} is past the end. Valid pages are 1–${meta.totalPages}.`,
+      };
+    }
+
+    return {
+      content: result.content,
+      id: input.id,
+      page: result.page,
+      total_pages: result.totalPages,
+      total_chars: meta.totalChars,
+      is_error: false,
+    };
+  },
+} satisfies ToolDefinition<typeof inputSchema, typeof outputSchema>;

package/src/worker/large-results.ts

@@ -52,6 +52,19 @@ export function readLargeResultPage(
   return { content, page, totalPages: entry.totalPages };
 }
 
+/** Inspect a stored result without consuming a page. Returns null if unknown. */
+export function peekLargeResult(
+  id: string,
+): { toolName: string; totalChars: number; totalPages: number } | null {
+  const entry = store.get(id);
+  if (!entry) return null;
+  return {
+    toolName: entry.toolName,
+    totalChars: entry.totalChars,
+    totalPages: entry.totalPages,
+  };
+}
+
 /** Build the inline stub that replaces the full result in the conversation */
 export function buildResultStub(
   id: string,
@@ -67,7 +80,7 @@ export function buildResultStub(
     preview,
     preview.length < content.length ? "..." : "",
     "",
-    `Use read_large_result with id="${id}" to read page-by-page (pages 1–${totalPages}).`,
+    `Use read_large_result with id="${id}" and page=<n> (1–${totalPages}) to read it in ~${PAGE_SIZE_CHARS}-char pages.`,
   ].join("\n");
 }