@dynamicagents/plugins 0.11.1 → 0.13.0

package/dist/claude-code/config.d.ts

@@ -1,5 +1,5 @@
 /**
- * Everything one `claude-coder` deployment tunes, in one shape.
+ * Everything one deployment of this plugin tunes, in one shape.
  *
  * Config at instantiation rather than an `env` argument, for the reason the
  * whole package works this way: `Env` is the ambient interface `wrangler types`
@@ -14,8 +14,16 @@
  * the exact failure this option exists to end. The CLI validates the value too,
  * but it does so by exiting 1 with a message on stderr, and stderr reaches an
  * operator far less reliably than a type error reaches a developer.
+ *
+ * Two of these are worth knowing about before picking one. `default` is not
+ * among the choices the pinned CLI documents, and is accepted and echoed back as
+ * `permissionMode: "default"` anyway — so it stays. `manual` is the reverse: the
+ * CLI documents it and no session here has been run under it, so it is spellable
+ * rather than recommended, and whatever it prompts for the headless path denies.
+ * See {@link ClaudeCodeConfig.permissionMode} for why the default is the
+ * permissive one.
  */
-export type PermissionMode = "default" | "acceptEdits" | "bypassPermissions" | "plan" | "dontAsk" | "auto";
+export type PermissionMode = "default" | "acceptEdits" | "bypassPermissions" | "plan" | "dontAsk" | "manual" | "auto";
 /**
  * What a session runs under when a deployment says nothing.
  *
@@ -25,6 +33,21 @@ export type PermissionMode = "default" | "acceptEdits" | "bypassPermissions" | "
  * {@link ClaudeCodeConfig.permissionMode}.
  */
 export declare const DEFAULT_PERMISSION_MODE: PermissionMode;
