@modelprofile.com/flexharness 10.24.0 → 10.24.1

package/dist_ts/classes.flexharness.providers.d.ts

@@ -0,0 +1,18 @@
+import type { IFlexToolHandle, IFlexToolProviderContext } from './interfaces.js';
+import type { IStorageState, IActiveRun, IResolverOutcome } from './interfaces.flexharness.js';
+import type { FlexHarnessCore } from './classes.flexharness.core.js';
+/** Tool provider plumbing: run tool handles, resource tool providers and detached cleanups. */
+export declare class FlexHarnessToolProviders<TScope> {
+    private readonly core;
+    constructor(core: FlexHarnessCore<TScope>);
+    normalizeToolHandle(run: IActiveRun, handle: IFlexToolHandle | undefined): IFlexToolHandle | undefined;
+    provideRunToolHandle(run: IActiveRun, context: Readonly<IFlexToolProviderContext<TScope>>): Promise<IFlexToolHandle | undefined>;
+    private normalizeResourceToolProviderDescriptors;
+    closePartialToolHandle(handle: IFlexToolHandle, run: IActiveRun): Promise<void>;
+    private retainDetachedCleanup;
+    observeDetachedToolProvider(outcome: Promise<IResolverOutcome<IFlexToolHandle | undefined>>, run: IActiveRun): void;
+    private trackDetachedCleanup;
+    private runDetachedCleanup;
+    beginDetachedCleanupSettlement(state: IStorageState): Promise<void>[];
+    settleDetachedCleanups(state: IStorageState, attempts: readonly Promise<void>[]): Promise<Error[]>;
+}

package/dist_ts/classes.flexharness.providers.js

