cheap-agent 0.0.0-stage → 1.0.0

package/dist/login.js

@@ -0,0 +1,223 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { createInterface } from "node:readline/promises";
+import { loadConfig, userConfigFile } from "./config.js";
+import { detectProvider, LOGIN_COMMAND as LOGIN, PROVIDERS, providerLabel as label, redact, savedProviders } from "./credentials.js";
+import { ensureOpencode, opencodeBinary, stopOpencode } from "./opencode.js";
+import { isSupported, UNSUPPORTED_REASON } from "./platform.js";
+import { installPlugin, stableNode } from "./install.js";
+import { fullRoute, modelName, presetOf, PRESET_NAMES, PRESETS } from "./routing.js";
+import { runSession } from "./worker.js";
+/**
+ * `cheapag login`: the only setup (ADR-0004). Picks a provider, lets the bundled OpenCode's own login take the key
+ * (hidden input, saved in OpenCode's store; Cheap Agent never sees it), live-checks it, then offers to register
+ * the server with Claude Code at user scope and install the plugin (ticket 31). `npx cheap-agent` in a terminal runs it too.
+ */
+const { version } = createRequire(import.meta.url)("../package.json");
+const CHECK_TIMEOUT_MS = 90_000;
+const CHOICES = [...PRESET_NAMES, "custom"];
+const isChoice = (s) => CHOICES.includes(s);
+export async function login(args = []) {
+    const out = (line = "") => process.stdout.write(redact(line) + "\n");
+    if (!isSupported()) {
+        out(`✗ ${UNSUPPORTED_REASON}`);
+        return 1;
+    }
+    const flag = args.length === 2 && args[0] === "--preset" ? args[1] : undefined;
+    if (args.length && flag === undefined) {
+        out(`✗ usage: cheapag login [--preset ${CHOICES.join("|")}]`);
+        return 1;
+    }
+    if (flag !== undefined && !isChoice(flag)) {
+        out(`✗ "${flag}" is not a preset; use one of ${CHOICES.join(", ")}; nothing changed`);
+        return 1;
+    }
+    if (!process.stdin.isTTY) {
+        const saved = detectProvider();
+        if (!saved) {
+            out(`✗ ${LOGIN} needs an interactive terminal (the key is typed into a hidden prompt)`);
+            return 1;
+        }
+        // no terminal to type a key into: only the worker models are set, for the provider already logged in (scripts, the benchmark)
+        const choice = flag ?? currentPreset(saved.provider) ?? "balanced";
+        if (!flag)
+            out(`No terminal to ask in: worker models stay ${choice} for ${label(saved.provider)}; pass --preset to choose`);
+        return savePreset(saved.provider, choice, out) ? 0 : 1;
+    }
+    // the live check's OpenCode runs in its own process group; take it down on Ctrl-C too
+    process.on("exit", () => stopOpencode(true));
+    for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"])
+        process.on(signal, () => process.exit(130));
+    out("Cheap Agent login");
+    const current = detectProvider();
+    if (current)
+        out(`Currently using: ${label(current.provider)}. Logging in again replaces or adds a provider.`);
+    PROVIDERS.forEach((p, i) => out(`  ${i + 1}) ${p.label}`));
+    const answer = await ask(`Provider [1-${PROVIDERS.length}]: `);
+    const picked = PROVIDERS[Number(answer) - 1];
+    if (!picked) {
+        out(`✗ "${answer}" is not one of 1-${PROVIDERS.length}; nothing changed`);
+        return 1;
+    }
+    const preset = currentPreset(picked.id) ?? "balanced";
+    const choice = flag ?? ((await ask(`Worker models: cheapest / balanced (recommended) / strongest [${preset}]: `)) || preset);
+    if (!isChoice(choice)) {
+        out(`✗ "${choice}" is not one of ${CHOICES.join(", ")}; nothing changed`);
+        return 1;
+    }
+    // the bundled OpenCode prompts for the key with hidden input and saves it in its own credential store
+    const saved = spawnSync(opencodeBinary(), ["auth", "login", "--provider", picked.id], { stdio: "inherit" });
+    if (saved.status !== 0 || !savedProviders().includes(picked.id)) {
+        out(`✗ ${picked.label} login was not saved; run ${LOGIN} to try again`);
+        return 1;
+    }
+    if (!savePreset(picked.id, choice, out))
+        return 1;
+    const provider = { provider: picked.id, via: "login" };
+    const check = await liveCheck(provider);
+    out(check.ok ? `✓ ${check.line}` : `✗ ${check.line}`);
+    const active = detectProvider();
+    if (active.provider !== provider.provider)
+        out(`Note: ${label(active.provider)} is also saved and is used first.`);
+    if (!check.ok)
+        return 1; // the login stays saved; fix the cause and run login again
+    await register(out);
+    return 0;
+}
+/** The user-level config as written, so saving a preset keeps its other keys; {} when there is none. */
+function readUser() {
+    const file = userConfigFile();
+    if (!existsSync(file))
+        return {};
+    const value = JSON.parse(readFileSync(file, "utf8"));
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        throw new Error("must hold a JSON object");
+    return value;
+}
+/** The preset the user's config holds, when it sets `models` (Enter keeps it); a damaged file counts as none. */
+function currentPreset(provider) {
+    try {
+        const { models } = readUser();
+        return models ? presetOf(provider, models) : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Writes the preset as the user config's `models`, other keys kept; custom writes nothing. */
+function savePreset(provider, choice, out) {
+    const file = userConfigFile();
+    if (choice === "custom") {
+        out(`Worker models: custom, nothing written; set "models" in a repo's cheapag.json, or in ${file} for every repo`);
+        return true;
+    }
+    try {
+        const config = { ...readUser(), models: PRESETS[provider][choice] };
+        mkdirSync(dirname(file), { recursive: true });
+        writeFileSync(file, JSON.stringify(config, null, 2) + "\n");
+    }
+    catch (err) {
+        out(`✗ ${file}: ${err.message}; worker models not saved`);
+        return false;
+    }
+    out(`✓ Worker models: ${choice} (implement ${PRESETS[provider][choice].implement}), saved in ${file}`);
+    return true;
+}
+/** One tiny real call to the implement model the user's config now picks, through the bundled OpenCode, in a throwaway directory. */
+async function liveCheck(provider) {
+    const dir = mkdtempSync(join(tmpdir(), "cheapag-login-"));
+    let name = provider.provider;
+    let timer;
+    try {
+        // the throwaway dir has no cheapag.json, so this is the user's config alone
+        const route = fullRoute(provider.provider, loadConfig(dir).models);
+        const model = route.implement;
+        name = modelName(model);
+        // with the route, OpenCode's config pins this model too (on OpenRouter: data collection denied)
+        const run = ensureOpencode(provider, dir, route).then((opencode) => runSession({
+            opencode,
+            directory: dir,
+            model: { providerID: model.providerID, id: model.id },
+            prompt: "Live check: reply with the single word OK. Do not use any tools.",
+            onEvent: () => { },
+        }));
+        // covers boot as well as the answer; on timeout, stopping OpenCode below ends the session, and login exits
+        const timeout = new Promise((_, reject) => (timer = setTimeout(() => reject(new Error("no answer within 90s")), CHECK_TIMEOUT_MS)));
+        const result = await Promise.race([run, timeout]);
+        if (result.error)
+            return { ok: false, line: explain(result.error, name) };
+        return { ok: true, line: `${name} answered (cost $${result.usage.costUsd.toFixed(4)})` };
+    }
+    catch (err) {
+        return { ok: false, line: explain(err.message, name) };
+    }
+    finally {
+        clearTimeout(timer);
+        stopOpencode();
+        rmSync(dir, { recursive: true, force: true });
+    }
+}
+/** A one-line reason and fix for the common live-check failures. */
+function explain(message, model) {
+    const first = message.split("\n")[0];
+    if (/\b401\b|unauthori[sz]ed|authentication|invalid.*key|api key/i.test(message))
+        return `the key was rejected (${first}); run ${LOGIN} again with the right key`;
+    if (/\b402\b|credit|insufficient|balance|quota/i.test(message))
+        return `the account has no credit (${first}); top it up, then run ${LOGIN} again`;
+    if (/\b404\b|not found|no endpoints|not available/i.test(message))
+        return `${model} is unavailable to this account (${first}); run ${LOGIN} and pick another provider`;
+    return `live check failed: ${first}`;
+}
+/** Offers user-scope registration with Claude Code, then the plugin; prints the commands whenever it does not run them. */
+async function register(out) {
+    const command = serverCommand();
+    const manual = `claude mcp add -s user cheapag -- ${command.map(quote).join(" ")}`;
+    const existing = spawnSync("claude", ["mcp", "get", "cheapag"], { encoding: "utf8" });
+    if (existing.error) {
+        out(`Claude Code's CLI was not found. To add cheapag for all your projects, run:\n  ${manual}`);
+        return;
+    }
+    // only a user-scope entry counts: a local or project one doesn't cover "all your projects"
+    // shortcut: an existing user-scope entry is kept even if it points at an older install; re-register by hand after moving it
+    if (existing.status === 0 && /Scope:\s*User/i.test(existing.stdout)) {
+        out("✓ cheapag is already registered with Claude Code");
+        finish(out, installPlugin(out));
+        return;
+    }
+    if (/^n/i.test(await ask("Add cheapag to Claude Code for all your projects? [Y/n] "))) {
+        out(`Not registered. To add it later, run:\n  ${manual}`);
+        return;
+    }
+    const added = spawnSync("claude", ["mcp", "add", "-s", "user", "cheapag", "--", ...command], { encoding: "utf8" });
+    if (added.status !== 0) {
+        out(`✗ claude mcp add failed (${(added.stderr || added.stdout).trim().split("\n")[0]}). Run it yourself:\n  ${manual}`);
+        return;
+    }
+    out("✓ Added cheapag to Claude Code for all your projects");
+    finish(out, installPlugin(out));
+}
+/** The last thing setup says: how to start. */
+function finish(out, plugin) {
+    out(plugin
+        ? "\nDone. Open a new Claude Code session in your project and run /cheapag:allow once there; then ask for changes as usual."
+        : "\nThe server is set up; add the plugin with the commands above, then open a new Claude Code session.");
+}
+/** How Claude Code should start this installed package: npx when run from npx's cache, else this exact file. */
+function serverCommand() {
+    const entry = realpathSync(process.argv[1]);
+    return entry.includes("/_npx/") ? ["npx", "-y", `cheap-agent@${version}`] : [stableNode(), entry];
+}
+const quote = (arg) => (/^[\w@%+=:,./-]+$/.test(arg) ? arg : `'${arg.replace(/'/g, `'\\''`)}'`);
+/** One question on a fresh readline, closed before anything else (OpenCode's login) reads the terminal. */
+async function ask(question) {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        return (await rl.question(question)).trim();
+    }
+    finally {
+        rl.close();
+    }
+}

package/dist/opencode.js

@@ -0,0 +1,258 @@
+import { spawn } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { arch } from "node:os";
+import { dirname, join } from "node:path";
+import { baselinePermission } from "./permissions.js";
+import { killProcessGroup, opencodePlatform } from "./platform.js";
+import { fullRoute, modelName, routeModels } from "./routing.js";
+const require = createRequire(import.meta.url);
+export const OPENCODE_PIN = require("opencode-ai/package.json").version;
+/**
+ * The binary comes from opencode-ai's platform package, never PATH. We skip opencode-ai/bin because
+ * its postinstall (which fills it in) does not run under pnpm or npm's install-scripts gate.
+ * shortcut: takes the first installed variant, not the avx2/musl-aware pick postinstall makes; mirror it if x64 baseline users report crashes.
+ */
+export function opencodeBinary() {
+    const { os, binary } = opencodePlatform();
+    const base = `opencode-${os}-${arch()}`;
+    const fromPkg = createRequire(require.resolve("opencode-ai/package.json"));
+    for (const name of [base, `${base}-baseline`, `${base}-musl`, `${base}-baseline-musl`]) {
+        try {
+            const bin = join(dirname(fromPkg.resolve(`${name}/package.json`)), "bin", binary);
+            if (existsSync(bin))
+                return bin;
+        }
+        catch {
+            // variant not installed for this platform
+        }
+    }
+    throw new Error(`no OpenCode binary installed for ${base}; reinstall cheap-agent`);
+}
+const WORKER_PROMPT = `---
+description: Cheap Agent worker. Implements plan steps in an isolated git worktree.
+mode: primary
+---
+You implement the plan step marked >>> CURRENT STEP(S), in this repository, by editing files yourself.
+- Stay within the step's files: and make precise edits. If you must edit anything else, report it under risks.
+- Never install packages or run install commands. If the step needs a package that is not installed, ask with the question tool, worded exactly: step needs package <name>@<range> (not installed). Install it in the main checkout, then reply "installed", or reply "no" to proceed without. Options: installed, no.
+- Never touch .git, .env* files or lockfiles. Never commit.
+- If the step is ambiguous or conflicts with its dont:, ask with the question tool instead of guessing.
+- When a Source section is given (the user's request or the issue, verbatim), the step is someone's reading of it: check the step against the source before you start. Implement the step as written, but name every point where they disagree (a direction, an order, a value, an approach the source prefers) in finish's disagree. When the source names a preferred approach or links a fix, implement that one and say so in summary.
+- If the step fixes a bug or a wrong behaviour, prove it: first write a small test that reproduces the problem and run it to see it fail, then fix the code and run it again to see it pass. Write the test first, before reading widely. When the step names the exact change (the file and the code), make that change first, then write the test. Keep the test in the change, and run it with the same command the step's checks use (e.g. its test runner plus the test file or id).
+- The reproduction test asserts the exact values, order and types the source or step states or implies. "Does not crash" or "contains X" is not enough when the expected value is known.
+- When done, call the finish tool exactly once, last: summary (at most 160 chars), risks, review (path:start-end, max 5), missing, repro (the command that runs your reproduction test, "none: <why>" if you could not reproduce it, "n/a" if the step is not a fix), disagree (where the step and the source disagree, or "none").
+- If you cannot call finish, end your last message with a fenced cheapag-result block holding the same fields.
+`;
+// The research worker reports in its final text, not a custom tool: its ruleset stays exactly read, glob, grep, list
+const RESEARCH_PROMPT = `---
+description: Cheap Agent research worker. Answers questions about this repository, read-only.
+mode: primary
+---
+You answer one question about the code in this repository. You are read-only: you can read, grep, glob and list, nothing else (no edits, no commands, no questions, no web).
+- Answer from the code itself, never from memory. Cite what you state as path:line or path:start-end, paths relative to the repository root.
+- Stay within the scope and the word limit you are given.
+- End your last message with exactly one fenced block:
+\`\`\`cheapag-research
+status: answer (or unsure, if the code does not settle the question)
+confidence: high (seen directly in code) | medium (inferred) | low (a guess)
+refs: src/a.ts:18-42, src/b.ts:31
+answer:
+<your answer, in prose, within the word limit>
+\`\`\`
+`;
+// Runs inside OpenCode (Bun). Its input is captured from the event stream, so it only has to exist and validate.
+export const FINISH_TOOL_SOURCE = `import { tool } from "@opencode-ai/plugin";
+
+export default tool({
+  description: "Report the step as done. Call exactly once, as your last action.",
+  args: {
+    summary: tool.schema.string().max(160).describe("What you did, at most 160 characters"),
+    risks: tool.schema.array(tool.schema.string()).describe("Assumptions, unverified conditions, edits outside files:"),
+    review: tool.schema.array(tool.schema.string()).max(5).describe("Ranges worth a human look, as path:start-end"),
+    missing: tool.schema.array(tool.schema.string()).describe("Anything the step asked for that you did not do"),
+    repro: tool.schema.string().describe("The exact command that runs your reproduction test (fails on the original code, passes now); 'none: <why>' if you could not reproduce the problem; 'n/a' if the step is not a fix"),
+    disagree: tool.schema.string().describe("Where the step's spec and the Source you were given disagree (direction, order, value, approach), or 'none'"),
+  },
+  async execute() {
+    return "Reported. Stop now.";
+  },
+});
+`;
+/**
+ * Runs inside OpenCode (Bun), for every session: grep returns matching lines, and the read deny on .env* does not
+ * cover it (proven on 1.19, even with an explicit include: ".env*"), so .env* match blocks are cut from grep output
+ * before the model sees them. .env.example and .env.sample stay visible. Glob and list only return names.
+ */
+export const SECRETS_PLUGIN = `const SECRET = /(^|[\\\\/])\\.env(?!\\.(example|sample)$)[^\\\\/]*$/;
+
+export const CheapagSecrets = async () => ({
+  "tool.execute.after": async (input, output) => {
+    if (input.tool !== "grep" || typeof output.output !== "string") return;
+    let file = "";
+    let hidden = 0;
+    const kept = [];
+    for (const line of output.output.split("\\n")) {
+      const header = line.match(/^(\\S.*):$/);
+      if (header) file = header[1];
+      else if (line === "") file = "";
+      if (SECRET.test(file)) {
+        if (header) hidden++;
+        continue;
+      }
+      kept.push(line);
+    }
+    if (hidden) output.output = kept.join("\\n") + "\\n(" + hidden + " .env file(s) hidden by cheapag)";
+  },
+});
+`;
+/** Cheap Agent's own OpenCode config dir: worker and research agents, finish tool, secrets plugin, model pins and options. */
+export function writeConfigDir(dir, config) {
+    mkdirSync(join(dir, "agents"), { recursive: true });
+    mkdirSync(join(dir, "tools"), { recursive: true });
+    mkdirSync(join(dir, "plugins"), { recursive: true });
+    writeFileSync(join(dir, "agents", "cheapag-worker.md"), WORKER_PROMPT);
+    writeFileSync(join(dir, "agents", "cheapag-research.md"), RESEARCH_PROMPT);
+    writeFileSync(join(dir, "tools", "finish.ts"), FINISH_TOOL_SOURCE);
+    writeFileSync(join(dir, "plugins", "cheapag-secrets.js"), SECRETS_PLUGIN);
+    writeFileSync(join(dir, "opencode.json"), config);
+}
+/** The generated opencode.json for the route's models: their options (e.g. OpenRouter routing) and the small model. */
+function opencodeConfig(provider, route) {
+    // the key itself stays in OpenCode's own credential store; the config never names one
+    const models = Object.fromEntries(routeModels(route).filter((m) => m.options).map((m) => [m.id, { options: m.options }]));
+    const providerConfig = Object.keys(models).length ? { models } : {};
+    const config = {
+        $schema: "https://opencode.ai/config.json",
+        // OpenCode otherwise sends title generation to its own default small model, i.e. another provider the user never chose;
+        // the route's implement model is always an allowlisted one
+        small_model: modelName(route.implement),
+        provider: Object.keys(providerConfig).length ? { [provider.provider]: providerConfig } : {},
+    };
+    return JSON.stringify(config, null, 2) + "\n";
+}
+let started;
+let child;
+/** The config the running server was booted with. */
+let booted;
+/**
+ * Starts (once per process, until stopOpencode) or attaches to the OpenCode server and checks it runs the pinned version.
+ * Its generated config lives in `<projectDir>/.cheapag/opencode/`; projectDir only matters on the call that boots.
+ * `route` is a job's allowlisted models; OpenCode reads their options only at boot, so a job whose config differs reboots it.
+ * Without one (ping, login) any running server will do.
+ */
+let holds = 0;
+/** Marks the server in use for a job's or research call's lifetime, so a config change never reboots it under them. Returns the release. */
+export function holdOpencode() {
+    holds++;
+    let held = true;
+    return () => {
+        if (held)
+            holds--;
+        held = false;
+    };
+}
+export function ensureOpencode(provider, projectDir = process.cwd(), route) {
+    const config = opencodeConfig(provider, route ?? fullRoute(provider.provider));
+    if (started && route && booted !== config) {
+        // a reboot would kill every live session: refuse it while any job or research call holds the server
+        // shortcut: one server per config would let both run; worth it only if config changes mid-session become common
+        if (holds > 0)
+            return Promise.reject(new Error("the model configuration changed (consent or cheapag.json models) while jobs are running; retry once they finish"));
+        stopOpencode();
+    }
+    if (!started)
+        booted = config;
+    started ??= boot(projectDir, config).catch((err) => {
+        stopOpencode();
+        started = undefined;
+        throw err;
+    });
+    return started;
+}
+async function boot(projectDir, config) {
+    const configDir = join(projectDir, ".cheapag", "opencode");
+    writeConfigDir(configDir, config);
+    const external = process.env.CHEAPAG_OPENCODE_URL;
+    const password = (external && process.env.CHEAPAG_OPENCODE_PASSWORD) || randomBytes(24).toString("base64url");
+    const url = external || (await spawnServer(configDir, password));
+    const res = await fetch(new URL("/global/health", url), {
+        headers: { authorization: `Basic ${Buffer.from(`opencode:${password}`).toString("base64")}` },
+        signal: AbortSignal.timeout(5_000),
+    });
+    if (!res.ok)
+        throw new Error(`opencode health check at ${url} answered ${res.status}`);
+    const { version } = (await res.json());
+    if (version !== OPENCODE_PIN) {
+        throw new Error(`opencode version ${version}, expected ${OPENCODE_PIN}; reinstall cheap-agent`);
+    }
+    return { url, password, version };
+}
+function spawnServer(configDir, password) {
+    return new Promise((resolve, reject) => {
+        // detached: its own process group, so stopOpencode() also takes down anything it spawned
+        const proc = spawn(opencodeBinary(), ["serve", "--hostname", "127.0.0.1", "--port", "0"], {
+            detached: true,
+            stdio: ["ignore", "pipe", "pipe"],
+            env: {
+                ...process.env,
+                OPENCODE_SERVER_PASSWORD: password,
+                OPENCODE_CONFIG_DIR: configDir,
+                OPENCODE_DISABLE_PROJECT_CONFIG: "1",
+                // the server-wide baseline; each worker session also carries the full ruleset, which wins (src/permissions.ts)
+                OPENCODE_PERMISSION: JSON.stringify(baselinePermission()),
+            },
+        });
+        child = proc;
+        let output = "";
+        let listening = false;
+        const timer = setTimeout(() => fail(new Error("opencode serve did not start within 15s")), 15_000);
+        const fail = (err) => {
+            clearTimeout(timer);
+            stopOpencode();
+            reject(err);
+        };
+        // keep draining both pipes for the server's lifetime (a full pipe blocks it), but only buffer until it listens
+        proc.stderr.on("data", (chunk) => listening || (output += chunk));
+        proc.stdout.on("data", (chunk) => {
+            if (listening)
+                return;
+            output += chunk;
+            const match = output.match(/opencode server listening on (http:\/\/\S+)/);
+            if (match) {
+                listening = true;
+                clearTimeout(timer);
+                resolve(match[1]);
+            }
+        });
+        proc.on("error", fail);
+        proc.on("exit", (code) => {
+            if (listening) {
+                // a crash after startup: forget the dead server so the next call boots a fresh one. An old server exiting
+                // after a reboot is not this boot's failure: it must never stop the server that replaced it.
+                if (child === proc)
+                    started = child = undefined;
+            }
+            else
+                fail(new Error(`opencode serve exited (${code}): ${output.trim().slice(-500)}`));
+        });
+    });
+}
+/**
+ * Stops the OpenCode server's whole process group. Seen on 1.19.0: a SIGTERM shortly after boot, while it is still
+ * busy, can be ignored for good, so a SIGKILL follows if it is still there after a grace period. On process exit
+ * (`exiting`) there is no later: it is killed outright (its SQLite WAL survives that).
+ */
+export function stopOpencode(exiting = false) {
+    started = undefined; // the next ensureOpencode boots afresh
+    const proc = child;
+    child = undefined;
+    if (proc?.exitCode !== null || !proc.pid)
+        return;
+    if (exiting)
+        return killProcessGroup(proc.pid, "SIGKILL");
+    killProcessGroup(proc.pid);
+    setTimeout(() => proc.exitCode === null && killProcessGroup(proc.pid, "SIGKILL"), STOP_GRACE_MS).unref();
+}
+const STOP_GRACE_MS = 3_000;

package/dist/permissions.js

@@ -0,0 +1,122 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+const PACKAGE_MANAGERS = ["npm", "pnpm", "yarn", "bun"];
+/** Commands no project script or config may allow: always the last rules, so they always win. */
+export const HARD_DENY = [
+    ...PACKAGE_MANAGERS.flatMap((pm) => [`${pm} install*`, `${pm} i`, `${pm} i *`, `${pm} add*`, `${pm} ci*`]),
+    "pip install*", "pip3 install*", "python -m pip install*", "python3 -m pip install*", "uv add*", "uv pip install*",
+    "go get*", "go install*", "cargo add*", "cargo install*", "brew *",
+    ...["commit", "push", "reset", "checkout", "switch", "rebase", "merge", "stash", "clean"].map((verb) => `git ${verb}*`),
+    "rm -rf*", "rm -fr*", "sudo*", "curl*", "wget*", "ssh*", "scp*", "npm publish*", "chmod -R*",
+    // seen bypassing allowed prefixes against the real OpenCode: writes past the edit rules, or arbitrary programs
+    "*>*", "git *--output*", "git *--ext-diff*", "go test*-exec*", "go test*-toolexec*", "cargo test*--config*",
+    "npm exec*", "pnpm dlx*", "yarn dlx*", "bunx*",
+];
+const LOCKFILES = [
+    "package-lock.json", "npm-shrinkwrap.json", "pnpm-lock.yaml", "yarn.lock", "bun.lock", "bun.lockb",
+    "Cargo.lock", "poetry.lock", "uv.lock", "Pipfile.lock", "Gemfile.lock", "composer.lock", "go.sum",
+];
+/** Paths the worker may never edit: git internals, Cheap Agent state, env files, lockfiles. */
+export const PROTECTED = [
+    ".git", ".git/**", "**/.git", "**/.git/**", ".cheapag/**", ".env*", "**/.env*",
+    // the worker must not loosen its own (or a later job's) rules
+    "cheapag.json",
+    ...LOCKFILES.flatMap((f) => [f, `**/${f}`]),
+];
+/** Always-allowed commands, each as typed and with arguments: read-only git and the common test runners. */
+const ALWAYS = ["git status", "git diff", "git log", "git show", "pytest", "python -m pytest", "python3 -m pytest", "go test", "cargo test", "bun test"];
+const allow = (permission, pattern = "*") => ({ permission, pattern, action: "allow" });
+const deny = (permission, pattern = "*") => ({ permission, pattern, action: "deny" });
+/** A command allowed as typed, and with any arguments after it. */
+const command = (cmd) => [allow("bash", cmd), allow("bash", `${cmd} *`)];
+/** Secrets: OpenCode's default does not cover .env reads under these rulesets; examples stay readable (last match wins). */
+const ENV_READS = [
+    ...[".env*", "**/.env*"].map((p) => deny("read", p)),
+    ...[".env.example", "**/.env.example", ".env.sample", "**/.env.sample"].map((p) => allow("read", p)),
+];
+/**
+ * The full ruleset for one worker session: catch-all deny first, then explicit allows and denies for every key,
+ * then the hard denylist. `scripts` and `allowCommands` are allowed with any arguments; `exact` only as written
+ * (make targets, the step's done-when checks); `linked` are dependency dirs in the worktree (readable, never editable).
+ */
+export function workerRuleset(opts = {}) {
+    return [
+        deny("*"),
+        // `finish` is Cheap Agent's own tool (tools/finish.ts): custom tools are permission-checked by name, so the
+        // catch-all would otherwise hide it from the worker
+        ...["read", "glob", "grep", "list", "lsp", "todowrite", "question", "finish"].map((p) => allow(p)),
+        ...ENV_READS,
+        ...["external_directory", "webfetch", "websearch", "task", "skill", "doom_loop"].map((p) => deny(p)),
+        allow("edit"),
+        ...PROTECTED.map((p) => deny("edit", p)),
+        ...(opts.linked ?? []).flatMap((d) => [deny("edit", d), deny("edit", `${d}/**`)]),
+        deny("bash"),
+        ...[...ALWAYS, ...(opts.scripts ?? []), ...(opts.allowCommands ?? [])].flatMap(command),
+        ...(opts.exact ?? []).map((c) => allow("bash", c)),
+        ...HARD_DENY.map((p) => deny("bash", p)),
+    ];
+}
+/**
+ * The research worker's ruleset (spec E1, research; ticket 23.4): read, search, and run the same test commands as the
+ * implementation worker (to reproduce a failure it is asked about), never edit. It runs in a throwaway worktree (src/research.ts),
+ * so a command that writes files cannot touch the developer's tree. Env files are unreadable; outside the repo is denied.
+ */
+export function researchRuleset(opts = {}) {
+    return [
+        deny("*"),
+        ...["read", "glob", "grep", "list"].map((p) => allow(p)),
+        ...ENV_READS,
+        ...["edit", "question", "lsp", "todowrite", "finish", "external_directory", "webfetch", "websearch", "task", "skill", "doom_loop"].map((p) => deny(p)),
+        deny("bash"),
+        ...[...ALWAYS, ...(opts.scripts ?? []), ...(opts.allowCommands ?? [])].flatMap(command),
+        ...(opts.exact ?? []).map((c) => allow("bash", c)),
+        ...HARD_DENY.map((p) => deny("bash", p)),
+    ];
+}
+/** The same static rules in OpenCode's config form, for the server-wide `OPENCODE_PERMISSION` baseline. */
+export function baselinePermission() {
+    const config = {};
+    for (const rule of workerRuleset()) {
+        if (rule.pattern === "*" && !(rule.permission in config))
+            config[rule.permission] = rule.action;
+        else {
+            const current = config[rule.permission];
+            config[rule.permission] = { ...(typeof current === "string" ? { "*": current } : current), [rule.pattern]: rule.action };
+        }
+    }
+    return config;
+}
+/**
+ * The project's own runnable scripts: package.json scripts under each package manager (`scripts`, arguments allowed)
+ * and make targets (`exact`: `make -f`/`--eval` would run anything). Names with spaces or wildcards are skipped.
+ */
+export function projectScripts(dir) {
+    const commands = [];
+    const exact = [];
+    const plain = (name) => /^[\w:@./-]+$/.test(name);
+    const pkg = join(dir, "package.json");
+    if (existsSync(pkg)) {
+        try {
+            const scripts = Object.keys(JSON.parse(readFileSync(pkg, "utf8")).scripts ?? {}).filter(plain);
+            for (const s of scripts)
+                commands.push(...PACKAGE_MANAGERS.map((pm) => `${pm} run ${s}`), `yarn ${s}`);
+            if (scripts.includes("test"))
+                commands.push("npm test", "npm t", "pnpm test", "yarn test", "bun run test");
+        }
+        catch {
+            // an unreadable package.json contributes no scripts
+        }
+    }
+    for (const name of ["Makefile", "makefile", "GNUmakefile"]) {
+        if (!existsSync(join(dir, name)))
+            continue;
+        const targets = readFileSync(join(dir, name), "utf8").matchAll(/^([A-Za-z0-9][\w.-]*)\s*:(?!=)/gm);
+        for (const [, target] of targets)
+            if (plain(target))
+                exact.push(`make ${target}`);
+        exact.push("make");
+    }
+    return { scripts: [...new Set(commands)], exact: [...new Set(exact)] };
+}
+/** What a worker sees when a permission request is auto-rejected (spec E1). */
+export const rejectionMessage = (what) => `Not allowed in cheapag: \`${what}\`. If you need a dependency, use the question tool. Otherwise finish and list it in risks.`;