@dynamicagents/plugins 0.12.0 → 0.14.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.
  *
@@ -61,18 +69,6 @@ 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;
     /**
@@ -84,9 +80,9 @@ export interface ClaudeCodeConfig {
      * 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 host round loop's own reasoning effort, which
-     * belongs to a different model on the Worker side. This one reaches only the
-     * CLI in the container.
+     * 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;
     /**
@@ -94,8 +90,8 @@ export interface ClaudeCodeConfig {
      *
      * 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 Dynamic Agents' scheduler, so it multiplies whatever
-     * these say; {@link timeoutMs} is the ceiling that actually holds, because the
+     * 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.
      */
     maxSubagentDepth?: number;
@@ -127,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;
     /**
@@ -137,43 +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.
-     *
-     * **A read deadline on the session's stdout stream, not a halt.** Nothing is
-     * stopped and nothing is destroyed when it expires: the host detaches, the
-     * session process inside the container never notices, and the next chunk
-     * re-attaches to the live session from the cursor. So the window is bounded
-     * against `STEP_TIMEOUT_MS` rather than against core's `CHUNK_SOFT_MS` —
-     * there is no in-flight turn to overrun, which is what sizes the recipe
-     * path's budget.
-     *
-     * What prices the headroom instead is the post-exit filesystem pull, which is
-     * deliberately unbounded because it carries whatever the session wrote,
-     * dependency trees included, and can outlast the window. So no value here can
-     * guarantee the chunk fits inside the step timeout: what is left over is
-     * sized for an *expected* pull, plus the sub-second unwind of yielding and
-     * the step's own bookkeeping, and a large enough pull overruns it whatever
-     * this is set to. See {@link file://./run.ts DrainOptions.windowMs}.
-     *
-     * **Overrunning is the cheaper failure, which is why the default is
-     * generous.** The step is killed and retried; the filesystem sync resumes
-     * from the blocks it has already committed rather than starting over, and the
-     * retry re-attaches to the session from the cursor — so an overrun costs a
-     * retry and some replayed notes, never a session's edits. An undersized
-     * window costs a chunk boundary on *every* session instead — a checkpoint, a
-     * fresh step, a re-hydrated subagent and a re-attach that replays the tail —
-     * paid whether or not the pull was ever going to be large.
-     *
-     * It must also be long enough that a session does not exhaust its branch's
-     * chunk allowance while it is still thinking.
+     * 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.
+     *
+     * 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.
      *
@@ -202,16 +178,5 @@ export interface ClaudeCodeConfig {
         email: string;
     };
 }
-/**
- * Twenty minutes against a 30-minute step timeout, which leaves ~10 minutes for
- * the sub-second unwind of yielding the window and for the post-exit filesystem
- * pull. An expected pull fits there; a pull that carries an install's
- * dependency tree may not, and nothing here promises it will — that pull is
- * unbounded by design. Sized for the expected case deliberately: the pull that
- * overruns is retried and resumes, while a shorter window would buy that back
- * by paying for extra chunk boundaries on every session. See
- * {@link ClaudeCodeConfig.windowMs}.
- */
-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,16 +7,5 @@
  * {@link ClaudeCodeConfig.permissionMode}.
  */
 export const DEFAULT_PERMISSION_MODE = "bypassPermissions";
-/**
- * Twenty minutes against a 30-minute step timeout, which leaves ~10 minutes for
- * the sub-second unwind of yielding the window and for the post-exit filesystem
- * pull. An expected pull fits there; a pull that carries an install's
- * dependency tree may not, and nothing here promises it will — that pull is
- * unbounded by design. Sized for the expected case deliberately: the pull that
- * overruns is retried and resumes, while a shorter window would buy that back
- * by paying for extra chunk boundaries on every session. See
- * {@link ClaudeCodeConfig.windowMs}.
- */
-export const DEFAULT_WINDOW_MS = 20 * 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/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.
@@ -103,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.
@@ -57,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",
@@ -206,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
@@ -263,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.

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

