@modelprofile.com/flexharness 10.15.0 → 10.16.0

package/ts/classes.stores.ts

@@ -16,9 +16,11 @@ import type {
   IFlexProjectManagementWriteContext,
   IFlexProjectionSnapshotV3,
   IFlexProjectionStore,
+  IFlexResultStore,
   IFlexScopeSnapshot,
   IFlexScopeStore,
   IFlexToolJobStoreProvider,
+  TJsonValue,
   TFlexProjectionSnapshot,
   TFlexProjectManagementRecord,
 } from './interfaces.js';
@@ -336,6 +338,28 @@ class InMemoryToolJobStoreProvider implements IFlexToolJobStoreProvider {
   }
 }
 
+class InMemoryResultStore implements IFlexResultStore {
+  private readonly sessions = new Map<string, Map<string, TJsonValue>>();
+
+  public async save(storageKey: string, sessionId: string, handle: string, value: TJsonValue): Promise<void> {
+    validateIdentifier(handle, 'handle');
+    const key = providerKey(storageKey, sessionId);
+    const results = this.sessions.get(key) ?? new Map<string, TJsonValue>();
+    if (results.has(handle)) throw new FlexHarnessStoreConflictError(`${key}:${handle}`, 0, 1);
+    results.set(handle, cloneSerializable(value));
+    this.sessions.set(key, results);
+  }
+
+  public async load(storageKey: string, sessionId: string, handle: string): Promise<TJsonValue | undefined> {
+    const value = this.sessions.get(providerKey(storageKey, sessionId))?.get(handle);
+    return value === undefined ? undefined : cloneSerializable(value);
+  }
+
+  public async deleteSession(storageKey: string, sessionId: string): Promise<void> {
+    this.sessions.delete(providerKey(storageKey, sessionId));
+  }
+}
+
 export class InMemoryFlexHarnessStores implements IFlexHarnessStores {
   public readonly scopes: IFlexScopeStore = new InMemoryScopeStore();
   public readonly projections: IFlexProjectionStore = new InMemoryProjectionStore();
@@ -343,6 +367,7 @@ export class InMemoryFlexHarnessStores implements IFlexHarnessStores {
   public readonly agentEvents: IFlexAgentEventStoreProvider = new InMemoryAgentEventStoreProvider();
   public readonly jobs: IFlexToolJobStoreProvider = new InMemoryToolJobStoreProvider();
   public readonly projectManagement = new InMemoryFlexProjectManagementStore();
+  public readonly results: IFlexResultStore = new InMemoryResultStore();
 }
 
 const jsonDomains = [
@@ -353,6 +378,7 @@ const jsonDomains = [
   'events',
   'archives',
   'jobs',
+  'results',
 ] as const;
 type TJsonDomain = (typeof jsonDomains)[number];
 
@@ -433,6 +459,17 @@ class JsonFileRoot {
     );
   }
 
+  public resultPath(storageKey: string, sessionId: string, handle: string): string {
+    validateIdentifier(handle, 'handle');
+    return plugins.path.join(this.resultSessionPath(storageKey, sessionId), `${this.digest(handle)}.json`);
+  }
+
+  public resultSessionPath(storageKey: string, sessionId: string): string {
+    validateIdentifier(storageKey, 'storageKey');
+    validateIdentifier(sessionId, 'sessionId');
+    return plugins.path.join(this.directory, 'results', this.digest(storageKey), this.digest(sessionId));
+  }
+
   public eventQueueKey(storageKey: string, sessionId: string): string {
     return `event:${this.sessionPath('events', storageKey, sessionId)}`;
   }
@@ -851,6 +888,33 @@ class JsonPermissionStore implements IFlexPermissionStore {
   }
 }
 
