@dungle-scrubs/tether-client 0.1.1

package/dist/session-event-stream-client.js

@@ -0,0 +1,333 @@
+import { Effect, Either } from "effect";
+import WebSocket from "ws";
+import { resolveServiceAuthToken } from "./auth-token.js";
+import { sleepUnrefEffect } from "./effect-timing.js";
+import { ModuleObservability, readModuleObservabilityOptions } from "./observability.js";
+import { parseWebSocketServerEnvelope, webSocketOperation } from "./protocol.js";
+const defaultReconnectBaseDelayMs = 100;
+const defaultReconnectMaxDelayMs = 2_000;
+/**
+ * Observer-only stream client for replaying and following durable session
+ * events. Use this for passive readers such as bridges, approval observers, and
+ * dashboards; use `ParticipantRuntimeClient` when the caller must publish
+ * participant events, claim tasks, refresh claims, or complete task work.
+ */
+export class SessionEventStreamClient {
+    config;
+    deliveryQueue = [];
+    eventHandlers = new Set();
+    errorBacklog = [];
+    errorHandlers = new Set();
+    observability = new ModuleObservability(readModuleObservabilityOptions("SessionEventStreamClient"));
+    closePromise = Promise.resolve();
+    connectCount = 0;
+    draining = false;
+    eventCount = 0;
+    /** Highest sequence whose handlers have all resolved; the durable resume cursor. */
+    lastObservedSeq;
+    reconnectFailureCount = 0;
+    reconnectSuccessCount = 0;
+    replayComplete = Promise.resolve();
+    replayCompleteCount = 0;
+    replayCompleteSettled = true;
+    rejectReplayComplete = null;
+    resolveReplayComplete = null;
+    socket = null;
+    stopped = false;
+    webSocketFactory;
+    /** Creates an observer around the supplied stream configuration. */
+    constructor(config) {
+        this.config = config;
+        this.lastObservedSeq = config.afterSeq;
+        this.webSocketFactory = config.webSocketFactory ?? ((url) => new WebSocket(url));
+    }
+    /** Opens a passive observer stream without participant task authority. */
+    static async connect(config) {
+        const client = new SessionEventStreamClient(config);
+        await client.open(config.afterSeq);
+        return client;
+    }
+    /** Requests a graceful WebSocket close and stops reconnect attempts. */
+    close() {
+        this.stopped = true;
+        this.socket?.close();
+    }
+    /** Returns stream cursor, connection, handler, and replay diagnostics. */
+    debugInfo() {
+        return {
+            connectCount: this.connectCount,
+            eventCount: this.eventCount,
+            eventHandlerCount: this.eventHandlers.size,
+            lastObservedSeq: this.lastObservedSeq,
+            reconnectFailureCount: this.reconnectFailureCount,
+            reconnectSuccessCount: this.reconnectSuccessCount,
+            replayCompleteCount: this.replayCompleteCount,
+            socketReadyState: this.socket?.readyState ?? WebSocket.CLOSED,
+            stopped: this.stopped,
+        };
+    }
+    /** Registers an error callback and returns an unsubscribe function. */
+    onError(handler) {
+        this.errorHandlers.add(handler);
+        for (const error of this.errorBacklog.splice(0)) {
+            handler(error);
+        }
+        return () => {
+            this.errorHandlers.delete(handler);
+        };
+    }
+    /** Registers an event callback and resumes serial delivery of any backlog. */
+    onEvent(handler) {
+        this.eventHandlers.add(handler);
+        void this.drainDeliveryQueue();
+        return () => {
+            this.eventHandlers.delete(handler);
+        };
+    }
+    /** Reopens the stream from the highest observed event sequence. */
+    async reconnect() {
+        this.socket?.close();
+        await this.waitForClose().catch(() => undefined);
+        await this.reconnectWithBackoff(0);
+        return this;
+    }
+    /** Resolves when the current socket closes. */
+    async waitForClose() {
+        await this.closePromise;
+    }
+    /** Resolves once the current stream replay has completed. */
+    async waitForReplayComplete() {
+        await this.replayComplete;
+    }
+    /** Opens a WebSocket stream from the requested event cursor. */
+    async open(afterSeq) {
+        await this.observability.traceBoundary("open", { afterSeq, sessionId: this.config.sessionId }, async () => {
+            // Each connect resumes from lastObservedSeq, so the server replays every
+            // event after it. Discard any un-acknowledged items queued from a prior
+            // socket to avoid delivering them twice once replay re-sends them.
+            this.deliveryQueue.length = 0;
+            this.replayCompleteSettled = false;
+            const replayComplete = new Promise((resolve, reject) => {
+                this.rejectReplayComplete = reject;
+                this.resolveReplayComplete = resolve;
+            });
+            replayComplete.catch(() => undefined);
+            this.replayComplete = replayComplete;
+            const socket = this.webSocketFactory(buildSessionEventStreamUrl({
+                ...this.config,
+                afterSeq,
+            }));
+            this.socket = socket;
+            this.connectCount += 1;
+            this.closePromise = new Promise((resolve) => {
+                socket.once("close", () => {
+                    if (this.socket === socket) {
+                        this.socket = null;
+                    }
+                    this.settleReplayCompleteError(new Error("WebSocket closed before replay completed"));
+                    resolve();
+                });
+            });
+            socket.on("error", (error) => {
+                this.settleReplayCompleteError(error);
+                this.emitError(error);
+            });
+            socket.on("message", (data) => {
+                this.handleMessage(data);
+            });
+            await new Promise((resolve, reject) => {
+                socket.once("open", resolve);
+                socket.once("error", reject);
+            });
+        });
+    }
+    /** Reopens the stream with bounded retry backoff. */
+    async reconnectWithBackoff(initialDelayMs = null) {
+        await Effect.runPromise(this.buildReconnectWithBackoff(initialDelayMs));
+    }
+    /** Builds the bounded reconnect loop as an Effect program. */
+    buildReconnectWithBackoff(initialDelayMs = null) {
+        return Effect.gen(this, function* () {
+            let attempt = 0;
+            let delayMs = initialDelayMs ?? observerReconnectDelayMs(attempt, this.config);
+            while (!this.stopped) {
+                if (delayMs > 0) {
+                    yield* sleepUnrefEffect(delayMs);
+                }
+                const opened = yield* Effect.either(Effect.tryPromise({
+                    catch: (error) => error,
+                    try: () => this.open(this.lastObservedSeq),
+                }));
+                if (Either.isRight(opened)) {
+                    this.reconnectSuccessCount += 1;
+                    return;
+                }
+                const error = opened.left;
+                this.reconnectFailureCount += 1;
+                this.emitError(error instanceof Error ? error : new Error("Observer reconnect failed"));
+                attempt += 1;
+                delayMs = observerReconnectDelayMs(attempt, this.config);
+            }
+        });
+    }
+    /** Parses one server envelope and enqueues it for serial, in-order delivery. */
+    handleMessage(data) {
+        try {
+            const envelope = parseWebSocketServerEnvelope(JSON.parse(String(data)));
+            if (!envelope) {
+                this.emitError(new Error("Unsupported WebSocket envelope"));
+                return;
+            }
+            if (envelope.op === webSocketOperation.event) {
+                this.eventCount += 1;
+                this.deliveryQueue.push({ event: envelope.event, kind: "event" });
+                void this.drainDeliveryQueue();
+                return;
+            }
+            if (envelope.op === webSocketOperation.replayComplete) {
+                this.replayCompleteCount += 1;
+                this.deliveryQueue.push({ kind: "replay-complete" });
+                void this.drainDeliveryQueue();
+                return;
+            }
+            if (envelope.op === webSocketOperation.error) {
+                const error = new Error(envelope.error);
+                this.settleReplayCompleteError(error);
+                this.emitError(error);
+            }
+        }
+        catch (error) {
+            this.emitError(error instanceof Error ? error : new Error("Failed to handle WebSocket message"));
+        }
+    }
+    /**
+     * Drains queued events through registered handlers strictly one at a time and
+     * in sequence order. A single drain runs at a time, so handlers never overlap
+     * and later events wait behind in-flight delivery. The resume cursor advances
+     * only after an event's handlers all resolve, and a rejection halts delivery
+     * without acknowledging the failed event so the stream reconnects and replays
+     * from the last successfully handled position instead of skipping past it.
+     */
+    async drainDeliveryQueue() {
+        if (this.draining) {
+            return;
+        }
+        this.draining = true;
+        try {
+            while (!this.stopped && this.deliveryQueue.length > 0) {
+                const next = this.deliveryQueue[0];
+                if (!next) {
+                    break;
+                }
+                if (next.kind === "replay-complete") {
+                    this.deliveryQueue.shift();
+                    this.settleReplayComplete();
+                    continue;
+                }
+                if (this.eventHandlers.size === 0) {
+                    // Preserve the backlog until a handler registers and resumes delivery.
+                    break;
+                }
+                // Take ownership before awaiting so a concurrent reconnect that clears
+                // the queue cannot re-deliver the event now in flight.
+                this.deliveryQueue.shift();
+                const delivered = await this.deliverEventToHandlers(next.event);
+                if (!delivered) {
+                    this.recoverFromDeliveryFailure();
+                    return;
+                }
+                this.lastObservedSeq = Math.max(this.lastObservedSeq, next.event.seq);
+            }
+        }
+        finally {
+            this.draining = false;
+        }
+    }
+    /** Awaits every registered handler in turn; returns false on the first rejection. */
+    async deliverEventToHandlers(event) {
+        for (const handler of [...this.eventHandlers]) {
+            try {
+                await handler(event);
+            }
+            catch (error) {
+                this.emitError(error instanceof Error ? error : new Error("Session event handler failed"));
+                return false;
+            }
+        }
+        return true;
+    }
+    /**
+     * Recovers after a handler rejection by discarding un-acknowledged events and
+     * reconnecting from the last successfully handled sequence, so the server
+     * replays the failed event rather than the stream advancing past it.
+     */
+    recoverFromDeliveryFailure() {
+        if (this.stopped) {
+            return;
+        }
+        this.deliveryQueue.length = 0;
+        const socket = this.socket;
+        this.socket = null;
+        socket?.close();
+        void this.reconnectWithBackoff();
+    }
+    /** Routes operational failures to registered error handlers. */
+    emitError(error) {
+        if (this.errorHandlers.size === 0) {
+            this.errorBacklog.push(error);
+            return;
+        }
+        for (const handler of this.errorHandlers) {
+            handler(error);
+        }
+    }
+    /** Resolves the current replay wait once. */
+    settleReplayComplete() {
+        if (this.replayCompleteSettled) {
+            return;
+        }
+        this.replayCompleteSettled = true;
+        this.resolveReplayComplete?.();
+        this.resolveReplayComplete = null;
+        this.rejectReplayComplete = null;
+    }
+    /** Rejects the current replay wait once when the stream fails before replay completion. */
+    settleReplayCompleteError(error) {
+        if (this.replayCompleteSettled) {
+            return;
+        }
+        this.replayCompleteSettled = true;
+        this.rejectReplayComplete?.(error);
+        this.resolveReplayComplete = null;
+        this.rejectReplayComplete = null;
+    }
+}
+/**
+ * Runtime-kind value that selects the server's passive full-event observer
+ * mode: the connection receives the durable event stream (replay + live) but
+ * does not register a durable participant or acquire a control lease. Keep this
+ * in sync with `classifyHostPresenceStream` in the Tether gateway.
+ */
+export const sessionEventObserverRuntimeKind = "observer";
+/** Builds the observer WebSocket URL without participant or task authority. */
+export function buildSessionEventStreamUrl(config) {
+    const url = new URL(`/sessions/${encodeURIComponent(config.sessionId)}/stream`, config.serviceUrl);
+    url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
+    url.searchParams.set("after", String(config.afterSeq));
+    // Opt into the passive full-event observer mode so the server delivers the
+    // durable event stream without treating this connection as a control
+    // participant. A passive reader never acquires a control lease, so its
+    // reconnects cannot collide with the runtime's own control channel.
+    url.searchParams.set("runtimeKind", sessionEventObserverRuntimeKind);
+    const authToken = resolveServiceAuthToken(config.authToken);
+    if (authToken) {
+        url.searchParams.set("access_token", authToken);
+    }
+    return url.toString();
+}
+/** Computes bounded exponential reconnect backoff from observer configuration. */
+function observerReconnectDelayMs(attempt, config) {
+    const baseDelayMs = config.reconnect?.baseDelayMs ?? defaultReconnectBaseDelayMs;
+    const maxDelayMs = config.reconnect?.maxDelayMs ?? defaultReconnectMaxDelayMs;
+    return Math.min(maxDelayMs, baseDelayMs * 2 ** attempt);
+}

