@magland/gentl 0.0.0-stage → 0.1.0

package/dist/hub.js

@@ -0,0 +1,147 @@
+// The hub client: fetch tasks from a gentl hub, upload runs to the hub their task came from, and remember the
+// name and passcode to use for each hub (in ~/.config/gentl/hubs.json, readable only by you).
+import { execFileSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import * as readline from "node:readline";
+/** A task page URL (https://<hub>/tasks/<id>), or null if `s` is not one. */
+export function parseHubTaskUrl(s) {
+    const m = s.match(/^(https?:\/\/[^/]+)\/tasks\/(\d+)\/?$/);
+    return m ? { hub: m[1], id: Number(m[2]) } : null;
+}
+export async function fetchHubTask(url) {
+    const p = parseHubTaskUrl(url);
+    if (!p)
+        throw new Error(`not a hub task URL: ${url} (expected https://<hub>/tasks/<id>)`);
+    const r = await fetch(`${p.hub}/api/tasks/${p.id}`);
+    if (!r.ok)
+        throw new Error(`could not fetch task ${p.id} from ${p.hub}: HTTP ${r.status} ${(await r.text()).slice(0, 200)}`);
+    const { task } = (await r.json());
+    return { hub: p.hub, id: task.id, title: task.title, text: task.text.trim(), url: `${p.hub}/tasks/${task.id}` };
+}
+// ---------- credentials ----------
+function configPath() {
+    const base = process.env.XDG_CONFIG_HOME || path.join(os.homedir(), ".config");
+    return path.join(base, "gentl", "hubs.json");
+}
+function readConfig() {
+    try {
+        return JSON.parse(fs.readFileSync(configPath(), "utf8"));
+    }
+    catch {
+        return { hubs: {} };
+    }
+}
+function saveCredentials(hub, creds) {
+    const file = configPath();
+    const config = readConfig();
+    config.hubs[hub] = creds;
+    fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+    fs.writeFileSync(file, JSON.stringify(config, null, 2) + "\n", { mode: 0o600 });
+    fs.chmodSync(file, 0o600);
+}
+function ask(question, hidden = false) {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout, terminal: true });
+    let muted = false;
+    if (hidden)
+        rl._writeToOutput = (s) => { if (!muted)
+            process.stdout.write(s); };
+    return new Promise((resolve, reject) => {
+        let answered = false;
+        rl.on("close", () => { if (!answered)
+            reject(new Error("cancelled")); });
+        rl.question(question, (answer) => {
+            answered = true;
+            rl.close();
+            if (hidden)
+                process.stdout.write("\n");
+            resolve(answer.trim());
+        });
+        muted = true;
+    });
+}
+function gitUserName() {
+    try {
+        return execFileSync("git", ["config", "user.name"], { encoding: "utf8" }).trim();
+    }
+    catch {
+        return "";
+    }
+}
+/** Name and passcode for a hub: from GENTL_HUB_USER and GENTL_HUB_PASSCODE, the saved config, or by asking. */
+export async function hubCredentials(hub) {
+    const saved = readConfig().hubs[hub];
+    const user = process.env.GENTL_HUB_USER || saved?.user;
+    const passcode = process.env.GENTL_HUB_PASSCODE || saved?.passcode;
+    if (user && passcode)
+        return { user, passcode };
+    if (!process.stdin.isTTY)
+        throw new Error(`no credentials for ${hub}: set GENTL_HUB_USER and GENTL_HUB_PASSCODE, or run gentl upload in a terminal once`);
+    console.log(`Uploading to ${hub} needs your name (shown with your runs) and the hub's passcode.`);
+    const def = user || gitUserName();
+    const name = (await ask(`Your name${def ? ` [${def}]` : ""}: `)) || def;
+    if (!name)
+        throw new Error("a name is required");
+    const code = passcode || (await ask("Passcode: ", true));
+    if (!code)
+        throw new Error("a passcode is required");
+    const creds = { user: name, passcode: code };
+    const remember = (await ask(`Remember them in ${configPath()}? [y/n] `)).toLowerCase();
+    if (remember === "y" || remember === "yes")
+        saveCredentials(hub, creds);
+    return creds;
+}
+// ---------- upload ----------
+function readJsonl(file) {
+    return fs.readFileSync(file, "utf8").split("\n").filter(Boolean).map((l) => JSON.parse(l));
+}
+/** The hub a run's task came from, or null for a local task. */
+export function runHub(runDir) {
+    const s = JSON.parse(fs.readFileSync(path.join(runDir, "summary.json"), "utf8"));
+    return s.task_source?.kind === "hub" ? s.task_source.hub : null;
+}
+/** The upload payload: summary, evaluation, final state, and each turn as the agent saw it (not full results). */
+export function buildUpload(runDir, user) {
+    const read = (f) => (fs.existsSync(path.join(runDir, f)) ? fs.readFileSync(path.join(runDir, f), "utf8") : null);
+    const summary = JSON.parse(read("summary.json"));
+    const evaluation = read("evaluation.json");
+    const turns = readJsonl(path.join(runDir, "events.jsonl")).filter((e) => e.type === "turn").map((e) => ({
+        turn: e.turn,
+        notes_tokens: e.notes_tokens,
+        result_tokens: e.result_tokens,
+        notes: e.notes ?? null,
+        notes_ops: e.notes_ops ?? null,
+        action: e.parsed?.action ?? null,
+        result_shown: e.result_shown ?? null,
+        result_full_chars: typeof e.result_full === "string" ? e.result_full.length : null,
+        parse_error: e.parse_error ?? null,
+        raw_response: e.parse_error ? e.response : null,
+        notes_reminder: !!e.notes_reminder,
+    }));
+    return { user, summary, evaluation: evaluation ? JSON.parse(evaluation) : null, final_state: read("final-state.md"), turns };
+}
+/** Upload a run to the hub its task came from. Returns the run's page URL. */
+export async function uploadRun(runDir, creds) {
+    const hub = runHub(runDir);
+    if (!hub)
+        throw new Error(`${runDir}: its task did not come from a hub, so there is nowhere to upload it`);
+    const r = await fetch(`${hub}/api/runs`, {
+        method: "POST",
+        headers: { "content-type": "application/json", authorization: `Bearer ${creds.passcode}` },
+        body: JSON.stringify(buildUpload(runDir, creds.user)),
+    });
+    const text = await r.text();
+    if (r.status !== 201)
+        throw new Error(`upload to ${hub} failed: HTTP ${r.status} ${text.slice(0, 300)}`);
+    return `${hub}/runs/${JSON.parse(text).id}`;
+}
+/** Run directories under `dir`: the directory itself if it is a run, else its subdirectories that are runs (a batch). */
+export function runDirsIn(dir) {
+    if (fs.existsSync(path.join(dir, "summary.json")))
+        return [dir];
+    return fs.readdirSync(dir, { withFileTypes: true })
+        .filter((e) => e.isDirectory() && fs.existsSync(path.join(dir, e.name, "summary.json")))
+        .map((e) => path.join(dir, e.name))
+        .sort();
+}

