@modelprofile.com/flexharness 1.0.0

package/dist_ts/utils.prompt.js

@@ -0,0 +1,170 @@
+import { FlexHarnessValidationError } from './errors.js';
+import { cloneSerializable } from './utils.json.js';
+import { assertJsonSerializable } from './utils.json.js';
+function isPlainObject(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        return false;
+    }
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+function requireNonEmptyString(value, path) {
+    if (typeof value !== 'string' || value.length === 0) {
+        throw new FlexHarnessValidationError(`${path} must be a non-empty string.`);
+    }
+    return value;
+}
+function validateOptionalString(value, path) {
+    if (value === undefined) {
+        return undefined;
+    }
+    return requireNonEmptyString(value, path);
+}
+function toAgentData(data) {
+    try {
+        const url = new URL(data);
+        if (url.protocol === 'http:' || url.protocol === 'https:') {
+            return url;
+        }
+    }
+    catch {
+        // Plain base64 and data URLs stay strings at the SmartAgent boundary.
+    }
+    return data;
+}
+function validatePart(value, index) {
+    const path = `prompt[${index}]`;
+    if (!isPlainObject(value)) {
+        throw new FlexHarnessValidationError(`${path} must be a plain object.`);
+    }
+    if (value.type === 'text') {
+        rejectUnknownKeys(value, ['type', 'text'], path);
+        return {
+            type: 'text',
+            text: requireNonEmptyString(value.text, `${path}.text`),
+        };
+    }
+    if (value.type === 'image') {
+        rejectUnknownKeys(value, ['type', 'data', 'mediaType', 'name'], path);
+        const part = {
+            type: 'image',
+            data: requireNonEmptyString(value.data, `${path}.data`),
+        };
+        const mediaType = validateOptionalString(value.mediaType, `${path}.mediaType`);
+        const name = validateOptionalString(value.name, `${path}.name`);
+        if (mediaType)
+            part.mediaType = mediaType;
+        if (name)
+            part.name = name;
+        return part;
+    }
+    if (value.type === 'file') {
+        rejectUnknownKeys(value, ['type', 'data', 'mediaType', 'name'], path);
+        const part = {
+            type: 'file',
+            data: requireNonEmptyString(value.data, `${path}.data`),
+            mediaType: requireNonEmptyString(value.mediaType, `${path}.mediaType`),
+        };
+        const name = validateOptionalString(value.name, `${path}.name`);
+        if (name)
+            part.name = name;
+        return part;
+    }
+    throw new FlexHarnessValidationError(`${path}.type must be text, image, or file.`);
+}
+function rejectUnknownKeys(value, allowedKeys, path) {
+    const unknownKey = Object.keys(value).find((key) => !allowedKeys.includes(key));
+    if (unknownKey) {
+        throw new FlexHarnessValidationError(`${path}.${unknownKey} is not a supported prompt field.`);
+    }
+}
+function toAgentParts(parts) {
+    return parts.map((part) => {
+        if (part.type === 'text') {
+            return { type: 'text', text: part.text };
+        }
+        if (part.type === 'image') {
+            return {
+                type: 'image',
+                image: toAgentData(part.data),
+                ...(part.mediaType ? { mediaType: part.mediaType } : {}),
+            };
+        }
+        return {
+            type: 'file',
+            data: toAgentData(part.data),
+            mediaType: part.mediaType,
+            ...(part.name ? { filename: part.name } : {}),
+        };
+    });
+}
+function toStoredModelParts(parts) {
+    return parts.map((part) => {
+        if (part.type === 'text') {
+            return { type: 'text', text: part.text };
+        }
+        if (part.type === 'image') {
+            return {
+                type: 'image',
+                image: part.data,
+                ...(part.mediaType ? { mediaType: part.mediaType } : {}),
+            };
+        }
+        return {
+            type: 'file',
+            data: part.data,
+            mediaType: part.mediaType,
+            ...(part.name ? { filename: part.name } : {}),
+        };
+    });
+}
+export function normalizeFlexPrompt(prompt) {
+    try {
+        assertJsonSerializable(prompt, '$prompt');
+    }
+    catch (error) {
+        throw new FlexHarnessValidationError('prompt must contain only JSON-safe values.', {
+            cause: error,
+        });
+    }
+    if (typeof prompt === 'string') {
+        if (prompt.length === 0) {
+            throw new FlexHarnessValidationError('prompt must not be empty.');
+        }
+        return {
+            agentPrompt: prompt,
+            modelMessage: { role: 'user', content: prompt },
+            parts: [{ type: 'text', text: prompt }],
+        };
+    }
+    if (!Array.isArray(prompt) || prompt.length === 0) {
+        throw new FlexHarnessValidationError('prompt must be a string or a non-empty array of parts.');
+    }
+    const parts = prompt.map(validatePart);
+    return {
+        agentPrompt: toAgentParts(parts),
+        modelMessage: {
+            role: 'user',
+            content: toStoredModelParts(parts),
+        },
+        parts: cloneSerializable(parts),
+    };
+}
+export function hydrateAgentMessages(messages) {
+    const hydrated = cloneSerializable(messages);
+    for (const message of hydrated) {
+        if (!Array.isArray(message.content)) {
+            continue;
+        }
+        for (const part of message.content) {
+            if (message.role === 'user' && part.type === 'image' && typeof part.image === 'string') {
+                part.image = toAgentData(part.image);
+            }
+            else if (part.type === 'file' && typeof part.data === 'string') {
+                part.data = toAgentData(part.data);
+            }
+        }
+    }
+    return hydrated;
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoidXRpbHMucHJvbXB0LmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vdHMvdXRpbHMucHJvbXB0LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLE9BQU8sRUFBRSwwQkFBMEIsRUFBRSxNQUFNLGFBQWEsQ0FBQztBQVN6RCxPQUFPLEVBQUUsaUJBQWlCLEVBQUUsTUFBTSxpQkFBaUIsQ0FBQztBQUNwRCxPQUFPLEVBQUUsc0JBQXNCLEVBQUUsTUFBTSxpQkFBaUIsQ0FBQztBQVF6RCxTQUFTLGFBQWEsQ0FBQyxLQUFjO0lBQ25DLElBQUksQ0FBQyxLQUFLLElBQUksT0FBTyxLQUFLLEtBQUssUUFBUSxJQUFJLEtBQUssQ0FBQyxPQUFPLENBQUMsS0FBSyxDQUFDLEVBQUUsQ0FBQztRQUNoRSxPQUFPLEtBQUssQ0FBQztJQUNmLENBQUM7SUFDRCxNQUFNLFNBQVMsR0FBRyxNQUFNLENBQUMsY0FBYyxDQUFDLEtBQUssQ0FBQyxDQUFDO0lBQy9DLE9BQU8sU0FBUyxLQUFLLE1BQU0sQ0FBQyxTQUFTLElBQUksU0FBUyxLQUFLLElBQUksQ0FBQztBQUM5RCxDQUFDO0FBRUQsU0FBUyxxQkFBcUIsQ0FBQyxLQUFjLEVBQUUsSUFBWTtJQUN6RCxJQUFJLE9BQU8sS0FBSyxLQUFLLFFBQVEsSUFBSSxLQUFLLENBQUMsTUFBTSxLQUFLLENBQUMsRUFBRSxDQUFDO1FBQ3BELE1BQU0sSUFBSSwwQkFBMEIsQ0FBQyxHQUFHLElBQUksOEJBQThCLENBQUMsQ0FBQztJQUM5RSxDQUFDO0lBQ0QsT0FBTyxLQUFLLENBQUM7QUFDZixDQUFDO0FBRUQsU0FBUyxzQkFBc0IsQ0FBQyxLQUFjLEVBQUUsSUFBWTtJQUMxRCxJQUFJLEtBQUssS0FBSyxTQUFTLEVBQUUsQ0FBQztRQUN4QixPQUFPLFNBQVMsQ0FBQztJQUNuQixDQUFDO0lBQ0QsT0FBTyxxQkFBcUIsQ0FBQyxLQUFLLEVBQUUsSUFBSSxDQUFDLENBQUM7QUFDNUMsQ0FBQztBQUVELFNBQVMsV0FB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

package/license.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Task Venture Capital GmbH
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@modelprofile.com/flexharness",
+  "version": "1.0.0",
+  "private": false,
+  "description": "Provider-neutral model-session runtime with durable history, permissions, typed events, and pluggable local or remote tool execution.",
+  "main": "dist_ts/index.js",
+  "typings": "dist_ts/index.d.ts",
+  "type": "module",
+  "author": "Task Venture Capital GmbH",
+  "license": "MIT",
+  "engines": {
+    "node": ">=24"
+  },
+  "dependencies": {
+    "@push.rocks/smartagent": "^4.0.0"
+  },
+  "devDependencies": {
+    "@git.zone/tsbuild": "4.4.2",
+    "@git.zone/tsrun": "2.0.6",
+    "@git.zone/tstest": "4.0.0",
+    "@types/json-schema": "7.0.15",
+    "@types/node": "26.1.2"
+  },
+  "files": [
+    "ts/**/*",
+    "dist_ts/**/*",
+    ".smartconfig.json",
+    "readme.md",
+    "license.md"
+  ],
+  "scripts": {
+    "build": "tsbuild tsfolders",
+    "test": "pnpm run build && tstest test/ --verbose --logfile",
+    "check:test": "tsbuild check 'test/**/*'"
+  }
+}

