@stateforge-labs/herdr-sdk 0.0.0-stage → 0.3.0

package/dist/herdr/client/types.d.ts

@@ -0,0 +1,150 @@
+import type { Preset, ProtocolPolicy } from '../../constants.js';
+import type { AdminNamespaces, CallOptions, ClientNamespaces, ENTRY_METHODS, Method, PromptNamespaces, ReadOnlyContentNamespaces, ReadOnlyNamespaces, SessionsReaderNamespaces } from '../generated/index.js';
+import type { ServerCapabilities } from '../generated/results.js';
+import type { EnvMap } from '../wire/socket-path.js';
+import type { OnCall, ParamsOf, ResultOf, UnknownFrame } from '../wire/types.js';
+import type { Hold } from './held.js';
+import type { Subscribe } from './subscribe.js';
+import type { WatchFn } from './watch.js';
+export type { CallOptions } from '../generated/index.js';
+/** Options of every connect function. */
+export interface ConnectOptions {
+    /** Explicit path; else HERDR_SOCKET; else ~/.config/herdr/herdr.sock. */
+    readonly socketPath?: string | undefined;
+    /** Per-request timeout; default Timeout.DefaultMs (10 s). Long-poll calls add their own timeout_ms (plan 3.6). */
+    readonly timeoutMs?: number | undefined;
+    /** Exact (default) or Minimum. A mismatch rejects with ProtocolMismatchError. */
+    readonly protocolPolicy?: ProtocolPolicy | undefined;
+    readonly onCall?: OnCall | undefined;
+    /**
+     * Called once per UnknownFrame on every subscription of this client, including the ones watch() and watchPaneSet()
+     * open (HERDR-ADR-0016 P3). When a per-call onUnknown is also set, both fire: this one first, then the per-call one.
+     * subscribe is the only place that calls them; watch() forwards its own onUnknown to subscribe and never calls either.
+     */
+    readonly onUnknown?: ((frame: UnknownFrame) => void) | undefined;
+    /** Environment used to find the socket; tests pass their own, so nothing reads process.env. */
+    readonly env?: EnvMap | undefined;
+}
+/** What the server advertised in its pong. A missing key is not advertised. */
+export type ClientCapabilities = Readonly<Partial<ServerCapabilities>>;
+/** Server facts fixed at connect time. */
+export interface ServerInfo {
+    readonly protocol: number;
+    readonly version: string;
+}
+/**
+ * Members every client has. close() is local: later calls reject with HerdrTransportError without contacting herdr,
+ * and it aborts ClientTransport.closed, which ends every live subscription, watch loop and held connection of this
+ * client (each one closes as if its own close() ran). Idempotent.
+ */
+export interface ClientBase {
+    readonly capabilities: ClientCapabilities;
+    /** Not `server`: that name is herdr's `server.*` namespace. */
+    readonly serverInfo: ServerInfo;
+    close(): void;
+}
+/**
+ * The connection settings connectCore resolved once (socket path from options/env, timeout default applied). P2b
+ * passes them to SubscribeDeps and HoldDeps; nobody resolves them a second time. Not on public clients.
+ */
+export interface ClientTransport {
+    readonly socketPath: string;
+    readonly timeoutMs: number;
+    readonly onCall?: OnCall | undefined;
+    readonly onUnknown?: ((frame: UnknownFrame) => void) | undefined;
+    /** Aborted by close(). */
+    readonly closed: AbortSignal;
+}
+/** The generic escape hatch, limited to the methods `M` of the entry. Not on read-only or prompt clients. */
+export interface Caller<M extends Method> {
+    call<K extends M>(method: K, params: ParamsOf<K>, options?: CallOptions): Promise<ResultOf<K>>;
+}
+/** Streaming members (on clients whose class set includes L). */
+export interface Streaming {
+    readonly watch: WatchFn;
+}
+/** Held connections (on clients whose class set includes C). */
+export interface Holding {
+    readonly hold: Hold;
+}
+/** Replaces the generated `events.subscribe` placeholder with the real Subscribe (array of specs -> EventSubscription). */
+export type WithSubscribe<N extends {
+    events: object;
+}> = Omit<N, 'events'> & {
+    readonly events: Omit<N['events'], 'subscribe'> & {
+        readonly subscribe: Subscribe;
+    };
+};
+/** Method names of one entry, from the generated ENTRY_METHODS table. */
+export type EntryName = keyof typeof ENTRY_METHODS;
+export type EntryMethod<E extends EntryName> = (typeof ENTRY_METHODS)[E][number];
+/** P2a's client: ping, protocol policy, capabilities, gate, call(), and the resolved transport. Composed into every public client by P2b. */
+export type CoreClient = ClientBase & Caller<Method> & {
+    readonly transport: ClientTransport;
+};
+/** `connect()` (`.`): R-meta, R-content, W, I, H, L, C; no D, S, X. */
+export type Client = WithSubscribe<ClientNamespaces> & ClientBase & Caller<EntryMethod<'client'>> & Streaming & Holding;
+/** `connectAdmin()` (`/admin`): all methods. */
+export type AdminClient = WithSubscribe<AdminNamespaces> & ClientBase & Caller<Method> & Streaming & Holding;
+/** `connectReadOnly()`: R-meta + L. No call(), no writes. */
+export type ReadOnlyClient = WithSubscribe<ReadOnlyNamespaces> & ClientBase & Streaming;
+/** `connectReadOnly({ content: true })`: adds R-content. */
+export type ReadOnlyContentClient = WithSubscribe<ReadOnlyContentNamespaces> & ClientBase & Streaming;
+/** `connectPrompt()`: R-meta + agent.prompt. */
+export type PromptClient = PromptNamespaces & ClientBase;
+/** `connectReadOnly({ preset: Presets.SessionsReader })`: exactly PRESET_METHODS.SessionsReader. */
+export type SessionsReaderClient = SessionsReaderNamespaces & ClientBase;
+/** Options of connectReadOnly without a preset. `methods` narrows at runtime only; the type stays ReadOnlyClient. */
+export interface ReadOnlyOptions extends ConnectOptions {
+    readonly content?: boolean | undefined;
+    readonly methods?: readonly EntryMethod<'readOnlyContent'>[] | undefined;
+}
+export interface PresetOptions extends ConnectOptions {
+    readonly preset: Preset;
+}
+/** P2a: socket, ping, protocol policy, capabilities. Implemented by client/connect-core.ts. */
+export type ConnectCore = (options?: ConnectOptions) => Promise<CoreClient>;
+/** P2b. Implemented by client/connect.ts. */
+export type Connect = (options?: ConnectOptions) => Promise<Client>;
+/** P2b. Implemented by client/scoped/connect-admin.ts. */
+export type ConnectAdmin = (options?: ConnectOptions) => Promise<AdminClient>;
+/** P2b. Implemented by client/scoped/connect-prompt.ts. */
+export type ConnectPrompt = (options?: ConnectOptions) => Promise<PromptClient>;
+/** P2b. Implemented by client/scoped/connect-read-only.ts. Overloads: preset, content, default. */
+export interface ConnectReadOnly {
+    (options: PresetOptions): Promise<SessionsReaderClient>;
+    (options: ReadOnlyOptions & {
+        readonly content: true;
+    }): Promise<ReadOnlyContentClient>;
+    (options?: ReadOnlyOptions): Promise<ReadOnlyClient>;
+}
+/** Sends one allowed method; the tree calls it for every leaf. Applies the gate, long-poll timeout and allow-list. */
+export type Invoke = (method: Method, params: unknown, options?: CallOptions) => Promise<unknown>;
+/** A namespace tree before it is typed as one of the generated namespace interfaces (plain nested objects). */
+export type NamespaceTree = {
+    readonly [segment: string]: NamespaceTree | ((params?: unknown, options?: CallOptions) => Promise<unknown>);
+};
+/**
+ * Builds the nested tree once, eagerly, from exactly `allowed` (no Proxy, no getters; plan 3.3).
+ * `events.subscribe` is NOT a leaf of the tree; the composer adds Subscribe. Implemented by client/scoped/namespace-tree.ts (P2b).
+ * Also the builder of held connections: hold() calls it with the held list and an Invoke over the dedicated
+ * connection. There is no second tree builder.
+ */
+export type BuildNamespaceTree = (allowed: ReadonlySet<Method>, invoke: Invoke) => NamespaceTree;
+/**
+ * The allow-list of one scoped client: `base` is the entry's list (ENTRY_METHODS[entry], or a preset's list), narrowed by
+ * `methods`. The caller passes the list it needs, so this module never imports the table of every entry (plan 10.1 step 2).
+ * Implemented by client/scoped/allowed-methods.ts.
+ */
+export type AllowedMethods = (base: readonly Method[], options?: {
+    readonly methods?: readonly Method[];
+}) => ReadonlySet<Method>;
+/**
+ * The stream members of one client: events.subscribe, the watch factory and hold. They are loaded on first use
+ * (client/scoped/lazy-streams.ts), so a client that never streams does not carry their code.
+ */
+export interface StreamMembers {
+    readonly subscribe: Subscribe;
+    readonly watch: WatchFn;
+    readonly hold: Hold;
+}

