@modelprofile.com/flexharness 11.3.0 → 12.0.0

package/ts_stores_testing/fixtures.ts

@@ -0,0 +1,127 @@
+import * as plugins from './plugins.js';
+import type {
+  IFlexMessage,
+  IFlexPermissionSnapshot,
+  IFlexProjectionSnapshotCurrent,
+  IFlexReversionSegment,
+  IFlexScopeSnapshot,
+} from '../ts/interfaces.js';
+
+/** A scope snapshot with one idle session. */
+export function scopeSnapshot(revision: number, sessionId = 'session-1'): IFlexScopeSnapshot {
+  return {
+    schemaVersion: 1,
+    revision,
+    sessions: [
+      {
+        scopeId: 'scope-1',
+        sessionId,
+        createdAt: '2026-08-05T00:00:00.000Z',
+        updatedAt: '2026-08-05T00:00:00.000Z',
+        status: 'idle',
+        activity: { status: 'idle' },
+      },
+    ],
+    tombstones: [],
+  };
+}
+
+/** An empty projection. */
+export function projectionSnapshot(revision: number): IFlexProjectionSnapshotCurrent {
+  return {
+    schemaVersion: 3,
+    revision,
+    messages: [],
+    stagedTerminals: [],
+    reversionSegments: [],
+    revertCursor: 0,
+    excludedRunIds: [],
+    pendingReversionReleases: [],
+  };
+}
+
+/** The user and assistant message of one completed run of `session-1`. */
+export function runMessages(runId: string): IFlexMessage[] {
+  return [{
+    messageId: `user-${runId}`,
+    sessionId: 'session-1',
+    runId,
+    role: 'user',
+    status: 'completed',
+    createdAt: '2026-08-05T00:00:00.000Z',
+    completedAt: '2026-08-05T00:00:01.000Z',
+    parts: [{ partId: `user-part-${runId}`, type: 'text', text: runId }],
+  }, {
+    messageId: `assistant-${runId}`,
+    sessionId: 'session-1',
+    runId,
+    role: 'assistant',
+    status: 'completed',
+    createdAt: '2026-08-05T00:00:00.000Z',
+    completedAt: '2026-08-05T00:00:01.000Z',
+    parts: [{ partId: `assistant-part-${runId}`, type: 'text', text: 'answer' }],
+  }];
+}
+
+/** The reversion segment of one completed run, without a workspace capture. */
+export function runSegment(runId: string): IFlexReversionSegment {
+  return {
+    runId,
+    userMessageId: `user-${runId}`,
+    status: 'completed',
+    contextAvailable: true,
+    eventIds: [`event-${runId}`],
+    workspaceCaptured: false,
+    protocolVersion: 1,
+    provenance: 'transcript',
+  };
+}
+
+/** A projection of completed runs of `session-1`, each with its messages and reversion segment. */
+export function projectionWithRuns(revision: number, runIds: string[]): IFlexProjectionSnapshotCurrent {
+  return {
+    ...projectionSnapshot(revision),
+    messages: runIds.flatMap(runMessages),
+    reversionSegments: runIds.map(runSegment),
+    revertCursor: runIds.length,
+  };
+}
+
+/** A permission snapshot that remembers one approval. */
+export function permissionSnapshot(revision: number): IFlexPermissionSnapshot {
+  return {
+    schemaVersion: 1,
+    revision,
+    rememberedPermissionKeys: ['shell:approved'],
+  };
+}
+
+/** A system message event. */
+export function agentEvent(id = 'event-1', content = 'System prompt'): plugins.ISystemMessageEvent {
+  return plugins.createAgentEvent<plugins.ISystemMessageEvent>({
+    id,
+    timestamp: 1,
+    type: 'system-message',
+    content,
+  });
+}
+
+/** The Agent event change that appends `events`. */
+export function appendEvents(...events: plugins.TAgentEvent[]): plugins.IAgentEventChange {
+  return { remove: [], replace: [], append: events };
+}
+
+/** A finished shell job. */
+export function finishedJob(executionId = 'job-1'): plugins.IToolJobState {
+  return {
+    executionId,
+    type: 'shell',
+    state: 'finished',
+    exitCode: 0,
+    stdout: 'ok',
+    stderr: '',
+    startedAt: 1,
+    updatedAt: 2,
+    finishedAt: 2,
+  };
+}

