@introspection-ai/operator 0.1.0 → 0.1.1

package/README.md

@@ -9,19 +9,29 @@ The Operator is the agent that builds, deploys and improves other agents (Recipe
 | `evals/` | The evals that measure each loop (to come) |
 | `docs/` | [`DESIGN.md`](docs/DESIGN.md): what the Operator is being rebuilt to, and the decisions still open |
 
-## Run build locally
+## Run build
+
+You need Node 24 and credentials for the model in `agents/build.yaml` (sign in once with `/login` in Pi).
 
 ```sh
-pnpm build                                       # a new agent, in ~/.introspection/agents/new-<n>
-pnpm build ~/.introspection/agents/new-1         # resume that build
-pnpm build ~/work/my-agent --model <model>       # another folder; flags after it go to Pi
+npm i -g @introspection-ai/cli && introspection setup   # once: Pi and the Recipes release it needs
+npx @introspection-ai/operator                          # a new agent, in ~/.introspection/agents/new-<n>
+npx @introspection-ai/operator ~/work/my-agent          # start or resume a build in that folder
+npx @introspection-ai/operator ~/work/my-agent --model <model>   # flags after the folder go to Pi
 ```
 
-`scripts/build.sh` starts the build agent (`pi --recipe <this repo> --agent build --no-context-files`) in a folder of its own, because build treats the folder it starts in as the owner's workspace: it creates the agent's repository there and resumes from what it finds there. It turns off Pi's loading of AGENTS.md and CLAUDE.md from that folder and the folders above it, which are written for coding agents and can describe other agents build must not copy. It refuses a folder inside this repository or nested in another git repository, installs this repository's dependencies with pnpm once, and checks that Pi's `@introspection-ai/recipes` satisfies the `peerDependencies` range, printing the `pi install` command to run when it doesn't. Set `INTROSPECTION_AGENTS_DIR` to put new builds somewhere other than `~/.introspection/agents`. You need Pi and the `introspection` CLI (`npm i -g @introspection-ai/cli`), and credentials for the model in `agents/build.yaml`.
+`npx @introspection-ai/operator` runs the package's launcher, `bin/introspection-operator.js`. It starts the build agent (`pi --recipe <the package> --agent build --no-context-files`) in a folder of its own, because build treats the folder it starts in as the owner's workspace: it creates the agent's repository there and resumes from what it finds there.
+- **No AGENTS.md or CLAUDE.md:** it turns off Pi's loading of those files from that folder and the folders above it. They're written for coding agents and can describe other agents, which build must not copy.
+- **Folder safety:** it refuses a folder inside the package or nested in another git repository; the agent's own repository is allowed, to resume.
+- **Versions:** it checks that Pi's `@introspection-ai/recipes` satisfies the `peerDependencies` range, and says to run `introspection upgrade` when it doesn't.
+
+Set `INTROSPECTION_AGENTS_DIR` to put new builds somewhere other than `~/.introspection/agents`.
+
+In a checkout of this repository, `pnpm build` runs the same launcher, and installs the dependencies with pnpm once.
 
 ## Package
 
-`@introspection-ai/operator` is the npm package published from this repository's root. It contains the Recipe a person runs (`SYSTEM.md`, `agents/` and `skills/`), so `pi install npm:@introspection-ai/operator` then `pi --recipe @introspection-ai/operator --agent build` starts a build, and `npx skills sync` finds the skills in it. `docs/`, `scripts/` and the evals are never published.
+`@introspection-ai/operator` is the npm package published from this repository's root. It contains the Recipe a person runs (`SYSTEM.md`, `agents/` and `skills/`) and its launcher (`bin/`), so `npx @introspection-ai/operator` starts a build, and `npx skills sync` finds the skills in it. `docs/`, `scripts/` and the evals are never published.
 
 Skills are grouped by the stage of an agent's life (see [`docs/DESIGN.md`](docs/DESIGN.md)), and the group is the prefix of each skill's name, because `npx skills sync` finds skills only at `skills/<name>/SKILL.md` and not in nested folders:
 
@@ -33,8 +43,8 @@ Skills are grouped by the stage of an agent's life (see [`docs/DESIGN.md`](docs/
 | `optimize` | `optimize-quality`, `optimize-cost`, `optimize-latency` | Raise quality, then cut cost, then latency, each holding the gains of the one before | Designed; replaces today's `optimize` |
 | `harden` | `harden-scan`, `harden-spar`, `harden-stress` | Last, and optional apart from the scan: check the Recipe against the OWASP Agentic Skills Top 10, spar with it as a red team, and test it under load; failures become permanent cases | Designed; new, with no workflow behind it today |
 
-Releases are cut by release-please (`.github/workflows/release.yml`): Conventional Commit titles on `main` update a release pull request, and merging it tags `operator-vX.Y.Z` and publishes to npm through trusted publishing, starting at 0.1.0. CI runs `node scripts/check-skills.mjs` (frontmatter, folder names, and that exactly the Recipe is packed: `skills/`, `agents/` and `SYSTEM.md`) and `npm pack --dry-run`; publishing also requires at least one skill.
+Releases are cut by release-please (`.github/workflows/release.yml`): Conventional Commit titles on `main` update a release pull request, and merging it tags `operator-vX.Y.Z` and publishes to npm through trusted publishing, starting at 0.1.0. CI runs `node scripts/check-skills.mjs` (frontmatter, folder names, and that exactly the Recipe and its launcher are packed: `skills/`, `agents/`, `SYSTEM.md` and `bin/introspection-operator.js`) and `npm pack --dry-run`; publishing also requires at least one skill.
 
 ## License
 
-What `@introspection-ai/operator` publishes (`SYSTEM.md`, `agents/` and `skills/`) is licensed under the Apache License 2.0; see [`skills/LICENSE`](skills/LICENSE). Everything else in this repository is proprietary to Introspection and not licensed for use outside it.
+What `@introspection-ai/operator` publishes (`SYSTEM.md`, `agents/`, `skills/` and `bin/`) is licensed under the Apache License 2.0; see [`skills/LICENSE`](skills/LICENSE). Everything else in this repository is proprietary to Introspection and not licensed for use outside it.

package/bin/introspection-operator.js

@@ -0,0 +1,118 @@
+#!/usr/bin/env node
+// Start the Operator's build agent in a folder of its own.
+//
+//   npx @introspection-ai/operator                       new build in ~/.introspection/agents/new-<n>
+//   npx @introspection-ai/operator <folder>              start, or resume, a build in <folder>
+//   npx @introspection-ai/operator [<folder>] <pi flags> pass flags such as --model on to Pi
+//
+// In a checkout of this repository, `pnpm build` runs this same script.
+//
+// Build treats the folder it starts in as the owner's workspace: it creates the agent's repository
+// there and resumes from what it finds, so it must not start inside this package or another repository.
+import { execFileSync, spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, realpathSync } from "node:fs";
+import { homedir } from "node:os";
+import { delimiter, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const pkg = JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
+const agentsDir = process.env.INTROSPECTION_AGENTS_DIR || join(homedir(), ".introspection", "agents");
+const piDir = process.env.PI_CODING_AGENT_DIR || join(homedir(), ".pi", "agent");
+
+function fail(message) {
+  console.error(`introspection-operator: ${message}`);
+  process.exit(1);
+}
+
+let args = process.argv.slice(2);
+if (args[0] === "--help" || args[0] === "-h") {
+  console.log(readFileSync(fileURLToPath(import.meta.url), "utf8").split("\n").slice(1, 8).map((l) => l.replace(/^\/\/ ?/, "")).join("\n"));
+  process.exit(0);
+}
+if (args[0] === "--") args = args.slice(1); // pnpm passes a separating `--` through
+
+// A package manager puts this package's node_modules/.bin first on PATH, and the Recipes package installs
+// its own Pi there, one without the Recipe extension. Use the Pi the owner installed.
+const ownBin = join(root, "node_modules", ".bin");
+const path = (process.env.PATH || "").split(delimiter).filter((dir) => resolve(dir) !== ownBin).join(delimiter);
+const env = { ...process.env, PATH: path };
+const has = (cmd) => spawnSync(cmd, ["--version"], { env, stdio: "ignore", shell: process.platform === "win32" }).status === 0;
+if (!has("pi")) fail("Pi is not installed. Run: npm i -g @introspection-ai/cli && introspection setup");
+
+// The Recipe's own dependencies (the documents tool) load from this package by Node's resolution, which
+// also finds them where npx and npm hoist them, beside the package. A fresh checkout installs them once.
+// Search node_modules folders upward from the package, as Node does; resolving `<name>/package.json`
+// would fail for a package whose exports don't list it.
+const resolvable = (name) => {
+  for (let dir = root; ; dir = dirname(dir)) {
+    if (existsSync(join(dir, "node_modules", name, "package.json"))) return true;
+    if (dirname(dir) === dir) return false;
+  }
+};
+if (!Object.keys(pkg.dependencies ?? {}).every(resolvable)) {
+  if (!existsSync(join(root, "pnpm-lock.yaml"))) fail(`can't find the Operator's dependencies from ${root}; install it with npm or npx`);
+  console.error("introspection-operator: installing the Operator's dependencies (once)");
+  execFileSync("pnpm", ["install", "--frozen-lockfile", "--reporter=silent"], { cwd: root, env, stdio: "inherit", shell: process.platform === "win32" });
+}
+
+// Pi loads the Recipe through its own copy of @introspection-ai/recipes, which must satisfy the peer range.
+const range = pkg.peerDependencies?.["@introspection-ai/recipes"] ?? "";
+const min = /^>=\s*(\d+\.\d+\.\d+)/.exec(range)?.[1];
+const piRecipes = join(piDir, "npm", "node_modules", "@introspection-ai", "recipes", "package.json");
+if (min) {
+  if (!existsSync(piRecipes)) fail("Pi has no @introspection-ai/recipes package. Run: introspection setup");
+  const have = JSON.parse(readFileSync(piRecipes, "utf8")).version;
+  const num = (v) => v.split(/[.-]/).slice(0, 3).map(Number);
+  const [a, b] = [num(have), num(min)];
+  if ((a[0] - b[0] || a[1] - b[1] || a[2] - b[2]) < 0) {
+    fail(`Pi uses @introspection-ai/recipes ${have}; the Operator needs ${range}. Run: introspection upgrade`);
+  }
+}
+
+// The folder: the first argument when it isn't a flag, else the next new-<n>. A relative folder resolves
+// from where the command was typed (pnpm runs scripts from the package root, so INIT_CWD first).
+const typedFrom = process.env.INIT_CWD || process.cwd();
+let target;
+if (args.length > 0 && !args[0].startsWith("-")) {
+  target = resolve(typedFrom, args.shift());
+} else {
+  let n = 1;
+  while (existsSync(join(agentsDir, `new-${n}`))) n++;
+  target = join(agentsDir, `new-${n}`);
+}
+
+// Check the folder before creating anything, from its nearest existing parent.
+let existing = target;
+while (!existsSync(existing)) existing = dirname(existing);
+existing = realpathSync(existing);
+const inside = (parent, child) => {
+  const rel = relative(parent, child);
+  return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
+};
+if (inside(realpathSync(root), existing)) fail(`${target} is inside the Operator package; choose a folder outside it`);
+// A folder inside another repository would nest the agent's repository there. The agent's own repository
+// is fine: that's how a build resumes.
+let top;
+try {
+  top = execFileSync("git", ["-C", existing, "rev-parse", "--show-toplevel"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+} catch {}
+if (top) {
+  top = realpathSync(top);
+  if (!existsSync(target) || realpathSync(target) !== top) {
+    fail(`${target} is inside the git repository ${top}; choose a folder outside it, or the agent's own repository to resume`);
+  }
+}
+
+mkdirSync(target, { recursive: true });
+target = realpathSync(target);
+console.error(`introspection-operator: starting in ${target}`);
+// Pi would load AGENTS.md and CLAUDE.md from this folder and every folder above it. Those are written for
+// coding agents and can describe other agents, which build must not copy; the Recipe brings its own.
+const result = spawnSync("pi", ["--recipe", root, "--agent", "build", "--no-context-files", ...args], {
+  cwd: target,
+  env,
+  stdio: "inherit",
+  shell: process.platform === "win32",
+});
+process.exit(result.status ?? 1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@introspection-ai/operator",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "The Introspection Operator: a Recipe and skills that build an agent with its owner (brainstorm, draft and review).",
   "license": "Apache-2.0",
   "repository": {
@@ -18,7 +18,8 @@
   "files": [
     "skills",
     "agents",
-    "SYSTEM.md"
+    "SYSTEM.md",
+    "bin"
   ],
   "publishConfig": {
     "access": "public"
@@ -35,7 +36,7 @@
   },
   "type": "module",
   "scripts": {
-    "build": "scripts/build.sh"
+    "build": "node bin/introspection-operator.js"
   },
   "peerDependencies": {
     "@introspection-ai/recipes": ">=0.37.0"
@@ -44,5 +45,8 @@
     "@introspection-ai/recipe-documents-docx": ">=0.1.0",
     "@introspection-ai/recipe-documents-pdf": ">=0.1.0"
   },
-  "packageManager": "pnpm@12.9.1"
+  "packageManager": "pnpm@12.9.1",
+  "bin": {
+    "introspection-operator": "bin/introspection-operator.js"
+  }
 }