package/dist/localcopy.js

@@ -0,0 +1,116 @@
+// The local copy: clones of your repo's origin URL are served from a temporary bare mirror of your checkout,
+// including uncommitted changes as an extra commit, so you can edit docs and rerun without pushing.
+// The sandbox's git config gets url.<mirror>.insteadOf <origin URL variants>, so the agent runs the git clone the
+// task names and gets your working copy.
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { execLocal } from "./sandbox.js";
+/** Info recorded in summary.json. */
+export function localCopyInfo(lc) {
+    return { repo: lc.repo, origin: lc.origin, urls: lc.urls, branch: lc.branch, head: lc.head,
+        uncommitted_commit: lc.uncommitted_commit, uncommitted_files: lc.uncommitted_files };
+}
+function git(args, opts = {}) {
+    return execLocal("git", args, { cwd: opts.cwd, env: opts.env ? { ...process.env, ...opts.env } : undefined });
+}
+/** URL forms a task might use for the same repo: https, http, scp-style ssh and ssh://, each with and without .git. */
+export function urlVariants(origin) {
+    const m = origin.match(/^(?:https?:\/\/(?:[^@/]+@)?([^/]+)\/(.+?)|git@([^:]+):(.+?)|ssh:\/\/(?:[^@/]+@)?([^/:]+)(?::\d+)?\/(.+?))(?:\.git)?\/?$/);
+    if (!m)
+        return [origin];
+    const host = m[1] ?? m[3] ?? m[5];
+    const repoPath = m[2] ?? m[4] ?? m[6];
+    const forms = [`https://${host}/${repoPath}`, `http://${host}/${repoPath}`, `git@${host}:${repoPath}`, `ssh://git@${host}/${repoPath}`];
+    return [...new Set([origin, ...forms.flatMap((f) => [f, `${f}.git`])])];
+}
+/** URLs in the task text that a variant would also rewrite by prefix (e.g. owner/foo-extra for owner/foo). */
+export function prefixCollisions(task, urls) {
+    const found = new Set();
+    for (const u of urls) {
+        const re = new RegExp(u.replace(/[.*+?^${}()|[\]\\]/g, "\\$&") + "([A-Za-z0-9_-][^\\s)\"'`]*)", "g");
+        for (const m of task.matchAll(re))
+            found.add(m[0]);
+    }
+    return [...found];
+}
+/** The repo to mirror: the git checkout containing `dir`, if it has an origin. Returns a reason when there is none. */
+export function findRepo(dir) {
+    const top = git(["rev-parse", "--show-toplevel"], { cwd: dir });
+    if (!top.ok)
+        return { reason: `${dir} is not in a git repo` };
+    const repo = top.out.trim();
+    const origin = git(["remote", "get-url", "origin"], { cwd: repo });
+    if (!origin.ok)
+        return { reason: `${repo} has no origin remote` };
+    return { repo, origin: origin.out.trim() };
+}
+/** Make the mirror: a bare clone of the checkout, with uncommitted changes (tracked and untracked, not ignored)
+ * committed on top of HEAD. Your own repo, index and working tree are not modified. */
+export function prepareLocalCopy(repo, origin) {
+    const mirrorDir = fs.mkdtempSync(path.join(os.tmpdir(), "gentl-mirror-"));
+    const name = (origin.replace(/\/$/, "").split(/[/:]/).pop() ?? "repo").replace(/\.git$/, "").replace(/[^A-Za-z0-9_.-]/g, "-") || "repo";
+    const mirrorName = `${name}.git`;
+    const mirror = path.join(mirrorDir, mirrorName);
+    const clone = git(["clone", "--quiet", "--bare", repo, mirror]);
+    if (!clone.ok)
+        throw new Error(`could not mirror ${repo}: ${clone.out.trim()}`);
+    const branchRef = git(["symbolic-ref", "-q", "HEAD"], { cwd: repo });
+    const branch = branchRef.ok ? branchRef.out.trim().replace(/^refs\/heads\//, "") : null;
+    const head = git(["rev-parse", "HEAD"], { cwd: repo }).out.trim();
+    // Honor the checkout's own excludes (.git/info/exclude), which git would not read with GIT_DIR set to the mirror.
+    const exclude = git(["rev-parse", "--path-format=absolute", "--git-path", "info/exclude"], { cwd: repo }).out.trim();
+    if (exclude && fs.existsSync(exclude)) {
+        fs.mkdirSync(path.join(mirror, "info"), { recursive: true });
+        fs.copyFileSync(exclude, path.join(mirror, "info", "exclude"));
+    }
+    // Build a tree of the working copy with a temporary index, writing objects into the mirror only.
+    const index = path.join(mirrorDir, "index");
+    const env = { GIT_DIR: mirror, GIT_WORK_TREE: repo, GIT_INDEX_FILE: index };
+    const steps = [["read-tree", head], ["add", "-A"]];
+    for (const args of steps) {
+        const r = git(args, { cwd: repo, env });
+        if (!r.ok)
+            throw new Error(`could not record uncommitted changes (git ${args.join(" ")}): ${r.out.trim()}`);
+    }
+    const tree = git(["write-tree"], { cwd: repo, env }).out.trim();
+    fs.rmSync(index, { force: true });
+    const headTree = git(["--git-dir", mirror, "rev-parse", `${head}^{tree}`]).out.trim();
+    let uncommitted = null;
+    let files = 0;
+    if (tree && tree !== headTree) {
+        files = git(["--git-dir", mirror, "diff-tree", "-r", "--name-only", headTree, tree]).out.split("\n").filter(Boolean).length;
+        // An ordinary-looking commit under your identity, so the agent has no reason to dig into where its clone came from.
+        const name = git(["config", "user.name"], { cwd: repo }).out.trim() || "gentl";
+        const email = git(["config", "user.email"], { cwd: repo }).out.trim() || "gentl@localhost";
+        const ident = { GIT_AUTHOR_NAME: name, GIT_AUTHOR_EMAIL: email, GIT_COMMITTER_NAME: name, GIT_COMMITTER_EMAIL: email };
+        const c = git(["--git-dir", mirror, "commit-tree", tree, "-p", head, "-m", "Work in progress"], { env: ident });
+        if (!c.ok)
+            throw new Error(`could not commit uncommitted changes: ${c.out.trim()}`);
+        uncommitted = c.out.trim();
+        const ref = branch ? ["update-ref", `refs/heads/${branch}`, uncommitted] : ["update-ref", "--no-deref", "HEAD", uncommitted];
+        git(["--git-dir", mirror, ...ref]);
+    }
+    return { repo, origin, urls: urlVariants(origin), branch, head, uncommitted_commit: uncommitted,
+        uncommitted_files: files, mirrorDir, mirrorName };
+}
+export function describeLocalCopy(lc) {
+    const at = `${lc.branch ?? "detached HEAD"} @ ${lc.head.slice(0, 7)}`;
+    const extra = lc.uncommitted_commit ? ` + uncommitted changes in ${lc.uncommitted_files} file(s)` : "";
+    return `clones of ${lc.origin} are served from your checkout ${lc.repo} (${at}${extra})`;
+}
+/** Point the sandbox's git at the mirror. `mirrorPath` is where the mirror is seen inside the sandbox. */
+export function configureLocalCopy(sb, lc, mirrorPath) {
+    const url = `file://${mirrorPath}`;
+    for (const u of lc.urls) {
+        const r = sb.exec(["git", "config", "--global", "--add", `url.${url}.insteadOf`, u]);
+        if (!r.ok)
+            return `could not configure git in the sandbox: ${r.out.trim()}`;
+    }
+    // The mirror belongs to another user inside a container; without this git refuses to clone it.
+    sb.exec(["git", "config", "--global", "--add", "safe.directory", mirrorPath]);
+    return null;
+}
+export function removeLocalCopy(lc) {
+    fs.rmSync(lc.mirrorDir, { recursive: true, force: true });
+}

package/dist/model.js

@@ -0,0 +1,112 @@
+// Model backends. "openrouter": an OpenAI-compatible chat completions endpoint (OpenRouter by default).
+// "claude-code": the user's Claude Code login, through `claude -p` (see claude.ts).
+import { ClaudeCodeClient } from "./claude.js";
+/** `cwd` is where a claude-code call runs; ideally a directory that matches the agent's working directory. */
+export function createModelClient(cfg, schema, log, cwd) {
+    return cfg.backend === "claude-code" ? new ClaudeCodeClient(cfg.model, schema, log, cwd) : new OpenAIClient(cfg, schema, log);
+}
+export class Interrupted extends Error {
+    constructor() {
+        super("interrupted");
+    }
+}
+export const RETRY_DELAYS_S = [2, 5, 15];
+/** Wait before a retry; Ctrl-C ends the wait. */
+export async function retryWait(attempt, why, signal, log) {
+    const s = RETRY_DELAYS_S[attempt];
+    log(`${why}; retrying in ${s} s`);
+    await new Promise((resolve, reject) => {
+        const t = setTimeout(resolve, s * 1000);
+        signal.addEventListener("abort", () => {
+            clearTimeout(t);
+            reject(new Interrupted());
+        }, { once: true });
+    });
+}
+class OpenAIClient {
+    cfg;
+    schema;
+    log;
+    structured = true;
+    openrouter;
+    /** `schema` is the JSON schema requested for responses (structured output). */
+    constructor(cfg, schema, log) {
+        this.cfg = cfg;
+        this.schema = schema;
+        this.log = log;
+        this.openrouter = cfg.baseUrl.includes("openrouter.ai");
+    }
+    async call(system, user, signal) {
+        for (let attempt = 0;; attempt++) {
+            let r;
+            try {
+                r = await fetch(`${this.cfg.baseUrl.replace(/\/$/, "")}/chat/completions`, {
+                    method: "POST",
+                    headers: { Authorization: `Bearer ${this.cfg.apiKey}`, "Content-Type": "application/json" },
+                    body: JSON.stringify(this.body(system, user)),
+                    signal,
+                });
+            }
+            catch (e) {
+                if (signal.aborted)
+                    throw new Interrupted();
+                if (attempt >= RETRY_DELAYS_S.length)
+                    throw new Error(`model call failed: ${e.message}`);
+                await retryWait(attempt, `network error: ${e.message}`, signal, this.log);
+                continue;
+            }
+            const raw = await r.text().catch(() => "");
+            if (r.ok) {
+                let d;
+                try {
+                    d = JSON.parse(raw);
+                }
+                catch {
+                    d = { error: { message: `response is not JSON: ${raw.slice(0, 200)}` } };
+                }
+                if (!d.error && d.choices?.[0]?.message) {
+                    return { text: d.choices[0].message.content ?? "", usage: d.usage ?? {} };
+                }
+                if (this.structured) {
+                    this.fallBack(`error in response: ${JSON.stringify(d.error ?? d).slice(0, 200)}`);
+                    attempt--;
+                    continue;
+                }
+                if (attempt >= RETRY_DELAYS_S.length)
+                    throw new Error(`model call failed: ${JSON.stringify(d.error ?? d).slice(0, 500)}`);
+                await retryWait(attempt, `error in response: ${JSON.stringify(d.error ?? d).slice(0, 200)}`, signal, this.log);
+                continue;
+            }
+            if (this.structured && [400, 404, 422].includes(r.status)) {
+                this.fallBack(`HTTP ${r.status}: ${raw.slice(0, 200)}`);
+                attempt--;
+                continue;
+            }
+            const retryable = r.status === 429 || r.status >= 500;
+            if (!retryable || attempt >= RETRY_DELAYS_S.length)
+                throw new Error(`model call failed: HTTP ${r.status} ${raw.slice(0, 500)}`);
+            await retryWait(attempt, `HTTP ${r.status}`, signal, this.log);
+        }
+    }
+    fallBack(why) {
+        this.structured = false;
+        this.log(`structured output failed (${why}); using plain text from now on`);
+    }
+    body(system, user) {
+        const body = {
+            model: this.cfg.model,
+            max_tokens: 8000,
+            messages: [{ role: "system", content: system }, { role: "user", content: user }],
+        };
+        if (this.structured) {
+            body.response_format = { type: "json_schema", json_schema: { name: this.schema.name, strict: true, schema: this.schema.schema } };
+        }
+        if (this.openrouter) {
+            body.usage = { include: true };
+            // Only route to providers that honor response_format.
+            if (this.structured)
+                body.provider = { require_parameters: true };
+        }
+        return body;
+    }
+}

package/dist/protocol.js

@@ -0,0 +1,188 @@
+// What the agent sees and how its responses are parsed.
+export const ACTION_TYPES = ["run", "write_file", "edit_file", "ask", "finish"];
+export const ASK_RESULT = "No one is available to answer. Your question is recorded as a gap in the docs. Decide from the docs and code as best you can.";
+export const DEFAULT_MAX_CHARS = 2000;
+export const MAX_MAX_CHARS = 20000;
+export const CMD_TIMEOUT_S = 300;
+export function systemPrompt(workdir, platform) {
+    return `You are a newcomer to some software, carrying out a task on a ${platform} machine with internet access. Your working directory is ${workdir}; it starts empty. Tools include git, curl and w3m (\`w3m -dump URL\` renders a web page as plain text).
+
+Treat the software as unfamiliar. Go by its docs and code, not by what you remember about it, since the version here may differ.
+
+This is a test of how readable the software and its docs are. We count the tokens you read (every result you see, plus your notes each turn) as a proxy for the effort a human newcomer would need, and we collect what was missing or unclear. So read in a targeted way (grep, sed -n, head, --help) rather than dumping whole files or long pages. When the docs and code don't answer something you need, don't keep searching or guess silently: use the ask action, then make a reasonable decision and move on. A gap in the docs is useful feedback, not a failure on your part.
+
+You have no memory between turns. Each turn you see only the task, your notes, and your last action with its result. The result is shown once and is gone on the next turn; your notes are all you carry forward. They are your working memory, like what a person can hold in their head at once. They start empty.
+
+So every turn has two steps. First, update your notes: if the result (or the task, on the first turn) tells you something you will need later, such as a fact, a path, a command that worked, what is done or what is next, record it and set "notes_keep": false. Only if nothing is worth keeping, set "notes_keep": true. Second, choose the action. Keep the notes small, with only what you still need; they are counted every turn.
+
+Each turn, respond with one JSON object and nothing else:
+{"notes_keep": false, "notes": "...", "notes_edit": {"old": "...", "new": "..."}, "notes_append": "...", "action": {...}}
+"notes_keep" and "action" are required. With "notes_keep": false, give at least one of "notes" (replaces your notes), "notes_edit" (replaces text that occurs exactly once in them) and "notes_append" (adds a line at the end); they are applied in that order. "notes_keep": true leaves your notes as they are.
+
+Actions:
+- {"type": "run", "cmd": "..."}: run with bash in your working directory. Each command starts a fresh shell (cd and exported variables do not persist) with no input. stdout and stderr are combined; output longer than ${DEFAULT_MAX_CHARS} characters is cut in the middle (add "max_chars": N, at most ${MAX_MAX_CHARS}, to see more). Timeout ${CMD_TIMEOUT_S} s.
+- {"type": "write_file", "path": "...", "content": "..."}: create or overwrite a file. Relative paths are under your working directory.
+- {"type": "edit_file", "path": "...", "old": "...", "new": "..."}: replace text that occurs exactly once in the file.
+- {"type": "ask", "question": "..."}: ask the maintainers something the docs and code don't tell you. No one will answer during this test; the question is recorded as feedback on the docs.
+- {"type": "finish", "success": true|false, "summary": "...", "friction": "..."}: end the task. Verify your work before finishing. If success is true, the summary must cite the evidence: what you ran and what it showed. "friction" (optional) is what in the docs was missing, wrong or unclear, and where you had to guess.
+
+A person watching may decline an action; the result then says so, with their reason if they gave one.`;
+}
+/** JSON schema for the response, sent to endpoints that support structured output. Each action is its own
+ * variant with its fields required, since optional fields make grammar compilation slow (it timed out on Anthropic). */
+const obj = (properties, required) => ({ type: "object", properties, required, additionalProperties: false });
+const str = { type: "string" };
+const actionType = (t) => ({ type: "string", enum: [t] });
+export const RESPONSE_SCHEMA = obj({
+    notes_keep: { type: "boolean" },
+    notes: str,
+    notes_edit: obj({ old: str, new: str }, ["old", "new"]),
+    notes_append: str,
+    action: {
+        anyOf: [
+            obj({ type: actionType("run"), cmd: str, max_chars: { type: "integer" } }, ["type", "cmd"]),
+            obj({ type: actionType("write_file"), path: str, content: str }, ["type", "path", "content"]),
+            obj({ type: actionType("edit_file"), path: str, old: str, new: str }, ["type", "path", "old", "new"]),
+            obj({ type: actionType("ask"), question: str }, ["type", "question"]),
+            obj({ type: actionType("finish"), success: { type: "boolean" }, summary: str, friction: str }, ["type", "success", "summary"]),
+        ],
+    },
+}, ["notes_keep", "action"]);
+function isObject(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+/** Index of the brace closing the object that starts at `start`, or -1. */
+function matchBrace(s, start) {
+    let depth = 0;
+    let inString = false;
+    for (let j = start; j < s.length; j++) {
+        const c = s[j];
+        if (inString) {
+            if (c === "\\")
+                j++;
+            else if (c === '"')
+                inString = false;
+        }
+        else if (c === '"')
+            inString = true;
+        else if (c === "{")
+            depth++;
+        else if (c === "}" && --depth === 0)
+            return j;
+    }
+    return -1;
+}
+/** The first JSON object in the text that satisfies `accept`; anything around it is ignored. */
+export function parseFirstJson(text, accept) {
+    for (let i = text.indexOf("{"); i !== -1; i = text.indexOf("{", i + 1)) {
+        const end = matchBrace(text, i);
+        if (end === -1)
+            continue;
+        let v;
+        try {
+            v = JSON.parse(text.slice(i, end + 1));
+        }
+        catch {
+            continue;
+        }
+        if (isObject(v) && accept(v))
+            return v;
+    }
+    throw new Error("no matching JSON object was found");
+}
+/** The first JSON object in the text that contains an "action" object. */
+export function parseResponse(text) {
+    try {
+        return parseFirstJson(text, (v) => isObject(v.action));
+    }
+    catch {
+        throw new Error('no JSON object with an "action" object was found');
+    }
+}
+export function countOccurrences(text, sub) {
+    return sub === "" ? 0 : text.split(sub).length - 1;
+}
+/** Whether the response makes a notes decision: an operation, or "notes_keep": true. */
+export function hasNotesDecision(r) {
+    return r.notes !== undefined || r.notes_edit !== undefined || r.notes_append !== undefined || r.notes_keep === true;
+}
+/** The reminder sent, within the same turn, when a response has no notes decision. */
+export const NOTES_REMINDER = 'Your response did not update your notes or set "notes_keep": true. The result above will be gone on the next turn. Respond again with your notes update ("notes", "notes_edit" or "notes_append"), or "notes_keep": true if nothing is worth keeping, together with your action.';
+/** Apply the notes operations in order (rewrite, edit, append). Problems are returned as feedback for the agent. */
+export function applyNotes(notes, r) {
+    const ops = [];
+    const feedback = [];
+    if (r.notes !== undefined) {
+        if (typeof r.notes === "string") {
+            notes = r.notes;
+            ops.push("rewritten");
+        }
+        else
+            feedback.push('"notes" must be a string; it was ignored.');
+    }
+    if (r.notes_edit !== undefined) {
+        const e = r.notes_edit;
+        if (!isObject(e) || typeof e.old !== "string" || typeof e.new !== "string") {
+            feedback.push('"notes_edit" must be {"old": string, "new": string}; it was ignored.');
+        }
+        else {
+            const n = countOccurrences(notes, e.old);
+            if (n !== 1)
+                feedback.push(`notes_edit failed: the old text occurs ${n} times in your notes; it must occur exactly once.`);
+            else {
+                const replacement = e.new;
+                notes = notes.replace(e.old, () => replacement);
+                ops.push("edited");
+            }
+        }
+    }
+    if (r.notes_append !== undefined) {
+        if (typeof r.notes_append === "string") {
+            notes = notes ? `${notes}\n${r.notes_append}` : r.notes_append;
+            ops.push("appended");
+        }
+        else
+            feedback.push('"notes_append" must be a string; it was ignored.');
+    }
+    return { notes, ops, feedback };
+}
+/** Why the action is malformed, or null if it is fine. */
+export function validateAction(a) {
+    const str = (k) => typeof a[k] === "string";
+    switch (a.type) {
+        case "run":
+            if (!str("cmd"))
+                return 'run needs "cmd" (string)';
+            if (a.max_chars !== undefined && typeof a.max_chars !== "number")
+                return '"max_chars" must be a number';
+            return null;
+        case "write_file":
+            return str("path") && str("content") ? null : 'write_file needs "path" and "content" (strings)';
+        case "edit_file":
+            return str("path") && str("old") && str("new") ? null : 'edit_file needs "path", "old" and "new" (strings)';
+        case "ask":
+            return str("question") ? null : 'ask needs "question" (string)';
+        case "finish":
+            if (typeof a.success !== "boolean" || !str("summary"))
+                return 'finish needs "success" (boolean) and "summary" (string)';
+            if (a.friction !== undefined && !str("friction"))
+                return '"friction" must be a string';
+            return null;
+        default:
+            return `unknown action type ${JSON.stringify(a.type)}; use ${ACTION_TYPES.join(", ")}`;
+    }
+}
+/** The action as echoed back to the agent on the next turn. Files are shown by path only. */
+export function describeAction(a) {
+    switch (a.type) {
+        case "run":
+            return a.max_chars !== undefined && a.max_chars !== DEFAULT_MAX_CHARS ? `run (max_chars ${a.max_chars}): ${a.cmd}` : `run: ${a.cmd}`;
+        case "write_file":
+        case "edit_file":
+            return `${a.type}: ${a.path}`;
+        case "ask":
+            return `ask: ${a.question}`;
+        default:
+            return JSON.stringify(a);
+    }
+}