tinker-agent 1.10.1 → 2.0.0

package/CHANGELOG.md

@@ -5,6 +5,30 @@ All notable user-facing changes to Tinker are documented here. The project follo
 
 ## [Unreleased]
 
+## [2.0.0] - 2026-08-20
+
+### Changed
+
+- Estimate image input locally with deterministic size buckets instead of a
+  provider-side token-estimation request. Images are normalized for orientation
+  and provider limits before estimation and upload, keeping preflight accounting
+  aligned with the payload sent to the model.
+
+### Removed
+
+- Remove the `tokenEstimator` model-profile setting. Existing image profiles must
+  delete that field; sessions created under the previous image policy remain
+  inspectable but cannot be resumed for execution.
+
+## [1.11.0] - 2026-08-15
+
+### Added
+
+- Allow text follow-up prompts to be queued while a turn is running. Follow-ups
+  are applied safely after a complete tool batch or handed off to a new turn
+  after a final response, while preserving canonical session history and TUI
+  continuity.
+
 ## [1.10.1] - 2026-08-15
 
 ### Added
@@ -199,7 +223,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/v1.10.1...HEAD
+[Unreleased]: https://github.com/ishowshao/tinker/compare/v2.0.0...HEAD
+[2.0.0]: https://github.com/ishowshao/tinker/releases/tag/v2.0.0
+[1.11.0]: https://github.com/ishowshao/tinker/releases/tag/v1.11.0
 [1.10.1]: https://github.com/ishowshao/tinker/releases/tag/v1.10.1
 [1.9.0]: https://github.com/ishowshao/tinker/releases/tag/v1.9.0
 [1.8.0]: https://github.com/ishowshao/tinker/releases/tag/v1.8.0

package/README.md

@@ -194,7 +194,6 @@ Profile fields:
 | `includeReasoningContent` | No | JSON boolean | `false` | No | Replay provider reasoning_content in Chat Completions history; ignored by Responses. |
 | `stream` | No | JSON boolean | `true` | No | Use streaming transport for the selected model API. |
 | `inputModalities` | No | Normalized modality array | `["text"]` | No | Accepted model input modalities; normalizes to ["text"] or ["text", "image"]. |
-| `tokenEstimator` | With image | Object | — | Yes | Independent token estimator required for image profiles. |
 
 `reasoning` fields:
 
@@ -205,17 +204,6 @@ Profile fields:
 
 The optional `reasoning` object declares provider-specific effort values. Efforts must be unique non-whitespace strings, `reset` is reserved by the TUI command, and `defaultEffort` must appear in `supportedEfforts`. Omitting `reasoning` sends no effort parameter and disables `/reasoning` for that profile.
 