@@ -0,0 +1,267 @@
+import { FlexHarnessValidationError } from './errors.js';
+import { requireSessionGeneration, createFlexResourceIdentityDigest, createFlexResourceToolNamespace, createFlexResourceToolName, combineErrors, } from './utils.flexharness.js';
+const maxResourceToolProviders = 128;
+/** Tool provider plumbing: run tool handles, resource tool providers and detached cleanups. */
+export class FlexHarnessToolProviders {
+    core;
+    constructor(core) {
+        this.core = core;
+    }
+    normalizeToolHandle(run, handle) {
+        if (handle === undefined)
+            return undefined;
+        let close;
+        try {
+            close = handle.close;
+            if (close !== undefined && typeof close !== 'function') {
+                throw new FlexHarnessValidationError('Tool handle close must be a function.');
+            }
+            const tools = handle.tools;
+            this.core.runs.assertNoBuiltInToolCollisions(run, tools);
+            const catalog = handle.catalog;
+            if (catalog !== undefined && (typeof catalog !== 'object' || catalog === null)) {
+                throw new FlexHarnessValidationError('Tool handle catalog must be an object.');
+            }
+            const isReadOnlyToolCall = handle.isReadOnlyToolCall;
+            if (isReadOnlyToolCall !== undefined && typeof isReadOnlyToolCall !== 'function') {
+                throw new FlexHarnessValidationError('Tool handle isReadOnlyToolCall must be a function.');
+            }
+            const closeHandle = close;
+            return {
+                tools,
+                ...(catalog === undefined ? {} : { catalog }),
+                ...(isReadOnlyToolCall === undefined ? {} : {
+                    isReadOnlyToolCall: (call) => isReadOnlyToolCall.call(handle, call),
+                }),
+                ...(closeHandle ? { close: () => closeHandle.call(handle) } : {}),
+            };
+        }
+        catch (error) {
+            if (close)
+                this.trackDetachedCleanup(run.state, run, () => close.call(handle));
+            throw this.core.projectExternalError(run, error, 'toolProvider');
+        }
+    }
+    async provideRunToolHandle(run, context) {
+        if (!this.core.resourceToolProviderResolver)
+            return this.core.toolProvider?.provideTools(context);
+        const resolverContext = Object.freeze({
+            scopeId: context.scopeId,
+            scope: context.scope,
+            sessionId: context.sessionId,
+            ...requireSessionGeneration(run.stored.session),
+            runId: context.runId,
+            ...(context.parentSessionId === undefined ? {} : { parentSessionId: context.parentSessionId }),
+            ...(context.agent === undefined ? {} : { agent: context.agent }),
+            signal: context.signal,
+        });
+        const resolved = await this.core.resourceToolProviderResolver.resolveResourceToolProviders(resolverContext);
+        const descriptors = this.normalizeResourceToolProviderDescriptors(resolved);
+        const owned = [];
+        const tools = Object.create(null);
+        /** The handle and own name of each exposed resource tool, for the handle's classifier. */
+        const resourceTools = new Map();
+        const closeOwned = async () => {
+            const errors = [];
+            for (const entry of [...owned].reverse()) {
+                if (entry.closed || !entry.handle.close)
+                    continue;
+                try {
+                    await entry.handle.close();
+                    entry.closed = true;
+                }
+                catch (error) {
+                    errors.push(error);
+                }
+            }
+            if (errors.length > 0)
+                throw combineErrors(errors);
+        };
+        try {
+            context.signal.throwIfAborted();
+            const applicationHandle = this.normalizeToolHandle(run, await this.core.toolProvider?.provideTools(context));
+            if (applicationHandle) {
+                owned.push({ handle: applicationHandle, closed: false });
+                for (const [toolName, tool] of Object.entries(applicationHandle.tools)) {
+                    tools[toolName] = tool;
+                }
+            }
+            for (const descriptor of descriptors) {
+                context.signal.throwIfAborted();
+                const namespace = createFlexResourceToolNamespace(descriptor.resourceId, descriptor.attachmentRevision);
+                const resourceIdentity = createFlexResourceIdentityDigest(descriptor.resourceId, descriptor.attachmentRevision);
+                const resourceContext = Object.freeze({
+                    ...context,
+                    requestPermission: (request) => context.requestPermission({
+                        ...request,
+                        kind: `resource.${resourceIdentity}.${request.kind}`,
+                        ...(request.rememberKey === undefined
+                            ? {}
+                            : { rememberKey: `resource:${resourceIdentity}:${request.rememberKey}` }),
+                        metadata: {
+                            resourceId: descriptor.resourceId,
+                            attachmentRevision: descriptor.attachmentRevision,
+                            resourceIdentity,
+                            toolNamespace: namespace,
+                            ...(request.metadata === undefined ? {} : { providerMetadata: request.metadata }),
+                        },
+                    }),
+                });
+                const handle = this.normalizeToolHandle(run, await descriptor.provider.provideTools(resourceContext));
+                if (!handle)
+                    continue;
+                owned.push({ handle, closed: false });
+                if (handle.catalog !== undefined) {
+                    throw new FlexHarnessValidationError('Resource tool providers cannot supply a tool catalog.');
+                }
+                for (const [toolName, tool] of Object.entries(handle.tools)) {
+                    const exposedName = createFlexResourceToolName(namespace, toolName);
+                    if (Object.prototype.hasOwnProperty.call(tools, exposedName)) {
+                        throw new FlexHarnessValidationError(`Duplicate exposed tool "${exposedName}".`);
+                    }
+                    tools[exposedName] = tool;
+                    resourceTools.set(exposedName, { handle, toolName });
+                }
+            }
+            if (owned.length === 0 && Object.keys(tools).length === 0)
+                return undefined;
+            const classifies = applicationHandle?.isReadOnlyToolCall !== undefined
+                || [...resourceTools.values()].some((entry) => entry.handle.isReadOnlyToolCall !== undefined);
+            return {
+                tools: tools,
+                ...(applicationHandle?.catalog === undefined ? {} : { catalog: applicationHandle.catalog }),
+                ...(classifies ? {
+                    isReadOnlyToolCall: ({ toolName, input }) => {
+                        const resource = resourceTools.get(toolName);
+                        return resource
+                            ? resource.handle.isReadOnlyToolCall?.({ toolName: resource.toolName, input }) === true
+                            : applicationHandle?.isReadOnlyToolCall?.({ toolName, input }) === true;
+                    },
+                } : {}),
+                ...(owned.some((entry) => entry.handle.close) ? { close: closeOwned } : {}),
+            };
+        }
+        catch (error) {
+            if (owned.some((entry) => entry.handle.close && !entry.closed)) {
+                try {
+                    await this.closePartialToolHandle({ tools: {}, close: closeOwned }, run);
+                }
+                catch (cleanupError) {
+                    throw combineErrors([error, cleanupError]);
+                }
+            }
+            throw error;
+        }
+    }
+    normalizeResourceToolProviderDescriptors(descriptors) {
+        if (!Array.isArray(descriptors) || descriptors.length > maxResourceToolProviders) {
+            throw new FlexHarnessValidationError(`Resource tool providers must be an array with at most ${maxResourceToolProviders} descriptors.`);
+        }
+        const resourceIds = new Set();
+        const namespaces = new Set();
+        return descriptors.map((descriptor, index) => {
+            if (!descriptor
+                || typeof descriptor !== 'object'
+                || Array.isArray(descriptor)
+                || ![Object.prototype, null].includes(Object.getPrototypeOf(descriptor))) {
+                throw new FlexHarnessValidationError(`Resource tool provider descriptor ${index} is invalid.`);
+            }
+            const unsupported = Object.keys(descriptor).find((key) => !['resourceId', 'attachmentRevision', 'provider'].includes(key));
+            if (unsupported) {
+                throw new FlexHarnessValidationError(`Resource tool provider descriptor ${index} does not support "${unsupported}".`);
+            }
+            const resourceId = descriptor.resourceId;
+            const attachmentRevision = descriptor.attachmentRevision;
+            const provider = descriptor.provider;
+            const provideTools = provider?.provideTools;
+            const namespace = createFlexResourceToolNamespace(resourceId, attachmentRevision);
+            if (resourceIds.has(resourceId)) {
+                throw new FlexHarnessValidationError(`Duplicate resourceId "${resourceId}".`);
+            }
+            if (namespaces.has(namespace)) {
+                throw new FlexHarnessValidationError(`Duplicate resource tool namespace "${namespace}".`);
+            }
+            if (!provider || typeof provideTools !== 'function') {
+                throw new FlexHarnessValidationError(`Resource tool provider descriptor ${index} has no tool provider.`);
+            }
+            resourceIds.add(resourceId);
+            namespaces.add(namespace);
+            return {
+                resourceId,
+                attachmentRevision,
+                provider: {
+                    provideTools: (context) => provideTools.call(provider, context),
+                },
+            };
+        });
+    }
+    async closePartialToolHandle(handle, run) {
+        try {
+            await handle.close?.();
+        }
+        catch (error) {
+            const projected = this.core.projectExternalError(run, error, 'toolCleanup');
+            this.retainDetachedCleanup(run.state, run, () => handle.close?.(), projected);
+            throw projected;
+        }
+    }
+    retainDetachedCleanup(state, run, cleanup, error) {
+        state.detachedCleanups.add({
+            cleanup,
+            projectError: (cleanupError) => this.core.projectExternalError(run, cleanupError, 'toolCleanup'),
+            error,
+        });
+    }
+    observeDetachedToolProvider(outcome, run) {
+        this.trackDetachedCleanup(run.state, run, async () => {
+            const result = await outcome;
+            if (!result.success || result.source !== 'tools' || !result.value)
+                return;
+            const close = result.value.close;
+            if (close !== undefined && typeof close !== 'function') {
+                throw new FlexHarnessValidationError('Tool handle close must be a function.');
+            }
+            await close?.call(result.value);
+        });
+    }
+    trackDetachedCleanup(state, run, cleanup) {
+        const retained = {
+            cleanup,
+            projectError: (error) => this.core.projectExternalError(run, error, 'toolCleanup'),
+        };
+        state.detachedCleanups.add(retained);
+        void this.runDetachedCleanup(state, retained);
+    }
+    runDetachedCleanup(state, retained) {
+        if (retained.completion)
+            return retained.completion;
+        retained.error = undefined;
+        let completion;
+        completion = Promise.resolve()
+            .then(retained.cleanup)
+            .then(() => {
+            state.detachedCleanups.delete(retained);
+        }, (error) => {
+            retained.error = retained.projectError(error);
+        })
+            .finally(() => {
+            if (retained.completion === completion)
+                retained.completion = undefined;
+        });
+        retained.completion = completion;
+        return completion;
+    }
+    beginDetachedCleanupSettlement(state) {
+        return [...state.detachedCleanups].map((cleanup) => cleanup.completion ?? this.runDetachedCleanup(state, cleanup));
+    }
+    async settleDetachedCleanups(state, attempts) {
+        await Promise.all(attempts);
+        await Promise.all([...state.detachedCleanups]
+            .map((cleanup) => cleanup.completion)
+            .filter((completion) => completion !== undefined));
+        return [...state.detachedCleanups]
+            .map((cleanup) => cleanup.error)
+            .filter((error) => error !== undefined);
+    }
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY2xhc3Nlcy5mbGV4aGFybmVzcy5wcm92aWRlcnMuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi90cy9jbGFzc2VzLmZsZXhoYXJuZXNzLnByb3ZpZGVycy50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEVBQUUsMEJBQTBCLEVBQUUsTUFBTSxhQUFhLENBQUM7QUFjekQsT0FBTyxFQUNMLHdCQUF3QixFQUN4QixnQ0FBZ0MsRUFDaEMsK0JBQStCLEVBQy9CLDBCQUEwQixFQUMxQixhQUFhLEdBQ2QsTUFBTSx3QkFBd0IsQ0FBQztBQUdoQyxNQUFNLHdCQUF3QixHQUFHLEdBQUcsQ0FBQztBQUVyQywrRkFBK0Y7QUFDL0YsTUFBTSxPQUFPLHdCQUF3QjtJQUNOO0lBQTdCLFlBQTZCLElBQTZCO1FBQTdCLFNBQUksR0FBSixJQUFJLENBQXlCO0lBQUcsQ0FBQztJQUV2RCxtQkFBbUIsQ0FBQyxHQUFlLEVBQUUsTUFBbUM7UUFDN0UsSUFBSSxNQUFNLEtBQUssU0FBUztZQUFFLE9BQU8sU0FBUyxDQUFDO1FBQzNDLElBQUksS0FBK0IsQ0FBQztRQUNwQyxJQUFJLENBQUM7WUFDSCxLQUFLLEdBQUcsTUFBTSxDQUFDLEtBQUssQ0FBQztZQUNyQixJQUFJLEtBQUssS0FBSyxTQUFTLElBQUksT0FBTyxLQUFLLEtBQUssVUFBVSxFQUFFLENBQUM7Z0JBQ3ZELE1BQU0sSUFBSSwwQkFBMEIsQ0FBQyx1Q0FBdUMsQ0FBQyxDQUFDO1lBQ2hGLENBQUM7WUFDRCxNQUFNLEtBQUssR0FBRyxNQUFNLENBQUMsS0FBSyxDQUFDO1lBQzNCLElBQUksQ0FBQyxJQUFJLENBQUMsSUFBSSxDQUFDLDZCQUE2QixDQUFDLEdBQUcsRUFBRSxLQUFLLENBQUMsQ0FBQztZQUN6RCxNQUFNLE9BQU8sR0FBRyxNQUFNLENBQUMsT0FBTyxDQUFDO1lBQy9CLElBQUksT0FBTyxLQUFLLFNBQVMsSUFBSSxDQUFDLE9BQU8sT0FBTyxLQUFLLFFBQVEsSUFBSSxP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

package/dist_ts/classes.flexharness.results.d.ts

@@ -0,0 +1,26 @@
+import { type TJsonValue } from './interfaces.js';
+import type { IActiveRun, IResultRead } from './interfaces.flexharness.js';
+import type { FlexHarnessCore } from './classes.flexharness.core.js';
+/** Budgeted tool output: oversized results stored behind result handles and read back by page. */
+export declare class FlexHarnessResults<TScope> {
+    private readonly core;
+    /** A session's result writes, one at a time: they share the session's index of results. */
+    readonly resultQueues: Map<string, Promise<void>>;
+    constructor(core: FlexHarnessCore<TScope>);
+    /**
+     * The output the model gets: the output itself within the output budget, or, in a run with a
+     * catalog whose stores keep results, a handle to the stored output with a summary of it.
+     */
+    budgetOutput(run: IActiveRun, output: unknown): Promise<TJsonValue>;
+    resultQueueKey(storageKey: string, sessionId: string): string;
+    /** The JSON bytes of one `results.get` page: the output budget, less room for the page's fields. */
+    private resultPageBytes;
+    /** One page of a stored result of the run's session, or the error `results.get` reports. */
+    readResult(run: IActiveRun, params: IResultRead): Promise<{
+        ok: true;
+        value: TJsonValue;
+    } | {
+        ok: false;
+        error: TJsonValue;
+    }>;
+}

package/dist_ts/classes.flexharness.results.js

@@ -0,0 +1,89 @@
+import * as plugins from './plugins.js';
+import { FLEX_RESULT_LIMITS, FLEX_RESULT_METHOD, } from './interfaces.js';
+import { describeShape, resultPage, selectPath, summarizeResult } from './utils.results.js';
+import { normalizeJsonValue } from './utils.json.js';
+import { jsonBytes } from './utils.transfer.js';
+import { queueOperation } from './utils.flexharness.js';
+/** Budgeted tool output: oversized results stored behind result handles and read back by page. */
+export class FlexHarnessResults {
+    core;
+    /** A session's result writes, one at a time: they share the session's index of results. */
+    resultQueues = new Map();
+    constructor(core) {
+        this.core = core;
+    }
+    /**
+     * The output the model gets: the output itself within the output budget, or, in a run with a
+     * catalog whose stores keep results, a handle to the stored output with a summary of it.
+     */
+    async budgetOutput(run, output) {
+        const results = this.core.stores.results;
+        const maxBytes = this.core.toolOutputLimits.maxBytes;
+        if (!results || !run.toolCatalog)
+            return normalizeJsonValue(output, this.core.toolOutputLimits);
+        const stored = normalizeJsonValue(output, {
+            ...this.core.toolOutputLimits,
+            maxBytes: Math.max(maxBytes, FLEX_RESULT_LIMITS.maxStoredBytes),
+        });
+        const bytes = jsonBytes(stored);
+        if (bytes <= maxBytes)
+            return stored;
+        const handle = `res_${plugins.crypto.randomBytes(8).toString('hex')}`;
+        const read = `Too large to return whole: read it page by page with execute({ method: "${FLEX_RESULT_METHOD}", `
+            + `params: { handle: "${handle}", page: 1 } })${run.toolCatalog.codeMode
+                ? `, or in run_code with await api.results.get("${handle}", { page: 1 })`
+                : ''}; a dotted \`path\` reads a part of it.`;
+        const result = {
+            $flexType: 'result',
+            handle,
+            bytes,
+            pages: resultPage(stored, '', 1, this.resultPageBytes()).pages,
+            summary: summarizeResult(stored, Math.min(FLEX_RESULT_LIMITS.summaryBytes, Math.floor(maxBytes / 4))),
+            read,
+        };
+        // A budget too small for even the handle keeps the truncated output.
+        if (jsonBytes(result) > maxBytes)
+            return normalizeJsonValue(output, this.core.toolOutputLimits);
+        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;
+    }
+    resultQueueKey(storageKey, sessionId) {
+        return JSON.stringify([storageKey, sessionId]);
+    }
+    /** The JSON bytes of one `results.get` page: the output budget, less room for the page's fields. */
+    resultPageBytes() {
+        return Math.max(64, this.core.toolOutputLimits.maxBytes - 512);
+    }
+    /** One page of a stored result of the run's session, or the error `results.get` reports. */
+    async readResult(run, params) {
+        const method = FLEX_RESULT_METHOD;
+        const stored = await this.core.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 one of the latest ${FLEX_RESULT_LIMITS.maxResultsPerSession} results this session stored.` } };
+        }
+        const path = params.path ?? '';
+        const value = selectPath(stored, path);
+        if (value === undefined) {
+            return { ok: false, error: { error: 'unknown_path', method, path, hint: `The result is ${describeShape(stored)}.` } };
+        }
+        const page = params.page ?? 1;
+        const content = resultPage(value, path, page, this.resultPageBytes());
+        if (!content) {
+            const pages = resultPage(value, path, 1, this.resultPageBytes()).pages;
+            return { ok: false, error: { error: 'unknown_page', method, page, pages } };
+        }
+        return {
+            ok: true,
+            value: { handle: params.handle, path, page, pages: content.pages, ...content.range, value: content.value },
+        };
+    }
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY2xhc3Nlcy5mbGV4aGFybmVzcy5yZXN1bHRzLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vdHMvY2xhc3Nlcy5mbGV4aGFybmVzcy5yZXN1bHRzLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLE9BQU8sS0FBSyxPQUFPLE1BQU0sY0FBYyxDQUFDO0FBQ3hDLE9BQU8sRUFDTCxrQkFBa0IsRUFDbEIsa0JBQWtCLEdBR25CLE1BQU0saUJBQWlCLENBQUM7QUFDekIsT0FBTyxFQUFFLGFBQWEsRUFBRSxVQUFVLEVBQUUsVUFBVSxFQUFFLGVBQWUsRUFBRSxNQUFNLG9CQUFvQixDQUFDO0FBQzVGLE9BQU8sRUFBRSxrQkFBa0IsRUFBRSxNQUFNLGlCQUFpQixDQUFDO0FBQ3JELE9BQU8sRUFBRSxTQUFTLEVBQUUsTUFBTSxxQkFBcUIsQ0FBQztBQUVoRCxPQUFPLEVBQUUsY0FBYyxFQUFFLE1BQU0sd0JBQXdCLENBQUM7QUFHeEQsa0dBQWtHO0FBQ2xHLE1BQU0sT0FBTyxrQkFBa0I7SUFJQTtJQUg3QiwyRkFBMkY7SUFDM0UsWUFBWSxHQUFHLElBQUksR0FBRyxFQUF5QixDQUFDO0lBRWhFLFlBQTZCLElBQTZCO1FBQTdCLFNBQUksR0FBSixJQUFJLENBQXlCO0lBQUcsQ0FBQztJQUU5RDs7O09BR0c7SUFDSSxLQUFLLENBQUMsWUFBWSxDQUFDLEdBQWUsRUFBRSxNQUFlO1FBQ3hELE1BQU0sT0FBTyxHQUFHLElBQUksQ0FBQyxJQUFJLENBQUMsTUFBTSxDQUFDLE9BQU8sQ0FBQztRQUN6QyxNQUFNLFFBQVEsR0FBRyxJQUFJLENBQUMsSUFBSSxDQUFDLGdCQUFnQixDQUFDLFFBQVEsQ0FBQztRQUNyRCxJQUFJLENBQUMsT0FBTyxJQUFJLENBQUMsR0FBRyxDQUFDLFdBQVc7WUFBRSxPQUFPLGtCQUFrQixDQUFDLE1BQU0sRUFBRSxJQUFJLENBQUMsSUFBSSxDQUFDLGdCQUFnQixDQUFDLENBQUM7UUFDaEcsTUFBTSxNQUFNLEdBQUcs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QUFDLE9BQU8sRUFBRSxDQUFDO1lBQ2IsTUFBTSxLQUFLLEdBQUcsVUFBVSxDQUFDLEtBQUssRUFBRSxJQUFJLEVBQUUsQ0FBQyxFQUFFLElBQUksQ0FBQyxlQUFlLEVBQUUsQ0FBRSxDQUFDLEtBQUssQ0FBQztZQUN4RSxPQUFPLEVBQUUsRUFBRSxFQUFFLEtBQUssRUFBRSxLQUFLLEVBQUUsRUFBRSxLQUFLLEVBQUUsY0FBYyxFQUFFLE1BQU0sRUFBRSxJQUFJLEVBQUUsS0FBSyxFQUFFLEVBQUUsQ0FBQztRQUM5RSxDQUFDO1FBQ0QsT0FBTztZQUNMLEVBQUUsRUFBRSxJQUFJO1lBQ1IsS0FBSyxFQUFFLEVBQUUsTUFBTSxFQUFFLE1BQU0sQ0FBQyxNQUFNLEVBQUUsSUFBSSxFQUFFLElBQUksRUFBRSxLQUFLLEVBQUUsT0FBTyxDQUFDLEtBQUssRUFBRSxHQUFHLE9BQU8sQ0FBQyxLQUFLLEVBQUUsS0FBSyxFQUFFLE9BQU8sQ0FBQyxLQUFLLEVBQUU7U0FDM0csQ0FBQztJQUNKLENBQUM7Q0FDRiJ9

package/dist_ts/classes.flexharness.reversions.d.ts

@@ -0,0 +1,52 @@
+import * as plugins from './plugins.js';
+import { type IFlexReversionSegment, type IFlexRedoSessionResult, type IFlexSessionReversionInfo, type IFlexSessionTombstone, type IFlexUndoSessionResult } from './interfaces.js';
+import type { TCanonicalOutcome, IStoredSessionState, IReversionGroup, IStorageState, IActiveRun } from './interfaces.flexharness.js';
+import type { FlexHarnessCore } from './classes.flexharness.core.js';
+/** Turn reversion: capture, undo and redo, and the release of reversion state. */
+export declare class FlexHarnessReversions<TScope> {
+    private readonly core;
+    constructor(core: FlexHarnessCore<TScope>);
+    getSessionReversionInfo(scopeId: string, sessionId: string): Promise<IFlexSessionReversionInfo>;
+    undoSession(scopeId: string, sessionId: string, signal?: AbortSignal): Promise<IFlexUndoSessionResult>;
+    redoSession(scopeId: string, sessionId: string, signal?: AbortSignal): Promise<IFlexRedoSessionResult>;
+    reversionUnit(stored: IStoredSessionState, direction: 'undo' | 'redo'): {
+        target: IFlexReversionSegment;
+        segments: IFlexReversionSegment[];
+        toCursor: number;
+    } | undefined;
+    reversionGroups(stored: IStoredSessionState): IReversionGroup[];
+    private requireReversionIdle;
+    reversionUnavailableReason(state: IStorageState, stored: IStoredSessionState, allowPendingApply?: boolean, operationSignal?: AbortSignal): Promise<string | undefined>;
+    awaitReversionOperation<TResult>(operation: Promise<TResult>, signal?: AbortSignal): Promise<TResult>;
+    private changeReversionCursor;
+    changeReversionCursorResolved(scopeId: string, sessionId: string, direction: 'undo' | 'redo', scope: TScope, state: IStorageState, signal?: AbortSignal): Promise<string>;
+    reconcileContextAvailability(state: IStorageState, stored: IStoredSessionState): Promise<boolean>;
+    resumePendingApply(state: IStorageState, stored: IStoredSessionState, scopeId: string, scope: TScope, signal?: AbortSignal): Promise<void>;
+    private persistKnownNotApplied;
+    recoverPendingCapture(state: IStorageState, stored: IStoredSessionState, scopeId: string, scope: TScope, outcomes: Map<string, TCanonicalOutcome>): Promise<void>;
+    reversionId(kind: 'capture' | 'apply', storageKey: string, sessionId: string, value: string): string;
+    reversionProviderProtocolVersion(): 1 | 2 | undefined;
+    private reversionCaptureContext;
+    private withReversionMaintenanceSignal;
+    private inspectReversionCapture;
+    private finalizeReversionCapture;
+    private resolveReversionCaptureOutcome;
+    private normalizeReversionReference;
+    private normalizeReversionOutcome;
+    private normalizeAffectedWorkspaces;
+    prepareRunReversion(run: IActiveRun, signal: AbortSignal): Promise<void>;
+    finalizeRunReversion(run: IActiveRun, status: 'completed' | 'failed' | 'cancelled'): Promise<void>;
+    private applyFinalizedReversionOutcome;
+    private hiddenReversionSegments;
+    private enqueueReversionRelease;
+    private enqueueReversionReleaseReference;
+    pruneReversionState(stored: IStoredSessionState, reserveSegment?: boolean, dropNonUndoablePrefix?: boolean): void;
+    commitRevertedBranch(state: IStorageState, stored: IStoredSessionState, scopeId: string, scope: TScope): Promise<void>;
+    commitRevertedBranchState(stored: IStoredSessionState): boolean;
+    commitArchivedHiddenBranchState(stored: IStoredSessionState): boolean;
+    refreshAutomaticArchiveHorizon(stored: IStoredSessionState): void;
+    filterReversionContextEvents(stored: IStoredSessionState, events: readonly plugins.TAgentEvent[]): plugins.TAgentEvent[];
+    drainReversionReleases(state: IStorageState, stored: IStoredSessionState, scopeId: string, scope: TScope, throwOnFailure: boolean): Promise<void>;
+    releaseDeletedSessionReversions(state: IStorageState, storageKey: string, tombstone: IFlexSessionTombstone, scopeId: string, scope: TScope, stored?: IStoredSessionState): Promise<void>;
+    completedReversionCandidates(stored: IStoredSessionState): IFlexReversionSegment[];
+}