@modelprofile.com/flexharness 10.16.0 → 10.17.0

package/dist_ts_typedrequest/describe.js

@@ -0,0 +1,189 @@
+import * as plugins from './plugins.js';
+const componentsPrefix = '#/components/schemas/';
+const definitionsPrefix = '#/$defs/';
+const maxSummaryCharacters = 120;
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+/** A schema whose references name `#/$defs/<type>` instead of the OpenAPI components. */
+const withDefinitionRefs = (value) => {
+    if (Array.isArray(value))
+        return value.map(withDefinitionRefs);
+    if (!isRecord(value))
+        return value;
+    return Object.fromEntries(Object.entries(value).map(([key, child]) => [
+        key,
+        key === '$ref' && typeof child === 'string' && child.startsWith(componentsPrefix)
+            ? `${definitionsPrefix}${child.slice(componentsPrefix.length)}`
+            : withDefinitionRefs(child),
+    ]));
+};
+/** The type a `#/$defs/<type>` reference names. */
+const referencedType = (schema) => typeof schema.$ref === 'string' && schema.$ref.startsWith(definitionsPrefix)
+    ? schema.$ref.slice(definitionsPrefix.length)
+    : undefined;
+/**
+ * A request schema without the omitted properties: an object loses them, and a reference to a
+ * named type that holds one becomes the type's own schema without them.
+ */
+const withoutOmitted = (schema, omit, types) => {
+    const target = referencedType(schema);
+    if (target !== undefined) {
+        const named = types[target];
+        return named !== undefined && holdsOmitted(named, omit, types, new Set([target]))
+            ? withoutOmitted(named, omit, types)
+            : schema;
+    }
+    const stripped = { ...schema };
+    if (isRecord(stripped.properties)) {
+        stripped.properties = Object.fromEntries(Object.entries(stripped.properties).filter(([key]) => !omit.has(key)));
+    }
+    if (Array.isArray(stripped.required)) {
+        stripped.required = stripped.required.filter((key) => typeof key !== 'string' || !omit.has(key));
+    }
+    for (const key of ['allOf', 'anyOf', 'oneOf']) {
+        const members = stripped[key];
+        if (Array.isArray(members)) {
+            stripped[key] = members.map((member) => isRecord(member) ? withoutOmitted(member, omit, types) : member);
+        }
+    }
+    return stripped;
+};
+/** Whether a schema has an omitted property, itself or through the schemas it composes or refers to. */
+const holdsOmitted = (schema, omit, types, seen) => {
+    if (isRecord(schema.properties) && Object.keys(schema.properties).some((key) => omit.has(key)))
+        return true;
+    const target = referencedType(schema);
+    if (target !== undefined) {
+        if (seen.has(target) || types[target] === undefined)
+            return false;
+        seen.add(target);
+        return holdsOmitted(types[target], omit, types, seen);
+    }
+    return ['allOf', 'anyOf', 'oneOf'].some((key) => Array.isArray(schema[key])
+        && schema[key].some((member) => isRecord(member) && holdsOmitted(member, omit, types, seen)));
+};
+/** Whether a call may leave out every parameter: its schema requires none. */
+const requiresNothing = (schema, types) => {
+    const target = referencedType(schema);
+    if (target !== undefined)
+        return types[target] === undefined || requiresNothing(types[target], types);
+    if (Array.isArray(schema.required) && schema.required.length > 0)
+        return false;
+    return !Array.isArray(schema.allOf)
+        || schema.allOf.every((member) => !isRecord(member) || requiresNothing(member, types));
+};
+/** The named types a schema refers to. */
+const referencesIn = (value, found) => {
+    if (Array.isArray(value)) {
+        for (const entry of value)
+            referencesIn(entry, found);
+    }
+    else if (isRecord(value)) {
+        const target = referencedType(value);
+        if (target !== undefined)
+            found.add(target);
+        for (const child of Object.values(value))
+            referencesIn(child, found);
+    }
+    return found;
+};
+/** The first sentence of a contract's JSDoc, its tags left out, within the summary's length. */
+const summaryOf = (documentation, method) => {
+    const prose = (documentation ?? '').split(/\n(?=@)/)[0].replace(/\s+/g, ' ').trim();
+    const sentence = prose.split(/(?<=[.!?])\s/)[0] ?? '';
+    if (!sentence)
+        return method;
+    return [...sentence].length <= maxSummaryCharacters
+        ? sentence
+        : `${[...sentence].slice(0, maxSummaryCharacters - 1).join('')}…`;
+};
+/** A JSDoc block of the given lines; `*\/` in them cannot end it early. */
+const docBlock = (lines) => {
+    const text = lines.join('\n').replace(/\*\//g, '*\\/');
+    return `/**\n${text.split('\n').map((line) => (line ? ` * ${line}` : ' *')).join('\n')}\n */\n`;
+};
+/** The area of a contract when the options name none: its file's base name, an `index` file's folder. */
+const defaultArea = (file) => {
+    const parsed = plugins.path.posix.parse(file);
+    return parsed.name === 'index' ? plugins.path.posix.basename(parsed.dir) || parsed.name : parsed.name;
+};
+/**
+ * Reads a typedrequest API's contracts from their TypeScript sources: each typed method's path
+ * (`<area>.<method>`), its summary and JSDoc, its request and response as JSON Schema for
+ * validation, and its TypeScript declaration as the contract writes it, for the model to read; and
+ * the named types they reach, each with its schema, its declaration, or both. Needs the optional
+ * peer `@api.global/typedopenapi`. Run it at build time and keep the JSON, or at startup where the
+ * sources are at hand.
+ */
+export async function describeTypedRequests(options) {
+    let typedopenapi;
+    try {
+        typedopenapi = await plugins.importTypedOpenApi();
+    }
+    catch (error) {
+        throw new plugins.FlexHarnessValidationError('describeTypedRequests needs the optional peer @api.global/typedopenapi (0.8.0 or later).', { cause: error });
+    }
+    const omit = [...new Set(options.omit ?? [])].sort();
+    const source = {
+        tsconfig: options.tsconfig,
+        contracts: options.contracts,
+        ...(options.contractNamePattern ? { contractNamePattern: options.contractNamePattern } : {}),
+    };
+    const schemaSet = typedopenapi.generateContractSchemas(source);
+    const declarationSet = typedopenapi.generateContractDeclarations({ ...source, omit });
+    const schemas = withDefinitionRefs(schemaSet.schemas);
+    const declarations = new Map(declarationSet.contracts.map((contract) => [contract.name, contract]));
+    const omitted = new Set(omit);
+    const paths = new Set();
+    const methods = schemaSet.contracts.map((contract) => {
+        const declared = declarations.get(contract.name);
+        if (!declared) {
+            throw new plugins.FlexHarnessValidationError(`@api.global/typedopenapi declared no contract ${contract.name}, whose schemas it generated.`);
+        }
+        const area = options.area ? options.area({ name: contract.name, method: contract.method, file: declared.file }) : defaultArea(declared.file);
+        const name = plugins.FlexToolCatalog.identifierOf(contract.method);
+        const base = `${plugins.FlexToolCatalog.identifierOf(area)}.${name}`;
+        let path = base;
+        for (let suffix = 2; paths.has(path); suffix++)
+            path = `${base}_${suffix}`;
+        paths.add(path);
+        const inputSchema = withoutOmitted(withDefinitionRefs(contract.request), omitted, schemas);
+        const docLines = [
+            ...(declared.documentation ? [declared.documentation] : []),
+            ...(declared.request.documentation ? [`@param params ${declared.request.documentation}`] : []),
+            ...(declared.response.documentation ? [`@returns ${declared.response.documentation}`] : []),
+        ];
+        const functionName = path.slice(path.lastIndexOf('.') + 1);
+        const optional = requiresNothing(inputSchema, schemas) ? '?' : '';
+        return {
+            method: contract.method,
+            path,
+            summary: summaryOf(declared.documentation, contract.method),
+            ...(declared.documentation ? { description: declared.documentation } : {}),
+            ...(contract.deprecated ? { deprecated: true } : {}),
+            inputSchema,
+            outputSchema: withDefinitionRefs(contract.response),
+            declaration: `${docLines.length ? docBlock(docLines) : ''}function ${functionName}(params${optional}: ${declared.request.type}): Promise<${declared.response.type}>;`,
+        };
+    }).sort((left, right) => (left.path < right.path ? -1 : left.path > right.path ? 1 : 0));
+    // Only the schemas the methods still reach: an omitted property's types are gone with it.
+    const reached = new Set();
+    const pending = [...referencesIn(methods.map((method) => [method.inputSchema, method.outputSchema]), new Set())];
+    while (pending.length) {
+        const name = pending.pop();
+        if (reached.has(name) || schemas[name] === undefined)
+            continue;
+        reached.add(name);
+        pending.push(...referencesIn(schemas[name], new Set()));
+    }
+    const names = [...new Set([...reached, ...Object.keys(declarationSet.types)])].sort();
+    return {
+        methods,
+        types: names.map((name) => ({
+            name,
+            ...(reached.has(name) ? { schema: schemas[name] } : {}),
+            ...(declarationSet.types[name] !== undefined ? { declaration: declarationSet.types[name] } : {}),
+        })),
+        omit,
+    };
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZGVzY3JpYmUuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi90c190eXBlZHJlcXVlc3QvZGVzY3JpYmUudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsT0FBTyxLQUFLLE9BQU8sTUFBTSxjQUFjLENBQUM7QUFReEMsTUFBTSxnQkFBZ0IsR0FBRyx1QkFBdUIsQ0FBQztBQUNqRCxNQUFNLGlCQUFpQixHQUFHLFVBQVUsQ0FBQztBQUNyQyxNQUFNLG9CQUFvQixHQUFHLEdBQUcsQ0FBQztBQUVqQyxNQUFNLFFBQVEsR0FBRyxDQUFDLEtBQWMsRUFBb0MsRUFBRSxDQUNwRSxPQUFPLEtBQUssS0FBSyxRQUFRLElBQUksS0FBSyxLQUFLLElBQUksSUFBSSxDQUFDLEtBQUssQ0FBQyxPQUFPLENBQUMsS0FBSyxDQUFDLENBQUM7QUFFdkUseUZBQXlGO0FBQ3pGLE1BQU0sa0JBQWtCLEdBQUcsQ0FBQyxLQUFjLEVBQVcsRUFBRTtJQUNyRCxJQUFJLEtBQUssQ0FBQyxPQUFPLENBQUMsS0FBSyxDQUFDO1FBQUUsT0FBTyxLQUFLLENBQUMsR0FBRyxDQUFDLGtCQUFrQixDQUFDLENBQUM7SUFDL0QsSUFBSSxDQUFDLFFBQVEsQ0FBQyxLQUFLLENBQUM7UUFBRSxPQUFPLEtBQUssQ0FBQztJQUNuQyxPQUFPLE1BQU0sQ0FBQyxXQUFXLENBQUMsTUFBTSxDQUFDLE9BQU8sQ0FBQyxLQUFLLENBQUMsQ0FBQyxHQUFHLENBQUMsQ0FBQyxDQUFDLEdBQUcsRUFBRSxLQUFLLENBQUMsRUFBRSxFQUFFLENBQUM7UUFDcEUsR0FBRztRQUNILEdBQUcsS0FBSyxNQUFNLElBQUksT0FBTyxLQUFLLEtBQUssUUFBUSxJQUFJLEtBQUssQ0FBQyxVQUFVLENBQUMsZ0JBQWdCLENBQUM7WUFDL0UsQ0FBQyxDQUFDLEdBQUcsaUJBQWlCLEdBQUcsS0FBSyxDQUFDLEtBQUssQ0FBQyxnQkFBZ0IsQ0FBQyxNQUFNLENBQUMsRUFBRTtZQUMvRCxDQUFDLENBQUMsa0JB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

package/dist_ts_typedrequest/index.d.ts

@@ -0,0 +1,3 @@
+export * from './interfaces.js';
+export { describeTypedRequests } from './describe.js';
+export { FlexTypedRequestError, catalogFromTypedRequests } from './catalog.js';

package/dist_ts_typedrequest/index.js

@@ -0,0 +1,4 @@
+export * from './interfaces.js';
+export { describeTypedRequests } from './describe.js';
+export { FlexTypedRequestError, catalogFromTypedRequests } from './catalog.js';
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi90c190eXBlZHJlcXVlc3QvaW5kZXgudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsY0FBYyxpQkFBaUIsQ0FBQztBQUNoQyxPQUFPLEVBQUUscUJBQXFCLEVBQUUsTUFBTSxlQUFlLENBQUM7QUFDdEQsT0FBTyxFQUFFLHFCQUFxQixFQUFFLHdCQUF3QixFQUFFLE1BQU0sY0FBYyxDQUFDIn0=

package/dist_ts_typedrequest/interfaces.d.ts

@@ -0,0 +1,107 @@
+import type { IFlexCatalogRunContext, IFlexCatalogType, IFlexToolCatalog, TFlexCatalogCallDecision } from '@modelprofile.com/flexharness';
+/** A JSON Schema of the surface, plain JSON; its `$ref`s name `#/$defs/<type>` of the surface's types. */
+export type TFlexTypedRequestSchema = Record<string, unknown>;
+/** Where to read a typedrequest API's contracts, and what of them the catalog takes. */
+export interface IFlexTypedRequestSurfaceOptions {
+    /** The `tsconfig.json` of the project that holds the contracts. */
+    tsconfig: string;
+    /** The contract files, or a glob of several: `ts_interfaces/requests/*.ts`. */
+    contracts: string;
+    /** The names of the exports that are contracts (default `/^IReq_/`). */
+    contractNamePattern?: RegExp;
+    /**
+     * Request properties the binding fills from the run instead of the model, such as the caller's
+     * identity or a CSRF token: left out of every request's schema and declaration.
+     */
+    omit?: readonly string[];
+    /**
+     * The namespace of a contract's method. Default: the base name of the file that declares it
+     * (`vouchers` for `requests/vouchers.ts`, the folder's name for an `index.ts`).
+     */
+    area?(contract: {
+        name: string;
+        method: string;
+        file: string;
+    }): string;
+}
+/** One typed method of a surface: how the catalog shows it and validates its calls. */
+export interface IFlexTypedRequestMethod {
+    /** The typed method the router answers: `getVoucher`. */
+    method: string;
+    /** The catalog path the model calls: `vouchers.getVoucher`. */
+    path: string;
+    /** The first sentence of the contract's JSDoc, or the method. */
+    summary: string;
+    /** The contract's JSDoc, its tags included. */
+    description?: string;
+    /** Set by a `@deprecated` tag on the contract. */
+    deprecated?: boolean;
+    /** The request's schema, without the omitted properties. */
+    inputSchema: TFlexTypedRequestSchema;
+    /** The response's schema. */
+    outputSchema: TFlexTypedRequestSchema;
+    /** `function getVoucher(params: …): Promise<…>;` as the contract writes it, after its JSDoc. */
+    declaration: string;
+}
+/**
+ * A typedrequest API as the catalog takes it, read from its TypeScript sources by
+ * `describeTypedRequests()`. Plain JSON, so a build step can write it and a server read it.
+ */
+export interface IFlexTypedRequestSurface {
+    /** The typed methods, by path. */
+    methods: IFlexTypedRequestMethod[];
+    /**
+     * The named types, by name: each with its JSON Schema where requests and responses refer to it,
+     * its TypeScript declaration where declarations name it, or both. A generic is declared once
+     * (`IPage`) and its instances have schemas (`IPage_IVoucher`).
+     */
+    types: IFlexCatalogType[];
+    /** The request properties left out of every request, which the binding fills. */
+    omit: string[];
+}
+/**
+ * A router that answers typed requests in process, such as a `TypedRouter` of
+ * `@api.global/typedrequest`.
+ */
+export interface IFlexTypedRequestRouter {
+    routeAndAddResponse(request: IFlexTypedRequestEnvelope, options?: {
+        trustedLocalData?: Record<string, unknown>;
+        trustedAbortSignal?: AbortSignal;
+    }): Promise<IFlexTypedRequestEnvelope | null>;
+}
+/** A typed request as the router takes it and answers it. */
+export interface IFlexTypedRequestEnvelope {
+    method: string;
+    request: object;
+    response: object;
+    correlation?: {
+        id: string;
+        phase: 'request' | 'response';
+    };
+    error?: {
+        text: string;
+        data: any;
+    };
+}
+/** How a catalog answers a surface's methods. */
+export interface IFlexTypedRequestCatalogOptions<TScope = unknown> {
+    /** The router that answers the methods, in process. */
+    router: IFlexTypedRequestRouter;
+    /**
+     * The request properties the surface leaves out, from the run: `{ identity }` of the user the
+     * session acts for. They are merged over the model's parameters.
+     */
+    request?(method: IFlexTypedRequestMethod, context: IFlexCatalogRunContext<TScope>): Record<string, unknown> | PromiseLike<Record<string, unknown>>;
+    /** Server-owned data the handlers read as `localData`, as a transport would hand it. */
+    localData?(method: IFlexTypedRequestMethod, context: IFlexCatalogRunContext<TScope>): Record<string, unknown> | PromiseLike<Record<string, unknown>>;
+    /** The methods the model may use. Default: every method that is not deprecated. */
+    include?(method: IFlexTypedRequestMethod): boolean;
+    /** Other names of methods, by typed method: `{ getVoucher: ['Beleg abrufen'] }`. */
+    aliases?: Readonly<Record<string, readonly string[]>>;
+    /** The words the API's users say for its own words; see `IFlexToolCatalog.vocabulary`. */
+    vocabulary?: IFlexToolCatalog['vocabulary'];
+    /** Decides each validated call before it runs; see `IFlexCatalogMethod.onCall`. */
+    onCall?(method: IFlexTypedRequestMethod, params: Record<string, unknown>, context: IFlexCatalogRunContext<TScope>): TFlexCatalogCallDecision | PromiseLike<TFlexCatalogCallDecision>;
+    /** Receives the calls `onCall` proposed; see `IFlexToolCatalog.onProposals`. */
+    onProposals?: IFlexToolCatalog<TScope>['onProposals'];
+}

package/dist_ts_typedrequest/interfaces.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW50ZXJmYWNlcy5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3RzX3R5cGVkcmVxdWVzdC9pbnRlcmZhY2VzLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiIifQ==

package/dist_ts_typedrequest/plugins.d.ts

@@ -0,0 +1,7 @@
+import * as crypto from 'node:crypto';
+import * as path from 'node:path';
+export { crypto, path };
+import { FlexHarnessValidationError, FlexToolCatalog } from '@modelprofile.com/flexharness';
+export { FlexHarnessValidationError, FlexToolCatalog };
+/** Loads @api.global/typedopenapi, which reads the contracts from their TypeScript sources. */
+export declare const importTypedOpenApi: () => Promise<typeof import("@api.global/typedopenapi")>;

package/dist_ts_typedrequest/plugins.js

@@ -0,0 +1,11 @@
+// node native scope
+import * as crypto from 'node:crypto';
+import * as path from 'node:path';
+export { crypto, path };
+// @modelprofile.com scope
+import { FlexHarnessValidationError, FlexToolCatalog } from '@modelprofile.com/flexharness';
+export { FlexHarnessValidationError, FlexToolCatalog };
+// @api.global scope: @api.global/typedopenapi is an optional peer, loaded only to describe a surface
+/** Loads @api.global/typedopenapi, which reads the contracts from their TypeScript sources. */
+export const importTypedOpenApi = async () => await import('@api.global/typedopenapi');
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicGx1Z2lucy5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3RzX3R5cGVkcmVxdWVzdC9wbHVnaW5zLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLG9CQUFvQjtBQUNwQixPQUFPLEtBQUssTUFBTSxNQUFNLGFBQWEsQ0FBQztBQUN0QyxPQUFPLEtBQUssSUFBSSxNQUFNLFdBQVcsQ0FBQztBQUVsQyxPQUFPLEVBQUUsTUFBTSxFQUFFLElBQUksRUFBRSxDQUFDO0FBRXhCLDBCQUEwQjtBQUMxQixPQUFPLEVBQUUsMEJBQTBCLEVBQUUsZUFBZSxFQUFFLE1BQU0sK0JBQStCLENBQUM7QUFFNUYsT0FBTyxFQUFFLDBCQUEwQixFQUFFLGVBQWUsRUFBRSxDQUFDO0FBRXZELHFHQUFxRztBQUVyRywrRkFBK0Y7QUFDL0YsTUFBTSxDQUFDLE1BQU0sa0JBQWtCLEdBQUcsS0FBSyxJQUFJLEVBQUUsQ0FBQyxNQUFNLE1BQU0sQ0FBQywwQkFBMEIsQ0FBQyxDQUFDIn0=

package/package.json

@@ -2,7 +2,7 @@
   "author": "Task Venture Capital GmbH",
   "license": "MIT",
   "name": "@modelprofile.com/flexharness",
-  "version": "10.16.0",
+  "version": "10.17.0",
   "type": "module",
   "description": "Managed agent sessions with tools, MCP, chat, OCR, documents and browser control through focused subpath imports.",
   "main": "./dist_ts/index.js",
@@ -71,12 +71,16 @@
     "./stores/nosqldb": {
       "types": "./dist_ts_stores_nosqldb/index.d.ts",
       "import": "./dist_ts_stores_nosqldb/index.js"
+    },
+    "./typedrequest": {
+      "types": "./dist_ts_typedrequest/index.d.ts",
+      "import": "./dist_ts_typedrequest/index.js"
     }
   },
   "dependencies": {
     "@cfworker/json-schema": "^4.1.1",
-    "@modelprofile.com/flexharness-agent": "10.16.0",
-    "@modelprofile.com/flexharness-models": "10.16.0",
+    "@modelprofile.com/flexharness-agent": "10.17.0",
+    "@modelprofile.com/flexharness-models": "10.17.0",
     "@push.rocks/smartrequest": "^5.5.1",
     "ai": "^7.0.111",
     "zod": "^4.6.5"
@@ -96,7 +100,8 @@
     "@design.estate/dees-catalog": "^17.0.0 || ^19.5.0 || ^20.0.0 || ^21.0.0",
     "quickjs-emscripten-core": "^0.32.0",
     "@jitl/quickjs-ng-wasmfile-release-sync": "^0.32.0",
-    "amaro": "^1.2.1"
+    "amaro": "^1.2.1",
+    "@api.global/typedopenapi": "^0.8.0"
   },
   "peerDependenciesMeta": {
     "@modelcontextprotocol/sdk": {
@@ -143,6 +148,9 @@
     },
     "amaro": {
       "optional": true
+    },
+    "@api.global/typedopenapi": {
+      "optional": true
     }
   },
   "engines": {
@@ -184,6 +192,8 @@
     "dist_ts_chat_harness",
     "ts_stores_nosqldb",
     "dist_ts_stores_nosqldb",
+    "ts_typedrequest",
+    "dist_ts_typedrequest",
     "readme.md",
     "license.md"
   ]

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@modelprofile.com/flexharness',
-  version: '10.16.0',
+  version: '10.17.0',
   description: 'The FlexHarness toolbox source repository and shared dependency catalog.'
 }

