@rkat/sdk 0.3.4 → 0.4.1

package/dist/index.d.ts

@@ -1,11 +1,33 @@
 /**
- * Meerkat TypeScript SDK — communicate with the Meerkat agent runtime via JSON-RPC.
+ * Meerkat TypeScript SDK — communicate with the Meerkat agent runtime.
+ *
+ * @example
+ * ```ts
+ * import { MeerkatClient } from "@rkat/sdk";
+ *
+ * const client = new MeerkatClient();
+ * await client.connect();
+ *
+ * const session = await client.createSession("Hello!");
+ * console.log(session.text);
+ *
+ * for await (const event of session.stream("Tell me a joke")) {
+ *   if (event.type === "text_delta") {
+ *     process.stdout.write(event.delta);
+ *   }
+ * }
+ *
+ * await client.close();
+ * ```
  */
 export { MeerkatClient } from "./client.js";
-export { CapabilityChecker } from "./capabilities.js";
-export { EventStream } from "./streaming.js";
-export { SkillHelper } from "./skills.js";
+export type { ConnectOptions } from "./client.js";
+export { Session } from "./session.js";
+export { CommsEventStream, EventStream } from "./streaming.js";
+export type { Capability, RunResult, SchemaWarning, SessionInfo, SessionOptions, SkillQuarantineDiagnostic, SkillRuntimeDiagnostics, SkillKey, SkillRef, SourceHealthSnapshot, Usage, } from "./types.js";
 export { MeerkatError, CapabilityUnavailableError, SessionNotFoundError, SkillNotFoundError, } from "./generated/errors.js";
-export type { WireUsage, WireRunResult, WireEvent, CapabilitiesResponse, CapabilityEntry, } from "./generated/types.js";
 export { CONTRACT_VERSION } from "./generated/types.js";
+export type { McpAddParams, McpRemoveParams, McpReloadParams, McpLiveOpResponse, } from "./generated/types.js";
+export type { AgentEvent, CoreAgentEvent, StreamEvent, ScopedAgentEvent, StreamScopeFrame, RunStartedEvent, RunCompletedEvent, RunFailedEvent, TurnStartedEvent, TextDeltaEvent, TextCompleteEvent, ToolCallRequestedEvent, ToolResultReceivedEvent, TurnCompletedEvent, ToolExecutionStartedEvent, ToolExecutionCompletedEvent, ToolExecutionTimedOutEvent, CompactionStartedEvent, CompactionCompletedEvent, CompactionFailedEvent, BudgetWarningEvent, RetryingEvent, HookStartedEvent, HookCompletedEvent, HookFailedEvent, HookDeniedEvent, HookRewriteAppliedEvent, HookPatchPublishedEvent, SkillsResolvedEvent, SkillResolutionFailedEvent, InteractionCompleteEvent, InteractionFailedEvent, StreamTruncatedEvent, ToolConfigChangedEvent, ToolConfigChangedPayload, ToolConfigChangeOperation, UnknownEvent, StopReason, BudgetType, HookPoint, } from "./events.js";
+export { parseEvent, parseCoreEvent, isTextDelta, isTextComplete, isTurnCompleted, isToolCallRequested, isRunCompleted, isRunFailed, } from "./events.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC7C,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EACL,YAAY,EACZ,0BAA0B,EAC1B,oBAAoB,EACpB,kBAAkB,GACnB,MAAM,uBAAuB,CAAC;AAC/B,YAAY,EACV,SAAS,EACT,aAAa,EACb,SAAS,EACT,oBAAoB,EACpB,eAAe,GAChB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAGH,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,YAAY,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAG/D,YAAY,EACV,UAAU,EACV,SAAS,EACT,aAAa,EACb,WAAW,EACX,cAAc,EACd,yBAAyB,EACzB,uBAAuB,EACvB,QAAQ,EACR,QAAQ,EACR,oBAAoB,EACpB,KAAK,GACN,MAAM,YAAY,CAAC;AAGpB,OAAO,EACL,YAAY,EACZ,0BAA0B,EAC1B,oBAAoB,EACpB,kBAAkB,GACnB,MAAM,uBAAuB,CAAC;AAG/B,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AACxD,YAAY,EACV,YAAY,EACZ,eAAe,EACf,eAAe,EACf,iBAAiB,GAClB,MAAM,sBAAsB,CAAC;AAG9B,YAAY,EACV,UAAU,EACV,cAAc,EACd,WAAW,EACX,gBAAgB,EAChB,gBAAgB,EAChB,eAAe,EACf,iBAAiB,EACjB,cAAc,EACd,gBAAgB,EAChB,cAAc,EACd,iBAAiB,EACjB,sBAAsB,EACtB,uBAAuB,EACvB,kBAAkB,EAClB,yBAAyB,EACzB,2BAA2B,EAC3B,0BAA0B,EAC1B,sBAAsB,EACtB,wBAAwB,EACxB,qBAAqB,EACrB,kBAAkB,EAClB,aAAa,EACb,gBAAgB,EAChB,kBAAkB,EAClB,eAAe,EACf,eAAe,EACf,uBAAuB,EACvB,uBAAuB,EACvB,mBAAmB,EACnB,0BAA0B,EAC1B,wBAAwB,EACxB,sBAAsB,EACtB,oBAAoB,EACpB,sBAAsB,EACtB,wBAAwB,EACxB,yBAAyB,EACzB,YAAY,EACZ,UAAU,EACV,UAAU,EACV,SAAS,GACV,MAAM,aAAa,CAAC;AAGrB,OAAO,EACL,UAAU,EACV,cAAc,EACd,WAAW,EACX,cAAc,EACd,eAAe,EACf,mBAAmB,EACnB,cAAc,EACd,WAAW,GACZ,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -1,10 +1,33 @@
 /**
- * Meerkat TypeScript SDK — communicate with the Meerkat agent runtime via JSON-RPC.
+ * Meerkat TypeScript SDK — communicate with the Meerkat agent runtime.
+ *
+ * @example
+ * ```ts
+ * import { MeerkatClient } from "@rkat/sdk";
+ *
+ * const client = new MeerkatClient();
+ * await client.connect();
+ *
+ * const session = await client.createSession("Hello!");
+ * console.log(session.text);
+ *
+ * for await (const event of session.stream("Tell me a joke")) {
+ *   if (event.type === "text_delta") {
+ *     process.stdout.write(event.delta);
+ *   }
+ * }
+ *
+ * await client.close();
+ * ```
  */
