@dungle-scrubs/tether-client 0.1.1

package/dist/participant-task-claim-flow.d.ts

@@ -0,0 +1,51 @@
+import { Effect } from "effect";
+import { type AppendSessionEventInput } from "./protocol.js";
+import type { TaskCancellationContext } from "./participant-claimable-task-runner.js";
+import type { ParticipantTaskExecutor } from "./participant-runtime-client.js";
+import type { SessionEvent, TaskRecord } from "./types.js";
+/** Boundary log surface needed by the participant task claim flow. */
+export interface ParticipantTaskClaimFlowLogger {
+    /** Writes a debug event for task claim flow diagnostics. */
+    readonly debug: (boundary: string, message: string, details?: Record<string, unknown>) => void;
+}
+/** Command surface needed to claim, refresh, publish, and resolve one task. */
+export interface ParticipantTaskClaimFlowClient {
+    /** Publishes one participant-originated event. */
+    readonly appendEvent: (input: AppendSessionEventInput) => Promise<void>;
+    /** Attempts to claim a task. */
+    readonly claimTask: (taskId: string) => Promise<TaskRecord | null>;
+    /** Completes a claimed task. */
+    readonly completeTask: (taskId: string, result: Record<string, unknown>) => Promise<void>;
+    /** Fails a claimed task. */
+    readonly failTask: (taskId: string, failure: Record<string, unknown>) => Promise<void>;
+    /** Refreshes a claimed task lease. */
+    readonly refreshTaskClaim: (taskId: string) => Promise<TaskRecord | null>;
+}
+/** Runtime identity and event context for one task claim flow. */
+export interface ParticipantTaskClaimFlowContext {
+    /** Concrete runtime process id that owns the task claim. */
+    readonly instanceId: string;
+    /** Latest observed event sequence. */
+    readonly lastObservedSeq: number;
+    /** Stable participant identity that owns the task claim. */
+    readonly participantId: string;
+    /** Recent session events available to the executor. */
+    readonly recentEvents: readonly SessionEvent[];
+    /** Durable session that owns the task. */
+    readonly sessionId: string;
+}
+/** Inputs for running one participant task claim flow. */
+export interface ParticipantTaskClaimFlowInput {
+    /** Cancellation state for the active task. */
+    readonly cancellation: TaskCancellationContext;
+    /** Interval used to refresh the active claim. */
+    readonly claimRefreshMs: number;
+    /** Adapter-specific executor for the claimed task. */
+    readonly executor: ParticipantTaskExecutor;
+    /** Claimable task event payload. */
+    readonly task: TaskRecord;
+}
+/** Runs claim, refresh, execution, output, and completion for one task. */
+export declare function runParticipantTaskClaimFlow(client: ParticipantTaskClaimFlowClient, context: ParticipantTaskClaimFlowContext, logger: ParticipantTaskClaimFlowLogger, input: ParticipantTaskClaimFlowInput): Promise<void>;
+/** Builds the task claim flow as an Effect program for scoped refresh cleanup. */
+export declare function buildParticipantTaskClaimFlow(client: ParticipantTaskClaimFlowClient, context: ParticipantTaskClaimFlowContext, logger: ParticipantTaskClaimFlowLogger, input: ParticipantTaskClaimFlowInput): Effect.Effect<void, unknown>;

package/dist/participant-task-claim-flow.js

