tinker-agent 1.0.65 → 1.2.0

package/src/agent/runtime-session.ts

@@ -15,15 +15,35 @@ import {
   type SessionId,
 } from "../ids/runtime-id";
 import { loadMcpConfig } from "../mcp/mcp-config";
-import { createMcpManager, type McpManager } from "../mcp/mcp-manager";
-import type { ModelClient } from "../model/model-client";
+import {
+  createMcpManager,
+  type McpInventorySnapshot,
+  type McpManager,
+} from "../mcp/mcp-manager";
+import {
+  materializeModelRequest,
+  ModelRequestMediaAggregateError,
+  type MaterializedModelRequest,
+  type ModelClient,
+} from "../model/model-client";
+import { ImageAssetStore, type ImportedImageAsset } from "../image/image-asset-store";
+import { IMAGE_INPUT_POLICY } from "../image/image-input-policy";
+import {
+  validateUserMessage,
+  type ImageAssetRef,
+  type UserMessage,
+} from "../image/image-types";
+import { projectUserMessage } from "./user-prompt-projection";
 import { CommittedPrefixAuditor } from "../model/committed-prefix-auditor";
 import { SwapPlanner } from "../context/swap-planner";
 import {
+  commitAgentSkillsContextUpdate,
   ContextManager,
   ContextManagerError,
   type ContextCompactionResult,
   type ContextCompactionTrigger,
+  type ContextRetirementResult,
+  type ContextRetirementTrigger,
 } from "../context/context-manager";
 import {
   assertMatchingContextBudget,
@@ -33,20 +53,45 @@ import {
 import { ObservationBuilder } from "../observation/observation-builder";
 import { ContextProtocolError } from "../context/context-protocol-validator";
 import { CompiledContextError } from "../context/compiled-context-validator";
-import { ContextRevisionError } from "../context/context-revision-compiler";
+import {
+  ContextRevisionCompiler,
+  ContextRevisionError,
+} from "../context/context-revision-compiler";
+import {
+  changedContextSurfaceComponents,
+  contextSurfaceChangeManifestHash,
+  contextSurfaceChanges,
+  createContextSurface,
+  sameContextSurface,
+  type ContextSurfaceComponent,
+  type StoredContextSurfaceV8,
+} from "../context/context-surface";
+import {
+  canonicalSequenceHash,
+  renderedMessageHash,
+} from "../context/compiled-context-hash";
 import { createDefaultTooling, type DefaultTooling } from "../tools/registry";
 import type { Refiner } from "../tools/web-fetch/refiner";
 import type { ProjectInstructionManifest } from "../instructions/project-instructions";
 import {
   SessionStore,
-  createRuntimeContract,
+  createSessionCompatibilityContract,
   type SessionRecoveryResult,
+  type StoredSkillActivation,
 } from "../session/session-store";
 import { SqliteSessionLedger } from "../session/sqlite-session-ledger";
 import { SessionError } from "../session/session-errors";
 import { FatalAgentTurnError, runAgent, type RunAgentInput } from "./loop";
-import { SessionLedgerWriteError, type SessionLedger } from "./session-ledger";
+import {
+  AdmissionStaleError,
+  SessionLedgerWriteError,
+  type AdmissionBaseToken,
+  type SessionLedger,
+} from "./session-ledger";
 import { TurnCancelledError } from "./turn-cancellation";
+import type { ToolCompletionInput } from "../context/protocol-frame";
+import type { BuiltContextRequest } from "../context/context-revision";
+import type { CommittedToolCompletion } from "./session-ledger";
 import type {
   IterationIdentity,
   RunAgentResult,
@@ -54,12 +99,35 @@ import type {
   TurnIdentity,
 } from "./types";
 import { ContextMeter } from "./context-meter";
+import { CURRENT_RECALL_RETIREMENT_CONTRACT_VERSION } from "../context/recall-retirement-contract";
+import {
+  selectContextAutomation,
+  type ContextAutomationDecision,
+} from "../context/context-automation-policy";
+import type { SkillCatalogSnapshot } from "../skills/skill-loader";
+import {
+  activeSkillManifestEntry,
+  createSkillCatalogSnapshot,
+  skillCatalogManifest,
+} from "../skills/skill-catalog";
+import {
+  buildActiveSystemPrompt,
+  rebindActiveSkills,
+  renderSkillActivationReceipt,
+  SkillActivationCoordinator,
+} from "../skills/skill-context";
 
 export type ExecuteTurnInput = {
-  userPrompt: string;
+  userMessage: UserMessage;
   signal: AbortSignal;
 };
 
+export type AcceptedTurn = {
+  readonly turnId: TurnIdentity["turnId"];
+  readonly userMessage: UserMessage;
+  readonly completion: Promise<RunAgentResult>;
+};
+
 export type SessionDisposeReason =
   | { type: "oneshot_complete" }
   | { type: "tui_exit" }
@@ -71,12 +139,41 @@ export type RuntimeSession = {
   readonly sessionId: SessionId;
   readonly resumed: boolean;
   readonly recovery: SessionRecoveryResult;
+  skills(): RuntimeSkillsSnapshot;
+  mcp(): McpInventorySnapshot;
+  supportsImageInput(): boolean;
+  importImage(
+    sourcePath: string,
+    signal: AbortSignal,
+    prospectiveMessageImageCount: number,
+  ): Promise<ImportedImageAsset>;
+  verifyImageAssets(
+    assets: readonly ImageAssetRef[],
+    signal: AbortSignal,
+  ): Promise<void>;
+  admitTurn(input: ExecuteTurnInput): Promise<AcceptedTurn>;
   executeTurn(input: ExecuteTurnInput): Promise<RunAgentResult>;
   compactContext(): Promise<ContextCompactionResult>;
+  retireContext(): Promise<ContextRetirementResult>;
+  cloneSession(targetSessionId: SessionId): Promise<void>;
   canSwitchSession(): boolean;
   dispose(reason: SessionDisposeReason): Promise<void>;
 };
 
+const EMPTY_MCP_INVENTORY: McpInventorySnapshot = Object.freeze({
+  servers: Object.freeze([]),
+});
+
+export type RuntimeSkillsSnapshot = {
+  readonly skills: readonly {
+    readonly name: string;
+    readonly description: string;
+    readonly scope: "project" | "user";
+    readonly active: boolean;
+  }[];
+  readonly shadowedNames: readonly string[];
+};
+
 export type RuntimeSessionContext = {
   readonly sessionId: SessionId;
   createIteration(turn: TurnIdentity, iterationNumber: number): IterationIdentity;
@@ -86,6 +183,32 @@ export type RuntimeSessionContext = {
   ): ToolCallIdentity;
   finishIterationForContinuation(iteration: IterationIdentity): void;
   append(input: AgentEventInput): Promise<void>;
+  onToolCompletionsCommitted?(input: {
+    completions: readonly ToolCompletionInput[];
+    committed: readonly CommittedToolCompletion[];
+  }): void;
+  prepareModelDispatch?(input: {
+    iteration: IterationIdentity;
+    built: BuiltContextRequest;
+  }): void;
+};
+
+export type ContextSurfaceRefreshSummary = {
+  readonly previousRevisionNumber: number;
+  readonly revisionNumber: number;
+  readonly changed: readonly ContextSurfaceComponent[];
+  readonly toolCountBefore: number;
+  readonly toolCountAfter: number;
+};
+
+export type SkillsUpdateSummary = {
+  readonly previousRevisionNumber: number;
+  readonly revisionNumber: number;
+  readonly activated: readonly string[];
+  readonly refreshed: readonly string[];
+  readonly deactivated: readonly string[];
+  readonly unavailable: readonly string[];
+  readonly addedOverrideCount: number;
 };
 
 type CommonRuntimeSessionInput = {
@@ -97,6 +220,9 @@ type CommonRuntimeSessionInput = {
   contextProfile: ModelContextProfile;
   contextBudget: ModelContextBudget;
   modelClient: ModelClient;
+  systemPrompt: string;
+  projectInstruction?: ProjectInstructionManifest;
+  skillCatalog?: SkillCatalogSnapshot;
   presentationSinks?: EventSink[];
   persistence?:
     | false
@@ -109,8 +235,6 @@ type CommonRuntimeSessionInput = {
 
 type CreateNewRuntimeSessionInput = CommonRuntimeSessionInput & {
   selection: { mode: "new"; sessionId: SessionId };
-  systemPrompt: string;
-  projectInstruction?: ProjectInstructionManifest;
 };
 
 type ResumeRuntimeSessionInput = CommonRuntimeSessionInput & {
@@ -135,7 +259,11 @@ export type RuntimeSessionFactoryDependencies = {
   createEventSink: (input: CreateRuntimeSessionInput) => EventSink;
   selectShadowPlanning: NonNullable<RunAgentInput["shadowPlanning"]>["select"];
   onShadowPlanningResult?: NonNullable<RunAgentInput["shadowPlanning"]>["onResult"];
+  selectContextAutomation: typeof selectContextAutomation;
+  automaticCompactionTrigger: () => ContextCompactionTrigger;
+  automaticRetirementTrigger: () => ContextRetirementTrigger;
   manualCompactionTrigger: () => ContextCompactionTrigger;
+  manualRetirementTrigger: () => ContextRetirementTrigger;
 };
 
 export class RuntimeEventAppendError extends Error {
@@ -150,9 +278,11 @@ export class RuntimeEventAppendError extends Error {
 
 type RuntimeSessionState =
   | "initializing"
+  | "admitting"
   | "ready"
   | "executing"
   | "compacting"
+  | "maintaining_context"
   | "faulted"
   | "disposing"
   | "disposed";
@@ -162,6 +292,12 @@ type ActiveTurn = {
   completion: Promise<RunAgentResult>;
 };
 
+type ActiveAdmission = {
+  controller: AbortController;
+  settled: Promise<void>;
+  settle: () => void;
+};
+
 const defaultDependencies: RuntimeSessionFactoryDependencies = {
   idFactory: runtimeIdFactory,
   createTooling: createDefaultTooling,
@@ -186,7 +322,11 @@ const defaultDependencies: RuntimeSessionFactoryDependencies = {
   createEventSink,
   selectShadowPlanning: ({ preflight }) =>
     preflight.pressure === "normal" ? undefined : { trigger: "runtime_pressure" },
+  selectContextAutomation,
+  automaticCompactionTrigger: () => ({ kind: "runtime_pressure" }),
+  automaticRetirementTrigger: () => ({ kind: "runtime_pressure" }),
   manualCompactionTrigger: () => ({ kind: "manual" }),
+  manualRetirementTrigger: () => ({ kind: "manual" }),
 };
 
 class DefaultRuntimeSession implements RuntimeSession {
@@ -207,14 +347,21 @@ class DefaultRuntimeSession implements RuntimeSession {
   private tooling?: DefaultTooling;
   private mcpManager?: McpManager;
   private ledger?: SessionLedger;
+  private activeAdmission?: ActiveAdmission;
   private activeTurn?: ActiveTurn;
-  private activeCompaction?: Promise<ContextCompactionResult>;
+  private activeContextRevision?: Promise<
+    ContextCompactionResult | ContextRetirementResult
+  >;
   private disposePromise?: Promise<void>;
   private faultCause?: unknown;
   private readonly contextMeter: ContextMeter;
   private readonly committedPrefixAuditor = new CommittedPrefixAuditor();
   private readonly shadowPlanner: SwapPlanner;
   private contextManager?: ContextManager;
+  private contextAutomationDecision?: ContextAutomationDecision;
+  private pendingAutomaticContextMaintenance = false;
+  private readonly skillCatalog: SkillCatalogSnapshot;
+  private skillCoordinator = new SkillActivationCoordinator();
 
   private readonly context: RuntimeSessionContext;
 
@@ -224,9 +371,18 @@ class DefaultRuntimeSession implements RuntimeSession {
     private readonly eventSink: EventSink,
     private readonly observationBuilder: ObservationBuilder,
     private readonly store: SessionStore,
+    private readonly assetStore: ImageAssetStore,
   ) {
     this.sessionId = input.selection.sessionId;
     this.resumed = input.selection.mode === "resume";
+    this.skillCatalog =
+      input.skillCatalog ??
+      createSkillCatalogSnapshot({
+        workspaceRoot: input.workspaceRoot,
+        homeRoot: input.workspaceRoot,
+        skills: [],
+        shadowed: [],
+      });
     this.nextTurnNumber = store.nextTurnNumber();
     this.contextMeter = new ContextMeter(input.contextBudget, {
       onMeasuredAnchor: (anchor) => store.writeMeasuredContextAnchor(anchor),
@@ -241,6 +397,9 @@ class DefaultRuntimeSession implements RuntimeSession {
       finishIterationForContinuation: (iteration) =>
         this.finishIterationForContinuation(iteration),
       append: (event) => this.append(event),
+      onToolCompletionsCommitted: (completion) =>
+        this.onToolCompletionsCommitted(completion),
+      prepareModelDispatch: (dispatch) => this.prepareModelDispatch(dispatch),
     };
   }
 
@@ -250,18 +409,28 @@ class DefaultRuntimeSession implements RuntimeSession {
   ): Promise<RuntimeSession> {
     validateCreateInput(input);
     const store = await dependencies.openStore(input, dependencies.idFactory);
+    let assetStore: ImageAssetStore;
+    try {
+      assetStore = await ImageAssetStore.open({ workspaceRoot: store.workspaceRoot });
+    } catch (error) {
+      if (isNewSessionInput(input)) {
+        await store
+          .deleteFromDisk()
+          .catch(() => store.abandon().catch(() => undefined));
+      } else {
+        await store.abandon().catch(() => undefined);
+      }
+      throw error;
+    }
     let session: DefaultRuntimeSession;
-    let systemPrompt: string;
     try {
-      systemPrompt = isNewSessionInput(input)
-        ? input.systemPrompt
-        : store.readStoredSystemPrompt();
       session = new DefaultRuntimeSession(
         input,
         dependencies,
         dependencies.createEventSink(input),
         dependencies.createObservationBuilder(),
         store,
+        assetStore,
       );
     } catch (error) {
       if (isNewSessionInput(input)) {
@@ -276,6 +445,63 @@ class DefaultRuntimeSession implements RuntimeSession {
     let started = false;
 
     try {
+      const compatibility = createSessionCompatibilityContract({
+        modelName: input.modelName,
+        profileName: input.profileName,
+        includeReasoningContent: input.includeReasoningContent,
+        contextProfile: input.contextProfile,
+        messageProtocol: input.modelClient.messageProtocol,
+        inputModalities: input.modelClient.inputModalities ?? ["text"],
+        ...(input.modelClient.inputTokenEstimator === undefined
+          ? {}
+          : {
+              tokenEstimator: input.modelClient.inputTokenEstimator.compatibility,
+            }),
+      });
+      if (input.selection.mode === "resume") {
+        store.assertSessionCompatibility(compatibility);
+      }
+
+      let resumeSkills:
+        | {
+            unresolved: readonly StoredSkillActivation[];
+            activated: readonly string[];
+            refreshed: readonly string[];
+            deactivated: readonly string[];
+          }
+        | undefined;
+      if (input.selection.mode === "resume") {
+        session.recovery = store.recoverInterruptedState(dependencies.idFactory);
+        const storedSurface = store.loadContextSnapshot().surface;
+        const unresolved = store.loadSkillActivations(["pending", "dispatched"]);
+        const promotionNames = unresolved
+          .filter((activation) => activation.state === "dispatched")
+          .map((activation) => ({
+            name: activation.name,
+            activationMessageId: activation.activationMessageId,
+          }));
+        const rebound = rebindActiveSkills({
+          catalog: session.skillCatalog,
+          active: storedSurface.activeSkills,
+          promotionNames,
+        });
+        session.skillCoordinator = new SkillActivationCoordinator({
+          active: rebound.active,
+        });
+        const activated = promotionNames
+          .filter((entry) => session.skillCatalog.skills.has(entry.name))
+          .map((entry) => entry.name)
+          .sort();
+        resumeSkills = {
+          unresolved,
+          activated: Object.freeze(activated),
+          refreshed: Object.freeze(
+            rebound.refreshed.filter((name) => !activated.includes(name)).sort(),
+          ),
+          deactivated: rebound.deactivated,
+        };
+      }
+
       if (isNewSessionInput(input)) {
         await session.append({
           type: "session.started",
@@ -305,6 +531,12 @@ class DefaultRuntimeSession implements RuntimeSession {
         runtimeSession: session.context,
         historyReader: store.historyReader(),
         webFetchRefiner: input.webFetchRefiner,
+        ...(session.skillCatalog.skills.size === 0
+          ? {}
+          : {
+              skillCatalog: session.skillCatalog,
+              skillCoordinator: session.skillCoordinator,
+            }),
       });
 
       const mcpConfig = await dependencies.loadMcpConfig(input.workspaceRoot);
@@ -319,25 +551,53 @@ class DefaultRuntimeSession implements RuntimeSession {
       }
 
       const definitions = session.requireTooling().registry.definitions();
-      const contractPrepared = input.modelClient.prepare({
-        messages: [{ role: "system", content: systemPrompt }],
+      const activeSystemPrompt = buildActiveSystemPrompt({
+        baseSystemPrompt: input.systemPrompt,
+        activeSkills: session.skillCoordinator.activeEntries(),
+      });
+      const surfacePrepared = input.modelClient.prepare({
+        messages: [{ role: "system", content: activeSystemPrompt }],
         tools: definitions,
       });
-      const runtimeContract = createRuntimeContract({
-        modelName: input.modelName,
-        profileName: input.profileName,
-        includeReasoningContent: input.includeReasoningContent,
-        contextProfile: input.contextProfile,
-        contextBudget: input.contextBudget,
-        systemPrompt,
-        toolSchemaSha256: contractPrepared.toolSchemaHash,
-        requestConfigSha256: contractPrepared.requestConfigHash,
+      const candidateSurface = createContextSurface({
+        surfaceId: dependencies.idFactory.createContextSurfaceId(),
+        sessionId: session.sessionId,
+        systemPrompt: activeSystemPrompt,
+        recallContractVersion: CURRENT_RECALL_RETIREMENT_CONTRACT_VERSION,
+        ...(input.projectInstruction === undefined
+          ? {}
+          : { projectInstruction: input.projectInstruction }),
+        skillCatalog: skillCatalogManifest(session.skillCatalog.skills.values()),
+        activeSkills: session.skillCoordinator.activeManifest(),
+        toolDefinitions: definitions,
+        prepared: surfacePrepared,
+        createdAt: new Date().toISOString(),
       });
       if (input.selection.mode === "new") {
-        store.finalizeRuntimeContract(runtimeContract);
+        store.finalizeInitialization({
+          contract: compatibility,
+          surface: candidateSurface,
+          revisionId: dependencies.idFactory.createContextRevisionId(),
+        });
       } else {
-        store.assertRuntimeContract(runtimeContract);
-        session.recovery = store.recoverInterruptedState(dependencies.idFactory);
+        if (resumeSkills === undefined) {
+          throw new Error("Resume Agent Skills staging state is missing.");
+        }
+        let skillsUpdate: SkillsUpdateSummary | undefined;
+        const refresh =
+          resumeSkills.unresolved.length === 0
+            ? await session.refreshContextSurface(candidateSurface)
+            : undefined;
+        if (resumeSkills.unresolved.length > 0) {
+          skillsUpdate = await session.commitSkillSettlements({
+            reason: "resume",
+            candidateSurface,
+            unresolved: resumeSkills.unresolved,
+            activated: resumeSkills.activated,
+            refreshed: resumeSkills.refreshed,
+            deactivated: resumeSkills.deactivated,
+          });
+        }
         const openCount = store.markResumed();
         if (
           session.recovery.recoveredTurnId !== undefined &&
@@ -353,22 +613,58 @@ class DefaultRuntimeSession implements RuntimeSession {
             },
           });
         }
-        const projectInstruction = store.readProjectInstructionManifest();
         await session.append({
           type: "session.resumed",
           sessionId: session.sessionId,
           data: {
             openCount,
             ...session.recovery,
-            ...(projectInstruction === undefined
+            contextProfile: input.contextProfile,
+            contextBudget: input.contextBudget,
+            ...(input.projectInstruction === undefined
               ? {}
               : {
-                  projectInstructionFile: projectInstruction.path,
+                  projectInstructionFile: input.projectInstruction.path,
                 }),
+            ...(refresh === undefined ? {} : { contextRefresh: refresh }),
           },
         });
+        if (skillsUpdate !== undefined) {
+          await session.append({
+            type: "skills.updated",
+            sessionId: session.sessionId,
+            data: {
+              reason: "resume",
+              activated: skillsUpdate.activated,
+              refreshed: skillsUpdate.refreshed,
+              deactivated: skillsUpdate.deactivated,
+              unavailable: skillsUpdate.unavailable,
+              revisionNumber: skillsUpdate.revisionNumber,
+            },
+          });
+        } else if (
+          resumeSkills.refreshed.length > 0 ||
+          resumeSkills.deactivated.length > 0
+        ) {
+          await session.append({
+            type: "skills.updated",
+            sessionId: session.sessionId,
+            data: {
+              reason: "resume",
+              activated: [],
+              refreshed: resumeSkills.refreshed,
+              deactivated: resumeSkills.deactivated,
+              unavailable: [],
+              ...(refresh === undefined
+                ? {}
+                : { revisionNumber: refresh.revisionNumber }),
+            },
+          });
+        }
       }
 
+      await session.appendSkillsCatalogLoaded();
+
       session.ledger = dependencies.createLedger(store, dependencies.idFactory);
       session.contextManager = new ContextManager({
         store,
@@ -389,6 +685,7 @@ class DefaultRuntimeSession implements RuntimeSession {
         .requireLedger()
         .buildCommittedModelRequest(definitions);
       const initialPrepared = input.modelClient.prepare(initialBuilt.request);
+      assertPreparedMatchesSurface(initialPrepared, initialBuilt.surface);
       session.committedPrefixAuditor.audit(
         initialBuilt.compiled.revisionId,
         initialPrepared,
@@ -409,6 +706,20 @@ class DefaultRuntimeSession implements RuntimeSession {
         data: { phase: "initial", snapshot: initialSnapshot },
       });
 
+      session.contextAutomationDecision = dependencies.selectContextAutomation({
+        ...(input.profileName === undefined ? {} : { profileName: input.profileName }),
+        surface: store.loadContextSnapshot().surface,
+      });
+      if (
+        input.selection.mode === "resume" &&
+        initialSnapshot.pressure !== "normal" &&
+        session.contextAutomationDecision.automaticSwapOnly
+      ) {
+        session.pendingAutomaticContextMaintenance = true;
+        session.state = "executing";
+        await session.performAutomaticContextMaintenance();
+      }
+
       session.state = "ready";
       return session;
     } catch (error) {
@@ -416,58 +727,638 @@ class DefaultRuntimeSession implements RuntimeSession {
     }
   }
 
-  executeTurn(input: ExecuteTurnInput): Promise<RunAgentResult> {
+  private async refreshContextSurface(
+    candidateSurface: StoredContextSurfaceV8,
+  ): Promise<ContextSurfaceRefreshSummary | undefined> {
+    const snapshot = this.store.loadContextSnapshot();
+    if (sameContextSurface(snapshot.surface, candidateSurface)) {
+      return undefined;
+    }
+
+    const changes = contextSurfaceChanges(snapshot.surface, candidateSurface);
+    const changed = changedContextSurfaceComponents(changes);
+    if (changed.length === 0) {
+      throw new Error("Changed context surface has an empty change manifest.");
+    }
+    const startedAt = performance.now();
+    await this.append({
+      type: "context.revision.started",
+      sessionId: this.sessionId,
+      data: {
+        strategy: "surface_refresh",
+        reason: "resume",
+        baseRevisionNumber: snapshot.revision.revisionNumber,
+        changed,
+      },
+    });
+
+    let stage: "prepare" | "commit" | "activate" = "prepare";
+    let committed = false;
+    try {
+      const compiler = new ContextRevisionCompiler();
+      const active = compiler.compileActive(snapshot);
+      const candidateCompiled = compiler.compileProspective({
+        active,
+        canonical: snapshot.canonical,
+        activeOverrides: snapshot.activeOverrides,
+        addedOverrides: [],
+        activeSurface: snapshot.surface,
+        surface: candidateSurface,
+      });
+      const prepared = this.input.modelClient.prepare({
+        messages: candidateCompiled.entries.map((entry) => entry.message),
+        tools: [...candidateSurface.toolDefinitions],
+      });
+      assertPreparedMatchesSurface(prepared, candidateSurface);
+
+      stage = "commit";
+      const revision = this.store.commitSurfaceRefresh({
+        revisionId: this.dependencies.idFactory.createContextRevisionId(),
+        expectedBaseRevisionId: snapshot.revision.revisionId,
+        expectedBaseRevisionNumber: snapshot.revision.revisionNumber,
+        expectedCanonicalThroughOrdinal: snapshot.canonical.messages.length,
+        expectedBaseActiveOverrideManifestSha256:
+          snapshot.revision.activeOverrideManifestSha256,
+        surface: candidateSurface,
+        changes,
+        changeManifestSha256: contextSurfaceChangeManifestHash(changes),
+        canonicalSequenceSha256: canonicalSequenceHash(snapshot.canonical),
+        renderedMessageSha256: renderedMessageHash(candidateCompiled.entries),
+      });
+      committed = true;
+
+      stage = "activate";
+      this.contextMeter.startRevision({
+        reason: "context_rebuilt",
+        requestConfigHash: prepared.requestConfigHash,
+        toolSchemaHash: prepared.toolSchemaHash,
+      });
+      const summary = Object.freeze({
+        previousRevisionNumber: snapshot.revision.revisionNumber,
+        revisionNumber: revision.revisionNumber,
+        changed,
+        toolCountBefore: snapshot.surface.toolDefinitions.length,
+        toolCountAfter: candidateSurface.toolDefinitions.length,
+      });
+      await this.append({
+        type: "context.revision.finished",
+        sessionId: this.sessionId,
+        data: {
+          strategy: "surface_refresh",
+          reason: "resume",
+          baseRevisionNumber: summary.previousRevisionNumber,
+          revisionNumber: summary.revisionNumber,
+          changed: summary.changed,
+          toolCountBefore: summary.toolCountBefore,
+          toolCountAfter: summary.toolCountAfter,
+          measuredAnchorCleared: true,
+          durationMs: elapsedMs(startedAt),
+        },
+      });
+      return summary;
+    } catch (error) {
+      await this.append({
+        type: "context.revision.failed",
+        sessionId: this.sessionId,
+        data: {
+          strategy: "surface_refresh",
+          reason: "resume",
+          stage,
+          errorCode: boundedContextErrorCode(
+            error instanceof SessionError
+              ? error.code
+              : error instanceof Error
+                ? error.name
+                : "CONTEXT_SURFACE_REFRESH_FAILED",
+          ),
+          error: `Context surface refresh failed at ${stage}.`,
+          committed,
+        },
+      }).catch(() => undefined);
+      throw error;
+    }
+  }
+
+  skills(): RuntimeSkillsSnapshot {
+    const activeNames = new Set(
+      this.skillCoordinator.activeEntries().map((entry) => entry.skill.name),
+    );
+    return Object.freeze({
+      skills: Object.freeze(
+        [...this.skillCatalog.skills.values()]
+          .sort((left, right) => compareText(left.name, right.name))
+          .map((skill) =>
+            Object.freeze({
+              name: skill.name,
+              description: skill.description,
+              scope: skill.scope,
+              active: activeNames.has(skill.name),
+            }),
+          ),
+      ),
+      shadowedNames: Object.freeze(
+        this.skillCatalog.shadowed.map((entry) => entry.name),
+      ),
+    });
+  }
+
+  mcp(): McpInventorySnapshot {
+    return this.mcpManager?.inventory ?? EMPTY_MCP_INVENTORY;
+  }
+
+  supportsImageInput(): boolean {
+    return this.input.modelClient.inputModalities?.includes("image") === true;
+  }
+
+  importImage(
+    sourcePath: string,
+    signal: AbortSignal,
+    prospectiveMessageImageCount: number,
+  ): Promise<ImportedImageAsset> {
     if (this.state !== "ready") {
-      throw new Error(`Cannot execute a turn while RuntimeSession is ${this.state}.`);
+      throw new Error(`Cannot import an image while RuntimeSession is ${this.state}.`);
     }
-    if (input.userPrompt.trim() === "") {
-      throw new Error("Cannot execute a turn with an empty prompt.");
+    if (!this.supportsImageInput()) {
+      throw new Error("Current model profile does not support image input.");
     }
-    if (this.activeTurn !== undefined) {
-      throw new Error("Cannot execute concurrent turns in one RuntimeSession.");
+    if (
+      !Number.isSafeInteger(prospectiveMessageImageCount) ||
+      prospectiveMessageImageCount < 1 ||
+      prospectiveMessageImageCount > IMAGE_INPUT_POLICY.maxImagesPerMessage
+    ) {
+      throw new Error("Prospective Prompt image count is invalid.");
+    }
+    const activeImageCount = this.input.modelClient.prepare(
+      this.requireLedger().buildCommittedModelRequest(
+        this.requireTooling().registry.definitions(),
+      ).request,
+    ).mediaOccurrenceCount;
+    const aggregateImageCount = activeImageCount + prospectiveMessageImageCount;
+    if (aggregateImageCount > IMAGE_INPUT_POLICY.maxImagesPerRequest) {
+      throw new ModelRequestMediaAggregateError(
+        `Model request would have ${aggregateImageCount} images; maximum is ${IMAGE_INPUT_POLICY.maxImagesPerRequest}.`,
+      );
+    }
+    return this.assetStore.importWorkspaceFile(sourcePath, { signal });
+  }
+
+  async verifyImageAssets(
+    assets: readonly ImageAssetRef[],
+    signal: AbortSignal,
+  ): Promise<void> {
+    if (!this.supportsImageInput()) {
+      throw new Error("Current model profile does not support image input.");
+    }
+    for (const asset of assets) {
+      signal.throwIfAborted();
+      await this.assetStore.readVerified(asset, { signal });
+    }
+  }
+
+  private requireContextAutomation(): ContextAutomationDecision {
+    if (this.contextAutomationDecision === undefined) {
+      throw new Error("RuntimeSession context automation is not initialized.");
+    }
+    return this.contextAutomationDecision;
+  }
+
+  private appendSkillsCatalogLoaded(): Promise<void> {
+    const activeNames = this.skillCoordinator
+      .activeEntries()
+      .map((entry) => entry.skill.name);
+    if (
+      this.skillCatalog.skills.size === 0 &&
+      activeNames.length === 0 &&
+      this.skillCatalog.shadowed.length === 0
+    ) {
+      return Promise.resolve();
+    }
+    const skills = [...this.skillCatalog.skills.values()];
+    return this.append({
+      type: "skills.catalog.loaded",
+      sessionId: this.sessionId,
+      data: {
+        availableCount: skills.length,
+        projectCount: skills.filter((skill) => skill.scope === "project").length,
+        userCount: skills.filter((skill) => skill.scope === "user").length,
+        activeNames: Object.freeze(activeNames),
+        shadowedNames: Object.freeze(
+          this.skillCatalog.shadowed.map((entry) => entry.name),
+        ),
+      },
+    });
+  }
+
+  private onToolCompletionsCommitted(input: {
+    completions: readonly ToolCompletionInput[];
+    committed: readonly CommittedToolCompletion[];
+  }): void {
+    if (input.completions.length !== input.committed.length) {
+      throw new Error("Committed tool completion identity count does not match.");
     }
+    for (let index = 0; index < input.completions.length; index += 1) {
+      const completion = input.completions[index];
+      const committed = input.committed[index];
+      if (
+        completion === undefined ||
+        committed === undefined ||
+        completion.call.toolCallId !== committed.toolCallId
+      ) {
+        throw new Error("Committed tool completion identity is invalid.");
+      }
+      if (
+        completion.kind === "returned" &&
+        completion.raw.kind === "skill" &&
+        completion.raw.ok &&
+        completion.raw.status === "loaded"
+      ) {
+        this.skillCoordinator.markPending(completion.raw.name);
+      }
+    }
+  }
 
-    let admissionPrepared;
+  private prepareModelDispatch(input: {
+    iteration: IterationIdentity;
+    built: BuiltContextRequest;
+  }): void {
+    const pending = this.store.loadSkillActivations(["pending"]);
+    if (pending.length === 0) {
+      return;
+    }
+    const visibleCanonicalMessageIds = new Set(
+      input.built.compiled.entries
+        .filter(
+          (entry) =>
+            entry.representation === "canonical" && entry.message.role === "tool",
+        )
+        .map((entry) => entry.messageId),
+    );
+    const included = pending.filter((activation) =>
+      visibleCanonicalMessageIds.has(activation.activationMessageId),
+    );
+    if (included.length === 0) {
+      return;
+    }
+    const dispatched = this.store.markSkillActivationsDispatched({
+      iterationId: input.iteration.iterationId,
+      activationMessageIds: included.map(
+        (activation) => activation.activationMessageId,
+      ),
+    });
+    this.skillCoordinator.markDispatched(
+      dispatched.map((activation) => activation.name),
+    );
+  }
+
+  private async commitSkillSettlements(input: {
+    reason: "activation" | "resume";
+    unresolved: readonly StoredSkillActivation[];
+    candidateSurface?: StoredContextSurfaceV8;
+    activated?: readonly string[];
+    refreshed?: readonly string[];
+    deactivated?: readonly string[];
+  }): Promise<SkillsUpdateSummary> {
+    if (input.unresolved.length === 0) {
+      throw new Error("Agent Skills update requires unresolved activations.");
+    }
+    const snapshot = this.store.loadContextSnapshot();
+    const canonicalMessages = new Map(
+      snapshot.canonical.messages.map((message) => [message.messageId, message]),
+    );
+    const activeByName = new Map(
+      this.skillCoordinator
+        .activeEntries()
+        .map((entry) => [entry.skill.name, entry] as const),
+    );
+    const activated = new Set(input.activated ?? []);
+    const unavailable = new Set<string>();
+    const settlements: Array<{
+      activationMessageId: StoredSkillActivation["activationMessageId"];
+      name: string;
+      state: "promoted" | "rejected";
+      rejectionReason?: string;
+    }> = [];
+    const receipts = [];
+    for (const activation of [...input.unresolved].sort((left, right) =>
+      compareText(left.name, right.name),
+    )) {
+      const skill = this.skillCatalog.skills.get(activation.name);
+      const canPromote = activation.state === "dispatched" && skill !== undefined;
+      if (canPromote) {
+        const existing = activeByName.get(activation.name);
+        if (
+          existing !== undefined &&
+          existing.activationMessageId !== activation.activationMessageId
+        ) {
+          throw new Error(
+            `Agent Skill ${activation.name} already has another active activation.`,
+          );
+        }
+        activeByName.set(activation.name, {
+          skill,
+          activationMessageId: activation.activationMessageId,
+        });
+        activated.add(activation.name);
+      }
+      const state = canPromote ? "promoted" : "rejected";
+      const rejectionReason =
+        state === "promoted"
+          ? undefined
+          : activation.state === "pending"
+            ? "not_dispatched"
+            : "unavailable";
+      if (rejectionReason === "unavailable") {
+        unavailable.add(activation.name);
+      }
+      settlements.push({
+        activationMessageId: activation.activationMessageId,
+        name: activation.name,
+        state,
+        ...(rejectionReason === undefined ? {} : { rejectionReason }),
+      });
+      const message = canonicalMessages.get(activation.activationMessageId);
+      if (message?.role !== "tool") {
+        throw new Error(
+          `Agent Skill activation message ${activation.activationMessageId} is missing.`,
+        );
+      }
+      receipts.push(
+        renderSkillActivationReceipt({
+          message: {
+            messageId: message.messageId,
+            frameId: message.frameId,
+            ordinal: message.ordinal,
+            content: message.content,
+            contentSha256: message.contentSha256,
+          },
+          name: activation.name,
+          outcome:
+            state === "promoted"
+              ? "promoted"
+              : rejectionReason === "unavailable"
+                ? "unavailable"
+                : "rejected",
+        }),
+      );
+    }
+    const nextActive = Object.freeze(
+      [...activeByName.values()].sort((left, right) =>
+        compareText(left.skill.name, right.skill.name),
+      ),
+    );
+    const createdAt = new Date().toISOString();
+    const definitions = this.requireTooling().registry.definitions();
+    const renderedSystemPrompt = buildActiveSystemPrompt({
+      baseSystemPrompt: this.input.systemPrompt,
+      activeSkills: nextActive,
+    });
+    const surfacePrepared = this.input.modelClient.prepare({
+      messages: [{ role: "system", content: renderedSystemPrompt }],
+      tools: definitions,
+    });
+    const generatedSurface =
+      input.candidateSurface ??
+      createContextSurface({
+        surfaceId: this.dependencies.idFactory.createContextSurfaceId(),
+        sessionId: this.sessionId,
+        systemPrompt: renderedSystemPrompt,
+        recallContractVersion: CURRENT_RECALL_RETIREMENT_CONTRACT_VERSION,
+        ...(this.input.projectInstruction === undefined
+          ? {}
+          : { projectInstruction: this.input.projectInstruction }),
+        skillCatalog: skillCatalogManifest(this.skillCatalog.skills.values()),
+        activeSkills: nextActive.map((entry) =>
+          activeSkillManifestEntry(entry.skill, entry.activationMessageId),
+        ),
+        toolDefinitions: definitions,
+        prepared: surfacePrepared,
+        createdAt,
+      });
+    assertPreparedMatchesSurface(surfacePrepared, generatedSurface);
+    const surface = sameContextSurface(snapshot.surface, generatedSurface)
+      ? snapshot.surface
+      : generatedSurface;
+    const startedAt = performance.now();
+    await this.append({
+      type: "context.revision.started",
+      sessionId: this.sessionId,
+      data: {
+        strategy: "skills_update",
+        reason: input.reason,
+        baseRevisionNumber: snapshot.revision.revisionNumber,
+        names: Object.freeze(
+          input.unresolved.map((entry) => entry.name).sort(compareText),
+        ),
+      },
+    });
+    let stage: "prepare" | "commit" | "activate" = "prepare";
+    let committed = false;
     try {
-      admissionPrepared = this.input.modelClient.prepare(
-        this.requireLedger().buildCandidateModelRequest(
-          input.userPrompt,
-          this.requireTooling().registry.definitions(),
-        ).request,
+      const revision = commitAgentSkillsContextUpdate({
+        store: this.store,
+        contextMeter: this.contextMeter,
+        idFactory: this.dependencies.idFactory,
+        snapshot,
+        surface,
+        addedOverrides: receipts,
+        settlements,
+      });
+      committed = true;
+      stage = "activate";
+      this.skillCoordinator.replaceActive(nextActive);
+      this.skillCoordinator.settle(
+        input.unresolved.map((activation) => activation.name),
       );
+      const summary = Object.freeze({
+        previousRevisionNumber: snapshot.revision.revisionNumber,
+        revisionNumber: revision.revisionNumber,
+        activated: Object.freeze([...activated].sort()),
+        refreshed: Object.freeze([...(input.refreshed ?? [])].sort()),
+        deactivated: Object.freeze([...(input.deactivated ?? [])].sort()),
+        unavailable: Object.freeze([...unavailable].sort()),
+        addedOverrideCount: receipts.length,
+      });
+      await this.append({
+        type: "context.revision.finished",
+        sessionId: this.sessionId,
+        data: {
+          strategy: "skills_update",
+          reason: input.reason,
+          baseRevisionNumber: summary.previousRevisionNumber,
+          revisionNumber: summary.revisionNumber,
+          activated: summary.activated,
+          refreshed: summary.refreshed,
+          deactivated: summary.deactivated,
+          unavailable: summary.unavailable,
+          addedOverrideCount: summary.addedOverrideCount,
+          measuredAnchorCleared: true,
+          durationMs: elapsedMs(startedAt),
+        },
+      });
+      return summary;
     } catch (error) {
-      if (isCanonicalRuntimeFault(error)) {
-        this.fault(error);
+      if (error instanceof ContextManagerError) {
+        committed = error.committed;
+        stage =
+          error.stage === "commit"
+            ? "commit"
+            : error.stage === "activate"
+              ? "activate"
+              : "prepare";
       }
+      await this.append({
+        type: "context.revision.failed",
+        sessionId: this.sessionId,
+        data: {
+          strategy: "skills_update",
+          reason: input.reason,
+          stage,
+          errorCode: boundedContextErrorCode(
+            error instanceof ContextManagerError
+              ? error.code
+              : error instanceof SessionError
+                ? error.code
+                : error instanceof Error
+                  ? error.name
+                  : "SKILLS_UPDATE_VALIDATION_FAILED",
+          ),
+          error: `Agent Skills update failed at ${stage}.`,
+          committed,
+        },
+      }).catch(() => undefined);
       throw error;
     }
-    const admissionSnapshot = this.contextMeter.measure(admissionPrepared);
-    this.contextMeter.assertWithinBudget(admissionSnapshot);
+  }
+
+  async executeTurn(input: ExecuteTurnInput): Promise<RunAgentResult> {
+    return (await this.admitTurn(input)).completion;
+  }
+
+  async admitTurn(input: ExecuteTurnInput): Promise<AcceptedTurn> {
+    if (this.state !== "ready") {
+      throw new Error(`Cannot execute a turn while RuntimeSession is ${this.state}.`);
+    }
+    validateUserMessage(input.userMessage);
+    if (this.activeTurn !== undefined) {
+      throw new Error("Cannot execute concurrent turns in one RuntimeSession.");
+    }
 
+    this.state = "admitting";
     const controller = new AbortController();
     const removeExternalAbortListener = forwardExternalAbort(input.signal, controller);
-    const turn = this.stageTurn(input.userPrompt);
-    let pendingLedgerTurn;
+    const admission = createActiveAdmission(controller);
+    this.activeAdmission = admission;
+    let pendingLedgerTurn: ReturnType<SessionLedger["beginTurn"]>;
+    let admissionPrepared: MaterializedModelRequest;
+    let admissionSnapshot;
     try {
+      controller.signal.throwIfAborted();
+      const built = this.requireLedger().buildCandidateModelRequest(
+        input.userMessage,
+        this.requireTooling().registry.definitions(),
+      );
+      const admissionBase = this.createAdmissionBaseToken(built);
+      const prepared = this.input.modelClient.prepare(built.request);
+      const localSnapshot = this.contextMeter.measure(prepared);
+      this.contextMeter.assertWithinBudget(localSnapshot);
+      admissionPrepared = await materializeModelRequest(
+        this.input.modelClient,
+        prepared,
+        { assetStore: this.assetStore, signal: controller.signal },
+      );
+      admissionSnapshot = this.contextMeter.measure(admissionPrepared);
+      if (
+        prepared.mediaOccurrenceCount > 0 &&
+        admissionSnapshot.source !== "measured_plus_estimated_delta"
+      ) {
+        const estimator = this.input.modelClient.inputTokenEstimator;
+        if (estimator === undefined) {
+          throw new Error("Image model request has no input token estimator.");
+        }
+        const estimate = await this.contextMeter.estimateProviderInput(
+          admissionPrepared,
+          estimator,
+          { signal: controller.signal },
+        );
+        admissionSnapshot = this.contextMeter.applyProviderEstimate(
+          admissionPrepared,
+          estimate,
+        );
+      }
+      this.contextMeter.assertWithinBudget(admissionSnapshot);
+      controller.signal.throwIfAborted();
+      const turn = this.stageTurn(input.userMessage);
       pendingLedgerTurn = this.requireLedger().beginTurn({
         turn,
-        userPrompt: input.userPrompt,
+        userMessage: input.userMessage,
+        admissionBase,
+      });
+
+      this.settleAdmission(admission);
+      this.state = "executing";
+      const completion = this.startAcceptedTurn({
+        userMessage: input.userMessage,
+        turn,
+        pendingLedgerTurn,
+        controller,
+        removeExternalAbortListener,
+        initialRequest: {
+          prepared: admissionPrepared,
+          usage: admissionSnapshot,
+        },
+      });
+      this.activeTurn = { controller, completion };
+      return Object.freeze({
+        turnId: turn.turnId,
+        userMessage: input.userMessage,
+        completion,
       });
-      this.registerTurn(turn);
     } catch (error) {
-      this.fault(error);
+      this.settleAdmission(admission);
+      removeExternalAbortListener();
+      if (error instanceof AdmissionStaleError) {
+        this.nextTurnNumber = this.store.nextTurnNumber();
+      }
+      if (this.state === "admitting") {
+        this.state = "ready";
+      }
+      if (isCanonicalRuntimeFault(error)) {
+        this.fault(error);
+      }
       throw error;
     }
-    this.state = "executing";
-    const completion = this.performExecuteTurn(
-      input.userPrompt,
-      turn,
-      pendingLedgerTurn,
-      controller.signal,
-      removeExternalAbortListener,
-    );
-    this.activeTurn = { controller, completion };
-    return completion;
+  }
+
+  private settleAdmission(admission: ActiveAdmission): void {
+    if (this.activeAdmission !== admission) {
+      throw new Error("Runtime admission ownership was lost.");
+    }
+    this.activeAdmission = undefined;
+    admission.settle();
+  }
+
+  private createAdmissionBaseToken(built: BuiltContextRequest): AdmissionBaseToken {
+    const meta = this.store.readMeta();
+    const head = built.canonical.messages.at(-1);
+    if (
+      head === undefined ||
+      meta.sessionCompatibilitySha256 === null ||
+      built.revision.revisionId !== meta.activeRevisionId ||
+      built.surface.surfaceSha256 !== built.revision.surfaceSha256 ||
+      meta.nextTurnNumber !== this.nextTurnNumber
+    ) {
+      throw new Error("Cannot capture a consistent turn admission base.");
+    }
+    return Object.freeze({
+      canonicalMessageCount: built.canonical.messages.length,
+      canonicalHeadMessageId: head.messageId,
+      canonicalHeadContentSha256: head.contentSha256,
+      activeRevisionId: built.revision.revisionId,
+      activeRevisionNumber: built.revision.revisionNumber,
+      surfaceSha256: built.surface.surfaceSha256,
+      sessionCompatibilitySha256: meta.sessionCompatibilitySha256,
+      nextTurnNumber: meta.nextTurnNumber,
+    });
   }
 
   compactContext(): Promise<ContextCompactionResult> {
@@ -478,16 +1369,16 @@ class DefaultRuntimeSession implements RuntimeSession {
       throw new Error("Cannot compact context while a turn is active.");
     }
     const completion = this.performCompactContext();
-    this.activeCompaction = completion;
+    this.activeContextRevision = completion;
     void completion.then(
       () => {
-        if (this.activeCompaction === completion) {
-          this.activeCompaction = undefined;
+        if (this.activeContextRevision === completion) {
+          this.activeContextRevision = undefined;
         }
       },
       () => {
-        if (this.activeCompaction === completion) {
-          this.activeCompaction = undefined;
+        if (this.activeContextRevision === completion) {
+          this.activeContextRevision = undefined;
         }
       },
     );
@@ -562,6 +1453,104 @@ class DefaultRuntimeSession implements RuntimeSession {
     }
   }
 
+  retireContext(): Promise<ContextRetirementResult> {
+    if (this.state !== "ready") {
+      throw new Error(
+        `Cannot retire context prefix while RuntimeSession is ${this.state}.`,
+      );
+    }
+    if (this.activeTurn !== undefined) {
+      throw new Error("Cannot retire context prefix while a turn is active.");
+    }
+    const completion = this.performRetireContext();
+    this.activeContextRevision = completion;
+    void completion.then(
+      () => {
+        if (this.activeContextRevision === completion) {
+          this.activeContextRevision = undefined;
+        }
+      },
+      () => {
+        if (this.activeContextRevision === completion) {
+          this.activeContextRevision = undefined;
+        }
+      },
+    );
+    return completion;
+  }
+
+  private async performRetireContext(): Promise<ContextRetirementResult> {
+    if (this.state !== "ready") {
+      throw new Error(
+        `Cannot retire context prefix while RuntimeSession is ${this.state}.`,
+      );
+    }
+    if (this.activeTurn !== undefined) {
+      throw new Error("Cannot retire context prefix while a turn is active.");
+    }
+    this.store.assertContextRevisionIdle();
+    const baseRevisionNumber = this.store.loadContextSnapshot().revision.revisionNumber;
+    this.state = "compacting";
+    let started = false;
+    try {
+      await this.append({
+        type: "context.revision.started",
+        sessionId: this.sessionId,
+        data: {
+          strategy: "retire_prefix",
+          reason: "manual",
+          policyVersion: "recall-first-retirement-v1",
+          baseRevisionNumber,
+        },
+      });
+      started = true;
+      const result = await this.requireContextManager().retirePrefix(
+        this.dependencies.manualRetirementTrigger(),
+      );
+      await this.append({
+        type: "context.revision.finished",
+        sessionId: this.sessionId,
+        data: contextRetirementFinishedData(result),
+      });
+      if (this.state === "compacting") {
+        this.state = "ready";
+      }
+      return result;
+    } catch (error) {
+      if (started && !(error instanceof RuntimeEventAppendError)) {
+        const failure =
+          error instanceof ContextManagerError
+            ? error
+            : new ContextManagerError(
+                "activate",
+                error instanceof Error ? error.name : "CONTEXT_RETIREMENT_FAILED",
+                true,
+                false,
+                "Context prefix retirement failed.",
+                { cause: error },
+              );
+        await this.append({
+          type: "context.revision.failed",
+          sessionId: this.sessionId,
+          data: {
+            strategy: "retire_prefix",
+            reason: "manual",
+            stage: failure.stage,
+            errorCode: boundedContextErrorCode(failure.code),
+            error: `Context prefix retirement failed at ${failure.stage}.`,
+            committed: failure.committed,
+          },
+        }).catch(() => undefined);
+      }
+      if (!(error instanceof ContextManagerError) || error.fatal) {
+        this.fault(error);
+      } else if (this.state === "compacting") {
+        this.state = "ready";
+      }
+      throw error;
+    }
+  }
+
   dispose(reason: SessionDisposeReason): Promise<void> {
     this.disposePromise ??= this.performDispose(reason);
     return this.disposePromise;
@@ -578,12 +1567,65 @@ class DefaultRuntimeSession implements RuntimeSession {
     );
   }
 
+  async cloneSession(targetSessionId: SessionId): Promise<void> {
+    if (!this.canSwitchSession()) {
+      throw new Error(
+        "Cannot clone the session while a turn, context operation, or background task is active.",
+      );
+    }
+    await this.waitForStableEventTail();
+    if (!this.canSwitchSession()) {
+      throw new Error(
+        "Cannot clone the session while a turn, context operation, or background task is active.",
+      );
+    }
+    await this.store.cloneTo({ targetSessionId });
+  }
+
+  private async waitForStableEventTail(): Promise<void> {
+    for (;;) {
+      const tail = this.eventTail;
+      await tail;
+      if (this.eventTail === tail) {
+        return;
+      }
+    }
+  }
+
+  private async startAcceptedTurn(input: {
+    userMessage: UserMessage;
+    turn: TurnIdentity;
+    pendingLedgerTurn: ReturnType<SessionLedger["beginTurn"]>;
+    controller: AbortController;
+    removeExternalAbortListener: () => void;
+    initialRequest: NonNullable<RunAgentInput["initialRequest"]>;
+  }): Promise<RunAgentResult> {
+    try {
+      this.registerTurn(input.turn);
+    } catch (error) {
+      input.removeExternalAbortListener();
+      input.pendingLedgerTurn.fault(error);
+      this.activeTurn = undefined;
+      this.fault(error);
+      throw error;
+    }
+    return this.performExecuteTurn(
+      input.userMessage,
+      input.turn,
+      input.pendingLedgerTurn,
+      input.controller.signal,
+      input.removeExternalAbortListener,
+      input.initialRequest,
+    );
+  }
+
   private async performExecuteTurn(
-    userPrompt: string,
+    userMessage: UserMessage,
     turn: TurnIdentity,
     pendingLedgerTurn: ReturnType<SessionLedger["beginTurn"]>,
     signal: AbortSignal,
     removeExternalAbortListener: () => void,
+    initialRequest: NonNullable<RunAgentInput["initialRequest"]>,
   ): Promise<RunAgentResult> {
     let settled = false;
 
@@ -591,7 +1633,7 @@ class DefaultRuntimeSession implements RuntimeSession {
       await this.append({
         type: "turn.started",
         ...turn,
-        data: { userPrompt },
+        data: { userPrompt: projectUserMessage(userMessage) },
       });
 
       let result: RunAgentResult;
@@ -604,7 +1646,16 @@ class DefaultRuntimeSession implements RuntimeSession {
           committedPrefixAuditor: this.committedPrefixAuditor,
           shadowPlanning: {
             planner: this.shadowPlanner,
-            select: this.dependencies.selectShadowPlanning,
+            select: (planningInput) => {
+              const selection = this.dependencies.selectShadowPlanning(planningInput);
+              if (
+                selection?.trigger === "runtime_pressure" &&
+                this.requireContextAutomation().automaticSwapOnly
+              ) {
+                this.pendingAutomaticContextMaintenance = true;
+              }
+              return selection;
+            },
             ...(this.dependencies.onShadowPlanningResult === undefined
               ? {}
               : { onResult: this.dependencies.onShadowPlanningResult }),
@@ -615,6 +1666,8 @@ class DefaultRuntimeSession implements RuntimeSession {
           runtimeSession: this.context,
           turn,
           signal,
+          assetStore: this.assetStore,
+          initialRequest,
         });
       } catch (error) {
         if (error instanceof RuntimeEventAppendError) {
@@ -629,6 +1682,7 @@ class DefaultRuntimeSession implements RuntimeSession {
           );
           pendingLedgerTurn.finish(error.result);
           settled = true;
+          await this.settleClosedTurnSkills();
           throw error;
         }
 
@@ -644,6 +1698,10 @@ class DefaultRuntimeSession implements RuntimeSession {
       await this.appendTerminalEvent(turn, result, projectedMessageCount);
       pendingLedgerTurn.finish(result);
       settled = true;
+      await this.settleClosedTurnSkills();
+      if (result.status === "completed") {
+        await this.performAutomaticContextMaintenance();
+      }
       return result;
     } catch (error) {
       if (!settled) {
@@ -654,12 +1712,166 @@ class DefaultRuntimeSession implements RuntimeSession {
     } finally {
       removeExternalAbortListener();
       this.activeTurn = undefined;
+      this.pendingAutomaticContextMaintenance = false;
       if (this.state === "executing") {
         this.state = "ready";
       }
     }
   }
 
+  private async performAutomaticContextMaintenance(): Promise<void> {
+    if (!this.pendingAutomaticContextMaintenance) return;
+    this.pendingAutomaticContextMaintenance = false;
+    const automation = this.requireContextAutomation();
+    if (!automation.automaticSwapOnly) return;
+    if (this.state !== "executing") {
+      throw new Error(
+        `Cannot run automatic context maintenance while RuntimeSession is ${this.state}.`,
+      );
+    }
+    this.store.assertContextRevisionIdle();
+    const qualificationId = requireAutomationQualificationId(automation);
+    this.state = "maintaining_context";
+    try {
+      const swap = await this.performAutomaticCompaction(qualificationId);
+      if (swap === undefined) return;
+      if (automation.automaticPrefixRetirement && automaticSwapNeedsRetirement(swap)) {
+        await this.performAutomaticRetirement(qualificationId);
+      }
+    } finally {
+      if (this.state === "maintaining_context") {
+        this.state = "executing";
+      }
+    }
+  }
+
+  private async performAutomaticCompaction(
+    qualificationId: string,
+  ): Promise<ContextCompactionResult | undefined> {
+    let started = false;
+    try {
+      await this.append({
+        type: "context.revision.started",
+        sessionId: this.sessionId,
+        data: {
+          strategy: "swap",
+          reason: "runtime_pressure",
+          policyVersion: "swap-only-v1",
+          rendererFormat: "swap-observation-v1",
+          qualificationId,
+        },
+      });
+      started = true;
+      const result = await this.requireContextManager().compact(
+        this.dependencies.automaticCompactionTrigger(),
+      );
+      await this.append({
+        type: "context.revision.finished",
+        sessionId: this.sessionId,
+        data: contextRevisionFinishedData(result, "runtime_pressure", qualificationId),
+      });
+      return result;
+    } catch (error) {
+      if (started && !(error instanceof RuntimeEventAppendError)) {
+        const failure = automaticContextFailure(error, "compaction");
+        await this.append({
+          type: "context.revision.failed",
+          sessionId: this.sessionId,
+          data: {
+            strategy: "swap",
+            reason: "runtime_pressure",
+            stage: failure.stage,
+            errorCode: boundedContextErrorCode(failure.code),
+            error: `Automatic context compaction failed at ${failure.stage}.`,
+            qualificationId,
+          },
+        }).catch(() => undefined);
+      }
+      if (error instanceof ContextManagerError && !error.fatal) {
+        return undefined;
+      }
+      throw error;
+    }
+  }
+
+  private async performAutomaticRetirement(
+    qualificationId: string,
+  ): Promise<ContextRetirementResult | undefined> {
+    const baseRevisionNumber = this.store.loadContextSnapshot().revision.revisionNumber;
+    let started = false;
+    try {
+      await this.append({
+        type: "context.revision.started",
+        sessionId: this.sessionId,
+        data: {
+          strategy: "retire_prefix",
+          reason: "runtime_pressure",
+          policyVersion: "recall-first-retirement-v1",
+          baseRevisionNumber,
+          qualificationId,
+        },
+      });
+      started = true;
+      const result = await this.requireContextManager().retirePrefix(
+        this.dependencies.automaticRetirementTrigger(),
+      );
+      await this.append({
+        type: "context.revision.finished",
+        sessionId: this.sessionId,
+        data: contextRetirementFinishedData(
+          result,
+          "runtime_pressure",
+          qualificationId,
+        ),
+      });
+      return result;
+    } catch (error) {
+      if (started && !(error instanceof RuntimeEventAppendError)) {
+        const failure = automaticContextFailure(error, "retirement");
+        await this.append({
+          type: "context.revision.failed",
+          sessionId: this.sessionId,
+          data: {
+            strategy: "retire_prefix",
+            reason: "runtime_pressure",
+            stage: failure.stage,
+            errorCode: boundedContextErrorCode(failure.code),
+            error: `Automatic context retirement failed at ${failure.stage}.`,
+            committed: failure.committed,
+            qualificationId,
+          },
+        }).catch(() => undefined);
+      }
+      if (error instanceof ContextManagerError && !error.fatal) {
+        return undefined;
+      }
+      throw error;
+    }
+  }
+
+  private async settleClosedTurnSkills(): Promise<void> {
+    const unresolved = this.store.loadSkillActivations(["pending", "dispatched"]);
+    if (unresolved.length === 0) {
+      return;
+    }
+    const summary = await this.commitSkillSettlements({
+      reason: "activation",
+      unresolved,
+    });
+    await this.append({
+      type: "skills.updated",
+      sessionId: this.sessionId,
+      data: {
+        reason: "activation",
+        activated: summary.activated,
+        refreshed: summary.refreshed,
+        deactivated: summary.deactivated,
+        unavailable: summary.unavailable,
+        revisionNumber: summary.revisionNumber,
+      },
+    });
+  }
+
   private async appendTerminalEvent(
     turn: TurnIdentity,
     result: RunAgentResult,
@@ -702,10 +1914,15 @@ class DefaultRuntimeSession implements RuntimeSession {
 
     this.state = "disposing";
     const errors: unknown[] = this.faultCause === undefined ? [] : [this.faultCause];
-    const activeCompaction = this.activeCompaction;
-    if (activeCompaction !== undefined) {
+    const activeAdmission = this.activeAdmission;
+    if (activeAdmission !== undefined) {
+      activeAdmission.controller.abort(new TurnCancelledError("session_dispose"));
+      await activeAdmission.settled;
+    }
+    const activeContextRevision = this.activeContextRevision;
+    if (activeContextRevision !== undefined) {
       try {
-        await activeCompaction;
+        await activeContextRevision;
       } catch {
         // The compactContext caller owns its primary error. Disposal still continues.
       }
@@ -794,10 +2011,8 @@ class DefaultRuntimeSession implements RuntimeSession {
     throw new Error("Initialization error collection unexpectedly returned.");
   }
 
-  private stageTurn(userPrompt: string): TurnIdentity {
-    if (userPrompt.trim() === "") {
-      throw new Error("Cannot create an AgentTurn for an empty prompt.");
-    }
+  private stageTurn(userMessage: UserMessage): TurnIdentity {
+    validateUserMessage(userMessage);
 
     const identity: TurnIdentity = {
       sessionId: this.sessionId,
@@ -1074,18 +2289,26 @@ function validateCreateInput(input: CreateRuntimeSessionInput): void {
   if (!path.isAbsolute(input.workspaceRoot)) {
     throw new Error("RuntimeSession workspaceRoot must be an absolute path.");
   }
+  if (
+    input.skillCatalog !== undefined &&
+    input.skillCatalog.workspaceRoot !== input.workspaceRoot
+  ) {
+    throw new Error("RuntimeSession Agent Skill catalog belongs to another workspace.");
+  }
   if (input.modelName.trim() === "") {
     throw new Error("RuntimeSession modelName must not be empty.");
   }
   requirePositiveNumber(input.maxIterations, "maxIterations");
-  if (isNewSessionInput(input) && input.systemPrompt.trim() === "") {
+  if (input.systemPrompt.trim() === "") {
     throw new Error("RuntimeSession systemPrompt must not be empty.");
   }
   if (
     typeof input.modelClient !== "object" ||
     input.modelClient === null ||
     typeof input.modelClient.prepare !== "function" ||
-    typeof input.modelClient.request !== "function"
+    typeof input.modelClient.request !== "function" ||
+    typeof input.modelClient.messageProtocol !== "object" ||
+    input.modelClient.messageProtocol === null
   ) {
     throw new Error(
       "RuntimeSession modelClient must implement prepare() and request().",
@@ -1094,12 +2317,47 @@ function validateCreateInput(input: CreateRuntimeSessionInput): void {
   assertMatchingContextBudget(input.contextProfile, input.contextBudget);
 }
 
+function assertPreparedMatchesSurface(
+  prepared: ReturnType<ModelClient["prepare"]>,
+  surface: StoredContextSurfaceV8,
+): void {
+  if (
+    prepared.requestConfigHash !== surface.requestConfigSha256 ||
+    prepared.toolSchemaHash !== surface.toolSchemaSha256 ||
+    prepared.requestMaxOutputTokens !== surface.requestMaxOutputTokens
+  ) {
+    throw new Error("Prepared model request does not match its context surface.");
+  }
+}
+
+function elapsedMs(startedAt: number): number {
+  return Math.round((performance.now() - startedAt) * 100) / 100;
+}
+
 function isNewSessionInput(
   input: CreateRuntimeSessionInput,
 ): input is CreateNewRuntimeSessionInput {
   return input.selection.mode === "new";
 }
 
+function createActiveAdmission(controller: AbortController): ActiveAdmission {
+  let resolve!: () => void;
+  const settled = new Promise<void>((settle) => {
+    resolve = settle;
+  });
+  let didSettle = false;
+  return {
+    controller,
+    settled,
+    settle: () => {
+      if (!didSettle) {
+        didSettle = true;
+        resolve();
+      }
+    },
+  };
+}
+
 function forwardExternalAbort(
   externalSignal: AbortSignal,
   internalController: AbortController,
@@ -1150,33 +2408,36 @@ function errorMessage(error: unknown): string {
 
 function contextRevisionFinishedData(
   result: ContextCompactionResult,
+  reason: "manual" | "runtime_pressure" = "manual",
+  qualificationId?: string,
 ): ContextRevisionFinishedData {
   if (result.status === "unchanged") {
     return {
       strategy: "swap",
-      reason: "manual",
+      reason,
       policyVersion: "swap-only-v1",
       outcome: result.outcome,
       baseRevisionNumber: result.revisionNumber,
       addedOverrideCount: 0,
-      totalOverrideCount: result.totalOverrideCount,
+      activeOverrideCount: result.activeOverrideCount,
       originalObservationBytes: 0,
       projectedObservationBytes: 0,
       rawTokensBefore: result.rawTokensBefore,
       guardedTokensBefore: result.guardedTokensBefore,
       targetTokens: result.targetTokens,
       durationMs: result.durationMs,
+      ...(qualificationId === undefined ? {} : { qualificationId }),
     };
   }
   return {
     strategy: "swap",
-    reason: "manual",
+    reason,
     policyVersion: "swap-only-v1",
     outcome: result.outcome,
     baseRevisionNumber: result.previousRevisionNumber,
     revisionNumber: result.revisionNumber,
     addedOverrideCount: result.addedOverrideCount,
-    totalOverrideCount: result.totalOverrideCount,
+    activeOverrideCount: result.activeOverrideCount,
     originalObservationBytes: result.originalObservationBytes,
     projectedObservationBytes: result.projectedObservationBytes,
     rawTokensBefore: result.rawTokensBefore,
@@ -1186,9 +2447,99 @@ function contextRevisionFinishedData(
     targetTokens: result.targetTokens,
     planHash: result.planHash,
     durationMs: result.durationMs,
+    ...(qualificationId === undefined ? {} : { qualificationId }),
   };
 }
 
+function contextRetirementFinishedData(
+  result: ContextRetirementResult,
+  reason: "manual" | "runtime_pressure" = "manual",
+  qualificationId?: string,
+): ContextRevisionFinishedData {
+  if (result.status === "unchanged") {
+    return {
+      strategy: "retire_prefix",
+      reason,
+      policyVersion: "recall-first-retirement-v1",
+      outcome: result.outcome,
+      baseRevisionNumber: result.revisionNumber,
+      previousKeepFromOrdinal: result.keepFromOrdinal,
+      keepFromOrdinal: result.keepFromOrdinal,
+      retiredTurnCount: 0,
+      retiredFrameCount: 0,
+      retiredMessageCount: 0,
+      activeOverrideCount: result.activeOverrideCount,
+      guardedTokensBefore: result.guardedTokensBefore,
+      targetTokens: result.targetTokens,
+      planningDurationMs: result.planningDurationMs,
+      durationMs: result.durationMs,
+      ...(qualificationId === undefined ? {} : { qualificationId }),
+    };
+  }
+  return {
+    strategy: "retire_prefix",
+    reason,
+    policyVersion: "recall-first-retirement-v1",
+    outcome: result.outcome,
+    baseRevisionNumber: result.previousRevisionNumber,
+    revisionNumber: result.revisionNumber,
+    previousKeepFromOrdinal: result.previousKeepFromOrdinal,
+    keepFromOrdinal: result.keepFromOrdinal,
+    retiredTurnCount: result.retiredTurnCount,
+    retiredFrameCount: result.retiredFrameCount,
+    retiredMessageCount: result.retiredMessageCount,
+    activeOverrideCount: result.activeOverrideCount,
+    rawTokensBefore: result.rawTokensBefore,
+    rawTokensAfter: result.rawTokensAfter,
+    guardedTokensBefore: result.guardedTokensBefore,
+    guardedTokensAfter: result.guardedTokensAfter,
+    targetTokens: result.targetTokens,
+    planHash: result.planHash,
+    planningDurationMs: result.planningDurationMs,
+    validationDurationMs: result.validationDurationMs,
+    transactionDurationMs: result.transactionDurationMs,
+    activationDurationMs: result.activationDurationMs,
+    durationMs: result.durationMs,
+    ...(qualificationId === undefined ? {} : { qualificationId }),
+  };
+}
+
+function requireAutomationQualificationId(decision: ContextAutomationDecision): string {
+  if (
+    !decision.automaticSwapOnly ||
+    (decision.reason !== "qualified" && decision.reason !== "swap_only_qualified") ||
+    decision.qualificationId === undefined
+  ) {
+    throw new Error("Automatic context maintenance has no qualification identity.");
+  }
+  return decision.qualificationId;
+}
+
+function automaticSwapNeedsRetirement(result: ContextCompactionResult): boolean {
+  return (
+    result.outcome === "no_eligible_candidates" ||
+    result.outcome === "insufficient_candidates"
+  );
+}
+
+function automaticContextFailure(
+  error: unknown,
+  strategy: "compaction" | "retirement",
+): ContextManagerError {
+  return error instanceof ContextManagerError
+    ? error
+    : new ContextManagerError(
+        "activate",
+        error instanceof Error
+          ? error.name
+          : `AUTOMATIC_CONTEXT_${strategy.toUpperCase()}_FAILED`,
+        true,
+        false,
+        `Automatic context ${strategy} failed.`,
+        { cause: error },
+      );
+}
+
 function boundedContextErrorCode(code: string): string {
   return /^[A-Za-z0-9_]+$/.test(code) && code.length <= 80
     ? code
@@ -1201,6 +2552,10 @@ function requirePositiveNumber(value: number, name: string): void {
   }
 }
 
+function compareText(left: string, right: string): number {
+  return left < right ? -1 : left > right ? 1 : 0;
+}
+
 function isCanonicalRuntimeFault(error: unknown): boolean {
   return (
     error instanceof ContextProtocolError ||