@illuminis/comprism 0.1.0

package/out/executor/hooks.js

@@ -0,0 +1,247 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EXAMPLE = void 0;
+exports.hooksFor = hooksFor;
+exports.covers = covers;
+exports.before = before;
+exports.after = after;
+/**
+ * Something of your own, run before or after the agent acts.
+ *
+ * Specification: docs/modules/CODING_AGENT_BUILD_SPECIFICATION.md, register
+ * item C18. What Claude Code calls hooks.
+ *
+ * ## Why this belongs on the client
+ *
+ * A hook is the customer's own command, running in their own project, on their
+ * own machine. Nothing about it is ours to run: the command is theirs, the
+ * environment is theirs, and the thing it usually wants to do is reformat a
+ * file that only exists there.
+ *
+ * So the configuration is read from the project itself rather than from our
+ * database. A hook that lives in the repository is reviewed like any other
+ * change, travels with a branch, and is the same for everybody who works there.
+ * A hook stored in our settings would be invisible in the repository and
+ * different for whoever configured it.
+ *
+ * ## What they are for, in practice
+ *
+ * The overwhelming case is "run the formatter after the agent edits a file", and
+ * the reason it earns a feature is that the alternative is telling the model to
+ * remember to do it, which it does four times out of five.
+ *
+ * ## What a hook may not do
+ *
+ * **It cannot approve anything and it cannot change the decision.** A hook that
+ * could turn a refusal into an approval would be a permission system in a file
+ * inside the repository, which is the wrong place for one: the repository is
+ * exactly what an attacker who has got that far already controls.
+ *
+ * A hook that fails is reported and does not stop the job, with one exception
+ * stated in `before`: a `before` hook exiting non-zero cancels that one action,
+ * because "do not let the agent touch generated files" is a real thing to want
+ * and refusing is the only way to say it.
+ */
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const shell_1 = require("./shell");
+/** Where a project declares its hooks, in the order they are tried.
+ *
+ *  The settings file comes first, because that is where every other thing a
+ *  project says about its agent now lives, and keeping hooks somewhere else was
+ *  one more folder for a newcomer to know about.
+ *
+ *  `.illuminis/hooks.json` is still read, and last. It is what projects were
+ *  told to write, and silently ignoring a file somebody wrote on our
+ *  instructions would mean their formatter stops running with no message
+ *  anywhere. Only one file is used: the first that has hooks in it wins, so a
+ *  project that has moved does not get both. */
+const CONFIGS = [
+    ".completionprism/settings.json",
+    ".completionprism/settings.local.json",
+    ".comprism/settings.json",
+    ".claude/settings.json",
+    ".illuminis/hooks.json",
+];
+/** What this project asks for, or nothing.
+ *
+ *  A malformed file is ignored with a warning rather than failing the job. A
+ *  project whose hook configuration has a trailing comma should not be a project
+ *  where the agent refuses to work, and the person who broke it is not usually
+ *  the person now trying to get something done.
+ */
+function hooksFor(root) {
+    for (const name of CONFIGS) {
+        const file = path.join(root, name);
+        if (!fs.existsSync(file))
+            continue;
+        try {
+            const parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+            const hooks = Array.isArray(parsed.hooks) ? parsed.hooks : [];
+            const usable = hooks.filter((h) => h && typeof h.command === "string" && h.command.trim()
+                && (h.when === "before" || h.when === "after")
+                && typeof h.on === "string" && h.on.trim());
+            // A settings file with no hooks section is the ordinary case, and it must
+            // not stop the older file being read. Only a file that actually declares
+            // hooks ends the search.
+            if (usable.length)
+                return usable;
+        }
+        catch (err) {
+            process.stderr.write(`  ${name} could not be read (${err.message}), so no hooks ran.\n`);
+            return [];
+        }
+    }
+    return [];
+}
+/** Does this hook's matcher cover this action.
+ *
+ *  Exported because it is the part with the rules in it, and a rule with no
+ *  test is a rule that drifts.
+ */
+function covers(pattern, action) {
+    const p = String(pattern ?? "").trim();
+    if (!p || !action)
+        return false;
+    if (p === "*")
+        return true;
+    if (p === action)
+        return true;
+    if (p.includes("|") && !/[\\^$.?*+()[\]{}]/.test(p)) {
+        return p.split("|").some((one) => one.trim() === action);
+    }
+    if (!/[\\^$.?*+()[\]{}|]/.test(p))
+        return false;
+    try {
+        return new RegExp(`^(?:${p})$`).test(action);
+    }
+    catch {
+        // A pattern that will not compile matches NOTHING. The other direction,
+        // matching everything, would run somebody's script on every action because
+        // of a typo, which is the expensive way to be wrong.
+        process.stderr.write(`  A hook pattern is not valid and was skipped: ${p}\n`);
+        return false;
+    }
+}
+function matching(hooks, action, when) {
+    return hooks.filter((h) => h.when === when && covers(h.on, action));
+}
+/** The path the action is about, for a hook that wants to know. */
+function targetOf(args) {
+    return String(args.path ?? args.to ?? "");
+}
+/**
+ * Run the hooks that come before one action.
+ *
+ * **A non-zero exit cancels the action.** This is the one place a hook changes
+ * what happens, and it is deliberate: "do not let the agent touch anything under
+ * generated/" is a real thing to want, and refusing is the only way for a
+ * project to say it.
+ *
+ * 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.
+ */
+async function before(root, action, args, hooks = hooksFor(root)) {
+    const applicable = matching(hooks, action, "before");
+    let ran = 0;
+    for (const hook of applicable) {
+        const result = await (0, shell_1.runCommand)(hook.command, {
+            root,
+            timeoutMs: 60_000,
+            // What the hook is about, as environment rather than as arguments, so an
+            // existing script needs no wrapper to read it.
+            extraEnv: { ILLUMINIS_ACTION: action, ILLUMINIS_PATH: targetOf(args) },
+        });
+        ran += 1;
+        if (result.isError || !/^exit 0/.test(result.content)) {
+            return {
+                ran,
+                refusedBy: hook.command,
+                detail: `${hook.what ?? "A check in this project"} refused this: ${result.content.slice(0, 500)}`,
+            };
+        }
+    }
+    return { ran };
+}
+/**
+ * Run the hooks that come after one action.
+ *
+ * A failure here is reported and nothing else: the action has already happened,
+ * and refusing it afterwards is not a thing that can be done. The overwhelming
+ * case is a formatter, and a formatter that fails is worth knowing about and not
+ * worth losing the work over.
+ */
+async function after(root, action, args, hooks = hooksFor(root)) {
+    const applicable = matching(hooks, action, "after");
+    const failed = [];
+    let ran = 0;
+    for (const hook of applicable) {
+        const result = await (0, shell_1.runCommand)(hook.command, {
+            root, timeoutMs: 120_000,
+            extraEnv: { ILLUMINIS_ACTION: action, ILLUMINIS_PATH: targetOf(args) },
+        });
+        ran += 1;
+        if (result.isError || !/^exit 0/.test(result.content)) {
+            failed.push(`${hook.what ?? hook.command}: ${result.content.slice(0, 300)}`);
+        }
+    }
+    return { ran, failed };
+}
+/** The example a person copies. Kept in code so the readme and the behavior
+ *  cannot drift: this is what the reader actually gets. */
+exports.EXAMPLE = JSON.stringify({
+    hooks: [
+        {
+            on: "write_file|edit_file|multi_edit",
+            when: "after",
+            command: "npm run lint --silent",
+            what: "Lint after anything is written",
+        },
+        {
+            on: "edit_file",
+            when: "after",
+            command: "npx prettier --write $ILLUMINIS_PATH",
+            what: "Format the file that was just changed",
+        },
+        {
+            on: "write_file",
+            when: "before",
+            command: "test \"${ILLUMINIS_PATH#generated/}\" = \"$ILLUMINIS_PATH\"",
+            what: "Nothing under generated/ is edited by hand",
+        },
+    ],
+}, null, 2);

