@excitedjs/agent-runtime-claude-code 0.6.1 → 0.7.0-alpha.g1e011989dff1

package/README.md

@@ -7,68 +7,116 @@ The built-in **Claude Code** Agent Runtime provider for
 It implements the public `AgentRuntimeProvider` contract from
 [`@excitedjs/dreamux-types`](../../dreamux-types) against a resident `claude`
 stream-json child: process supervision, the stream-json wire protocol (line
-framing, turn aggregation, control-request replies), per-turn idle-deadline
-handling, MCP config translation (`--mcp-config`), teammate completion delivery
+framing, result aggregation, control-request replies), pending-request idle
+deadlines, MCP config translation (`--mcp-config`), teammate completion delivery
 as a plain user turn, bounded native transcript pagination, and Claude Code
 doctor diagnostics.
 
 ## Boundary
 
-This package depends on `@excitedjs/dreamux-types` **only**. It never imports
+This package uses `@excitedjs/dreamux-types` and shared `@excitedjs/dreamux-utils`.
+It never imports
 `@excitedjs/dreamux` core. Everything host-specific — per-dispatcher paths, the
 durable state sink, the process `PATH` seeded from the host package bins — is
 supplied by the Dreamux host through the neutral `AgentRuntimeCreateContext` and
 the provider factory options. The package owns only Claude Code engine mechanics
 and its own runtime config parsing; it reconstructs no Dreamux host
-layout/path/log contracts. Generic OS/validation/turn helpers it needs are
-vendored under `src/internal/`.
+layout/path/log contracts. Shared process supervision and state-write fencing
+come from `@excitedjs/dreamux-utils`.
 
 ## Loading
 
-Dreamux core resolves `builtin:claude-code` to this package and constructs the
-provider through its own core-owned adapter, which maps core's host-shaped create
-context onto the neutral one and supplies the host contracts. The package also
-default-exports a generic provider-loader factory, so
+Dreamux core resolves `builtin:claude-code` through the generic provider loader
+and supplies host contracts through the neutral create context. The package
+default-exports that provider factory, so
 `loadExternalAgentRuntimeProviders({ refs: ['builtin:claude-code'] })` can load it
 through the same package-loader path as external `npm:` providers.
 
-## Turn lifecycle
+## Resident session and request settlement
 
 The public runtime boundary returns one `RuntimeSubmission` handle per accepted
-send, settled by an immutable provider-owned `RuntimeCompletion` created at each
-real native result boundary. Inputs merged before session creation and supported
-live steering settle with the same completion object; queued sends settle with
-distinct completions in native order. Command UUIDs are private wire aliases;
-when `msg_lifecycle_v1` is available, all aliases must reach a terminal command
-state and a final result must be captured before the object settles. Live steer
-fails loudly without that capability. Runtime stop fences queued session work,
-terminates the supervised process group with absence proof, and resolves every
-unsettled public object as stopped.
-
-Source deduplication is provider-private. A source is reserved while its native
-admission is in flight, committed only after acceptance or an ambiguous
-post-write failure, and released after a proven pre-write failure. Concurrent
-uses of the same reserved source share the same admission outcome. Accordingly,
-`failed` means the command was proven not written, while `ambiguous` means a
-native write may have been accepted and must not be retried automatically.
-Runtime stop synchronously fences new input, releases pending capability/write
-waiters, and drains all already-started admission calls before it resolves.
+send. Every input follows the same native write path; admission resolves after
+write acknowledgement or positive native evidence. RPC holds one table of
+unanswered requests and settles them directly from native results or command
+cancellation/refusal. There is no enclosing request window or aggregate drainage.
+
+A native result answering requests creates one immutable `RuntimeCompletion`
+shared by those requests. Folded inputs share that object; queued inputs wait
+for their own result. Consumption lifecycle and a matching submitted result UUID
+are positive attribution evidence. A completed lifecycle frame may precede or
+follow its result and does not decide when another input can be submitted.
+
+Background native turns may run without a submission. Their activity and result
+boundaries remain observable, but they settle no unrelated request and do not
+terminate the resident process. Explicit inputs steered into a background turn
+settle normally once they join it. Concurrent input requires lifecycle evidence;
+sessions without it retain single-input compatibility. Native `cancelled` can
+describe a hard failure; it does not imply a user stop. Consumed commands retain
+their result membership through terminal lifecycle frames. An unconsumed command
+that is cancelled, refused or discarded settles as failed. Every native error
+result remains observable, including UUID-less errors and the `success` arm with
+`is_error: true` carrying API error text.
+
+A setup error can precede `started` and omit the input UUID. It reports a failed
+native end with its error details but cannot identify a queued request. A later
+named `cancelled` fails that request with its protocol state; the adapter does not
+guess that a preceding unbound error belongs to it.
+
+Core owns source deduplication, captured recipients and completion-token delivery.
+The provider owns native admission: `failed` means the command was proven not
+written, while `ambiguous` means a native write may have been accepted and must
+not be retried automatically. Runtime stop synchronously fences new input,
+releases pending capability/write waiters, terminates the supervised process
+group with absence proof, resolves unsettled submissions as stopped, and drains
+already-started admission calls before it resolves.
 
 ## Native sessions and transcripts
 
