tinker-agent 2.3.0 → 2.5.0

package/src/context/context-manager.ts

@@ -1,7 +1,7 @@
 import { ContextBuilder } from "../agent/context-builder";
 import type { ContextMeter, ContextUsageSnapshot } from "../agent/context-meter";
 import type { AgentTurnLedger, SessionLedger } from "../agent/session-ledger";
-import type { RuntimeIdFactory, TurnId } from "../ids/runtime-id";
+import type { MessageId, RuntimeIdFactory, TurnId } from "../ids/runtime-id";
 import {
   CommittedPrefixAuditError,
   type CommittedPrefixAuditor,
@@ -15,7 +15,12 @@ import {
   type CommitSkillsUpdateInput,
   type SessionStore,
 } from "../session/session-store";
-import type { ToolDefinition } from "../tools/types";
+import type {
+  ContextSwapCandidate,
+  ContextSwapRejectedCandidate,
+  ContextSwapScheduledCandidate,
+  ToolDefinition,
+} from "../tools/types";
 import {
   activeOverrideManifestHash,
   canonicalSequenceHash,
@@ -36,10 +41,11 @@ import {
 } from "./context-surface";
 import {
   assertPlanBaseCurrent,
+  swapCandidateRejectionReason,
   SwapPlanner,
   SwapPlanningDiagnosticError,
-  SwapPlanStaleError,
 } from "./swap-planner";
+import { renderContextSwapCandidateLabel } from "./context-swap-label";
 import {
   assertRetirementPlanBaseCurrent,
   PrefixRetirementPlanner,
@@ -59,8 +65,28 @@ export type ContextCompactionTrigger =
         consumedThroughOrdinal: number;
       };
     }
+  | {
+      kind: "model_directed";
+      messageIds: readonly MessageId[];
+      activeTurn: {
+        turnId: TurnId;
+        consumedThroughOrdinal: number;
+      };
+    }
   | { kind: "benchmark_forced"; targetTokens: number };
 
+export type ActiveSwapCandidatePage = {
+  readonly usage: ContextUsageSnapshot;
+  readonly total: number;
+  readonly candidates: readonly ContextSwapCandidate[];
+};
+
+export type ActiveSwapSelection = {
+  readonly usage: ContextUsageSnapshot;
+  readonly scheduled: readonly ContextSwapScheduledCandidate[];
+  readonly rejected: readonly ContextSwapRejectedCandidate[];
+};
+
 export type ContextRetirementTrigger =
   | { kind: "manual" }
   | { kind: "runtime_pressure"; activeTurnId?: TurnId }
@@ -267,6 +293,155 @@ export class ContextManager {
     return this.input.contextMeter.measure(prepared);
   }
 
+  measureActive(turnId: TurnId, activeLedger: AgentTurnLedger): ContextUsageSnapshot {
+    return this.inspectActive(turnId, activeLedger).usage;
+  }
+
+  listActiveSwapCandidates(input: {
+    turnId: TurnId;
+    consumedThroughOrdinal: number;
+    activeLedger: AgentTurnLedger;
+    limit: number;
+    offset: number;
+  }): ActiveSwapCandidatePage {
+    if (
+      !Number.isSafeInteger(input.limit) ||
+      input.limit < 1 ||
+      input.limit > 50 ||
+      !Number.isSafeInteger(input.offset) ||
+      input.offset < 0
+    ) {
+      throw new Error("Active swap candidate pagination is invalid.");
+    }
+    const inspected = this.inspectActive(input.turnId, input.activeLedger);
+    let scan;
+    try {
+      scan = this.planner.scanCandidates(
+        inspected.built.canonical,
+        inspected.built.activeOverrides,
+        swapOnlyPolicyV1,
+        inspected.built.revision.keepFromOrdinal,
+        {
+          turnId: input.turnId,
+          consumedThroughOrdinal: input.consumedThroughOrdinal,
+        },
+      );
+    } catch (error) {
+      throw managerError("plan", error);
+    }
+    const chronological = [...scan.eligible].sort(
+      (left, right) =>
+        left.message.ordinal - right.message.ordinal ||
+        left.message.messageId.localeCompare(right.message.messageId),
+    );
+    const candidates = chronological
+      .slice(input.offset, input.offset + input.limit)
+      .map((candidate) =>
+        Object.freeze({
+          candidateId: candidate.message.messageId,
+          label: renderContextSwapCandidateLabel({
+            canonical: inspected.built.canonical,
+            message: candidate.message,
+            result: candidate.result,
+          }),
+          ordinal: candidate.message.ordinal,
+          savingsBytes: candidate.override.byteSavings,
+        }),
+      );
+    return Object.freeze({
+      usage: inspected.usage,
+      total: chronological.length,
+      candidates: Object.freeze(candidates),
+    });
+  }
+
+  validateActiveSwapSelection(input: {
+    turnId: TurnId;
+    consumedThroughOrdinal: number;
+    activeLedger: AgentTurnLedger;
+    messageIds: readonly MessageId[];
+  }): ActiveSwapSelection {
+    if (
+      input.messageIds.length < 1 ||
+      input.messageIds.length > 16 ||
+      new Set(input.messageIds).size !== input.messageIds.length
+    ) {
+      throw new Error("Active swap selection must contain 1 to 16 unique IDs.");
+    }
+    const inspected = this.inspectActive(input.turnId, input.activeLedger);
+    let scan;
+    try {
+      scan = this.planner.scanCandidates(
+        inspected.built.canonical,
+        inspected.built.activeOverrides,
+        swapOnlyPolicyV1,
+        inspected.built.revision.keepFromOrdinal,
+        {
+          turnId: input.turnId,
+          consumedThroughOrdinal: input.consumedThroughOrdinal,
+        },
+      );
+    } catch (error) {
+      throw managerError("plan", error);
+    }
+    const eligibleById = new Map(
+      scan.eligible.map((candidate) => [candidate.message.messageId, candidate]),
+    );
+    const scheduled: ContextSwapScheduledCandidate[] = [];
+    const rejected: ContextSwapRejectedCandidate[] = [];
+    for (const messageId of input.messageIds) {
+      const candidate = eligibleById.get(messageId);
+      if (candidate === undefined) {
+        rejected.push(
+          Object.freeze({
+            candidateId: messageId,
+            reason: swapCandidateRejectionReason(
+              scan,
+              inspected.built.canonical,
+              messageId,
+            ),
+          }),
+        );
+      } else {
+        scheduled.push(
+          Object.freeze({
+            candidateId: messageId,
+            savingsBytes: candidate.override.byteSavings,
+          }),
+        );
+      }
+    }
+    return Object.freeze({
+      usage: inspected.usage,
+      scheduled: Object.freeze(scheduled),
+      rejected: Object.freeze(rejected),
+    });
+  }
+
+  private inspectActive(turnId: TurnId, activeLedger: AgentTurnLedger) {
+    const tools = this.input.tools();
+    try {
+      const built = activeLedger.buildModelRequest(tools, {
+        allowOpenTail: true,
+      });
+      if (
+        !built.canonical.messages.some(
+          (message) => message.role !== "system" && message.turnId === turnId,
+        )
+      ) {
+        throw new ContextRevisionError(
+          "Active context view does not contain the requested turn.",
+        );
+      }
+      const prepared = this.input.model.prepare(built.request);
+      this.input.committedPrefixAuditor.audit(built.compiled.revisionId, prepared);
+      const usage = this.input.contextMeter.measure(prepared);
+      return Object.freeze({ built, prepared, usage });
+    } catch (error) {
+      throw managerError("snapshot", error);
+    }
+  }
+
   async compact(
     trigger: ContextCompactionTrigger,
     activeLedger?: AgentTurnLedger,
@@ -299,9 +474,13 @@ export class ContextManager {
         tools,
         policy: swapOnlyPolicyV1,
         trigger: trigger.kind,
-        ...(trigger.kind === "runtime_pressure" && trigger.activeTurn !== undefined
+        ...((trigger.kind === "runtime_pressure" && trigger.activeTurn !== undefined) ||
+        trigger.kind === "model_directed"
           ? { activeTurn: trigger.activeTurn }
           : {}),
+        ...(trigger.kind === "model_directed"
+          ? { selectedMessageIds: trigger.messageIds }
+          : {}),
         ...(trigger.kind === "benchmark_forced"
           ? { forcedTargetTokens: trigger.targetTokens }
           : {}),
@@ -763,7 +942,6 @@ function isFatalContextError(error: unknown): boolean {
     error instanceof ContextProtocolError ||
     error instanceof ContextRevisionError ||
     error instanceof CompiledContextError ||
-    error instanceof SwapPlanStaleError ||
     error instanceof PrefixRetirementPlanStaleError ||
     error instanceof CommittedPrefixAuditError ||
     error instanceof SessionError
@@ -787,9 +965,8 @@ function elapsedMs(startedAt: number): number {
 function activeTurnId(
   trigger: ContextCompactionTrigger | ContextRetirementTrigger,
 ): TurnId | undefined {
-  if (trigger.kind !== "runtime_pressure") {
-    return undefined;
-  }
+  if (trigger.kind === "model_directed") return trigger.activeTurn.turnId;
+  if (trigger.kind !== "runtime_pressure") return undefined;
   if ("activeTurnId" in trigger) {
     return trigger.activeTurnId;
   }

package/src/context/context-policy.ts

@@ -1,6 +1,6 @@
 export const swapOnlyPolicyV1 = Object.freeze({
   version: "swap-only-v1",
-  minimumObservationBytes: 8 * 1_024,
+  minimumObservationBytes: 2 * 1_024,
   targetInputRatio: 0.3,
 } as const);
 

package/src/context/context-revision-compiler.ts

@@ -36,9 +36,14 @@ export class ContextRevisionCompiler {
     private readonly compiledValidator = new CompiledContextValidator(),
   ) {}
 
-  compileActive(snapshot: StoredContextSnapshotV8): CompiledRevisionContext {
+  compileActive(
+    snapshot: StoredContextSnapshotV8,
+    options: { readonly allowOpenTail?: boolean } = {},
+  ): CompiledRevisionContext {
     validateSnapshotIdentity(snapshot);
-    this.protocolValidator.validate(snapshot.canonical);
+    this.protocolValidator.validate(snapshot.canonical, {
+      allowOpenTail: options.allowOpenTail,
+    });
     const overrides = overrideMap(snapshot.activeOverrides);
     const compiled = compileEntries({
       canonical: snapshot.canonical,

package/src/context/context-swap-label.ts

@@ -0,0 +1,132 @@
+import type { ToolCall } from "../agent/types";
+import type { ToolRawResult } from "../tools/types";
+import type {
+  CanonicalMessageRecord,
+  ProtocolContextView,
+  ToolResultRecord,
+} from "./protocol-frame";
+
+const MAX_LABEL_BYTES = 80;
+
+export function renderContextSwapCandidateLabel(input: {
+  canonical: ProtocolContextView;
+  message: Extract<CanonicalMessageRecord, { role: "tool" }>;
+  result: ToolResultRecord;
+}): string {
+  const call = toolCallForMessage(input.canonical, input.message);
+  const raw =
+    input.result.completion.kind === "returned"
+      ? input.result.completion.raw
+      : undefined;
+  return compactLabel(labelFor(input.message.name, call, raw));
+}
+
+function labelFor(
+  toolName: string,
+  call: ToolCall | undefined,
+  raw: ToolRawResult | undefined,
+): string {
+  const args = asRecord(call?.args);
+  switch (raw?.kind) {
+    case "bash": {
+      const description = nonEmptyString(args?.description);
+      const command = nonEmptyString(args?.command)?.split(/\r?\n/, 1)[0];
+      return prefixed("Bash", description ?? command, toolName);
+    }
+    case "read": {
+      const filePath = nonEmptyString(args?.file_path);
+      return prefixed("Read", readLocation(filePath, args), toolName);
+    }
+    case "grep": {
+      const pattern = nonEmptyString(args?.pattern);
+      if (pattern === undefined) return toolName;
+      const searchPath = nonEmptyString(args?.path);
+      return `Grep: ${JSON.stringify(pattern)}${searchPath === undefined ? "" : ` in ${searchPath}`}`;
+    }
+    case "glob":
+      return prefixed("Glob", nonEmptyString(args?.pattern), toolName);
+    case "task_output":
+      return prefixed("TaskOutput", nonEmptyString(args?.task_id), toolName);
+    case "web_search":
+      return prefixed("WebSearch", nonEmptyString(args?.query), toolName);
+    case "web_fetch": {
+      const url = nonEmptyString(args?.url)?.replace(/^[a-z][a-z0-9+.-]*:\/\//iu, "");
+      return prefixed("WebFetch", url, toolName);
+    }
+    case "mcp":
+      return `MCP: ${raw.serverName}.${raw.serverToolName}`;
+    case "view_image":
+      return prefixed(
+        "view_image",
+        nonEmptyString(args?.file_path) ?? raw.filePath,
+        toolName,
+      );
+    default:
+      return toolName;
+  }
+}
+
+function toolCallForMessage(
+  canonical: ProtocolContextView,
+  message: Extract<CanonicalMessageRecord, { role: "tool" }>,
+): ToolCall | undefined {
+  const assistant = canonical.messages.find(
+    (entry) => entry.role === "assistant" && entry.frameId === message.frameId,
+  );
+  return assistant?.role === "assistant"
+    ? assistant.toolCalls?.find((call) => call.toolCallId === message.toolCallId)
+    : undefined;
+}
+
+function readLocation(
+  filePath: string | undefined,
+  args: Record<string, unknown> | undefined,
+): string | undefined {
+  if (filePath === undefined) return undefined;
+  const offset = positiveInteger(args?.offset);
+  const limit = positiveInteger(args?.limit);
+  if (offset === undefined && limit === undefined) return filePath;
+  const start = offset ?? 1;
+  return limit === undefined
+    ? `${filePath}:${start}`
+    : `${filePath}:${start}-${start + limit - 1}`;
+}
+
+function prefixed(prefix: string, value: string | undefined, fallback: string): string {
+  return value === undefined ? fallback : `${prefix}: ${value}`;
+}
+
+function compactLabel(value: string): string {
+  const normalized = value.replace(/[\p{Cc}\p{Cf}\s]+/gu, " ").trim();
+  const label = normalized === "" ? "Tool" : normalized;
+  if (Buffer.byteLength(label, "utf8") <= MAX_LABEL_BYTES) return label;
+  return `${utf8Prefix(label, MAX_LABEL_BYTES - Buffer.byteLength("…", "utf8"))}…`;
+}
+
+function utf8Prefix(value: string, maximumBytes: number): string {
+  let output = "";
+  let bytes = 0;
+  for (const character of value) {
+    const size = Buffer.byteLength(character, "utf8");
+    if (bytes + size > maximumBytes) break;
+    output += character;
+    bytes += size;
+  }
+  return output;
+}
+
+function nonEmptyString(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim() !== "" ? value : undefined;
+}
+
+function positiveInteger(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isSafeInteger(value) && value > 0
+    ? value
+    : undefined;
+}
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : undefined;
+}