tinker-agent 1.0.65 → 1.2.0

package/src/context/swap-planner.ts

@@ -14,8 +14,9 @@ import { CompiledContextError } from "./compiled-context-validator";
 import type { SwapOnlyPolicyV1 } from "./context-policy";
 import { ContextProtocolError } from "./context-protocol-validator";
 import type {
+  BuiltContextRequest,
   CompiledRevisionContext,
-  StoredContextRevisionV5,
+  StoredContextRevisionV8,
   SwapOverride,
 } from "./context-revision";
 import {
@@ -48,13 +49,14 @@ export type SwapRevisionPlan = {
   readonly policyVersion: "swap-only-v1";
   readonly baseRevisionId: CompiledRevisionContext["revisionId"];
   readonly baseRevisionNumber: number;
+  readonly baseKeepFromOrdinal: number;
   readonly baseCanonicalThroughOrdinal: number;
-  readonly baseOverrideManifestSha256: string;
+  readonly baseActiveOverrideManifestSha256: string;
   readonly basePrefixHash: string;
   readonly requestConfigHash: string;
   readonly toolSchemaHash: string;
   readonly addedOverrides: readonly SwapOverride[];
-  readonly nextOverrideManifestSha256: string;
+  readonly nextActiveOverrideManifestSha256: string;
   readonly targetTokens: number;
   readonly rawTokensBefore: number;
   readonly rawTokensAfter: number;
@@ -66,7 +68,8 @@ export type SwapRevisionPlan = {
 
 export type SwapPlanningInput = {
   readonly active: CompiledRevisionContext;
-  readonly revision: StoredContextRevisionV5;
+  readonly revision: StoredContextRevisionV8;
+  readonly surface: BuiltContextRequest["surface"];
   readonly activeOverrides: readonly SwapOverride[];
   readonly canonical: ProtocolContextView;
   readonly activePrepared: PreparedModelRequest;
@@ -176,6 +179,7 @@ export class SwapPlanner {
       input.canonical,
       input.activeOverrides,
       input.policy,
+      input.revision.keepFromOrdinal,
     );
     if (scan.eligible.length === 0) {
       return {
@@ -206,10 +210,12 @@ export class SwapPlanner {
           canonical: input.canonical,
           activeOverrides: input.activeOverrides,
           addedOverrides,
+          activeSurface: input.surface,
         });
         const built = this.requestBuilder.build({
           canonical: input.canonical,
           revision: input.revision,
+          surface: input.surface,
           activeOverrides: [...input.activeOverrides, ...addedOverrides],
           compiled,
           tools: input.tools,
@@ -344,6 +350,7 @@ export class SwapPlanner {
     canonical: ProtocolContextView,
     activeOverrides: readonly SwapOverride[],
     policy: SwapOnlyPolicyV1,
+    keepFromOrdinal: number,
   ): CandidateScan {
     const alreadySwapped = new Set(
       activeOverrides.map((override) => override.messageId),
@@ -367,6 +374,10 @@ export class SwapPlanner {
       if (message.role !== "tool") {
         continue;
       }
+      if (message.ordinal < keepFromOrdinal) {
+        increment(exclusions, "retired_prefix");
+        continue;
+      }
       if (alreadySwapped.has(message.messageId)) {
         increment(exclusions, "already_swapped");
         continue;
@@ -428,7 +439,7 @@ export function assertPlanBaseCurrent(
   plan: SwapRevisionPlan,
   current: {
     readonly active: CompiledRevisionContext;
-    readonly revision: StoredContextRevisionV5;
+    readonly revision: StoredContextRevisionV8;
     readonly activeOverrides: readonly SwapOverride[];
     readonly activePrepared: PreparedModelRequest;
   },
@@ -438,8 +449,9 @@ export function assertPlanBaseCurrent(
     plan.baseRevisionId !== current.active.revisionId ||
     plan.baseRevisionId !== current.revision.revisionId ||
     plan.baseRevisionNumber !== current.revision.revisionNumber ||
+    plan.baseKeepFromOrdinal !== current.revision.keepFromOrdinal ||
     plan.baseCanonicalThroughOrdinal !== current.active.canonicalThroughOrdinal ||
-    plan.baseOverrideManifestSha256 !==
+    plan.baseActiveOverrideManifestSha256 !==
       activeOverrideManifestHash(current.activeOverrides) ||
     plan.basePrefixHash !== fingerprint.prefixHash ||
     plan.requestConfigHash !== fingerprint.requestConfigHash ||
@@ -463,14 +475,24 @@ function validatePlanningInput(input: SwapPlanningInput): void {
     input.active.sessionId !== input.canonical.sessionId ||
     input.revision.sessionId !== input.canonical.sessionId ||
     input.revision.revisionId !== input.active.revisionId ||
+    input.revision.keepFromOrdinal !== input.active.manifest.keepFromOrdinal ||
     input.active.canonicalThroughOrdinal !== input.canonical.messages.length ||
-    input.revision.overrideManifestSha256 !==
+    input.revision.activeOverrideManifestSha256 !==
       activeOverrideManifestHash(input.activeOverrides)
   ) {
     throw new ContextRevisionError(
       "Active revision does not match canonical planning input.",
     );
   }
+  if (
+    input.activeOverrides.some(
+      (override) => override.ordinal < input.revision.keepFromOrdinal,
+    )
+  ) {
+    throw new ContextRevisionError(
+      "Active swap planning input contains a retired override.",
+    );
+  }
   if (
     input.forcedTargetTokens !== undefined &&
     (!Number.isSafeInteger(input.forcedTargetTokens) || input.forcedTargetTokens < 0)
@@ -654,7 +676,7 @@ function createPlan(input: {
   guardedTokensAfter: number;
 }): SwapRevisionPlan {
   const planningInput = input.input;
-  const nextOverrideManifestSha256 = activeOverrideManifestHash([
+  const nextActiveOverrideManifestSha256 = activeOverrideManifestHash([
     ...planningInput.activeOverrides,
     ...input.addedOverrides,
   ]);
@@ -663,8 +685,10 @@ function createPlan(input: {
     policyVersion: "swap-only-v1",
     baseRevisionId: planningInput.active.revisionId,
     baseRevisionNumber: planningInput.revision.revisionNumber,
+    baseKeepFromOrdinal: planningInput.revision.keepFromOrdinal,
     baseCanonicalThroughOrdinal: planningInput.active.canonicalThroughOrdinal,
-    baseOverrideManifestSha256: planningInput.revision.overrideManifestSha256,
+    baseActiveOverrideManifestSha256:
+      planningInput.revision.activeOverrideManifestSha256,
     basePrefixHash: input.activeFingerprint.prefixHash,
     requestConfigHash: input.activeFingerprint.requestConfigHash,
     toolSchemaHash: input.activeFingerprint.toolSchemaHash,
@@ -673,7 +697,7 @@ function createPlan(input: {
       originalContentSha256: override.originalContentSha256,
       renderedContentSha256: override.renderedContentSha256,
     })),
-    nextOverrideManifestSha256,
+    nextActiveOverrideManifestSha256,
     targetTokens: input.targetTokens,
     projectedPrefixHash: input.projectedFingerprint.prefixHash,
   } as const;

package/src/events/observation-text-log.ts

@@ -10,7 +10,7 @@ export class ObservationTextLog implements EventSink {
   constructor(private readonly filePath: string) {}
 
   async append(event: AgentEvent): Promise<void> {
-    const text = renderObservationLogBlock(event);
+    const text = renderObservationLogEvent(event);
     if (text === undefined) {
       return;
     }
@@ -19,7 +19,7 @@ export class ObservationTextLog implements EventSink {
   }
 }
 
-function renderObservationLogBlock(event: AgentEvent): string | undefined {
+export function renderObservationLogEvent(event: AgentEvent): string | undefined {
   switch (event.type) {
     case "session.started":
       return renderSessionStarted(event);
@@ -72,7 +72,7 @@ function renderTurnStarted(
   return [
     `## Turn ${event.turnNumber ?? ""} - Prompt`,
     "",
-    event.data.userPrompt,
+    event.data.userPrompt.text,
     "",
     "---",
     "",

package/src/events/stdout-event-printer.ts

@@ -24,7 +24,7 @@ export class StdoutEventPrinter implements EventSink {
         break;
       case "session.resumed":
         this.stdout.write(
-          `session.resumed sessionId=${event.sessionId} openCount=${event.data.openCount} recallIndexRebuilt=${event.data.recallIndexRebuilt}\n`,
+          `session.resumed sessionId=${event.sessionId} openCount=${event.data.openCount} recallIndexRebuilt=${event.data.recallIndexRebuilt}${event.data.contextRefresh === undefined ? "" : ` contextRevision=${event.data.contextRefresh.revisionNumber}`}\n`,
         );
         break;
       case "session.interrupted_frame_recovered":
@@ -67,12 +67,24 @@ export class StdoutEventPrinter implements EventSink {
         break;
       case "context.revision.started":
         this.stdout.write(
-          `context.revision.started reason=${event.data.reason} policy=${event.data.policyVersion}\n`,
+          event.data.strategy === "swap"
+            ? `context.revision.started reason=${event.data.reason} policy=${event.data.policyVersion}\n`
+            : event.data.strategy === "surface_refresh"
+              ? `context.revision.started reason=${event.data.reason} strategy=surface_refresh changed=${event.data.changed.join(",")}\n`
+              : event.data.strategy === "skills_update"
+                ? `context.revision.started reason=${event.data.reason} strategy=skills_update names=${event.data.names.join(",")}\n`
+                : `context.revision.started reason=${event.data.reason} strategy=retire_prefix policy=${event.data.policyVersion}\n`,
         );
         break;
       case "context.revision.finished":
         this.stdout.write(
-          `context.revision.finished outcome=${event.data.outcome} revision=${event.data.revisionNumber ?? event.data.baseRevisionNumber} added=${event.data.addedOverrideCount} before=${event.data.guardedTokensBefore} after=${event.data.guardedTokensAfter ?? "n/a"}\n`,
+          event.data.strategy === "swap"
+            ? `context.revision.finished outcome=${event.data.outcome} revision=${event.data.revisionNumber ?? event.data.baseRevisionNumber} added=${event.data.addedOverrideCount} before=${event.data.guardedTokensBefore} after=${event.data.guardedTokensAfter ?? "n/a"}\n`
+            : event.data.strategy === "surface_refresh"
+              ? `context.revision.finished strategy=surface_refresh revision=${event.data.revisionNumber} changed=${event.data.changed.join(",")} tools=${event.data.toolCountBefore}->${event.data.toolCountAfter}\n`
+              : event.data.strategy === "skills_update"
+                ? `context.revision.finished strategy=skills_update revision=${event.data.revisionNumber} activated=${event.data.activated.join(",")} refreshed=${event.data.refreshed.join(",")} deactivated=${event.data.deactivated.join(",")} unavailable=${event.data.unavailable.join(",")}\n`
+                : `context.revision.finished strategy=retire_prefix outcome=${event.data.outcome} revision=${event.data.revisionNumber ?? event.data.baseRevisionNumber} retired_turns=${event.data.retiredTurnCount} before=${event.data.guardedTokensBefore} after=${event.data.guardedTokensAfter ?? "n/a"}\n`,
         );
         break;
       case "context.revision.failed":
@@ -151,6 +163,16 @@ export class StdoutEventPrinter implements EventSink {
       case "session.finished":
         this.stdout.write(`session.finished reason=${event.data.reason}\n`);
         break;
+      case "skills.catalog.loaded":
+        this.stdout.write(
+          `skills.catalog.loaded available=${event.data.availableCount} active=${event.data.activeNames.join(",")} shadowed=${event.data.shadowedNames.join(",")}\n`,
+        );
+        break;
+      case "skills.updated":
+        this.stdout.write(
+          `skills.updated reason=${event.data.reason} activated=${event.data.activated.join(",")} refreshed=${event.data.refreshed.join(",")} deactivated=${event.data.deactivated.join(",")} unavailable=${event.data.unavailable.join(",")}\n`,
+        );
+        break;
       default:
         break;
     }
@@ -168,6 +190,8 @@ function formatToolRawResult(call: ToolCall, raw: ToolRawResult): string[] {
     case "task_list":
     case "task_stop":
       return optionalLine(formatTaskResult(call, raw));
+    case "skill":
+      return [formatSkillResult(raw)];
     case "read":
     case "glob":
     case "grep":
@@ -182,6 +206,18 @@ function formatToolRawResult(call: ToolCall, raw: ToolRawResult): string[] {
   }
 }
 
+function formatSkillResult(raw: Extract<ToolRawResult, { kind: "skill" }>): string {
+  if (!raw.ok) {
+    return `skill ${raw.name || "(unknown)"} failed -> ${boundedToolError(raw.error)}\n`;
+  }
+  return `skill ${raw.name} ${raw.status.replaceAll("_", " ")}\n`;
+}
+
+function boundedToolError(error: string): string {
+  const limit = 1_000;
+  return error.length <= limit ? error : `${error.slice(0, limit)}…`;
+}
+
 function optionalLine(line: string | undefined): string[] {
   return line === undefined ? [] : [line];
 }

package/src/events/types.ts

@@ -5,6 +5,7 @@ import type {
   TurnCancellation,
   TurnIdentity,
 } from "../agent/types";
+import type { UserPromptProjection } from "../agent/user-prompt-projection";
 import type {
   IterationId,
   ProtocolFrameId,
@@ -25,6 +26,7 @@ import type {
   ProjectInstructionFileName,
   ProjectInstructionManifest,
 } from "../instructions/project-instructions";
+import type { ContextSurfaceComponent } from "../context/context-surface";
 
 export type SessionStartedData = {
   workspaceRoot: string;
@@ -44,43 +46,165 @@ export type ContextUsageUpdatedData = {
   snapshot: ContextUsageSnapshot;
 };
 
-export type ContextRevisionStartedData = {
-  strategy: "swap";
-  reason: "manual";
-  policyVersion: "swap-only-v1";
-  rendererFormat: "swap-observation-v1";
-};
+export type ContextRevisionStartedData =
+  | {
+      strategy: "swap";
+      reason: "manual" | "runtime_pressure";
+      policyVersion: "swap-only-v1";
+      rendererFormat: "swap-observation-v1";
+      qualificationId?: string;
+    }
+  | {
+      strategy: "surface_refresh";
+      reason: "resume";
+      baseRevisionNumber: number;
+      changed: readonly ContextSurfaceComponent[];
+    }
+  | {
+      strategy: "retire_prefix";
+      reason: "manual" | "runtime_pressure";
+      policyVersion: "recall-first-retirement-v1";
+      baseRevisionNumber: number;
+      qualificationId?: string;
+    }
+  | {
+      strategy: "skills_update";
+      reason: "activation" | "resume";
+      baseRevisionNumber: number;
+      names: readonly string[];
+    };
 
-export type ContextRevisionFinishedData = {
-  strategy: "swap";
-  reason: "manual";
-  policyVersion: "swap-only-v1";
-  outcome:
-    | "below_target"
-    | "no_eligible_candidates"
-    | "target_reached"
-    | "insufficient_candidates";
-  baseRevisionNumber: number;
-  revisionNumber?: number;
-  addedOverrideCount: number;
-  totalOverrideCount: number;
-  originalObservationBytes: number;
-  projectedObservationBytes: number;
-  rawTokensBefore: number;
-  rawTokensAfter?: number;
-  guardedTokensBefore: number;
-  guardedTokensAfter?: number;
-  targetTokens: number;
-  planHash?: string;
-  durationMs: number;
+export type ContextRevisionFinishedData =
+  | {
+      strategy: "swap";
+      reason: "manual" | "runtime_pressure";
+      policyVersion: "swap-only-v1";
+      outcome:
+        | "below_trigger"
+        | "below_target"
+        | "no_eligible_candidates"
+        | "target_reached"
+        | "insufficient_candidates";
+      baseRevisionNumber: number;
+      revisionNumber?: number;
+      addedOverrideCount: number;
+      activeOverrideCount: number;
+      originalObservationBytes: number;
+      projectedObservationBytes: number;
+      rawTokensBefore: number;
+      rawTokensAfter?: number;
+      guardedTokensBefore: number;
+      guardedTokensAfter?: number;
+      targetTokens: number;
+      planHash?: string;
+      durationMs: number;
+      qualificationId?: string;
+    }
+  | {
+      strategy: "surface_refresh";
+      reason: "resume";
+      baseRevisionNumber: number;
+      revisionNumber: number;
+      changed: readonly ContextSurfaceComponent[];
+      toolCountBefore: number;
+      toolCountAfter: number;
+      measuredAnchorCleared: true;
+      durationMs: number;
+    }
+  | {
+      strategy: "retire_prefix";
+      reason: "manual" | "runtime_pressure";
+      policyVersion: "recall-first-retirement-v1";
+      outcome:
+        | "below_target"
+        | "no_complete_prefix"
+        | "target_reached"
+        | "retirement_floor";
+      baseRevisionNumber: 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;
+      qualificationId?: string;
+    }
+  | {
+      strategy: "skills_update";
+      reason: "activation" | "resume";
+      baseRevisionNumber: number;
+      revisionNumber: number;
+      activated: readonly string[];
+      refreshed: readonly string[];
+      deactivated: readonly string[];
+      unavailable: readonly string[];
+      addedOverrideCount: number;
+      measuredAnchorCleared: true;
+      durationMs: number;
+    };
+
+export type ContextRevisionFailedData =
+  | {
+      strategy: "swap";
+      reason: "manual" | "runtime_pressure";
+      stage: "snapshot" | "plan" | "validate" | "commit" | "activate";
+      errorCode: string;
+      error: string;
+      qualificationId?: string;
+    }
+  | {
+      strategy: "surface_refresh";
+      reason: "resume";
+      stage: "prepare" | "commit" | "activate";
+      errorCode: string;
+      error: string;
+      committed: boolean;
+    }
+  | {
+      strategy: "retire_prefix";
+      reason: "manual" | "runtime_pressure";
+      stage: "snapshot" | "plan" | "validate" | "commit" | "activate";
+      errorCode: string;
+      error: string;
+      committed: boolean;
+      qualificationId?: string;
+    }
+  | {
+      strategy: "skills_update";
+      reason: "activation" | "resume";
+      stage: "prepare" | "commit" | "activate";
+      errorCode: string;
+      error: string;
+      committed: boolean;
+    };
+
+export type SkillsCatalogLoadedData = {
+  availableCount: number;
+  projectCount: number;
+  userCount: number;
+  activeNames: readonly string[];
+  shadowedNames: readonly string[];
 };
 
-export type ContextRevisionFailedData = {
-  strategy: "swap";
-  reason: "manual";
-  stage: "snapshot" | "plan" | "validate" | "commit" | "activate";
-  errorCode: string;
-  error: string;
+export type SkillsUpdatedData = {
+  reason: "activation" | "resume";
+  activated: readonly string[];
+  refreshed: readonly string[];
+  deactivated: readonly string[];
+  unavailable: readonly string[];
+  revisionNumber?: number;
 };
 
 export type ContextShadowPlannedData = {
@@ -131,7 +255,16 @@ export type SessionResumedData = {
   recoveredFrameId?: ProtocolFrameId;
   syntheticCompletionCount: number;
   recallIndexRebuilt: boolean;
+  contextProfile: ModelContextProfile;
+  contextBudget: ModelContextBudget;
   projectInstructionFile?: ProjectInstructionFileName;
+  contextRefresh?: {
+    previousRevisionNumber: number;
+    revisionNumber: number;
+    changed: readonly ContextSurfaceComponent[];
+    toolCountBefore: number;
+    toolCountAfter: number;
+  };
 };
 
 export type InterruptedFrameRecoveredData = {
@@ -152,7 +285,7 @@ export type AgentEventDataMap = {
   "session.resumed": SessionResumedData;
   "session.interrupted_frame_recovered": InterruptedFrameRecoveredData;
   "session.finished": SessionFinishedData;
-  "turn.started": { userPrompt: string };
+  "turn.started": { userPrompt: UserPromptProjection };
   "turn.finished": TurnFinishedData;
   "turn.failed": { error: string };
   "turn.cancelled": { cancellation: TurnCancellation };
@@ -165,6 +298,8 @@ export type AgentEventDataMap = {
   "context.revision.failed": ContextRevisionFailedData;
   "context.shadow.planned": ContextShadowPlannedData;
   "context.shadow.failed": ContextShadowFailedData;
+  "skills.catalog.loaded": SkillsCatalogLoadedData;
+  "skills.updated": SkillsUpdatedData;
   "assistant.progress": { content: string };
   "tool.started": { call: ToolCall };
   "tool.raw_result": { call: ToolCall; raw: ToolRawResult };
@@ -237,6 +372,8 @@ export type AgentEventInput =
       | "context.revision.started"
       | "context.revision.finished"
       | "context.revision.failed"
+      | "skills.catalog.loaded"
+      | "skills.updated"
     >
   | SessionEventInput<"mcp.server.connected" | "mcp.server.failed">
   | SessionEventInput<"diagnostic.sink_failed">

package/src/ids/runtime-id.ts

@@ -1,4 +1,5 @@
 import { createUuidV7 } from "./uuid-v7";
+import type { ImageAttachmentId } from "../image/image-types";
 
 export type RuntimeId<Name extends string> = string & {
   readonly __runtimeId: Name;
@@ -11,6 +12,7 @@ export type ToolCallId = RuntimeId<"tool-call">;
 export type MessageId = RuntimeId<"message">;
 export type ProtocolFrameId = RuntimeId<"protocol-frame">;
 export type ContextRevisionId = RuntimeId<"context-revision">;
+export type ContextSurfaceId = RuntimeId<"context-surface">;
 
 export type RuntimeIdFactory = {
   createSessionId(): SessionId;
@@ -20,6 +22,8 @@ export type RuntimeIdFactory = {
   createMessageId(): MessageId;
   createProtocolFrameId(): ProtocolFrameId;
   createContextRevisionId(): ContextRevisionId;
+  createContextSurfaceId(): ContextSurfaceId;
+  createImageAttachmentId(): ImageAttachmentId;
 };
 
 export const runtimeIdFactory: RuntimeIdFactory = {
@@ -30,6 +34,8 @@ export const runtimeIdFactory: RuntimeIdFactory = {
   createMessageId: () => createUuidV7() as MessageId,
   createProtocolFrameId: () => createUuidV7() as ProtocolFrameId,
   createContextRevisionId: () => createUuidV7() as ContextRevisionId,
+  createContextSurfaceId: () => createUuidV7() as ContextSurfaceId,
+  createImageAttachmentId: () => createUuidV7() as ImageAttachmentId,
 };
 
 const canonicalUuidV7Pattern =

package/src/ids/uuid-v7.ts

@@ -1,5 +1,12 @@
 import { v7 as uuidv7 } from "uuid";
 
+const CANONICAL_UUID_V7_PATTERN =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+
 export function createUuidV7(): string {
   return uuidv7();
 }
+
+export function isCanonicalUuidV7(value: string): boolean {
+  return CANONICAL_UUID_V7_PATTERN.test(value);
+}