tinker-agent 1.3.0 → 1.4.0

package/src/tools/ripgrep.ts

@@ -1,13 +1,10 @@
 import { execFile } from "node:child_process";
-import { rgPath } from "@vscode/ripgrep";
 import { cancellationError, throwIfTurnCancelled } from "../agent/turn-cancellation";
+import { DEFAULT_PUBLIC_TOOLING_CONFIG } from "../cli/public-config-contract";
 
 export const RIPGREP_MISSING_ERROR =
   "Tinker's bundled ripgrep executable is unavailable. Reinstall tinker-agent.";
 
-const defaultTimeoutMs = 20_000;
-const defaultMaxBufferBytes = 20_000_000;
-
 export type RipgrepResult = {
   ok: boolean;
   lines: string[];
@@ -18,12 +15,13 @@ export type RipgrepResult = {
 
 export type RipgrepOptions = {
   signal: AbortSignal;
+  command?: string;
   timeoutMs?: number;
   maxBufferBytes?: number;
 };
 
-export function findRipgrepCommand(): string {
-  return process.env.TINKER_RIPGREP_PATH ?? rgPath;
+export function findRipgrepCommand(command?: string): string {
+  return command ?? DEFAULT_PUBLIC_TOOLING_CONFIG.ripgrepPath;
 }
 
 export async function ripGrep(
@@ -31,21 +29,28 @@ export async function ripGrep(
   options: RipgrepOptions,
 ): Promise<RipgrepResult> {
   throwIfTurnCancelled(options.signal);
-  const timeoutMs =
-    options.timeoutMs ??
-    parsePositiveInteger(process.env.TINKER_GREP_TIMEOUT_MS, defaultTimeoutMs);
+  const timeoutMs = options.timeoutMs ?? DEFAULT_PUBLIC_TOOLING_CONFIG.grepTimeoutMs;
   const maxBufferBytes =
-    options.maxBufferBytes ??
-    parsePositiveInteger(
-      process.env.TINKER_GREP_MAX_BUFFER_BYTES,
-      defaultMaxBufferBytes,
-    );
-
-  const first = await runRipgrep(args, timeoutMs, maxBufferBytes, options.signal);
+    options.maxBufferBytes ?? DEFAULT_PUBLIC_TOOLING_CONFIG.grepMaxBufferBytes;
+  const command = findRipgrepCommand(options.command);
+
+  const first = await runRipgrep(
+    command,
+    args,
+    timeoutMs,
+    maxBufferBytes,
+    options.signal,
+  );
   if (first.retryWithSingleThread) {
     throwIfTurnCancelled(options.signal);
     return finalizeResult(
-      await runRipgrep(["-j", "1", ...args], timeoutMs, maxBufferBytes, options.signal),
+      await runRipgrep(
+        command,
+        ["-j", "1", ...args],
+        timeoutMs,
+        maxBufferBytes,
+        options.signal,
+      ),
     );
   }
 
@@ -62,6 +67,7 @@ type RipgrepAttempt = {
 };
 
 function runRipgrep(
+  command: string,
   args: string[],
   timeoutMs: number,
   maxBufferBytes: number,
@@ -74,7 +80,7 @@ function runRipgrep(
     }
 
     execFile(
-      findRipgrepCommand(),
+      command,
       args,
       { timeout: timeoutMs, maxBuffer: maxBufferBytes, signal },
       (error, stdout, stderr) => {
@@ -210,12 +216,3 @@ function isEagainError(
     stderr.includes("Resource temporarily unavailable")
   );
 }
-
-function parsePositiveInteger(value: string | undefined, fallback: number): number {
-  if (value === undefined || value.trim() === "") {
-    return fallback;
-  }
-
-  const parsed = Number(value);
-  return Number.isInteger(parsed) && parsed > 0 ? parsed : fallback;
-}

package/src/tools/web-fetch/index.ts

@@ -1,4 +1,5 @@
 import { cancellationError, throwIfTurnCancelled } from "../../agent/turn-cancellation";
+import { DEFAULT_PUBLIC_TOOLING_CONFIG } from "../../cli/public-config-contract";
 import { defineToolExecutor } from "../types";
 import type { ToolExecutionContext, ToolExecutor, WebFetchRawResult } from "../types";
 import type { WebFetchBackend, WebFetchBackendResult, WebFetchRoute } from "./backend";
@@ -25,7 +26,6 @@ export type WebFetchToolOptions = {
   browserBackend?: WebFetchBackend | false;
 };
 
-export const WEB_FETCH_DEFAULT_REFINE_THRESHOLD = 2000;
 export const WEB_FETCH_DEFAULT_CACHE_TTL_MS = 15 * 60 * 1000;
 
 type CacheEntry = {
@@ -50,11 +50,7 @@ export function createWebFetchToolExecutor(
       : (options.browserBackend ??
         (isBrowserBackendAvailable() ? createBrowserWebFetchBackend() : undefined));
   const refineThreshold =
-    options.refineThreshold ??
-    parsePositiveInteger(
-      process.env.TINKER_WEBFETCH_REFINE_THRESHOLD,
-      WEB_FETCH_DEFAULT_REFINE_THRESHOLD,
-    );
+    options.refineThreshold ?? DEFAULT_PUBLIC_TOOLING_CONFIG.webFetchRefineThreshold;
   const cacheTtlMs = options.cacheTtlMs ?? WEB_FETCH_DEFAULT_CACHE_TTL_MS;
   const cache = new Map<string, CacheEntry>();
 
@@ -284,15 +280,6 @@ function pruneCache(cache: Map<string, CacheEntry>): void {
   }
 }
 
-function parsePositiveInteger(value: string | undefined, fallback: number): number {
-  if (value === undefined || value.trim() === "") {
-    return fallback;
-  }
-
-  const parsed = Number(value);
-  return Number.isInteger(parsed) && parsed > 0 ? parsed : fallback;
-}
-
 function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }

package/src/tui/app.tsx

@@ -42,12 +42,14 @@ import type { SessionSummary } from "../session/session-catalog";
 import type { ModelProfile, ModelProfiles } from "../cli/model-profiles";
 import { loadViewFile, type ViewFile } from "./view-file";
 import { writeClipboardText } from "./clipboard";
+import type { WorkspaceFileLister } from "./workspace-file-search";
 
 export type AppProps = {
   sessionController: TuiSessionController;
   readGitBranch?: (workspaceRoot: string) => Promise<string | undefined>;
   history?: PromptHistory;
   projectSlashCommands?: readonly ProjectSlashCommand[];
+  fileLister?: WorkspaceFileLister;
   profiles?: ModelProfiles;
   persistDefaultProfile?: (profileName: string) => Promise<void>;
   readViewFile?: (workspaceRoot: string, filePath: string) => Promise<ViewFile>;
@@ -647,6 +649,7 @@ export function App(props: AppProps) {
                 isDisabled={isRunning || isSessionOperation || isCopying}
                 history={props.history}
                 commands={availableCommands}
+                fileLister={props.fileLister}
                 importImage={binding.importImage}
                 verifyImageAssets={binding.verifyImageAssets}
                 onSubmit={onSubmit}

package/src/tui/components/prompt-input.tsx

@@ -222,7 +222,8 @@ export function PromptInput(props: PromptInputProps) {
     if (mention === undefined || locked) {
       return;
     }
-    if (props.importImage === undefined) {
+    const importImage = props.importImage;
+    if (importImage === undefined) {
       insertFilePath(filePath);
       return;
     }
@@ -236,8 +237,10 @@ export function PromptInput(props: PromptInputProps) {
       phase: { kind: "attaching", operationId },
       error: undefined,
     }));
-    void props
-      .importImage(filePath, controller.signal, captured.attachments.length + 1)
+    void Promise.resolve()
+      .then(() =>
+        importImage(filePath, controller.signal, captured.attachments.length + 1),
+      )
       .then((imported) => {
         setState((current) => {
           if (

package/src/tui/slash-commands.ts

@@ -1,24 +1,66 @@
 export type SlashCommand = {
-  name: string;
-  description: string;
+  readonly name: string;
+  readonly description: string;
+  readonly usage?: string;
 };
 
-export const SLASH_COMMANDS: readonly SlashCommand[] = [
-  { name: "status", description: "Show session and context details" },
-  { name: "skills", description: "Show available and active Agent Skills" },
-  { name: "mcp", description: "Show MCP servers and runtime tools" },
+export type BuiltInSlashCommand = SlashCommand & {
+  readonly usage: string;
+};
+
+export const SLASH_COMMANDS: readonly BuiltInSlashCommand[] = [
+  {
+    name: "status",
+    usage: "/status",
+    description: "Show session and context details",
+  },
+  {
+    name: "skills",
+    usage: "/skills",
+    description: "Show available and active Agent Skills",
+  },
+  {
+    name: "mcp",
+    usage: "/mcp",
+    description: "Show MCP servers and runtime tools",
+  },
   {
     name: "compact",
+    usage: "/compact [retire]",
     description: "Swap tool output or retire a cold history prefix",
   },
-  { name: "clear", description: "Start a new session and clear conversation" },
-  { name: "fork", description: "Clone the current session" },
-  { name: "view", description: "View a local UTF-8 text file" },
-  { name: "copy", description: "Copy the last response as Markdown" },
-  { name: "model", description: "Switch model profile (new session)" },
-  { name: "resume", description: "Choose or resume a session" },
-  { name: "session", description: "Manage stored sessions" },
-  { name: "quit", description: "Exit the TUI" },
+  {
+    name: "clear",
+    usage: "/clear",
+    description: "Start a new session and clear conversation",
+  },
+  { name: "fork", usage: "/fork", description: "Clone the current session" },
+  {
+    name: "view",
+    usage: "/view <path>",
+    description: "View a local UTF-8 text file",
+  },
+  {
+    name: "copy",
+    usage: "/copy",
+    description: "Copy the last response as Markdown",
+  },
+  {
+    name: "model",
+    usage: "/model [profile-name]",
+    description: "Switch model profile (new session)",
+  },
+  {
+    name: "resume",
+    usage: "/resume [session-id]",
+    description: "Choose or resume a session",
+  },
+  {
+    name: "session",
+    usage: "/session delete <session-id> --confirm",
+    description: "Manage stored sessions",
+  },
+  { name: "quit", usage: "/quit", description: "Exit the TUI" },
 ];
 
 export type ParsedSlashCommand =
@@ -48,12 +90,12 @@ export class SlashCommandError extends Error {
 export function parseSlashCommand(input: string): ParsedSlashCommand {
   const trimmed = input.trim();
   if (trimmed === "/view") {
-    throw new SlashCommandError("Usage: /view <path>");
+    throw slashCommandUsageError("view");
   }
   if (trimmed.startsWith("/view ") || trimmed.startsWith("/view\t")) {
     const filePath = trimmed.slice(5).trim();
     if (filePath === "") {
-      throw new SlashCommandError("Usage: /view <path>");
+      throw slashCommandUsageError("view");
     }
     return { type: "view", filePath };
   }
@@ -70,7 +112,7 @@ export function parseSlashCommand(input: string): ParsedSlashCommand {
     if (tokens.length === 1) {
       return { type: "mcp" };
     }
-    throw new SlashCommandError("Usage: /mcp");
+    throw slashCommandUsageError("mcp");
   }
   if (command === "/compact") {
     if (tokens.length === 1) {
@@ -79,25 +121,25 @@ export function parseSlashCommand(input: string): ParsedSlashCommand {
     if (tokens.length === 2 && tokens[1] === "retire") {
       return { type: "compact_retire" };
     }
-    throw new SlashCommandError("Usage: /compact [retire]");
+    throw slashCommandUsageError("compact");
   }
   if (command === "/clear") {
     if (tokens.length === 1) {
       return { type: "clear" };
     }
-    throw new SlashCommandError("Usage: /clear");
+    throw slashCommandUsageError("clear");
   }
   if (command === "/fork") {
     if (tokens.length === 1) {
       return { type: "fork" };
     }
-    throw new SlashCommandError("Usage: /fork");
+    throw slashCommandUsageError("fork");
   }
   if (command === "/copy") {
     if (tokens.length === 1) {
       return { type: "copy" };
     }
-    throw new SlashCommandError("Usage: /copy");
+    throw slashCommandUsageError("copy");
   }
   if (command === "/quit" && tokens.length === 1) {
     return { type: "quit" };
@@ -109,7 +151,7 @@ export function parseSlashCommand(input: string): ParsedSlashCommand {
     if (tokens.length === 2) {
       return { type: "model_switch", profileName: tokens[1] };
     }
-    throw new SlashCommandError("Usage: /model [profile-name]");
+    throw slashCommandUsageError("model");
   }
   if (command === "/resume") {
     if (tokens.length === 1) {
@@ -118,7 +160,7 @@ export function parseSlashCommand(input: string): ParsedSlashCommand {
     if (tokens.length === 2) {
       return { type: "resume", sessionId: parsePublicSessionId(tokens[1]) };
     }
-    throw new SlashCommandError("Usage: /resume [session-id]");
+    throw slashCommandUsageError("resume");
   }
   if (command === "/session") {
     if (tokens.length === 4 && tokens[1] === "delete" && tokens[3] === "--confirm") {
@@ -127,7 +169,7 @@ export function parseSlashCommand(input: string): ParsedSlashCommand {
         sessionId: parsePublicSessionId(tokens[2]),
       };
     }
-    throw new SlashCommandError("Usage: /session delete <session-id> --confirm");
+    throw slashCommandUsageError("session");
   }
   throw new SlashCommandError(`Unknown command: ${trimmed}`);
 }
@@ -167,4 +209,14 @@ function parsePublicSessionId(value: string): SessionId {
     throw new SlashCommandError(`Invalid session ID: ${value}`);
   }
 }
+
+function slashCommandUsageError(
+  name: (typeof SLASH_COMMANDS)[number]["name"],
+): SlashCommandError {
+  const command = SLASH_COMMANDS.find((candidate) => candidate.name === name);
+  if (command === undefined) {
+    throw new Error(`Missing built-in slash command declaration for ${name}.`);
+  }
+  return new SlashCommandError(`Usage: ${command.usage}`);
+}
 import { parseSessionId, type SessionId } from "../ids/runtime-id";

package/src/tui/workspace-file-search.ts

@@ -1,90 +1,97 @@
 import { execFile } from "node:child_process";
 import { RIPGREP_MISSING_ERROR, findRipgrepCommand } from "../tools/ripgrep";
-
-const FILE_SEARCH_TIMEOUT_MS = 20_000;
-const FILE_SEARCH_MAX_BUFFER_BYTES = 20_000_000;
+import { DEFAULT_PUBLIC_TOOLING_CONFIG } from "../cli/public-config-contract";
 
 export type WorkspaceFileLister = (
   workspaceRoot: string,
   signal: AbortSignal,
 ) => Promise<readonly string[]>;
 
-export const listWorkspaceFiles: WorkspaceFileLister = (workspaceRoot, signal) =>
-  new Promise((resolve, reject) => {
-    if (signal.aborted) {
-      reject(new Error("Workspace file search was cancelled."));
-      return;
-    }
+export type WorkspaceFileListerOptions = {
+  readonly command?: string;
+  readonly timeoutMs?: number;
+  readonly maxBufferBytes?: number;
+};
+
+export function createWorkspaceFileLister(
+  options: WorkspaceFileListerOptions = {},
+): WorkspaceFileLister {
+  const command = findRipgrepCommand(options.command);
+  const timeoutMs = options.timeoutMs ?? DEFAULT_PUBLIC_TOOLING_CONFIG.grepTimeoutMs;
+  const maxBufferBytes =
+    options.maxBufferBytes ?? DEFAULT_PUBLIC_TOOLING_CONFIG.grepMaxBufferBytes;
+
+  return (workspaceRoot, signal) =>
+    new Promise((resolve, reject) => {
+      if (signal.aborted) {
+        reject(new Error("Workspace file search was cancelled."));
+        return;
+      }
 
-    execFile(
-      findRipgrepCommand(),
-      [
-        "--files",
-        "--hidden",
-        "--glob",
-        "!**/node_modules/**",
-        "--glob",
-        "!**/.git/**",
-        "--glob",
-        "!**/.tinker/**",
-      ],
-      {
-        cwd: workspaceRoot,
-        encoding: "utf8",
-        maxBuffer: FILE_SEARCH_MAX_BUFFER_BYTES,
-        signal,
-        timeout: FILE_SEARCH_TIMEOUT_MS,
-      },
-      (error, stdout, stderr) => {
-        if (signal.aborted) {
-          reject(error ?? new Error("Workspace file search was cancelled."));
-          return;
-        }
+      execFile(
+        command,
+        [
+          "--files",
+          "--hidden",
+          "--glob",
+          "!**/node_modules/**",
+          "--glob",
+          "!**/.git/**",
+          "--glob",
+          "!**/.tinker/**",
+        ],
+        {
+          cwd: workspaceRoot,
+          encoding: "utf8",
+          maxBuffer: maxBufferBytes,
+          signal,
+          timeout: timeoutMs,
+        },
+        (error, stdout, stderr) => {
+          if (signal.aborted) {
+            reject(error ?? new Error("Workspace file search was cancelled."));
+            return;
+          }
 
-        if (error === null) {
-          resolve(splitPaths(stdout));
-          return;
-        }
+          if (error === null) {
+            resolve(splitPaths(stdout));
+            return;
+          }
 
-        const execError = error as Error & {
-          code?: number | string;
-          killed?: boolean;
-          signal?: string | null;
-        };
+          const execError = error as Error & {
+            code?: number | string;
+            killed?: boolean;
+            signal?: string | null;
+          };
 
-        if (execError.code === 1 && stderr.trim() === "") {
-          resolve(splitPaths(stdout));
-          return;
-        }
+          if (execError.code === 1 && stderr.trim() === "") {
+            resolve(splitPaths(stdout));
+            return;
+          }
 
-        if (execError.code === "ENOENT") {
-          reject(new Error(RIPGREP_MISSING_ERROR));
-          return;
-        }
+          if (execError.code === "ENOENT") {
+            reject(new Error(RIPGREP_MISSING_ERROR));
+            return;
+          }
 
-        if (execError.killed === true || typeof execError.signal === "string") {
-          reject(
-            new Error(
-              `Workspace file search timed out after ${FILE_SEARCH_TIMEOUT_MS}ms.`,
-            ),
-          );
-          return;
-        }
+          if (execError.killed === true || typeof execError.signal === "string") {
+            reject(new Error(`Workspace file search timed out after ${timeoutMs}ms.`));
+            return;
+          }
 
-        if (execError.message.includes("maxBuffer")) {
-          reject(
-            new Error(
-              `Workspace file list exceeded ${FILE_SEARCH_MAX_BUFFER_BYTES} bytes.`,
-            ),
-          );
-          return;
-        }
+          if (execError.message.includes("maxBuffer")) {
+            reject(new Error(`Workspace file list exceeded ${maxBufferBytes} bytes.`));
+            return;
+          }
+
+          const detail = stderr.trim() === "" ? execError.message : stderr.trim();
+          reject(new Error(`Workspace file search failed: ${detail}`));
+        },
+      );
+    });
+}
 
-        const detail = stderr.trim() === "" ? execError.message : stderr.trim();
-        reject(new Error(`Workspace file search failed: ${detail}`));
-      },
-    );
-  });
+export const listWorkspaceFiles = createWorkspaceFileLister();
 
 function splitPaths(stdout: string): string[] {
   return stdout