package/ts_stores_testing/index.ts

@@ -0,0 +1,17 @@
+export {
+  createFlexStoreContractTests,
+  type IFlexStoreContractBackend,
+  type IFlexStoreContractFixture,
+  type IFlexStoreContractTest,
+} from './contract.js';
+export {
+  agentEvent,
+  appendEvents,
+  finishedJob,
+  permissionSnapshot,
+  projectionSnapshot,
+  projectionWithRuns,
+  runMessages,
+  runSegment,
+  scopeSnapshot,
+} from './fixtures.js';

package/ts_stores_testing/plugins.ts

@@ -0,0 +1,20 @@
+// node native scope
+import { strict as assert } from 'node:assert';
+
+export { assert };
+
+// @modelprofile.com scope
+import {
+  AgentEventStoreConflictError,
+  ToolJobStoreConflictError,
+  createAgentEvent,
+} from '@modelprofile.com/flexharness-agent';
+
+export { AgentEventStoreConflictError, ToolJobStoreConflictError, createAgentEvent };
+export type {
+  IAgentEventArchive,
+  IAgentEventChange,
+  ISystemMessageEvent,
+  IToolJobState,
+  TAgentEvent,
+} from '@modelprofile.com/flexharness-agent';

package/ts_stores_testing/readme.md

@@ -0,0 +1,62 @@
+The store contract of FlexHarness as test cases for any test runner: the behaviour every built-in `IFlexHarnessStores` bundle passes, to run against a custom one.
+
+```sh
+pnpm add @modelprofile.com/flexharness
+```
+
+```typescript
+import { test } from 'node:test';
+import { createFlexStoreContractTests } from '@modelprofile.com/flexharness/stores/testing';
+
+for (const contractTest of createFlexStoreContractTests({
+  name: 'my stores',
+  sharedBackingStore: true,
+  releasesSessions: false,
+  storesResults: false,
+  async open() {
+    const database = await createDisposableDatabase();
+    return {
+      stores: new MyFlexHarnessStores(database),
+      openPeer: async () => new MyFlexHarnessStores(database.connectAgain()),
+      close: () => database.drop(),
+    };
+  },
+})) {
+  test(contractTest.title, () => contractTest.run());
+}
+```
+
+`createFlexStoreContractTests(backend)` returns one `{ title, run() }` per case; `run()` resolves when the case passes and throws a `node:assert` error, or the store's own error, when it fails. Each case calls `backend.open()` for a fixture over an empty backing store and closes it afterwards, also when it fails, so the backend needs no cleanup between cases and the cases may run in any order. The backend declares what its bundle offers, and the cases that need more are left out:
+
+- `sharedBackingStore`: several bundles can open one backing store, as separate processes would. The fixture's `openPeer()` opens another, and a case checks that the bundles share compare-and-swap revisions.
+- `releasesSessions`: the Agent event and tool job providers implement `releaseSession`, which must evict their session wrappers without deleting stored data.
+- `storesResults`: the bundle provides the optional `results` store.
+
+The cases cover compare-and-swap revisions and the conflict errors that report them, cloning at the store boundary, session and storage key isolation, the snapshot validation every domain applies, and the change-based saves of projections and Agent events: a projection change keeps the stored entries its list changes name and appends the rest, an Agent event change removes, replaces and appends events, and a change that does not fit the stored value never loads, whether the store rejects it when it saves the change or when it next loads the value. The cases await every store call, as FlexHarness does, so a store method may reject or throw.
+
+A store that keeps snapshots implements the change-based saves with the helpers of the root and Agent packages: `assertFlexProjectionChange()` and `applyFlexProjectionChange()` from `@modelprofile.com/flexharness`, `assertAgentEventChange()` and `applyAgentEventChange()` from `@modelprofile.com/flexharness-agent`, followed by the snapshot validators the root readme lists. The fixture builders the cases use, such as `projectionWithRuns()` and `appendEvents()`, are exported too, for a backend's own tests.
+
+## 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.
+
+## 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.