@hypercli.com/sdk 0.9.1

package/dist/acp-driver.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Serializes original messages through CodingAgentAcpClient.prompt(), which
+ * waits for the native v1 terminal response. Commit precedes settlement.
+ * Cancelled completion pauses queued input until a new explicit submission;
+ * uncertain delivery or commit failure fences this driver without resending.
+ */
+import { type CodingAgentAcpClient, type ContentBlock } from './acp.js';
+import type { AcpLease } from './acp-pool.js';
+export type AcpTurnDriverState = 'idle' | 'submitted' | 'running';
+/** Settlement of one turn covering a submitted message. */
+export interface AcpTurnOutcome {
+    stopReason: string | null;
+}
+export interface AcpTurnBundle {
+    sessionId: string;
+    /** Text blocks from the single queued submission, in order. */
+    messages: string[];
+    /** The exact content blocks sent in `session/prompt`, including non-text content. */
+    blocks: ContentBlock[];
+}
+export interface AcpTurnDriverOptions {
+    sessionId: string;
+    /**
+     * Durable-commit hook run when the client's completion helper resolves.
+     * Window advance, submit-promise resolution, and the next bundle's flush
+     * all happen only after this resolves. Receives the stopReason verbatim
+     * (`end_turn`, `cancelled`, ...); cancelled turns commit normally — their
+     * bundled messages reached the model.
+     */
+    commit: (stopReason: string | null) => Promise<void>;
+    /** Fired once per flush with the bundle going on the wire. */
+    onBundleOpen?: (bundle: AcpTurnBundle) => void;
+    /**
+     * Prompt observation and commit failures fence this driver and reject all
+     * pending submissions. The window is retained; later submissions reject
+     * with the same failure without resending input.
+     */
+    onError?: (error: Error) => void;
+}
+export declare class AcpTurnDriver {
+    private readonly client;
+    private readonly leaseRelease;
+    private readonly options;
+    private readonly window;
+    private state;
+    private inFlight;
+    private closed;
+    private failure;
+    constructor(source: CodingAgentAcpClient | AcpLease, options: AcpTurnDriverOptions);
+    get sessionId(): string;
+    /** `idle | submitted | running` — the per-leg turn state machine. */
+    get turnState(): AcpTurnDriverState;
+    /** Messages waiting in the pending window, including the in-flight bundle. */
+    get pendingCount(): number;
+    /** Queue one original message; a new explicit submission resumes paused input. */
+    submit(content: string | ContentBlock[]): Promise<AcpTurnOutcome>;
+    /**
+     * Stop consuming settlement and release the pool lease when this
+     * driver was built from one. A client passed directly is NOT closed.
+     * Outstanding `submit()` promises reject; an in-flight turn keeps running
+     * pod-side but its response is no longer consumed here (mirrors the py-sdk
+     * driver's close dropping its prompt waiter).
+     */
+    close(): void;
+    private flush;
+    /** The correlated native prompt result settles the owned turn. */
+    private onPromptResponse;
+    private onPromptFailed;
+    private completeTurn;
+    private emitError;
+}
+//# sourceMappingURL=acp-driver.d.ts.map

package/dist/acp-driver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"acp-driver.d.ts","sourceRoot":"","sources":["../src/acp-driver.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EACL,KAAK,oBAAoB,EACzB,KAAK,YAAY,EAClB,MAAM,UAAU,CAAC;AAClB,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE9C,MAAM,MAAM,kBAAkB,GAAG,MAAM,GAAG,WAAW,GAAG,SAAS,CAAC;AAElE,2DAA2D;AAC3D,MAAM,WAAW,cAAc;IAC7B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,+DAA+D;IAC/D,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,qFAAqF;IACrF,MAAM,EAAE,YAAY,EAAE,CAAC;CACxB;AAED,MAAM,WAAW,oBAAoB;IACnC,SAAS,EAAE,MAAM,CAAC;IAClB;;;;;;OAMG;IACH,MAAM,EAAE,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACrD,8DAA8D;IAC9D,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,aAAa,KAAK,IAAI,CAAC;IAC/C;;;;OAIG;IACH,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;CAClC;AA8BD,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAuB;IAC9C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAA6B;IAC1D,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAuB;IAC/C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAwB;IAC/C,OAAO,CAAC,KAAK,CAA8B;IAC3C,OAAO,CAAC,QAAQ,CAA+B;IAC/C,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,OAAO,CAAsB;gBAEzB,MAAM,EAAE,oBAAoB,GAAG,QAAQ,EAAE,OAAO,EAAE,oBAAoB;IAalF,IAAI,SAAS,IAAI,MAAM,CAEtB;IAED,qEAAqE;IACrE,IAAI,SAAS,IAAI,kBAAkB,CAElC;IAED,8EAA8E;IAC9E,IAAI,YAAY,IAAI,MAAM,CAEzB;IAED,kFAAkF;IAClF,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,YAAY,EAAE,GAAG,OAAO,CAAC,cAAc,CAAC;IAUjE;;;;;;OAMG;IACH,KAAK,IAAI,IAAI;IAYb,OAAO,CAAC,KAAK;IAuBb,kEAAkE;IAClE,OAAO,CAAC,gBAAgB;IAKxB,OAAO,CAAC,cAAc;YAUR,YAAY;IAiB1B,OAAO,CAAC,SAAS;CAOlB"}

