tinker-agent 2.2.0 → 2.4.0

package/CHANGELOG.md

@@ -5,6 +5,39 @@ All notable user-facing changes to Tinker are documented here. The project follo
 
 ## [Unreleased]
 
+## [2.4.0] - 2026-09-02
+
+### Added
+
+- Add model-directed context management. Three new built-in tools open context
+  maintenance to the model itself: `ContextStatus` reports live input-token
+  usage and pressure, `ContextSwapCandidates` lists swappable historical tool
+  observations with short labels and byte savings, and `ContextSwap` schedules
+  selected observations for eviction. Scheduled swaps are validated immediately
+  and committed as one context revision when the iteration's tool frames close,
+  leaving Recall-recoverable placeholders behind. A one-shot lease pauses
+  automatic compaction for exactly one iteration after a candidate listing so
+  the model keeps the choice under real pressure.
+
+### Changed
+
+- Lower the swap eligibility floor from 8 KiB to 2 KiB per observation. Both
+  automatic compaction and model-directed swaps can now evict medium-sized
+  tool observations, individually or in batches of up to 16 per swap.
+
+## [2.3.0] - 2026-08-31
+
+### Changed
+
+- Store per-workspace runtime state in the global Tinker home instead of inside
+  the project. Sessions (`sessions/<id>/`), background Bash logs (`bash/`),
+  image assets (`assets/images/`), and prompt history now live under
+  `~/.tinker/projects/<workspace-slug-hash>/`, keyed by the workspace's
+  canonical absolute path. Projects no longer grow a `.tinker/` directory.
+  Existing in-project `.tinker/` state is left in place but no longer read.
+- Add `TINKER_HOME` to relocate the global Tinker home directory (default: the
+  OS home directory).
+
 ## [2.2.0] - 2026-08-29
 
 ### Added
