@modelprofile.com/flexharness 10.15.1 → 10.17.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';
@@ -50,6 +52,7 @@ import {
   providerKey,
   validateExpectedRevision,
   validateIdentifier,
+  validateResultIndex,
   validateProjectManagementWriteContext,
   validateSnapshotSave,
 } from './utils.storerules.js';
@@ -336,6 +339,36 @@ 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 list(storageKey: string, sessionId: string): Promise<string[]> {
+    return [...this.sessions.get(providerKey(storageKey, sessionId))?.keys() ?? []];
+  }
+
+  public async delete(storageKey: string, sessionId: string, handle: string): Promise<void> {
+    this.sessions.get(providerKey(storageKey, sessionId))?.delete(handle);
+  }
+
+  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 +376,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 +387,7 @@ const jsonDomains = [
   'events',
   'archives',
   'jobs',
+  'results',
 ] as const;
 type TJsonDomain = (typeof jsonDomains)[number];
 
@@ -433,6 +468,21 @@ 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 resultIndexPath(storageKey: string, sessionId: string): string {
+    return plugins.path.join(this.resultSessionPath(storageKey, sessionId), 'index.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 +901,63 @@ class JsonPermissionStore implements IFlexPermissionStore {
   }
 }
 
+/**
+ * One file per result and an index of the session's handles, oldest first. Every operation of a
+ * session runs in the session's queue, so the index follows the files.
+ */
+class JsonResultStore implements IFlexResultStore {
+  constructor(private readonly root: JsonFileRoot) {}
+
+  private inSessionQueue<T>(storageKey: string, sessionId: string, operation: () => Promise<T>): Promise<T> {
+    return JsonFileRoot.inQueue(`results:${this.root.resultSessionPath(storageKey, sessionId)}`, operation);
+  }
+
+  private readIndex(storageKey: string, sessionId: string): Promise<string[]> {
+    return this.root.read(this.root.resultIndexPath(storageKey, sessionId), validateResultIndex)
+      .then((index) => index?.handles ?? []);
+  }
+
+  public save(storageKey: string, sessionId: string, handle: string, value: TJsonValue): Promise<void> {
+    const filePath = this.root.resultPath(storageKey, sessionId, handle);
+    return this.inSessionQueue(storageKey, sessionId, 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);
+      const handles = await this.readIndex(storageKey, sessionId);
+      await this.root.write(this.root.resultIndexPath(storageKey, sessionId), { handles: [...handles, handle] });
+    });
+  }
+
+  public load(storageKey: string, sessionId: string, handle: string): Promise<TJsonValue | undefined> {
+    const filePath = this.root.resultPath(storageKey, sessionId, handle);
+    return this.inSessionQueue(storageKey, sessionId, () => this.root.read(filePath, (value) => {
+      assertJsonSerializable(value);
+      return value as TJsonValue;
+    }));
+  }
+
+  public list(storageKey: string, sessionId: string): Promise<string[]> {
+    return this.inSessionQueue(storageKey, sessionId, () => this.readIndex(storageKey, sessionId));
+  }
+
+  public delete(storageKey: string, sessionId: string, handle: string): Promise<void> {
+    return this.inSessionQueue(storageKey, sessionId, async () => {
+      const handles = await this.readIndex(storageKey, sessionId);
+      await this.root.write(
+        this.root.resultIndexPath(storageKey, sessionId),
+        { handles: handles.filter((entry) => entry !== handle) },
+      );
+      await this.root.deleteFile(this.root.resultPath(storageKey, sessionId, handle));
+    });
+  }
+
+  public deleteSession(storageKey: string, sessionId: string): Promise<void> {
+    const directory = this.root.resultSessionPath(storageKey, sessionId);
+    return this.inSessionQueue(storageKey, sessionId, () => this.root.deleteDirectory(directory));
+  }
+}
+
 class JsonProjectManagementStore implements IFlexProjectManagementStore {
   constructor(private readonly root: JsonFileRoot) {}
 
@@ -1186,6 +1293,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 +1307,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,
     };
   }
 
