@dungle-scrubs/tether-client 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kevin Frilot
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,70 @@
+# @dungle-scrubs/tether-client
+
+Public adapter API for external Tether participant runtimes.
+
+Use this package from agents that live outside the Tether service. The package
+owns WebSocket connection setup, replay, task claiming, claim refresh,
+cancellation, task completion, task failure, and reconnect handling.
+
+## Agent Shape
+
+New agents usually provide only three pieces:
+
+- Runtime identity and session configuration for `runParticipantRuntime`.
+- A list of task `workKinds` the agent is allowed to claim.
+- A `ParticipantTaskExecutor` containing the domain-specific work.
+
+```ts
+import { runParticipantRuntime, type ParticipantTaskExecutor } from "@dungle-scrubs/tether-client";
+
+const executor: ParticipantTaskExecutor = async ({ signal, task }) => {
+  if (signal.aborted) {
+    throw new Error("Task cancelled");
+  }
+  const summary = `Handled ${task.taskId}`;
+  return {
+    output: summary,
+    result: { summary },
+  };
+};
+
+await runParticipantRuntime({
+  afterSeq: 0,
+  capabilities: { workKinds: ["example_work"] },
+  claimRefreshMs: 5_000,
+  displayName: "Example Agent",
+  executor,
+  instanceId: "inst_example",
+  participantId: "part_example",
+  runtimeKind: "example_agent",
+  serviceUrl: "http://127.0.0.1:3025",
+  sessionId: "sess_example",
+  workKinds: ["example_work"],
+});
+```
+
+When Tether runs with the default `AUTH_MODE=required`, pass `authToken` or set
+`SERVICE_AUTH_TOKEN`. The package falls back to `TETHER_AUTH_TOKEN` only for
+external consumers that need a namespaced environment variable.
+
+The executor receives a claimed task, the active cancellation `AbortSignal`,
+participant/session identity, and helper methods for extra progress or output
+events. It returns the structured durable completion payload and optional
+user-visible output text.
+
+## Runtime API Selection
+
+Use `runParticipantRuntime` for most external agents. It connects the
+participant stream, installs the default structured error channel, waits for
+replay, runs optional replay-ready hooks, processes claimable tasks, refreshes
+claims, and runs hook cleanup after the claim loop exits.
+
+Use `ParticipantRuntimeClient` directly only when an adapter needs lower-level
+control over participant WebSocket commands such as `appendEvent`, `claimTask`,
+`refreshTaskClaim`, `completeTask`, or `failTask`.
+
+Use `SessionEventStreamClient` for passive observers that need session replay
+and live events without participant identity or task authority. Bridges,
+dashboards, and approval observers should use this API when they only need
+`onEvent`, `onError`, `waitForReplayComplete`, reconnect behavior, and stream
+diagnostics.

package/dist/approval-observer.d.ts