@@ -0,0 +1,248 @@
+import { Effect } from "effect";
+import { buildTaskOutputEventInput, buildTaskProgressEventInput, } from "./protocol.js";
+import { sleepUnrefEffect } from "./effect-timing.js";
+const maxConsecutiveRefreshFailures = 3;
+/** Runs claim, refresh, execution, output, and completion for one task. */
+export async function runParticipantTaskClaimFlow(client, context, logger, input) {
+    await Effect.runPromise(buildParticipantTaskClaimFlow(client, context, logger, input));
+}
+/** Builds the task claim flow as an Effect program for scoped refresh cleanup. */
+export function buildParticipantTaskClaimFlow(client, context, logger, input) {
+    const shouldStop = () => isTaskStopped(input.cancellation);
+    const debugTaskStop = (message) => {
+        logger.debug("runTaskClaimFlow", message, {
+            participantId: context.participantId,
+            sessionId: context.sessionId,
+            taskId: input.task.taskId,
+        });
+    };
+    return Effect.scoped(Effect.gen(function* () {
+        const claimSetup = yield* claimAndPublishInitialProgress(client, context, logger, input);
+        if (claimSetup.type !== "claimed") {
+            if (claimSetup.type === "cancelled") {
+                debugTaskStop("task.cancelled_before_executor");
+            }
+            return;
+        }
+        yield* buildTaskClaimRefresh(client, logger, {
+            cancellation: input.cancellation,
+            claimExpiresAt: claimSetup.task.claimExpiresAt,
+            intervalMs: input.claimRefreshMs,
+            taskId: input.task.taskId,
+        }).pipe(Effect.forkScoped);
+        if (shouldStop()) {
+            debugTaskStop("task.cancelled_after_claim");
+            return;
+        }
+        const executorContext = {
+            instanceId: context.instanceId,
+            participantId: context.participantId,
+            recentEvents: context.recentEvents.filter((event) => event.seq < context.lastObservedSeq),
+            publishOutput: async (output) => {
+                if (shouldStop()) {
+                    return;
+                }
+                await client.appendEvent(buildTaskOutputEventInput({
+                    output,
+                    participantId: context.participantId,
+                    sessionId: context.sessionId,
+                    taskId: input.task.taskId,
+                }));
+            },
+            publishProgress: async () => {
+                if (shouldStop()) {
+                    return;
+                }
+                await client.appendEvent(buildTaskProgressEventInput({
+                    participantId: context.participantId,
+                    sessionId: context.sessionId,
+                    taskId: input.task.taskId,
+                }));
+            },
+            sessionId: context.sessionId,
+            signal: input.cancellation.signal,
+            task: claimSetup.task,
+        };
+        const execution = yield* runExecutor(input.executor, executorContext);
+        if (execution.type === "executor_failed") {
+            if (!shouldStop()) {
+                yield* Effect.tryPromise(() => client.failTask(input.task.taskId, {
+                    error: execution.error.message,
+                }));
+            }
+            return;
+        }
+        if (shouldStop()) {
+            debugTaskStop("task.cancelled_after_executor");
+            return;
+        }
+        if (execution.execution.output) {
+            const outputPublished = yield* Effect.tryPromise(() => executorContext.publishOutput(execution.execution.output ?? "")).pipe(Effect.match({
+                onFailure: (error) => {
+                    logCompletionTransportFailed(logger, context, input.task.taskId, error);
+                    return false;
+                },
+                onSuccess: () => true,
+            }));
+            if (!outputPublished) {
+                return;
+            }
+            if (shouldStop()) {
+                debugTaskStop("task.cancelled_after_output");
+                return;
+            }
+        }
+        yield* Effect.tryPromise(() => client.completeTask(input.task.taskId, execution.execution.result)).pipe(Effect.catchAll((error) => Effect.sync(() => {
+            logCompletionTransportFailed(logger, context, input.task.taskId, error);
+        })));
+    }));
+}
+function claimAndPublishInitialProgress(client, context, logger, input) {
+    if (isTaskStopped(input.cancellation)) {
+        return Effect.succeed({ type: "cancelled" });
+    }
+    return Effect.gen(function* () {
+        const claimOutcome = yield* Effect.tryPromise(() => client.claimTask(input.task.taskId)).pipe(Effect.match({
+            onFailure: (error) => {
+                logger.debug("runTaskClaimFlow", "task.claim_transport_unknown", {
+                    error: error instanceof Error ? error.message : "Unknown claim error",
+                    participantId: context.participantId,
+                    recovery: "lease_expiry_fallback",
+                    sessionId: context.sessionId,
+                    taskId: input.task.taskId,
+                });
+                return { type: "claim_transport_unknown" };
+            },
+            onSuccess: (task) => task ? { task, type: "claimed" } : { type: "claim_not_won" },
+        }));
+        if (claimOutcome.type === "claim_transport_unknown") {
+            return claimOutcome;
+        }
+        if (claimOutcome.type === "claim_not_won") {
+            logger.debug("runTaskClaimFlow", "task.claim_not_won", {
+                participantId: context.participantId,
+                sessionId: context.sessionId,
+                taskId: input.task.taskId,
+            });
+            return claimOutcome;
+        }
+        if (isTaskStopped(input.cancellation)) {
+            return { type: "cancelled" };
+        }
+        const progressPublished = yield* Effect.tryPromise(() => client.appendEvent(buildTaskProgressEventInput({
+            participantId: context.participantId,
+            sessionId: context.sessionId,
+            taskId: input.task.taskId,
+        }))).pipe(Effect.match({
+            onFailure: (error) => {
+                logger.debug("runTaskClaimFlow", "task.setup_failed_before_executor", {
+                    error: error instanceof Error ? error.message : "Unknown setup error",
+                    participantId: context.participantId,
+                    recovery: "lease_expiry_fallback",
+                    sessionId: context.sessionId,
+                    taskId: input.task.taskId,
+                });
+                return false;
+            },
+            onSuccess: () => true,
+        }));
+        return progressPublished ? claimOutcome : { type: "setup_failed" };
+    });
+}
+function runExecutor(executor, context) {
+    return Effect.tryPromise({
+        catch: normalizeRuntimeError,
+        try: () => executor(context),
+    }).pipe(Effect.match({
+        onFailure: (error) => ({ error, type: "executor_failed" }),
+        onSuccess: (execution) => ({ execution, type: "succeeded" }),
+    }));
+}
+function logCompletionTransportFailed(logger, context, taskId, error) {
+    logger.debug("runTaskClaimFlow", "task.completion_transport_failed", {
+        error: error instanceof Error ? error.message : "Unknown completion transport error",
+        participantId: context.participantId,
+        recovery: "lease_expiry_fallback",
+        sessionId: context.sessionId,
+        taskId,
+    });
+}
+/** Periodically refreshes a claimed task lease inside the active task scope. */
+function buildTaskClaimRefresh(client, logger, input) {
+    if (input.intervalMs <= 0) {
+        return Effect.void;
+    }
+    return Effect.gen(function* () {
+        let consecutiveFailures = 0;
+        let currentClaimExpiresAt = input.claimExpiresAt;
+        while (!isTaskStopped(input.cancellation)) {
+            yield* sleepUnrefEffect(input.intervalMs);
+            if (isTaskStopped(input.cancellation)) {
+                return;
+            }
+            const refreshOutcome = yield* Effect.tryPromise(() => client.refreshTaskClaim(input.taskId)).pipe(Effect.catchAll((error) => Effect.sync(() => {
+                consecutiveFailures += 1;
+                logger.debug("runTaskClaimFlow", "task.claim_refresh_failed", {
+                    consecutiveFailures,
+                    error: error instanceof Error ? error.message : "Unknown refresh error",
+                    taskId: input.taskId,
+                });
+                return "failed";
+            })));
+            if (refreshOutcome === "failed") {
+                if (consecutiveFailures >= maxConsecutiveRefreshFailures ||
+                    isClaimLeaseExpired(currentClaimExpiresAt)) {
+                    logger.debug("runTaskClaimFlow", "task.claim_refresh_failure_budget_exhausted", {
+                        consecutiveFailures,
+                        maxConsecutiveRefreshFailures,
+                        taskId: input.taskId,
+                    });
+                    input.cancellation.abortActive();
+                    return;
+                }
+                continue;
+            }
+            if (refreshOutcome === null) {
+                logger.debug("runTaskClaimFlow", "task.claim_refresh_rejected", {
+                    taskId: input.taskId,
+                });
+                input.cancellation.abortActive();
+                return;
+            }
+            consecutiveFailures = 0;
+            currentClaimExpiresAt = refreshOutcome.claimExpiresAt;
+            if (isClaimLeaseExpired(refreshOutcome.claimExpiresAt)) {
+                logger.debug("runTaskClaimFlow", "task.claim_refresh_lease_expired", {
+                    taskId: input.taskId,
+                });
+                input.cancellation.abortActive();
+                return;
+            }
+        }
+    });
+}
+/** Preserves executor error messages when Effect wraps rejected promises. */
+function normalizeRuntimeError(error) {
+    if (error instanceof Error) {
+        return error;
+    }
+    if (isRecord(error) && typeof error.message === "string" && error.message.trim()) {
+        return new Error(error.message);
+    }
+    return new Error(String(error));
+}
+/** Narrows unknown values to plain records for error normalization. */
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+/** Checks whether cancellation has made the current task flow stop publishing visible outputs. */
+function isTaskStopped(cancellation) {
+    return cancellation.signal.aborted || cancellation.isCancelled();
+}
+function isClaimLeaseExpired(claimExpiresAt) {
+    if (!claimExpiresAt) {
+        return false;
+    }
+    const claimExpiresAtMs = Date.parse(claimExpiresAt);
+    return Number.isFinite(claimExpiresAtMs) && claimExpiresAtMs <= Date.now();
+}

