@dynamicagents/plugins 0.10.3 → 0.11.0

package/README.md

@@ -136,8 +136,9 @@ npm run verify:exports
 
 ### Working against an unpublished core
 
-`@dynamicagents/core` is a **peer** dependency, so a plain `npm install` always resolves
-it from the registry — including over a local build you are testing against.
+A plain `npm install` resolves `@dynamicagents/core` from whatever this branch's
+`package.json` declares — `AGENTS.md` says which — and does it right over a local build
+you are testing against.
 
 ```bash
 npm run link:local   # npm pack + tarball install from ../core
@@ -150,7 +151,7 @@ repo's source for a contract change sitting uninstalled one directory away.
 `npm pack` + tarball, deliberately — not `npm link`, which symlinks the checkout and
 gives it its own copy of every peer. Two copies of `agents` in one bundle breaks the
 `Session` types and every `instanceof`, at runtime rather than at the type level.
-Nothing is written to `package.json`, so CI still builds against the real packages.
+Nothing is written to `package.json`, so CI never builds against a local checkout.
 
 `test/arc-agi/recorded.spec.ts` drives the **real** ARC API and replays a committed
 cassette, so it needs no key either. Re-record it against the live API with:

package/dist/arc-agi/client.d.ts

@@ -14,6 +14,10 @@ import { type CookieJar, type FrameResponse, type GameInfo, type ScorecardSummar
  *   exponential backoff. Exhausted retries and 5xx throw (transient — the
  *   Workflow step retries and the runner resumes from its checkpoint); a 401
  *   throws a tagged deterministic error (bad key — a terminal failure).
+ * - **Cancellation**: a client built with a `signal` stops at it — the `fetch` and
+ *   the backoff between retries alike. `Retry-After` is honoured up to
+ *   {@link MAX_RETRY_AFTER_MS} and no further: the header is the server's to set,
+ *   and an uncapped one parks a tool for as long as the server likes.
  */
 export interface ArcClient {
     listGames(cookies: CookieJar): Promise<{
@@ -53,6 +57,12 @@ export interface ArcClient {
         cookies: CookieJar;
     }>;
 }
+/**
+ * The longest a `Retry-After` is waited out. A minute covers the API's own
+ * per-minute rate window; past that the header is either hostile or describing an
+ * outage, and a retry loop is the wrong place to sit through either.
+ */
+export declare const MAX_RETRY_AFTER_MS = 60000;
 /** Message prefix of the deterministic (non-retryable) auth error. */
 export declare const ARC_AUTH_ERROR = "arc-client: unauthorized";
 export interface ArcClientOptions {
@@ -61,5 +71,11 @@ export interface ArcClientOptions {
     sleep?: (ms: number) => Promise<void>;
     /** Max attempts per request before a 429/5xx becomes a thrown transient fault. */
     maxAttempts?: number;
+    /**
+     * Stops every request this client makes, and every wait between them. Taken at
+     * construction, because a client built for one tool surface stops on that
+     * surface's signal — core's `ToolFamilyContext.signal` for a subagent's.
+     */
+    signal?: AbortSignal;
 }
 export declare function makeArcClient(apiKey: string, options?: ArcClientOptions): ArcClient;

package/dist/arc-agi/client.js

@@ -1,4 +1,11 @@
+import { withAbort } from "@dynamicagents/core";
 import { ARC_BASE_URL } from "./types.js";
+/**
+ * The longest a `Retry-After` is waited out. A minute covers the API's own
+ * per-minute rate window; past that the header is either hostile or describing an
+ * outage, and a retry loop is the wrong place to sit through either.
+ */
+export const MAX_RETRY_AFTER_MS = 60_000;
 /** Message prefix of the deterministic (non-retryable) auth error. */
 export const ARC_AUTH_ERROR = "arc-client: unauthorized";
 const realSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
@@ -23,6 +30,7 @@ export function makeArcClient(apiKey, options = {}) {
     const doFetch = options.fetchFn ?? fetch;
     const sleep = options.sleep ?? realSleep;
     const maxAttempts = options.maxAttempts ?? 4;
+    const signal = options.signal;
     async function request(path, init, cookies) {
         const headers = {
             "X-API-Key": apiKey,
@@ -39,7 +47,8 @@ export function makeArcClient(apiKey, options = {}) {
             const res = await doFetch(`${ARC_BASE_URL}${path}`, {
                 method: init.method,
                 headers,
-                body: init.body === undefined ? undefined : JSON.stringify(init.body)
+                body: init.body === undefined ? undefined : JSON.stringify(init.body),
+                ...(signal ? { signal } : {})
             });
             if (res.ok) {
                 const nextCookies = mergeCookies(cookies, res);
@@ -56,9 +65,11 @@ export function makeArcClient(apiKey, options = {}) {
             }
             const retryAfter = Number(res.headers.get("retry-after"));
             const backoffMs = Number.isFinite(retryAfter) && retryAfter > 0
-                ? retryAfter * 1000
+                ? Math.min(retryAfter * 1000, MAX_RETRY_AFTER_MS)
                 : Math.min(1000 * 2 ** (attempt - 1), 8000);
-            await sleep(backoffMs);
+            // The wait between attempts is the longest thing this loop does, so it is
+            // the part a cancel most needs to reach.
+            await withAbort(signal, sleep(backoffMs));
         }
     }
     return {

package/dist/arc-agi/tools.js

@@ -45,7 +45,9 @@ export function buildArcGameTools(apiKey, ctx) {
     // cannot do — `Env` is the ambient interface `wrangler types` generates into a
     // *consumer's* app and does not exist here. Config-at-instantiation is also
     // the only thing that works on Workers at all, where `env` has no module scope.
-    const client = makeArcClient(apiKey);
+    // The execution's signal goes in the same way, so a cancel reaches a request or
+    // a backoff without every call having to carry it.
+    const client = makeArcClient(apiKey, { signal: ctx.signal });
     const runtime = runtimeAs(ctx.runtime);
     // All settled before the model runs — it cannot pick a different game, and it
     // cannot see, choose, or name a card or a play at all. The game is the type's
@@ -249,6 +251,18 @@ export function buildArcGameTools(apiKey, ctx) {
                     // exactly as a crash mid-action always was.
                     session.pendingAction = { action, x, y };
                     await save(session);
+                    // A cancel is checked here, with the intent already on disk, because this
+                    // is the last moment before the request: a check ahead of the write would
+                    // miss a cancel that lands during it. A request on an aborted signal is
+                    // never sent, so the intent is taken back rather than left for the next
+                    // chunk to warn about a move that never left. The batch ends the ordinary
+                    // way, with every step already sent recorded.
+                    if (ctx.signal?.aborted) {
+                        session.pendingAction = null;
+                        await save(session);
+                        trace.push(remaining(steps.length, index, "this call was cancelled"));
+                        break;
+                    }
                     const { frame, cookies } = await client.act({ action, gameId: session.gameId, guid: session.guid, x, y, note }, session.cookies);
                     // Diff against the board as it was immediately BEFORE this step, so each
                     // line attributes its change to the one action that caused it. That

package/dist/computer/index.js

@@ -52,7 +52,7 @@ var __disposeResources = (this && this.__disposeResources) || (function (Suppres
 });
 import { tool } from "ai";
 import { z } from "zod";
-import { definePlugin } from "@dynamicagents/core";
+import { definePlugin, withAbort } from "@dynamicagents/core";
 import { getWorkspace, shellQuote } from "@cloudflare/computer";
 import { guardPath } from "./paths.js";
 import { cancelledNote, humanBytes, packBlocks, renderGrepMatches, renderResult } from "./render.js";
@@ -290,6 +290,31 @@ export function withShell(command, shell) {
 export function withShellTranscript(command, shell) {
     return shell ? `${wrapped(command, shell)} 2>&1` : command;
 }
+/**
+ * Wait for a disposable resource without outliving `signal`.
+ *
+ * `withAbort` can abandon the wait but not the resource, and one that arrives
+ * after its caller has given up has nobody left to dispose it. So it is released
+ * on arrival instead — disposed by default, or handed to `release` where
+ * disposing alone would leave work running.
+ */
+function acquire(signal, opening, release = (resource) => resource[Symbol.dispose]()) {
+    return withAbort(signal, opening, () => {
+        void opening.then(release).catch(() => { });
+    });
+}
+/**
+ * How an exec handle that arrived too late is released. Disposing only detaches
+ * this side, so the process is killed first.
+ */
+async function killLate(handle) {
+    try {
+        await handle.kill("SIGTERM");
+    }
+    finally {
+        handle[Symbol.dispose]();
+    }
+}
 export function buildComputerTools(workspace, config, advisories) {
     const cwd = config.cwd ?? DEFAULT_CWD;
     const timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
@@ -311,7 +336,7 @@ export function buildComputerTools(workspace, config, advisories) {
      * it was dropping. The cost is one same-colo RPC on commands that previously
      * skipped it, against a class of silent data loss.
      */
-    const awaitAdvisories = async (command) => {
+    const awaitAdvisories = async (command, signal) => {
         if (!advisories)
             return {};
         // Fails **open**, and that belongs here rather than at the call site: this
@@ -321,9 +346,14 @@ export function buildComputerTools(workspace, config, advisories) {
         // subagent.
         const read = async () => {
             try {
-                return await advisories();
+                signal?.throwIfAborted();
+                return await withAbort(signal, advisories());
             }
-            catch {
+            catch (err) {
+                // Open on a failed read, never on a cancel: failing open here would go on
+                // to run the command the caller just gave up on.
+                if (signal?.aborted)
+                    throw err;
                 return [];
             }
         };
@@ -338,7 +368,9 @@ export function buildComputerTools(workspace, config, advisories) {
         // the outcome.
         while (execGate(current, command).block && Date.now() < deadline) {
             const wait = Math.min(INSTALL_POLL_MS, deadline - Date.now());
-            await new Promise((resolve) => setTimeout(resolve, wait));
+            // Throws on a cancel rather than returning the verdict so far: a gate that
+            // outlived its caller would otherwise go on to run the command it was holding.
+            await withAbort(signal, new Promise((resolve) => setTimeout(resolve, wait)));
             current = await read();
         }
         return execGate(current, command);
@@ -444,7 +476,7 @@ export function buildComputerTools(workspace, config, advisories) {
                     .optional()
                     .describe(`Working directory (default: ${cwd})`)
             }),
-            execute: async ({ command, cwd: overrideCwd }) => {
+            execute: async ({ command, cwd: overrideCwd }, { abortSignal }) => {
                 /**
                  * One line per command, and it is the only view of where a task's wall
                  * clock actually goes.
@@ -462,13 +494,50 @@ export function buildComputerTools(workspace, config, advisories) {
                  * indistinguishable from the outside and want opposite fixes.
                  */
                 const startedAtMs = Date.now();
+                /**
+                 * What the model is told when this call stops before the command
+                 * finishes. Said plainly, because the likeliest next move after a bare
+                 * error is the same command again — and whether that is right depends on
+                 * where the call stopped. A command that outran the limit once will again;
+                 * one that never started because the workspace did not answer may not.
+                 *
+                 * `sb_exec` reads its call's signal rather than leaving the wait to core,
+                 * and this is why: core's abandonment can say only that the command may
+                 * still be running. Core's `TOOL_CALL_GRACE_MS` is the window this answer
+                 * has to arrive in, and it covers sending the kill below.
+                 */
+                const stopped = (gateMs, started) => {
+                    const timedOut = abortSignal?.reason?.name ===
+                        "TimeoutError";
+                    console.info("[computer] sb_exec stopped", {
+                        command,
+                        gateMs,
+                        durationMs: Date.now() - startedAtMs - gateMs,
+                        started,
+                        reason: timedOut ? "time limit" : "cancelled"
+                    });
+                    if (!timedOut)
+                        return "the command was stopped because this call was cancelled. Anything it changed before then is still changed.";
+                    return started
+                        ? "the command was stopped: it ran past this call's time limit. Anything it changed before then is still changed. Try something narrower."
+                        : "the command did not run: this call reached its time limit while the workspace was still getting ready, so nothing was changed. Try again; if it happens again, the workspace is not responding.";
+                };
                 // Only `sb_exec` waits on an install. The file tools read and write
                 // source, which is in the workspace and unaffected by an install in
                 // flight — blocking them would stop the subagent doing the reading it
                 // could usefully do while it waits. They do consult `writeGate`, which
                 // is a different question: not "is the tree ready" but "does a write
                 // survive at all".
-                const gate = await awaitAdvisories(command);
+                let gate;
+                try {
+                    gate = await awaitAdvisories(command, abortSignal);
+                }
+                catch (err) {
+                    // Only a cancel gets out of the gate; a failed advisory read opens it.
+                    if (abortSignal?.aborted)
+                        return stopped(Date.now() - startedAtMs, false);
+                    throw err;
+                }
                 const gateMsWaited = Date.now() - startedAtMs;
                 if (gate.block) {
                     console.info("[computer] sb_exec blocked by a workspace advisory", {
@@ -481,10 +550,15 @@ export function buildComputerTools(workspace, config, advisories) {
                 // is context for the output, not a substitute for it — which is why it
                 // is carried through the catch as well.
                 const note = (body) => gate.warn ? `${gate.warn}\n\n${body}` : body;
+                // Set once the exec is sent. See `stopped`.
+                let started = false;
                 try {
                     const env_2 = { stack: [], error: void 0, hasError: false };
                     try {
-                        const ws = __addDisposableResource(env_2, await workspace(), false);
+                        // A workspace that stops answering would hold the call before any of the
+                        // cancellation below is reached.
+                        abortSignal?.throwIfAborted();
+                        const ws = __addDisposableResource(env_2, await acquire(abortSignal, workspace()), false);
                         // Read once per command. This is the *host's* thunk, so calling it
                         // twice in the construction of one command's options is two chances to
                         // disagree — the check and the value would come from different reads.
@@ -497,8 +571,17 @@ export function buildComputerTools(workspace, config, advisories) {
                         };
                         // Transcript, not two streams: this result goes to a model, which
                         // reads it as a terminal session rather than parsing it.
-                        const handle = __addDisposableResource(env_2, await ws.runtime.exec(withShellTranscript(command, config.shell), options), false);
-                        const result = await handle.result();
+                        // Not started at all on a signal that has already fired: a process that
+                        // is killed on the next line still ran long enough to change something.
+                        abortSignal?.throwIfAborted();
+                        // From here a stop cannot promise nothing ran: the exec may reach the
+                        // container before its handle reaches this side.
+                        started = true;
+                        const handle = __addDisposableResource(env_2, await acquire(abortSignal, ws.runtime.exec(withShellTranscript(command, config.shell), options), killLate), false);
+                        // The runtime takes no signal, so stopping the wait and stopping the
+                        // process are two acts. Disposing the handle is neither — it releases
+                        // this side's attachment and leaves the command running.
+                        const result = await withAbort(abortSignal, handle.result(), () => handle.kill("SIGTERM"));
                         console.info("[computer] sb_exec", {
                             command,
                             exitCode: result.exitCode,
@@ -520,6 +603,8 @@ export function buildComputerTools(workspace, config, advisories) {
                     }
                 }
                 catch (err) {
+                    if (abortSignal?.aborted)
+                        return note(stopped(gateMsWaited, started));
                     const lost = execLostNote(err);
                     console.warn("[computer] sb_exec failed", {
                         command,

package/dist/recall/index.js

@@ -119,10 +119,7 @@ export function recall(config) {
             });
             const { embeddings } = await embedMany({
                 model: provider.embedding(embeddingModelId),
-                values: texts,
-                // Failures surface to the caller; archival is best-effort and the SDK's
-                // backoff would only add latency in front of a compaction.
-                maxRetries: 0
+                values: texts
             });
             return embeddings;
         });

package/dist/repo/checkout.d.ts

@@ -34,7 +34,7 @@ export interface GitAnswer {
     stderr: string;
     unreachable?: true;
 }
-/** The two runners `refreshCheckout` borrows from `buildRepoTools`. */
+/** The two runners `refreshCheckout` borrows from `repoSurface`. */
 export interface GitRunners {
     plain: (args: string, cwd: string, vars?: Record<string, string>) => Promise<GitAnswer>;
     /**

package/dist/repo/index.d.ts

@@ -1,5 +1,5 @@
 import type { ToolSet } from "ai";
-import type { AgentPlugin } from "@dynamicagents/core";
+import type { AgentPlugin, MainAgentToolApproval } from "@dynamicagents/core";
 /**
  * The URL parsing, re-exported from the one entry point.
  *
@@ -311,4 +311,17 @@ 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`.
+ */
+export declare function repoToolApproval(config: RepoConfig): MainAgentToolApproval;
 export declare function repo(config: RepoConfig): AgentPlugin;

