tinker-agent 2.4.0 → 2.5.0

package/CHANGELOG.md

@@ -5,6 +5,16 @@ All notable user-facing changes to Tinker are documented here. The project follo
 
 ## [Unreleased]
 
+## [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 +307,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.4.0...HEAD
+[Unreleased]: https://github.com/ishowshao/tinker/compare/v2.5.0...HEAD
+[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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tinker-agent",
-  "version": "2.4.0",
+  "version": "2.5.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/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/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;
     }
   }

package/src/tui/event-store.ts

@@ -170,6 +170,15 @@ export function reduceTuiProjection(
         }),
       );
     }
+    case "context.pressure_notice.sent":
+      return updateActiveTurn(state, event, policy, (turn) =>
+        appendTurnItem(turn, {
+          id: `turn-${event.turnId}-pressure-notice-${event.eventSequence}`,
+          label: "context notice",
+          text: `input pressure ${event.data.pressure} (${event.data.usedInputTokens}/${event.data.inputBudgetTokens} tokens) — model notified to self-manage`,
+          status: "text",
+        }),
+      );
     case "model.request.started":
       return updateActiveTurn(state, event, policy, (turn) =>
         event.data.attemptNumber === 1