-For a fresh runtime this package generates the native UUID before launch,
-passes it through Claude Code's `--session-id`, and deterministically derives
-the native transcript under
-`<CLAUDE_CONFIG_DIR-or-~/.claude>/projects/<project>/<session-id>.jsonl`.
-The validated canonical path is persisted with the checkpoint before admission
-can be reported. Resume keeps the authoritative native session id and can
-rediscover a moved transcript across Claude Code project directories. No
-SessionStart Hook, callback process, placeholder file, or auxiliary IPC bridge
-is used to discover `transcript_path`.
-
-`readTranscript` is a cold bounded read that never starts a Claude process. It
-applies native rewrite lineage, returns completed provider-neutral
-message/tool blocks in chronological order, and owns opaque cursors, query and
-rewrite mismatch detection, payload redaction/truncation, and the fixed host
-output budget. Native command/session IDs and filesystem paths never appear in
-transcript pages.
+For a fresh runtime this package generates the native UUID before launch and
+passes it through Claude Code's `--session-id`. The native identity is durably
+published before input is written. Resume uses that same authoritative session
+id. Recent activity reads locate Claude's native history independently of the
+live process; transcript discovery never controls request settlement.
+
+`readRecentActivity` is a cold bounded read that never starts a Claude process.
+It returns neutral assistant/tool activity records and provider-owned opaque
+cursors. It is not a completion source.
+
+## Custom session factories
+
+A custom `ClaudeCodeSessionFactory` now implements `submit()` returning
+`RuntimeAdmission`; accepted submissions carry their own settlement promises.
+The old `submitTurn()`/`steerTurn()` window interface is removed. Session specs
+provide the pinned `sessionId` and optional `outputSchemaEnabled` result contract;
+the exit handler receives its failure cause.
+
+Session implementations own result validation and settlement. Their
+`onProtocolEvent` callback reports native activity independently: result events
+retain `commandUuids` for observation, and the public `command_lifecycle` variant
+reports native command state without deciding settlement in runtime or Core.
+An `interrupted` event can report an independently known interruption boundary.
+Emitting a callback alone no longer settles a
+request. These are breaking changes to the Claude-specific extension seam;
+the neutral `AgentRuntime` and `RuntimeSubmission` contracts are unchanged.
+
+## Direct stream RPC consumers
+
+The exported `ClaudeCodeStreamRpc` has the same single `submit()` path, returning
+`Promise<RuntimeAdmission>` in place of `submitTurn()` and `steerTurn()`. Accepted
+handles own eventual settlement; callers no longer await an aggregate window.
+Replace `failPending(error)` with `fail(error)` for transport failure or `stop()`
+for deliberate teardown. A session retired after an unexpected exit retains
+that failure for subsequent admission, even after cleanup calls `stop()`.
+
+`ClaudeCodeStreamRpcOptions` now requires `sessionId` (a pinned native ID or
+`null`) and accepts optional `outputSchemaEnabled` for result validation.
+`reapOnTimeout(error)` receives the failure `Error`. Protocol callbacks are
+observation only, as described above. Parsed `ResultEnvelope` and `TurnOutcome`
+also expose `terminalReason`, a string or `null`, for native terminal diagnostics.
+These changes break direct RPC consumers as well as custom session factories.
+
+The default adapter uses consumption events because the observed background
+folds omit both result UUID echo fields. Claude Code 2.1.263 marks
+`command_lifecycle` as internal; it is not a documented stable SDK contract.
+Compatibility tests and real native captures are distinguished in the task's
+verification record.

