@modelprofile.com/flexharness 11.3.1 → 12.1.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.

package/ts_typedrequest/catalog.ts

@@ -27,10 +27,10 @@ export class FlexTypedRequestError extends Error {
 /**
  * The tool catalog of a typedrequest surface: every included method becomes a catalog method of
  * its path, declared as its contract writes it and validated against its schema, and runs through
- * `router.routeAndAddResponse()` in process, its request the model's parameters with the omitted
- * properties `request` fills and its result what `response` makes of the answer. A refusal rejects
- * with `FlexTypedRequestError`. A method `readOnly` marks is declared read-only and not gated by
- * `onCall`.
+ * `router.routeAndAddResponse()` in process, its request what `params` makes of the model's
+ * parameters with the omitted properties its request has as `request` fills them, and its result
+ * what `response` makes of the answer. A refusal rejects with `FlexTypedRequestError`. A method
+ * `readOnly` marks is declared read-only and not gated by `onCall`.
  */
 export function catalogFromTypedRequests<TScope = unknown>(
   surface: IFlexTypedRequestSurface,
@@ -39,6 +39,12 @@ export function catalogFromTypedRequests<TScope = unknown>(
   if (typeof options?.router?.routeAndAddResponse !== 'function') {
     throw new plugins.FlexHarnessValidationError('catalogFromTypedRequests needs a router with routeAndAddResponse().');
   }
+  const unlisted = surface.methods.find((method) => !Array.isArray(method.omitted));
+  if (unlisted) {
+    throw new plugins.FlexHarnessValidationError(
+      `The surface's method ${unlisted.method} has no omitted list, as one an earlier version described; describe it again with this version's describeTypedRequests().`,
+    );
+  }
   const aliases = options.aliases ?? {};
   const known = new Set(surface.methods.map((method) => method.method));
   const unknown = Object.keys(aliases).filter((method) => !known.has(method));
@@ -58,12 +64,24 @@ export function catalogFromTypedRequests<TScope = unknown>(
     params: Record<string, unknown>,
     context: IFlexCatalogRunContext<TScope>,
   ): Promise<unknown> => {
-    const filled = options.request ? await options.request(method, context) : {};
+    const mapped = options.params ? await options.params(method, params, context) : params;
+    if (typeof mapped !== 'object' || mapped === null || Array.isArray(mapped)) {
+      throw new plugins.FlexHarnessValidationError(`The options' params() made no request object for ${method.method}.`);
+    }
+    // An omitted property is the binding's alone: the model's value never reaches the router.
+    const request: Record<string, unknown> = { ...mapped };
+    for (const key of surface.omit) delete request[key];
+    if (method.omitted.length > 0) {
+      const filled = options.request ? await options.request(method, context) : {};
+      for (const key of method.omitted) {
+        if (Object.hasOwn(filled, key)) request[key] = filled[key];
+      }
+    }
     const localData = options.localData ? await options.localData(method, context) : undefined;
     const answer = await router.routeAndAddResponse(
       {
         method: method.method,
-        request: { ...params, ...filled },
+        request,
         response: {},
         correlation: { id: plugins.crypto.randomUUID(), phase: 'request' },
       },

package/ts_typedrequest/describe.ts

@@ -43,7 +43,7 @@ const withoutOmitted = (
   const target = referencedType(schema);
   if (target !== undefined) {
     const named = types[target];
-    return named !== undefined && holdsOmitted(named, omit, types, new Set([target]))
+    return named !== undefined && omittedIn(named, omit, types, new Set([target])).size > 0
       ? withoutOmitted(named, omit, types)
       : schema;
   }
@@ -63,22 +63,29 @@ const withoutOmitted = (
   return stripped;
 };
 
-/** Whether a schema has an omitted property, itself or through the schemas it composes or refers to. */
-const holdsOmitted = (
+/** The omitted properties a schema has, itself or through the schemas it composes or refers to. */
+const omittedIn = (
   schema: TFlexTypedRequestSchema,
   omit: ReadonlySet<string>,
   types: Readonly<Record<string, TFlexTypedRequestSchema>>,
   seen: Set<string>,
-): boolean => {
-  if (isRecord(schema.properties) && Object.keys(schema.properties).some((key) => omit.has(key))) return true;
+  found = new Set<string>(),
+): Set<string> => {
+  if (isRecord(schema.properties)) {
+    for (const key of Object.keys(schema.properties)) if (omit.has(key)) found.add(key);
+  }
   const target = referencedType(schema);
   if (target !== undefined) {
-    if (seen.has(target) || types[target] === undefined) return false;
+    if (seen.has(target) || types[target] === undefined) return found;
     seen.add(target);
-    return holdsOmitted(types[target], omit, types, seen);
+    return omittedIn(types[target], omit, types, seen, found);
   }
-  return (['allOf', 'anyOf', 'oneOf'] as const).some((key) => Array.isArray(schema[key])
-    && (schema[key] as unknown[]).some((member) => isRecord(member) && holdsOmitted(member, omit, types, seen)));
+  for (const key of ['allOf', 'anyOf', 'oneOf'] as const) {
+    const members = schema[key];
+    if (!Array.isArray(members)) continue;
+    for (const member of members) if (isRecord(member)) omittedIn(member, omit, types, seen, found);
+  }
+  return found;
 };
 
 /** Whether a call may leave out every parameter: its schema requires none. */
@@ -169,7 +176,8 @@ export async function describeTypedRequests(options: IFlexTypedRequestSurfaceOpt
     let path = base;
     for (let suffix = 2; paths.has(path); suffix++) path = `${base}_${suffix}`;
     paths.add(path);
-    const inputSchema = withoutOmitted(withDefinitionRefs(contract.request) as TFlexTypedRequestSchema, omitted, schemas);
+    const requestSchema = withDefinitionRefs(contract.request) as TFlexTypedRequestSchema;
+    const inputSchema = withoutOmitted(requestSchema, omitted, schemas);
     const docLines = [
       ...(declared.documentation ? [declared.documentation] : []),
       ...(declared.request.documentation ? [`@param params ${declared.request.documentation}`] : []),
@@ -183,6 +191,7 @@ export async function describeTypedRequests(options: IFlexTypedRequestSurfaceOpt
       summary: summaryOf(declared.documentation, contract.method),
       ...(declared.documentation ? { description: declared.documentation } : {}),
       ...(contract.deprecated ? { deprecated: true } : {}),
+      omitted: [...omittedIn(requestSchema, omitted, schemas, new Set())].sort(),
       inputSchema,
       outputSchema: withDefinitionRefs(contract.response) as TFlexTypedRequestSchema,
       declaration: `${docLines.length ? docBlock(docLines) : ''}function ${functionName}(params${optional}: ${declared.request.type}): Promise<${declared.response.type}>;`,

package/ts_typedrequest/interfaces.ts

@@ -42,6 +42,11 @@ export interface IFlexTypedRequestMethod {
   description?: string;
   /** Set by a `@deprecated` tag on the contract. */
   deprecated?: boolean;
+  /**
+   * The properties of the surface's `omit` this method's request has, itself or through the types
+   * it refers to: the ones the binding fills for its calls. Empty where it has none.
+   */
+  omitted: string[];
   /** The request's schema, without the omitted properties. */
   inputSchema: TFlexTypedRequestSchema;
   /** The response's schema. */
@@ -96,7 +101,9 @@ export interface IFlexTypedRequestCatalogOptions<TScope = unknown> {
   router: IFlexTypedRequestRouter;
   /**
    * The request properties the surface leaves out, from the run: `{ identity }` of the user the
-   * session acts for. They are merged over the model's parameters.
+   * session acts for. A call takes from it the properties its method's request has
+   * (`IFlexTypedRequestMethod.omitted`) and nothing else; a method whose request has none is called
+   * without asking.
    */
   request?(
     method: IFlexTypedRequestMethod,
@@ -116,6 +123,19 @@ export interface IFlexTypedRequestCatalogOptions<TScope = unknown> {
    * `IFlexCatalogMethod.readOnly`. Default: none.
    */
   readOnly?(method: IFlexTypedRequestMethod): boolean;
+  /**
+   * The request a call routes for the model's validated parameters, such as the parameters with the
+   * short names the model was shown for records turned back into their IDs. Default: the
+   * parameters. It runs when the call runs, after `onCall` decided it where the method has one:
+   * `onCall` and a proposal see the model's parameters. The omitted properties are dropped from what
+   * it returns, as from the model's, and only `request` fills them. A throw refuses the call with
+   * its error, and so does a result that is no object.
+   */
+  params?(
+    method: IFlexTypedRequestMethod,
+    params: Record<string, unknown>,
+    context: IFlexCatalogRunContext<TScope>,
+  ): Record<string, unknown> | PromiseLike<Record<string, unknown>>;
   /**
    * What the model sees of a method's answered response, such as the response without a
    * credential's secret. Default: the response. A refusal does not reach it, and the method's

package/ts_typedrequest/readme.md

@@ -29,19 +29,21 @@ const catalog = catalogFromTypedRequests<IAppScope>(surface, {
 - Each typed method becomes a method of the path `<area>.<method>`; the area is the base name of the file that declares the contract (`vouchers` for `requests/vouchers.ts`, the folder's name for an `index.ts`), or what `area` returns. A name that is no identifier is mapped as `FlexToolCatalog.identifierOf()` maps it (`export` becomes `export_`).
 - Its declaration is the contract as written: `function getVoucher(params: { voucherId: string }): Promise<{ voucher: IVoucher }>;` after the contract's JSDoc with its tags, the request property's JSDoc as `@param params`, the response property's as `@returns`. `params` is optional where the request requires nothing.
 - Its `inputSchema` and `outputSchema` are the request's and response's JSON Schema; `execute` validates every call against the request's.
-- `omit` names request properties the binding fills from the run, such as the caller's identity or a CSRF token: they leave every request's schema and declaration, so the model can neither see nor send them.
+- `omit` names request properties the binding fills from the run, such as the caller's identity or a CSRF token: they leave every request's schema and declaration, so the model can neither see nor send them. Each method lists in `omitted` those its request has, itself or through the types it refers to; a public method's list may be empty.
 - The named types the requests and responses reach become the catalog's types, each with its JSON Schema, its declaration from the sources, or both: a generic is declared once (`IPage<T>`) and its instances have schemas (`IPage_IVoucher`). A method's result types are declared only as deep as `toolCatalog.outputTypeDepth` asks, as for any declaration.
 
 The surface is plain JSON, so a build step can write it next to the server and the server read it at startup without TypeScript or `@api.global/typedopenapi`. A 330-method API is described in about 8 seconds.
 
 `catalogFromTypedRequests(surface, options)` returns an `IFlexToolCatalog`:
 
-- `router` answers the calls: anything with `routeAndAddResponse()`, such as a `TypedRouter` of `@api.global/typedrequest`. A call is routed as a typed request with the model's parameters and what `request` returns for the omitted properties, `localData` as the trusted route data a transport would hand the handlers, and the run's abort signal.
+- `router` answers the calls: anything with `routeAndAddResponse()`, such as a `TypedRouter` of `@api.global/typedrequest`. A call is routed as a typed request with the model's parameters, `localData` as the trusted route data a transport would hand the handlers, and the run's abort signal.
+- `request` fills the omitted properties. A call takes from what it returns only the omitted properties its method's request has, so one answer serves every method (`{ identity, csrfToken }`), and a method whose request has none is routed without asking it. A value the model passes for any omitted property never reaches the router.
 - A refusal rejects with `FlexTypedRequestError`: the typed method, the error's `text` and `data`, as a client of the API would receive them. A handler's own failure arrives as the router's internal error. A host's `externalErrorProjector` decides what of it the model sees.
 - `include` picks the methods the model may use, by default every method that is not deprecated; `aliases` gives methods other names by typed method; `vocabulary`, `onCall` and `onProposals` are the catalog's own (`onCall` receives the typed method first).
 - `readOnly` marks the methods that only read. A marked method is declared `readOnly` and `onCall` does not decide its calls, so they run concurrently with other reads, may start while the model still streams, and a turn answers identical ones once; every other method's calls, gated by `onCall` or not, run in the order the model made them. Mark nothing that asks for permission.
+- `params` makes the request a call routes of the model's validated parameters, such as the parameters with the short names the model was shown for records turned back into their IDs; by default the parameters themselves. It runs when the call runs, after `onCall` decided it where the method has one, so `onCall` and a proposal see the model's parameters. The omitted properties are dropped from what it returns as from the model's, and only `request` fills them. A throw refuses the call with its error, and so does a result that is no object.
 - `response` decides what the model sees of an answered response, such as the response without a credential's secret; by default the response itself. A refusal does not reach it, and the method's declaration still shows the contract's response.
-- A surface that omits properties needs `request`; an alias for a method the surface lacks is refused.
+- A surface that omits properties needs `request`; an alias for a method the surface lacks is refused, and so is a surface whose methods have no `omitted` list, as one described by an earlier version: describe it again.
 
 ## Issue Reporting and Security