tinker-agent 1.0.65 → 1.2.0

package/src/context/context-manager.ts

@@ -10,35 +10,61 @@ import type { ModelClient } from "../model/model-client";
 import { promptPrefixFingerprint } from "../model/prompt-prefix-hash";
 import { estimatePromptSegments } from "../model/token-estimator";
 import { SessionError } from "../session/session-errors";
-import type { SessionStore } from "../session/session-store";
+import {
+  skillActivationManifestSha256,
+  type CommitSkillsUpdateInput,
+  type SessionStore,
+} from "../session/session-store";
 import type { ToolDefinition } from "../tools/types";
-import { canonicalSequenceHash, renderedMessageHash } from "./compiled-context-hash";
+import {
+  activeOverrideManifestHash,
+  canonicalSequenceHash,
+  renderedMessageHash,
+} from "./compiled-context-hash";
 import { CompiledContextError } from "./compiled-context-validator";
-import { swapOnlyPolicyV1 } from "./context-policy";
+import { recallFirstRetirementPolicyV1, swapOnlyPolicyV1 } from "./context-policy";
 import { ContextProtocolError } from "./context-protocol-validator";
+import type { StoredContextSnapshotV8, SwapOverride } from "./context-revision";
 import {
   ContextRevisionCompiler,
   ContextRevisionError,
 } from "./context-revision-compiler";
+import {
+  contextSurfaceChangeManifestHash,
+  contextSurfaceChanges,
+  type StoredContextSurfaceV8,
+} from "./context-surface";
 import {
   assertPlanBaseCurrent,
   SwapPlanner,
   SwapPlanningDiagnosticError,
   SwapPlanStaleError,
 } from "./swap-planner";
+import {
+  assertRetirementPlanBaseCurrent,
+  PrefixRetirementPlanner,
+  PrefixRetirementPlanningError,
+  PrefixRetirementPlanStaleError,
+  type PrefixRetirementPlan,
+} from "./prefix-retirement-planner";
 
 export type ContextCompactionTrigger =
   | { kind: "manual" }
   | { kind: "runtime_pressure" }
   | { kind: "benchmark_forced"; targetTokens: number };
 
+export type ContextRetirementTrigger =
+  | { kind: "manual" }
+  | { kind: "runtime_pressure" }
+  | { kind: "benchmark_forced"; targetTokens: number };
+
 export type ContextCompactionResult =
   | {
       status: "unchanged";
-      outcome: "below_target" | "no_eligible_candidates";
+      outcome: "below_trigger" | "below_target" | "no_eligible_candidates";
       revisionId: ReturnType<RuntimeIdFactory["createContextRevisionId"]>;
       revisionNumber: number;
-      totalOverrideCount: number;
+      activeOverrideCount: number;
       rawTokensBefore: number;
       guardedTokensBefore: number;
       targetTokens: number;
@@ -53,7 +79,7 @@ export type ContextCompactionResult =
       previousRevisionNumber: number;
       revisionNumber: number;
       addedOverrideCount: number;
-      totalOverrideCount: number;
+      activeOverrideCount: number;
       originalObservationBytes: number;
       projectedObservationBytes: number;
       rawTokensBefore: number;
@@ -69,6 +95,45 @@ export type ContextCompactionResult =
       durationMs: number;
     };
 