package/dist/config.d.ts

@@ -28,8 +28,8 @@
  * is reset on every inbound stream line, so it bounds the max time the
  * still-alive child may emit *no* stream activity — not the total turn duration.
  * A child silent for the whole window is failed and reaped/re-spawned (rather
- * than wedging the serial turn queue and, behind it, TeamMate completion
- * delivery), while a long but actively-streaming turn never trips it.
+ * than blocking request settlement and TeamMate completion delivery), while a
+ * long but actively-streaming turn never trips it.
  */
 export interface DispatcherClaudeCodeConfig {
     bin: string;

package/dist/control-rpc.d.ts

@@ -0,0 +1,32 @@
+import type { Writable } from 'node:stream';
+export declare class ClaudeCodeControlRpc {
+    private readonly stdin;
+    private readonly options;
+    private remoteControlRequestId;
+    private pendingInterrupt;
+    constructor(stdin: Writable, options: {
+        log?: (level: 'info' | 'warn' | 'error', msg: string, err?: unknown) => void;
+        onRemoteControlUrl?: (url: string) => void;
+    });
+    /**
+     * Ask claude to interrupt whatever it is doing, and answer when it replies.
+     *
+     * Which turn this belongs to is the caller's fact, not this class's: this
+     * only correlates one control request with its `control_response`. A second
+     * ask while one is outstanding joins it rather than sending a second request.
+     */
+    requestInterrupt(reason: string): Promise<boolean>;
+    /**
+     * Answer an outstanding interrupt from the turn's own ending instead.
+     *
+     * The turn can reach its terminal before claude answers the control request;
+     * the caller, which owns the turn, decides that has happened and says how it
+     * ended. A no-op when nothing is outstanding, because the ordinary path is
+     * the `control_response` below.
+     */
+    settleInterrupt(failure?: Error, interrupted?: boolean): void;
+    enableRemoteControl(): void;
+    onControlRequest(requestId: string | null, subtype: string | null, request: Record<string, unknown>): void;
+    onControlResponse(requestId: string | null, ok: boolean, response: Record<string, unknown> | null, error: string | null): void;
+}
+//# sourceMappingURL=control-rpc.d.ts.map

package/dist/control-rpc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"control-rpc.d.ts","sourceRoot":"","sources":["../src/control-rpc.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAgB5C,qBAAa,oBAAoB;IAK7B,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAL1B,OAAO,CAAC,sBAAsB,CAAuB;IACrD,OAAO,CAAC,gBAAgB,CAAiC;gBAGtC,KAAK,EAAE,QAAQ,EACf,OAAO,EAAE;QACxB,GAAG,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;QAC7E,kBAAkB,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;KAC5C;IAGH;;;;;;OAMG;IACH,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAoBlD;;;;;;;OAOG;IACH,eAAe,CAAC,OAAO,CAAC,EAAE,KAAK,EAAE,WAAW,UAAQ,GAAG,IAAI;IAQ3D,mBAAmB,IAAI,IAAI;IAM3B,gBAAgB,CACd,SAAS,EAAE,MAAM,GAAG,IAAI,EACxB,OAAO,EAAE,MAAM,GAAG,IAAI,EACtB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,IAAI;IAoBP,iBAAiB,CACf,SAAS,EAAE,MAAM,GAAG,IAAI,EACxB,EAAE,EAAE,OAAO,EACX,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,EACxC,KAAK,EAAE,MAAM,GAAG,IAAI,GACnB,IAAI;CA4BR"}

package/dist/control-rpc.js

@@ -0,0 +1,112 @@
+/** Claude Code stream-json control requests and their one pending reply. */
+import { randomUUID } from 'node:crypto';
+import { buildCanUseToolAllow, buildControlAck, buildInterruptRequest, buildRemoteControlEnable, } from './stream.js';
+export class ClaudeCodeControlRpc {
+    stdin;
+    options;
+    remoteControlRequestId = null;
+    pendingInterrupt = null;
+    constructor(stdin, options) {
+        this.stdin = stdin;
+        this.options = options;
+    }
+    /**
+     * Ask claude to interrupt whatever it is doing, and answer when it replies.
+     *
+     * Which turn this belongs to is the caller's fact, not this class's: this
+     * only correlates one control request with its `control_response`. A second
+     * ask while one is outstanding joins it rather than sending a second request.
+     */
+    requestInterrupt(reason) {
+        if (this.pendingInterrupt !== null)
+            return this.pendingInterrupt.promise;
+        const requestId = randomUUID();
+        let resolve;
+        let reject;
+        const promise = new Promise((resolvePromise, rejectPromise) => {
+            resolve = resolvePromise;
+            reject = rejectPromise;
+        });
+        const pending = { requestId, promise, resolve, reject };
+        this.pendingInterrupt = pending;
+        this.stdin.write(`${buildInterruptRequest(requestId, reason)}\n`, (error) => {
+            if (error != null && this.pendingInterrupt === pending) {
+                this.pendingInterrupt = null;
+                reject(error);
+            }
+        });
+        return promise;
+    }
+    /**
+     * Answer an outstanding interrupt from the turn's own ending instead.
+     *
+     * The turn can reach its terminal before claude answers the control request;
+     * the caller, which owns the turn, decides that has happened and says how it
+     * ended. A no-op when nothing is outstanding, because the ordinary path is
+     * the `control_response` below.
+     */
+    settleInterrupt(failure, interrupted = false) {
+        const pending = this.pendingInterrupt;
+        if (pending === null)
+            return;
+        this.pendingInterrupt = null;
+        if (failure !== undefined)
+            pending.reject(failure);
+        else
+            pending.resolve(interrupted);
+    }
+    enableRemoteControl() {
+        if (!this.stdin.writable)
+            return;
+        this.remoteControlRequestId = randomUUID();
+        this.stdin.write(`${buildRemoteControlEnable(this.remoteControlRequestId)}\n`);
+    }
+    onControlRequest(requestId, subtype, request) {
+        if (requestId === null || !this.stdin.writable)
+            return;
+        // Unattended posture: answer permission callbacks so a turn never wedges
+        // waiting on a human.
+        let reply;
+        if (subtype === 'can_use_tool') {
+            const rawInput = request['input'];
+            const input = typeof rawInput === 'object' &&
+                rawInput !== null &&
+                !Array.isArray(rawInput)
+                ? rawInput
+                : {};
+            reply = buildCanUseToolAllow(requestId, input);
+        }
+        else {
+            reply = buildControlAck(requestId);
+        }
+        this.stdin.write(`${reply}\n`);
+    }
+    onControlResponse(requestId, ok, response, error) {
+        if (requestId === null)
+            return;
+        const interrupt = this.pendingInterrupt;
+        if (interrupt !== null && requestId === interrupt.requestId) {
+            this.pendingInterrupt = null;
+            if (ok)
+                interrupt.resolve(true);
+            else
+                interrupt.reject(new Error(error ?? 'claude interrupt request failed'));
+            return;
+        }
+        if (requestId !== this.remoteControlRequestId)
+            return;
+        this.remoteControlRequestId = null;
+        if (ok && response !== null) {
+            const url = response['session_url'] ?? response['connect_url'];
+            if (typeof url === 'string') {
+                this.options.onRemoteControlUrl?.(url);
+            }
+            else {
+                this.options.log?.('warn', 'claude remote control enable succeeded without a URL');
+            }
+            return;
+        }
+        this.options.log?.('warn', `claude remote control enable failed${error !== null ? `: ${error}` : ''}`);
+    }
+}
+//# sourceMappingURL=control-rpc.js.map

package/dist/control-rpc.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"control-rpc.js","sourceRoot":"","sources":["../src/control-rpc.ts"],"names":[],"mappings":"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"}

