@modelprofile.com/flexharness 9.4.0 → 9.6.0

package/dist_ts/utils.sessionimport.js

@@ -0,0 +1,241 @@
+import { FlexHarnessValidationError } from './errors.js';
+import { FLEX_PROJECT_MANAGEMENT_LIMITS, FLEX_SESSION_IMPORT_DEFAULT_LIMITS, FLEX_SESSION_IMPORT_MAXIMUM_LIMITS, FLEX_SESSION_IMPORT_MAX_DETAILS_BYTES, FLEX_SESSION_IMPORT_MAX_MESSAGE_BYTES, } from './interfaces.js';
+import { maxSubagentNameBytes } from './utils.harnessoptions.js';
+import { assertFlexMessageRecord, assertJsonSerializable, cloneSerializable } from './utils.json.js';
+import { createBoundedTransferMessage, jsonBytes, maxTransferIdentifierBytes, requireTransferIdentifier, } from './utils.transfer.js';
+import { validateIdentifier, validateUtf8String } from './utils.validation.js';
+const maxSourceBytes = 128;
+const maxDigestBytes = 256;
+const maxImportParts = 1024;
+const controlCharacterPattern = /[\u0000-\u001f\u007f]/u;
+export function resolveSessionImportLimits(limits = {}) {
+    const resolved = {
+        maxOpenImports: limits.maxOpenImports ?? FLEX_SESSION_IMPORT_DEFAULT_LIMITS.maxOpenImports,
+        maxMessagesPerSession: limits.maxMessagesPerSession
+            ?? FLEX_SESSION_IMPORT_DEFAULT_LIMITS.maxMessagesPerSession,
+        maxSessionBytes: limits.maxSessionBytes ?? FLEX_SESSION_IMPORT_DEFAULT_LIMITS.maxSessionBytes,
+        maxPageBytes: limits.maxPageBytes ?? FLEX_SESSION_IMPORT_DEFAULT_LIMITS.maxPageBytes,
+        stagedImportIdleTimeoutMs: limits.stagedImportIdleTimeoutMs
+            ?? FLEX_SESSION_IMPORT_DEFAULT_LIMITS.stagedImportIdleTimeoutMs,
+    };
+    for (const [name, value] of Object.entries(resolved)) {
+        const maximum = FLEX_SESSION_IMPORT_MAXIMUM_LIMITS[name];
+        if (!Number.isSafeInteger(value) || value < 1 || value > maximum) {
+            throw new FlexHarnessValidationError(`sessionImportLimits.${name} must be an integer from 1 through ${maximum}.`);
+        }
+    }
+    return resolved;
+}
+function requirePlainRecord(value, name) {
+    if (!value
+        || typeof value !== 'object'
+        || Array.isArray(value)
+        || ![Object.prototype, null].includes(Object.getPrototypeOf(value))) {
+        throw new FlexHarnessValidationError(`${name} must be a plain object.`);
+    }
+    return value;
+}
+function requireKnownKeys(record, allowedKeys, name) {
+    const unsupported = Reflect.ownKeys(record).find((key) => typeof key !== 'string' || !allowedKeys.includes(key));
+    if (unsupported !== undefined) {
+        throw new FlexHarnessValidationError(`${name} does not support "${String(unsupported)}".`);
+    }
+}
+function requireBoundedText(value, name, maxBytes) {
+    validateUtf8String(value, name, maxBytes, true);
+    if (controlCharacterPattern.test(value)) {
+        throw new FlexHarnessValidationError(`${name} must not contain control characters.`);
+    }
+    return value;
+}
+/** A timestamp exactly as `Date.prototype.toISOString()` renders it. */
+export function requireCanonicalTimestamp(value, name) {
+    if (typeof value !== 'string' || value.length > 64) {
+        throw new FlexHarnessValidationError(`${name} must be an ISO 8601 timestamp.`);
+    }
+    const time = Date.parse(value);
+    if (!Number.isFinite(time) || new Date(time).toISOString() !== value) {
+        throw new FlexHarnessValidationError(`${name} must be an ISO 8601 timestamp as Date.prototype.toISOString() renders it.`);
+    }
+    return value;
+}
+function normalizeImportPart(value) {
+    const part = requirePlainRecord(value, 'origin.part');
+    requireKnownKeys(part, ['index', 'count'], 'origin.part');
+    const { index, count } = part;
+    if (!Number.isSafeInteger(count)
+        || Number(count) < 1
+        || Number(count) > maxImportParts
+        || !Number.isSafeInteger(index)
+        || Number(index) < 0
+        || Number(index) >= Number(count)) {
+        throw new FlexHarnessValidationError(`origin.part must have a count from 1 through ${maxImportParts} and a zero-based index below it.`);
+    }
+    return { index: index, count: count };
+}
+function normalizeImportDetails(value) {
+    requirePlainRecord(value, 'origin.details');
+    try {
+        assertJsonSerializable(value, 'origin.details');
+    }
+    catch (error) {
+        throw new FlexHarnessValidationError('origin.details must be a JSON object.', { cause: error });
+    }
+    if (jsonBytes(value) > FLEX_SESSION_IMPORT_MAX_DETAILS_BYTES) {
+        throw new FlexHarnessValidationError(`origin.details must be at most ${FLEX_SESSION_IMPORT_MAX_DETAILS_BYTES} JSON bytes.`);
+    }
+    return cloneSerializable(value);
+}
+function normalizeImportSource(value) {
+    const origin = requirePlainRecord(value, 'origin');
+    requireKnownKeys(origin, ['source', 'sourceId', 'digest', 'part', 'details'], 'origin');
+    return {
+        source: requireBoundedText(origin.source, 'origin.source', maxSourceBytes),
+        sourceId: requireBoundedText(origin.sourceId, 'origin.sourceId', maxTransferIdentifierBytes),
+        digest: requireBoundedText(origin.digest, 'origin.digest', maxDigestBytes),
+        ...(origin.part === undefined ? {} : { part: normalizeImportPart(origin.part) }),
+        ...(origin.details === undefined ? {} : { details: normalizeImportDetails(origin.details) }),
+    };
+}
+function normalizeImportParent(value) {
+    const parent = requirePlainRecord(value, 'parent');
+    requireKnownKeys(parent, ['sessionId', 'runId', 'toolCallId', 'agent'], 'parent');
+    return {
+        sessionId: requireBoundedText(parent.sessionId, 'parent.sessionId', maxTransferIdentifierBytes),
+        runId: requireBoundedText(parent.runId, 'parent.runId', maxTransferIdentifierBytes),
+        toolCallId: requireBoundedText(parent.toolCallId, 'parent.toolCallId', maxTransferIdentifierBytes),
+        agent: requireBoundedText(parent.agent, 'parent.agent', maxSubagentNameBytes),
+    };
+}
+export function normalizeBeginSessionImportOptions(options) {
+    const record = requirePlainRecord(options, 'beginSessionImport options');
+    requireKnownKeys(record, ['sessionId', 'title', 'createdAt', 'updatedAt', 'origin', 'parent'], 'beginSessionImport options');
+    const sessionId = record.sessionId;
+    validateIdentifier(sessionId, 'sessionId');
+    requireTransferIdentifier(sessionId, 'sessionId');
+    if (record.title !== undefined) {
+        validateUtf8String(record.title, 'title', FLEX_PROJECT_MANAGEMENT_LIMITS.maxTitleBytes, true);
+    }
+    const createdAt = requireCanonicalTimestamp(record.createdAt, 'createdAt');
+    const updatedAt = record.updatedAt === undefined
+        ? createdAt
+        : requireCanonicalTimestamp(record.updatedAt, 'updatedAt');
+    if (Date.parse(updatedAt) < Date.parse(createdAt)) {
+        throw new FlexHarnessValidationError('updatedAt must not be earlier than createdAt.');
+    }
+    const parent = record.parent === undefined ? undefined : normalizeImportParent(record.parent);
+    if (parent?.sessionId === sessionId) {
+        throw new FlexHarnessValidationError('An imported session cannot be its own parent.');
+    }
+    return {
+        sessionId,
+        ...(record.title === undefined ? {} : { title: record.title }),
+        createdAt,
+        updatedAt,
+        origin: normalizeImportSource(record.origin),
+        ...(parent === undefined ? {} : { parent }),
+    };
+}
+/** The identity an import is idempotent by: its source, source id and part. */
+export function sessionImportIdentity(origin) {
+    return JSON.stringify([origin.source, origin.sourceId, origin.part?.index ?? null]);
+}
+function normalizeImportedMessage(value, path, role, sessionId) {
+    try {
+        assertFlexMessageRecord(value, path);
+    }
+    catch (error) {
+        throw new FlexHarnessValidationError(`${path} is not a valid message: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+    }
+    const message = cloneSerializable(value);
+    if (message.role !== role) {
+        throw new FlexHarnessValidationError(`${path}.role must be "${role}".`);
+    }
+    if (message.sessionId !== sessionId) {
+        throw new FlexHarnessValidationError(`${path}.sessionId must be the imported session "${sessionId}".`);
+    }
+    if (message.status === 'streaming') {
+        throw new FlexHarnessValidationError(`${path}.status must be completed, failed or cancelled.`);
+    }
+    requireCanonicalTimestamp(message.createdAt, `${path}.createdAt`);
+    if (message.completedAt !== undefined) {
+        requireCanonicalTimestamp(message.completedAt, `${path}.completedAt`);
+    }
+    for (const [index, part] of message.parts.entries()) {
+        if (part.type !== 'reasoning' && part.type !== 'tool')
+            continue;
+        if (part.status === 'running') {
+            throw new FlexHarnessValidationError(`${path}.parts[${index}] must not be running.`);
+        }
+    }
+    const bytes = jsonBytes(message);
+    if (bytes > FLEX_SESSION_IMPORT_MAX_MESSAGE_BYTES) {
+        throw new FlexHarnessValidationError(`${path} exceeds ${FLEX_SESSION_IMPORT_MAX_MESSAGE_BYTES} JSON bytes.`);
+    }
+    try {
+        createBoundedTransferMessage(message);
+    }
+    catch (error) {
+        throw new FlexHarnessValidationError(`${path} cannot be read back within the transfer limits.`, {
+            cause: error,
+        });
+    }
+    return { message, bytes };
+}
+/**
+ * Validates one page of imported runs. Every message must belong to `sessionId`, be terminal and
+ * fit the transfer limits; a run's user and assistant message share its run id and status.
+ */
+export function normalizeImportedRunPage(runs, sessionId, maxPageBytes) {
+    if (!Array.isArray(runs) || runs.length === 0) {
+        throw new FlexHarnessValidationError('Imported runs must be a non-empty array.');
+    }
+    let pageBytes;
+    try {
+        assertJsonSerializable(runs, 'runs');
+        pageBytes = jsonBytes(runs);
+    }
+    catch (error) {
+        throw new FlexHarnessValidationError('Imported runs must be JSON-safe.', { cause: error });
+    }
+    if (pageBytes > maxPageBytes) {
+        throw new FlexHarnessValidationError(`Imported runs exceed the page limit of ${maxPageBytes} JSON bytes.`);
+    }
+    const normalized = [];
+    let bytes = 0;
+    for (const [index, value] of runs.entries()) {
+        const path = `runs[${index}]`;
+        const run = requirePlainRecord(value, path);
+        requireKnownKeys(run, ['user', 'assistant'], path);
+        const user = normalizeImportedMessage(run.user, `${path}.user`, 'user', sessionId);
+        const assistant = normalizeImportedMessage(run.assistant, `${path}.assistant`, 'assistant', sessionId);
+        if (user.message.runId !== assistant.message.runId) {
+            throw new FlexHarnessValidationError(`${path} user and assistant messages must share one runId.`);
+        }
+        if (user.message.messageId === assistant.message.messageId) {
+            throw new FlexHarnessValidationError(`${path} user and assistant messages must have distinct ids.`);
+        }
+        if (user.message.status !== assistant.message.status) {
+            throw new FlexHarnessValidationError(`${path} user and assistant messages must share one status.`);
+        }
+        normalized.push({ user: user.message, assistant: assistant.message });
+        bytes += user.bytes + assistant.bytes;
+    }
+    return { runs: normalized, bytes };
+}
+/** Validates the shape of a handle `beginSessionImport()` returned. */
+export function validateSessionImportHandle(handle) {
+    const record = requirePlainRecord(handle, 'Session import handle');
+    requireKnownKeys(record, ['importId', 'scopeId', 'sessionId'], 'Session import handle');
+    for (const key of ['importId', 'scopeId', 'sessionId']) {
+        if (typeof record[key] !== 'string' || record[key] === '') {
+            throw new FlexHarnessValidationError(`Session import handle ${key} must be a non-empty string.`);
+        }
+    }
+    return {
+        importId: record.importId,
+        scopeId: record.scopeId,
+        sessionId: record.sessionId,
+    };
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoidXRpbHMuc2Vzc2lvbmltcG9ydC5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3RzL3V0aWxzLnNlc3Npb25pbXBvcnQudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsT0FBTyxFQUFFLDBCQUEwQixFQUFFLE1BQU0sYUFBYSxDQUFDO0FBQ3pELE9BQU8sRUFDTCw4QkFBOEIsRUFDOUIsa0NBQWtDLEVBQ2xDLGtDQUFrQyxFQUNsQyxxQ0FBcUMsRUFDckMscUNBQXFDLEdBQ3RDLE1BQU0saUJBQWlCLENBQUM7QUFZekIsT0FBTyxFQUFFLG9CQUFvQixFQUFFLE1BQU0sMkJBQTJCLENBQUM7QUFDakUsT0FBTyxFQUFFLHVCQUF1QixFQUFFLHNCQUFzQixFQUFFLGlCQUFpQixFQUFFLE1BQU0saUJBQWlCLENBQUM7QUFDckcsT0FBTyxFQUNMLDRCQUE0QixFQUM1QixTQUFTLEVBQ1QsMEJBQTBCLEVBQzFCLHlCQUF5QixHQUMxQixNQUFNLHFCQUFxQixDQUFDO0FBQzdCLE9BQU8sRUFBRSxrQkFBa0IsRUFBRSxrQkFBa0IsRUFBRSxNQUFNLHVCQUF1QixDQUFDO0FBRS9FLE1BQU0sY0FBYyxHQUFHLEdBQUcsQ0FBQztBQUMzQixNQUFNLGNBQWMsR0FBRyxHQUFHLENBQUM7QUFDM0IsTUFBTSxjQUFjLEdBQUcsSUFBSSxDQUFDO0FBQzVCLE1BQU0sdUJBQXVCLEdBQUcsd0JBQXdCLENBQUM7QUFnQnpELE1BQU0sVUFBVSwwQkFBMEIsQ0FDeEMsU0FBbUMsRUFBRTtJQUVyQyxNQUFNLFFBQVEsR0FBRztRQUNmLGNBQWMsRUFBRSxNQUFNLENBQUMsY0FBYyxJQUFJLGtDQUFrQyxDQUFDLGNBQWM7UUFDMUYscUJBQXFCLEVBQUUsTUFBTSxDQUFDLHFCQUFxQjtlQUM5QyxrQ0FBa0MsQ0FBQyxxQkFBcUI7UUFDN0QsZUFBZSxFQUFFLE1BQU0sQ0FBQyxlQUFlLElBQUksa0NBQWtDLENBQUMsZUFBZTtRQUM3RixZQUFZLEVBQUUsTUFBTSxDQUFD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

package/package.json

@@ -2,7 +2,7 @@
   "author": "Task Venture Capital GmbH",
   "license": "MIT",
   "name": "@modelprofile.com/flexharness",
-  "version": "9.4.0",
+  "version": "9.6.0",
   "type": "module",
   "description": "Managed agent sessions with tools, MCP, chat, OCR, documents and browser control through focused subpath imports.",
   "main": "./dist_ts/index.js",
@@ -62,8 +62,8 @@
     }
   },
   "dependencies": {
-    "@modelprofile.com/flexharness-agent": "9.4.0",
-    "@modelprofile.com/flexharness-models": "9.4.0",
+    "@modelprofile.com/flexharness-agent": "9.6.0",
+    "@modelprofile.com/flexharness-models": "9.6.0",
     "@push.rocks/smartrequest": "^5.0.1",
     "ai": "^7.0.107",
     "zod": "^4.4.1"

package/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',
@@ -601,9 +608,9 @@ Queue payloads, status records, and `prompt.*` queue events are process-local. T
 
 The reservation save is the admission point. A save failure produces no start events or active audit. If disposal begins while that save is in flight and the save commits, admission still resolves and its completion settles as cancelled; disposal waits for terminal finalization.
 
-`listMessagePage()` returns the newest contiguous page in chronological order. `limit` must be an integer from 1 through 50 and defaults to 50. `nextCursor` is opaque, limited to 4096 UTF-8 bytes, bound to the resolved storage namespace and session, and remains stable when newer messages are appended. Mismatched and stale cursors fail validation. `getMessage()` performs an exact lookup. Transfer identifiers are limited to 512 bytes, text and reasoning parts to 96 KiB, complete messages to 480 KiB, and complete page envelopes to 512 KiB. A page may therefore contain fewer messages than requested. Oversized text is truncated and an otherwise oversized parts collection is replaced with an explicit elision marker; metadata that still cannot fit fails validation. Canonical private Agent events are unchanged.
+`listMessagePage()` returns the newest contiguous page in chronological order. `limit` must be an integer from 1 through 50 and defaults to 50. `nextCursor` is opaque, limited to 4096 UTF-8 bytes, bound to the resolved storage namespace and session, and remains stable when newer messages are appended. Mismatched and stale cursors fail validation. Each page carries `startIndex`, the zero-based index of its first message in the session's visible history (for an empty page, the index the page ends at), so a consumer can order and page by absolute position. Appending messages leaves every index unchanged; a branch after an undo reuses the positions of the history it replaces, so a consumer re-reads its pages after `session.history.changed`. `getMessage()` performs an exact lookup. Transfer identifiers are limited to 512 bytes, text and reasoning parts to 96 KiB, complete messages to 480 KiB, and complete page envelopes to 512 KiB. A page may therefore contain fewer messages than requested. Oversized text is truncated and an otherwise oversized parts collection is replaced with an explicit elision marker; metadata that still cannot fit fails validation. Canonical private Agent events are unchanged.
 
-`updateSession()` supports title replacement, explicit title clearing with `null`, and archive state through `archived`. Title-only updates remain available while prompts are queued or running, while permission is pending, and after archival. Requests containing `archived` are rejected while the session has any outstanding prompt or pending permission; a mixed title-and-archive request is rejected atomically without changing the title. Archived sessions expose `archivedAt`. Deleting a session cascades through its complete descendant subtree. One durable root-keyed tombstone group hides every newly affected live session, and the delete also joins any already-separate descendant cleanup groups without rewriting their roots. FlexHarness then cancels queued and active subtree work, emits terminal queue events, waits for admitted initialization, and purges runtime queue status while cleaning runtime and persisted domains child-first. The requested root tombstone is removed last after every domain confirms cleanup; project-management cleanup confirmation is a retained durable project tombstone rather than physical removal. A successful live `deleteSession()` call emits `session.deleted` for each session it newly tombstoned; retries of an existing tombstone and automatic load, retirement, or disposal cleanup emit no deletion events. Direct deletion of a descendant cascades only through that descendant's subtree. Cleanup authority follows the resolved storage namespace, so scope aliases share the same groups. A partial failure retains durable ownership for retry by a later `deleteSession()`, namespace load, `retireScope()`, or `dispose()` call.
+`updateSession()` supports title replacement, explicit title clearing with `null`, and archive state through `archived`. Title-only updates remain available while prompts are queued or running, while permission is pending, and after archival. Requests containing `archived` are rejected while the session has any outstanding prompt or pending permission; a mixed title-and-archive request is rejected atomically without changing the title. Archived sessions expose `archivedAt`. Deleting a session cascades through its complete descendant subtree. One durable root-keyed tombstone group hides every newly affected live session, and the delete also joins any already-separate descendant cleanup groups without rewriting their roots. FlexHarness then cancels queued and active subtree work, emits terminal queue events, waits for admitted initialization, and purges runtime queue status while cleaning runtime and persisted domains child-first. The requested root tombstone is removed last after every domain confirms cleanup; project-management cleanup confirmation is a retained durable project tombstone rather than physical removal. An imported session can hold no project-management state, so its deletion writes no project tombstone. A successful live `deleteSession()` call emits `session.deleted` for each session it newly tombstoned; retries of an existing tombstone and automatic load, retirement, or disposal cleanup emit no deletion events. Direct deletion of a descendant cascades only through that descendant's subtree. Cleanup authority follows the resolved storage namespace, so scope aliases share the same groups. A partial failure retains durable ownership for retry by a later `deleteSession()`, namespace load, `retireScope()`, or `dispose()` call.
 
 `deleteSessionGenerationCohort()` is the generation-fenced destructive form for controllers. Its `root` and every `authorizedCohort` entry use the exact `{ sessionId, sessionGenerationId, sessionGenerationSequence }` shape. The cohort contains unique entries in strictly ascending `sessionId` order and is limited by `FLEX_SESSION_GENERATION_COHORT_MAX_ENTRIES` (2048). FlexHarness atomically validates the matching root, its complete live subtree, and every retained descendant tombstone group before reserving deletion. A missing or different root generation returns `{ matched: false }` without touching a newer generation; a missing or mismatched cascade entry throws before new tombstoning or cleanup. Extra valid entries do not expand the cascade. A matched partial cleanup remains retryable with the same authority and resolves to `{ matched: true }` when cleanup completes. The existing `deleteSession()` method remains available for callers that intentionally own the complete reusable-ID namespace.
 
@@ -783,7 +790,7 @@ Workspace reversion is generic and application-defined. It does not reverse netw
 
 Every configured value must be an integer from 1 through its hard maximum. Pruning removes complete prefixes rather than splitting an undo unit. Excluded run IDs prevent a committed branch from re-entering model context, while pending releases retain provider ownership until acknowledgement.
 
-`retireScope()` stops runtime ownership for the complete resolved storage namespace without deleting its durable snapshot. It does not load a namespace that has no cached or in-flight state. For loaded state, it preserves and waits for persistence that has already started, while later queued reads, writes, and run admissions reject with `FlexHarnessAbortError`. It cancels queued prompts and cancellable runs, rejects pending permissions, emits queue terminal events, waits for committing runs, terminal persistence, queue drains, tool-handle closure, and detached tool-provider cleanup, then purges queue status and clears and evicts the cached state. Failed cleanup ownership remains cached so a later `retireScope()` or `dispose()` call can retry it. Calls through storage-key aliases share the same retirement drain. A later call can load the durable namespace again after successful retirement if the application still resolves it.
+`retireScope()` stops runtime ownership for the complete resolved storage namespace without deleting its durable snapshot. It does not load a namespace that has no cached or in-flight state. For loaded state, it preserves and waits for persistence that has already started, while later queued reads, writes, and run admissions reject with `FlexHarnessAbortError`. It cancels queued prompts and cancellable runs, rejects pending permissions, emits queue terminal events, waits for committing runs, terminal persistence, queue drains, tool-handle closure, and detached tool-provider cleanup, then purges queue status and clears and evicts the cached state. Failed cleanup ownership remains cached so a later `retireScope()` or `dispose()` call can retry it. Calls through storage-key aliases share the same retirement drain. A later call can load the durable namespace again after successful retirement if the application still resolves it. A loaded namespace keeps every session's messages in memory, so `retireScope()` is also the supported way for a host to evict a scope it has stopped using, such as an opened archive of imported sessions. Retirement releases every staged session import and cancels queued prompts and runs, so a host retires only a scope with no open import and no work it still wants.
 
 Normal retirement-induced cancellation does not make `retireScope()` reject. Unexpected failures observed through run finalization or scoped cleanup are surfaced without dropping the resources that still require cleanup. One such failure is thrown directly; multiple failures are reported through `FlexHarnessRunError`. Calling retirement or disposal again retries retained cleanup ownership.
 
@@ -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. The tombstone that reserves an import, or that deletes an imported session, carries the optional `imported: true`, and a store that validates tombstone keys exactly must accept it. FlexHarness 9.5.x rejects a scope snapshot that holds such a tombstone; one exists only while an import commits or an imported session is deleted, or after either was interrupted.
+
 ## Permissions
 
 Tools request permission through the run-scoped provider context:

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@modelprofile.com/flexharness',
-  version: '9.4.0',
+  version: '9.6.0',
   description: 'The FlexHarness toolbox source repository and shared dependency catalog.'
 }