tinker-agent 2.6.0 → 2.8.0

package/CHANGELOG.md

@@ -5,6 +5,43 @@ All notable user-facing changes to Tinker are documented here. The project follo
 
 ## [Unreleased]
 
+## [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
+
+- Add `AskUser`, an interactive tool that lets the agent pause on a material
+  ambiguity and present two to six complete choices in the TUI before resuming
+  the same turn with the selected answer.
+- Add model-accessible `MemoryCreate`, `MemoryUpdate`, and `MemoryDelete` tools
+  for explicitly maintaining global memories shared across sessions and
+  workspaces.
+
+### Changed
+
+- Redesign the session resume picker as a compact table, making session metadata
+  easier to scan while preserving keyboard navigation and search.
+
+### Fixed
+
+- Give the long-history PTY resume fixture enough time on slower Linux CI
+  runners, avoiding a false timeout while the model is still producing the
+  expected response.
+
 ## [2.6.0] - 2026-09-03
 
 ### Added
@@ -324,7 +361,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.6.0...HEAD
+[Unreleased]: https://github.com/ishowshao/tinker/compare/v2.8.0...HEAD
+[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
 [2.4.0]: https://github.com/ishowshao/tinker/releases/tag/v2.4.0

package/package.json

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

package/src/agent/loop.ts

@@ -384,6 +384,28 @@ export async function runAgent(input: RunAgentInput): Promise<RunAgentResult> {
       });
     }
 