+// Core client and session
 export { MeerkatClient } from "./client.js";
-export { CapabilityChecker } from "./capabilities.js";
-export { EventStream } from "./streaming.js";
-export { SkillHelper } from "./skills.js";
+export { Session } from "./session.js";
+export { CommsEventStream, EventStream } from "./streaming.js";
+// Error hierarchy
 export { MeerkatError, CapabilityUnavailableError, SessionNotFoundError, SkillNotFoundError, } from "./generated/errors.js";
+// Contract version
 export { CONTRACT_VERSION } from "./generated/types.js";
+// Event utilities
+export { parseEvent, parseCoreEvent, isTextDelta, isTextComplete, isTurnCompleted, isToolCallRequested, isRunCompleted, isRunFailed, } from "./events.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC7C,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EACL,YAAY,EACZ,0BAA0B,EAC1B,oBAAoB,EACpB,kBAAkB,GACnB,MAAM,uBAAuB,CAAC;AAQ/B,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,0BAA0B;AAC1B,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAiB/D,kBAAkB;AAClB,OAAO,EACL,YAAY,EACZ,0BAA0B,EAC1B,oBAAoB,EACpB,kBAAkB,GACnB,MAAM,uBAAuB,CAAC;AAE/B,mBAAmB;AACnB,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAoDxD,kBAAkB;AAClB,OAAO,EACL,UAAU,EACV,cAAc,EACd,WAAW,EACX,cAAc,EACd,eAAe,EACf,mBAAmB,EACnB,cAAc,EACd,WAAW,GACZ,MAAM,aAAa,CAAC"}

