@dynamicagents/plugins 0.14.0 → 0.16.0

package/dist/repo-github/sandbox-egress.js

@@ -0,0 +1,272 @@
+import { CREDENTIAL_HEADERS, forward } from "../sandbox/egress.js";
+import { PROTECTED_BRANCHES } from "./url.js";
+/**
+ * GitHub from inside a sandbox, with the token on the Worker side: the
+ * sandbox's egress rule for it.
+ *
+ * The harness intercepts `github.com` over HTTPS, and git's credential helper
+ * answers with {@link GITHUB_TOKEN_PLACEHOLDER}. **Never an `insteadOf` onto a
+ * placeholder host:** git reports the rewritten URL to whatever reads a remote
+ * (`git remote get-url`, `git remote -v`), so `/repo` would take a checkout's
+ * origin for a host it does not allow, and `gh` would find no GitHub remote. A
+ * sandbox allowed the API intercepts `api.github.com` too, and gives `gh` the
+ * placeholder as `GH_TOKEN`.
+ *
+ * The egress swaps the placeholder for the real token, so a process can *use*
+ * GitHub as the deployment's account and never *read* the token. A request
+ * that presents no placeholder goes out anonymous, as it would anywhere else.
+ *
+ * Any process in the container can present the placeholder, a model's own
+ * shell included, so what `repo_push` refuses is refused here too, for every
+ * credentialed push: a ref that is not a branch, a protected name, and the
+ * repository's own default branch, which work reaches through a pull request.
+ */
+/** What `GH_TOKEN` and git's credential helper hold. Shaped like a classic token, so nothing refuses it on shape. */
+export const GITHUB_TOKEN_PLACEHOLDER = "ghp_" + "0".repeat(36);
+/** Where git's own traffic goes. */
+const GIT_HOST = "github.com";
+/** The username GitHub expects beside a token in git's Basic auth. */
+const GIT_USER = "x-access-token";
+const API_HOST = "api.github.com";
+/** The egress rule of a sandbox whose processes use GitHub. */
+export function githubSandboxEgress(options) {
+    const api = options.api ?? false;
+    return {
+        name: "github",
+        https: {
+            [GIT_HOST]: `https://${GIT_HOST}`,
+            ...(api ? { [API_HOST]: `https://${API_HOST}` } : {})
+        },
+        env: githubEnv(api),
+        handle: (call) => githubEgress(call, options)
+    };
+}
+/**
+ * The environment a sandbox gives its processes.
+ *
+ * In the environment rather than a gitconfig file because a session's home is
+ * copied from the agent's when the session opens, so a `git config --global`
+ * written afterwards never reaches it; an environment reaches every process.
+ *
+ * `GH_TOKEN` only with the API intercepted: otherwise `gh` would send the
+ * placeholder to the real API, which refuses even a read anyone may make.
+ */
+function githubEnv(api) {
+    return {
+        ...(api ? { GH_TOKEN: GITHUB_TOKEN_PLACEHOLDER } : {}),
+        GIT_CONFIG_COUNT: "1",
+        GIT_CONFIG_KEY_0: `credential.https://${GIT_HOST}.helper`,
+        // Answers `get` only; `store` and `erase` are no-ops that still exit 0.
+        GIT_CONFIG_VALUE_0: `!f() { if test "$1" = get; then printf 'username=${GIT_USER}\\npassword=${GITHUB_TOKEN_PLACEHOLDER}\\n'; fi; }; f`
+    };
+}
+/** Anonymous unless the placeholder is presented; then the real token, and for a push, what it may update. */
+async function githubEgress(call, options) {
+    const presented = presentsPlaceholder(call.request.headers.get("authorization"));
+    const strip = (headers) => {
+        for (const name of CREDENTIAL_HEADERS)
+            headers.delete(name);
+    };
+    if (!presented)
+        return forward(call, strip);
+    const token = call.env[options.tokenBinding];
+    if (typeof token !== "string" || token === "") {
+        return githubError("no GitHub token is configured for this deployment, so nothing can be done as its account", 401);
+    }
+    const policy = options.push;
+    const git = new URL(call.request.url).hostname === GIT_HOST
+        ? gitTarget(call.target.pathname)
+        : undefined;
+    let body;
+    if (git) {
+        if (policy &&
+            !policy.repos.some((repo) => repo.toLowerCase() === git.repo)) {
+            return githubError(`this sandbox may not use ${git.repo} as the deployment's account`, 403);
+        }
+        if (git.service === "receive-pack" && call.request.method === "POST") {
+            const [inspected, forwarded] = (call.request.body ?? new Blob().stream()).tee();
+            const refuse = (message, status) => {
+                void forwarded.cancel().catch(() => undefined);
+                return githubError(message, status);
+            };
+            const refs = await receivePackRefs(inspected, call.request.headers.get("content-encoding")).catch(() => undefined);
+            if (!refs || refs.length === 0) {
+                return refuse("this push names no ref this egress can read", 400);
+            }
+            const defaultBranch = await defaultBranchOf(git.repo, token);
+            if (defaultBranch === undefined) {
+                return refuse(`could not read ${git.repo}'s default branch, so nothing was pushed: retry`, 503);
+            }
+            const refused = refs.flatMap((ref) => {
+                const why = refusal(ref, defaultBranch, policy);
+                return why ? [`${ref} (${why})`] : [];
+            });
+            if (refused.length > 0) {
+                return refuse(`this sandbox may not push ${refused.join(", ")}`, 403);
+            }
+            body = forwarded;
+        }
+    }
+    return forward(call, (headers) => {
+        strip(headers);
+        headers.set("authorization", githubAuthorization(presented, token));
+    }, body);
+}
+/** Why a push may not update `ref`, if it may not. */
+function refusal(ref, defaultBranch, policy) {
+    if (!ref.startsWith("refs/heads/"))
+        return "not a branch";
+    const branch = ref.slice("refs/heads/".length);
+    if (branch === defaultBranch)
+        return "the repository's default branch: work reaches it through a pull request";
+    if (PROTECTED_BRANCHES.has(branch))
+        return "a protected branch";
+    if (policy && !branchAllowed(policy, branch))
+        return `this sandbox may push ${policy.branches.join(", ")}`;
+    return undefined;
+}
+/** `repo`'s default branch, as the token sees it; `undefined` when it cannot be read. */
+async function defaultBranchOf(repo, token) {
+    try {
+        const response = await fetch(`https://${API_HOST}/repos/${repo}`, {
+            headers: {
+                authorization: `Bearer ${token}`,
+                accept: "application/vnd.github+json",
+                // GitHub refuses a request with none.
+                "user-agent": "dynamicagents-sandbox-egress"
+            }
+        });
+        if (!response.ok)
+            return undefined;
+        const found = (await response.json());
+        return typeof found.default_branch === "string" && found.default_branch
+            ? found.default_branch
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Whether `value` presents the placeholder: Bearer/`token` as `gh` sends it, or Basic `user:placeholder` as git does after a 401. */
+function presentsPlaceholder(value) {
+    if (!value)
+        return undefined;
+    const [scheme = "", credential = ""] = value.trim().split(/\s+/, 2);
+    switch (scheme.toLowerCase()) {
+        case "bearer":
+        case "token":
+            return credential === GITHUB_TOKEN_PLACEHOLDER ? "bearer" : undefined;
+        case "basic": {
+            let decoded;
+            try {
+                decoded = atob(credential);
+            }
+            catch {
+                return undefined;
+            }
+            const password = decoded.slice(decoded.indexOf(":") + 1);
+            return decoded.includes(":") && password === GITHUB_TOKEN_PLACEHOLDER
+                ? "basic"
+                : undefined;
+        }
+        default:
+            return undefined;
+    }
+}
+/** The real credential, in the scheme the placeholder came in. */
+function githubAuthorization(presented, token) {
+    return presented === "basic"
+        ? `Basic ${btoa(`${GIT_USER}:${token}`)}`
+        : `Bearer ${token}`;
+}
+/** A refusal in GitHub's error shape, which `gh` and git both print. */
+function githubError(message, status) {
+    return new Response(JSON.stringify({ message }), {
+        status,
+        headers: { "content-type": "application/json" }
+    });
+}
+/** `owner/repo` of a smart-HTTP git path, and which service it asks for. */
+export function gitTarget(pathname) {
+    const match = /^\/([^/]+)\/([^/]+?)(?:\.git)?\/(info\/refs|git-upload-pack|git-receive-pack)$/.exec(pathname);
+    if (!match)
+        return undefined;
+    const [, owner = "", name = "", tail = ""] = match;
+    const service = tail.endsWith("receive-pack")
+        ? "receive-pack"
+        : tail.endsWith("upload-pack")
+            ? "upload-pack"
+            : undefined;
+    return { repo: `${owner}/${name}`.toLowerCase(), service };
+}
+/** Whether `branch` is one the policy allows. */
+export function branchAllowed(policy, branch) {
+    return policy.branches.some((pattern) => pattern.endsWith("*")
+        ? branch.startsWith(pattern.slice(0, -1))
+        : branch === pattern);
+}
+/** A command list git would never send: thousands of refs fit well inside it. */
+const COMMANDS_MAX_BYTES = 1 << 20;
+/** pkt-line's own ceiling on one packet, its four length digits included. */
+const PKT_MAX = 65520;
+/**
+ * The refs a `git-receive-pack` request updates, from its pkt-line commands.
+ *
+ * Each command is `<old> <new> <ref>`, the first carrying `\0<capabilities>`,
+ * and the list ends at a flush packet; the pack follows. Only the list is read,
+ * so a caller hands this one branch of a `tee()` and forwards the other: the
+ * pack is never held in the Worker. git compresses the request body when it is
+ * large, so a gzip body is inflated as it is read.
+ *
+ * Read as strictly as git reads it, since the refs this returns are the ones a
+ * policy allows: a length is four hex digits, `0000` ends the list, and any
+ * other packet shorter than its own length or past the ceiling is refused
+ * rather than skipped. A ref is UTF-8, as git writes it.
+ */
+export async function receivePackRefs(body, encoding) {
+    const reader = (encoding?.toLowerCase() === "gzip"
+        ? body.pipeThrough(new DecompressionStream("gzip"))
+        : body).getReader();
+    const ascii = new TextDecoder("latin1");
+    const utf8 = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
+    const refs = [];
+    let buffer = new Uint8Array(0);
+    let read = 0;
+    try {
+        for (;;) {
+            while (buffer.length >= 4) {
+                const digits = ascii.decode(buffer.subarray(0, 4));
+                if (!/^[0-9a-f]{4}$/i.test(digits))
+                    throw new Error(`not a pkt-line length: ${JSON.stringify(digits)}`);
+                const length = Number.parseInt(digits, 16);
+                if (length === 0)
+                    return refs;
+                if (length < 4 || length > PKT_MAX)
+                    throw new Error(`a pkt-line of length ${length} is not a command`);
+                if (buffer.length < length)
+                    break;
+                const line = utf8.decode(buffer.subarray(4, length));
+                buffer = buffer.subarray(length);
+                const ref = line.split("\0", 1)[0]?.trim().split(" ")[2];
+                if (ref)
+                    refs.push(ref);
+            }
+            const chunk = await reader.read();
+            if (chunk.done)
+                return refs;
+            read += chunk.value.byteLength;
+            if (read > COMMANDS_MAX_BYTES)
+                throw new Error("the push's command list never ended");
+            const next = new Uint8Array(buffer.length + chunk.value.byteLength);
+            next.set(buffer);
+            next.set(chunk.value, buffer.length);
+            buffer = next;
+        }
+    }
+    finally {
+        // Not awaited: a tee branch's cancel settles only once the other branch is
+        // cancelled or read to its end, and the caller does neither until this
+        // returns.
+        void reader.cancel().catch(() => undefined);
+    }
+}

package/dist/repo-github/sandbox-git.d.ts

@@ -0,0 +1,30 @@
+import type { RepoGit } from "./index.js";
+/**
+ * The three credentialed operations, as `git` in a sandbox.
+ *
+ * The workspace ran them in its object, beside the token. Here they run where
+ * the checkout is, as the agent, with only the placeholder. The sandbox carries
+ * `githubSandboxEgress` (`./sandbox-egress.ts`), whose environment sends
+ * github.com to the intercepted host and whose handler swaps the token in and
+ * holds a push to its policy. So the container still never holds the token, and
+ * a push the policy refuses is refused before GitHub sees it.
+ *
+ * A host passes this as `RepoConfig.git`, and records the checkouts that are
+ * its own on the sandbox — `afterCheckout` is the place for the one `repo_clone`
+ * makes. This notes none: a clone may be a superproject's submodule, which is
+ * that superproject's checkout and not one of its own.
+ */
+/** The sandbox RPCs this uses. */
+export interface SandboxGitHost {
+    exec(argv: string[], options?: {
+        cwd?: string;
+        env?: Record<string, string>;
+        timeoutMs?: number;
+    }): Promise<{
+        exitCode: number;
+        stdout: string;
+        stderr: string;
+    }>;
+}
+/** @param sandbox Called per operation, so each reaches the object through a new stub. */
+export declare function sandboxRepoGit(sandbox: () => SandboxGitHost): RepoGit;

package/dist/repo-github/sandbox-git.js

@@ -0,0 +1,113 @@
+import { SANDBOX_ROOT } from "../sandbox/header.js";
+const LIMIT_MS = { clone: 10 * 60_000, fetch: 5 * 60_000, push: 5 * 60_000 };
+/** After `timeout`'s TERM, how long before its KILL. */
+const KILL_AFTER_S = 5;
+/**
+ * `timeout`'s exits for a git it ended: TERM taken, or KILL after a hook
+ * ignored it. Read as the limit only once the limit has passed, since any
+ * SIGKILL is a 137.
+ */
+const TIMED_OUT = new Set([124, 137]);
+/** @param sandbox Called per operation, so each reaches the object through a new stub. */
+export function sandboxRepoGit(sandbox) {
+    const git = async (cwd, args, limitMs) => {
+        const startedAt = Date.now();
+        const run = await sandbox().exec([
+            "timeout",
+            `--kill-after=${KILL_AFTER_S}`,
+            String(Math.ceil(limitMs / 1000)),
+            "git",
+            ...args
+        ], {
+            cwd,
+            // A credential prompt would wait out the limit: there is nobody to answer it.
+            env: { GIT_TERMINAL_PROMPT: "0" },
+            timeoutMs: limitMs + (KILL_AFTER_S + 5) * 1000
+        });
+        if (run.exitCode === 0)
+            return { ok: true, stdout: run.stdout, stderr: run.stderr };
+        const timedOut = TIMED_OUT.has(run.exitCode) && Date.now() - startedAt >= limitMs;
+        return {
+            ok: false,
+            code: timedOut ? "ETIMEDOUT" : `exit-${run.exitCode}`,
+            message: timedOut
+                ? `git ${args[0]} ran past its limit of ${limitMs / 60_000} minutes`
+                : run.stderr.trim() ||
+                    run.stdout.trim() ||
+                    `git ${args[0]} exited ${run.exitCode}`
+        };
+    };
+    return {
+        async clone(req) {
+            const refused = refuse(req.url, req.allowedHosts);
+            if (refused)
+                return refused;
+            const cloned = await git(SANDBOX_ROOT, [
+                "clone",
+                ...(req.depth ? ["--depth", String(req.depth)] : []),
+                ...(req.branch ? ["--branch", req.branch] : []),
+                "--",
+                req.url,
+                req.dir
+            ], LIMIT_MS.clone);
+            if (!cloned.ok)
+                return cloned;
+            // The branch's name, unborn too — an empty repository's — and `HEAD`
+            // for a checkout that landed detached, as one of a tag does.
+            const branch = await git(req.dir, ["symbolic-ref", "--short", "-q", "HEAD"], 30_000);
+            if (branch.ok)
+                return { ok: true, detail: branch.stdout.trim() };
+            const head = await git(req.dir, ["rev-parse", "--abbrev-ref", "HEAD"], 30_000);
+            return head.ok ? { ok: true, detail: head.stdout.trim() } : head;
+        },
+        async fetch(req) {
+            const refused = refuse(req.url, req.allowedHosts);
+            if (refused)
+                return refused;
+            const fetched = await git(req.dir, [
+                "fetch",
+                "--prune",
+                ...(req.depth ? ["--depth", String(req.depth)] : []),
+                "--",
+                req.url,
+                "+refs/heads/*:refs/remotes/origin/*"
+            ], LIMIT_MS.fetch);
+            return fetched.ok ? { ok: true, detail: `fetched ${req.url}` } : fetched;
+        },
+        async push(req) {
+            const refused = refuse(req.url, req.allowedHosts);
+            if (refused)
+                return refused;
+            // Never forced, and only the one branch, to its own name: no tag rides
+            // along, whatever `push.followTags` says.
+            const pushed = await git(req.dir, [
+                "push",
+                "--no-follow-tags",
+                "--",
+                req.url,
+                `refs/heads/${req.branch}:refs/heads/${req.branch}`
+            ], LIMIT_MS.push);
+            return pushed.ok
+                ? { ok: true, detail: pushed.stderr.trim() || `pushed ${req.branch}` }
+                : pushed;
+        }
+    };
+}
+/** A URL this may not use, as the answer; `undefined` for one it may. */
+function refuse(url, allowedHosts) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return { ok: false, code: "EINVAL", message: `not a URL: ${url}` };
+    }
+    if (parsed.protocol !== "https:" || !allowedHosts.includes(parsed.hostname)) {
+        return {
+            ok: false,
+            code: "EACCES",
+            message: `git may use https only, and only these hosts: ${allowedHosts.join(", ")}`
+        };
+    }
+    return undefined;
+}

