@dynamicagents/plugins 0.11.0 → 0.12.0

package/dist/repo/tools-clone.d.ts

@@ -0,0 +1,4 @@
+import type { ToolSet } from "ai";
+import type { RepoContext } from "./context.js";
+/** Putting a checkout on disk, fresh or refreshed. */
+export declare function cloneTools(ctx: RepoContext): ToolSet;

package/dist/repo/tools-clone.js

@@ -0,0 +1,192 @@
+import { tool } from "ai";
+import { z } from "zod";
+import { parseRepo, repoLocation, UNSAFE_BRANCH } from "./url.js";
+import { refreshCheckout, writeGitIdentity } from "./checkout.js";
+/** Putting a checkout on disk, fresh or refreshed. */
+export function cloneTools(ctx) {
+    const { config, workdir, author, allowedHosts, bounded, notifyCheckout, logFailure, plain, runGit, fetchOrigin } = ctx;
+    return {
+        repo_clone: tool({
+            description: "Clone a git repository into the workspace. Returns the checkout path and the branch you landed on. If the repository is already checked out from an earlier task, it is fetched and reset to the remote instead — unless it has uncommitted changes, which are left alone for you to inspect.",
+            inputSchema: z.object({
+                url: z.string().describe("HTTPS repository URL"),
+                branch: z
+                    .string()
+                    .optional()
+                    .describe("Branch to check out (default: the repo's default)"),
+                depth: z
+                    .number()
+                    .optional()
+                    .describe("Shallow-clone depth. Omit for full history; needed if you must rebase.")
+            }),
+            execute: async ({ url, branch, depth }) => {
+                // The gate, before anything runs. `url` is model input, and a clone is
+                // the one command that hands a credential to a host it names.
+                const location = repoLocation(url);
+                if (!location || !allowedHosts.includes(location.host)) {
+                    return (`refusing to clone from "${location?.host ?? url}" — this agent may ` +
+                        `only clone over https from: ${allowedHosts.join(", ")}`);
+                }
+                // Everything past this point travels the canonical form, so what the
+                // host clones, what lands in `.git/config`, and what `afterCheckout`
+                // records are one string. Refusals above still quote what the model
+                // actually sent.
+                const { host, url: target } = location;
+                // Refused rather than worked around. A URL that passes the host check
+                // but names no repository is what a model copies out of a browser —
+                // `.../tree/main`, `.../pull/4` — and carrying on means cloning without
+                // telling `beforeCheckout` which repository this is, so a host keying its
+                // filesystem per repository never switches and the checkout lands in
+                // whichever workspace was already open.
+                //
+                // Not silently trimmed to the first two segments either, tempting as it
+                // is: that reads `.../orgs/x/repositories` as the repository `x`, and
+                // quietly reinterpreting the target is the wrong instinct for the one
+                // tool that offers a credential to a host on the model's say-so. A
+                // refusal costs one turn and says exactly what to send instead.
+                const parsed = parseRepo(target, allowedHosts);
+                if (!parsed) {
+                    return (`refusing to clone "${url}" — it does not name a repository. ` +
+                        `A clone URL is https://<host>/<owner>/<repo>, so if this came out of ` +
+                        `a browser, drop everything after the repository name (the /tree/…, ` +
+                        `/pull/… or /blob/… part) and try again.`);
+                }
+                // The same guard `repo_push` applies, at the second door a branch name
+                // enters by. `refreshCheckout` runs `git checkout "$REPO_BRANCH"`, and
+                // quoting stops word-splitting but *not* option parsing: a `branch` of
+                // `--detach` arrives as an option, git detaches HEAD, the `reset` that
+                // follows fails against `origin/--detach`, and the checkout a later task
+                // inherits has moved for reasons nothing reported.
+                //
+                // 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.
+                if (branch !== undefined && UNSAFE_BRANCH.test(branch))
+                    return `"${branch}" is not a plain branch name — use something like "main"`;
+                const dir = `${workdir}/${parsed.repo}`;
+                // Before anything runs, and before `dir` is touched: a host keying its
+                // filesystem per repository needs to have switched by now. See
+                // `beforeCheckout` for why this cannot wait for the clone to finish.
+                //
+                // A throw here stops the clone, which is the exact opposite of how
+                // `afterCheckout` is treated — and the asymmetry is the point rather than
+                // an inconsistency. This hook *chooses the workspace*; carrying on past a
+                // failed one would put the checkout wherever the last task left the
+                // selection, which is the failure the hook exists to prevent. By the time
+                // `afterCheckout` runs there is a checkout on disk and the model needs to
+                // be told about it, so that one is caught and logged.
+                try {
+                    config.beforeCheckout?.({
+                        url: target,
+                        host,
+                        owner: parsed.owner,
+                        repo: parsed.repo
+                    });
+                }
+                catch (err) {
+                    console.error("[repo] beforeCheckout failed", {
+                        url,
+                        repo: `${parsed.owner}/${parsed.repo}`,
+                        err: String(err)
+                    });
+                    return (`could not select a workspace for ${parsed.owner}/${parsed.repo}: ` +
+                        `${String(err)}\nNothing was cloned — going ahead would have put the ` +
+                        `checkout in whichever workspace was already open.`);
+                }
+                // The workspace outlives the task, so this path may already hold the
+                // checkout a previous task left — see `refreshCheckout`.
+                const existing = await plain("rev-parse --git-dir", dir);
+                // A failed probe means "nothing here, clone it" — but only when git
+                // answered. A command that never ran means nothing, and the distinction
+                // is not academic: a replaced container is precisely the case where this
+                // call fails and the *next* one lands on a working replacement. Read as
+                // "empty", it points `git clone` at a directory that already holds the
+                // checkout — which fails with `destination path already exists` and skips
+                // the refresh that was the right answer all along.
+                if (existing.unreachable)
+                    return bounded(`could not clone ${url}: ${existing.stderr}`);
+                if (existing.success) {
+                    const refreshed = await refreshCheckout({
+                        dir,
+                        url: target,
+                        branch,
+                        author,
+                        plain,
+                        fetchOrigin
+                    });
+                    if (refreshed.branch) {
+                        await notifyCheckout({
+                            dir,
+                            url: target,
+                            host,
+                            repo: `${parsed.owner}/${parsed.repo}`,
+                            branch: refreshed.branch,
+                            fresh: false
+                        });
+                    }
+                    return refreshed.message;
+                }
+                // `depth` is bounded here rather than trusted from the schema. It no
+                // longer reaches a shell, so this is arithmetic rather than quoting: a
+                // fractional or negative depth is not something to hand to git.
+                const result = await runGit(() => config.git.clone({
+                    url: target,
+                    dir,
+                    allowedHosts,
+                    ...(branch ? { branch } : {}),
+                    ...(depth ? { depth: Math.max(1, Math.floor(depth)) } : {})
+                }));
+                if (!result.success) {
+                    logFailure("repo_clone", result);
+                    return bounded(`clone failed: ${result.stderr || result.stdout}`);
+                }
+                // Identity has to exist before the first commit. Written through the
+                // container, and deliberately: the commits it names are made there, by
+                // `repo_commit`, with no credential in sight — only the three operations
+                // that talk to the forge moved.
+                //
+                // Why a refresh rewrites it, and what answers for a repository this
+                // 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.
+                const landed = result.stdout.trim() || branch;
+                if (!landed) {
+                    logFailure("repo_clone", result);
+                    return bounded(`cloned to ${dir}, but could not read which branch it landed on`);
+                }
+                await notifyCheckout({
+                    dir,
+                    url: target,
+                    host,
+                    repo: `${parsed.owner}/${parsed.repo}`,
+                    branch: landed,
+                    fresh: true
+                });
+                return `cloned to ${dir} on branch ${landed}`;
+            }
+        })
+    };
+}

