@iowarp/clio-coder 0.4.7 → 0.4.9

package/dist/chunk-HCVKSGNZ.js

@@ -0,0 +1,990 @@
+import { createRequire as __clioCreateRequire } from "node:module"; const require = __clioCreateRequire(import.meta.url);
+import {
+  findExecutableOnPath
+} from "./chunk-XCUDZQLX.js";
+import {
+  isSecretArgKey
+} from "./chunk-EFSEIZE6.js";
+import {
+  formatSize
+} from "./chunk-KECNXMDE.js";
+import {
+  byteLength
+} from "./chunk-MYI32N4R.js";
+import {
+  StringEnum
+} from "./chunk-UIU7MGZ3.js";
+import {
+  SAFE_EXEC_GROUP_TEARDOWN_BOUND_MS,
+  createRetainedStreamWindow,
+  resolveSafeCwd,
+  runCommandVector
+} from "./chunk-XTQ7MEJG.js";
+import {
+  typebox_exports
+} from "./chunk-GH5ZR6JP.js";
+import {
+  init_esm_shims
+} from "./chunk-ECBHH7LU.js";
+
+// src/tools/run-script.ts
+init_esm_shims();
+import { closeSync as closeSync2, openSync as openSync2, realpathSync, statSync as statSync2, writeSync } from "node:fs";
+import path2 from "node:path";
+
+// src/core/run-records.ts
+init_esm_shims();
+import { createHash, randomBytes } from "node:crypto";
+import {
+  closeSync,
+  constants,
+  existsSync,
+  fstatSync,
+  lstatSync,
+  mkdirSync,
+  openSync,
+  readdirSync,
+  readSync,
+  renameSync,
+  rmSync,
+  statSync,
+  writeFileSync
+} from "node:fs";
+import { open } from "node:fs/promises";
+import path from "node:path";
+var RUN_RECORDS_RELATIVE_DIR = ".clio-coder/runs";
+var RUN_MANIFEST_FILENAME = "run.json";
+var RUN_STDOUT_FILENAME = "stdout.log";
+var RUN_STDERR_FILENAME = "stderr.log";
+var RUN_SWEEP_MANIFEST_MAX_BYTES = 64 * 1024;
+var RUN_FILE_HASH_MAX_BYTES = 64 * 1024 * 1024;
+var RUN_FILE_HASH_CHUNK_BYTES = 1024 * 1024;
+var RUN_RECORDS_DEFAULT_KEEP = 100;
+var RUN_RECORDS_ORPHAN_AFTER_MS = 24 * 60 * 60 * 1e3;
+var RUN_ID_PATTERN = /^\d{8}T\d{6}Z-[0-9a-f]{6}$/u;
+function compactUtc(now) {
+  return now.toISOString().replace(/[-:]/gu, "").replace(/\.\d{3}Z$/u, "Z");
+}
+function newRunId(now = /* @__PURE__ */ new Date()) {
+  return `${compactUtc(now)}-${randomBytes(3).toString("hex")}`;
+}
+function isRunId(value) {
+  return RUN_ID_PATTERN.test(value);
+}
+function runRecordsDir(workspaceRoot) {
+  return path.join(path.resolve(workspaceRoot), ...RUN_RECORDS_RELATIVE_DIR.split("/"));
+}
+function runRecordPaths(workspaceRoot, runId) {
+  const dir = path.join(runRecordsDir(workspaceRoot), runId);
+  return {
+    runId,
+    dir,
+    manifestPath: path.join(dir, RUN_MANIFEST_FILENAME),
+    stdoutPath: path.join(dir, RUN_STDOUT_FILENAME),
+    stderrPath: path.join(dir, RUN_STDERR_FILENAME)
+  };
+}
+function createRunRecord(workspaceRoot, runId = newRunId()) {
+  const paths = runRecordPaths(workspaceRoot, runId);
+  if (existsSync(paths.dir)) throw new Error(`run record already exists: ${paths.dir}`);
+  mkdirSync(paths.dir, { recursive: true });
+  return paths;
+}
+function workspaceRelativePath(workspaceRoot, target) {
+  const root = path.resolve(workspaceRoot);
+  const absolute = path.isAbsolute(target) ? path.resolve(target) : path.resolve(root, target);
+  const relative = path.relative(root, absolute);
+  if (relative.startsWith("..") || path.isAbsolute(relative)) return null;
+  return relative.length === 0 ? "." : relative.split(path.sep).join("/");
+}
+function abortError(signal) {
+  const error = new Error("file hashing cancelled", { cause: signal.reason });
+  error.name = "AbortError";
+  return error;
+}
+function isAbortError(error) {
+  return error instanceof Error && error.name === "AbortError";
+}
+async function hashFile(filePath, options = {}) {
+  const signal = options.signal;
+  if (signal?.aborted) throw abortError(signal);
+  const chunkBytes = Math.max(4096, Math.floor(options.chunkBytes ?? RUN_FILE_HASH_CHUNK_BYTES));
+  const hash = createHash("sha256");
+  const handle = await open(filePath, "r");
+  try {
+    const buffer = Buffer.allocUnsafe(chunkBytes);
+    for (; ; ) {
+      if (signal?.aborted) throw abortError(signal);
+      const { bytesRead } = await handle.read(buffer, 0, buffer.byteLength, null);
+      if (bytesRead === 0) break;
+      hash.update(buffer.subarray(0, bytesRead));
+    }
+  } finally {
+    await handle.close();
+  }
+  return hash.digest("hex");
+}
+async function observeFileHash(filePath, bytes, signal) {
+  if (bytes > RUN_FILE_HASH_MAX_BYTES) return { sha256: null, hashOmitted: "too-large" };
+  if (signal?.aborted) return { sha256: null, hashOmitted: "cancelled" };
+  try {
+    return { sha256: await hashFile(filePath, { signal }) };
+  } catch (error) {
+    return { sha256: null, hashOmitted: isAbortError(error) ? "cancelled" : "unreadable" };
+  }
+}
+async function captureFileRef(workspaceRoot, declaredPath, options = {}) {
+  const relative = workspaceRelativePath(workspaceRoot, declaredPath);
+  const rendered = relative ?? declaredPath.split(path.sep).join("/");
+  const absolute = path.resolve(workspaceRoot, declaredPath);
+  let stat;
+  try {
+    stat = statSync(absolute);
+  } catch {
+    return { path: rendered, exists: false };
+  }
+  if (!stat.isFile()) return { path: rendered, exists: true, mtimeMs: stat.mtimeMs };
+  const observation = await observeFileHash(absolute, stat.size, options.signal);
+  return { path: rendered, exists: true, bytes: stat.size, mtimeMs: stat.mtimeMs, ...observation };
+}
+async function captureOutputRef(workspaceRoot, declaredPath, before, options = {}) {
+  const after = await captureFileRef(workspaceRoot, declaredPath, options);
+  if (!after.exists) return { ...after, status: "absent" };
+  if (!before.exists) return { ...after, status: "created" };
+  const unchanged = typeof before.sha256 === "string" && typeof after.sha256 === "string" ? before.sha256 === after.sha256 : before.bytes === after.bytes && before.mtimeMs === after.mtimeMs;
+  return { ...after, status: unchanged ? "unchanged" : "modified" };
+}
+function writeRunManifest(paths, manifest) {
+  const temp = path.join(paths.dir, `${RUN_MANIFEST_FILENAME}.${process.pid}.tmp`);
+  writeFileSync(temp, `${JSON.stringify(manifest, null, 2)}
+`, "utf8");
+  renameSync(temp, paths.manifestPath);
+}
+function manifestCompletionMs(manifestPath) {
+  let before;
+  try {
+    before = lstatSync(manifestPath);
+  } catch (error) {
+    return error.code === "ENOENT" ? null : void 0;
+  }
+  if (!before.isFile()) return void 0;
+  let fd;
+  try {
+    fd = openSync(manifestPath, constants.O_RDONLY | constants.O_NONBLOCK | (constants.O_NOFOLLOW ?? 0));
+    const stat = fstatSync(fd);
+    if (!stat.isFile() || stat.dev !== before.dev || stat.ino !== before.ino) return void 0;
+    if (stat.size > RUN_SWEEP_MANIFEST_MAX_BYTES) return stat.mtimeMs;
+    const buffer = Buffer.alloc(stat.size);
+    let offset = 0;
+    while (offset < buffer.length) {
+      const count = readSync(fd, buffer, offset, Math.min(8192, buffer.length - offset), offset);
+      if (count === 0) break;
+      offset += count;
+    }
+    const after = fstatSync(fd);
+    if (after.size !== stat.size || after.mtimeMs !== stat.mtimeMs || offset !== stat.size) return stat.mtimeMs;
+    try {
+      const parsed = JSON.parse(buffer.toString("utf8"));
+      if (parsed !== null && typeof parsed === "object" && "finishedAt" in parsed && typeof parsed.finishedAt === "string") {
+        const finished = Date.parse(parsed.finishedAt);
+        if (Number.isFinite(finished)) return finished;
+      }
+    } catch {
+    }
+    return stat.mtimeMs;
+  } catch {
+    return void 0;
+  } finally {
+    if (fd !== void 0) closeSync(fd);
+  }
+}
+function sweepRunRecords(workspaceRoot, options = {}) {
+  const keep = Math.max(0, Math.floor(options.keep ?? RUN_RECORDS_DEFAULT_KEEP));
+  const root = runRecordsDir(workspaceRoot);
+  let entries;
+  try {
+    entries = readdirSync(root);
+  } catch {
+    return { removed: 0, kept: 0, active: 0, skipped: 0 };
+  }
+  const now = Date.now();
+  let skipped = 0;
+  let active = 0;
+  const completed = [];
+  for (const entry of entries) {
+    if (!isRunId(entry)) {
+      skipped += 1;
+      continue;
+    }
+    const dir = path.join(root, entry);
+    let dirStat;
+    try {
+      dirStat = lstatSync(dir);
+    } catch {
+      skipped += 1;
+      continue;
+    }
+    if (!dirStat.isDirectory()) {
+      skipped += 1;
+      continue;
+    }
+    const finishedMs = manifestCompletionMs(path.join(dir, RUN_MANIFEST_FILENAME));
+    if (finishedMs === void 0) {
+      skipped += 1;
+      continue;
+    }
+    if (finishedMs !== null) {
+      completed.push({ entry, finishedMs });
+      continue;
+    }
+    if (now - dirStat.mtimeMs < RUN_RECORDS_ORPHAN_AFTER_MS) {
+      active += 1;
+      continue;
+    }
+    completed.push({ entry, finishedMs: dirStat.mtimeMs });
+  }
+  completed.sort((a, b) => a.finishedMs - b.finishedMs || a.entry.localeCompare(b.entry));
+  const excess = Math.max(0, completed.length - keep);
+  let removed = 0;
+  for (const { entry } of completed.slice(0, excess)) {
+    try {
+      rmSync(path.join(root, entry), { recursive: true, force: true });
+      removed += 1;
+    } catch {
+      skipped += 1;
+    }
+  }
+  return { removed, kept: completed.length - removed, active, skipped };
+}
+
+// src/tools/run-script.ts
+var RUN_SCRIPT_INTERPRETERS = [
+  "python3",
+  "python",
+  "node",
+  "bash",
+  "sh",
+  "Rscript",
+  "julia",
+  "perl",
+  "ruby",
+  "octave"
+];
+var RUN_SCRIPT_CAPS = Object.freeze({
+  argEntries: 64,
+  argBytes: 4096,
+  declaredRefs: 64,
+  envEntries: 32,
+  envValueBytes: 4096,
+  defaultTimeoutMs: 6e5,
+  maxTimeoutMs: 216e5,
+  /** Bytes of each stream kept in memory for the result tail. */
+  resultTailBytes: 8 * 1024,
+  /** Bytes of each stream shown in a live progress snapshot. */
+  progressTailBytes: 2 * 1024,
+  progressThrottleMs: 250
+});
+var RUN_SCRIPT_DEFAULT_INTERPRETER_ARGS = {
+  python3: ["-u"],
+  python: ["-u"],
+  node: [],
+  bash: [],
+  sh: [],
+  Rscript: [],
+  julia: [],
+  perl: [],
+  ruby: [],
+  octave: []
+};
+var RUN_SCRIPT_TOOL_NAME = "run_script";
+var ENV_KEY_PATTERN = /^[A-Z_][A-Z0-9_]*$/u;
+function parseStringArray(value) {
+  if (value === void 0 || value === null) return [];
+  if (!Array.isArray(value)) return null;
+  const out = [];
+  for (const entry of value) {
+    if (typeof entry !== "string") return null;
+    out.push(entry);
+  }
+  return out;
+}
+function prepareRunScriptArguments(args) {
+  if (!args || typeof args !== "object" || Array.isArray(args)) return args;
+  const next = { ...args };
+  for (const key of ["args", "interpreter_args", "inputs", "outputs"]) {
+    const value = next[key];
+    if (typeof value !== "string") continue;
+    const trimmed = value.trim();
+    if (trimmed.startsWith("[")) {
+      try {
+        const parsed = JSON.parse(trimmed);
+        if (Array.isArray(parsed)) {
+          next[key] = parsed;
+          continue;
+        }
+      } catch {
+      }
+    }
+    next[key] = trimmed.length === 0 ? [] : [value];
+  }
+  if (typeof next.env === "string") {
+    try {
+      const parsed = JSON.parse(next.env);
+      if (parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)) next.env = parsed;
+    } catch {
+    }
+  }
+  return next;
+}
+function invalid(message) {
+  return { ok: false, message: `run_script: ${message}` };
+}
+function isInterpreter(value) {
+  return RUN_SCRIPT_INTERPRETERS.includes(value);
+}
+function validateArgVector(value, field) {
+  const entries = parseStringArray(value);
+  if (entries === null) return `${field} must be an array of strings`;
+  if (entries.length > RUN_SCRIPT_CAPS.argEntries) {
+    return `${field} exceeds the ${RUN_SCRIPT_CAPS.argEntries}-entry cap`;
+  }
+  for (const [index, entry] of entries.entries()) {
+    if (entry.includes("\0")) return `${field}[${index}] must not contain a NUL byte`;
+    if (byteLength(entry) > RUN_SCRIPT_CAPS.argBytes) {
+      return `${field}[${index}] exceeds the ${RUN_SCRIPT_CAPS.argBytes}-byte cap`;
+    }
+  }
+  return entries;
+}
+function validateDeclaredRefs(value, field, workspaceRoot) {
+  const entries = parseStringArray(value);
+  if (entries === null) return `${field} must be an array of workspace-relative path strings`;
+  if (entries.length > RUN_SCRIPT_CAPS.declaredRefs) {
+    return `${field} exceeds the ${RUN_SCRIPT_CAPS.declaredRefs}-entry cap`;
+  }
+  const refs = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const [index, entry] of entries.entries()) {
+    const location = `${field}[${index}]`;
+    if (entry.trim().length === 0) return `${location} must be a non-empty path`;
+    if (entry.includes("\0")) return `${location} must not contain a NUL byte`;
+    if (path2.isAbsolute(entry) || path2.win32.isAbsolute(entry)) {
+      return `${location} must be workspace-relative; absolute path '${entry}' is not allowed`;
+    }
+    const relative = workspaceRelativePath(workspaceRoot, entry);
+    if (relative === null) return `${location} escapes the workspace root: '${entry}'`;
+    if (seen.has(relative)) continue;
+    seen.add(relative);
+    refs.push({ declared: entry, relative });
+  }
+  return refs;
+}
+function validateEnv(value) {
+  if (value === void 0 || value === null) return {};
+  if (typeof value !== "object" || Array.isArray(value)) return "env must be an object of string values";
+  const entries = Object.entries(value);
+  if (entries.length > RUN_SCRIPT_CAPS.envEntries) return `env exceeds the ${RUN_SCRIPT_CAPS.envEntries}-entry cap`;
+  const env = {};
+  for (const [key, raw] of entries) {
+    if (!ENV_KEY_PATTERN.test(key)) return `env key '${key}' must match /^[A-Z_][A-Z0-9_]*$/`;
+    if (typeof raw !== "string") return `env.${key} must be a string`;
+    if (raw.includes("\0")) return `env.${key} must not contain a NUL byte`;
+    if (byteLength(raw) > RUN_SCRIPT_CAPS.envValueBytes) {
+      return `env.${key} exceeds the ${RUN_SCRIPT_CAPS.envValueBytes}-byte cap`;
+    }
+    env[key] = raw;
+  }
+  return env;
+}
+function insideRoot(realRoot, candidate) {
+  const relative = path2.relative(realRoot, candidate);
+  return relative === "" || !relative.startsWith("..") && !path2.isAbsolute(relative);
+}
+function validateRequest(args, workspaceRoot) {
+  const interpreterArg = typeof args.interpreter === "string" ? args.interpreter.trim() : "";
+  if (interpreterArg.length === 0) return invalid("missing interpreter argument");
+  if (!isInterpreter(interpreterArg)) {
+    return invalid(
+      `interpreter must be one of ${RUN_SCRIPT_INTERPRETERS.join(", ")}; got '${interpreterArg}'. Paths and other executables are not accepted.`
+    );
+  }
+  const interpreter = interpreterArg;
+  const interpreterPath = findExecutableOnPath(interpreter);
+  if (interpreterPath === null) return invalid(`interpreter '${interpreter}' was not found on PATH`);
+  const scriptArg = typeof args.script === "string" ? args.script.trim() : "";
+  if (scriptArg.length === 0) return invalid("missing script argument");
+  if (scriptArg.includes("\0")) return invalid("script must not contain a NUL byte");
+  let realRoot;
+  try {
+    realRoot = realpathSync(workspaceRoot);
+  } catch (error) {
+    return invalid(`workspace root cannot be resolved (${error instanceof Error ? error.message : String(error)})`);
+  }
+  const scriptAbsolute = path2.isAbsolute(scriptArg) ? path2.resolve(scriptArg) : path2.resolve(realRoot, scriptArg);
+  let scriptRealPath;
+  let scriptBytes;
+  try {
+    scriptRealPath = realpathSync(scriptAbsolute);
+    const stat = statSync2(scriptRealPath);
+    if (!stat.isFile()) return invalid(`script is not a regular file: ${scriptArg}`);
+    scriptBytes = stat.size;
+  } catch (error) {
+    const code = error?.code;
+    if (code === "ENOENT") return invalid(`script not found: ${scriptArg}`);
+    return invalid(`script cannot be resolved: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  if (!insideRoot(realRoot, scriptRealPath)) {
+    return invalid(`script resolves outside the workspace root: ${scriptArg} -> ${scriptRealPath}`);
+  }
+  const scriptRelative = workspaceRelativePath(realRoot, scriptRealPath) ?? scriptArg;
+  const scriptArgs = validateArgVector(args.args, "args");
+  if (typeof scriptArgs === "string") return invalid(scriptArgs);
+  let interpreterArgs;
+  if (args.interpreter_args === void 0 || args.interpreter_args === null) {
+    interpreterArgs = [...RUN_SCRIPT_DEFAULT_INTERPRETER_ARGS[interpreter]];
+  } else {
+    const explicit = validateArgVector(args.interpreter_args, "interpreter_args");
+    if (typeof explicit === "string") return invalid(explicit);
+    interpreterArgs = explicit;
+  }
+  const cwdArg = typeof args.cwd === "string" && args.cwd.trim().length > 0 ? args.cwd.trim() : void 0;
+  let cwdExecution;
+  try {
+    const resolved = resolveSafeCwd(cwdArg, realRoot);
+    const stat = statSync2(resolved);
+    if (!stat.isDirectory()) return invalid(`cwd is not a directory: ${cwdArg ?? "."}`);
+    cwdExecution = realpathSync(resolved);
+    if (!insideRoot(realRoot, cwdExecution)) {
+      return invalid(`cwd escapes the workspace root through a symbolic link: ${cwdArg ?? "."}`);
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (message.includes("escapes workspace root")) return invalid(`cwd escapes the workspace root: ${cwdArg ?? "."}`);
+    return invalid(`cwd cannot be resolved: ${cwdArg ?? "."} (${message})`);
+  }
+  const cwdRelative = workspaceRelativePath(realRoot, cwdExecution) ?? ".";
+  let timeoutMs = RUN_SCRIPT_CAPS.defaultTimeoutMs;
+  if (args.timeout_ms !== void 0 && args.timeout_ms !== null) {
+    if (typeof args.timeout_ms !== "number" || !Number.isInteger(args.timeout_ms) || args.timeout_ms < 1) {
+      return invalid("timeout_ms must be a positive integer number of milliseconds");
+    }
+    timeoutMs = Math.min(Math.max(1, args.timeout_ms), RUN_SCRIPT_CAPS.maxTimeoutMs);
+  }
+  const inputs = validateDeclaredRefs(args.inputs, "inputs", realRoot);
+  if (typeof inputs === "string") return invalid(inputs);
+  const outputs = validateDeclaredRefs(args.outputs, "outputs", realRoot);
+  if (typeof outputs === "string") return invalid(outputs);
+  const env = validateEnv(args.env);
+  if (typeof env === "string") return invalid(env);
+  return {
+    ok: true,
+    request: {
+      workspaceRoot: realRoot,
+      interpreter,
+      interpreterPath,
+      interpreterArgs,
+      scriptDeclared: scriptArg,
+      scriptRelative,
+      scriptRealPath,
+      scriptBytes,
+      args: scriptArgs,
+      cwdRelative,
+      cwdExecution,
+      timeoutMs,
+      inputs,
+      outputs,
+      env
+    }
+  };
+}
+function quoted(value) {
+  return `'${value.replaceAll("'", "'\\''")}'`;
+}
+function runScriptSafetyProjection(args) {
+  const prepared = prepareRunScriptArguments(args);
+  const interpreter = typeof prepared.interpreter === "string" ? prepared.interpreter.trim() : "";
+  const script = typeof prepared.script === "string" ? prepared.script.trim() : "";
+  const interpreterArgs = prepared.interpreter_args === void 0 || prepared.interpreter_args === null ? isInterpreter(interpreter) ? [...RUN_SCRIPT_DEFAULT_INTERPRETER_ARGS[interpreter]] : [] : parseStringArray(prepared.interpreter_args) ?? [];
+  const scriptArgs = parseStringArray(prepared.args) ?? [];
+  const vector = [
+    ...interpreter.length > 0 ? [interpreter] : [],
+    ...interpreterArgs,
+    ...script.length > 0 ? [script] : [],
+    ...scriptArgs
+  ];
+  const command = vector.map(quoted).join(" ");
+  const cwd = typeof prepared.cwd === "string" && prepared.cwd.trim().length > 0 ? prepared.cwd.trim() : void 0;
+  return cwd === void 0 ? { command } : { command, cwd };
+}
+var SYSTEM_SCHEDULER = {
+  now: Date.now,
+  setTimeout: (callback, delayMs) => setTimeout(callback, delayMs),
+  clearTimeout: (timer) => clearTimeout(timer)
+};
+function createRunScriptProgressController(input) {
+  const scheduler = input.scheduler ?? SYSTEM_SCHEDULER;
+  const throttleMs = input.throttleMs ?? RUN_SCRIPT_CAPS.progressThrottleMs;
+  const tailBytes = input.tailBytes ?? RUN_SCRIPT_CAPS.progressTailBytes;
+  const stdoutTail = createRetainedStreamWindow(0, tailBytes);
+  const stderrTail = createRetainedStreamWindow(0, tailBytes);
+  let phase = "idle";
+  let startedAt = 0;
+  let lastEmitAt = Number.NEGATIVE_INFINITY;
+  let dirty = false;
+  let timer = null;
+  const snapshot = () => {
+    const elapsedMs = Math.max(0, scheduler.now() - startedAt);
+    const out = stdoutTail.render();
+    const err = stderrTail.render();
+    const lines = [
+      `run_script: running ${input.label} (${formatElapsed(elapsedMs)} elapsed)`,
+      `stdout: ${out.totalBytes} bytes | stderr: ${err.totalBytes} bytes`,
+      "--- stdout tail ---",
+      out.text.length > 0 ? out.text : "(no output yet)",
+      "--- stderr tail ---",
+      err.text.length > 0 ? err.text : "(no output yet)"
+    ];
+    return {
+      kind: "ok",
+      output: lines.join("\n"),
+      details: { progress: { elapsedMs, stdoutBytes: out.totalBytes, stderrBytes: err.totalBytes } }
+    };
+  };
+  const emit = () => {
+    if (!dirty) return;
+    dirty = false;
+    lastEmitAt = scheduler.now();
+    try {
+      input.onUpdate(snapshot());
+    } catch {
+    }
+  };
+  const clearTimer = () => {
+    if (timer === null) return;
+    scheduler.clearTimeout(timer);
+    timer = null;
+  };
+  const schedule = () => {
+    if (phase !== "active") return;
+    dirty = true;
+    const delay = throttleMs - (scheduler.now() - lastEmitAt);
+    if (delay <= 0) {
+      clearTimer();
+      emit();
+      return;
+    }
+    timer ??= scheduler.setTimeout(() => {
+      timer = null;
+      if (phase === "active") emit();
+    }, delay);
+  };
+  return {
+    start() {
+      if (phase !== "idle") return;
+      phase = "active";
+      startedAt = scheduler.now();
+      dirty = true;
+      emit();
+    },
+    append(target, chunk) {
+      if (phase !== "active") return;
+      (target === "stdout" ? stdoutTail : stderrTail).append(chunk);
+      schedule();
+    },
+    settle() {
+      if (phase !== "active") return;
+      clearTimer();
+      emit();
+      phase = "settled";
+    }
+  };
+}
+function formatElapsed(ms) {
+  if (ms < 1e3) return `${Math.round(ms)}ms`;
+  const seconds = ms / 1e3;
+  if (seconds < 60) return `${seconds.toFixed(1)}s`;
+  const minutes = Math.floor(seconds / 60);
+  return `${minutes}m${Math.round(seconds - minutes * 60)}s`;
+}
+function classifyOutcome(result) {
+  if (result.aborted) return "aborted";
+  if (result.timedOut) return "timed-out";
+  if (result.pipeDrainIncomplete) return "pipe-drain-incomplete";
+  if (result.sinkError !== void 0) return "failed";
+  if (result.exitCode === null && result.signal === null) return "spawn-failed";
+  if (result.cleanupIncomplete && result.leaderExit?.code === 0) return "cleanup-incomplete";
+  if (result.exitCode !== 0) return "failed";
+  return result.cleanupIncomplete === true ? "cleanup-incomplete" : "succeeded";
+}
+function runnerFailureResult(file, args, cwd, startedAt, written, aborted) {
+  return {
+    file,
+    args,
+    cwd,
+    stdout: "",
+    stderr: "",
+    exitCode: null,
+    signal: null,
+    aborted,
+    timedOut: false,
+    outputCapped: false,
+    durationMs: Math.max(0, Date.now() - startedAt.getTime()),
+    startedAt: startedAt.getTime(),
+    stdoutBytes: written.stdout,
+    stderrBytes: written.stderr,
+    stdoutRetained: written.stdout === 0,
+    stderrRetained: written.stderr === 0,
+    descendantsCleaned: false,
+    cleanupIncomplete: false,
+    failure: null
+  };
+}
+function streamLine(name, bytes, retained, logRelative, tailBytes) {
+  if (bytes === 0) return `${name}: 0 bytes (empty)`;
+  if (retained) return `${name}: ${bytes} bytes (complete below)`;
+  return `${name}: ${bytes} bytes (last ${formatSize(tailBytes)} below; full log: ${logRelative})`;
+}
+function refsTable(heading, refs) {
+  if (refs.length === 0) return [];
+  const lines = [`${heading}:`];
+  for (const ref of refs) {
+    const status = "status" in ref ? ref.status : ref.exists ? "present" : "absent";
+    const size = ref.bytes === void 0 ? "" : ` ${ref.bytes} bytes`;
+    const omission = ref.hashOmitted === void 0 ? "" : ` (hash omitted: ${ref.hashOmitted})`;
+    lines.push(`  ${ref.path}  ${status}${size}${omission}`);
+  }
+  return lines;
+}
+function tailSection(name, text) {
+  return [`--- ${name} tail ---`, text.length > 0 ? text : "(empty)"];
+}
+var DESCRIPTION = `Run one script from the workspace with an explicit interpreter, arguments, and working directory, as an observable scientific step. Complete stdout and stderr stream to .clio-coder/runs/<runId>/stdout.log and stderr.log and a run.json manifest records the script hash, exact argv, cwd, declared env keys, timing, outcome, and the observed state of declared inputs and outputs; the result carries bounded tails of both streams and names the run directory. Declared inputs and outputs are provenance only and do not restrict what the script may touch. No dependency installation, no retries, no hidden environment changes. Default timeout ${RUN_SCRIPT_CAPS.defaultTimeoutMs}ms; a nonzero exit, timeout, or cancellation returns an error that still names the logs and any partial outputs.`;
+var runScriptToolSurface = {
+  name: RUN_SCRIPT_TOOL_NAME,
+  description: DESCRIPTION,
+  parameters: typebox_exports.Object({
+    interpreter: StringEnum(RUN_SCRIPT_INTERPRETERS, {
+      description: "Interpreter resolved on PATH. Only these names are accepted; never a path."
+    }),
+    script: typebox_exports.String({
+      description: "Script file inside the workspace (relative to the workspace root or absolute)."
+    }),
+    args: typebox_exports.Optional(typebox_exports.Array(typebox_exports.String(), { description: "Arguments passed to the script, in order." })),
+    interpreter_args: typebox_exports.Optional(
+      typebox_exports.Array(typebox_exports.String(), {
+        description: "Flags placed before the script. Omit for the recorded default (-u for python/python3, none otherwise)."
+      })
+    ),
+    cwd: typebox_exports.Optional(
+      typebox_exports.String({ description: "Working directory, relative to the workspace root (default: the root)." })
+    ),
+    timeout_ms: typebox_exports.Optional(
+      typebox_exports.Number({ description: `Wall-clock limit in ms (default ${RUN_SCRIPT_CAPS.defaultTimeoutMs}).` })
+    ),
+    inputs: typebox_exports.Optional(
+      typebox_exports.Array(typebox_exports.String(), {
+        description: "Workspace-relative files the script reads; recorded with size and hash before the run."
+      })
+    ),
+    outputs: typebox_exports.Optional(
+      typebox_exports.Array(typebox_exports.String(), {
+        description: "Workspace-relative files the script should produce; reported as created, modified, unchanged, or absent after the run."
+      })
+    ),
+    env: typebox_exports.Optional(
+      typebox_exports.Record(typebox_exports.String(), typebox_exports.String(), {
+        description: "Extra environment variables for the script; keys are recorded, values never are."
+      })
+    )
+  }),
+  baseActionClass: "execute",
+  executionMode: "sequential",
+  prepareArguments: prepareRunScriptArguments,
+  safetyCall(args) {
+    const projection = runScriptSafetyProjection(args);
+    return {
+      tool: "bash",
+      args: { command: projection.command, ...projection.cwd === void 0 ? {} : { cwd: projection.cwd } }
+    };
+  }
+};
+function openLogs(paths) {
+  const stdout = { fd: openSync2(paths.stdoutPath, "w"), path: paths.stdoutPath };
+  let stderr;
+  try {
+    stderr = { fd: openSync2(paths.stderrPath, "w"), path: paths.stderrPath };
+  } catch (error) {
+    closeSync2(stdout.fd);
+    throw error;
+  }
+  return { stdout, stderr };
+}
+function writeAll(fd, chunk) {
+  let offset = 0;
+  while (offset < chunk.byteLength) {
+    offset += writeSync(fd, chunk, offset, chunk.byteLength - offset, null);
+  }
+}
+function closeQuietly(fd) {
+  try {
+    closeSync2(fd);
+  } catch {
+  }
+}
+function createRunScriptTool(deps = {}) {
+  const getWorkspaceRoot = deps.getWorkspaceRoot ?? (() => process.cwd());
+  const now = deps.now ?? (() => /* @__PURE__ */ new Date());
+  const runCommand = deps.runCommand ?? runCommandVector;
+  return {
+    ...runScriptToolSurface,
+    async run(rawArgs, options) {
+      const args = prepareRunScriptArguments(rawArgs);
+      const validation = validateRequest(args, path2.resolve(getWorkspaceRoot()));
+      if (!validation.ok) return { kind: "error", message: validation.message };
+      const request = validation.request;
+      const workspaceRoot = request.workspaceRoot;
+      const signal = options?.signal;
+      const abortedBeforeExecution = () => ({
+        kind: "error",
+        message: "run_script: aborted before execution"
+      });
+      if (signal?.aborted) return abortedBeforeExecution();
+      const scriptHash = await observeFileHash(request.scriptRealPath, request.scriptBytes, signal);
+      if (scriptHash.hashOmitted === "cancelled") return abortedBeforeExecution();
+      if (scriptHash.hashOmitted === "unreadable") {
+        return { kind: "error", message: `run_script: script cannot be read: ${request.scriptDeclared}` };
+      }
+      const inputRefs = [];
+      for (const ref of request.inputs) inputRefs.push(await captureFileRef(workspaceRoot, ref.declared, { signal }));
+      const outputsBefore = [];
+      for (const ref of request.outputs) {
+        outputsBefore.push(await captureFileRef(workspaceRoot, ref.declared, { signal }));
+      }
+      if (signal?.aborted) return abortedBeforeExecution();
+      let paths;
+      let logs;
+      try {
+        paths = createRunRecord(workspaceRoot);
+        logs = openLogs(paths);
+      } catch (error) {
+        return {
+          kind: "error",
+          message: `run_script: cannot create the run record: ${error instanceof Error ? error.message : String(error)}`
+        };
+      }
+      const label = [request.interpreter, ...request.interpreterArgs, request.scriptRelative, ...request.args].join(" ");
+      const progress = options?.onUpdate === void 0 ? null : createRunScriptProgressController({
+        onUpdate: options.onUpdate,
+        label,
+        ...deps.scheduler ? { scheduler: deps.scheduler } : {}
+      });
+      const vector = [...request.interpreterArgs, request.scriptRealPath, ...request.args];
+      const written = { stdout: 0, stderr: 0 };
+      const startedAt = now();
+      let result;
+      let failure = null;
+      progress?.start();
+      try {
+        result = await runCommand(request.interpreterPath, vector, {
+          cwd: request.cwdExecution,
+          workspaceRoot,
+          timeoutMs: request.timeoutMs,
+          env: request.env,
+          ...signal ? { signal } : {},
+          output: {
+            retainHeadBytes: 0,
+            retainTailBytes: RUN_SCRIPT_CAPS.resultTailBytes,
+            onStdout(chunk) {
+              writeAll(logs.stdout.fd, chunk);
+              written.stdout += chunk.byteLength;
+              progress?.append("stdout", chunk);
+            },
+            onStderr(chunk) {
+              writeAll(logs.stderr.fd, chunk);
+              written.stderr += chunk.byteLength;
+              progress?.append("stderr", chunk);
+            }
+          }
+        });
+      } catch (error) {
+        failure = error instanceof Error ? error.message : String(error);
+        result = runnerFailureResult(
+          request.interpreterPath,
+          vector,
+          request.cwdExecution,
+          startedAt,
+          written,
+          signal?.aborted === true
+        );
+      } finally {
+        progress?.settle();
+        closeQuietly(logs.stdout.fd);
+        closeQuietly(logs.stderr.fd);
+      }
+      const finishedAt = now();
+      const outcome = classifyOutcome(result);
+      const outputRefs = [];
+      for (const [index, ref] of request.outputs.entries()) {
+        outputRefs.push(
+          await captureOutputRef(workspaceRoot, ref.declared, outputsBefore[index], { signal })
+        );
+      }
+      const declaredKeys = Object.keys(request.env).sort();
+      const manifest = {
+        version: 1,
+        runId: paths.runId,
+        tool: "run_script",
+        startedAt: startedAt.toISOString(),
+        finishedAt: finishedAt.toISOString(),
+        durationMs: result.durationMs,
+        script: {
+          path: request.scriptRelative,
+          realPath: request.scriptRealPath,
+          sha256: scriptHash.sha256,
+          ...scriptHash.hashOmitted === void 0 ? {} : { hashOmitted: scriptHash.hashOmitted },
+          bytes: request.scriptBytes
+        },
+        interpreter: {
+          name: request.interpreter,
+          resolvedPath: request.interpreterPath,
+          args: [...request.interpreterArgs]
+        },
+        argv: [result.file, ...result.args],
+        cwd: request.cwdRelative,
+        env: { declaredKeys, redactedKeys: declaredKeys.filter((key) => isSecretArgKey(key)) },
+        timeoutMs: request.timeoutMs,
+        outcome,
+        exitCode: result.exitCode,
+        leaderExit: result.leaderExit ?? null,
+        pipeDrainIncomplete: result.pipeDrainIncomplete === true,
+        signal: result.signal,
+        stdoutBytes: result.stdoutBytes ?? 0,
+        stderrBytes: result.stderrBytes ?? 0,
+        logs: { stdout: path2.basename(paths.stdoutPath), stderr: path2.basename(paths.stderrPath) },
+        inputs: inputRefs,
+        outputs: outputRefs,
+        cleanup: {
+          descendantsCleaned: result.descendantsCleaned === true,
+          incomplete: result.cleanupIncomplete === true
+        },
+        ...failure === null ? {} : { failure }
+      };
+      let manifestError = null;
+      try {
+        writeRunManifest(paths, manifest);
+      } catch (error) {
+        manifestError = error instanceof Error ? error.message : String(error);
+      }
+      const sweep = sweepRunRecords(workspaceRoot, { keep: deps.keepRuns ?? RUN_RECORDS_DEFAULT_KEEP });
+      const runRelative = workspaceRelativePath(workspaceRoot, paths.dir) ?? paths.dir;
+      const stdoutRelative = workspaceRelativePath(workspaceRoot, paths.stdoutPath) ?? paths.stdoutPath;
+      const stderrRelative = workspaceRelativePath(workspaceRoot, paths.stderrPath) ?? paths.stderrPath;
+      const reportedExit = result.leaderExit ?? { code: result.exitCode, signal: result.signal };
+      const ending = reportedExit.code !== null ? `exit ${reportedExit.code}` : reportedExit.signal !== null ? `signal ${reportedExit.signal}` : "did not start";
+      const headline = `run_script ${outcome}: ${label} (${ending}, ${formatElapsed(result.durationMs)})`;
+      const lines = [
+        headline,
+        `run: ${runRelative}`,
+        streamLine(
+          "stdout",
+          manifest.stdoutBytes,
+          result.stdoutRetained === true,
+          stdoutRelative,
+          RUN_SCRIPT_CAPS.resultTailBytes
+        ),
+        streamLine(
+          "stderr",
+          manifest.stderrBytes,
+          result.stderrRetained === true,
+          stderrRelative,
+          RUN_SCRIPT_CAPS.resultTailBytes
+        ),
+        ...refsTable("inputs", inputRefs),
+        ...refsTable("outputs", outputRefs),
+        ...tailSection("stdout", result.stdout),
+        ...tailSection("stderr", result.stderr)
+      ];
+      if (outcome === "timed-out") {
+        lines.push(
+          `the run timed out after ${request.timeoutMs}ms (SIGTERM, then SIGKILL); the logs end where the script was stopped`
+        );
+      } else if (outcome === "aborted") {
+        lines.push("the run was cancelled; the logs end where the script was stopped");
+      } else if (outcome === "spawn-failed") {
+        lines.push(`the interpreter did not start: ${failure ?? (result.stderr.trim() || "unknown spawn failure")}`);
+      }
+      if (result.sinkError !== void 0) {
+        lines.push(`log write failed (${result.sinkError}); the script was stopped and the logs are incomplete`);
+      }
+      if (manifest.cleanup.descendantsCleaned) {
+        lines.push(
+          "processes the script started were still running in its process group after it ended; they were sent SIGTERM, then SIGKILL"
+        );
+      }
+      if (result.pipeDrainIncomplete) {
+        lines.push(
+          "output pipe draining incomplete after leader exit; logs may be incomplete and escaped processes are not contained"
+        );
+      }
+      if (manifest.cleanup.incomplete) {
+        lines.push(
+          `${result.failure ?? `process group cleanup incomplete: members were still present ${SAFE_EXEC_GROUP_TEARDOWN_BOUND_MS}ms after SIGKILL`}; check for stuck processes before trusting the outputs`
+        );
+      }
+      if ((outcome === "cleanup-incomplete" || result.pipeDrainIncomplete) && outputRefs.length > 0) {
+        lines.push(
+          result.pipeDrainIncomplete ? "outputs listed above may still change; processes outside the original group may still be running" : "outputs listed above may still change; processes the script started are still present"
+        );
+      } else if (outcome !== "succeeded" && outputRefs.length > 0) {
+        lines.push(
+          reportedExit.code === 0 ? "outputs listed above may be partial; the run did not complete successfully" : "outputs listed above may be partial; the script did not exit 0"
+        );
+      }
+      if (manifestError !== null) lines.push(`manifest write failed: ${manifestError}`);
+      const text = lines.join("\n");
+      const details = {
+        runId: paths.runId,
+        runDir: paths.dir,
+        manifestPath: paths.manifestPath,
+        outcome,
+        exitCode: result.exitCode,
+        leaderExit: result.leaderExit ?? null,
+        pipeDrainIncomplete: result.pipeDrainIncomplete === true,
+        signal: result.signal,
+        timedOut: result.timedOut,
+        aborted: result.aborted,
+        durationMs: result.durationMs,
+        stdoutBytes: manifest.stdoutBytes,
+        stderrBytes: manifest.stderrBytes,
+        stdoutPath: paths.stdoutPath,
+        stderrPath: paths.stderrPath,
+        script: { path: request.scriptRelative, sha256: scriptHash.sha256 },
+        argv: manifest.argv,
+        cwd: request.cwdRelative,
+        inputs: inputRefs,
+        outputs: outputRefs,
+        cleanup: manifest.cleanup,
+        sweep,
+        ...failure === null ? {} : { failure },
+        ...manifestError === null ? {} : { manifestError }
+      };
+      if (outcome === "succeeded" && manifestError === null) return { kind: "ok", output: text, details };
+      return { kind: "error", message: text, details };
+    }
+  };
+}
+var runScriptTool = createRunScriptTool();
+
+export {
+  RUN_SCRIPT_INTERPRETERS,
+  RUN_SCRIPT_CAPS,
+  RUN_SCRIPT_DEFAULT_INTERPRETER_ARGS,
+  RUN_SCRIPT_TOOL_NAME,
+  prepareRunScriptArguments,
+  runScriptSafetyProjection,
+  createRunScriptProgressController,
+  runScriptToolSurface,
+  createRunScriptTool,
+  runScriptTool
+};
+//# sourceMappingURL=chunk-HCVKSGNZ.js.map