tinker-agent 1.3.0 → 1.5.0

package/src/tui/app.tsx

@@ -1,6 +1,7 @@
 import { Box, Text, useApp, useInput } from "ink";
-import { useEffect, useRef, useState, useSyncExternalStore } from "react";
+import { useCallback, useEffect, useRef, useState, useSyncExternalStore } from "react";
 import { TurnCancelledError } from "../agent/turn-cancellation";
+import { boundedMemoryError, type StoredMemorySummary } from "../memory/contracts";
 import {
   ContextManagerError,
   type ContextCompactionResult,
@@ -18,6 +19,7 @@ import { BackgroundTasks } from "./components/background-tasks";
 import { Header } from "./components/header";
 import { ModelPicker } from "./components/model-picker";
 import { FileViewer, FileViewerLoading } from "./components/file-viewer";
+import { MemoryBrowser } from "./components/memory-browser";
 import {
   PromptInput,
   type PromptMaintenanceAction,
@@ -42,12 +44,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>;
@@ -57,6 +61,9 @@ export type AppProps = {
   ) => Promise<string | undefined>;
   writeClipboard?: (markdown: string) => Promise<void>;
   onQuit?: () => void;
+  initialNotice?: string;
+  listStoredMemories?: () => readonly StoredMemorySummary[];
+  memoryDisabledNotice?: string;
 };
 
 type ResumePickerState =
@@ -97,7 +104,7 @@ export function App(props: AppProps) {
   const [isSessionOperation, setIsSessionOperation] = useState(false);
   const [isCopying, setIsCopying] = useState(false);
   const [isCancelling, setIsCancelling] = useState(false);
-  const [notice, setNotice] = useState<string | undefined>(undefined);
+  const [notice, setNotice] = useState<string | undefined>(props.initialNotice);
   const [showStatus, setShowStatus] = useState(false);
   const [showSkills, setShowSkills] = useState(false);
   const [showMcp, setShowMcp] = useState(false);
@@ -109,6 +116,9 @@ export function App(props: AppProps) {
     ModelPickerState | undefined
   >(undefined);
   const [fileView, setFileView] = useState<FileViewState | undefined>(undefined);
+  const [memoryView, setMemoryView] = useState<
+    readonly StoredMemorySummary[] | undefined
+  >(undefined);
   const [viewError, setViewError] = useState<string | undefined>(undefined);
   const [gitBranch, setGitBranch] = useState<string | undefined>(undefined);
   const [gitBranchRefresh, setGitBranchRefresh] = useState(0);
@@ -130,6 +140,8 @@ export function App(props: AppProps) {
 
   const profileList = props.profiles ? [...props.profiles.profiles.values()] : [];
 
+  const runningElapsedMs = useElapsedMs(state.activeTurn?.startedAt);
+
   useEffect(() => {
     if (readGitBranch === undefined) {
       return;
@@ -274,6 +286,20 @@ export function App(props: AppProps) {
     setFileView(undefined);
   };
 
+  const openMemoryView = () => {
+    if (props.listStoredMemories === undefined) {
+      setNotice(props.memoryDisabledNotice ?? "memory disabled: not configured");
+      return;
+    }
+    try {
+      const snapshot = props.listStoredMemories();
+      setNotice(undefined);
+      setMemoryView(snapshot);
+    } catch (error) {
+      setNotice(`memory unavailable: ${boundedMemoryError(error)}`);
+    }
+  };
+
   const openFileView = (filePath: string) => {
     const requestId = fileViewRequest.current + 1;
     fileViewRequest.current = requestId;
@@ -452,6 +478,10 @@ export function App(props: AppProps) {
           openFileView(command.filePath);
           return true;
         }
+        if (command.type === "memory") {
+          openMemoryView();
+          return true;
+        }
         if (command.type === "copy") {
           copyLastResponse();
           return true;
@@ -581,6 +611,8 @@ export function App(props: AppProps) {
         <FileViewerLoading filePath={fileView.filePath} onCancel={closeFileView} />
       ) : fileView?.status === "ready" ? (
         <FileViewer file={fileView.file} onClose={closeFileView} />
+      ) : memoryView !== undefined ? (
+        <MemoryBrowser memories={memoryView} onClose={() => setMemoryView(undefined)} />
       ) : resumePicker?.status === "loading" ? (
         <ResumeSessionPickerLoading onCancel={closeResumePicker} />
       ) : resumePicker?.status === "ready" ? (
@@ -626,6 +658,7 @@ export function App(props: AppProps) {
             <Footer
               status={isCancelling ? "cancelling" : state.status}
               workedForMs={state.workedForMs}
+              elapsedMs={runningElapsedMs}
             />
           </Box>
           <Box marginTop={1} flexDirection="column">
@@ -647,6 +680,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}
@@ -667,6 +701,42 @@ function errorMessage(error: unknown): string {
   return error instanceof Error ? error.message : String(error);
 }
 
+const ELAPSED_TICK_MS = 1_000;
+
+// The wall clock, quantized to whole ticks so a render pass reads one stable
+// value and re-renders at most once per second.
+function readElapsedClockMs(): number {
+  return Math.floor(Date.now() / ELAPSED_TICK_MS) * ELAPSED_TICK_MS;
+}
+
+// Counts up while a turn is active. The interval only exists while `startedAt`
+// is defined, so an idle TUI keeps no timer running.
+function useElapsedMs(startedAt: string | undefined): number | undefined {
+  const subscribe = useCallback(
+    (onClockTick: () => void) => {
+      if (startedAt === undefined) {
+        return () => undefined;
+      }
+
+      const timer = setInterval(onClockTick, ELAPSED_TICK_MS);
+      return () => clearInterval(timer);
+    },
+    [startedAt],
+  );
+  const nowMs = useSyncExternalStore(subscribe, readElapsedClockMs, readElapsedClockMs);
+
+  if (startedAt === undefined) {
+    return undefined;
+  }
+
+  const startedAtMs = Date.parse(startedAt);
+  if (!Number.isFinite(startedAtMs)) {
+    throw new Error(`Invalid turn start timestamp: ${startedAt}`);
+  }
+
+  return Math.max(0, nowMs - startedAtMs);
+}
+
 export function formatContextCompactionNotice(result: ContextCompactionResult): string {
   if (result.status === "unchanged") {
     if (result.outcome === "below_target") {

package/src/tui/clipboard.ts

@@ -1,5 +1,27 @@
 import clipboard from "clipboardy";
+import { writeFile } from "node:fs/promises";
+import path from "node:path";
 
 export async function writeClipboardText(text: string): Promise<void> {
   await clipboard.write(text);
 }
+
+export function clipboardWriterForEnvironment(
+  env: NodeJS.ProcessEnv,
+): ((text: string) => Promise<void>) | undefined {
+  const filePath = env.TINKER_TEST_CLIPBOARD_FILE;
+  if (filePath === undefined || filePath === "") {
+    return undefined;
+  }
+  if (env.TINKER_TEST_FAKE_MODEL === undefined || env.TINKER_TEST_FAKE_MODEL === "") {
+    throw new Error("TINKER_TEST_CLIPBOARD_FILE requires TINKER_TEST_FAKE_MODEL.");
+  }
+  if (!path.isAbsolute(filePath)) {
+    throw new Error("TINKER_TEST_CLIPBOARD_FILE must be an absolute path.");
+  }
+  return (text) =>
+    writeFile(filePath, text, {
+      encoding: "utf8",
+      mode: 0o600,
+    });
+}

package/src/tui/components/footer.tsx

@@ -4,6 +4,7 @@ import { Text } from "ink";
 export type FooterProps = {
   status: "idle" | "running" | "cancelling" | "cancelled" | "done" | "failed";
   workedForMs?: number;
+  elapsedMs?: number;
 };
 
 export function Footer(props: FooterProps) {
@@ -14,7 +15,7 @@ export function Footer(props: FooterProps) {
 
     return (
       <StatusMessage variant="success">
-        Worked for {formatWorkedDuration(props.workedForMs)}
+        Worked for {formatDuration(props.workedForMs)}
       </StatusMessage>
     );
   }
@@ -24,7 +25,11 @@ export function Footer(props: FooterProps) {
   }
 
   if (props.status === "running") {
-    return <Text color="yellow">• Running</Text>;
+    if (props.elapsedMs === undefined) {
+      return <Text color="yellow">• Running</Text>;
+    }
+
+    return <Text color="yellow">{`• Running ${formatDuration(props.elapsedMs)}`}</Text>;
   }
 
   if (props.status === "cancelling") {
@@ -38,9 +43,9 @@ export function Footer(props: FooterProps) {
   return <StatusMessage variant="info">idle</StatusMessage>;
 }
 
-function formatWorkedDuration(durationMs: number): string {
+function formatDuration(durationMs: number): string {
   if (!Number.isFinite(durationMs) || durationMs < 0) {
-    throw new Error(`Invalid worked duration: ${durationMs}`);
+    throw new Error(`Invalid duration: ${durationMs}`);
   }
 
   const totalSeconds = Math.floor(durationMs / 1000);

package/src/tui/components/memory-browser.tsx

@@ -0,0 +1,151 @@
+import {
+  Box,
+  Text,
+  useBoxMetrics,
+  useInput,
+  useWindowSize,
+  type DOMElement,
+} from "ink";
+import { useRef, useState } from "react";
+import type { StoredMemorySummary } from "../../memory/contracts";
+
+const BROWSER_CHROME_ROWS = 3;
+
+export type MemoryBrowserProps = {
+  readonly memories: readonly StoredMemorySummary[];
+  readonly onClose: () => void;
+  readonly viewportRows?: number;
+  readonly viewportColumns?: number;
+};
+
+export function MemoryBrowser(props: MemoryBrowserProps) {
+  const windowSize = useWindowSize();
+  const rows = Math.max(4, props.viewportRows ?? windowSize.rows);
+  const columns = Math.max(20, props.viewportColumns ?? windowSize.columns);
+  const bodyRows = Math.max(1, rows - BROWSER_CHROME_ROWS);
+  const contentRef = useRef<DOMElement>(null);
+  const { height: measuredContentRows, hasMeasured } = useBoxMetrics(contentRef);
+  const totalLines = props.memories.length === 0 ? 0 : measuredContentRows;
+  const maxTopLine = Math.max(0, totalLines - bodyRows);
+  const [topLine, setTopLine] = useState(0);
+  const visibleTopLine = clamp(topLine, 0, maxTopLine);
+  const visibleEnd = Math.min(totalLines, visibleTopLine + bodyRows);
+
+  useInput((input, key) => {
+    if (key.escape) {
+      props.onClose();
+      return;
+    }
+    if (key.home) {
+      setTopLine(0);
+      return;
+    }
+    if (key.end) {
+      setTopLine(maxTopLine);
+      return;
+    }
+    if (key.pageUp || key.pageDown) {
+      const direction = key.pageUp ? -1 : 1;
+      setTopLine((current) => clamp(current + direction * bodyRows, 0, maxTopLine));
+      return;
+    }
+    const direction =
+      key.upArrow || (input === "k" && !key.ctrl && !key.meta)
+        ? -1
+        : key.downArrow || (input === "j" && !key.ctrl && !key.meta)
+          ? 1
+          : 0;
+    if (direction !== 0) {
+      setTopLine((current) => clamp(current + direction, 0, maxTopLine));
+    }
+  });
+
+  return (
+    <Box width={columns} height={rows} flexDirection="column" overflow="hidden">
+      <Text bold>Global memory</Text>
+      <Text dimColor wrap="truncate-end">
+        ↑/↓ or j/k · PgUp/PgDn · Home/End · Esc close
+      </Text>
+      <Box
+        height={bodyRows}
+        width={columns}
+        position="relative"
+        overflow="hidden"
+        flexDirection="column"
+      >
+        {props.memories.length === 0 ? (
+          <Text dimColor>No stored memories.</Text>
+        ) : (
+          <Box
+            ref={contentRef}
+            position="absolute"
+            top={-visibleTopLine}
+            width={columns}
+            flexDirection="column"
+          >
+            {props.memories.map((memory, index) => (
+              <Box
+                key={memory.memoryId}
+                flexDirection="column"
+                marginBottom={index === props.memories.length - 1 ? 0 : 1}
+              >
+                <Text dimColor wrap="truncate-middle">
+                  {formatMemoryCreatedAt(memory.createdAt)} · {memory.sourceWorkspace}
+                </Text>
+                <Text>{normalizeMemoryDisplayText(memory.text)}</Text>
+              </Box>
+            ))}
+          </Box>
+        )}
+      </Box>
+      <Text dimColor wrap="truncate-end">
+        {props.memories.length === 0
+          ? "0 memories"
+          : memoryBrowserStatus(
+              visibleTopLine,
+              visibleEnd,
+              hasMeasured ? totalLines : 0,
+              props.memories.length,
+            )}
+      </Text>
+    </Box>
+  );
+}
+
+export function normalizeMemoryDisplayText(text: string): string {
+  return (
+    text
+      .replaceAll(/\r\n?/g, "\n")
+      .replaceAll("\t", "    ")
+      // eslint-disable-next-line no-control-regex
+      .replaceAll(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f-\u009f]/g, "\uFFFD")
+  );
+}
+
+export function formatMemoryCreatedAt(createdAt: string): string {
+  const date = new Date(createdAt);
+  const year = String(date.getFullYear()).padStart(4, "0");
+  const month = String(date.getMonth() + 1).padStart(2, "0");
+  const day = String(date.getDate()).padStart(2, "0");
+  const hours = String(date.getHours()).padStart(2, "0");
+  const minutes = String(date.getMinutes()).padStart(2, "0");
+  return `${year}-${month}-${day} ${hours}:${minutes}`;
+}
+
+function memoryBrowserStatus(
+  topLine: number,
+  endLine: number,
+  totalLines: number,
+  memoryCount: number,
+): string {
+  if (totalLines === 0) {
+    return `0 lines · ${memoryCount} ${memoryCount === 1 ? "memory" : "memories"}`;
+  }
+  return `${topLine + 1}–${endLine} / ${totalLines} lines · ${memoryCount} ${
+    memoryCount === 1 ? "memory" : "memories"
+  }`;
+}
+
+function clamp(value: number, minimum: number, maximum: number): number {
+  return Math.min(Math.max(value, minimum), maximum);
+}

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/event-store.ts

@@ -697,8 +697,8 @@ function toolCallSummary(input: { name: string; args: unknown }): string {
   if (input.name === "Grep") {
     return `Grep ${toolPattern(input.args) ?? ""}`.trim();
   }
-  if (input.name === "WebSearch") {
-    return `WebSearch ${toolQuery(input.args) ?? ""}`.trim();
+  if (input.name === "WebSearch" || input.name === "MemorySearch") {
+    return `${input.name} ${toolQuery(input.args) ?? ""}`.trim();
   }
   if (input.name === "WebFetch") {
     return `WebFetch ${toolUrl(input.args) ?? ""}`.trim();
@@ -779,6 +779,11 @@ function toolRawResultSummary(name: string, args: unknown, raw: ToolRawResult):
       return raw.mode === "search"
         ? `${base} -> ${raw.page.hits.length} historical match${raw.page.hits.length === 1 ? "" : "es"}`
         : `${base} -> ${raw.page.returnedBytes} historical bytes`;
+    case "memory_search":
+      if (!raw.ok) {
+        return base;
+      }
+      return `${base} -> ${raw.matches.length} derived memor${raw.matches.length === 1 ? "y" : "ies"}`;
     case "skill":
       if (!raw.ok) {
         return `${base} failed -> ${boundedToolError(raw.error)}`;
@@ -846,6 +851,7 @@ function toolRawResultBashDetail(raw: ToolRawResult): Pick<TimelineItem, "bash">
     case "web_search":
     case "web_fetch":
     case "recall":
+    case "memory_search":
     case "skill":
     case "mcp":
     case "generic":
@@ -880,6 +886,7 @@ function toolRawResultDiff(
     case "web_search":
     case "web_fetch":
     case "recall":
+    case "memory_search":
     case "skill":
     case "mcp":
     case "generic":

package/src/tui/slash-commands.ts

@@ -1,30 +1,78 @@
 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: "memory",
+    usage: "/memory",
+    description: "Browse stored global memories",
+  },
   {
     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 =
   | { type: "status" }
   | { type: "skills" }
   | { type: "mcp" }
+  | { type: "memory" }
   | { type: "compact" }
   | { type: "compact_retire" }
   | { type: "clear" }
@@ -48,12 +96,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 +118,13 @@ export function parseSlashCommand(input: string): ParsedSlashCommand {
     if (tokens.length === 1) {
       return { type: "mcp" };
     }
-    throw new SlashCommandError("Usage: /mcp");
+    throw slashCommandUsageError("mcp");
+  }
+  if (command === "/memory") {
+    if (tokens.length === 1) {
+      return { type: "memory" };
+    }
+    throw slashCommandUsageError("memory");
   }
   if (command === "/compact") {
     if (tokens.length === 1) {
@@ -79,25 +133,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 +163,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 +172,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 +181,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 +221,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";