@dynamicagents/plugins 0.11.1 → 0.13.0

package/dist/repo/checkout.d.ts

@@ -21,8 +21,8 @@ interface RefreshOutcome {
 /**
  * What this module needs back from a git command.
  *
- * A structural subset of `index.ts`'s `RunResult` rather than an import of it,
- * so the dependency runs one way: `index.ts` knows about this file, and this file
+ * A structural subset of `context.ts`'s `RunResult` rather than an import of it,
+ * so the dependency runs one way: the tools know about this file, and this file
  * knows only about the shape of an answer. `unreachable` is the field that earns
  * the type — a command that *ran and failed* has answered the question it was
  * asked, and one that never ran has answered nothing, which two refusals below
@@ -34,7 +34,7 @@ export interface GitAnswer {
     stderr: string;
     unreachable?: true;
 }
-/** The two runners `refreshCheckout` borrows from `repoSurface`. */
+/** The two runners `refreshCheckout` borrows from `repoContext`. */
 export interface GitRunners {
     plain: (args: string, cwd: string, vars?: Record<string, string>) => Promise<GitAnswer>;
     /**
@@ -64,23 +64,52 @@ export declare function resolveDefaultBranch(plain: GitRunners["plain"], dir: st
     branch?: string;
     unreachable?: string;
 }>;
+/**
+ * Write the identity this checkout's commits carry into its own config.
+ *
+ * **Repo-local, and repeated on every clone and every refresh.** The workspace
+ * outlives the deployment's configuration: written once, at the clone, it is
+ * frozen — change the configured name and every checkout that already exists
+ * goes on committing under the old one, with nothing in the tree saying why.
+ * Rewriting costs two commands against a checkout that is being set up anyway.
+ *
+ * It is the *nearest* answer, not the only one. `repo_commit` names the identity
+ * on the commit itself, which is the one layer a stale config cannot outrank.
+ * Underneath, a repository this plugin never cloned falls back to whatever the
+ * shell's own git is configured with — which is an identity rather than nothing
+ * only where `exec` is backed by `/workspace`, whose object writes one per
+ * container; see {@link file://../workspace/git-identity.ts}. `exec` is an arbitrary
+ * runner, so that is a property of a deployment, not of this plugin.
+ *
+ * Unchecked, like the config pins at the clone: git's identity is needed by the
+ * first commit, and a failure to write it fails that commit with a sentence far
+ * clearer than anything this could report from here.
+ */
+export declare function writeGitIdentity(plain: GitRunners["plain"], dir: string, author: {
+    name: string;
+    email: string;
+}): Promise<void>;
 /**
  * Bring an existing checkout back to a clean, current state.
  *
  * The workspace outlives the task, so a clone target may already hold one —
  * where `git clone` fails with "destination path already exists and is not an
- * empty directory" and the round has to improvise from an error that reads like
+ * empty directory" and the model has to improvise from an error that reads like
  * a bug.
  *
  * The refusal on a dirty tree is the important half. Uncommitted changes there
  * are a *previous task's work* — possibly the thing a human is waiting on — and
  * silently `reset --hard`ing them away to make a fresh clone look clean is the
- * one outcome nobody could recover from. Refusing costs a round; discarding
+ * one outcome nobody could recover from. Refusing costs a tool call; discarding
  * costs the work.
  */
-export declare function refreshCheckout({ dir, url, branch, plain, fetchOrigin }: GitRunners & {
+export declare function refreshCheckout({ dir, url, branch, author, plain, fetchOrigin }: GitRunners & {
     dir: string;
     url: string;
     branch: string | undefined;
+    author: {
+        name: string;
+        email: string;
+    };
 }): Promise<RefreshOutcome>;
 export {};

package/dist/repo/checkout.js

@@ -21,21 +21,50 @@ export async function resolveDefaultBranch(plain, dir) {
         ? { branch: head.stdout.trim().replace(/^origin\//, "") }
         : {};
 }
+/**
+ * Write the identity this checkout's commits carry into its own config.
+ *
+ * **Repo-local, and repeated on every clone and every refresh.** The workspace
+ * outlives the deployment's configuration: written once, at the clone, it is
+ * frozen — change the configured name and every checkout that already exists
+ * goes on committing under the old one, with nothing in the tree saying why.
+ * Rewriting costs two commands against a checkout that is being set up anyway.
+ *
+ * It is the *nearest* answer, not the only one. `repo_commit` names the identity
+ * on the commit itself, which is the one layer a stale config cannot outrank.
+ * Underneath, a repository this plugin never cloned falls back to whatever the
+ * shell's own git is configured with — which is an identity rather than nothing
+ * only where `exec` is backed by `/workspace`, whose object writes one per
+ * container; see {@link file://../workspace/git-identity.ts}. `exec` is an arbitrary
+ * runner, so that is a property of a deployment, not of this plugin.
+ *
+ * Unchecked, like the config pins at the clone: git's identity is needed by the
+ * first commit, and a failure to write it fails that commit with a sentence far
+ * clearer than anything this could report from here.
+ */
+export async function writeGitIdentity(plain, dir, author) {
+    // Through the environment, so a configured name containing a quote stays a
+    // value rather than becoming shell.
+    await plain(`config user.name "$GIT_NAME"`, dir, { GIT_NAME: author.name });
+    await plain(`config user.email "$GIT_EMAIL"`, dir, {
+        GIT_EMAIL: author.email
+    });
+}
 /**
  * Bring an existing checkout back to a clean, current state.
  *
  * The workspace outlives the task, so a clone target may already hold one —
  * where `git clone` fails with "destination path already exists and is not an
- * empty directory" and the round has to improvise from an error that reads like
+ * empty directory" and the model has to improvise from an error that reads like
  * a bug.
  *
  * The refusal on a dirty tree is the important half. Uncommitted changes there
  * are a *previous task's work* — possibly the thing a human is waiting on — and
  * silently `reset --hard`ing them away to make a fresh clone look clean is the
- * one outcome nobody could recover from. Refusing costs a round; discarding
+ * one outcome nobody could recover from. Refusing costs a tool call; discarding
  * costs the work.
  */
-export async function refreshCheckout({ dir, url, branch, plain, fetchOrigin }) {
+export async function refreshCheckout({ dir, url, branch, author, plain, fetchOrigin }) {
     const remote = await plain("remote get-url origin", dir);
     // Interrogated, for the same reason the `status` below is: a question that went
     // unanswered is not the answer "some other repository". Read as one, an
@@ -59,12 +88,24 @@ export async function refreshCheckout({ dir, url, branch, plain, fetchOrigin })
                 `not ${url}. Pick a different directory or work with the checkout that is there.`
         };
     }
+    // Ahead of every refusal below, and deliberately: a refusal leaves the *tree*
+    // untouched, which is what those sentences promise. An identity is not tree
+    // state, and a dirty tree is the case where somebody is about to commit —
+    // exactly when a stale name would be spent.
+    await writeGitIdentity(plain, dir, author);
     // Interrogated, not assumed. Empty stdout from a `status` that *failed* is not
     // a clean tree, it is no answer at all — and the next two commands are `fetch`
     // and `reset --hard`. Conflating the two lets a permissions error or a
     // half-written index discard a tree nobody established was clean, which is the
     // one loss in this file that cannot be undone.
-    const dirty = await plain("status --porcelain", dir);
+    //
+    // Submodules are left out of the question. Neither `checkout` nor
+    // `reset --hard` below touches a submodule's tree without
+    // `--recurse-submodules`, so a submodule that has moved past its pin — which
+    // is what a superproject looks like after its own sync — is not work this
+    // refresh could lose. Counted as dirty, it would refuse every refresh of such
+    // a checkout, and a host's `afterCheckout` would never learn it is there.
+    const dirty = await plain("status --porcelain --ignore-submodules=all", dir);
     if (!dirty.success) {
         return {
             message: `could not read the state of the checkout at ${dir}: ` +
@@ -86,9 +127,26 @@ export async function refreshCheckout({ dir, url, branch, plain, fetchOrigin })
                 `Nothing was fetched or reset.`
         };
     }
+    /**
+     * A failed fetch leaves a checkout that is still there, still clean and still
+     * on its branch — only not updated. So it is still reported, on the branch it
+     * is on: a host that records checkouts would otherwise lose sight of one that
+     * exists because its remote could not be reached, and a clone taken from the
+     * recorded url goes to the remote itself. Nothing below — no checkout, no
+     * reset — runs against a tree whose remote state is unknown.
+     */
     const fetched = await fetchOrigin(dir, url);
-    if (!fetched.success)
-        return { message: `fetch failed: ${fetched.stderr || fetched.stdout}` };
+    if (!fetched.success) {
+        const failure = `fetch failed: ${fetched.stderr || fetched.stdout}`;
+        const current = await plain("symbolic-ref --quiet --short HEAD", dir);
+        const on = current.success ? current.stdout.trim() : "";
+        if (!on)
+            return { message: failure };
+        return {
+            message: `${failure}\nThe checkout was left on ${on}, clean but not updated from the remote.`,
+            branch: on
+        };
+    }
     // The branch to land on: the one asked for, else the remote's own default.
     let target = branch;
     if (!target) {

package/dist/repo/context.d.ts

@@ -0,0 +1,135 @@
+import type { ActionContext } from "@cloudflare/think";
+import type { RepoCheckout, RepoConfig, RepoExec, RepoGitResult } from "./index.js";
+/**
+ * How many items one GitHub list call asks for. GitHub's maximum, and its default
+ * without this is 30.
+ *
+ * One page, never a Link-header walk: an unbounded fetch loop does not belong
+ * inside a model turn, and the render is bounded by `maxOutputChars` anyway. What
+ * matters is that a full page is *reported* as possibly partial rather than
+ * presented as the whole answer — a pull request's newest review comments are on
+ * the last page, and those are exactly the ones an agent was sent to act on.
+ */
+export declare 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.
+ */
+export declare function graphqlEndpoint(apiBase: string): string;
+/**
+ * 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 declare function truncateOutput(text: string, max: number): string;
+/**
+ * What one container command produced — plus one bit the container did not.
+ *
+ * `exec` does not only *return* failures, it throws them: `@cloudflare/computer`
+ * throws `EEXEC_LOST` when a container is replaced mid-command, and any call to a
+ * Durable Object can fail outright. Both are caught at the seam
+ * ({@link repoContext}'s `run`) and turned into a failed result, so every tool
+ * answers in its own `!success` branch — "could not read the status of /w/r: …"
+ * is a better sentence than any wrapper one level up could write, and a seventh
+ * tool calling `plain` gets it without being told.
+ *
+ * `unreachable` is for the branches that must tell the two apart. A command that
+ * ran and failed has answered the question it was asked; a command that never ran
+ * has answered nothing, and three places here read a failure as an answer.
+ */
+export type RunResult = Awaited<ReturnType<RepoExec>> & {
+    unreachable?: true;
+};
+/** What {@link repoContext} hands each group of tools. */
+export interface RepoContext {
+    config: RepoConfig;
+    workdir: string;
+    author: {
+        name: string;
+        email: string;
+    };
+    allowedHosts: string[];
+    bounded: (text: string) => string;
+    notifyCheckout: (checkout: RepoCheckout) => Promise<void>;
+    logFailure: (tool: string, detail: {
+        exitCode?: number;
+        stderr?: string;
+        stdout?: string;
+    }) => void;
+    plain: (args: string, cwd: string, vars?: Record<string, string>) => Promise<RunResult>;
+    runGit: (op: () => Promise<RepoGitResult>) => Promise<RunResult>;
+    fetchOrigin: (dir: string, url: string) => Promise<RunResult>;
+    pushBranch: (dir: string, url: string, branch: string) => Promise<RunResult>;
+    origin: (dir: string) => Promise<{
+        remote?: {
+            host: string;
+            url: string;
+        };
+        unreachable?: string;
+    }>;
+    github: (tool: string, path: string, init?: {
+        method: string;
+        body: unknown;
+    }) => Promise<{
+        ok: true;
+        data: unknown;
+    } | {
+        ok: false;
+        message: string;
+    }>;
+    githubGraphql: (tool: string, query: string, variables: Record<string, unknown>) => Promise<{
+        ok: true;
+        data: unknown;
+    } | {
+        ok: false;
+        message: string;
+    }>;
+    githubRepo: (dir: string) => Promise<{
+        owner: string;
+        repo: string;
+    } | {
+        refusal: string;
+    }>;
+}
+/**
+ * How long an action that calls GitHub may run before Think gives up on it.
+ *
+ * An action's default is thirty seconds, which is {@link GITHUB_TIMEOUT_MS}
+ * alone — and a thread reply is three GitHub calls, after an `origin` read that
+ * waits its turn in the git queue.
+ */
+export declare const GITHUB_ACTION_TIMEOUT_MS = 120000;
+/**
+ * The task an action runs for, which leads its idempotency key.
+ *
+ * Think replays a settled key for as long as it keeps the row
+ * (`actionLedgerRetention`), so a key without the task would replay, not post,
+ * the same comment in a later task. Every turn core runs carries a task id, so
+ * a missing one is a wiring fault — and keying without it would be the silent
+ * version of that fault.
+ */
+export declare function actionTask(ctx: ActionContext): string;
+/** A hex SHA-256, so a key names a body without carrying it. */
+export declare function sha256(text: string): Promise<string>;
+export declare function repoContext(config: RepoConfig, 
+/**
+ * The running sub-agent's `runtime()`, read per command. Forwarded to every
+ * `exec`; see {@link RepoExec}'s `runtime` option.
+ */
+runtime?: () => unknown): RepoContext;