package/dist/task-cancellation-registry.d.ts

@@ -0,0 +1,48 @@
+import type { SessionEvent } from "./types.js";
+/** Constructor settings for task cancellation memory. */
+export interface TaskCancellationRegistryOptions {
+    /** Maximum inactive cancelled task ids to remember. */
+    readonly maxCancelledTaskIds?: number;
+}
+/** Inspectable cancellation registry state for runtime diagnostics. */
+export interface TaskCancellationRegistryDebugInfo {
+    /** Number of active task abort controllers. */
+    readonly activeTaskCount: number;
+    /** Number of active and inactive cancelled task ids currently remembered. */
+    readonly cancelledTaskIdCount: number;
+    /** Number of inactive cancelled task ids currently remembered. */
+    readonly inactiveCancelledTaskIdCount: number;
+    /** Maximum inactive cancelled task ids retained by this registry. */
+    readonly maxCancelledTaskIds: number;
+}
+/** Tracks cancellation events and exposes abort signals for active task work. */
+export declare class TaskCancellationRegistry {
+    private readonly maxCancelledTaskIds;
+    private readonly cancelledTaskIds;
+    private readonly controllersByTaskId;
+    /** Creates a cancellation registry with bounded inactive cancellation memory. */
+    constructor(options?: TaskCancellationRegistryOptions);
+    /** Aborts in-flight work for a task without marking it cancelled. */
+    abortActive(taskId: string): void;
+    /** Starts an abortable active-work scope for a task. */
+    begin(taskId: string): AbortSignal;
+    /** Marks a task as cancelled and aborts in-flight work for it. */
+    cancel(taskId: string): void;
+    /**
+     * Ends active-work tracking for a task and drops its cancellation memory.
+     *
+     * Task ids are unique and terminal tasks never become claimable again, so it
+     * is safe to forget a cancelled id once no executor is tracking it. This
+     * keeps long-lived participant runtimes from accumulating cancelled ids
+     * indefinitely.
+     */
+    end(taskId: string): void;
+    /** Checks whether a task has been cancelled in the observed event stream. */
+    isCancelled(taskId: string): boolean;
+    /** Observes one session event and records task cancellation when present. */
+    observe(event: SessionEvent): string | null;
+    /** Returns bounded cancellation-memory counters for diagnostics. */
+    debugInfo(): TaskCancellationRegistryDebugInfo;
+    private rememberCancellation;
+    private inactiveCancelledTaskIdCount;
+}