package/dist/rpc.d.ts

@@ -1,45 +1,13 @@
-/**
- * Claude Code stream-json turn RPC.
- *
- * The supervisor owns the child process. This class owns one in-flight command
- * group, stdout line demux, command drainage, and defensive control replies.
- *
- * One resident CLI execution window can span several submitted commands: a
- * live steer is written while the CLI is already running. How the CLI answers them is
- * not fixed, which is what makes settlement subtle (probed against a live
- * 2.1.231 resident session):
- *
- *  - **Commands fold.** A message that arrives while the in-flight turn is
- *    inside a tool call is absorbed into that turn at the next query-loop
- *    boundary. Several commands then share ONE `result` (3 → 1 observed), and
- *    a folded command's uuid never appears on any `result`.
- *  - **Or they do not.** A command that arrives between turns runs on its own
- *    and gets its own `result`.
- *  - **`result.user_message_uuid` is not a completion ledger.** It is present
- *    only sometimes, is not reliably the first-submitted uuid of a fold, and
- *    is absent entirely on the `error_during_execution` artifact an
- *    interrupt produces.
- *  - **`command_lifecycle` is the attribution signal.** Started commands identify
- *    the submissions represented by the next native `result`; terminal states
- *    drain the resident execution window. Its ordering against `result` is not
- *    stable.
- *
- * Every valid `result` is forwarded immediately as its own native completion
- * boundary. Lifecycle terminality only decides when the command group has
- * drained and the resident session may accept a new initial command; it never
- * aggregates several results into one completion.
- */
+/** Resident Claude input admission, request settlement and native stream handling. */
 import type { Writable } from 'node:stream';
 import type { TurnSubmitOptions } from './types.js';