package/dist/session.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Session — the first-class handle for multi-turn agent conversations.
+ *
+ * @example
+ * ```ts
+ * const client = await Meerkat.connect();
+ * const session = await client.createSession("Summarise this repo");
+ * console.log(session.text);
+ *
+ * // Multi-turn
+ * const result = await session.turn("Now list the open issues");
+ *
+ * // Streaming
+ * for await (const event of session.stream("Explain the CI pipeline")) {
+ *   if (event.type === "text_delta") {
+ *     process.stdout.write(event.delta);
+ *   }
+ * }
+ * ```
+ */
+import type { RunResult, SkillRef, TurnToolOverlay } from "./types.js";
+import type { MeerkatClient } from "./client.js";
+import type { CommsEventStream, EventStream } from "./streaming.js";
+export declare class Session {
+    /** @internal */
+    _lastResult: RunResult;
+    private readonly _client;
+    private readonly _id;
+    private readonly _ref;
+    /** @internal — constructed by MeerkatClient, not directly. */
+    constructor(client: MeerkatClient, result: RunResult);
+    /** The stable UUID for this session. */
+    get id(): string;
+    /** Optional human-readable session reference. */
+    get ref(): string | undefined;
+    /** The most recent {@link RunResult}. */
+    get lastResult(): RunResult;
+    /** The assistant's text from the last turn. */
+    get text(): string;
+    /** Token usage from the last turn. */
+    get usage(): import("./events.js").Usage;
+    /** Number of LLM turns in the last run. */
+    get turns(): number;
+    /** Number of tool calls in the last run. */
+    get toolCalls(): number;
+    /** Structured output from the last run, if requested. */
+    get structuredOutput(): unknown;
+    /** Run another turn on this session (non-streaming). */
+    turn(prompt: string, options?: {
+        skillRefs?: SkillRef[];
+        skillReferences?: string[];
+        flowToolOverlay?: TurnToolOverlay;
+    }): Promise<RunResult>;
+    /**
+     * Run another turn on this session with streaming events.
+     *
+     * Returns an {@link EventStream} `AsyncIterable<AgentEvent>`.
+     *
+     * @example
+     * ```ts
+     * for await (const event of session.stream("prompt")) {
+     *   // ...
+     * }
+     * ```
+     */
+    stream(prompt: string, options?: {
+        skillRefs?: SkillRef[];
+        skillReferences?: string[];
+        flowToolOverlay?: TurnToolOverlay;
+    }): EventStream;
+    /** Cancel the currently running turn, if any. */
+    interrupt(): Promise<void>;
+    /** Archive (remove) this session from the server. */
+    archive(): Promise<void>;
+    /**
+     * Invoke a skill in this session.
+     *
+     * Accepts a {@link SkillKey} or a legacy string reference.
+     * Sends the structured `skill_refs` parameter to the runtime.
+     */
+    invokeSkill(skillRef: SkillRef, prompt: string): Promise<RunResult>;
+    /** Send a comms command scoped to this session. */
+    send(command: Record<string, unknown>): Promise<Record<string, unknown>>;
+    /** List peers visible to this session's comms runtime. */
+    peers(): Promise<Array<Record<string, unknown>>>;
+    openCommsStream(options?: {
+        scope?: "session" | "interaction";
+        interactionId?: string;
+    }): Promise<CommsEventStream>;
+    sendAndStream(command: Record<string, unknown>): Promise<{
+        receipt: Record<string, unknown>;
+        stream: CommsEventStream;
+    }>;
+    toString(): string;
+}
+//# sourceMappingURL=session.d.ts.map

package/dist/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AACvE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,KAAK,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAEpE,qBAAa,OAAO;IAClB,gBAAgB;IAChB,WAAW,EAAE,SAAS,CAAC;IAEvB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAgB;IACxC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAC7B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAqB;IAE1C,8DAA8D;gBAClD,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,SAAS;IASpD,wCAAwC;IACxC,IAAI,EAAE,IAAI,MAAM,CAEf;IAED,iDAAiD;IACjD,IAAI,GAAG,IAAI,MAAM,GAAG,SAAS,CAE5B;IAID,yCAAyC;IACzC,IAAI,UAAU,IAAI,SAAS,CAE1B;IAED,+CAA+C;IAC/C,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,sCAAsC;IACtC,IAAI,KAAK,gCAER;IAED,2CAA2C;IAC3C,IAAI,KAAK,IAAI,MAAM,CAElB;IAED,4CAA4C;IAC5C,IAAI,SAAS,IAAI,MAAM,CAEtB;IAED,yDAAyD;IACzD,IAAI,gBAAgB,IAAI,OAAO,CAE9B;IAID,wDAAwD;IAClD,IAAI,CACR,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE;QACR,SAAS,CAAC,EAAE,QAAQ,EAAE,CAAC;QACvB,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;QAC3B,eAAe,CAAC,EAAE,eAAe,CAAC;KACnC,GACA,OAAO,CAAC,SAAS,CAAC;IAUrB;;;;;;;;;;;OAWG;IACH,MAAM,CACJ,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE;QACR,SAAS,CAAC,EAAE,QAAQ,EAAE,CAAC;QACvB,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;QAC3B,eAAe,CAAC,EAAE,eAAe,CAAC;KACnC,GACA,WAAW;IAWd,iDAAiD;IAC3C,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;IAIhC,qDAAqD;IAC/C,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAM9B;;;;;OAKG;IACG,WAAW,CACf,QAAQ,EAAE,QAAQ,EAClB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,SAAS,CAAC;IAOrB,mDAAmD;IAC7C,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAI9E,0DAA0D;IACpD,KAAK,IAAI,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAKhD,eAAe,CACnB,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,SAAS,GAAG,aAAa,CAAC;QAAC,aAAa,CAAC,EAAE,MAAM,CAAA;KAAE,GACtE,OAAO,CAAC,gBAAgB,CAAC;IAItB,aAAa,CACjB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAAC,MAAM,EAAE,gBAAgB,CAAA;KAAE,CAAC;IAI1E,QAAQ,IAAI,MAAM;CAInB"}

