tinker-agent 2.5.0 → 2.6.0

package/CHANGELOG.md

@@ -5,6 +5,23 @@ 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
@@ -307,7 +324,8 @@ 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.5.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

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.5.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/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/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/session/session-clone-helpers.ts

@@ -0,0 +1,249 @@
+import path from "node:path";
+import { chmod, lstat, open, readFile } from "node:fs/promises";
+import { Database } from "bun:sqlite";
+import type { SessionId } from "../ids/runtime-id";
+import { stableJsonStringify } from "../model/model-request-preflight";
+import type { ProtocolContextView } from "../context/protocol-frame";
+import {
+  canonicalSequenceHash,
+  renderedMessageHash,
+} from "../context/compiled-context-hash";
+import { ContextRevisionCompiler } from "../context/context-revision-compiler";
+import type { AgentEvent } from "../events/types";
+import { renderObservationLogEvent } from "../events/observation-text-log";
+import type { CloneSessionFaultStage } from "./session-store-contracts";
+import { validateSecureFile } from "./session-store-filesystem";
+import {
+  decodeContextRevision,
+  decodeContextSurface,
+  decodeStoredSwapOverride,
+  decodeStoredToolCalls,
+  protocolPrefixView,
+} from "./session-store-record-codecs";
+
+export const SESSION_SCOPED_TABLES = [
+  "session_meta",
+  "turns",
+  "iterations",
+  "protocol_frames",
+  "messages",
+  "tool_results",
+  "context_surfaces",
+  "context_revisions",
+  "context_overrides",
+  "skill_activations",
+  "context_measurement_state",
+] as const;
+
+export function rekeyStoredToolCalls(
+  database: Database,
+  targetSessionId: SessionId,
+): void {
+  const rows = database
+    .query(
+      `SELECT message_id, tool_calls_json FROM messages
+       WHERE tool_calls_json IS NOT NULL ORDER BY ordinal`,
+    )
+    .all() as Array<{ message_id: string; tool_calls_json: string }>;
+  for (const row of rows) {
+    const calls = decodeStoredToolCalls(row.tool_calls_json).map((call) => ({
+      ...call,
+      sessionId: targetSessionId,
+    }));
+    database
+      .query("UPDATE messages SET tool_calls_json = ? WHERE message_id = ?")
+      .run(stableJsonStringify(calls), row.message_id);
+  }
+}
+
+export function rekeyProtocolView(
+  source: ProtocolContextView,
+  targetSessionId: SessionId,
+): ProtocolContextView {
+  return {
+    sessionId: targetSessionId,
+    faulted: source.faulted,
+    frames: source.frames.map((frame) => ({
+      ...frame,
+      sessionId: targetSessionId,
+    })),
+    messages: source.messages.map((message) => ({
+      ...message,
+      sessionId: targetSessionId,
+      ...(message.role === "assistant" && message.toolCalls !== undefined
+        ? {
+            toolCalls: message.toolCalls.map((call) => ({
+              ...call,
+              sessionId: targetSessionId,
+            })),
+          }
+        : {}),
+    })),
+    toolResults: source.toolResults.map((result) => ({
+      ...result,
+      sessionId: targetSessionId,
+    })),
+  };
+}
+
+export function rewriteCloneRevisionHashes(
+  database: Database,
+  canonical: ProtocolContextView,
+): void {
+  const surfaces = database
+    .query("SELECT * FROM context_surfaces")
+    .all()
+    .map(decodeContextSurface);
+  const surfacesById = new Map(surfaces.map((surface) => [surface.surfaceId, surface]));
+  const revisions = database
+    .query("SELECT * FROM context_revisions ORDER BY revision_number")
+    .all()
+    .map(decodeContextRevision);
+  const revisionNumberById = new Map(
+    revisions.map((revision) => [revision.revisionId, revision.revisionNumber]),
+  );
+  const overrides = database
+    .query(
+      `SELECT co.* FROM context_overrides co
+       JOIN context_revisions cr ON cr.revision_id = co.introduced_revision_id
+       ORDER BY cr.revision_number, co.ordinal`,
+    )
+    .all()
+    .map(decodeStoredSwapOverride);
+  const compiler = new ContextRevisionCompiler();
+  for (const revision of revisions) {
+    const surface = surfacesById.get(revision.surfaceId);
+    if (surface === undefined) {
+      throw new Error(`Cloned revision ${revision.revisionId} has no surface.`);
+    }
+    const activeOverrides = overrides.filter(
+      (override) =>
+        (revisionNumberById.get(override.introducedRevisionId) ??
+          Number.POSITIVE_INFINITY) <= revision.revisionNumber &&
+        override.ordinal >= revision.keepFromOrdinal,
+    );
+    const prefix = protocolPrefixView(canonical, revision.sourceThroughOrdinal);
+    const compiled = compiler.compileForIdentityRekey({
+      canonical: prefix,
+      revisionId: revision.revisionId,
+      activeOverrides,
+      keepFromOrdinal: revision.keepFromOrdinal,
+      surface,
+    });
+    database
+      .query(
+        `UPDATE context_revisions
+         SET canonical_sequence_sha256 = ?, rendered_message_sha256 = ?
+         WHERE revision_id = ?`,
+      )
+      .run(
+        canonicalSequenceHash(canonical, revision.sourceThroughOrdinal),
+        renderedMessageHash(compiled.entries, revision.sourceThroughOrdinal),
+        revision.revisionId,
+      );
+  }
+}
+
+export async function cloneDiagnosticFiles(input: {
+  sourceDirectory: string;
+  stagingDirectory: string;
+  sourceSessionId: SessionId;
+  targetSessionId: SessionId;
+  nextEventSequence: number;
+  faultInjector?: (stage: CloneSessionFaultStage) => void;
+}): Promise<void> {
+  const sourcePath = path.join(input.sourceDirectory, "events.jsonl");
+  try {
+    await lstat(sourcePath);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+      return;
+    }
+    throw error;
+  }
+  await validateSecureFile(sourcePath, input.sourceSessionId);
+
+  const bytes = await readFile(sourcePath);
+  const text = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+  const rawLines = text.split("\n");
+  if (rawLines.at(-1) === "") {
+    rawLines.pop();
+  }
+  const events: AgentEvent[] = [];
+  let previousSequence = 0;
+  for (const [index, line] of rawLines.entries()) {
+    if (line === "") {
+      throw new Error(`Session event log contains an empty line at ${index + 1}.`);
+    }
+    let value: unknown;
+    try {
+      value = JSON.parse(line);
+    } catch (error) {
+      throw new Error(`Session event log has invalid JSON at line ${index + 1}.`, {
+        cause: error,
+      });
+    }
+    if (!isEventEnvelope(value)) {
+      throw new Error(
+        `Session event log has an invalid envelope at line ${index + 1}.`,
+      );
+    }
+    if (value.sessionId !== input.sourceSessionId) {
+      throw new Error(`Session event log identity changed at line ${index + 1}.`);
+    }
+    if (value.eventSequence <= previousSequence) {
+      throw new Error(
+        `Session event sequence is not strictly increasing at line ${index + 1}.`,
+      );
+    }
+    if (value.eventSequence >= input.nextEventSequence) {
+      throw new Error(
+        `Session event sequence exceeds the canonical next counter at line ${index + 1}.`,
+      );
+    }
+    previousSequence = value.eventSequence;
+    events.push({ ...value, sessionId: input.targetSessionId });
+  }
+
+  const eventText = events.map((event) => JSON.stringify(event)).join("\n");
+  await writePrivateNewFile(
+    path.join(input.stagingDirectory, "events.jsonl"),
+    eventText === "" ? "" : `${eventText}\n`,
+  );
+  input.faultInjector?.("after_event_rewrite");
+  const observationText = events
+    .map((event) => renderObservationLogEvent(event))
+    .filter((block): block is string => block !== undefined)
+    .join("");
+  await writePrivateNewFile(
+    path.join(input.stagingDirectory, "observations.md"),
+    observationText,
+  );
+  input.faultInjector?.("after_observation_render");
+}
+
+function isEventEnvelope(value: unknown): value is AgentEvent {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    return false;
+  }
+  const record = value as Record<string, unknown>;
+  return (
+    typeof record.sessionId === "string" &&
+    Number.isSafeInteger(record.eventSequence) &&
+    Number(record.eventSequence) >= 1 &&
+    typeof record.timestamp === "string" &&
+    typeof record.type === "string" &&
+    record.data !== null &&
+    typeof record.data === "object"
+  );
+}
+
+async function writePrivateNewFile(filePath: string, content: string): Promise<void> {
+  const handle = await open(filePath, "wx", 0o600);
+  try {
+    await handle.writeFile(content, "utf8");
+  } finally {
+    await handle.close();
+  }
+  await chmod(filePath, 0o600);
+}