-/** Provider-private admission classification; never crosses the neutral API. */
-export declare class ClaudeSteerAdmissionError extends Error {
-    readonly admission: 'failed' | 'ambiguous';
-    constructor(admission: 'failed' | 'ambiguous', message: string, options?: ErrorOptions);
-}
+import type { RuntimeAdmission } from '@excitedjs/dreamux-types';
 export interface ClaudeCodeStreamRpcOptions {
+    sessionId: string | null;
+    outputSchemaEnabled?: boolean;
     turnTimeoutMs: number;
     log?: (level: 'info' | 'warn' | 'error', msg: string, err?: unknown) => void;
-    reapOnTimeout: () => void;
+    reapOnTimeout: (error: Error) => void;
     onRemoteControlUrl?: (url: string) => void;
     onProtocolEvent?: import('./types.js').ClaudeCodeSessionSpec['onProtocolEvent'];
 }
@@ -47,71 +15,47 @@ export declare class ClaudeCodeStreamRpc {
     private readonly stdin;
     private readonly options;
     private readonly lineBuf;
-    private pending;
+    private readonly aggregator;
+    private readonly requests;
+    private readonly consumed;
     private lifecycleSupported;
-    private remoteControlRequestId;
-    constructor(stdin: Writable, options: ClaudeCodeStreamRpcOptions);
-    submitTurn(prompt: string, options?: TurnSubmitOptions, commandUuid?: string): Promise<void>;
-    steerTurn(prompt: string, options?: TurnSubmitOptions, commandUuid?: string): Promise<void>;
-    private writeSteer;
-    onStdoutChunk(chunk: string): void;
-    failPending(err: Error): void;
-    enableRemoteControl(): void;
+    private timer;
+    private closed;
+    private readonly control;
     /**
-     * Detach the in-flight turn: clear its deadline timer and null `pending`,
-     * returning it so the caller can resolve or reject it exactly once.
-     */
-    private settlePending;
-    /**
-     * Mark a submitted command as producing nothing further, then re-check
-     * settlement. `abnormalReason` is `null` for the normal ending (`completed`)
-     * and a short phrase for a command that never ran — those are logged,
-     * because the CLI gives no other trace of a command it declined.
+     * An interrupt this session asked for has not been answered yet.
      *
-     * A command ending abnormally never fails the turn by itself: the probe
-     * shows a `cancelled` command coexisting with another that answers normally
-     * (that is exactly what an interrupt looks like), so
-     * rejecting on `cancelled` — as the pre-#342 code did — is wrong.
+     * It is the session's fact, not a request's: claude interrupts whatever it is
+     * doing, and the artifact it leaves behind names the command it was in the
+     * middle of. This only decides who is still waiting for an answer — what
+     * ended the work is read from the result itself.
      */
-    private markCommandTerminal;
+    private interruptRequested;
+    constructor(stdin: Writable, options: ClaudeCodeStreamRpcOptions);
+    submit(prompt: string, options?: TurnSubmitOptions, commandUuid?: string): Promise<RuntimeAdmission>;
+    private acceptRequest;
+    private failWrite;
+    onStdoutChunk(chunk: string): void;
+    /** Actual transport loss fails each outstanding request, without a completion. */
+    fail(error: Error): void;
+    /** Explicit teardown stops requests and converges unconfirmed admissions. */
+    stop(): void;
+    private close;
     /**
-     * The drainage gate: every submitted command has reached a terminal
-     * lifecycle state AND at least one valid `result` has been seen. Result
-     * identity and settlement have already been forwarded one-by-one.
-     *
-     * Two escapes, both anti-hang:
-     *
-     *  - no lifecycle signal at all (`msg_lifecycle_v1` absent, so no
-     *    `command_lifecycle` will ever arrive) — the `result` is then the only
-     *    terminal event there is, so settle on it;
-     *  - every command terminal, none of them ever ran, and no result — nothing
-     *    can answer this turn, so fail it loudly. The idle deadline is not an
-     *    acceptable backstop here: it reaps the resident child, and any inbound
-     *    line re-arms it, so a healthy session could be killed long after the
-     *    turn became unanswerable.
+     * Ask claude to interrupt whatever it is doing.
      *
-     * When a command *did* run but no result has arrived yet, this waits: the
-     * probe shows terminal lifecycle states arriving both before and after the
-     * result they belong to, so "terminal, therefore no result is coming" is not
-     * a sound inference.
-     */
-    private settleIfReady;
-    /**
-     * (Re)arm the per-turn idle deadline. `turnTimeoutMs` is a *max-idle* window,
-     * not a total-turn cap: any inbound stream line for this turn pushes it out
-     * (see `onLine`). A genuinely wedged child (no stream activity for the whole
-     * window) is still reaped — preserving the #120 anti-hang intent — but a long
-     * but continuously-streaming turn never trips the deadline (#156).
+     * Whatever it is doing, not only what this host asked for: a resident session
+     * runs turns of its own, and a `/stop` that skipped those would leave the
+     * conversation watching work it cannot stop. Answers false only when there is
+     * no session left to ask.
      */
+    interrupt(reason: string): Promise<boolean>;
+    enableRemoteControl(): void;
+    private clearIdleIfEmpty;
+    /** Outstanding work has a max-idle deadline; pure background work has none. */
     private armIdleTimer;
     private onLine;
     private decideLifecycleSupport;
-    private flushCapabilityWaiters;
-    private rejectCapabilityWaiters;
-    private resolveWriteWaiter;
-    private rejectWriteWaiter;
-    private rejectWriteWaiters;
-    private onControlRequest;
-    private onControlResponse;
+    private rejectWaitingRequests;
 }
 //# sourceMappingURL=rpc.d.ts.map