@@ -1,4 +1,4 @@
-import type { ProgressEvent } from "@dynamicagents/core/subtasks";
+import type { NoteData } from "@dynamicagents/core/subagent";
 /** What a `result` line carries, of the fields anything here reads. */
 export interface ClaudeCodeResult {
     /** `success`, or one of the `error_*` subtypes. */
@@ -16,6 +16,23 @@ export interface ClaudeCodeResult {
     /** How many inner subagents the run spawned — advisory, for the logs. */
     subagentsSpawned?: number;
     permissionDenials: number;
+    /**
+     * The answer of a session launched with a JSON Schema: the input of its
+     * `StructuredOutput` call, which `text` then holds as a JSON string. Absent
+     * for any other session, and for one that never made the call.
+     */
+    structured?: unknown;
+    /**
+     * What the CLI says went wrong, when it reports an error rather than an
+     * answer.
+     *
+     * The only account there is of a refused resume: a `--resume` naming a
+     * conversation the config directory does not hold ends in a `result` line with
+     * no `text` at all, and `No conversation found with session ID: …` here. A
+     * caller that reports such a run as a failed session rather than as "not
+     * resumable" is reporting the one thing it was handed to say.
+     */
+    errors?: string[];
 }
 /**
  * Token counts, flattened.
@@ -63,6 +80,8 @@ export type ClaudeCodeEvent = {
     kind: "init";
     sessionId: string;
     model?: string;
+    cwd?: string;
+    permissionMode?: string;
 }
 /**
  * The subscription bucket, as the client sees it. Carried rather than acted
@@ -72,10 +91,44 @@ export type ClaudeCodeEvent = {
  | {
     kind: "rateLimit";
     info: RateLimitInfo;
-} | {
-    kind: "assistant";
+}
+/** One `text` block of an assistant message, verbatim — it is markdown. */
+ | {
+    kind: "text";
     text: string;
-    tools: string[];
+}
+/**
+ * One `thinking` block, as how long it took — never what it said. A block can
+ * run to thousands of tokens of private reasoning; a reader is told that the
+ * model thought, and for how long, the way the CLI itself says it.
+ *
+ * `durationMs` is measured, never inferred: see
+ * {@link ParsedStream.thinkingFrom} for where it starts, and it is absent
+ * whenever that cannot be trusted. `messageId` is the API message the block
+ * belongs to — a message can carry more than one.
+ */
+ | {
+    kind: "thinking";
+    messageId?: string;
+    durationMs?: number;
+} | {
+    kind: "toolUse";
+    id: string;
+    name: string;
+    input: unknown;
+}
+/**
+ * One `tool_result` block of a `user` line: a tool's answer going back to
+ * the model. `structured` is the line's `tool_use_result` — the tool's own
+ * record of what it did, richer than the text the model reads — and is read
+ * only when the line carries a single result, since it is not per block.
+ */
+ | {
+    kind: "toolResult";
+    id: string;
+    isError: boolean;
+    content: string;
+    structured?: unknown;
 } | {
     kind: "retry";
     detail: string;
@@ -124,7 +177,46 @@ export interface ParsedStream {
     sample?: string;
     /** Lines dropped for carrying `parent_tool_use_id`. See {@link parseStream}. */
     nested: number;
+    /**
+     * When the pending thinking block began streaming, on the caller's clock:
+     * the `now` of the read that brought its first `system/thinking_tokens`
+     * line.
+     *
+     * That line is the one sign on the stream that thinking is under way. The
+     * CLI prints it as the block's text arrives, so it comes after everything
+     * that is not thinking: request setup, the wait for a first token, an API
+     * retry's back-off, a compaction. The line before a block — the tool result
+     * it answers — comes before all of those, and timing from it is how a minute
+     * of retries reads as a minute of thought. The token line carries no time of
+     * its own, which is why the caller's clock stamps it.
+     *
+     * Cleared by every line that carries a `timestamp`, so a start belongs to
+     * the block that follows the last message and never to work before it. Handed
+     * back with `carry`, for the same reason, and kept on the caller's cursor.
+     */
+    thinkingFrom?: number;
+}
+/** What {@link parseStream} times a thinking block against. */
+export interface ParseClock {
+    /** When this read arrived, in epoch milliseconds. */
+    now: number;
+    /** {@link ParsedStream.thinkingFrom} from the previous read. */
+    thinkingFrom?: number;
 }
+/**
+ * How far a thinking line's arrival may be from its own `timestamp` for the
+ * block to be timed.
+ *
+ * Both ends of a block are timed by when they arrive, which is only the truth
+ * while the drain reads live. A drain that re-attached after a cut is handed
+ * what was printed meanwhile in one burst, and its arrival times are the
+ * replay's — so a block whose line arrived far from when the CLI stamped it
+ * reads "Thought", with no time. Locally a line arrives 5–31 ms after its
+ * stamp; a re-attach has been measured at about a second. A container clock
+ * this far from the Worker's degrades every block to no time, rather than to a
+ * wrong one.
+ */
+export declare const LIVE_SLACK_MS = 5000;
 /**
  * Parse whatever has arrived so far into complete events plus a carry.
  *
@@ -138,8 +230,12 @@ export interface ParsedStream {
  * the filter.
  *
  * `result` and `init` are never nested and are read unconditionally.
+ *
+ * `clock` is when this read arrived, and the pending thinking block's start
+ * from the previous read — see {@link ParsedStream.thinkingFrom}. Without it no
+ * block is timed.
  */
-export declare function parseStream(buffer: string): ParsedStream;
+export declare function parseStream(buffer: string, clock?: ParseClock): ParsedStream;
 /**
  * The status a healthy bucket reports, and the only one ever observed.
  *
@@ -152,18 +248,19 @@ export declare function parseStream(buffer: string): ParsedStream;
  */
 export declare const RATE_LIMIT_OK = "allowed";
 /**
- * Turn events into progress notes the parent can post.
+ * Turn events into progress notes for the parent's transcript.
  *
  * **`from` is the number of notes already emitted for this run, and the key is
  * derived from it.** Not from the note's content, not from a clock, and not from
  * the Claude Code `uuid` — from position alone.
  *
- * The reason is replay. A chunk that dies mid-drain is retried by the Workflow,
- * the re-attach replays the tail, and the same assistant turn is parsed twice. A
+ * The reason is replay. A drain that dies mid-stream is resumed from the last
+ * stored sequence, whatever arrived after it is read again, and the same
+ * assistant turn is parsed twice. A
  * content-derived key would make two identical notes collide *by luck* (and two
  * genuinely repeated notes — "Running tests" twice — collide wrongly). A
  * clock-derived key would never collide, so every replay would re-post
  * everything. Position is the only choice that dedupes exactly the events that
  * are the same event.
  */
-export declare function toProgress(events: readonly ClaudeCodeEvent[], from: number): ProgressEvent[];
+export declare function toProgress(events: readonly ClaudeCodeEvent[], from: number): NoteData[];