package/dist/session.js

@@ -0,0 +1,131 @@
+/**
+ * Session — the first-class handle for multi-turn agent conversations.
+ *
+ * @example
+ * ```ts
+ * const client = await Meerkat.connect();
+ * const session = await client.createSession("Summarise this repo");
+ * console.log(session.text);
+ *
+ * // Multi-turn
+ * const result = await session.turn("Now list the open issues");
+ *
+ * // Streaming
+ * for await (const event of session.stream("Explain the CI pipeline")) {
+ *   if (event.type === "text_delta") {
+ *     process.stdout.write(event.delta);
+ *   }
+ * }
+ * ```
+ */
+export class Session {
+    /** @internal */
+    _lastResult;
+    _client;
+    _id;
+    _ref;
+    /** @internal — constructed by MeerkatClient, not directly. */
+    constructor(client, result) {
+        this._client = client;
+        this._id = result.sessionId;
+        this._ref = result.sessionRef;
+        this._lastResult = result;
+    }
+    // -- Identity -----------------------------------------------------------
+    /** The stable UUID for this session. */
+    get id() {
+        return this._id;
+    }
+    /** Optional human-readable session reference. */
+    get ref() {
+        return this._ref;
+    }
+    // -- Last result shortcuts ----------------------------------------------
+    /** The most recent {@link RunResult}. */
+    get lastResult() {
+        return this._lastResult;
+    }
+    /** The assistant's text from the last turn. */
+    get text() {
+        return this._lastResult.text;
+    }
+    /** Token usage from the last turn. */
+    get usage() {
+        return this._lastResult.usage;
+    }
+    /** Number of LLM turns in the last run. */
+    get turns() {
+        return this._lastResult.turns;
+    }
+    /** Number of tool calls in the last run. */
+    get toolCalls() {
+        return this._lastResult.toolCalls;
+    }
+    /** Structured output from the last run, if requested. */
+    get structuredOutput() {
+        return this._lastResult.structuredOutput;
+    }
+    // -- Multi-turn ---------------------------------------------------------
+    /** Run another turn on this session (non-streaming). */
+    async turn(prompt, options) {
+        const result = await this._client._startTurn(this._id, prompt, options);
+        this._lastResult = result;
+        return result;
+    }
+    /**
+     * Run another turn on this session with streaming events.
+     *
+     * Returns an {@link EventStream} `AsyncIterable<AgentEvent>`.
+     *
+     * @example
+     * ```ts
+     * for await (const event of session.stream("prompt")) {
+     *   // ...
+     * }
+     * ```
+     */
+    stream(prompt, options) {
+        return this._client._startTurnStreaming(this._id, prompt, options, this);
+    }
+    // -- Lifecycle ----------------------------------------------------------
+    /** Cancel the currently running turn, if any. */
+    async interrupt() {
+        await this._client._interrupt(this._id);
+    }
+    /** Archive (remove) this session from the server. */
+    async archive() {
+        await this._client._archive(this._id);
+    }
+    // -- Skills convenience -------------------------------------------------
+    /**
+     * Invoke a skill in this session.
+     *
+     * Accepts a {@link SkillKey} or a legacy string reference.
+     * Sends the structured `skill_refs` parameter to the runtime.
+     */
+    async invokeSkill(skillRef, prompt) {
+        this._client.requireCapability("skills");
+        return this.turn(prompt, { skillRefs: [skillRef] });
+    }
+    // -- Comms convenience --------------------------------------------------
+    /** Send a comms command scoped to this session. */
+    async send(command) {
+        return this._client._send(this._id, command);
+    }
+    /** List peers visible to this session's comms runtime. */
+    async peers() {
+        const result = await this._client._peers(this._id);
+        return (result.peers ?? []);
+    }
+    async openCommsStream(options) {
+        return this._client.openCommsStream(this._id, options);
+    }
+    async sendAndStream(command) {
+        return this._client.sendAndStream(this._id, command);
+    }
+    toString() {
+        const ref = this._ref ? ` ref=${this._ref}` : "";
+        return `Session(id=${this._id}${ref})`;
+    }
+}
+//# sourceMappingURL=session.js.map