package/out/executor/index.d.ts

@@ -0,0 +1,29 @@
+import { RunResult, guessTestCommand, stopEverything } from "./shell";
+export { stopEverything, guessTestCommand };
+export type { RunResult };
+/** 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. */
+export declare const NATIVE_CAPABILITIES: string[];
+export interface ExecutorOptions {
+    root: string;
+    /** Called with each chunk of a running command's output, so a terminal can
+     *  show it as it happens rather than in one block at the end. */
+    onOutput?: (chunk: string) => void;
+}
+export declare class NativeExecutor {
+    readonly capabilities: string[];
+    readonly root: string;
+    private readonly 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. */
+    private testCommand?;
+    /** What this project asks to happen around the agent's actions, read once. */
+    private 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?: boolean;
+    constructor(opts: ExecutorOptions);
+    execute(name: string, a: Record<string, unknown>): Promise<RunResult>;
+    private perform;
+}

package/out/executor/index.js

@@ -0,0 +1,221 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NativeExecutor = exports.NATIVE_CAPABILITIES = exports.guessTestCommand = exports.stopEverything = void 0;
+/**
+ * The executor: one implementation of every action, for every native client.
+ *
+ * Specification: docs/modules/CODING_AGENT_BUILD_SPECIFICATION.md §7.1 and
+ * register item E2.
+ *
+ * The terminal runs this today. **The editor extension and the desktop app
+ * bundle this same file rather than writing their own**, and that is the point
+ * of it existing separately from the command line interface around it. Three
+ * implementations of "read a file" would be three different answers to what a
+ * file contains, and the one that differs is always the one nobody is looking at.
+ *
+ * It decides nothing. Whether an action is allowed, which model asked for it and
+ * what it cost are all the server's business. This performs and reports.
+ */
+const fs = __importStar(require("fs"));
+const files_1 = require("./files");
+const documents_1 = require("./documents");
+const hooks = __importStar(require("./hooks"));
+const notebook_1 = require("./notebook");
+const git_1 = require("./git");
+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; } });
+/** 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",
+    "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
+    // loop issues it after `make_document`, so a deck lands in the folder the
+    // person is standing in rather than behind a link in a web page they are not
+    // looking at.
+    "write_bytes",
+    "run_command", "run_tests", "run_background", "read_output", "stop_process",
+    "install_dependency",
+    "git_status", "git_diff", "git_log", "git_branch", "git_commit",
+    // Pushing is here because it needs the repository. Pull requests, reviews,
+    // checks and releases are NOT: they need the tenant's credential, so they run
+    // on the server and are never offered to a client.
+    "git_push",
+    "todo_write",
+];
+/** How a package is added, per ecosystem.
+ *
+ *  Named rather than passed through as a raw command, because "install a
+ *  dependency" is a thing a person can meaningfully approve and
+ *  `npm i --silent --prefix ../.. something` is not. The approval is only worth
+ *  asking for if what is being approved is legible. */
+function installCommand(root, pkg, manager, dev) {
+    const has = (f) => fs.existsSync(`${root}/${f}`);
+    const m = manager
+        || (has("pnpm-lock.yaml") ? "pnpm" : has("yarn.lock") ? "yarn"
+            : has("package.json") ? "npm" : has("Cargo.toml") ? "cargo"
+                : has("go.mod") ? "go" : has("pyproject.toml") || has("requirements.txt") ? "pip" : "");
+    switch (m) {
+        case "npm": return `npm install ${dev ? "--save-dev " : ""}${pkg}`;
+        case "pnpm": return `pnpm add ${dev ? "-D " : ""}${pkg}`;
+        case "yarn": return `yarn add ${dev ? "-D " : ""}${pkg}`;
+        case "pip": return `python -m pip install ${pkg}`;
+        case "cargo": return `cargo add ${pkg}${dev ? " --dev" : ""}`;
+        case "go": return `go get ${pkg}`;
+        default: return null;
+    }
+}
+class NativeExecutor {
+    capabilities = exports.NATIVE_CAPABILITIES;
+    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;
+    constructor(opts) {
+        this.root = fs.realpathSync(opts.root);
+        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);
+        // 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);
+        if (gate.refusedBy) {
+            return { isError: true, content: gate.detail ?? "A check in this project refused it." };
+        }
+        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,
+        };
+        try {
+            const done = await this.perform(name, a, shell);
+            // And afterwards. A failure here is reported and nothing else: the action
+            // 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);
+                if (ran.failed.length) {
+                    return {
+                        ...done,
+                        content: `${done.content}\n\n[This project's own checks reported: ${ran.failed.join("; ")}]`,
+                    };
+                }
+            }
+            return done;
+        }
+        catch (err) {
+            // Never thrown to the loop. A failure here is a RESULT the model reads and
+            // works around; an exception would end a job over something it could have
+            // handled itself, and the person would lose everything already done.
+            return {
+                isError: true,
+                content: `This action could not be completed: ${err?.message ?? err}`,
+            };
+        }
+    }
+    async perform(name, a, shell) {
+        {
+            switch (name) {
+                case "run_command":
+                    return await (0, shell_1.runCommand)(String(a.command ?? ""), shell);
+                case "run_tests": {
+                    const r = await (0, shell_1.runTests)({
+                        ...shell,
+                        command: a.command || this.testCommand,
+                        path: a.path,
+                    });
+                    if (r.command)
+                        this.testCommand = r.command;
+                    if (typeof r.passed === "boolean")
+                        this.lastTestsPassed = r.passed;
+                    return r;
+                }
+                case "run_background":
+                    return (0, shell_1.startBackground)(String(a.command ?? ""), shell);
+                case "read_output":
+                    return (0, shell_1.readOutput)(String(a.process_id ?? ""));
+                case "stop_process":
+                    return (0, shell_1.stopProcess)(String(a.process_id ?? ""));
+                case "install_dependency": {
+                    const cmd = installCommand(this.root, String(a.package ?? ""), a.manager, Boolean(a.dev));
+                    if (!cmd) {
+                        return {
+                            isError: true,
+                            content: "I could not work out how this project installs packages. Tell " +
+                                "me which package manager it uses.",
+                        };
+                    }
+                    return await (0, shell_1.runCommand)(cmd, shell);
+                }
+                case "apply_patch":
+                    return await (0, documents_1.applyPatch)(String(a.patch ?? ""), shell);
+                case "read_pdf":
+                    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 "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 });
+                case "git_branch": return await (0, git_1.gitBranch)(String(a.name ?? ""), shell);
+                case "git_commit": return await (0, git_1.gitCommit)(String(a.message ?? ""), { ...shell, paths: a.paths });
+                case "git_push": return await (0, git_1.gitPush)(String(a.branch ?? ""), {
+                    ...shell, createRemote: Boolean(a.create_remote),
+                });
+                default:
+                    return (0, files_1.performFileAction)(this.root, name, a);
+            }
+        }
+    }
+}
+exports.NativeExecutor = NativeExecutor;

