@modelprofile.com/flexharness 11.0.1 → 11.1.1

package/ts/readme.md

@@ -293,6 +293,10 @@ const harness = new FlexHarness<IProjectScope>({
     maxPageBytes: 1024 * 1024,
     stagedImportIdleTimeoutMs: 5 * 60 * 1000,
   },
+  resultLimits: {
+    maxStoredBytes: 8 * 1024 * 1024,
+    maxResultsPerSession: 32,
+  },
   subagents: [
     {
       name: 'researcher',
@@ -1002,7 +1006,7 @@ FlexHarness wraps every provided tool `execute` method before AgentSession recei
 
 `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 source delta. Text and reasoning accumulate only in the run-local terminal projection while each source delta remains an immediate exact public event. Every distinct async-iterable tool output appears immediately as a bounded cumulative `part.updated` snapshot while the tool remains `running`, including the final yielded value before completion. Only the authoritative `part.completed` output enters the terminal projection, and failed or interrupted tools discard their transient output. `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.
+Streaming callbacks use run-local synchronous state rather than one persistence promise per source delta. Text and reasoning accumulate only in the run-local terminal projection while each source delta remains an immediate exact public event. Every distinct async-iterable tool output appears immediately as a bounded cumulative `part.updated` snapshot while the tool remains `running`, including the final yielded value before completion. Only the authoritative `part.completed` output enters the terminal projection, and failed or interrupted tools discard their transient output. `callbackLimits` bounds callback events, accumulated output bytes, and part count; overflow aborts internally with `FlexHarnessCallbackOverflowError` and the turn is recorded as failed. The calls of a `run_code` program never overflow it: they stop their program at its `callbacks` limit instead. Reservation and terminal finalization are the normal persistence checkpoints, with permission state changes as explicit additional checkpoints.
 
 Model resolver, tool provider, delegated run admission provider, AgentSession, tool execution, tool callback, tool cleanup, and run-persistence failures cross an untrusted error boundary. By default they become a fixed immutable `FlexHarnessExternalError` before completion rejection, persistence, events, or detached-cleanup reporting. Raw external messages and aggregate members are not retained. A failed `onToolCallFinish` callback stores and accounts for only the bounded projected message; it does not otherwise reject completion, although exceeding the configured callback limits still fails the run. Scope resolution and the initial store load happen before a run exists and remain outside this boundary.
 
@@ -1096,7 +1100,7 @@ const unsubscribe = harness.subscribe((event) => {
 unsubscribe();
 ```
 
-Events are discriminated, deeply immutable values with one global sequence within each `FlexHarness` instance. Every `IFlexEventBase` carries the exact source `sessionGenerationId` and `sessionGenerationSequence`; `session.deleted` retains the deleted generation after live metadata is removed. Listener exceptions are isolated from runs and other listeners. Every accepted queue entry emits `prompt.queued` and exactly one `prompt.finished`. Every accepted steer emits `prompt.steer.accepted`, and `prompt.steer.applied`, after the `message.*` events of its user message, once the run took it in; `run.finished` lists it in `unappliedSteerIds` unless it is in the model context of later turns. Durable promotion additionally emits `prompt.started`, and actual model preparation emits `prompt.running`; cancellation or failure can omit either intermediate event. Existing durable run/message terminal events precede `prompt.finished`. Every callback-backed streamed text part emits exactly one `part.completed` event before the corresponding `run.finished` event. Every `part.started`, `part.delta`, `part.updated`, and `part.completed` event carries zero-based `messageIndex` and `partIndex` coordinates from the session's authoritative message and part sequences.
+Events are discriminated, deeply immutable values with one global sequence within each `FlexHarness` instance. Every `IFlexEventBase` carries the exact source `sessionGenerationId` and `sessionGenerationSequence`; `session.deleted` retains the deleted generation after live metadata is removed. Listener exceptions are isolated from runs and other listeners. Every accepted queue entry emits `prompt.queued` and exactly one `prompt.finished`. Every accepted steer emits `prompt.steer.accepted`, and `prompt.steer.applied`, after the `message.*` events of its user message, once the run took it in; `run.finished` lists it in `unappliedSteerIds` unless it is in the model context of later turns. Durable promotion additionally emits `prompt.started`, and actual model preparation emits `prompt.running`; cancellation or failure can omit either intermediate event. Existing durable run/message terminal events precede `prompt.finished`. Every callback-backed streamed text part emits exactly one `part.completed` event before the corresponding `run.finished` event: once the model step that streamed it is committed, so its text is final and saved, or with the run's terminal projection when that step did not commit. Text a later model step streams starts a new part. Every `part.started`, `part.delta`, `part.updated`, and `part.completed` event carries zero-based `messageIndex` and `partIndex` coordinates from the session's authoritative message and part sequences.
 
 `getSessionView(scopeId, sessionId)` reads a session's metadata, visible messages and pending permission requests in one step, together with the instance's event `sequence` they include. The messages include what a running turn has streamed so far, so a consumer that applies every event of the instance with a greater `sequence` follows the session exactly from the view on; events up to `sequence` are already in it. The read waits while a queued write or a change that emits events for the session is in progress; a session that keeps changing through 64 consecutive waits is refused with `FlexHarnessSessionBusyError`, and the read can be repeated. Session metadata is current: status changes such as `waiting_permission` emit no event. A permission request its run leaves unanswered leaves `pendingPermissions` without an event of its own; the run's `run.finished` follows.
 
@@ -1121,6 +1125,8 @@ Current FlexHarness persistence is separated by trust and lifecycle domain throu
 
 `InMemoryFlexHarnessStores` implements all six required domains with revision-based compare-and-swap behavior for tests and ephemeral processes. It is the default when `stores` is omitted. Custom `IFlexHarnessStores` implementations must provide `projectManagement` even when project-management tools are disabled, because deletion cleanup always writes the generation fence.
 
+A custom store validates what it loads and saves with the validators the built-in stores apply. Each throws `FlexHarnessStoreFormatError` for a malformed or wrong-schema snapshot: `assertFlexScopeSnapshot()`, `assertFlexProjectionSnapshot(value, sessionId)`, which also requires every message and staged terminal to belong to `sessionId`, `assertFlexPermissionSnapshot()`, `assertFlexProjectManagementRecord()` and `assertFlexToolJobSnapshot()`. Agent event snapshots and archives have `validateAgentEventSnapshotV2()` and `validateAgentEventArchiveV2()` in `@modelprofile.com/flexharness-agent`.
+
 Custom Agent event and job providers may implement `releaseSession(storageKey, sessionId)` to release session-bound wrappers, handles, or caches without deleting durable data. FlexHarness calls these hooks only after the corresponding AgentSession or execution context has released runtime ownership. A failed release remains owned for a later retirement or disposal retry. `deleteSession()` and `deleteSessionGenerationCohort()` are the separate destructive operations for durable session data.
 
 `JsonFileFlexHarnessStores` stores the domains in separate `scopes`, `projections`, `permissions`, `projectManagement`, `events`, `archives`, and `jobs` directories. Storage and session identifiers are SHA-256 hashed for filenames. Passing the store bundle supplies lifecycle persistence but does not enable any built-in tool. It provides:

package/ts/utils.harnessoptions.ts

@@ -2,6 +2,7 @@ import { FlexHarnessValidationError } from './errors.js';
 import {
   FLEX_CODE_MODE_DEFAULT_LIMITS,
   FLEX_CODE_MODE_MAXIMUM_LIMITS,
+  FLEX_RESULT_LIMITS,
   FLEX_REVERSION_DEFAULT_LIMITS,
   FLEX_TOOL_CATALOG_DEFAULT_OUTPUT_TYPE_DEPTH,
   FLEX_TOOL_CATALOG_LIMITS,
@@ -12,7 +13,9 @@ import type {
   IFlexCallbackLimits,
   IFlexHarnessOptions,
   IFlexHarnessStores,
+  IFlexJsonLimits,
   IFlexPromptQueueLimits,
+  IFlexResultLimits,
   IFlexReversionLimits,
   IFlexSlashCommandHandlerRegistration,
   IFlexSlashCommandTemplateRegistration,
@@ -452,6 +455,25 @@ export function resolveReversionLimits(
   return resolved;
 }
 
+/** The result limits, resolved against the output budget: a stored result never holds less. */
+export function resolveResultLimits(
+  limits: IFlexResultLimits = {},
+  toolOutputLimits: Required<IFlexJsonLimits>,
+): Required<IFlexResultLimits> {
+  const maxStoredBytes = limits.maxStoredBytes
+    ?? Math.max(FLEX_RESULT_LIMITS.maxStoredBytes, toolOutputLimits.maxBytes);
+  if (!Number.isSafeInteger(maxStoredBytes) || maxStoredBytes < toolOutputLimits.maxBytes) {
+    throw new FlexHarnessValidationError(
+      `resultLimits.maxStoredBytes must be an integer of at least toolOutputLimits.maxBytes (${toolOutputLimits.maxBytes}).`,
+    );
+  }
+  const maxResultsPerSession = limits.maxResultsPerSession ?? FLEX_RESULT_LIMITS.maxResultsPerSession;
+  if (!Number.isSafeInteger(maxResultsPerSession) || maxResultsPerSession < 1) {
+    throw new FlexHarnessValidationError('resultLimits.maxResultsPerSession must be a positive integer.');
+  }
+  return { maxStoredBytes, maxResultsPerSession };
+}
+
 export function normalizeAgentSessionPolicy<TScope>(
   policy: IFlexAgentSessionPolicy<TScope> = {},
 ): IFlexAgentSessionPolicy<TScope> {

package/ts/utils.json.ts

@@ -24,7 +24,8 @@ import { isValidSessionConfigurationRef } from './utils.validation.js';
 
 const DEFAULT_MAX_DEPTH = 12;
 const DEFAULT_MAX_BYTES = 256 * 1024;
-const MIN_MAX_BYTES = 128;
+/** The least `maxBytes`: room for the marker that stands for a truncated value. */
+export const MIN_MAX_BYTES = 128;
 
 function isPlainObject(value: object): boolean {
   const prototype = Object.getPrototypeOf(value);
@@ -321,62 +322,108 @@ export function normalizeJsonValue(value: unknown, limits: IFlexJsonLimits = {})
   return makeDescription('truncated', { reason: 'bytes' });
 }
 
-function assertJsonSerializableAt(value: unknown, path: string, seen: WeakSet<object>): void {
+const ARRAY_INDEX_PATTERN = /^(0|[1-9]\d*)$/;
+
+/**
+ * One walk over a value as JSON sees it. The path to the current value is kept as segments and only
+ * formatted for an error, and `ancestors` holds the objects on that path to detect cycles.
+ */
+interface IJsonWalk {
+  readonly root: string;
+  readonly segments: Array<string | number>;
+  readonly ancestors: object[];
+  readonly copy: boolean;
+}
+
+function failJsonWalk(walk: IJsonWalk, message: string): never {
+  let path = walk.root;
+  for (const segment of walk.segments) {
+    path += typeof segment === 'number' ? `[${segment}]` : `.${segment}`;
+  }
+  throw new FlexHarnessStoreFormatError(`${path} ${message}`);
+}
+
+/**
+ * Rejects anything a JSON round trip would not preserve. With `walk.copy` it also returns the copy
+ * `JSON.parse(JSON.stringify(value))` would return, built in the same pass.
+ */
+function walkJsonValue(walk: IJsonWalk, value: unknown): unknown {
   if (value === null || typeof value === 'string' || typeof value === 'boolean') {
-    return;
+    return value;
   }
   if (typeof value === 'number') {
-    if (!Number.isFinite(value)) {
-      throw new FlexHarnessStoreFormatError(`${path} contains a non-finite number.`);
-    }
-    return;
+    if (!Number.isFinite(value)) failJsonWalk(walk, 'contains a non-finite number.');
+    // JSON writes -0 as 0.
+    return value === 0 ? 0 : value;
   }
   if (typeof value !== 'object') {
-    throw new FlexHarnessStoreFormatError(`${path} contains ${typeof value}, which is not JSON-safe.`);
+    failJsonWalk(walk, `contains ${typeof value}, which is not JSON-safe.`);
   }
-  if (seen.has(value)) {
-    throw new FlexHarnessStoreFormatError(`${path} contains a circular reference.`);
+  if (walk.ancestors.includes(value)) {
+    failJsonWalk(walk, 'contains a circular reference.');
   }
   if (!Array.isArray(value) && !isPlainObject(value)) {
-    throw new FlexHarnessStoreFormatError(`${path} contains a non-plain object.`);
+    failJsonWalk(walk, 'contains a non-plain object.');
   }
   if (Object.getOwnPropertySymbols(value).length > 0) {
-    throw new FlexHarnessStoreFormatError(`${path} contains a symbol-keyed property.`);
+    failJsonWalk(walk, 'contains a symbol-keyed property.');
   }
-  seen.add(value);
+  walk.ancestors.push(value);
+  let copy: unknown;
   if (Array.isArray(value)) {
-    const extraKey = Object.keys(value).find(
-      (key) => !/^(0|[1-9]\d*)$/.test(key) || Number(key) >= value.length,
-    );
-    if (extraKey) {
-      throw new FlexHarnessStoreFormatError(`${path}.${extraKey} is not a JSON array index.`);
-    }
-    const customHiddenKey = Object.getOwnPropertyNames(value).find(
-      (key) => key !== 'length' && !/^(0|[1-9]\d*)$/.test(key),
-    );
-    if (customHiddenKey) {
-      throw new FlexHarnessStoreFormatError(`${path}.${customHiddenKey} is not JSON-visible.`);
-    }
-    for (let index = 0; index < value.length; index++) {
-      if (!(index in value)) {
-        throw new FlexHarnessStoreFormatError(`${path}[${index}] is a sparse array entry.`);
+    const length = value.length;
+    // Own names list array indices in ascending order, then `length`, then any other keys, so a
+    // dense array without extra properties has exactly its indices followed by `length`.
+    const names = Object.getOwnPropertyNames(value);
+    if (names.length !== length + 1 || names[length] !== 'length') {
+      const extraKey = Object.keys(value).find(
+        (key) => !ARRAY_INDEX_PATTERN.test(key) || Number(key) >= length,
+      );
+      if (extraKey) {
+        walk.segments.push(extraKey);
+        failJsonWalk(walk, 'is not a JSON array index.');
       }
-      assertJsonSerializableAt(value[index], `${path}[${index}]`, seen);
+      const customHiddenKey = names.find((key) => key !== 'length' && !ARRAY_INDEX_PATTERN.test(key));
+      if (customHiddenKey) {
+        walk.segments.push(customHiddenKey);
+        failJsonWalk(walk, 'is not JSON-visible.');
+      }
+    }
+    const items: unknown[] | undefined = walk.copy ? [] : undefined;
+    for (let index = 0; index < length; index++) {
+      walk.segments.push(index);
+      if (!(index in value)) failJsonWalk(walk, 'is a sparse array entry.');
+      const item = walkJsonValue(walk, value[index]);
+      items?.push(item);
+      walk.segments.pop();
     }
+    copy = items;
   } else {
+    const fields: Record<string, unknown> | undefined = walk.copy ? {} : undefined;
     for (const key of Object.getOwnPropertyNames(value)) {
       const descriptor = Object.getOwnPropertyDescriptor(value, key)!;
+      walk.segments.push(key);
       if (!descriptor.enumerable || !('value' in descriptor)) {
-        throw new FlexHarnessStoreFormatError(`${path}.${key} is not a plain JSON property.`);
+        failJsonWalk(walk, 'is not a plain JSON property.');
+      }
+      const field = walkJsonValue(walk, descriptor.value);
+      if (fields && key in fields) {
+        // JSON.parse defines every key as an own property, so a key that names an inherited property,
+        // such as `__proto__`, neither sets the prototype nor reaches an inherited setter.
+        Object.defineProperty(fields, key, { value: field, enumerable: true, writable: true, configurable: true });
+      } else if (fields) {
+        fields[key] = field;
       }
-      assertJsonSerializableAt(descriptor.value, `${path}.${key}`, seen);
+      walk.segments.pop();
     }
+    copy = fields;
   }
-  seen.delete(value);
+  walk.ancestors.pop();
+  return copy;
 }
 
 export function assertJsonSerializable(value: unknown, path = '$'): void {
-  assertJsonSerializableAt(value, path, new WeakSet<object>());
+  walkJsonValue({ root: path, segments: [], ancestors: [], copy: false }, value);
 }
 
 function requireRecord(value: unknown, path: string): Record<string, unknown> {
@@ -1764,13 +1811,43 @@ export function assertFlexProjectionSnapshotV3(
   assertFlexProjectionSnapshotV2(compatibleV2);
 }
 
+/**
+ * Validates a projection snapshot of any stored schema version. With `sessionId`, every message
+ * and staged terminal must also belong to that session, as a store requires of what it loads or
+ * saves under that session.
+ */
 export function assertFlexProjectionSnapshot(
   value: unknown,
+  sessionId?: string,
 ): asserts value is IFlexProjectionSnapshotV1 | IFlexProjectionSnapshotV2 | IFlexProjectionSnapshotV3 {
   const record = requireRecord(value, '$snapshot');
   if (record.schemaVersion === 1) assertFlexProjectionSnapshotV1(value);
   else if (record.schemaVersion === 2) assertFlexProjectionSnapshotV2(value);
   else assertFlexProjectionSnapshotV3(value);
+  if (sessionId !== undefined) assertProjectionSession(value, sessionId);
+}
+
+function assertProjectionSession(
+  snapshot: IFlexProjectionSnapshotV1 | IFlexProjectionSnapshotV2 | IFlexProjectionSnapshotV3,
+  sessionId: string,
+): void {
+  for (const message of snapshot.messages) {
+    if (message.sessionId !== sessionId) {
+      throw new FlexHarnessStoreFormatError(
+        `Projection message "${message.messageId}" does not belong to session "${sessionId}".`,
+      );
+    }
+  }
+  for (const terminal of snapshot.stagedTerminals) {
+    if (
+      terminal.userMessage.sessionId !== sessionId
+      || terminal.assistantMessage.sessionId !== sessionId
+    ) {
+      throw new FlexHarnessStoreFormatError(
+        `Staged terminal "${terminal.runId}" does not belong to session "${sessionId}".`,
+      );
+    }
+  }
 }
 
 export function assertFlexPermissionSnapshot(
@@ -1812,9 +1889,9 @@ export function canonicalJson(value: unknown): string | undefined {
   return result === notJson ? undefined : JSON.stringify(result);
 }
 
+/** Copies a JSON-safe value as a JSON round trip would, and rejects any other value. */
 export function cloneSerializable<T>(value: T): T {
-  assertJsonSerializable(value);
-  return JSON.parse(JSON.stringify(value)) as T;
+  return walkJsonValue({ root: '$', segments: [], ancestors: [], copy: true }, value) as T;
 }
 
 export function deepFreeze<T>(value: T): T {

package/ts/utils.storecodecs.ts

@@ -139,7 +139,7 @@ export function validateAgentEventArchive(
   }
 }
 
-export function validateToolJobSnapshot(value: unknown): plugins.IToolJobSnapshot {
+export function assertFlexToolJobSnapshot(value: unknown): asserts value is plugins.IToolJobSnapshot {
   assertJsonSerializable(value, '$snapshot');
   assertRecord(value, '$snapshot');
   assertExactKeys(value, ['schemaVersion', 'revision', 'updatedAt', 'jobs'], '$snapshot');
@@ -229,7 +229,6 @@ export function validateToolJobSnapshot(value: unknown): plugins.IToolJobSnapsho
       if (job[key] !== undefined) assertNonNegativeInteger(job[key], `${path}.${key}`);
     }
   }
-  return value as unknown as plugins.IToolJobSnapshot;
 }
 
 export function createToolJobSnapshot(
@@ -242,5 +241,6 @@ export function createToolJobSnapshot(
     updatedAt: Date.now(),
     jobs: normalizeJsonObjectUndefined([...jobs], '$jobs'),
   };
-  return validateToolJobSnapshot(snapshot);
+  assertFlexToolJobSnapshot(snapshot);
+  return snapshot;
 }

package/ts/utils.storerules.ts

@@ -27,9 +27,8 @@ type TSnapshot =
   | TFlexProjectionSnapshot
   | IFlexPermissionSnapshot
   | TFlexProjectManagementRecord;
-type TSnapshotValidator<TSnapshotValue extends TSnapshot> = (
-  value: unknown,
-) => asserts value is TSnapshotValue;
+/** Throws when `value` is not a valid snapshot of the domain being saved. */
+type TSnapshotValidator = (value: unknown) => void;
 
 export function validateIdentifier(value: string, name: string): void {
   if (typeof value !== 'string' || !value.trim()) {
@@ -60,7 +59,7 @@ export function validateProjectManagementWriteContext(
 export function validateSnapshotSave<TSnapshotValue extends TSnapshot>(
   snapshot: TSnapshotValue,
   expectedRevision: number,
-  validator: TSnapshotValidator<TSnapshotValue>,
+  validator: TSnapshotValidator,
 ): TSnapshotValue {
   validator(snapshot);
   validateExpectedRevision(expectedRevision);
@@ -78,26 +77,6 @@ export function providerKey(storageKey: string, sessionId: string): string {
   return JSON.stringify([storageKey, sessionId]);
 }
 
-export function assertProjectionSession(snapshot: TFlexProjectionSnapshot, sessionId: string): void {
-  for (const message of snapshot.messages) {
-    if (message.sessionId !== sessionId) {
-      throw new FlexHarnessStoreFormatError(
-        `Projection message "${message.messageId}" does not belong to session "${sessionId}".`,
-      );
-    }
-  }
-  for (const terminal of snapshot.stagedTerminals) {
-    if (
-      terminal.userMessage.sessionId !== sessionId
-      || terminal.assistantMessage.sessionId !== sessionId
-    ) {
-      throw new FlexHarnessStoreFormatError(
-        `Staged terminal "${terminal.runId}" does not belong to session "${sessionId}".`,
-      );
-    }
-  }
-}
-
 function sameProjectManagementGeneration(
   left: TFlexProjectManagementRecord,
   right: TFlexProjectManagementRecord,

package/ts_mcp/index.ts

@@ -255,7 +255,9 @@ export interface ICreateMcpToolCatalogResult<TScope = unknown> {
  * The MCP tools of `servers` as a tool catalog, which the model searches, describes and calls through
  * `execute` and `run_code`. A method's path is the name `createMcpTools` gives the tool; a name that
  * is no identifier (with `-`, or a reserved word) is declared as `FlexToolCatalog.identifierOf()`
- * makes it. Create one catalog per set of tool definitions and return the same object on every run.
+ * makes it. A prefixed method has the tool's own name as an alias, so a search that names the tool
+ * without its server declares it, as one naming the method does. Create one catalog per set of tool
+ * definitions and return the same object on every run.
  */
 export const createMcpToolCatalog = <TScope = unknown>(
   options: ICreateMcpToolCatalogOptions<TScope>,
@@ -286,10 +288,12 @@ export const createMcpToolCatalog = <TScope = unknown>(
     const description = text === summary ? undefined : truncateUtf8(text, plugins.FLEX_TOOL_CATALOG_LIMITS.maxDescriptionBytes);
     const readOnly = (server.trustReadOnlyHints === true && mcpTool.annotations?.readOnlyHint === true)
       || options.isReadOnly?.(toolContext) === true;
+    const alias = shouldPrefixToolNames ? unprefixedAliasOf(mcpTool.name) : undefined;
     methods.push({
       method: path,
       summary,
       ...(description ? { description } : {}),
+      ...(alias ? { aliases: [alias] } : {}),
       inputSchema: mcpTool.inputSchema,
       ...(readOnly ? { readOnly: true } : {}),
       run: (params, call) => callMcpTool({
@@ -532,6 +536,18 @@ const callMcpTool = async (call: IMcpToolCall): Promise<unknown> => {
 /** A catalog method path: the exposed name where it is an identifier, else the identifier made of it. */
 const catalogPathOf = (exposedToolName: string): string => plugins.FlexToolCatalog.identifierOf(exposedToolName);
 
+/**
+ * A prefixed method's search alias: the tool's own name, as its exposed name holds it after the
+ * server prefix, so that a search naming the tool without its server names the method. A name the
+ * catalog cannot take as an alias, longer than an alias may be or without a letter or digit, has none.
+ */
+const unprefixedAliasOf = (toolName: string): string | undefined => {
+  const alias = sanitizeMcpToolName(toolName);
+  return alias.length <= plugins.FLEX_TOOL_CATALOG_LIMITS.maxAliasCharacters && /[a-zA-Z0-9]/.test(alias)
+    ? alias
+    : undefined;
+};
+
 /** The first line of a description, as one line of at most the catalog's summary length. */
 const summaryOf = (text: string): string => {
   const line = text.split(/\r?\n/).find((candidate) => candidate.trim())!.replace(/[\s\u0000-\u001f\u007f]+/g, ' ').trim();

package/ts_mcp/readme.md

@@ -18,7 +18,9 @@ by default; `servers` carries each server's `trustReadOnlyHints`.
 run, each call on the client `resolveClient` names for its run, method paths equal to
 `createMcpTools()`' tool names, `authorizeToolCall` deciding catalog calls as it decides
 tool calls, and read-only methods where a server whose entry sets `trustReadOnlyHints: true`
-annotates its tool `readOnlyHint: true` or where `isReadOnly` declares them. The root readme's
+annotates its tool `readOnlyHint: true` or where `isReadOnly` declares them. A prefixed method
+has the tool's own name as a search alias, so `search_tools` finds and declares it for a query
+that names the tool without its server. The root readme's
 Tool Catalog section shows a tool provider that connects clients per run.
 
 See the [toolbox usage and migration guide](https://code.foss.global/modelprofile.com/flexharness#readme)

package/ts_stores_nosqldb/classes.nosqldbstores.ts

@@ -31,15 +31,14 @@ import {
   assertFlexProjectManagementTombstone,
 } from '../ts/utils.projectmanagement.js';
 import {
+  assertFlexToolJobSnapshot,
   createAgentEventSnapshot,
   createToolJobSnapshot,
   normalizeJsonObjectUndefined,
   validateAgentEventArchive,
   validateAgentEventSnapshot,
-  validateToolJobSnapshot,
 } from '../ts/utils.storecodecs.js';
 import {
-  assertProjectionSession,
   assertProjectManagementSaveAdmitted,
   assertSameArchiveEvents,
   isProjectManagementTombstoneAdmitted,
@@ -73,6 +72,11 @@ function validatePermission(value: unknown): IFlexPermissionSnapshot {
   return value;
 }
 
+function validateToolJobs(value: unknown): plugins.IToolJobSnapshot {
+  assertFlexToolJobSnapshot(value);
+  return value;
+}
+
 function validateProjectManagement(value: unknown): TFlexProjectManagementRecord {
   assertFlexProjectManagementRecord(value);
   return value;
@@ -108,8 +112,7 @@ class NoSqlProjectionStore implements IFlexProjectionStore {
 
   private validator(sessionId: string): (value: unknown) => TFlexProjectionSnapshot {
     return (value) => {
-      assertFlexProjectionSnapshot(value);
-      assertProjectionSession(value, sessionId);
+      assertFlexProjectionSnapshot(value, sessionId);
       return value;
     };
   }
@@ -129,8 +132,11 @@ class NoSqlProjectionStore implements IFlexProjectionStore {
     expectedRevision: number,
   ): Promise<void> {
     const key = providerKey(storageKey, sessionId);
-    const validated = validateSnapshotSave(snapshot, expectedRevision, assertFlexProjectionSnapshot);
-    assertProjectionSession(validated, sessionId);
+    const validated = validateSnapshotSave(
+      snapshot,
+      expectedRevision,
+      (value) => assertFlexProjectionSnapshot(value, sessionId),
+    );
     const conflict = (actualRevision: number) =>
       new FlexHarnessStoreConflictError(key, expectedRevision, actualRevision);
     await this.records.mutate({ domain: 'projection', storageKey, sessionId }, {
@@ -365,7 +371,7 @@ class NoSqlToolJobStore implements plugins.IToolJobStore {
     abortSignal?.throwIfAborted();
     const snapshot = await this.records.read(
       { domain: 'jobs', storageKey: this.storageKey, sessionId: this.sessionId },
-      validateToolJobSnapshot,
+      validateToolJobs,
     );
     abortSignal?.throwIfAborted();
     return snapshot;
@@ -384,7 +390,7 @@ class NoSqlToolJobStore implements plugins.IToolJobStore {
     await this.records.mutate(
       { domain: 'jobs', storageKey: this.storageKey, sessionId: this.sessionId },
       {
-        validate: validateToolJobSnapshot,
+        validate: validateToolJobs,
         decide: (current) => {
           abortSignal?.throwIfAborted();
           return revisionWrite(current, snapshot, expectedRevision, conflict);
@@ -432,6 +438,15 @@ export interface INoSqlFlexHarnessStoresOptions {
   operationTimeoutMs?: number;
 }
 
+export interface INoSqlFlexHarnessPurgeOptions {
+  /**
+   * Fences the namespace in the purge's transaction: every later record creation in it is
+   * refused with `FlexHarnessStorePurgedError`, from any process and for good, so a harness that
+   * still holds the scope cannot write it back. A purge without the fence never lifts one.
+   */
+  fence?: boolean;
+}
+
 /**
  * One record per result and an index record of the session's handles, oldest first, changed with
  * compare-and-swap. A result whose handle the index lost to a failed write stays until its session
@@ -495,7 +510,8 @@ function validateResult(value: unknown): TJsonValue {
 /**
  * Every FlexHarness persistence domain on `@lossless.org/client/nosqldb`, with compare-and-swap
  * that holds across processes. Records live in `flexharness_records`; payloads longer than one
- * chunk live in `flexharness_chunks`.
+ * chunk live in `flexharness_chunks`; `flexharness_namespaces` holds each storage namespace's
+ * fence.
  */
 export class NoSqlFlexHarnessStores implements IFlexHarnessStores {
   public readonly scopes: IFlexScopeStore;
@@ -522,7 +538,7 @@ export class NoSqlFlexHarnessStores implements IFlexHarnessStores {
   }
 
   /**
-   * Creates or verifies the two collections and their indexes. Every store operation awaits the
+   * Creates or verifies the three collections and their indexes. Every store operation awaits the
    * same preparation, so calling it at startup only moves that work, and its failure, forward.
    */
   public prepare(): Promise<void> {
@@ -533,12 +549,20 @@ export class NoSqlFlexHarnessStores implements IFlexHarnessStores {
    * Physically removes every record and chunk of one storage namespace in every domain: the
    * scope snapshot, each session's projection, permissions, Agent events and archives, jobs and
    * results, and the project-management records and tombstones. This is the host's durable
-   * deletion of a scope. Call it only after stopping new admission for every alias of the scope
-   * and awaiting `retireScope()` on every harness that owns it; purging under a live harness
-   * removes the fences that keep its writes safe.
+   * deletion of a scope. Stop new admission for every alias of the scope first. Without `fence`,
+   * also await `retireScope()` on every harness that owns it: purging under a live harness
+   * removes the revisions its writes would conflict with, so it can write records back. With
+   * `fence`, the namespace refuses every later record creation, from any process and for good,
+   * so such a harness gets `FlexHarnessStorePurgedError` instead; the storage key is never usable
+   * again.
    */
-  public purgeNamespace(storageKey: string): Promise<void> {
+  public purgeNamespace(storageKey: string, options: INoSqlFlexHarnessPurgeOptions = {}): Promise<void> {
     validateIdentifier(storageKey, 'storageKey');
-    return this.records.purgeNamespace(storageKey);
+    if (options.fence !== undefined && typeof options.fence !== 'boolean') {
+      throw new FlexHarnessValidationError('fence must be a boolean.');
+    }
+    return options.fence
+      ? this.records.fenceNamespace(storageKey)
+      : this.records.purgeNamespace(storageKey);
   }
 }