@modelprofile.com/flexharness 9.4.0 → 9.6.0

package/ts/classes.flexharness.ts

@@ -4,6 +4,7 @@ import {
   FlexHarnessCallbackOverflowError,
   FlexHarnessClosedError,
   FlexHarnessExternalError,
+  FlexHarnessImportedSessionError,
   FlexHarnessNotFoundError,
   FlexHarnessPermissionRejectedError,
   FlexHarnessPermissionStateError,
@@ -25,6 +26,7 @@ import {
   FLEX_REVERSION_REFERENCE_MAX_BYTES,
   FLEX_REVERSION_WORKSPACE_ID_MAX_BYTES,
   FLEX_REVERSION_WORKSPACE_LABEL_MAX_BYTES,
+  FLEX_SESSION_IMPORT_MAX_DEPTH,
 } from './interfaces.js';
 import type {
   IFlexAgentContextCompactionOptions,
@@ -32,6 +34,7 @@ import type {
   IFlexAgentSessionPolicy,
   IFlexAffectedWorkspace,
   IFlexBackgroundExecution,
+  IFlexBeginSessionImportOptions,
   IFlexCallbackLimits,
   IFlexCompactSessionOptions,
   IFlexCreateProjectTaskInput,
@@ -45,6 +48,7 @@ import type {
   IFlexExecutionContextHandle,
   IFlexHarnessOptions,
   IFlexHarnessStores,
+  IFlexImportedRun,
   IFlexMessage,
   IFlexMessagePage,
   IFlexMessagePageOptions,
@@ -85,6 +89,10 @@ import type {
   IFlexSessionActivity,
   IFlexSessionGeneration,
   IFlexSessionGenerationCohortEntry,
+  IFlexSessionImportHandle,
+  IFlexSessionImportLimits,
+  IFlexSessionImportProgress,
+  IFlexSessionOrigin,
   IFlexSessionReversionGroup,
   IFlexSessionReversionInfo,
   IFlexSessionTombstone,
@@ -106,6 +114,7 @@ import type {
   TFlexAgentToolCallUpdateEvent,
   TFlexAgentToolCallFinishEvent,
   TFlexAgentToolSet,
+  TFlexBeginSessionImportResult,
   TFlexExternalErrorProjector,
   TFlexExternalErrorSource,
   TFlexHarnessEvent,
@@ -184,6 +193,14 @@ import {
   truncateUtf8,
   type IRunResultProjection,
 } from './utils.transfer.js';
+import {
+  normalizeBeginSessionImportOptions,
+  normalizeImportedRunPage,
+  resolveSessionImportLimits,
+  sessionImportIdentity,
+  validateSessionImportHandle,
+  type INormalizedSessionImportOptions,
+} from './utils.sessionimport.js';
 import { wrapToolSet } from './utils.tooloutput.js';
 import {
   validateCompactSessionOptions,
@@ -299,6 +316,25 @@ interface IOrphanedExecutionContextOwner {
   sessionId: string;
 }
 
+/** A staged session import: its runs stay in memory until the import is committed. */
+interface IStagedSessionImport {
+  importId: string;
+  scopeId: string;
+  state: IStorageState;
+  scope: unknown;
+  sessionId: string;
+  options: INormalizedSessionImportOptions;
+  identity: string;
+  runs: IFlexImportedRun[];
+  runIds: Set<string>;
+  messageIds: Set<string>;
+  messageCount: number;
+  bytes: number;
+  phase: 'staging' | 'committing';
+  /** Discards the import when it stays idle; cleared once the import commits or is released. */
+  idleTimer?: ReturnType<typeof setTimeout>;
+}
+
 interface IStorageState {
   storageKey: string;
   compactorLifecycleController: AbortController;
@@ -310,6 +346,8 @@ interface IStorageState {
   sessionDeletions: Map<string, Promise<void>>;
   initializingSessions: Set<string>;
   sessionInitializations: Map<string, Promise<void>>;
+  /** Staged session imports by session id; their ids are also in `initializingSessions`. */
+  sessionImports: Map<string, IStagedSessionImport>;
   tombstones: Map<string, IFlexSessionTombstone>;
   tombstoneCleanups: Map<string, Promise<void>>;
   activeRuns: Map<string, IActiveRun>;
@@ -575,6 +613,7 @@ const resourceToolStemLength = 16;
 const repairCancellationMessage = 'The process stopped before this run completed.';
 const scopeRetirementMessage = 'The scope is being retired.';
 const slashCommandSessionUnavailableReason = 'Session must be idle with no queued prompts.';
+const importedSessionUnavailableReason = 'Session is an imported conversation and is read-only.';
 const externalErrorFallback: IFlexErrorInfo = Object.freeze({
   name: 'FlexHarnessExternalError',
   message: 'The model operation failed.',
@@ -714,6 +753,7 @@ export class FlexHarness<TScope = unknown> {
   private readonly callbackLimits: Required<IFlexCallbackLimits>;
   private readonly promptQueueLimits: Required<IFlexPromptQueueLimits>;
   private readonly reversionLimits: Required<IFlexReversionLimits>;
+  private readonly sessionImportLimits: Required<IFlexSessionImportLimits>;
   private readonly reversionMaintenanceTimeoutMs: number;
   private readonly turnReversionProvider: IFlexHarnessOptions<TScope>['turnReversionProvider'];
   private readonly reversionPolicy: TFlexReversionPolicy;
@@ -743,6 +783,7 @@ export class FlexHarness<TScope = unknown> {
   private readonly projectManagementQueues = new Map<string, Promise<void>>();
   private readonly activeSlashCommandExecutions = new Map<string, IActiveSlashCommandExecution>();
   private readonly activeSlashCommandListings = new Set<IActiveSlashCommandListing>();
+  private readonly stagedSessionImports = new Map<string, IStagedSessionImport>();
   private readonly compactorInvocationContext = new plugins.AsyncLocalStorage<
     ICompactorInvocation<TScope>
   >();
@@ -779,6 +820,7 @@ export class FlexHarness<TScope = unknown> {
     this.callbackLimits = resolveCallbackLimits(options.callbackLimits);
     this.promptQueueLimits = resolvePromptQueueLimits(options.promptQueueLimits);
     this.reversionLimits = resolveReversionLimits(options.reversionLimits);
+    this.sessionImportLimits = resolveSessionImportLimits(options.sessionImportLimits);
     this.reversionMaintenanceTimeoutMs = resolveReversionMaintenanceTimeoutMs(options);
     this.turnReversionProvider = options.turnReversionProvider;
     this.reversionPolicy = options.reversionPolicy ?? 'transcript-optional';
@@ -996,6 +1038,272 @@ export class FlexHarness<TScope = unknown> {
     return result;
   }
 
+  /**
+   * Starts a staged import of a finished conversation into a new read-only session. The session
+   * stays hidden until `commitSessionImport()`. A committed session with the same source, source
+   * id and part is reported instead of being imported twice.
+   */
+  public async beginSessionImport(
+    scopeId: string,
+    options: IFlexBeginSessionImportOptions,
+  ): Promise<TFlexBeginSessionImportResult> {
+    this.assertOpen();
+    const normalized = normalizeBeginSessionImportOptions(options);
+    const { scope, state } = await this.resolveState(scopeId);
+    await state.scopeQueue;
+    this.assertOpen();
+    this.assertStateAcceptingWork(state);
+    const { sessionId } = normalized;
+    const identity = sessionImportIdentity(normalized.origin);
+    for (const staged of state.sessionImports.values()) {
+      if (staged.sessionId === sessionId || staged.identity === identity) {
+        throw new FlexHarnessSessionBusyError(staged.sessionId, 'is already being imported');
+      }
+    }
+    for (const stored of state.sessions.values()) {
+      const origin = stored.session.origin;
+      if (origin === undefined || sessionImportIdentity(origin) !== identity) continue;
+      const existing: TFlexBeginSessionImportResult = {
+        status: origin.digest === normalized.origin.digest ? 'already_imported' : 'digest_mismatch',
+        session: stored.session,
+      };
+      return publicSnapshot(existing);
+    }
+    if (
+      state.sessions.has(sessionId)
+      || state.tombstones.has(sessionId)
+      || state.initializingSessions.has(sessionId)
+    ) {
+      throw new FlexHarnessValidationError(`Session "${sessionId}" already exists or is being deleted.`);
+    }
+    if (normalized.parent) this.requireImportParent(state, sessionId, normalized.parent);
+    if (this.stagedSessionImports.size >= this.sessionImportLimits.maxOpenImports) {
+      throw new FlexHarnessQueueFullError('FlexHarness has reached its open session import limit.');
+    }
+    const staged: IStagedSessionImport = {
+      importId: `import_${plugins.crypto.randomUUID()}`,
+      scopeId,
+      state,
+      scope: scope.scope,
+      sessionId,
+      options: normalized,
+      identity,
+      runs: [],
+      runIds: new Set(),
+      messageIds: new Set(),
+      messageCount: 0,
+      bytes: 0,
+      phase: 'staging',
+    };
+    this.stagedSessionImports.set(staged.importId, staged);
+    this.armStagedImportIdleTimer(staged);
+    state.sessionImports.set(sessionId, staged);
+    state.initializingSessions.add(sessionId);
+    const started: TFlexBeginSessionImportResult = {
+      status: 'started',
+      handle: { importId: staged.importId, scopeId, sessionId },
+    };
+    return publicSnapshot(started);
+  }
+
+  /** Stages one page of runs, in order, for a started session import. A rejected page stages nothing. */
+  public async appendImportedRuns(
+    handle: IFlexSessionImportHandle,
+    runs: readonly IFlexImportedRun[],
+  ): Promise<IFlexSessionImportProgress> {
+    const staged = this.requireStagedSessionImport(handle);
+    this.assertOpen();
+    this.assertStateAcceptingWork(staged.state);
+    const page = normalizeImportedRunPage(runs, staged.sessionId, this.sessionImportLimits.maxPageBytes);
+    const runIds = new Set<string>();
+    const messageIds = new Set<string>();
+    for (const run of page.runs) {
+      if (staged.runIds.has(run.user.runId) || runIds.has(run.user.runId)) {
+        throw new FlexHarnessValidationError(`Imported run "${run.user.runId}" is not unique.`);
+      }
+      runIds.add(run.user.runId);
+      for (const message of [run.user, run.assistant]) {
+        if (staged.messageIds.has(message.messageId) || messageIds.has(message.messageId)) {
+          throw new FlexHarnessValidationError(`Imported message "${message.messageId}" is not unique.`);
+        }
+        messageIds.add(message.messageId);
+      }
+    }
+    const messageCount = staged.messageCount + page.runs.length * 2;
+    if (messageCount > this.sessionImportLimits.maxMessagesPerSession) {
+      throw new FlexHarnessValidationError(
+        `An imported session holds at most ${this.sessionImportLimits.maxMessagesPerSession} messages.`,
+      );
+    }
+    const bytes = staged.bytes + page.bytes;
+    if (bytes > this.sessionImportLimits.maxSessionBytes) {
+      throw new FlexHarnessValidationError(
+        `An imported session holds at most ${this.sessionImportLimits.maxSessionBytes} message bytes.`,
+      );
+    }
+    staged.runs.push(...page.runs);
+    for (const runId of runIds) staged.runIds.add(runId);
+    for (const messageId of messageIds) staged.messageIds.add(messageId);
+    staged.messageCount = messageCount;
+    staged.bytes = bytes;
+    this.armStagedImportIdleTimer(staged);
+    return publicSnapshot({ runs: staged.runs.length, messages: messageCount, bytes });
+  }
+
+  /**
+   * Persists the staged runs and publishes the session: archived, read-only and marked with its
+   * `origin`. A failed commit removes everything it persisted before it rejects.
+   */
+  public async commitSessionImport(handle: IFlexSessionImportHandle): Promise<IFlexSession> {
+    const staged = this.requireStagedSessionImport(handle);
+    this.assertOpen();
+    const { state, scopeId, sessionId, options } = staged;
+    this.assertStateAcceptingWork(state);
+    if (staged.runs.length === 0) {
+      throw new FlexHarnessValidationError('A session import needs at least one run before it is committed.');
+    }
+    staged.phase = 'committing';
+    this.clearStagedImportIdleTimer(staged);
+    const scope = staged.scope as TScope;
+    let resolveInitialization!: () => void;
+    const initialization = new Promise<void>((resolve) => {
+      resolveInitialization = resolve;
+    });
+    let initializationCompleted = false;
+    const completeInitialization = () => {
+      if (initializationCompleted) return;
+      initializationCompleted = true;
+      if (state.sessionInitializations.get(sessionId) === initialization) {
+        state.sessionInitializations.delete(sessionId);
+      }
+      resolveInitialization();
+    };
+    state.sessionInitializations.set(sessionId, initialization);
+    const importedAt = new Date().toISOString();
+    const origin: IFlexSessionOrigin = {
+      kind: 'import',
+      ...cloneSerializable(options.origin),
+      importedAt,
+    };
+    let metadata!: IFlexSession;
+    let reserved = false;
+    let loaded: IStoredSessionState | undefined;
+    try {
+      // A tombstone reserves the id while the projection is written, so a crash before the session
+      // is published leaves only data that the next load or deletion cleans up.
+      await this.mutateScope(state, () => {
+        if (state.sessions.has(sessionId) || state.tombstones.has(sessionId)) {
+          throw this.trustInternalError(new FlexHarnessValidationError(
+            `Session "${sessionId}" already exists or is being deleted.`,
+          ));
+        }
+        const parent = options.parent
+          ? this.requireImportParent(state, sessionId, options.parent)
+          : undefined;
+        metadata = {
+          scopeId,
+          sessionId,
+          sessionGenerationId: createSessionGenerationId(),
+          sessionGenerationSequence: state.revision + 1,
+          ...(options.title === undefined ? {} : { title: options.title }),
+          createdAt: options.createdAt,
+          updatedAt: options.updatedAt,
+          archivedAt: importedAt,
+          status: 'idle',
+          activity: { status: 'idle' },
+          ...(options.parent === undefined
+            ? {}
+            : {
+                parentSessionId: options.parent.sessionId,
+                parentRunId: options.parent.runId,
+                parentToolCallId: options.parent.toolCallId,
+                agent: options.parent.agent,
+              }),
+          depth: parent === undefined ? 0 : (parent.session.depth ?? 0) + 1,
+          origin,
+        };
+        state.tombstones.set(sessionId, {
+          sessionId,
+          ...requireSessionGeneration(metadata),
+          deletedAt: importedAt,
+          rootSessionId: sessionId,
+          depth: 0,
+          imported: true,
+        });
+      });
+      reserved = true;
+      await this.stores.projections.save(state.storageKey, sessionId, {
+        schemaVersion: 3,
+        revision: 1,
+        messages: staged.runs.flatMap((run) => [run.user, run.assistant]),
+        stagedTerminals: [],
+        reversionSegments: [],
+        revertCursor: 0,
+        excludedRunIds: [],
+        pendingReversionReleases: [],
+      }, 0);
+      const runtime = await this.loadSessionRuntime(state, metadata, scopeId, scope);
+      loaded = runtime;
+      await this.mutateScope(state, () => {
+        if (
+          state.sessions.has(sessionId)
+          || state.tombstones.get(sessionId)?.sessionGenerationId !== metadata.sessionGenerationId
+        ) {
+          throw this.trustInternalError(new FlexHarnessAbortError(
+            'The session import lost its reservation before it was committed.',
+          ));
+        }
+        if (options.parent) this.requireImportParent(state, sessionId, options.parent);
+        state.tombstones.delete(sessionId);
+        state.sessions.set(sessionId, runtime);
+      });
+    } catch (error) {
+      const projected = this.projectOperationError(error, 'persistence', scopeId, sessionId, 'session-import');
+      const errors: unknown[] = [projected];
+      if (loaded && state.sessions.get(sessionId) !== loaded) {
+        try {
+          await this.closeStoredSession(loaded);
+        } catch (closeError) {
+          this.orphanedStoredSessions.add(loaded);
+          errors.push(closeError);
+        }
+      }
+      // A fenced namespace cannot tell whether its last save was persisted; its next load resolves
+      // the reservation instead: a surviving tombstone is cleaned up, a published session is kept.
+      if (reserved && state.tombstones.has(sessionId) && state.lifecycle !== 'fenced') {
+        completeInitialization();
+        try {
+          await this.finishTombstoneCleanup(state, sessionId, scopeId, { scopeId, scope });
+        } catch (cleanupError) {
+          errors.push(this.projectOperationError(
+            cleanupError,
+            'persistence',
+            scopeId,
+            sessionId,
+            'session-import-cleanup',
+          ));
+        }
+      }
+      throw combineErrors(errors);
+    } finally {
+      this.releaseStagedSessionImport(staged);
+      completeInitialization();
+    }
+    const result = publicSnapshot(metadata);
+    this.emitEvent(scopeId, metadata, { type: 'session.created', session: result });
+    return result;
+  }
+
+  /** Discards a staged import. Nothing of it was persisted; an unknown or finished handle is ignored. */
+  public async abortSessionImport(handle: IFlexSessionImportHandle): Promise<void> {
+    const staged = this.findStagedSessionImport(handle);
+    if (!staged) return;
+    if (staged.phase === 'committing') {
+      throw new FlexHarnessSessionBusyError(staged.sessionId, 'is being committed');
+    }
+    this.releaseStagedSessionImport(staged);
+  }
+
   public async getSession(scopeId: string, sessionId: string): Promise<IFlexSession> {
     const { state } = await this.resolveState(scopeId);
     await state.scopeQueue;
@@ -1068,7 +1376,7 @@ export class FlexHarness<TScope = unknown> {
     scopeId: string,
     sessionId: string,
   ): Promise<IFlexProjectStateResult> {
-    const { state, stored } = await this.resolveProjectManagementSession(scopeId, sessionId);
+    const { state, stored } = await this.resolveProjectManagementSession(scopeId, sessionId, 'read');
     const snapshot = await this.readProjectManagementState(state, stored);
     return this.projectStateResult(snapshot);
   }
@@ -1077,7 +1385,7 @@ export class FlexHarness<TScope = unknown> {
     scopeId: string,
     sessionId: string,
   ): Promise<IFlexProjectTasksResult> {
-    const { state, stored } = await this.resolveProjectManagementSession(scopeId, sessionId);
+    const { state, stored } = await this.resolveProjectManagementSession(scopeId, sessionId, 'read');
     const snapshot = await this.readProjectManagementState(state, stored);
     return this.projectTasksResult(snapshot, snapshot.tasks);
   }
@@ -1088,7 +1396,7 @@ export class FlexHarness<TScope = unknown> {
     input: IFlexCreateProjectTaskInput,
   ): Promise<IFlexProjectTaskResult> {
     validateCreateProjectTaskInput(input);
-    const { state, stored } = await this.resolveProjectManagementSession(scopeId, sessionId);
+    const { state, stored } = await this.resolveProjectManagementSession(scopeId, sessionId, 'write');
     return this.createProjectTaskInState(
       state,
       stored,
@@ -1103,7 +1411,7 @@ export class FlexHarness<TScope = unknown> {
     input: IFlexUpdateProjectTaskInput,
   ): Promise<IFlexProjectTaskResult> {
     validateUpdateProjectTaskInput(input);
-    const { state, stored } = await this.resolveProjectManagementSession(scopeId, sessionId);
+    const { state, stored } = await this.resolveProjectManagementSession(scopeId, sessionId, 'write');
     return this.updateProjectTaskInState(
       state,
       stored,
@@ -1118,7 +1426,7 @@ export class FlexHarness<TScope = unknown> {
     taskId: string,
   ): Promise<IFlexProjectTaskResult> {
     validateProjectTaskId(taskId);
-    const { state, stored } = await this.resolveProjectManagementSession(scopeId, sessionId);
+    const { state, stored } = await this.resolveProjectManagementSession(scopeId, sessionId, 'write');
     return this.deleteProjectTaskInState(
       state,
       stored,
@@ -1131,7 +1439,7 @@ export class FlexHarness<TScope = unknown> {
     scopeId: string,
     sessionId: string,
   ): Promise<IFlexProjectTasksResult> {
-    const { state, stored } = await this.resolveProjectManagementSession(scopeId, sessionId);
+    const { state, stored } = await this.resolveProjectManagementSession(scopeId, sessionId, 'write');
     return this.clearProjectTasksInState(
       state,
       stored,
@@ -1143,7 +1451,7 @@ export class FlexHarness<TScope = unknown> {
     scopeId: string,
     sessionId: string,
   ): Promise<IFlexProjectGoalResult> {
-    const { state, stored } = await this.resolveProjectManagementSession(scopeId, sessionId);
+    const { state, stored } = await this.resolveProjectManagementSession(scopeId, sessionId, 'read');
     const snapshot = await this.readProjectManagementState(state, stored);
     return this.projectGoalResult(snapshot);
   }
@@ -1159,7 +1467,7 @@ export class FlexHarness<TScope = unknown> {
       FLEX_PROJECT_MANAGEMENT_LIMITS.maxGoalBytes,
       true,
     );
-    const { state, stored } = await this.resolveProjectManagementSession(scopeId, sessionId);
+    const { state, stored } = await this.resolveProjectManagementSession(scopeId, sessionId, 'write');
     return this.setProjectGoalInState(
       state,
       stored,
@@ -1172,7 +1480,7 @@ export class FlexHarness<TScope = unknown> {
     scopeId: string,
     sessionId: string,
   ): Promise<IFlexProjectGoalResult> {
-    const { state, stored } = await this.resolveProjectManagementSession(scopeId, sessionId);
+    const { state, stored } = await this.resolveProjectManagementSession(scopeId, sessionId, 'write');
     return this.clearProjectGoalInState(
       state,
       stored,
@@ -1184,7 +1492,7 @@ export class FlexHarness<TScope = unknown> {
     scopeId: string,
     sessionId: string,
   ): Promise<IFlexProjectScratchpadResult> {
-    const { state, stored } = await this.resolveProjectManagementSession(scopeId, sessionId);
+    const { state, stored } = await this.resolveProjectManagementSession(scopeId, sessionId, 'read');
     const snapshot = await this.readProjectManagementState(state, stored);
     return this.projectScratchpadResult(snapshot);
   }
@@ -1199,7 +1507,7 @@ export class FlexHarness<TScope = unknown> {
       'project scratchpad',
       FLEX_PROJECT_MANAGEMENT_LIMITS.maxScratchpadBytes,
     );
-    const { state, stored } = await this.resolveProjectManagementSession(scopeId, sessionId);
+    const { state, stored } = await this.resolveProjectManagementSession(scopeId, sessionId, 'write');
     return this.setProjectScratchpadInState(
       state,
       stored,
@@ -1218,7 +1526,7 @@ export class FlexHarness<TScope = unknown> {
       'project scratchpad append',
       FLEX_PROJECT_MANAGEMENT_LIMITS.maxScratchpadBytes,
     );
-    const { state, stored } = await this.resolveProjectManagementSession(scopeId, sessionId);
+    const { state, stored } = await this.resolveProjectManagementSession(scopeId, sessionId, 'write');
     return this.appendProjectScratchpadInState(
       state,
       stored,
@@ -1231,7 +1539,7 @@ export class FlexHarness<TScope = unknown> {
     scopeId: string,
     sessionId: string,
   ): Promise<IFlexProjectScratchpadResult> {
-    const { state, stored } = await this.resolveProjectManagementSession(scopeId, sessionId);
+    const { state, stored } = await this.resolveProjectManagementSession(scopeId, sessionId, 'write');
     return this.clearProjectScratchpadInState(
       state,
       stored,
@@ -1295,6 +1603,7 @@ export class FlexHarness<TScope = unknown> {
       if (!tombstone || !matchesSessionGeneration(tombstone, validated.root)) {
         return { matched: false };
       }
+      this.assertNoCommittingSessionImport(state, validated.root.sessionId);
       const rootSessionId = tombstone.rootSessionId ?? tombstone.sessionId;
       const descendantRoots = this.descendantTombstoneRoots(state, rootSessionId);
       this.assertAuthorizedSessionGenerationCohort(
@@ -1323,6 +1632,7 @@ export class FlexHarness<TScope = unknown> {
     this.assertNoAmbientSlashCommandTeardown({ storageKey: state.storageKey });
     validateIdentifier(sessionId, 'sessionId');
     await state.scopeQueue;
+    this.assertNoCommittingSessionImport(state, sessionId);
     return this.startSessionDeletion(state, scopeId, scope.scope, sessionId);
   }
 
@@ -1429,6 +1739,7 @@ export class FlexHarness<TScope = unknown> {
           ? {}
           : { parentSessionId: entry.session.parentSessionId }),
         ...(subagent === undefined ? {} : { subagent: cloneSerializable(subagent) }),
+        ...(entry.session.origin === undefined ? {} : { imported: true as const }),
       });
     }
     return {
@@ -1597,7 +1908,12 @@ export class FlexHarness<TScope = unknown> {
       const nextCursor = index > 0
         ? this.createMessageCursor(namespace, sessionId, candidate.messageId)
         : undefined;
-      if (jsonBytes({ messages: candidateMessages, ...(nextCursor ? { nextCursor } : {}) }) > maxTransferPageBytes) break;
+      const candidatePage: IFlexMessagePage = {
+        messages: candidateMessages,
+        startIndex: index,
+        ...(nextCursor ? { nextCursor } : {}),
+      };
+      if (jsonBytes(candidatePage) > maxTransferPageBytes) break;
       start = index;
       messages = candidateMessages;
     }
@@ -1607,7 +1923,7 @@ export class FlexHarness<TScope = unknown> {
     const nextCursor = start > 0
       ? this.createMessageCursor(namespace, sessionId, messages[0].messageId)
       : undefined;
-    return publicSnapshot({ messages, ...(nextCursor ? { nextCursor } : {}) });
+    return publicSnapshot({ messages, startIndex: start, ...(nextCursor ? { nextCursor } : {}) });
   }
 
   public async getMessage(
@@ -1644,12 +1960,18 @@ export class FlexHarness<TScope = unknown> {
         signal,
       );
       signal.throwIfAborted();
-      return this.createSlashCommandDescriptors(
+      const descriptors = this.createSlashCommandDescriptors(
         state,
         stored,
         sessionAvailable,
         reversionIdleReason,
       );
+      if (stored.session.origin === undefined) return descriptors;
+      return publicSnapshot(descriptors.map((descriptor): IFlexSlashCommandDescriptor => ({
+        ...descriptor,
+        available: false,
+        unavailableReason: importedSessionUnavailableReason,
+      })));
     });
   }
 
@@ -1788,6 +2110,7 @@ export class FlexHarness<TScope = unknown> {
     this.assertOpen();
     this.assertStateAcceptingWork(state);
     const stored = this.requireSession(state, sessionId);
+    this.assertSessionWritable(stored);
     const sessionKey = this.slashCommandSessionKey(state.storageKey, sessionId);
     const invocationOwner = this.slashCommandInvocationContext.getStore();
     if (invocationOwner?.sessionKey === sessionKey) {
@@ -2383,6 +2706,7 @@ export class FlexHarness<TScope = unknown> {
     }
     const { scope, state } = await this.resolveState(scopeId);
     const stored = this.requireSession(state, sessionId);
+    this.assertSessionWritable(stored);
     this.assertStateAcceptingWork(state);
     let canonical: plugins.TAgentToolExecutionReconciliationOptions;
     if (reconciliation.resolution === 'executed') {
@@ -2422,6 +2746,7 @@ export class FlexHarness<TScope = unknown> {
     this.validateRuntimeEvent(event);
     const { scope, state } = await this.resolveState(scopeId);
     const stored = this.requireSession(state, sessionId);
+    this.assertSessionWritable(stored);
     this.assertStateAcceptingWork(state);
     try {
       await this.withCompactorContext(
@@ -2441,6 +2766,7 @@ export class FlexHarness<TScope = unknown> {
     const { modelHint } = validateCompactSessionOptions(options);
     const { scope, state } = await this.resolveState(scopeId);
     const stored = this.requireSession(state, sessionId);
+    this.assertSessionWritable(stored);
     const invocationOwner = this.slashCommandInvocationContext.getStore();
     if (invocationOwner?.sessionKey === this.slashCommandSessionKey(state.storageKey, sessionId)) {
       throw this.trustInternalError(new FlexHarnessSlashCommandReentryError(sessionId));
@@ -2688,6 +3014,7 @@ export class FlexHarness<TScope = unknown> {
     signal?: AbortSignal,
   ): Promise<string> {
     const stored = this.requireSession(state, sessionId);
+    this.assertSessionWritable(stored);
     this.assertStateAcceptingWork(state);
     const invocationOwner = this.slashCommandInvocationContext.getStore();
     if (invocationOwner?.sessionKey === this.slashCommandSessionKey(state.storageKey, sessionId)) {
@@ -3040,6 +3367,7 @@ export class FlexHarness<TScope = unknown> {
     }
     const { scope, state } = await this.resolveState(scopeId);
     const stored = this.requireSession(state, sessionId);
+    this.assertSessionWritable(stored);
     this.assertStateAcceptingWork(state);
     this.requireSessionAvailableForSlashCommand(state, stored, 'archive');
     const compaction = compactionEventId === undefined
@@ -3239,6 +3567,7 @@ export class FlexHarness<TScope = unknown> {
       }
       this.assertStateAcceptingWork(state);
       const stored = this.requireSession(state, sessionId);
+      this.assertSessionWritable(stored);
       const sessionKey = this.slashCommandSessionKey(state.storageKey, sessionId);
       const invocationOwner = this.slashCommandInvocationContext.getStore();
       if (invocationOwner?.sessionKey === sessionKey) {
@@ -4209,13 +4538,16 @@ export class FlexHarness<TScope = unknown> {
   private async resolveProjectManagementSession(
     scopeId: string,
     sessionId: string,
+    access: 'read' | 'write',
   ): Promise<{ state: IStorageState; stored: IStoredSessionState }> {
     this.requireProjectManagementTools();
     const { state } = await this.resolveState(scopeId);
     await state.scopeQueue;
     this.assertOpen();
     this.assertStateAcceptingWork(state);
-    return { state, stored: this.requireSession(state, sessionId) };
+    const stored = this.requireSession(state, sessionId);
+    if (access === 'write') this.assertSessionWritable(stored);
+    return { state, stored };
   }
 
   private assertProjectManagementSession(
@@ -7984,6 +8316,7 @@ export class FlexHarness<TScope = unknown> {
       sessionDeletions: new Map(),
       initializingSessions: new Set(),
       sessionInitializations: new Map(),
+      sessionImports: new Map(),
       tombstones: new Map(snapshot.tombstones.map((entry) => [entry.sessionId, entry])),
       tombstoneCleanups: new Map(),
       activeRuns: new Map(),
@@ -8397,6 +8730,10 @@ export class FlexHarness<TScope = unknown> {
     scopeId?: string,
     scope?: TScope,
   ): Promise<boolean> {
+    if (stored.session.origin !== undefined) {
+      this.assertImportedSessionState(stored);
+      return false;
+    }
     const beforeProjection = JSON.stringify({
       messages: stored.messages,
       stagedTerminals: stored.stagedTerminals,
@@ -9054,7 +9391,8 @@ export class FlexHarness<TScope = unknown> {
       this.stores.jobs.deleteSession(storageKey, sessionId),
       this.stores.projections.deleteSession(storageKey, sessionId),
       this.stores.permissions.deleteSession(storageKey, sessionId),
-      projectManagementCleanup(),
+      // An imported session refuses every project-management write, so it has no state to fence.
+      ...(tombstone.imported ? [] : [projectManagementCleanup()]),
     ]);
     const errors = results
       .filter((result): result is PromiseRejectedResult => result.status === 'rejected')
@@ -9916,6 +10254,9 @@ export class FlexHarness<TScope = unknown> {
       return;
     }
     if (state.lifecycle !== 'fenced') state.lifecycle = 'retiring';
+    for (const staged of [...state.sessionImports.values()]) {
+      if (staged.phase === 'staging') this.releaseStagedSessionImport(staged);
+    }
     const errors: unknown[] = [];
     const listingSettlement = this.abortSlashCommandListings(storageKey, reason);
     if (listingSettlement) await listingSettlement;
@@ -10048,6 +10389,7 @@ export class FlexHarness<TScope = unknown> {
     state.pendingPermissions.clear();
     state.initializingSessions.clear();
     state.sessionInitializations.clear();
+    state.sessionImports.clear();
   }
 
   private async disposeInternal(): Promise<void> {
@@ -10388,6 +10730,138 @@ export class FlexHarness<TScope = unknown> {
     return stored;
   }
 
+  /** Refuses an operation that would change an imported session's history or model context. */
+  private assertSessionWritable(stored: IStoredSessionState): void {
+    if (stored.session.origin !== undefined) {
+      throw this.trustInternalError(new FlexHarnessImportedSessionError(stored.session.sessionId));
+    }
+  }
+
+  /** An imported session never ran here, so it has no hidden stage and no reversion state. */
+  private assertImportedSessionState(stored: IStoredSessionState): void {
+    if (
+      stored.stagedTerminals.length > 0
+      || stored.reversionSegments.length > 0
+      || stored.excludedRunIds.length > 0
+      || stored.pendingReversion !== undefined
+      || stored.pendingReversionReleases.length > 0
+      || stored.messages.some((message) => message.status === 'streaming')
+    ) {
+      throw new FlexHarnessValidationError(
+        `Imported session "${stored.session.sessionId}" has run state it cannot have.`,
+      );
+    }
+  }
+
+  private assertNoCommittingSessionImport(state: IStorageState, sessionId: string): void {
+    if (state.sessionImports.get(sessionId)?.phase === 'committing') {
+      throw new FlexHarnessSessionBusyError(sessionId, 'is being imported');
+    }
+  }
+
+  private findStagedSessionImport(
+    handle: IFlexSessionImportHandle,
+  ): IStagedSessionImport | undefined {
+    const validated = validateSessionImportHandle(handle);
+    const staged = this.stagedSessionImports.get(validated.importId);
+    if (
+      staged
+      && (staged.scopeId !== validated.scopeId || staged.sessionId !== validated.sessionId)
+    ) {
+      throw new FlexHarnessValidationError('The session import handle does not match its import.');
+    }
+    return staged;
+  }
+
+  private requireStagedSessionImport(handle: IFlexSessionImportHandle): IStagedSessionImport {
+    const staged = this.findStagedSessionImport(handle);
+    if (!staged) throw new FlexHarnessNotFoundError('Session import', handle.importId);
+    if (staged.phase !== 'staging') {
+      throw new FlexHarnessSessionBusyError(staged.sessionId, 'is being committed');
+    }
+    return staged;
+  }
+
+  private armStagedImportIdleTimer(staged: IStagedSessionImport): void {
+    this.clearStagedImportIdleTimer(staged);
+    const timer = setTimeout(() => {
+      if (staged.idleTimer !== timer) return;
+      delete staged.idleTimer;
+      if (staged.phase === 'staging') this.releaseStagedSessionImport(staged);
+    }, this.sessionImportLimits.stagedImportIdleTimeoutMs);
+    timer.unref();
+    staged.idleTimer = timer;
+  }
+
+  private clearStagedImportIdleTimer(staged: IStagedSessionImport): void {
+    if (staged.idleTimer === undefined) return;
+    clearTimeout(staged.idleTimer);
+    delete staged.idleTimer;
+  }
+
+  private releaseStagedSessionImport(staged: IStagedSessionImport): void {
+    this.clearStagedImportIdleTimer(staged);
+    if (this.stagedSessionImports.get(staged.importId) === staged) {
+      this.stagedSessionImports.delete(staged.importId);
+    }
+    if (staged.state.sessionImports.get(staged.sessionId) === staged) {
+      staged.state.sessionImports.delete(staged.sessionId);
+      staged.state.initializingSessions.delete(staged.sessionId);
+    }
+    staged.runs = [];
+    staged.runIds.clear();
+    staged.messageIds.clear();
+  }
+
+  /**
+   * An imported child session belongs to a committed imported parent whose run `parent.runId` holds
+   * the tool call `parent.toolCallId` naming the child, and no other session claims that tool call.
+   */
+  private requireImportParent(
+    state: IStorageState,
+    sessionId: string,
+    parent: NonNullable<INormalizedSessionImportOptions['parent']>,
+  ): IStoredSessionState {
+    const parentStored = state.initializingSessions.has(parent.sessionId)
+      || state.tombstones.has(parent.sessionId)
+      ? undefined
+      : state.sessions.get(parent.sessionId);
+    if (!parentStored?.session.origin) {
+      throw this.trustInternalError(new FlexHarnessValidationError(
+        `The parent of imported session "${sessionId}" must be a committed imported session.`,
+      ));
+    }
+    if ((parentStored.session.depth ?? 0) + 1 > FLEX_SESSION_IMPORT_MAX_DEPTH) {
+      throw this.trustInternalError(new FlexHarnessValidationError(
+        `Imported sessions nest at most ${FLEX_SESSION_IMPORT_MAX_DEPTH} levels deep.`,
+      ));
+    }
+    const referenced = parentStored.messages.some((message) =>
+      message.role === 'assistant'
+      && message.runId === parent.runId
+      && message.parts.some((part) =>
+        part.type === 'tool'
+        && part.toolCallId === parent.toolCallId
+        && part.childSessionId === sessionId));
+    if (!referenced) {
+      throw this.trustInternalError(new FlexHarnessValidationError(
+        `Parent run "${parent.runId}" has no tool call "${parent.toolCallId}" whose childSessionId is "${sessionId}".`,
+      ));
+    }
+    for (const stored of state.sessions.values()) {
+      if (
+        stored.session.parentSessionId === parent.sessionId
+        && stored.session.parentRunId === parent.runId
+        && stored.session.parentToolCallId === parent.toolCallId
+      ) {
+        throw this.trustInternalError(new FlexHarnessValidationError(
+          `Session "${stored.session.sessionId}" already belongs to tool call "${parent.toolCallId}".`,
+        ));
+      }
+    }
+    return parentStored;
+  }
+
   private requireMessage(stored: IStoredSessionState, messageId: string): IFlexMessage {
     const message = this.visibleMessages(stored).find((entry) => entry.messageId === messageId);
     if (!message) throw new FlexHarnessNotFoundError('Message', messageId);