@modelprofile.com/flexharness 10.15.1 → 10.17.0

package/ts/utils.json.ts

@@ -786,6 +786,7 @@ function validateMessage(value: unknown, path: string): IValidatedMessageIdentit
           'error',
           'childSessionId',
           'parentToolCallId',
+          'deduplicatedFrom',
           'model',
           'startedAt',
           'completedAt',
@@ -803,6 +804,7 @@ function validateMessage(value: unknown, path: string): IValidatedMessageIdentit
       requireOptionalString(part.error, `${partPath}.error`);
       requireOptionalString(part.childSessionId, `${partPath}.childSessionId`);
       requireOptionalString(part.parentToolCallId, `${partPath}.parentToolCallId`);
+      requireOptionalString(part.deduplicatedFrom, `${partPath}.deduplicatedFrom`);
       if (part.model !== undefined) validateModel(part.model, `${partPath}.model`);
       requireOptionalString(part.startedAt, `${partPath}.startedAt`);
       requireOptionalString(part.completedAt, `${partPath}.completedAt`);
@@ -1763,6 +1765,34 @@ export function assertFlexPermissionSnapshot(
   validatePermissionKeys(snapshot.rememberedPermissionKeys, '$snapshot.rememberedPermissionKeys');
 }
 
+/**
+ * The JSON text of a plain JSON value with every object's keys sorted, so equal values read the
+ * same; undefined for anything else, such as a Date or a Map, whose JSON could equal another's.
+ */
+export function canonicalJson(value: unknown): string | undefined {
+  const notJson = Symbol('not JSON');
+  const canonical = (entry: unknown): unknown => {
+    if (entry === null || typeof entry === 'string' || typeof entry === 'boolean') return entry;
+    if (typeof entry === 'number') return Number.isFinite(entry) ? entry : notJson;
+    if (Array.isArray(entry)) {
+      const items = entry.map(canonical);
+      return items.includes(notJson) ? notJson : items;
+    }
+    if (typeof entry !== 'object' || ![Object.prototype, null].includes(Object.getPrototypeOf(entry))) return notJson;
+    const sorted: Record<string, unknown> = {};
+    for (const key of Object.keys(entry).sort()) {
+      const field = (entry as Record<string, unknown>)[key];
+      if (field === undefined) continue;
+      const canonicalField = canonical(field);
+      if (canonicalField === notJson) return notJson;
+      sorted[key] = canonicalField;
+    }
+    return sorted;
+  };
+  const result = canonical(value);
+  return result === notJson ? undefined : JSON.stringify(result);
+}
+
 export function cloneSerializable<T>(value: T): T {
   assertJsonSerializable(value);
   return JSON.parse(JSON.stringify(value)) as T;

package/ts/utils.results.ts

@@ -0,0 +1,164 @@
+import type { TJsonValue } from './interfaces.js';
+
+/**
+ * Stored tool results: the summary the model gets in place of an output over its budget, and the
+ * pages `results.get` reads from it. A page holds whole array items, whole object entries or a
+ * slice of a string; an item or entry too large for a page stands as a marker naming its path,
+ * which `results.get` reads in turn.
+ */
+
+const jsonBytes = (value: unknown): number => Buffer.byteLength(JSON.stringify(value) ?? 'null');
+
+const isRecord = (value: TJsonValue): value is { [key: string]: TJsonValue } =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+/** The shape of a value in a few words, such as `array(120)` or `string(2048 chars)`. */
+export function describeShape(value: TJsonValue): string {
+  if (Array.isArray(value)) return `array(${value.length})`;
+  if (isRecord(value)) return `object(${Object.keys(value).length} keys)`;
+  if (typeof value === 'string') return `string(${value.length} chars)`;
+  return value === null ? 'null' : typeof value;
+}
+
+/** What a stored result holds, within about `budgetBytes`: its shape and a preview of its start. */
+export function summarizeResult(value: TJsonValue, budgetBytes: number): TJsonValue {
+  if (Array.isArray(value)) {
+    const preview: TJsonValue[] = [];
+    let bytes = 0;
+    for (const item of value) {
+      const itemBytes = jsonBytes(item) + 1;
+      if (bytes + itemBytes > budgetBytes) break;
+      preview.push(item);
+      bytes += itemBytes;
+    }
+    const first = value[0];
+    return {
+      type: 'array',
+      length: value.length,
+      ...(first !== undefined && isRecord(first) ? { itemKeys: Object.keys(first).slice(0, 40) } : {}),
+      preview,
+    };
+  }
+  if (isRecord(value)) {
+    const keys: { [key: string]: TJsonValue } = {};
+    let bytes = 0;
+    for (const [key, entry] of Object.entries(value)) {
+      const shape = describeShape(entry);
+      bytes += jsonBytes(key) + jsonBytes(shape) + 2;
+      if (bytes > budgetBytes) break;
+      keys[key] = shape;
+    }
+    return { type: 'object', size: Object.keys(value).length, keys };
+  }
+  if (typeof value === 'string') {
+    return { type: 'string', length: value.length, preview: sliceWithin(value, 0, budgetBytes).text };
+  }
+  return { type: value === null ? 'null' : typeof value, value };
+}
+
+/** The value at a dotted `path`, such as `items.3.lines`; undefined when it has none. */
+export function selectPath(value: TJsonValue, path: string): TJsonValue | undefined {
+  let current: TJsonValue | undefined = value;
+  for (const segment of path === '' ? [] : path.split('.')) {
+    if (Array.isArray(current)) {
+      current = /^(?:0|[1-9]\d*)$/.test(segment) ? current[Number(segment)] : undefined;
+    } else if (current !== undefined && isRecord(current)) {
+      current = Object.prototype.hasOwnProperty.call(current, segment) ? current[segment] : undefined;
+    } else {
+      return undefined;
+    }
+  }
+  return current;
+}
+
+export interface IResultPage {
+  pages: number;
+  value: TJsonValue;
+  /** The array items (`items`), object entries (`entries`) or string characters (`chars`) the page holds, as [from, to). */
+  range?: { items: [number, number] } | { entries: [number, number] } | { chars: [number, number] };
+}
+
+/** Page `page` (1-based) of `value`, each page at most `pageBytes` of JSON; undefined past the last. */
+export function resultPage(value: TJsonValue, path: string, page: number, pageBytes: number): IResultPage | undefined {
+  const at = (key: string) => path === '' ? key : `${path}.${key}`;
+  const oversize = (key: string, entry: TJsonValue): TJsonValue => ({
+    $flexType: 'oversize',
+    path: at(key),
+    bytes: jsonBytes(entry),
+    shape: describeShape(entry),
+  });
+  if (Array.isArray(value)) {
+    const bounds = packPages(value.map((item, index) => {
+      const bytes = jsonBytes(item) + 1;
+      return bytes <= pageBytes ? { value: item, bytes } : { value: oversize(String(index), item), bytes: 0 };
+    }), pageBytes);
+    const bound = bounds[page - 1];
+    if (!bound) return page === 1 && value.length === 0 ? { pages: 1, value: [], range: { items: [0, 0] } } : undefined;
+    return { pages: bounds.length, value: bound.values, range: { items: [bound.from, bound.to] } };
+  }
+  if (isRecord(value)) {
+    const entries = Object.entries(value);
+    const bounds = packPages(entries.map(([key, entry]) => {
+      const bytes = jsonBytes(key) + jsonBytes(entry) + 2;
+      return { value: bytes <= pageBytes ? entry : oversize(key, entry), bytes: bytes <= pageBytes ? bytes : 0 };
+    }), pageBytes);
+    const bound = bounds[page - 1];
+    if (!bound) return page === 1 && entries.length === 0 ? { pages: 1, value: {}, range: { entries: [0, 0] } } : undefined;
+    const pageValue: { [key: string]: TJsonValue } = {};
+    entries.slice(bound.from, bound.to).forEach(([key], index) => {
+      pageValue[key] = bound.values[index];
+    });
+    return { pages: bounds.length, value: pageValue, range: { entries: [bound.from, bound.to] } };
+  }
+  if (typeof value === 'string') {
+    const slices: Array<[number, number]> = [];
+    for (let from = 0; from < value.length || slices.length === 0;) {
+      const slice = sliceWithin(value, from, pageBytes);
+      slices.push([from, slice.end]);
+      if (slice.end === from) break;
+      from = slice.end;
+    }
+    const slice = slices[page - 1];
+    if (!slice) return undefined;
+    return { pages: slices.length, value: value.slice(slice[0], slice[1]), range: { chars: slice } };
+  }
+  return page === 1 ? { pages: 1, value } : undefined;
+}
+
+/** Packs sized values into consecutive pages of at most `pageBytes`; a zero-sized value always fits. */
+function packPages(
+  sized: Array<{ value: TJsonValue; bytes: number }>,
+  pageBytes: number,
+): Array<{ from: number; to: number; values: TJsonValue[] }> {
+  const pages: Array<{ from: number; to: number; values: TJsonValue[] }> = [];
+  let current: { from: number; to: number; values: TJsonValue[] } | undefined;
+  let bytes = 0;
+  sized.forEach((entry, index) => {
+    // An oversize marker is small; give it room as if it were 256 bytes.
+    const entryBytes = entry.bytes === 0 ? 256 : entry.bytes;
+    if (!current || bytes + entryBytes > pageBytes) {
+      current = { from: index, to: index, values: [] };
+      pages.push(current);
+      bytes = 0;
+    }
+    current.values.push(entry.value);
+    current.to = index + 1;
+    bytes += entryBytes;
+  });
+  return pages;
+}
+
+/** The longest slice of `text` from `from` whose JSON encoding fits `maxBytes`, never splitting a surrogate pair. */
+function sliceWithin(text: string, from: number, maxBytes: number): { text: string; end: number } {
+  let low = from;
+  let high = text.length;
+  while (low < high) {
+    const middle = Math.ceil((low + high) / 2);
+    if (jsonBytes(text.slice(from, middle)) <= maxBytes) low = middle;
+    else high = middle - 1;
+  }
+  let end = low;
+  const last = text.charCodeAt(end - 1);
+  if (end > from && end < text.length && last >= 0xd800 && last <= 0xdbff) end--;
+  return { text: text.slice(from, end), end };
+}

package/ts/utils.storerules.ts

@@ -175,3 +175,18 @@ export function assertSameArchiveEvents(
     throw new Error(`Archive "${next.archiveId}" already exists with different events.`);
   }
 }