package/dist/acp-driver.js

@@ -0,0 +1,147 @@
+function newTurnWaiter() {
+    let resolve;
+    let reject;
+    const promise = new Promise((res, rej) => {
+        resolve = res;
+        reject = rej;
+    });
+    // The promise is optional for callers; never let an ignored rejection trip
+    // the runtime's unhandled-rejection guard.
+    void promise.catch(() => { });
+    return { promise, resolve, reject };
+}
+function toError(error) {
+    return error instanceof Error ? error : new Error(String(error));
+}
+export class AcpTurnDriver {
+    client;
+    leaseRelease = null;
+    options;
+    window = [];
+    state = 'idle';
+    inFlight = null;
+    closed = false;
+    failure = null;
+    constructor(source, options) {
+        // Duck-typed: an AcpLease carries `client` + `release`, the bare client
+        // does not. (Structural fakes therefore take the bare-client branch.)
+        if (typeof source.release === 'function' && source.client !== undefined) {
+            const lease = source;
+            this.client = lease.client;
+            this.leaseRelease = lease.release;
+        }
+        else {
+            this.client = source;
+        }
+        this.options = options;
+    }
+    get sessionId() {
+        return this.options.sessionId;
+    }
+    /** `idle | submitted | running` — the per-leg turn state machine. */
+    get turnState() {
+        return this.state;
+    }
+    /** Messages waiting in the pending window, including the in-flight bundle. */
+    get pendingCount() {
+        return this.window.length;
+    }
+    /** Queue one original message; a new explicit submission resumes paused input. */
+    submit(content) {
+        if (this.closed)
+            return Promise.reject(new Error('AcpTurnDriver is closed'));
+        if (this.failure)
+            return Promise.reject(this.failure);
+        const blocks = typeof content === 'string' ? [{ type: 'text', text: content }] : content;
+        const waiter = newTurnWaiter();
+        this.window.push({ blocks: structuredClone(blocks), waiter });
+        this.flush();
+        return waiter.promise;
+    }
+    /**
+     * Stop consuming settlement and release the pool lease when this
+     * driver was built from one. A client passed directly is NOT closed.
+     * Outstanding `submit()` promises reject; an in-flight turn keeps running
+     * pod-side but its response is no longer consumed here (mirrors the py-sdk
+     * driver's close dropping its prompt waiter).
+     */
+    close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        // Every in-flight bundle entry is still in the window (entries leave only
+        // on commit), so rejecting the whole window settles every live waiter.
+        const error = new Error('AcpTurnDriver is closed');
+        for (const entry of this.window)
+            entry.waiter.reject(error);
+        this.inFlight = null;
+        this.state = 'idle';
+        this.leaseRelease?.();
+    }
+    flush() {
+        if (this.closed || this.state !== 'idle' || this.window.length === 0 || this.inFlight !== null)
+            return;
+        const flight = this.window[0];
+        const blocks = structuredClone(flight.blocks);
+        const texts = blocks.filter((block) => block.type === 'text').map((block) => block.text);
+        this.state = 'submitted';
+        this.inFlight = flight;
+        const bundle = {
+            sessionId: this.options.sessionId,
+            messages: texts,
+            blocks,
+        };
+        try {
+            this.options.onBundleOpen?.(bundle);
+        }
+        catch (error) {
+            console.error('AcpTurnDriver onBundleOpen listener threw', error);
+        }
+        this.client.prompt(this.options.sessionId, blocks).then((response) => this.onPromptResponse(flight, response), (error) => this.onPromptFailed(flight, error));
+    }
+    /** The correlated native prompt result settles the owned turn. */
+    onPromptResponse(flight, response) {
+        if (this.closed || this.inFlight !== flight)
+            return;
+        void this.completeTurn(flight, response.stopReason ?? null);
+    }
+    onPromptFailed(flight, error) {
+        if (this.closed || this.inFlight !== flight)
+            return;
+        // Delivery is uncertain. Retain the flight as a fence until the caller
+        // reconciles/closes this driver; later submissions must not resend it.
+        const failure = toError(error);
+        this.failure = failure;
+        for (const entry of this.window)
+            entry.waiter.reject(failure);
+        this.emitError(failure);
+    }
+    async completeTurn(flight, stopReason) {
+        try {
+            await this.options.commit(stopReason);
+        }
+        catch (error) {
+            // The runtime completed but persistence failed. Never resend its input.
+            this.onPromptFailed(flight, error);
+            return;
+        }
+        if (this.closed || this.inFlight !== flight)
+            return;
+        this.inFlight = null;
+        this.state = 'idle';
+        this.window.splice(0, 1);
+        const outcome = { stopReason };
+        flight.waiter.resolve(outcome);
+        if (stopReason !== 'cancelled')
+            this.flush();
+    }
+    emitError(error) {
+        try {
+            this.options.onError?.(error);
+        }
+        catch (listenerError) {
+            console.error('AcpTurnDriver onError listener threw', listenerError);
+        }
+    }
+}
+//# sourceMappingURL=acp-driver.js.map

