@twinsearth/w2m-dsh-plugin 0.0.0-stage → 0.4.7

package/src/agent/resolve.mjs

@@ -0,0 +1,148 @@
+/**
+ * Executable resolution shared by capability probing and task execution.
+ *
+ * This file exists because those two used to disagree, and the disagreement was
+ * invisible until a task ran.
+ *
+ * The capability probe deliberately looks for a tool **on PATH first, in DSH's
+ * bundled runtime second** — that is how a machine with no system `node` still
+ * reports `caps.node = "v24.21.0"` and means it. The executor, by contrast,
+ * spawned `argv[0]` verbatim with `shell: false`, so it could only ever find what
+ * PATH held. On a machine where the tool exists *only* in the bundle, the probe
+ * advertised a capability and every task that used it died at spawn with a bare
+ * `crashed`. One search order has to serve both, so it lives here.
+ *
+ * Nothing in this module guesses: a name that cannot be found is returned
+ * unchanged, so the caller still gets the real ENOENT instead of a fake path.
+ */
+
+import { accessSync, constants, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { delimiter, join } from 'node:path';
+
+/** The DSH runtime directory layout we fall back to (task-8, measured). */
+export const DSH_RUNTIME_RELATIVE = join('dsh-runtimes', 'dsh-primary-runtime', 'dependencies');
+
+/**
+ * `%DSH_HOME%` (or `~/.dsh`) — the root the bundled runtimes live under.
+ *
+ * @param {Record<string,string|undefined>} [env]
+ * @returns {string}
+ */
+export function dshHome(env = process.env) {
+  const explicit = env.DSH_HOME && env.DSH_HOME.trim() !== '' ? env.DSH_HOME : null;
+  return explicit ?? join(homedir(), '.dsh');
+}
+
+/**
+ * Absolute path of the bundled DSH dependency directory, or `null` when absent.
+ *
+ * `DSH_RUNTIME_DEPS` overrides the guess, which keeps tests hermetic.
+ *
+ * @param {Record<string,string|undefined>} [env]
+ * @returns {string|null}
+ */
+export function dshDependenciesDir(env = process.env) {
+  const override = env.DSH_RUNTIME_DEPS && env.DSH_RUNTIME_DEPS.trim() !== '';
+  const dir = override ? env.DSH_RUNTIME_DEPS : join(dshHome(env), DSH_RUNTIME_RELATIVE);
+  try {
+    return statSync(dir).isDirectory() ? dir : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Windows only: the extensions `CreateProcess` will accept for a bare name.
+ * (`.cmd`/`.bat` are listed so we can *report* them, but they cannot be
+ * started with `shell: false`, so they are never returned as executable.)
+ */
+const WIN_EXTENSIONS = ['.exe', '.com'];
+
+/**
+ * Find a real executable on PATH (then, optionally, in extra directories).
+ *
+ * @param {string} name Bare command name, e.g. `node`, `python3`.
+ * @param {object} [options]
+ * @param {Record<string,string|undefined>} [options.env]
+ * @param {string[]} [options.extraDirs] Absolute directories to try after PATH.
+ * @param {string[]} [options.extensions] Override the candidate extensions.
+ * @returns {string|null} Absolute path.
+ */
+export function findExecutable(name, options = {}) {
+  const env = options.env ?? process.env;
+  const isWin = process.platform === 'win32';
+  const extensions = options.extensions ?? (isWin ? ['', ...WIN_EXTENSIONS] : ['']);
+  const dirs = [
+    ...String(env.PATH ?? '')
+      .split(delimiter)
+      .filter((d) => d.trim() !== ''),
+    ...(options.extraDirs ?? []),
+  ];
+
+  for (const dir of dirs) {
+    for (const ext of extensions) {
+      const candidate = join(dir, name + ext);
+      try {
+        accessSync(candidate, isWin ? constants.F_OK : constants.F_OK | constants.X_OK);
+        if (statSync(candidate).isFile()) return candidate;
+      } catch {
+        /* keep looking */
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * The `bin` directories inside DSH's bundled runtime tree.
+ *
+ * This is the second half of the probe's search order, expressed once. A tool
+ * found here is a tool the probe would have reported a real version for, which
+ * is exactly why the executor must be able to start it.
+ *
+ * @param {Record<string,string|undefined>} [env]
+ * @returns {string[]} Existing directories, in priority order.
+ */
+export function bundledBinDirs(env = process.env) {
+  const depsDir = dshDependenciesDir(env);
+  if (!depsDir) return [];
+  const isWin = process.platform === 'win32';
+  const candidates = [
+    join(depsDir, 'node', 'bin'),
+    join(depsDir, 'node'),
+    join(depsDir, 'python', isWin ? '' : 'bin'),
+    join(depsDir, 'pnpm', 'bin'),
+  ];
+  return candidates.filter((dir) => {
+    try {
+      return statSync(dir).isDirectory();
+    } catch {
+      return false;
+    }
+  });
+}
+
+/**
+ * Resolve `argv[0]` the way the capability probe resolves a tool.
+ *
+ * * A name containing a path separator is the caller's own path: returned
+ *   unchanged, because rewriting an explicit path would be second-guessing.
+ * * Otherwise: PATH first, then DSH's bundled runtime.
+ * * Not found anywhere: returned unchanged, so `spawn` still reports ENOENT and
+ *   the result keeps saying `crashed` for the honest reason.
+ *
+ * @param {string} exe Bare command name or a path.
+ * @param {object} [options]
+ * @param {Record<string,string|undefined>} [options.env]
+ * @param {string[]} [options.extraDirs] Extra directories tried after PATH.
+ * @returns {string} Absolute path when one was found, else `exe`.
+ */
+export function resolveCommand(exe, options = {}) {
+  if (typeof exe !== 'string' || exe === '') return exe;
+  // Anything with a separator is a path the caller chose, not a name to look up.
+  if (exe.includes('/') || exe.includes('\\')) return exe;
+  const env = options.env ?? process.env;
+  const extraDirs = options.extraDirs ?? bundledBinDirs(env);
+  return findExecutable(exe, { env, extraDirs }) ?? exe;
+}

package/src/agent/spool.mjs

@@ -0,0 +1,252 @@
+/**
+ * Write-ahead spool: "先落盘再回传" (§0).
+ *
+ * Ordering that the contract requires:
+ *
+ *   1. an offer is written to the spool **before** anything executes;
+ *   2. the finished envelope is written to the spool **before** it is POSTed;
+ *   3. the spool entry is deleted only after Rabbit confirms receipt.
+ *
+ * A crash between (2) and (3) therefore leaves a replayable envelope on disk,
+ * and a lost Rabbit (or a laptop lid closing mid-run) cannot silently swallow a
+ * result.  Everything lives under the `--state` directory: read-only mode must
+ * never write into the project, and the spool is not part of the project.
+ */
+
+import { mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+
+/** Sub-directory of the state dir that holds spooled tasks. */
+export const SPOOL_DIR_NAME = 'spool';
+
+/** Entry states, in the order they occur. */
+export const SPOOL_STATES = ['claimed', 'completed', 'acked'];
+
+/**
+ * @typedef {object} SpoolRecord
+ * @property {string} task_id
+ * @property {number} attempt
+ * @property {string|null} dedupe_key
+ * @property {'claimed'|'completed'|'acked'} state
+ * @property {string} dir
+ * @property {string} created_at
+ * @property {string} updated_at
+ * @property {object|null} task
+ * @property {object|null} envelope
+ */
+
+/** @param {string} value */
+function sanitize(value) {
+  return String(value).replace(/[^A-Za-z0-9._-]/g, '_').slice(0, 120);
+}
+
+/** Atomic file write: temp file in the same directory, then rename. */
+function writeAtomic(file, text) {
+  const tmp = `${file}.tmp-${process.pid}-${randomUUID().slice(0, 8)}`;
+  writeFileSync(tmp, text, { encoding: 'utf8', mode: 0o600 });
+  renameSync(tmp, file);
+}
+
+/**
+ * Create a spool rooted at `<stateDir>/spool`.
+ *
+ * @param {string} stateDir
+ * @returns {object} Spool handle.
+ */
+export function createSpool(stateDir) {
+  if (typeof stateDir !== 'string' || stateDir.trim() === '') {
+    throw new TypeError('createSpool: stateDir must be a non-empty string');
+  }
+  const root = join(stateDir, SPOOL_DIR_NAME);
+  mkdirSync(root, { recursive: true, mode: 0o700 });
+
+  /** @param {string} taskId @param {number} attempt */
+  const taskDir = (taskId, attempt) => join(root, `${sanitize(taskId)}__a${Number(attempt) || 1}`);
+
+  /** @param {string} dir */
+  const readJson = (dir, name) => {
+    try {
+      return JSON.parse(readFileSync(join(dir, name), 'utf8'));
+    } catch {
+      return null;
+    }
+  };
+
+  /** @param {string} dir @returns {SpoolRecord|null} */
+  const readRecord = (dir) => {
+    const meta = readJson(dir, 'meta.json');
+    if (!meta || typeof meta.task_id !== 'string') return null;
+    return {
+      task_id: meta.task_id,
+      attempt: Number(meta.attempt) || 1,
+      dedupe_key: meta.dedupe_key ?? null,
+      state: meta.state ?? 'claimed',
+      dir,
+      created_at: meta.created_at ?? null,
+      updated_at: meta.updated_at ?? null,
+      task: readJson(dir, 'task.json'),
+      envelope: readJson(dir, 'envelope.json'),
+    };
+  };
+
+  const spool = {
+    /** Absolute spool root. */
+    root,
+    /** State directory the spool belongs to. */
+    stateDir,
+    taskDir,
+
+    /**
+     * Step 1: persist the offer before doing anything with it.
+     *
+     * @param {{task_id: string, attempt?: number, dedupe_key?: string|null, offer?: object|null}} entry
+     * @returns {SpoolRecord}
+     */
+    saveTask(entry) {
+      if (!entry || typeof entry.task_id !== 'string' || entry.task_id === '') {
+        throw new TypeError('spool.saveTask: task_id is required');
+      }
+      const attempt = Number(entry.attempt) || 1;
+      const dir = taskDir(entry.task_id, attempt);
+      mkdirSync(dir, { recursive: true, mode: 0o700 });
+      const now = new Date().toISOString();
+      const existing = readJson(dir, 'meta.json');
+      if (entry.offer) writeAtomic(join(dir, 'task.json'), `${JSON.stringify(entry.offer, null, 2)}\n`);
+      const meta = {
+        task_id: entry.task_id,
+        attempt,
+        dedupe_key: entry.dedupe_key ?? existing?.dedupe_key ?? null,
+        state: 'claimed',
+        created_at: existing?.created_at ?? now,
+        updated_at: now,
+      };
+      writeAtomic(join(dir, 'meta.json'), `${JSON.stringify(meta, null, 2)}\n`);
+      return readRecord(dir);
+    },
+
+    /**
+     * Step 2: persist the envelope before the POST.
+     *
+     * @param {{task_id: string, attempt?: number, envelope: object}} entry
+     * @returns {SpoolRecord}
+     */
+    saveEnvelope(entry) {
+      if (!entry || typeof entry.task_id !== 'string' || entry.task_id === '') {
+        throw new TypeError('spool.saveEnvelope: task_id is required');
+      }
+      if (!entry.envelope || typeof entry.envelope !== 'object') {
+        throw new TypeError('spool.saveEnvelope: envelope is required');
+      }
+      const attempt = Number(entry.attempt) || 1;
+      const dir = taskDir(entry.task_id, attempt);
+      mkdirSync(dir, { recursive: true, mode: 0o700 });
+      writeAtomic(join(dir, 'envelope.json'), `${JSON.stringify(entry.envelope, null, 2)}\n`);
+      const existing = readJson(dir, 'meta.json') ?? {};
+      const now = new Date().toISOString();
+      const meta = {
+        task_id: entry.task_id,
+        attempt,
+        dedupe_key: entry.dedupe_key ?? entry.envelope.dedupe_key ?? existing.dedupe_key ?? null,
+        state: 'completed',
+        created_at: existing.created_at ?? now,
+        updated_at: now,
+      };
+      writeAtomic(join(dir, 'meta.json'), `${JSON.stringify(meta, null, 2)}\n`);
+      return readRecord(dir);
+    },
+
+    /**
+     * Every spool entry, oldest first.
+     *
+     * @returns {SpoolRecord[]}
+     */
+    list() {
+      let names;
+      try {
+        names = readdirSync(root);
+      } catch {
+        return [];
+      }
+      const records = [];
+      for (const name of names) {
+        const dir = join(root, name);
+        try {
+          if (!statSync(dir).isDirectory()) continue;
+        } catch {
+          continue;
+        }
+        const record = readRecord(dir);
+        if (record) records.push(record);
+      }
+      records.sort((a, b) => String(a.created_at).localeCompare(String(b.created_at)));
+      return records;
+    },
+
+    /**
+     * Entries whose envelope has not been acknowledged yet.
+     *
+     * @returns {SpoolRecord[]}
+     */
+    pendingResults() {
+      return spool.list().filter((record) => record.envelope !== null);
+    },
+
+    /**
+     * Entries claimed but never completed (a crash mid-run).
+     *
+     * @returns {SpoolRecord[]}
+     */
+    interruptedTasks() {
+      return spool.list().filter((record) => record.envelope === null);
+    },
+
+    /**
+     * Step 3: drop the entry once Rabbit confirmed it.
+     *
+     * @param {{task_id: string, attempt?: number}} entry
+     * @returns {boolean} Whether an entry was removed.
+     */
+    ack(entry) {
+      const dir = taskDir(entry.task_id, Number(entry.attempt) || 1);
+      try {
+        statSync(dir);
+      } catch {
+        return false;
+      }
+      rmSync(dir, { recursive: true, force: true });
+      return true;
+    },
+
+    /**
+     * Acknowledge by dedupe key (Rabbit may answer `deduped: true`).
+     *
+     * @param {string} dedupeKey
+     * @returns {number} Count removed.
+     */
+    ackByDedupeKey(dedupeKey) {
+      let removed = 0;
+      for (const record of spool.list()) {
+        if (record.dedupe_key && record.dedupe_key === dedupeKey) {
+          rmSync(record.dir, { recursive: true, force: true });
+          removed += 1;
+        }
+      }
+      return removed;
+    },
+
+    /** @returns {number} Entry count. */
+    size() {
+      return spool.list().length;
+    },
+
+    /** Remove everything (tests, `--reset-spool`). */
+    clear() {
+      const records = spool.list();
+      for (const record of records) rmSync(record.dir, { recursive: true, force: true });
+      return records.length;
+    },
+  };
+
+  return spool;
+}