+/**
+ * The effort levels `claude --effort` accepts.
+ *
+ * Spelled out for a sharper reason than {@link PermissionMode}: an unrecognised
+ * permission mode exits 1, but an unrecognised effort is **warned about on
+ * stderr and then ignored**, leaving the session at the model's default. A typo
+ * here does not fail, it quietly buys nothing — and stderr from a headless
+ * session reaches an operator far less reliably than a type error reaches a
+ * developer.
+ *
+ * A model that does not carry a level is the same silence: the CLI clamps down
+ * to `high` rather than refusing, so asking for more than a model offers is
+ * indistinguishable from asking for `high`.
+ */
+export type EffortLevel = "low" | "medium" | "high" | "xhigh" | "max";
 export interface ClaudeCodeConfig {
     /**
      * The credential pool, in priority order — index 0 is tried first.
@@ -46,29 +69,31 @@ export interface ClaudeCodeConfig {
      * refused with the reset time.
      */
     credentials: () => readonly string[];
-    /**
-     * Which workspace this agent's sessions run in.
-     *
-     * Resolved on the **parent**, where the verified caller is known: core
-     * dispatches `resolveRuntime` to the plugin that declared the subtask type,
-     * which is this one, and the value it writes is how the subagent facet learns
-     * which Durable Object holds its checkout. A facet cannot work this out for
-     * itself — `callerKey()` throws there by design — and it is deliberately not a
-     * subtask param, because a model-authored workspace name would let a model
-     * name somebody else's.
-     */
-    workspaceName: () => string;
     /** Which model the session runs. Unset, Claude Code picks its own default. */
     model?: string;
     /**
-     * Ceiling on the *outer* session's turns.
+     * How hard the session's model thinks, per turn.
+     *
+     * Unset, the model's own default applies, which is `high` for the frontier
+     * models this plugin exists to reach. Raising it buys depth at a multiple of
+     * the spend, per turn — so the level decides how many sessions a credential
+     * holds, not just how well one thinks. The README's Costs section carries the
+     * multiples and the sizing they imply.
+     *
+     * Not to be confused with the agent's own reasoning effort, which belongs to
+     * a different model on the Worker side. This one reaches only the CLI in the
+     * container.
+     */
+    effort?: EffortLevel;
+    /**
+     * Caps on Claude Code's own subagent tree.
      *
-     * Advisory. Claude Code's own subagent tree multiplies whatever this says, and
-     * the tree is invisible to Dynamic Agents' scheduler. {@link timeoutMs} is
-     * the ceiling that actually holds, because the container runtime enforces it.
+     * Advisory, and the distinction is the reason there is no turn ceiling beside
+     * them — see the README on what this package deliberately does not do. That
+     * tree is invisible to the agent running the session, so it multiplies
+     * whatever these say; {@link timeoutMs} is the ceiling that actually holds, because the
+     * container runtime enforces it.
      */
-    maxTurns?: number;
-    /** Caps on Claude Code's own subagent tree. Advisory, like `maxTurns`. */
     maxSubagentDepth?: number;
     maxConcurrentSubagents?: number;
     /**
@@ -98,6 +123,9 @@ export interface ClaudeCodeConfig {
      *
      * See {@link file://./run.ts buildLaunch} for the root guard this mode trips,
      * which is the other half of making it work.
+     *
+     * A run may set its own, over this one: a planning run's is `plan` — see
+     * {@link file://./model.ts ClaudeCodeModelOptions.permissionMode}.
      */
     permissionMode?: PermissionMode;
     /**
@@ -108,20 +136,20 @@ export interface ClaudeCodeConfig {
      * {@link file://./egress.ts EgressConfig.restrictToHosts} for the full table
      * and for why open is the default.
      *
-     * Whatever this says, the container never needs forge access: `/repo` runs
-     * clone, fetch and push as isomorphic-git inside the workspace object, so the
-     * forge token stays on the Worker side.
+     * A restriction that leaves out `github.com` and `api.github.com` leaves out
+     * {@link githubToken} with them.
      */
     restrictToHosts?: readonly string[];
     /**
-     * How long one chunk blocks before checkpointing and yielding.
+     * GitHub as the deployment's account, for a session that pushes its branch,
+     * opens its pull request and answers its review. Read per request, on the
+     * Worker side.
      *
-     * Must stay under the Workflow step timeout with room to spare, and must be
-     * long enough that a session does not exhaust its branch's chunk allowance
-     * while it is still thinking. Defaults to eight minutes, against a 30-minute
-     * step timeout and a 15-minute soft chunk budget.
+     * The session gets a placeholder as `GH_TOKEN` and as git's credential, and
+     * the egress gateway swaps in this token for GitHub's hosts only — see
+     * {@link file://./github.ts}. Unset, `gh` and git reach GitHub anonymously.
      */
-    windowMs?: number;
+    githubToken?: () => string | undefined;
     /**
      * Ceiling on the whole session, enforced by the container runtime.
      *
@@ -133,8 +161,22 @@ export interface ClaudeCodeConfig {
     timeoutMs?: number;
     /** Extra environment for the session. Never secrets — see the README. */
     env?: Record<string, string>;
+    /**
+     * Who the session's own git commits are attributed to.
+     *
+     * A session has a shell and a checkout, so it commits — and it amends,
+     * rebases and cherry-picks, none of which a host can intercept the way it
+     * names an identity on a commit it makes itself. Left unset, every one of
+     * those falls through to whatever config the checkout happens to carry, which
+     * is a value frozen whenever that checkout was created.
+     *
+     * See {@link file://./run.ts buildLaunch} for why this becomes an environment
+     * rather than a `git config`.
+     */
+    author?: {
+        name: string;
+        email: string;
+    };
 }
-/** Eight minutes: comfortably inside `CHUNK_SOFT_MS`, long enough to be useful. */
-export declare const DEFAULT_WINDOW_MS: number;
 /** Fifteen minutes, well under the coder workspace's 20-minute idle timer. */
 export declare const DEFAULT_TIMEOUT_MS: number;

package/dist/claude-code/config.js

@@ -7,7 +7,5 @@
  * {@link ClaudeCodeConfig.permissionMode}.
  */
 export const DEFAULT_PERMISSION_MODE = "bypassPermissions";
-/** Eight minutes: comfortably inside `CHUNK_SOFT_MS`, long enough to be useful. */
-export const DEFAULT_WINDOW_MS = 8 * 60_000;
 /** Fifteen minutes, well under the coder workspace's 20-minute idle timer. */
 export const DEFAULT_TIMEOUT_MS = 15 * 60_000;

package/dist/claude-code/credentials.d.ts

@@ -5,15 +5,12 @@
  * ## Why a pool rather than a budget
  *
  * A Claude subscription has two limits that matter here: a rolling 5-hour
- * session bucket and a weekly one. Neither is readable, and 0.5.0 tried to stay
- * under them by *estimating* spend — a counter in dollars, a cap, and a gate
- * that refused to start work when the counter got high.
- *
- * That was the wrong instrument. The estimate is a guess about a bucket nobody
- * can see, and it only moved when a run *ended* (usage is learned from the
- * terminal `result` event), so it was never a cap on spend at all — only a gate
- * on starting. Meanwhile the bucket itself says so, precisely, the moment it is
- * empty: Anthropic answers `429`.
+ * session bucket and a weekly one. Neither is readable, so staying under them by
+ * *estimating* spend is the wrong instrument twice over — the estimate is a
+ * guess about a bucket nobody can see, and it only moves when a run *ends*,
+ * since usage is learned from the terminal `result` event. It is never a cap on
+ * spend, only a gate on starting. The bucket itself says so precisely the moment
+ * it is empty: Anthropic answers `429`.
  *
  * So this module does not predict. It **detects and routes around**: the
  * credential becomes an ordered pool, the gateway uses the first usable entry,
