tinker-agent 1.0.65 → 1.2.0

package/src/cli/model-profiles.ts

@@ -13,6 +13,20 @@ export type ModelProfile = {
   readonly contextWindowTokens: number;
   readonly maxSupportedOutputTokens: number;
   readonly includeReasoningContent: boolean;
+  readonly stream: boolean;
+  readonly inputModalities: readonly ModelInputModality[];
+  readonly tokenEstimator?: ModelTokenEstimatorProfile;
+};
+
+export type ModelInputModality = "text" | "image";
+
+export type ModelTokenEstimatorProfile = {
+  readonly kind: "moonshot-estimate-token-count-v1";
+  readonly model: string;
+  readonly apiBase: string;
+  readonly apiKey: string;
+  readonly timeoutMs: number;
+  readonly maxRetries: 0;
 };
 
 export type ModelProfiles = {
@@ -222,6 +236,22 @@ function parseProfile(
     throw new Error(`${where} must be an object.`);
   }
 
+  assertKnownKeys(
+    value,
+    [
+      "model",
+      "apiBase",
+      "apiKey",
+      "contextWindowTokens",
+      "maxSupportedOutputTokens",
+      "includeReasoningContent",
+      "stream",
+      "inputModalities",
+      "tokenEstimator",
+    ],
+    where,
+  );
+
   const model = requireString(value.model, `${where}: "model"`);
   const apiBase = requireString(value.apiBase, `${where}: "apiBase"`);
   const apiKey = requireString(value.apiKey, `${where}: "apiKey"`);
@@ -243,6 +273,25 @@ function parseProfile(
           `${where}: "includeReasoningContent"`,
         );
 
+  const stream =
+    value.stream === undefined
+      ? true
+      : parseBoolean(value.stream, `${where}: "stream"`);
+
+  const inputModalities = parseInputModalities(
+    value.inputModalities,
+    `${where}: "inputModalities"`,
+  );
+  const tokenEstimator =
+    value.tokenEstimator === undefined
+      ? undefined
+      : parseTokenEstimator(value.tokenEstimator, `${where}: "tokenEstimator"`);
+  if (inputModalities.includes("image") && tokenEstimator === undefined) {
+    throw new Error(
+      `${where}: image input requires a complete "tokenEstimator" configuration.`,
+    );
+  }
+
   createModelContextProfile({
     contextWindowTokens,
     maxSupportedOutputTokens,
@@ -256,9 +305,84 @@ function parseProfile(
     contextWindowTokens,
     maxSupportedOutputTokens,
     includeReasoningContent,
+    stream,
+    inputModalities,
+    ...(tokenEstimator === undefined ? {} : { tokenEstimator }),
+  });
+}
+
+function parseInputModalities(
+  value: unknown,
+  name: string,
+): readonly ModelInputModality[] {
+  if (value === undefined) {
+    return Object.freeze(["text"]);
+  }
+  if (!Array.isArray(value) || value.length === 0) {
+    throw new Error(`${name} must be a non-empty array.`);
+  }
+  const modalities = value.map((rawEntry): ModelInputModality => {
+    const entry: unknown = rawEntry;
+    if (entry !== "text" && entry !== "image") {
+      throw new Error(`${name} contains an unsupported modality.`);
+    }
+    return entry;
+  });
+  if (new Set(modalities).size !== modalities.length) {
+    throw new Error(`${name} must not contain duplicates.`);
+  }
+  if (!modalities.includes("text")) {
+    throw new Error(`${name} must include "text".`);
+  }
+  return Object.freeze(
+    modalities.includes("image") ? (["text", "image"] as const) : (["text"] as const),
+  );
+}
+
+function parseTokenEstimator(value: unknown, name: string): ModelTokenEstimatorProfile {
+  if (!isRecord(value)) {
+    throw new Error(`${name} must be an object.`);
+  }
+  assertKnownKeys(
+    value,
+    ["kind", "model", "apiBase", "apiKey", "timeoutMs", "maxRetries"],
+    name,
+  );
+  if (value.kind !== "moonshot-estimate-token-count-v1") {
+    throw new Error(`${name}.kind must be "moonshot-estimate-token-count-v1".`);
+  }
+  const model = requireString(value.model, `${name}.model`);
+  const apiBase = requireString(value.apiBase, `${name}.apiBase`);
+  const apiKey = requireString(value.apiKey, `${name}.apiKey`);
+  const timeoutMs = requirePositiveInteger(value.timeoutMs, `${name}.timeoutMs`);
+  if (timeoutMs < 1_000 || timeoutMs > 60_000) {
+    throw new Error(`${name}.timeoutMs must be between 1000 and 60000.`);
+  }
+  if (value.maxRetries !== 0) {
+    throw new Error(`${name}.maxRetries must be 0.`);
+  }
+  return Object.freeze({
+    kind: value.kind,
+    model,
+    apiBase,
+    apiKey,
+    timeoutMs,
+    maxRetries: 0,
   });
 }
 
+function assertKnownKeys(
+  value: Record<string, unknown>,
+  allowed: readonly string[],
+  name: string,
+): void {
+  const allowedSet = new Set(allowed);
+  const unknown = Object.keys(value).find((key) => !allowedSet.has(key));
+  if (unknown !== undefined) {
+    throw new Error(`${name} contains unknown field ${JSON.stringify(unknown)}.`);
+  }
+}
+
 function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }

package/src/cli/run-runner.ts

@@ -19,6 +19,7 @@ import {
 } from "./config";
 import { loadModelProfiles } from "./model-profiles";
 import { realpath } from "node:fs/promises";
+import { loadSkillCatalog } from "../skills/skill-loader";
 
 export type RunOneShotOptions = RunnerConfigOverrides & {
   modelClient?: ModelClient;
@@ -44,6 +45,7 @@ export async function runOneShot(
     const config = readRunnerConfig(options, profiles);
     const workspaceRoot = await realpath(config.workspaceRoot);
     const projectInstructions = await loadProjectInstructions(workspaceRoot);
+    const skillCatalog = await loadSkillCatalog({ workspaceRoot });
     const systemPrompt = buildSystemPrompt({
       workspaceRoot,
       runtimeInstructions: RUNTIME_INSTRUCTIONS(workspaceRoot),
@@ -61,6 +63,7 @@ export async function runOneShot(
       contextBudget: config.contextBudget,
       systemPrompt,
       projectInstruction: projectInstructionManifest(projectInstructions),
+      skillCatalog,
       modelClient,
       presentationSinks: [new StdoutEventPrinter(stdout, stderr)],
       persistence:
@@ -69,7 +72,7 @@ export async function runOneShot(
     });
 
     const result = await session.executeTurn({
-      userPrompt,
+      userMessage: { role: "user", content: userPrompt },
       signal: new AbortController().signal,
     });
     if (result.status === "completed") {

package/src/cli/tui-runner.tsx

@@ -24,6 +24,7 @@ import {
   DefaultTuiSessionController,
   managedTuiBinding,
   type ManagedTuiSessionBinding,
+  type TuiSessionBinding,
 } from "../tui/tui-session-controller";
 import {
   createRunnerModelClient,
@@ -39,6 +40,8 @@ import {
   resolveSessionProfileName,
   type ModelProfile,
 } from "./model-profiles";
+import { loadSkillCatalog } from "../skills/skill-loader";
+import { loadProjectSlashCommands } from "../tui/project-slash-commands";
 
 export async function runTui(options: { profileName?: string } = {}): Promise<void> {
   const profiles = await loadModelProfiles();
@@ -54,6 +57,7 @@ export async function runTui(options: { profileName?: string } = {}): Promise<vo
   let quitRequested = false;
 
   try {
+    const projectSlashCommands = await loadProjectSlashCommands(workspaceRoot);
     const createSessionForConfig = async (
       sessionConfig: RunnerConfig,
       mode: "new" | "resume",
@@ -61,6 +65,8 @@ export async function runTui(options: { profileName?: string } = {}): Promise<vo
       sink: EventSink,
     ): Promise<RuntimeSession> => {
       const modelClient = createRunnerModelClient(sessionConfig);
+      const projectInstructions = await loadProjectInstructions(workspaceRoot);
+      const skillCatalog = await loadSkillCatalog({ workspaceRoot });
       const common = {
         workspaceRoot,
         modelName: sessionConfig.modelName,
@@ -70,6 +76,13 @@ export async function runTui(options: { profileName?: string } = {}): Promise<vo
         contextProfile: sessionConfig.contextProfile,
         contextBudget: sessionConfig.contextBudget,
         modelClient,
+        systemPrompt: buildSystemPrompt({
+          workspaceRoot,
+          runtimeInstructions: RUNTIME_INSTRUCTIONS(workspaceRoot),
+          projectInstructions,
+        }),
+        projectInstruction: projectInstructionManifest(projectInstructions),
+        skillCatalog,
         presentationSinks: [sink],
         webFetchRefiner: createWebFetchRefinerFromEnv(sessionConfig),
       };
@@ -80,16 +93,9 @@ export async function runTui(options: { profileName?: string } = {}): Promise<vo
         });
       }
 
-      const projectInstructions = await loadProjectInstructions(workspaceRoot);
       return createRuntimeSession({
         ...common,
         selection: { mode, sessionId },
-        systemPrompt: buildSystemPrompt({
-          workspaceRoot,
-          runtimeInstructions: RUNTIME_INSTRUCTIONS(workspaceRoot),
-          projectInstructions,
-        }),
-        projectInstruction: projectInstructionManifest(projectInstructions),
       });
     };
 
@@ -159,41 +165,71 @@ export async function runTui(options: { profileName?: string } = {}): Promise<vo
       });
     };
 
-    const createSessionWithProfile = async (
-      profile: ModelProfile,
+    const createNewSessionBinding = async (
+      sessionConfig: RunnerConfig,
     ): Promise<ManagedTuiSessionBinding> => {
-      if (profiles === undefined) {
-        throw new Error("Model profiles are not configured.");
-      }
-      const profileConfig = readRunnerConfig(
-        {
-          sessionId: createUuidV7() as SessionId,
-          workspaceRoot: config.workspaceRoot,
-          profileName: profile.name,
-          maxIterations: config.maxIterations,
-        },
-        profiles,
-      );
-      const profileProjectionStore = new TuiProjectionStore({
-        sessionId: profileConfig.sessionId,
-        modelName: profileConfig.modelName,
+      const freshProjectionStore = new TuiProjectionStore({
+        sessionId: sessionConfig.sessionId,
+        modelName: sessionConfig.modelName,
         workspaceRoot,
       });
       const runtimeSession = await createSessionForConfig(
-        profileConfig,
+        sessionConfig,
         "new",
-        profileConfig.sessionId,
-        profileProjectionStore,
+        sessionConfig.sessionId,
+        freshProjectionStore,
       );
       return managedTuiBinding({
         runtimeSession,
-        modelName: profileConfig.modelName,
+        modelName: sessionConfig.modelName,
         workspaceRoot,
-        profileName: profile.name,
-        projectionStore: profileProjectionStore,
+        profileName: sessionConfig.profileName,
+        projectionStore: freshProjectionStore,
       });
     };
 
+    const createSessionWithProfile = async (
+      profile: ModelProfile,
+    ): Promise<ManagedTuiSessionBinding> => {
+      if (profiles === undefined) {
+        throw new Error("Model profiles are not configured.");
+      }
+      return createNewSessionBinding(
+        readRunnerConfig(
+          {
+            sessionId: createUuidV7() as SessionId,
+            workspaceRoot: config.workspaceRoot,
+            profileName: profile.name,
+            maxIterations: config.maxIterations,
+          },
+          profiles,
+        ),
+      );
+    };
+
+    const createFreshSession = async (
+      current: TuiSessionBinding,
+    ): Promise<ManagedTuiSessionBinding> => {
+      const sessionId = createUuidV7() as SessionId;
+      if (profiles === undefined) {
+        return createNewSessionBinding({ ...config, sessionId });
+      }
+      if (current.profileName === undefined) {
+        throw new Error("Current session does not have a model profile.");
+      }
+      return createNewSessionBinding(
+        readRunnerConfig(
+          {
+            sessionId,
+            workspaceRoot: config.workspaceRoot,
+            profileName: current.profileName,
+            maxIterations: config.maxIterations,
+          },
+          profiles,
+        ),
+      );
+    };
+
     controller = new DefaultTuiSessionController(
       managedTuiBinding({
         runtimeSession: initialSession,
@@ -205,6 +241,7 @@ export async function runTui(options: { profileName?: string } = {}): Promise<vo
       catalog,
       openStoredSession,
       createSessionWithProfile,
+      createFreshSession,
     );
 
     instance = render(
@@ -212,6 +249,7 @@ export async function runTui(options: { profileName?: string } = {}): Promise<vo
         sessionController={controller}
         readGitBranch={readCurrentGitBranch}
         history={promptHistory}
+        projectSlashCommands={projectSlashCommands}
         profiles={profiles}
         persistDefaultProfile={persistDefaultProfile}
         onQuit={() => {

package/src/context/compiled-context-hash.ts

@@ -92,7 +92,7 @@ export function activeOverrideManifestHash(overrides: readonly SwapOverride[]):
           ordinal: override.ordinal,
           originalContentSha256: override.originalContentSha256,
           renderedContentSha256: override.renderedContentSha256,
-          rendererFormat: "swap-observation-v1",
+          rendererFormat: override.rendererFormat ?? "swap-observation-v1",
         })),
     ),
   );

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

@@ -2,6 +2,7 @@ import type { AgentMessage } from "../agent/types";
 import { stableJsonStringify } from "../model/model-request-preflight";
 import { formatMessageSource } from "./context-source";
 import type { CompiledRevisionContext, SwapOverride } from "./context-revision";
+import type { StoredContextSurfaceV8 } from "./context-surface";
 import {
   contentHash,
   type CanonicalMessageRecord,
@@ -21,38 +22,89 @@ export class CompiledContextValidator {
     compiled: CompiledRevisionContext,
     canonical: ProtocolContextView,
     overrides: readonly SwapOverride[],
+    surface: StoredContextSurfaceV8,
   ): void {
     const byMessageId = overrideMap(overrides, "Active");
-    this.validate(compiled, canonical, byMessageId);
+    this.validate(compiled, canonical, byMessageId, surface);
   }
 
   validateProspective(
     compiled: CompiledRevisionContext,
     canonical: ProtocolContextView,
     overrides: readonly SwapOverride[],
+    surface: StoredContextSurfaceV8,
   ): void {
     const byMessageId = overrideMap(overrides, "Prospective");
-    this.validate(compiled, canonical, byMessageId);
+    this.validate(compiled, canonical, byMessageId, surface);
   }
 
   private validate(
     compiled: CompiledRevisionContext,
     canonical: ProtocolContextView,
     overrides: ReadonlyMap<string, SwapOverride>,
+    surface: StoredContextSurfaceV8,
   ): void {
     if (compiled.sessionId !== canonical.sessionId) {
       fail("Compiled context belongs to another session.");
     }
-    if (compiled.entries.length !== canonical.messages.length) {
-      fail("Compiled context changed the canonical message count.");
+    const keepFromOrdinal = compiled.manifest.keepFromOrdinal;
+    if (
+      !Number.isSafeInteger(keepFromOrdinal) ||
+      keepFromOrdinal < 1 ||
+      keepFromOrdinal > canonical.messages.length
+    ) {
+      fail("Compiled context keep boundary is invalid.");
+    }
+    const activeRecords =
+      keepFromOrdinal === 1
+        ? canonical.messages
+        : [
+            requireItem(canonical.messages, 0, "canonical system message"),
+            ...canonical.messages.slice(keepFromOrdinal - 1),
+          ];
+    const activeFrames =
+      keepFromOrdinal === 1
+        ? canonical.frames
+        : [
+            requireItem(canonical.frames, 0, "canonical system frame"),
+            ...canonical.frames.filter(
+              (frame) => frame.firstOrdinal >= keepFromOrdinal,
+            ),
+          ];
+    if (keepFromOrdinal > 1) {
+      const boundaryMessage = canonical.messages[keepFromOrdinal - 1];
+      const boundaryFrame = canonical.frames.find(
+        (frame) => frame.firstOrdinal === keepFromOrdinal,
+      );
+      if (
+        boundaryMessage?.ordinal !== keepFromOrdinal ||
+        boundaryMessage.role !== "user" ||
+        boundaryFrame?.kind !== "user" ||
+        boundaryFrame.state !== "closed" ||
+        boundaryFrame.lastOrdinal !== keepFromOrdinal
+      ) {
+        fail("Compiled context keep boundary does not start a closed user frame.");
+      }
+    }
+    if (compiled.entries.length !== activeRecords.length) {
+      fail("Compiled context does not match the active message projection.");
     }
     if (
       compiled.canonicalThroughOrdinal !== canonical.messages.length ||
-      compiled.manifest.frameCount !== canonical.frames.length ||
-      compiled.manifest.messageCount !== compiled.entries.length
+      compiled.manifest.canonicalFrameCount !== canonical.frames.length ||
+      compiled.manifest.canonicalMessageCount !== canonical.messages.length ||
+      compiled.manifest.activeFrameCount !== activeFrames.length ||
+      compiled.manifest.activeMessageCount !== compiled.entries.length
     ) {
       fail("Compiled context manifest counts do not match canonical history.");
     }
+    if (overrides.size > 0) {
+      for (const override of overrides.values()) {
+        if (override.ordinal < keepFromOrdinal) {
+          fail("Compiled context contains an override before its keep boundary.");
+        }
+      }
+    }
 
     const seenFrames = new Set<string>();
     const seenMessages = new Set<string>();
@@ -61,7 +113,7 @@ export class CompiledContextValidator {
 
     for (let index = 0; index < compiled.entries.length; index += 1) {
       const entry = requireItem(compiled.entries, index, "compiled entry");
-      const record = requireItem(canonical.messages, index, "canonical message");
+      const record = requireItem(activeRecords, index, "active canonical message");
       if (
         entry.frameId !== record.frameId ||
         entry.messageId !== record.messageId ||
@@ -79,10 +131,19 @@ export class CompiledContextValidator {
 
       const override = overrides.get(entry.messageId);
       if (override === undefined) {
-        if (entry.representation !== "canonical") {
-          fail(`Unapproved swapped entry at ordinal ${entry.ordinal}.`);
+        if (entry.representation === "canonical") {
+          assertSameMessage(entry.message, record);
+          continue;
+        }
+        if (
+          entry.representation !== "surface" ||
+          record.ordinal !== 1 ||
+          record.role !== "system" ||
+          entry.message.role !== "system" ||
+          entry.message.content !== surface.systemPrompt
+        ) {
+          fail(`Unapproved surface entry at ordinal ${entry.ordinal}.`);
         }
-        assertSameMessage(entry.message, record);
         continue;
       }
 
@@ -104,15 +165,19 @@ export class CompiledContextValidator {
       }
     }
 
-    if (seenFrames.size !== canonical.frames.length) {
-      fail("Compiled entries do not preserve every protocol frame.");
+    if (
+      seenFrames.size !== activeFrames.length ||
+      activeFrames.some((frame) => !seenFrames.has(frame.frameId))
+    ) {
+      fail("Compiled entries do not preserve every active protocol frame.");
     }
     if (consumedOverrides.size !== overrides.size) {
       fail("A prospective override does not reference canonical history.");
     }
     if (
       compiled.manifest.canonicalSequenceHash !== canonicalSequenceHash(canonical) ||
-      compiled.manifest.renderedMessageHash !== renderedMessageHash(compiled.entries)
+      compiled.manifest.renderedMessageHash !== renderedMessageHash(compiled.entries) ||
+      compiled.manifest.surfaceSha256 !== surface.surfaceSha256
     ) {
       fail("Compiled context manifest hash does not match its entries.");
     }
@@ -136,13 +201,16 @@ function validateOverrideIdentity(
     "utf8",
   );
   const renderedBytes = Buffer.byteLength(override.renderedContent, "utf8");
+  const rendererFormat = override.rendererFormat ?? "swap-observation-v1";
   if (
     override.source !== formatMessageSource(record.messageId) ||
     override.renderedContentSha256 !== contentHash(override.renderedContent) ||
     override.originalBytes !== originalBytes ||
     override.renderedBytes !== renderedBytes ||
     override.byteSavings !== originalBytes - renderedBytes ||
-    override.byteSavings <= 0
+    (rendererFormat === "swap-observation-v1" && override.byteSavings <= 0) ||
+    (rendererFormat !== "swap-observation-v1" &&
+      rendererFormat !== "skill-activation-receipt-v1")
   ) {
     fail(`Swap override metadata is invalid at ordinal ${record.ordinal}.`);
   }
@@ -167,11 +235,20 @@ function assertSameMessage(actual: AgentMessage, record: CanonicalMessageRecord)
   }
   switch (record.role) {
     case "system":
-    case "user":
       if (actual.role !== record.role || actual.content !== record.content) {
         fail(`Canonical entry changed message content at ordinal ${record.ordinal}.`);
       }
       return;
+    case "user":
+      if (
+        actual.role !== "user" ||
+        actual.content !== record.content ||
+        stableJsonStringify(actual.attachments ?? null) !==
+          stableJsonStringify(record.attachments ?? null)
+      ) {
+        fail(`Canonical entry changed user data at ordinal ${record.ordinal}.`);
+      }
+      return;
     case "assistant":
       if (
         actual.role !== "assistant" ||

package/src/context/context-automation-policy.ts

@@ -0,0 +1,121 @@
+import { stableJsonStringify, sha256 } from "../model/model-request-preflight";
+import { RECALL_TOOL_DEFINITION } from "../tools/recall";
+import type { ToolDefinition } from "../tools/types";
+import type { StoredContextSurfaceV8 } from "./context-surface";
+import {
+  CURRENT_RECALL_RETIREMENT_CONTRACT_VERSION,
+  renderRecallRetirementContract,
+} from "./recall-retirement-contract";
+
+export const I4_ACTIVE_RECALL_QUALIFICATION = Object.freeze({
+  qualificationId: "deepseek-v4-flash-floor-v1",
+  evaluatedProfile: "deepseek-v4-flash",
+  manifestVersion: "active-recall-manifest-v1",
+  manifestSha256: "093679e221e02b71ba5acf54693faa7a299d05dd25f6faabbeb84645d4db4d2d",
+  graderVersion: "active-recall-deterministic-grader-v1",
+  fixtureVersion: "active-recall-long-session-fixture-v1",
+  policyVersion: "active-recall-qualification-policy-v1",
+  policySha256: "77ca611594d4e9b7b5a597a3a33e35fcaaffae284dc2ac9953ce9a63cce1c009",
+  positiveReportSha256:
+    "ef84dfee3fdefd7bbf1be2f1641bccc4a1aa06874b22172fecc03dfa2db840d6",
+  negativeReportSha256:
+    "c991980ae2824102174315c9b25c1e4affdbbd22aac320e1a254f2702ba3d1b4",
+  resolvedModel: "deepseek-v4-flash",
+  recallContractVersion: CURRENT_RECALL_RETIREMENT_CONTRACT_VERSION,
+  recallContractSha256:
+    "c75108d351ed3223928ebeb52c7258a6f95033287a8e560fb5b2efff8e084c9b",
+  recallToolDefinitionSha256:
+    "60caf87f313ea35e74e278ab8b30337cc8af1cc83d82d957a73857a764f3e3d9",
+  metrics: Object.freeze({
+    fullHistoryTaskSuccessRate: 1,
+    swapOnlyTaskSuccessRate: 1,
+    recallOnlyTaskSuccessRate: 0.9667,
+    recallOnlyActiveRecallRate: 0.9667,
+    recallOnlySearchGetSuccessRate: 0.3,
+    minimumCounterfactualGroupTaskSuccessRate: 0.8333,
+    invalidRecallCallsPerRecallOnlyTrial: 0.0333,
+    negativeUnnecessaryRecallRate: 0,
+    recallOnlyTokenRatioToFullHistory: 1.1555,
+    recallOnlyLatencyRatioToFullHistory: 1.365,
+  }),
+  passed: true,
+} as const);
+
+export const I4_SWAP_ONLY_QUALIFICATION_ID = "swap-only-engineering-v1";
+
+export type ActiveRecallQualificationEvidence = {
+  readonly qualificationId: string;
+  readonly recallContractVersion: string;
+  readonly recallContractSha256: string;
+  readonly recallToolDefinitionSha256: string;
+  readonly passed: boolean;
+};
+
+export type ContextAutomationDecision = {
+  readonly automaticSwapOnly: boolean;
+  readonly automaticPrefixRetirement: boolean;
+  readonly reason:
+    | "qualified"
+    | "swap_only_qualified"
+    | "qualification_pending"
+    | "unprofiled_model"
+    | "recall_contract_mismatch"
+    | "recall_tool_mismatch";
+  readonly qualificationId?: string;
+};
+
+export function selectContextAutomation(
+  input: {
+    readonly profileName?: string;
+    readonly surface: StoredContextSurfaceV8;
+  },
+  evidence: ActiveRecallQualificationEvidence = I4_ACTIVE_RECALL_QUALIFICATION,
+): ContextAutomationDecision {
+  if (input.profileName === undefined) {
+    return disabled("unprofiled_model");
+  }
+  if (
+    input.surface.recallContractVersion !== evidence.recallContractVersion ||
+    sha256(renderRecallRetirementContract()) !== evidence.recallContractSha256
+  ) {
+    return disabled("recall_contract_mismatch");
+  }
+  const recall = input.surface.toolDefinitions.find(
+    (definition) => definition.name === "Recall",
+  );
+  if (
+    recall === undefined ||
+    toolDefinitionHash(recall) !== evidence.recallToolDefinitionSha256 ||
+    toolDefinitionHash(RECALL_TOOL_DEFINITION) !== evidence.recallToolDefinitionSha256
+  ) {
+    return disabled("recall_tool_mismatch");
+  }
+  if (!evidence.passed) {
+    return Object.freeze({
+      automaticSwapOnly: true,
+      automaticPrefixRetirement: false,
+      reason: "swap_only_qualified",
+      qualificationId: I4_SWAP_ONLY_QUALIFICATION_ID,
+    });
+  }
+  return Object.freeze({
+    automaticSwapOnly: true,
+    automaticPrefixRetirement: true,
+    reason: "qualified",
+    qualificationId: evidence.qualificationId,
+  });
+}
+
+function disabled(
+  reason: Exclude<ContextAutomationDecision["reason"], "qualified">,
+): ContextAutomationDecision {
+  return Object.freeze({
+    automaticSwapOnly: false,
+    automaticPrefixRetirement: false,
+    reason,
+  });
+}
+
+function toolDefinitionHash(definition: ToolDefinition): string {
+  return sha256(stableJsonStringify(definition));
+}