package/dist/task-cancellation-registry.js

@@ -0,0 +1,95 @@
+import { taskIdFromCancelledEvent } from "./protocol.js";
+const defaultMaxCancelledTaskIds = 1024;
+/** Tracks cancellation events and exposes abort signals for active task work. */
+export class TaskCancellationRegistry {
+    maxCancelledTaskIds;
+    cancelledTaskIds = new Set();
+    controllersByTaskId = new Map();
+    /** Creates a cancellation registry with bounded inactive cancellation memory. */
+    constructor(options = {}) {
+        this.maxCancelledTaskIds = Math.max(0, options.maxCancelledTaskIds ?? defaultMaxCancelledTaskIds);
+    }
+    /** Aborts in-flight work for a task without marking it cancelled. */
+    abortActive(taskId) {
+        this.controllersByTaskId.get(taskId)?.abort();
+    }
+    /** Starts an abortable active-work scope for a task. */
+    begin(taskId) {
+        const controller = new AbortController();
+        this.controllersByTaskId.set(taskId, controller);
+        if (this.cancelledTaskIds.has(taskId)) {
+            controller.abort();
+        }
+        return controller.signal;
+    }
+    /** Marks a task as cancelled and aborts in-flight work for it. */
+    cancel(taskId) {
+        const controller = this.controllersByTaskId.get(taskId);
+        controller?.abort();
+        this.rememberCancellation(taskId);
+    }
+    /**
+     * Ends active-work tracking for a task and drops its cancellation memory.
+     *
+     * Task ids are unique and terminal tasks never become claimable again, so it
+     * is safe to forget a cancelled id once no executor is tracking it. This
+     * keeps long-lived participant runtimes from accumulating cancelled ids
+     * indefinitely.
+     */
+    end(taskId) {
+        this.controllersByTaskId.delete(taskId);
+        this.cancelledTaskIds.delete(taskId);
+    }
+    /** Checks whether a task has been cancelled in the observed event stream. */
+    isCancelled(taskId) {
+        return this.cancelledTaskIds.has(taskId);
+    }
+    /** Observes one session event and records task cancellation when present. */
+    observe(event) {
+        const taskId = taskIdFromCancelledEvent(event);
+        if (taskId) {
+            this.cancel(taskId);
+        }
+        return taskId;
+    }
+    /** Returns bounded cancellation-memory counters for diagnostics. */
+    debugInfo() {
+        return {
+            activeTaskCount: this.controllersByTaskId.size,
+            cancelledTaskIdCount: this.cancelledTaskIds.size,
+            inactiveCancelledTaskIdCount: this.inactiveCancelledTaskIdCount(),
+            maxCancelledTaskIds: this.maxCancelledTaskIds,
+        };
+    }
+    rememberCancellation(taskId) {
+        if (this.maxCancelledTaskIds === 0) {
+            if (this.controllersByTaskId.has(taskId)) {
+                this.cancelledTaskIds.add(taskId);
+            }
+            return;
+        }
+        this.cancelledTaskIds.delete(taskId);
+        this.cancelledTaskIds.add(taskId);
+        while (this.inactiveCancelledTaskIdCount() > this.maxCancelledTaskIds) {
+            const oldestTaskId = this.cancelledTaskIds.values().next().value;
+            if (typeof oldestTaskId !== "string") {
+                return;
+            }
+            if (this.controllersByTaskId.has(oldestTaskId)) {
+                this.cancelledTaskIds.delete(oldestTaskId);
+                this.cancelledTaskIds.add(oldestTaskId);
+                continue;
+            }
+            this.cancelledTaskIds.delete(oldestTaskId);
+        }
+    }
+    inactiveCancelledTaskIdCount() {
+        let count = 0;
+        for (const taskId of this.cancelledTaskIds) {
+            if (!this.controllersByTaskId.has(taskId)) {
+                count += 1;
+            }
+        }
+        return count;
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,8 @@
+export type { ClientSessionBindingRecord, ControlChannel, ControlLeaseSnapshot, ControlLeaseStatus, ParticipantRecord, ParticipantRuntimeKind, ParticipantRuntimeSnapshot, ParticipantRuntimeSnapshotStatus, SessionDebugControlLeaseSummary, SessionDebugParticipantSummary, SessionDebugSummary, SessionDebugTaskSummary, SessionEvent, SessionEventType, SessionRecord, TaskListStatus, TaskRecord, TaskSnapshot, TaskSnapshotStatus, } from "@dungle-scrubs/tether-protocol";
+export type Result<TValue, TError extends Error = Error> = {
+    readonly ok: true;
+    readonly value: TValue;
+} | {
+    readonly ok: false;
+    readonly error: TError;
+};

package/dist/types.js

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

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@dungle-scrubs/tether-client",
+  "version": "0.1.1",
+  "description": "Participant runtime client for Tether REST and WebSocket integration.",
+  "license": "MIT",
+  "author": "Kevin Frilot",
+  "homepage": "https://github.com/dungle-scrubs/tether/tree/main/packages/client#readme",
+  "bugs": "https://github.com/dungle-scrubs/tether/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dungle-scrubs/tether.git",
+    "directory": "packages/client"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./observability": {
+      "import": "./dist/observability.js",
+      "types": "./dist/observability.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@opentelemetry/api": "^1.9.1",
+    "effect": "^3.21.2",
+    "ws": "^8.20.1",
+    "zod": "^4.4.3",
+    "@dungle-scrubs/tether-protocol": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.1",
+    "@types/ws": "^8.18.1",
+    "esbuild": "0.25.12",
+    "vitest": "^4.1.7"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "format": "biome format --config-path=../../tooling/biome.json --write .",
+    "format:check": "biome format --config-path=../../tooling/biome.json .",
+    "lint": "biome lint --config-path=../../tooling/biome.json .",
+    "pack:tether": "pnpm --filter @dungle-scrubs/tether-protocol build && pnpm --filter @dungle-scrubs/tether-client build && node scripts/pack-tether-client.mjs",
+    "test": "vitest run --passWithNoTests",
+    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.test.json"
+  }
+}