tinker-agent 2.7.0 → 2.9.0

package/CHANGELOG.md

@@ -5,6 +5,58 @@ All notable user-facing changes to Tinker are documented here. The project follo
 
 ## [Unreleased]
 
+## [2.9.0] - 2026-09-05
+
+### Added
+
+- Add optional `sessionId` selection to `RecallSearch` and `RecallGet`, allowing
+  the agent to retrieve original history from another session, including a
+  Memory result's source session or another workspace under the same Tinker
+  home. Results identify their source session and workspace. External history is
+  read without resuming, repairing, or migrating the source session. Retrieved
+  text is sent to the current model provider and stored in the current session;
+  cross-workspace access does not show an additional confirmation dialog.
+- Add `offset` and `limit` to `TaskOutput` for reading consecutive, numbered lines
+  from non-PTY task logs. Omitting both preserves the head/tail preview; PTY tasks
+  continue to return the current terminal screen.
+
+### Changed
+
+- Enable automatic context swaps and prefix retirement as product defaults,
+  independent of model names, evaluation results, report availability, and tool
+  description hashes. Existing Recall capability, protocol, transaction, and
+  request-consistency checks remain enforced. Evaluation still measures model
+  behavior but no longer enables or disables runtime maintenance; this does not
+  guarantee reliable history retrieval by every model.
+- Clarify shell guidance so finite builds, tests, and checks run in the foreground
+  when their result is needed next and no independent work remains. Reserve
+  background execution for persistent processes or useful concurrent work, and
+  describe task tools in terms of their capabilities.
+
+### Fixed
+
+- Restore sessions containing follow-up messages submitted during an active turn
+  instead of rejecting turns with multiple user messages. Resumed timelines keep
+  follow-ups in their original order for completed and failed turns.
+- Include available exit codes, termination signals, and errors in `TaskOutput`
+  observations. Distinguish PTY screen snapshots from cumulative log statistics,
+  and clarify byte-limited log ranges and polling of a still-growing final line.
+
+## [2.8.0] - 2026-09-04
+
+### Changed
+
+- Refresh built-in tool descriptions so filesystem scope, local command
+  execution, waiting, and context swaps are stated more precisely to the model.
+- Remove obsolete implementation roadmaps and reconcile the remaining design
+  documents with the behavior already delivered by the runtime.
+
+### Fixed
+
+- Re-evaluate context pressure after a completed turn so automatic maintenance
+  still runs when closing the turn itself moves the active context above its
+  configured pressure threshold.
+
 ## [2.7.0] - 2026-09-04
 
 ### Added
