@illuminis/comprism 0.1.2 → 0.1.4

package/out/executor/index.js

@@ -33,7 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.NativeExecutor = exports.NATIVE_CAPABILITIES = exports.guessTestCommand = exports.stopEverything = void 0;
+exports.NativeExecutor = exports.NATIVE_CAPABILITIES = exports.guessTestCommand = exports.stopForeground = exports.stopEverything = void 0;
 /**
  * The executor: one implementation of every action, for every native client.
  *
@@ -50,19 +50,28 @@ exports.NativeExecutor = exports.NATIVE_CAPABILITIES = exports.guessTestCommand
  * what it cost are all the server's business. This performs and reports.
  */
 const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
 const files_1 = require("./files");
 const documents_1 = require("./documents");
 const hooks = __importStar(require("./hooks"));
+const browser_1 = require("./browser");
 const notebook_1 = require("./notebook");
+const diagnostics_1 = require("./diagnostics");
+const worktree_1 = require("./worktree");
+const paths_1 = require("./paths");
 const git_1 = require("./git");
+const toolservers_1 = require("./toolservers");
 const shell_1 = require("./shell");
 Object.defineProperty(exports, "guessTestCommand", { enumerable: true, get: function () { return shell_1.guessTestCommand; } });
 Object.defineProperty(exports, "stopEverything", { enumerable: true, get: function () { return shell_1.stopEverything; } });
