@dynamicagents/plugins 0.11.1 → 0.13.0

package/dist/claude-code/events.js

@@ -1,3 +1,18 @@
+import { initCard, resultCard, thinkingCard, toolCallCard, toolResultCard } from "./cards.js";
+/**
+ * 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 const LIVE_SLACK_MS = 5_000;
 const EMPTY_USAGE = {
     input: 0,
     output: 0,
@@ -27,29 +42,86 @@ function readUsage(raw) {
     };
 }
 /**
- * Flatten an `assistant` message into a line of prose and the tools it called.
+ * An `assistant` message as events, one per block, in the order it said them.
  *
- * `thinking` blocks are dropped. They are the model's private reasoning, they
- * are the largest thing in the stream by a wide margin, and the parent agent is
- * being shown progress rather than asked to review the subagent's deliberation.
+ * Per block rather than flattened, because the blocks are different things to
+ * a reader: prose, the model's reasoning, and each tool it called. A message
+ * that only calls tools is as much progress as one that narrates.
  */
-function readAssistant(message) {
+function readAssistant(message, thought) {
+    const messageId = str(message.id);
     const content = Array.isArray(message.content)
         ? message.content
         : [];
-    const text = [];
-    const tools = [];
+    const events = [];
     for (const block of content) {
         if (!asRecord(block))
             continue;
-        const blockText = str(block.text);
-        if (block.type === "text" && blockText)
-            text.push(blockText.trim());
-        const toolName = str(block.name);
-        if (block.type === "tool_use" && toolName)
-            tools.push(toolName);
+        if (block.type === "text") {
+            // Trimmed only to ask whether it is empty: indentation is a code block's
+            // and trailing spaces a hard break's, so the event keeps it verbatim.
+            const text = str(block.text);
+            if (text?.trim())
+                events.push({ kind: "text", text });
+        }
+        else if (block.type === "thinking") {
+            events.push({
+                kind: "thinking",
+                ...(messageId ? { messageId } : {}),
+                ...(thought === undefined ? {} : { durationMs: thought })
+            });
+        }
+        else if (block.type === "tool_use") {
+            const id = str(block.id);
+            const name = str(block.name);
+            if (id && name)
+                events.push({ kind: "toolUse", id, name, input: block.input });
+        }
+    }
+    return events;
+}
+/**
+ * A `user` line's tool results. Anything else a user line carries — the
+ * prompt echoed back, a hook's note — is not a tool's answer and says nothing.
+ */
+function readToolResults(event, message) {
+    const content = Array.isArray(message.content) ? message.content : [];
+    const results = content.filter((block) => asRecord(block)?.type === "tool_result");
+    const structured = results.length === 1 ? event.tool_use_result : undefined;
+    const events = [];
+    for (const block of results) {
+        const id = str(block.tool_use_id);
+        if (!id)
+            continue;
+        events.push({
+            kind: "toolResult",
+            id,
+            isError: block.is_error === true,
+            content: resultText(block.content),
+            ...(structured === undefined || structured === null ? {} : { structured })
+        });
     }
-    return { text: text.join(" ").replace(/\s+/g, " ").trim(), tools };
+    return events;
+}
+/**
+ * A `tool_result` block's content as text. It is a string, or a list of
+ * blocks of which only the text ones are readable here — an image a tool
+ * returned is named, not carried.
+ */
+function resultText(content) {
+    if (typeof content === "string")
+        return content;
+    if (!Array.isArray(content))
+        return "";
+    return content
+        .map((block) => {
+        const record = asRecord(block);
+        if (record?.type === "text")
+            return str(record.text) ?? "";
+        return record?.type ? `[${String(record.type)}]` : "";
+    })
+        .filter(Boolean)
+        .join("\n");
 }
 /**
  * Read a `system`/`permission_denied` line into something worth reporting.
@@ -87,8 +159,13 @@ function readDenial(event) {
  * 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 function parseStream(buffer) {
+export function parseStream(buffer, clock) {
+    let thinkingFrom = clock?.thinkingFrom;
     const events = [];
     let skipped = 0;
     let nested = 0;
@@ -131,6 +208,7 @@ export function parseStream(buffer) {
             nested++;
             continue;
         }
+        const at = readTime(event.timestamp);
         switch (event.type) {
             case "system": {
                 if (event.subtype === "init") {
@@ -140,10 +218,14 @@ export function parseStream(buffer) {
                         break;
                     }
                     const model = str(event.model);
+                    const cwd = str(event.cwd);
+                    const permissionMode = str(event.permissionMode);
                     events.push({
                         kind: "init",
                         sessionId,
-                        ...(model ? { model } : {})
+                        ...(model ? { model } : {}),
+                        ...(cwd ? { cwd } : {}),
+                        ...(permissionMode ? { permissionMode } : {})
                     });
                     break;
                 }
@@ -151,6 +233,11 @@ export function parseStream(buffer) {
                     events.push(readDenial(event));
                     break;
                 }
+                if (event.subtype === "thinking_tokens") {
+                    if (clock)
+                        thinkingFrom ??= clock.now;
+                    break;
+                }
                 if (event.subtype === "api_retry") {
                     events.push({
                         kind: "retry",
@@ -176,29 +263,120 @@ export function parseStream(buffer) {
                     skip(trimmed);
                     break;
                 }
-                const { text, tools } = readAssistant(message);
-                if (!text && tools.length === 0)
-                    break;
-                events.push({ kind: "assistant", text, tools });
+                // Ended by its own line's arrival, and trusted only on a live read.
+                const thought = clock !== undefined &&
+                    thinkingFrom !== undefined &&
+                    at !== undefined &&
+                    Math.abs(clock.now - at) <= LIVE_SLACK_MS
+                    ? clock.now - thinkingFrom
+                    : undefined;
+                events.push(...readAssistant(message, thought));
                 break;
             }
             // `user` messages on this stream are tool *results* being fed back to the
-            // model, not anything a human said. They are large, they are already
-            // summarised by the assistant turn that follows, and the un-nested ones
-            // belong to the outer run's own tools — so they are deliberately not
-            // surfaced as progress.
-            case "user":
+            // model, not anything a human said — each one completes the card its call
+            // opened.
+            case "user": {
+                const message = asRecord(event.message);
+                if (message)
+                    events.push(...readToolResults(event, message));
                 break;
+            }
             case "result": {
                 events.push({ kind: "result", result: readResult(event) });
                 break;
             }
+            /**
+             * A top-level `type`, not a `system` subtype, so it is handled here and
+             * not in the subtype switch above.
+             *
+             * The placement is load-bearing rather than tidy: everything this switch
+             * does not name falls to `default`, which counts it as an unrecognised
+             * line and warns. A recognised shape parsed in the wrong place is
+             * therefore indistinguishable from a schema that moved — the drain reports
+             * a steady `skipped` on every session, and the reading it is dropping is
+             * the only free view of the subscription bucket anything here gets.
+             */
+            case "rate_limit_event": {
+                const info = readRateLimit(event);
+                if (!info) {
+                    skip(trimmed);
+                    break;
+                }
+                events.push({ kind: "rateLimit", info });
+                break;
+            }
             default:
                 skip(trimmed);
         }