@@ -346,7 +398,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.7.0...HEAD
+[Unreleased]: https://github.com/ishowshao/tinker/compare/v2.9.0...HEAD
+[2.9.0]: https://github.com/ishowshao/tinker/releases/tag/v2.9.0
+[2.8.0]: https://github.com/ishowshao/tinker/releases/tag/v2.8.0
 [2.7.0]: https://github.com/ishowshao/tinker/releases/tag/v2.7.0
 [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

package/README.md

@@ -19,7 +19,7 @@ This does not pretend that any model has infinite tokens or guarantee that it wi
   - `TaskList` / `TaskOutput` / `TaskInput` / `TaskStop` — Inspect, interact with, and stop long-running shell tasks
   - `WebSearch` — Search the web via Exa API
   - `WebFetch` — Fetch and refine web page content (local, browser, or Exa backend)
-  - `Recall` — Search or retrieve model-visible history from the current session
+  - `RecallSearch` / `RecallGet` — Search or retrieve model-visible history from the current session or an explicitly selected session
 - **Agent Skills**: Discover compatible `SKILL.md` packages at project and user
   scope, disclose their catalog progressively, and keep activated instructions
   durable across context compaction and session resume.
@@ -29,11 +29,65 @@ This does not pretend that any model has infinite tokens or guarantee that it wi
 - **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 support sessions designed to continue indefinitely 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 protocol-safe prefix retirement support sessions designed to continue indefinitely without pretending the model has infinite tokens.
 - **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.
 
+### Reading another session's history
+
+Both Recall tools accept an optional `sessionId` (a canonical session UUID).
+Omitting it keeps the current-session behavior. In the TUI or one-shot CLI, the
+agent can use a session ID you supply or a Memory result's `sourceSessionId`:
+
+```ts
+RecallSearch({ sessionId: sourceSessionId, query: "distinctive-anchor" })
+RecallGet({ sessionId: sourceSessionId, source: "ctx://message/<message-UUID>" })
+```
+
+Reuse the same `sessionId` for Get and subsequent pages. Search's
+`snapshot_through_ordinal`, ordinals and turn numbers belong to that session only.
+Results identify their source session and workspace. Missing, ambiguous, unsafe,
+unsupported or corrupt sessions return errors; Recall never silently switches
+back to the current session. Memory is not required.
+
+**Data scope:** explicit session selection can read other workspaces under the
+configured Tinker home (`TINKER_HOME` overrides the OS home). Retrieved text is
+sent to the **current model provider** and saved as a tool result in the **current
+session**, including when projects or providers differ. There is no additional
+cross-workspace confirmation dialog.
+
+External history uses short read-only SQLite snapshots, without resuming the
+source session, taking its execution lock, repairing indexes or migrating its
+schema. Only the current readable schema is supported. Active writers' committed
+history is readable; an open/interrupted turn may be incomplete. Historical
+instructions, Skills and authorizations are not activated, and content hashes
+prove storage consistency, not truth. Use Read/Grep to verify current facts.
+Original workspaces need not still exist. SQLite WAL reads can coordinate through
+SHM; read-only access does not promise that an active writer's directory remains
+byte-for-byte unchanged. See the
+[history access implementation](src/session/session-history-access.ts).
+
+### Automatic context maintenance and evaluation
+
+Automatic swap and prefix retirement are product defaults, independent of model
+names, evaluation scores, report availability, and tool-description hashes. Under
+context pressure, the runtime tries swap first and attempts retirement only when
+swap has no eligible candidates or insufficient candidates. Existing scheduling,
+protocol boundaries, cancellation, transaction, and request/surface consistency
+checks remain in force. Required Recall tools and the current retirement contract
+must be available; enabling a product policy does not bypass execution safety.
+There are no new user-facing switches or model allowlists.
+
+Evaluation measures model behavior; it does not enable or disable these features.
+New evaluation reports (`active-recall-qualification-v2`) contain metrics, gates,
+and provenance but no automation flags. Historical reports remain unchanged. The
+session-selection evaluation
+retains its measured failure: Search → Get missed the threshold even though all
+Recall-only tasks passed. Its old automation fields are legacy data, not runtime
+policy. The subsequent description cleanup has not been re-evaluated with a live
+model.
+
 ## Quick Start
 
 ### Install with your existing agent
@@ -398,9 +452,9 @@ pixels in total. Provider requests preserve smaller images and proportionally
 downscale larger images to a maximum 2048-pixel long edge. Context planning uses
 fixed local token buckets derived from the materialized dimensions and performs no
 independent token-estimator request. See the
-[`image token bucket design`](docs/image-token-bucket-estimation-design.md) and
-[`multimodal image input design`](docs/multimodal-image-input-design.md) for the
-complete fixed policy and persistence contract.
+[image input policy](src/image/image-input-policy.ts) and
+[image asset store](src/image/image-asset-store.ts) for the policy and storage
+implementations.
 
 `ViewImage(file_path)` is registered only when the selected profile declares both
 `inputModalities: ["text", "image"]` and
@@ -410,8 +464,8 @@ text-only for tool results. Relative paths stay inside the workspace, absolute
 paths may explicitly select an external local file, and symbolic links are
 rejected. Canonical history stores content-addressed image references rather than
 Base64, while stdout, TUI, Recall, and logs show deterministic text summaries.
-See the [`ViewImage tool design`](docs/view-image-tool-design.md) for the complete
-capability, persistence, provider, and compaction contract.
+See the [`ViewImage implementation`](src/tools/view-image.ts) for the tool's
+validation and execution logic.
 
 ### Built-in Slash Commands
 
@@ -476,9 +530,9 @@ turn. Built-in slash commands appear first in suggestions, followed by project
 commands in configuration order. Custom commands accept no arguments and cannot
 override built-ins. The optional configuration is loaded once at TUI startup,
 must be valid when present, and has a 1 MiB size limit. It is not loaded by the
-one-shot `tinker run` command. See
-[`docs/project-custom-slash-commands-design.md`](docs/project-custom-slash-commands-design.md)
-for the full contract.
+one-shot `tinker run` command. See the
+[project command loader](src/tui/project-slash-commands.ts) for configuration
+validation and loading behavior.
 
 ### Global Runtime Data
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tinker-agent",
-  "version": "2.7.0",
+  "version": "2.9.0",
   "description": "A personal coding agent with an interactive TUI and one-shot CLI.",
   "license": "Apache-2.0",
   "type": "module",
@@ -64,8 +64,9 @@
     "docs:generate": "bun scripts/render-public-contract-docs.ts --write",
     "docs:check": "bun scripts/render-public-contract-docs.ts --check",
     "tinker": "bun src/cli/index.ts",
-    "check": "bun run typecheck && bun run format:check && bun run lint && bun run docs:check && bun run test && bun run bench:smoke",
-    "check:fast": "bun run typecheck && bun run format:check && bun run lint && bun run test:fast",
+    "check": "bun run check:source-lines && bun run typecheck && bun run format:check && bun run lint && bun run docs:check && bun run test && bun run bench:smoke",
+    "check:fast": "bun run check:source-lines && bun run typecheck && bun run format:check && bun run lint && bun run test:fast",
+    "check:source-lines": "bun scripts/check-source-lines.ts",
     "format": "biome format --write .",
     "format:check": "biome format .",
     "lint": "eslint \"bin/**/*.js\" \"src/**/*.{ts,tsx}\" \"scripts/**/*.ts\" \"packages/**/*.ts\" --max-warnings=0",

package/src/agent/runtime-context-capabilities.ts

@@ -0,0 +1,19 @@
+import { CURRENT_RECALL_RETIREMENT_CONTRACT_VERSION } from "../context/recall-retirement-contract";
+import type { ToolRegistry } from "../tools/registry";
+
+/** Structural runtime prerequisites, not model qualification or description hashes. */
+export function assertContextMaintenanceCapabilities(
+  registry: Pick<ToolRegistry, "get">,
+  recallContractVersion: string,
+): void {
+  for (const name of ["RecallSearch", "RecallGet"]) {
+    if (registry.get(name) === undefined) {
+      throw new Error(`Context maintenance requires an executable ${name} tool.`);
+    }
+  }
+  if (recallContractVersion !== CURRENT_RECALL_RETIREMENT_CONTRACT_VERSION) {
+    throw new Error(
+      "Context maintenance requires the current Recall retirement contract.",
+    );
+  }
+}

package/src/agent/runtime-context-events.ts

@@ -0,0 +1,127 @@
+import {
+  type ContextCompactionResult,
+  type ContextRetirementResult,
+} from "../context/context-manager";
+import { type StoredContextSurfaceV8 } from "../context/context-surface";
+import type { ContextRevisionFinishedData } from "../events/types";
+import { type ModelClient } from "../model/model-client";
+
+export function assertPreparedMatchesSurface(
+  prepared: ReturnType<ModelClient["prepare"]>,
+  surface: StoredContextSurfaceV8,
+): void {
+  if (
+    prepared.requestConfigHash !== surface.requestConfigSha256 ||
+    prepared.toolSchemaHash !== surface.toolSchemaSha256 ||
+    prepared.requestMaxOutputTokens !== surface.requestMaxOutputTokens
+  ) {
+    throw new Error("Prepared model request does not match its context surface.");
+  }
+}
+
+export function elapsedMs(startedAt: number): number {
+  return Math.round((performance.now() - startedAt) * 100) / 100;
+}
+
+export function boundedContextErrorCode(code: string): string {
+  return /^[A-Za-z0-9_]+$/.test(code) && code.length <= 80
+    ? code
+    : "CONTEXT_COMPACTION_FAILED";
+}
+export function contextRevisionFinishedData(
+  result: ContextCompactionResult,
+  reason: "manual" | "runtime_pressure" | "model_directed" = "manual",
+  automationPolicyId?: string,
+): ContextRevisionFinishedData {
+  if (result.status === "unchanged") {
+    return {
+      strategy: "swap",
+      reason,
+      policyVersion: "swap-only-v1",
+      outcome: result.outcome,
+      baseRevisionNumber: result.revisionNumber,
+      addedOverrideCount: 0,
+      activeOverrideCount: result.activeOverrideCount,
+      originalObservationBytes: 0,
+      projectedObservationBytes: 0,
+      rawTokensBefore: result.rawTokensBefore,
+      guardedTokensBefore: result.guardedTokensBefore,
+      targetTokens: result.targetTokens,
+      durationMs: result.durationMs,
+      ...(automationPolicyId === undefined ? {} : { automationPolicyId }),
+    };
+  }
+  return {
+    strategy: "swap",
+    reason,
+    policyVersion: "swap-only-v1",
+    outcome: result.outcome,
+    baseRevisionNumber: result.previousRevisionNumber,
+    revisionNumber: result.revisionNumber,
+    addedOverrideCount: result.addedOverrideCount,
+    activeOverrideCount: result.activeOverrideCount,
+    originalObservationBytes: result.originalObservationBytes,
+    projectedObservationBytes: result.projectedObservationBytes,
+    rawTokensBefore: result.rawTokensBefore,
+    rawTokensAfter: result.rawTokensAfter,
+    guardedTokensBefore: result.guardedTokensBefore,
+    guardedTokensAfter: result.guardedTokensAfter,
+    targetTokens: result.targetTokens,
+    planHash: result.planHash,
+    durationMs: result.durationMs,
+    ...(automationPolicyId === undefined ? {} : { automationPolicyId }),
+  };
+}
+
+export function contextRetirementFinishedData(
+  result: ContextRetirementResult,
+  reason: "manual" | "runtime_pressure" = "manual",
+  automationPolicyId?: string,
+): ContextRevisionFinishedData {
+  if (result.status === "unchanged") {
+    return {
+      strategy: "retire_prefix",
+      reason,
+      policyVersion: "recall-first-retirement-v1",
+      outcome: result.outcome,
+      baseRevisionNumber: result.revisionNumber,
+      previousKeepFromOrdinal: result.keepFromOrdinal,
+      keepFromOrdinal: result.keepFromOrdinal,
+      retiredTurnCount: 0,
+      retiredFrameCount: 0,
+      retiredMessageCount: 0,
+      activeOverrideCount: result.activeOverrideCount,
+      guardedTokensBefore: result.guardedTokensBefore,
+      targetTokens: result.targetTokens,
+      planningDurationMs: result.planningDurationMs,
+      durationMs: result.durationMs,
+      ...(automationPolicyId === undefined ? {} : { automationPolicyId }),
+    };
+  }
+  return {
+    strategy: "retire_prefix",
+    reason,
+    policyVersion: "recall-first-retirement-v1",
+    outcome: result.outcome,
+    baseRevisionNumber: result.previousRevisionNumber,
+    revisionNumber: result.revisionNumber,
+    previousKeepFromOrdinal: result.previousKeepFromOrdinal,
+    keepFromOrdinal: result.keepFromOrdinal,
+    retiredTurnCount: result.retiredTurnCount,
+    retiredFrameCount: result.retiredFrameCount,
+    retiredMessageCount: result.retiredMessageCount,
+    activeOverrideCount: result.activeOverrideCount,
+    rawTokensBefore: result.rawTokensBefore,
+    rawTokensAfter: result.rawTokensAfter,
+    guardedTokensBefore: result.guardedTokensBefore,
+    guardedTokensAfter: result.guardedTokensAfter,
+    targetTokens: result.targetTokens,
+    planHash: result.planHash,
+    planningDurationMs: result.planningDurationMs,
+    validationDurationMs: result.validationDurationMs,
+    transactionDurationMs: result.transactionDurationMs,
+    activationDurationMs: result.activationDurationMs,
+    durationMs: result.durationMs,
+    ...(automationPolicyId === undefined ? {} : { automationPolicyId }),
+  };
+}