@@ -0,0 +1,74 @@
+import type { SessionEvent } from "./types.js";
+/** Last approval processing failure captured by the observer diagnostics. */
+export interface TaskApprovalObserverFailureInfo {
+    /** Approval id whose processing failed. */
+    readonly approvalId: string;
+    /** Original or wrapped error message. */
+    readonly message: string;
+    /** Original or wrapped error name. */
+    readonly name: string;
+    /** Observer operation that failed. */
+    readonly operation: string;
+}
+/** Snapshot of one approval observer's local process state. */
+export interface TaskApprovalObserverDebugInfo {
+    /** Number of approval ids currently inside processApproval. */
+    readonly activeProcessingCount: number;
+    /** Current in-flight approval ids. */
+    readonly inFlightApprovalIds: readonly string[];
+    /** Most recent processing failure, if any. */
+    readonly lastError: TaskApprovalObserverFailureInfo | null;
+    /** Observer module name used for boundary logs and spans. */
+    readonly moduleName: string;
+    /** Current processed approval ids known to this process. */
+    readonly processedApprovalIds: readonly string[];
+    /** Number of replay-buffered approval ids. */
+    readonly replayBufferCount: number;
+}
+/** Callable unsubscribe handle with inspectable local observer state. */
+export interface TaskApprovalObserver {
+    /** Stops observing approval events. */
+    (): void;
+    /** Returns a point-in-time debug snapshot of local approval observer state. */
+    readonly debugInfo: () => TaskApprovalObserverDebugInfo;
+}
+/** Error raised when a task approval processing callback rejects. */
+export declare class TaskApprovalProcessingError extends Error {
+    /** Approval id that failed processing. */
+    readonly approvalId: string;
+    /** Observer operation that failed. */
+    readonly operation: string;
+    /** Captures approval processing context while preserving the original cause. */
+    constructor(input: {
+        readonly approvalId: string;
+        readonly cause: unknown;
+        readonly operation: string;
+    });
+}
+/** Minimal event-stream client surface needed by approval observers. */
+export interface TaskApprovalObserverClient {
+    /** Registers one durable event handler. */
+    readonly onEvent: (handler: (event: SessionEvent) => void) => () => void;
+    /** Resolves once historical event replay has completed. */
+    readonly waitForReplayComplete: () => Promise<void>;
+}
+/** Options for observing approval events with replay-safe idempotency. */
+export interface ObserveTaskApprovalsOptions<TApproval> {
+    /** Event stream client that provides replay and live events. */
+    readonly client: TaskApprovalObserverClient;
+    /** Stable id for one parsed approval, usually the approval event id. */
+    readonly approvalId: (approval: TApproval) => string;
+    /** Handles observer processing failures. Defaults to console.error. */
+    readonly onError?: (error: unknown) => void;
+    /** Parses a relevant approval from one durable session event. */
+    readonly parseApproval: (event: SessionEvent) => TApproval | null;
+    /** Processes one approval after replay and idempotency checks. */
+    readonly processApproval: (approval: TApproval) => Promise<void>;
+    /** Extracts already-processed approval ids from prior output events. */
+    readonly processedApprovalIdFromEvent: (event: SessionEvent) => string | null;
+}
+/**
+ * Observes approval events after replay while suppressing approvals that have
+ * already produced follow-up output.
+ */
+export declare function observeTaskApprovals<TApproval>(options: ObserveTaskApprovalsOptions<TApproval>): TaskApprovalObserver;

package/dist/approval-observer.js