package/dist/rpc.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rpc.d.ts","sourceRoot":"","sources":["../src/rpc.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAY5C,OAAO,KAAK,EAAc,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAmDhE,gFAAgF;AAChF,qBAAa,yBAA0B,SAAQ,KAAK;IAEhD,QAAQ,CAAC,SAAS,EAAE,QAAQ,GAAG,WAAW;gBAAjC,SAAS,EAAE,QAAQ,GAAG,WAAW,EAC1C,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,YAAY;CAKzB;AAED,MAAM,WAAW,0BAA0B;IACzC,aAAa,EAAE,MAAM,CAAC;IACtB,GAAG,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;IAC7E,aAAa,EAAE,MAAM,IAAI,CAAC;IAC1B,kBAAkB,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAC3C,eAAe,CAAC,EAAE,OAAO,YAAY,EAAE,qBAAqB,CAAC,iBAAiB,CAAC,CAAC;CACjF;AAED,qBAAa,mBAAmB;IAO5B,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAP1B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAoB;IAC5C,OAAO,CAAC,OAAO,CAA4B;IAC3C,OAAO,CAAC,kBAAkB,CAAwB;IAClD,OAAO,CAAC,sBAAsB,CAAuB;gBAGlC,KAAK,EAAE,QAAQ,EACf,OAAO,EAAE,0BAA0B;IAGhD,UAAU,CACd,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,iBAAsB,EAC/B,WAAW,GAAE,MAAqB,GACjC,OAAO,CAAC,IAAI,CAAC;IA8CV,SAAS,CACb,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,iBAAsB,EAC/B,WAAW,GAAE,MAAqB,GACjC,OAAO,CAAC,IAAI,CAAC;IAuBhB,OAAO,CAAC,UAAU;IA6ClB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAIlC,WAAW,CAAC,GAAG,EAAE,KAAK,GAAG,IAAI;IAI7B,mBAAmB,IAAI,IAAI;IAM3B;;;OAGG;IACH,OAAO,CAAC,aAAa;IAiBrB;;;;;;;;;;OAUG;IACH,OAAO,CAAC,mBAAmB;IAsB3B;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,OAAO,CAAC,aAAa;IAwBrB;;;;;;OAMG;IACH,OAAO,CAAC,YAAY;IAkBpB,OAAO,CAAC,MAAM;IAqHd,OAAO,CAAC,sBAAsB;IAY9B,OAAO,CAAC,sBAAsB;IAe9B,OAAO,CAAC,uBAAuB;IAQ/B,OAAO,CAAC,kBAAkB;IAO1B,OAAO,CAAC,iBAAiB;IAWzB,OAAO,CAAC,kBAAkB;IAU1B,OAAO,CAAC,gBAAgB;IAwBxB,OAAO,CAAC,iBAAiB;CAyB1B"}
+{"version":3,"file":"rpc.d.ts","sourceRoot":"","sources":["../src/rpc.ts"],"names":[],"mappings":"AAAA,sFAAsF;AACtF,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAW5C,OAAO,KAAK,EAAc,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAChE,OAAO,KAAK,EACV,gBAAgB,EAGjB,MAAM,0BAA0B,CAAC;AAWlC,MAAM,WAAW,0BAA0B;IACzC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,aAAa,EAAE,MAAM,CAAC;IACtB,GAAG,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;IAC7E,aAAa,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IACtC,kBAAkB,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAC3C,eAAe,CAAC,EAAE,OAAO,YAAY,EAAE,qBAAqB,CAAC,iBAAiB,CAAC,CAAC;CACjF;AAkBD,qBAAa,mBAAmB;IAoB5B,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,OAAO;IApB1B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAoB;IAC5C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAwB;IACnD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAqC;IAC9D,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAqB;IAC9C,OAAO,CAAC,kBAAkB,CAAwB;IAClD,OAAO,CAAC,KAAK,CAA+B;IAC5C,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAuB;IAC/C;;;;;;;OAOG;IACH,OAAO,CAAC,kBAAkB,CAAS;gBAGhB,KAAK,EAAE,QAAQ,EACf,OAAO,EAAE,0BAA0B;IAKtD,MAAM,CACJ,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,iBAAsB,EAC/B,WAAW,GAAE,MAAqB,GACjC,OAAO,CAAC,gBAAgB,CAAC;IAwC5B,OAAO,CAAC,aAAa;IAKrB,OAAO,CAAC,SAAS;IAUjB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAQlC,kFAAkF;IAClF,IAAI,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI;IAIxB,6EAA6E;IAC7E,IAAI,IAAI,IAAI;IAIZ,OAAO,CAAC,KAAK;IA2Bb;;;;;;;OAOG;IACG,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAWjD,mBAAmB,IAAI,IAAI;IAK3B,OAAO,CAAC,gBAAgB;IAOxB,+EAA+E;IAC/E,OAAO,CAAC,YAAY;IAapB,OAAO,CAAC,MAAM;IAwGd,OAAO,CAAC,sBAAsB;IAW9B,OAAO,CAAC,qBAAqB;CAY9B"}