package/readme.hints.md

@@ -0,0 +1,29 @@
+# readme.hints.md
+
+Implementation findings for flexharness.
+
+## SmartAgent boundary
+
+- SmartAgent is the only external runtime dependency. FlexHarness imports only `@push.rocks/smartagent`; its model, prompt, message, provider-option, tool-set, runner-option, and runner-result aliases are derived from SmartAgent's exported `IAgentRunOptions` and `IAgentRunResult`.
+- Public prompts remain JSON-safe. URL strings are converted to `URL` instances only at the private SmartAgent invocation boundary.
+- Prompt attachment payloads exist only in the private SmartAgent prompt and, for successful turns, persisted model history. Public messages, prompt results, store audit messages, and events project them to `attachmentType`, source kind, optional media/name, and decoded size when determinable.
+- Resolver calls start in promise continuations so synchronous throws are observed. The first failure aborts the shared internal signal without awaiting an ignoring sibling; detached tool-provider settlement is observed and late handles are closed.
+
+## Persistence boundary
+
+- Snapshot schema version 1 uses optimistic revisions. Harness mutations are serialized per resolved storage key, while the JSON store adds a process-wide per-file queue shared by all instances.
+- Every queued mutation snapshots `revision` and persistent sessions first. Mutation, schema, save, and CAS failures restore that snapshot without replacing `activeRuns`, pending permission objects, or the save queue. Code that crosses the save `await` must re-fetch session records because restoration intentionally recreates them.
+- `JsonFileFlexHarnessStore` is intentionally not cross-process safe. It provides atomic rename and in-process CAS, not an operating-system lock.
+- Active persisted session states are normalized to idle when loaded. Incomplete messages and tool parts are marked cancelled in memory so a restarted process never presents them as still running.
+- Session update/delete checks runtime runs and pending permissions inside the queued mutation. Deletion removes the entire stored session record, including private history and remembered grants.
+- Tool close settles before success/history is decided. Final persistence is still attempted after original or close failure. A final save failure rolls back the store mutation, then terminalizes only the current in-memory audit before emitting terminal events once.
+- Disposal waits finalizers and every loaded state save tail before clearing listeners, session histories, and the state-load cache.
+- Terminal persistence is the cancellation linearization point. Abort returns false once a run starts committing, while the active-run entry continues to block new prompts until the commit settles.
+- Permission callbacks wait for the current save tail and then revalidate their run before reading remembered grants, so neither uncommitted grants nor captured callbacks can authorize later work.
+- Detached tool-provider settlement remains tracked after prompt finalization. Disposal awaits late handle closure and reports cleanup failure.
+
+## Tool output boundary
+
+- Every tool `execute` result and every async-iterable yield is converted to bounded JSON before SmartAgent observes it. Thrown errors and iterator failures are not converted or swallowed.
+- JSON byte limits are propagated through traversal. Large strings never enter normalized output, and array/object traversal stops once the remaining allowance is reserved for deterministic truncation metadata.
+- Model callbacks use bounded synchronous run-local parts. Adjacent text/reasoning deltas coalesce; no per-delta snapshot is written. Callback event, byte, or part overflow aborts internally and is classified as failure, not owner cancellation.

