tinker-agent 2.4.0 → 2.6.0

package/CHANGELOG.md

@@ -5,6 +5,33 @@ All notable user-facing changes to Tinker are documented here. The project follo
 
 ## [Unreleased]
 
+## [2.6.0] - 2026-09-03
+
+### Added
+
+- Show the installed Tinker version at the end of the interactive prompt status
+  bar.
+
+### Changed
+
+- Raise the default maximum agent-loop iterations per turn from 512 to 65,536,
+  allowing longer autonomous tasks without requiring configuration changes.
+
+### Fixed
+
+- Preserve brace expressions in Grep glob filters, so patterns such as
+  `**/*.{ts,tsx}` are passed to ripgrep intact.
+
+## [2.5.0] - 2026-09-03
+
+### Added
+
+- Proactively notify the model when input context reaches high or critical
+  pressure, prompting it to review and swap evictable historical tool
+  observations while keeping swapped content recoverable through Recall. The
+  runtime gives the model one iteration to act before automatic compaction
+  resumes, while critical pressure still triggers immediate maintenance.
+
 ## [2.4.0] - 2026-09-02
 
 ### Added
@@ -297,7 +324,9 @@ All notable user-facing changes to Tinker are documented here. The project follo
 - First formal npm release under the `tinker-agent` package name with the `tinker`
   executable.
 
-[Unreleased]: https://github.com/ishowshao/tinker/compare/v2.4.0...HEAD
+[Unreleased]: https://github.com/ishowshao/tinker/compare/v2.6.0...HEAD
+[2.6.0]: https://github.com/ishowshao/tinker/releases/tag/v2.6.0
+[2.5.0]: https://github.com/ishowshao/tinker/releases/tag/v2.5.0
 [2.4.0]: https://github.com/ishowshao/tinker/releases/tag/v2.4.0
 [2.3.0]: https://github.com/ishowshao/tinker/releases/tag/v2.3.0
 [2.2.0]: https://github.com/ishowshao/tinker/releases/tag/v2.2.0

package/README.md

@@ -1,8 +1,10 @@
 # Tinker
 
-**Tinker** is a personal coding agent — an interactive TUI (Terminal User Interface) and one-shot CLI tool that drives an LLM in an agent loop with file, search, shell, and MCP tools to read and modify a local workspace.
+**Tinker** is a personal coding-agent harness — an interactive TUI (Terminal User Interface) and one-shot CLI that drives an LLM in an agent loop with file, search, shell, and MCP tools to read and modify a local workspace.
 
