@modelprofile.com/flexharness 9.3.1 → 9.5.0

package/ts/errors.ts

@@ -44,6 +44,17 @@ export class FlexHarnessSessionBusyError extends FlexHarnessError {
   }
 }
 
+/** An operation would change the history or model context of an imported, read-only session. */
+export class FlexHarnessImportedSessionError extends FlexHarnessError {
+  public readonly sessionId: string;
+
+  constructor(sessionId: string) {
+    super('FLEX_SESSION_READ_ONLY', `Session "${sessionId}" is an imported conversation and is read-only.`);
+    this.name = 'FlexHarnessImportedSessionError';
+    this.sessionId = sessionId;
+  }
+}
+
 export class FlexHarnessSlashCommandUnavailableError extends FlexHarnessError {
   public readonly commandName: string;
   public readonly unavailableReason: string;

package/ts/interfaces.ts

@@ -169,8 +169,129 @@ export interface IFlexSession {
   parentToolCallId?: string;
   agent?: string;
   depth?: number;
+  /** Set only on a session the staged session import created; such a session is read-only. */
+  origin?: IFlexSessionOrigin;
 }
 
+/** The position of an imported session when one source conversation was split into several sessions. */
+export interface IFlexSessionImportPart {
+  /** Zero-based position of this session among the parts. */
+  index: number;
+  /** The number of parts the source was split into. */
+  count: number;
+}
+
+/** What an import caller states about the source of the history it imports. */
+export interface IFlexSessionImportSource {
+  /** The kind of source, for example `claude-code-transcript`. */
+  source: string;
+  /** The source's own identifier of the conversation. */
+  sourceId: string;
+  /** The caller's digest of the source content; a changed source has a changed digest. */
+  digest: string;
+  part?: IFlexSessionImportPart;
+  /** Source-specific metadata, for example the source working directory or what the conversion lost. */
+  details?: IJsonObject;
+}
+
+/** Where an imported session's history came from. */
+export interface IFlexSessionOrigin extends IFlexSessionImportSource {
+  kind: 'import';
+  /** When FlexHarness committed the import. */
+  importedAt: string;
+}
+
+/** The imported parent session, run and tool call an imported child session belongs to. */
+export interface IFlexSessionImportParent {
+  sessionId: string;
+  runId: string;
+  toolCallId: string;
+  agent: string;
+}
+
+export interface IFlexBeginSessionImportOptions {
+  /** Caller-chosen and deterministic, so a repeated import finds the earlier one. */
+  sessionId: string;
+  title?: string;
+  /** When the source conversation started, as `Date.prototype.toISOString()` renders it. */
+  createdAt: string;
+  /** When the source conversation last changed; defaults to `createdAt`. */
+  updatedAt?: string;
+  origin: IFlexSessionImportSource;
+  parent?: IFlexSessionImportParent;
+}
+
+export interface IFlexSessionImportHandle {
+  importId: string;
+  scopeId: string;
+  sessionId: string;
+}
+
+export interface IFlexSessionImportStarted {
+  status: 'started';
+  handle: IFlexSessionImportHandle;
+}
+
+/**
+ * A session with the same source, source id and part already exists. `already_imported` means its
+ * digest equals the requested one; `digest_mismatch` means the source changed since that import.
+ */
+export interface IFlexSessionImportExisting {
+  status: 'already_imported' | 'digest_mismatch';
+  session: IFlexSession;
+}
+
+export type TFlexBeginSessionImportResult = IFlexSessionImportStarted | IFlexSessionImportExisting;
+
+/** One imported run: a user message and the assistant message that answered it. */
+export interface IFlexImportedRun {
+  user: IFlexMessage;
+  assistant: IFlexMessage;
+}
+
+export interface IFlexSessionImportProgress {
+  runs: number;
+  messages: number;
+  bytes: number;
+}
+
+export interface IFlexSessionImportLimits {
+  /** Staged imports open at once in one FlexHarness. */
+  maxOpenImports?: number;
+  /** Messages in one imported session, two per run. */
+  maxMessagesPerSession?: number;
+  /** JSON bytes of all messages of one imported session. */
+  maxSessionBytes?: number;
+  /** JSON bytes of the runs one `appendImportedRuns()` call carries. */
+  maxPageBytes?: number;
+  /**
+   * Milliseconds a staged import may stay without an `appendImportedRuns()` call. An expired
+   * import is discarded as if it were aborted, which frees its slot and its staged memory.
+   */
+  stagedImportIdleTimeoutMs?: number;
+}
+
+/** JSON bytes of one imported message; a larger message could not be read back whole. */
+export const FLEX_SESSION_IMPORT_MAX_MESSAGE_BYTES = 480 * 1024;
+export const FLEX_SESSION_IMPORT_MAX_DETAILS_BYTES = 16 * 1024;
+export const FLEX_SESSION_IMPORT_MAX_DEPTH = 8;
+
+export const FLEX_SESSION_IMPORT_DEFAULT_LIMITS = Object.freeze({
+  maxOpenImports: 2,
+  maxMessagesPerSession: 2048,
+  maxSessionBytes: 64 * 1024 * 1024,
+  maxPageBytes: 1024 * 1024,
+  stagedImportIdleTimeoutMs: 5 * 60 * 1000,
+});
+
+export const FLEX_SESSION_IMPORT_MAXIMUM_LIMITS = Object.freeze({
+  maxOpenImports: 64,
+  maxMessagesPerSession: 20_000,
+  maxSessionBytes: 256 * 1024 * 1024,
+  maxPageBytes: 1536 * 1024,
+  stagedImportIdleTimeoutMs: 60 * 60 * 1000,
+});
+
 export interface IFlexCreateSessionOptions {
   sessionId?: string;
   sessionGenerationId?: string;
@@ -1059,8 +1180,31 @@ export interface IFlexAgentContextInvocation<TScope = unknown> {
   readonly sessionId: string;
 }
 
+/**
+ * The options a `contextCompactor` receives. `resolvedModel` and `modelHint` state the model the
+ * compacted work was dispatched on; when both are absent nothing dispatched states one and the
+ * host chooses the compaction model.
+ */
 export interface IFlexAgentContextCompactionOptions<TScope = unknown>
-  extends plugins.IAgentContextCompactionOptions, IFlexAgentContextInvocation<TScope> {}
+  extends plugins.IAgentContextCompactionOptions, IFlexAgentContextInvocation<TScope> {
+  /**
+   * Set when `reason` is `'context-overflow'`: the model the run whose context overflowed resolved
+   * and generates with, as `IFlexModelResolver.resolveModel()` returned it for that run. A
+   * delegated run's overflow carries the delegated run's own model.
+   */
+  readonly resolvedModel?: Readonly<IFlexResolvedModel>;
+  /**
+   * Set when `reason` is `'manual'` and the compaction was requested with a model hint: the
+   * `modelHint` of the `/compact` slash command's execution options or of `compactSession()`.
+   * Resolve it as the model resolver resolves a prompt's `modelHint`.
+   */
+  readonly modelHint?: string;
+}
+
+export interface IFlexCompactSessionOptions {
+  /** The model hint the compactor receives as `modelHint`. */
+  modelHint?: string;
+}
 
 export type TFlexAgentContextCompactor<TScope = unknown> = (
   messages: Parameters<plugins.TAgentContextCompactor>[0],
@@ -1111,6 +1255,7 @@ export interface IFlexHarnessOptions<TScope> {
   callbackLimits?: IFlexCallbackLimits;
   promptQueueLimits?: IFlexPromptQueueLimits;
   reversionLimits?: IFlexReversionLimits;
+  sessionImportLimits?: IFlexSessionImportLimits;
   /**
    * Bounds each turn-reversion maintenance operation. Falls back to
    * agentSessionPolicy.generationLeaseCleanupTimeoutMs, then 30 seconds.

package/ts/readme.md

@@ -235,6 +235,13 @@ const harness = new FlexHarness<IProjectScope>({
     maxExcludedRunIds: 1000,
     maxPendingReversionReleases: 1000,
   },
+  sessionImportLimits: {
+    maxOpenImports: 2,
+    maxMessagesPerSession: 2048,
+    maxSessionBytes: 64 * 1024 * 1024,
+    maxPageBytes: 1024 * 1024,
+    stagedImportIdleTimeoutMs: 5 * 60 * 1000,
+  },
   subagents: [
     {
       name: 'researcher',
@@ -580,7 +587,7 @@ const undone = await harness.undoSession(scopeId, sessionId);
 console.log(undone.revertedRunId);
 const redone = await harness.redoSession(scopeId, sessionId);
 console.log(redone.restoredRunId);
-await harness.compactSession(scopeId, sessionId);
+await harness.compactSession(scopeId, sessionId, { modelHint: 'summary-model' });
 await harness.archiveSessionEvents(scopeId, sessionId, compactionEventId);
 await harness.listBackgroundExecutions(scopeId, sessionId);
 await harness.getBackgroundExecution(scopeId, sessionId, executionId);
@@ -667,7 +674,7 @@ Two horizons bound undo. Retention pruning removes the oldest complete visible u
 
 Session metadata archival through `updateSession(..., { archived: true })` only sets `archivedAt`. It does not archive Agent events, retire captures, or remove undo history.
 
-`executeSlashCommand()` is the authoritative parser and lookup boundary. Its result distinguishes `not-command`, `malformed`, `unknown`, completed `operation`, bounded `handler-result`, and `prompt-admission`. A prompt admission contains the normal `{ queueId, runId, completion }`; await `admission.completion` for the model result. Unknown commands are never admitted as literal prompts. Known unavailable commands and invalid arguments throw typed FlexHarness errors. Options accept `modelHint`, `system`, `maxSteps`, and `signal`; commands do not accept attachments. Aborting a template or `init` execution cancels its exact queued or started prompt without affecting another queue entry.
+`executeSlashCommand()` is the authoritative parser and lookup boundary. Its result distinguishes `not-command`, `malformed`, `unknown`, completed `operation`, bounded `handler-result`, and `prompt-admission`. A prompt admission contains the normal `{ queueId, runId, completion }`; await `admission.completion` for the model result. Unknown commands are never admitted as literal prompts. Known unavailable commands and invalid arguments throw typed FlexHarness errors. Options accept `modelHint`, `system`, `maxSteps`, and `signal`; commands do not accept attachments. `/compact` takes `modelHint` and `signal` only and refuses `system` and `maxSteps` with `FlexHarnessValidationError`. Aborting a template or `init` execution cancels its exact queued or started prompt without affecting another queue entry.
 
 Templates replace every `$ARGUMENTS` with untouched raw argument text. `$1` through the highest referenced positional placeholder use tokenized arguments, with the highest position receiving all remaining tokens joined by spaces. Missing positions become empty. A template with no placeholders appends non-empty raw arguments after a blank line. `/init` uses the OpenCode 1.18.15 `AGENTS.md` initialization prompt with provider-neutral active-workspace wording.
 
@@ -805,6 +812,82 @@ Public audit history is safe to send to controllers: attachment parts contain so
 
 Sessions expose `idle`, `scheduled`, `running`, `waiting_permission`, `failed`, and `cancelled` status. Persisted non-terminal activity is repaired from canonical Agent generation outcomes after process restart; incomplete messages and parts normalize to `cancelled` unless an accepted hidden terminal stage can be promoted.
 
+## Conversation Import
+
+A finished conversation from another tool can be imported as an archived, read-only session. The import is staged in three steps, so a large conversation crosses a process boundary in bounded pages. Turning a source format into Flex messages is the importer's job; the core validates, bounds, persists and protects the result.
+
+```typescript
+const started = await harness.beginSessionImport('project:billing', {
+  sessionId: 'claude-7f3c2a',
+  title: 'Fix the billing export',
+  createdAt: '2026-09-01T09:00:00.000Z',
+  updatedAt: '2026-09-01T11:00:00.000Z',
+  origin: {
+    source: 'claude-code-transcript',
+    sourceId: '7f3c2a',
+    digest: 'sha256:9b1d…',
+    details: { cwd: '/workspace' },
+  },
+});
+
+if (started.status === 'started') {
+  try {
+    for (const page of pages) {
+      await harness.appendImportedRuns(started.handle, page);
+    }
+    const session = await harness.commitSessionImport(started.handle);
+  } finally {
+    await harness.abortSessionImport(started.handle);
+  }
+}
+```
+
+- **`beginSessionImport(scopeId, options)`** validates the options and reserves the caller-chosen `sessionId`. Choose a deterministic id, derived from the source. The result is one of three:
+  - `started`, with a handle `{ importId, scopeId, sessionId }`;
+  - `already_imported`, with the existing session;
+  - `digest_mismatch`, with the existing session.
+
+  A scope holds at most one import per `origin.source`, `origin.sourceId` and `origin.part.index`, whatever its session id. `already_imported` means that session has the same `origin.digest`, so the caller skips it. `digest_mismatch` means the source changed since; the caller deletes that session and imports again. A staged import of the same session id or source identity throws `FlexHarnessSessionBusyError`. Until the commit completes, `listSessions()` omits the session and `createSession()` refuses its id. While the import is staged, `getSession()` throws `FlexHarnessSessionBusyError`. While its commit runs, `getSession()` throws `FlexHarnessNotFoundError`, because a deletion tombstone reserves the id.
+- **`appendImportedRuns(handle, runs)`** stages one page of runs, in order. A run is `{ user, assistant }`, two messages of the exact `IFlexMessage` shape. Both belong to the imported session, share one `runId` and one terminal status (`completed`, `failed` or `cancelled`), and have no `running` reasoning or tool part. Timestamps are ISO 8601 as `Date.prototype.toISOString()` renders them. Run ids and message ids are unique within the import. A page that breaks a rule or a bound stages nothing, and the import stays open. The result reports the staged `runs`, `messages` and `bytes`.
+- **`commitSessionImport(handle)`** persists the runs and publishes the session, with one `session.created` event:
+  - `origin` is `{ kind: 'import', source, sourceId, digest, part?, details?, importedAt }`, and `archivedAt` equals `importedAt`;
+  - `createdAt` and `updatedAt` are the ones passed to `beginSessionImport()`, and the status is `idle`.
+
+  The commit first persists a deletion tombstone for the id, then writes the projection, then replaces the tombstone with the session in one scope save. A failed commit removes what it persisted through the normal tombstone cleanup. After a crash, or a save whose outcome is uncertain, the next load of the namespace resolves it: a surviving tombstone is cleaned up, and a published session is kept. A commit needs at least one run.
+- **`abortSessionImport(handle)`** discards a staged import. Nothing of it was persisted. An unknown or finished handle is ignored, so the call is safe in a `finally`. A staged import that receives no `appendImportedRuns()` call for `stagedImportIdleTimeoutMs` expires and is discarded the same way; its handle then reports `FlexHarnessNotFoundError`.
+- **Child sessions.** `parent: { sessionId, runId, toolCallId, agent }` imports a child session, such as a subagent's conversation. The parent must be a committed imported session in the same scope. Its assistant message of `runId` must hold the tool call `toolCallId` whose `childSessionId` names the child. No other session may claim that tool call. The child gets `depth` one below its parent, at most `FLEX_SESSION_IMPORT_MAX_DEPTH` (8). Deleting the parent deletes its children.
+
+**Read-only.** An imported session never runs, and nothing writes model context for it: it has no Agent events and no tool jobs. Every operation that would change its history or model context throws `FlexHarnessImportedSessionError` (code `FLEX_SESSION_READ_ONLY`):
+
+- `prompt`, `startPrompt`, `enqueuePrompt` and `schedulePrompt`;
+- `executeSlashCommand` and `compactSession`;
+- `undoSession` and `redoSession`;
+- `pushRuntimeEvent`, `reconcileToolExecution` and `archiveSessionEvents`;
+- the project-management writes: tasks, goal and scratchpad.
+
+`listSlashCommands()` reports every command unavailable with the reason `Session is an imported conversation and is read-only.` Reads work: sessions, messages, message pages, reversion info and project state. So do `updateSession()` (title and archived flag), `deleteSession()` and `deleteSessionGenerationCohort()`. A load never repairs an imported session's runs from Agent generation outcomes, because it has none.
+
+**Bounds.** `sessionImportLimits` sets the bounds; each must be an integer from 1 through its maximum:
+
+| Limit | Default | Maximum |
+|---|---|---|
+| `maxOpenImports` (staged imports at once, per harness) | 2 | 64 |
+| `maxMessagesPerSession` | 2048 | 20000 |
+| `maxSessionBytes` (JSON bytes of all messages) | 64 MiB | 256 MiB |
+| `maxPageBytes` (JSON bytes of one `appendImportedRuns()` page) | 1 MiB | 1.5 MiB |
+| `stagedImportIdleTimeoutMs` (idle time before a staged import expires) | 5 minutes | 1 hour |
+
+Some bounds are fixed:
+
+- one message is at most `FLEX_SESSION_IMPORT_MAX_MESSAGE_BYTES` (480 KiB), and must read back through the message transfer limits;
+- `origin.details` is a JSON object of at most `FLEX_SESSION_IMPORT_MAX_DETAILS_BYTES` (16 KiB);
+- `origin.source` is at most 128 UTF-8 bytes, `origin.sourceId` 512 and `origin.digest` 256, none with control characters;
+- `origin.part` has a `count` from 1 through 1024 and a zero-based `index` below it.
+
+Staged runs are held in memory until the commit, so the memory of open imports is bounded by `maxOpenImports` × `maxSessionBytes`. Retiring the scope, disposing the harness or the idle expiry discards staged imports. The expiry timer does not keep the process alive.
+
+**Stores.** The import adds no store method. Scope snapshots carry the optional session `origin`, and a store that validates session keys exactly must accept it. The commit writes the whole projection in one save at revision 1. FlexHarness versions before 9.5.0 reject the new key under their strict reader, so a downgrade over imported sessions is unsupported.
+
 ## Permissions
 
 Tools request permission through the run-scoped provider context:
@@ -851,6 +934,28 @@ Transactional tool calls persist an execution intent before the tool side effect
 
 `executionContextProvider` can construct a AgentSession execution context for each session. FlexHarness supplies the resolved scope, storage key, and the session's private job store. The public background APIs expose only execution ID, type, state, exit code, and timestamps; command payloads, stdout, and stderr remain private. The provider's optional `close()` is owned by session deletion, scope retirement, and harness disposal.
 
+### Context Compaction Model
+
+A `contextCompactor` states which model to compact with from the model the compacted work was dispatched on, never from a host default that may name another account:
+
+| `reason` | Compaction | Model members |
+| --- | --- | --- |
+| `context-overflow` | A run's context overflowed, including a delegated run's | `resolvedModel`: the `IFlexResolvedModel` the model resolver returned for that run, frozen; a delegated run's overflow carries the delegated run's own model |
+| `manual` | `/compact` or `compactSession()` | `modelHint`: the `modelHint` of the `/compact` execution options or of `compactSession(scopeId, sessionId, { modelHint })`, when one was passed |
+| `retention` | Event retention | none |
+
+A compactor uses `resolvedModel.model` directly, and resolves `modelHint` the way its model resolver resolves a prompt's `modelHint`. Only when neither member is present, because nothing dispatched states a model, does the host choose the compaction model itself.
+
+```typescript
+agentSessionPolicy: {
+  contextCompactor: async (messages, _events, options) => {
+    const model = options.resolvedModel?.model
+      ?? await resolveHostModel(options.scopeId, options.modelHint);
+    return compactMessages(model, messages, options);
+  },
+},
+```
+
 ## Events
 
 ```typescript

package/ts/utils.json.ts

@@ -494,10 +494,12 @@ function validateSession(value: unknown, path: string): IValidatedSessionIdentit
       'parentToolCallId',
       'agent',
       'depth',
+      'origin',
     ],
     path,
   );
   requireString(session.scopeId, `${path}.scopeId`);
+  if (session.origin !== undefined) validateSessionOrigin(session.origin, `${path}.origin`);
   const sessionId = requireString(session.sessionId, `${path}.sessionId`);
   const generation = validateOptionalSessionGeneration(session, path);
   requireOptionalString(session.title, `${path}.title`);
@@ -555,6 +557,41 @@ function validateSession(value: unknown, path: string): IValidatedSessionIdentit
   };
 }
 
+function validateSessionOrigin(value: unknown, path: string): void {
+  const origin = requireRecord(value, path);
+  requireOnlyKeys(
+    origin,
+    ['kind', 'source', 'sourceId', 'digest', 'importedAt', 'part', 'details'],
+    path,
+  );
+  if (origin.kind !== 'import') {
+    throw new FlexHarnessStoreFormatError(`${path}.kind is invalid.`);
+  }
+  requireString(origin.source, `${path}.source`);
+  requireString(origin.sourceId, `${path}.sourceId`);
+  requireString(origin.digest, `${path}.digest`);
+  requireString(origin.importedAt, `${path}.importedAt`);
+  if (origin.part !== undefined) {
+    const part = requireRecord(origin.part, `${path}.part`);
+    requireOnlyKeys(part, ['index', 'count'], `${path}.part`);
+    requireNonNegativeInteger(part.index, `${path}.part.index`);
+    requireNonNegativeInteger(part.count, `${path}.part.count`);
+    if (Number(part.index) >= Number(part.count)) {
+      throw new FlexHarnessStoreFormatError(`${path}.part.index must be below part.count.`);
+    }
+  }
+  if (origin.details !== undefined) requireRecord(origin.details, `${path}.details`);
+}
+
+/**
+ * Asserts the exact stored shape of one public message: its keys, part kinds and field types.
+ * Throws `FlexHarnessStoreFormatError`.
+ */
+export function assertFlexMessageRecord(value: unknown, path: string): void {
+  assertJsonSerializable(value, path);
+  validateMessage(value, path);
+}
+
 function validateSubagentProvenance(
   value: unknown,
   path: string,