@modelprofile.com/flexharness 10.17.0 → 10.18.0

package/dist_ts_tools_node/classes.workspacereversion.js

@@ -0,0 +1,202 @@
+import * as plugins from './plugins.js';
+import { fileImageBytes, fileImagesEqual, missingAncestors, readFileImage, removeEmptyDirectories, writeFileImage, } from './functions.fileimages.js';
+const DEFAULT_MAX_CAPTURE_BYTES = 64 * 1024 * 1024;
+const isCaptureReference = (valueArg) => !!valueArg
+    && typeof valueArg === 'object'
+    && !Array.isArray(valueArg)
+    && typeof valueArg.captureId === 'string';
+/**
+ * Turn reversion for the local filesystem tools, held in memory: FlexHarness `/undo` and `/redo`
+ * move a turn's file changes together with its transcript.
+ *
+ * Give each run's `createLocalToolExecutionContext` the observer `observerFor(context.runId)`. The
+ * first change of a file in a turn records what the file held before; `finalize` records what it
+ * holds after. Undo puts the before images back and redo the after images, each only while every
+ * file still holds what the other direction left, so a later edit of the user is never overwritten.
+ * A turn that ran a shell command is nonrevertible, since the command may have changed files no
+ * observer saw.
+ *
+ * Captures live as long as the process. A capture FlexHarness asks about after a restart is
+ * `missing`, and undoing past it fails without changing anything. Only root-session runs are
+ * captured; a change of a run without a prepared capture is refused.
+ */
+export class InMemoryWorkspaceReversion {
+    protocolVersion = 2;
+    workspace;
+    maxCaptureBytes;
+    captures = new Map();
+    captureIdsByRun = new Map();
+    constructor(optionsArg) {
+        this.workspace = { id: optionsArg.workspace.id, label: optionsArg.workspace.label };
+        this.maxCaptureBytes = optionsArg.maxCaptureBytes ?? DEFAULT_MAX_CAPTURE_BYTES;
+        if (!Number.isSafeInteger(this.maxCaptureBytes) || this.maxCaptureBytes <= 0) {
+            throw new Error('maxCaptureBytes must be a positive integer.');
+        }
+    }
+    /** The observer of one run's file changes and shell commands. */
+    observerFor(runIdArg) {
+        return {
+            beforeFileChange: (changeArg) => this.recordChange(runIdArg, changeArg),
+            beforeShellCommand: () => {
+                this.markNonrevertible(this.requirePreparedCapture(runIdArg), 'shell-command');
+            },
+        };
+    }
+    prepare(contextArg) {
+        contextArg.signal.throwIfAborted();
+        if (this.captures.has(contextArg.captureId))
+            return;
+        this.captures.set(contextArg.captureId, {
+            captureId: contextArg.captureId,
+            runId: contextArg.runId,
+            state: 'prepared',
+            files: new Map(),
+            bytes: 0,
+            appliedOperations: new Set(),
+            uncertainOperations: new Set(),
+        });
+        this.captureIdsByRun.set(contextArg.runId, contextArg.captureId);
+    }
+    inspectCapture(contextArg) {
+        const capture = this.captures.get(contextArg.captureId);
+        if (!capture)
+            return { status: 'missing' };
+        return capture.outcome ? { status: 'finalized', outcome: capture.outcome } : { status: 'prepared' };
+    }
+    async finalize(contextArg) {
+        contextArg.signal.throwIfAborted();
+        const capture = this.requireCapture(contextArg.captureId);
+        if (capture.outcome)
+            return capture.outcome;
+        const reference = { captureId: capture.captureId };
+        if (!capture.nonrevertibleReason) {
+            for (const [filePath, record] of capture.files) {
+                record.after = await readFileImage(filePath);
+                if (fileImagesEqual(record.before, record.after))
+                    capture.files.delete(filePath);
+            }
+        }
+        capture.state = 'finalized';
+        if (capture.nonrevertibleReason) {
+            capture.outcome = {
+                disposition: 'nonrevertible',
+                reference: { ...reference },
+                reasonCode: capture.nonrevertibleReason,
+                affectedWorkspaces: [this.workspace],
+            };
+        }
+        else if (capture.files.size === 0) {
+            capture.outcome = { disposition: 'no-change', reference: { ...reference } };
+        }
+        else {
+            capture.outcome = { disposition: 'revertible', reference: { ...reference }, affectedWorkspaces: [this.workspace] };
+        }
+        this.captureIdsByRun.delete(capture.runId);
+        return capture.outcome;
+    }
+    async apply(contextArg) {
+        contextArg.signal.throwIfAborted();
+        const capture = this.captureOf(contextArg.reference);
+        if (capture.outcome?.disposition !== 'revertible') {
+            throw new Error('This turn has no revertible workspace changes.');
+        }
+        const records = [...capture.files.entries()];
+        const expected = (recordArg) => (contextArg.direction === 'undo' ? recordArg.after : recordArg.before);
+        const target = (recordArg) => (contextArg.direction === 'undo' ? recordArg.before : recordArg.after);
+        for (const [filePath, record] of records) {
+            if (!fileImagesEqual(await readFileImage(filePath), expected(record))) {
+                throw new Error(`"${filePath}" changed after the turn; its changes were not ${contextArg.direction === 'undo' ? 'undone' : 'redone'}.`);
+            }
+        }
+        const written = [];
+        try {
+            for (const entry of records) {
+                await writeFileImage(entry[0], target(entry[1]));
+                written.push(entry);
+            }
+        }
+        catch (error) {
+            await this.rollBack(written, expected, contextArg.operationId, capture);
+            throw error;
+        }
+        if (contextArg.direction === 'undo') {
+            for (const [, record] of records)
+                await removeEmptyDirectories(record.createdDirectories);
+        }
+        capture.appliedOperations.add(contextArg.operationId);
+    }
+    inspectApply(contextArg) {
+        const capture = this.captures.get(isCaptureReference(contextArg.reference) ? contextArg.reference.captureId : '');
+        if (!capture)
+            return { status: 'not-applied' };
+        if (capture.appliedOperations.has(contextArg.operationId))
+            return { status: 'applied' };
+        if (capture.uncertainOperations.has(contextArg.operationId))
+            return { status: 'unknown' };
+        return { status: 'not-applied' };
+    }
+    release(contextArg) {
+        const captureId = isCaptureReference(contextArg.reference) ? contextArg.reference.captureId : contextArg.captureId;
+        const capture = this.captures.get(captureId);
+        if (!capture)
+            return;
+        this.captures.delete(captureId);
+        if (this.captureIdsByRun.get(capture.runId) === captureId)
+            this.captureIdsByRun.delete(capture.runId);
+    }
+    async recordChange(runIdArg, changeArg) {
+        const capture = this.requirePreparedCapture(runIdArg);
+        if (capture.nonrevertibleReason || capture.files.has(changeArg.path))
+            return;
+        const before = await readFileImage(changeArg.path);
+        const createdDirectories = before.kind === 'absent' && changeArg.kind === 'write'
+            ? await missingAncestors(changeArg.path)
+            : [];
+        if (capture.files.has(changeArg.path))
+            return;
+        capture.bytes += fileImageBytes(before);
+        if (capture.bytes > this.maxCaptureBytes) {
+            this.markNonrevertible(capture, 'capture-too-large');
+            return;
+        }
+        capture.files.set(changeArg.path, { before, createdDirectories });
+    }
+    markNonrevertible(captureArg, reasonArg) {
+        captureArg.nonrevertibleReason ??= reasonArg;
+        captureArg.files.clear();
+        captureArg.bytes = 0;
+    }
+    async rollBack(writtenArg, expectedArg, operationIdArg, captureArg) {
+        try {
+            for (const [filePath, record] of writtenArg.reverse())
+                await writeFileImage(filePath, expectedArg(record));
+        }
+        catch {
+            // the workspace holds part of the change; FlexHarness learns that the outcome is unknown
+            captureArg.uncertainOperations.add(operationIdArg);
+        }
+    }
+    requirePreparedCapture(runIdArg) {
+        const captureId = this.captureIdsByRun.get(runIdArg);
+        const capture = captureId ? this.captures.get(captureId) : undefined;
+        if (!capture || capture.state !== 'prepared') {
+            throw new Error(`No workspace capture is open for run "${runIdArg}"; the change was refused.`);
+        }
+        return capture;
+    }
+    requireCapture(captureIdArg) {
+        const capture = this.captures.get(captureIdArg);
+        if (!capture)
+            throw new Error(`The workspace capture "${captureIdArg}" is not held.`);
+        return capture;
+    }
+    captureOf(referenceArg) {
+        if (!isCaptureReference(referenceArg))
+            throw new Error('The workspace capture reference is malformed.');
+        const capture = this.captures.get(referenceArg.captureId);
+        if (!capture)
+            throw new Error('The workspace changes of this turn are no longer held in memory.');
+        return capture;
+    }
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY2xhc3Nlcy53b3Jrc3BhY2VyZXZlcnNpb24uanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi90c190b29sc19ub2RlL2NsYXNzZXMud29ya3NwYWNlcmV2ZXJzaW9uLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLE9BQU8sS0FBSyxPQUFPLE1BQU0sY0FBYyxDQUFDO0FBRXhDLE9BQU8sRUFDTCxjQUFjLEVBQ2QsZUFBZSxFQUNmLGdCQUFnQixFQUNoQixhQUFhLEVBQ2Isc0JBQXNCLEVBQ3RCLGNBQWMsR0FFZixNQUFNLDJCQUEyQixDQUFDO0FBcUNuQyxNQUFNLHlCQUF5QixHQUFHLEVBQUUsR0FBRyxJQUFJLEdBQUcsSUFBSSxDQUFDO0FBRW5ELE1BQU0sa0JBQWtCLEdBQUcsQ0FBQyxRQUE0QixFQUFzRCxFQUFFLENBQzlHLENBQUMsQ0FBQyxRQUFRO09BQ1AsT0FBTyxRQUFRLEtBQUssUUFBUTtPQUM1QixDQUFDLEtBQUssQ0FBQyxPQUFPLENBQUMsUUFBUSxDQUFDO09BQ3hCLE9BQU8sUUFBUSxDQUFDLFNBQVMsS0FBSyxRQUFRLENBQUM7QUFFNUM7Ozs7Ozs7Ozs7Ozs7O0dBY0c7QUFDSCxNQUFNLE9BQU8sMEJBQTBCO0lBQ3JCLGVBQWUsR0FBRyxDQUFDLENBQUM7SUFFbkIsU0FBUyxDQUFpQztJQUMxQyxlQUFlLENBQVM7SUFDeEIsUUFBUSxHQUFHLElBQUksR0FBRyxFQUFvQixDQUFDO0lBQ3ZDLGVBQWUsR0FBRyxJQUFJLEdBQUcsRUFBa0IsQ0FBQztJQUU3RCxZQUFZLFVBQThDO1FBQ3hELElBQUksQ0FBQyxTQUFTLEdBQUcsRUFBRSxFQUFFLEVBQUUsVUFBVSxDQUFDLFNBQVMsQ0FBQyxFQUFFLEVBQUUsS0FBSyxFQUFFLFVBQVUsQ0FBQyxTQUFTLENBQUMsS0FBSyxFQUFFLENBQUM7UUFDcEYsSUFBSSxDQUFDLGVBQWUsR0FBRyxVQUFVLENBQUMsZUFBZSxJQUFJLHlCQUF5QixDQUFDO1FBQy9FLElBQUksQ0FBQyxN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

package/dist_ts_tools_node/functions.fileimages.d.ts

@@ -0,0 +1,22 @@
+/** What one path holds at a moment: nothing, a regular file, or a symbolic link. */
+export type TFileImage = {
+    kind: 'absent';
+} | {
+    kind: 'file';
+    bytes: Buffer;
+    mode: number;
+} | {
+    kind: 'symlink';
+    target: string;
+};
+/** Reads what the path holds, without following a final symbolic link. */
+export declare const readFileImage: (pathArg: string) => Promise<TFileImage>;
+/** The bytes an image keeps in memory. */
+export declare const fileImageBytes: (imageArg: TFileImage) => number;
+export declare const fileImagesEqual: (leftArg: TFileImage, rightArg: TFileImage) => boolean;
+/** Puts the image at the path, creating parent directories as needed. */
+export declare const writeFileImage: (pathArg: string, imageArg: TFileImage) => Promise<void>;
+/** The ancestors of the path that do not exist yet, deepest first: a write would create them. */
+export declare const missingAncestors: (pathArg: string) => Promise<string[]>;
+/** Removes the directories, deepest first, as far as they are empty. */
+export declare const removeEmptyDirectories: (directoriesArg: readonly string[]) => Promise<void>;

package/dist_ts_tools_node/functions.fileimages.js

@@ -0,0 +1,87 @@
+import * as plugins from './plugins.js';
+const isMissing = (error) => {
+    const code = error.code;
+    return code === 'ENOENT' || code === 'ENOTDIR';
+};
+/** Reads what the path holds, without following a final symbolic link. */
+export const readFileImage = async (pathArg) => {
+    let stats;
+    try {
+        stats = await plugins.fs.promises.lstat(pathArg);
+    }
+    catch (error) {
+        if (isMissing(error))
+            return { kind: 'absent' };
+        throw error;
+    }
+    if (stats.isSymbolicLink())
+        return { kind: 'symlink', target: await plugins.fs.promises.readlink(pathArg) };
+    if (stats.isFile())
+        return { kind: 'file', bytes: await plugins.fs.promises.readFile(pathArg), mode: stats.mode & 0o7777 };
+    throw new Error(`"${pathArg}" is neither a file nor a symbolic link.`);
+};
+/** The bytes an image keeps in memory. */
+export const fileImageBytes = (imageArg) => imageArg.kind === 'file'
+    ? imageArg.bytes.byteLength
+    : imageArg.kind === 'symlink'
+        ? Buffer.byteLength(imageArg.target)
+        : 0;
+export const fileImagesEqual = (leftArg, rightArg) => {
+    if (leftArg.kind === 'absent' || rightArg.kind === 'absent')
+        return leftArg.kind === rightArg.kind;
+    if (leftArg.kind === 'symlink' || rightArg.kind === 'symlink') {
+        return leftArg.kind === 'symlink' && rightArg.kind === 'symlink' && leftArg.target === rightArg.target;
+    }
+    return leftArg.bytes.equals(rightArg.bytes);
+};
+/** Puts the image at the path, creating parent directories as needed. */
+export const writeFileImage = async (pathArg, imageArg) => {
+    if (imageArg.kind === 'absent') {
+        await plugins.fs.promises.rm(pathArg, { force: true });
+        return;
+    }
+    await plugins.fs.promises.mkdir(plugins.path.dirname(pathArg), { recursive: true });
+    if (imageArg.kind === 'symlink') {
+        await plugins.fs.promises.rm(pathArg, { force: true });
+        await plugins.fs.promises.symlink(imageArg.target, pathArg);
+        return;
+    }
+    if ((await readFileImage(pathArg)).kind === 'symlink')
+        await plugins.fs.promises.rm(pathArg);
+    await plugins.fs.promises.writeFile(pathArg, imageArg.bytes);
+    await plugins.fs.promises.chmod(pathArg, imageArg.mode);
+};
+/** The ancestors of the path that do not exist yet, deepest first: a write would create them. */
+export const missingAncestors = async (pathArg) => {
+    const missing = [];
+    let current = plugins.path.dirname(pathArg);
+    while (current !== plugins.path.dirname(current)) {
+        try {
+            await plugins.fs.promises.lstat(current);
+            break;
+        }
+        catch (error) {
+            if (!isMissing(error))
+                throw error;
+            missing.push(current);
+            current = plugins.path.dirname(current);
+        }
+    }
+    return missing;
+};
+/** Removes the directories, deepest first, as far as they are empty. */
+export const removeEmptyDirectories = async (directoriesArg) => {
+    for (const directory of directoriesArg) {
+        try {
+            await plugins.fs.promises.rmdir(directory);
+        }
+        catch (error) {
+            const code = error.code;
+            if (code === 'ENOTEMPTY' || code === 'EEXIST')
+                return;
+            if (!isMissing(error))
+                throw error;
+        }
+    }
+};
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZnVuY3Rpb25zLmZpbGVpbWFnZXMuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi90c190b29sc19ub2RlL2Z1bmN0aW9ucy5maWxlaW1hZ2VzLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLE9BQU8sS0FBSyxPQUFPLE1BQU0sY0FBYyxDQUFDO0FBUXhDLE1BQU0sU0FBUyxHQUFHLENBQUMsS0FBYyxFQUFXLEVBQUU7SUFDNUMsTUFBTSxJQUFJLEdBQUksS0FBK0IsQ0FBQyxJQUFJLENBQUM7SUFDbkQsT0FBTyxJQUFJLEtBQUssUUFBUSxJQUFJLElBQUksS0FBSyxTQUFTLENBQUM7QUFDakQsQ0FBQyxDQUFDO0FBRUYsMEVBQTBFO0FBQzFFLE1BQU0sQ0FBQyxNQUFNLGFBQWEsR0FBRyxLQUFLLEVBQUUsT0FBZSxFQUF1QixFQUFFO0lBQzFFLElBQUksS0FBdUIsQ0FBQztJQUM1QixJQUFJLENBQUM7UUFDSCxLQUFLLEdBQUcsTUFBTSxPQUFPLENBQUMsRUFBRSxDQUFDLFFBQVEsQ0FBQyxLQUFLLENBQUMsT0FBTyxDQUFDLENBQUM7SUFDbkQsQ0FBQztJQUFDLE9BQU8sS0FBSyxFQUFFLENBQUM7UUFDZixJQUFJLFNBQVMsQ0FBQyxLQUFLLENBQUM7WUFBRSxPQUFPLEVBQUUsSUFBSSxFQUFFLFFBQVEsRUFBRSxDQUFDO1FBQ2hELE1BQU0sS0FBSyxDQUFDO0lBQ2QsQ0FBQztJQUNELElBQUksS0FBSyxDQUFDLGNBQWMsRUFBRTtRQUFFLE9BQU8sRUFBRSxJQUFJLEVBQUUsU0FBUyxFQUFFLE1BQU0sRUFBRSxNQUFNLE9BQU8sQ0FBQyxFQUFFLENBQUMsUUFBUSxDQUFDLFFBQVEsQ0FBQyxPQUFPLENBQUMsRUFBRSxDQUFDO0lBQzVHLElBQUksS0FBSyxDQUFDLE1BQU0sRUFBRTtRQUFFLE9BQU8sRUFBRSxJQUFJLEVBQUUsTUFBTSxFQUFFLEtBQUssRUFBRSxNQUFNLE9BQU8sQ0FBQyxFQUFFLENBQUMsUUFBUSxDQUFDLFFBQVEs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

package/dist_ts_tools_node/index.d.ts

@@ -1,5 +1,7 @@
 export { createLocalToolExecutionContext } from './tool.context.js';
-export type { ILocalToolExecutionContextOptions } from './tool.context.js';
+export type { ILocalToolExecutionContextOptions, IToolFileChange, IToolFileChangeObserver, } from './tool.context.js';
+export { InMemoryWorkspaceReversion } from './classes.workspacereversion.js';
+export type { IInMemoryWorkspaceReversionOptions } from './classes.workspacereversion.js';
 export { FileToolJobStore } from './tool.persistence.js';
 export type { IFileToolJobStoreOptions } from './tool.persistence.js';
 export * from './tools.local.js';

package/dist_ts_tools_node/index.js

@@ -1,4 +1,5 @@
 export { createLocalToolExecutionContext } from './tool.context.js';
+export { InMemoryWorkspaceReversion } from './classes.workspacereversion.js';
 export { FileToolJobStore } from './tool.persistence.js';
 export * from './tools.local.js';
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi90c190b29sc19ub2RlL2luZGV4LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLE9BQU8sRUFBRSwrQkFBK0IsRUFBRSxNQUFNLG1CQUFtQixDQUFDO0FBRXBFLE9BQU8sRUFBRSxnQkFBZ0IsRUFBRSxNQUFNLHVCQUF1QixDQUFDO0FBRXpELGNBQWMsa0JBQWtCLENBQUMifQ==
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi90c190b29sc19ub2RlL2luZGV4LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLE9BQU8sRUFBRSwrQkFBK0IsRUFBRSxNQUFNLG1CQUFtQixDQUFDO0FBTXBFLE9BQU8sRUFBRSwwQkFBMEIsRUFBRSxNQUFNLGlDQUFpQyxDQUFDO0FBRTdFLE9BQU8sRUFBRSxnQkFBZ0IsRUFBRSxNQUFNLHVCQUF1QixDQUFDO0FBRXpELGNBQWMsa0JBQWtCLENBQUMifQ==

package/dist_ts_tools_node/plugins.d.ts

@@ -11,3 +11,4 @@ import { createFilesystemTools, createShellTools } from '@modelprofile.com/flexh
 export { createFilesystemTools, createShellTools };
 export type { ICreateFilesystemToolsOptions, ICreateShellToolsOptions, ToolSet } from '@modelprofile.com/flexharness/tools';
 export type { IBrowserToolInput, IShellCommand, IShellFinishedResult, IShellStartedResult, IToolBrowserContext, IToolBrowserRunOptions, IToolExecutionContext, IToolFilesystemContext, IToolFilesystemListOptions, IToolFilesystemReadOptions, IToolInvocationOptions, IToolJobContext, IToolJobEvent, IToolJobHandle, IToolJobOutputEvent, IToolJobRequest, IToolJobSnapshot, IToolJobState, IToolJobStore, IToolPermissionRequest, IToolRunOptions, IToolShellContext, IToolShellResult, TBrowserToolAction, TToolJobEvent, TToolJobEventListener, } from '@modelprofile.com/flexharness-agent';
+export type { IFlexAffectedWorkspace, IFlexTurnReversionApplyContext, IFlexTurnReversionApplyInspection, IFlexTurnReversionBaseContext, IFlexTurnReversionProviderV2, IFlexTurnReversionReleaseContext, TFlexTurnReversionCaptureInspectionV2, TFlexTurnReversionFinalizedOutcome, TJsonValue, } from '@modelprofile.com/flexharness';

package/dist_ts_tools_node/tool.context.d.ts

@@ -1,4 +1,22 @@
 import type { IToolJobStore, IToolPermissionRequest, IToolJobState, IToolExecutionContext } from './plugins.js';
+/** A file a tool is about to change, named by its canonical path. */
+export interface IToolFileChange {
+    kind: 'write' | 'delete';
+    /**
+     * The canonical absolute path the operation changes. A write follows a symlink to its target; a
+     * delete removes the link itself, so its path is the link's.
+     */
+    path: string;
+}
+/**
+ * Sees every change the local filesystem tools make, after the path checks and before the change,
+ * and every shell command before it starts. A rejection refuses the operation.
+ */
+export interface IToolFileChangeObserver {
+    beforeFileChange(change: IToolFileChange): Promise<void> | void;
+    /** A shell command or background job may change files the observer does not see. */
+    beforeShellCommand(): Promise<void> | void;
+}
 export interface ILocalToolExecutionContextOptions {
     cwd?: string;
     rootDir?: string;
@@ -7,6 +25,8 @@ export interface ILocalToolExecutionContextOptions {
     abortSignal?: AbortSignal;
     /** Guards each local filesystem operation or shell side effect. */
     beforeOperation?: () => Promise<void> | void;
+    /** Observes every file change and shell command, for example to capture a turn for undo. */
+    fileChangeObserver?: IToolFileChangeObserver;
     /** Hard combined stdout/stderr capture limit for each local shell command. Default: 1 MiB. */
     maxShellOutputBytes?: number;
     /** Number of terminal background job snapshots retained for get/list. Default: 100. */