package/readme.md

@@ -0,0 +1,285 @@
+# @modelprofile.com/flexharness
+
+Provider-neutral model-session runtime with durable history, permissions, typed events, and pluggable local or remote tool execution.
+
+## Issue Reporting and Security
+
+For reporting bugs, issues, or security vulnerabilities, please visit [community.foss.global/](https://community.foss.global/). This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a [code.foss.global/](https://code.foss.global/) account to submit Pull Requests directly.
+
+## Install
+
+```bash
+pnpm add @modelprofile.com/flexharness
+```
+
+Node.js 24 or newer is required.
+
+## Overview
+
+FlexHarness owns session state, audit messages, successful model context, permission decisions, event delivery, cancellation, and persistence. Model selection and tool execution remain application-defined extension points. The package depends on SmartAgent but does not expose AI SDK or SmartAI imports as part of its API.
+
+## Core Setup
+
+```typescript
+import {
+  FlexHarness,
+  JsonFileFlexHarnessStore,
+  type IFlexResolvedModel,
+  type TFlexAgentToolSet,
+} from '@modelprofile.com/flexharness';
+
+interface IProjectScope {
+  projectRoot: string;
+}
+
+const harness = new FlexHarness<IProjectScope>({
+  scopeResolver: {
+    async resolveScope(scopeId) {
+      const project = await projectRegistry.get(scopeId);
+      return {
+        // Aliases that resolve to this same key share sessions and save ordering.
+        storageKey: project.accountAndProjectKey,
+        scope: { projectRoot: project.root },
+      };
+    },
+  },
+  modelResolver: {
+    async resolveModel({ scope, modelHint, signal }): Promise<IFlexResolvedModel> {
+      const configured = await modelRegistry.resolve({ scope, modelHint, signal });
+      return {
+        model: configured.model,
+        identity: {
+          provider: configured.providerId,
+          model: configured.modelId,
+          displayName: configured.label,
+        },
+        providerOptions: configured.providerOptions,
+      };
+    },
+  },
+  toolProvider: {
+    async provideTools(context) {
+      const tools: TFlexAgentToolSet = await createProjectTools({
+        root: context.scope.projectRoot,
+        signal: context.signal,
+        requestPermission: context.requestPermission,
+      });
+      return {
+        tools,
+        close: async () => closeProjectTools(tools),
+      };
+    },
+  },
+  store: new JsonFileFlexHarnessStore({
+    directory: '/var/lib/my-app/model-sessions',
+  }),
+  toolOutputLimits: {
+    maxDepth: 12,
+    maxBytes: 256 * 1024,
+  },
+  callbackLimits: {
+    maxEvents: 10_000,
+    maxOutputBytes: 1024 * 1024,
+    maxParts: 2_000,
+  },
+});
+```
+
+`modelRegistry`, `projectRegistry`, `createProjectTools`, and `closeProjectTools` in this example are application-owned integrations. FlexHarness passes the same run `AbortSignal` to the model resolver and tool provider.
+
+## Sessions And Prompts
+
+```typescript
+const session = await harness.createSession('project:billing', {
+  title: 'Invoice import',
+});
+
+const result = await harness.prompt(
+  'project:billing',
+  session.sessionId,
+  [
+    { type: 'text', text: 'Extract the invoice totals.' },
+    {
+      type: 'file',
+      data: invoicePdfBase64,
+      mediaType: 'application/pdf',
+      name: 'invoice.pdf',
+    },
+  ],
+  { modelHint: 'document-model', maxSteps: 12 },
+);
+
+console.log(result.assistantMessage.parts);
+console.log(result.usage);
+```
+
+`TFlexPrompt` is deliberately JSON-safe. It accepts a string or an ordered array of:
+
+- `{ type: 'text', text }`
+- `{ type: 'image', data, mediaType?, name? }`
+- `{ type: 'file', data, mediaType, name? }`
+
+Attachment `data` is a string containing base64, a data URL, or a remote URL. Public input never requires `Buffer` or `URL` objects. Remote URL strings are converted only at the private SmartAgent invocation boundary.
+
+Attachment payloads are never copied into public audit messages or events. Public attachment parts contain metadata only:
+
+```typescript
+{
+  type: 'attachment',
+  partId: '...',
+  attachmentType: 'file',
+  source: 'inline-base64', // or data-url / remote-url
+  sizeBytes: 48231,        // omitted when it cannot be determined
+  mediaType: 'application/pdf',
+  name: 'invoice.pdf',
+}
+```
+
+When the turn succeeds, the original string remains only in private persisted model history so a later model turn can receive the attachment again. Failed, cancelled, resolver-failed, cleanup-failed, and persistence-failed turns do not add it to future context.
+
+The main session methods are:
+
+```typescript
+await harness.listSessions(scopeId);
+await harness.createSession(scopeId, { sessionId, title });
+await harness.getSession(scopeId, sessionId);
+await harness.getMessages(scopeId, sessionId);
+await harness.updateSession(scopeId, sessionId, { title: 'Renamed', archived: true });
+await harness.updateSession(scopeId, sessionId, { title: null, archived: false });
+await harness.deleteSession(scopeId, sessionId);
+await harness.prompt(scopeId, sessionId, prompt, options);
+await harness.abort(scopeId, sessionId, 'Cancelled by the user');
+await harness.listPendingPermissions(scopeId, sessionId);
+await harness.respondToPermission(scopeId, sessionId, permissionId, 'once');
+await harness.dispose();
+```
+
+Only one run may be active in a session. Different sessions can run concurrently. The run ID and audit messages are reserved and persisted before asynchronous model or tool resolution begins.
+
+`updateSession()` supports title replacement, explicit title clearing with `null`, and archive state through `archived`. Archived sessions expose `archivedAt`. Update and deletion are rejected while the session has an active run or pending permission. Deletion removes the complete persisted session, including messages, private model history, and remembered permission grants.
+
+`abort()` returns `true` only while cancellation is still accepted. Terminal persistence is the run's commit point; once it starts, `abort()` returns `false` and the already-fixed terminal outcome completes while the session remains busy.
+
+## History And Audit Behavior
+
+Successful model context is accumulated as:
+
+1. Previous successful model history.
+2. The normalized current user message.
+3. SmartAgent's result messages.
+
+A failed or cancelled prompt remains visible through `getMessages()`, with `failed` or `cancelled` status, but is not included in future model context. Model history is held only in the store snapshot and is not exposed by the session or message APIs.
+
+Public audit history is safe to send to controllers: attachment parts contain source and size metadata, never inline base64, data URLs, or remote URL payloads. Private model history retains those values solely for subsequent model turns.
+
+Sessions expose `idle`, `running`, `waiting_permission`, `failed`, and `cancelled` status. Persisted `running` and `waiting_permission` states normalize to `idle` after process restart; incomplete messages and parts normalize to `cancelled`.
+
+## Permissions
+
+Tools request permission through the run-scoped provider context:
+
+```typescript
+await context.requestPermission({
+  kind: 'filesystem.write',
+  description: 'Write generated files into the project',
+  toolCallId,
+  rememberKey: 'filesystem.write:project-output',
+  metadata: { target: 'generated/' },
+});
+```
+
+Pending requests are runtime-only and queryable with `listPendingPermissions()`. A controller answers with:
+
+- `once`: allow this request.
+- `always`: allow and remember the request's `rememberKey` for this session.
+- `reject`: reject the tool execution.
+
+`always` is invalid when the request has no `rememberKey`. Remembered decisions are persisted before the waiting tool resolves. If persistence fails, the key is rolled back and the request remains pending so the response can be retried. Concurrent response attempts are serialized and exactly one successful response settles a request.
+
+## Tool Output Safety
+
+FlexHarness wraps every provided tool `execute` method before SmartAgent receives it. Direct outputs and every `AsyncIterable` yield are converted into bounded JSON-safe values. Circular references, functions, symbols, bigint values, dates, URLs, and binary values receive deterministic descriptions or records. Thrown errors and iterator failures remain errors.
+
+`toolOutputLimits` in the complete setup above bounds traversal depth and encoded bytes. The normalizer enforces its byte allowance incrementally: oversized strings are replaced before entering output, and arrays/objects stop reading entries once only truncation metadata fits.
+
+Streaming callbacks use run-local synchronous state rather than one persistence promise per delta. Adjacent text and reasoning deltas coalesce. `callbackLimits` bounds callback events, accumulated output bytes, and part count; overflow aborts internally with `FlexHarnessCallbackOverflowError` and the turn is recorded as failed. Reservation and terminal finalization are the normal persistence checkpoints, with permission state changes as explicit additional checkpoints.
+
+`normalizeJsonValue()` is also exported for integrations that need the same conversion independently.
+
+## Events
+
+```typescript
+const unsubscribe = harness.subscribe((event) => {
+  switch (event.type) {
+    case 'part.delta':
+      renderDelta(event.sessionId, event.messageId, event.partId, event.delta);
+      break;
+    case 'permission.requested':
+      showPermission(event.request);
+      break;
+    case 'session.updated':
+      renderSession(event.session);
+      break;
+    case 'session.deleted':
+      removeSession(event.sessionId);
+      break;
+    case 'run.finished':
+      markRunFinished(event.runId, event.status);
+      break;
+  }
+});
+
+unsubscribe();
+```
+
+Events are discriminated, sequenced, deeply immutable snapshots. Listener exceptions are isolated from runs and other listeners. Events contain public IDs and snapshots only; they do not expose the resolved scope object, storage key, model object, or provider options.
+
+## Stores
+
+`InMemoryFlexHarnessStore` provides revision-based compare-and-swap behavior for tests and ephemeral processes.
+
+`JsonFileFlexHarnessStore` stores one `sha256(storageKey).json` file per resolved key. It provides:
+
+- Snapshot schema version 1 and optimistic revisions.
+- Static process-wide queues shared by all store instances for the same absolute file.
+- Revision re-reads inside the queue before every save.
+- Atomic temporary-file write and rename.
+- Directory mode `0700` and file mode `0600`, including existing paths.
+- Stale temporary-file cleanup and strict snapshot validation.
+
+The JSON file store is explicitly not cross-process safe. Use a custom `IFlexHarnessStore` backed by a database or another cross-process CAS mechanism when several processes write the same storage key.
+
+Store conflicts are surfaced as `FlexHarnessStoreConflictError`; malformed, wrong-schema, or non-JSON snapshots are surfaced as `FlexHarnessStoreFormatError`. FlexHarness does not merge conflicts.
+
+Every harness mutation snapshots the persistent session state inside its per-storage queue. If the mutation itself or `store.save()` fails, the in-memory revision and sessions are restored before the queue settles. Runtime run controllers, pending permission objects, and queue identity are preserved. CAS conflicts therefore expose neither an uncommitted create/update/delete nor an automatic merge.
+
+## Shutdown
+
+Model and tool resolution share the run signal. Synchronous throws are observed as resolver failures; the first failure aborts that signal and finalizes immediately without waiting for an unresponsive sibling. A detached tool provider that resolves later is observed and its handle is closed; disposal waits for that settlement and reports a late close failure.
+
+Tool-handle close settles before a turn can be successful. Final persistence is attempted even when model execution or close fails. Cleanup failure prevents history append. If final persistence also fails, the stored reserved snapshot remains unchanged while the current in-memory audit is terminalized and terminal events are emitted exactly once.
+
+`dispose()` is asynchronous and idempotent. It marks the harness closed, prevents operations waiting on persistence from reserving a run, aborts cancellable active runs, rejects pending permissions, waits for committing runs, all run finalizers, and state save tails, then clears listeners and loaded state caches. Multiple run or cleanup failures are reported through `FlexHarnessRunError`.
+
+Cancellation is cooperative: model resolvers, tool providers, runners, tools, and cleanup functions must observe the supplied `AbortSignal` and settle their work. `dispose()` deliberately waits for owned work instead of abandoning resources. A process host that needs a hard shutdown deadline must enforce that deadline outside FlexHarness and terminate only the process it owns.
+
+## License and Legal Information
+
+This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the repository license file.
+
+**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.
+
+### Trademarks
+
+This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.
+
+Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.
+
+### Company Information
+
+Task Venture Capital GmbH<br>
+Registered at District Court Bremen HRB 35230 HB, Germany
+
+For any legal inquiries or further information, please contact us via email at hello@task.vc.
+
+By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.

package/ts/00_commitinfo_data.ts

@@ -0,0 +1,8 @@
+/**
+ * autocreated commitinfo by @push.rocks/commitinfo
+ */
+export const commitinfo = {
+  name: '@modelprofile.com/flexharness',
+  version: '1.0.0',
+  description: 'Provider-neutral model-session runtime with durable history, permissions, typed events, and pluggable local or remote tool execution.'
+}