package/dist/acp-driver.js.map

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

package/dist/acp-pool.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Keyed connection pool for {@link CodingAgentAcpClient}.
+ *
+ * Callers choose keys for connections they want to share (for example, an
+ * agent ID or an agent/session pair). The pool hands out refcounted leases
+ * on a single connected client per key: concurrent `acquire()` calls dedupe onto one
+ * in-flight connect, the last `release()` closes the client, and a terminal
+ * self-close makes the pool forget the entry so the next `acquire()` dials
+ * fresh. Update fan-out across subscribers is handled by
+ * `client.addUpdateListener(...)`.
+ *
+ * Protocol-version awareness: negotiation happens per connection — every key
+ * negotiates independently — and the negotiated version is read off the
+ * lease's client (`lease.client.negotiatedProtocolVersion`; the client only
+ * speaks v1). Pool bookkeeping itself (refcounts, close discipline) is
+ * version-agnostic.
+ */
+import { CodingAgentAcpClient, type CodingAgentAcpConnectOptions } from './acp.js';
+/** A live hold on a pooled connection. `release()` is idempotent per lease. */
+export interface AcpLease {
+    client: CodingAgentAcpClient;
+    release(): void;
+}
+export declare class CodingAgentAcpPool {
+    private readonly connect;
+    private readonly connectOptions?;
+    private readonly entries;
+    constructor(options: {
+        /**
+         * Dial one connection for the key. Forward the optional second argument
+         * into the dial: its signal cancels pending initialization on pool teardown.
+         * Legacy factories that ignore it still have their acquisitions rejected
+         * and late clients closed, but must forward it to abort a pending socket.
+         */
+        connect: (key: string, options?: CodingAgentAcpConnectOptions) => Promise<CodingAgentAcpClient>;
+        /** Per-key connect options; the pool chains its close bookkeeping into `onClose`. */
+        connectOptions?: (key: string) => CodingAgentAcpConnectOptions;
+    });
+    /**
+     * Take a lease on the connection for `key`, dialing on first use. All
+     * concurrent acquirers share one in-flight connect; each gets its own
+     * lease. A terminal client close may redial; explicit pool teardown rejects
+     * affected acquisitions instead of silently creating another connection.
+     */
+    acquire(key: string): Promise<AcpLease>;
+    /** Live refcounts: per-key when `key` is given, pooled connections otherwise. */
+    size(key?: string): number;
+    /** Force-close the connection for `key` even with live leases and forget it. */
+    drop(key: string): void;
+    /**
+     * Force-close every connection whose key starts with `prefix` and forget
+     * them. Pair with key builders that namespace sub-connections under a
+     * parent id (e.g. `agentId` / `agentId#sessionId`) so tearing down the
+     * parent reaps the pinned children too.
+     */
+    dropPrefix(prefix: string): void;
+    /** Drop every pooled connection. */
+    close(): void;
+    private dial;
+    /**
+     * `terminate()` runs through `this.close()`, so shadowing it observes every
+     * close path — explicit, abort-driven, or a terminal bridge close code —
+     * without depending on the consumer threading connectOptions through.
+     */
+    private wrapClose;
+    private handleClientClosed;
+    private releaseEntry;
+    private forget;
+}
+//# sourceMappingURL=acp-pool.d.ts.map