package/dist/herdr/client/types.js

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

package/dist/herdr/client/watch-pane-set.d.ts

@@ -0,0 +1,34 @@
+import { EventKind, SubscriptionType } from '../generated/index.js';
+import type { DecodedFrame } from '../wire/types.js';
+import type { PerPaneSubscription, PerPaneSubscriptionType, WatchPaneSet } from './watch.js';
+import type { QueueOptions } from './subscribe.js';
+export interface PaneLifecycle {
+    readonly event: typeof EventKind.PaneCreated | typeof EventKind.PaneClosed;
+    readonly paneId: string;
+}
+export declare function lifecycleOf(frame: DecodedFrame): PaneLifecycle | undefined;
+export interface PaneSet {
+    /** The pane ids now in the set. */
+    ids(): string[];
+    /** Adds the pane and returns its signal (aborts on remove or when the parent aborts); undefined when it was already present. */
+    add(paneId: string): AbortSignal | undefined;
+    /** Removes the pane and aborts its subscriptions; false when it was not in the set. */
+    remove(paneId: string): boolean;
+}
+export declare function createPaneSet(parent: AbortSignal): PaneSet;
+export type PaneIdOnlyType = Exclude<PerPaneSubscriptionType, typeof SubscriptionType.PaneOutputMatched>;
+export declare const DEFAULT_PANE_TYPES: readonly PaneIdOnlyType[];
+export declare function checkedPaneTypes(types: readonly PerPaneSubscriptionType[]): readonly PaneIdOnlyType[];
+export declare function perPaneSpecs(paneId: string, types: readonly PaneIdOnlyType[]): readonly PerPaneSubscription[];
+export interface ReplayBuffer<T> {
+    /** Queues one item. Returns false once the buffer has stopped (overflow under Fail, or end/fail already ran). */
+    push(item: T): boolean;
+    /** Ends the buffer normally: takers get the queued items, then done. Idempotent. */
+    end(): void;
+    /** Ends the buffer with an error, after the queued items. Idempotent. */
+    fail(error: unknown): void;
+    /** The next item in arrival order. Rejects with the failure once the queue is empty; done after end() once empty. */
+    take(): Promise<IteratorResult<T>>;
+}
+export declare function createReplayBuffer<T>(queue?: QueueOptions): ReplayBuffer<T>;
+export declare const watchPaneSet: WatchPaneSet;

