tinker-agent 2.2.0 → 2.4.0

package/src/session/session-store.ts

@@ -13,6 +13,7 @@ import {
 } from "node:fs/promises";
 import { randomUUID } from "node:crypto";
 import { Database } from "bun:sqlite";
+import { parseMessageId } from "../ids/runtime-id";
 import type {
   ContextRevisionId,
   ContextSurfaceId,
@@ -34,6 +35,11 @@ import {
 } from "../model/model-client";
 import type { ToolDefinition, ToolRawResult } from "../tools/types";
 import { sha256, stableJsonStringify } from "../model/model-request-preflight";
+import {
+  canonicalHomeRoot,
+  resolveWorkspaceStorageRoot,
+  workspaceStorageRoot,
+} from "./workspace-storage";
 import {
   ContextProtocolError,
   ContextProtocolValidator,
@@ -418,6 +424,7 @@ export type CreateNewSessionStoreInput = {
   projectInstruction?: ProjectInstructionManifest;
   idFactory: RuntimeIdFactory;
   clock?: () => string;
+  homeRoot?: string;
 };
 
 export type OpenSessionStoreInput = {
@@ -425,6 +432,7 @@ export type OpenSessionStoreInput = {
   sessionId: SessionId;
   clock?: () => string;
   allowIncomplete?: boolean;
+  homeRoot?: string;
 };
 
 export class SessionStore implements SessionLedgerCommitter {
@@ -447,6 +455,7 @@ export class SessionStore implements SessionLedgerCommitter {
       sessionDirectory: string;
       databasePath: string;
       clock: () => string;
+      homeRoot?: string;
     },
   ) {
     this.sessionId = input.sessionId;
@@ -454,14 +463,17 @@ export class SessionStore implements SessionLedgerCommitter {
     this.sessionDirectory = input.sessionDirectory;
     this.databasePath = input.databasePath;
     this.clock = input.clock;
+    this.homeRoot = input.homeRoot;
   }
 
+  private readonly homeRoot?: string;
+
   private readonly clock: () => string;
 
   static async createNew(input: CreateNewSessionStoreInput): Promise<SessionStore> {
     const clock = input.clock ?? (() => new Date().toISOString());
     const workspaceRoot = await canonicalWorkspaceRoot(input.workspaceRoot);
-    const sessionsRoot = await ensureSessionsRoot(workspaceRoot);
+    const sessionsRoot = await ensureSessionsRoot(workspaceRoot, input.homeRoot);
     const sessionDirectory = safeSessionDirectory(sessionsRoot, input.sessionId);
     try {
       await mkdir(sessionDirectory, { mode: 0o700 });
@@ -540,6 +552,7 @@ export class SessionStore implements SessionLedgerCommitter {
         sessionDirectory,
         databasePath,
         clock,
+        ...(input.homeRoot === undefined ? {} : { homeRoot: input.homeRoot }),
       });
       await store.correctDatabaseModes();
       store.validateCreatingState();
@@ -558,7 +571,10 @@ export class SessionStore implements SessionLedgerCommitter {
   static async openExisting(input: OpenSessionStoreInput): Promise<SessionStore> {
     const clock = input.clock ?? (() => new Date().toISOString());
     const workspaceRoot = await canonicalWorkspaceRoot(input.workspaceRoot);
-    const sessionsRoot = path.join(workspaceRoot, ".tinker", "sessions");
+    const sessionsRoot = path.join(
+      workspaceStorageRoot(workspaceRoot, await canonicalHomeRoot(input.homeRoot)),
+      "sessions",
+    );
     await validateSessionsRoot(sessionsRoot, input.sessionId);
     const sessionDirectory = safeSessionDirectory(sessionsRoot, input.sessionId);
     await validateSecureDirectory(sessionDirectory, input.sessionId);
@@ -593,6 +609,7 @@ export class SessionStore implements SessionLedgerCommitter {
         sessionDirectory,
         databasePath,
         clock,
+        ...(input.homeRoot === undefined ? {} : { homeRoot: input.homeRoot }),
       });
       store.recallIndexRebuilt = recallIndexContractUpgraded;
       const meta = store.readMeta();
@@ -2366,7 +2383,10 @@ export class SessionStore implements SessionLedgerCommitter {
     if (distinct.size === 0) {
       return;
     }
-    const store = await ImageAssetStore.open({ workspaceRoot: this.workspaceRoot });
+    const store = await ImageAssetStore.open({
+      workspaceRoot: this.workspaceRoot,
+      ...(this.homeRoot === undefined ? {} : { homeRoot: this.homeRoot }),
+    });
     for (const asset of distinct.values()) {
       await store.verify(asset);
     }
@@ -2670,6 +2690,7 @@ export class SessionStore implements SessionLedgerCommitter {
         sessionDirectory: stagingDirectory,
         databasePath: stagingDatabasePath,
         clock: this.clock,
+        ...(this.homeRoot === undefined ? {} : { homeRoot: this.homeRoot }),
       });
       clonedStore.validateAll({ allowOpenTail: false });
       await clonedStore.verifyImageAssetFiles();
@@ -3802,11 +3823,17 @@ function normalizeInputModalities(
   );
 }
 
-export function sessionDatabasePath(
+export async function resolveSessionDatabasePath(
   workspaceRoot: string,
   sessionId: SessionId,
-): string {
-  return path.join(workspaceRoot, ".tinker", "sessions", sessionId, "session.sqlite");
+  homeRoot?: string,
+): Promise<string> {
+  return path.join(
+    await resolveWorkspaceStorageRoot(workspaceRoot, homeRoot),
+    "sessions",
+    sessionId,
+    "session.sqlite",
+  );
 }
 
 function insertFrame(database: Database, frame: ProtocolFrame): void {
@@ -5070,6 +5097,7 @@ export function decodeStoredToolRawResult(value: unknown): ToolRawResult {
       "web_search",
       "web_fetch",
       "recall",
+      "context_maintenance",
       "memory_search",
       "memory_get",
       "wait",
@@ -5088,9 +5116,282 @@ export function decodeStoredToolRawResult(value: unknown): ToolRawResult {
   if (kind === "view_image") {
     return decodeStoredViewImageRawResult(raw);
   }
+  if (kind === "context_maintenance") {
+    return decodeStoredContextMaintenanceRawResult(raw);
+  }
   return immutableCanonicalClone(raw) as ToolRawResult;
 }
 
+function decodeStoredContextMaintenanceRawResult(
+  raw: Record<string, unknown>,
+): Extract<ToolRawResult, { kind: "context_maintenance" }> {
+  const operation = enumFromSql(
+    raw.operation,
+    ["status", "candidates", "swap"] as const,
+    "context maintenance operation",
+  );
+  if (raw.ok === false) {
+    if (operation !== "swap") {
+      assertObjectKeys(
+        raw,
+        ["kind", "ok", "operation", "error"],
+        ["kind", "ok", "operation", "error"],
+        `failed context ${operation} result`,
+      );
+      return immutableRecord({
+        kind: "context_maintenance" as const,
+        ok: false as const,
+        operation,
+        error: nonEmptyStringFromJson(raw.error, `context ${operation} error`),
+      });
+    }
+    assertObjectKeys(
+      raw,
+      ["kind", "ok", "operation", "scheduled", "rejected", "error"],
+      ["kind", "ok", "operation", "scheduled", "rejected"],
+      "failed context swap result",
+    );
+    if (!Array.isArray(raw.scheduled) || raw.scheduled.length !== 0) {
+      throw new Error("Failed context swap result must schedule no candidates.");
+    }
+    const rejected = decodeContextSwapRejected(raw.rejected);
+    const error =
+      raw.error === undefined
+        ? undefined
+        : nonEmptyStringFromJson(raw.error, "context swap error");
+    if (rejected.length === 0 && error === undefined) {
+      throw new Error("Failed context swap result must explain its failure.");
+    }
+    return immutableRecord({
+      kind: "context_maintenance" as const,
+      ok: false as const,
+      operation,
+      scheduled: Object.freeze([]),
+      rejected,
+      ...(error === undefined ? {} : { error }),
+    });
+  }
+  if (raw.ok !== true) {
+    throw new Error("Context maintenance raw result ok must be a boolean.");
+  }
+  if (operation === "status") {
+    assertObjectKeys(
+      raw,
+      [
+        "kind",
+        "ok",
+        "operation",
+        "usedInputTokens",
+        "inputBudgetTokens",
+        "pressure",
+        "triggerTokens",
+        "source",
+      ],
+      [
+        "kind",
+        "ok",
+        "operation",
+        "usedInputTokens",
+        "inputBudgetTokens",
+        "pressure",
+        "triggerTokens",
+        "source",
+      ],
+      "context status result",
+    );
+    return immutableRecord({
+      kind: "context_maintenance" as const,
+      ok: true as const,
+      operation,
+      usedInputTokens: nonNegativeJsonInteger(
+        raw.usedInputTokens,
+        "context status usedInputTokens",
+      ),
+      inputBudgetTokens: positiveJsonInteger(
+        raw.inputBudgetTokens,
+        "context status inputBudgetTokens",
+      ),
+      pressure: enumFromSql(
+        raw.pressure,
+        ["normal", "high", "critical"] as const,
+        "context status pressure",
+      ),
+      triggerTokens: positiveJsonInteger(
+        raw.triggerTokens,
+        "context status triggerTokens",
+      ),
+      source: enumFromSql(
+        raw.source,
+        [
+          "estimated_full",
+          "provider_measured",
+          "measured_plus_estimated_delta",
+        ] as const,
+        "context status source",
+      ),
+    });
+  }
+  if (operation === "candidates") {
+    assertObjectKeys(
+      raw,
+      ["kind", "ok", "operation", "total", "candidates"],
+      ["kind", "ok", "operation", "total", "candidates"],
+      "context swap candidates result",
+    );
+    if (!Array.isArray(raw.candidates) || raw.candidates.length > 50) {
+      throw new Error("Context swap candidates result has an invalid page.");
+    }
+    const candidates = raw.candidates.map((value, index) => {
+      const candidate = recordFromSql(value, `context candidate ${index}`);
+      assertObjectKeys(
+        candidate,
+        ["candidateId", "label", "ordinal", "savingsBytes"],
+        ["candidateId", "label", "ordinal", "savingsBytes"],
+        `context candidate ${index}`,
+      );
+      const label = stringFromSql(candidate.label, `context candidate ${index} label`);
+      if (
+        label === "" ||
+        label !== label.replace(/[\p{Cc}\p{Cf}\s]+/gu, " ").trim() ||
+        Buffer.byteLength(label, "utf8") > 80
+      ) {
+        throw new Error(`Context candidate ${index} label is invalid or too large.`);
+      }
+      return immutableRecord({
+        candidateId: parseMessageId(
+          stringFromSql(candidate.candidateId, `context candidate ${index} ID`),
+        ),
+        label,
+        ordinal: positiveJsonInteger(
+          candidate.ordinal,
+          `context candidate ${index} ordinal`,
+        ),
+        savingsBytes: positiveJsonInteger(
+          candidate.savingsBytes,
+          `context candidate ${index} savingsBytes`,
+        ),
+      });
+    });
+    if (
+      new Set(candidates.map((candidate) => candidate.candidateId)).size !==
+        candidates.length ||
+      candidates.some(
+        (candidate, index) =>
+          index > 0 &&
+          candidate.ordinal <= (candidates[index - 1]?.ordinal ?? candidate.ordinal),
+      )
+    ) {
+      throw new Error(
+        "Context swap candidates must have unique IDs and ascending ordinals.",
+      );
+    }
+    const total = nonNegativeJsonInteger(raw.total, "context candidates total");
+    if (total < candidates.length) {
+      throw new Error("Context candidates total is smaller than its page.");
+    }
+    return immutableRecord({
+      kind: "context_maintenance" as const,
+      ok: true as const,
+      operation,
+      total,
+      candidates: Object.freeze(candidates),
+    });
+  }
+
+  assertObjectKeys(
+    raw,
+    ["kind", "ok", "operation", "scheduled", "rejected", "note"],
+    ["kind", "ok", "operation", "scheduled", "rejected", "note"],
+    "context swap result",
+  );
+  if (!Array.isArray(raw.scheduled) || raw.scheduled.length < 1) {
+    throw new Error("Successful context swap result must schedule candidates.");
+  }
+  const scheduled = raw.scheduled.map((value, index) => {
+    const candidate = recordFromSql(value, `scheduled context candidate ${index}`);
+    assertObjectKeys(
+      candidate,
+      ["candidateId", "savingsBytes"],
+      ["candidateId", "savingsBytes"],
+      `scheduled context candidate ${index}`,
+    );
+    return immutableRecord({
+      candidateId: parseMessageId(
+        stringFromSql(candidate.candidateId, `scheduled candidate ${index} ID`),
+      ),
+      savingsBytes: positiveJsonInteger(
+        candidate.savingsBytes,
+        `scheduled candidate ${index} savingsBytes`,
+      ),
+    });
+  });
+  if (
+    scheduled.length > 16 ||
+    new Set(scheduled.map((candidate) => candidate.candidateId)).size !==
+      scheduled.length
+  ) {
+    throw new Error("Successful context swap result has invalid scheduled IDs.");
+  }
+  const rejected = decodeContextSwapRejected(raw.rejected);
+  if (
+    scheduled.length + rejected.length > 16 ||
+    scheduled.some((scheduledCandidate) =>
+      rejected.some(
+        (rejectedCandidate) =>
+          rejectedCandidate.candidateId === scheduledCandidate.candidateId,
+      ),
+    )
+  ) {
+    throw new Error("Context swap result candidate partitions are invalid.");
+  }
+  const note = stringFromSql(raw.note, "context swap note");
+  return immutableRecord({
+    kind: "context_maintenance" as const,
+    ok: true as const,
+    operation,
+    scheduled: Object.freeze(scheduled),
+    rejected,
+    note,
+  });
+}
+
+function decodeContextSwapRejected(value: unknown): readonly {
+  readonly candidateId: MessageId;
+  readonly reason: string;
+}[] {
+  if (!Array.isArray(value) || value.length > 16) {
+    throw new Error("Context swap rejected candidates must be an array of at most 16.");
+  }
+  const rejected = value.map((entry, index) => {
+    const candidate = recordFromSql(entry, `rejected context candidate ${index}`);
+    assertObjectKeys(
+      candidate,
+      ["candidateId", "reason"],
+      ["candidateId", "reason"],
+      `rejected context candidate ${index}`,
+    );
+    const reason = stringFromSql(
+      candidate.reason,
+      `rejected context candidate ${index} reason`,
+    );
+    if (!/^[a-z][a-z0-9_]{0,79}$/.test(reason)) {
+      throw new Error(`Rejected context candidate ${index} reason is invalid.`);
+    }
+    return immutableRecord({
+      candidateId: parseMessageId(
+        stringFromSql(candidate.candidateId, `rejected candidate ${index} ID`),
+      ),
+      reason,
+    });
+  });
+  if (
+    new Set(rejected.map((candidate) => candidate.candidateId)).size !== rejected.length
+  ) {
+    throw new Error("Context swap rejected candidate IDs must be unique.");
+  }
+  return Object.freeze(rejected);
+}
+
 function decodeStoredViewImageRawResult(
   raw: Record<string, unknown>,
 ): Extract<ToolRawResult, { kind: "view_image" }> {
@@ -6081,8 +6382,14 @@ async function canonicalWorkspaceRoot(workspaceRoot: string): Promise<string> {
   return realpath(workspaceRoot);
 }
 
-async function ensureSessionsRoot(workspaceRoot: string): Promise<string> {
-  const tinkerRoot = path.join(workspaceRoot, ".tinker");
+async function ensureSessionsRoot(
+  workspaceRoot: string,
+  homeRoot?: string,
+): Promise<string> {
+  const tinkerRoot = workspaceStorageRoot(
+    workspaceRoot,
+    await canonicalHomeRoot(homeRoot),
+  );
   const sessionsRoot = path.join(tinkerRoot, "sessions");
   await mkdir(sessionsRoot, { recursive: true, mode: 0o700 });
   await validateSessionsRoot(sessionsRoot);
@@ -6398,6 +6705,31 @@ function numberFromJson(value: unknown, name: string): number {
   return value as number;
 }
 
+function safeJsonInteger(value: unknown, name: string): number {
+  if (!Number.isSafeInteger(value)) {
+    throw new Error(`${name} must be a safe integer.`);
+  }
+  return value as number;
+}
+
+function nonNegativeJsonInteger(value: unknown, name: string): number {
+  const number = safeJsonInteger(value, name);
+  if (number < 0) throw new Error(`${name} must be non-negative.`);
+  return number;
+}
+
+function positiveJsonInteger(value: unknown, name: string): number {
+  const number = safeJsonInteger(value, name);
+  if (number < 1) throw new Error(`${name} must be positive.`);
+  return number;
+}
+
+function nonEmptyStringFromJson(value: unknown, name: string): string {
+  const text = stringFromSql(value, name);
+  if (text.trim() === "") throw new Error(`${name} must not be empty.`);
+  return text;
+}
+
 function enumFromSql<const T extends readonly string[]>(
   value: unknown,
   values: T,

package/src/session/workspace-storage.ts

@@ -0,0 +1,84 @@
+import { createHash } from "node:crypto";
+import { realpath } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+const TINKER_HOME_DIR = ".tinker";
+const PROJECTS_DIR = "projects";
+const SLUG_MAX_LENGTH = 24;
+const HASH_HEX_LENGTH = 8;
+const FALLBACK_SLUG = "project";
+
+export const TINKER_HOME_ENV = "TINKER_HOME";
+
+/**
+ * Base directory for global Tinker state. TINKER_HOME overrides the OS home
+ * directory; tests and the PTY harness use it to isolate state.
+ */
+export function defaultHomeRoot(env: NodeJS.ProcessEnv = process.env): string {
+  const override = env[TINKER_HOME_ENV]?.trim();
+  return override === undefined || override === "" ? os.homedir() : override;
+}
+
+/**
+ * Stable directory name for one workspace inside the global Tinker home, e.g.
+ * "tinker-a1b2c3d4". The slug is decorative; the hash suffix over the
+ * canonical workspace path provides uniqueness.
+ */
+export function workspaceStorageDirectoryName(canonicalWorkspaceRoot: string): string {
+  const slug = slugify(path.basename(canonicalWorkspaceRoot));
+  const hash = createHash("sha256")
+    .update(canonicalWorkspaceRoot)
+    .digest("hex")
+    .slice(0, HASH_HEX_LENGTH);
+  return `${slug}-${hash}`;
+}
+
+/**
+ * Storage root for one canonical workspace root under a canonical home root:
+ * <home>/.tinker/projects/<slug-hash>. Both inputs must already be canonical
+ * (see resolveWorkspaceStorageRoot for the resolving variant).
+ */
+export function workspaceStorageRoot(
+  canonicalWorkspaceRoot: string,
+  canonicalHomeRoot: string,
+): string {
+  return path.join(
+    canonicalHomeRoot,
+    TINKER_HOME_DIR,
+    PROJECTS_DIR,
+    workspaceStorageDirectoryName(canonicalWorkspaceRoot),
+  );
+}
+
+/** Canonical (symlink-resolved) home root used for global Tinker state. */
+export async function canonicalHomeRoot(
+  homeRoot: string = defaultHomeRoot(),
+): Promise<string> {
+  return realpath(homeRoot);
+}
+
+/**
+ * Resolves the per-workspace storage root under the global Tinker home. Both
+ * the workspace and the home root are canonicalized so a project reached
+ * through different symlinked paths maps to a single storage directory.
+ */
+export async function resolveWorkspaceStorageRoot(
+  workspaceRoot: string,
+  homeRoot: string = defaultHomeRoot(),
+): Promise<string> {
+  return workspaceStorageRoot(
+    await realpath(workspaceRoot),
+    await canonicalHomeRoot(homeRoot),
+  );
+}
+
+function slugify(name: string): string {
+  const slug = name
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+/, "")
+    .slice(0, SLUG_MAX_LENGTH)
+    .replace(/-+$/, "");
+  return slug === "" ? FALLBACK_SLUG : slug;
+}

package/src/tools/bash-task.ts

@@ -20,6 +20,7 @@ import {
   TERMINAL_SCREEN_ROWS,
   type TerminalScreen,
 } from "./terminal-screen";
+import { resolveWorkspaceStorageRoot } from "../session/workspace-storage";
 
 export type ShellTaskStatus =
   | "running"
@@ -112,6 +113,7 @@ export type ShellTaskManagerOptions = {
   cwdState: CwdState;
   runtimeSession: RuntimeSessionContext;
   stopGraceMs?: number;
+  homeRoot?: string;
 };
 
 const defaultStopGraceMs = 2_000;
@@ -121,6 +123,7 @@ export class ShellTaskManager {
   private readonly stopGraceMs: number;
   private acceptingTasks = true;
   private shutdownPromise?: Promise<ShutdownResult>;
+  private bashDirectoryPromise?: Promise<string>;
 
   constructor(private readonly options: ShellTaskManagerOptions) {
     this.stopGraceMs = options.stopGraceMs ?? defaultStopGraceMs;
@@ -129,6 +132,14 @@ export class ShellTaskManager {
     }
   }
 
+  private bashDirectory(): Promise<string> {
+    this.bashDirectoryPromise ??= resolveWorkspaceStorageRoot(
+      this.options.workspaceRoot,
+      this.options.homeRoot,
+    ).then((storageRoot) => path.join(storageRoot, "bash"));
+    return this.bashDirectoryPromise;
+  }
+
   async start(input: {
     command: string;
     description: string;
@@ -140,18 +151,9 @@ export class ShellTaskManager {
     }
 
     const id = createUuidV7();
-    const outputFilePath = path.join(
-      this.options.workspaceRoot,
-      ".tinker",
-      "bash",
-      `${id}.log`,
-    );
-    const cwdFilePath = path.join(
-      this.options.workspaceRoot,
-      ".tinker",
-      "bash",
-      `${id}.cwd`,
-    );
+    const bashDirectory = await this.bashDirectory();
+    const outputFilePath = path.join(bashDirectory, `${id}.log`);
+    const cwdFilePath = path.join(bashDirectory, `${id}.cwd`);
     await ensureEmptyFile(cwdFilePath);
 
     const output = await TaskOutput.create(outputFilePath);