botholomew 0.13.0 → 0.14.2

package/src/tools/tool.ts

@@ -17,6 +17,11 @@ export interface ToolContext {
   projectDir: string;
   config: Required<BotholomewConfig>;
   mcpxClient: McpxClient | null;
+  /**
+   * Chat-mode only. Lets long-running tools (e.g. `sleep`) poll for
+   * Esc-to-abort by reading `session.aborted`. Workers leave this `undefined`.
+   */
+  shouldAbort?: () => boolean;
 }
 
 type ToolOutputBase = { is_error: z.ZodBoolean };

package/src/tools/util/sleep.ts

@@ -0,0 +1,77 @@
+import { z } from "zod";
+import type { ToolDefinition } from "../tool.ts";
+
+const MIN_SECONDS = 1;
+const MAX_SECONDS = 3600;
+const POLL_INTERVAL_MS = 250;
+
+const inputSchema = z.object({
+  seconds: z
+    .number()
+    .int()
+    .min(MIN_SECONDS)
+    .max(MAX_SECONDS)
+    .describe(
+      `How long to sleep, in seconds (${MIN_SECONDS}–${MAX_SECONDS}). For longer pauses, create a schedule instead.`,
+    ),
+  reason: z
+    .string()
+    .min(1)
+    .describe(
+      "Why you're sleeping — shown to the user under the progress bar. Be specific (e.g. 'waiting for worker to finish task abc').",
+    ),
+});
+
+const outputSchema = z.object({
+  message: z.string(),
+  slept_seconds: z.number(),
+  aborted: z.boolean(),
+  is_error: z.boolean(),
+});
+
+export const sleepTool = {
+  name: "sleep",
+  description:
+    "[[ bash equivalent command: sleep ]] Pause the chat agent for a fixed number of seconds. Useful after enqueuing tasks for workers, before checking results. The user sees a progress bar while you wait; pressing Esc cancels the wait. Returns when the time elapses or the user steers.",
+  group: "util",
+  inputSchema,
+  outputSchema,
+  execute: async (input, ctx): Promise<z.infer<typeof outputSchema>> => {
+    const startedAt = Date.now();
+    const totalMs = input.seconds * 1000;
+    const shouldAbort = ctx.shouldAbort;
+
+    let aborted: boolean = false;
+    await new Promise<void>((resolve) => {
+      let timeout: ReturnType<typeof setTimeout> | null = null;
+      let interval: ReturnType<typeof setInterval> | null = null;
+
+      const finish = () => {
+        if (timeout) clearTimeout(timeout);
+        if (interval) clearInterval(interval);
+        resolve();
+      };
+
+      timeout = setTimeout(finish, totalMs);
+
+      if (shouldAbort) {
+        interval = setInterval(() => {
+          if (shouldAbort()) {
+            aborted = true;
+            finish();
+          }
+        }, POLL_INTERVAL_MS);
+      }
+    });
+
+    const sleptSeconds = (Date.now() - startedAt) / 1000;
+    return {
+      message: aborted
+        ? `Sleep interrupted after ${sleptSeconds.toFixed(1)}s of ${input.seconds}s — user steered.`
+        : `Slept ${sleptSeconds.toFixed(1)}s. ${input.reason}`,
+      slept_seconds: sleptSeconds,
+      aborted,
+      is_error: false,
+    };
+  },
+} satisfies ToolDefinition<typeof inputSchema, typeof outputSchema>;

package/src/tui/components/SleepProgress.tsx