-Built with [Bun](https://bun.sh) + TypeScript ESM, powered by [Ink](https://github.com/vadimdemedes/ink) (React for CLIs).
+**Tinker is designed for models that work over extremely long horizons — potentially as persistent agents that continue indefinitely, rather than as disposable chat sessions.** Its architecture treats the model's context window as a bounded working set, not as the source of truth. Immutable canonical history, durable sessions, protocol-safe recovery, deterministic context revisions, Recall-addressable cold state, and context-pressure management allow work to continue across compaction, process restarts, and context-window limits.
+
+This does not pretend that any model has infinite tokens or guarantee that it will recall every relevant fact. It means the harness is designed so that history remains durable and recoverable while the model repeatedly operates on a bounded, valid view of an ongoing session.
 
 ## Features
 
@@ -27,16 +29,36 @@ Built with [Bun](https://bun.sh) + TypeScript ESM, powered by [Ink](https://gith
 - **Turn cancellation**: Users can cancel an ongoing turn safely, with protocol-safe synthetic tool messages.
 - **Context metering**: Budget-aware context management with protocol validation before sending requests to the model.
 - **Deterministic context compaction**: Idle sessions can swap eligible historical tool output into Recall-addressable placeholders without calling the model.
-- **Infinite Context architecture**: Immutable canonical history, deterministic
-  context revisions, Recall-addressable cold state, and qualified prefix retirement
-  keep long-running sessions recoverable without pretending the model has infinite
-  tokens. See the [technical design](docs/infinite-context-technical-design.md).
+- **Infinite Context architecture**: Immutable canonical history, deterministic context revisions, Recall-addressable cold state, and qualified prefix retirement support sessions designed to continue indefinitely without pretending the model has infinite tokens. See the [technical design](docs/infinite-context-technical-design.md).
 - **Choice of models**: Uses an OpenAI-compatible Chat Completions transport with
   explicit model and context limits. Actual provider support must be established
   by a qualification matrix; transport compatibility alone is not a guarantee.
 
 ## Quick Start
 
+### Install with your existing agent
+
+If you already use a coding agent, you can ask it to read Tinker's documentation, install the package, and prepare a complete local configuration for you. Values it cannot safely determine can be left as clearly named placeholders; when setup is complete, the agent should tell you exactly which file to edit and what each placeholder expects.
+
+Copy and send this prompt to your existing agent:
+
+```text
+Open https://github.com/ishowshao/tinker and read Tinker's README and linked model-configuration documentation, then install and configure Tinker on this machine.
+
+Create a complete model profile configuration in an appropriate local file. Use clearly named placeholders for any required values that cannot be determined from the documentation or the current environment; do not invent API credentials, endpoint URLs, model names, or model limits. Configure Tinker to use that file, and verify the installation and configuration as far as possible without making a live model request.
+
+When finished, tell me:
+1. the exact path of the configuration file you created;
+2. every placeholder I still need to replace;
+3. what value each placeholder expects;
+4. any command I need to run after filling them in;
+5. the command to start Tinker.
+
+Do not ask me for the missing values during setup unless proceeding would be unsafe. Prefer creating a structurally complete configuration with placeholders so I can fill them in locally afterward.
+```
+
+### Install manually
+
 ```bash
 npm install --global tinker-agent
 
@@ -149,7 +171,7 @@ are required. Boolean environment values accept case-insensitive `true/false`,
 | `TINKER_STREAM` | Model | Env mode | No | Boolean | `true` | No | Use streaming transport for the selected model API. |
 | `TINKER_WEBFETCH_REFINE_MODEL` | Model | Env mode | No | Non-empty string | — | No | Optional WebFetch refiner model; currently must match TINKER_MODEL. |
 | `TINKER_WORKSPACE` | Workspace | All modes | No | Non-empty string | Process cwd | No | Workspace path. A leading ~ expands to the home directory; other relative paths resolve from the process cwd. |
-| `TINKER_MAX_ITERATIONS` | Workspace | All modes | No | Positive integer | `512` | No | Maximum agent-loop iterations per turn. |
+| `TINKER_MAX_ITERATIONS` | Workspace | All modes | No | Positive integer | `65536` | No | Maximum agent-loop iterations per turn. |
 | `EXA_API_KEY` | Tooling | All modes | No | Non-empty string | — | Yes | Enables WebSearch and the Exa WebFetch backend when set. |
 | `TINKER_MCP_TIMEOUT_MS` | Tooling | All modes | No | Positive integer | `60000` | No | MCP tool-call timeout in milliseconds. |
 | `TINKER_MCP_MAX_OBSERVATION_CHARS` | Tooling | All modes | No | Positive integer | `40000` | No | Maximum model-visible characters in one MCP result. |
@@ -513,6 +535,7 @@ Runtime data lives in ~/.tinker/ (sessions, bash tasks, assets), not in the repo
 - **Fast-fail**: Validate assumptions early and return clear errors close to the source. Structured failures allow the model to correct and retry.
 - **Model sees only text**: Tool execution results are rendered into readable text for the model. Raw result data with extra detail is kept for event logs and the TUI.
 - **Protocol safety**: All tool calls produce protocol-safe messages — even cancellations, fatal errors, or interruptions generate well-formed tool messages so the agent loop can continue.
+- **Long-horizon continuity**: Treat the context window as a replaceable working set over durable canonical history. Sessions should remain resumable and historically recoverable across compaction, interruption, and process restarts.
 - **Session durability**: Every turn, iteration, and tool call is committed to the SQLite ledger before the model is called, enabling reliable resume and history recall.
 
 ## Requirements

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tinker-agent",
-  "version": "2.4.0",
+  "version": "2.6.0",
   "description": "A personal coding agent with an interactive TUI and one-shot CLI.",
   "license": "Apache-2.0",
   "type": "module",

package/src/agent/context-pressure-notice.ts

@@ -0,0 +1,37 @@
+import type { ContextUsageSnapshot } from "./context-meter";
+
+export const CONTEXT_PRESSURE_NOTICE_PREFIX = "[tinker context notice]";
+
+export function isContextPressureNotice(message: {
+  readonly role: string;
+  readonly content?: unknown;
+}): boolean {
+  return (
+    message.role === "user" &&
+    typeof message.content === "string" &&
+    message.content.startsWith(CONTEXT_PRESSURE_NOTICE_PREFIX)
+  );
+}
+
+export function contextPressureNoticeText(input: {
+  usage: ContextUsageSnapshot;
+  toolPressure: "high" | "critical";
+  automaticSwapEnabled: boolean;
+}): string {
+  const base =
+    `${CONTEXT_PRESSURE_NOTICE_PREFIX} Input pressure is now "${input.toolPressure}" ` +
+    `(${input.usage.usedInputTokens} of ${input.usage.inputBudgetTokens} input tokens; ` +
+    `trigger at ${input.usage.triggerTokens}). ` +
+    "Call ContextSwapCandidates to review evictable historical tool observations, " +
+    "then ContextSwap to replace them with Recall-backed placeholders; " +
+    "swapped content stays recoverable through RecallGet.";
+  if (!input.automaticSwapEnabled) {
+    return (
+      `${base} Automatic compaction is disabled in this session, so pressure will ` +
+      "keep growing unless you swap observations or the turn ends."
+    );
+  }
+  return input.toolPressure === "critical"
+    ? `${base} Automatic compaction is running immediately because pressure exceeded the input budget.`
+    : `${base} Automatic compaction will resume next iteration if you do not act.`;
+}

package/src/agent/runtime-session.ts

@@ -118,7 +118,8 @@ import type {
   ToolCallIdentity,
   TurnIdentity,
 } from "./types";
-import { ContextMeter } from "./context-meter";
+import { ContextMeter, type ContextUsageSnapshot } from "./context-meter";
+import { contextPressureNoticeText } from "./context-pressure-notice";
 import { CURRENT_RECALL_RETIREMENT_CONTRACT_VERSION } from "../context/recall-retirement-contract";
 import {
   selectContextAutomation,
@@ -482,6 +483,7 @@ class DefaultRuntimeSession implements RuntimeSession {
   private pendingAutomaticContextMaintenance = false;
   private pendingModelDirectedSwap?: Set<MessageId>;
   private modelDirectedSwapLease = false;
+  private pressureNoticeSentThisTurn = false;
   private readonly skillCatalog: SkillCatalogSnapshot;
   private skillCoordinator = new SkillActivationCoordinator();
   private bashGuardMode: "guard" | "yolo";
@@ -2355,6 +2357,7 @@ class DefaultRuntimeSession implements RuntimeSession {
       this.pendingAutomaticContextMaintenance = false;
       this.pendingModelDirectedSwap = undefined;
       this.modelDirectedSwapLease = false;
+      this.pressureNoticeSentThisTurn = false;
       if (this.state === "executing") {
         this.state = "ready";
       }
@@ -2399,31 +2402,64 @@ class DefaultRuntimeSession implements RuntimeSession {
     }
     const pendingModelDirectedSwap = this.pendingModelDirectedSwap;
     this.pendingModelDirectedSwap = undefined;
-    if (pendingModelDirectedSwap === undefined && this.modelDirectedSwapLease) {
-      this.modelDirectedSwapLease = false;
-      return;
-    }
 
     const automation = this.requireContextAutomation();
-    if (pendingModelDirectedSwap === undefined && !automation.automaticSwapOnly) {
-      return;
-    }
     const manager = this.requireContextManager();
     this.pendingAutomaticContextMaintenance = false;
+
+    let suppressAutomaticSwap = this.modelDirectedSwapLease;
     this.modelDirectedSwapLease = false;
-    this.state = "maintaining_context";
-    try {
-      if (pendingModelDirectedSwap !== undefined) {
+
+    if (pendingModelDirectedSwap !== undefined) {
+      suppressAutomaticSwap = false;
+      this.state = "maintaining_context";
+      try {
         await this.performModelDirectedCompaction({
           turn: input.turn,
           consumedThroughOrdinal: input.consumedThroughOrdinal,
           ledger: input.ledger,
           messageIds: Object.freeze([...pendingModelDirectedSwap]),
         });
+      } finally {
+        if (this.state === "maintaining_context") {
+          this.state = "executing";
+        }
+      }
+    }
+
+    let measured: ContextUsageSnapshot | undefined;
+    if (
+      pendingModelDirectedSwap === undefined &&
+      (suppressAutomaticSwap ||
+        !this.pressureNoticeSentThisTurn ||
+        automation.automaticSwapOnly)
+    ) {
+      measured = manager.measureCurrent(input.turn.turnId, input.ledger);
+      if (!this.pressureNoticeSentThisTurn && measured.pressure !== "normal") {
+        await this.injectContextPressureNotice({
+          turn: input.turn,
+          ledger: input.ledger,
+          usage: measured,
+          automaticSwapEnabled: automation.automaticSwapOnly,
+        });
+        this.pressureNoticeSentThisTurn = true;
+        suppressAutomaticSwap = true;
       }
-      if (!automation.automaticSwapOnly) return;
+      if (measured.pressure === "blocked") {
+        // Emergency override: a lease or notice must never hold automatic
+        // compaction past the budget line; the next preflight would fail the
+        // turn before the model could act.
+        suppressAutomaticSwap = false;
+      }
+    }
+
+    if (suppressAutomaticSwap || !automation.automaticSwapOnly) {
+      return;
+    }
 
-      const usage = manager.measureCurrent(input.turn.turnId, input.ledger);
+    this.state = "maintaining_context";
+    try {
+      const usage = measured ?? manager.measureCurrent(input.turn.turnId, input.ledger);
       if (usage.pressure === "normal") return;
 
       const qualificationId = requireAutomationQualificationId(automation);
@@ -2530,6 +2566,39 @@ class DefaultRuntimeSession implements RuntimeSession {
     }
   }
 
+  private async injectContextPressureNotice(input: {
+    turn: TurnIdentity;
+    ledger: AgentTurnLedger;
+    usage: ContextUsageSnapshot;
+    automaticSwapEnabled: boolean;
+  }): Promise<void> {
+    const userMessage: UserMessage = Object.freeze({
+      role: "user",
+      content: contextPressureNoticeText({
+        usage: input.usage,
+        toolPressure: toolContextPressure(input.usage.pressure) as "high" | "critical",
+        automaticSwapEnabled: input.automaticSwapEnabled,
+      }),
+    });
+    const records = input.ledger.appendSteeringUserMessages([userMessage]);
+    const record = records[0];
+    if (records.length !== 1 || record === undefined) {
+      throw new Error("Pressure notice steering did not append exactly one message.");
+    }
+    await this.append({
+      type: "context.pressure_notice.sent",
+      ...input.turn,
+      data: {
+        usedInputTokens: input.usage.usedInputTokens,
+        inputBudgetTokens: input.usage.inputBudgetTokens,
+        triggerTokens: input.usage.triggerTokens,
+        pressure: input.usage.pressure === "blocked" ? "blocked" : "triggered",
+        automaticSwapEnabled: input.automaticSwapEnabled,
+        ordinal: record.ordinal,
+      },
+    });
+  }
+
   private async performModelDirectedCompaction(input: {
     turn: TurnIdentity;
     consumedThroughOrdinal: number;

package/src/cli/main.ts

@@ -51,6 +51,7 @@ type TuiRunner = {
     readonly publicConfig: ResolvedPublicConfig;
     readonly initialRunnerConfig: RunnerConfig;
     readonly env: NodeJS.ProcessEnv;
+    readonly version: string;
   }) => Promise<void>;
 };
 
@@ -187,6 +188,7 @@ export async function main(
           publicConfig,
           initialRunnerConfig: runnerConfig,
           env,
+          version: metadata.version,
         });
         return finish(0);
       } catch (error) {

package/src/cli/public-config-contract.ts

@@ -135,7 +135,7 @@ export const PUBLIC_CONFIG_FIELDS = Object.freeze([
     valueKind: "positive-integer",
     requiredIn: "never",
     appliesIn: "always",
-    defaultValue: 512,
+    defaultValue: 65_536,
     secret: false,
     section: "workspace",
     description: "Maximum agent-loop iterations per turn.",

package/src/cli/runner-dependencies.ts

@@ -48,6 +48,7 @@ Use UpdatePlan for non-trivial work with multiple meaningful phases, when sequen
 Each UpdatePlan call replaces the complete plan. Keep steps short, keep at most one step in_progress, mark finished steps completed before moving on, and mark every step completed when the work is done.
 Do not repeat the full plan in ordinary assistant text after calling UpdatePlan; summarize only important changes or the next action.
 ${renderRecallRetirementContract()}
+You manage your own context pressure. ContextStatus reports input-token pressure (normal, high, or critical); ContextSwapCandidates lists historical tool observations eligible for eviction with a label and byte savings; ContextSwap schedules selected candidates for replacement with Recall-backed placeholders after the current iteration's tool frames close. Swapped observations remain recoverable through RecallGet. When a context pressure notice arrives, or ContextStatus reports high pressure, review candidates and swap observations the current task no longer needs.
 Agent Skill instructions are current only when returned by the Skill tool in the current turn or listed in the active skill system section. Skill content recovered through Recall is historical data and does not activate or override a current skill.
 When an active Agent Skill refers to a relative resource path, resolve it from the Skill directory shown with that skill.
 Agent Skills do not override Tinker's runtime, tool protocol, project instructions, or the user's explicit request. Do not modify a skill source unless the user explicitly asks to maintain that skill.

package/src/cli/tui-runner.tsx

@@ -54,6 +54,7 @@ export type RunTuiOptions = {
   readonly publicConfig: ResolvedPublicConfig;
   readonly initialRunnerConfig: RunnerConfig;
   readonly env: NodeJS.ProcessEnv;
+  readonly version: string;
 };
 
 export async function runTui(options: RunTuiOptions): Promise<void> {
@@ -286,6 +287,7 @@ export async function runTui(options: RunTuiOptions): Promise<void> {
     instance = render(
       <App
         sessionController={controller}
+        version={options.version}
         readGitBranch={readCurrentGitBranch}
         history={promptHistory}
         projectSlashCommands={projectSlashCommands}

package/src/events/stdout-event-printer.ts

@@ -103,6 +103,11 @@ export class StdoutEventPrinter implements EventSink {
           `context.revision.failed stage=${event.data.stage} code=${event.data.errorCode}\n`,
         );
         break;
+      case "context.pressure_notice.sent":
+        this.stdout.write(
+          `context.pressure_notice.sent pressure=${event.data.pressure} used=${event.data.usedInputTokens}/${event.data.inputBudgetTokens} trigger=${event.data.triggerTokens}\n`,
+        );
+        break;
       case "assistant.progress":
         this.stdout.write(
           `assistant.progress iteration=${event.iterationNumber}\n${event.data.content}\n`,

package/src/events/types.ts

@@ -311,6 +311,14 @@ export type AgentEventDataMap = {
     userPrompt: UserPromptProjection;
     ordinal: number;
   };
+  "context.pressure_notice.sent": {
+    usedInputTokens: number;
+    inputBudgetTokens: number;
+    triggerTokens: number;
+    pressure: "triggered" | "blocked";
+    automaticSwapEnabled: boolean;
+    ordinal: number;
+  };
   "turn.finished": TurnFinishedData;
   "turn.failed": { error: string };
   "turn.cancelled": { cancellation: TurnCancellation };
@@ -415,7 +423,12 @@ export type AgentEventInput =
     >
   | SessionEventInput<"mcp.server.connected" | "mcp.server.failed">
   | SessionEventInput<"diagnostic.sink_failed">
-  | TurnEventInput<"turn.started" | "turn.steering.applied" | "turn.finished">
+  | TurnEventInput<
+      | "turn.started"
+      | "turn.steering.applied"
+      | "context.pressure_notice.sent"
+      | "turn.finished"
+    >
   | (
       | TurnEventInput<"turn.failed" | "turn.cancelled">
       | IterationEventInput<"turn.failed" | "turn.cancelled">

package/src/model/fake-model-client.ts

@@ -1,5 +1,6 @@
 import { createHash } from "node:crypto";
 import { appendFile } from "node:fs/promises";
+import { isContextPressureNotice } from "../agent/context-pressure-notice";
 import type { AgentMessage, AssistantMessage } from "../agent/types";
 import { toolResultDisplayText } from "../agent/tool-result-content";
 import { cancellationError } from "../agent/turn-cancellation";
@@ -1333,7 +1334,8 @@ function waitForCancellation(signal: AbortSignal): Promise<ModelRequestOutput> {
 
 function lastUserMessage(messages: AgentMessage[]): string {
   const users = messages.filter(
-    (message): message is { role: "user"; content: string } => message.role === "user",
+    (message): message is { role: "user"; content: string } =>
+      message.role === "user" && !isContextPressureNotice(message),
   );
   return users.at(-1)?.content ?? "";
 }
@@ -1451,7 +1453,11 @@ function lastMessageIndex(
   role: AgentMessage["role"],
 ): number {
   for (let index = messages.length - 1; index >= 0; index -= 1) {
-    if (messages[index]?.role === role) {
+    const message = messages[index];
+    if (message === undefined || isContextPressureNotice(message)) {
+      continue;
+    }
+    if (message.role === role) {
       return index;
     }
   }