package/dist/protocol.d.ts

@@ -0,0 +1,2 @@
+export { appendEventSchema, buildPublishedEventInput, buildTaskOutputEventInput, buildTaskProgressEventInput, buildWsPublishMessage, buildWsTaskCancelMessage, buildWsTaskClaimMessage, buildWsTaskCompleteMessage, buildWsTaskFailMessage, buildWsTaskRefreshMessage, buildWsTaskReleaseMessage, parseAfterSeq, parseWebSocketServerEnvelope, participantRuntimeKindSchema, registerParticipantSchema, serializeCommandResultEnvelope, serializeErrorEnvelope, sessionEventSchema, sessionEventType, systemProducerId, taskClaimExpiredPayloadSchema, taskCreatedPayloadSchema, taskFromClaimableEvent, taskFromCreatedEvent, taskIdFromCancelledEvent, taskRecordSchema, webSocketOperation, webSocketServerEnvelopeSchema, wsPublishMessageSchema, wsTaskCancelMessageSchema, wsTaskClaimMessageSchema, wsTaskCompleteMessageSchema, wsTaskFailMessageSchema, wsTaskRefreshMessageSchema, wsTaskReleaseMessageSchema, } from "@dungle-scrubs/tether-protocol";
+export type { AppendSessionEventInput, CommandResultEnvelope, WebSocketCommandMessage, WebSocketServerEnvelope, WebSocketTaskCommandMessage, } from "@dungle-scrubs/tether-protocol";