package/dist/repo/tools-forge.d.ts

@@ -0,0 +1,4 @@
+import type { ToolSet } from "ai";
+import type { RepoContext } from "./context.js";
+/** The forge's REST surface: pull requests, issues and their comments. */
+export declare function forgeTools(ctx: RepoContext): ToolSet;

package/dist/repo/tools-forge.js

@@ -0,0 +1,179 @@
+import { tool } from "ai";
+import { z } from "zod";
+import { FORGE_PAGE_SIZE } from "./context.js";
+/** The forge's REST surface: pull requests, issues and their comments. */
+export function forgeTools(ctx) {
+    const { bounded, forge, forgeRepo } = ctx;
+    return {
+        repo_open_pr: tool({
+            description: "Open a pull request for a pushed branch and return its URL. Do this once the branch is pushed and the tests pass.",
+            inputSchema: z.object({
+                dir: z.string().describe("The checkout directory"),
+                head: z.string().describe("The branch you pushed"),
+                base: z.string().describe("The branch to merge into, e.g. 'main'"),
+                title: z.string().describe("Pull request title"),
+                body: z
+                    .string()
+                    .describe("Pull request description — what changed and why, and how you verified it")
+            }),
+            execute: async ({ dir, head, base, title, body }) => {
+                // The checkout's own origin, never a URL the model names — the rule the
+                // three read tools follow, and it binds harder here because this one
+                // writes. A repository named at the call site is bounded only by the
+                // host allowlist, so an agent talked into naming one could open a pull
+                // request on anything the token can write to.
+                const target = await forgeRepo(dir);
+                if ("refusal" in target)
+                    return target.refusal;
+                const { owner, repo } = target;
+                // One may be open already: a call abandoned before its answer arrived
+                // still opened it, and the retry that follows is the ordinary case.
+                // Best-effort — a lookup that fails leaves the POST to answer for itself.
+                // The filter wants `owner:branch`; a fork's head already says whose.
+                const filter = new URLSearchParams({
+                    state: "open",
+                    head: head.includes(":")
+                        ? head
+                        : `${decodeURIComponent(owner)}:${head}`,
+                    base
+                });
+                const existing = await forge("repo_open_pr", `/repos/${owner}/${repo}/pulls?${filter}`);
+                const open = existing.ok && Array.isArray(existing.data)
+                    ? existing.data[0]
+                    : undefined;
+                if (open?.html_url)
+                    return `already open, nothing new was created: ${open.html_url}`;
+                const opened = await forge("repo_open_pr", `/repos/${owner}/${repo}/pulls`, { method: "POST", body: { title, head, base, body } });
+                if (!opened.ok)
+                    // A POST whose answer never arrived may still have been received, and
+                    // a blind retry is how one pull request becomes two.
+                    return bounded(`${opened.message}\nIf this was a timeout rather than a rejection the ` +
+                        `pull request may have been opened anyway — check with repo_pr_view ` +
+                        `before retrying, or the retry will open a second one alongside it.`);
+                const data = opened.data;
+                return (data.html_url ??
+                    "pull request opened, but the response carried no URL");
+            }
+        }),
+        repo_issue_view: tool({
+            description: "Read an issue or pull request from the repository you have checked out: its title, state, description and comments. Use this when a task refers to an issue number, before guessing what it asks for.",
+            inputSchema: z.object({
+                dir: z.string().describe("The checkout directory"),
+                number: z.number().int().positive().describe("Issue or PR number")
+            }),
+            execute: async ({ dir, number }) => {
+                const target = await forgeRepo(dir);
+                if ("refusal" in target)
+                    return target.refusal;
+                const { owner, repo } = target;
+                // The issues endpoint, deliberately, even for a pull request: GitHub
+                // models every PR as an issue, and this is the one that carries the
+                // discussion. `repo_pr_view` is for the parts that are only a PR's.
+                const issue = await forge("repo_issue_view", `/repos/${owner}/${repo}/issues/${number}`);
+                if (!issue.ok)
+                    return bounded(issue.message);
+                const data = issue.data;
+                const comments = await forge("repo_issue_view", `/repos/${owner}/${repo}/issues/${number}/comments?per_page=${FORGE_PAGE_SIZE}`);
+                // A failure here is not a failure of the tool: the issue itself was
+                // read, and half an answer beats none.
+                const thread = (comments.ok && Array.isArray(comments.data) ? comments.data : []);
+                // A full page means there is very likely another. Said out loud, because
+                // this thread is what the model reasons from: comments arrive oldest
+                // first, so the ones it cannot see are the most recent — the review
+                // feedback, on the pull request busy enough to have overflowed.
+                const moreComments = thread.length >= FORGE_PAGE_SIZE;
+                return bounded([
+                    `#${number} ${data.title ?? "(no title)"} [${data.state ?? "?"}]` +
+                        (data.pull_request ? " (pull request)" : ""),
+                    `opened by ${data.user?.login ?? "unknown"}`,
+                    "",
+                    data.body?.trim() || "(no description)",
+                    ...thread.map((c) => `\n--- ${c.user?.login ?? "unknown"} ---\n${c.body?.trim() ?? ""}`),
+                    ...(comments.ok ? [] : [`\n(comments could not be read)`]),
+                    ...(moreComments
+                        ? [
+                            `\n(showing the first ${FORGE_PAGE_SIZE} comments; the thread is ` +
+                                `longer, and the newest are not among them)`
+                        ]
+                        : [])
+                ].join("\n"));
+            }
+        }),
+        repo_pr_view: tool({
+            description: "Read a pull request's state and the files it touches — whether it is mergeable, its review state, and which paths changed. Use this to check on a pull request you opened, or to see what an existing one does before duplicating it.",
+            inputSchema: z.object({
+                dir: z.string().describe("The checkout directory"),
+                number: z.number().int().positive().describe("Pull request number")
+            }),
+            execute: async ({ dir, number }) => {
+                const target = await forgeRepo(dir);
+                if ("refusal" in target)
+                    return target.refusal;
+                const { owner, repo } = target;
+                const pr = await forge("repo_pr_view", `/repos/${owner}/${repo}/pulls/${number}`);
+                if (!pr.ok)
+                    return bounded(pr.message);
+                const data = pr.data;
+                const files = await forge("repo_pr_view", `/repos/${owner}/${repo}/pulls/${number}/files?per_page=${FORGE_PAGE_SIZE}`);
+                const changed = (files.ok && Array.isArray(files.data) ? files.data : []);
+                const moreFiles = changed.length >= FORGE_PAGE_SIZE;
+                return bounded([
+                    `#${number} ${data.title ?? "(no title)"}`,
+                    `${data.merged ? "merged" : (data.state ?? "?")}` +
+                        (data.draft ? " (draft)" : "") +
+                        // `mergeable` is computed asynchronously by GitHub and is `null`
+                        // until it has been, which is common on a pull request opened
+                        // seconds ago — exactly when this tool is most likely to be called.
+                        (data.mergeable === null
+                            ? ", mergeability not yet computed"
+                            : data.mergeable === false
+                                ? ", NOT mergeable"
+                                : ""),
+                    `${data.head?.ref ?? "?"} → ${data.base?.ref ?? "?"}`,
+                    data.html_url ?? "",
+                    "",
+                    changed.length
+                        ? changed
+                            .map((f) => `  ${f.filename ?? "?"} (+${f.additions ?? 0} -${f.deletions ?? 0})`)
+                            .join("\n")
+                        : files.ok
+                            ? "  (no files reported)"
+                            : "  (changed files could not be read)",
+                    ...(moreFiles
+                        ? [
+                            `\n(showing the first ${FORGE_PAGE_SIZE} files; this pull request ` +
+                                `touches more)`
+                        ]
+                        : [])
+                ].join("\n"));
+            }
+        }),
+        repo_pr_comment: tool({
+            description: "Leave a comment on a pull request or issue in the repository you have checked out. Use this to report what you did, or to answer a review — not to announce work you have not finished.",
+            inputSchema: z.object({
+                dir: z.string().describe("The checkout directory"),
+                number: z
+                    .number()
+                    .int()
+                    .positive()
+                    .describe("Pull request or issue number"),
+                body: z.string().describe("The comment, as markdown")
+            }),
+            execute: async ({ dir, number, body }) => {
+                const target = await forgeRepo(dir);
+                if ("refusal" in target)
+                    return target.refusal;
+                const { owner, repo } = target;
+                const posted = await forge("repo_pr_comment", `/repos/${owner}/${repo}/issues/${number}/comments`, { method: "POST", body: { body } });
+                if (!posted.ok)
+                    // The same hazard `repo_open_pr` names, for the same reason: a POST
+                    // whose answer never arrived may still have been received, and a blind
+                    // retry is how one comment becomes two.
+                    return bounded(`${posted.message}\nIf this was a timeout rather than a rejection the ` +
+                        `comment may exist anyway — read it back with repo_issue_view before retrying.`);
+                const data = posted.data;
+                return data.html_url ?? `commented on #${number}`;
+            }
+        })
+    };
+}

package/dist/repo/tools-review.d.ts

@@ -0,0 +1,3 @@
+import type { ToolSet } from "ai";
+import type { RepoContext } from "./context.js";
+export declare function reviewTools(ctx: RepoContext): ToolSet;