tinker-agent 2.6.0 → 2.7.0

package/src/tools/ask-user.ts

@@ -0,0 +1,100 @@
+import { throwIfTurnCancelled } from "../agent/turn-cancellation";
+import {
+  defineToolExecutor,
+  type AskUserRawResult,
+  type AskUserRequest,
+  type ToolExecutionContext,
+  type ToolExecutor,
+} from "./types";
+
+export function createAskUserToolExecutor(): ToolExecutor {
+  return defineToolExecutor("ask_user", {
+    definition: {
+      name: "AskUser",
+      description:
+        "Ask the user one multiple-choice question when a material ambiguity prevents correct progress. Investigate the conversation and workspace first. Provide 2-6 options, each as a complete answer the user can select. The user may select one option or dismiss the question. If dismissed, use your own judgment and do not immediately repeat the same question. Call AskUser alone, without other tool calls in the same response.",
+      parameters: {
+        type: "object",
+        properties: {
+          question: {
+            type: "string",
+            description: "The question shown to the user.",
+          },
+          options: {
+            type: "array",
+            minItems: 2,
+            maxItems: 6,
+            items: {
+              type: "object",
+              properties: {
+                description: {
+                  type: "string",
+                  description: "An answer the user can select.",
+                },
+              },
+              required: ["description"],
+            },
+          },
+        },
+        required: ["question", "options"],
+      },
+    },
+    async execute(
+      args,
+      _call,
+      context: ToolExecutionContext,
+    ): Promise<AskUserRawResult> {
+      throwIfTurnCancelled(context.signal);
+      const parsed = parseAskUserArgs(args);
+      if (!parsed.ok) {
+        return parsed;
+      }
+      if (context.askUser === undefined) {
+        return { ok: false, error: "AskUser interaction is unavailable." };
+      }
+      const response = await context.askUser(parsed.request);
+      throwIfTurnCancelled(context.signal);
+      return response.outcome === "selected"
+        ? { ok: true, outcome: "selected", answer: response.answer }
+        : { ok: true, outcome: "dismissed" };
+    },
+  });
+}
+
+function parseAskUserArgs(
+  args: unknown,
+): { ok: true; request: AskUserRequest } | { ok: false; error: string } {
+  if (!isRecord(args)) {
+    return { ok: false, error: "AskUser arguments must be an object." };
+  }
+  if (typeof args.question !== "string") {
+    return { ok: false, error: "AskUser question must be a string." };
+  }
+  if (!Array.isArray(args.options)) {
+    return { ok: false, error: "AskUser options must be an array." };
+  }
+  if (args.options.length < 2 || args.options.length > 6) {
+    return { ok: false, error: "AskUser options must contain between 2 and 6 items." };
+  }
+  const options: { description: string }[] = [];
+  for (const [index, option] of args.options.entries()) {
+    if (!isRecord(option) || typeof option.description !== "string") {
+      return {
+        ok: false,
+        error: `AskUser option ${index + 1} must be an object with a string description.`,
+      };
+    }
+    options.push({ description: option.description });
+  }
+  return {
+    ok: true,
+    request: Object.freeze({
+      question: args.question,
+      options: Object.freeze(options.map((option) => Object.freeze(option))),
+    }),
+  };
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/tools/registry.ts

@@ -1,3 +1,4 @@
+import { createAskUserToolExecutor } from "./ask-user";
 import { createBashToolExecutor } from "./bash";
 import { ShellTaskManager } from "./bash-task";
 import { createCwdState } from "./cwd-state";
@@ -86,6 +87,11 @@ export class ToolRuntime {
       ): Promise<"allow" | "deny">;
     },
     private readonly contextMaintenance?: ContextMaintenanceHandle,
