@modelprofile.com/flexharness 6.0.0 → 7.0.0

package/ts_tools_node/tool.persistence.ts

@@ -0,0 +1,146 @@
+import * as plugins from './plugins.js';
+import type { IToolJobSnapshot, IToolJobStore, IToolJobState } from '@modelprofile.com/flexharness-agent';
+
+export interface IFileToolJobStoreOptions {
+  filePath: string;
+  lockTimeoutMs?: number;
+}
+
+const decodeSnapshot = (value: unknown): IToolJobSnapshot => {
+  const snapshot = value as Partial<IToolJobSnapshot>;
+  if (
+    !snapshot
+    || snapshot.schemaVersion !== plugins.JOB_SNAPSHOT_SCHEMA_VERSION
+    || !Number.isSafeInteger(snapshot.revision)
+    || (snapshot.revision ?? -1) < 1
+    || !Array.isArray(snapshot.jobs)
+  ) {
+    throw new Error('Invalid tool job snapshot.');
+  }
+  return snapshot as IToolJobSnapshot;
+};
+
+const sleep = async (milliseconds: number): Promise<void> => {
+  await new Promise((resolve) => setTimeout(resolve, milliseconds));
+};
+
+export class FileToolJobStore implements IToolJobStore {
+  private readonly filePath: string;
+  private readonly lockTimeoutMs: number;
+
+  constructor(options: IFileToolJobStoreOptions) {
+    if (!options.filePath.trim()) throw new Error('FileToolJobStore filePath must not be empty.');
+    this.filePath = plugins.path.resolve(options.filePath);
+    this.lockTimeoutMs = options.lockTimeoutMs ?? 10_000;
+    if (!Number.isSafeInteger(this.lockTimeoutMs) || this.lockTimeoutMs <= 0) {
+      throw new Error('lockTimeoutMs must be a positive integer.');
+    }
+  }
+
+  private async readSnapshot(): Promise<IToolJobSnapshot | undefined> {
+    try {
+      return decodeSnapshot(plugins.v8.deserialize(await plugins.fs.promises.readFile(this.filePath)));
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === 'ENOENT') return undefined;
+      throw error;
+    }
+  }
+
+  private async withLock<TValue>(
+    operation: () => Promise<TValue>,
+    abortSignal?: AbortSignal,
+  ): Promise<TValue> {
+    const lockPath = `${this.filePath}.lock`;
+    const ownerPath = plugins.path.join(lockPath, 'owner');
+    const ownerToken = plugins.crypto.randomUUID();
+    const ownerRecord = JSON.stringify({ token: ownerToken });
+    await plugins.fs.promises.mkdir(plugins.path.dirname(lockPath), { recursive: true });
+    const startedAt = Date.now();
+    while (true) {
+      abortSignal?.throwIfAborted();
+      try {
+        await plugins.fs.promises.mkdir(lockPath);
+        try {
+          await plugins.fs.promises.writeFile(ownerPath, ownerRecord, 'utf8');
+        } catch (error) {
+          await plugins.fs.promises.rm(lockPath, { recursive: true, force: true });
+          throw error;
+        }
+        break;
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error;
+        if (Date.now() - startedAt >= this.lockTimeoutMs) {
+          throw new Error(`Timed out waiting for the tool job store lock at "${lockPath}".`);
+        }
+        await sleep(20);
+      }
+    }
+    try {
+      return await operation();
+    } finally {
+      let stillOwner = false;
+      try {
+        const owner = JSON.parse(
+          await plugins.fs.promises.readFile(ownerPath, 'utf8'),
+        ) as { token?: unknown };
+        stillOwner = owner.token === ownerToken;
+      } catch {}
+      if (stillOwner) {
+        await plugins.fs.promises.rm(lockPath, { recursive: true, force: true });
+      }
+    }
+  }
+
+  private async writeAtomic(
+    snapshot: IToolJobSnapshot,
+    abortSignal?: AbortSignal,
+  ): Promise<void> {
+    abortSignal?.throwIfAborted();
+    const directoryPath = plugins.path.dirname(this.filePath);
+    await plugins.fs.promises.mkdir(directoryPath, { recursive: true });
+    const temporaryPath = `${this.filePath}.${process.pid}.${plugins.crypto.randomUUID()}.tmp`;
+    let handle: Awaited<ReturnType<typeof plugins.fs.promises.open>> | undefined;
+    try {
+      handle = await plugins.fs.promises.open(temporaryPath, 'wx');
+      await handle.writeFile(plugins.v8.serialize(snapshot));
+      await handle.sync();
+      await handle.close();
+      handle = undefined;
+      abortSignal?.throwIfAborted();
+      await plugins.fs.promises.rename(temporaryPath, this.filePath);
+      const directoryHandle = await plugins.fs.promises.open(directoryPath, 'r');
+      try {
+        await directoryHandle.sync();
+      } finally {
+        await directoryHandle.close();
+      }
+    } finally {
+      if (handle) await handle.close().catch(() => undefined);
+      await plugins.fs.promises.rm(temporaryPath, { force: true });
+    }
+  }
+
+  public async load(abortSignal?: AbortSignal): Promise<IToolJobSnapshot | undefined> {
+    abortSignal?.throwIfAborted();
+    const snapshot = await this.readSnapshot();
+    abortSignal?.throwIfAborted();
+    return snapshot;
+  }
+
+  public async save(
+    jobs: readonly IToolJobState[],
+    expectedRevision: number,
+    abortSignal?: AbortSignal,
+  ): Promise<number> {
+    return this.withLock(async () => {
+      abortSignal?.throwIfAborted();
+      const actualRevision = (await this.readSnapshot())?.revision ?? 0;
+      if (actualRevision !== expectedRevision) {
+        throw new plugins.ToolJobStoreConflictError(expectedRevision, actualRevision);
+      }
+      const revision = expectedRevision + 1;
+      await this.writeAtomic(plugins.createToolJobSnapshot(jobs, revision), abortSignal);
+      return revision;
+    }, abortSignal);
+  }
+}

package/ts_tools_node/tools.local.ts

@@ -0,0 +1,26 @@
+import * as plugins from './plugins.js';
+import { createLocalToolExecutionContext } from './tool.context.js';
+
+export interface IFilesystemToolOptions extends plugins.ICreateFilesystemToolsOptions {
+  rootDir?: string;
+  context?: plugins.IToolExecutionContext;
+}
+
+export interface IShellToolOptions extends plugins.ICreateShellToolsOptions {
+  cwd?: string;
+  context?: plugins.IToolExecutionContext;
+}
+
+export function filesystemTool(options?: IFilesystemToolOptions): plugins.ToolSet {
+  const context = options?.context ?? createLocalToolExecutionContext({ rootDir: options?.rootDir });
+  return plugins.createFilesystemTools(context, options);
+}
+
+export function shellTool(options?: IShellToolOptions): plugins.ToolSet {
+  const context = options?.context ?? createLocalToolExecutionContext({ cwd: options?.cwd });
+  return plugins.createShellTools(context, {
+    ...options,
+    // An internally created context has no caller-visible background-job owner.
+    includeBackground: options?.context ? true : false,
+  });
+}