@modelprofile.com/flexharness 9.4.0 → 9.5.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.5.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.5.0",
+    "@modelprofile.com/flexharness-models": "9.5.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',
@@ -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:

package/ts/00_commitinfo_data.ts

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