+    private readonly askUser?: (
+      call: ToolCall,
+      request: Parameters<NonNullable<ToolExecutionContext["askUser"]>>[0],
+      signal: AbortSignal,
+    ) => ReturnType<NonNullable<ToolExecutionContext["askUser"]>>,
   ) {}
 
   async execute(call: ToolCall, context: ToolExecutionContext): Promise<ToolRawResult> {
@@ -117,6 +123,9 @@ export class ToolRuntime {
         ...(this.contextMaintenance === undefined
           ? {}
           : { contextMaintenance: this.contextMaintenance }),
+        ...(this.askUser === undefined
+          ? {}
+          : { askUser: (request) => this.askUser!(call, request, context.signal) }),
         ...(this.bashGuard === undefined
           ? {}
           : {
@@ -173,9 +182,17 @@ export function createDefaultTooling(options: {
   toolingConfig?: PublicToolingConfig;
   memorySearch?: ToolExecutor;
   memoryGet?: ToolExecutor;
+  memoryCreate?: ToolExecutor;
+  memoryUpdate?: ToolExecutor;
+  memoryDelete?: ToolExecutor;
   enableTurnUndo?: boolean;
   imageAssetStore?: ImageAssetStore;
   supportsViewImage?: boolean;
+  askUser?: (
+    call: ToolCall,
+    request: Parameters<NonNullable<ToolExecutionContext["askUser"]>>[0],
+    signal: AbortSignal,
+  ) => ReturnType<NonNullable<ToolExecutionContext["askUser"]>>;
   bashGuard?: {
     readonly surface: "tui" | "one-shot";
     confirm(
@@ -201,6 +218,9 @@ export function createDefaultTooling(options: {
     ...(options.homeRoot === undefined ? {} : { homeRoot: options.homeRoot }),
   });
 
+  if (options.askUser !== undefined) {
+    registry.register(createAskUserToolExecutor());
+  }
   registry.register(
     createGlobToolExecutor({
       workspaceRoot: options.workspaceRoot,
@@ -247,6 +267,15 @@ export function createDefaultTooling(options: {
   if (options.memoryGet !== undefined) {
     registry.register(options.memoryGet);
   }
+  if (options.memoryCreate !== undefined) {
+    registry.register(options.memoryCreate);
+  }
+  if (options.memoryUpdate !== undefined) {
+    registry.register(options.memoryUpdate);
+  }
+  if (options.memoryDelete !== undefined) {
+    registry.register(options.memoryDelete);
+  }
   if (options.skillCatalog !== undefined) {
     if (options.skillCatalog.skills.size === 0) {
       throw new Error("An empty Agent Skill catalog must not register tooling.");
@@ -321,6 +350,7 @@ export function createDefaultTooling(options: {
       registry,
       options.bashGuard,
       options.runtimeSession.contextMaintenance,
+      options.askUser,
     ),
     snapshots,
     taskManager,

package/src/tools/types.ts

@@ -428,6 +428,58 @@ export type MemoryGetRawResult =
       error: string;
     };
 
+export type MemoryCreateRawResult =
+  | {
+      ok: true;
+      status: "created" | "already_exists";
+      memoryId: string;
+      createdAt: string;
+    }
+  | {
+      ok: false;
+      error: string;
+    };
+
+export type MemoryUpdateRawResult =
+  | {
+      ok: true;
+      status: "updated";
+      memoryId: string;
+    }
+  | {
+      ok: false;
+      code: "memory_not_found";
+      error: string;
+    }
+  | {
+      ok: false;
+      code: "memory_duplicate";
+      conflictMemoryId: string;
+      error: string;
+    }
+  | {
+      ok: false;
+      code?: undefined;
+      error: string;
+    };
+
+export type MemoryDeleteRawResult =
+  | {
+      ok: true;
+      status: "deleted";
+      memoryId: string;
+    }
+  | {
+      ok: false;
+      code: "memory_not_found";
+      error: string;
+    }
+  | {
+      ok: false;
+      code?: undefined;
+      error: string;
+    };
+
 export type SkillRawResult =
   | {
       ok: true;
@@ -488,6 +540,20 @@ export type WaitRawResult =
       error: string;
     };
 
+export type AskUserRequest = {
+  readonly question: string;
+  readonly options: readonly { readonly description: string }[];
+};
+
+export type AskUserResponse =
+  | { readonly outcome: "selected"; readonly answer: string }
+  | { readonly outcome: "dismissed" };
+
+export type AskUserRawResult =
+  | { ok: true; outcome: "selected"; answer: string }
+  | { ok: true; outcome: "dismissed" }
+  | { ok: false; error: string };
+
 export type ToolRawResultByKind = {
   read: ReadFileRawResult;
   view_image: ViewImageRawResult;
@@ -508,7 +574,11 @@ export type ToolRawResultByKind = {
   context_maintenance: ContextMaintenanceRawResult;
   memory_search: MemorySearchRawResult;
   memory_get: MemoryGetRawResult;
+  memory_create: MemoryCreateRawResult;
+  memory_update: MemoryUpdateRawResult;
+  memory_delete: MemoryDeleteRawResult;
   wait: WaitRawResult;
+  ask_user: AskUserRawResult;
   skill: SkillRawResult;
   mcp: McpToolRawResult;
   generic: GenericToolRawResult;
@@ -553,6 +623,7 @@ export function defineToolExecutor<TKind extends ToolRawResultKind>(
 
 export type ToolExecutionContext = {
   signal: AbortSignal;
+  askUser?: (request: AskUserRequest) => Promise<AskUserResponse>;
   contextMaintenance?: ContextMaintenanceHandle;
   confirmBashCommand?: (request: {
     command: string;

package/src/tui/app.tsx

@@ -25,6 +25,7 @@ import { Footer } from "./components/footer";
 import { AssistantMarkdownProvider } from "./components/assistant-markdown";
 import { ContextStatus } from "./components/context-status";
 import { BackgroundTasks } from "./components/background-tasks";
+import { AskUser } from "./components/ask-user";
 import { BashConfirmation } from "./components/bash-confirmation";
 import { Header } from "./components/header";
 import { ModelPicker } from "./components/model-picker";
@@ -142,6 +143,11 @@ export function App(props: AppProps) {
     () => binding.bashGuard(),
     () => binding.bashGuard(),
   );
+  const askUser = useSyncExternalStore(
+    (listener) => binding.subscribeAskUser(listener),
+    () => binding.askUser(),
+    () => binding.askUser(),
+  );
   const promptScheduler = useSyncExternalStore(
     (listener) => binding.subscribePromptScheduler?.(listener) ?? (() => undefined),
     () => binding.promptScheduler?.() ?? IDLE_PROMPT_SCHEDULER,
@@ -276,7 +282,7 @@ export function App(props: AppProps) {
       setIsCancelling(true);
       setNotice("Cancelling current turn...");
     },
-    { isActive: executionRunning },
+    { isActive: executionRunning && askUser.pending === undefined },
   );
 
   const closeResumePicker = () => {
@@ -906,9 +912,11 @@ export function App(props: AppProps) {
                 status={
                   isCancelling
                     ? "cancelling"
-                    : executionRunning
-                      ? "running"
-                      : state.status
+                    : askUser.pending !== undefined
+                      ? "waiting_for_answer"
+                      : executionRunning
+                        ? "running"
+                        : state.status
                 }
                 workedForMs={state.workedForMs}
                 yolo={bashGuard.mode === "yolo"}
@@ -916,7 +924,26 @@ export function App(props: AppProps) {
               />
             </Box>
             <Box marginTop={1} flexDirection="column" flexShrink={0}>
-              {bashGuard.pending !== undefined ? (
+              {askUser.pending !== undefined ? (
+                <AskUser
+                  question={askUser.pending.question}
+                  options={askUser.pending.options}
+                  onSelect={(selectedIndex) => {
+                    void binding
+                      .resolveAskUser({ outcome: "selected", selectedIndex })
+                      .catch((error: unknown) =>
+                        setNotice(`Answer failed: ${errorMessage(error)}`),
+                      );
+                  }}
+                  onDismiss={() => {
+                    void binding
+                      .resolveAskUser({ outcome: "dismissed" })
+                      .catch((error: unknown) =>
+                        setNotice(`Dismiss failed: ${errorMessage(error)}`),
+                      );
+                  }}
+                />
+              ) : bashGuard.pending !== undefined ? (
                 <BashConfirmation
                   command={bashGuard.pending.command}
                   reason={bashGuard.pending.reason}
@@ -949,6 +976,7 @@ export function App(props: AppProps) {
                     isSessionOperation ||
                     isCopying ||
                     isCancelling ||
+                    askUser.pending !== undefined ||
                     bashGuard.pending !== undefined
                   }
                   history={props.history}

package/src/tui/components/ask-user.tsx

@@ -0,0 +1,61 @@
+import { Box, Text, useInput } from "ink";
+import { useState } from "react";
+
+export type AskUserProps = {
+  question: string;
+  options: readonly { readonly description: string }[];
+  onSelect(selectedIndex: number): void;
+  onDismiss(): void;
+};
+
+export function AskUser(props: AskUserProps) {
+  const [selectedIndex, setSelectedIndex] = useState(0);
+
+  useInput((input, key) => {
+    if (key.escape) {
+      props.onDismiss();
+      return;
+    }
+    if (key.upArrow) {
+      setSelectedIndex((current) =>
+        current === 0 ? props.options.length - 1 : current - 1,
+      );
+      return;
+    }
+    if (key.downArrow) {
+      setSelectedIndex((current) => (current + 1) % props.options.length);
+      return;
+    }
+    if (key.return) {
+      props.onSelect(selectedIndex);
+      return;
+    }
+    if (/^[1-6]$/.test(input)) {
+      const index = Number(input) - 1;
+      if (index < props.options.length) {
+        props.onSelect(index);
+      }
+    }
+  });
+
+  return (
+    <Box flexDirection="column" borderStyle="round" borderColor="cyan" paddingX={1}>
+      <Text color="cyan" bold>
+        Tinker asks
+      </Text>
+      <Text>{props.question}</Text>
+      <Box flexDirection="column" marginTop={1}>
+        {props.options.map((option, index) => (
+          <Text key={`${index}:${option.description}`}>
+            <Text color={index === selectedIndex ? "cyan" : undefined}>
+              {index === selectedIndex ? "❯" : " "} {index + 1}. {option.description}
+            </Text>
+          </Text>
+        ))}
+      </Box>
+      <Text dimColor>
+        ↑/↓ select · 1-{props.options.length} choose · Enter confirm · Esc skip
+      </Text>
+    </Box>
+  );
+}

package/src/tui/components/footer.tsx

@@ -1,7 +1,14 @@
 import { Spinner, StatusMessage } from "@inkjs/ui";
 
 export type FooterProps = {
-  status: "idle" | "running" | "cancelling" | "cancelled" | "done" | "failed";
+  status:
+    | "idle"
+    | "running"
+    | "waiting_for_answer"
+    | "cancelling"
+    | "cancelled"
+    | "done"
+    | "failed";
   workedForMs?: number;
   yolo?: boolean;
   pendingFollowUps?: number;
@@ -26,6 +33,12 @@ export function Footer(props: FooterProps) {
     return <StatusMessage variant="error">failed{suffix}</StatusMessage>;
   }
 
+  if (props.status === "waiting_for_answer") {
+    return (
+      <StatusMessage variant="info">Waiting for your selection{suffix}</StatusMessage>
+    );
+  }
+
   if (props.status === "running") {
     const queued =
       props.pendingFollowUps === undefined || props.pendingFollowUps === 0