package/dist/session.js.map

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

package/dist/streaming.d.ts

@@ -1,26 +1,80 @@
 /**
- * Async event stream over JSON-RPC notifications from rkat-rpc.
- */
-import type { Interface as ReadlineInterface } from "node:readline";
-import type { WireEvent } from "./generated/types.js";
-/**
- * Async iterator that yields WireEvent objects from JSON-RPC notifications.
+ * Streaming API for the Meerkat TypeScript SDK.
  *
- * Skips response messages (which have an `id` field) and only yields
- * notification payloads parsed as WireEvent.
+ * {@link EventStream} is an `AsyncIterable<StreamEvent>` that yields typed
+ * events from a running turn, with access to the final {@link RunResult}
+ * after iteration.
  *
  * @example
  * ```ts
- * for await (const event of new EventStream(readline)) {
- *   console.log(event.session_id, event.event);
+ * for await (const event of session.stream("prompt")) {
+ *   if (event.type === "text_delta") {
+ *     process.stdout.write(event.delta);
+ *   }
  * }
+ * console.log(stream.result.usage.inputTokens);
  * ```
  */
-export declare class EventStream implements AsyncIterable<WireEvent> {
+import type { StreamEvent } from "./events.js";
+import type { RunResult } from "./types.js";
+import type { Session } from "./session.js";
+/** @internal Queue with promise-based get(). */
+declare class AsyncQueue<T> {
     private buffer;
     private waiters;
-    private closed;
-    constructor(rl: ReadlineInterface);
-    [Symbol.asyncIterator](): AsyncIterator<WireEvent>;
+    put(item: T): void;
+    get(): Promise<T>;
+    tryGet(): T | undefined;
+    get isEmpty(): boolean;
+    failAll(error: Error): void;
+}
+/**
+ * Typed async iterable of {@link StreamEvent} objects from a running turn.
+ *
+ * After iteration completes, the {@link result} getter returns the final
+ * {@link RunResult}.
+ */
+export declare class EventStream implements AsyncIterable<StreamEvent> {
+    /** @internal */ _sessionId: string;
+    private readonly _eventQueue;
+    private readonly _responsePromise;
+    private readonly _parseResult;
+    private _result;
+    private readonly _session;
+    /** @internal — constructed by MeerkatClient, not directly. */
+    constructor(opts: {
+        sessionId: string;
+        eventQueue: AsyncQueue<Record<string, unknown> | null>;
+        responsePromise: Promise<Record<string, unknown>>;
+        parseResult: (raw: Record<string, unknown>) => RunResult;
+        session?: Session;
+    });
+    /** The session ID for this turn. */
+    get sessionId(): string;
+    /** The final {@link RunResult}. Available after iteration completes. */
+    get result(): RunResult;
+    [Symbol.asyncIterator](): AsyncGenerator<StreamEvent, void, undefined>;
+    /** Consume all events silently and return the final result. */
+    collect(): Promise<RunResult>;
+    /** Consume events, accumulate text deltas, return `[fullText, result]`. */
+    collectText(): Promise<[string, RunResult]>;
+    private _finalise;
+}
+/**
+ * Async iterable of raw comms stream notifications emitted via `comms/stream_event`.
+ */
+export declare class CommsEventStream implements AsyncIterable<Record<string, unknown>> {
+    private readonly _streamId;
+    private readonly _eventQueue;
+    private readonly _onClose;
+    constructor(opts: {
+        streamId: string;
+        eventQueue: AsyncQueue<Record<string, unknown> | null>;
+        onClose: (streamId: string) => Promise<void>;
+    });
+    get streamId(): string;
+    [Symbol.asyncIterator](): AsyncGenerator<Record<string, unknown>, void, undefined>;
+    close(): Promise<void>;
 }
+export { AsyncQueue };
 //# sourceMappingURL=streaming.d.ts.map

package/dist/streaming.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"streaming.d.ts","sourceRoot":"","sources":["../src/streaming.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,SAAS,IAAI,iBAAiB,EAAE,MAAM,eAAe,CAAC;AACpE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAEtD;;;;;;;;;;;;GAYG;AACH,qBAAa,WAAY,YAAW,aAAa,CAAC,SAAS,CAAC;IAC1D,OAAO,CAAC,MAAM,CAAmB;IACjC,OAAO,CAAC,OAAO,CAAyD;IACxE,OAAO,CAAC,MAAM,CAAS;gBAEX,EAAE,EAAE,iBAAiB;IAoCjC,CAAC,MAAM,CAAC,aAAa,CAAC,IAAI,aAAa,CAAC,SAAS,CAAC;CAqBnD"}
+{"version":3,"file":"streaming.d.ts","sourceRoot":"","sources":["../src/streaming.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAG5C,gDAAgD;AAChD,cAAM,UAAU,CAAC,CAAC;IAChB,OAAO,CAAC,MAAM,CAAW;IACzB,OAAO,CAAC,OAAO,CAAiC;IAEhD,GAAG,CAAC,IAAI,EAAE,CAAC,GAAG,IAAI;IAQlB,GAAG,IAAI,OAAO,CAAC,CAAC,CAAC;IASjB,MAAM,IAAI,CAAC,GAAG,SAAS;IAIvB,IAAI,OAAO,IAAI,OAAO,CAErB;IAED,OAAO,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI;CAQ5B;AAKD;;;;;GAKG;AACH,qBAAa,WAAY,YAAW,aAAa,CAAC,WAAW,CAAC;IAC5D,gBAAgB,CAAC,UAAU,EAAE,MAAM,CAAC;IACpC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA6C;IACzE,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAmC;IACpE,OAAO,CAAC,QAAQ,CAAC,YAAY,CAA8C;IAC3E,OAAO,CAAC,OAAO,CAA0B;IACzC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAiB;IAE1C,8DAA8D;gBAClD,IAAI,EAAE;QAChB,SAAS,EAAE,MAAM,CAAC;QAClB,UAAU,EAAE,UAAU,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC,CAAC;QACvD,eAAe,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;QAClD,WAAW,EAAE,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,SAAS,CAAC;QACzD,OAAO,CAAC,EAAE,OAAO,CAAC;KACnB;IAQD,oCAAoC;IACpC,IAAI,SAAS,IAAI,MAAM,CAEtB;IAED,wEAAwE;IACxE,IAAI,MAAM,IAAI,SAAS,CAQtB;IAEM,CAAC,MAAM,CAAC,aAAa,CAAC,IAAI,cAAc,CAAC,WAAW,EAAE,IAAI,EAAE,SAAS,CAAC;IA0C7E,+DAA+D;IACzD,OAAO,IAAI,OAAO,CAAC,SAAS,CAAC;IAOnC,2EAA2E;IACrE,WAAW,IAAI,OAAO,CAAC,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IAUjD,OAAO,CAAC,SAAS;CASlB;AAED;;GAEG;AACH,qBAAa,gBAAiB,YAAW,aAAa,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC7E,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA6C;IACzE,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAsC;gBAEnD,IAAI,EAAE;QAChB,QAAQ,EAAE,MAAM,CAAC;QACjB,UAAU,EAAE,UAAU,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC,CAAC;QACvD,OAAO,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;KAC9C;IAMD,IAAI,QAAQ,IAAI,MAAM,CAErB;IAEM,CAAC,MAAM,CAAC,aAAa,CAAC,IAAI,cAAc,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,IAAI,EAAE,SAAS,CAAC;IAQnF,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAG7B;AAGD,OAAO,EAAE,UAAU,EAAE,CAAC"}