@@ -154,6 +151,21 @@ export type Refusal = {
     kind: "transient";
     retryAfterMs: number;
 };
+/**
+ * Read the client's own bucket reading as a verdict on the credential in use.
+ *
+ * `undefined` means "nothing to act on", which today is every reading — see
+ * {@link RATE_LIMIT_SPENT}. Otherwise the epoch-milliseconds the bucket refills,
+ * ready for {@link CredentialPool.spend}.
+ *
+ * Here rather than beside the parser because this is the same question
+ * {@link readRefusal} answers about a response: is this credential still worth
+ * using? The parser's job is to say what the line contained.
+ */
+export declare function readRateLimitEvent(info: {
+    status: string;
+    resetsAt?: number;
+}): number | undefined;
 /**
  * Read a response as a verdict on the credential that produced it.
  *

package/dist/claude-code/credentials.js

@@ -5,15 +5,12 @@
  * ## Why a pool rather than a budget
  *
  * A Claude subscription has two limits that matter here: a rolling 5-hour
- * session bucket and a weekly one. Neither is readable, and 0.5.0 tried to stay
- * under them by *estimating* spend — a counter in dollars, a cap, and a gate
- * that refused to start work when the counter got high.
- *
- * That was the wrong instrument. The estimate is a guess about a bucket nobody
- * can see, and it only moved when a run *ended* (usage is learned from the
- * terminal `result` event), so it was never a cap on spend at all — only a gate
- * on starting. Meanwhile the bucket itself says so, precisely, the moment it is
- * empty: Anthropic answers `429`.
+ * session bucket and a weekly one. Neither is readable, so staying under them by
+ * *estimating* spend is the wrong instrument twice over — the estimate is a
+ * guess about a bucket nobody can see, and it only moves when a run *ends*,
+ * since usage is learned from the terminal `result` event. It is never a cap on
+ * spend, only a gate on starting. The bucket itself says so precisely the moment
+ * it is empty: Anthropic answers `429`.
  *
  * So this module does not predict. It **detects and routes around**: the
  * credential becomes an ordered pool, the gateway uses the first usable entry,
@@ -243,6 +240,43 @@ function resetAtFrom(value) {
     const parsed = Date.parse(trimmed);
     return Number.isNaN(parsed) ? undefined : parsed;
 }
+/**
+ * The `rate_limit_event` statuses that mean the bucket is empty.
+ *
+ * **Empty, and that is the finding rather than a placeholder.** The client
+ * announces its bucket on every session and the only status ever observed is
+ * {@link file://./events.ts RATE_LIMIT_OK} — so there is no known value here to
+ * put in, and putting in a guess is the expensive half of the asymmetry
+ * {@link readRefusal} is built around: reading a healthy bucket as exhausted
+ * retires a working credential for hours, and with a pool of one that is an
+ * outage. The same reasoning that leaves a 403 unclassified leaves this set
+ * empty.
+ *
+ * What fills it is the log. `run.ts` reports every change of reading, and a
+ * status that is not `allowed` is also surfaced as a progress note, so the first
+ * real one arrives named — at which point it goes in here and the pool starts
+ * rotating *before* Anthropic refuses a request rather than because it did.
+ */
+const RATE_LIMIT_SPENT = new Set();
+/**
+ * Read the client's own bucket reading as a verdict on the credential in use.
+ *
+ * `undefined` means "nothing to act on", which today is every reading — see
+ * {@link RATE_LIMIT_SPENT}. Otherwise the epoch-milliseconds the bucket refills,
+ * ready for {@link CredentialPool.spend}.
+ *
+ * Here rather than beside the parser because this is the same question
+ * {@link readRefusal} answers about a response: is this credential still worth
+ * using? The parser's job is to say what the line contained.
+ */
+export function readRateLimitEvent(info) {
+    if (!RATE_LIMIT_SPENT.has(info.status))
+        return undefined;
+    // Seconds on the wire. A value passed through unconverted lands in 1970, and a
+    // credential marked spent until then reads as usable — the failure would be
+    // this function doing nothing, silently.
+    return info.resetsAt === undefined ? undefined : info.resetsAt * 1000;
+}
 /**
  * Read a response as a verdict on the credential that produced it.
  *

package/dist/claude-code/egress.d.ts

@@ -22,7 +22,8 @@ import { type CredentialStore } from "./credentials.js";
  *    with a placeholder; the swap happens here. A `postinstall` script in a
  *    cloned repository can read every environment variable the container has and
  *    still learn nothing — which is the repository's standing rule ("hand it the
- *    action, not the credential") applied to a process nobody can constrain.
+ *    action, not the credential") applied to a process nobody can constrain. A
+ *    GitHub token, when configured, is held the same way — see `./github.ts`.
  * 2. **Any restriction that is applied is total.** Not a policy the container
  *    cooperates with; the only route out. Restriction is **off by default** —
  *    see {@link EgressConfig.restrictToHosts} for why.
@@ -33,10 +34,9 @@ import { type CredentialStore } from "./credentials.js";
  *
  * ## What this deliberately does not do
  *
- * It does not meter. 0.5.0 had a budget gate that estimated spend in dollars and
- * refused to start work over a cap; 0.6.0 deleted it. An estimate is a guess
- * about a bucket nobody can read, it only moved once per run, and the bucket
- * itself announces the answer exactly — see the docblock in `credentials.ts`.
+ * It does not meter, and a budget gate must not come back: an estimate of spend
+ * is a guess about a bucket nobody can read, moves only once per run, and the
+ * bucket announces the answer exactly — see the docblock in `credentials.ts`.
  *
  * And it does not, by default, **bound exfiltration**. The container holds the
  * checkout, and with no restriction configured it can send it anywhere. That is
@@ -49,16 +49,11 @@ import { type CredentialStore } from "./credentials.js";
 export declare const ANTHROPIC_HOST = "api.anthropic.com";
 export interface EgressConfig {
     /**
-     * The credential pool, in priority order — index 0 is tried first.
+     * The credential pool — see {@link file://./config.ts ClaudeCodeConfig.credentials}.
      *
-     * A thunk so a rotated secret is picked up without rebuilding the plugin list.
-     * Called per request; it must be cheap. **None of these values enters the
-     * container**: the session is launched with `CREDENTIAL_PLACEHOLDER` and the
-     * swap happens here.
-     *
-     * An array of one is entirely valid and behaves as 0.5.0's single credential
-     * did — used until its bucket empties, after which requests are refused with
-     * the reset time.
+     * Called per request, so it must be cheap. This is the one place a real
+     * credential is read: the session is launched with `CREDENTIAL_PLACEHOLDER`
+     * and the swap happens here.
      */
     credentials: () => readonly string[];
     /**
@@ -109,6 +104,12 @@ export interface EgressConfig {
      * restriction, the first time a host serves user-controlled subdomains.
      */
     restrictToHosts?: readonly string[];
