@dynamicagents/plugins 0.11.1 → 0.13.0

package/dist/repo/index.d.ts

@@ -1,5 +1,4 @@
-import type { ToolSet } from "ai";
-import type { AgentPlugin, MainAgentToolApproval } from "@dynamicagents/core";
+import type { AgentPlugin } from "@dynamicagents/core";
 /**
  * The URL parsing, re-exported from the one entry point.
  *
@@ -8,12 +7,13 @@ import type { AgentPlugin, MainAgentToolApproval } 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.
  *
  * Layered over a container rather than owning one: it needs a shell with `git`
- * on it, and `@dynamicagents/plugins/computer` provides exactly that through
- * `computerExec`. Passing `exec` in rather than importing that plugin keeps the
+ * on it, and `@dynamicagents/plugins/workspace` provides exactly that through
+ * `workspaceExec`. 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.
  *
@@ -26,7 +26,7 @@ export { parseRepo } from "./url.js";
  * none of it needs to authenticate.
  *
  * That split is the one thing to preserve when changing this file: if an
- * operation talks to the forge it does not belong on `exec`, and if it does not,
+ * operation talks to GitHub it does not belong on `exec`, and if it does not,
  * it has no business anywhere else.
  *
  * It is absolute rather than careful because a narrower version does not hold.
@@ -40,9 +40,9 @@ export { parseRepo } from "./url.js";
  * the length of one command is readable at `/proc/<pid>/environ` by anything
  * else in the container.
  *
- * Two further rules, which are about the forge rather than the container:
+ * Two further rules, which are about GitHub rather than the container:
  *
- * 1. **The forge is an allowlist, checked before anything runs.** A clone URL is
+ * 1. **GitHub's hosts are an allowlist, checked before anything runs.** A clone URL is
  *    model input — a repository README, an issue body, or a page fetched by a
  *    co-installed browser plugin is enough to choose it — and a credential
  *    offered to a host of the model's choosing is the whole game. So the URL's
@@ -51,7 +51,7 @@ export { parseRepo } from "./url.js";
  *    check to the moment the token would actually be handed over. `origin` is
  *    re-derived and re-checked on every push rather than remembered, because the
  *    checkout's `.git/config` is a file the container can rewrite.
- * 2. **The forge API is called from the Worker**, so the credential that can
+ * 2. **The GitHub API is called from the Worker**, so the credential that can
  *    write to a repository through the API never crosses the boundary either.
  *    Every tool that reads or writes through it resolves the repository from the
  *    checkout's own origin rather than from a parameter, so there is no way to
@@ -66,23 +66,20 @@ export { parseRepo } from "./url.js";
  * repository. Whatever the token can reach, an agent talked into naming it can
  * reach. See the README — the token wants to be fine-grained.
  */