+        if (at !== undefined)
+            thinkingFrom = undefined;
     }
-    return { events, carry, skipped, nested, ...(sample ? { sample } : {}) };
+    return {
+        events,
+        carry,
+        skipped,
+        nested,
+        ...(sample ? { sample } : {}),
+        ...(thinkingFrom === undefined ? {} : { thinkingFrom })
+    };
+}
+/**
+ * Read a `rate_limit_event` line, or nothing when it carries no status.
+ *
+ * `status` is the only required field: it is what decides whether anything is
+ * wrong, and a line without it says nothing this package can use — so it is
+ * skipped and sampled like any other unrecognised shape, rather than recorded as
+ * a bucket in an unknown state.
+ */
+function readRateLimit(event) {
+    const info = asRecord(event.rate_limit_info);
+    const status = info && str(info.status);
+    if (!info || !status)
+        return undefined;
+    const resetsAt = info.resetsAt;
+    return {
+        status,
+        // Finite is not enough. `1e308` is finite, and seconds past the `Date` range
+        // make `toISOString()` throw — inside `describe`, inside the drain's parse
+        // loop, which would take a whole session down over one malformed vendor
+        // field. The contract everywhere else here is to drop a bad line, not to
+        // raise, so the check is "does this name a moment" rather than "is this a
+        // number".
+        ...(typeof resetsAt === "number" && isRealDate(resetsAt * 1000)
+            ? { resetsAt }
+            : {}),
+        ...(str(info.rateLimitType)
+            ? { rateLimitType: str(info.rateLimitType) }
+            : {}),
+        ...(str(info.overageStatus)
+            ? { overageStatus: str(info.overageStatus) }
+            : {}),
+        ...(str(info.overageDisabledReason)
+            ? { overageDisabledReason: str(info.overageDisabledReason) }
+            : {})
+    };
+}
+/** A line's `timestamp`, in epoch milliseconds, or `undefined`. */
+function readTime(value) {
+    const ms = typeof value === "string" ? Date.parse(value) : NaN;
+    return Number.isFinite(ms) ? ms : undefined;
 }