@@ -264,7 +297,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.2.0...HEAD
+[Unreleased]: https://github.com/ishowshao/tinker/compare/v2.4.0...HEAD
+[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
 [2.1.0]: https://github.com/ishowshao/tinker/releases/tag/v2.1.0
 [2.0.0]: https://github.com/ishowshao/tinker/releases/tag/v2.0.0

package/README.md

@@ -458,13 +458,22 @@ one-shot `tinker run` command. See
 [`docs/project-custom-slash-commands-design.md`](docs/project-custom-slash-commands-design.md)
 for the full contract.
 
-### Workspace-Local Runtime Data
-
-Tinker keeps private runtime state under `<workspace>/.tinker/`: each session has
-its own SQLite database, event log, and observation log, while image assets and
-Prompt history are stored at the workspace level. These locations are fixed and
-have no public path-override environment variables. MCP server configuration is
-loaded from `<workspace>/.mcp.json`; project slash commands are loaded from
+### Global Runtime Data
+
+Tinker keeps private runtime state in a global home directory instead of inside
+your projects. Each workspace maps to
+`~/.tinker/projects/<workspace-slug-hash>/` — the slug comes from the workspace
+directory name and the hash from its canonical absolute path, so one project
+always resolves to one storage directory even when reached through symlinks.
+That directory holds per-session SQLite databases, event logs, and observation
+logs (`sessions/<id>/`), background Bash task logs (`bash/`), imported image
+assets (`assets/images/`), and prompt history (`prompt-history.jsonl`).
+Workspaces stay clean: no `.tinker/` directory is created inside them.
+
+Set `TINKER_HOME` to relocate the global home (default: the OS home directory).
+Global memory lives in `<home>/.tinker/memory/` and the Chrome bridge host in
+`<home>/.tinker/chrome/`. MCP server configuration is loaded from
+`<workspace>/.mcp.json`; project slash commands are loaded from
 `<workspace>/.tinker.json`.
 
 `Read` has a fixed 262144-byte (256 KiB) content limit per call. A successful
@@ -494,8 +503,9 @@ tinker/
 │   ├── context/       # Context protocol validation, protocol frame construction
 │   └── ids/           # Runtime ID generation (UUID v7)
 ├── docs/              # Design notes and planning documents
-├── .tinker/           # Runtime data (sessions, bash tasks, events)
 └── package.json
+
+Runtime data lives in ~/.tinker/ (sessions, bash tasks, assets), not in the repo.
 ```
 
 ## Design Philosophy

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tinker-agent",
-  "version": "2.2.0",
+  "version": "2.4.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

@@ -56,7 +56,7 @@ export type RunAgentInput = {
       preflight: ReturnType<ContextMeter["measure"]>;
     }):
       | {
-          trigger: Exclude<SwapPlanningTrigger, "manual">;
+          trigger: Exclude<SwapPlanningTrigger, "manual" | "model_directed">;
           forcedTargetTokens?: number;
         }
       | undefined;

package/src/agent/runtime-session.ts

@@ -11,6 +11,7 @@ import type {
 } from "../events/types";
 import {
   runtimeIdFactory,
+  type MessageId,
   type RuntimeIdFactory,
   type SessionId,
   type TurnId,
@@ -27,6 +28,7 @@ import {
   type MaterializedModelRequest,
   type ModelClient,
 } from "../model/model-client";
+import type { ContextPressure } from "../model/model-request-preflight";
 import { ImageAssetStore, type ImportedImageAsset } from "../image/image-asset-store";
 import { IMAGE_INPUT_POLICY } from "../image/image-input-policy";
 import {
@@ -72,7 +74,14 @@ import {
   renderedMessageHash,
 } from "../context/compiled-context-hash";
 import { createDefaultTooling, type DefaultTooling } from "../tools/registry";
-import type { ToolExecutor } from "../tools/types";
+import {
+  ToolExecutionFatalError,
+  type ContextMaintenanceHandle,
+  type ContextStatusRawResult,
+  type ContextSwapCandidatesRawResult,
+  type ContextSwapRawResult,
+  type ToolExecutor,
+} from "../tools/types";
 import type { TurnUndoResult } from "../tools/turn-undo-manager";
 import type { Refiner } from "../tools/web-fetch/refiner";
 import type { ProjectInstructionManifest } from "../instructions/project-instructions";
@@ -105,6 +114,7 @@ import type { PublicToolingConfig } from "../cli/public-config-contract";
 import type {
   IterationIdentity,
   RunAgentResult,
+  ToolCall,
   ToolCallIdentity,
   TurnIdentity,
 } from "./types";
@@ -221,6 +231,7 @@ export type RuntimeSkillsSnapshot = {
 
 export type RuntimeSessionContext = {
   readonly sessionId: SessionId;
+  readonly contextMaintenance: ContextMaintenanceHandle;
   createIteration(turn: TurnIdentity, iterationNumber: number): IterationIdentity;
   createToolCall(
     iteration: IterationIdentity,
@@ -287,6 +298,7 @@ export type CompletedTurnHook = {
 
 type CommonRuntimeSessionInput = {
   workspaceRoot: string;
+  homeRoot?: string;
   modelName: string;
   profileName?: string;
   maxIterations: number;
@@ -341,7 +353,10 @@ export type RuntimeSessionFactoryDependencies = {
     idFactory: RuntimeIdFactory,
   ) => Promise<SessionStore>;
   createLedger: (store: SessionStore, idFactory: RuntimeIdFactory) => SessionLedger;
-  createEventSink: (input: CreateRuntimeSessionInput) => EventSink;
+  createEventSink: (
+    input: CreateRuntimeSessionInput,
+    sessionDirectory: string,
+  ) => EventSink;
   selectShadowPlanning: NonNullable<RunAgentInput["shadowPlanning"]>["select"];
   onShadowPlanningResult?: NonNullable<RunAgentInput["shadowPlanning"]>["onResult"];
   selectContextAutomation: typeof selectContextAutomation;
@@ -375,6 +390,8 @@ type RuntimeSessionState =
 
 type ActiveTurn = {
   turn: TurnIdentity;
+  ledger: AgentTurnLedger;
+  consumedThroughOrdinal?: number;
   controller: AbortController;
   completion: Promise<RunAgentResult>;
 };
@@ -407,10 +424,12 @@ const defaultDependencies: RuntimeSessionFactoryDependencies = {
           systemPrompt: input.systemPrompt,
           projectInstruction: input.projectInstruction,
           idFactory,
+          ...(input.homeRoot === undefined ? {} : { homeRoot: input.homeRoot }),
         })
       : SessionStore.openExisting({
           workspaceRoot: input.workspaceRoot,
           sessionId: input.selection.sessionId,
+          ...(input.homeRoot === undefined ? {} : { homeRoot: input.homeRoot }),
         }),
   createLedger: (store, idFactory) => new SqliteSessionLedger(store, idFactory),
   createEventSink,
@@ -461,6 +480,8 @@ class DefaultRuntimeSession implements RuntimeSession {
   private contextManager?: ContextManager;
   private contextAutomationDecision?: ContextAutomationDecision;
   private pendingAutomaticContextMaintenance = false;
+  private pendingModelDirectedSwap?: Set<MessageId>;
+  private modelDirectedSwapLease = false;
   private readonly skillCatalog: SkillCatalogSnapshot;
   private skillCoordinator = new SkillActivationCoordinator();
   private bashGuardMode: "guard" | "yolo";
@@ -511,6 +532,11 @@ class DefaultRuntimeSession implements RuntimeSession {
     this.shadowPlanner = new SwapPlanner(input.modelClient);
     this.context = {
       sessionId: this.sessionId,
+      contextMaintenance: {
+        status: (call) => this.contextStatus(call),
+        candidates: (call, page) => this.contextSwapCandidates(call, page),
+        swap: (call, selection) => this.contextSwap(call, selection),
+      },
       createIteration: (turn, iterationNumber) =>
         this.createIteration(turn, iterationNumber),
       createToolCall: (iteration, toolCallNumber) =>
@@ -541,7 +567,10 @@ class DefaultRuntimeSession implements RuntimeSession {
     const store = await dependencies.openStore(input, dependencies.idFactory);
     let assetStore: ImageAssetStore;
     try {
-      assetStore = await ImageAssetStore.open({ workspaceRoot: store.workspaceRoot });
+      assetStore = await ImageAssetStore.open({
+        workspaceRoot: store.workspaceRoot,
+        ...(input.homeRoot === undefined ? {} : { homeRoot: input.homeRoot }),
+      });
     } catch (error) {
       if (isNewSessionInput(input)) {
         await store
@@ -557,7 +586,7 @@ class DefaultRuntimeSession implements RuntimeSession {
       session = new DefaultRuntimeSession(
         input,
         dependencies,
-        dependencies.createEventSink(input),
+        dependencies.createEventSink(input, store.sessionDirectory),
         dependencies.createObservationBuilder(),
         store,
         assetStore,
@@ -654,6 +683,7 @@ class DefaultRuntimeSession implements RuntimeSession {
 
       session.tooling = dependencies.createTooling({
         workspaceRoot: input.workspaceRoot,
+        ...(input.homeRoot === undefined ? {} : { homeRoot: input.homeRoot }),
         runtimeSession: session.context,
         historyReader: store.historyReader(),
         imageAssetStore: assetStore,
@@ -1238,6 +1268,133 @@ class DefaultRuntimeSession implements RuntimeSession {
     return this.contextAutomationDecision;
   }
 
+  private async contextStatus(call: ToolCall): Promise<ContextStatusRawResult> {
+    const active = this.requireActiveContextTool(call, "ContextStatus");
+    try {
+      const usage = this.requireContextManager().measureActive(
+        active.turn.turnId,
+        active.ledger,
+      );
+      return Object.freeze({
+        ok: true,
+        operation: "status",
+        usedInputTokens: usage.usedInputTokens,
+        inputBudgetTokens: usage.inputBudgetTokens,
+        pressure: toolContextPressure(usage.pressure),
+        triggerTokens: usage.triggerTokens,
+        source: usage.source,
+      });
+    } catch (error) {
+      return {
+        ok: false,
+        operation: "status",
+        error: this.contextToolFailure("status", error),
+      };
+    }
+  }
+
+  private async contextSwapCandidates(
+    call: ToolCall,
+    page: { readonly limit: number; readonly offset: number },
+  ): Promise<ContextSwapCandidatesRawResult> {
+    const active = this.requireActiveContextTool(call, "ContextSwapCandidates");
+    try {
+      const result = this.requireContextManager().listActiveSwapCandidates({
+        turnId: active.turn.turnId,
+        consumedThroughOrdinal: active.consumedThroughOrdinal,
+        activeLedger: active.ledger,
+        limit: page.limit,
+        offset: page.offset,
+      });
+      if (result.total > 0 && result.usage.pressure !== "normal") {
+        this.modelDirectedSwapLease = true;
+      }
+      return Object.freeze({
+        ok: true,
+        operation: "candidates",
+        total: result.total,
+        candidates: result.candidates,
+      });
+    } catch (error) {
+      return {
+        ok: false,
+        operation: "candidates",
+        error: this.contextToolFailure("candidate listing", error),
+      };
+    }
+  }
+
+  private async contextSwap(
+    call: ToolCall,
+    selection: { readonly candidateIds: readonly MessageId[] },
+  ): Promise<ContextSwapRawResult> {
+    const active = this.requireActiveContextTool(call, "ContextSwap");
+    try {
+      const result = this.requireContextManager().validateActiveSwapSelection({
+        turnId: active.turn.turnId,
+        consumedThroughOrdinal: active.consumedThroughOrdinal,
+        activeLedger: active.ledger,
+        messageIds: selection.candidateIds,
+      });
+      if (result.scheduled.length === 0) {
+        return Object.freeze({
+          ok: false,
+          operation: "swap",
+          scheduled: Object.freeze([]),
+          rejected: result.rejected,
+        });
+      }
+      const pending = (this.pendingModelDirectedSwap ??= new Set<MessageId>());
+      for (const candidate of result.scheduled) pending.add(candidate.candidateId);
+      this.modelDirectedSwapLease = false;
+      return Object.freeze({
+        ok: true,
+        operation: "swap",
+        scheduled: result.scheduled,
+        rejected: result.rejected,
+        note: "Swap executes when this iteration's tool frames close.",
+      });
+    } catch (error) {
+      return {
+        ok: false,
+        operation: "swap",
+        scheduled: [],
+        rejected: [],
+        error: this.contextToolFailure("swap scheduling", error),
+      };
+    }
+  }
+
+  private requireActiveContextTool(
+    call: ToolCall,
+    expectedName: "ContextStatus" | "ContextSwapCandidates" | "ContextSwap",
+  ): ActiveTurn & { consumedThroughOrdinal: number } {
+    this.requireToolCall(call);
+    const active = this.activeTurn;
+    if (
+      call.name !== expectedName ||
+      active === undefined ||
+      active.turn.turnId !== call.turnId ||
+      active.consumedThroughOrdinal === undefined ||
+      this.state !== "executing"
+    ) {
+      throw new ToolExecutionFatalError(
+        `${expectedName} was called outside an active model iteration.`,
+      );
+    }
+    return active as ActiveTurn & { consumedThroughOrdinal: number };
+  }
+
+  private contextToolFailure(operation: string, error: unknown): string {
+    if (error instanceof ContextManagerError && !error.fatal) {
+      return `Context ${operation} failed (${boundedContextErrorCode(error.code)}).`;
+    }
+    throw new ToolExecutionFatalError(
+      `Context ${operation} required canonical session state that could not be read safely.`,
+      { cause: error },
+    );
+  }
+
   private appendSkillsCatalogLoaded(): Promise<void> {
     const activeNames = this.skillCoordinator
       .activeEntries()
@@ -1297,6 +1454,15 @@ class DefaultRuntimeSession implements RuntimeSession {
     iteration: IterationIdentity;
     built: BuiltContextRequest;
   }): void {
+    const active = this.activeTurn;
+    if (
+      active === undefined ||
+      active.turn.turnId !== input.iteration.turnId ||
+      active.turn.sessionId !== input.iteration.sessionId
+    ) {
+      throw new Error("Model dispatch does not belong to the active runtime turn.");
+    }
+    active.consumedThroughOrdinal = input.built.canonical.messages.length;
     const pending = this.store.loadSkillActivations(["pending"]);
     if (pending.length === 0) {
       return;
@@ -1665,7 +1831,12 @@ class DefaultRuntimeSession implements RuntimeSession {
           usage: admissionSnapshot,
         },
       });
-      this.activeTurn = { turn, controller, completion };
+      this.activeTurn = {
+        turn,
+        ledger: pendingLedgerTurn.agent,
+        controller,
+        completion,
+      };
       this.notifyPromptScheduler();
       return Object.freeze({
         turnId: turn.turnId,
@@ -2182,6 +2353,8 @@ class DefaultRuntimeSession implements RuntimeSession {
       this.activeTurn = undefined;
       this.notifyPromptScheduler();
       this.pendingAutomaticContextMaintenance = false;
+      this.pendingModelDirectedSwap = undefined;
+      this.modelDirectedSwapLease = false;
       if (this.state === "executing") {
         this.state = "ready";
       }
@@ -2219,28 +2392,48 @@ class DefaultRuntimeSession implements RuntimeSession {
     consumedThroughOrdinal: number;
     ledger: AgentTurnLedger;
   }): Promise<void> {
-    const automation = this.requireContextAutomation();
-    if (!automation.automaticSwapOnly) return;
     if (this.state !== "executing") {
       throw new Error(
         `Cannot maintain active-turn context while RuntimeSession is ${this.state}.`,
       );
     }
-    const manager = this.requireContextManager();
-    const usage = manager.measureCurrent(input.turn.turnId, input.ledger);
-    if (usage.pressure === "normal") return;
+    const pendingModelDirectedSwap = this.pendingModelDirectedSwap;
+    this.pendingModelDirectedSwap = undefined;
+    if (pendingModelDirectedSwap === undefined && this.modelDirectedSwapLease) {
+      this.modelDirectedSwapLease = false;
+      return;
+    }
 
-    const qualificationId = requireAutomationQualificationId(automation);
-    const compactionTrigger = {
-      kind: "runtime_pressure",
-      activeTurn: {
-        turnId: input.turn.turnId,
-        consumedThroughOrdinal: input.consumedThroughOrdinal,
-      },
-    } as const;
+    const automation = this.requireContextAutomation();
+    if (pendingModelDirectedSwap === undefined && !automation.automaticSwapOnly) {
+      return;
+    }
+    const manager = this.requireContextManager();
     this.pendingAutomaticContextMaintenance = false;
+    this.modelDirectedSwapLease = false;
     this.state = "maintaining_context";
     try {
+      if (pendingModelDirectedSwap !== undefined) {
+        await this.performModelDirectedCompaction({
+          turn: input.turn,
+          consumedThroughOrdinal: input.consumedThroughOrdinal,
+          ledger: input.ledger,
+          messageIds: Object.freeze([...pendingModelDirectedSwap]),
+        });
+      }
+      if (!automation.automaticSwapOnly) return;
+
+      const usage = manager.measureCurrent(input.turn.turnId, input.ledger);
+      if (usage.pressure === "normal") return;
+
+      const qualificationId = requireAutomationQualificationId(automation);
+      const compactionTrigger = {
+        kind: "runtime_pressure",
+        activeTurn: {
+          turnId: input.turn.turnId,
+          consumedThroughOrdinal: input.consumedThroughOrdinal,
+        },
+      } as const;
       await this.append({
         type: "context.revision.started",
         sessionId: this.sessionId,
@@ -2337,6 +2530,56 @@ class DefaultRuntimeSession implements RuntimeSession {
     }
   }
 
+  private async performModelDirectedCompaction(input: {
+    turn: TurnIdentity;
+    consumedThroughOrdinal: number;
+    ledger: AgentTurnLedger;
+    messageIds: readonly MessageId[];
+  }): Promise<void> {
+    await this.append({
+      type: "context.revision.started",
+      sessionId: this.sessionId,
+      data: {
+        strategy: "swap",
+        reason: "model_directed",
+        policyVersion: "swap-only-v1",
+        rendererFormat: "swap-observation-v1",
+      },
+    });
+    try {
+      const result = await this.requireContextManager().compact(
+        {
+          kind: "model_directed",
+          messageIds: input.messageIds,
+          activeTurn: {
+            turnId: input.turn.turnId,
+            consumedThroughOrdinal: input.consumedThroughOrdinal,
+          },
+        },
+        input.ledger,
+      );
+      await this.append({
+        type: "context.revision.finished",
+        sessionId: this.sessionId,
+        data: contextRevisionFinishedData(result, "model_directed"),
+      });
+    } catch (error) {
+      const failure = automaticContextFailure(error, "compaction");
+      await this.append({
+        type: "context.revision.failed",
+        sessionId: this.sessionId,
+        data: {
+          strategy: "swap",
+          reason: "model_directed",
+          stage: failure.stage,
+          errorCode: boundedContextErrorCode(failure.code),
+          error: `Model-directed context compaction failed at ${failure.stage}.`,
+        },
+      }).catch(() => undefined);
+      if (failure.fatal) throw error;
+    }
+  }
+
   private notifyCompletedTurn(turn: TurnIdentity): void {
     const hook = this.input.completedTurnHook;
     if (hook === undefined) {
@@ -2928,21 +3171,19 @@ export async function createRuntimeSession(
   });
 }
 
-function createEventSink(input: CreateRuntimeSessionInput): EventSink {
+function createEventSink(
+  input: CreateRuntimeSessionInput,
+  sessionDirectory: string,
+): EventSink {
   const requiredSinks: EventSink[] = [];
   if (input.persistence !== false) {
-    const basePath = path.join(
-      input.workspaceRoot,
-      ".tinker",
-      "sessions",
-      input.selection.sessionId,
-    );
     requiredSinks.push(
       new JsonlEventLog(
-        input.persistence?.eventLogPath ?? path.join(basePath, "events.jsonl"),
+        input.persistence?.eventLogPath ?? path.join(sessionDirectory, "events.jsonl"),
       ),
       new ObservationTextLog(
-        input.persistence?.observationLogPath ?? path.join(basePath, "observations.md"),
+        input.persistence?.observationLogPath ??
+          path.join(sessionDirectory, "observations.md"),
       ),
     );
   }
@@ -3078,7 +3319,7 @@ function errorMessage(error: unknown): string {
 
 function contextRevisionFinishedData(
   result: ContextCompactionResult,
-  reason: "manual" | "runtime_pressure" = "manual",
+  reason: "manual" | "runtime_pressure" | "model_directed" = "manual",
   qualificationId?: string,
 ): ContextRevisionFinishedData {
   if (result.status === "unchanged") {
@@ -3216,6 +3457,16 @@ function boundedContextErrorCode(code: string): string {
     : "CONTEXT_COMPACTION_FAILED";
 }
 
+function toolContextPressure(
+  pressure: ContextPressure,
+): "normal" | "high" | "critical" {
+  return pressure === "triggered"
+    ? "high"
+    : pressure === "blocked"
+      ? "critical"
+      : "normal";
+}
+
 function requirePositiveNumber(value: number, name: string): void {
   if (!Number.isInteger(value) || value < 1) {
     throw new Error(`${name} must be a positive integer; received ${value}.`);

package/src/agent/session-ledger.ts

@@ -116,7 +116,10 @@ export type AgentTurnLedger = {
   commitToolCompletions(
     completions: readonly ToolCompletionInput[],
   ): readonly CommittedToolCompletion[];
-  buildModelRequest(tools: readonly ToolDefinition[]): BuiltContextRequest;
+  buildModelRequest(
+    tools: readonly ToolDefinition[],
+    options?: { readonly allowOpenTail?: boolean },
+  ): BuiltContextRequest;
   activateContextSnapshot(snapshot: StoredContextSnapshotV8): void;
 };
 
@@ -657,9 +660,10 @@ export class InMemorySessionLedger implements SessionLedger {
   buildTurnModelRequest(
     pending: InMemoryPendingLedgerTurn,
     tools: readonly ToolDefinition[],
+    options: { readonly allowOpenTail?: boolean } = {},
   ): BuiltContextRequest {
     this.requirePending(pending, "build a model request");
-    return this.buildRequest(tools);
+    return this.buildRequest(tools, undefined, options);
   }
 
   finishTurn(pending: InMemoryPendingLedgerTurn, result: RunAgentResult): void {
@@ -702,11 +706,13 @@ export class InMemorySessionLedger implements SessionLedger {
   private buildRequest(
     tools: readonly ToolDefinition[],
     candidateUserMessage?: UserMessage,
+    options: { readonly allowOpenTail?: boolean } = {},
   ): BuiltContextRequest {
     try {
       const canonical = this.view;
       const compiled = this.revisionCompiler.compileActive(
         snapshotFor(canonical, this.revision, this.surface, this.activeOverrides),
+        { allowOpenTail: options.allowOpenTail },
       );
       return this.contextBuilder.build({
         canonical,
@@ -865,7 +871,8 @@ class InMemoryPendingLedgerTurn implements PendingLedgerTurn {
       assertCanExecuteTool: (call) => this.ledger.assertCanExecuteTool(this, call),
       commitToolCompletions: (completions) =>
         this.ledger.commitToolCompletions(this, completions),
-      buildModelRequest: (tools) => this.ledger.buildTurnModelRequest(this, tools),
+      buildModelRequest: (tools, options) =>
+        this.ledger.buildTurnModelRequest(this, tools, options),
       activateContextSnapshot: (snapshot) =>
         this.ledger.activateContextSnapshot(snapshot),
     };

package/src/cli/config.ts

@@ -24,6 +24,7 @@ import {
   type ParsedPublicEnvironment,
   type PublicToolingConfig,
 } from "./public-config-contract";
+import { resolveWorkspaceStorageRoot } from "../session/workspace-storage";
 
 export type RunnerConfig = {
   readonly sessionId: SessionId;
@@ -227,17 +228,12 @@ function runnerConfigFromTemplate(
   });
 }
 
-export function eventLogPath(workspaceRoot: string, sessionId: SessionId): string {
-  return path.join(workspaceRoot, ".tinker", "sessions", sessionId, "events.jsonl");
-}
-
-export function observationLogPath(
+export async function promptHistoryPath(
   workspaceRoot: string,
-  sessionId: SessionId,
-): string {
-  return path.join(workspaceRoot, ".tinker", "sessions", sessionId, "observations.md");
-}
-
-export function promptHistoryPath(workspaceRoot: string): string {
-  return path.join(workspaceRoot, ".tinker", "prompt-history.jsonl");
+  homeRoot?: string,
+): Promise<string> {
+  return path.join(
+    await resolveWorkspaceStorageRoot(workspaceRoot, homeRoot),
+    "prompt-history.jsonl",
+  );
 }

package/src/cli/tui-runner.tsx

@@ -160,7 +160,9 @@ export async function runTui(options: RunTuiOptions): Promise<void> {
       config.sessionId,
       projectionStore,
     );
-    const promptHistory = await PromptHistory.load(promptHistoryPath(workspaceRoot));
+    const promptHistory = await PromptHistory.load(
+      await promptHistoryPath(workspaceRoot),
+    );
     const catalog = new SessionCatalog({ workspaceRoot });
 
     const openStoredSession = async (