tinker-agent 1.0.65 → 1.2.0

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

@@ -11,10 +11,11 @@ import { ContextProtocolValidator } from "./context-protocol-validator";
 import type {
   CompiledContextEntry,
   CompiledRevisionContext,
-  StoredContextSnapshotV5,
-  StoredInitialContextRevisionV5,
+  StoredContextSnapshotV8,
+  StoredInitialContextRevisionV8,
   SwapOverride,
 } from "./context-revision";
+import type { StoredContextSurfaceV8 } from "./context-surface";
 import {
   immutableRecord,
   materializeAgentMessages,
@@ -34,7 +35,7 @@ export class ContextRevisionCompiler {
     private readonly compiledValidator = new CompiledContextValidator(),
   ) {}
 
-  compileActive(snapshot: StoredContextSnapshotV5): CompiledRevisionContext {
+  compileActive(snapshot: StoredContextSnapshotV8): CompiledRevisionContext {
     validateSnapshotIdentity(snapshot);
     this.protocolValidator.validate(snapshot.canonical);
     const overrides = overrideMap(snapshot.activeOverrides);
@@ -42,11 +43,15 @@ export class ContextRevisionCompiler {
       canonical: snapshot.canonical,
       revisionId: snapshot.revision.revisionId,
       overrides,
+      keepFromOrdinal: snapshot.revision.keepFromOrdinal,
+      systemPrompt: snapshot.surface.systemPrompt,
+      surfaceSha256: snapshot.surface.surfaceSha256,
     });
     this.compiledValidator.validateActive(
       compiled,
       snapshot.canonical,
       snapshot.activeOverrides,
+      snapshot.surface,
     );
     if (
       compiled.manifest.canonicalSequenceHash !==
@@ -65,11 +70,40 @@ export class ContextRevisionCompiler {
     return compiled;
   }
 
+  compileForIdentityRekey(input: {
+    canonical: ProtocolContextView;
+    revisionId: ContextRevisionId;
+    activeOverrides: readonly SwapOverride[];
+    keepFromOrdinal: number;
+    surface: StoredContextSurfaceV8;
+  }): CompiledRevisionContext {
+    this.protocolValidator.validate(input.canonical);
+    const compiled = compileEntries({
+      canonical: input.canonical,
+      revisionId: input.revisionId,
+      overrides: overrideMap(input.activeOverrides),
+      keepFromOrdinal: input.keepFromOrdinal,
+      systemPrompt: input.surface.systemPrompt,
+      surfaceSha256: input.surface.surfaceSha256,
+    });
+    this.compiledValidator.validateActive(
+      compiled,
+      input.canonical,
+      input.activeOverrides,
+      input.surface,
+    );
+    return compiled;
+  }
+
   compileProspective(input: {
     active: CompiledRevisionContext;
     canonical: ProtocolContextView;
     activeOverrides: readonly SwapOverride[];
     addedOverrides: readonly SwapOverride[];
+    activeSurface: StoredContextSurfaceV8;
+    surface?: StoredContextSurfaceV8;
+    keepFromOrdinal?: number;
+    allowCombinedSurfaceAndOverrides?: boolean;
   }): CompiledRevisionContext {
     this.protocolValidator.validate(input.canonical);
     if (
@@ -86,21 +120,53 @@ export class ContextRevisionCompiler {
       input.active,
       input.canonical,
       input.activeOverrides,
+      input.activeSurface,
     );
-    const candidateOverrides = [...input.activeOverrides, ...input.addedOverrides];
+    const keepFromOrdinal =
+      input.keepFromOrdinal ?? input.active.manifest.keepFromOrdinal;
+    if (
+      !Number.isSafeInteger(keepFromOrdinal) ||
+      keepFromOrdinal < input.active.manifest.keepFromOrdinal
+    ) {
+      throw new ContextRevisionError(
+        "Prospective keep boundary must move monotonically forward.",
+      );
+    }
+    const changes = [
+      input.addedOverrides.length > 0,
+      input.surface !== undefined &&
+        input.surface.surfaceSha256 !== input.activeSurface.surfaceSha256,
+      keepFromOrdinal > input.active.manifest.keepFromOrdinal,
+    ].filter(Boolean).length;
+    if (changes > 1 && input.allowCombinedSurfaceAndOverrides !== true) {
+      throw new ContextRevisionError(
+        "A prospective context revision cannot combine revision semantics.",
+      );
+    }
+    const candidateOverrides =
+      keepFromOrdinal > input.active.manifest.keepFromOrdinal
+        ? input.activeOverrides.filter(
+            (override) => override.ordinal >= keepFromOrdinal,
+          )
+        : [...input.activeOverrides, ...input.addedOverrides];
     const overrides = overrideMap(candidateOverrides);
     if (overrides.size !== candidateOverrides.length) {
       throw new ContextRevisionError("Prospective overrides contain duplicate IDs.");
     }
+    const surface = input.surface ?? input.activeSurface;
     const compiled = compileEntries({
       canonical: input.canonical,
       revisionId: input.active.revisionId,
       overrides,
+      keepFromOrdinal,
+      systemPrompt: surface.systemPrompt,
+      surfaceSha256: surface.surfaceSha256,
     });
     this.compiledValidator.validateProspective(
       compiled,
       input.canonical,
       candidateOverrides,
+      surface,
     );
     return compiled;
   }
@@ -110,29 +176,59 @@ function compileEntries(input: {
   canonical: ProtocolContextView;
   revisionId: CompiledRevisionContext["revisionId"];
   overrides: ReadonlyMap<string, SwapOverride>;
+  keepFromOrdinal: number;
+  systemPrompt: string;
+  surfaceSha256: string;
 }): CompiledRevisionContext {
-  const materialized = materializeAgentMessages(input.canonical.messages);
-  const entries = input.canonical.messages.map((record, index) => {
+  const records =
+    input.keepFromOrdinal === 1
+      ? input.canonical.messages
+      : [
+          requireItem(input.canonical.messages, 0, "canonical system message"),
+          ...input.canonical.messages.slice(input.keepFromOrdinal - 1),
+        ];
+  const materialized = materializeAgentMessages(records);
+  const entries = records.map((record, index) => {
     const canonicalMessage = requireItem(materialized, index, "canonical message");
     const override = input.overrides.get(record.messageId);
+    const surfacedMessage =
+      record.ordinal === 1
+        ? surfacedSystemMessage(canonicalMessage, input.systemPrompt)
+        : canonicalMessage;
     const message =
       override === undefined
-        ? canonicalMessage
-        : swappedToolMessage(canonicalMessage, override);
+        ? surfacedMessage
+        : swappedToolMessage(surfacedMessage, override);
+    const representation =
+      override !== undefined
+        ? "swapped"
+        : record.ordinal === 1 && input.systemPrompt !== record.content
+          ? "surface"
+          : "canonical";
     return Object.freeze<CompiledContextEntry>({
       frameId: record.frameId,
       messageId: record.messageId,
       ordinal: record.ordinal,
-      representation: override === undefined ? "canonical" : "swapped",
+      representation,
       sourceContentSha256: record.contentSha256,
       message: immutableRecord(message),
     });
   });
   const manifest = Object.freeze({
-    frameCount: input.canonical.frames.length,
-    messageCount: entries.length,
+    canonicalFrameCount: input.canonical.frames.length,
+    canonicalMessageCount: input.canonical.messages.length,
+    activeFrameCount:
+      input.keepFromOrdinal === 1
+        ? input.canonical.frames.length
+        : 1 +
+          input.canonical.frames.filter(
+            (frame) => frame.firstOrdinal >= input.keepFromOrdinal,
+          ).length,
+    activeMessageCount: entries.length,
+    keepFromOrdinal: input.keepFromOrdinal,
     canonicalSequenceHash: canonicalSequenceHash(input.canonical),
     renderedMessageHash: renderedMessageHash(entries),
+    surfaceSha256: input.surfaceSha256,
   });
   return Object.freeze({
     sessionId: input.canonical.sessionId,
@@ -143,6 +239,19 @@ function compileEntries(input: {
   });
 }
 
+function surfacedSystemMessage(
+  message: AgentMessage,
+  systemPrompt: string,
+): AgentMessage {
+  if (message.role !== "system") {
+    throw new ContextRevisionError("Canonical ordinal 1 is not a system message.");
+  }
+  if (systemPrompt.trim() === "") {
+    throw new ContextRevisionError("Active context surface prompt is empty.");
+  }
+  return { role: "system", content: systemPrompt };
+}
+
 function swappedToolMessage(
   message: AgentMessage,
   override: SwapOverride,
@@ -158,18 +267,25 @@ function swappedToolMessage(
   };
 }
 
-function validateSnapshotIdentity(snapshot: StoredContextSnapshotV5): void {
+function validateSnapshotIdentity(snapshot: StoredContextSnapshotV8): void {
   if (
     snapshot.meta.sessionId !== snapshot.canonical.sessionId ||
     snapshot.revision.sessionId !== snapshot.canonical.sessionId ||
-    snapshot.meta.activeRevisionId !== snapshot.revision.revisionId
+    snapshot.meta.activeRevisionId !== snapshot.revision.revisionId ||
+    snapshot.surface.sessionId !== snapshot.canonical.sessionId ||
+    snapshot.surface.surfaceId !== snapshot.revision.surfaceId ||
+    snapshot.surface.surfaceSha256 !== snapshot.revision.surfaceSha256
   ) {
     throw new ContextRevisionError(
       "Active context revision identity does not match canonical history.",
     );
   }
-  if (snapshot.revision.keepFromOrdinal !== 1) {
-    throw new ContextRevisionError("Unsupported active context revision.");
+  if (
+    !Number.isSafeInteger(snapshot.revision.keepFromOrdinal) ||
+    snapshot.revision.keepFromOrdinal < 1 ||
+    snapshot.revision.keepFromOrdinal > snapshot.revision.sourceThroughOrdinal
+  ) {
+    throw new ContextRevisionError("Active context revision boundary is invalid.");
   }
   const firstFrame = snapshot.canonical.frames[0];
   const firstMessage = snapshot.canonical.messages[0];
@@ -202,25 +318,67 @@ function validateSnapshotIdentity(snapshot: StoredContextSnapshotV5): void {
       snapshot.revision.parentRevisionId !== null ||
       snapshot.revision.sourceThroughOrdinal !== 1 ||
       snapshot.revision.addedOverrideCount !== 0 ||
-      snapshot.revision.totalOverrideCount !== 0 ||
+      snapshot.revision.keepFromOrdinal !== 1 ||
+      snapshot.revision.activeOverrideCount !== 0 ||
       snapshot.activeOverrides.length !== 0
     ) {
       throw new ContextRevisionError("Initial context revision invariant failed.");
     }
   } else if (
-    snapshot.revision.revisionNumber < 2 ||
-    snapshot.revision.addedOverrideCount < 1 ||
-    snapshot.revision.totalOverrideCount < snapshot.revision.addedOverrideCount ||
-    snapshot.revision.policyVersion !== "swap-only-v1" ||
-    snapshot.revision.rendererFormat !== "swap-observation-v1" ||
-    snapshot.activeOverrides.length !== snapshot.revision.totalOverrideCount
+    snapshot.revision.kind === "swap_only" &&
+    (snapshot.revision.revisionNumber < 2 ||
+      snapshot.revision.addedOverrideCount < 1 ||
+      snapshot.revision.activeOverrideCount < snapshot.revision.addedOverrideCount ||
+      snapshot.revision.policyVersion !== "swap-only-v1" ||
+      snapshot.revision.rendererFormat !== "swap-observation-v1" ||
+      snapshot.activeOverrides.length !== snapshot.revision.activeOverrideCount)
   ) {
     throw new ContextRevisionError("Swap context revision invariant failed.");
+  } else if (
+    snapshot.revision.kind === "surface_refresh" &&
+    (snapshot.revision.revisionNumber < 2 ||
+      snapshot.revision.addedOverrideCount !== 0 ||
+      snapshot.activeOverrides.length !== snapshot.revision.activeOverrideCount)
+  ) {
+    throw new ContextRevisionError("Surface context revision invariant failed.");
+  } else if (
+    snapshot.revision.kind === "prefix_retirement" &&
+    (snapshot.revision.revisionNumber < 2 ||
+      snapshot.revision.keepFromOrdinal <= 1 ||
+      snapshot.revision.addedOverrideCount !== 0 ||
+      snapshot.revision.retiredThroughOrdinal !==
+        snapshot.revision.keepFromOrdinal - 1 ||
+      snapshot.revision.retiredTurnCount < 1 ||
+      snapshot.revision.retiredFrameCount < 1 ||
+      snapshot.revision.retiredMessageCount < 1 ||
+      snapshot.activeOverrides.length !== snapshot.revision.activeOverrideCount)
+  ) {
+    throw new ContextRevisionError("Prefix retirement revision invariant failed.");
+  } else if (
+    snapshot.revision.kind === "skills_update" &&
+    (snapshot.revision.revisionNumber < 2 ||
+      snapshot.revision.addedOverrideCount < 1 ||
+      snapshot.revision.activeOverrideCount < snapshot.revision.addedOverrideCount ||
+      snapshot.revision.policyVersion !== "agent-skills-v1" ||
+      snapshot.revision.rendererFormat !== "skill-activation-receipt-v1" ||
+      snapshot.activeOverrides.length !== snapshot.revision.activeOverrideCount)
+  ) {
+    throw new ContextRevisionError("Agent Skills context revision invariant failed.");
+  }
+
+  if (
+    snapshot.activeOverrides.some(
+      (override) => override.ordinal < snapshot.revision.keepFromOrdinal,
+    )
+  ) {
+    throw new ContextRevisionError(
+      "Active context revision contains an override before its keep boundary.",
+    );
   }
 
   if (
     activeOverrideManifestHash(snapshot.activeOverrides) !==
-    snapshot.revision.overrideManifestSha256
+    snapshot.revision.activeOverrideManifestSha256
   ) {
     throw new ContextRevisionError(
       "Active context revision override manifest does not match stored overrides.",
@@ -231,8 +389,9 @@ function validateSnapshotIdentity(snapshot: StoredContextSnapshotV5): void {
 export function createInitialContextRevision(input: {
   revisionId: ContextRevisionId;
   canonical: ProtocolContextView;
+  surface: StoredContextSurfaceV8;
   createdAt: string;
-}): StoredInitialContextRevisionV5 {
+}): StoredInitialContextRevisionV8 {
   const firstFrame = input.canonical.frames[0];
   const firstMessage = input.canonical.messages[0];
   if (
@@ -243,7 +402,9 @@ export function createInitialContextRevision(input: {
     firstFrame.firstOrdinal !== 1 ||
     firstFrame.lastOrdinal !== 1 ||
     firstMessage?.role !== "system" ||
-    firstMessage.ordinal !== 1
+    firstMessage.ordinal !== 1 ||
+    input.surface.sessionId !== input.canonical.sessionId ||
+    input.surface.systemPrompt !== firstMessage.content
   ) {
     throw new ContextRevisionError(
       "Initial context revision requires exactly one closed system frame.",
@@ -255,11 +416,13 @@ export function createInitialContextRevision(input: {
     revisionNumber: 1,
     parentRevisionId: null,
     kind: "initial_full",
+    surfaceId: input.surface.surfaceId,
+    surfaceSha256: input.surface.surfaceSha256,
     keepFromOrdinal: 1,
     sourceThroughOrdinal: 1,
     addedOverrideCount: 0,
-    totalOverrideCount: 0,
-    overrideManifestSha256: activeOverrideManifestHash([]),
+    activeOverrideCount: 0,
+    activeOverrideManifestSha256: activeOverrideManifestHash([]),
     canonicalSequenceSha256: canonicalSequenceHash(input.canonical, 1),
     renderedMessageSha256: canonicalRenderedMessageHash(input.canonical, 1),
     createdAt: input.createdAt,

package/src/context/context-revision.ts

@@ -1,41 +1,47 @@
 import type { AgentMessage } from "../agent/types";
 import type {
   ContextRevisionId,
+  ContextSurfaceId,
   MessageId,
   ProtocolFrameId,
   SessionId,
 } from "../ids/runtime-id";
 import type { ModelRequestInput } from "../model/model-client";
 import type { MessageSource } from "./context-source";
+import type { ContextSurfaceChanges, StoredContextSurfaceV8 } from "./context-surface";
 import type { ProtocolContextView } from "./protocol-frame";
 
-export type StoredInitialContextRevisionV5 = {
+export type StoredInitialContextRevisionV8 = {
   readonly revisionId: ContextRevisionId;
   readonly sessionId: SessionId;
   readonly revisionNumber: 1;
   readonly parentRevisionId: null;
   readonly kind: "initial_full";
+  readonly surfaceId: ContextSurfaceId;
+  readonly surfaceSha256: string;
   readonly keepFromOrdinal: 1;
   readonly sourceThroughOrdinal: 1;
   readonly addedOverrideCount: 0;
-  readonly totalOverrideCount: 0;
-  readonly overrideManifestSha256: string;
+  readonly activeOverrideCount: 0;
+  readonly activeOverrideManifestSha256: string;
   readonly canonicalSequenceSha256: string;
   readonly renderedMessageSha256: string;
   readonly createdAt: string;
 };
 
-export type StoredSwapContextRevisionV5 = {
+export type StoredSwapContextRevisionV8 = {
   readonly revisionId: ContextRevisionId;
   readonly sessionId: SessionId;
   readonly revisionNumber: number;
   readonly parentRevisionId: ContextRevisionId;
   readonly kind: "swap_only";
-  readonly keepFromOrdinal: 1;
+  readonly surfaceId: ContextSurfaceId;
+  readonly surfaceSha256: string;
+  readonly keepFromOrdinal: number;
   readonly sourceThroughOrdinal: number;
   readonly addedOverrideCount: number;
-  readonly totalOverrideCount: number;
-  readonly overrideManifestSha256: string;
+  readonly activeOverrideCount: number;
+  readonly activeOverrideManifestSha256: string;
   readonly canonicalSequenceSha256: string;
   readonly renderedMessageSha256: string;
   readonly policyVersion: "swap-only-v1";
@@ -44,9 +50,77 @@ export type StoredSwapContextRevisionV5 = {
   readonly createdAt: string;
 };
 
-export type StoredContextRevisionV5 =
-  | StoredInitialContextRevisionV5
-  | StoredSwapContextRevisionV5;
+export type StoredSurfaceRefreshContextRevisionV8 = {
+  readonly revisionId: ContextRevisionId;
+  readonly sessionId: SessionId;
+  readonly revisionNumber: number;
+  readonly parentRevisionId: ContextRevisionId;
+  readonly kind: "surface_refresh";
+  readonly surfaceId: ContextSurfaceId;
+  readonly surfaceSha256: string;
+  readonly keepFromOrdinal: number;
+  readonly sourceThroughOrdinal: number;
+  readonly addedOverrideCount: 0;
+  readonly activeOverrideCount: number;
+  readonly activeOverrideManifestSha256: string;
+  readonly canonicalSequenceSha256: string;
+  readonly renderedMessageSha256: string;
+  readonly changeManifestSha256: string;
+  readonly createdAt: string;
+};
+
+export type StoredPrefixRetirementContextRevisionV8 = {
+  readonly revisionId: ContextRevisionId;
+  readonly sessionId: SessionId;
+  readonly revisionNumber: number;
+  readonly parentRevisionId: ContextRevisionId;
+  readonly kind: "prefix_retirement";
+  readonly surfaceId: ContextSurfaceId;
+  readonly surfaceSha256: string;
+  readonly keepFromOrdinal: number;
+  readonly sourceThroughOrdinal: number;
+  readonly addedOverrideCount: 0;
+  readonly activeOverrideCount: number;
+  readonly activeOverrideManifestSha256: string;
+  readonly canonicalSequenceSha256: string;
+  readonly renderedMessageSha256: string;
+  readonly policyVersion: "recall-first-retirement-v1";
+  readonly planSha256: string;
+  readonly retiredThroughOrdinal: number;
+  readonly retiredTurnCount: number;
+  readonly retiredFrameCount: number;
+  readonly retiredMessageCount: number;
+  readonly createdAt: string;
+};
+
+export type StoredSkillsUpdateContextRevisionV8 = {
+  readonly revisionId: ContextRevisionId;
+  readonly sessionId: SessionId;
+  readonly revisionNumber: number;
+  readonly parentRevisionId: ContextRevisionId;
+  readonly kind: "skills_update";
+  readonly surfaceId: ContextSurfaceId;
+  readonly surfaceSha256: string;
+  readonly keepFromOrdinal: number;
+  readonly sourceThroughOrdinal: number;
+  readonly addedOverrideCount: number;
+  readonly activeOverrideCount: number;
+  readonly activeOverrideManifestSha256: string;
+  readonly canonicalSequenceSha256: string;
+  readonly renderedMessageSha256: string;
+  readonly policyVersion: "agent-skills-v1";
+  readonly rendererFormat: "skill-activation-receipt-v1";
+  readonly changeManifestSha256: string;
+  readonly activationManifestSha256: string;
+  readonly createdAt: string;
+};
+
+export type StoredContextRevisionV8 =
+  | StoredInitialContextRevisionV8
+  | StoredSwapContextRevisionV8
+  | StoredSurfaceRefreshContextRevisionV8
+  | StoredPrefixRetirementContextRevisionV8
+  | StoredSkillsUpdateContextRevisionV8;
 
 export type SwapOverride = {
   readonly frameId: ProtocolFrameId;
@@ -59,21 +133,23 @@ export type SwapOverride = {
   readonly originalBytes: number;
   readonly renderedBytes: number;
   readonly byteSavings: number;
+  readonly rendererFormat?: "swap-observation-v1" | "skill-activation-receipt-v1";
 };
 
-export type StoredSwapOverrideV5 = SwapOverride & {
+export type StoredContextOverrideV8 = SwapOverride & {
   readonly introducedRevisionId: ContextRevisionId;
-  readonly rendererFormat: "swap-observation-v1";
+  readonly rendererFormat: "swap-observation-v1" | "skill-activation-receipt-v1";
   readonly createdAt: string;
 };
 
-export type StoredContextSnapshotV5 = {
+export type StoredContextSnapshotV8 = {
   readonly meta: {
     readonly sessionId: SessionId;
     readonly activeRevisionId: ContextRevisionId;
   };
-  readonly revision: StoredContextRevisionV5;
-  readonly activeOverrides: readonly StoredSwapOverrideV5[];
+  readonly revision: StoredContextRevisionV8;
+  readonly surface: StoredContextSurfaceV8;
+  readonly activeOverrides: readonly StoredContextOverrideV8[];
   readonly canonical: ProtocolContextView;
 };
 
@@ -81,16 +157,20 @@ export type CompiledContextEntry = {
   readonly frameId: ProtocolFrameId;
   readonly messageId: MessageId;
   readonly ordinal: number;
-  readonly representation: "canonical" | "swapped";
+  readonly representation: "canonical" | "surface" | "swapped";
   readonly sourceContentSha256: string;
   readonly message: AgentMessage;
 };
 
 export type CompiledContextManifest = {
-  readonly frameCount: number;
-  readonly messageCount: number;
+  readonly canonicalFrameCount: number;
+  readonly canonicalMessageCount: number;
+  readonly activeFrameCount: number;
+  readonly activeMessageCount: number;
+  readonly keepFromOrdinal: number;
   readonly canonicalSequenceHash: string;
   readonly renderedMessageHash: string;
+  readonly surfaceSha256: string;
 };
 
 export type CompiledRevisionContext = {
@@ -103,9 +183,15 @@ export type CompiledRevisionContext = {
 
 export type BuiltContextRequest = {
   readonly canonical: ProtocolContextView;
-  readonly revision: StoredContextRevisionV5;
+  readonly revision: StoredContextRevisionV8;
+  readonly surface: StoredContextSurfaceV8;
   readonly activeOverrides: readonly SwapOverride[];
   readonly compiled: CompiledRevisionContext;
   readonly request: ModelRequestInput;
   readonly candidateUserPromptIncluded: boolean;
 };
+
+export type SurfaceRefreshPlan = {
+  readonly surface: StoredContextSurfaceV8;
+  readonly changes: ContextSurfaceChanges;
+};