@@ -0,0 +1,163 @@
+import { ModuleObservability, readModuleObservabilityOptions } from "./observability.js";
+/** Error raised when a task approval processing callback rejects. */
+export class TaskApprovalProcessingError extends Error {
+    /** Approval id that failed processing. */
+    approvalId;
+    /** Observer operation that failed. */
+    operation;
+    /** Captures approval processing context while preserving the original cause. */
+    constructor(input) {
+        super(`Approval ${input.approvalId} failed during ${input.operation}`, {
+            cause: input.cause,
+        });
+        this.approvalId = input.approvalId;
+        this.name = "TaskApprovalProcessingError";
+        this.operation = input.operation;
+    }
+}
+/**
+ * Observes approval events after replay while suppressing approvals that have
+ * already produced follow-up output.
+ */
+export function observeTaskApprovals(options) {
+    const observability = new ModuleObservability(readModuleObservabilityOptions("TaskApprovalObserver"));
+    const processedApprovalIds = new Set();
+    const inFlightApprovalIds = new Set();
+    const replayedApprovals = new Map();
+    const onError = options.onError ?? console.error;
+    let activeProcessingCount = 0;
+    let lastError = null;
+    let replayComplete = false;
+    let stopped = false;
+    /** Processes one approval unless it has already been handled. */
+    const processApproval = async (approval, eventPhase) => {
+        if (stopped) {
+            observability.debug("processApproval", "approval.skipped_stopped", {
+                eventPhase,
+                outcome: "stopped",
+            });
+            return;
+        }
+        const approvalId = options.approvalId(approval);
+        if (processedApprovalIds.has(approvalId)) {
+            observability.debug("processApproval", "approval.skipped_processed", {
+                approvalId,
+                eventPhase,
+                outcome: "skipped_processed",
+                ...stateCounts(),
+            });
+            return;
+        }
+        if (inFlightApprovalIds.has(approvalId)) {
+            observability.debug("processApproval", "approval.skipped_in_flight", {
+                approvalId,
+                eventPhase,
+                outcome: "skipped_in_flight",
+                ...stateCounts(),
+            });
+            return;
+        }
+        inFlightApprovalIds.add(approvalId);
+        activeProcessingCount += 1;
+        observability.debug("processApproval", "approval.started", {
+            approvalId,
+            eventPhase,
+            outcome: "started",
+            ...stateCounts(),
+        });
+        try {
+            await observability.traceBoundary("processApproval", { approvalId, eventPhase }, async () => {
+                try {
+                    await options.processApproval(approval);
+                }
+                catch (cause) {
+                    const error = new TaskApprovalProcessingError({
+                        approvalId,
+                        cause,
+                        operation: "processApproval",
+                    });
+                    lastError = {
+                        approvalId,
+                        message: cause instanceof Error ? cause.message : String(cause),
+                        name: cause instanceof Error ? cause.name : "UnknownError",
+                        operation: "processApproval",
+                    };
+                    throw error;
+                }
+            }, () => ({ approvalId, outcome: "processed" }));
+            processedApprovalIds.add(approvalId);
+            observability.debug("processApproval", "approval.processed", {
+                approvalId,
+                eventPhase,
+                outcome: "processed",
+                ...stateCounts(),
+            });
+        }
+        finally {
+            inFlightApprovalIds.delete(approvalId);
+            activeProcessingCount -= 1;
+        }
+    };
+    const unsubscribe = options.client.onEvent((event) => {
+        const processedApprovalId = options.processedApprovalIdFromEvent(event);
+        if (processedApprovalId) {
+            processedApprovalIds.add(processedApprovalId);
+            replayedApprovals.delete(processedApprovalId);
+            observability.debug("onEvent", "approval.processed_output_seen", {
+                approvalId: processedApprovalId,
+                eventPhase: "processed-output",
+                outcome: "processed",
+                ...stateCounts(),
+            });
+            return;
+        }
+        const approval = options.parseApproval(event);
+        if (!approval) {
+            return;
+        }
+        if (!replayComplete) {
+            replayedApprovals.set(options.approvalId(approval), approval);
+            observability.debug("onEvent", "approval.buffered", {
+                approvalId: options.approvalId(approval),
+                eventPhase: "replay",
+                outcome: "buffered",
+                ...stateCounts(),
+            });
+            return;
+        }
+        void processApproval(approval, "live").catch(onError);
+    });
+    void options.client.waitForReplayComplete().then(() => {
+        if (stopped) {
+            return;
+        }
+        replayComplete = true;
+        for (const approval of replayedApprovals.values()) {
+            void processApproval(approval, "replay").catch(onError);
+        }
+        replayedApprovals.clear();
+    });
+    const stop = Object.assign(() => {
+        stopped = true;
+        unsubscribe();
+    }, {
+        debugInfo: () => ({
+            activeProcessingCount,
+            inFlightApprovalIds: [...inFlightApprovalIds],
+            lastError,
+            moduleName: observability.debugInfo().moduleName,
+            processedApprovalIds: [...processedApprovalIds],
+            replayBufferCount: replayedApprovals.size,
+        }),
+    });
+    return stop;
+    /** Returns local state counts for structured logs. */
+    function stateCounts() {
+        return {
+            activeProcessingCount,
+            inFlightApprovalCount: inFlightApprovalIds.size,
+            processedApprovalCount: processedApprovalIds.size,
+            replayBufferCount: replayedApprovals.size,
+        };
+    }
+}