package/dist/acp-pool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"acp-pool.d.ts","sourceRoot":"","sources":["../src/acp-pool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,EACL,oBAAoB,EAEpB,KAAK,4BAA4B,EAClC,MAAM,UAAU,CAAC;AAElB,+EAA+E;AAC/E,MAAM,WAAW,QAAQ;IACvB,MAAM,EAAE,oBAAoB,CAAC;IAC7B,OAAO,IAAI,IAAI,CAAC;CACjB;AAYD,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAGW;IACnC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAC,CAAgD;IAChF,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAgC;gBAE5C,OAAO,EAAE;QACnB;;;;;WAKG;QACH,OAAO,EAAE,CACP,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,4BAA4B,KACnC,OAAO,CAAC,oBAAoB,CAAC,CAAC;QACnC,qFAAqF;QACrF,cAAc,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,4BAA4B,CAAC;KAChE;IAKD;;;;;OAKG;IACG,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC;IA+B7C,iFAAiF;IACjF,IAAI,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM;IAK1B,gFAAgF;IAChF,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAUvB;;;;;OAKG;IACH,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAMhC,oCAAoC;IACpC,KAAK,IAAI,IAAI;IAIb,OAAO,CAAC,IAAI;IA2CZ;;;;OAIG;IACH,OAAO,CAAC,SAAS;IASjB,OAAO,CAAC,kBAAkB;IAM1B,OAAO,CAAC,YAAY;IAOpB,OAAO,CAAC,MAAM;CAMf"}

package/dist/acp-pool.js