+Object.defineProperty(exports, "stopForeground", { enumerable: true, get: function () { return shell_1.stopForeground; } });
 /** Everything a machine with a shell can do. Sent to the server on hello, and
  *  the catalog offered to the model is narrowed to it, so a client is never
  *  told about an action it cannot perform. */
 exports.NATIVE_CAPABILITIES = [
     "read_file", "read_notebook", "read_pdf", "list_dir", "file_map", "glob", "grep",
+    // The project's own checker for a changed file (manual 5.11).
+    "read_diagnostics",
     "write_file", "edit_file", "multi_edit", "create_dir", "delete_file",
     "move_file", "apply_patch",
     // Bytes, for a document the server built. Never offered to the model; the
@@ -78,7 +87,27 @@ exports.NATIVE_CAPABILITIES = [
     // on the server and are never offered to a client.
     "git_push",
     "todo_write",
+    // A helper's own copy of the project (manual 5.26). Never offered to the
+    // model: the service opens, reads and removes copies for editing helpers.
+    "worktree_open", "worktree_diff", "worktree_close",
+    // Tool servers on this machine the person approved (manual 9.10). Never
+    // offered to the model: the service lists and calls them by name.
+    "tool_server_list", "tool_server_call",
+    // The hooks of plugins installed here (manual 9.15), handed over by the
+    // service at the start of a job. Never offered to the model.
+    "plugin_hooks",
+    // This machine runs the hooks the service names, with each action and at
+    // the moments of a job (manual 10.9). Never offered to the model.
+    "run_hooks",
+    // A whole file, byte for byte, for a checkpoint (manual 7.3). Never offered
+    // to the model: `read_file` pages a long file and trims its last line break.
+    "read_raw",
 ];
+/** What a helper may do inside its own copy (manual 5.26). */
+const IN_COPY = new Set([
+    "read_file", "list_dir", "file_map", "glob", "grep",
+    "write_file", "edit_file", "multi_edit", "apply_patch", "create_dir", "git_status", "git_diff",
+]);
 /** How a package is added, per ecosystem.
  *
  *  Named rather than passed through as a raw command, because "install a
@@ -101,42 +130,133 @@ function installCommand(root, pkg, manager, dev) {
         default: return null;
     }
 }
+/** A file's exact contents and their SHA-256, for a checkpoint (manual 7.3).
+ *  Refused, never trimmed, when it is too large or not text. */
+function readRaw(root, rel) {
+    const crypto = require("crypto");
+    const base = fs.realpathSync(root);
+    const where = path.resolve(base, rel);
+    if (!where.startsWith(base + path.sep))
+        return { isError: true, content: `${rel} is outside this project.` };
+    let bytes;
+    try {
+        bytes = fs.readFileSync(where);
+    }
+    catch {
+        return { isError: true, content: `${rel} does not exist.`, facts: { missing: 1 } };
+    }
+    if (bytes.length > 400_000)
+        return { isError: true, content: `${rel} is too large to copy.`, facts: { too_large: 1 } };
+    let text;
+    try {
+        text = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+    }
+    catch {
+        return { isError: true, content: `${rel} is not text, so it cannot be copied.`, facts: { binary: 1 } };
+    }
+    return { isError: false, content: text, summary: `${bytes.length} bytes`,
+        facts: { sha256: crypto.createHash("sha256").update(bytes).digest("hex") } };
+}
 class NativeExecutor {
-    capabilities = exports.NATIVE_CAPABILITIES;
+    /** What this machine can do. The browser actions only where a browser is
+     *  installed (manual 10.16); the service offers them only when switched on. */
+    capabilities = (0, browser_1.findBrowser)() ? [...exports.NATIVE_CAPABILITIES, ...browser_1.BROWSER_ACTIONS] : exports.NATIVE_CAPABILITIES;
+    /** The job's browser, started on first use (10.16). */
+    browser;
+    /** Close what this job opened on the machine: its browser. */
+    close() {
+        this.browser?.close();
+        this.browser = undefined;
+    }
     root;
     onOutput;
     /** The test command, once it has been worked out or supplied. Remembered so a
      *  job that had to be told does not have to be told again. */
     testCommand;
-    /** What this project asks to happen around the agent's actions, read once. */
-    hooks;
     /** Whether the last test run passed. The grading signal the whole product
      *  rests on, kept so a session can report it when the job ends. */
     lastTestsPassed;
+    /** The operating system's sandbox, set when the service turns it on for a
+     *  job (manual 4.12). Absent, commands run with the person's own access. */
+    sandbox;
     constructor(opts) {
         this.root = fs.realpathSync(opts.root);
+        this.toolServers = new toolservers_1.ToolServers(this.root);
+        (0, paths_1.allowFolders)(this.root, opts.added ?? []);
         this.onOutput = opts.onOutput;
     }
-    async execute(name, a) {
-        // What this project asks to happen around the agent's actions. Read once
-        // and kept: reading the file on every action would mean a project could
-        // change its own rules mid job, which is not a property anybody wants.
-        if (this.hooks === undefined)
-            this.hooks = hooks.hooksFor(this.root);
+    /** One executor per helper copy, rooted there and nowhere else. */
+    inCopies = new Map();
+    /** Tool servers this job started (manual 9.10), stopped when it ends. */
+    toolServers;
+    async execute(name, a, plan) {
+        // An action for a helper's copy runs there, rooted in the copy, so it can
+        // never touch the person's own folder (manual 5.26).
+        if (typeof a._worktree === "string") {
+            const id = a._worktree;
+            const where = (0, worktree_1.worktreePath)(id);
+            if (!where)
+                return { isError: true, content: `There is no copy called ${id}.` };
+            if (!IN_COPY.has(name))
+                return { isError: true, content: `Refused: a helper cannot ${name} in its copy.` };
+            let inner = this.inCopies.get(id);
+            if (!inner) {
+                inner = new NativeExecutor({ root: where });
+                this.inCopies.set(id, inner);
+            }
+            const { _worktree: _dropped, ...rest } = a;
+            void _dropped;
+            return inner.execute(name, rest, plan);
+        }
+        // A tool server's list or call is carried, never gated by the project's
+        // own hooks: the service already decided whether it may happen.
+        if (name === "plugin_hooks") {
+            // An older service handing over plugin hooks in bulk. This machine runs
+            // the hooks the service names with each action instead, so nothing is
+            // kept here and nothing is matched here (manual 10.9).
+            const given = Array.isArray(a.hooks) ? a.hooks.length : 0;
+            return { isError: false, content: `${given} plugin hooks noted; the service names them per action` };
+        }
+        if (name === "read_raw") {
+            return readRaw(this.root, String(a.path ?? ""));
+        }
+        if (name === "run_hooks") {
+            // A moment of the job: job_start, job_end or waiting (manual 10.9).
+            const given = Array.isArray(a.hooks) ? a.hooks : [];
+            const done = await hooks.runHooks(this.root, given, {
+                when: String(a.when ?? ""), facts: (a.facts ?? {}),
+            });
+            const lines = hooks.reportLines(done);
+            return {
+                isError: done.failed.length > 0,
+                content: lines.join("\n") || "no hooks ran",
+                summary: done.failed.length ? `hook failed: ${done.failed.join("; ")}`
+                    : `${done.runs.length} ${String(a.when)} hook${done.runs.length === 1 ? "" : "s"} ran`,
+            };
+        }
+        if (name === "tool_server_list") {
+            return this.toolServers.list(String(a.server ?? ""), String(a.command ?? ""));
+        }
+        if (name === "tool_server_call") {
+            return this.toolServers.call(String(a.server ?? ""), String(a.command ?? ""), String(a.tool ?? ""), (a.arguments ?? {}));
+        }
+        // The hooks the service named for this action, run in its order (10.9).
         // A `before` hook may REFUSE this action, and that is the one place a
         // project's own script changes what happens. It can only ever refuse: there
         // is no exit code that approves something the agent was not already allowed
         // to do, because a permission system inside the repository would live
         // exactly where an attacker who got that far already is.
-        const gate = await hooks.before(this.root, name, a, this.hooks);
+        const gate = await hooks.runHooks(this.root, plan?.before ?? [], { when: "before", action: name, args: a });
         if (gate.refusedBy) {
-            return { isError: true, content: gate.detail ?? "A check in this project refused it." };
+            return { isError: true, content: gate.detail ?? "A hook in this project refused it.",
+                summary: gate.detail };
         }
         const shell = {
             root: this.root,
             cwd: typeof a.cwd === "string" ? a.cwd : undefined,
             timeoutMs: typeof a.timeout_s === "number" ? a.timeout_s * 1000 : undefined,
             onOutput: this.onOutput,
+            sandbox: this.sandbox,
         };
         try {
             const done = await this.perform(name, a, shell);
@@ -144,13 +264,24 @@ class NativeExecutor {
             // has already happened, and the overwhelming case is a formatter, which is
             // worth knowing about and not worth losing the work over.
             if (!done.isError) {
-                const ran = await hooks.after(this.root, name, a, this.hooks);
+                const ran = await hooks.runHooks(this.root, plan?.after ?? [], { when: "after", action: name, args: a });
+                const shown = hooks.reportLines(ran);
                 if (ran.failed.length) {
+                    // Said on the action's own line, so the person sees it, and told to
+                    // the model as what it is: the project's hook, not the file.
                     return {
                         ...done,
-                        content: `${done.content}\n\n[This project's own checks reported: ${ran.failed.join("; ")}]`,
+                        summary: `${done.summary ? `${done.summary}; ` : ""}hook: ${ran.failed.join("; ")}`,
+                        // The service words the action line from these (manual 10.9).
+                        facts: { ...(done.facts ?? {}), hook_note: ran.failed.join("; ") },
+                        content: `${done.content}\n\n[CompletionPrism ran this project's after hooks for this `
+                            + `action, as its settings ask. They reported: ${ran.failed.join("; ")}. This note is `
+                            + `from the tool, not part of the result.]`,
                     };
                 }
+                // Each hook's output, for the full view (manual 10.10).
+                if (shown.length)
+                    return { ...done, content: `${done.content}\n\n${shown.join("\n")}` };
             }
             return done;
         }
@@ -164,8 +295,15 @@ class NativeExecutor {
             };
         }
     }
+    async browse(name, a) {
+        if (!this.browser)
+            this.browser = new browser_1.Browser(this.root);
+        return this.browser.perform(name, a);
+    }
     async perform(name, a, shell) {
         {
+            if (name.startsWith("browser_"))
+                return await this.browse(name, a);
             switch (name) {
                 case "run_command":
                     return await (0, shell_1.runCommand)(String(a.command ?? ""), shell);
@@ -204,6 +342,14 @@ class NativeExecutor {
                     return await (0, documents_1.readPdf)(this.root, String(a.path ?? ""), a.pages, shell);
                 case "read_notebook":
                     return (0, notebook_1.readNotebook)(this.root, String(a.path ?? ""), a.include_output !== false);
+                case "read_diagnostics":
+                    return await (0, diagnostics_1.readDiagnostics)(this.root, a.path, a.severity, shell);
+                case "worktree_open": return await (0, worktree_1.openWorktree)(String(a.id ?? ""), shell);
+                case "worktree_diff": return await (0, worktree_1.diffWorktree)(String(a.id ?? ""), shell);
+                case "worktree_close": {
+                    this.inCopies.delete(String(a.id ?? ""));
+                    return await (0, worktree_1.closeWorktree)(String(a.id ?? ""), shell);
+                }
                 case "git_status": return await (0, git_1.gitStatus)(shell);
                 case "git_diff": return await (0, git_1.gitDiff)({ ...shell, path: a.path, staged: Boolean(a.staged) });
                 case "git_log": return await (0, git_1.gitLog)({ ...shell, path: a.path, limit: a.limit });

package/out/executor/paths.d.ts

@@ -1,7 +1,12 @@
 export declare class OutsideWorkspace extends Error {
     readonly attempted: string;
-    constructor(attempted: string);
+    /** `real` is where the path actually leads, when that differs from what was
+     *  asked for: a link is refused by naming its real location (manual 2.4). */
+    constructor(attempted: string, real?: string);
 }
+export declare function allowFolders(root: string, added: string[]): void;
+/** Every folder a job in `root` may touch, the project first. */
+export declare function allowedFolders(root: string): string[];
 export declare function isSecret(p: string): boolean;
 /**
  * An absolute path inside the workspace, or a refusal.

package/out/executor/paths.js

@@ -34,6 +34,8 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.OutsideWorkspace = void 0;
+exports.allowFolders = allowFolders;
+exports.allowedFolders = allowedFolders;
 exports.isSecret = isSecret;
 exports.resolveInside = resolveInside;
 /**
@@ -63,14 +65,40 @@ const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 class OutsideWorkspace extends Error {
     attempted;
-    constructor(attempted) {
-        super(`Refused: ${attempted} is outside this project. The agent works only ` +
-            `inside the folder that was opened.`);
+    /** `real` is where the path actually leads, when that differs from what was
+     *  asked for: a link is refused by naming its real location (manual 2.4). */
+    constructor(attempted, real) {
+        super(`Refused: ${attempted} is outside this project` +
+            (real && real !== attempted ? ` (it leads to ${real})` : "") +
+            `. The agent works only inside the folders that were opened.`);
         this.attempted = attempted;
         this.name = "OutsideWorkspace";
     }
 }
 exports.OutsideWorkspace = OutsideWorkspace;
+/**
+ * Folders the person added for this job (manual 2.3), keyed by the project's
+ * real root. Registered by the executor that owns the job, so every existing
+ * `resolveInside(root, ...)` call checks all allowed folders without each one
+ * having to carry the list. Only folders the person named reach here.
+ */
+const addedFolders = new Map();
+function allowFolders(root, added) {
+    const realRoot = fs.realpathSync(root);
+    const real = added.map((a) => fs.realpathSync(a)).filter((a) => a !== realRoot);
+    if (real.length)
+        addedFolders.set(realRoot, [...new Set(real)]);
+    else
+        addedFolders.delete(realRoot);
+}
+/** Every folder a job in `root` may touch, the project first. */
+function allowedFolders(root) {
+    const realRoot = fs.realpathSync(root);
+    return [realRoot, ...(addedFolders.get(realRoot) ?? [])];
+}
+function inside(real, folder) {
+    return real === folder || real.startsWith(folder.endsWith(path.sep) ? folder : folder + path.sep);
+}
 /** Files never read, whatever the mode. Mirrors the server's own list. */
 const SECRET = /^(\.env(\..*)?|.*\.pem|.*\.key|.*\.p12|.*\.pfx|id_rsa.*|id_ed25519.*|.*\.keystore|credentials|\.npmrc|\.netrc|\.git-credentials)$/i;
 function isSecret(p) {
@@ -116,9 +144,9 @@ function resolveInside(root, rel, mustExist = false) {
     }
     // The comparison, with a separator on the end. Without it `/work/project-two`
     // passes as being inside `/work/project`, because one string starts with the
-    // other.
-    if (real !== realRoot && !real.startsWith(realRoot + path.sep)) {
-        throw new OutsideWorkspace(rel);
+    // other. Every allowed folder is checked, and nothing else.
+    if (!allowedFolders(realRoot).some((folder) => inside(real, folder))) {
+        throw new OutsideWorkspace(rel, real);
     }
     // Return the requested path, not the probe: the caller wants to write to the
     // file it named, and the probe may be an ancestor of it.

package/out/executor/sandbox.d.ts

@@ -0,0 +1,40 @@
+export type SandboxSystem = "macOS" | "Linux";
+/** Which sandbox this machine offers, or why none. */
+export declare function availability(): {
+    system: SandboxSystem | null;
+    why: string;
+};
+/** Does this host match an allowed address: exact, or `*.example.com`. */
+export declare function hostAllowed(host: string, allow: string[]): boolean;
+export declare class Sandbox {
+    readonly system: SandboxSystem;
+    private readonly writable;
+    private allow;
+    private proxy;
+    private port;
+    /** Hosts refused since the last `takeBlocked`, for the result to name. */
+    private blocked;
+    constructor(system: SandboxSystem, root: string, added: string[]);
+    /** The allowed internet addresses, as the service sent them. */
+    setAllowed(allow: string[]): void;
+    /** Where the gatekeeper listens on Linux: a socket file the relay inside
+     *  the sandbox connects to, and a folder for the relay's ready marks. */
+    private socketPath;
+    private marks;
+    private calls;
+    /** Start the gatekeeper. Idempotent. */
+    start(): Promise<void>;
+    close(): void;
+    /** The hosts refused since the last call. */
+    takeBlocked(): string[];
+    private profile;
+    /** The program and arguments that run `command` inside the sandbox, and
+     *  the variables that send its web traffic to the gatekeeper. */
+    wrap(command: string, cwd: string): {
+        file: string;
+        args: string[];
+        env: Record<string, string>;
+    };
+    /** What was blocked, in the manual's words, or null (manual 4.12). */
+    explain(output: string, hosts: string[]): string | null;
+}