@proagentstore/cli 0.4.13 → 0.4.15

package/dist/browser-runner/coding/headless.js

@@ -1,6 +1,7 @@
 import { spawn } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
+import { handlerFor } from "./handlers.js";
 export class HeadlessSession {
     config;
     sessionName;
@@ -28,9 +29,15 @@ export class HeadlessSession {
         // Claude is the structured engine; everything else is a raw CLI.
         this.mode = config.clientType === "claude" ? "stream-json" : "raw";
         const { bin, args } = parseCommand(config.command);
+        // When no explicit command is configured, fall back to THIS engine's default
+        // command (codex/gemini/grok/…) — not a hard-coded "claude", which would drive a
+        // non-Claude session with the wrong CLI (and mode is already "raw" for it).
+        const fallback = parseCommand(handlerFor(config.clientType).cliCommand);
         // A test/override bin wins for the binary only; the command's args are kept.
-        this.cmdBin = config.bin ?? (bin || "claude");
-        this.cmdArgs = args;
+        this.cmdBin = config.bin ?? (bin || fallback.bin || "claude");
+        // Use the configured command's args when a command was given (bin set), else the
+        // engine default's args.
+        this.cmdArgs = bin ? args : fallback.args;
         this.binName = (this.cmdBin.split("/").pop() || this.cmdBin) || "cli";
     }
     /** True while the agent process is running. NOTE: do NOT use `proc.killed` — Node sets
@@ -81,31 +88,39 @@ export class HeadlessSession {
         // (e.g. --model) without letting them clobber or orphan-value our flags. raw:
         // run exactly what the user configured and capture stdout.
         const args = this.mode === "stream-json" ? buildClaudeArgs(this.cmdArgs, this.claudeSessionId) : [...this.cmdArgs];
-        this.proc = spawn(this.cmdBin, args, {
+        const proc = spawn(this.cmdBin, args, {
             cwd: this.config.workDir,
             env: { ...process.env, ...this.config.env },
             stdio: ["pipe", "pipe", "pipe"],
         });
+        this.proc = proc;
         this.run = "idle";
         this.lastOutputAt = Date.now();
         // MUST handle 'error' — without a listener, a spawn failure (e.g. the binary
         // not on PATH) is thrown as an uncaught exception and crashes the runner.
-        this.proc.on("error", (err) => {
+        proc.on("error", (err) => {
+            if (this.proc !== proc)
+                return; // a newer process replaced this one — ignore the stale event
             this.run = "idle";
             this.push(`[cannot run \`${this.cmdBin}\`: ${err.message} — is ${this.binName} installed and on your PATH?]`);
             this.proc = null;
         });
         // Swallow EPIPE when writing to a process that just exited (one-shot turn).
-        this.proc.stdin?.on("error", () => { });
-        this.proc.stdout?.on("data", (d) => this.onStdout(d.toString("utf8")));
-        this.proc.stderr?.on("data", (d) => {
+        proc.stdin?.on("error", () => { });
+        proc.stdout?.on("data", (d) => this.onStdout(d.toString("utf8")));
+        proc.stderr?.on("data", (d) => {
             this.lastOutputAt = Date.now();
             this.sawOutputSinceInput = true;
             const text = d.toString("utf8").trim();
             if (text)
                 this.push(`[${this.binName}] ${stripAnsi(text)}`);
         });
-        this.proc.on("exit", (code) => {
+        proc.on("exit", (code) => {
+            // A stop() + re-start() on the SAME session object can leave this old process's
+            // async exit to fire AFTER the fresh start — capturing `proc` and bailing when it
+            // no longer matches stops the stale handler from resetting the new turn to idle.
+            if (this.proc !== proc)
+                return;
             this.run = "idle";
             if (code && code !== 0)
                 this.push(`[${this.binName} exited with code ${code}]`);
@@ -184,9 +199,14 @@ export class HeadlessSession {
             else
                 this.pushRaw(line); // raw engine — the line IS the terminal output
         }
-        // A TUI/raw engine may render without newlines; don't let `buf` grow unbounded
-        // (and surface the partial output so the pane isn't blank). 16KB is generous.
-        if (this.buf.length > 16 * 1024) {
+        // A TUI/raw engine may render without newlines; surface the partial output and cap
+        // growth at 16KB. Claude's stream-json, though, emits ONE JSON object per line and a
+        // single event (a large tool_result / the final `result`) can legitimately exceed
+        // 16KB — truncating mid-line there corrupts the event, and losing a `result` line
+        // wedges the turn "thinking" forever (stream-json has no idle backstop). So give the
+        // structured path a far larger ceiling; only a pathologically huge line resets it.
+        const cap = this.mode === "raw" ? 16 * 1024 : 4 * 1024 * 1024;
+        if (this.buf.length > cap) {
             if (this.mode === "raw")
                 this.pushRaw(this.buf);
             this.buf = "";

package/dist/browser-runner/coding/inspect.js

@@ -0,0 +1,143 @@
+import { execFileSync } from "node:child_process";
+import { existsSync, readdirSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { relative, resolve, sep } from "node:path";
+/**
+ * Read-only code inspection for the coding runtime — the "eyes" the Co-pilot/Chat use
+ * to GROUND their answers in the real repo (read a file, `git diff`, list the tree)
+ * WITHOUT driving the live CLI. All access is confined to the session's workDir.
+ *
+ * Two pure, separately-tested primitives carry the safety:
+ *   - resolveInside(): rejects any path escaping the repo root (../, absolute, sibling
+ *     prefix, symlink escape).
+ *   - gitArgv(): maps a fixed command enum to a fixed argv — no user string ever
+ *     becomes a git token except a resolveInside-validated path after a literal `--`.
+ */
+/** Resolve `rel` under `root`, refusing anything that escapes it. Pure (no fs) EXCEPT the
+ *  optional symlink check, which is what defends against a symlink inside the repo pointing
+ *  at e.g. ~/.ssh. Throws on any escape. */
+export function resolveInside(root, rel, opts = {}) {
+    const rootAbs = resolve(root);
+    const abs = resolve(rootAbs, rel);
+    // `resolve` collapses `..`, so a traversal or absolute escape lands outside rootAbs.
+    // The explicit `+ sep` blocks a sibling-prefix attack (/repo vs /repo-secrets).
+    if (abs !== rootAbs && !abs.startsWith(rootAbs + sep)) {
+        throw new InspectError(`path escapes the repo: ${rel}`);
+    }
+    if (opts.checkSymlink && existsSync(abs)) {
+        // A symlink inside the repo could still point outside it — resolve the real path and
+        // re-check the same invariant.
+        const real = realpathSync(abs);
+        const realRoot = realpathSync(rootAbs);
+        if (real !== realRoot && !real.startsWith(realRoot + sep)) {
+            throw new InspectError(`path resolves (via symlink) outside the repo: ${rel}`);
+        }
+    }
+    return abs;
+}
+/** Map a whitelisted command enum to a fixed git argv. `path` (already validated by the
+ *  caller via resolveInside) is only ever appended after a literal `--` separator. */
+export function gitArgv(cmd, opts = {}) {
+    const clampN = Math.max(1, Math.min(200, Math.floor(opts.n ?? 20)));
+    switch (cmd) {
+        case "status":
+            return ["status", "--short"];
+        case "diff":
+            return opts.relPath ? ["diff", "--", opts.relPath] : ["diff"];
+        case "diff-stat":
+            return ["diff", "--stat"];
+        case "log":
+            return ["log", "--oneline", "-n", String(clampN)];
+        case "ls-files":
+            return ["ls-files"];
+        default:
+            throw new InspectError(`unsupported git command: ${cmd}`);
+    }
+}
+export class InspectError extends Error {
+    constructor(msg) {
+        super(msg);
+        this.name = "InspectError";
+    }
+}
+const DEFAULT_MAX_FILE_BYTES = 64 * 1024;
+const HARD_MAX_FILE_BYTES = 128 * 1024;
+/** Read a text file inside the repo. Rejects traversal, oversize, and binary files. */
+export function readRepoFile(workDir, relPath, maxBytes) {
+    const abs = resolveInside(workDir, relPath, { checkSymlink: true });
+    const st = statSync(abs);
+    if (!st.isFile())
+        throw new InspectError(`not a regular file: ${relPath}`);
+    const cap = Math.min(maxBytes ?? DEFAULT_MAX_FILE_BYTES, HARD_MAX_FILE_BYTES);
+    const buf = readFileSync(abs);
+    // Binary sniff: a NUL byte in the first 8KB → don't feed bytes to the model.
+    const head = buf.subarray(0, 8192);
+    if (head.includes(0))
+        return { path: relPath, size: st.size, truncated: false, binary: true };
+    const truncated = buf.length > cap;
+    return { path: relPath, size: st.size, truncated, content: buf.subarray(0, cap).toString("utf-8") };
+}
+/** Run a whitelisted read-only git command in the repo. Never uses a shell. */
+export function runRepoGit(workDir, cmd, opts = {}) {
+    if (!existsSync(resolve(workDir, ".git")))
+        throw new InspectError("not a git repo");
+    const relPath = opts.path ? relative(workDir, resolveInside(workDir, opts.path)) : undefined;
+    const argv = gitArgv(cmd, { relPath, n: opts.n });
+    let out = "";
+    try {
+        out = execFileSync("git", argv, { cwd: workDir, encoding: "utf-8", timeout: 10_000, maxBuffer: 4 * 1024 * 1024 });
+    }
+    catch (e) {
+        // git exits non-zero for benign cases (e.g. `diff` on nothing) — surface stdout if present.
+        const err = e;
+        out = err.stdout ?? "";
+        if (!out)
+            throw new InspectError(err.message || `git ${cmd} failed`);
+    }
+    const cap = opts.maxBytes ?? 64 * 1024;
+    const truncated = out.length > cap;
+    return { cmd, output: truncated ? out.slice(0, cap) : out, truncated };
+}
+const IGNORE_DIRS = new Set(["node_modules", ".git", "dist", "build", ".next", ".turbo", "coverage", ".wrangler"]);
+/** Bounded recursive file tree (names/type/size only — no contents). */
+export function repoTree(workDir, relPath = ".", maxDepth = 3, maxEntries = 500) {
+    const start = resolveInside(workDir, relPath, { checkSymlink: true });
+    const depthCap = Math.max(1, Math.min(4, maxDepth));
+    const entryCap = Math.max(1, Math.min(1000, maxEntries));
+    const entries = [];
+    const queue = [{ dir: start, depth: 0 }];
+    let truncated = false;
+    while (queue.length) {
+        const { dir, depth } = queue.shift();
+        let items;
+        try {
+            items = readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const it of items) {
+            if (it.name.startsWith(".") || IGNORE_DIRS.has(it.name))
+                continue;
+            if (entries.length >= entryCap) {
+                truncated = true;
+                return { root: relPath, entries, truncated };
+            }
+            const abs = resolve(dir, it.name);
+            const rel = relative(workDir, abs);
+            if (it.isDirectory()) {
+                entries.push({ path: rel, type: "dir" });
+                if (depth + 1 < depthCap)
+                    queue.push({ dir: abs, depth: depth + 1 });
+            }
+            else if (it.isFile()) {
+                let size;
+                try {
+                    size = statSync(abs).size;
+                }
+                catch { }
+                entries.push({ path: rel, type: "file", size });
+            }
+        }
+    }
+    return { root: relPath, entries, truncated };
+}

package/dist/browser-runner/coding/runtime.js

@@ -1,6 +1,7 @@
 import { homedir } from "node:os";
 import { join, resolve } from "node:path";
 import { defaultStatePath, HeadlessSession } from "./headless.js";
+import { InspectError, readRepoFile, repoTree, runRepoGit } from "./inspect.js";
 import { ensureRepo, sanitizeSessionName } from "./tmux.js";
 /** Hard cap on a pane returned to the brain/console (matches the worker MAX_PANE_CHARS). */
 const MAX_PANE = 64 * 1024;
@@ -18,9 +19,39 @@ export class CodingRuntime {
     constructor(reposBaseDir = join(homedir(), ".config", "proagentstore", "repos")) {
         this.reposBaseDir = reposBaseDir;
     }
-    /** Capabilities advertised to PAGS at registration. */
+    /** Capabilities advertised to PAGS at registration. `coding.inspect` signals the
+     *  read-only code-inspection endpoints exist, so the cloud offers the grounding tools
+     *  (older runners omit it → the cloud degrades to terminal-only). */
     static capabilities() {
-        return ["coding.sessions", "coding.stream", "human.takeover"];
+        return ["coding.sessions", "coding.stream", "human.takeover", "coding.inspect"];
+    }
+    /**
+     * Resolve the workDir for a read-only inspection. Prefer the tracked session's real
+     * workDir (authoritative even for managed clone dirs); fall back to an explicit path
+     * (the cloud passes the D1 `repo.workdir` when the session map is empty after a runner
+     * restart). Expands a leading `~` the same way start() does.
+     */
+    resolveWorkDir(input) {
+        if (input.sessionId) {
+            const s = this.sessions.get(input.sessionId);
+            if (s)
+                return s.config.workDir;
+        }
+        if (input.workDir)
+            return resolve(input.workDir.replace(/^~(?=$|\/)/, homedir()));
+        throw new InspectError("no session or workDir to inspect");
+    }
+    /** Read one file inside the session's repo (traversal-guarded, size-capped). */
+    readFile(input) {
+        return readRepoFile(this.resolveWorkDir(input), input.path, input.maxBytes);
+    }
+    /** Run a whitelisted read-only git command in the session's repo. */
+    git(input) {
+        return runRepoGit(this.resolveWorkDir(input), input.cmd, { path: input.path, n: input.n });
+    }
+    /** Bounded recursive file tree of the session's repo (names/type/size only). */
+    tree(input) {
+        return repoTree(this.resolveWorkDir(input), input.path, input.maxDepth, input.maxEntries);
     }
     static taskTypes() {
         return ["coding.session"];

package/dist/browser-runner/coding/tmux.js

@@ -1,5 +1,5 @@
 import { execFileSync } from "node:child_process";
-import { existsSync, mkdirSync, rmSync } from "node:fs";
+import { existsSync, mkdirSync, readdirSync, rmSync } from "node:fs";
 import { join } from "node:path";
 /**
  * Low-level tmux primitives for the coding runtime.
@@ -108,10 +108,18 @@ export function ensureRepo(dir, opts = {}) {
             mkdirSync(dir, { recursive: true });
         return dir;
     }
-    // A stale/empty/half-cloned dir (exists but no .git) would make `git clone`
-    // fail on a non-empty target — clear it first so the clone is clean.
-    if (existsSync(dir))
+    // The dir exists but has no `.git`. It could be a half-cloned/empty managed dir
+    // (safe to clear) OR a real user directory the caller passed as an explicit workDir
+    // (deleting it = data loss). NEVER recursively delete a non-empty non-git dir — refuse
+    // instead, so a mis-wired workDir+cloneUrl can't nuke a user's files. An empty dir is
+    // fine to remove (git clone needs an empty/absent target).
+    if (existsSync(dir)) {
+        const entries = readdirSync(dir);
+        if (entries.length > 0) {
+            throw new Error(`Refusing to clone into non-empty directory "${dir}" (no .git found) — move it aside or point at an empty path.`);
+        }
         rmSync(dir, { recursive: true, force: true });
+    }
     let url = opts.cloneUrl;
     if (opts.token && /^https:\/\//.test(url)) {
         url = url.replace(/^https:\/\//, `https://x-access-token:${opts.token}@`);

package/dist/browser-runner/runner.js

@@ -758,6 +758,28 @@ export class LocalRunner {
             return `⚠ "${name}" REJECTED: now reads "${shown}"${parsed.msg ? ` — ${parsed.msg.slice(0, 80)}` : ""}`;
         return `"${name}" now reads "${shown}"`;
     }
+    /** Read a checkbox/radio's checked state via the standard evaluate tool so `check`
+     *  can be made idempotent (a raw click would toggle). Returns true/false, or null when
+     *  the state can't be determined (then we fall back to clicking). Never throws. */
+    async isChecked(mcp, ref, label) {
+        const fn = "el => { if (el.checked !== undefined && el.checked !== null) return !!el.checked; " +
+            "const a = el.getAttribute('aria-checked'); return a === 'true' ? true : a === 'false' ? false : null; }";
+        const res = await mcp.callTool("browser_evaluate", { element: label, target: ref, function: fn }).catch(() => null);
+        if (!res || res.isError)
+            return null;
+        const txt = mcp.textOf(res);
+        const i = txt.indexOf("### Result");
+        if (i < 0)
+            return null;
+        const after = txt.slice(i + "### Result".length).trim();
+        const end = after.indexOf("\n###");
+        const block = (end >= 0 ? after.slice(0, end) : after).trim().replace(/^["']|["']$/g, "");
+        if (/^true$/i.test(block))
+            return true;
+        if (/^false$/i.test(block))
+            return false;
+        return null;
+    }
     /** The snapshot ref the brain must target the element by (standard-tool `target`). */
     refOf(action) {
         const ref = (action.ref || "").trim();
@@ -773,10 +795,19 @@ export class LocalRunner {
                 return mcp.callTool("browser_navigate", { url: a.url });
             case "type":
                 return mcp.callTool("browser_type", { element: label, target: this.refOf(a), text: a.text ?? "" });
-            // A checkbox/radio is just a click at the standard-tool level.
             case "click":
-            case "check":
                 return mcp.callTool("browser_click", { element: label, target: this.refOf(a) });
+            case "check": {
+                const ref = this.refOf(a);
+                // A checkbox/radio click is a TOGGLE at the standard-tool level — clicking an
+                // ALREADY-checked control unchecks it, silently reversing a pre-ticked consent
+                // or a default-selected radio before submit. Make `check` idempotent
+                // (ensure-checked): read the current state and only click when it isn't set.
+                if ((await this.isChecked(mcp, ref, label)) === true) {
+                    return { isError: false, content: [{ type: "text", text: `"${label}" already checked` }] };
+                }
+                return mcp.callTool("browser_click", { element: label, target: ref });
+            }
             case "upload": {
                 if (!this.applyResumePath)
                     throw new RunnerInputError("no résumé file available to upload");

package/dist/browser-runner/server.js

@@ -222,6 +222,35 @@ async function route(runner, req, res) {
         }
         return json(res, 200, { killed, sessions: targets });
     }
+    // ── Read-only code inspection (the Co-pilot/Chat's "eyes" — no CLI driving) ──
+    // Confined to the session's workDir by inspect.ts; errors surface as 400.
+    if (req.method === "POST" && path === "/coding/read-file") {
+        const b = await readJson(req);
+        try {
+            return json(res, 200, runner.coding.readFile(b));
+        }
+        catch (e) {
+            return json(res, 400, { error: e instanceof Error ? e.message : String(e) });
+        }
+    }
+    if (req.method === "POST" && path === "/coding/git") {
+        const b = await readJson(req);
+        try {
+            return json(res, 200, runner.coding.git(b));
+        }
+        catch (e) {
+            return json(res, 400, { error: e instanceof Error ? e.message : String(e) });
+        }
+    }
+    if (req.method === "POST" && path === "/coding/tree") {
+        const b = await readJson(req);
+        try {
+            return json(res, 200, runner.coding.tree(b));
+        }
+        catch (e) {
+            return json(res, 400, { error: e instanceof Error ? e.message : String(e) });
+        }
+    }
     if (req.method === "POST" && path === "/coding/event") {
         // Brain progress events — recorded by PAGS, ignored locally. Accept + ack.
         return json(res, 200, { ok: true });

package/dist/index.js

@@ -1365,9 +1365,13 @@ var upCommand = new Command7("up").description("Start the browser runner for all
     if (key === "r") {
       if (childDead) {
         writeLine("  Restarting runner...");
-        const { execSync } = await import("child_process");
+        const { execFileSync: execFileSync2 } = await import("child_process");
+        const restartArgs = [process.argv[1], "up"];
+        if (opts.headless) restartArgs.push("--headless");
+        if (opts.force) restartArgs.push("--force");
+        if (opts.instance) restartArgs.push("--instance", opts.instance);
         try {
-          execSync(`${process.execPath} ${process.argv[1]} up${opts.headless ? " --headless" : ""}${opts.force ? " --force" : ""}`, {
+          execFileSync2(process.execPath, restartArgs, {
             stdio: "inherit",
             env: process.env
           });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proagentstore/cli",
-  "version": "0.4.13",
+  "version": "0.4.15",
   "description": "CLI for creating, publishing, and running ProAgentStore agents",
   "license": "MIT",
   "type": "module",