@diffexai/diffex-client 0.2.0

package/dist/connection.js

@@ -0,0 +1,203 @@
+import { DEFAULT_MAX_FRAME_LENGTH, encodeClientMessage, PROTOCOL_VERSION, ProtocolValidationError, ServerMessageDecoder, } from "@diffexai/diffex-protocol";
+import { DiffexDisconnectedError, DiffexServerError, toDisconnectedError, toError } from "./errors.js";
+import { createPromiseResolvers } from "./promise.js";
+const MAX_UINT32 = 0xffff_ffff;
+export class Connection {
+    #options;
+    #maxFrameLength;
+    #lifecycle = { state: "disconnected" };
+    #sequence = 0;
+    constructor(options) {
+        this.#options = options;
+        this.#maxFrameLength = options.maxFrameLength ?? DEFAULT_MAX_FRAME_LENGTH;
+        if (!Number.isSafeInteger(this.#maxFrameLength) ||
+            this.#maxFrameLength <= 0 ||
+            this.#maxFrameLength > MAX_UINT32) {
+            throw new TypeError(`DiffexClient maxFrameLength must be an integer between 1 and ${MAX_UINT32}`);
+        }
+    }
+    get state() {
+        return this.#lifecycle.state;
+    }
+    get maxFrameLength() {
+        return this.#maxFrameLength;
+    }
+    connect() {
+        if (this.#lifecycle.state !== "disconnected") {
+            return Promise.reject(new DiffexDisconnectedError(`DiffexClient is already ${this.#lifecycle.state}`));
+        }
+        const id = ++this.#sequence;
+        const handshake = createPromiseResolvers();
+        this.#lifecycle = {
+            state: "connecting",
+            id,
+            decoder: new ServerMessageDecoder({ maxFrameLength: this.#maxFrameLength }),
+            handshake,
+        };
+        this.#options.onStateChange({ state: "connecting" });
+        const handlers = {
+            onData: (chunk) => this.#handleData(id, chunk),
+            onClose: () => {
+                if (this.#isCurrent(id))
+                    this.#handleClose();
+            },
+            onError: (error) => {
+                if (this.#isCurrent(id))
+                    this.#failAndClose(toDisconnectedError(error));
+            },
+        };
+        void this.#openTransport(id, handlers);
+        return handshake.promise;
+    }
+    disconnect(reason = "Client disconnected") {
+        if (this.#lifecycle.state === "disconnected")
+            return;
+        this.#failAndClose(typeof reason === "string" ? new DiffexDisconnectedError(reason) : reason);
+    }
+    fail(error) {
+        this.#failAndClose(error);
+    }
+    send(frame) {
+        const lifecycle = this.#lifecycle;
+        if (lifecycle.state !== "connected")
+            throw new DiffexDisconnectedError();
+        let sending;
+        try {
+            sending = lifecycle.transport.send(frame);
+        }
+        catch (error) {
+            this.#failAndClose(toDisconnectedError(error));
+            return;
+        }
+        void sending.catch((error) => {
+            const current = this.#lifecycle;
+            if (current.state !== "disconnected" && current.transport === lifecycle.transport) {
+                this.#failAndClose(toDisconnectedError(error));
+            }
+        });
+    }
+    async #openTransport(id, handlers) {
+        let transport;
+        try {
+            transport = await this.#options.transportFactory(handlers);
+        }
+        catch (error) {
+            if (this.#isCurrent(id))
+                this.#fail(toDisconnectedError(error));
+            return;
+        }
+        const lifecycle = this.#lifecycle;
+        if (lifecycle.state !== "connecting" || lifecycle.id !== id) {
+            transport.close();
+            return;
+        }
+        this.#lifecycle = { ...lifecycle, transport };
+        try {
+            await transport.send(encodeClientMessage({ type: "hello", version: PROTOCOL_VERSION }, { maxFrameLength: this.#maxFrameLength }));
+        }
+        catch (error) {
+            if (this.#isCurrent(id))
+                this.#failAndClose(toDisconnectedError(error));
+        }
+    }
+    #handleData(id, chunk) {
+        const lifecycle = this.#lifecycle;
+        if (lifecycle.state === "disconnected" || lifecycle.id !== id)
+            return;
+        if (lifecycle.state === "connecting" && !lifecycle.transport) {
+            this.#failAndClose(new ProtocolValidationError("Received server data before the client hello was sent"));
+            return;
+        }
+        let messages;
+        try {
+            messages = lifecycle.decoder.push(chunk);
+        }
+        catch (error) {
+            this.#failAndClose(toError(error));
+            return;
+        }
+        for (const message of messages) {
+            if (this.#lifecycle.state === "disconnected")
+                return;
+            this.#handleMessage(message);
+        }
+    }
+    #handleMessage(message) {
+        const lifecycle = this.#lifecycle;
+        if (lifecycle.state === "connecting") {
+            if (message.type === "hello_error") {
+                this.#failAndClose(new DiffexServerError(message.error));
+                return;
+            }
+            if (message.type !== "hello") {
+                this.#failAndClose(new ProtocolValidationError("Expected server hello as first message"));
+                return;
+            }
+            if (!lifecycle.transport) {
+                this.#failAndClose(new ProtocolValidationError("Received server hello before the client hello was sent"));
+                return;
+            }
+            const connected = {
+                state: "connected",
+                id: lifecycle.id,
+                decoder: lifecycle.decoder,
+                transport: lifecycle.transport,
+                handshake: lifecycle.handshake,
+            };
+            this.#lifecycle = connected;
+            try {
+                this.#options.onHandshake(message.snapshot);
+            }
+            catch (error) {
+                if (this.#lifecycle === connected)
+                    this.#failAndClose(toError(error));
+                return;
+            }
+            if (this.#lifecycle !== connected)
+                return;
+            this.#options.onStateChange({ state: "connected" });
+            if (this.#lifecycle !== connected)
+                return;
+            this.#lifecycle = { ...connected, handshake: undefined };
+            lifecycle.handshake.resolve(message.snapshot);
+            return;
+        }
+        if (lifecycle.state !== "connected")
+            return;
+        if (message.type === "hello" || message.type === "hello_error") {
+            this.#failAndClose(new ProtocolValidationError("Unexpected handshake message"));
+            return;
+        }
+        this.#options.onMessage(message);
+    }
+    #handleClose() {
+        const lifecycle = this.#lifecycle;
+        if (lifecycle.state === "disconnected")
+            return;
+        let error = new DiffexDisconnectedError("Byte transport closed");
+        try {
+            lifecycle.decoder.end();
+        }
+        catch (decoderError) {
+            error = toError(decoderError);
+        }
+        this.#fail(error);
+    }
+    #failAndClose(error) {
+        const lifecycle = this.#lifecycle;
+        const transport = lifecycle.state === "disconnected" ? undefined : lifecycle.transport;
+        this.#fail(error);
+        transport?.close();
+    }
+    #fail(error) {
+        const lifecycle = this.#lifecycle;
+        if (lifecycle.state === "disconnected")
+            return;
+        this.#lifecycle = { state: "disconnected" };
+        lifecycle.handshake?.reject(error);
+        this.#options.onStateChange({ state: "disconnected", error });
+    }
+    #isCurrent(id) {
+        return this.#lifecycle.state !== "disconnected" && this.#lifecycle.id === id;
+    }
+}

package/dist/errors.d.ts

@@ -0,0 +1,22 @@
+import type { JsonValue, ProtocolError, ProtocolErrorCode } from "@diffexai/diffex-protocol";
+export declare class DiffexServerError extends Error {
+    readonly code: ProtocolErrorCode;
+    readonly details: JsonValue | undefined;
+    constructor(error: ProtocolError);
+}
+export declare class DiffexDisconnectedError extends Error {
+    constructor(message?: string);
+}
+export declare class DiffexClientDisposedError extends Error {
+    constructor();
+}
+export declare class DiffexSessionOwnershipError extends Error {
+    readonly sessionId: string;
+    constructor(sessionId: string, message: string);
+}
+export declare class DiffexSessionDetachedError extends Error {
+    readonly sessionId: string;
+    constructor(sessionId: string);
+}
+export declare function toError(error: unknown): Error;
+export declare function toDisconnectedError(error: unknown): DiffexDisconnectedError;

package/dist/errors.js

@@ -0,0 +1,45 @@
+export class DiffexServerError extends Error {
+    code;
+    details;
+    constructor(error) {
+        super(error.message);
+        this.name = "DiffexServerError";
+        this.code = error.code;
+        this.details = error.details;
+    }
+}
+export class DiffexDisconnectedError extends Error {
+    constructor(message = "Diffex client is disconnected") {
+        super(message);
+        this.name = "DiffexDisconnectedError";
+    }
+}
+export class DiffexClientDisposedError extends Error {
+    constructor() {
+        super("Diffex client is disposed");
+        this.name = "DiffexClientDisposedError";
+    }
+}
+export class DiffexSessionOwnershipError extends Error {
+    sessionId;
+    constructor(sessionId, message) {
+        super(message);
+        this.name = "DiffexSessionOwnershipError";
+        this.sessionId = sessionId;
+    }
+}
+export class DiffexSessionDetachedError extends Error {
+    sessionId;
+    constructor(sessionId) {
+        super(`Session ${sessionId} is not attached`);
+        this.name = "DiffexSessionDetachedError";
+        this.sessionId = sessionId;
+    }
+}
+export function toError(error) {
+    return error instanceof Error ? error : new Error(String(error));
+}
+export function toDisconnectedError(error) {
+    const cause = toError(error);
+    return cause instanceof DiffexDisconnectedError ? cause : new DiffexDisconnectedError(cause.message);
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { DiffexClient } from "./client.ts";
+export { DiffexClientDisposedError, DiffexDisconnectedError, DiffexServerError, DiffexSessionDetachedError, DiffexSessionOwnershipError, } from "./errors.ts";
+export type { AcquireSessionOptions, DiffexSessionHandle, SessionLease, SessionLeaseMode } from "./session-handle.ts";
+export type { ByteTransport, ByteTransportFactory, ByteTransportHandlers } from "./transport.ts";
+export type { ConnectionState, ConnectionStateChange, CreateSessionOptions, DiffexClientOptions, ListenerErrorHandler, Unsubscribe, } from "./types.ts";

package/dist/index.js

@@ -0,0 +1,2 @@
+export { DiffexClient } from "./client.js";
+export { DiffexClientDisposedError, DiffexDisconnectedError, DiffexServerError, DiffexSessionDetachedError, DiffexSessionOwnershipError, } from "./errors.js";

package/dist/promise.d.ts

@@ -0,0 +1,7 @@
+export interface PromiseResolvers<T> {
+    promise: Promise<T>;
+    resolve(value: T | PromiseLike<T>): void;
+    reject(reason?: unknown): void;
+}
+/** Remove in favor of `Promise.withResolvers()` when the repository's TypeScript lib baseline moves to ES2024. */
+export declare function createPromiseResolvers<T>(): PromiseResolvers<T>;

package/dist/promise.js

@@ -0,0 +1,10 @@
+/** Remove in favor of `Promise.withResolvers()` when the repository's TypeScript lib baseline moves to ES2024. */
+export function createPromiseResolvers() {
+    let resolve;
+    let reject;
+    const promise = new Promise((resolvePromise, rejectPromise) => {
+        resolve = resolvePromise;
+        reject = rejectPromise;
+    });
+    return { promise, resolve, reject };
+}

package/dist/session-handle.d.ts

@@ -0,0 +1,53 @@
+import type { Command, ModelRef, ResultForCommand, ServerEvent, SessionSnapshot, ThinkingLevel } from "@diffexai/diffex-protocol";
+import type { Unsubscribe } from "./types.ts";
+type SessionCommand = Extract<Command, {
+    sessionId: string;
+}>;
+export type SessionLeaseMode = "shared" | "exclusive";
+export interface AcquireSessionOptions {
+    mode: SessionLeaseMode;
+}
+export interface SessionLease extends AsyncDisposable {
+    readonly id: string;
+    readonly active: boolean;
+    readonly attached: boolean;
+    readonly snapshot: SessionSnapshot | undefined;
+    subscribe(listener: (snapshot: SessionSnapshot) => void): Unsubscribe;
+    onEvent(listener: (event: ServerEvent) => void): Unsubscribe;
+    detach(): Promise<void>;
+    dispose(): Promise<void>;
+    prompt(text: string): Promise<SessionSnapshot>;
+    steer(text: string): Promise<SessionSnapshot>;
+    abort(): Promise<SessionSnapshot>;
+    setModel(model: ModelRef): Promise<SessionSnapshot>;
+    setThinking(thinkingLevel: ThinkingLevel): Promise<SessionSnapshot>;
+}
+export type DiffexSessionHandle = SessionLease;
+export interface SessionHandleCallbacks {
+    isAttached(): boolean;
+    getSnapshot(): SessionSnapshot | undefined;
+    subscribe(listener: (snapshot: SessionSnapshot) => void): Unsubscribe;
+    onEvent(listener: (event: ServerEvent) => void): Unsubscribe;
+    detach(): Promise<void>;
+    dispose(): Promise<void>;
+    request<const TCommand extends SessionCommand>(command: TCommand): Promise<ResultForCommand<TCommand>>;
+}
+export declare class SessionHandle implements SessionLease {
+    #private;
+    readonly id: string;
+    constructor(id: string, callbacks: SessionHandleCallbacks);
+    get attached(): boolean;
+    get active(): boolean;
+    get snapshot(): SessionSnapshot | undefined;
+    subscribe(listener: (snapshot: SessionSnapshot) => void): Unsubscribe;
+    onEvent(listener: (event: ServerEvent) => void): Unsubscribe;
+    detach(): Promise<void>;
+    dispose(): Promise<void>;
+    [Symbol.asyncDispose](): Promise<void>;
+    prompt(text: string): Promise<SessionSnapshot>;
+    steer(text: string): Promise<SessionSnapshot>;
+    abort(): Promise<SessionSnapshot>;
+    setModel(model: ModelRef): Promise<SessionSnapshot>;
+    setThinking(thinkingLevel: ThinkingLevel): Promise<SessionSnapshot>;
+}
+export {};

package/dist/session-handle.js

@@ -0,0 +1,50 @@
+export class SessionHandle {
+    id;
+    #callbacks;
+    constructor(id, callbacks) {
+        this.id = id;
+        this.#callbacks = callbacks;
+    }
+    get attached() {
+        return this.#callbacks.isAttached();
+    }
+    get active() {
+        return this.attached;
+    }
+    get snapshot() {
+        return this.#callbacks.getSnapshot();
+    }
+    subscribe(listener) {
+        return this.#callbacks.subscribe(listener);
+    }
+    onEvent(listener) {
+        return this.#callbacks.onEvent(listener);
+    }
+    async detach() {
+        await this.#callbacks.detach();
+    }
+    dispose() {
+        return this.#callbacks.dispose();
+    }
+    [Symbol.asyncDispose]() {
+        return this.dispose();
+    }
+    async prompt(text) {
+        return (await this.#request({ command: "prompt", sessionId: this.id, text })).session;
+    }
+    async steer(text) {
+        return (await this.#request({ command: "steer", sessionId: this.id, text })).session;
+    }
+    async abort() {
+        return (await this.#request({ command: "abort", sessionId: this.id })).session;
+    }
+    async setModel(model) {
+        return (await this.#request({ command: "set_model", sessionId: this.id, model })).session;
+    }
+    async setThinking(thinkingLevel) {
+        return (await this.#request({ command: "set_thinking", sessionId: this.id, thinkingLevel })).session;
+    }
+    #request(command) {
+        return this.#callbacks.request(command);
+    }
+}

package/dist/state.d.ts

@@ -0,0 +1,21 @@
+import type { CommandResult, ServerEvent, ServerSnapshot, SessionSnapshot } from "@diffexai/diffex-protocol";
+import type { ListenerErrorHandler, Unsubscribe } from "./types.ts";
+export declare class ClientState {
+    #private;
+    constructor(onListenerError?: ListenerErrorHandler);
+    get snapshot(): ServerSnapshot | undefined;
+    reset(): void;
+    clearAttachments(): void;
+    dispose(): void;
+    getSessionSnapshot(sessionId: string): SessionSnapshot | undefined;
+    isSessionAttached(sessionId: string): boolean;
+    forgetSessionSnapshot(sessionId: string): SessionSnapshot | undefined;
+    restoreSessionSnapshot(snapshot: SessionSnapshot): void;
+    subscribe(listener: (snapshot: ServerSnapshot) => void): Unsubscribe;
+    onEvent(listener: (event: ServerEvent) => void): Unsubscribe;
+    subscribeSession(sessionId: string, listener: (snapshot: SessionSnapshot) => void): Unsubscribe;
+    onSessionEvent(sessionId: string, listener: (event: ServerEvent) => void): Unsubscribe;
+    applyResult(result: CommandResult): void;
+    applyEvent(event: ServerEvent): void;
+    applyServerSnapshot(snapshot: ServerSnapshot): void;
+}

package/dist/state.js

@@ -0,0 +1,144 @@
+import { toError } from "./errors.js";
+export class ClientState {
+    #sessionSnapshots = new Map();
+    #attachedSessionIds = new Set();
+    #snapshotListeners = new Set();
+    #eventListeners = new Set();
+    #sessionSnapshotListeners = new Map();
+    #sessionEventListeners = new Map();
+    #onListenerError;
+    #snapshot;
+    constructor(onListenerError) {
+        this.#onListenerError = onListenerError;
+    }
+    get snapshot() {
+        return this.#snapshot;
+    }
+    reset() {
+        this.#snapshot = undefined;
+        this.#sessionSnapshots.clear();
+        this.#attachedSessionIds.clear();
+    }
+    clearAttachments() {
+        this.#attachedSessionIds.clear();
+    }
+    dispose() {
+        this.reset();
+        this.#snapshotListeners.clear();
+        this.#eventListeners.clear();
+        this.#sessionSnapshotListeners.clear();
+        this.#sessionEventListeners.clear();
+    }
+    getSessionSnapshot(sessionId) {
+        return this.#sessionSnapshots.get(sessionId);
+    }
+    isSessionAttached(sessionId) {
+        return this.#attachedSessionIds.has(sessionId);
+    }
+    forgetSessionSnapshot(sessionId) {
+        const previous = this.#sessionSnapshots.get(sessionId);
+        this.#sessionSnapshots.delete(sessionId);
+        return previous;
+    }
+    restoreSessionSnapshot(snapshot) {
+        if (!this.#sessionSnapshots.has(snapshot.id))
+            this.#sessionSnapshots.set(snapshot.id, snapshot);
+    }
+    subscribe(listener) {
+        this.#snapshotListeners.add(listener);
+        return () => this.#snapshotListeners.delete(listener);
+    }
+    onEvent(listener) {
+        this.#eventListeners.add(listener);
+        return () => this.#eventListeners.delete(listener);
+    }
+    subscribeSession(sessionId, listener) {
+        return addMappedListener(this.#sessionSnapshotListeners, sessionId, listener);
+    }
+    onSessionEvent(sessionId, listener) {
+        return addMappedListener(this.#sessionEventListeners, sessionId, listener);
+    }
+    applyResult(result) {
+        if (result.command === "list")
+            return;
+        if (result.command === "detach") {
+            this.#attachedSessionIds.delete(result.sessionId);
+            const snapshot = this.#sessionSnapshots.get(result.sessionId);
+            if (snapshot)
+                this.#applySessionSnapshot({ ...snapshot, attached: false }, true);
+            return;
+        }
+        this.#applySessionSnapshot(result.session);
+    }
+    applyEvent(event) {
+        if (event.type === "server_snapshot")
+            this.applyServerSnapshot(event.snapshot);
+        if (event.type === "session_snapshot")
+            this.#applySessionSnapshot(event.snapshot);
+        if (event.type === "session_removed") {
+            this.#sessionSnapshots.delete(event.sessionId);
+            this.#attachedSessionIds.delete(event.sessionId);
+        }
+        this.#notify(this.#eventListeners, event);
+        const sessionId = getEventSessionId(event);
+        if (sessionId)
+            this.#notify(this.#sessionEventListeners.get(sessionId), event);
+    }
+    applyServerSnapshot(snapshot) {
+        if (this.#snapshot && snapshot.revision < this.#snapshot.revision)
+            return;
+        this.#snapshot = snapshot;
+        this.#notify(this.#snapshotListeners, snapshot);
+    }
+    #applySessionSnapshot(snapshot, force = false) {
+        const current = this.#sessionSnapshots.get(snapshot.id);
+        if (!force && current && snapshot.revision < current.revision)
+            return;
+        this.#sessionSnapshots.set(snapshot.id, snapshot);
+        if (snapshot.attached)
+            this.#attachedSessionIds.add(snapshot.id);
+        else
+            this.#attachedSessionIds.delete(snapshot.id);
+        this.#notify(this.#sessionSnapshotListeners.get(snapshot.id), snapshot);
+    }
+    #notify(listeners, value) {
+        for (const listener of listeners ?? []) {
+            try {
+                listener(value);
+            }
+            catch (error) {
+                this.#reportListenerError(error);
+            }
+        }
+    }
+    #reportListenerError(error) {
+        if (!this.#onListenerError)
+            return;
+        try {
+            this.#onListenerError(toError(error));
+        }
+        catch {
+            // Diagnostics cannot affect client state.
+        }
+    }
+}
+function addMappedListener(listenersById, id, listener) {
+    let listeners = listenersById.get(id);
+    if (!listeners) {
+        listeners = new Set();
+        listenersById.set(id, listeners);
+    }
+    listeners.add(listener);
+    return () => {
+        listeners.delete(listener);
+        if (listeners.size === 0)
+            listenersById.delete(id);
+    };
+}
+function getEventSessionId(event) {
+    if (event.type === "session_snapshot")
+        return event.snapshot.id;
+    if (event.type === "session_progress" || event.type === "session_removed")
+        return event.sessionId;
+    return undefined;
+}

package/dist/transport.d.ts

@@ -0,0 +1,16 @@
+export interface ByteTransport {
+    /** Sends one byte chunk. Calls must be delivered in invocation order. */
+    send(chunk: Uint8Array): Promise<void>;
+    /** Closes the transport. Implementations must make repeated calls harmless. */
+    close(): void;
+}
+export interface ByteTransportHandlers {
+    /** Delivers an arbitrary inbound byte chunk. */
+    onData(chunk: Uint8Array): void;
+    /** Reports an orderly terminal close. */
+    onClose(): void;
+    /** Reports a terminal transport failure. */
+    onError(error: Error): void;
+}
+/** Creates a fresh connected, authenticated transport. Exactly one terminal handler is expected. */
+export type ByteTransportFactory = (handlers: ByteTransportHandlers) => ByteTransport | Promise<ByteTransport>;

package/dist/transport.js

@@ -0,0 +1 @@
+export {};

package/dist/types.d.ts

@@ -0,0 +1,21 @@
+import type { ModelRef, ThinkingLevel } from "@diffexai/diffex-protocol";
+import type { ByteTransportFactory } from "./transport.ts";
+export type ConnectionState = "disconnected" | "connecting" | "connected";
+export interface ConnectionStateChange {
+    state: ConnectionState;
+    error?: Error;
+}
+export type Unsubscribe = () => void;
+export type ListenerErrorHandler = (error: Error) => void;
+export interface DiffexClientOptions {
+    transportFactory: ByteTransportFactory;
+    maxFrameLength?: number;
+    /** Reports subscriber failures without allowing them to corrupt client state. */
+    onListenerError?: ListenerErrorHandler;
+}
+export interface CreateSessionOptions {
+    cwd?: string;
+    name?: string;
+    model?: ModelRef;
+    thinkingLevel?: ThinkingLevel;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/unix.d.ts

@@ -0,0 +1,7 @@
+import type { ByteTransportFactory } from "./transport.ts";
+export interface UnixTransportOptions {
+    path: string;
+    maxPendingBytes?: number;
+}
+/** Creates fresh Unix-domain socket transports for DiffexClient connection attempts in Node-compatible runtimes. */
+export declare function createUnixTransportFactory(options: UnixTransportOptions): ByteTransportFactory;