@introspection-ai/operator 0.1.1 → 0.1.2

package/extensions/case-runs/runs.mjs

@@ -0,0 +1,191 @@
+// Runs of the agent being built, one per case, in the background: the part of the case-run tools that doesn't
+// need Pi, so it can be tested on its own.
+//
+// A bash call that runs `introspection local` and is killed at its time limit leaves only "timed out": a run
+// that was still thinking looks the same as one stuck on a tool. Here each run keeps its session and its event
+// stream in its own folder, and the events say which it is. A run is stopped only when a tool hangs, the model
+// goes quiet, or its time budget runs out, and the status says which.
+import { spawn } from "node:child_process";
+import { copyFileSync, createWriteStream, existsSync, mkdirSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import { basename, delimiter, isAbsolute, join, relative, resolve } from "node:path";
+import { createRunReader, describe } from "./events.mjs";
+
+export const DEFAULT_BUDGET_MINUTES = 45;
+export const MAX_WAIT_SECONDS = 1800;
+const WATCH_MS = 15_000;
+// Problems that end a run on their own; a loop is reported, and the build agent decides.
+const STOPS = new Set(["tool-hung", "stalled", "over-budget"]);
+
+// The run must not inherit the Operator's own launch: its agent name and Recipe (a Recipe launch reads them as
+// defaults) and its Python environment.
+export function runEnvironment(base, extra = {}) {
+  const env = { ...base };
+  delete env.PI_AGENT_NAME;
+  delete env.PI_RECIPE_DIR;
+  if (env.VIRTUAL_ENV) {
+    const bin = join(env.VIRTUAL_ENV, process.platform === "win32" ? "Scripts" : "bin");
+    env.PATH = (env.PATH ?? "").split(delimiter).filter((dir) => dir !== bin).join(delimiter);
+    delete env.VIRTUAL_ENV;
+  }
+  Object.assign(env, extra);
+  if (extra.VIRTUAL_ENV) {
+    const bin = join(extra.VIRTUAL_ENV, process.platform === "win32" ? "Scripts" : "bin");
+    env.PATH = [bin, env.PATH].filter(Boolean).join(delimiter);
+  }
+  return env;
+}
+
+export function createCaseRuns({ command = "introspection", env: baseEnv = process.env, watchMs = WATCH_MS, shutdownGraceMs = 5_000 } = {}) {
+  const runs = new Map();
+
+  function outputsOf(run) {
+    const root = join(run.dir, "outputs");
+    const found = [];
+    const walk = (dir) => {
+      if (!existsSync(dir)) return;
+      for (const name of readdirSync(dir)) {
+        const path = join(dir, name);
+        const stat = statSync(path);
+        if (stat.isDirectory()) walk(path);
+        else found.push({ path: relative(run.cwd, path), bytes: stat.size });
+      }
+    };
+    walk(root);
+    return found;
+  }
+
+  function status(run, now = Date.now()) {
+    return describe(run.reader.state, { ...run, outputs: run.exit ? outputsOf(run) : [] }, now);
+  }
+
+  function save(run) {
+    const { id, case: caseId, prompt, repository, started, budgetMs, exit, stopReason } = run;
+    writeFileSync(join(run.dir, "run.json"), `${JSON.stringify({ id, case: caseId, prompt, repository, started: new Date(started).toISOString(), budgetMinutes: budgetMs / 60_000, exit, stopReason }, null, 2)}\n`);
+  }
+
+  // The run's whole process group: what the launcher started, too, even after the launcher has exited.
+  function kill(run, signal) {
+    try {
+      if (process.platform === "win32") run.child.kill(signal);
+      else process.kill(-run.child.pid, signal);
+    } catch {
+      // Already gone.
+    }
+  }
+
+  function stop(run, reason, problem) {
+    if (run.exit || run.stopping) return;
+    run.stopping = true;
+    run.stopReason = reason;
+    run.stopProblem = problem;
+    kill(run, "SIGTERM");
+    // A tool the run started may ignore SIGTERM.
+    setTimeout(() => kill(run, "SIGKILL"), 10_000).unref();
+  }
+
+  function start({ cwd, caseId, prompt, repository, files = [], agent, budgetMinutes = DEFAULT_BUDGET_MINUTES, env = {} }) {
+    const name = String(caseId).replace(/[^A-Za-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "") || "case";
+    const runsDir = join(cwd, "runs");
+    let n = 1;
+    while (existsSync(join(runsDir, `${name}-${n}`))) n++;
+    const id = `${name}-${n}`;
+    const dir = join(runsDir, id);
+    const repo = resolve(cwd, repository);
+    if (!existsSync(join(repo, "package.json"))) throw new Error(`${repository} is not the agent's repository: no package.json in ${repo}`);
+    const inputs = new Map();
+    for (const file of files) {
+      const from = resolve(cwd, file);
+      if (!existsSync(from)) throw new Error(`no file ${file}`);
+      const name = basename(from);
+      if (inputs.has(name)) throw new Error(`two input files are named ${name} (${inputs.get(name)} and ${file}); rename one, since both would be files/${name}`);
+      inputs.set(name, file);
+    }
+    for (const sub of ["files", "outputs", "session"]) mkdirSync(join(dir, sub), { recursive: true });
+    for (const [name, file] of inputs) copyFileSync(resolve(cwd, file), join(dir, "files", name));
+
+    const args = ["local", "--work-dir", repo, ...(agent ? ["--agent", agent] : []), "-p", prompt, "--mode", "json", "--", "--session-dir", join(dir, "session")];
+    const child = spawn(command, args, {
+      cwd: dir,
+      env: runEnvironment(baseEnv, env),
+      stdio: ["ignore", "pipe", "pipe"],
+      // Its own process group, so stopping it also stops the Pi it starts.
+      detached: process.platform !== "win32",
+    });
+    const run = {
+      id, case: caseId, prompt, repository: relative(cwd, repo) || ".", cwd, dir, child,
+      started: Date.now(), budgetMs: budgetMinutes * 60_000,
+      reader: createRunReader(), stderr: "", exit: undefined, waiters: new Set(),
+    };
+    runs.set(id, run);
+    const events = createWriteStream(join(dir, "events.jsonl"));
+    child.stdout.setEncoding("utf8");
+    child.stdout.on("data", (chunk) => {
+      for (const line of run.reader.feed(chunk)) events.write(`${line}\n`);
+    });
+    child.stderr.setEncoding("utf8");
+    child.stderr.on("data", (chunk) => {
+      run.stderr = (run.stderr + chunk).slice(-20_000);
+    });
+    const finish = (exit) => {
+      if (run.exit) return;
+      run.exit = exit;
+      clearInterval(run.watch);
+      events.end();
+      writeFileSync(join(dir, "stderr.log"), run.stderr);
+      save(run);
+      for (const wake of run.waiters) wake();
+    };
+    child.on("error", (err) => {
+      run.stderr += `\n${err.message}`;
+      finish({ code: 127, signal: null });
+    });
+    child.on("close", (code, signal) => finish({ code, signal }));
+    run.watch = setInterval(() => {
+      const { problem, verdict } = status(run);
+      if (STOPS.has(problem)) stop(run, verdict, problem);
+      for (const wake of run.waiters) wake();
+    }, watchMs);
+    run.watch.unref?.();
+    save(run);
+    return run;
+  }
+
+  async function wait(run, seconds, signal) {
+    const until = Date.now() + Math.min(Math.max(seconds, 0), MAX_WAIT_SECONDS) * 1000;
+    while (!run.exit && Date.now() < until && !signal?.aborted) {
+      const { problem, verdict } = status(run);
+      // A run that must stop is stopped now, and the wait goes on until it has; a loop is the caller's call.
+      if (STOPS.has(problem)) stop(run, verdict, problem);
+      else if (problem) break;
+      await new Promise((done) => {
+        const timer = setTimeout(finish, Math.min(5_000, until - Date.now()));
+        function finish() {
+          clearTimeout(timer);
+          run.waiters.delete(finish);
+          signal?.removeEventListener?.("abort", finish);
+          done();
+        }
+        run.waiters.add(finish);
+        signal?.addEventListener?.("abort", finish, { once: true });
+      });
+    }
+  }
+
+  // When the Operator session ends, nothing it started may outlive it: SIGTERM every run, give them a moment,
+  // then SIGKILL every run's group, finished or not, before returning.
+  async function stopAll() {
+    const all = [...runs.values()];
+    for (const run of all) stop(run, "the Operator session ended", "session-ended");
+    const open = all.filter((run) => !run.exit);
+    if (open.length) {
+      await Promise.race([
+        Promise.all(open.map((run) => new Promise((done) => (run.exit ? done() : run.child.once("close", done))))),
+        new Promise((done) => setTimeout(done, shutdownGraceMs)),
+      ]);
+    }
+    for (const run of all) kill(run, "SIGKILL");
+  }
+
+  return { runs, start, status, stop, wait, stopAll };
+}
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@introspection-ai/operator",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "The Introspection Operator: a Recipe and skills that build an agent with its owner (brainstorm, draft and review).",
   "license": "Apache-2.0",
   "repository": {
@@ -19,12 +19,18 @@
     "skills",
     "agents",
     "SYSTEM.md",
-    "bin"
+    "bin",
+    "extensions",
+    "python/pyproject.toml",
+    "python/uv.lock"
   ],
   "publishConfig": {
     "access": "public"
   },
   "pi": {
+    "extensions": [
+      "extensions/case-runs"
+    ],
     "documents": [
       {
         "format": "docx"
@@ -32,7 +38,20 @@
       {
         "format": "pdf"
       }
-    ]
+    ],
+    "runtime": {
+      "python": {
+        "project": "python",
+        "lockfile": "python/uv.lock",
+        "version": ">=3.12,<3.15",
+        "imports": [
+          "docx",
+          "pypdf",
+          "pypdfium2",
+          "PIL"
+        ]
+      }
+    }
   },
   "type": "module",
   "scripts": {

package/python/pyproject.toml

@@ -0,0 +1,17 @@
+# The Python the Recipe's `documents` tool runs on: paper-docx for Word, and pypdf, pypdfium2 and pillow for
+# PDF. Declared in package.json#pi.runtime.python; the launcher builds it with `uv sync --frozen`.
+[project]
+name = "introspection-operator-runtime"
+version = "0.0.0"
+requires-python = ">=3.12,<3.15"
+dependencies = [
+  "paper-docx==0.2.0",
+  "pypdf[crypto]==6.21.4",
+  "pypdfium2==5.14.0",
+  "pillow==13.0.0",
+]
+
+[tool.uv]
+package = false
+# paper-docx provides the `docx` module; python-docx would shadow it.
+constraint-dependencies = ["python-docx<0"]