package/dist/protocol.js

@@ -0,0 +1 @@
+export { appendEventSchema, buildPublishedEventInput, buildTaskOutputEventInput, buildTaskProgressEventInput, buildWsPublishMessage, buildWsTaskCancelMessage, buildWsTaskClaimMessage, buildWsTaskCompleteMessage, buildWsTaskFailMessage, buildWsTaskRefreshMessage, buildWsTaskReleaseMessage, parseAfterSeq, parseWebSocketServerEnvelope, participantRuntimeKindSchema, registerParticipantSchema, serializeCommandResultEnvelope, serializeErrorEnvelope, sessionEventSchema, sessionEventType, systemProducerId, taskClaimExpiredPayloadSchema, taskCreatedPayloadSchema, taskFromClaimableEvent, taskFromCreatedEvent, taskIdFromCancelledEvent, taskRecordSchema, webSocketOperation, webSocketServerEnvelopeSchema, wsPublishMessageSchema, wsTaskCancelMessageSchema, wsTaskClaimMessageSchema, wsTaskCompleteMessageSchema, wsTaskFailMessageSchema, wsTaskRefreshMessageSchema, wsTaskReleaseMessageSchema, } from "@dungle-scrubs/tether-protocol";

package/dist/session-event-stream-client.d.ts