-`tokenEstimator` fields:
-
-| Field | Type / constraint | Secret | Description |
-| --- | --- | --- | --- |
-| `kind` | Literal `"moonshot-estimate-token-count-v1"` | No | Estimator protocol discriminator. |
-| `model` | Non-empty string | No | Estimator model name. |
-| `apiBase` | Non-empty string | No | Estimator API base URL. |
-| `apiKey` | Non-empty string | Yes | Estimator API credential. |
-| `timeoutMs` | Integer 1000–60000 | No | Estimator request timeout in milliseconds. |
-| `maxRetries` | Literal `0` | No | Estimator retry count; retries are disabled. |
-
 Text-only profile example:
 
 ```json
@@ -271,15 +259,7 @@ Image-capable profile example:
       "inputModalities": [
         "text",
         "image"
-      ],
-      "tokenEstimator": {
-        "kind": "moonshot-estimate-token-count-v1",
-        "model": "example-token-estimator",
-        "apiBase": "https://estimator.example.com/v1",
-        "apiKey": "your-estimator-api-key",
-        "timeoutMs": 30000,
-        "maxRetries": 0
-      }
+      ]
     }
   }
 }
@@ -370,7 +350,7 @@ configured profile.
 ### Image Input
 
 Image attachment is enabled only for a profile whose `inputModalities` explicitly
-includes `image` and which supplies a valid `tokenEstimator`. In the interactive
+includes `image`. In the interactive
 TUI, type `@` and select a file that is inside the workspace and visible to the
 workspace search rules. One-shot commands, clipboard image bytes, remote URLs, and
 files outside or ignored by the workspace search are not supported.
@@ -378,7 +358,11 @@ files outside or ignored by the workspace search are not supported.
 Tinker accepts PNG (not APNG), JPEG, and static WebP. It rejects GIF, animated
 WebP, and other formats. A message and provider request may contain at most eight
 images; each image may be at most 20 MiB, 4096 pixels on either edge, and 8,847,360
-pixels in total. See the
+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.
 

package/package.json

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

package/src/agent/context-meter.ts

@@ -2,13 +2,8 @@ import type { ModelContextBudget } from "../model/model-context-profile";
 import type {
   ModelRequestOutput,
   ModelUsage,
-  MaterializedModelRequest,
   PreparedModelRequest,
 } from "../model/model-client";
-import type {
-  InputTokenEstimate,
-  InputTokenEstimator,
-} from "../model/input-token-estimator";
 import {
   assertContextBudget,
   contextPressure,
@@ -68,7 +63,6 @@ export class ContextMeter {
   private anchor?: MeasuredContextAnchor;
   private lastProviderUsage?: ModelUsage;
   private calibrationIdentity?: string;
-  private readonly providerEstimateCache = new Map<string, InputTokenEstimate>();
 
   constructor(
     private readonly budget: ModelContextBudget,
@@ -129,13 +123,14 @@ export class ContextMeter {
     let guardedDeltaTokens: number | undefined;
     if (anchor === undefined) {
       source = "estimated_full";
-      usedInputTokens = Math.ceil(rawFullEstimate.totalTokens * correctionFactor);
+      usedInputTokens = guardedEstimate(rawFullEstimate, correctionFactor);
     } else {
       source = "measured_plus_estimated_delta";
-      rawDeltaTokens = estimatePromptSegments(
+      const rawDelta = estimatePromptSegments(
         prepared.promptSegments.slice(anchor.segmentCount),
-      ).totalTokens;
-      guardedDeltaTokens = Math.ceil(rawDeltaTokens * correctionFactor);
+      );
+      rawDeltaTokens = rawDelta.totalTokens;
+      guardedDeltaTokens = guardedEstimate(rawDelta, correctionFactor);
       usedInputTokens = anchor.totalTokens + guardedDeltaTokens;
     }
 
@@ -217,62 +212,6 @@ export class ContextMeter {
     };
   }
 
-  applyProviderEstimate(
-    prepared: PreparedModelRequest,
-    estimate: {
-      inputTokens: number;
-      coverage: "messages" | "full_request";
-    },
-  ): ContextUsageSnapshot {
-    if (!Number.isSafeInteger(estimate.inputTokens) || estimate.inputTokens < 0) {
-      throw new Error("Provider input estimate must be a non-negative safe integer.");
-    }
-    const local = this.measure(prepared);
-    const measurement = this.measurements.get(prepared)!;
-    const guardedTools =
-      estimate.coverage === "messages"
-        ? Math.ceil(
-            measurement.rawFullEstimate.toolSchemaTokens * local.correctionFactor,
-          )
-        : 0;
-    const providerGuarded = estimate.inputTokens + guardedTools;
-    if (providerGuarded <= local.usedInputTokens) {
-      return local;
-    }
-    const snapshot: ContextUsageSnapshot = {
-      ...local,
-      usedInputTokens: providerGuarded,
-      source: "provider_estimated",
-      pressure: contextPressure(providerGuarded, this.budget),
-    };
-    this.measurements.set(prepared, {
-      rawFullEstimate: measurement.rawFullEstimate,
-      snapshot,
-    });
-    return snapshot;
-  }
-
-  async estimateProviderInput(
-    prepared: MaterializedModelRequest,
-    estimator: InputTokenEstimator,
-    options: { signal: AbortSignal },
-  ): Promise<InputTokenEstimate> {
-    options.signal.throwIfAborted();
-    const key = providerEstimateCacheKey(
-      prepared,
-      estimator.compatibility.coverageVersion,
-    );
-    const cached = this.providerEstimateCache.get(key);
-    if (cached !== undefined) {
-      return cached;
-    }
-    const estimate = await estimator.estimate(prepared, options);
-    options.signal.throwIfAborted();
-    const frozen = Object.freeze({ ...estimate });
-    this.providerEstimateCache.set(key, frozen);
-    return frozen;
-  }
-
   assertWithinBudget(snapshot: ContextUsageSnapshot): void {
     assertContextBudget({
       usedInputTokens: snapshot.usedInputTokens,
@@ -295,7 +234,6 @@ export class ContextMeter {
       this.lastProviderUsage = undefined;
       this.measurements = new WeakMap();
       this.calibration.clear();
-      this.providerEstimateCache.clear();
       this.calibrationIdentity = nextIdentity;
       throw new Error(
         "Context revision changed the request configuration or tool schema.",
@@ -304,7 +242,6 @@ export class ContextMeter {
     this.anchor = undefined;
     this.lastProviderUsage = undefined;
     this.measurements = new WeakMap();
-    this.providerEstimateCache.clear();
     this.calibrationIdentity = nextIdentity;
   }
 
@@ -315,7 +252,6 @@ export class ContextMeter {
     this.measurements = new WeakMap();
     this.calibration.clear();
     this.calibrationIdentity = undefined;
-    this.providerEstimateCache.clear();
   }
 
   private usableAnchor(
@@ -330,10 +266,7 @@ export class ContextMeter {
       anchor.requestConfigHash !== prepared.requestConfigHash ||
       anchor.toolSchemaHash !== prepared.toolSchemaHash ||
       anchor.segmentCount > prepared.promptSegments.length ||
-      prefixHashes[anchor.segmentCount] !== anchor.prefixHash ||
-      prepared.promptSegments
-        .slice(anchor.segmentCount)
-        .some((segment) => (segment.media?.length ?? 0) > 0)
+      prefixHashes[anchor.segmentCount] !== anchor.prefixHash
     ) {
       this.anchor = undefined;
       return undefined;
@@ -359,18 +292,14 @@ export class ContextMeter {
   }
 }
 
-function providerEstimateCacheKey(
-  prepared: PreparedModelRequest,
-  coverageVersion: string,
-): string {
-  return [
-    prepared.requestConfigHash,
-    prepared.toolSchemaHash,
-    lastPromptPrefixHash(
-      promptPrefixHashes(prepared.requestConfigHash, prepared.promptSegments),
-    ),
-    coverageVersion,
-  ].join(":");
+function guardedEstimate(
+  breakdown: RawContextBreakdown,
+  correctionFactor: number,
+): number {
+  return (
+    Math.ceil(breakdown.textAndProtocolTokens * correctionFactor) +
+    breakdown.imageTokens
+  );
 }
 
 function assertMeasuredContextAnchor(anchor: MeasuredContextAnchor): void {

package/src/agent/loop.ts

@@ -175,20 +175,7 @@ export async function runAgent(input: RunAgentInput): Promise<RunAgentResult> {
             assetStore: input.assetStore,
             signal: input.signal,
           });
-          if (preflight.source === "measured_plus_estimated_delta") {
-            preflight = input.contextMeter.measure(request);
-          } else {
-            const estimator = input.model.inputTokenEstimator;
-            if (estimator === undefined) {
-              throw new Error("Image model request has no input token estimator.");
-            }
-            const estimate = await input.contextMeter.estimateProviderInput(
-              request as MaterializedModelRequest,
-              estimator,
-              { signal: input.signal },
-            );
-            preflight = input.contextMeter.applyProviderEstimate(request, estimate);
-          }
+          preflight = input.contextMeter.measure(request);
           input.contextMeter.assertWithinBudget(preflight);
           await input.runtimeSession.append({
             type: "context.usage.updated",
@@ -498,6 +485,10 @@ export async function runAgent(input: RunAgentInput): Promise<RunAgentResult> {
       }
     }
 
+    await input.runtimeSession.applyQueuedSteering?.({
+      turn: input.turn,
+      ledger: input.ledger,
+    });
     await input.runtimeSession.append({
       type: "agent.iteration.finished",
       ...iteration,

package/src/agent/runtime-session.ts

@@ -139,6 +139,18 @@ export type AcceptedTurn = {
   readonly completion: Promise<RunAgentResult>;
 };
 
+export type PromptSchedulerSnapshot = {
+  readonly state: "idle" | "running";
+  readonly activeTurnId?: TurnIdentity["turnId"];
+  readonly pendingCount: number;
+};
+
+export type QueueFollowUpResult = {
+  readonly kind: "queued";
+  readonly pendingCount: number;
+  readonly activeTurnId?: TurnIdentity["turnId"];
+};
+
 export type SessionDisposeReason =
   | { type: "oneshot_complete" }
   | { type: "tui_exit" }
@@ -167,6 +179,9 @@ export type RuntimeSession = {
   ): Promise<void>;
   admitTurn(input: ExecuteTurnInput): Promise<AcceptedTurn>;
   executeTurn(input: ExecuteTurnInput): Promise<RunAgentResult>;
+  promptScheduler(): PromptSchedulerSnapshot;
+  subscribePromptScheduler(listener: () => void): () => void;
+  queueFollowUp(userMessage: UserMessage): QueueFollowUpResult;
   compactContext(): Promise<ContextCompactionResult>;
   retireContext(): Promise<ContextRetirementResult>;
   undoLatestFileMutationTurn(): Promise<TurnUndoResult>;
@@ -227,6 +242,10 @@ export type RuntimeSessionContext = {
     consumedThroughOrdinal: number;
     ledger: AgentTurnLedger;
   }): Promise<void>;
+  applyQueuedSteering?(input: {
+    turn: TurnIdentity;
+    ledger: AgentTurnLedger;
+  }): Promise<number>;
 };
 
 export type ContextSurfaceRefreshSummary = {
@@ -354,10 +373,18 @@ type RuntimeSessionState =
   | "disposed";
 
 type ActiveTurn = {
+  turn: TurnIdentity;
   controller: AbortController;
   completion: Promise<RunAgentResult>;
 };
 
+type QueuedPrompt = {
+  readonly userMessage: UserMessage;
+};
+
+const MAX_QUEUED_PROMPTS = 8;
+const MAX_QUEUED_PROMPT_TEXT_BYTES = 64 * 1024;
+
 type ActiveAdmission = {
   controller: AbortController;
   settled: Promise<void>;
@@ -415,6 +442,13 @@ class DefaultRuntimeSession implements RuntimeSession {
   private ledger?: SessionLedger;
   private activeAdmission?: ActiveAdmission;
   private activeTurn?: ActiveTurn;
+  private executionChainRunning = false;
+  private readonly queuedPrompts: QueuedPrompt[] = [];
+  private promptSchedulerSnapshot: PromptSchedulerSnapshot = Object.freeze({
+    state: "idle",
+    pendingCount: 0,
+  });
+  private readonly promptSchedulerListeners = new Set<() => void>();
   private activeContextRevision?: Promise<
     ContextCompactionResult | ContextRetirementResult
   >;
@@ -494,6 +528,7 @@ class DefaultRuntimeSession implements RuntimeSession {
       prepareModelDispatch: (dispatch) => this.prepareModelDispatch(dispatch),
       maintainContextAfterIteration: (maintenance) =>
         this.performActiveTurnContextMaintenance(maintenance),
+      applyQueuedSteering: (steering) => this.applyQueuedSteering(steering),
     };
   }
 
@@ -546,11 +581,6 @@ class DefaultRuntimeSession implements RuntimeSession {
         contextProfile: input.contextProfile,
         messageProtocol: input.modelClient.messageProtocol,
         inputModalities: input.modelClient.inputModalities ?? ["text"],
-        ...(input.modelClient.inputTokenEstimator === undefined
-          ? {}
-          : {
-              tokenEstimator: input.modelClient.inputTokenEstimator.compatibility,
-            }),
       });
       if (input.selection.mode === "resume") {
         store.assertSessionCompatibility(compatibility);
@@ -1509,11 +1539,71 @@ class DefaultRuntimeSession implements RuntimeSession {
     }
   }
 
+  promptScheduler(): PromptSchedulerSnapshot {
+    return this.promptSchedulerSnapshot;
+  }
+
+  subscribePromptScheduler(listener: () => void): () => void {
+    this.promptSchedulerListeners.add(listener);
+    return () => this.promptSchedulerListeners.delete(listener);
+  }
+
+  queueFollowUp(userMessage: UserMessage): QueueFollowUpResult {
+    if (!this.executionChainRunning) {
+      throw new Error("Cannot queue a follow-up while no execution chain is running.");
+    }
+    validateUserMessage(userMessage);
+    if (userMessage.attachments !== undefined) {
+      throw new Error("Active-turn follow-ups do not support image attachments.");
+    }
+    if (this.queuedPrompts.length >= MAX_QUEUED_PROMPTS) {
+      throw new Error(`At most ${MAX_QUEUED_PROMPTS} follow-ups may be queued.`);
+    }
+    const queuedBytes = this.queuedPrompts.reduce(
+      (total, entry) => total + Buffer.byteLength(entry.userMessage.content, "utf8"),
+      0,
+    );
+    const nextBytes = Buffer.byteLength(userMessage.content, "utf8");
+    if (queuedBytes + nextBytes > MAX_QUEUED_PROMPT_TEXT_BYTES) {
+      throw new Error("Queued follow-ups exceed the 64 KiB text limit.");
+    }
+    this.queuedPrompts.push({
+      userMessage: Object.freeze({ ...userMessage }),
+    });
+    this.notifyPromptScheduler();
+    return Object.freeze({
+      kind: "queued",
+      pendingCount: this.queuedPrompts.length,
+      ...(this.activeTurn === undefined
+        ? {}
+        : { activeTurnId: this.activeTurn.turn.turnId }),
+    });
+  }
+
   async executeTurn(input: ExecuteTurnInput): Promise<RunAgentResult> {
     return (await this.admitTurn(input)).completion;
   }
 
   async admitTurn(input: ExecuteTurnInput): Promise<AcceptedTurn> {
+    if (this.executionChainRunning) {
+      throw new Error(
+        `Cannot execute a turn while RuntimeSession is ${this.state}; a prompt chain is already executing.`,
+      );
+    }
+    this.executionChainRunning = true;
+    this.notifyPromptScheduler();
+    try {
+      const accepted = await this.admitSingleTurn(input);
+      const completion = this.continueExecutionChain(accepted.completion, input.signal);
+      return Object.freeze({ ...accepted, completion });
+    } catch (error) {
+      this.executionChainRunning = false;
+      this.notifyPromptScheduler();
+      throw error;
+    }
+  }
+
+  private async admitSingleTurn(input: ExecuteTurnInput): Promise<AcceptedTurn> {
     if (this.state !== "ready") {
       throw new Error(`Cannot execute a turn while RuntimeSession is ${this.state}.`);
     }
@@ -1546,24 +1636,6 @@ class DefaultRuntimeSession implements RuntimeSession {
         { assetStore: this.assetStore, signal: controller.signal },
       );
       admissionSnapshot = this.contextMeter.measure(admissionPrepared);
-      if (
-        prepared.mediaOccurrenceCount > 0 &&
-        admissionSnapshot.source !== "measured_plus_estimated_delta"
-      ) {
-        const estimator = this.input.modelClient.inputTokenEstimator;
-        if (estimator === undefined) {
-          throw new Error("Image model request has no input token estimator.");
-        }
-        const estimate = await this.contextMeter.estimateProviderInput(
-          admissionPrepared,
-          estimator,
-          { signal: controller.signal },
-        );
-        admissionSnapshot = this.contextMeter.applyProviderEstimate(
-          admissionPrepared,
-          estimate,
-        );
-      }
       this.contextMeter.assertWithinBudget(admissionSnapshot);
       controller.signal.throwIfAborted();
       const turn = this.stageTurn(input.userMessage);
@@ -1586,7 +1658,8 @@ class DefaultRuntimeSession implements RuntimeSession {
           usage: admissionSnapshot,
         },
       });
-      this.activeTurn = { controller, completion };
+      this.activeTurn = { turn, controller, completion };
+      this.notifyPromptScheduler();
       return Object.freeze({
         turnId: turn.turnId,
         userMessage: input.userMessage,
@@ -1608,6 +1681,79 @@ class DefaultRuntimeSession implements RuntimeSession {
     }
   }
 
+  private async continueExecutionChain(
+    initialCompletion: Promise<RunAgentResult>,
+    signal: AbortSignal,
+  ): Promise<RunAgentResult> {
+    let completion = initialCompletion;
+    let finalResult: RunAgentResult;
+    try {
+      for (;;) {
+        finalResult = await completion;
+        if (finalResult.status !== "completed" || this.queuedPrompts.length === 0) {
+          return finalResult;
+        }
+        const next = this.queuedPrompts[0];
+        if (next === undefined) {
+          return finalResult;
+        }
+        const accepted = await this.admitSingleTurn({
+          userMessage: next.userMessage,
+          signal,
+        });
+        this.queuedPrompts.shift();
+        this.notifyPromptScheduler();
+        completion = accepted.completion;
+      }
+    } finally {
+      this.queuedPrompts.splice(0);
+      this.executionChainRunning = false;
+      this.notifyPromptScheduler();
+    }
+  }
+
+  private notifyPromptScheduler(): void {
+    this.promptSchedulerSnapshot = Object.freeze({
+      state: this.executionChainRunning ? "running" : "idle",
+      ...(this.activeTurn === undefined
+        ? {}
+        : { activeTurnId: this.activeTurn.turn.turnId }),
+      pendingCount: this.queuedPrompts.length,
+    });
+    for (const listener of this.promptSchedulerListeners) listener();
+  }
+
+  private async applyQueuedSteering(input: {
+    turn: TurnIdentity;
+    ledger: AgentTurnLedger;
+  }): Promise<number> {
+    if (this.activeTurn?.turn.turnId !== input.turn.turnId) {
+      throw new Error("Cannot apply steering outside the active turn.");
+    }
+    if (this.queuedPrompts.length === 0) return 0;
+    const drained = this.queuedPrompts.splice(0);
+    const records = input.ledger.appendSteeringUserMessages(
+      drained.map((entry) => entry.userMessage),
+    );
+    this.notifyPromptScheduler();
+    for (let index = 0; index < records.length; index += 1) {
+      const record = records[index];
+      const queued = drained[index];
+      if (record === undefined || queued === undefined) {
+        throw new Error("Steering ledger result did not match the drained queue.");
+      }
+      await this.append({
+        type: "turn.steering.applied",
+        ...input.turn,
+        data: {
+          userPrompt: projectUserMessage(queued.userMessage),
+          ordinal: record.ordinal,
+        },
+      });
+    }
+    return records.length;
+  }
+
   private settleAdmission(admission: ActiveAdmission): void {
     if (this.activeAdmission !== admission) {
       throw new Error("Runtime admission ownership was lost.");
@@ -1838,6 +1984,8 @@ class DefaultRuntimeSession implements RuntimeSession {
   canSwitchSession(): boolean {
     return (
       this.state === "ready" &&
+      !this.executionChainRunning &&
+      this.queuedPrompts.length === 0 &&
       this.activeTurn === undefined &&
       (this.tooling?.taskManager
         .listBackgroundTasks()
@@ -2025,6 +2173,7 @@ class DefaultRuntimeSession implements RuntimeSession {
     } finally {
       removeExternalAbortListener();
       this.activeTurn = undefined;
+      this.notifyPromptScheduler();
       this.pendingAutomaticContextMaintenance = false;
       if (this.state === "executing") {
         this.state = "ready";
@@ -2398,6 +2547,9 @@ class DefaultRuntimeSession implements RuntimeSession {
     }
 
     this.state = "disposing";
+    this.queuedPrompts.splice(0);
+    this.executionChainRunning = false;
+    this.notifyPromptScheduler();
     const errors: unknown[] = this.faultCause === undefined ? [] : [this.faultCause];
     const activeAdmission = this.activeAdmission;
     if (activeAdmission !== undefined) {