+    /**
+     * The GitHub token to swap for its placeholder, read per request. It reaches
+     * {@link GITHUB_HOSTS} and nowhere else. Unset, GitHub is reached
+     * anonymously like any other host. See `./github.ts`.
+     */
+    githubToken?: () => string | undefined;
     /** Named in log lines so one Worker's several gateways stay tellable apart. */
     label?: string;
     now?: () => number;

package/dist/claude-code/egress.js

@@ -1,4 +1,5 @@
 import { credentialPool, readRefusal } from "./credentials.js";
+import { GITHUB_HOSTS, githubAuthorization, githubError, presentsPlaceholder } from "./github.js";
 /**
  * `@dynamicagents/plugins/claude-code` — the container's only way out.
  *
@@ -22,7 +23,8 @@ import { credentialPool, readRefusal } from "./credentials.js";
  *    with a placeholder; the swap happens here. A `postinstall` script in a
  *    cloned repository can read every environment variable the container has and
  *    still learn nothing — which is the repository's standing rule ("hand it the
- *    action, not the credential") applied to a process nobody can constrain.
+ *    action, not the credential") applied to a process nobody can constrain. A
+ *    GitHub token, when configured, is held the same way — see `./github.ts`.
  * 2. **Any restriction that is applied is total.** Not a policy the container
  *    cooperates with; the only route out. Restriction is **off by default** —
  *    see {@link EgressConfig.restrictToHosts} for why.
@@ -33,10 +35,9 @@ import { credentialPool, readRefusal } from "./credentials.js";
  *
  * ## What this deliberately does not do
  *
- * It does not meter. 0.5.0 had a budget gate that estimated spend in dollars and
- * refused to start work over a cap; 0.6.0 deleted it. An estimate is a guess
- * about a bucket nobody can read, it only moved once per run, and the bucket
- * itself announces the answer exactly — see the docblock in `credentials.ts`.
+ * It does not meter, and a budget gate must not come back: an estimate of spend
+ * is a guess about a bucket nobody can read, moves only once per run, and the
+ * bucket announces the answer exactly — see the docblock in `credentials.ts`.
  *
  * And it does not, by default, **bound exfiltration**. The container holds the
  * checkout, and with no restriction configured it can send it anywhere. That is
@@ -58,9 +59,9 @@ export const ANTHROPIC_HOST = "api.anthropic.com";
  * Bouncing a request back into it is never a legitimate fetch, so it is refused
  * before any policy is consulted.
  *
- * A workspace that overrides `egressHost` on its `CloudflareContainerBackend`
- * should add that name here; the default is what the backend uses when nothing
- * says otherwise.
+ * A workspace that overrides `egressHost` on its `ContainerBackend` should add
+ * that name here; the default is what the backend uses when nothing says
+ * otherwise.
  */
 const NEVER_ALLOWED = new Set([
     "computer.internal",
@@ -207,6 +208,9 @@ export function claudeCodeEgress(config) {
             });
             return apiError("permission_error", `${host} is outside this workspace's egress host restriction`, 403);
         }
