@modelprofile.com/flexharness 6.1.0 → 7.0.0

package/ts_tools_node/tool.context.ts

@@ -0,0 +1,991 @@
+import * as plugins from './plugins.js';
+import type { IToolJobStore } from '@modelprofile.com/flexharness-agent';
+import type { IToolPermissionRequest, IToolInvocationOptions, IToolRunOptions, IToolShellResult, IShellCommand, IToolShellContext, IToolJobRequest, IShellStartedResult, IShellFinishedResult, IToolJobState, IToolJobHandle, IToolJobEvent, IToolJobOutputEvent, TToolJobEvent, TToolJobEventListener, IToolJobContext, IToolFilesystemReadOptions, IToolFilesystemListOptions, IToolFilesystemContext, IToolBrowserRunOptions, TBrowserToolAction, IBrowserToolInput, IToolBrowserContext, IToolExecutionContext } from '@modelprofile.com/flexharness-agent';
+
+export interface ILocalToolExecutionContextOptions {
+  cwd?: string;
+  rootDir?: string;
+  /** Additional canonical roots available to filesystem read/list operations only. */
+  additionalReadOnlyRoots?: string[];
+  abortSignal?: AbortSignal;
+  /** Guards each local filesystem operation or shell side effect. */
+  beforeOperation?: () => Promise<void> | void;
+  /** 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. */
+  maxRetainedJobs?: number;
+  /** Optional durable store used to restore terminal jobs after host restarts. */
+  jobStore?: IToolJobStore;
+  /** Maximum wait for each local shell output listener before its process is terminated. Default: 30 seconds. */
+  outputListenerTimeoutMs?: number;
+  /** Maximum wait for job-store load/save operations. Defaults to outputListenerTimeoutMs. */
+  jobStoreOperationTimeoutMs?: number;
+  /** Reconciles a persisted running job whose original process ownership was lost. */
+  settleOrphanedJob?: (
+    job: IToolJobState,
+    abortSignal: AbortSignal,
+  ) => Promise<IToolJobState> | IToolJobState;
+  requestPermission?: (request: IToolPermissionRequest) => Promise<void>;
+}
+
+const DEFAULT_LOCAL_SHELL_MAX_OUTPUT_BYTES = 1024 * 1024;
+const LOCAL_SHELL_KILL_GRACE_MS = 1000;
+
+export const createLocalToolExecutionContext = (options: ILocalToolExecutionContextOptions = {}): IToolExecutionContext => {
+  const cwd = options.cwd ?? process.cwd();
+  const rootDir = options.rootDir;
+  const additionalReadOnlyRoots = [...new Set((options.additionalReadOnlyRoots ?? []).map(
+    (rootDirArg, index) => {
+      if (typeof rootDirArg !== 'string' || !rootDirArg.trim()) {
+        throw new Error(`additionalReadOnlyRoots[${index}] must be a non-empty path.`);
+      }
+      return plugins.path.resolve(rootDirArg);
+    },
+  ))];
+  const maxShellOutputBytes = options.maxShellOutputBytes ?? DEFAULT_LOCAL_SHELL_MAX_OUTPUT_BYTES;
+  if (!Number.isSafeInteger(maxShellOutputBytes) || maxShellOutputBytes <= 0) {
+    throw new Error('maxShellOutputBytes must be a positive integer.');
+  }
+  const maxRetainedJobs = options.maxRetainedJobs ?? 100;
+  if (!Number.isSafeInteger(maxRetainedJobs) || maxRetainedJobs < 0) {
+    throw new Error('maxRetainedJobs must be a non-negative integer.');
+  }
+  const outputListenerTimeoutMs = options.outputListenerTimeoutMs ?? 30_000;
+  if (!Number.isSafeInteger(outputListenerTimeoutMs) || outputListenerTimeoutMs <= 0) {
+    throw new Error('outputListenerTimeoutMs must be a positive integer.');
+  }
+  const jobStoreOperationTimeoutMs = options.jobStoreOperationTimeoutMs
+    ?? outputListenerTimeoutMs;
+  if (!Number.isSafeInteger(jobStoreOperationTimeoutMs) || jobStoreOperationTimeoutMs <= 0) {
+    throw new Error('jobStoreOperationTimeoutMs must be a positive integer.');
+  }
+  const jobs = createLocalToolJobContext({
+    cwd,
+    rootDir,
+    maxOutputBytes: maxShellOutputBytes,
+    maxRetainedJobs,
+    jobStore: options.jobStore,
+    outputListenerTimeoutMs,
+    jobStoreOperationTimeoutMs,
+    settleOrphanedJob: options.settleOrphanedJob,
+    beforeOperation: options.beforeOperation,
+    abortSignal: options.abortSignal,
+  });
+  return {
+    cwd,
+    rootDir,
+    additionalReadOnlyRoots,
+    abortSignal: options.abortSignal,
+    requestPermission: options.requestPermission,
+    shell: {
+      run: (command, runOptions) => runLocalShellCommand(command, {
+        cwd: resolveLocalPath(runOptions?.cwd ?? cwd, rootDir),
+        timeoutMs: runOptions?.timeoutMs,
+        abortSignal: runOptions?.abortSignal ?? options.abortSignal,
+        onOutput: runOptions?.onOutput,
+        outputListenerTimeoutMs,
+        maxOutputBytes: maxShellOutputBytes,
+        beforeOperation: options.beforeOperation,
+      }),
+      runStructured: (command, runOptions) => runLocalStructuredCommand(command, {
+        cwd: resolveLocalPath(runOptions?.cwd ?? cwd, rootDir),
+        timeoutMs: runOptions?.timeoutMs,
+        abortSignal: runOptions?.abortSignal ?? options.abortSignal,
+        onOutput: runOptions?.onOutput,
+        outputListenerTimeoutMs,
+        maxOutputBytes: maxShellOutputBytes,
+        beforeOperation: options.beforeOperation,
+      }),
+    },
+    jobs,
+    fs: {
+      readFile: async (filePath, readOptions, invocationOptions) => {
+        const abortSignal = invocationOptions?.abortSignal ?? options.abortSignal;
+        throwIfAborted(abortSignal);
+        const resolved = resolveLocalReadPath(filePath, rootDir, cwd);
+        const readRoots = plugins.path.isAbsolute(filePath)
+          ? [...(rootDir ? [rootDir] : []), ...additionalReadOnlyRoots]
+          : rootDir
+            ? [rootDir]
+            : [];
+        const operationPath = readRoots.length > 0
+          ? await resolveCanonicalExistingLocalReadPath(resolved, filePath, readRoots)
+          : resolved;
+        await runBeforeLocalOperation(options.beforeOperation, abortSignal);
+        const content = await plugins.fs.promises.readFile(operationPath, 'utf8');
+        throwIfAborted(abortSignal);
+        if (readOptions?.startLine !== undefined || readOptions?.endLine !== undefined) {
+          const lines = content.split('\n');
+          const start = Math.max((readOptions.startLine ?? 1) - 1, 0);
+          const end = Math.max(readOptions.endLine ?? lines.length, start);
+          return lines.slice(start, end).join('\n');
+        }
+        return content;
+      },
+      writeFile: async (filePath, content, invocationOptions) => {
+        const abortSignal = invocationOptions?.abortSignal ?? options.abortSignal;
+        throwIfAborted(abortSignal);
+        const resolved = resolveLocalPath(filePath, rootDir, cwd);
+        const parentPath = plugins.path.dirname(resolved);
+        const canonicalBoundary = rootDir
+          ? {
+              rootDir,
+              canonicalRoot: await resolveCanonicalProspectivePath(plugins.path.resolve(rootDir)),
+            }
+          : undefined;
+        if (canonicalBoundary) {
+          const canonicalProspectiveParent = await resolveCanonicalProspectivePath(parentPath);
+          assertCanonicalPathAllowed(
+            canonicalProspectiveParent,
+            canonicalBoundary.canonicalRoot,
+            filePath,
+            canonicalBoundary.rootDir,
+          );
+          await assertExistingWriteTargetAllowed(
+            resolved,
+            canonicalBoundary.canonicalRoot,
+            filePath,
+            canonicalBoundary.rootDir,
+          );
+        }
+        await runBeforeLocalOperation(options.beforeOperation, abortSignal);
+        await plugins.fs.promises.mkdir(parentPath, { recursive: true });
+        throwIfAborted(abortSignal);
+        if (canonicalBoundary) {
+          const canonicalParent = await plugins.fs.promises.realpath(parentPath);
+          assertCanonicalPathAllowed(
+            canonicalParent,
+            canonicalBoundary.canonicalRoot,
+            filePath,
+            canonicalBoundary.rootDir,
+          );
+          await assertExistingWriteTargetAllowed(
+            resolved,
+            canonicalBoundary.canonicalRoot,
+            filePath,
+            canonicalBoundary.rootDir,
+          );
+        }
+        await plugins.fs.promises.writeFile(resolved, content, 'utf8');
+        throwIfAborted(abortSignal);
+        return `Written ${Buffer.byteLength(content, 'utf8')} bytes to ${filePath}`;
+      },
+      listDirectory: async (directoryPath, listOptions, invocationOptions) => {
+        const abortSignal = invocationOptions?.abortSignal ?? options.abortSignal;
+        throwIfAborted(abortSignal);
+        const resolved = resolveLocalReadPath(directoryPath, rootDir, cwd);
+        const readRoots = plugins.path.isAbsolute(directoryPath)
+          ? [...(rootDir ? [rootDir] : []), ...additionalReadOnlyRoots]
+          : rootDir
+            ? [rootDir]
+            : [];
+        const operationPath = readRoots.length > 0
+          ? await resolveCanonicalExistingLocalReadPath(resolved, directoryPath, readRoots)
+          : resolved;
+        await runBeforeLocalOperation(options.beforeOperation, abortSignal);
+        const result = await listLocalDirectory(operationPath, !!listOptions?.recursive, abortSignal);
+        throwIfAborted(abortSignal);
+        return result;
+      },
+      deletePath: async (targetPath, invocationOptions) => {
+        const abortSignal = invocationOptions?.abortSignal ?? options.abortSignal;
+        throwIfAborted(abortSignal);
+        const resolved = resolveLocalPath(targetPath, rootDir, cwd);
+        if (rootDir) {
+          await resolveCanonicalExistingLocalPath(resolved, targetPath, rootDir);
+        }
+        await runBeforeLocalOperation(options.beforeOperation, abortSignal);
+        await plugins.fs.promises.rm(resolved, { recursive: false, force: false });
+        throwIfAborted(abortSignal);
+        return `Deleted ${targetPath}`;
+      },
+    },
+  };
+};
+
+const resolveLocalPath = (targetPath: string, rootDir?: string, baseDir?: string): string => {
+  const base = rootDir ?? baseDir ?? process.cwd();
+  const resolved = plugins.path.isAbsolute(targetPath)
+    ? plugins.path.resolve(targetPath)
+    : plugins.path.resolve(base, targetPath);
+  if (rootDir) {
+    const resolvedRoot = plugins.path.resolve(rootDir);
+    if (resolved !== resolvedRoot && !resolved.startsWith(resolvedRoot + plugins.path.sep)) {
+      throw new Error(`Access denied: "${targetPath}" is outside allowed root "${rootDir}"`);
+    }
+  }
+  return resolved;
+};
+
+const resolveLocalReadPath = (
+  targetPath: string,
+  rootDir?: string,
+  baseDir?: string,
+): string => plugins.path.isAbsolute(targetPath)
+  ? plugins.path.resolve(targetPath)
+  : plugins.path.resolve(rootDir ?? baseDir ?? process.cwd(), targetPath);
+
+const resolveCanonicalExistingLocalReadPath = async (
+  resolvedPath: string,
+  targetPath: string,
+  readRoots: string[],
+): Promise<string> => {
+  const canonicalPath = await plugins.fs.promises.realpath(resolvedPath);
+  for (const readRoot of readRoots) {
+    const canonicalRoot = await resolveCanonicalProspectivePath(plugins.path.resolve(readRoot));
+    if (canonicalPathIsAllowed(canonicalPath, canonicalRoot)) return canonicalPath;
+  }
+  throw new Error(`Access denied: "${targetPath}" resolves outside allowed read roots.`);
+};
+
+const resolveCanonicalExistingLocalPath = async (
+  resolvedPath: string,
+  targetPath: string,
+  rootDir: string,
+): Promise<string> => {
+  const canonicalRoot = await resolveCanonicalProspectivePath(plugins.path.resolve(rootDir));
+  const canonicalPath = await plugins.fs.promises.realpath(resolvedPath);
+  assertCanonicalPathAllowed(canonicalPath, canonicalRoot, targetPath, rootDir);
+  return canonicalPath;
+};
+
+const resolveCanonicalProspectivePath = async (targetPath: string): Promise<string> => {
+  let existingAncestor = targetPath;
+  while (true) {
+    try {
+      const canonicalAncestor = await plugins.fs.promises.realpath(existingAncestor);
+      return plugins.path.resolve(
+        canonicalAncestor,
+        plugins.path.relative(existingAncestor, targetPath),
+      );
+    } catch (error) {
+      const errorCode = (error as NodeJS.ErrnoException).code;
+      if (errorCode !== 'ENOENT' && errorCode !== 'ENOTDIR') {
+        throw error;
+      }
+      const parentPath = plugins.path.dirname(existingAncestor);
+      if (parentPath === existingAncestor) {
+        throw error;
+      }
+      existingAncestor = parentPath;
+    }
+  }
+};
+
+const assertExistingWriteTargetAllowed = async (
+  resolvedPath: string,
+  canonicalRoot: string,
+  targetPath: string,
+  rootDir: string,
+): Promise<void> => {
+  try {
+    await plugins.fs.promises.lstat(resolvedPath);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+      return;
+    }
+    throw error;
+  }
+  let canonicalTarget: string;
+  try {
+    canonicalTarget = await plugins.fs.promises.realpath(resolvedPath);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+      throw createAccessDeniedError(targetPath, rootDir);
+    }
+    throw error;
+  }
+  assertCanonicalPathAllowed(canonicalTarget, canonicalRoot, targetPath, rootDir);
+};
+
+const assertCanonicalPathAllowed = (
+  canonicalPath: string,
+  canonicalRoot: string,
+  targetPath: string,
+  rootDir: string,
+): void => {
+  if (!canonicalPathIsAllowed(canonicalPath, canonicalRoot)) {
+    throw createAccessDeniedError(targetPath, rootDir);
+  }
+};
+
+const canonicalPathIsAllowed = (
+  canonicalPath: string,
+  canonicalRoot: string,
+): boolean => {
+  const relativePath = plugins.path.relative(canonicalRoot, canonicalPath);
+  return relativePath !== '..'
+    && !relativePath.startsWith(`..${plugins.path.sep}`)
+    && !plugins.path.isAbsolute(relativePath);
+};
+
+const createAccessDeniedError = (targetPath: string, rootDir: string): Error =>
+  new Error(`Access denied: "${targetPath}" resolves outside canonical root "${rootDir}"`);
+
+const throwIfAborted = (abortSignal?: AbortSignal): void => {
+  abortSignal?.throwIfAborted();
+};
+
+const runBeforeLocalOperation = async (
+  beforeOperation: ILocalToolExecutionContextOptions['beforeOperation'],
+  abortSignal?: AbortSignal,
+): Promise<void> => {
+  throwIfAborted(abortSignal);
+  if (!beforeOperation) return;
+  const guardPromise = Promise.resolve().then(() => beforeOperation());
+  void guardPromise.catch(() => undefined);
+  if (!abortSignal) {
+    await guardPromise;
+    return;
+  }
+  let onAbort!: () => void;
+  const aborted = new Promise<never>((_resolve, reject) => {
+    onAbort = () => reject(
+      abortSignal.reason ?? new DOMException('Local operation aborted', 'AbortError'),
+    );
+    abortSignal.addEventListener('abort', onAbort, { once: true });
+    if (abortSignal.aborted) onAbort();
+  });
+  try {
+    await Promise.race([guardPromise, aborted]);
+  } finally {
+    abortSignal.removeEventListener('abort', onAbort);
+  }
+  throwIfAborted(abortSignal);
+};
+
+const listLocalDirectory = async (
+  directoryPath: string,
+  recursive: boolean,
+  abortSignal?: AbortSignal,
+): Promise<string[]> => {
+  throwIfAborted(abortSignal);
+  const entries = await plugins.fs.promises.readdir(directoryPath, { withFileTypes: true });
+  throwIfAborted(abortSignal);
+  const result: string[] = [];
+  for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+    throwIfAborted(abortSignal);
+    const relativePath = entry.name + (entry.isDirectory() ? '/' : '');
+    result.push(relativePath);
+    if (recursive && entry.isDirectory()) {
+      const childEntries = await listLocalDirectory(
+        plugins.path.join(directoryPath, entry.name),
+        true,
+        abortSignal,
+      );
+      result.push(...childEntries.map((childEntry) => `${entry.name}/${childEntry}`));
+    }
+  }
+  throwIfAborted(abortSignal);
+  return result;
+};
+
+type TLocalShellTerminationReason = 'abort' | 'error' | 'timeout' | 'output-limit' | 'output-listener';
+
+/** @internal */
+export const handleLocalShellChildError = (
+  error: Error,
+  childPid: number | undefined,
+  handlers: {
+    settleSpawnFailure: (error: Error) => void;
+    retainError: (error: Error) => void;
+    requestTermination: () => void;
+  },
+): void => {
+  if (childPid === undefined) {
+    handlers.settleSpawnFailure(error);
+    return;
+  }
+  handlers.retainError(error);
+  handlers.requestTermination();
+};
+
+const runLocalShellCommand = async (
+  command: string,
+  options: IToolRunOptions & {
+    maxOutputBytes: number;
+    outputListenerTimeoutMs?: number;
+    beforeOperation?: ILocalToolExecutionContextOptions['beforeOperation'];
+  },
+): Promise<IToolShellResult> => runLocalProcessCommand(command, options);
+
+const runLocalStructuredCommand = async (
+  command: IShellCommand,
+  options: IToolRunOptions & {
+    maxOutputBytes: number;
+    outputListenerTimeoutMs?: number;
+    beforeOperation?: ILocalToolExecutionContextOptions['beforeOperation'];
+  },
+): Promise<IToolShellResult> => {
+  validateLocalStructuredCommand(command);
+  return runLocalProcessCommand(command, options);
+};
+
+const validateLocalStructuredCommand = (command: IShellCommand): void => {
+  if (!command.executable.trim()) throw new Error('Structured shell executable must not be empty.');
+  if (!command.args.every((argument) => typeof argument === 'string')) {
+    throw new Error('Structured shell arguments must all be strings.');
+  }
+};
+
+const runLocalProcessCommand = async (
+  command: string | IShellCommand,
+  options: IToolRunOptions & {
+    maxOutputBytes: number;
+    outputListenerTimeoutMs?: number;
+    beforeOperation?: ILocalToolExecutionContextOptions['beforeOperation'];
+  },
+): Promise<IToolShellResult> => {
+  if (options.beforeOperation) {
+    await runBeforeLocalOperation(options.beforeOperation, options.abortSignal);
+  } else {
+    throwIfAborted(options.abortSignal);
+  }
+  return new Promise<IToolShellResult>((resolve) => {
+    const ownsProcessGroup = process.platform !== 'win32';
+    const executable = typeof command === 'string' ? 'bash' : command.executable;
+    const args = typeof command === 'string' ? ['-lc', command] : command.args;
+    const child = plugins.childProcess.spawn(executable, args, {
+      cwd: options.cwd,
+      detached: ownsProcessGroup,
+      shell: false,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    const stdoutChunks: Buffer[] = [];
+    const stderrChunks: Buffer[] = [];
+    let capturedBytes = 0;
+    let settled = false;
+    let terminationReason: TLocalShellTerminationReason | undefined;
+    let childError: Error | undefined;
+    let signalError: Error | undefined;
+    let outputListenerError: Error | undefined;
+    let outputQueue: Promise<void> = Promise.resolve();
+    const outputAbortController = new AbortController();
+    const outputDecoders = {
+      stdout: new plugins.StringDecoder('utf8'),
+      stderr: new plugins.StringDecoder('utf8'),
+    };
+    let killTimer: NodeJS.Timeout | undefined;
+    const timeoutTimer = options.timeoutMs && options.timeoutMs > 0
+      ? setTimeout(() => requestTermination('timeout'), options.timeoutMs)
+      : undefined;
+    const signalProcess = (signal: NodeJS.Signals) => {
+      if (child.pid === undefined) return;
+      if (ownsProcessGroup) {
+        try {
+          process.kill(-child.pid, signal);
+          return;
+        } catch (error) {
+          if ((error as NodeJS.ErrnoException).code === 'ESRCH') return;
+          signalError = error as Error;
+        }
+      }
+      try {
+        child.kill(signal);
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== 'ESRCH') {
+          signalError = error as Error;
+        }
+      }
+    };
+    function requestTermination(reason: TLocalShellTerminationReason): void {
+      if (terminationReason) return;
+      terminationReason = reason;
+      outputAbortController.abort(
+        new Error(`Command output delivery stopped because the command is terminating (${reason}).`),
+      );
+      signalProcess('SIGTERM');
+      killTimer = setTimeout(() => signalProcess('SIGKILL'), LOCAL_SHELL_KILL_GRACE_MS);
+    }
+    const onAbort = () => requestTermination('abort');
+    const deliverOutput = async (
+      stream: 'stdout' | 'stderr',
+      text: string,
+    ): Promise<void> => {
+      const listenerPromise = Promise.resolve(options.onOutput!(stream, text));
+      void listenerPromise.catch(() => undefined);
+      let timeoutTimer: NodeJS.Timeout | undefined;
+      let onOutputAbort!: () => void;
+      const aborted = new Promise<never>((_resolve, reject) => {
+        onOutputAbort = () => reject(outputAbortController.signal.reason);
+        outputAbortController.signal.addEventListener('abort', onOutputAbort, { once: true });
+        if (outputAbortController.signal.aborted) onOutputAbort();
+      });
+      const timeout = options.outputListenerTimeoutMs === undefined
+        ? undefined
+        : new Promise<never>((_resolve, reject) => {
+            timeoutTimer = setTimeout(
+              () => reject(new Error(
+                `Command output listener timed out after ${options.outputListenerTimeoutMs}ms.`,
+              )),
+              options.outputListenerTimeoutMs,
+            );
+          });
+      try {
+        await Promise.race([listenerPromise, aborted, ...(timeout ? [timeout] : [])]);
+      } finally {
+        if (timeoutTimer) clearTimeout(timeoutTimer);
+        outputAbortController.signal.removeEventListener('abort', onOutputAbort);
+      }
+    };
+    const enqueueOutput = (
+      stream: 'stdout' | 'stderr',
+      source: NodeJS.ReadableStream | null,
+      text: string,
+    ) => {
+      if (!text || !options.onOutput) return;
+      source?.pause();
+      outputQueue = outputQueue
+        .then(() => outputListenerError ? undefined : deliverOutput(stream, text))
+        .catch((error) => {
+          outputListenerError = error instanceof Error ? error : new Error(String(error));
+          requestTermination('output-listener');
+        })
+        .finally(() => source?.resume());
+    };
+    const captureChunk = (
+      stream: 'stdout' | 'stderr',
+      chunks: Buffer[],
+      source: NodeJS.ReadableStream | null,
+      chunk: Buffer | string,
+    ) => {
+      const chunkBuffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+      const remainingBytes = Math.max(options.maxOutputBytes - capturedBytes, 0);
+      if (remainingBytes > 0) {
+        const capturedChunk = chunkBuffer.subarray(0, remainingBytes);
+        chunks.push(capturedChunk);
+        capturedBytes += capturedChunk.byteLength;
+        enqueueOutput(stream, source, outputDecoders[stream].write(capturedChunk));
+      }
+      if (chunkBuffer.byteLength > remainingBytes) {
+        requestTermination('output-limit');
+      }
+    };
+    const onStdout = (chunk: Buffer | string) => captureChunk('stdout', stdoutChunks, child.stdout, chunk);
+    const onStderr = (chunk: Buffer | string) => captureChunk('stderr', stderrChunks, child.stderr, chunk);
+    const cleanup = () => {
+      if (timeoutTimer) clearTimeout(timeoutTimer);
+      if (killTimer) clearTimeout(killTimer);
+      options.abortSignal?.removeEventListener('abort', onAbort);
+      child.stdout?.removeListener('data', onStdout);
+      child.stderr?.removeListener('data', onStderr);
+      child.removeListener('error', onChildError);
+      child.removeListener('exit', onChildExit);
+      child.removeListener('close', onChildClose);
+    };
+    const settle = (result: IToolShellResult) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      resolve(result);
+    };
+    const buildOutput = () => ({
+      stdout: Buffer.concat(stdoutChunks).toString('utf8'),
+      stderr: Buffer.concat(stderrChunks).toString('utf8'),
+    });
+    function onChildError(error: Error): void {
+      handleLocalShellChildError(error, child.pid, {
+        settleSpawnFailure: (spawnError) => {
+          const output = buildOutput();
+          settle({
+            exitCode: 1,
+            stdout: output.stdout,
+            stderr: `${output.stderr}${spawnError.message}`,
+          });
+        },
+        retainError: (processError) => {
+          childError = processError;
+        },
+        requestTermination: () => requestTermination('error'),
+      });
+    }
+    function onChildExit(): void {
+      if (ownsProcessGroup) signalProcess('SIGKILL');
+    }
+    async function finishChildClose(code: number | null, signal: NodeJS.Signals | null): Promise<void> {
+      enqueueOutput('stdout', child.stdout, outputDecoders.stdout.end());
+      enqueueOutput('stderr', child.stderr, outputDecoders.stderr.end());
+      // Process outcome is fixed at close. Later aborts/timeouts must not reclassify it while
+      // already-received output finishes its bounded listener delivery.
+      if (timeoutTimer) clearTimeout(timeoutTimer);
+      if (killTimer) clearTimeout(killTimer);
+      options.abortSignal?.removeEventListener('abort', onAbort);
+      await outputQueue;
+      if (terminationReason) {
+        signalProcess('SIGKILL');
+      }
+      const output = buildOutput();
+      const statusMessage = terminationReason === 'timeout'
+        ? `Command timed out after ${options.timeoutMs}ms.`
+          : terminationReason === 'output-limit'
+            ? `Command output exceeded the local limit of ${options.maxOutputBytes} bytes and was terminated.`
+            : terminationReason === 'output-listener'
+              ? `Command output listener failed and the command was terminated: ${outputListenerError?.message ?? 'unknown listener error'}`
+            : terminationReason === 'abort'
+            ? 'Command was aborted.'
+            : '';
+      const signalErrorMessage = signalError ? `Failed to signal command process: ${signalError.message}` : '';
+      const childErrorMessage = childError ? `Command process error: ${childError.message}` : '';
+      settle({
+        exitCode: terminationReason === 'timeout'
+          ? 124
+          : terminationReason === 'abort'
+            ? 130
+              : terminationReason === 'output-limit'
+                ? 1
+                : terminationReason === 'output-listener'
+                  ? 1
+                : terminationReason === 'error'
+                ? 1
+                : code ?? 1,
+        stdout: output.stdout,
+        stderr: [output.stderr, statusMessage, childErrorMessage, signalErrorMessage].filter(Boolean).join('\n').trim(),
+        signal: signal ?? undefined,
+      });
+    }
+    function onChildClose(code: number | null, signal: NodeJS.Signals | null): void {
+      void finishChildClose(code, signal);
+    }
+
+    options.abortSignal?.addEventListener('abort', onAbort, { once: true });
+    if (options.abortSignal?.aborted) onAbort();
+    child.stdout?.on('data', onStdout);
+    child.stderr?.on('data', onStderr);
+    child.once('error', onChildError);
+    child.once('exit', onChildExit);
+    child.once('close', onChildClose);
+  });
+};
+
+interface ICreateLocalToolJobContextOptions {
+  cwd: string;
+  rootDir?: string;
+  maxOutputBytes: number;
+  maxRetainedJobs: number;
+  jobStore?: IToolJobStore;
+  outputListenerTimeoutMs: number;
+  jobStoreOperationTimeoutMs: number;
+  settleOrphanedJob?: (
+    job: IToolJobState,
+    abortSignal: AbortSignal,
+  ) => Promise<IToolJobState> | IToolJobState;
+  beforeOperation?: ILocalToolExecutionContextOptions['beforeOperation'];
+  abortSignal?: AbortSignal;
+}
+
+const assertOrphanSettlement = (
+  persistedJob: IToolJobState,
+  settledJob: IToolJobState,
+): void => {
+  if (
+    !settledJob
+    || settledJob.executionId !== persistedJob.executionId
+    || settledJob.type !== persistedJob.type
+    || !['finished', 'failed', 'aborted'].includes(settledJob.state)
+  ) {
+    throw new Error(
+      `Orphan settlement for background execution "${persistedJob.executionId}" must return a terminal state with the same executionId and type.`,
+    );
+  }
+};
+
+const createLocalToolJobContext = (
+  options: ICreateLocalToolJobContextOptions,
+): IToolJobContext => {
+  const states = new Map<string, IToolJobState>();
+  const controllers = new Map<string, AbortController>();
+  const completions = new Map<string, Promise<IToolJobState>>();
+  const terminalExecutionIds: string[] = [];
+  const listeners = new Set<TToolJobEventListener>();
+  let persistenceRevision = 0;
+  let persistenceError: unknown;
+  let persistenceQueue: Promise<void> = Promise.resolve();
+  const reportListenerError = (error: unknown): void => {
+    process.emitWarning(error instanceof Error ? error : String(error), {
+      code: 'SMARTAGENT_JOB_LISTENER_ERROR',
+    });
+  };
+  const runJobStoreOperation = async <TValue>(
+    operation: (abortSignal: AbortSignal) => Promise<TValue>,
+  ): Promise<TValue> => {
+    const controller = new AbortController();
+    const timeoutError = new Error(
+      `Job store operation timed out after ${options.jobStoreOperationTimeoutMs}ms.`,
+    );
+    let timer: NodeJS.Timeout | undefined;
+    const operationPromise = Promise.resolve().then(() => operation(controller.signal));
+    const timeoutPromise = new Promise<never>((_resolve, reject) => {
+      timer = setTimeout(() => {
+        controller.abort(timeoutError);
+        reject(timeoutError);
+      }, options.jobStoreOperationTimeoutMs);
+    });
+    try {
+      return await Promise.race([operationPromise, timeoutPromise]);
+    } finally {
+      if (timer) clearTimeout(timer);
+    }
+  };
+  const persist = (): Promise<void> => {
+    if (!options.jobStore) return Promise.resolve();
+    const snapshot = structuredClone([...states.values()]);
+    const operation = persistenceQueue.then(async () => {
+      if (persistenceError !== undefined) throw persistenceError;
+      persistenceRevision = await runJobStoreOperation((abortSignal) =>
+        options.jobStore!.save(snapshot, persistenceRevision, abortSignal));
+    });
+    persistenceQueue = operation.catch((error) => {
+      persistenceError ??= error;
+    });
+    return operation;
+  };
+  const flushPersistence = async (): Promise<void> => {
+    if (persistenceError !== undefined) throw persistenceError;
+    await persistenceQueue;
+    if (persistenceError !== undefined) throw persistenceError;
+  };
+  const emitLifecycle = (event: IToolJobEvent): void => {
+    for (const listener of [...listeners]) {
+      try {
+        const result = listener(event);
+        if (result && typeof result.then === 'function') {
+          void result.catch(reportListenerError);
+        }
+      } catch (error) {
+        reportListenerError(error);
+      }
+    }
+  };
+  const emitOutput = async (event: IToolJobOutputEvent): Promise<void> => {
+    for (const listener of [...listeners]) {
+      let timer: NodeJS.Timeout | undefined;
+      try {
+        await Promise.race([
+          Promise.resolve().then(() => listener(event)),
+          new Promise<never>((_resolve, reject) => {
+            timer = setTimeout(
+              () => reject(new Error(
+                `Job output listener timed out after ${options.outputListenerTimeoutMs}ms.`,
+              )),
+              options.outputListenerTimeoutMs,
+            );
+          }),
+        ]);
+      } finally {
+        if (timer) clearTimeout(timer);
+      }
+    }
+  };
+  const ready = (async () => {
+    const snapshot = options.jobStore
+      ? await runJobStoreOperation((abortSignal) => options.jobStore!.load(abortSignal))
+      : undefined;
+    if (!snapshot) return;
+    persistenceRevision = snapshot.revision;
+    let changed = false;
+    for (const restoredState of snapshot.jobs) {
+      let state = structuredClone(restoredState);
+      if (state.state === 'running') {
+        if (options.settleOrphanedJob) {
+          const settledState = await runJobStoreOperation(async (abortSignal) =>
+            options.settleOrphanedJob!(structuredClone(state), abortSignal));
+          assertOrphanSettlement(state, settledState);
+          state = structuredClone(settledState);
+        } else {
+          const now = Date.now();
+          state.state = 'failed';
+          state.exitCode = null;
+          state.stderr = [state.stderr, 'Background execution was interrupted by a host restart.']
+            .filter(Boolean)
+            .join('\n');
+          state.updatedAt = now;
+          state.finishedAt = now;
+        }
+        changed = true;
+      }
+      states.set(state.executionId, state);
+      terminalExecutionIds.push(state.executionId);
+    }
+    while (terminalExecutionIds.length > options.maxRetainedJobs) {
+      const expiredExecutionId = terminalExecutionIds.shift();
+      if (expiredExecutionId) {
+        states.delete(expiredExecutionId);
+        changed = true;
+      }
+    }
+    if (changed) await persist();
+  })();
+
+  return {
+    start: async (request, invocationOptions) => {
+      await ready;
+      await flushPersistence();
+      const operationAbortSignal = invocationOptions?.abortSignal ?? options.abortSignal;
+      const clonedRequest = structuredClone(request);
+      if (clonedRequest.type !== 'shell' || !clonedRequest.command) {
+        throw new Error('The local job context only supports structured shell jobs.');
+      }
+      validateLocalStructuredCommand(clonedRequest.command);
+      const commandCwd = resolveLocalPath(clonedRequest.cwd ?? options.cwd, options.rootDir);
+      await runBeforeLocalOperation(options.beforeOperation, operationAbortSignal);
+      const executionId = `shell_${plugins.crypto.randomUUID()}`;
+      const startedAt = Date.now();
+      const runningState: IToolJobState = {
+        executionId,
+        type: 'shell',
+        state: 'running',
+        request: clonedRequest,
+        stdout: '',
+        stderr: '',
+        startedAt,
+        updatedAt: startedAt,
+      };
+      const startedEvent = structuredClone({
+        type: 'started',
+        job: runningState,
+      } satisfies IToolJobEvent);
+      const controller = new AbortController();
+      states.set(executionId, runningState);
+      controllers.set(executionId, controller);
+      try {
+        await persist();
+      } catch (error) {
+        states.delete(executionId);
+        controllers.delete(executionId);
+        throw error;
+      }
+      try {
+        throwIfAborted(operationAbortSignal);
+      } catch (error) {
+        states.delete(executionId);
+        controllers.delete(executionId);
+        try {
+          await persist();
+        } catch (rollbackError) {
+          process.emitWarning(
+            rollbackError instanceof Error ? rollbackError : String(rollbackError),
+            { code: 'SMARTAGENT_JOB_ADMISSION_ROLLBACK_ERROR' },
+          );
+        }
+        throw error;
+      }
+
+      let outputSequence = 0;
+      let outputPersistenceFailed = false;
+      let resolveProcessResult!: (result: IToolShellResult) => void;
+      let rejectProcessResult!: (error: unknown) => void;
+      const processResult = new Promise<IToolShellResult>((resolve, reject) => {
+        resolveProcessResult = resolve;
+        rejectProcessResult = reject;
+      });
+      const completion = (async (): Promise<IToolJobState> => {
+        let terminalState: IToolJobState;
+        try {
+          const result = await processResult;
+          const finishedAt = Date.now();
+          terminalState = {
+            executionId,
+            type: 'shell',
+            state: controller.signal.aborted
+              ? 'aborted'
+              : result.exitCode === 0
+                ? 'finished'
+                : 'failed',
+            request: clonedRequest,
+            exitCode: result.exitCode,
+            stdout: result.stdout,
+            stderr: result.stderr ?? '',
+            signal: result.signal,
+            startedAt,
+            updatedAt: finishedAt,
+            finishedAt,
+          };
+        } catch (error) {
+          const finishedAt = Date.now();
+          terminalState = {
+            executionId,
+            type: 'shell',
+            state: controller.signal.aborted ? 'aborted' : 'failed',
+            request: clonedRequest,
+            exitCode: null,
+            stdout: states.get(executionId)?.stdout ?? '',
+            stderr: [
+              states.get(executionId)?.stderr,
+              error instanceof Error ? error.message : String(error),
+            ].filter(Boolean).join('\n'),
+            startedAt,
+            updatedAt: finishedAt,
+            finishedAt,
+          };
+        }
+        states.set(executionId, terminalState);
+        controllers.delete(executionId);
+        completions.delete(executionId);
+        terminalExecutionIds.push(executionId);
+        while (terminalExecutionIds.length > options.maxRetainedJobs) {
+          const expiredExecutionId = terminalExecutionIds.shift();
+          if (expiredExecutionId) states.delete(expiredExecutionId);
+        }
+        if (!outputPersistenceFailed) await persist();
+        emitLifecycle({ type: 'finished', job: structuredClone(terminalState) });
+        return terminalState;
+      })();
+      completions.set(executionId, completion);
+      const handle: IToolJobHandle = { executionId, state: 'running', completion };
+      const processCompletion = runLocalProcessCommand(clonedRequest.command, {
+        cwd: commandCwd,
+        timeoutMs: clonedRequest.timeoutMs,
+        abortSignal: controller.signal,
+        maxOutputBytes: options.maxOutputBytes,
+        onOutput: async (stream, chunk) => {
+          const state = states.get(executionId);
+          if (!state || state.state !== 'running') return;
+          if (stream === 'stdout') state.stdout = `${state.stdout ?? ''}${chunk}`;
+          else state.stderr = `${state.stderr ?? ''}${chunk}`;
+          state.updatedAt = Date.now();
+          try {
+            await persist();
+          } catch (error) {
+            outputPersistenceFailed = true;
+            persistenceError ??= error;
+            throw error;
+          }
+          await emitOutput({
+            type: 'output',
+            job: structuredClone(state),
+            stream,
+            chunk,
+            sequence: ++outputSequence,
+          });
+        },
+      });
+      void processCompletion.then(resolveProcessResult, rejectProcessResult);
+      emitLifecycle(startedEvent);
+      return handle;
+    },
+    get: async (executionId) => {
+      await ready;
+      await flushPersistence();
+      const state = states.get(executionId);
+      if (!state) throw new Error(`Unknown background execution "${executionId}".`);
+      return structuredClone(state);
+    },
+    list: async () => {
+      await ready;
+      await flushPersistence();
+      return structuredClone([...states.values()]);
+    },
+    abort: async (executionId) => {
+      await ready;
+      const state = states.get(executionId);
+      if (!state) throw new Error(`Unknown background execution "${executionId}".`);
+      if (state.state !== 'running') return;
+      controllers.get(executionId)?.abort(new DOMException('Background execution aborted', 'AbortError'));
+      await completions.get(executionId);
+    },
+    subscribe: (listener) => {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+  };
+};