@@ -0,0 +1,133 @@
+import WebSocket from "ws";
+import type { SessionEvent } from "./types.js";
+/** Factory for observer WebSocket connections, injectable by tests and hosts. */
+export type SessionEventStreamWebSocketFactory = (url: string) => WebSocket;
+/** Connection settings for a passive session event observer stream. */
+export interface SessionEventStreamClientConfig {
+    /** Last observed event sequence to resume after. */
+    readonly afterSeq: number;
+    /** Bearer token sent to Tether; falls back to SERVICE_AUTH_TOKEN/TETHER_AUTH_TOKEN when omitted. */
+    readonly authToken?: string | null;
+    /** Optional reconnect backoff settings for long-running observers. */
+    readonly reconnect?: {
+        /** Initial delay before reconnecting after an unexpected disconnect. */
+        readonly baseDelayMs?: number;
+        /** Maximum reconnect delay after repeated failures. */
+        readonly maxDelayMs?: number;
+    };
+    /** Base URL of the Tether HTTP service. */
+    readonly serviceUrl: string;
+    /** Session whose durable event stream should be observed. */
+    readonly sessionId: string;
+    /** WebSocket implementation factory, injected by tests and non-Node hosts. */
+    readonly webSocketFactory?: SessionEventStreamWebSocketFactory;
+}
+/** Runtime diagnostics for one passive session event observer. */
+export interface SessionEventStreamClientDebugInfo {
+    /** Number of WebSocket connections opened. */
+    readonly connectCount: number;
+    /** Number of durable events delivered by the stream. */
+    readonly eventCount: number;
+    /** Number of registered event handlers. */
+    readonly eventHandlerCount: number;
+    /** Highest event sequence whose handlers have all resolved; the durable resume cursor. */
+    readonly lastObservedSeq: number;
+    /** Number of failed reconnect attempts since startup. */
+    readonly reconnectFailureCount: number;
+    /** Number of successful reconnects since startup. */
+    readonly reconnectSuccessCount: number;
+    /** Number of replay completion markers observed. */
+    readonly replayCompleteCount: number;
+    /** Underlying WebSocket ready state. */
+    readonly socketReadyState: number;
+    /** Whether the client has been intentionally closed. */
+    readonly stopped: boolean;
+}
+/**
+ * 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 declare class SessionEventStreamClient {
+    private readonly config;
+    private readonly deliveryQueue;
+    private readonly eventHandlers;
+    private readonly errorBacklog;
+    private readonly errorHandlers;
+    private readonly observability;
+    private closePromise;
+    private connectCount;
+    private draining;
+    private eventCount;
+    /** Highest sequence whose handlers have all resolved; the durable resume cursor. */
+    private lastObservedSeq;
+    private reconnectFailureCount;
+    private reconnectSuccessCount;
+    private replayComplete;
+    private replayCompleteCount;
+    private replayCompleteSettled;
+    private rejectReplayComplete;
+    private resolveReplayComplete;
+    private socket;
+    private stopped;
+    private readonly webSocketFactory;
+    /** Creates an observer around the supplied stream configuration. */
+    private constructor();
+    /** Opens a passive observer stream without participant task authority. */
+    static connect(config: SessionEventStreamClientConfig): Promise<SessionEventStreamClient>;
+    /** Requests a graceful WebSocket close and stops reconnect attempts. */
+    close(): void;
+    /** Returns stream cursor, connection, handler, and replay diagnostics. */
+    debugInfo(): SessionEventStreamClientDebugInfo;
+    /** Registers an error callback and returns an unsubscribe function. */
+    onError(handler: (error: Error) => void): () => void;
+    /** Registers an event callback and resumes serial delivery of any backlog. */
+    onEvent(handler: (event: SessionEvent) => void | Promise<void>): () => void;
+    /** Reopens the stream from the highest observed event sequence. */
+    reconnect(): Promise<SessionEventStreamClient>;
+    /** Resolves when the current socket closes. */
+    waitForClose(): Promise<void>;
+    /** Resolves once the current stream replay has completed. */
+    waitForReplayComplete(): Promise<void>;
+    /** Opens a WebSocket stream from the requested event cursor. */
+    private open;
+    /** Reopens the stream with bounded retry backoff. */
+    private reconnectWithBackoff;
+    /** Builds the bounded reconnect loop as an Effect program. */
+    private buildReconnectWithBackoff;
+    /** Parses one server envelope and enqueues it for serial, in-order delivery. */
+    private handleMessage;
+    /**
+     * 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.
+     */
+    private drainDeliveryQueue;
+    /** Awaits every registered handler in turn; returns false on the first rejection. */
+    private deliverEventToHandlers;
+    /**
+     * 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.
+     */
+    private recoverFromDeliveryFailure;
+    /** Routes operational failures to registered error handlers. */
+    private emitError;
+    /** Resolves the current replay wait once. */
+    private settleReplayComplete;
+    /** Rejects the current replay wait once when the stream fails before replay completion. */
+    private settleReplayCompleteError;
+}
+/**
+ * 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 declare const sessionEventObserverRuntimeKind = "observer";
+/** Builds the observer WebSocket URL without participant or task authority. */
+export declare function buildSessionEventStreamUrl(config: SessionEventStreamClientConfig): string;