@dynamicagents/plugins 0.11.0 → 0.12.0

package/dist/arc-agi/store.js

@@ -16,11 +16,10 @@ import { z } from "zod";
  *
  * A plugin must never run drizzle's durable-sqlite **migrator**: it keeps one
  * flat integer journal and one global `__drizzle_migrations` table, which two
- * independently-versioned packages cannot share — the two predecessor agents,
- * both consuming the same `notify_tasks` module, had already forked that journal
- * at index 1. And `drizzle-kit generate` diffs against a snapshot in a single
- * output directory, so a plugin shipping from its own repo cannot produce a
- * correct diff at all.
+ * independently-versioned packages cannot share: two agents consuming the same
+ * module fork that journal at the first index they disagree on. And
+ * `drizzle-kit generate` diffs against a snapshot in a single output directory,
+ * so a plugin shipping from its own repo cannot produce a correct diff at all.
  *
  * None of that touches the **query builder**, which is a typed wrapper over the
  * same `DurableObjectStorage` holding no journal and no connection state. So the

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

@@ -30,7 +30,7 @@ import type { ToolFamilyContext, RecipeToolSet } from "@dynamicagents/core";
 /**
  * This family's key in a Recipe's `toolFamilies`. Exported because it is also
  * what tells the parent a Subtask needs a scorecard leased before it can run —
- * see `resolveRuntime` in the ReactiveAgent DO.
+ * see `resolveRuntime` in `./index.ts`.
  */
 export declare const ARC_GAME_FAMILY = "arc-game";
 export declare function buildArcGameTools(apiKey: string, ctx: ToolFamilyContext): RecipeToolSet;

package/dist/arc-agi/tools.js

@@ -35,19 +35,15 @@ import { ARC_SESSION_PATH } from "./types.js";
 /**
  * This family's key in a Recipe's `toolFamilies`. Exported because it is also
  * what tells the parent a Subtask needs a scorecard leased before it can run —
- * see `resolveRuntime` in the ReactiveAgent DO.
+ * see `resolveRuntime` in `./index.ts`.
  */
 export const ARC_GAME_FAMILY = "arc-game";
 export function buildArcGameTools(apiKey, ctx) {
     const { workspace, emitProgress, params } = ctx;
-    // Closed over from the plugin's config, never `ctx.env`. The predecessor
-    // passed the Worker `env` to every tool family, which a published package
-    // 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.
-    // 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 });
+    // Closed over from the plugin's config, never `ctx.env`: a published package
+    // cannot name `Env`, which is the ambient interface `wrangler types` generates
+    // into a *consumer's* app. Config-at-instantiation is also the only thing that
+    // works on Workers at all, where `env` has no module scope.
     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
@@ -183,7 +179,19 @@ export function buildArcGameTools(apiKey, ctx) {
                     .optional()
                     .describe("brief reasoning for this move or sequence")
             }),
-            execute: async ({ steps, note }) => {
+            execute: async ({ steps, note }, { abortSignal }) => {
+                // The call's own signal, not the execution's: it fires at this call's time
+                // limit as well as on a cancel, and past that limit core has stopped
+                // waiting — a batch still sending would spend moves on the card that the
+                // model is told never finished, and it may send them again. A caller
+                // with no loop hands `execute` no signal, and then a cancel is all there
+                // is to stop at.
+                const signal = abortSignal ?? ctx.signal;
+                const client = makeArcClient(apiKey, { signal });
+                const stoppedBy = () => signal?.reason?.name ===
+                    "TimeoutError"
+                    ? "this call reached its time limit"
+                    : "this call was cancelled";
                 // Acting immediately is right — the results below carry the board — but
                 // this chunk's orientation goes out first, so the model is never acting
                 // on a board it can no longer see.
@@ -251,16 +259,16 @@ 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
+                    // The signal 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) {
+                    if (signal?.aborted) {
                         session.pendingAction = null;
                         await save(session);
-                        trace.push(remaining(steps.length, index, "this call was cancelled"));
+                        trace.push(remaining(steps.length, index, stoppedBy()));
                         break;
                     }
                     const { frame, cookies } = await client.act({ action, gameId: session.gameId, guid: session.guid, x, y, note }, session.cookies);
@@ -391,10 +399,9 @@ export function buildArcGameTools(apiKey, ctx) {
             }
         })
     };
-    // No `abort` hook: the only external state this family used to hold was the
-    // scorecard, and nothing closes one any more — the API retires an idle card on
-    // its own. A play left unfinished is simply a run the card records as
-    // incomplete.
+    // No `abort` hook: this family holds no external state to release. The API
+    // retires an idle card itself, so a play left unfinished is simply a run the
+    // card records as incomplete.
     return { tools };
 }
 /**
@@ -402,8 +409,8 @@ export function buildArcGameTools(apiKey, ctx) {
  * supply.
  *
  * With `runtime.frame` — this chunk is the one that opened the play — the state
- * is complete and indistinguishable from what a local RESET used to produce.
- * Without it the play already existed, so everything a frame carries is unknown:
+ * is complete. Without it the play already existed, so everything a frame
+ * carries is unknown:
  * empty `availableActions` and a null board, both filled in by the first ACTION.
  * Only `guid` matters for correctness, and it always comes from the parent.
  */

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

