@dynamicagents/plugins 0.13.0 → 0.15.0

package/dist/{repo → repo-github}/context.js

@@ -1,10 +1,18 @@
-import { DEFAULT_ALLOWED_HOSTS, parseRepo, repoLocation } from "./url.js";
+import { truncateOutput } from "@dynamicagents/core";
+import { githubMcp } from "./mcp.js";
+import { DEFAULT_ALLOWED_HOSTS, GITHUB_HOST, parseRepo, repoLocation } from "./url.js";
 /**
  * The machinery every repo tool closes over: the resolved config, the git
  * runners, and the GitHub client.
  */
 const DEFAULT_WORKDIR = "/workspace";
-const DEFAULT_API_BASE = "https://api.github.com";
+/**
+ * GitHub's API. Not a host's to configure: the hosted MCP server these tools
+ * read through is github.com's alone, so an Enterprise base here would point
+ * half of this plugin at an install the other half cannot reach. That is
+ * {@link GITHUB_HOST}, which `githubRepo` holds every checkout to.
+ */
+const API_BASE = `https://api.${GITHUB_HOST}`;
 const DEFAULT_AUTHOR = {
     name: "da-coder",
     email: "coder@dynamicagents.invalid"
@@ -30,70 +38,25 @@ const GITHUB_TIMEOUT_MS = 30_000;
  */
 export const GITHUB_PAGE_SIZE = 100;
 /**
- * Where GraphQL lives, given where REST does.
- *
- * On github.com they share an origin and `/graphql` hangs off it. On GitHub
- * Enterprise — which {@link RepoConfig.apiBase} exists for — REST is under
- * `/api/v3` and GraphQL is its **sibling** at `/api/graphql`, not a path beneath
- * it. Appending blindly yields `/api/v3/graphql`, which is a 404 on every
- * Enterprise install and no failure at all on the public API, so the mistake
- * survives every test written against github.com.
+ * Where GraphQL lives. A constant, because github.com is the only host these
+ * tools talk to — see `./mcp.ts` for why Enterprise is not supported.
  */
-export function graphqlEndpoint(apiBase) {
-    const trimmed = apiBase.replace(/\/+$/, "");
-    const enterprise = trimmed.replace(/\/api\/v3$/, "/api/graphql");
-    return enterprise === trimmed ? `${trimmed}/graphql` : enterprise;
-}
-/**
- * Middle-out truncation, so both the head of a diff and its tail survive.
- *
- * Deliberately a **copy** of `/workspace`'s function of the same name, not an
- * import. `npm run verify:exports` fails any subpath whose module graph
- * reaches a sibling's directory, and its own advice for a shared helper is to
- * duplicate it — installing `repo` must not drag `/workspace` (and therefore
- * `@cloudflare/computer`) into a consumer's bundle. Fifteen lines is a cheaper
- * price than that coupling, and it is the same reason `exec` is injected here
- * rather than imported.
- *
- * The `half < 1` guard is not padding: without it a small `max` makes `half`
- * zero or negative, and `slice(-0)` is `slice(0)` — the whole string — so the
- * function would return *more* than it was given.
- */
-export function truncateOutput(text, max) {
-    if (text.length <= max)
-        return text;
-    const marker = (dropped) => `\n\n… [${dropped} characters omitted from the middle] …\n\n`;
-    const half = Math.floor((max - marker(text.length).length) / 2);
-    if (half < 1)
-        return text.slice(0, Math.max(0, max));
-    return (text.slice(0, half) + marker(text.length - half * 2) + text.slice(-half));
-}
+const GRAPHQL_URL = `${API_BASE}/graphql`;
 /**
  * What to tell the model when the plumbing, not the command, is the problem.
- *
- * A sibling of the computer plugin's `execLostNote` rather than an import, for
- * the same reason {@link truncateOutput} is a copy: `verify:exports` fails any
- * subpath whose module graph reaches a sibling's, and installing `repo` must
- * not drag `/computer` in behind it. The wording differs anyway, and the
- * difference is the point — that plugin cannot know the lost command was git,
- * and this one does. What a model needs after a lost `git push` is not "re-run
- * it" but whether re-running it is *safe*.
+ * What a model needs after a lost `git push` is not "re-run it" but whether
+ * re-running it is *safe*, which only this plugin knows: the lost command was
+ * git.
  */
 function unreachableNote(err) {
-    if (err?.code === "EEXEC_LOST") {
-        return ("the container was replaced while this command was running, so nothing here " +
-            "is known to have finished. This is infrastructure — not git, and not what " +
-            "you asked for. The checkout is durable and is exactly as you left it. " +
-            "Retry, and read what the retry says rather than assuming it starts from " +
-            "nothing: a command that had already reached GitHub may have taken " +
-            "effect. Retrying is safe either way — these commands push one branch to " +
-            "the branch of the same name, and never force.");
-    }
     return (`the command could not be run: ${String(err)}. This is the plumbing — the ` +
         `container, the transport to it, or the host's own configuration — rather ` +
         `than git or anything you passed, and nothing is known to have completed. ` +
-        `Retry once; if it happens again, say so in your result rather than working ` +
-        `around it.`);
+        `Retry once, and read what the retry says rather than assuming it starts ` +
+        `from nothing: a command that had already reached GitHub may have taken ` +
+        `effect. Retrying is safe either way — these commands push one branch to ` +
+        `the branch of the same name, and never force. If it happens again, say so ` +
+        `in your result rather than working around it.`);
 }
 /**
  * One git command at a time, per plugin instance.
@@ -185,13 +148,6 @@ export function actionTask(ctx) {
             "the repo plugin's actions run only in turns core started for a task");
     return task;
 }
-/** A hex SHA-256, so a key names a body without carrying it. */
-export async function sha256(text) {
-    const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(text));
-    return [...new Uint8Array(digest)]
-        .map((byte) => byte.toString(16).padStart(2, "0"))
-        .join("");
-}
 export function repoContext(config, 
 /**
  * The running sub-agent's `runtime()`, read per command. Forwarded to every
@@ -199,8 +155,6 @@ export function repoContext(config,
  */
 runtime = () => undefined) {
     const workdir = config.workdir ?? DEFAULT_WORKDIR;
-    const apiBase = config.apiBase ?? DEFAULT_API_BASE;
-    const graphqlUrl = graphqlEndpoint(apiBase);
     const author = config.author ?? DEFAULT_AUTHOR;
     const allowedHosts = config.allowedHosts ?? DEFAULT_ALLOWED_HOSTS;
     const maxChars = config.maxOutputChars ?? DEFAULT_MAX_OUTPUT_CHARS;
@@ -412,13 +366,8 @@ runtime = () => undefined) {
      * its own sentence to add: a POST whose answer never arrived may have been
      * received, which a GET has no reason to warn about.
      */
-    const github = (tool, path, init) => githubAt(tool, `${apiBase}${path}`, init);
-    /**
-     * The same call, against a URL rather than a path under {@link apiBase}.
-     *
-     * GraphQL needs it: on Enterprise the REST base carries `/api/v3` and GraphQL
-     * does not live under it — see {@link graphqlEndpoint}.
-     */
+    const github = (tool, path, init) => githubAt(tool, `${API_BASE}${path}`, init);
+    /** The same call, against a URL rather than a path under {@link API_BASE}. */
     const githubAt = async (tool, url, init) => {
         const secret = credential();
         if ("failure" in secret) {
@@ -464,13 +413,12 @@ runtime = () => undefined) {
      * nothing there" and is acted on accordingly. That is the whole reason this
      * wrapper exists rather than each caller posting to `/graphql` itself.
      *
-     * What needs it is what REST cannot express: resolving a review thread has no
-     * REST equivalent at all, the threads themselves are not on the issue timeline
-     * `repo_issue_view` reads, and a review *request* naming an app is invisible to
-     * REST — see {@link file://./tools-review.ts REVIEW_REQUESTS_QUERY}.
+     * What still needs it is answering a review thread: replying to one and
+     * resolving it have no REST equivalent at all. Reading them does not — that
+     * goes through `./mcp.ts` with everything else this plugin reads.
      */
     const githubGraphql = async (tool, query, variables) => {
-        const answered = await githubAt(tool, graphqlUrl, {
+        const answered = await githubAt(tool, GRAPHQL_URL, {
             method: "POST",
             body: { query, variables }
         });
@@ -484,7 +432,7 @@ runtime = () => undefined) {
             logFailure(tool, { stderr: detail });
             return {
                 ok: false,
-                message: `${graphqlUrl} refused the query: ${detail.slice(0, 500)}`
+                message: `${GRAPHQL_URL} refused the query: ${detail.slice(0, 500)}`
             };
         }
         return { ok: true, data: body.data };
@@ -499,6 +447,13 @@ runtime = () => undefined) {
      * the reach this plugin does not want to widen; and an agent asking about
      * "issue 42" almost always means the repository it is working in, so the extra
      * parameter would mostly be an extra way to be wrong.
+     *
+     * **The host allowlist is not narrow enough on its own.** It bounds cloning,
+     * which is generic git and works on any host; every API call here goes to
+     * github.com — see {@link GITHUB_HOST}. A widened `allowedHosts` therefore
+     * admits an origin whose `owner/repo` names a *different* repository on
+     * github.com, and resolving it would read that one and let a write reach it.
+     * So the host is checked here rather than discarded.
      */
     const githubRepo = async (dir) => {
         const { remote, unreachable } = await origin(dir);
@@ -508,7 +463,13 @@ runtime = () => undefined) {
             return {
                 refusal: `${dir} has no origin on an allowed host — clone it with repo_clone first`
             };
-        const parsed = parseRepo(remote.url, allowedHosts);
+        if (remote.host !== GITHUB_HOST)
+            return {
+                refusal: `${dir}'s origin is on ${remote.host}, and these tools read and write ` +
+                    `${GITHUB_HOST} alone — an owner/repo from another host would name a ` +
+                    `different repository there`
+            };
+        const parsed = parseRepo(remote.url, [GITHUB_HOST]);
         if (!parsed)
             return {
                 refusal: `could not parse an owner/repo out of ${dir}'s origin`
@@ -575,6 +536,10 @@ runtime = () => undefined) {
         fetchOrigin,
         pushBranch,
         origin,
+        // Keyed on the config, so one plugin instance keeps one MCP connection
+        // however many times its tools are rebuilt — the reason the git queue
+        // above is keyed the same way.
+        mcp: githubMcp(config, credential, logFailure),
         github,
         githubGraphql,
         githubRepo

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

@@ -7,13 +7,29 @@ import type { AgentPlugin } from "@dynamicagents/core";
  * though it is implemented in `url.ts`.
  */
 export { parseRepo } from "./url.js";
-export { graphqlEndpoint, truncateOutput } from "./context.js";
 /**
- * `@dynamicagents/plugins/repo` — clone, commit, push, open a pull request.
+ * The hosted MCP server this plugin reads GitHub through, and the allowlist it
+ * is held to. Exported so a deployment can state in its own docs what the
+ * token is able to reach, and so a spec can assert the list has not grown.
+ *
+ * Named for the provider rather than for the protocol: the protocol's own
+ * surface is `@dynamicagents/core/mcp`'s, and a bare `MCP_TOOLS` here would not
+ * say whose policy it is.
+ */
+export { GITHUB_MCP_URL, GITHUB_MCP_TOOLS } from "./mcp.js";
+/**
+ * Over a `/sandbox` object: the sandbox's egress rule for GitHub, and the
+ * `RepoGit` that runs the container's own git behind it.
+ */
+export { GITHUB_TOKEN_PLACEHOLDER, githubSandboxEgress, type GitHubSandboxEgressOptions, type GitPushPolicy } from "./sandbox-egress.js";
+export { sandboxRepoGit, type SandboxGitHost } from "./sandbox-git.js";
+/**
+ * `@dynamicagents/plugins/repo-github` — clone, commit, push, open a pull
+ * request, on GitHub.
  *
  * Layered over a container rather than owning one: it needs a shell with `git`
- * on it, and `@dynamicagents/plugins/workspace` provides exactly that through
- * `workspaceExec`. Passing `exec` in rather than importing that plugin keeps the
+ * on it, and `@dynamicagents/plugins/sandbox` provides exactly that through
+ * `sandboxExec`. Passing `exec` in rather than importing that plugin keeps the
  * two independent — a host with its own container can use this against that
  * instead, and the tests here need no container at all.
  *
@@ -102,10 +118,10 @@ export type RepoExec = (command: string, options?: {
  * `commit` and `checkout` are local, need nothing to authenticate with, and stay
  * on `exec` where they are cheap and where the model can see them work.
  *
- * A host implements this against whatever git it has on its own side of the
- * boundary. The coder in `starter` runs isomorphic-git inside the
- * Durable Object that owns the workspace filesystem, so a push reads the token
- * from that object's environment and the container never holds one.
+ * A host implements this against whatever git it has. Over `/sandbox`,
+ * `sandboxRepoGit` runs the container's own git with a placeholder, and the
+ * egress swaps the token in on the Worker side, so the container never holds
+ * one.
  *
  * ## Failures arrive as values
  *
@@ -186,8 +202,6 @@ export interface RepoConfig {
     token: () => string;
     /** Where clones land. Defaults to `/workspace`. */
     workdir?: string;
-    /** API origin, for GitHub Enterprise. Defaults to the public API. */
-    apiBase?: string;
     /** Committer identity. Defaults to a generic agent identity. */
     author?: {
         name: string;
@@ -197,8 +211,11 @@ export interface RepoConfig {
      * Hosts a clone may target, lowercase and exact. Defaults to `github.com`.
      *
      * A fail-closed allowlist rather than a blocklist, because the failure it
-     * prevents is credential exfiltration and the input is model-chosen. Widen it
-     * for GitHub Enterprise (alongside `apiBase`); an empty array clones nothing.
+     * prevents is credential exfiltration and the input is model-chosen. An empty
+     * array clones nothing.
+     *
+     * This bounds *cloning*, which is generic git and works against any host. The
+     * GitHub tools are github.com's alone — see `./mcp.ts`.
      */
     allowedHosts?: string[];
     /**
@@ -287,7 +304,7 @@ export interface RepoConfig {
     tools?: readonly RepoToolName[];
 }
 /** Every tool and action this plugin can offer, by the name the model sees. */
-export declare const REPO_TOOL_NAMES: readonly ["repo_clone", "repo_fetch", "repo_status", "repo_diff", "repo_commit", "repo_push", "repo_open_pr", "repo_issue_view", "repo_pr_view", "repo_pr_comment", "repo_pr_review_status", "repo_pr_threads", "repo_pr_thread_reply", "repo_pr_checks", "repo_worktrees", "repo_worktree"];
+export declare const REPO_TOOL_NAMES: readonly ["repo_clone", "repo_fetch", "repo_status", "repo_diff", "repo_commit", "repo_push", "repo_open_pr", "repo_issue_view", "repo_pr_view", "repo_pr_comment", "repo_pr_threads", "repo_pr_thread_reply", "repo_pr_checks", "repo_worktrees", "repo_worktree"];
 export type RepoToolName = (typeof REPO_TOOL_NAMES)[number];
 /**
  * Checkouts a host keeps apart from the main one — each holding a branch its

package/dist/{repo → repo-github}/index.js

@@ -14,7 +14,22 @@ import { worktreesTools } from "./tools-worktrees.js";
  * though it is implemented in `url.ts`.
  */
 export { parseRepo } from "./url.js";
-export { graphqlEndpoint, truncateOutput } from "./context.js";
+/**
+ * The hosted MCP server this plugin reads GitHub through, and the allowlist it
+ * is held to. Exported so a deployment can state in its own docs what the
+ * token is able to reach, and so a spec can assert the list has not grown.
+ *
+ * Named for the provider rather than for the protocol: the protocol's own
+ * surface is `@dynamicagents/core/mcp`'s, and a bare `MCP_TOOLS` here would not
+ * say whose policy it is.
+ */
+export { GITHUB_MCP_URL, GITHUB_MCP_TOOLS } from "./mcp.js";
+/**
+ * Over a `/sandbox` object: the sandbox's egress rule for GitHub, and the
+ * `RepoGit` that runs the container's own git behind it.
+ */
+export { GITHUB_TOKEN_PLACEHOLDER, githubSandboxEgress } from "./sandbox-egress.js";
+export { sandboxRepoGit } from "./sandbox-git.js";
 /** Every tool and action this plugin can offer, by the name the model sees. */
 export const REPO_TOOL_NAMES = [
     "repo_clone",
@@ -27,7 +42,6 @@ export const REPO_TOOL_NAMES = [
     "repo_issue_view",
     "repo_pr_view",
     "repo_pr_comment",
-    "repo_pr_review_status",
     "repo_pr_threads",
     "repo_pr_thread_reply",
     "repo_pr_checks",
@@ -46,7 +60,7 @@ export function repo(config) {
         has("repo_issue_view") &&
             "`repo_issue_view` reads an issue or pull request with its comments",
         has("repo_pr_view") &&
-            "`repo_pr_view` shows a pull request's state and the files it touches",
+            "`repo_pr_view` shows a pull request's state, the reviews that have landed on it and the files it touches",
         has("repo_pr_comment") && "`repo_pr_comment` leaves a comment"
     ].filter((line) => typeof line === "string");
     const worktrees = config.worktrees && [
@@ -82,8 +96,9 @@ export function repo(config) {
             "`repo_open_pr` opens the pull request and returns its URL.",
         views.length > 0 &&
             `${views.join(", ")}. ${views.length > 1 ? "Each acts" : "It acts"} on the repository you have checked out — read the issue a task refers to before guessing what it asks for.`,
-        has("repo_pr_review_status") &&
-            "`repo_pr_review_status` says whether a reviewer has finished. Ask it before reading a review: one that has not landed has left nothing, so an empty list of threads means nothing yet rather than nothing to do.",
+        has("repo_pr_threads") &&
+            has("repo_pr_view") &&
+            "Read `repo_pr_view` before reading a review: a review that has not landed has left nothing, so an empty list of threads means nothing yet rather than nothing to do.",
         has("repo_pr_threads") &&
             "`repo_pr_threads` reads the review threads — the comments left on particular lines, which are not on the " +
                 (has("repo_issue_view")
@@ -110,7 +125,11 @@ export function repo(config) {
         ...(rules.length > 0 ? [rules.join(" ")] : [])
     ].join("\n");
     return definePlugin({
-        name: "repo",
+        // The installed capability's identity, and so the label core namespaces
+        // this plugin's context block under. The provider is in it for the same
+        // reason it is in the subpath: an agent installs one forge plugin, and
+        // which one is a thing the model may as well be able to read.
+        name: "repo-github",
         // `runtime` goes through to `exec` untouched and is read per command, so a
         // sub-agent's git commands run in the same container its parent cloned
         // into.

package/dist/repo-github/mcp.d.ts

@@ -0,0 +1,95 @@
+/**
+ * GitHub's hosted MCP server, called from the Worker.
+ *
+ * The reads this plugin makes — a pull request, its files, its reviews, its
+ * review threads, its checks, an issue and its comments — are one
+ * vendor-maintained surface. What stays ours is everything above the transport:
+ * the tool names, their schemas, the repository binding and the renders. The
+ * model never sees an MCP tool; see `./index.ts` for why the tools are wrapped
+ * rather than surfaced.
+ *
+ * The transport itself is not here and not ours. `@dynamicagents/core/mcp`
+ * holds it, over the official `@modelcontextprotocol/client`, and its module
+ * comment is where the protocol decisions live — why no `authProvider` is
+ * configured, which headers a caller may not set, how a connection is kept per
+ * plugin instance. What this file is, is the policy that is GitHub's.
+ *
+ * ## The credential, and what bounds it
+ *
+ * The token is the host's, read through {@link RepoConfig.token} at the moment
+ * of use and sent as `Authorization: Bearer` from here — the Worker. It reaches
+ * no container: this host is deliberately absent from the egress gateway's
+ * `GITHUB_HOSTS`, so nothing inside a session's container can offer the
+ * placeholder to it and be given the real one.
+ *
+ * Two caps ride on every request, and they are policy rather than tuning:
+ *
+ * 1. {@link GITHUB_MCP_TOOLS} goes out as `X-MCP-Tools`, an **enable** list.
+ *    The server offers nothing else, so a bug here — or an argument a prompt
+ *    injection talked the model into — cannot reach a tool that writes.
+ * 2. {@link GITHUB_MCP_URL} is the server's read-only variant, which refuses a
+ *    write whatever the list says.
+ *
+ * Both, not either. The list is the narrow bound and the path is the one that
+ * still holds if the list is ever edited carelessly. Neither is redundant with
+ * the wrapping: wrapping keeps GitHub's schemas out of the model's context, and
+ * these two bound what this Worker can do with the token at all.
+ *
+ * GitHub Enterprise Server is not supported, which is why the URL is a constant
+ * rather than something a host configures.
+ */
+import { type McpAnswer } from "@dynamicagents/core/mcp";
+import type { RepoConfig } from "./index.js";
+/**
+ * The server, read-only. A single toolset or a modifier is a path segment on
+ * this server — see the `X-MCP-Tools` note above for why the list does the
+ * narrow work and this does the coarse.
+ */
+export declare const GITHUB_MCP_URL = "https://api.githubcopilot.com/mcp/readonly";
+/**
+ * Every tool this plugin may call, as `X-MCP-Tools`.
+ *
+ * Deliberately not configurable. A host that could widen this could hand the
+ * deployment's token to a tool nobody reviewed, and the point of an allowlist
+ * is that adding to it is a code change somebody reads.
+ *
+ * Both are read tools. `pull_request_read` is one name over nine methods —
+ * `get`, `get_files`, `get_reviews`, `get_review_comments`, `get_check_runs`,
+ * `get_status` are the ones used here — and `issue_read` covers an issue and
+ * its comments.
+ *
+ * **`pull_request_review_write` is the one deliberate absence worth naming.**
+ * It is the only tool that resolves a review thread, and the same name submits
+ * a review — `APPROVE` included — so taking thread resolution would mean taking
+ * self-approval. Nothing needs it: a revising Claude Code session answers and
+ * resolves threads itself, with `gh` inside its container. Merging, commenting
+ * and replying are absent for the same reason.
+ */
+export declare const GITHUB_MCP_TOOLS: readonly ["pull_request_read", "issue_read"];
+/**
+ * One call to GitHub's MCP server, as the rest of this plugin asks for it.
+ *
+ * `tool` is this plugin's own tool — `repo_pr_view` — and is what the failure
+ * log names, because that is the name an operator reading the log has in front
+ * of them. `name` is the MCP tool, which must be one of
+ * {@link GITHUB_MCP_TOOLS}.
+ */
+export type GithubMcpCall = (tool: string, name: string, args: Record<string, unknown>) => Promise<McpAnswer>;
+/**
+ * The caller for one plugin instance.
+ *
+ * `config` is the key a connection is kept against, the way the git queue
+ * beside it is keyed: the tools are rebuilt every turn, so anything held in
+ * that closure would renegotiate on each one.
+ *
+ * No turn signal is threaded through. Core's client takes one, and a caller
+ * that has one should pass it; these tools do not hold the turn's signal today,
+ * and the call is bounded by core's own deadline either way.
+ */
+export declare function githubMcp(config: RepoConfig, credential: () => {
+    token: string;
+} | {
+    failure: string;
+}, logFailure: (tool: string, detail: {
+    stderr?: string;
+}) => void): GithubMcpCall;

package/dist/repo-github/mcp.js

@@ -0,0 +1,107 @@
+/**
+ * GitHub's hosted MCP server, called from the Worker.
+ *
+ * The reads this plugin makes — a pull request, its files, its reviews, its
+ * review threads, its checks, an issue and its comments — are one
+ * vendor-maintained surface. What stays ours is everything above the transport:
+ * the tool names, their schemas, the repository binding and the renders. The
+ * model never sees an MCP tool; see `./index.ts` for why the tools are wrapped
+ * rather than surfaced.
+ *
+ * The transport itself is not here and not ours. `@dynamicagents/core/mcp`
+ * holds it, over the official `@modelcontextprotocol/client`, and its module
+ * comment is where the protocol decisions live — why no `authProvider` is
+ * configured, which headers a caller may not set, how a connection is kept per
+ * plugin instance. What this file is, is the policy that is GitHub's.
+ *
+ * ## The credential, and what bounds it
+ *
+ * The token is the host's, read through {@link RepoConfig.token} at the moment
+ * of use and sent as `Authorization: Bearer` from here — the Worker. It reaches
+ * no container: this host is deliberately absent from the egress gateway's
+ * `GITHUB_HOSTS`, so nothing inside a session's container can offer the
+ * placeholder to it and be given the real one.
+ *
+ * Two caps ride on every request, and they are policy rather than tuning:
+ *
+ * 1. {@link GITHUB_MCP_TOOLS} goes out as `X-MCP-Tools`, an **enable** list.
+ *    The server offers nothing else, so a bug here — or an argument a prompt
+ *    injection talked the model into — cannot reach a tool that writes.
+ * 2. {@link GITHUB_MCP_URL} is the server's read-only variant, which refuses a
+ *    write whatever the list says.
+ *
+ * Both, not either. The list is the narrow bound and the path is the one that
+ * still holds if the list is ever edited carelessly. Neither is redundant with
+ * the wrapping: wrapping keeps GitHub's schemas out of the model's context, and
+ * these two bound what this Worker can do with the token at all.
+ *
+ * GitHub Enterprise Server is not supported, which is why the URL is a constant
+ * rather than something a host configures.
+ */
+import { mcpClient } from "@dynamicagents/core/mcp";
+/**
+ * The server, read-only. A single toolset or a modifier is a path segment on
+ * this server — see the `X-MCP-Tools` note above for why the list does the
+ * narrow work and this does the coarse.
+ */
+export const GITHUB_MCP_URL = "https://api.githubcopilot.com/mcp/readonly";
+/**
+ * Every tool this plugin may call, as `X-MCP-Tools`.
+ *
+ * Deliberately not configurable. A host that could widen this could hand the
+ * deployment's token to a tool nobody reviewed, and the point of an allowlist
+ * is that adding to it is a code change somebody reads.
+ *
+ * Both are read tools. `pull_request_read` is one name over nine methods —
+ * `get`, `get_files`, `get_reviews`, `get_review_comments`, `get_check_runs`,
+ * `get_status` are the ones used here — and `issue_read` covers an issue and
+ * its comments.
+ *
+ * **`pull_request_review_write` is the one deliberate absence worth naming.**
+ * It is the only tool that resolves a review thread, and the same name submits
+ * a review — `APPROVE` included — so taking thread resolution would mean taking
+ * self-approval. Nothing needs it: a revising Claude Code session answers and
+ * resolves threads itself, with `gh` inside its container. Merging, commenting
+ * and replying are absent for the same reason.
+ */
+export const GITHUB_MCP_TOOLS = ["pull_request_read", "issue_read"];
+/**
+ * The caller for one plugin instance.
+ *
+ * `config` is the key a connection is kept against, the way the git queue
+ * beside it is keyed: the tools are rebuilt every turn, so anything held in
+ * that closure would renegotiate on each one.
+ *
+ * No turn signal is threaded through. Core's client takes one, and a caller
+ * that has one should pass it; these tools do not hold the turn's signal today,
+ * and the call is bounded by core's own deadline either way.
+ */
+export function githubMcp(config, credential, logFailure) {
+    const call = mcpClient({
+        url: GITHUB_MCP_URL,
+        keyedOn: config,
+        // Thrown rather than returned, because core keeps an `Error`'s own message
+        // verbatim: the sentence a host's unreadable secret deserves is written
+        // once, in `repoContext`, and reaches the model unframed.
+        token: () => {
+            const secret = credential();
+            if ("failure" in secret)
+                throw new Error(secret.failure);
+            return secret.token;
+        },
+        headers: () => ({
+            "x-mcp-tools": GITHUB_MCP_TOOLS.join(","),
+            "user-agent": "da-coder"
+        }),
+        clientInfo: { name: "dynamicagents-repo-github", version: "1" }
+    });
+    return async (tool, name, args) => {
+        const answered = await call(name, args);
+        // Said out loud as well as returned. A failure that only reaches the model
+        // leaves nothing behind for an operator, and an unreadable credential is a
+        // likely reason to be on this path at all.
+        if (!answered.ok)
+            logFailure(tool, { stderr: answered.message });
+        return answered;
+    };
+}

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

@@ -0,0 +1,68 @@
+import { type SandboxEgressRule } from "../sandbox/egress.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 declare const GITHUB_TOKEN_PLACEHOLDER: string;
+/**
+ * Where a credentialed git request may go, beyond what every push is held to.
+ *
+ * Checked on git's own requests only: anonymous traffic to GitHub is whatever
+ * GitHub allows anyone. `repos` are `owner/repo`; `branches` are branch names,
+ * a trailing `*` matching any suffix. A deletion is an update like any other,
+ * so it is held to the same names.
+ */
+export interface GitPushPolicy {
+    readonly repos: readonly string[];
+    readonly branches: readonly string[];
+}
+export interface GitHubSandboxEgressOptions {
+    /** The `env` binding holding the token, read at the moment it is used and never carried. */
+    tokenBinding: string;
+    /** Absent: any repository and any work branch the token reaches. */
+    push?: GitPushPolicy;
+    /** Intercept `api.github.com` as well, so `gh` works as the deployment's account. */
+    api?: boolean;
+}
+/** The egress rule of a sandbox whose processes use GitHub. */
+export declare function githubSandboxEgress(options: GitHubSandboxEgressOptions): SandboxEgressRule;
+/** `owner/repo` of a smart-HTTP git path, and which service it asks for. */
+export declare function gitTarget(pathname: string): {
+    repo: string;
+    service: "upload-pack" | "receive-pack" | undefined;
+} | undefined;
+/** Whether `branch` is one the policy allows. */
+export declare function branchAllowed(policy: GitPushPolicy, branch: string): boolean;
+/**
+ * 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 declare function receivePackRefs(body: ReadableStream<Uint8Array>, encoding: string | null): Promise<string[]>;