package/dist/herdr/client/watch-pane-set.js

@@ -0,0 +1,271 @@
+// Role: watchPaneSet(): the set of panes, one per-pane subscription each, and the replay buffer that orders their changes.
+// Informs HERDR-ADR-0016, plan 3.6, HERDR-ADR-0007; merged by HERDR-ADR-0021 from pane-event.ts, pane-set.ts, per-pane-specs.ts, replay-buffer.ts, watch-pane-set.ts.
+import { UNKNOWN_EVENT, PER_PANE_SUBSCRIPTION_TYPES, WatchText, Overflow, PANE_LIFECYCLE_SUBSCRIPTION_TYPES, PaneSetKind, WatchKind } from '../../constants.js';
+import { EventKind, SubscriptionType } from '../generated/index.js';
+import { linkSignal, createBackoffState, resolveBackoff, defaultSleep, forwardFrames, sleepOrAbort, bareSpecs, createWatch } from './watch.js';
+import { UnsupportedWatchError, HerdrTransportError } from '../errors.js';
+export function lifecycleOf(frame) {
+    if (frame.event === UNKNOWN_EVENT) {
+        return undefined;
+    }
+    if (frame.event === EventKind.PaneCreated && frame.data.type === EventKind.PaneCreated) {
+        return { event: EventKind.PaneCreated, paneId: frame.data.pane.pane_id };
+    }
+    if (frame.event === EventKind.PaneClosed && frame.data.type === EventKind.PaneClosed) {
+        return { event: EventKind.PaneClosed, paneId: frame.data.pane_id };
+    }
+    return undefined;
+}
+export function createPaneSet(parent) {
+    const controllers = new Map();
+    return {
+        ids() {
+            return [...controllers.keys()];
+        },
+        add(paneId) {
+            if (controllers.has(paneId)) {
+                return undefined;
+            }
+            const controller = new AbortController();
+            controllers.set(paneId, controller);
+            return linkSignal(controller.signal, parent);
+        },
+        remove(paneId) {
+            const controller = controllers.get(paneId);
+            if (controller === undefined) {
+                return false;
+            }
+            controllers.delete(paneId);
+            controller.abort();
+            return true;
+        },
+    };
+}
+function isPaneIdOnly(type) {
+    return type !== SubscriptionType.PaneOutputMatched;
+}
+// watchPaneSet's default types: PER_PANE_SUBSCRIPTION_TYPES minus pane.output_matched (open issue 8).
+export const DEFAULT_PANE_TYPES = PER_PANE_SUBSCRIPTION_TYPES.filter(isPaneIdOnly);
+// Narrows the caller's types to the ones this lane can subscribe to; a pane.output_matched request is refused, not dropped.
+export function checkedPaneTypes(types) {
+    return types.map((type) => {
+        if (isPaneIdOnly(type)) {
+            return type;
+        }
+        throw new UnsupportedWatchError(WatchText.OutputMatchUnsupported);
+    });
+}
+export function perPaneSpecs(paneId, types) {
+    return types.map((type) => ({ type, pane_id: paneId }));
+}
+export function createReplayBuffer(queue) {
+    const items = [];
+    let ending;
+    let waiter;
+    // Serves the single waiting taker as soon as something changed: a queued item first, then the failure, then the end.
+    function wake() {
+        if (waiter === undefined) {
+            return;
+        }
+        const pending = waiter;
+        const next = items.shift();
+        if (next !== undefined) {
+            waiter = undefined;
+            pending.resolve({ value: next, done: false });
+            return;
+        }
+        if (ending?.failed === true) {
+            waiter = undefined;
+            pending.reject(ending.error);
+            return;
+        }
+        if (ending !== undefined) {
+            waiter = undefined;
+            pending.resolve({ value: undefined, done: true });
+        }
+    }
+    function stop(next) {
+        if (ending !== undefined) {
+            return;
+        }
+        ending = next;
+        wake();
+    }
+    return {
+        push(item) {
+            if (ending !== undefined) {
+                return false;
+            }
+            if (queue !== undefined && items.length >= queue.max) {
+                if (queue.overflow === Overflow.Fail) {
+                    items.length = 0;
+                    stop({ failed: true, error: new HerdrTransportError(WatchText.ReplayOverflow(queue.max)) });
+                    return false;
+                }
+                items.shift();
+            }
+            items.push(item);
+            wake();
+            return true;
+        },
+        end() {
+            stop({ failed: false });
+        },
+        fail(error) {
+            stop({ failed: true, error });
+        },
+        take() {
+            return new Promise((resolve, reject) => {
+                waiter = { resolve, reject };
+                wake();
+            });
+        },
+    };
+}
+export const watchPaneSet = (source, options = {}) => {
+    // Checked when watchPaneSet is called, so a pane.output_matched request fails at the call site, not inside the loop.
+    const types = checkedPaneTypes(options.types ?? DEFAULT_PANE_TYPES);
+    const controller = new AbortController();
+    return {
+        close() {
+            controller.abort();
+        },
+        [Symbol.asyncIterator]() {
+            return paneChanges(source, options, types, controller);
+        },
+    };
+};
+async function* paneChanges(source, options, types, controller) {
+    const signal = linkSignal(controller.signal, options.signal);
+    const output = createReplayBuffer();
+    const endOnAbort = () => output.end();
+    signal.addEventListener('abort', endOnAbort, { once: true });
+    const run = {
+        source,
+        options,
+        types,
+        signal,
+        output,
+        panes: createPaneSet(signal),
+        stop: () => controller.abort(),
+    };
+    followLifecycle(run);
+    try {
+        for (;;) {
+            const next = await output.take();
+            if (next.done === true || signal.aborted) {
+                return;
+            }
+            yield next.value;
+        }
+    }
+    finally {
+        signal.removeEventListener('abort', endOnAbort);
+        controller.abort();
+    }
+}
+// The lifecycle is a watch over pane.created and pane.closed; its snapshot is the list of pane ids.
+function followLifecycle(run) {
+    const lifecycle = createWatch(run.source.events.subscribe)({
+        snapshot: async () => (await run.source.pane.list()).panes.map((pane) => pane.pane_id),
+        subscriptions: bareSpecs(PANE_LIFECYCLE_SUBSCRIPTION_TYPES),
+        backoff: run.options.backoff,
+        sleep: run.options.sleep,
+        signal: run.signal,
+        onUnknown: run.options.onUnknown,
+    });
+    void pumpLifecycle(lifecycle, run);
+}
+// The lifecycle ends only when the iteration is closed or the client closed; either way every pane stops with it.
+async function pumpLifecycle(lifecycle, run) {
+    try {
+        for await (const change of lifecycle) {
+            applyChange(change, run);
+        }
+    }
+    finally {
+        run.stop();
+    }
+}
+function applyChange(change, run) {
+    if (change.kind === WatchKind.Live) {
+        syncPanes(change.snapshot, run);
+        return;
+    }
+    const lifecycle = lifecycleOf(change.frame);
+    if (lifecycle === undefined) {
+        return;
+    }
+    if (lifecycle.event === EventKind.PaneCreated) {
+        addPane(lifecycle.paneId, run);
+    }
+    else {
+        removePane(lifecycle.paneId, run);
+    }
+}
+// After a Live the set equals the listed panes: missing ones are added, panes no longer listed are removed.
+function syncPanes(listed, run) {
+    const current = run.panes.ids();
+    for (const paneId of listed) {
+        addPane(paneId, run);
+    }
+    for (const paneId of current) {
+        if (!listed.includes(paneId)) {
+            removePane(paneId, run);
+        }
+    }
+}
+function addPane(paneId, run) {
+    const paneSignal = run.panes.add(paneId);
+    if (paneSignal === undefined) {
+        return;
+    }
+    run.output.push({ kind: PaneSetKind.Added, paneId });
+    void followPane(paneId, paneSignal, run);
+}
+function removePane(paneId, run) {
+    if (run.panes.remove(paneId)) {
+        run.output.push({ kind: PaneSetKind.Removed, paneId });
+    }
+}
+// One pane's subscription. A failure resubscribes that pane with backoff while it is still in the set. A normal end that this pane did not ask for means the client closed, so the whole set stops.
+// A Sleep that fails for a reason other than the abort is passed to the consumer's iterator, never left as an unhandled rejection.
+async function followPane(paneId, paneSignal, run) {
+    const backoff = createBackoffState(resolveBackoff(run.options.backoff), Date.now);
+    const sleep = run.options.sleep ?? defaultSleep;
+    try {
+        while (!paneSignal.aborted) {
+            backoff.startCycle();
+            try {
+                await runPaneSubscription(paneId, paneSignal, run);
+                if (!paneSignal.aborted) {
+                    run.stop();
+                }
+                return;
+            }
+            catch {
+                if (paneSignal.aborted) {
+                    return;
+                }
+                await sleepOrAbort(sleep, backoff.delayAfterFailure(), paneSignal);
+            }
+        }
+    }
+    catch (error) {
+        run.output.fail(error);
+    }
+}
+// One subscribe and its frames until the subscription ends. Resolves on a normal end; rejects when the subscribe or the subscription failed.
+async function runPaneSubscription(paneId, paneSignal, run) {
+    const subscription = await run.source.events.subscribe(perPaneSpecs(paneId, run.types), {
+        signal: paneSignal,
+        queue: run.options.queue,
+        onUnknown: run.options.onUnknown,
+    });
+    try {
+        await forwardFrames(subscription, (frame) => run.output.push({ kind: PaneSetKind.Frame, paneId, frame }));
+    }
+    finally {
+        subscription.close();
+    }
+}

