thincoder 0.8.11 → 0.8.13

package/README.md

@@ -205,10 +205,37 @@ Code conventions: pure `.mjs`, no semicolons, no npm dependencies allowed (inclu
 
 ## Changelog
 
+### 0.8.13 (2026-07)
+- **TUI: incremental rendering** — panel-level cache (`panelCache`) with sync-update bracketing (`DECSET 2026`). Only redraws changed panels, eliminating flicker. `saveCursor`/`restoreCursor` for efficient cursor positioning. Panel order reorganized: `header → conversation → subagent → output → todo → picker → permission → queue → input → status`.
+- **Ctrl+I inject resume** — Ctrl+I (or Tab during processing) now properly interrupts, injects the message, and *resumes* the agent loop. Controller is recreated after abort. Added active signal check in SSE read loop for faster abort on Windows.
+- **Processing hints** — Input box shows "Ctrl+U clear" hint during processing. Tab during processing treated as Ctrl+I. Slash commands re-render the frame.
+- **Compression visibility** — `compressIfNeeded` now forwards `onToken`/`onReasoning` callbacks, making compression activity visible in the TUI.
+- **Session: data-preserving fallback** — when atomic rename fails during session save, fall back to direct write instead of losing data.
+- **Distill: balanced-bracket JSON extraction** — handles nested arrays in LLM output (e.g. `"tags": ["a", "b"]`), replacing the broken non-greedy regex approach.
+- **File tools: EOL normalization** — `normalizeEOL` (`\r\n` → `\n`) applied on all reads (`read`, `edit`, `hashline_edit`, `insert_after`, `grep`, `repomap`), making hash computation and string matching platform-consistent.
+- **hashline_edit: multiple-match detection** — when a hash sequence matches multiple positions, reports all with surrounding context instead of silently picking one.
+- **delete: symlink-safe** — uses `lstat` instead of `stat` to correctly identify symlinks (not directories even if pointing to one).
+- **repomap: large file guard** — skip files >10MB in dependency outline builds to prevent OOM.
+- **Improved error messages** — `grep` and `insert_after` now catch invalid regex patterns at validation time with clear error messages.
+- **Advisor session persistence** — advisor config saved/restored across sessions.
+- **Timeout hardening** — auto-think uses `AbortSignal.timeout(5s)`, embedding requests add 60s timeout, MCP HTTP connect uses `INIT_TIMEOUT_MS`, fetch timeout extended to 10 minutes.
+- **ClearScreen on exit** — terminal restored with `clearScreen` ANSI on TUI cleanup.
+
+### 0.8.12 (2026-07)
+- **Indexing: git-repo-only** — `codeSync` and `docSync` now only index inside git worktrees (via `git ls-files`), respecting `.gitignore`. Non-git directories get empty indexes. Prevents 2.9GB memory.db from accidentally indexing entire user profiles (AppData, browser extensions, Office add-ins, Program Files)
+- **Indexing: file-size caps** — code files >1MB and doc files >512KB are skipped during bulk indexing (minified bundles, test fixtures, generated code)
+- **Compaction: earlier trigger** — `COMPACT_RATIO` lowered from 0.8 to 0.6 (with 40K floor), so injected context (directory tree, git context, outline, memory/doc search results) doesn't starve the model for headroom before compaction fires
+- **Bugfix: event-loop blocking** — `buildOutline`/`buildSummary` in `repomap.mjs` now awaited (was sync calling async), `setup.mjs` outline injection fixed, `codeSync` walk uses `readFile` instead of `readFileSync`
+- **Feat: SKIP_DIRS expanded** — Windows profile directories (`AppData`, `Desktop`, `Documents`, `Downloads`, `Music`, `Pictures`, `Videos`, etc.) added to the skip list
+- **Feat: `listProjectFiles` shared helper** — extracted from `codeSync`/`docSync`, used by both; git-only with fallback removed
+- **Refactor: `embed-config.mjs`** — simplified to only read API key via `resolveEmbedKey()`, base URL and model are fixed constants; VSCode SecretStorage dependency removed
+
 ### 0.8.11 (2026-07)
 - **Feat**: `checklist` tool — persistent project task tracking in `.thincoder/checklist.md`. Add/mark/list items, auto-archive done items to `checklist-done.md`. Injected at session start (pending + in_progress only)
 - **Feat**: updated prompts — four-step workflow (requirements→design→development→testing), three-step debugging strategy (logs→docs→binary search), working checklist discipline
 - **Feat**: methodology docs — `docs/design/METHODOLOGY.md` rebuilt, `PHILOSOPHY.md` expanded with worldview #6 (official docs over guessing)
+- **Bugfix**: vision guard — `read_image` now refuses non-vision models before reading the file, the agent loop injects a system reminder instead of image parts for text-only models, and `stripImagesForTextModel` sanitizes image parts at send time (history untouched, restored when switching back to a vision model). Previously a single image in history made text-only APIs (e.g. DeepSeek) reject EVERY subsequent request with 400, bricking the conversation
+- **Improvement**: silent `catch {}` blocks now log to stderr (checkpoint file copies, MCP notify/close, session incremental save, clipboard paste, provider picker, team-memory rebase abort, tool dispatch) — failures are visible for debugging instead of disappearing
 
 ### 0.8.10 (2026-07)
 - **Bugfix**: pasted text now lands in the active TUI text target — the API key prompt when adding a provider via `/model` (and any free-text `askQuestion`) now accepts paste correctly. Previously, bracketed-paste injection in the terminal was always written to the main input box, so pasting into a question prompt appeared as "nothing happened" and orphaned the text into the input box after the question closed. Both bracketed-paste (Windows Terminal / most modern terminals) and Ctrl+V-as-key-event (legacy conhost) now route through a single `insertPastedText` helper that targets the question answer, options-list (ignored), or main input box as appropriate

package/bin/thincoder.mjs

@@ -6,6 +6,7 @@
  *   thincoder chat "..."      One-shot agent run (tools enabled, streamed)
  *   thincoder memory <sub>    Memory management: list / search / put / remove
  *   thincoder upgrade         Update to the latest version from npm
+ *   thincoder completion <sh> Shell completion: bash / zsh / fish
  *   thincoder -v              Print version
  *   thincoder --help          Print help
  */
@@ -49,6 +50,7 @@ Usage:
                             Extract knowledge candidates from a session
                             transcript file; confirm each before saving
   thincoder upgrade         Update to the latest version from npm
+  thincoder completion <sh>  Generate shell completion script (bash / zsh / fish)
   thincoder -v, --version   Print version
 
 Config: ~/.thincoder/config.json (providers[] + activeProvider; manage via /provider, /model in TUI)
@@ -252,6 +254,119 @@ switch (command) {
     break
   }
 
+  case "completion": {
+    const shell = args[0]
+    if (!["bash", "zsh", "fish"].includes(shell)) {
+      console.error(`Usage: thincoder completion <bash|zsh|fish>`)
+      exitSoon(1)
+      break
+    }
+    if (shell === "bash") {
+      process.stdout.write(`_thincoder() {
+  local cur prev words cword
+  _init_completion 2>/dev/null || { COMPREPLY=(); return; }
+  cur="\${COMP_WORDS[COMP_CWORD]}"
+  prev="\${COMP_WORDS[COMP_CWORD-1]}"
+  case "\${COMP_WORDS[1]}" in
+    chat)    COMPREPLY=( \\$(compgen -W "--auto" -- "\\$cur") ) ;;
+    memory)
+      case "\\$prev" in
+        memory) COMPREPLY=( \\$(compgen -W "list search put remove" -- "\\$cur") ) ;;
+        list)   COMPREPLY=( \\$(compgen -W "--type=rule --type=knowledge --type=decision --type=pattern" -- "\\$cur") ) ;;
+        put)    COMPREPLY=( \\$(compgen -W "--type= --title= --content= --tags=" -- "\\$cur") ) ;;
+      esac ;;
+    distill) COMPREPLY=( \\$(compgen -W "--yes --scope=" -- "\\$cur") ) ;;
+    completion) COMPREPLY=( \\$(compgen -W "bash zsh fish" -- "\\$cur") ) ;;
+    *)
+      COMPREPLY=( \\$(compgen -W "chat memory sync reindex distill upgrade completion -v --version -h --help" -- "\\$cur") ) ;;
+  esac
+}
+complete -F _thincoder thincoder
+`)
+    } else if (shell === "zsh") {
+      process.stdout.write(`#compdef thincoder
+
+_thincoder() {
+  local context state state_descr line
+  typeset -A opt_args
+  _arguments -C \\
+    '1: :->cmd' \\
+    '*:: :->args'
+
+  case "\\$state" in
+    cmd)
+      _values 'command' \\
+        'chat[One-shot agent run with tools]' \\
+        'memory[Manage long-term memory]' \\
+        'sync[Sync team memory repo]' \\
+        'reindex[Rebuild local index from markdown]' \\
+        'distill[Extract knowledge from session transcript]' \\
+        'upgrade[Update to latest version from npm]' \\
+        'completion[Generate shell completion script]'
+      ;;
+    args)
+      case "\\$words[1]" in
+        chat)    _arguments '--auto[Auto-approve all tool calls]' ;;
+        memory)
+          case "\\$words[2]" in
+            list) _arguments '--type=[Filter by type]' ;;
+            put)  _arguments '--type=[Entry type]' '--title=[Title]' '--content=[Content]' '--tags=[Space-separated tags]' ;;
+          esac ;;
+        distill) _arguments '--yes[Skip confirmation]' '--scope=[Scope filter]' ;;
+        completion) _values 'shell' 'bash' 'zsh' 'fish' ;;
+      esac ;;
+  esac
+}
+_thincoder
+`)
+    } else if (shell === "fish") {
+      process.stdout.write(`# thincoder completions for fish shell
+complete -c thincoder -f
+
+# Subcommands
+complete -c thincoder -a chat     -d 'One-shot agent run with tools'
+complete -c thincoder -a memory   -d 'Manage long-term memory'
+complete -c thincoder -a sync     -d 'Sync team memory repo'
+complete -c thincoder -a reindex  -d 'Rebuild local index from markdown'
+complete -c thincoder -a distill  -d 'Extract knowledge from session'
+complete -c thincoder -a upgrade  -d 'Update to latest version'
+complete -c thincoder -a completion -d 'Shell completion'
+
+# Flags
+complete -c thincoder -s v -l version -d 'Print version'
+complete -c thincoder -s h -l help    -d 'Print help'
+
+# chat flags
+complete -c thincoder -n '__fish_seen_subcommand_from chat' -l auto -d 'Auto-approve tool calls'
+
+# memory subcommands
+complete -c thincoder -n '__fish_seen_subcommand_from memory' -a list   -d 'List entries'
+complete -c thincoder -n '__fish_seen_subcommand_from memory' -a search -d 'Search memory'
+complete -c thincoder -n '__fish_seen_subcommand_from memory' -a put    -d 'Add entry'
+complete -c thincoder -n '__fish_seen_subcommand_from memory' -a remove -d 'Remove entry'
+
+# memory list flags
+complete -c thincoder -n '__fish_seen_subcommand_from memory; and __fish_seen_subcommand_from list' -l type -d 'Filter by type' -xa 'rule knowledge decision pattern'
+
+# memory put flags
+complete -c thincoder -n '__fish_seen_subcommand_from memory; and __fish_seen_subcommand_from put' -l type    -d 'Entry type'
+complete -c thincoder -n '__fish_seen_subcommand_from memory; and __fish_seen_subcommand_from put' -l title   -d 'Title'
+complete -c thincoder -n '__fish_seen_subcommand_from memory; and __fish_seen_subcommand_from put' -l content -d 'Content'
+complete -c thincoder -n '__fish_seen_subcommand_from memory; and __fish_seen_subcommand_from put' -l tags    -d 'Space-separated tags'
+
+# distill flags
+complete -c thincoder -n '__fish_seen_subcommand_from distill' -l yes   -d 'Skip confirmation'
+complete -c thincoder -n '__fish_seen_subcommand_from distill' -l scope -d 'Scope filter'
+
+# completion shells
+complete -c thincoder -n '__fish_seen_subcommand_from completion' -a bash -d 'Bash completions'
+complete -c thincoder -n '__fish_seen_subcommand_from completion' -a zsh  -d 'Zsh completions'
+complete -c thincoder -n '__fish_seen_subcommand_from completion' -a fish -d 'Fish completions'
+`)
+    }
+    break
+  }
+
   case "upgrade": {
     const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"))
     const local = pkg.version

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "thincoder",
-  "version": "0.8.11",
+  "version": "0.8.13",
   "description": "Thin coding agent - zero dependencies, no build step, Node.js native. Sharp code, zero bloat.",
   "keywords": [
     "ai",

package/src/advisor.mjs

@@ -0,0 +1,105 @@
+/**
+ * advisor.mjs — automated code review after each turn.
+ *
+ * After every agent turn with tool execution, a second chat completion reviews
+ * the turn's transcript and injects observations as a system reminder.
+ *
+ * Config:
+ *   { advisor: { enabled: true, provider: "deepseek", model: "deepseek-chat" } }
+ *   provider + model are optional — defaults to the main agent's provider/model.
+ */
+import { chat } from "./provider/core.mjs"
+import { findProvider } from "./config.mjs"
+
+const ADVISOR_PROMPT = `你是代码审查顾问。审查编程助手最近一轮操作并提供简短的观察。
+
+规则：
+- 用中文回答，2-4 行，分条目
+- 关注：遗漏的边界情况、错误的假设、低效的模式、安全隐患
+- 如果一切正常，说"未发现问题"
+- 不要建议或调用工具 — 只做只读审查
+- 不要直接对用户说话 — 用第三人称评价助手的行为`
+
+/**
+ * Run advisor review on the most recent turn.
+ * Only fires when the agent executed tool calls (did real work).
+ * Returns the advisor's message, or null if advisor is disabled or there's nothing to review.
+ */
+export async function runAdvisor(agent) {
+  const cfg = agent.config?.advisor
+  if (!cfg?.enabled) return null
+
+  // Only review turns where the agent did real work (tool calls executed)
+  const lastAssistant = findLast(agent.history, (m) => m.role === "assistant")
+  const lastTool = findLast(agent.history, (m) => m.role === "tool")
+  if (!lastAssistant || !lastTool) return null
+
+  // Build a clean transcript: last user message + assistant + tool results
+  const lastUser = findLast(agent.history, (m) => m.role === "user")
+  const transcript = buildTranscript(agent.history, lastUser)
+
+  // Resolve provider: explicit provider name → look up from providers list;
+  // only model → reuse main provider with different model; neither → main provider as-is.
+  let provider
+  if (cfg.provider) {
+    provider = findProvider(agent.providers ?? [agent.provider], cfg.provider)
+    if (cfg.model) provider = { ...provider, model: cfg.model }
+  } else {
+    provider = { ...agent.provider }
+    if (cfg.model) provider.model = cfg.model
+  }
+
+  try {
+    const response = await chat(provider, {
+      messages: [
+        { role: "system", content: ADVISOR_PROMPT },
+        { role: "user", content: transcript },
+      ],
+      tools: [],
+      signal: new AbortController().signal,
+    })
+    if (!response.content?.trim()) return null
+
+    return `[Advisor 审查 — 自动观察，非用户指令。请批判性参考：\n${response.content.trim()}]`
+  } catch {
+    // Advisor failure is non-fatal — main loop continues
+    return null
+  }
+}
+
+/** Find the last history entry matching a predicate. */
+function findLast(arr, fn) {
+  for (let i = arr.length - 1; i >= 0; i--) {
+    if (fn(arr[i])) return i
+  }
+  return -1
+}
+
+/** Build a compact transcript of the last turn for the advisor. */
+function buildTranscript(history, lastUserIdx) {
+  const lines = []
+  lines.push("## Last user message")
+  lines.push(truncate(String(history[lastUserIdx]?.content ?? "")))
+  lines.push("")
+  lines.push("## Assistant response and tool calls")
+
+  for (let i = lastUserIdx + 1; i < history.length; i++) {
+    const m = history[i]
+    if (m.role === "assistant") {
+      const content = typeof m.content === "string" ? m.content : ""
+      const tools = m.tool_calls?.map((tc) => tc.function?.name).filter(Boolean) ?? []
+      const label = tools.length ? ` (called: ${tools.join(", ")})` : ""
+      lines.push(`[assistant${label}] ${truncate(content, 500)}`)
+    } else if (m.role === "tool") {
+      lines.push(`[tool ${m.tool_call_id}] ${truncate(String(m.content ?? ""), 300)}`)
+    }
+  }
+
+  return lines.join("\n")
+}
+
+/** Truncate text to maxLen characters, adding "…" if truncated. */
+function truncate(text, maxLen = 1000) {
+  if (text.length <= maxLen) return text
+  return text.slice(0, maxLen) + "…"
+}

package/src/agent/dispatch.mjs

@@ -2,6 +2,37 @@
  * agent/dispatch.mjs — two-phase tool call execution
  */
 import { offloadToolResult } from "./helpers.mjs"
+import { writeFileSync, mkdirSync, existsSync } from "node:fs"
+import { join } from "node:path"
+import { homedir } from "node:os"
+
+const ERRORS_DIR = join(homedir(), ".thincoder", "tool-errors")
+
+/**
+ * Persist a tool error to ~/.thincoder/tool-errors/YYYY-MM-DD/HHmmss-toolName.log
+ * Only called for actual execution failures and malformed invocations.
+ * Skipped for intentional denials (plan mode, user reject).
+ */
+function logToolError(toolName, args, error) {
+  try {
+    const now = new Date()
+    const ymd = now.toISOString().slice(0, 10)
+    const ts = now.toISOString().replace(/:/g, "").replace(/\..+/, "").replace("T", "-")
+    const dir = join(ERRORS_DIR, ymd)
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true })
+    const file = join(dir, `${ts}-${toolName.replace(/[/\\]/g, "_")}.log`)
+    const entry = [
+      `time: ${now.toISOString()}`,
+      `tool: ${toolName}`,
+      `args: ${JSON.stringify(args, null, 2)}`,
+      `error: ${error?.message ?? String(error)}`,
+      error?.stack ? `stack:\n${error.stack}` : "",
+    ].filter(Boolean).join("\n") + "\n"
+    writeFileSync(file, entry, "utf8")
+  } catch {
+    // Log failure itself must not crash the agent
+  }
+}
 
 /**
  * Two-phase execution:
@@ -19,11 +50,13 @@ export async function executeToolCalls(agent, toolByName, toolCalls, callbacks,
     try {
       args = JSON.parse(toolCall.arguments || "{}")
     } catch {
+      logToolError(toolCall.name, { arguments: toolCall.arguments }, new Error("Invalid JSON arguments"))
       prepared.push({ toolCall, tool: null, error: `Invalid tool arguments JSON: ${toolCall.arguments}` })
       continue
     }
 
     if (!tool) {
+      logToolError(toolCall.name, {}, new Error(`Unknown tool: ${toolCall.name}`))
       prepared.push({ toolCall, tool: null, error: `Unknown tool: ${toolCall.name}` })
       continue
     }
@@ -79,6 +112,8 @@ export async function executeToolCalls(agent, toolByName, toolCalls, callbacks,
       callbacks.onToolResult?.(item.toolCall.name, result)
       return { ...item, result, ok: true }
     } catch (error) {
+      // Persist to ~/.thincoder/tool-errors/ for post-mortem; only pass message to the model (stack traces confuse LLMs and may leak paths)
+      logToolError(item.toolCall.name, item.args, error)
       return { ...item, result: `Error: ${error.message}`, ok: false }
     }
   }

package/src/agent/setup.mjs

@@ -1,12 +1,9 @@
 /**
  * agent/setup.mjs — runAgent pre-flight setup: context injection, system prompt construction, tool injection
  */
-import { compressIfNeeded, compressFallback, COMPRESS_FAILURE_LIMIT } from "../context.mjs"
 import { search as memorySearch, docSearch } from "../memory.mjs"
 import { toOpenAISchema } from "../tools/index.mjs"
 import { loadSkills, formatSkillListing } from "../skills.mjs"
-import { specForModel } from "../config.mjs"
-import { join } from "node:path"
 import {
   escapeXml, repairHistory, listWorkDir, readonlyToolNames,
   collectGitContext, loadProjectInstructions, OUTLINE_INJECT_PREFIX,
@@ -47,13 +44,17 @@ export async function prepareRun(agent, input, callbacks, {
       }
     if (depth === 0) {
       const tree = listWorkDir(agent.cwd)
+      const platform = { win32: 'Windows', darwin: 'macOS', linux: 'Linux' }[process.platform] ?? process.platform
+      agent._sessionStart ??= new Date().toISOString()
       if (tree) {
-        agent.history.push({ role: "user", content: `[System reminder: working directory snapshot (${new Date().toISOString()}):\n<untrusted_cwd_listing>\n${escapeXml(tree)}\n</untrusted_cwd_listing>]`, transient: true })
+        agent.history.push({ role: "user", content: `[System reminder: OS: ${platform}. Working directory: ${agent.cwd}. Session start: ${agent._sessionStart}. Working directory snapshot:\n<untrusted_cwd_listing>\n${escapeXml(tree)}\n</untrusted_cwd_listing>]`, transient: true })
+      } else {
+        agent.history.push({ role: "user", content: `[System reminder: OS: ${platform}. Working directory: ${agent.cwd}. Session start: ${agent._sessionStart}.]`, transient: true })
       }
       if (agent.memory && !agent.history.some((m) => typeof m.content === "string" && m.content.startsWith(OUTLINE_INJECT_PREFIX))) {
         try {
           const { buildSummary } = await import("../tools/repomap.mjs")
-          const summary = buildSummary(agent.memory.db, agent.cwd)
+          const summary = await buildSummary(agent.memory.db, agent.cwd)
           if (summary && !summary.startsWith("(no indexed")) {
             agent.history.push({ role: "user", content: `${OUTLINE_INJECT_PREFIX}\n${summary}]`, transient: true })
           }
@@ -116,8 +117,8 @@ export async function prepareRun(agent, input, callbacks, {
   }
 
   // task/plan tools are injected with the main loop; subagent/skill/goal/verify only at top level
-  const { planTool, subagentTool, taskTool, skillTool, goalTool, verifyTool, recentChangesTool } = await import("../agent-tools.mjs")
-  const tools = [...agent.tools, taskTool, planTool, ...(depth === 0 ? [subagentTool, skillTool, goalTool, verifyTool, recentChangesTool] : [])]
+  const { planTool, subagentTool, taskTool, skillTool, goalTool, verifyTool, recentChangesTool, timerTool } = await import("../agent-tools.mjs")
+  const tools = [...agent.tools, taskTool, planTool, timerTool, ...(depth === 0 ? [subagentTool, skillTool, goalTool, verifyTool, recentChangesTool] : [])]
   const toolSchemas = tools.map(toOpenAISchema)
   const toolByName = new Map(tools.map((t) => [t.name, t]))
   agent._onTaskUpdate = callbacks.onTaskUpdate
@@ -130,9 +131,7 @@ export async function prepareRun(agent, input, callbacks, {
     : depth === 0
       ? `${base}\n\n${mainOverlay}`
       : base
-  const platform = { win32: 'Windows', darwin: 'macOS', linux: 'Linux' }[process.platform] ?? process.platform
-  agent._sessionStart ??= new Date().toISOString()
-  systemPrompt += `\n\nOS: ${platform}. Working directory: ${agent.cwd}. Session start: ${agent._sessionStart}.`
+
   const projectRules = await loadProjectInstructions(agent.cwd)
   if (projectRules) {
     systemPrompt += `\n\nProject instructions (follow these as project conventions):\n<untrusted_project_instructions>\n${escapeXml(projectRules)}\n</untrusted_project_instructions>`

package/src/agent-tools/subagent.mjs

@@ -100,7 +100,7 @@ export const subagentTool = {
         ? (name, args) => ctx.callbacks.onToolCall(`${relayPrefix}${name}`, args)
         : null,
     }
-    const childRunOpts = { depth: (ctx.depth ?? 0) + 1, maxTurns: DEFAULT_SUBAGENT_TURNS }
+    const childRunOpts = { depth: (ctx.depth ?? 0) + 1, maxTurns: ctx.agent?.config?.agent?.subagentTurns ?? DEFAULT_SUBAGENT_TURNS }
     let report = await runAgent(child, input, childOpts, childRunOpts)
 
     // Report too short = incomplete handoff: send back for expansion once (inspired by kimi-code's summaryPolicy: min 200 chars, retry 1 time).

package/src/agent-tools/timer.mjs

@@ -0,0 +1,41 @@
+/**
+ * timer tool: set a time budget for thinking before the agent insists on action.
+ * Call this when starting to analyze code or debug — it gives a bounded
+ * thinking window. When the timer fires, a system reminder is injected
+ * suggesting the model try running code, adding logs, or otherwise acting
+ * instead of continuing to think.
+ */
+export const timerTool = {
+  name: "timer",
+  description:
+    "Set a timer before you start analyzing code. When the timer fires, " +
+    "a system reminder will be injected suggesting you try running code or " +
+    "adding debug logs. Use this to enforce a thinking budget: you get " +
+    "N seconds to reason, then the timer reminds you to act.",
+  parameters: {
+    type: "object",
+    properties: {
+      seconds: {
+        type: "number",
+        description: "Thinking budget in seconds (default 30). Longer for complex reasoning, shorter for simple tasks.",
+      },
+      message: {
+        type: "string",
+        description: "Custom reminder message to show when time is up. Default: a suggestion to add debug logs or run the code.",
+      },
+    },
+    required: ["seconds"],
+  },
+  readonly: true,
+  sideEffectExempt: true,
+  execute(args, ctx) {
+    const seconds = args.seconds ?? 30
+    const expiresAt = Date.now() + seconds * 1000
+    const message = args.message || `⏰ Time's up (${seconds}s). Have you tried running the code, adding a console.log, or checking the output? Thinking more without data is guessing.`
+
+    ctx.agent._pendingTimers = ctx.agent._pendingTimers ?? []
+    ctx.agent._pendingTimers.push({ id: Date.now(), expiresAt, message })
+
+    return `Timer set for ${seconds} seconds. A reminder will appear when time is up.`
+  },
+}