+
+/** The index of a session's stored results: their handles, oldest first. */
+export interface IFlexResultIndex {
+  handles: string[];
+}
+
+export function validateResultIndex(value: unknown): IFlexResultIndex {
+  assertRecord(value, '$resultIndex');
+  assertExactKeys(value, ['handles'], '$resultIndex');
+  const handles = value.handles;
+  if (!Array.isArray(handles) || !handles.every((handle) => typeof handle === 'string')) {
+    throw new FlexHarnessStoreFormatError('$resultIndex.handles must list handles.');
+  }
+  return { handles: [...handles] };
+}

package/ts/utils.tooloutput.ts

@@ -1,11 +1,11 @@
-import type { IFlexHarnessOptions, TFlexAgentToolSet } from './interfaces.js';
+import type { IFlexHarnessOptions, TFlexAgentToolSet, TJsonValue } from './interfaces.js';
 import { normalizeJsonValue } from './utils.json.js';
 
 interface IExecutableToolRecord extends Record<string, unknown> {
   execute?: (input: unknown, options: unknown) => unknown;
 }
 
-function isAsyncIterable(value: unknown): value is AsyncIterable<unknown> {
+export function isAsyncIterable(value: unknown): value is AsyncIterable<unknown> {
   return Boolean(
     value
     && (typeof value === 'object' || typeof value === 'function')
@@ -38,6 +38,8 @@ export function wrapToolSet(
   tools: TFlexAgentToolSet,
   limits: Required<NonNullable<IFlexHarnessOptions<unknown>['toolOutputLimits']>>,
   projectError: (error: unknown) => Error,
+  /** Bounds a final output that is not streamed, in place of normalizing it to `limits`. */
+  budget?: (output: unknown) => Promise<TJsonValue>,
 ): TFlexAgentToolSet {
   const wrapped: Record<string, unknown> = {};
   for (const [name, tool] of Object.entries(tools)) {
@@ -65,6 +67,11 @@ export function wrapToolSet(
               if (isAsyncIterable(value)) {
                 return normalizeAsyncIterable(value, limits, projectError);
               }
+              if (budget) {
+                return budget(value).catch((error: unknown) => {
+                  throw projectError(error);
+                });
+              }
               return normalizeJsonValue(value, limits);
             } catch (error) {
               throw projectError(error);

package/ts_stores_nosqldb/classes.nosqldbstores.ts

@@ -11,16 +11,19 @@ import type {
   IFlexProjectManagementWriteContext,
   IFlexProjectionSnapshotV3,
   IFlexProjectionStore,
+  IFlexResultStore,
   IFlexScopeSnapshot,
   IFlexScopeStore,
   IFlexToolJobStoreProvider,
   TFlexProjectionSnapshot,
   TFlexProjectManagementRecord,
+  TJsonValue,
 } from '../ts/interfaces.js';
 import {
   assertFlexPermissionSnapshot,
   assertFlexProjectionSnapshot,
   assertFlexScopeSnapshot,
+  assertJsonSerializable,
 } from '../ts/utils.json.js';
 import {
   assertFlexProjectManagementRecord,
@@ -44,6 +47,7 @@ import {
   validateExpectedRevision,
   validateIdentifier,
   validateProjectManagementWriteContext,
+  validateResultIndex,
   validateSnapshotSave,
 } from '../ts/utils.storerules.js';
 import { FlexRecordStore, type IFlexRecordWrite } from './classes.recordstore.js';
@@ -297,7 +301,7 @@ class NoSqlAgentEventStore implements plugins.IAgentEventStoreV2 {
       domain: 'agentEventArchive' as const,
       storageKey: this.storageKey,
       sessionId: this.sessionId,
-      archiveId: archive.archiveId,
+      entryId: archive.archiveId,
     };
     await this.records.mutate(address, {
       validate: (value) => validateAgentEventArchive(value, this.sessionId, archive.archiveId),
@@ -318,7 +322,7 @@ class NoSqlAgentEventStore implements plugins.IAgentEventStoreV2 {
     this.assertSession(sessionId);
     validateIdentifier(archiveId, 'archiveId');
     return this.records.read(
-      { domain: 'agentEventArchive', storageKey: this.storageKey, sessionId, archiveId },
+      { domain: 'agentEventArchive', storageKey: this.storageKey, sessionId, entryId: archiveId },
       (value) => validateAgentEventArchive(value, this.sessionId, archiveId),
     );
   }
@@ -428,6 +432,66 @@ export interface INoSqlFlexHarnessStoresOptions {
   operationTimeoutMs?: number;
 }
 
+/**
+ * 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
+ * is deleted.
+ */
+class NoSqlResultStore implements IFlexResultStore {
+  constructor(private readonly records: FlexRecordStore) {}
+
+  public async save(storageKey: string, sessionId: string, handle: string, value: TJsonValue): Promise<void> {
+    validateIdentifier(handle, 'handle');
+    assertJsonSerializable(value);
+    const conflict = () => new FlexHarnessStoreConflictError(`${providerKey(storageKey, sessionId)}:${handle}`, 0, 1);
+    await this.records.mutate({ domain: 'result', storageKey, sessionId, entryId: handle }, {
+      validate: validateResult,
+      decide: (current) => {
+        if (current !== undefined) throw conflict();
+        return { revision: 1, value };
+      },
+      contention: conflict,
+    });
+    await this.changeIndex(storageKey, sessionId, (handles) => [...handles, handle]);
+  }
+
+  public load(storageKey: string, sessionId: string, handle: string): Promise<TJsonValue | undefined> {
+    validateIdentifier(handle, 'handle');
+    return this.records.read({ domain: 'result', storageKey, sessionId, entryId: handle }, validateResult);
+  }
+
+  public async list(storageKey: string, sessionId: string): Promise<string[]> {
+    const index = await this.records.read({ domain: 'result', storageKey, sessionId }, validateResultIndex);
+    return index?.handles ?? [];
+  }
+
+  public async delete(storageKey: string, sessionId: string, handle: string): Promise<void> {
+    validateIdentifier(handle, 'handle');
+    await this.changeIndex(storageKey, sessionId, (handles) => handles.filter((entry) => entry !== handle));
+    await this.records.delete({ domain: 'result', storageKey, sessionId, entryId: handle });
+  }
+
+  public deleteSession(storageKey: string, sessionId: string): Promise<void> {
+    return this.records.deleteOwner(storageKey, sessionId, ['result']);
+  }
+
+  /** The session's index record: the result records' handles, without an entry of its own. */
+  private changeIndex(storageKey: string, sessionId: string, change: (handles: string[]) => string[]): Promise<void> {
+    const contention = () => new Error(`The result index of session "${sessionId}" is contended by concurrent writers.`);
+    return this.records.mutate({ domain: 'result', storageKey, sessionId }, {
+      validate: validateResultIndex,
+      // The write token fences concurrent writers; the index keeps no revision of its own.
+      decide: (current) => ({ revision: 1, value: { handles: change(current?.handles ?? []) } }),
+      contention,
+    });
+  }
+}
+
+function validateResult(value: unknown): TJsonValue {
+  assertJsonSerializable(value);
+  return value as 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
@@ -440,6 +504,7 @@ export class NoSqlFlexHarnessStores implements IFlexHarnessStores {
   public readonly projectManagement: IFlexProjectManagementStore;
   public readonly agentEvents: IFlexAgentEventStoreProvider;
   public readonly jobs: IFlexToolJobStoreProvider;
+  public readonly results: IFlexResultStore;
   private readonly records: FlexRecordStore;
 
   constructor(options: INoSqlFlexHarnessStoresOptions) {
@@ -453,6 +518,7 @@ export class NoSqlFlexHarnessStores implements IFlexHarnessStores {
     this.projectManagement = new NoSqlProjectManagementStore(this.records);
     this.agentEvents = new NoSqlAgentEventStoreProvider(this.records);
     this.jobs = new NoSqlToolJobStoreProvider(this.records);
+    this.results = new NoSqlResultStore(this.records);
   }
 
   /**

package/ts_stores_nosqldb/classes.recordstore.ts

@@ -12,14 +12,16 @@ export type TFlexRecordDomain =
   | 'projectManagement'
   | 'agentEvents'
   | 'agentEventArchive'
-  | 'jobs';
+  | 'jobs'
+  | 'result';
 
-/** Names one record: a domain snapshot of a storage key, a session or an archive. */
+/** Names one record: a domain snapshot of a storage key or a session, or one entry of a session. */
 export interface IFlexRecordAddress {
   domain: TFlexRecordDomain;
   storageKey: string;
   sessionId?: string;
-  archiveId?: string;
+  /** The archive or result the record holds. */
+  entryId?: string;
 }
 
 /** The next stored value a mutation decided on. */
@@ -256,7 +258,7 @@ export class FlexRecordStore {
       address.domain,
       address.storageKey,
       address.sessionId ?? null,
-      address.archiveId ?? null,
+      address.entryId ?? null,
     ]));
     return {
       recordId,
@@ -295,6 +297,13 @@ export class FlexRecordStore {
     throw mutation.contention(actualRevision);
   }
 
+  /** Deletes one record and its chunks. */
+  public async delete(address: IFlexRecordAddress): Promise<void> {
+    await this.prepare();
+    const resolved = this.resolve(address);
+    await this.deleteInTransaction(resolved.path, { recordId: resolved.recordId, domain: resolved.domain });
+  }
+
   /** Deletes every record and chunk one session owns in the given domains. */
   public async deleteOwner(
     storageKey: string,
@@ -322,6 +331,7 @@ export class FlexRecordStore {
   private async deleteInTransaction(
     path: string,
     selector:
+      | { recordId: string; domain: TFlexRecordDomain }
       | { ownerKey: string; domain: { $in: TFlexRecordDomain[] } }
       | { namespaceKey: string; domain: TFlexRecordDomain },
   ): Promise<void> {

package/ts_typedrequest/catalog.ts

@@ -0,0 +1,91 @@
+import * as plugins from './plugins.js';
+import type { IFlexCatalogMethod, IFlexCatalogRunContext, IFlexToolCatalog } from '@modelprofile.com/flexharness';
+import type {
+  IFlexTypedRequestCatalogOptions,
+  IFlexTypedRequestMethod,
+  IFlexTypedRequestSurface,
+} from './interfaces.js';
+
+/**
+ * A typed request the router refused: the `text` and `data` of its error, as a client of the API
+ * would receive them. A host's `externalErrorProjector` decides what of it the model sees.
+ */
+export class FlexTypedRequestError extends Error {
+  constructor(
+    /** The typed method: `getVoucher`. */
+    public readonly method: string,
+    /** The error's text, such as a `TypedResponseError`'s message. */
+    public readonly text: string,
+    /** The error's data. */
+    public readonly data?: unknown,
+  ) {
+    super(`${method} was refused: ${text}`);
+    this.name = 'FlexTypedRequestError';
+  }
+}
+
+/**
+ * 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. A refusal rejects with `FlexTypedRequestError`.
+ */
+export function catalogFromTypedRequests<TScope = unknown>(
+  surface: IFlexTypedRequestSurface,
+  options: IFlexTypedRequestCatalogOptions<TScope>,
+): IFlexToolCatalog<TScope> {
+  if (typeof options?.router?.routeAndAddResponse !== 'function') {
+    throw new plugins.FlexHarnessValidationError('catalogFromTypedRequests needs a router with routeAndAddResponse().');
+  }
+  const aliases = options.aliases ?? {};
+  const known = new Set(surface.methods.map((method) => method.method));
+  const unknown = Object.keys(aliases).filter((method) => !known.has(method));
+  if (unknown.length > 0) {
+    throw new plugins.FlexHarnessValidationError(`The surface has no method ${unknown.join(', ')} to give aliases.`);
+  }
+  if (surface.omit.length > 0 && !options.request) {
+    throw new plugins.FlexHarnessValidationError(
+      `The surface leaves ${surface.omit.join(', ')} out of every request; the options' request() must fill them.`,
+    );
+  }
+  const include = options.include ?? ((method: IFlexTypedRequestMethod) => !method.deprecated);
+  const { router } = options;
+  const call = async (
+    method: IFlexTypedRequestMethod,
+    params: Record<string, unknown>,
+    context: IFlexCatalogRunContext<TScope>,
+  ): Promise<unknown> => {
+    const filled = options.request ? await options.request(method, context) : {};
+    const localData = options.localData ? await options.localData(method, context) : undefined;
+    const answer = await router.routeAndAddResponse(
+      {
+        method: method.method,
+        request: { ...params, ...filled },
+        response: {},
+        correlation: { id: plugins.crypto.randomUUID(), phase: 'request' },
+      },
+      { ...(localData ? { trustedLocalData: localData } : {}), trustedAbortSignal: context.abortSignal },
+    );
+    if (!answer) throw new FlexTypedRequestError(method.method, 'The router answered nothing.');
+    if (answer.error) throw new FlexTypedRequestError(method.method, answer.error.text, answer.error.data);
+    return answer.response;
+  };
+  return {
+    methods: surface.methods.filter((method) => include(method)).map((method): IFlexCatalogMethod<TScope> => ({
+      method: method.path,
+      summary: method.summary,
+      ...(method.description ? { description: method.description } : {}),
+      ...(aliases[method.method] ? { aliases: aliases[method.method] } : {}),
+      inputSchema: method.inputSchema,
+      outputSchema: method.outputSchema,
+      declaration: method.declaration,
+      run: (params: Record<string, unknown>, context) => call(method, params, context),
+      ...(options.onCall
+        ? { onCall: (params: Record<string, unknown>, context: IFlexCatalogRunContext<TScope>) => options.onCall!(method, params, context) }
+        : {}),
+    })),
+    types: surface.types,
+    ...(options.vocabulary ? { vocabulary: options.vocabulary } : {}),
+    ...(options.onProposals ? { onProposals: options.onProposals } : {}),
+  };
+}