@@ -0,0 +1,70 @@
+import { Box, Text } from "ink";
+import { useEffect, useState } from "react";
+import { theme } from "../theme.ts";
+
+interface SleepProgressProps {
+  startedAt: Date;
+  totalSeconds: number;
+  reason?: string;
+}
+
+const BAR_WIDTH = 24;
+const TICK_MS = 200;
+
+export function SleepProgress({
+  startedAt,
+  totalSeconds,
+  reason,
+}: SleepProgressProps) {
+  const [now, setNow] = useState(() => Date.now());
+
+  useEffect(() => {
+    const id = setInterval(() => setNow(Date.now()), TICK_MS);
+    return () => clearInterval(id);
+  }, []);
+
+  const totalMs = totalSeconds * 1000;
+  const elapsedMs = Math.min(totalMs, Math.max(0, now - startedAt.getTime()));
+  const ratio = totalMs > 0 ? elapsedMs / totalMs : 1;
+  const filled = Math.round(ratio * BAR_WIDTH);
+  const bar = "█".repeat(filled) + "░".repeat(BAR_WIDTH - filled);
+  const elapsedSec = (elapsedMs / 1000).toFixed(1);
+
+  return (
+    <Box flexDirection="column">
+      <Box>
+        <Text dimColor>{"    "}</Text>
+        <Text color={theme.accent}>{bar}</Text>
+        <Text dimColor>
+          {" "}
+          {elapsedSec}s / {totalSeconds}s
+        </Text>
+      </Box>
+      {reason && (
+        <Text dimColor wrap="truncate-end">
+          {"    "}
+          {reason}
+        </Text>
+      )}
+    </Box>
+  );
+}
+
+/**
+ * Pull `seconds` and `reason` out of a sleep tool's stringified JSON input.
+ * Returns `null` if the input can't be parsed or doesn't have a numeric duration.
+ */
+export function parseSleepInput(
+  raw: string,
+): { seconds: number; reason?: string } | null {
+  try {
+    const parsed = JSON.parse(raw);
+    if (typeof parsed?.seconds !== "number") return null;
+    return {
+      seconds: parsed.seconds,
+      reason: typeof parsed.reason === "string" ? parsed.reason : undefined,
+    };
+  } catch {
+    return null;
+  }
+}

package/src/tui/components/ToolCall.tsx

@@ -1,5 +1,6 @@
 import { Box, Text } from "ink";
 import { theme } from "../theme.ts";
+import { parseSleepInput, SleepProgress } from "./SleepProgress.tsx";
 
 /**
  * For mcp_exec calls, extract server/tool into a top-level display name
@@ -53,6 +54,8 @@ export function ToolCall({ tool }: ToolCallProps) {
   const truncatedInput =
     displayInput.length > 60 ? `${displayInput.slice(0, 60)}…` : displayInput;
   const truncatedOutput = tool.output ? tool.output.slice(0, 120) : "";
+  const sleepArgs =
+    tool.name === "sleep" && tool.running ? parseSleepInput(tool.input) : null;
 
   return (
     <Box flexDirection="column">
@@ -83,6 +86,13 @@ export function ToolCall({ tool }: ToolCallProps) {
         {tool.name === "mcp_exec" && <Text dimColor> (exec)</Text>}
         <Text dimColor> ({truncatedInput})</Text>
       </Box>
+      {sleepArgs && (
+        <SleepProgress
+          startedAt={tool.timestamp}
+          totalSeconds={sleepArgs.seconds}
+          reason={sleepArgs.reason}
+        />
+      )}
       {truncatedOutput && !tool.running && (
         <Text dimColor wrap="truncate-end">
           {"    → "}

package/src/utils/frontmatter.ts

@@ -1,8 +1,16 @@
 import matter from "gray-matter";
 
 export interface ContextFileMeta {
-  loading: "always" | "contextual";
-  "agent-modification": boolean;
+  loading?: "always" | "contextual";
+  "agent-modification"?: boolean;
+  // Set by `bothy context import <url>` so the saved file remembers
+  // where it came from. Optional so files written by other paths
+  // (prompts/, beliefs/, agent-authored notes) aren't required to
+  // carry import metadata.
+  source_url?: string;
+  imported_at?: string;
+  title?: string;
+  [key: string]: unknown;
 }
 
 export function parseContextFile(raw: string): {