+export type ContextRetirementResult =
+  | {
+      status: "unchanged";
+      outcome: "below_target" | "no_complete_prefix";
+      revisionId: ReturnType<RuntimeIdFactory["createContextRevisionId"]>;
+      revisionNumber: number;
+      keepFromOrdinal: number;
+      activeOverrideCount: number;
+      guardedTokensBefore: number;
+      targetTokens: number;
+      planningDurationMs: number;
+      durationMs: number;
+    }
+  | {
+      status: "retired";
+      outcome: "target_reached" | "retirement_floor";
+      previousRevisionId: ReturnType<RuntimeIdFactory["createContextRevisionId"]>;
+      revisionId: ReturnType<RuntimeIdFactory["createContextRevisionId"]>;
+      previousRevisionNumber: number;
+      revisionNumber: number;
+      previousKeepFromOrdinal: number;
+      keepFromOrdinal: number;
+      retiredTurnCount: number;
+      retiredFrameCount: number;
+      retiredMessageCount: number;
+      activeOverrideCount: number;
+      rawTokensBefore: number;
+      rawTokensAfter: number;
+      guardedTokensBefore: number;
+      guardedTokensAfter: number;
+      targetTokens: number;
+      planHash: string;
+      planningDurationMs: number;
+      validationDurationMs: number;
+      transactionDurationMs: number;
+      activationDurationMs: number;
+      durationMs: number;
+    };
+
 export class ContextManagerError extends Error {
   constructor(
     readonly stage: "snapshot" | "plan" | "validate" | "commit" | "activate",
@@ -85,8 +150,83 @@ export class ContextManagerError extends Error {
 
 type ModelPreparer = Pick<ModelClient, "prepare">;
 
+export function commitAgentSkillsContextUpdate(input: {
+  store: SessionStore;
+  contextMeter: ContextMeter;
+  idFactory: RuntimeIdFactory;
+  snapshot: StoredContextSnapshotV8;
+  surface: StoredContextSurfaceV8;
+  addedOverrides: readonly SwapOverride[];
+  settlements: CommitSkillsUpdateInput["settlements"];
+}): ReturnType<SessionStore["commitSkillsUpdate"]> {
+  const compiler = new ContextRevisionCompiler();
+  let candidateCompiled: ReturnType<ContextRevisionCompiler["compileProspective"]>;
+  let changes: ReturnType<typeof contextSurfaceChanges>;
+  try {
+    input.store.assertContextRevisionIdle();
+    const active = compiler.compileActive(input.snapshot);
+    changes = contextSurfaceChanges(input.snapshot.surface, input.surface);
+    candidateCompiled = compiler.compileProspective({
+      active,
+      canonical: input.snapshot.canonical,
+      activeOverrides: input.snapshot.activeOverrides,
+      addedOverrides: input.addedOverrides,
+      activeSurface: input.snapshot.surface,
+      ...(input.surface === input.snapshot.surface ? {} : { surface: input.surface }),
+      allowCombinedSurfaceAndOverrides: true,
+    });
+  } catch (error) {
+    throw managerError("validate", error);
+  }
+
+  let revision: ReturnType<SessionStore["commitSkillsUpdate"]>;
+  try {
+    revision = input.store.commitSkillsUpdate({
+      revisionId: input.idFactory.createContextRevisionId(),
+      expectedBaseRevisionId: input.snapshot.revision.revisionId,
+      expectedBaseRevisionNumber: input.snapshot.revision.revisionNumber,
+      expectedCanonicalThroughOrdinal: input.snapshot.canonical.messages.length,
+      expectedBaseActiveOverrideManifestSha256:
+        input.snapshot.revision.activeOverrideManifestSha256,
+      surface: input.surface,
+      changes,
+      changeManifestSha256: contextSurfaceChangeManifestHash(changes),
+      activationManifestSha256: skillActivationManifestSha256(input.settlements),
+      addedOverrides: input.addedOverrides,
+      nextActiveOverrideManifestSha256: activeOverrideManifestHash([
+        ...input.snapshot.activeOverrides,
+        ...input.addedOverrides,
+      ]),
+      settlements: input.settlements,
+      canonicalSequenceSha256: canonicalSequenceHash(input.snapshot.canonical),
+      renderedMessageSha256: renderedMessageHash(candidateCompiled.entries),
+    });
+  } catch (error) {
+    throw managerError("commit", error);
+  }
+
+  try {
+    input.contextMeter.startRevision({
+      reason: "context_rebuilt",
+      requestConfigHash: input.surface.requestConfigSha256,
+      toolSchemaHash: input.surface.toolSchemaSha256,
+    });
+  } catch (error) {
+    throw new ContextManagerError(
+      "activate",
+      errorCode(error),
+      true,
+      true,
+      "Agent Skills context revision committed but runtime activation failed.",
+      { cause: error },
+    );
+  }
+  return revision;
+}
+
 export class ContextManager {
   private readonly planner: SwapPlanner;
+  private readonly retirementPlanner: PrefixRetirementPlanner;
   private readonly compiler = new ContextRevisionCompiler();
   private readonly requestBuilder = new ContextBuilder();
 
@@ -103,6 +243,7 @@ export class ContextManager {
     },
   ) {
     this.planner = new SwapPlanner(input.model);
+    this.retirementPlanner = new PrefixRetirementPlanner(input.model);
   }
 
   async compact(trigger: ContextCompactionTrigger): Promise<ContextCompactionResult> {
@@ -125,6 +266,7 @@ export class ContextManager {
       planning = this.planner.plan({
         active: built.compiled,
         revision: built.revision,
+        surface: built.surface,
         activeOverrides: built.activeOverrides,
         canonical: built.canonical,
         activePrepared,
@@ -141,6 +283,20 @@ export class ContextManager {
     }
     const planningDurationMs = elapsedMs(startedAt);
 
+    if (planning.outcome === "below_trigger" && trigger.kind === "runtime_pressure") {
+      return Object.freeze({
+        status: "unchanged",
+        outcome: planning.outcome,
+        revisionId: built.revision.revisionId,
+        revisionNumber: built.revision.revisionNumber,
+        activeOverrideCount: built.revision.activeOverrideCount,
+        rawTokensBefore: planning.rawTokensBefore,
+        guardedTokensBefore: planning.guardedTokensBefore,
+        targetTokens: planning.targetTokens,
+        planningDurationMs,
+        durationMs: elapsedMs(startedAt),
+      });
+    }
     if (
       planning.outcome === "below_target" ||
       planning.outcome === "no_eligible_candidates"
@@ -150,7 +306,7 @@ export class ContextManager {
         outcome: planning.outcome,
         revisionId: built.revision.revisionId,
         revisionNumber: built.revision.revisionNumber,
-        totalOverrideCount: built.revision.totalOverrideCount,
+        activeOverrideCount: built.revision.activeOverrideCount,
         rawTokensBefore: planning.rawTokensBefore,
         guardedTokensBefore: planning.guardedTokensBefore,
         targetTokens: planning.targetTokens,
@@ -188,10 +344,12 @@ export class ContextManager {
         canonical: built.canonical,
         activeOverrides: built.activeOverrides,
         addedOverrides: plan.addedOverrides,
+        activeSurface: built.surface,
       });
       const candidate = this.requestBuilder.build({
         canonical: built.canonical,
         revision: built.revision,
+        surface: built.surface,
         activeOverrides: candidateOverrides,
         compiled: candidateCompiled,
         tools,
@@ -222,12 +380,12 @@ export class ContextManager {
         expectedBaseRevisionId: plan.baseRevisionId,
         expectedBaseRevisionNumber: plan.baseRevisionNumber,
         expectedCanonicalThroughOrdinal: plan.baseCanonicalThroughOrdinal,
-        expectedBaseOverrideManifestSha256: plan.baseOverrideManifestSha256,
+        expectedBaseActiveOverrideManifestSha256: plan.baseActiveOverrideManifestSha256,
         policyVersion: plan.policyVersion,
         rendererFormat: "swap-observation-v1",
         planHash: plan.planHash,
         addedOverrides: plan.addedOverrides,
-        nextOverrideManifestSha256: plan.nextOverrideManifestSha256,
+        nextActiveOverrideManifestSha256: plan.nextActiveOverrideManifestSha256,
         canonicalSequenceSha256: canonicalSequenceHash(
           built.canonical,
           plan.baseCanonicalThroughOrdinal,
@@ -277,7 +435,7 @@ export class ContextManager {
       previousRevisionNumber: built.revision.revisionNumber,
       revisionNumber: revision.revisionNumber,
       addedOverrideCount: plan.addedOverrides.length,
-      totalOverrideCount: revision.totalOverrideCount,
+      activeOverrideCount: revision.activeOverrideCount,
       originalObservationBytes: planning.originalObservationBytes,
       projectedObservationBytes: planning.projectedObservationBytes,
       rawTokensBefore: plan.rawTokensBefore,
@@ -293,6 +451,224 @@ export class ContextManager {
       durationMs: elapsedMs(startedAt),
     });
   }
+
+  async retirePrefix(
+    trigger: ContextRetirementTrigger,
+  ): Promise<ContextRetirementResult> {
+    const startedAt = performance.now();
+    const tools = this.input.tools();
+    let built;
+    let activePrepared;
+    let activeUsage;
+    let closedTurns;
+    try {
+      this.input.store.assertContextRevisionIdle();
+      built = this.input.ledger.buildCommittedModelRequest(tools);
+      activePrepared = this.input.model.prepare(built.request);
+      activeUsage = this.input.contextMeter.measure(activePrepared);
+      closedTurns = this.input.store.loadClosedTurnBoundaries();
+    } catch (error) {
+      throw managerError("snapshot", error);
+    }
+
+    let planning;
+    try {
+      planning = this.retirementPlanner.plan({
+        active: built.compiled,
+        revision: built.revision,
+        surface: built.surface,
+        activeOverrides: built.activeOverrides,
+        canonical: built.canonical,
+        closedTurns,
+        activePrepared,
+        activeUsage,
+        tools,
+        policy: recallFirstRetirementPolicyV1,
+        trigger: trigger.kind,
+        ...(trigger.kind === "benchmark_forced"
+          ? { forcedTargetTokens: trigger.targetTokens }
+          : {}),
+      });
+    } catch (error) {
+      throw managerError("plan", error);
+    }
+    const planningDurationMs = elapsedMs(startedAt);
+    if (
+      planning.outcome === "below_target" ||
+      planning.outcome === "no_complete_prefix"
+    ) {
+      return Object.freeze({
+        status: "unchanged",
+        outcome: planning.outcome,
+        revisionId: built.revision.revisionId,
+        revisionNumber: built.revision.revisionNumber,
+        keepFromOrdinal: built.revision.keepFromOrdinal,
+        activeOverrideCount: built.revision.activeOverrideCount,
+        guardedTokensBefore: planning.guardedTokensBefore,
+        targetTokens: planning.targetTokens,
+        planningDurationMs,
+        durationMs: elapsedMs(startedAt),
+      });
+    }
+
+    if (!("plan" in planning)) {
+      throw new ContextManagerError(
+        "validate",
+        "missing_retirement_plan",
+        true,
+        false,
+        "Committable prefix retirement produced no revision plan.",
+      );
+    }
+    const plan = planning.plan;
+    const validationStartedAt = performance.now();
+    const nextActiveOverrides = built.activeOverrides.filter(
+      (override) => override.ordinal >= plan.nextKeepFromOrdinal,
+    );
+    let candidateCompiled;
+    let candidatePrepared;
+    try {
+      candidateCompiled = this.compiler.compileProspective({
+        active: built.compiled,
+        canonical: built.canonical,
+        activeOverrides: built.activeOverrides,
+        addedOverrides: [],
+        activeSurface: built.surface,
+        keepFromOrdinal: plan.nextKeepFromOrdinal,
+      });
+      const candidate = this.requestBuilder.build({
+        canonical: built.canonical,
+        revision: built.revision,
+        surface: built.surface,
+        activeOverrides: nextActiveOverrides,
+        compiled: candidateCompiled,
+        tools,
+      });
+      candidatePrepared = this.input.model.prepare(candidate.request);
+      assertRetirementCandidatePrepared(activePrepared, candidatePrepared, plan);
+
+      const current = this.input.ledger.buildCommittedModelRequest(tools);
+      const currentPrepared = this.input.model.prepare(current.request);
+      assertRetirementPlanBaseCurrent(plan, {
+        active: current.compiled,
+        revision: current.revision,
+        surface: current.surface,
+        activeOverrides: current.activeOverrides,
+        canonical: current.canonical,
+        activePrepared: currentPrepared,
+      });
+      this.input.store.assertContextRevisionIdle();
+    } catch (error) {
+      throw managerError("validate", error);
+    }
+    const validationDurationMs = elapsedMs(validationStartedAt);
+
+    const revisionId = this.input.idFactory.createContextRevisionId();
+    const transactionStartedAt = performance.now();
+    let revision;
+    try {
+      revision = this.input.store.commitPrefixRetirementRevision({
+        revisionId,
+        expectedBaseRevisionId: plan.baseRevisionId,
+        expectedBaseRevisionNumber: plan.baseRevisionNumber,
+        expectedBaseKeepFromOrdinal: plan.baseKeepFromOrdinal,
+        expectedCanonicalThroughOrdinal: plan.baseCanonicalThroughOrdinal,
+        expectedSurfaceSha256: plan.baseSurfaceSha256,
+        expectedBaseActiveOverrideManifestSha256: plan.baseActiveOverrideManifestSha256,
+        policyVersion: plan.policyVersion,
+        planHash: plan.planHash,
+        nextKeepFromOrdinal: plan.nextKeepFromOrdinal,
+        retiredThroughOrdinal: plan.retiredThroughOrdinal,
+        retiredTurnCount: plan.retiredTurnCount,
+        retiredFrameCount: plan.retiredFrameCount,
+        retiredMessageCount: plan.retiredMessageCount,
+        nextActiveOverrideCount: plan.nextActiveOverrideCount,
+        nextActiveOverrideManifestSha256: plan.nextActiveOverrideManifestSha256,
+        canonicalSequenceSha256: plan.canonicalSequenceSha256,
+        renderedMessageSha256: plan.renderedMessageSha256,
+      });
+    } catch (error) {
+      throw managerError("commit", error);
+    }
+    const transactionDurationMs = elapsedMs(transactionStartedAt);
+
+    const activationStartedAt = performance.now();
+    try {
+      this.input.contextMeter.startRevision({
+        reason: "context_rebuilt",
+        requestConfigHash: candidatePrepared.requestConfigHash,
+        toolSchemaHash: candidatePrepared.toolSchemaHash,
+      });
+      this.input.committedPrefixAuditor.audit(revisionId, candidatePrepared);
+      const usage = this.input.contextMeter.measure(candidatePrepared);
+      if (usage.source !== "estimated_full") {
+        throw new Error(
+          "First context measurement after prefix retirement was not a full estimate.",
+        );
+      }
+      await this.input.onUsageUpdated(usage);
+    } catch (error) {
+      throw new ContextManagerError(
+        "activate",
+        errorCode(error),
+        true,
+        true,
+        "Prefix retirement committed but runtime activation failed.",
+        { cause: error },
+      );
+    }
+    const activationDurationMs = elapsedMs(activationStartedAt);
+
+    return Object.freeze({
+      status: "retired",
+      outcome: planning.outcome,
+      previousRevisionId: built.revision.revisionId,
+      revisionId,
+      previousRevisionNumber: built.revision.revisionNumber,
+      revisionNumber: revision.revisionNumber,
+      previousKeepFromOrdinal: built.revision.keepFromOrdinal,
+      keepFromOrdinal: revision.keepFromOrdinal,
+      retiredTurnCount: plan.retiredTurnCount,
+      retiredFrameCount: plan.retiredFrameCount,
+      retiredMessageCount: plan.retiredMessageCount,
+      activeOverrideCount: revision.activeOverrideCount,
+      rawTokensBefore: plan.rawTokensBefore,
+      rawTokensAfter: plan.rawTokensAfter,
+      guardedTokensBefore: plan.guardedTokensBefore,
+      guardedTokensAfter: plan.guardedTokensAfter,
+      targetTokens: plan.targetTokens,
+      planHash: plan.planHash,
+      planningDurationMs,
+      validationDurationMs,
+      transactionDurationMs,
+      activationDurationMs,
+      durationMs: elapsedMs(startedAt),
+    });
+  }
+}
+
+function assertRetirementCandidatePrepared(
+  active: ReturnType<ModelPreparer["prepare"]>,
+  candidate: ReturnType<ModelPreparer["prepare"]>,
+  plan: PrefixRetirementPlan,
+): void {
+  const rawTokens = estimatePromptSegments(candidate.promptSegments).totalTokens;
+  const fingerprint = promptPrefixFingerprint(candidate);
+  if (
+    candidate.provider !== active.provider ||
+    candidate.model !== active.model ||
+    candidate.requestConfigHash !== active.requestConfigHash ||
+    candidate.toolSchemaHash !== active.toolSchemaHash ||
+    candidate.requestMaxOutputTokens !== active.requestMaxOutputTokens ||
+    rawTokens !== plan.rawTokensAfter ||
+    fingerprint.prefixHash !== plan.projectedPrefixHash ||
+    plan.rawTokensAfter >= plan.rawTokensBefore ||
+    plan.guardedTokensAfter >= plan.guardedTokensBefore
+  ) {
+    throw new Error(
+      "Prepared candidate does not match its validated prefix retirement plan.",
+    );
+  }
 }
 
 function assertCandidatePrepared(
@@ -325,7 +701,9 @@ function managerError(
     return error;
   }
   const fatal = isFatalContextError(error) || stage === "commit";
-  const diagnostic = error instanceof SwapPlanningDiagnosticError;
+  const diagnostic =
+    error instanceof SwapPlanningDiagnosticError ||
+    error instanceof PrefixRetirementPlanningError;
   return new ContextManagerError(
     stage,
     diagnostic ? error.code : errorCode(error),
@@ -342,6 +720,7 @@ function isFatalContextError(error: unknown): boolean {
     error instanceof ContextRevisionError ||
     error instanceof CompiledContextError ||
     error instanceof SwapPlanStaleError ||
+    error instanceof PrefixRetirementPlanStaleError ||
     error instanceof CommittedPrefixAuditError ||
     error instanceof SessionError
   );

package/src/context/context-policy.ts

@@ -6,3 +6,11 @@ export const swapOnlyPolicyV1 = Object.freeze({
 } as const);
 
 export type SwapOnlyPolicyV1 = typeof swapOnlyPolicyV1;
+
+export const recallFirstRetirementPolicyV1 = Object.freeze({
+  version: "recall-first-retirement-v1",
+  protectedRecentTurnCount: 8,
+  targetInputRatio: 0.6,
+} as const);
+
+export type RecallFirstRetirementPolicyV1 = typeof recallFirstRetirementPolicyV1;

package/src/context/context-protocol-validator.ts

@@ -1,6 +1,7 @@
 import type { MessageId, ProtocolFrameId, ToolCallId } from "../ids/runtime-id";
 import {
   contentHash,
+  userMessageHash,
   rawResultHash,
   type CanonicalMessageRecord,
   type ProtocolContextView,
@@ -103,7 +104,16 @@ export class ContextProtocolValidator {
 
       if (
         options.fullIntegrity === true &&
-        message.contentSha256 !== contentHash(message.content)
+        message.contentSha256 !==
+          (message.role === "user"
+            ? userMessageHash({
+                role: "user",
+                content: message.content,
+                ...(message.attachments === undefined
+                  ? {}
+                  : { attachments: message.attachments }),
+              })
+            : contentHash(message.content))
       ) {
         fail(
           "content_hash_mismatch",