package/ts/classes.flexharness.ts

@@ -497,6 +497,22 @@ interface IRunReadCall {
 
 const notShared = Symbol('not shared');
 
+/** Runs `operation` after the operations queued before it under `key`, whatever their outcome. */
+function queueOperation<TResult>(
+  queues: Map<string, Promise<void>>,
+  key: string,
+  operation: () => Promise<TResult>,
+): Promise<TResult> {
+  const previous = queues.get(key) ?? Promise.resolve();
+  const result = previous.then(operation);
+  const barrier = result.then(() => undefined, () => undefined);
+  queues.set(key, barrier);
+  void barrier.then(() => {
+    if (queues.get(key) === barrier) queues.delete(key);
+  });
+  return result;
+}
+
 /** The steers of a run: the input its generation takes in, and the prompts it accepted for it. */
 interface IRunSteering {
   readonly input: plugins.AgentPendingInputQueue;
@@ -928,6 +944,8 @@ export class FlexHarness<TScope = unknown> {
   private readonly orphanedTombstoneOwners = new Map<string, IOrphanedTombstoneOwner<TScope>>();
   private readonly pendingPromptAdmissionOwners = new Set<IPendingPromptAdmission>();
   private readonly projectManagementQueues = new Map<string, Promise<void>>();
+  /** A session's result writes, one at a time: they share the session's index of results. */
+  private readonly resultQueues = new Map<string, Promise<void>>();
   private readonly activeSlashCommandExecutions = new Map<string, IActiveSlashCommandExecution>();
   private readonly activeSlashCommandListings = new Set<IActiveSlashCommandListing>();
   private readonly stagedSessionImports = new Map<string, IStagedSessionImport>();
@@ -5318,17 +5336,7 @@ export class FlexHarness<TScope = unknown> {
     sessionId: string,
     operation: () => Promise<TResult>,
   ): Promise<TResult> {
-    const key = this.projectManagementKey(storageKey, sessionId);
-    const previous = this.projectManagementQueues.get(key) ?? Promise.resolve();
-    const result = previous.then(operation);
-    const barrier = result.then(() => undefined, () => undefined);
-    this.projectManagementQueues.set(key, barrier);
-    void barrier.then(() => {
-      if (this.projectManagementQueues.get(key) === barrier) {
-        this.projectManagementQueues.delete(key);
-      }
-    });
-    return result;
+    return queueOperation(this.projectManagementQueues, this.projectManagementKey(storageKey, sessionId), operation);
   }
 
   private async awaitProjectManagementOperations(
@@ -6016,10 +6024,22 @@ export class FlexHarness<TScope = unknown> {
     };
     // A budget too small for even the handle keeps the truncated output.
     if (jsonBytes(result) > maxBytes) return normalizeJsonValue(output, this.toolOutputLimits);
-    await results.save(run.state.storageKey, run.sessionId, handle, stored);
+    const { storageKey } = run.state;
+    await queueOperation(this.resultQueues, this.resultQueueKey(storageKey, run.sessionId), async () => {
+      await results.save(storageKey, run.sessionId, handle, stored);
+      // The session keeps its latest results; older ones are deleted.
+      const handles = await results.list(storageKey, run.sessionId);
+      for (const old of handles.slice(0, Math.max(0, handles.length - FLEX_RESULT_LIMITS.maxResultsPerSession))) {
+        await results.delete(storageKey, run.sessionId, old);
+      }
+    });
     return result as unknown as TJsonValue;
   }
 
+  private resultQueueKey(storageKey: string, sessionId: string): string {
+    return JSON.stringify([storageKey, sessionId]);
+  }
+
   /** The JSON bytes of one `results.get` page: the output budget, less room for the page's fields. */
   private resultPageBytes(): number {
     return Math.max(64, this.toolOutputLimits.maxBytes - 512);
@@ -6033,7 +6053,7 @@ export class FlexHarness<TScope = unknown> {
     const method = FLEX_RESULT_METHOD;
     const stored = await this.stores.results!.load(run.state.storageKey, run.sessionId, params.handle);
     if (stored === undefined) {
-      return { ok: false, error: { error: 'unknown_handle', method, handle: params.handle, hint: 'A handle reads a result this session stored.' } };
+      return { ok: false, error: { error: 'unknown_handle', method, handle: params.handle, hint: `A handle reads one of the latest ${FLEX_RESULT_LIMITS.maxResultsPerSession} results this session stored.` } };
     }
     const path = params.path ?? '';
     const value = selectPath(stored, path);
@@ -11243,12 +11263,18 @@ export class FlexHarness<TScope = unknown> {
         tombstone,
       );
     };
+    const resultStore = this.stores.results;
+    const resultCleanup = async (): Promise<void> => {
+      // A result being saved for the session is written before its results are deleted.
+      await this.resultQueues.get(this.resultQueueKey(storageKey, sessionId));
+      await resultStore!.deleteSession(storageKey, sessionId);
+    };
     const results = await Promise.allSettled([
       this.stores.agentEvents.deleteSession(storageKey, sessionId),
       this.stores.jobs.deleteSession(storageKey, sessionId),
       this.stores.projections.deleteSession(storageKey, sessionId),
       this.stores.permissions.deleteSession(storageKey, sessionId),
-      ...(this.stores.results ? [this.stores.results.deleteSession(storageKey, sessionId)] : []),
+      ...(resultStore ? [resultCleanup()] : []),
       // An imported session refuses every project-management write, so it has no state to fence.
       ...(tombstone.imported ? [] : [projectManagementCleanup()]),
     ]);

package/ts/classes.stores.ts

@@ -52,6 +52,7 @@ import {
   providerKey,
   validateExpectedRevision,
   validateIdentifier,
+  validateResultIndex,
   validateProjectManagementWriteContext,
   validateSnapshotSave,
 } from './utils.storerules.js';
@@ -355,6 +356,14 @@ class InMemoryResultStore implements IFlexResultStore {
     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));
   }
@@ -464,6 +473,10 @@ class JsonFileRoot {
     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');
@@ -888,30 +901,60 @@ 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) {}
 
-  public async save(storageKey: string, sessionId: string, handle: string, value: TJsonValue): Promise<void> {
+  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);
-    await JsonFileRoot.inQueue(filePath, async () => {
+    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 async load(storageKey: string, sessionId: string, handle: string): Promise<TJsonValue | undefined> {
+  public 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) => {
+    return this.inSessionQueue(storageKey, sessionId, () => this.root.read(filePath, (value) => {
       assertJsonSerializable(value);
       return value as TJsonValue;
     }));
   }
 
-  public async deleteSession(storageKey: string, sessionId: string): Promise<void> {
+  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);
-    await JsonFileRoot.inQueue(`results:${directory}`, () => this.root.deleteDirectory(directory));
+    return this.inSessionQueue(storageKey, sessionId, () => this.root.deleteDirectory(directory));
   }
 }