@dynamicagents/plugins 0.11.1 → 0.13.0

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.
@@ -32,14 +49,86 @@ 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;
-} | {
-    kind: "assistant";
+    cwd?: string;
+    permissionMode?: 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;
+}
+/** 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;
@@ -88,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.
  *
@@ -102,21 +230,37 @@ 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, clock?: ParseClock): 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 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[];