+class JsonResultStore implements IFlexResultStore {
+  constructor(private readonly root: JsonFileRoot) {}
+
+  public async save(storageKey: string, sessionId: string, handle: string, value: TJsonValue): Promise<void> {
+    const filePath = this.root.resultPath(storageKey, sessionId, handle);
+    await JsonFileRoot.inQueue(filePath, async () => {
+      if (await this.root.read(filePath, (stored) => stored) !== undefined) {
+        throw new FlexHarnessStoreConflictError(`${providerKey(storageKey, sessionId)}:${handle}`, 0, 1);
+      }
+      await this.root.write(filePath, value);
+    });
+  }
+
+  public async load(storageKey: string, sessionId: string, handle: string): Promise<TJsonValue | undefined> {
+    const filePath = this.root.resultPath(storageKey, sessionId, handle);
+    return JsonFileRoot.inQueue(filePath, () => this.root.read(filePath, (value) => {
+      assertJsonSerializable(value);
+      return value as TJsonValue;
+    }));
+  }
+
+  public async deleteSession(storageKey: string, sessionId: string): Promise<void> {
+    const directory = this.root.resultSessionPath(storageKey, sessionId);
+    await JsonFileRoot.inQueue(`results:${directory}`, () => this.root.deleteDirectory(directory));
+  }
+}
+
 class JsonProjectManagementStore implements IFlexProjectManagementStore {
   constructor(private readonly root: JsonFileRoot) {}
 
@@ -1186,6 +1250,7 @@ export class JsonFileFlexHarnessStores implements IFlexHarnessStores {
   public readonly agentEvents: IFlexAgentEventStoreProvider;
   public readonly jobs: IFlexToolJobStoreProvider;
   public readonly projectManagement: IFlexProjectManagementStore;
+  public readonly results: IFlexResultStore;
   private readonly root: JsonFileRoot;
 
   constructor(options: IJsonFileFlexHarnessStoresOptions) {
@@ -1199,6 +1264,7 @@ export class JsonFileFlexHarnessStores implements IFlexHarnessStores {
     this.projectManagement = new JsonProjectManagementStore(this.root);
     this.agentEvents = new JsonAgentEventStoreProvider(this.root);
     this.jobs = new JsonToolJobStoreProvider(this.root);
+    this.results = new JsonResultStore(this.root);
   }
 
   public dispose(): Promise<void> {

package/ts/classes.toolcatalog.ts

@@ -2,6 +2,7 @@ import * as plugins from './plugins.js';
 import { FlexHarnessValidationError } from './errors.js';
 import {
   FLEX_CODE_MODE_TOOL_NAME,
+  FLEX_RESULT_METHOD,
   FLEX_TOOL_CATALOG_LIMITS as limits,
   FLEX_TOOL_CATALOG_TOOL_NAMES as toolNames,
   type IFlexCatalogProposal,
@@ -66,6 +67,7 @@ interface IMethodEntry {
   readonly declaration?: string;
   readonly run: IFlexCatalogMethod['run'];
   readonly onCall?: NonNullable<IFlexCatalogMethod['onCall']>;
+  readonly readOnly: boolean;
 }
 
 interface ITypeEntry {
@@ -115,6 +117,7 @@ const declaredTypesLine = /^\/\/ Declares types: (.*)$/gm;
 const identifierScanPattern = /[A-Za-z_$][A-Za-z0-9_$]*/g;
 const methodKeys = new Set([
   'method', 'summary', 'description', 'tags', 'aliases', 'examples', 'inputSchema', 'outputSchema', 'declaration', 'run', 'onCall',
+  'readOnly',
 ]);
 const catalogKeys = new Set(['methods', 'types', 'vocabulary', 'onProposals']);
 const typeKeys = new Set(['name', 'description', 'schema', 'declaration']);
@@ -136,7 +139,58 @@ const clearMatchMargin = 1.25;
 type TSearchField = keyof typeof fieldWeights;
 const bm25K1 = 1.2;
 const bm25B = 0.75;
-const coreCache = new WeakMap<object, Map<TDeclarationMode, Promise<FlexToolCatalogCore>>>();
+const coreCache = new WeakMap<object, Map<string, Promise<FlexToolCatalogCore>>>();
+
+/** The catalog with `results.get` added; a catalog of its own cannot define it. */
+function withResultsMethod(catalog: IFlexToolCatalog<any>): IFlexToolCatalog<any> {
+  const methods = Array.isArray(catalog.methods) ? catalog.methods : [];
+  if (methods.some((method) => isPlainObject(method) && method.method === FLEX_RESULT_METHOD)) {
+    throw new FlexHarnessValidationError(`Tool catalog method "${FLEX_RESULT_METHOD}" is reserved for stored results.`);
+  }
+  return { ...catalog, methods: [...methods, resultsMethod] };
+}
+
+/**
+ * `results.get`, which reads a stored result. FlexHarness serves its calls itself; the entry gives
+ * it a declaration and parameter validation like any method. Search and namespace listings leave it
+ * out: the result handle names it.
+ */
+const resultsMethod: IFlexCatalogMethod = {
+  method: FLEX_RESULT_METHOD,
+  summary: 'Read a page of a tool result that was too large to return whole.',
+  description: 'A result too large for the output budget comes back as { $flexType: "result", handle, summary, pages }. '
+    + 'This reads one page of it, or of the value at `path`, a dotted path such as "items.3.lines". Each page holds '
+    + 'whole array items, object entries or a slice of a string; a part too large for a page stands as '
+    + '{ $flexType: "oversize", path } to read by its path.',
+  readOnly: true,
+  inputSchema: {
+    type: 'object',
+    properties: {
+      handle: { type: 'string', minLength: 1, maxLength: 64, description: 'The handle of the stored result.' },
+      page: { type: 'integer', minimum: 1, description: 'The page to read, from 1. Defaults to 1.' },
+      path: { type: 'string', maxLength: 512, description: 'A dotted path into the result. Defaults to the whole result.' },
+    },
+    required: ['handle'],
+    additionalProperties: false,
+  },
+  outputSchema: {
+    type: 'object',
+    properties: {
+      handle: { type: 'string' },
+      path: { type: 'string' },
+      page: { type: 'integer' },
+      pages: { type: 'integer' },
+      items: { type: 'array', items: { type: 'integer' }, description: 'The array items the page holds, [from, to).' },
+      entries: { type: 'array', items: { type: 'integer' }, description: 'The object entries the page holds, [from, to).' },
+      chars: { type: 'array', items: { type: 'integer' }, description: 'The string characters the page holds, [from, to).' },
+      value: {},
+    },
+    required: ['handle', 'path', 'page', 'pages', 'value'],
+  },
+  run: () => {
+    throw new FlexHarnessValidationError(`${FLEX_RESULT_METHOD} is served by the session that stored the result.`);
+  },
+};
 
 const isPlainObject = (value: unknown): value is Record<string, unknown> =>
   typeof value === 'object'
@@ -516,11 +570,17 @@ class FlexToolCatalogCore {
     public readonly typeIdentifiers: ReadonlyMap<string, string>,
     vocabulary: readonly IVocabularyEntry[],
     public readonly onProposals: IFlexToolCatalog['onProposals'] | undefined,
+    /** Built-in methods that search and namespace listings leave out. */
+    public readonly unlisted: ReadonlySet<string> = new Set(),
   ) {
-    this.index = new CatalogSearchIndex([...methods.values()], vocabulary);
+    this.index = new CatalogSearchIndex([...methods.values()].filter((entry) => !unlisted.has(entry.path)), vocabulary);
   }
 
-  public static async build(catalog: unknown, mode: TDeclarationMode): Promise<FlexToolCatalogCore> {
+  public static async build(
+    catalog: unknown,
+    mode: TDeclarationMode,
+    unlisted: ReadonlySet<string> = new Set(),
+  ): Promise<FlexToolCatalogCore> {
     if (!isPlainObject(catalog)) throw new FlexHarnessValidationError('A tool catalog must be a plain object.');
     const unsupported = Object.keys(catalog).find((key) => !catalogKeys.has(key));
     if (unsupported) throw new FlexHarnessValidationError(`A tool catalog does not support "${unsupported}".`);
@@ -645,6 +705,7 @@ class FlexToolCatalogCore {
       onProposals === undefined
         ? undefined
         : (proposals, context) => (onProposals as NonNullable<IFlexToolCatalog['onProposals']>).call(catalog, proposals, context),
+      unlisted,
     );
   }
 
@@ -731,6 +792,9 @@ class FlexToolCatalogCore {
     if (value.onCall !== undefined && typeof value.onCall !== 'function') {
       throw new FlexHarnessValidationError(`${methodLabel} onCall must be a function.`);
     }
+    if (value.readOnly !== undefined && typeof value.readOnly !== 'boolean') {
+      throw new FlexHarnessValidationError(`${methodLabel} readOnly must be a boolean.`);
+    }
     if (value.inputSchema === undefined) throw new FlexHarnessValidationError(`${methodLabel} needs an inputSchema.`);
     const input = await resolveCatalogSchema(value.inputSchema, `${methodLabel} inputSchema`);
     const inputJson = input.json;
@@ -762,6 +826,7 @@ class FlexToolCatalogCore {
       ...(onCall === undefined ? {} : {
         onCall: (params: unknown, context: IFlexCatalogRunContext) => onCall.call(value, params, context),
       }),
+      readOnly: value.readOnly === true,
     };
   }
 
@@ -987,6 +1052,8 @@ export class FlexToolCatalog<TScope = unknown> {
   public static async create<TScope = unknown>(
     catalog: IFlexToolCatalog<TScope>,
     options: IFlexToolCatalogOptions = {},
+    /** `results`: adds `results.get`, for a FlexHarness run that stores results. */
+    builtIns: { results?: boolean } = {},
   ): Promise<FlexToolCatalog<TScope>> {
     const normalized = normalizeToolCatalogOptions(options);
     const mode = normalized.declarations;
@@ -998,10 +1065,13 @@ export class FlexToolCatalog<TScope = unknown> {
       byMode = new Map();
       coreCache.set(catalog, byMode);
     }
-    let core = byMode.get(mode);
+    const key = builtIns.results ? `${mode}+results` : mode;
+    let core = byMode.get(key);
     if (!core) {
-      core = FlexToolCatalogCore.build(catalog, mode);
-      byMode.set(mode, core);
+      core = builtIns.results
+        ? FlexToolCatalogCore.build(withResultsMethod(catalog), mode, new Set([FLEX_RESULT_METHOD]))
+        : FlexToolCatalogCore.build(catalog, mode);
+      byMode.set(key, core);
     }
     return new FlexToolCatalog<TScope>(
       await core,
@@ -1038,6 +1108,16 @@ export class FlexToolCatalog<TScope = unknown> {
     return this.core.methods.has(path) && this.isAdmitted(path);
   }
 
+  /** Whether the method at `path` declared that it only reads. */
+  public isReadOnly(path: string): boolean {
+    return this.has(path) && this.core.methods.get(path)!.readOnly;
+  }
+
+  /** Whether the method at `path` decides each call with `onCall`. */
+  public decides(path: string): boolean {
+    return this.has(path) && this.core.methods.get(path)!.onCall !== undefined;
+  }
+
   /**
    * The built-in tools as the model sees them: the three catalog tools, and `run_code` in code
    * mode. Their text depends only on the catalog and its options.
@@ -1330,7 +1410,7 @@ export class FlexToolCatalog<TScope = unknown> {
     };
     node('');
     for (const entry of this.core.methods.values()) {
-      if (!this.isAdmitted(entry.path)) continue;
+      if (!this.isAdmitted(entry.path) || this.core.unlisted.has(entry.path)) continue;
       node(entry.namespace).methods.push(entry);
       const segments = entry.path.split('.');
       for (let depth = 1; depth < segments.length; depth++) {

package/ts/interfaces.ts

@@ -139,6 +139,11 @@ export interface IFlexToolMessagePart {
   childSessionId?: string;
   /** For a catalog call a `run_code` program made: the `run_code` call's ID. */
   parentToolCallId?: string;
+  /**
+   * For a read-only call an identical read earlier in the turn answered: that call's ID. The call
+   * did not run; its output is the earlier call's.
+   */
+  deduplicatedFrom?: string;
   model?: IFlexModelIdentity;
   /** ISO time the tool call began. Absent on parts recorded before part times existed. */
   startedAt?: string;
@@ -660,6 +665,14 @@ export interface IFlexToolHandle<TScope = unknown> {
    * every run: FlexHarness prepares a catalog once per object and treats it as immutable.
    */
   catalog?: IFlexToolCatalog<TScope>;
+  /**
+   * Tells read-only calls apart, by the tool's name or a catalog method's path and the call's
+   * input or params: they have no effect but their result. They run concurrently, may start while
+   * the model still streams its response, and a turn answers identical ones once. Every other call
+   * runs in the order the model made it, after the calls before it. A catalog method's `readOnly`
+   * declaration needs no classifier. It may be asked more than once about one call.
+   */
+  isReadOnlyToolCall?(call: { toolName: string; input: unknown }): boolean;
   close?(): Promise<void> | void;
 }
 
@@ -669,6 +682,29 @@ export interface IFlexToolProvider<TScope> {
   ): Promise<IFlexToolHandle<TScope> | undefined> | IFlexToolHandle<TScope> | undefined;
 }
 
+/** The catalog method that reads stored results, reserved while a run stores results. */
+export const FLEX_RESULT_METHOD = 'results.get';
+
+export const FLEX_RESULT_LIMITS = Object.freeze({
+  /** The most of one output a result stores; beyond it the stored value is truncated. */
+  maxStoredBytes: 8 * 1024 * 1024,
+  /** The size of the summary the model gets in place of the output. */
+  summaryBytes: 2 * 1024,
+});
+
+/** What the model gets in place of an output over the budget. */
+export interface IFlexResultHandle {
+  $flexType: 'result';
+  handle: string;
+  /** The stored output's size as JSON. */
+  bytes: number;
+  /** The pages `results.get` reads the whole output in. */
+  pages: number;
+  summary: TJsonValue;
+  /** How to read it. */
+  read: string;
+}
+
 /** The names of the built-in catalog tools, reserved while a run has a catalog. */
 export const FLEX_TOOL_CATALOG_TOOL_NAMES = Object.freeze({
   search: 'search_tools',
@@ -826,6 +862,14 @@ export interface IFlexCatalogMethod<TScope = unknown, TParams = any, TResult = u
     params: TParams,
     context: IFlexCatalogRunContext<TScope>,
   ): TResult | PromiseLike<TResult> | AsyncIterable<TResult>;
+  /**
+   * The method only reads: it has no effect but its result. Its calls run concurrently with other
+   * read-only calls, `execute` may start one while the model still streams its response, and a
+   * turn answers identical calls once. Calls of other methods, and of a method with `onCall`, run
+   * in the order the model made them. A method that asks for permission is best left undeclared:
+   * the prompts of concurrent calls would overlap.
+   */
+  readOnly?: boolean;
   /**
    * Decides each validated call before it runs: `run` (the default without this hook), `propose`
    * to hand it to the catalog's `onProposals` instead of running it, or `{ deny }` to refuse it.
@@ -1386,6 +1430,16 @@ export interface IFlexToolJobStoreProvider {
   deleteSession(storageKey: string, sessionId: string): Promise<void>;
 }
 
+/**
+ * Tool outputs over the output budget, stored whole for the session that produced them. A result
+ * is written once under its handle and read by `results.get`.
+ */
+export interface IFlexResultStore {
+  save(storageKey: string, sessionId: string, handle: string, value: TJsonValue): Promise<void>;
+  load(storageKey: string, sessionId: string, handle: string): Promise<TJsonValue | undefined>;
+  deleteSession(storageKey: string, sessionId: string): Promise<void>;
+}
+
 export interface IFlexHarnessStores {
   scopes: IFlexScopeStore;
   projections: IFlexProjectionStore;
@@ -1393,6 +1447,12 @@ export interface IFlexHarnessStores {
   projectManagement: IFlexProjectManagementStore;
   agentEvents: IFlexAgentEventStoreProvider;
   jobs: IFlexToolJobStoreProvider;
+  /**
+   * Stores the outputs of a run with a tool catalog that exceed the output budget: the model gets a
+   * summary and a handle it reads with `results.get`. Without it, such outputs are truncated to
+   * the budget. The built-in stores provide it.
+   */
+  results?: IFlexResultStore;
 }
 
 export interface IFlexJsonLimits {

package/ts/plugins.ts

@@ -97,6 +97,7 @@ import {
   AgentPendingInputQueue,
   AgentPendingInputRejectedError,
   AgentSession,
+  AgentToolCallScheduler,
   buildModelMessages,
   ToolJobStoreConflictError,
   createAgentEvent,
@@ -115,6 +116,7 @@ export {
   AgentPendingInputQueue,
   AgentPendingInputRejectedError,
   AgentSession,
+  AgentToolCallScheduler,
   buildModelMessages,
   ToolJobStoreConflictError,
   createAgentEvent,
@@ -142,6 +144,7 @@ export type {
   IAgentSession,
   IAgentSessionOptions,
   IAgentToolCallUpdateEvent,
+  IAgentToolExecutionOptions,
   IAgentRuntimeEventPayload,
   IGenerationBegunEvent,
   IGenerationExecutionCompletedEvent,

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.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);