package/dist/{repo → repo-github}/tools-checks.js

@@ -48,7 +48,7 @@ function listed(checks) {
         .join("\n");
 }
 export function checkTools(ctx) {
-    const { bounded, github, githubRepo } = ctx;
+    const { bounded, mcp, githubRepo } = ctx;
     return {
         repo_pr_checks: tool({
             description: "Say how a pull request's checks stand on its latest commit — CI that is still running, failed or passed — in the repository you have checked out. Use it to know whether CI has finished and what failed, without waiting inside a session for it.",
@@ -61,23 +61,62 @@ export function checkTools(ctx) {
                 if ("refusal" in target)
                     return target.refusal;
                 const { owner, repo } = target;
-                const pr = await github("repo_pr_checks", `/repos/${owner}/${repo}/pulls/${number}`);
+                const where = {
+                    owner: decodeURIComponent(owner),
+                    repo: decodeURIComponent(repo),
+                    pullNumber: number,
+                    perPage: GITHUB_PAGE_SIZE
+                };
+                /**
+                 * The head commit, read first and checked again at the end.
+                 *
+                 * Neither CI method takes a commit: each resolves the pull request's
+                 * head for itself, so a push landing between the two reads combines one
+                 * commit's check runs with another's statuses — and the combination
+                 * renders as "every check has finished and passed" for a commit whose
+                 * runs were never read, which is the one answer a waiting agent acts on
+                 * by stopping. Reading the head first costs a call and makes the
+                 * mismatch detectable: the combined status reports the sha it answered
+                 * for, so an answer that disagrees with this one is thrown away rather
+                 * than rendered.
+                 */
+                const pr = await mcp("repo_pr_checks", "pull_request_read", {
+                    ...where,
+                    method: "get"
+                });
                 if (!pr.ok)
                     return bounded(pr.message);
                 const sha = pr.data.head?.sha;
                 if (!sha)
                     return `#${number} is not a pull request in ${owner}/${repo}`;
                 const short = sha.slice(0, 7);
-                const runs = await github("repo_pr_checks", `/repos/${owner}/${repo}/commits/${sha}/check-runs?per_page=${GITHUB_PAGE_SIZE}`);
+                const runs = await mcp("repo_pr_checks", "pull_request_read", {
+                    ...where,
+                    method: "get_check_runs"
+                });
                 if (!runs.ok)
                     return bounded(runs.message);
                 // The combined status holds the latest per context, so one page is
                 // every context there is.
-                const statuses = await github("repo_pr_checks", `/repos/${owner}/${repo}/commits/${sha}/status?per_page=${GITHUB_PAGE_SIZE}`);
+                const statuses = await mcp("repo_pr_checks", "pull_request_read", {
+                    ...where,
+                    method: "get_status"
+                });
                 if (!statuses.ok)
                     return bounded(statuses.message);
                 const runData = runs.data;
                 const statusData = statuses.data;
+                // The head was this commit before the check runs were read and still is
+                // after the statuses were, so both answers are that commit's. Unequal —
+                // or absent, which is the server declining to say — leaves no partial
+                // answer worth rendering, because the mixture is indistinguishable from
+                // a clean pass.
+                if (statusData.sha !== sha) {
+                    return (`#${number}'s checks could not be read as one commit's: this started ` +
+                        `at ${short} and the combined status answered for ` +
+                        `${statusData.sha ? statusData.sha.slice(0, 7) : "no commit it named"}. ` +
+                        "A push landing during the read does this — ask again.");
+                }
                 const checks = readChecks(runData.check_runs ?? [], statusData.statuses ?? []);
                 if (checks.length === 0) {
                     return (`No checks have reported on #${number}'s latest commit (${short}). ` +

package/dist/{repo → repo-github}/tools-clone.js

@@ -60,9 +60,8 @@ export function cloneTools(ctx) {
                 //
                 // Checked here rather than in `refreshCheckout` because this is where
                 // model input arrives and where the message can say what to send instead.
-                // It also covers the fresh-clone path, where the name reaches
-                // isomorphic-git as a ref: no argv there, so no option to parse, but an
-                // unresolvable ref is a worse error than this sentence.
+                // It also covers the fresh-clone path, where an unresolvable ref is a
+                // worse error than this sentence.
                 if (branch !== undefined && UNSAFE_BRANCH.test(branch))
                     return `"${branch}" is not a plain branch name — use something like "main"`;
                 const dir = `${workdir}/${parsed.repo}`;
@@ -151,24 +150,6 @@ export function cloneTools(ctx) {
                 // plugin never cloned, is on
                 // {@link file://./checkout.ts writeGitIdentity}.
                 await writeGitIdentity(plain, dir, author);
-                // Two gits now share one `.git`, and this is where they could disagree.
-                //
-                // The container's git and the host's isomorphic-git read and write the
-                // same index. isomorphic-git understands version 2 and the extensions
-                // git writes for its own caches are not part of that contract, so a
-                // repository that picked up an untracked cache or a split index — from a
-                // `feature.manyFiles` default, or a user config in some future image —
-                // would be written by one and misread by the other. Pinned at clone
-                // time, repo-locally, where it costs three commands and cannot surprise
-                // anyone later.
-                //
-                // Unchecked deliberately, like the upstream-tracking pair in
-                // `repo_push`: git's own defaults are already these values, so a failure
-                // here means the config could not be written at all, which the very next
-                // command will say far more clearly than this one could.
-                await plain(`config index.version 2`, dir);
-                await plain(`config core.untrackedCache false`, dir);
-                await plain(`config core.splitIndex false`, dir);
                 // The clone reports the branch it landed on, so nothing has to ask git
                 // afterwards — and a failed question would fire `afterCheckout` with no
                 // branch at all, starting an install against a checkout nobody can name.

package/dist/{repo → repo-github}/tools-pr.d.ts

@@ -1,7 +1,6 @@
 import { type Action } from "@cloudflare/think";
 import type { ToolSet } from "ai";
 import type { RepoContext } from "./context.js";
-/** GitHub's REST surface: pull requests, issues and their comments. */
 export declare function prTools(ctx: RepoContext): ToolSet;
 /**
  * The GitHub writes a recovered turn must not repeat, as Think actions.