+    if (toolCalls.some((call) => call.name === "AskUser") && toolCalls.length !== 1) {
+      const detail =
+        "AskUser must be the only tool call in an assistant response. Call it alone on the next iteration.";
+      const completions = toolCalls.map((call, index) => {
+        requireCallInIteration(call, iteration, index + 1);
+        return {
+          call,
+          kind: "synthetic" as const,
+          reason: "failed_active" as const,
+          detail,
+        };
+      });
+      input.ledger.commitToolCompletions(completions);
+      await input.runtimeSession.append({
+        type: "agent.iteration.finished",
+        ...iteration,
+        data: { outcome: "continue", toolCallCount: toolCalls.length },
+      });
+      input.runtimeSession.finishIterationForContinuation(iteration);
+      continue;
+    }
+
     for (let callIndex = 0; callIndex < toolCalls.length; callIndex += 1) {
       const call = requireToolCall(toolCalls, callIndex);
       requireCallInIteration(call, iteration, callIndex + 1);

package/src/agent/runtime-session.ts

@@ -80,6 +80,8 @@ import {
   type ContextStatusRawResult,
   type ContextSwapCandidatesRawResult,
   type ContextSwapRawResult,
+  type AskUserRequest,
+  type AskUserResponse,
   type ToolExecutor,
 } from "../tools/types";
 import type { TurnUndoResult } from "../tools/turn-undo-manager";
@@ -202,9 +204,20 @@ export type RuntimeSession = {
   subscribeBashGuard(listener: () => void): () => void;
   setYoloMode(enabled: boolean): void;
   resolveBashConfirmation(decision: "allow" | "deny"): Promise<void>;
+  askUser(): AskUserSnapshot;
+  subscribeAskUser(listener: () => void): () => void;
+  resolveAskUser(response: AskUserResolution): Promise<void>;
   dispose(reason: SessionDisposeReason): Promise<void>;
 };
 
+export type AskUserSnapshot = {
+  readonly pending?: AskUserRequest;
+};
+
+export type AskUserResolution =
+  | { readonly outcome: "selected"; readonly selectedIndex: number }
+  | { readonly outcome: "dismissed" };
+
 export type BashGuardSource = "default" | "environment" | "cli" | "session";
 
 export type BashGuardSnapshot = {
@@ -322,8 +335,12 @@ type CommonRuntimeSessionInput = {
   toolingConfig?: PublicToolingConfig;
   memorySearch?: ToolExecutor;
   memoryGet?: ToolExecutor;
+  memoryCreate?: ToolExecutor;
+  memoryUpdate?: ToolExecutor;
+  memoryDelete?: ToolExecutor;
   completedTurnHook?: CompletedTurnHook;
   enableTurnUndo?: boolean;
+  enableAskUser?: boolean;
   bashGuard?: {
     readonly mode: "guard" | "yolo";
     readonly source: Exclude<BashGuardSource, "session">;
@@ -490,6 +507,16 @@ class DefaultRuntimeSession implements RuntimeSession {
   private bashGuardSource: BashGuardSource;
   private bashGuardSnapshot: BashGuardSnapshot;
   private readonly bashGuardListeners = new Set<() => void>();
+  private askUserSnapshot: AskUserSnapshot = Object.freeze({});
+  private readonly askUserListeners = new Set<() => void>();
+  private pendingAskUser?: {
+    readonly request: AskUserRequest;
+    readonly startedAt: number;
+    readonly call: ToolCallIdentity;
+    readonly resolve: (response: AskUserResponse) => void;
+    readonly reject: (error: unknown) => void;
+    readonly removeAbortListener: () => void;
+  };
   private assistantTextDeltaSinkDisabled = false;
   private pendingBashConfirmation?: {
     readonly command: string;
@@ -695,6 +722,15 @@ class DefaultRuntimeSession implements RuntimeSession {
         ...(input.enableTurnUndo === true ? { enableTurnUndo: true } : {}),
         webFetchRefiner: input.webFetchRefiner,
         toolingConfig: input.toolingConfig,
+        ...(input.enableAskUser === true
+          ? {
+              askUser: (
+                call: ToolCallIdentity,
+                request: AskUserRequest,
+                signal: AbortSignal,
+              ) => session.requestUserAnswer(call, request, signal),
+            }
+          : {}),
         bashGuard: {
           surface: input.bashGuard?.surface ?? "one-shot",
           confirm: (call, request, signal) =>
@@ -704,6 +740,15 @@ class DefaultRuntimeSession implements RuntimeSession {
           ? {}
           : { memorySearch: input.memorySearch }),
         ...(input.memoryGet === undefined ? {} : { memoryGet: input.memoryGet }),
+        ...(input.memoryCreate === undefined
+          ? {}
+          : { memoryCreate: input.memoryCreate }),
+        ...(input.memoryUpdate === undefined
+          ? {}
+          : { memoryUpdate: input.memoryUpdate }),
+        ...(input.memoryDelete === undefined
+          ? {}
+          : { memoryDelete: input.memoryDelete }),
         ...(session.skillCatalog.skills.size === 0
           ? {}
           : {
@@ -1204,6 +1249,119 @@ class DefaultRuntimeSession implements RuntimeSession {
     }
   }
 
+  askUser(): AskUserSnapshot {
+    return this.askUserSnapshot;
+  }
+
+  subscribeAskUser(listener: () => void): () => void {
+    this.askUserListeners.add(listener);
+    return () => this.askUserListeners.delete(listener);
+  }
+
+  async resolveAskUser(response: AskUserResolution): Promise<void> {
+    const pending = this.pendingAskUser;
+    if (pending === undefined) {
+      throw new Error("No AskUser question is pending.");
+    }
+    let result: AskUserResponse;
+    if (response.outcome === "selected") {
+      if (!Number.isSafeInteger(response.selectedIndex)) {
+        throw new Error("AskUser selectedIndex must be an integer.");
+      }
+      const option = pending.request.options[response.selectedIndex];
+      if (option === undefined) {
+        throw new Error("AskUser selectedIndex is out of range.");
+      }
+      result = { outcome: "selected", answer: option.description };
+    } else {
+      result = { outcome: "dismissed" };
+    }
+    this.pendingAskUser = undefined;
+    this.askUserSnapshot = Object.freeze({});
+    pending.removeAbortListener();
+    await this.append({
+      type: "tool.user_question.resolved",
+      ...pending.call,
+      data: {
+        ...result,
+        durationMs: Date.now() - pending.startedAt,
+      },
+    });
+    pending.resolve(result);
+    this.notifyAskUserListeners();
+  }
+
+  private async requestUserAnswer(
+    call: ToolCallIdentity,
+    request: AskUserRequest,
+    signal: AbortSignal,
+  ): Promise<AskUserResponse> {
+    if (this.pendingAskUser !== undefined) {
+      throw new Error("Another AskUser question is already pending.");
+    }
+    if (this.pendingBashConfirmation !== undefined) {
+      throw new Error("Cannot ask the user while a Bash confirmation is pending.");
+    }
+    if (signal.aborted) {
+      throw cancellationError(signal);
+    }
+    const startedAt = Date.now();
+    await this.append({
+      type: "tool.user_question.requested",
+      ...call,
+      data: request,
+    });
+    return new Promise<AskUserResponse>((resolve, reject) => {
+      const onAbort = () => {
+        const pending = this.pendingAskUser;
+        if (pending?.call.toolCallId !== call.toolCallId) {
+          return;
+        }
+        this.pendingAskUser = undefined;
+        this.askUserSnapshot = Object.freeze({});
+        void this.append({
+          type: "tool.user_question.resolved",
+          ...call,
+          data: {
+            outcome: "cancelled",
+            durationMs: Date.now() - startedAt,
+          },
+        }).finally(() => {
+          reject(cancellationError(signal));
+          this.notifyAskUserListeners();
+        });
+      };
+      signal.addEventListener("abort", onAbort, { once: true });
+      const immutableRequest = Object.freeze({
+        question: request.question,
+        options: Object.freeze(
+          request.options.map((option) =>
+            Object.freeze({ description: option.description }),
+          ),
+        ),
+      });
+      this.pendingAskUser = {
+        request: immutableRequest,
+        startedAt,
+        call,
+        resolve,
+        reject,
+        removeAbortListener: () => signal.removeEventListener("abort", onAbort),
+      };
+      this.askUserSnapshot = Object.freeze({ pending: immutableRequest });
+      this.notifyAskUserListeners();
+      if (signal.aborted) {
+        onAbort();
+      }
+    });
+  }
+
+  private notifyAskUserListeners(): void {
+    for (const listener of this.askUserListeners) {
+      listener();
+    }
+  }
+
   async importImage(
     sourcePath: string,
     signal: AbortSignal,
@@ -2341,6 +2499,7 @@ class DefaultRuntimeSession implements RuntimeSession {
       }
       await this.settleClosedTurnSkills();
       if (result.status === "completed") {
+        await this.evaluateClosedTurnContextPressure();
         await this.performAutomaticContextMaintenance();
       }
       return result;
@@ -2364,6 +2523,21 @@ class DefaultRuntimeSession implements RuntimeSession {
     }
   }
 
+  private async evaluateClosedTurnContextPressure(): Promise<void> {
+    const automation = this.requireContextAutomation();
+    if (!automation.automaticSwapOnly) return;
+
+    const snapshot = this.requireContextManager().measureCurrent();
+    await this.append({
+      type: "context.usage.updated",
+      sessionId: this.sessionId,
+      data: { phase: "turn_close", snapshot },
+    });
+    if (snapshot.pressure !== "normal") {
+      this.pendingAutomaticContextMaintenance = true;
+    }
+  }
+
   private async performAutomaticContextMaintenance(): Promise<void> {
     if (!this.pendingAutomaticContextMaintenance) return;
     this.pendingAutomaticContextMaintenance = false;

package/src/cli/tui-runner.tsx

@@ -118,6 +118,7 @@ export async function runTui(options: RunTuiOptions): Promise<void> {
         ),
         toolingConfig: options.publicConfig.tooling,
         enableTurnUndo: true,
+        enableAskUser: true,
         bashGuard: {
           mode: sessionConfig.bashGuardMode,
           source: sessionConfig.bashGuardSource,
@@ -134,6 +135,18 @@ export async function runTui(options: RunTuiOptions): Promise<void> {
                 workspaceRoot,
                 sessionId,
               }),
+              memoryCreate: memoryCoordinator.createCreateToolExecutor({
+                workspaceRoot,
+                sessionId,
+              }),
+              memoryUpdate: memoryCoordinator.createUpdateToolExecutor({
+                workspaceRoot,
+                sessionId,
+              }),
+              memoryDelete: memoryCoordinator.createDeleteToolExecutor({
+                workspaceRoot,
+                sessionId,
+              }),
               completedTurnHook: memoryCoordinator,
             }),
       };
@@ -323,7 +336,6 @@ export async function runTui(options: RunTuiOptions): Promise<void> {
   } finally {
     instance?.unmount();
     restoreStdin();
-    memoryCoordinator?.dispose();
     if (controller !== undefined) {
       try {
         await controller.dispose(disposeReason);
@@ -337,6 +349,7 @@ export async function runTui(options: RunTuiOptions): Promise<void> {
               );
       }
     }
+    memoryCoordinator?.dispose();
   }
 
   if (primaryError !== undefined) {

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

@@ -140,6 +140,16 @@ export class StdoutEventPrinter implements EventSink {
           `tool.confirmation.resolved toolCallId=${event.toolCallId} decision=${event.data.decision} durationMs=${event.data.durationMs}\n`,
         );
         break;
+      case "tool.user_question.requested":
+        this.stdout.write(
+          `tool.user_question.requested toolCallId=${event.toolCallId} question=${JSON.stringify(event.data.question)} options=${event.data.options.length}\n`,
+        );
+        break;
+      case "tool.user_question.resolved":
+        this.stdout.write(
+          `tool.user_question.resolved toolCallId=${event.toolCallId} outcome=${event.data.outcome} durationMs=${event.data.durationMs}\n`,
+        );
+        break;
       case "mcp.server.connected":
         this.stdout.write(
           `mcp.server.connected name=${event.data.serverName} tools=${event.data.toolCount}\n`,
@@ -235,7 +245,11 @@ function formatToolRawResult(call: ToolCall, raw: ToolRawResult): string[] {
     case "context_maintenance":
     case "memory_search":
     case "memory_get":
+    case "memory_create":
+    case "memory_update":
+    case "memory_delete":
     case "wait":
+    case "ask_user":
     case "mcp":
     case "generic":
       return [];

package/src/events/types.ts

@@ -46,7 +46,7 @@ export type SessionStartedData = {
 };
 
 export type ContextUsageUpdatedData = {
-  phase: "initial" | "preflight" | "measured" | "revision";
+  phase: "initial" | "preflight" | "measured" | "turn_close" | "revision";
   snapshot: ContextUsageSnapshot;
 };
 
@@ -351,6 +351,14 @@ export type AgentEventDataMap = {
     decision: "allow" | "deny" | "cancelled";
     durationMs: number;
   };
+  "tool.user_question.requested": {
+    question: string;
+    options: readonly { description: string }[];
+  };
+  "tool.user_question.resolved":
+    | { outcome: "selected"; answer: string; durationMs: number }
+    | { outcome: "dismissed"; durationMs: number }
+    | { outcome: "cancelled"; durationMs: number };
   "agent.iteration.finished": {
     outcome: "continue" | "completed";
     toolCallCount: number;
@@ -448,6 +456,7 @@ export type AgentEventInput =
       "tool.started" | "tool.raw_result" | "tool.finished" | "tool.observation"
     >
   | ToolEventInput<"tool.confirmation.requested" | "tool.confirmation.resolved">
+  | ToolEventInput<"tool.user_question.requested" | "tool.user_question.resolved">
   | ToolEventInput<
       "bash.task.backgrounded" | "bash.task.stopping" | "bash.task.finished"
     >;

package/src/memory/contracts.ts

@@ -2,6 +2,9 @@ import type { SessionId, TurnId } from "../ids/runtime-id";
 
 export const MEMORY_SEARCH_TOOL_NAME = "MemorySearch" as const;
 export const MEMORY_GET_TOOL_NAME = "MemoryGet" as const;
+export const MEMORY_CREATE_TOOL_NAME = "MemoryCreate" as const;
+export const MEMORY_UPDATE_TOOL_NAME = "MemoryUpdate" as const;
+export const MEMORY_DELETE_TOOL_NAME = "MemoryDelete" as const;
 export const MEMORY_SCHEMA_VERSION = 2 as const;
 export const MAX_MEMORY_TEXT_BYTES = 512;
 export const MAX_MEMORY_SUMMARY_BYTES = 4_096;
@@ -112,6 +115,35 @@ export type StoredMemoryRecord = StoredMemorySummary & {
   readonly sourceTurnId: string;
 };
 
+export type StoredMemoryMutationRecord = StoredMemoryRecord & {
+  readonly embedding: Float32Array;
+};
+
+export type MemoryUpdateStoreResult =
+  | {
+      readonly ok: true;
+      readonly memoryId: string;
+    }
+  | {
+      readonly ok: false;
+      readonly code: "memory_not_found";
+    }
+  | {
+      readonly ok: false;
+      readonly code: "memory_duplicate";
+      readonly conflictMemoryId: string;
+    };
+
+export type MemoryDeleteStoreResult =
+  | {
+      readonly ok: true;
+      readonly memoryId: string;
+    }
+  | {
+      readonly ok: false;
+      readonly code: "memory_not_found";
+    };
+
 export type MemoryExtractionRejectedCounts = {
   readonly duplicate: number;
   readonly secret: number;
@@ -175,10 +207,24 @@ export type MemoryGetDiagnostic = {
   readonly ms: number;
 };
 
+export type MemoryMutationDiagnostic = {
+  readonly at: string;
+  readonly kind: "create" | "update" | "delete";
+  readonly outcome: "ok" | "failed" | "skipped";
+  readonly reason: string | null;
+  readonly workspace: string;
+  readonly sessionId: string;
+  readonly turnId: string;
+  readonly toolCallId: string;
+  readonly memoryId: string | null;
+  readonly ms: number;
+};
+
 export type MemoryDiagnostic =
   | MemoryExtractionDiagnostic
   | MemorySearchDiagnostic
   | MemoryGetDiagnostic
+  | MemoryMutationDiagnostic
   | MemoryInitDiagnostic;
 
 export class MemoryError extends Error {