package/dist/auth-token.d.ts

@@ -0,0 +1,6 @@
+type ServiceAuthEnv = Readonly<Record<string, string | undefined>>;
+/** Reads the first configured Tether service auth token from an explicit environment map. */
+export declare function readServiceAuthToken(env?: ServiceAuthEnv): string | null;
+/** Resolves an explicit token value, falling back to service environment names. */
+export declare function resolveServiceAuthToken(authToken: string | null | undefined, env?: ServiceAuthEnv): string | null;
+export {};

package/dist/auth-token.js

@@ -0,0 +1,25 @@
+/** Reads the first configured Tether service auth token from an explicit environment map. */
+export function readServiceAuthToken(env = readProcessEnv()) {
+    const serviceToken = readNonEmptyEnv(env.SERVICE_AUTH_TOKEN);
+    if (serviceToken) {
+        return serviceToken;
+    }
+    return readNonEmptyEnv(env.TETHER_AUTH_TOKEN);
+}
+/** Resolves an explicit token value, falling back to service environment names. */
+export function resolveServiceAuthToken(authToken, env = readProcessEnv()) {
+    if (authToken !== undefined) {
+        return authToken?.trim() || null;
+    }
+    return readServiceAuthToken(env);
+}
+/** Reads process.env without requiring Node ambient types in downstream packages. */
+function readProcessEnv() {
+    const maybeGlobal = globalThis;
+    return maybeGlobal.process?.env ?? {};
+}
+/** Reads a trimmed environment value, treating blanks as omitted. */
+function readNonEmptyEnv(value) {
+    const trimmed = value?.trim();
+    return trimmed ? trimmed : null;
+}

package/dist/effect-timing.d.ts

@@ -0,0 +1,3 @@
+import { Effect } from "effect";
+/** Sleeps inside an Effect program without keeping the Node.js process alive. */
+export declare function sleepUnrefEffect(delayMs: number): Effect.Effect<void, never>;

package/dist/effect-timing.js

@@ -0,0 +1,9 @@
+import { Effect } from "effect";
+/** Sleeps inside an Effect program without keeping the Node.js process alive. */
+export function sleepUnrefEffect(delayMs) {
+    return Effect.async((resume) => {
+        const timeout = setTimeout(() => resume(Effect.void), delayMs);
+        timeout.unref();
+        return Effect.sync(() => clearTimeout(timeout));
+    });
+}

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Public adapter API for external participant runtimes.
+ *
+ * Adapter implementations should import from this module instead of reaching
+ * into Tether service implementation paths.
+ */
+export type { ObserveTaskApprovalsOptions, TaskApprovalObserver, TaskApprovalObserverClient, TaskApprovalObserverDebugInfo, TaskApprovalObserverFailureInfo, } from "./approval-observer.js";
+export { observeTaskApprovals, TaskApprovalProcessingError } from "./approval-observer.js";
+export { readServiceAuthToken, resolveServiceAuthToken } from "./auth-token.js";
+export type { SessionEventStreamClientConfig, SessionEventStreamClientDebugInfo, SessionEventStreamWebSocketFactory, } from "./session-event-stream-client.js";
+export { buildSessionEventStreamUrl, sessionEventObserverRuntimeKind, SessionEventStreamClient, } from "./session-event-stream-client.js";
+export type { ParticipantRuntimeClientConfig, ParticipantRuntimeClientDebugInfo, ParticipantRuntimeCursorPersistPolicy, ParticipantRuntimeCursorStore, ParticipantRuntimeTaskLoopOptions, ParticipantRuntimeCleanup, ParticipantTaskExecutor, ParticipantTaskExecutorContext, ParticipantTaskExecutorResult, ParticipantTaskSelector, RunParticipantRuntimeHooks, RunParticipantRuntimeInput, } from "./participant-runtime-client.js";
+export { buildParticipantRuntimeStreamUrl, ParticipantRuntimeClient, ParticipantRuntimeClientConfigurationError, ParticipantRuntimeCommandError, ParticipantRuntimeCommandTimeoutError, resolveCommandTimeoutMs, resolveResumeSeq, runParticipantRuntime, shouldClaimParticipantTask, } from "./participant-runtime-client.js";
+export { buildPublishedEventInput, taskFromClaimableEvent, taskFromCreatedEvent, taskIdFromCancelledEvent, } from "./protocol.js";
+export { TaskCancellationRegistry } from "./task-cancellation-registry.js";
+export type { ClientSessionBindingRecord, ControlLeaseSnapshot, ControlLeaseStatus, ParticipantRuntimeKind, ParticipantRuntimeSnapshot, ParticipantRuntimeSnapshotStatus, SessionDebugSummary, SessionEvent, SessionRecord, TaskRecord, TaskSnapshot, TaskSnapshotStatus, } from "./types.js";

