botholomew 0.8.10 → 0.9.5

package/src/tools/file/copy.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { formatDriveRef } from "../../context/drives.ts";
 import {
   contextPathExists,
   copyContextItem,
@@ -7,14 +8,16 @@ import {
 import type { ToolDefinition } from "../tool.ts";
 
 const inputSchema = z.object({
-  src: z.string().describe("Source file path"),
-  dst: z.string().describe("Destination file path"),
+  src_drive: z.string().describe("Source drive"),
+  src_path: z.string().describe("Source path within the drive"),
+  dst_drive: z.string().describe("Destination drive"),
+  dst_path: z.string().describe("Destination path within the drive"),
   overwrite: z.boolean().optional().describe("Overwrite if destination exists"),
 });
 
 const outputSchema = z.object({
   id: z.string(),
-  path: z.string(),
+  ref: z.string(),
   is_error: z.boolean(),
 });
 
@@ -25,15 +28,18 @@ export const contextCopyTool = {
   inputSchema,
   outputSchema,
   execute: async (input, ctx) => {
-    const dstExists = await contextPathExists(ctx.conn, input.dst);
+    const src = { drive: input.src_drive, path: input.src_path };
+    const dst = { drive: input.dst_drive, path: input.dst_path };
+
+    const dstExists = await contextPathExists(ctx.conn, dst);
     if (dstExists && !input.overwrite) {
-      throw new Error(`Destination already exists: ${input.dst}`);
+      throw new Error(`Destination already exists: ${formatDriveRef(dst)}`);
     }
     if (dstExists) {
-      await deleteContextItemByPath(ctx.conn, input.dst);
+      await deleteContextItemByPath(ctx.conn, dst);
     }
 
-    const item = await copyContextItem(ctx.conn, input.src, input.dst);
-    return { id: item.id, path: item.context_path, is_error: false };
+    const item = await copyContextItem(ctx.conn, src, dst);
+    return { id: item.id, ref: formatDriveRef(item), is_error: false };
   },
 } satisfies ToolDefinition<typeof inputSchema, typeof outputSchema>;

package/src/tools/file/count-lines.ts

@@ -1,9 +1,11 @@
 import { z } from "zod";
+import { formatDriveRef } from "../../context/drives.ts";
 import { resolveContextItemOrThrow } from "../../db/context.ts";
 import type { ToolDefinition } from "../tool.ts";
 
 const inputSchema = z.object({
-  path: z.string().describe("File path or context item ID"),
+  drive: z.string().describe("Drive name (e.g. 'disk', 'agent')"),
+  path: z.string().describe("Path within the drive"),
 });
 
 const outputSchema = z.object({
@@ -19,8 +21,9 @@ export const contextCountLinesTool = {
   inputSchema,
   outputSchema,
   execute: async (input, ctx) => {
-    const item = await resolveContextItemOrThrow(ctx.conn, input.path);
-    if (item.content == null) throw new Error(`No text content: ${input.path}`);
+    const ref = formatDriveRef({ drive: input.drive, path: input.path });
+    const item = await resolveContextItemOrThrow(ctx.conn, ref);
+    if (item.content == null) throw new Error(`No text content: ${ref}`);
 
     return { lines: item.content.split("\n").length, is_error: false };
   },

package/src/tools/file/delete.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { formatDriveRef } from "../../context/drives.ts";
 import {
   deleteContextItemByPath,
   deleteContextItemsByPrefix,
@@ -6,7 +7,8 @@ import {
 import type { ToolDefinition } from "../tool.ts";
 
 const inputSchema = z.object({
-  path: z.string().describe("Path to delete"),
+  drive: z.string().describe("Drive name"),
+  path: z.string().describe("Path to delete within the drive"),
   recursive: z
     .boolean()
     .optional()
@@ -30,15 +32,20 @@ export const contextDeleteTool = {
   inputSchema,
   outputSchema,
   execute: async (input, ctx) => {
+    const target = { drive: input.drive, path: input.path };
     if (input.recursive) {
-      const count = await deleteContextItemsByPrefix(ctx.conn, input.path);
-      const exact = await deleteContextItemByPath(ctx.conn, input.path);
+      const count = await deleteContextItemsByPrefix(
+        ctx.conn,
+        target.drive,
+        target.path,
+      );
+      const exact = await deleteContextItemByPath(ctx.conn, target);
       return { deleted: count + (exact ? 1 : 0), is_error: false };
     }
 
-    const deleted = await deleteContextItemByPath(ctx.conn, input.path);
+    const deleted = await deleteContextItemByPath(ctx.conn, target);
     if (!deleted && !input.force) {
-      throw new Error(`Not found: ${input.path}`);
+      throw new Error(`Not found: ${formatDriveRef(target)}`);
     }
     return { deleted: deleted ? 1 : 0, is_error: false };
   },

package/src/tools/file/edit.ts

@@ -14,7 +14,8 @@ const PatchSchema = z.object({
 });
 
 const inputSchema = z.object({
-  path: z.string().describe("File path to edit"),
+  drive: z.string().describe("Drive name (e.g. 'agent', 'disk')"),
+  path: z.string().describe("Path within the drive (starts with /)"),
   patches: z.array(PatchSchema).describe("Patches to apply"),
 });
 
@@ -32,13 +33,14 @@ export const contextEditTool = {
   inputSchema,
   outputSchema,
   execute: async (input, ctx) => {
+    const target = { drive: input.drive, path: input.path };
     const { item, applied } = await applyPatchesToContextItem(
       ctx.conn,
-      input.path,
+      target,
       input.patches,
     );
 
-    await ingestByPath(ctx.conn, input.path, ctx.config);
+    await ingestByPath(ctx.conn, target, ctx.config);
     return { applied, content: item.content ?? "", is_error: false };
   },
 } satisfies ToolDefinition<typeof inputSchema, typeof outputSchema>;

package/src/tools/file/exists.ts

@@ -1,9 +1,17 @@
 import { z } from "zod";
-import { resolveContextItem } from "../../db/context.ts";
+import { parseDriveRef } from "../../context/drives.ts";
+import { getContextItem, getContextItemById } from "../../db/context.ts";
+import { isUuid } from "../../db/uuid.ts";
 import type { ToolDefinition } from "../tool.ts";
 
 const inputSchema = z.object({
-  path: z.string().describe("File path or context item ID"),
+  drive: z
+    .string()
+    .optional()
+    .describe("Drive name. Optional when `path` is a UUID or 'drive:/path'."),
+  path: z
+    .string()
+    .describe("Path within the drive (or UUID / drive:/path ref)"),
 });
 
 const outputSchema = z.object({
@@ -19,7 +27,21 @@ export const contextExistsTool = {
   inputSchema,
   outputSchema,
   execute: async (input, ctx) => {
-    const item = await resolveContextItem(ctx.conn, input.path);
+    if (isUuid(input.path)) {
+      const item = await getContextItemById(ctx.conn, input.path);
+      return { exists: item !== null, is_error: false };
+    }
+    const parsed = parseDriveRef(input.path);
+    if (parsed) {
+      const item = await getContextItem(ctx.conn, parsed);
+      return { exists: item !== null, is_error: false };
+    }
+    if (!input.drive) return { exists: false, is_error: false };
+    const path = input.path.startsWith("/") ? input.path : `/${input.path}`;
+    const item = await getContextItem(ctx.conn, {
+      drive: input.drive,
+      path,
+    });
     return { exists: item !== null, is_error: false };
   },
 } satisfies ToolDefinition<typeof inputSchema, typeof outputSchema>;

package/src/tools/file/info.ts

@@ -1,12 +1,28 @@
 import { z } from "zod";
-import { resolveContextItemOrThrow } from "../../db/context.ts";
+import { formatDriveRef, parseDriveRef } from "../../context/drives.ts";
+import {
+  findNearbyContextPaths,
+  getContextItem,
+  getContextItemById,
+} from "../../db/context.ts";
+import { isUuid } from "../../db/uuid.ts";
 import type { ToolDefinition } from "../tool.ts";
 
 const inputSchema = z.object({
-  path: z.string().describe("File path or context item ID"),
+  drive: z
+    .string()
+    .optional()
+    .describe(
+      "Drive name (e.g. 'disk', 'url', 'agent'). Optional when `path` is a UUID or already in `drive:/...` form.",
+    ),
+  path: z
+    .string()
+    .describe(
+      "Path within the drive (starts with /), or a bare UUID / 'drive:/path' ref.",
+    ),
 });
 
-const outputSchema = z.object({
+const fileSchema = z.object({
   id: z.string(),
   title: z.string(),
   description: z.string(),
@@ -14,12 +30,20 @@ const outputSchema = z.object({
   is_textual: z.boolean(),
   size: z.number(),
   lines: z.number(),
-  source_path: z.string().nullable(),
-  context_path: z.string(),
+  drive: z.string(),
+  path: z.string(),
+  ref: z.string(),
   indexed_at: z.string().nullable(),
   created_at: z.string(),
   updated_at: z.string(),
+});
+
+const outputSchema = z.object({
+  file: fileSchema.optional(),
   is_error: z.boolean(),
+  error_type: z.string().optional(),
+  message: z.string().optional(),
+  next_action_hint: z.string().optional(),
 });
 
 export const contextInfoTool = {
@@ -30,22 +54,70 @@ export const contextInfoTool = {
   inputSchema,
   outputSchema,
   execute: async (input, ctx) => {
-    const item = await resolveContextItemOrThrow(ctx.conn, input.path);
+    let drive = input.drive;
+    let path = input.path;
+    if (isUuid(input.path)) {
+      const byId = await getContextItemById(ctx.conn, input.path);
+      if (byId) {
+        drive = byId.drive;
+        path = byId.path;
+      }
+    } else {
+      const parsed = parseDriveRef(input.path);
+      if (parsed) {
+        drive = parsed.drive;
+        path = parsed.path;
+      }
+    }
+
+    if (!drive) {
+      return {
+        is_error: true,
+        error_type: "missing_drive",
+        message: `Cannot resolve context item: no drive provided and \`${input.path}\` is not a UUID or \`drive:/path\` ref.`,
+        next_action_hint:
+          "Pass `drive` explicitly, or use a `drive:/path` ref. Call context_list_drives to see which drives exist.",
+      };
+    }
+
+    if (!path.startsWith("/")) path = `/${path}`;
+
+    const item = await getContextItem(ctx.conn, { drive, path });
+    if (!item) {
+      const { parent, siblings, walkedUp } = await findNearbyContextPaths(
+        ctx.conn,
+        drive,
+        path,
+      );
+      const hint =
+        siblings.length > 0
+          ? `${walkedUp ? `Parent ${parent} has no direct entries; ` : ""}Nearby items under ${parent}: ${siblings.join(", ")}. Call context_tree({drive:"${drive}",path:"${parent.replace(/^[^:]*:/, "")}"}) to see more.`
+          : `No items found under ${parent}. Call context_list_drives to see which drives exist.`;
+      return {
+        is_error: true,
+        error_type: "not_found",
+        message: `No context item at ${formatDriveRef({ drive, path })}`,
+        next_action_hint: hint,
+      };
+    }
 
     const content = item.content ?? "";
     return {
-      id: item.id,
-      title: item.title,
-      description: item.description,
-      mime_type: item.mime_type,
-      is_textual: item.is_textual,
-      size: content.length,
-      lines: content ? content.split("\n").length : 0,
-      source_path: item.source_path,
-      context_path: item.context_path,
-      indexed_at: item.indexed_at?.toISOString() ?? null,
-      created_at: item.created_at.toISOString(),
-      updated_at: item.updated_at.toISOString(),
+      file: {
+        id: item.id,
+        title: item.title,
+        description: item.description,
+        mime_type: item.mime_type,
+        is_textual: item.is_textual,
+        size: content.length,
+        lines: content ? content.split("\n").length : 0,
+        drive: item.drive,
+        path: item.path,
+        ref: formatDriveRef(item),
+        indexed_at: item.indexed_at?.toISOString() ?? null,
+        created_at: item.created_at.toISOString(),
+        updated_at: item.updated_at.toISOString(),
+      },
       is_error: false,
     };
   },

package/src/tools/file/move.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { formatDriveRef } from "../../context/drives.ts";
 import {
   contextPathExists,
   deleteContextItemByPath,
@@ -7,41 +8,39 @@ import {
 import type { ToolDefinition } from "../tool.ts";
 
 const inputSchema = z.object({
-  src: z.string().describe("Source file path"),
-  dst: z.string().describe("Destination file path"),
+  src_drive: z.string().describe("Source drive"),
+  src_path: z.string().describe("Source path within the drive"),
+  dst_drive: z.string().describe("Destination drive"),
+  dst_path: z.string().describe("Destination path within the drive"),
   overwrite: z.boolean().optional().describe("Overwrite if destination exists"),
 });
 
 const outputSchema = z.object({
-  path: z.string(),
+  ref: z.string(),
   is_error: z.boolean(),
 });
 
 export const contextMoveTool = {
   name: "context_move",
   description:
-    "[[ bash equivalent command: mv ]] Move or rename a context item.",
+    "[[ bash equivalent command: mv ]] Move or rename a context item (can also relocate between drives).",
   group: "context",
   inputSchema,
   outputSchema,
   execute: async (input, ctx) => {
-    const dstExists = await contextPathExists(ctx.conn, input.dst);
+    const src = { drive: input.src_drive, path: input.src_path };
+    const dst = { drive: input.dst_drive, path: input.dst_path };
+
+    const dstExists = await contextPathExists(ctx.conn, dst);
     if (dstExists && !input.overwrite) {
-      throw new Error(`Destination already exists: ${input.dst}`);
+      throw new Error(`Destination already exists: ${formatDriveRef(dst)}`);
     }
     if (dstExists) {
-      await deleteContextItemByPath(ctx.conn, input.dst);
+      await deleteContextItemByPath(ctx.conn, dst);
     }
 
-    await moveContextItem(ctx.conn, input.src, input.dst);
-
-    // Update embedding source_paths to match new location
-    await ctx.conn.queryRun(
-      "UPDATE embeddings SET source_path = ?1 WHERE source_path = ?2",
-      input.dst,
-      input.src,
-    );
+    await moveContextItem(ctx.conn, src, dst);
 
-    return { path: input.dst, is_error: false };
+    return { ref: formatDriveRef(dst), is_error: false };
   },
 } satisfies ToolDefinition<typeof inputSchema, typeof outputSchema>;

package/src/tools/file/read.ts

@@ -1,9 +1,25 @@
 import { z } from "zod";
-import { resolveContextItemOrThrow } from "../../db/context.ts";
+import { formatDriveRef, parseDriveRef } from "../../context/drives.ts";
+import {
+  findNearbyContextPaths,
+  getContextItem,
+  getContextItemById,
+} from "../../db/context.ts";
+import { isUuid } from "../../db/uuid.ts";
 import type { ToolDefinition } from "../tool.ts";
 
 const inputSchema = z.object({
-  path: z.string().describe("File path or context item ID"),
+  drive: z
+    .string()
+    .optional()
+    .describe(
+      "Drive name (e.g. 'disk', 'url', 'agent', 'google-docs', 'github'). Use context_list_drives to see what's available. Optional when `path` is a UUID or already in `drive:/...` form.",
+    ),
+  path: z
+    .string()
+    .describe(
+      "Path within the drive (starts with /), or a bare UUID / 'drive:/path' ref (in which case `drive` is ignored).",
+    ),
   offset: z
     .number()
     .optional()
@@ -12,8 +28,11 @@ const inputSchema = z.object({
 });
 
 const outputSchema = z.object({
-  content: z.string(),
+  content: z.string().optional(),
   is_error: z.boolean(),
+  error_type: z.string().optional(),
+  message: z.string().optional(),
+  next_action_hint: z.string().optional(),
 });
 
 export const contextReadTool = {
@@ -24,8 +43,63 @@ export const contextReadTool = {
   inputSchema,
   outputSchema,
   execute: async (input, ctx) => {
-    const item = await resolveContextItemOrThrow(ctx.conn, input.path);
-    if (item.content == null) throw new Error(`No text content: ${input.path}`);
+    // Accept either (drive, path) or a bare UUID / drive:/path ref in `path`.
+    let drive = input.drive;
+    let path = input.path;
+    if (isUuid(input.path)) {
+      const byId = await getContextItemById(ctx.conn, input.path);
+      if (byId) {
+        drive = byId.drive;
+        path = byId.path;
+      }
+    } else {
+      const parsed = parseDriveRef(input.path);
+      if (parsed) {
+        drive = parsed.drive;
+        path = parsed.path;
+      }
+    }
+
+    if (!drive) {
+      return {
+        is_error: true,
+        error_type: "missing_drive",
+        message: `Cannot resolve context item: no drive provided and \`${input.path}\` is not a UUID or \`drive:/path\` ref.`,
+        next_action_hint:
+          "Pass `drive` explicitly, or use a `drive:/path` ref. Call context_list_drives to see which drives exist.",
+      };
+    }
+
+    if (!path.startsWith("/")) path = `/${path}`;
+
+    const item = await getContextItem(ctx.conn, { drive, path });
+    if (!item) {
+      const { parent, siblings, walkedUp } = await findNearbyContextPaths(
+        ctx.conn,
+        drive,
+        path,
+      );
+      const hint =
+        siblings.length > 0
+          ? `${walkedUp ? `Parent ${parent} has no direct entries; ` : ""}Nearby items under ${parent}: ${siblings.join(", ")}. Call context_tree({drive:"${drive}",path:"${parent.replace(/^[^:]*:/, "")}"}) to see more.`
+          : `No items found under ${parent}. Call context_list_drives to see which drives exist.`;
+      return {
+        is_error: true,
+        error_type: "not_found",
+        message: `No context item at ${formatDriveRef({ drive, path })}`,
+        next_action_hint: hint,
+      };
+    }
+
+    if (item.content == null) {
+      return {
+        is_error: true,
+        error_type: "no_text_content",
+        message: `Context item ${formatDriveRef(item)} has no text content (mime: ${item.mime_type})`,
+        next_action_hint:
+          "Binary items can't be read as text. Call context_info to inspect metadata, or pick a textual sibling.",
+      };
+    }
 
     let content = item.content;
 

package/src/tools/file/write.ts

@@ -1,5 +1,6 @@
 import { isText } from "istextorbinary";
 import { z } from "zod";
+import { formatDriveRef } from "../../context/drives.ts";
 import { ingestByPath } from "../../context/ingest.ts";
 import {
   createContextItemStrict,
@@ -17,12 +18,17 @@ function mimeFromPath(path: string): string {
 function isTextualPath(path: string): boolean {
   const filename = path.split("/").pop() ?? path;
   const result = isText(filename);
-  // isText returns null if it can't determine from filename alone — default to true
   return result !== false;
 }
 
 const inputSchema = z.object({
-  path: z.string().describe("File path to write"),
+  drive: z
+    .string()
+    .default("agent")
+    .describe(
+      "Drive to write to (defaults to 'agent', which is the agent's scratch drive). Only 'agent' and drives mirroring an external system you can write back to make sense here.",
+    ),
+  path: z.string().describe("Path within the drive (starts with /)"),
   content: z.string().describe("Text content to write"),
   content_base64: z
     .string()
@@ -39,13 +45,15 @@ const inputSchema = z.object({
     .enum(["error", "overwrite"])
     .optional()
     .describe(
-      "What to do if a file already exists at this path. Defaults to 'error'. Pass 'overwrite' to replace.",
+      "What to do if a file already exists at this (drive, path). Defaults to 'error'. Pass 'overwrite' to replace.",
     ),
 });
 
 const outputSchema = z.object({
   id: z.string().nullable(),
+  drive: z.string(),
   path: z.string(),
+  ref: z.string(),
   is_error: z.boolean(),
   error_type: z.string().optional(),
   message: z.string().optional(),
@@ -54,14 +62,14 @@ const outputSchema = z.object({
     .string()
     .optional()
     .describe(
-      "Snapshot of the context filesystem after the write so you can see the surrounding files.",
+      "Snapshot of the drive's tree after the write so you can see the surrounding files.",
     ),
 });
 
 export const contextWriteTool = {
   name: "context_write",
   description:
-    "[[ bash equivalent command: tee ]] Write content to a context item. By default, fails if the path already exists — pass on_conflict='overwrite' to replace.",
+    "[[ bash equivalent command: tee ]] Write content to a context item. By default writes to drive='agent' (the agent's scratch drive). Fails if the (drive, path) already exists — pass on_conflict='overwrite' to replace.",
   group: "context",
   inputSchema,
   outputSchema,
@@ -71,6 +79,7 @@ export const contextWriteTool = {
     const title =
       input.title ?? input.path.split("/").filter(Boolean).pop() ?? input.path;
     const onConflict = input.on_conflict ?? "error";
+    const target = { drive: input.drive, path: input.path };
 
     try {
       const item =
@@ -79,7 +88,8 @@ export const contextWriteTool = {
               title,
               description: input.description,
               content: input.content_base64 ?? input.content,
-              contextPath: input.path,
+              drive: target.drive,
+              path: target.path,
               mimeType,
               isTextual,
             })
@@ -87,16 +97,21 @@ export const contextWriteTool = {
               title,
               description: input.description,
               content: input.content_base64 ?? input.content,
-              contextPath: input.path,
+              drive: target.drive,
+              path: target.path,
               mimeType,
               isTextual,
             });
 
-      await ingestByPath(ctx.conn, input.path, ctx.config);
-      const { tree } = await buildContextTree(ctx.conn);
+      await ingestByPath(ctx.conn, target, ctx.config);
+      const { tree } = await buildContextTree(ctx.conn, {
+        drive: target.drive,
+      });
       return {
         id: item.id,
-        path: item.context_path,
+        drive: item.drive,
+        path: item.path,
+        ref: formatDriveRef(item),
         is_error: false,
         tree,
       };
@@ -104,10 +119,12 @@ export const contextWriteTool = {
       if (err instanceof PathConflictError) {
         return {
           id: null,
-          path: input.path,
+          drive: err.drive,
+          path: err.path,
+          ref: formatDriveRef({ drive: err.drive, path: err.path }),
           is_error: true,
           error_type: "path_conflict",
-          message: `A file already exists at ${input.path} (id: ${err.existingId}).`,
+          message: `A file already exists at ${formatDriveRef({ drive: err.drive, path: err.path })} (id: ${err.existingId}).`,
           next_action_hint:
             "Call context_read to inspect the existing file, or retry with on_conflict='overwrite' to replace it.",
         };

package/src/tools/registry.ts

@@ -1,6 +1,7 @@
 // Capabilities tools
 import { capabilitiesRefreshTool } from "./capabilities/refresh.ts";
 // Context tools
+import { contextListDrivesTool } from "./context/list-drives.ts";
 import { readLargeResultTool } from "./context/read-large-result.ts";
 import { contextRefreshTool } from "./context/refresh.ts";
 import { contextSearchTool } from "./context/search.ts";
@@ -8,7 +9,6 @@ import { updateBeliefsTool } from "./context/update-beliefs.ts";
 import { updateGoalsTool } from "./context/update-goals.ts";
 // Context — directory operations
 import { contextCreateDirTool } from "./dir/create.ts";
-import { contextListDirTool } from "./dir/list.ts";
 import { contextDirSizeTool } from "./dir/size.ts";
 import { contextTreeTool } from "./dir/tree.ts";
 // Context — file operations
@@ -58,8 +58,8 @@ export function registerAllTools(): void {
   registerTool(viewTaskTool);
 
   // Context
+  registerTool(contextListDrivesTool);
   registerTool(contextCreateDirTool);
-  registerTool(contextListDirTool);
   registerTool(contextTreeTool);
   registerTool(contextDirSizeTool);
   registerTool(contextReadTool);