tinker-agent 2.2.0 → 2.4.0

package/src/tools/context-maintenance.ts

@@ -0,0 +1,266 @@
+import { throwIfTurnCancelled } from "../agent/turn-cancellation";
+import { parseMessageId, type MessageId } from "../ids/runtime-id";
+import {
+  defineToolExecutor,
+  ToolExecutionFatalError,
+  type ContextMaintenanceHandle,
+  type ContextStatusRawResult,
+  type ContextSwapCandidatesRawResult,
+  type ContextSwapRawResult,
+  type ToolDefinition,
+  type ToolExecutionContext,
+  type ToolExecutor,
+} from "./types";
+
+const DEFAULT_CANDIDATE_LIMIT = 20;
+const MAX_CANDIDATE_LIMIT = 50;
+const MAX_SWAP_CANDIDATES = 16;
+
+export const CONTEXT_STATUS_TOOL_DEFINITION: ToolDefinition = Object.freeze({
+  name: "ContextStatus",
+  description:
+    "Inspect the current model-input token pressure without changing context. When pressure is high or critical, use ContextSwapCandidates to review eligible historical tool observations before choosing what to swap.",
+  parameters: {
+    type: "object",
+    additionalProperties: false,
+    properties: {},
+  },
+});
+
+export const CONTEXT_SWAP_CANDIDATES_TOOL_DEFINITION: ToolDefinition = Object.freeze({
+  name: "ContextSwapCandidates",
+  description:
+    "List currently eligible historical tool observations that can be replaced by compact Recall-backed placeholders. Results are ordered oldest first. Use candidate IDs with ContextSwap; listing does not change context.",
+  parameters: {
+    type: "object",
+    additionalProperties: false,
+    properties: {
+      limit: {
+        type: "integer",
+        minimum: 1,
+        maximum: MAX_CANDIDATE_LIMIT,
+        default: DEFAULT_CANDIDATE_LIMIT,
+      },
+      offset: {
+        type: "integer",
+        minimum: 0,
+        default: 0,
+      },
+    },
+  },
+});
+
+export const CONTEXT_SWAP_TOOL_DEFINITION: ToolDefinition = Object.freeze({
+  name: "ContextSwap",
+  description:
+    "Schedule selected ContextSwapCandidates for replacement by compact Recall-backed placeholders. The swap runs after this iteration's tool frame closes and preserves canonical history for RecallGet. Pass only candidate IDs returned by ContextSwapCandidates.",
+  parameters: {
+    type: "object",
+    additionalProperties: false,
+    properties: {
+      candidate_ids: {
+        type: "array",
+        minItems: 1,
+        maxItems: MAX_SWAP_CANDIDATES,
+        uniqueItems: true,
+        items: {
+          type: "string",
+          pattern:
+            "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
+        },
+      },
+    },
+    required: ["candidate_ids"],
+  },
+});
+
+export const CONTEXT_MAINTENANCE_TOOL_DEFINITIONS: readonly ToolDefinition[] =
+  Object.freeze([
+    CONTEXT_STATUS_TOOL_DEFINITION,
+    CONTEXT_SWAP_CANDIDATES_TOOL_DEFINITION,
+    CONTEXT_SWAP_TOOL_DEFINITION,
+  ]);
+
+export function createContextStatusToolExecutor(): ToolExecutor {
+  return defineToolExecutor("context_maintenance", {
+    definition: CONTEXT_STATUS_TOOL_DEFINITION,
+    async execute(args, _call, context): Promise<ContextStatusRawResult> {
+      throwIfTurnCancelled(context.signal);
+      const parsed = parseEmptyArgs(args, "ContextStatus");
+      if (!parsed.ok) {
+        return { ok: false, operation: "status", error: parsed.error };
+      }
+      const result = await requireContextMaintenance(context).status(_call);
+      throwIfTurnCancelled(context.signal);
+      return result;
+    },
+  });
+}
+
+export function createContextSwapCandidatesToolExecutor(): ToolExecutor {
+  return defineToolExecutor("context_maintenance", {
+    definition: CONTEXT_SWAP_CANDIDATES_TOOL_DEFINITION,
+    async execute(args, call, context): Promise<ContextSwapCandidatesRawResult> {
+      throwIfTurnCancelled(context.signal);
+      const parsed = parseCandidatePageArgs(args);
+      if (!parsed.ok) {
+        return { ok: false, operation: "candidates", error: parsed.error };
+      }
+      const result = await requireContextMaintenance(context).candidates(call, {
+        limit: parsed.limit,
+        offset: parsed.offset,
+      });
+      throwIfTurnCancelled(context.signal);
+      return result;
+    },
+  });
+}
+
+export function createContextSwapToolExecutor(): ToolExecutor {
+  return defineToolExecutor("context_maintenance", {
+    definition: CONTEXT_SWAP_TOOL_DEFINITION,
+    async execute(args, call, context): Promise<ContextSwapRawResult> {
+      throwIfTurnCancelled(context.signal);
+      const parsed = parseSwapArgs(args);
+      if (!parsed.ok) {
+        return {
+          ok: false,
+          operation: "swap",
+          scheduled: [],
+          rejected: [],
+          error: parsed.error,
+        };
+      }
+      const result = await requireContextMaintenance(context).swap(call, {
+        candidateIds: parsed.candidateIds,
+      });
+      throwIfTurnCancelled(context.signal);
+      return result;
+    },
+  });
+}
+
+function requireContextMaintenance(
+  context: ToolExecutionContext,
+): ContextMaintenanceHandle {
+  if (context.contextMaintenance === undefined) {
+    throw new ToolExecutionFatalError(
+      "Context maintenance tools have no active runtime coordinator.",
+    );
+  }
+  return context.contextMaintenance;
+}
+
+function parseEmptyArgs(
+  args: unknown,
+  toolName: string,
+): { ok: true } | { ok: false; error: string } {
+  if (!isRecord(args)) {
+    return { ok: false, error: `${toolName} arguments must be an object.` };
+  }
+  const unexpected = Object.keys(args)[0];
+  return unexpected === undefined
+    ? { ok: true }
+    : {
+        ok: false,
+        error: `${toolName} received unexpected field: ${unexpected}.`,
+      };
+}
+
+function parseCandidatePageArgs(
+  args: unknown,
+): { ok: true; limit: number; offset: number } | { ok: false; error: string } {
+  if (!isRecord(args)) {
+    return {
+      ok: false,
+      error: "ContextSwapCandidates arguments must be an object.",
+    };
+  }
+  const unexpected = Object.keys(args).find(
+    (key) => key !== "limit" && key !== "offset",
+  );
+  if (unexpected !== undefined) {
+    return {
+      ok: false,
+      error: `ContextSwapCandidates received unexpected field: ${unexpected}.`,
+    };
+  }
+  const limit = args.limit ?? DEFAULT_CANDIDATE_LIMIT;
+  const offset = args.offset ?? 0;
+  if (!isIntegerInRange(limit, 1, MAX_CANDIDATE_LIMIT)) {
+    return {
+      ok: false,
+      error: `ContextSwapCandidates.limit must be an integer from 1 to ${MAX_CANDIDATE_LIMIT}.`,
+    };
+  }
+  if (!Number.isSafeInteger(offset) || (offset as number) < 0) {
+    return {
+      ok: false,
+      error: "ContextSwapCandidates.offset must be a non-negative integer.",
+    };
+  }
+  return { ok: true, limit: limit as number, offset: offset as number };
+}
+
+function parseSwapArgs(
+  args: unknown,
+): { ok: true; candidateIds: readonly MessageId[] } | { ok: false; error: string } {
+  if (!isRecord(args)) {
+    return { ok: false, error: "ContextSwap arguments must be an object." };
+  }
+  const unexpected = Object.keys(args).find((key) => key !== "candidate_ids");
+  if (unexpected !== undefined) {
+    return {
+      ok: false,
+      error: `ContextSwap received unexpected field: ${unexpected}.`,
+    };
+  }
+  if (
+    !Array.isArray(args.candidate_ids) ||
+    args.candidate_ids.length < 1 ||
+    args.candidate_ids.length > MAX_SWAP_CANDIDATES
+  ) {
+    return {
+      ok: false,
+      error: `ContextSwap.candidate_ids must contain 1 to ${MAX_SWAP_CANDIDATES} message IDs.`,
+    };
+  }
+
+  const candidateIds: MessageId[] = [];
+  const seen = new Set<string>();
+  for (const candidate of args.candidate_ids) {
+    if (typeof candidate !== "string") {
+      return {
+        ok: false,
+        error: "ContextSwap.candidate_ids must contain only message ID strings.",
+      };
+    }
+    let candidateId: MessageId;
+    try {
+      candidateId = parseMessageId(candidate);
+    } catch {
+      return {
+        ok: false,
+        error: "ContextSwap.candidate_ids contains an invalid message ID.",
+      };
+    }
+    if (!seen.has(candidateId)) {
+      seen.add(candidateId);
+      candidateIds.push(candidateId);
+    }
+  }
+  return { ok: true, candidateIds: Object.freeze(candidateIds) };
+}
+
+function isIntegerInRange(value: unknown, minimum: number, maximum: number): boolean {
+  return (
+    typeof value === "number" &&
+    Number.isSafeInteger(value) &&
+    value >= minimum &&
+    value <= maximum
+  );
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/tools/registry.ts

@@ -1,6 +1,11 @@
 import { createBashToolExecutor } from "./bash";
 import { ShellTaskManager } from "./bash-task";
 import { createCwdState } from "./cwd-state";
+import {
+  createContextStatusToolExecutor,
+  createContextSwapCandidatesToolExecutor,
+  createContextSwapToolExecutor,
+} from "./context-maintenance";
 import { createDeleteToolExecutor } from "./delete";
 import { createEditToolExecutor } from "./edit";
 import { createGlobToolExecutor } from "./glob";
@@ -26,6 +31,7 @@ import type {
 } from "../agent/runtime-session";
 import type {
   FileSnapshotStore,
+  ContextMaintenanceHandle,
   ToolDefinition,
   ToolExecutionContext,
   ToolExecutor,
@@ -79,6 +85,7 @@ export class ToolRuntime {
         signal: AbortSignal,
       ): Promise<"allow" | "deny">;
     },
+    private readonly contextMaintenance?: ContextMaintenanceHandle,
   ) {}
 
   async execute(call: ToolCall, context: ToolExecutionContext): Promise<ToolRawResult> {
@@ -107,6 +114,9 @@ export class ToolRuntime {
     try {
       return await tool.execute(call.args, call, {
         ...context,
+        ...(this.contextMaintenance === undefined
+          ? {}
+          : { contextMaintenance: this.contextMaintenance }),
         ...(this.bashGuard === undefined
           ? {}
           : {
@@ -153,6 +163,7 @@ export function createDefaultTooling(options: {
   workspaceRoot: string;
   runtimeSession: RuntimeSessionContext;
   historyReader: SessionHistoryReader;
+  homeRoot?: string;
   maxReadContentBytes?: number;
   exaApiKey?: string;
   webFetchRefiner?: Refiner;
@@ -187,6 +198,7 @@ export function createDefaultTooling(options: {
     cwdState,
     runtimeSession,
     stopGraceMs: options.taskStopGraceMs,
+    ...(options.homeRoot === undefined ? {} : { homeRoot: options.homeRoot }),
   });
 
   registry.register(
@@ -226,6 +238,9 @@ export function createDefaultTooling(options: {
   registry.register(
     createRecallGetToolExecutor({ historyReader: options.historyReader }),
   );
+  registry.register(createContextStatusToolExecutor());
+  registry.register(createContextSwapCandidatesToolExecutor());
+  registry.register(createContextSwapToolExecutor());
   if (options.memorySearch !== undefined) {
     registry.register(options.memorySearch);
   }
@@ -302,7 +317,11 @@ export function createDefaultTooling(options: {
 
   return {
     registry,
-    runtime: new ToolRuntime(registry, options.bashGuard),
+    runtime: new ToolRuntime(
+      registry,
+      options.bashGuard,
+      options.runtimeSession.contextMaintenance,
+    ),
     snapshots,
     taskManager,
     ...(turnUndoManager === undefined ? {} : { turnUndoManager }),

package/src/tools/types.ts

@@ -1,6 +1,7 @@
 import type { ToolCall } from "../agent/types";
 import type { ImageAssetRef } from "../image/image-types";
-import type { SessionId } from "../ids/runtime-id";
+import type { MessageId, SessionId } from "../ids/runtime-id";
+import type { ContextUsageSource } from "../model/model-request-preflight";
 import type {
   RecallGetPage,
   RecallSearchFilters,
@@ -310,6 +311,85 @@ export type RecallGetRawResult =
 
 export type RecallRawResult = RecallSearchRawResult | RecallGetRawResult;
 
+export type ContextMaintenancePressure = "normal" | "high" | "critical";
+
+export type ContextSwapCandidate = {
+  candidateId: MessageId;
+  label: string;
+  ordinal: number;
+  savingsBytes: number;
+};
+
+export type ContextSwapScheduledCandidate = {
+  candidateId: MessageId;
+  savingsBytes: number;
+};
+
+export type ContextSwapRejectedCandidate = {
+  candidateId: MessageId;
+  reason: string;
+};
+
+type ContextMaintenanceFailure<TOperation extends "status" | "candidates" | "swap"> = {
+  ok: false;
+  operation: TOperation;
+  error: string;
+};
+
+export type ContextStatusRawResult =
+  | {
+      ok: true;
+      operation: "status";
+      usedInputTokens: number;
+      inputBudgetTokens: number;
+      pressure: ContextMaintenancePressure;
+      triggerTokens: number;
+      source: ContextUsageSource;
+    }
+  | ContextMaintenanceFailure<"status">;
+
+export type ContextSwapCandidatesRawResult =
+  | {
+      ok: true;
+      operation: "candidates";
+      total: number;
+      candidates: readonly ContextSwapCandidate[];
+    }
+  | ContextMaintenanceFailure<"candidates">;
+
+export type ContextSwapRawResult =
+  | {
+      ok: true;
+      operation: "swap";
+      scheduled: readonly ContextSwapScheduledCandidate[];
+      rejected: readonly ContextSwapRejectedCandidate[];
+      note: string;
+    }
+  | {
+      ok: false;
+      operation: "swap";
+      scheduled: readonly ContextSwapScheduledCandidate[];
+      rejected: readonly ContextSwapRejectedCandidate[];
+      error?: string;
+    };
+
+export type ContextMaintenanceRawResult =
+  | ContextStatusRawResult
+  | ContextSwapCandidatesRawResult
+  | ContextSwapRawResult;
+
+export type ContextMaintenanceHandle = {
+  status(call: ToolCall): Promise<ContextStatusRawResult>;
+  candidates(
+    call: ToolCall,
+    input: { readonly limit: number; readonly offset: number },
+  ): Promise<ContextSwapCandidatesRawResult>;
+  swap(
+    call: ToolCall,
+    input: { readonly candidateIds: readonly MessageId[] },
+  ): Promise<ContextSwapRawResult>;
+};
+
 export type MemorySearchRawResult =
   | {
       ok: true;
@@ -425,6 +505,7 @@ export type ToolRawResultByKind = {
   web_search: WebSearchRawResult;
   web_fetch: WebFetchRawResult;
   recall: RecallRawResult;
+  context_maintenance: ContextMaintenanceRawResult;
   memory_search: MemorySearchRawResult;
   memory_get: MemoryGetRawResult;
   wait: WaitRawResult;
@@ -472,6 +553,7 @@ export function defineToolExecutor<TKind extends ToolRawResultKind>(
 
 export type ToolExecutionContext = {
   signal: AbortSignal;
+  contextMaintenance?: ContextMaintenanceHandle;
   confirmBashCommand?: (request: {
     command: string;
     reason: string;

package/src/tui/event-store.ts

@@ -883,6 +883,19 @@ function toolRawResultSummary(name: string, args: unknown, raw: ToolRawResult):
       return raw.mode === "search"
         ? `${base} -> ${raw.page.hits.length} historical match${raw.page.hits.length === 1 ? "" : "es"}`
         : `${base} -> ${raw.page.returnedBytes} historical bytes`;
+    case "context_maintenance":
+      if (!raw.ok) {
+        return raw.operation === "swap"
+          ? `${base} -> 0 scheduled, ${raw.rejected.length} rejected`
+          : base;
+      }
+      if (raw.operation === "status") {
+        return `${base} -> ${raw.pressure}, ${raw.usedInputTokens}/${raw.inputBudgetTokens} tokens`;
+      }
+      if (raw.operation === "candidates") {
+        return `${base} -> ${raw.candidates.length}/${raw.total} candidates`;
+      }
+      return `${base} -> ${raw.scheduled.length} scheduled, ${raw.rejected.length} rejected`;
     case "memory_search":
       if (!raw.ok) {
         return base;
@@ -980,6 +993,7 @@ function toolRawResultBashDetail(raw: ToolRawResult): Pick<TimelineItem, "bash">
     case "web_search":
     case "web_fetch":
     case "recall":
+    case "context_maintenance":
     case "memory_search":
     case "memory_get":
     case "wait":
@@ -1021,6 +1035,7 @@ function toolRawResultDiff(
     case "web_search":
     case "web_fetch":
     case "recall":
+    case "context_maintenance":
     case "memory_search":
     case "memory_get":
     case "wait":