+        if (config.githubToken && GITHUB_HOSTS.has(host)) {
+            return await toGitHub(request, url, config.githubToken);
+        }
         const headers = new Headers(request.headers);
         if (host !== ANTHROPIC_HOST) {
             // The placeholder must not leave the boundary either. It is worthless to
@@ -241,8 +245,8 @@ export function claudeCodeEgress(config) {
          * The swap, and it is the whole point of the file.
          *
          * `authorization` is set and `x-api-key` removed because that is the shape
-         * the sanctioned client sends — the Phase 0 capture showed `authorization:
-         * Bearer …` with no `x-api-key` at all. Everything else is forwarded
+         * the sanctioned client sends: `authorization: Bearer …` with no
+         * `x-api-key` at all. Everything else is forwarded
          * untouched: the `anthropic-beta` list (which carries
          * `claude-code-20250219` and `oauth-2025-04-20`, almost certainly part of
          * what marks the request as coming from the client) and the `user-agent`
@@ -264,6 +268,39 @@ export function claudeCodeEgress(config) {
         }
         return await rotate(request, response, lead.id, lead.index);
     };
+    /**
+     * A request to GitHub: anonymous unless it presents the placeholder,
+     * which is swapped for the real token over https only.
+     *
+     * `redirect: "manual"`, so the token rides only the request it was swapped
+     * into: a redirect goes back to the client, whose next request crosses this
+     * gateway again and is judged on its own host.
+     */
+    const toGitHub = async (request, url, githubToken) => {
+        const headers = new Headers(request.headers);
+        const presented = presentsPlaceholder(headers.get("authorization"));
+        for (const name of CREDENTIAL_HEADERS)
+            headers.delete(name);
+        if (!presented) {
+            return await fetch(new Request(url, new Request(request, { headers })));
+        }
+        if (url.protocol !== "https:") {
+            console.warn(`[${tag}] refused a plaintext request to GitHub`, {
+                host: url.hostname,
+                method: request.method
+            });
+            return githubError(`${url.hostname} is reachable over https only; a credential is never ` +
+                "attached to a plaintext request", 403);
+        }
+        const token = githubToken();
+        if (!token) {
+            console.error(`[${tag}] a session asked for GitHub with no token set`);
+            return githubError("no GitHub token is configured for this deployment, so nothing can " +
+                "be done as its account", 401);
+        }
+        headers.set("authorization", githubAuthorization(presented, token));
+        return await fetch(new Request(url, new Request(request, { headers, redirect: "manual" })));
+    };
     /**
      * Read a refusal, move the lead if it earned one, and shape what the client
      * sees so its own retry lands on the new credential.
@@ -278,10 +315,10 @@ export function claudeCodeEgress(config) {
         /**
          * Capture the whole thing, every time.
          *
-         * **No genuine subscription-exhaustion `429` has ever been observed through
-         * this path** — the Phase 0 spike's 429s were the raw-API refusal, which is
-         * a different response — so the rules in `readRefusal` are inferences from
-         * the documented API rate limits. This log is the instrument that replaces
+         * **No genuine subscription-exhaustion `429` has been observed through this
+         * path** — a raw-API refusal is a different response — so the rules in
+         * `readRefusal` are inferences from the documented API rate limits. This log
+         * is the instrument that replaces
          * them with a fact, and it costs nothing: these statuses are rare, and the
          * body of one is a few hundred bytes.
          */