@dungle-scrubs/tether-client 0.1.1

package/dist/participant-runtime-client.d.ts

@@ -0,0 +1,443 @@
+import { type BoundaryDebugInfo } from "./observability.js";
+import { type AppendSessionEventInput } from "./protocol.js";
+import { type TaskCancellationContext } from "./participant-claimable-task-runner.js";
+import type { ParticipantRuntimeKind, SessionEvent, TaskRecord } from "./types.js";
+/**
+ * Error raised when participant runtime client configuration is invalid.
+ */
+export declare class ParticipantRuntimeClientConfigurationError extends Error {
+    /** Machine-readable configuration field that failed validation. */
+    readonly field: string;
+    constructor(field: string, message: string);
+}
+/**
+ * Error raised when the server returns a correlated command error envelope.
+ */
+export declare class ParticipantRuntimeCommandError extends Error {
+    /** WebSocket command operation that rejected. */
+    readonly op: string;
+    /** Number of pending commands observed when the rejection was handled. */
+    readonly pendingCommandCount: number;
+    /** Correlation id attached to the command request. */
+    readonly requestId: string;
+    /** Task id carried by task-scoped commands when present. */
+    readonly taskId?: string;
+    constructor(input: {
+        readonly message: string;
+        readonly op: string;
+        readonly pendingCommandCount: number;
+        readonly requestId: string;
+        readonly taskId?: string;
+    });
+}
+/**
+ * Error raised when a correlated WebSocket command does not receive a response
+ * before the configured command timeout.
+ */
+export declare class ParticipantRuntimeCommandTimeoutError extends Error {
+    /** WebSocket command operation that timed out. */
+    readonly op: string;
+    /** Number of pending commands observed when the timeout fired. */
+    readonly pendingCommandCount: number;
+    /** Correlation id attached to the command request. */
+    readonly requestId: string;
+    /** Task id carried by task-scoped commands when present. */
+    readonly taskId?: string;
+    /** Command response timeout in milliseconds. */
+    readonly timeoutMs: number;
+    constructor(input: {
+        readonly op: string;
+        readonly pendingCommandCount: number;
+        readonly requestId: string;
+        readonly taskId?: string;
+        readonly timeoutMs: number;
+    });
+}
+/**
+ * Result returned by an adapter-specific task executor after task work finishes.
+ */
+export interface ParticipantTaskExecutorResult {
+    /** Optional user-visible output event to publish before completion. */
+    readonly output?: string | null;
+    /** Structured completion payload stored on the durable task row. */
+    readonly result: Record<string, unknown>;
+}
+/**
+ * Runtime helpers and claimed task state passed to adapter-specific executors.
+ */
+export interface ParticipantTaskExecutorContext {
+    /** Concrete runtime process id that owns the task claim. */
+    readonly instanceId: string;
+    /** Stable participant identity that owns the task claim. */
+    readonly participantId: string;
+    /** Bounded session events observed before this task executor started. */
+    readonly recentEvents: readonly SessionEvent[];
+    /** Publishes an additional user-visible output event for the active task. */
+    readonly publishOutput: (output: string) => Promise<void>;
+    /** Publishes an additional progress event for the active task. */
+    readonly publishProgress: () => Promise<void>;
+    /** Cancellation signal aborted when Tether cancels the active task or its claim is lost. */
+    readonly signal: AbortSignal;
+    /** Durable session that owns the task. */
+    readonly sessionId: string;
+    /** Claimed task record returned by Tether after this participant won the claim. */
+    readonly task: TaskRecord;
+}
+/**
+ * Executes a claimed task and returns the durable completion payload.
+ */
+export type ParticipantTaskExecutor = (context: ParticipantTaskExecutorContext) => Promise<ParticipantTaskExecutorResult>;
+/**
+ * Decides whether a participant runtime should attempt a claim for a task.
+ */
+export type ParticipantTaskSelector = (task: TaskRecord) => boolean;
+/**
+ * Durable resume cursor for a participant runtime. When supplied, the runtime
+ * resumes from the persisted sequence instead of replaying a fixed window from
+ * `afterSeq` on every process start. `read` runs once at startup; `write` runs
+ * throttled as events are handled and once more on graceful close.
+ */
+export interface ParticipantRuntimeCursorStore {
+    /** Returns the last persisted event sequence, or null when none is stored. */
+    read(): number | null | Promise<number | null>;
+    /** Persists the highest event sequence the runtime has confirmed as handled. */
+    write(seq: number): void | Promise<void>;
+}
+/**
+ * Throttle policy for durable cursor writes. Persists at most once per
+ * `intervalMs`, or immediately once `eventCount` events have been observed
+ * since the last write.
+ */
+export interface ParticipantRuntimeCursorPersistPolicy {
+    /** Maximum observed events between writes before forcing a persist. */
+    readonly eventCount?: number;
+    /** Minimum delay between throttled cursor writes in milliseconds. */
+    readonly intervalMs?: number;
+}
+/**
+ * Connection settings for one external participant runtime process.
+ */
+export interface ParticipantRuntimeClientConfig {
+    /** Last observed event sequence to resume after; acts as a resume floor. */
+    readonly afterSeq: number;
+    /** Bearer token sent to Tether; falls back to SERVICE_AUTH_TOKEN/TETHER_AUTH_TOKEN when omitted. */
+    readonly authToken?: string | null;
+    /** Public participant capabilities registered with the session. */
+    readonly capabilities: Record<string, unknown>;
+    /** Maximum time to wait for one correlated WebSocket command response. */
+    readonly commandTimeoutMs?: number;
+    /** Optional throttle policy for durable cursor writes. */
+    readonly cursorPersist?: ParticipantRuntimeCursorPersistPolicy;
+    /** Optional durable resume cursor. When omitted, resume behavior is unchanged. */
+    readonly cursorStore?: ParticipantRuntimeCursorStore;
+    /** Display name shown in participant presence. */
+    readonly displayName: string;
+    /** Concrete runtime process id that owns the WebSocket control lease. */
+    readonly instanceId: string;
+    /** Stable or generated participant identity controlled by this runtime. */
+    readonly participantId: string;
+    /** Optional reconnect backoff settings for long-running adapters. */
+    readonly reconnect?: {
+        /** Initial delay before reconnecting after an unexpected disconnect. */
+        readonly baseDelayMs?: number;
+        /** Maximum reconnect delay after repeated failures. */
+        readonly maxDelayMs?: number;
+    };
+    /** Runtime implementation kind, such as `generic_agent` or `codex`. */
+    readonly runtimeKind: ParticipantRuntimeKind;
+    /** Base URL of the Tether HTTP service. */
+    readonly serviceUrl: string;
+    /** Session the participant runtime connects to. */
+    readonly sessionId: string;
+}
+/**
+ * Options for processing claimable tasks from the event stream.
+ */
+export interface ParticipantRuntimeTaskLoopOptions {
+    /** Interval used to refresh active task claim leases. */
+    readonly claimRefreshMs: number;
+    /** Adapter-specific task executor. */
+    readonly executor: ParticipantTaskExecutor;
+    /** Whether to process replayed claimable work once and exit. */
+    readonly once: boolean;
+    /** Adapter-specific task selection rule. */
+    readonly shouldClaimTask: ParticipantTaskSelector;
+}
+/** Cleanup callback returned by participant runtime lifecycle hooks. */
+export type ParticipantRuntimeCleanup = () => void | Promise<void>;
+/** Optional lifecycle hooks for the high-level participant runtime runner. */
+export interface RunParticipantRuntimeHooks {
+    /**
+     * Handles stream and reconnect errors. Omit to use structured stderr
+     * logging; pass null only when the embedding host installs an equivalent
+     * visible error path.
+     */
+    readonly onError?: ((error: Error) => void) | null;
+    /**
+     * Runs after historical replay completes and before the task claim loop
+     * starts. Use this to publish startup status or register observers that must
+     * receive replay backlog. A returned cleanup callback runs after the claim
+     * loop exits.
+     */
+    readonly onReplayComplete?: (client: ParticipantRuntimeClient) => undefined | ParticipantRuntimeCleanup | Promise<undefined | ParticipantRuntimeCleanup>;
+}
+/**
+ * High-level adapter entry point for running one participant runtime.
+ */
+export interface RunParticipantRuntimeInput extends ParticipantRuntimeClientConfig {
+    /** Interval used to refresh active task claim leases. */
+    readonly claimRefreshMs: number;
+    /** Adapter-specific task executor. */
+    readonly executor: ParticipantTaskExecutor;
+    /** Optional lifecycle and error hooks for adapters with replay-ready setup. */
+    readonly hooks?: RunParticipantRuntimeHooks;
+    /** Whether to process replayed claimable work once and exit. */
+    readonly once?: boolean;
+    /** Optional adapter-specific selector; defaults to work kind and participant ownership checks. */
+    readonly shouldClaimTask?: ParticipantTaskSelector;
+    /** Task kinds this runtime is willing to claim. */
+    readonly workKinds: readonly string[];
+}
+/**
+ * Runtime diagnostics for one participant WebSocket client.
+ */
+export interface ParticipantRuntimeClientDebugInfo extends BoundaryDebugInfo {
+    /** Number of events received before a handler was attached. */
+    readonly eventBacklogSize: number;
+    /** Number of registered event handlers. */
+    readonly eventHandlerCount: number;
+    /** Highest event sequence observed by this client. */
+    readonly lastObservedSeq: number;
+    /** Number of failed reconnect attempts since startup. */
+    readonly reconnectFailureCount: number;
+    /** Number of successful reconnects since startup. */
+    readonly reconnectSuccessCount: number;
+    /** Whether the client has been intentionally closed. */
+    readonly stopped: boolean;
+    /** Number of in-flight command requests waiting for server responses. */
+    readonly pendingCommandCount: number;
+    /** Underlying WebSocket ready state. */
+    readonly socketReadyState: number;
+}
+/**
+ * Runs a participant runtime using the reusable client boundary. Adapters call
+ * this when they only need to provide identity, capabilities, task selection,
+ * and execution policy.
+ */
+export declare function runParticipantRuntime(input: RunParticipantRuntimeInput): Promise<void>;
+/**
+ * Checks whether a task is claimable by a participant with a work-kind allow
+ * list.
+ */
+export declare function shouldClaimParticipantTask(task: TaskRecord, workKinds: readonly string[], participantId: string): boolean;
+/**
+ * Reusable WebSocket runtime client for external participants. It owns replay
+ * buffering, command correlation, task claiming, claim refresh, cancellation,
+ * and shutdown hooks so adapter workers only provide task-selection and
+ * execution policy.
+ */
+export declare class ParticipantRuntimeClient {
+    private readonly config;
+    private static readonly maxRecentEvents;
+    private readonly closeHandlers;
+    private closePromise;
+    private readonly eventBacklog;
+    private readonly eventHandlers;
+    private readonly errorHandlers;
+    private lastObservedSeq;
+    private lastHandledSeq;
+    private lastPersistedSeq;
+    private eventsSinceCursorPersist;
+    private cursorPersistTimer;
+    private readonly cursorPersistIntervalMs;
+    private readonly cursorPersistEventCount;
+    private readonly commandTimeoutMs;
+    private readonly observability;
+    private readonly pendingCommands;
+    private readonly recentEvents;
+    private reconnectFailureCount;
+    private reconnectSuccessCount;
+    private replayComplete;
+    private rejectReplayComplete;
+    private resolveReplayComplete;
+    private replayCompleteSettled;
+    private socket;
+    private stopped;
+    /**
+     * Attaches protocol message handling to an already-created WebSocket.
+     */
+    private constructor();
+    /**
+     * Opens the WebSocket stream and returns a command-capable participant client.
+     * When a durable cursor is configured, the stream resumes from the higher of
+     * `afterSeq` and the persisted cursor so restarts replay only actual downtime.
+     */
+    static connect(config: ParticipantRuntimeClientConfig): Promise<ParticipantRuntimeClient>;
+    /**
+     * Publishes one participant-originated event over the WebSocket command
+     * channel.
+     */
+    appendEvent(input: AppendSessionEventInput): Promise<void>;
+    /**
+     * Attempts to claim a task and returns null when another participant won.
+     */
+    claimTask(taskId: string): Promise<TaskRecord | null>;
+    /**
+     * Requests a graceful WebSocket close.
+     */
+    close(): void;
+    /**
+     * Drops the current transport without stopping the client. Long-running task
+     * loops reconnect from the last observed event sequence.
+     */
+    disconnect(): void;
+    /**
+     * Returns client-side queue, cursor, and pending-command counters.
+     */
+    debugInfo(): ParticipantRuntimeClientDebugInfo;
+    /**
+     * Completes the active task claim with a structured result payload.
+     */
+    completeTask(taskId: string, result: Record<string, unknown>): Promise<void>;
+    /**
+     * Fails the active task claim with a structured failure payload.
+     */
+    failTask(taskId: string, failure: Record<string, unknown>): Promise<void>;
+    /**
+     * Registers a close callback and returns an unsubscribe function.
+     */
+    onClose(handler: () => void): () => void;
+    /**
+     * Registers an error callback and returns an unsubscribe function.
+     */
+    onError(handler: (error: Error) => void): () => void;
+    /**
+     * Registers an event callback and drains any events received before the
+     * handler was attached.
+     */
+    onEvent(handler: (event: SessionEvent) => void): () => void;
+    /**
+     * Reopens the participant stream from the highest observed event sequence.
+     */
+    reconnect(): Promise<ParticipantRuntimeClient>;
+    /**
+     * Refreshes the active task claim lease and returns null if the claim is no
+     * longer valid.
+     */
+    refreshTaskClaim(taskId: string): Promise<TaskRecord | null>;
+    /**
+     * Processes claimable tasks from replay and live events until either the
+     * one-shot replay work completes or the socket closes.
+     */
+    runClaimableTasks(options: ParticipantRuntimeTaskLoopOptions): Promise<void>;
+    /**
+     * Runs the claim, progress, execution, output, and completion sequence for
+     * one task while respecting cancellation.
+     */
+    runTaskClaimFlow(input: {
+        readonly cancellation: TaskCancellationContext;
+        readonly claimRefreshMs: number;
+        readonly executor: ParticipantTaskExecutor;
+        readonly task: TaskRecord;
+    }): Promise<void>;
+    /**
+     * Resolves when the current socket closes.
+     */
+    waitForClose(): Promise<void>;
+    /**
+     * Resolves once the server has finished replaying historical events.
+     */
+    waitForReplayComplete(): Promise<void>;
+    /**
+     * Opens a WebSocket stream from the requested event cursor.
+     */
+    private open;
+    /**
+     * Reopens the WebSocket stream with bounded retry backoff.
+     */
+    private reconnectWithBackoff;
+    /**
+     * Builds the bounded reconnect loop as an Effect program.
+     */
+    private buildReconnectWithBackoff;
+    /**
+     * Returns the currently open socket or throws a connection-level error.
+     */
+    private requireOpenSocket;
+    /**
+     * Parses one server envelope and routes it to event handlers, pending command
+     * promises, or replay completion state.
+     */
+    private handleMessage;
+    /**
+     * Routes a connection-level or message-handling error to registered error
+     * handlers instead of throwing out of a ws event listener, which would
+     * surface as an unhandled exception.
+     */
+    private emitError;
+    /** Resolves the replay wait once, preserving later reconnect state. */
+    private settleReplayComplete;
+    /** Rejects the replay wait once when the socket fails before replay.complete. */
+    private settleReplayCompleteError;
+    /**
+     * Keeps a bounded in-memory window of replay/live events for executors that
+     * need conversation context without reimplementing stream replay.
+     */
+    private rememberEvent;
+    /**
+     * Resolves the startup resume sequence from the durable cursor, never below
+     * the configured `afterSeq` floor. Returns `afterSeq` when no cursor store is
+     * configured, preserving the fixed-window resume behavior.
+     */
+    private resolveInitialResumeSeq;
+    /**
+     * Advances the handled cursor once an event's handlers have been invoked and
+     * schedules a durable persist. Only sequences that have actually been
+     * delivered to a handler reach the durable store, so a restart never resumes
+     * past an event that was merely received but never handled. No-op when the
+     * sequence has not advanced past the last handled value.
+     */
+    private markSeqHandled;
+    /**
+     * Records that the handled cursor advanced and persists it under the
+     * configured throttle: immediately once enough events accumulate, otherwise
+     * on a trailing timer. No-op when no cursor store is configured.
+     */
+    private scheduleCursorPersist;
+    /**
+     * Writes the highest handled event sequence to the durable cursor store,
+     * skipping when it has not advanced past the last persisted value. Only
+     * sequences confirmed as handled are persisted, never a value ahead of the
+     * events the runtime has actually processed.
+     */
+    private persistCursor;
+    /**
+     * Rejects all pending command promises with a shared connection-level error.
+     */
+    private rejectPendingCommands;
+    /**
+     * Sends a command with a generated request id and waits for its matching
+     * command result or error envelope.
+     */
+    private sendCommand;
+    /**
+     * Builds one correlated WebSocket command request and guarantees pending
+     * command cleanup if the waiting Effect is interrupted.
+     */
+    private buildCommandRequest;
+    /** Removes one pending command and clears its timer before settlement. */
+    private settlePendingCommand;
+}
+/**
+ * Builds the WebSocket stream URL with participant identity and capabilities in
+ * query parameters.
+ */
+export declare function buildParticipantRuntimeStreamUrl(config: ParticipantRuntimeClientConfig): string;
+/**
+ * Resolves the durable resume sequence as the higher of the configured
+ * `afterSeq` floor and the persisted cursor, treating a missing or non-finite
+ * stored value as zero. The resume point is never below `afterSeq`.
+ */
+export declare function resolveResumeSeq(afterSeq: number, storedSeq: number | null): number;
+/** Resolves and validates the finite command response timeout. */
+export declare function resolveCommandTimeoutMs(commandTimeoutMs: number | undefined): number;