package/out/executor/notebook.d.ts

@@ -0,0 +1,2 @@
+import { RunResult } from "./shell";
+export declare function readNotebook(root: string, path: string, includeOutput?: boolean): RunResult;

package/out/executor/notebook.js

@@ -0,0 +1,147 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readNotebook = readNotebook;
+/**
+ * Reading a Jupyter notebook.
+ *
+ * Specification: docs/modules/CODING_AGENT_BUILD_SPECIFICATION.md, register
+ * item D4.
+ *
+ * A notebook is JSON on disk, and reading it with `read_file` gives you that
+ * JSON: source split into one string per line, escaped newlines, and base64
+ * images that can run to hundreds of kilobytes. A model handed that spends a
+ * fortune reading almost nothing.
+ *
+ * So this reads the cells. Code, markdown, and what each cell actually printed,
+ * because in a notebook the output IS the state: a cell that raised is the
+ * whole reason somebody is looking, and a variable's value three cells up is
+ * often the only record of what the data looked like.
+ *
+ * **Images are named, never included.** A plot is the point of many cells and
+ * it is also a quarter of a megabyte of base64. The cell says a plot was
+ * produced, which is the useful fact, at a cost of nine words.
+ */
+const fs = __importStar(require("fs"));
+const paths_1 = require("./paths");
+/** What one notebook may contribute. Beyond this it is cut and says so. */
+const MAX_CHARS = 60_000;
+/** What one cell's output may contribute. A cell that printed a whole dataframe
+ *  is common, and the first thirty lines of it say the same thing as all of it. */
+const MAX_OUTPUT_CHARS = 2_000;
+/** Source arrives as one string per line, with the newlines still on them. */
+function text(source) {
+    if (Array.isArray(source))
+        return source.join("");
+    return String(source ?? "");
+}
+function outputOf(cell) {
+    const parts = [];
+    for (const out of cell.outputs ?? []) {
+        const kind = String(out.output_type ?? "");
+        if (kind === "stream") {
+            parts.push(text(out.text));
+            continue;
+        }
+        if (kind === "error") {
+            // The most valuable thing in the file. A traceback is usually the reason
+            // somebody opened the notebook at all, so it is never trimmed away first.
+            const name = String(out.ename ?? "error");
+            const message = String(out.evalue ?? "");
+            const trace = Array.isArray(out.traceback) ? out.traceback.join("\n") : "";
+            parts.push(`${name}: ${message}\n${trace}`);
+            continue;
+        }
+        if (kind === "execute_result" || kind === "display_data") {
+            const data = (out.data ?? {});
+            if (data["text/plain"]) {
+                parts.push(text(data["text/plain"]));
+            }
+            // Named, not included. A plot is the point of the cell and also a quarter
+            // of a megabyte of base64; "a plot was produced" is the useful fact.
+            for (const mime of Object.keys(data)) {
+                if (mime.startsWith("image/"))
+                    parts.push(`[${mime} produced, not shown]`);
+            }
+        }
+    }
+    const joined = parts.join("\n").trim();
+    if (joined.length <= MAX_OUTPUT_CHARS)
+        return joined;
+    return `${joined.slice(0, MAX_OUTPUT_CHARS)}\n[... output truncated]`;
+}
+function readNotebook(root, path, includeOutput = true) {
+    let raw;
+    try {
+        raw = fs.readFileSync((0, paths_1.resolveInside)(root, path, true), "utf8");
+    }
+    catch (err) {
+        return { isError: true, content: `Could not read ${path}: ${err.message}` };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return {
+            isError: true,
+            content: `${path} is not a readable notebook. It may be corrupt, or it may not be a notebook at all.`,
+        };
+    }
+    const cells = parsed.cells ?? [];
+    if (!cells.length) {
+        return { content: `${path} has no cells in it.`, summary: "empty notebook" };
+    }
+    const lines = [`${path}: ${cells.length} cells`];
+    let used = lines[0].length;
+    for (let i = 0; i < cells.length; i += 1) {
+        const cell = cells[i];
+        const kind = cell.cell_type ?? "code";
+        // Numbered, because that is how a person refers to a cell and how an edit
+        // will have to name one later.
+        const header = `\n--- cell ${i + 1} (${kind}) ---`;
+        const source = text(cell.source).trimEnd();
+        const output = includeOutput && kind === "code" ? outputOf(cell) : "";
+        const block = [header, source, output ? `\n[output]\n${output}` : ""]
+            .filter(Boolean).join("\n");
+        if (used + block.length > MAX_CHARS) {
+            lines.push(`\n[... ${cells.length - i} more cells not read. Ask for a range if you need them.]`);
+            break;
+        }
+        lines.push(block);
+        used += block.length;
+    }
+    return { content: lines.join("\n"), summary: `read ${path} (${cells.length} cells)` };
+}

package/out/executor/paths.d.ts

@@ -0,0 +1,15 @@
+export declare class OutsideWorkspace extends Error {
+    readonly attempted: string;
+    constructor(attempted: string);
+}
+export declare function isSecret(p: string): boolean;
+/**
+ * An absolute path inside the workspace, or a refusal.
+ *
+ * `mustExist` is false when the caller is about to CREATE the thing. A file that
+ * does not exist yet cannot be resolved, so the check is applied to the deepest
+ * parent that does exist: creating `src/new/deep/file.ts` is inside the project
+ * exactly when `src` is, and demanding the leaf exist first would make it
+ * impossible to write a new file at all.
+ */
+export declare function resolveInside(root: string, rel: string, mustExist?: boolean): string;