@@ -188,13 +188,12 @@ export declare const ARC_SESSION_PATH = "arc/session.json";
  * This plugin's slice of a Subtask's runtime bag — what the parent resolves for
  * an execution and no model could supply.
  *
- * Core's `SubtaskRuntime` is an open `Record<string, unknown>`, and these four
- * fields are the reason. The predecessor declared them in core's own delegation
- * types, which meant core imported a domain's vocabulary and every unrelated
- * agent carried `cardId`, `cookies`, `guid` and `frame` in its bundle. The
- * plugin that writes this slice is the plugin that reads it, so narrow it with
- * `runtimeAs<ArcRuntime>` at the boundary and keep the cast's blast radius to
- * this one module.
+ * Core's `SubtaskRuntime` is an open `Record<string, unknown>`, and this slice is
+ * why: declared in core's own delegation types instead, core would import a
+ * domain's vocabulary and every unrelated agent would carry it in its bundle.
+ * The plugin that writes this slice is the plugin that reads it, so narrow it
+ * with `runtimeAs<ArcRuntime>` at the boundary and keep the cast's blast radius
+ * to this one module.
  */
 export type ArcRuntime = {
     /** The scorecard leased for this chunk. */

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

@@ -25,6 +25,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.
@@ -61,14 +76,28 @@ export interface ClaudeCodeConfig {
     /** 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.
      *
-     * 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.
+     * 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.
+     */
+    effort?: EffortLevel;
+    /**
+     * Caps on Claude Code's own subagent tree.
+     *
+     * 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
+     * container runtime enforces it.
      */
-    maxTurns?: number;
-    /** Caps on Claude Code's own subagent tree. Advisory, like `maxTurns`. */
     maxSubagentDepth?: number;
     maxConcurrentSubagents?: number;
     /**
@@ -116,10 +145,33 @@ export interface ClaudeCodeConfig {
     /**
      * How long one chunk blocks before checkpointing and yielding.
      *
-     * 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.
+     * **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.
      */
     windowMs?: number;
     /**
@@ -133,8 +185,33 @@ 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. */
+/**
+ * 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,7 +7,16 @@
  * {@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;
+/**
+ * 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/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

@@ -33,10 +33,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 +48,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[];
     /**

package/dist/claude-code/egress.js

@@ -33,10 +33,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
@@ -241,8 +240,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`
@@ -278,10 +277,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.
          */

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

@@ -32,10 +32,46 @@ export interface ClaudeCodeUsage {
     cacheRead: number;
     cacheWrite: number;
 }
+/**
+ * What the client knows about the subscription bucket it is drawing on.
+ *
+ * The one thing on this stream that is about the *deployment* rather than the
+ * run. This plugin's entry point describes the 5-hour and weekly limits as
+ * routed around rather than predicted, because the gateway only learns a bucket
+ * is empty when Anthropic refuses a request — this is the client saying so in
+ * advance, on every session.
+ *
+ * `resetsAt` is **seconds**, not milliseconds, which is the one field here it is
+ * possible to get silently wrong: a value handed to `Date` unconverted lands in
+ * January 1970, and a credential marked spent until then reads as usable.
+ */
+export interface RateLimitInfo {
+    /**
+     * {@link RATE_LIMIT_OK} on a healthy bucket. Any other value is
+     * **unclassified** — no consumer should read one as exhaustion.
+     */
+    status: string;
+    /** Unix **seconds** at which this bucket refills. */
+    resetsAt?: number;
+    /** Which bucket — `five_hour`, and the weekly one. */
+    rateLimitType?: string;
+    /** Whether spend beyond the bucket is permitted, and why not. */
+    overageStatus?: string;
+    overageDisabledReason?: string;
+}
 export type ClaudeCodeEvent = {
     kind: "init";
     sessionId: string;
     model?: string;
+}
+/**
+ * The subscription bucket, as the client sees it. Carried rather than acted
+ * on here — {@link describe} decides what a reader is told, and the caller
+ * decides what the credential pool is told.
+ */
+ | {
+    kind: "rateLimit";
+    info: RateLimitInfo;
 } | {
     kind: "assistant";
     text: string;
@@ -104,6 +140,17 @@ export interface ParsedStream {
  * `result` and `init` are never nested and are read unconditionally.
  */
 export declare function parseStream(buffer: string): ParsedStream;
+/**
+ * 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 declare const RATE_LIMIT_OK = "allowed";
 /**
  * Turn events into progress notes the parent can post.
  *