-/** This plugin's tool-family name, as a recipe's `toolFamilies` lists it. */
-export declare const REPO_FAMILY = "repo";
-/** Run one command in the host's container. Matches `computerExec`'s shape. */
+/** Run one command in the host's container. Matches `workspaceExec`'s shape. */
 export type RepoExec = (command: string, options?: {
     cwd?: string;
     env?: Record<string, string | undefined>;
     timeout?: number;
     /**
-     * The executing subtask's runtime state, forwarded **opaquely**.
+     * The running sub-agent's `runtime()`, forwarded **opaquely**.
      *
-     * This plugin never looks inside it. A delegated subtask has to reach the
-     * container its parent prepared, and the key for that lives in the runtime
-     * state the parent resolved — but decoding it is the container plugin's
+     * This plugin never looks inside it. A sub-agent has to reach the
+     * container its parent prepared, and the key for that lives in what the
+     * parent's `prepare` returned — but decoding it is the container plugin's
      * business, not git's. Passing it through untouched is what lets the two
-     * plugins compose
-     * without either importing the other, which is the whole reason `exec` is
-     * injected rather than imported.
+     * plugins compose without either importing the other, which is the whole
+     * reason `exec` is injected rather than imported.
      */
     runtime?: unknown;
 }) => Promise<{
@@ -92,7 +89,7 @@ export type RepoExec = (command: string, options?: {
     exitCode: number;
 }>;
 /**
- * The three git operations that need the forge token, run by the host.
+ * The three git operations that need the GitHub token, run by the host.
  *
  * Injected for the same reason {@link RepoExec} is — this plugin owns the
  * policy, not the plumbing — but the split between the two is not arbitrary. It
@@ -101,7 +98,7 @@ export type RepoExec = (command: string, options?: {
  * keeps its secret and never touches the container at all.
  *
  * That is why `clone`, `fetch` and `push` are the whole interface. They are
- * exactly the operations that talk to the forge. `status`, `diff`, `add`,
+ * exactly the operations that talk to GitHub. `status`, `diff`, `add`,
  * `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.
  *
@@ -116,7 +113,8 @@ export type RepoExec = (command: string, options?: {
  * branch that does not resolve, a repository that is not there — all of it comes
  * back as `ok: false`, because those are answers. A rejection means the host
  * itself could not be reached, which is a different fact and gets a different
- * sentence from every tool in this file. See {@link RunResult}.
+ * sentence from every tool in this file. See
+ * {@link file://./context.ts RunResult}.
  */
 export interface RepoGit {
     /**
@@ -153,6 +151,14 @@ export interface RepoGit {
         branch: string;
         allowedHosts: string[];
     }): Promise<RepoGitResult>;
+    /**
+     * The checkout's `origin` URL, read on the host's side; `undefined` for none.
+     *
+     * Optional. Set, the GitHub tools resolve their repository without the
+     * container, so an agent polling a pull request does not keep one running.
+     * Unset, the origin is read through {@link RepoConfig.exec}.
+     */
+    origin?(dir: string): Promise<string | undefined>;
 }
 /** What a {@link RepoGit} operation reports. */
 export type RepoGitResult = {
@@ -167,14 +173,14 @@ export interface RepoConfig {
     /**
      * Runs commands in the container holding the checkout.
      *
-     * Uncredentialed, always. Nothing this runs is ever given the forge token —
+     * Uncredentialed, always. Nothing this runs is ever given the GitHub token —
      * see {@link RepoGit} for the operations that need one.
      */
     exec: RepoExec;
     /** Runs the three credentialed operations, on the host's side of the boundary. */
     git: RepoGit;
     /**
-     * A forge token with contents+pull-request write. A thunk so a rotated secret
+     * A GitHub token with contents+pull-request write. A thunk so a rotated secret
      * is picked up without rebuilding the plugin list.
      */
     token: () => string;
@@ -203,9 +209,9 @@ export interface RepoConfig {
      * 16,000 non-ASCII characters is three times that many UTF-8 bytes.
      *
      * `repo_diff` is the main input for an agent that
-     * reviews rather than writes — a delegating coder whose subagents hold the
-     * shell — and an unbounded diff on a large change is precisely the context
-     * blowup that design exists to prevent.
+     * reviews rather than writes — a coder whose sub-agents hold the shell — and
+     * an unbounded diff on a large change is precisely the context blowup that
+     * design exists to prevent.
      */
     maxOutputChars?: number;
     /**
@@ -226,7 +232,7 @@ export interface RepoConfig {
      * not — a host that stored the path alongside its install state found that a
      * repository the resolver had nothing to install in (no `package.json`) cloned
      * perfectly, reported itself correctly, and could never be worked in, because
-     * the one path its subagents needed was written on a branch that never ran.
+     * the one path its sub-agents needed was written on a branch that never ran.
      *
      * Awaited, so it can record intent durably, but it must **return quickly**:
      * it runs inside `repo_clone`, which runs inside a model turn. A host that
@@ -263,6 +269,50 @@ export interface RepoConfig {
         owner: string;
         repo: string;
     }) => void;
+    /**
+     * The worktrees a host keeps for its sub-agents' work, and the way between
+     * them.
+     *
+     * Set, the plugin offers `repo_worktrees` and `repo_worktree`. A switch moves
+     * the installing agent's own tools, so a host sets this on the parent's
+     * install and never on a sub-agent's. See {@link RepoWorktrees}.
+     */
+    worktrees?: RepoWorktrees;
+    /**
+     * The tools this install offers, and with them the lines of context that
+     * describe them. Unset, every tool. A selection rather than core's
+     * `restrictTools`, which drops a plugin's context whole: an agent that
+     * coordinates others' work reads about the tools it has and no others.
+     */
+    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 type RepoToolName = (typeof REPO_TOOL_NAMES)[number];
+/**
+ * Checkouts a host keeps apart from the main one — each holding a branch its
+ * writing sub-agents committed on — and the switch that points every repo tool
+ * at one of them.
+ *
+ * The host renders every answer: which worktrees exist, where their checkouts
+ * sit and what is safe to do in them are its facts, and a sentence is what the
+ * model reads.
+ */
+export interface RepoWorktrees {
+    /** Every worktree, with its branch and state. */
+    list(): Promise<string>;
+    /**
+     * Point every repo tool — and whatever else the host routes the same way — at
+     * the worktree holding `branch`, or back at the main checkout when it is absent.
+     * Answers what the model now has in front of it.
+     *
+     * The switch holds until the next one. This answer is what the model
+     * remembers, so a host that moves the tools on its own says so where the
+     * model reads it every turn.
+     */
+    use(branch?: string): Promise<string>;
+    /** Give up `branch`'s worktree, and the unpushed work in it. */
+    release(branch: string): Promise<string>;
 }
 /** What {@link RepoConfig.afterCheckout} is told about a checkout. */
 export interface RepoCheckout {
@@ -293,35 +343,7 @@ export interface RepoCheckout {
     fresh: boolean;
 }
 /**
- * Middle-out truncation, so both the head of a diff and its tail survive.
- *
- * Deliberately a **copy** of the computer plugin'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 `computer` (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 declare function truncateOutput(text: string, max: number): string;
-export declare function buildRepoTools(config: RepoConfig, 
-/** Forwarded to every `exec`; see {@link RepoExec}'s `runtime` option. */
-runtime?: unknown): ToolSet;
-/**
- * The repo tools a person approves before they run: opening a pull request, and
- * nothing else. Pushing a work branch and commenting run without asking.
- *
- * The reason is what the person reads beside Approve and Reject, so it says what
- * the call will do in their terms: which repository, from which branch into
- * which, and under what title. The repository is the checkout's origin, read
- * through the same lookup the tool runs, so a directory named after one
- * repository cannot present a pull request on another. The input has already
- * passed the tool's own schema. What a rule is, and whose calls it covers, is
- * core's to say — see `AgentPlugin.mainAgentToolApproval`.
+ * No tool here is held for a person's approval — see this plugin's README for
+ * why, and for what a fork that wants one does instead.
  */
-export declare function repoToolApproval(config: RepoConfig): MainAgentToolApproval;
 export declare function repo(config: RepoConfig): AgentPlugin;