package/dist/index.js

@@ -0,0 +1,12 @@
+/**
+ * Public adapter API for external participant runtimes.
+ *
+ * Adapter implementations should import from this module instead of reaching
+ * into Tether service implementation paths.
+ */
+export { observeTaskApprovals, TaskApprovalProcessingError } from "./approval-observer.js";
+export { readServiceAuthToken, resolveServiceAuthToken } from "./auth-token.js";
+export { buildSessionEventStreamUrl, sessionEventObserverRuntimeKind, SessionEventStreamClient, } from "./session-event-stream-client.js";
+export { buildParticipantRuntimeStreamUrl, ParticipantRuntimeClient, ParticipantRuntimeClientConfigurationError, ParticipantRuntimeCommandError, ParticipantRuntimeCommandTimeoutError, resolveCommandTimeoutMs, resolveResumeSeq, runParticipantRuntime, shouldClaimParticipantTask, } from "./participant-runtime-client.js";
+export { buildPublishedEventInput, taskFromClaimableEvent, taskFromCreatedEvent, taskIdFromCancelledEvent, } from "./protocol.js";
+export { TaskCancellationRegistry } from "./task-cancellation-registry.js";

package/dist/observability.d.ts

@@ -0,0 +1,147 @@
+type LogLevel = "debug" | "error" | "info" | "warn";
+/**
+ * Snapshot of a module boundary helper's current counters and last-known
+ * failure state.
+ */
+export interface BoundaryDebugInfo {
+    /** Number of boundary operations currently running. */
+    readonly activeOperations: number;
+    /** Total number of boundary calls observed since helper creation. */
+    readonly boundaryCalls: number;
+    /** Total number of boundary calls that ended by throwing. */
+    readonly boundaryFailures: number;
+    /** Whether structured enter, exit, and error boundary logs are enabled. */
+    readonly boundaryLogsEnabled: boolean;
+    /** Whether debug-level diagnostic logs are enabled. */
+    readonly debugEnabled: boolean;
+    /** Most recent boundary failure metadata, or null when none has failed. */
+    readonly lastError: StructuredErrorInfo | null;
+    /** Most recent operation name observed by the helper. */
+    readonly lastOperation: string | null;
+    /** Logical module name attached to logs, spans, errors, and debug snapshots. */
+    readonly moduleName: string;
+}
+/**
+ * Construction options for module-boundary observability helpers.
+ */
+export interface ModuleObservabilityOptions {
+    /** Enables structured boundary enter, exit, and error logs when true. */
+    readonly boundaryLogsEnabled?: boolean;
+    /** Enables scoped debug logs when true. */
+    readonly debugEnabled?: boolean;
+    /** Optional structured logger; defaults to JSON console logging. */
+    readonly logger?: StructuredLogger;
+    /** Logical module name attached to logs, spans, errors, and debug snapshots. */
+    readonly moduleName: string;
+    /** Optional OpenTelemetry tracer name; defaults to the module name. */
+    readonly tracerName?: string;
+}
+/**
+ * Stable error metadata captured from an unknown thrown value.
+ */
+export interface StructuredErrorInfo {
+    /** Human-readable error message. */
+    readonly message: string;
+    /** Error class or normalized error name. */
+    readonly name: string;
+}
+/**
+ * Structured module-boundary log entry emitted by ModuleObservability.
+ */
+export interface StructuredLogEntry {
+    /** ISO timestamp for when the log entry was emitted. */
+    readonly at: string;
+    /** Operation-specific structured payload with sensitive data already redacted by the caller. */
+    readonly data: Record<string, unknown>;
+    /** Severity level for routing the entry to the matching log sink. */
+    readonly level: LogLevel;
+    /** Stable event name or debug message for the boundary event. */
+    readonly message: string;
+    /** Logical module name that emitted the entry. */
+    readonly moduleName: string;
+    /** Public boundary operation associated with the entry. */
+    readonly operation: string;
+    /**
+     * Synthetic module-boundary correlation id for pairing enter, exit, and error
+     * logs; this is not an OpenTelemetry trace id.
+     */
+    readonly traceId: string;
+}
+/**
+ * Sink for structured module-boundary log entries.
+ */
+export interface StructuredLogger {
+    /** Receives one structured log entry. */
+    readonly log: (entry: StructuredLogEntry) => void;
+}
+/**
+ * Error thrown when a Tether module invariant breaks.
+ */
+export declare class TetherInvariantError extends Error {
+    readonly code = "TETHER_INVARIANT_VIOLATION";
+    readonly details: Record<string, unknown>;
+    readonly moduleName: string;
+    readonly operation: string;
+    /**
+     * Captures a violated invariant with machine-readable module and operation
+     * context.
+     */
+    constructor(input: {
+        readonly cause?: unknown;
+        readonly details?: Record<string, unknown>;
+        readonly message: string;
+        readonly moduleName: string;
+        readonly operation: string;
+    });
+}
+/**
+ * JSON logger used when boundary logs are enabled through module options.
+ */
+export declare class ConsoleStructuredLogger implements StructuredLogger {
+    /**
+     * Writes structured log entries to the matching console level.
+     */
+    log(entry: StructuredLogEntry): void;
+}
+/**
+ * Boundary observability helper for deep modules.
+ */
+export declare class ModuleObservability {
+    private activeOperations;
+    private boundaryCalls;
+    private boundaryFailures;
+    private readonly boundaryLogsEnabled;
+    private readonly debugEnabled;
+    private lastError;
+    private lastOperation;
+    private readonly logger;
+    private readonly moduleName;
+    private readonly tracer;
+    /**
+     * Creates an observability boundary helper with optional logging and tracing
+     * dependencies.
+     */
+    constructor(options: ModuleObservabilityOptions);
+    /**
+     * Snapshots boundary counters and the most recent failure.
+     */
+    debugInfo(): BoundaryDebugInfo;
+    /**
+     * Runs one public boundary method inside logs and an OpenTelemetry span.
+     */
+    traceBoundary<TValue>(operation: string, input: Record<string, unknown>, action: () => Promise<TValue>, summarize?: (value: TValue) => Record<string, unknown>): Promise<TValue>;
+    /**
+     * Throws a typed invariant error when internal module assumptions break.
+     */
+    assertInvariant(condition: boolean, operation: string, message: string, details?: Record<string, unknown>): asserts condition;
+    /**
+     * Emits scoped verbose data without turning on global logging.
+     */
+    debug(operation: string, message: string, data?: Record<string, unknown>): void;
+    private logBoundary;
+}
+/**
+ * Reads module observability toggles from environment variables.
+ */
+export declare function readModuleObservabilityOptions(moduleName: string, env?: NodeJS.ProcessEnv): ModuleObservabilityOptions;
+export {};