@@ -0,0 +1,181 @@
+/**
+ * Keyed connection pool for {@link CodingAgentAcpClient}.
+ *
+ * Callers choose keys for connections they want to share (for example, an
+ * agent ID or an agent/session pair). The pool hands out refcounted leases
+ * on a single connected client per key: concurrent `acquire()` calls dedupe onto one
+ * in-flight connect, the last `release()` closes the client, and a terminal
+ * self-close makes the pool forget the entry so the next `acquire()` dials
+ * fresh. Update fan-out across subscribers is handled by
+ * `client.addUpdateListener(...)`.
+ *
+ * Protocol-version awareness: negotiation happens per connection — every key
+ * negotiates independently — and the negotiated version is read off the
+ * lease's client (`lease.client.negotiatedProtocolVersion`; the client only
+ * speaks v1). Pool bookkeeping itself (refcounts, close discipline) is
+ * version-agnostic.
+ */
+import { CodingAgentAcpConnectionError, } from './acp.js';
+export class CodingAgentAcpPool {
+    connect;
+    connectOptions;
+    entries = new Map();
+    constructor(options) {
+        this.connect = options.connect;
+        this.connectOptions = options.connectOptions;
+    }
+    /**
+     * Take a lease on the connection for `key`, dialing on first use. All
+     * concurrent acquirers share one in-flight connect; each gets its own
+     * lease. A terminal client close may redial; explicit pool teardown rejects
+     * affected acquisitions instead of silently creating another connection.
+     */
+    async acquire(key) {
+        for (;;) {
+            let entry = this.entries.get(key);
+            if (entry && (entry.forgotten || entry.client?.closed === true)) {
+                this.forget(key, entry);
+                entry = undefined;
+            }
+            if (!entry) {
+                entry = this.dial(key);
+                this.entries.set(key, entry);
+            }
+            entry.refs += 1;
+            const client = await entry.promise;
+            if (entry.controller.signal.aborted)
+                throw entry.controller.signal.reason;
+            if (entry.forgotten || client.closed) {
+                entry.refs -= 1;
+                continue;
+            }
+            const current = entry;
+            let released = false;
+            return {
+                client,
+                release: () => {
+                    if (released)
+                        return;
+                    released = true;
+                    this.releaseEntry(key, current);
+                },
+            };
+        }
+    }
+    /** Live refcounts: per-key when `key` is given, pooled connections otherwise. */
+    size(key) {
+        if (key !== undefined)
+            return this.entries.get(key)?.refs ?? 0;
+        return this.entries.size;
+    }
+    /** Force-close the connection for `key` even with live leases and forget it. */
+    drop(key) {
+        const entry = this.entries.get(key);
+        if (!entry)
+            return;
+        this.entries.delete(key);
+        entry.forgotten = true;
+        entry.controller.abort(new CodingAgentAcpConnectionError('ACP pool entry dropped'));
+        entry.dispose();
+        entry.client?.close();
+    }
+    /**
+     * Force-close every connection whose key starts with `prefix` and forget
+     * them. Pair with key builders that namespace sub-connections under a
+     * parent id (e.g. `agentId` / `agentId#sessionId`) so tearing down the
+     * parent reaps the pinned children too.
+     */
+    dropPrefix(prefix) {
+        for (const key of [...this.entries.keys()]) {
+            if (key.startsWith(prefix))
+                this.drop(key);
+        }
+    }
+    /** Drop every pooled connection. */
+    close() {
+        for (const key of [...this.entries.keys()])
+            this.drop(key);
+    }
+    dial(key) {
+        const entry = {
+            refs: 0,
+            client: null,
+            forgotten: false,
+            promise: null,
+            controller: new AbortController(),
+            dispose: () => { },
+        };
+        const base = this.connectOptions?.(key);
+        const signal = entry.controller.signal;
+        const cancelled = new Promise((_resolve, reject) => {
+            signal.addEventListener('abort', () => reject(signal.reason), { once: true });
+        });
+        const abort = () => entry.controller.abort(new CodingAgentAcpConnectionError('ACP pool connect aborted'));
+        base?.signal?.addEventListener('abort', abort, { once: true });
+        entry.dispose = () => base?.signal?.removeEventListener('abort', abort);
+        if (base?.signal?.aborted)
+            abort();
+        const options = {
+            ...base,
+            signal,
+            onClose: (event) => {
+                this.handleClientClosed(key, entry);
+                base?.onClose?.(event);
+            },
+        };
+        const connecting = Promise.resolve().then(() => {
+            if (signal.aborted)
+                throw signal.reason;
+            return this.connect(key, options);
+        }).then((client) => {
+            entry.client = client;
+            this.wrapClose(key, entry, client);
+            if (entry.forgotten || signal.aborted || client.closed)
+                client.close();
+            return client;
+        });
+        entry.promise = Promise.race([connecting, cancelled]).catch((error) => {
+            entry.dispose();
+            this.forget(key, entry);
+            throw error;
+        });
+        return entry;
+    }
+    /**
+     * `terminate()` runs through `this.close()`, so shadowing it observes every
+     * close path — explicit, abort-driven, or a terminal bridge close code —
+     * without depending on the consumer threading connectOptions through.
+     */
+    wrapClose(key, entry, client) {
+        const original = client.close.bind(client);
+        client.close = () => {
+            const wasClosed = client.closed;
+            original();
+            if (!wasClosed)
+                this.handleClientClosed(key, entry);
+        };
+    }
+    handleClientClosed(key, entry) {
+        if (this.entries.get(key) !== entry)
+            return;
+        if (entry.client?.closed !== true)
+            return;
+        this.forget(key, entry);
+    }
+    releaseEntry(key, entry) {
+        if (entry.forgotten)
+            return;
+        entry.refs -= 1;
+        if (entry.refs > 0)
+            return;
+        this.drop(key);
+    }
+    forget(key, entry) {
+        if (this.entries.get(key) !== entry)
+            return;
+        this.entries.delete(key);
+        entry.forgotten = true;
+        entry.dispose();
+    }
+}
+//# sourceMappingURL=acp-pool.js.map

package/dist/acp-pool.js.map

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