tinker-agent 2.3.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,
@@ -5096,6 +5097,7 @@ export function decodeStoredToolRawResult(value: unknown): ToolRawResult {
       "web_search",
       "web_fetch",
       "recall",
+      "context_maintenance",
       "memory_search",
       "memory_get",
       "wait",
@@ -5114,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" }> {
@@ -6430,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/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
           ? {}
           : {
@@ -228,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);
   }
@@ -304,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 }),