package/dist/herdr/client/watch.d.ts

@@ -0,0 +1,117 @@
+import { WatchKind } from '../../constants.js';
+import type { PaneSetKind } from '../../constants.js';
+import type { Subscription, SubscriptionType } from '../generated/index.js';
+import type { MethodPaneList } from '../generated/names/method.js';
+import type { DecodedFrame, ParamsOf, ResultOf, UnknownFrame } from '../wire/types.js';
+import type { EventSubscription, QueueOptions, Subscribe } from './subscribe.js';
+/** `Live` carries a fresh snapshot (first, and after every resubscribe); `Frame` a frame received after it. */
+export type WatchChange<S> = {
+    readonly kind: typeof WatchKind.Live;
+    readonly snapshot: S;
+} | {
+    readonly kind: typeof WatchKind.Frame;
+    readonly frame: DecodedFrame;
+};
+/** Resubscribe backoff: InitialMs doubling (Factor) to MaxMs, reset after StableResetMs up (constants Backoff). */
+export interface BackoffPolicy {
+    readonly initialMs: number;
+    readonly maxMs: number;
+    readonly factor: number;
+    readonly stableResetMs: number;
+}
+/** Injectable wait, so tests never sleep for real. Resolves after ms, or rejects/ends early when the signal aborts. */
+export type Sleep = (ms: number, signal: AbortSignal) => Promise<void>;
+export interface WatchOptions<S> {
+    /** Takes the present. Required: there is no subscribe-only watch (W5). */
+    readonly snapshot: (signal: AbortSignal) => Promise<S>;
+    /** Default: GLOBAL_SUBSCRIPTION_TYPES (constants.ts), every SubscriptionType that needs no pane_id. */
+    readonly subscriptions?: readonly Subscription[] | undefined;
+    readonly queue?: QueueOptions | undefined;
+    readonly backoff?: Partial<BackoffPolicy> | undefined;
+    readonly sleep?: Sleep | undefined;
+    readonly signal?: AbortSignal | undefined;
+    /** Forwarded to subscribe as SubscribeOptions.onUnknown; watch() itself never calls it (no double count). */
+    readonly onUnknown?: ((frame: UnknownFrame) => void) | undefined;
+}
+/**
+ * The watch loop: subscribe -> ack -> snapshot -> yield Live -> replay the frames that arrived between ack and snapshot
+ * reply (the consumer's fold must be idempotent) -> live frames. Any close: resubscribe + resnapshot with backoff.
+ * close() (or abort) ends the iteration normally. Never yields a Frame before the first Live.
+ */
+export interface Watch<S> extends AsyncIterable<WatchChange<S>> {
+    close(): void;
+}
+/** `herdr.watch(options)`. Synchronous: the loop starts on the first iteration. */
+export type WatchFn = <S>(options: WatchOptions<S>) => Watch<S>;
+/** Builds watch() of one client from its subscribe. Implemented by client/watch/watch.ts (P4b). */
+export type CreateWatch = (subscribe: Subscribe) => WatchFn;
+/** The per-pane subscription specs (W6: the 3 types that need pane_id). */
+export type PerPaneSubscription = Extract<Subscription, {
+    pane_id: string;
+}>;
+export type PerPaneSubscriptionType = PerPaneSubscription['type'];
+/** A pane joined or left the set, or a per-pane frame arrived for one pane. */
+export type PaneSetChange = {
+    readonly kind: typeof PaneSetKind.Added;
+    readonly paneId: string;
+} | {
+    readonly kind: typeof PaneSetKind.Removed;
+    readonly paneId: string;
+} | {
+    readonly kind: typeof PaneSetKind.Frame;
+    readonly paneId: string;
+    readonly frame: DecodedFrame;
+};
+/** The smallest client watchPaneSet needs; every ReadOnlyClient, Client and AdminClient satisfies it. */
+export interface PaneSetSource {
+    readonly pane: {
+        list(params?: ParamsOf<typeof MethodPaneList>): Promise<ResultOf<typeof MethodPaneList>>;
+    };
+    readonly events: {
+        subscribe: Subscribe;
+    };
+}
+export interface WatchPaneSetOptions {
+    /** Which per-pane types to subscribe for each pane (default: PER_PANE_SUBSCRIPTION_TYPES, constants.ts). */
+    readonly types?: readonly PerPaneSubscriptionType[] | undefined;
+    /** Bounds each per-pane subscription's queue (passed to subscribe). */
+    readonly queue?: QueueOptions | undefined;
+    /** Forwarded to every per-pane subscribe as SubscribeOptions.onUnknown. */
+    readonly onUnknown?: ((frame: UnknownFrame) => void) | undefined;
+    readonly backoff?: Partial<BackoffPolicy> | undefined;
+    readonly sleep?: Sleep | undefined;
+    readonly signal?: AbortSignal | undefined;
+}
+export interface PaneSetWatch extends AsyncIterable<PaneSetChange> {
+    close(): void;
+}
+/**
+ * Lists panes, subscribes pane by pane to the per-pane types, and keeps the set with pane.created / pane.closed
+ * (W6). Implemented by client/watch/watch-pane-set.ts (P4b); the Effect twin wraps it (P6a).
+ */
+export type WatchPaneSet = (source: PaneSetSource, options?: WatchPaneSetOptions) => PaneSetWatch;
+/** Re-exported for implementers that hold a subscription per pane. */
+export type { EventSubscription };
+export declare const defaultSleep: Sleep;
+export declare function sleepOrAbort(sleep: Sleep, ms: number, signal: AbortSignal): Promise<void>;
+export declare function linkSignal(own: AbortSignal, parent: AbortSignal | undefined): AbortSignal;
+export declare function forwardFrames(subscription: EventSubscription, accept: (frame: DecodedFrame) => boolean): Promise<void>;
+export declare function bareSpecs(types: readonly SubscriptionType[]): readonly Subscription[];
+export declare function resolveBackoff(partial?: Partial<BackoffPolicy>): BackoffPolicy;
+export declare function nextDelayMs(policy: BackoffPolicy, attempt: number): number;
+export interface BackoffState {
+    /** Marks the start of a cycle, so the next failure can tell whether it stayed up long enough to reset. */
+    startCycle(): void;
+    /** Records a failed cycle and returns the delay before the next attempt. */
+    delayAfterFailure(): number;
+}
+export declare function createBackoffState(policy: BackoffPolicy, now: () => number): BackoffState;
+export interface CycleInput<S> {
+    readonly subscribe: Subscribe;
+    readonly specs: readonly Subscription[];
+    readonly options: WatchOptions<S>;
+    readonly signal: AbortSignal;
+}
+export declare function runCycle<S>(input: CycleInput<S>): AsyncGenerator<WatchChange<S>, void, undefined>;
+export declare const createWatch: CreateWatch;
+export declare function createWatchWithClock(subscribe: Subscribe, now: () => number): WatchFn;