@@ -842,10 +907,13 @@ class FlexToolCatalogCore {
     if (cached) return cached;
     let rendered: IRenderedDeclaration;
     if (entry.declaration !== undefined) {
-      rendered = { text: entry.declaration.trim(), types: this.scanTypes(entry.declaration) };
-      // A host's declaration text does not tell parameters from the result: every type it names is
-      // declared with it.
-      this.methodTypeSets.set(entry.path, { input: rendered.types, output: [] });
+      // A host's declaration names its parameters' types in its parameter list and its result's after
+      // it; text that is no plain function declaration declares every type it names with it.
+      const parts = signatureParts(entry.declaration, entry.name);
+      const input = this.scanTypes(parts?.params ?? entry.declaration);
+      const output = parts ? this.scanTypes(parts.result) : [];
+      rendered = { text: entry.declaration.trim(), types: [...new Set([...input, ...output])].sort(compareCodePoints) };
+      this.methodTypeSets.set(entry.path, { input, output });
     } else {
       const inputWriter = new SchemaDeclarationWriter(this.scopeContext(entry.inputScope));
       const members = inputWriter.objectMembers(entry.input.json);
@@ -879,9 +947,10 @@ class FlexToolCatalogCore {
     return rendered;
   }
 
+  /** The catalog types a declaration's code names; its comments and string literals name none. */
   private scanTypes(text: string, self?: string): string[] {
     const found = new Set<string>();
-    for (const match of text.matchAll(identifierScanPattern)) {
+    for (const match of codeOf(text).matchAll(identifierScanPattern)) {
       if (match[0] !== self && this.types.has(match[0])) found.add(match[0]);
     }
     return [...found].sort(compareCodePoints);
@@ -980,6 +1049,16 @@ export class FlexToolCatalog<TScope = unknown> {
     private readonly describeTopMatch: boolean,
   ) {}
 
+  /**
+   * The identifier a name from elsewhere, such as a file or an API's method, is declared under as a
+   * path segment or a type: every other character `_`, `_` before a leading digit and after a
+   * reserved word (`export-jobs` becomes `export_jobs`, `delete` becomes `delete_`). The catalog
+   * maps type names that are no identifiers the same way.
+   */
+  public static identifierOf(name: string): string {
+    return typeIdentifierOf(name);
+  }
+
   /**
    * Prepares `catalog`. Preparing the same object again returns the cached preparation, so a host
    * that returns one catalog object for every run pays for it once.
@@ -987,6 +1066,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 +1079,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 +1122,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.
@@ -1210,7 +1304,7 @@ export class FlexToolCatalog<TScope = unknown> {
     const unknownTypes = requestedTypes.filter((name) => identifierOf(name) === undefined).sort(compareCodePoints);
     const notes = [
       ...unknownMethods.map((path) => {
-        const suggestions = closeMatches(path, this.methods);
+        const suggestions = closeMatches(path, this.listedMethods());
         return `Unknown method ${path}.${suggestions.length ? ` Did you mean ${suggestions.join(', ')}?` : ' Find methods with search_tools.'}`;
       }),
       ...unknownTypes.map((name) => {
@@ -1256,7 +1350,7 @@ export class FlexToolCatalog<TScope = unknown> {
         error: {
           error: 'unknown_method',
           method: path,
-          didYouMean: isNamespace ? [] : closeMatches(path, this.methods),
+          didYouMean: isNamespace ? [] : closeMatches(path, this.listedMethods()),
           hint: isNamespace
             ? `${path} is a namespace; list it with search_tools({"namespace":"${path}"}).`
             : 'Find methods with search_tools.',
@@ -1313,6 +1407,11 @@ export class FlexToolCatalog<TScope = unknown> {
     return { method: input.method, params: input.params === undefined ? {} : input.params };
   }
 
+  /** The method paths search and suggestions may name: built-ins such as `results.get` stay out. */
+  private listedMethods(): string[] {
+    return this.methods.filter((path) => !this.core.unlisted.has(path));
+  }
+
   private isAdmitted(path: string): boolean {
     return this.admitted === undefined || this.admitted.has(path);
   }
@@ -1330,7 +1429,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++) {
@@ -1700,6 +1799,70 @@ export const catalogToolInputSchema = <TInput>(definition: IFlexCatalogToolDefin
   });
 };
 
+/** Declaration text with its comments and the contents of its string literals blanked. */
+const codeOf = (text: string): string => {
+  let code = '';
+  for (let index = 0; index < text.length; index++) {
+    const char = text[index];
+    if (char === '/' && text[index + 1] === '/') {
+      const end = text.indexOf('\n', index);
+      index = (end === -1 ? text.length : end) - 1;
+      code += ' ';
+    } else if (char === '/' && text[index + 1] === '*') {
+      const end = text.indexOf('*/', index + 2);
+      index = end === -1 ? text.length : end + 1;
+      code += ' ';
+    } else if (char === '"' || char === "'" || char === '`') {
+      let end = index + 1;
+      while (end < text.length && text[end] !== char) end += text[end] === '\\' ? 2 : 1;
+      code += `${char}${char}`;
+      index = end;
+    } else {
+      code += char;
+    }
+  }
+  return code;
+};
+
+/** The index of the bracket that closes the one at `open`, or -1. */
+const closingBracket = (code: string, open: number): number => {
+  const pairs: Record<string, string> = { '(': ')', '<': '>', '{': '}', '[': ']' };
+  const stack: string[] = [];
+  for (let index = open; index < code.length; index++) {
+    const char = code[index];
+    if (char === '=' && code[index + 1] === '>') {
+      index++;
+    } else if (pairs[char] !== undefined && (char !== '<' || stack.length === 0 || stack[stack.length - 1] === '>')) {
+      stack.push(pairs[char]);
+    } else if (char === stack[stack.length - 1]) {
+      stack.pop();
+      if (stack.length === 0) return index;
+    }
+  }
+  return -1;
+};
+
+/**
+ * A host method declaration's parameter list and the result after it, as code without comments, or
+ * undefined where the text is no plain `function name(…): …` declaration.
+ */
+const signatureParts = (declaration: string, name: string): { params: string; result: string } | undefined => {
+  const code = codeOf(declaration);
+  const start = new RegExp(`\\bfunction\\s+${name}\\s*`).exec(code);
+  if (!start) return undefined;
+  let open = start.index + start[0].length;
+  if (code[open] === '<') {
+    const typeParameters = closingBracket(code, open);
+    if (typeParameters === -1) return undefined;
+    open = typeParameters + 1;
+    while (/\s/.test(code[open] ?? '')) open++;
+  }
+  if (code[open] !== '(') return undefined;
+  const close = closingBracket(code, open);
+  if (close === -1) return undefined;
+  return { params: code.slice(open + 1, close), result: code.slice(close + 1) };
+};
+
 /** A root-level method declaration gets `declare`, as a namespace member does not need it. */
 const withDeclare = (text: string): string => {
   const lines = text.split('\n');

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,31 @@ 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 results a session keeps; a new one beyond them deletes the oldest. */
+  maxResultsPerSession: 32,
+  /** 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',
@@ -684,7 +722,7 @@ export const FLEX_TOOL_CATALOG_LIMITS = Object.freeze({
   maxIdentifierCharacters: 128,
   maxSummaryCharacters: 120,
   maxDescriptionBytes: 16 * 1024,
-  maxDeclarationBytes: 16 * 1024,
+  maxDeclarationBytes: 64 * 1024,
   maxTags: 16,
   maxTagCharacters: 48,
   maxAliases: 16,
@@ -826,6 +864,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 +1432,22 @@ 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`; FlexHarness keeps a session's latest
+ * `FLEX_RESULT_LIMITS.maxResultsPerSession` results and deletes older ones. A FlexHarness writes a
+ * session's results one operation at a time, so a store need not order concurrent writes of one
+ * session.
+ */
+export interface IFlexResultStore {
+  save(storageKey: string, sessionId: string, handle: string, value: TJsonValue): Promise<void>;
+  load(storageKey: string, sessionId: string, handle: string): Promise<TJsonValue | undefined>;
+  /** The handles of the session's results, oldest first. */
+  list(storageKey: string, sessionId: string): Promise<string[]>;
+  delete(storageKey: string, sessionId: string, handle: string): Promise<void>;
+  deleteSession(storageKey: string, sessionId: string): Promise<void>;
+}
+
 export interface IFlexHarnessStores {
   scopes: IFlexScopeStore;
   projections: IFlexProjectionStore;
@@ -1393,6 +1455,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,