+/** Whether a millisecond value is one `Date` can actually represent. */
+function isRealDate(ms) {
+    return Number.isFinite(ms) && !Number.isNaN(new Date(ms).getTime());
+}
+/**
+ * The status a healthy bucket reports, and the only one ever observed.
+ *
+ * **Every other value is unclassified, not a refusal.** Nothing here knows what
+ * a non-`allowed` status means, and the one place that decides whether a
+ * credential is spent — `readRateLimitEvent` in this package's `credentials.ts`
+ * — recognises none of them, deliberately: retiring a working credential on a
+ * guess is the expensive half of that trade. What an unrecognised status earns
+ * is a note and a log, so somebody can name it.
+ */
+export const RATE_LIMIT_OK = "allowed";
 /** Read a `result` line. Total by construction — a missing field reads as zero. */
 function readResult(event) {
     const apiErrorStatus = event.api_error_status;
@@ -208,6 +386,7 @@ function readResult(event) {
         : 0;
     const sessionId = str(event.session_id);
     const spawned = stats ? num(stats.spawned) : undefined;
+    const errors = readErrors(event.errors);
     return {
         subtype: str(event.subtype) ?? "unknown",
         isError: event.is_error === true,
@@ -219,29 +398,57 @@ function readResult(event) {
         costUsd: num(event.total_cost_usd),
         usage: readUsage(event.usage),
         ...(spawned === undefined ? {} : { subagentsSpawned: spawned }),
-        permissionDenials: denials
+        permissionDenials: denials,
+        ...(errors.length > 0 ? { errors } : {}),
+        ...(event.structured_output === undefined ||
+            event.structured_output === null
+            ? {}
+            : { structured: event.structured_output })
     };
 }
-/** How much of one progress note the parent is shown. */
-const PROGRESS_MAX_CHARS = 240;
+/**
+ * A result line's `errors`, as sentences.
+ *
+ * **Anything that is not a string is stringified rather than dropped**, which is
+ * the whole of the care this needs: the field is a vendor's, an entry carrying a
+ * code and a message is a perfectly likely shape for it, and on the run this
+ * exists to explain — a resume with nowhere to resume from — it is the only
+ * account of what happened. Dropping an unexpected entry would report that run
+ * as having failed for no stated reason.
+ */
+function readErrors(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    return raw
+        .map((entry) => (typeof entry === "string" ? entry : safeJson(entry)))
+        .filter((entry) => entry.length > 0);
+}
+/** `value` as JSON, or as whatever `String` makes of it when it has no JSON. */
+function safeJson(value) {
+    try {
+        return JSON.stringify(value) ?? String(value);
+    }
+    catch {
+        return String(value);
+    }
+}
 /**
  * How much of an unrecognised line is kept for the logs.
  *
- * Shorter than a progress note and for a different reason: a note is read by a
- * model deciding what to do next, whereas this is read by a person deciding
- * whether a schema moved. The discriminating part of a stream-json line is its
- * `type` and `subtype`, both of which are at the front.
+ * Read by a person deciding whether a schema moved, and the discriminating part
+ * of a stream-json line is its `type` and `subtype`, both at the front.
  */
 const SAMPLE_MAX_CHARS = 200;
 /**
- * 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
@@ -252,29 +459,30 @@ export function toProgress(events, from) {
     const out = [];
     let n = from;
     for (const event of events) {
-        const text = describe(event);
-        if (!text)
+        const note = describe(event);
+        if (!note)
             continue;
-        out.push({ key: `claude:${n}`, text });
+        out.push({ key: `claude:${n}`, ...note });
         n++;
     }
     return out;
 }
-/** One line of progress, or nothing when the event is not worth a note. */
+/** One note, or nothing when the event is not worth one. */
 function describe(event) {
     switch (event.kind) {
-        // Tool calls are not narration. A turn that only called tools said nothing
-        // the reader can act on, and it cost one Slack message per Bash/Read/Edit —
-        // nine of them for a one-line README edit. The tool names added nothing to
-        // the turns that *did* have text either, so the prefix goes with them.
-        //
-        // Same policy the in-process agents already apply in the gatekeeper
-        // (src/agents/shared/loop.ts: "Tool-only steps stay silent in Slack").
-        // Deliberately narrower than silencing the whole channel: `denied` and
-        // `retry` below stay, because they are the only evidence of a session that
-        // is being refused or throttled.
-        case "assistant":
-            return event.text ? clip(event.text) : undefined;
+        // Never clipped. A plan or a report cut mid-sentence reads as complete.
+        case "text":
+            return { text: event.text };
+        // Tool activity is a card, and a card never reaches the thread — core's
+        // `transcribeNote` keeps it on the transcript — so a session's every Bash,
+        // Read and Edit is shown without one message each in front of the person.
+        // `./cards.ts` holds how each tool reads.
+        case "toolUse":
+            return toolCallCard(event.id, event.name, event.input);
+        case "toolResult":
+            return toolResultCard(event);
+        case "thinking":
+            return thinkingCard(event.durationMs, event.messageId);
         case "denied":
             // The one progress note that is more useful than the session's own
             // account of itself. A refused tool call is invisible in the transcript —
@@ -282,19 +490,42 @@ function describe(event) {
             // parent sees a subagent being resourceful and never learns it was fenced
             // in. Named tool first, because that is what distinguishes a broken
             // configuration from a deny rule doing its job.
-            return `permission denied${event.tool ? ` for ${event.tool}` : ""}: ${clip(event.reason)}`;
+            return {
+                text: `permission denied${event.tool ? ` for ${event.tool}` : ""}: ${event.reason}`
+            };
         case "retry":
             // Surfaced deliberately. This is what a budget refusal from the egress
             // gateway looks like from inside the container, and a run that ends
             // shortly afterwards is explained by it.
-            return `retrying the model call: ${clip(event.detail)}`;
-        // `init` names a session id nobody outside this package can use, and
-        // `result` is the terminal outcome the caller reports itself.
+            return { text: `retrying the model call: ${event.detail}` };
+        case "rateLimit":
+            /**
+             * Silent while the bucket is fine, which is every line of a healthy
+             * session — one note per `rate_limit_event` would be the noisiest thing on
+             * the stream and would say "allowed" each time.
+             *
+             * The test is inverted deliberately: an unrecognised status produces a
+             * note rather than silence. The statuses are a vendor's and only
+             * {@link RATE_LIMIT_OK} has been seen, so a new one meaning "nearly out"
+             * should surface as prose somebody reads, not be assumed benign.
+             */
+            return event.info.status === RATE_LIMIT_OK
+                ? undefined
+                : {
+                    text: `the ${event.info.rateLimitType ?? "subscription"} limit reports "${event.info.status}"` +
+                        (event.info.resetsAt === undefined
+                            ? ""
+                            : ` until ${new Date(event.info.resetsAt * 1000).toISOString()}`)
+                };
+        // `init`'s session id is a handle as well as news: it reaches the host on
+        // the drain's cursor — see `DrainCursor.sessionId` in ./run.ts — where
+        // something can record it and resume with it.
         case "init":
+            return initCard(event);
         case "result":
-            return undefined;
+            return resultCard(event.result);
     }
 }
-function clip(text, max = PROGRESS_MAX_CHARS) {
+function clip(text, max) {
     return text.length <= max ? text : `${text.slice(0, max - 1)}…`;
 }

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

@@ -0,0 +1,39 @@
+/**
+ * GitHub access for a session, with the token on the Worker side.
+ *
+ * The session is launched with {@link GITHUB_TOKEN_PLACEHOLDER} as `GH_TOKEN`,
+ * and git is given a credential helper that answers with it. The egress gateway swaps
+ * the placeholder for the real token on {@link GITHUB_HOSTS} only, so a process
+ * in the container can *use* GitHub as the deployment's account and can never
+ * *read* the token — the same containment as the Anthropic credential.
+ *
+ * Keyed on the placeholder, unlike the Anthropic swap: a GitHub request that
+ * did not ask for a credential stays anonymous, as it would be anywhere else.
+ */
+/** The hosts the token is ever sent to: git over HTTPS, and the API. */
+export declare const GITHUB_HOSTS: ReadonlySet<string>;
+/**
+ * What `GH_TOKEN` and git's credential helper hold. Shaped like a classic
+ * token, so nothing that checks the shape refuses it before sending it.
+ */
+export declare const GITHUB_TOKEN_PLACEHOLDER: string;
+/**
+ * The session's GitHub environment. A credential helper for `https://github.com`
+ * rather than a token in the remote URL, so the checkout's `.git/config` holds
+ * nothing and every git the session starts presents the placeholder.
+ */
+export declare function githubEnv(): Record<string, string>;
+/** The keys {@link githubEnv} owns, which a host's `env` may not set beside it. */
+export declare const GITHUB_ENV_KEYS: readonly string[];
+/** How an authorization header carried the placeholder, if it did. */
+type Presented = "bearer" | "basic";
+/**
+ * Whether `value` presents the placeholder: `Bearer`/`token` as `gh` sends it,
+ * or Basic `user:placeholder` as git does after a `401`.
+ */
+export declare function presentsPlaceholder(value: string | null): Presented | undefined;
+/** The real credential, in the scheme the placeholder came in. */
+export declare function githubAuthorization(presented: Presented, token: string): string;
+/** A refusal in GitHub's error shape, which `gh` and git both print. */
+export declare function githubError(message: string, status: number): Response;
+export {};

package/dist/claude-code/github.js

@@ -0,0 +1,82 @@
+/**
+ * GitHub access for a session, with the token on the Worker side.
+ *
+ * The session is launched with {@link GITHUB_TOKEN_PLACEHOLDER} as `GH_TOKEN`,
+ * and git is given a credential helper that answers with it. The egress gateway swaps
+ * the placeholder for the real token on {@link GITHUB_HOSTS} only, so a process
+ * in the container can *use* GitHub as the deployment's account and can never
+ * *read* the token — the same containment as the Anthropic credential.
+ *
+ * Keyed on the placeholder, unlike the Anthropic swap: a GitHub request that
+ * did not ask for a credential stays anonymous, as it would be anywhere else.
+ */
+/** The hosts the token is ever sent to: git over HTTPS, and the API. */
+export const GITHUB_HOSTS = new Set([
+    "github.com",
+    "api.github.com"
+]);
+/**
+ * What `GH_TOKEN` and git's credential helper hold. Shaped like a classic
+ * token, so nothing that checks the shape refuses it before sending it.
+ */
+export const GITHUB_TOKEN_PLACEHOLDER = "ghp_" + "0".repeat(36);
+/** The username GitHub expects beside a token in git's Basic auth. */
+const GIT_USER = "x-access-token";
+/**
+ * The session's GitHub environment. A credential helper for `https://github.com`
+ * rather than a token in the remote URL, so the checkout's `.git/config` holds
+ * nothing and every git the session starts presents the placeholder.
+ */
+export function githubEnv() {
+    return {
+        GH_TOKEN: GITHUB_TOKEN_PLACEHOLDER,
+        GIT_CONFIG_COUNT: "1",
+        GIT_CONFIG_KEY_0: "credential.https://github.com.helper",
+        // Answers `get` only; `store` and `erase` are no-ops that still exit 0.
+        GIT_CONFIG_VALUE_0: `!f() { if test "$1" = get; then printf 'username=${GIT_USER}\\npassword=%s\\n' "$GH_TOKEN"; fi; }; f`
+    };
+}
+/** The keys {@link githubEnv} owns, which a host's `env` may not set beside it. */
+export const GITHUB_ENV_KEYS = Object.keys(githubEnv());
+/**
+ * Whether `value` presents the placeholder: `Bearer`/`token` as `gh` sends it,
+ * or Basic `user:placeholder` as git does after a `401`.
+ */
+export function presentsPlaceholder(value) {
+    if (!value)
+        return undefined;
+    const [scheme = "", credential = ""] = value.trim().split(/\s+/, 2);
+    switch (scheme.toLowerCase()) {
+        case "bearer":
+        case "token":
+            return credential === GITHUB_TOKEN_PLACEHOLDER ? "bearer" : undefined;
+        case "basic": {
+            let decoded;
+            try {
+                decoded = atob(credential);
+            }
+            catch {
+                return undefined;
+            }
+            const password = decoded.slice(decoded.indexOf(":") + 1);
+            return decoded.includes(":") && password === GITHUB_TOKEN_PLACEHOLDER
+                ? "basic"
+                : undefined;
+        }
+        default:
+            return undefined;
+    }
+}
+/** The real credential, in the scheme the placeholder came in. */
+export function githubAuthorization(presented, token) {
+    return presented === "basic"
+        ? `Basic ${btoa(`${GIT_USER}:${token}`)}`
+        : `Bearer ${token}`;
+}
+/** A refusal in GitHub's error shape, which `gh` and git both print. */
+export function githubError(message, status) {
+    return new Response(JSON.stringify({ message }), {
+        status,
+        headers: { "content-type": "application/json" }
+    });
+}