package/dist/repo/index.js

@@ -157,7 +157,7 @@ function unreachableNote(err) {
  * `repo_push` race: the commit fails, the push succeeds against the previous
  * state, and the round reports work that never landed.
  *
- * Held here rather than in {@link buildRepoTools}'s closure, because that closure
+ * Held here rather than in {@link repoSurface}'s closure, because that closure
  * is too short-lived to be the boundary. Core rebuilds `mainAgentTools` every
  * turn and gives each subagent execution its own tool family, so a per-call queue
  * leaves a subagent racing its parent over one checkout — the same collision, one
@@ -196,6 +196,14 @@ const gitQueues = new WeakMap();
 export function buildRepoTools(config, 
 /** Forwarded to every `exec`; see {@link RepoExec}'s `runtime` option. */
 runtime) {
+    return repoSurface(config, runtime).tools;
+}
+/**
+ * The repo tools, and the approval rule for the one a person approves — one
+ * closure, so the rule reads the checkout through the same `origin` the tool it
+ * gates runs against. See {@link repoToolApproval}.
+ */
+function repoSurface(config, runtime) {
     const workdir = config.workdir ?? DEFAULT_WORKDIR;
     const apiBase = config.apiBase ?? DEFAULT_API_BASE;
     const author = config.author ?? DEFAULT_AUTHOR;
@@ -502,7 +510,7 @@ runtime) {
         // `.git/config`.
         return { remote: { host: location.host, url: location.url } };
     };
-    return {
+    const tools = {
         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({
@@ -1044,11 +1052,63 @@ runtime) {
             }
         })
     };
+    /**
+     * Where a pull request is opened, as the person approving it reads it: the
+     * host, owner and repository of the checkout's origin — what the tool resolves
+     * when it runs. Never the directory's name, which says nothing about where
+     * `.git/config` points. A checkout with no readable origin on an allowed host is
+     * named by its path, and the tool refuses it when it runs.
+     */
+    const destination = async (dir) => {
+        const { remote } = await origin(dir);
+        const parsed = remote ? parseRepo(remote.url, allowedHosts) : undefined;
+        return remote && parsed
+            ? `${remote.host}/${parsed.owner}/${parsed.repo}`
+            : `the checkout at ${approvalField(dir)}, whose origin could not be read`;
+    };
+    const approval = {
+        repo_open_pr: async (input) => {
+            const { dir, head, base, title } = input;
+            return {
+                type: "user-approval",
+                reason: `Open a pull request on ${await destination(dir)} from \`${approvalField(head)}\` into \`${approvalField(base)}\`: ${approvalField(title)}`
+            };
+        }
+    };
+    return { tools, approval };
+}
+/**
+ * The longest branch, title or path a person is shown in full before approving.
+ * Every model-supplied field in a reason is cut to it, so no one input can bury
+ * the rest of what they are deciding.
+ */
+const APPROVAL_FIELD_CHARS = 200;
+/** One model-supplied field of an approval reason, cut to {@link APPROVAL_FIELD_CHARS}. */
+function approvalField(text) {
+    return text.length <= APPROVAL_FIELD_CHARS
+        ? text
+        : `${text.slice(0, APPROVAL_FIELD_CHARS - 1)}…`;
+}
+/**
+ * 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`.
+ */
+export function repoToolApproval(config) {
+    return repoSurface(config).approval;
 }
 export function repo(config) {
     return definePlugin({
         key: "repo",
         mainAgentTools: () => buildRepoTools(config),
+        mainAgentToolApproval: () => repoToolApproval(config),
         // The runtime state goes through to `exec` untouched, so a delegated
         // subtask's git commands run in the same container its parent cloned into.
         toolFamilies: {

package/dist/triage/index.js

@@ -144,10 +144,7 @@ export async function shouldReply(model, history, options = {}) {
         const { output } = await generateText({
             model,
             output: Output.object({ schema: triageSchema }),
-            prompt: buildTriagePrompt(history, options),
-            // Consistent with the rest of the runtime: we handle failure ourselves
-            // (here, by failing open), so SDK backoff would only delay the turn.
-            maxRetries: 0
+            prompt: buildTriagePrompt(history, options)
         });
         // Log the whole verdict, not just the outcome. The booleans are the
         // reasoning — a correct verdict reached through wrong booleans means the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dynamicagents/plugins",
-  "version": "0.10.3",
+  "version": "0.11.0",
   "description": "Optional, composable capabilities for a Dynamic Agent: ARC-AGI-3, browser rendering, a Linux container, git and pull requests, workspace, episodic recall, and pre-turn triage. One subpath per plugin, so a bundle grows only with what it imports.",
   "keywords": [
     "ai-agents",
@@ -85,12 +85,12 @@
     "verify:peer-ranges": "node scripts/verify-peer-ranges.mjs",
     "prepack": "npm run build && npm run verify:exports",
     "prepublishOnly": "npm run check && npm test && npm run verify:exports",
-    "prepare": "husky"
+    "prepare": "husky || true && npm run build"
   },
   "peerDependencies": {
     "@cloudflare/computer": "^0.2.1",
     "@cloudflare/shell": "^0.4.3",
-    "@dynamicagents/core": ">=0.9.0 <0.11.0",
+    "@dynamicagents/core": ">=0.11.0 <0.12.0",
     "agents": ">=0.21.0 <0.23.0",
     "ai": "^7.0.77",
     "drizzle-orm": ">=0.45.2",
@@ -109,7 +109,7 @@
     "@cloudflare/computer": "^0.2.1",
     "@cloudflare/shell": "0.4.3",
     "@cloudflare/vitest-plugin": "^1.1.5",
-    "@dynamicagents/core": "^0.9.0",
+    "@dynamicagents/core": "^0.11.0",
     "@types/node": "^26.5.0",
     "agents": ">=0.21.0 <0.23.0",
     "ai": "^7.0.93",