@naswerks/periscope 1.0.0

package/dist/control/frames.js

@@ -0,0 +1,441 @@
+import { isRefusalReason } from '../core/refusal.js';
+/**
+ * Bumped when a change is not backward-compatible. Exchanged in the hello handshake.
+ *
+ * The rule: a new payload kind, a new member on an existing kind, a member whose nullability
+ * changed, or a new hello member is a bump, even when the change is additive in practice. The
+ * handshake's job is to let a peer refuse a version it does not know rather than to guess whether
+ * a difference happened to be survivable: every declared member is required on the wire, so a
+ * peer one version behind refuses the whole frame, and because refusals are not acknowledged that
+ * refusal would be a permanent silent wedge on the session lane. The handshake refuses by version
+ * instead, by name, once. A new value in the open `capabilities` list is not a bump; a new
+ * `RefusalReason` is one, because a strict encoder on the other side must learn it first.
+ *
+ * Every bump re-approves `contracts/wire-vectors/` (`npm run contracts:update`) and regenerates
+ * any consumer's readers.
+ */
+export const PROTOCOL_VERSION = 9;
+/**
+ * The oldest protocol version this build still speaks. A hello advertises the window
+ * `[PROTOCOL_VERSION_MIN, PROTOCOL_VERSION]` beside `protocolVersion`; the controller answers with
+ * its choice inside the overlap and the host accepts any version in its own window. The window
+ * opens at the first negotiated version; from the next bump on it is one minor wide, the version
+ * before the current one staying supported for one release. A hello with no range does not
+ * decode, so a version older than the first negotiated one cannot be inside the window.
+ */
+export const PROTOCOL_VERSION_MIN = 9;
+/**
+ * A frame larger than this is refused by the codec.
+ *
+ * This is the mechanical half of "commands only, never payloads": bulk bytes cannot ride the link
+ * even by accident, because a frame carrying them will not encode. The refusal names the bulk lane
+ * so the failure teaches the fix rather than just reporting a size.
+ */
+export const MAX_FRAME_BYTES = 64 * 1024;
+/** Build the update carrying a transition. The only supported way to put one on the wire. */
+export function stateTransitionUpdate(transition) {
+    const body = { update: 'state_transition', transition };
+    return { kind: 'session_update', body: body };
+}
+/**
+ * Read a transition back out, or null when the body is some other kind of update.
+ *
+ * Null rather than a throw: an older host receiving a body it does not model must keep going, and
+ * a consumer that gets null knows to leave the frame alone rather than to treat it as corrupt.
+ */
+export function readStateTransition(body) {
+    const update = body;
+    if (update.update !== 'state_transition')
+        return null;
+    const transition = update.transition;
+    if (transition === undefined || typeof transition.seq !== 'number' || transition.cause === undefined) {
+        return null;
+    }
+    return transition;
+}
+/** Build the update carrying an agent message. The only supported way to put one on the wire. */
+export function agentMessageUpdate(message) {
+    const body = { update: 'agent_message', message };
+    return { kind: 'session_update', body: body };
+}
+/** Read a forwarded message back out, or null when the body is some other kind of update. */
+export function readAgentMessage(body) {
+    const update = body;
+    if (update.update !== 'agent_message')
+        return null;
+    const message = update.message;
+    if (typeof message !== 'object' || message === null || Array.isArray(message))
+        return null;
+    return message;
+}
+/** Build the update carrying a refusal about the peer's own traffic. The only supported way. */
+export function wireRefusalUpdate(refusal, expected, received) {
+    const body = { update: 'wire_refusal', refusal, expected, received };
+    return { kind: 'session_update', body: body };
+}
+/**
+ * Read a wire refusal back out, or null when the body is some other kind of update.
+ *
+ * Null rather than a throw, for the same reason `readStateTransition` returns null: a peer that does
+ * not model this member must keep going rather than treat the frame as corrupt. A v1 controller
+ * reaching this body gets null from all three readers and leaves the frame alone — which is a
+ * degraded outcome, not a broken one, and is the honest cost the version bump exists to announce.
+ */
+export function readWireRefusal(body) {
+    const update = body;
+    if (update.update !== 'wire_refusal')
+        return null;
+    if (typeof update.expected !== 'number' || typeof update.received !== 'number')
+        return null;
+    const refusal = update.refusal;
+    if (refusal === undefined || typeof refusal.reason !== 'string' || typeof refusal.detail !== 'string') {
+        return null;
+    }
+    return {
+        update: 'wire_refusal',
+        refusal: { reason: refusal.reason, detail: refusal.detail },
+        expected: update.expected,
+        received: update.received,
+    };
+}
+/**
+ * Build a delta carrying one message verbatim.
+ *
+ * The body is the same shape a `session_update` carries, deliberately: the lanes differ in what
+ * losing a frame costs, not in what a frame says, so `readAgentMessage` reads either. A consumer
+ * that had to parse two shapes for one idea would have been handed the drift this package's
+ * vocabulary rules exist to prevent.
+ */
+export function agentMessageDelta(message) {
+    const body = { update: 'agent_message', message };
+    return { kind: 'session_delta', body: body };
+}
+/**
+ * Build a `session_new`. The only supported way to put one on the wire.
+ *
+ * It exists for the reason `stateTransitionUpdate` does, and for one more. The wire's rule is that
+ * absent is `null` and never an omitted property, but a hand-written literal makes that a
+ * discipline every author has to remember, and the moment one is forgotten the frame carries
+ * `undefined`, which `JSON.stringify` deletes. The field then arrives absent, and "absent" and
+ * "explicitly unset" are the two states this file spends its opening paragraph refusing to
+ * conflate. Passing `asked` as a partial and filling every remaining key with `null` here makes
+ * the rule a property of construction instead of a rule in a comment.
+ *
+ * The argument is a partial of the wire type; what comes out is fully populated. So a caller writes
+ * only what it means, and no caller can produce a frame that says nothing where it meant nothing.
+ */
+export function sessionNew(cwd, asked = {}) {
+    return {
+        kind: 'session_new',
+        cwd,
+        workspaceKey: asked.workspaceKey ?? null,
+        correlationId: asked.correlationId ?? null,
+        request: asked.request ?? null,
+        gate: asked.gate ?? null,
+    };
+}
+/**
+ * Build a `session_new.request`. Same argument as `sessionNew`: every unstated key becomes `null`.
+ *
+ * The partial is the convenience and the full object is the contract. Nothing about the wire is
+ * relaxed here: a controller in another language builds the whole object, and this is the shortcut
+ * for the one that happens to be written in this one.
+ */
+export function sessionNewRequest(asked = {}) {
+    return {
+        resume: asked.resume ?? null,
+        fork: asked.fork ?? null,
+        settingSources: asked.settingSources ?? null,
+        plugins: asked.plugins ?? null,
+        mcpServers: asked.mcpServers ?? null,
+        strictMcpConfig: asked.strictMcpConfig ?? null,
+        includePartialMessages: asked.includePartialMessages ?? null,
+        thinking: asked.thinking ?? null,
+        forwardSubagentText: asked.forwardSubagentText ?? null,
+        env: asked.env ?? null,
+        model: asked.model ?? null,
+        systemPrompt: asked.systemPrompt ?? null,
+        effort: asked.effort ?? null,
+        permissionMode: asked.permissionMode ?? null,
+    };
+}
+/**
+ * Every key a `session_new.request` carries, as data, so a check can enumerate them at run time.
+ *
+ * It exists so a pin cannot quietly stop covering something. The egress pin walks a populated
+ * request looking for a field that could name a transcript destination, and a walk is only as
+ * complete as the object it is handed: a hand-built fixture silently stops being full the moment a
+ * later change adds a key, and the pin then passes while covering less, with nothing to say so.
+ *
+ * `satisfies Record<keyof SessionNewRequest, true>` makes the compiler the enforcer: adding a field
+ * to the type without adding it here does not build. So the pin's fixture is checked against a list
+ * that cannot fall behind the type it describes.
+ */
+export const SESSION_NEW_REQUEST_KEYS = {
+    resume: true,
+    fork: true,
+    settingSources: true,
+    plugins: true,
+    mcpServers: true,
+    strictMcpConfig: true,
+    includePartialMessages: true,
+    thinking: true,
+    forwardSubagentText: true,
+    env: true,
+    model: true,
+    systemPrompt: true,
+    effort: true,
+    permissionMode: true,
+};
+/** The same, for the payload itself. Same argument, one level up. */
+export const SESSION_NEW_KEYS = {
+    kind: true,
+    cwd: true,
+    workspaceKey: true,
+    correlationId: true,
+    request: true,
+    gate: true,
+};
+/** Build a `bulk_delivered`. Fills the stat pair with null so an absent value is stated, not deleted. */
+export function bulkDelivered(deliveryId, byteCount, stat = {}) {
+    return {
+        kind: 'bulk_delivered',
+        deliveryId,
+        byteCount,
+        sizeBytes: stat.sizeBytes ?? null,
+        mtimeMs: stat.mtimeMs ?? null,
+    };
+}
+/**
+ * The most releases one `workspace_release_bulk` may carry: one inventory page, so a controller
+ * can clean what it was just shown in one ask, and an answer of that size stays well under the
+ * frame cap.
+ */
+export const MAX_BULK_RELEASES = 25;
+/** Build a `workspace_release`. A string target is a key; `{ path }` addresses by path. */
+export function workspaceRelease(requestId, target, flags = {}) {
+    return {
+        kind: 'workspace_release',
+        requestId,
+        workspaceKey: typeof target === 'string' ? target : null,
+        path: typeof target === 'string' ? null : target.path,
+        deleteBranch: flags.deleteBranch ?? false,
+        force: flags.force ?? false,
+    };
+}
+/** Build a `workspace_release_result`. Every omitted member takes the released-or-absent value. */
+export function workspaceReleaseResult(requestId, outcome = {}) {
+    return { kind: 'workspace_release_result', requestId, ...workspaceReleaseEntryResult(outcome) };
+}
+/** Build one entry result with the released-or-absent defaults. */
+export function workspaceReleaseEntryResult(outcome = {}) {
+    return {
+        workspaceKey: outcome.workspaceKey ?? null,
+        path: outcome.path ?? null,
+        directoryRemoved: outcome.directoryRemoved ?? false,
+        branchDeleted: outcome.branchDeleted ?? false,
+        refusal: outcome.refusal ?? null,
+    };
+}
+/** Build a `workspace_release_bulk`. */
+export function workspaceReleaseBulk(requestId, releases) {
+    return { kind: 'workspace_release_bulk', requestId, releases };
+}
+/** Build a `workspace_release_bulk_result`. */
+export function workspaceReleaseBulkResult(requestId, results) {
+    return { kind: 'workspace_release_bulk_result', requestId, results };
+}
+/**
+ * The most entries one `host_configure` may carry: the closed config key set is smaller than this,
+ * so a legal ask never meets the bound and an ask past it is malformed rather than large.
+ */
+export const MAX_CONFIGURE_ENTRIES = 8;
+/**
+ * How many worktrees one `workspace_list_result` carries. A path is bounded at 1000 characters, a
+ * branch at 400 and a key at 200, so a full page stays under the frame cap with the same margin
+ * the transcript page keeps.
+ */
+export const WORKSPACE_PAGE_SIZE = 25;
+/**
+ * How many entries one `transcript_list_result` carries.
+ *
+ * Bounded so the frame stays well under `MAX_FRAME_BYTES` (64 KiB): an entry is a slug (measured
+ * up to about 80 characters on one real 139-slug corpus), a 36-character session id and two
+ * integers, comfortably under 300 bytes of JSON each, so 100 entries is under half the cap even
+ * with slugs twice as long as any measured one.
+ */
+export const TRANSCRIPT_PAGE_SIZE = 100;
+/**
+ * The bulk-lane locator namespace for a transcript read: `claude-transcript:{projectSlug}/{sessionId}`.
+ * A `bulk_request.what` that a host resolves to the agent CLI's own transcript files starts with
+ * this prefix; the slug is the CLI's flattened project directory name and is opaque.
+ */
+export const TRANSCRIPT_WHAT_PREFIX = 'claude-transcript:';
+/** Build a `workspace_list`. The only supported way to put one on the wire. */
+export function workspaceList(requestId, fromIndex = 0) {
+    return { kind: 'workspace_list', requestId, fromIndex };
+}
+/** Build a `workspace_list_result`. Fills `refusal` with null, the answered page. */
+export function workspaceListResult(requestId, entries, page, refusal) {
+    return {
+        kind: 'workspace_list_result',
+        requestId,
+        entries,
+        totalCount: page.totalCount,
+        nextIndex: page.nextIndex ?? null,
+        defaultBranch: page.defaultBranch ?? null,
+        refusal: refusal ?? null,
+    };
+}
+/** Build a `host_configure`. The only supported way to put one on the wire. */
+export function hostConfigure(requestId, entries) {
+    return { kind: 'host_configure', requestId, entries };
+}
+/** Build a `host_configure_result`. Fills `refusal` with null, the applied answer. */
+export function hostConfigureResult(requestId, configuration, overriddenByEnvironment, refusal, pendingRestart = []) {
+    return {
+        kind: 'host_configure_result',
+        requestId,
+        configuration,
+        overriddenByEnvironment,
+        pendingRestart,
+        refusal: refusal ?? null,
+    };
+}
+/** Build a `session_list`. The only supported way to put one on the wire. */
+export function sessionList(requestId) {
+    return { kind: 'session_list', requestId };
+}
+/** Build a `session_list_result`. */
+export function sessionListResult(requestId, sessions, counts) {
+    return {
+        kind: 'session_list_result',
+        requestId,
+        sessions,
+        liveCount: counts.liveCount,
+        provisioningCount: counts.provisioningCount,
+    };
+}
+/** Build a `transcript_list`. `fromIndex` defaults to the start. */
+export function transcriptList(requestId, fromIndex = 0) {
+    return { kind: 'transcript_list', requestId, fromIndex };
+}
+/** Build a `transcript_list_result`. Fills `nextIndex` with null so absence is stated, not deleted. */
+export function transcriptListResult(requestId, entries, totals) {
+    return {
+        kind: 'transcript_list_result',
+        requestId,
+        entries,
+        totalCount: totals.totalCount,
+        nextIndex: totals.nextIndex ?? null,
+    };
+}
+/** Build a `transcript_tail`. Fills `needle` with null, meaning "any user-text entry". */
+export function transcriptTail(requestId, projectSlug, sessionId, fromOffset, needle) {
+    return { kind: 'transcript_tail', requestId, projectSlug, sessionId, fromOffset, needle: needle ?? null };
+}
+/** Build a `transcript_tail_result`. Fills the stat pair with null so absence is stated. */
+export function transcriptTailResult(requestId, answer) {
+    return {
+        kind: 'transcript_tail_result',
+        requestId,
+        found: answer.found,
+        absent: answer.absent,
+        newOffset: answer.newOffset,
+        sizeBytes: answer.sizeBytes ?? null,
+        mtimeMs: answer.mtimeMs ?? null,
+    };
+}
+/** Build a `transcript_failed`. */
+export function transcriptFailed(requestId, refusal) {
+    return { kind: 'transcript_failed', requestId, refusal };
+}
+// ---------------------------------------------------------------------------
+// The repository read: a controller reading the operator's checkout, jailed and bounded.
+// ---------------------------------------------------------------------------
+/**
+ * How many entries one `repository_list_result` carries. A directory with more than this many
+ * children is listed to the cap and marked `truncated`; names are bounded by the filesystem, so a
+ * full page stays well under the frame cap.
+ */
+export const MAX_REPOSITORY_ENTRIES = 500;
+/**
+ * The most text one `repository_read_result` carries. The frame cap is 64 KiB and the envelope plus
+ * JSON escaping must fit inside it, so the text is bounded below the cap with margin; a longer file
+ * is answered to this many bytes and marked `truncated`.
+ */
+export const MAX_REPOSITORY_READ_BYTES = 48 * 1024;
+/** Build a `repository_list`. The only supported way to put one on the wire. */
+export function repositoryList(requestId, path = '') {
+    return { kind: 'repository_list', requestId, path };
+}
+/** Build a `repository_list_result`. Fills `refusal` with null, the listed answer. */
+export function repositoryListResult(requestId, entries, truncated = false, refusal) {
+    return { kind: 'repository_list_result', requestId, entries, truncated, refusal: refusal ?? null };
+}
+/** Build a `repository_read`. Fills `maxBytes` with the cap. */
+export function repositoryRead(requestId, path, maxBytes = MAX_REPOSITORY_READ_BYTES) {
+    return { kind: 'repository_read', requestId, path, maxBytes };
+}
+/** Build a `repository_read_result`. Fills `refusal` with null, the read answer. */
+export function repositoryReadResult(requestId, read, refusal) {
+    return {
+        kind: 'repository_read_result',
+        requestId,
+        text: read.text,
+        sizeBytes: read.sizeBytes,
+        truncated: read.truncated,
+        refusal: refusal ?? null,
+    };
+}
+export function readRefusal(wire) {
+    if (isRefusalReason(wire.reason)) {
+        return { recognised: true, refusal: { reason: wire.reason, detail: wire.detail } };
+    }
+    return { recognised: false, raw: wire.reason, detail: wire.detail };
+}
+/**
+ * What may be dropped when the offline queue is full, stated as data so the decision lives in one
+ * place instead of inside a queue method. Everything absent from this list is a transition or a
+ * receipt, and losing one of those is a lie about what happened.
+ */
+export const DROPPABLE_KINDS = ['session_delta'];
+export function isDroppable(kind) {
+    return DROPPABLE_KINDS.includes(kind);
+}
+// ---------------------------------------------------------------------------
+// Control payloads — the link's own lifecycle. Never sequenced, never replayed.
+// ---------------------------------------------------------------------------
+/**
+ * The longest value `HostConfiguration` carries. Paths and URLs are host-controlled text on a
+ * frame the controller must accept before anything else, so each is bounded here rather than
+ * trusted; a controller stores them under the same cap.
+ */
+export const MAX_CONFIGURATION_VALUE_LENGTH = 1000;
+/** A `HostConfiguration` with nothing set: what a host composed without one reports. */
+export function unsetHostConfiguration() {
+    return {
+        repositoryRoot: null,
+        workspaceRoot: null,
+        branchScheme: null,
+        transcriptsRoot: null,
+        controllerUrl: null,
+        decisionUrl: null,
+        agentHome: null,
+    };
+}
+export function isSessionFrame(frame) {
+    return frame.frame === 'session';
+}
+export function isControlFrame(frame) {
+    return frame.frame === 'control';
+}
+/**
+ * A frame's identity, and the reason `seq` is shaped this way: this string is exactly what an SSE
+ * `Last-Event-ID` header carries. Moving to one stream per session later needs no change to the
+ * frame; the cursor set decomposes into per-stream ids one for one.
+ */
+export function frameId(frame) {
+    return `${frame.sessionId}/${frame.seq}`;
+}
+//# sourceMappingURL=frames.js.map

package/dist/control/link-state.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The link's own state, as transitions that carry why.
+ *
+ * Reconnects are the most common thing that happens to an unattended run, so the trace has to show
+ * them — and a state change without a cause is exactly as useful as no state change at all when
+ * you are reading back a night nobody watched. `cause` is required by the type, so a transition
+ * without one does not compile.
+ */
+/**
+ * `open` is the socket; `accepted` is the controller's welcome. They are two states because they are
+ * two facts an operator asks about separately: a link that opens and is never welcomed is a version
+ * or credential problem, not a network one, and a reporter that saw only `open` could not tell them
+ * apart.
+ */
+export type LinkState = 'idle' | 'connecting' | 'open' | 'accepted' | 'backoff' | 'closed';
+export declare const LINK_CAUSES: readonly ["start_requested", "socket_connected", "hello_completed", "socket_error", "socket_closed", "heartbeat_timeout", "connect_timeout", "protocol_version_rejected", "replay_requested", "credential_unavailable", "credential_rejected", "retry_scheduled", "shutdown_requested"];
+export type LinkCause = (typeof LINK_CAUSES)[number];
+export interface LinkTransition {
+    readonly from: LinkState;
+    readonly to: LinkState;
+    readonly cause: LinkCause;
+    readonly at: string;
+    /** Free text for a human reading a log. Never branched on. */
+    readonly detail: string | null;
+}
+export declare class LinkStateMachine {
+    #private;
+    get state(): LinkState;
+    /** Moves, and returns the transition. Returns null when already in `to` — no self-loops. */
+    to(next: LinkState, cause: LinkCause, at: string, detail?: string | null): LinkTransition | null;
+}
+//# sourceMappingURL=link-state.d.ts.map

package/dist/control/link-state.js

@@ -0,0 +1,39 @@
+export const LINK_CAUSES = [
+    'start_requested',
+    'socket_connected',
+    'hello_completed',
+    'socket_error',
+    'socket_closed',
+    'heartbeat_timeout',
+    // The dial never completed its upgrade inside `connectTimeoutMs`; abandoned and retried.
+    'connect_timeout',
+    'protocol_version_rejected',
+    // The controller closed the socket because a session's seq jumped past what it holds; the next
+    // dial replays from the cursor it reports. Distinct from a version rejection, which a retry cannot heal.
+    'replay_requested',
+    'credential_unavailable',
+    // Not the same event as `credential_unavailable`; the difference is whether a retry can help.
+    // `credential_unavailable` means this attempt had no header to present and the next one may;
+    // `credential_rejected` means the identity provider has refused the material outright and will
+    // keep refusing until a person signs in. The first belongs in `backoff`. The second is the only
+    // cause on this list that ends in `closed` without a shutdown having been requested, because
+    // retrying it is a loop with no exit that reports success when the process finally drains.
+    'credential_rejected',
+    'retry_scheduled',
+    'shutdown_requested',
+];
+export class LinkStateMachine {
+    #state = 'idle';
+    get state() {
+        return this.#state;
+    }
+    /** Moves, and returns the transition. Returns null when already in `to` — no self-loops. */
+    to(next, cause, at, detail = null) {
+        if (this.#state === next)
+            return null;
+        const transition = { from: this.#state, to: next, cause, at, detail };
+        this.#state = next;
+        return transition;
+    }
+}
+//# sourceMappingURL=link-state.js.map

package/dist/control/link.d.ts

@@ -0,0 +1,109 @@
+import type { Clock, Ticker } from '../core/time.js';
+import type { Refusal } from '../core/refusal.js';
+import type { Result } from '../core/result.js';
+import type { ControllerCredential } from './credential.js';
+import type { HostConfiguration, SessionCursor, SessionFrame, SessionPayload } from './frames.js';
+import type { BackoffOptions } from './backoff.js';
+import type { LinkTransition } from './link-state.js';
+export interface LinkHandlers {
+    /** Every state change, with its cause. */
+    onTransition(transition: LinkTransition): void;
+    /** An in-order session frame from the controller. Duplicates never reach here. */
+    onSessionFrame(frame: SessionFrame): void;
+    /** Frames were lost between the two ends. Loud by design; replay exists to make this not happen. */
+    onGap(sessionId: string, expected: number, received: number): void;
+    /** Anything the link declined to do, named. */
+    onRefusal(refused: Refusal): void;
+}
+export interface LinkOptions {
+    readonly url: string;
+    readonly hostId: string;
+    readonly handlers: LinkHandlers;
+    readonly credential?: ControllerCredential;
+    readonly backoff?: BackoffOptions;
+    readonly clock?: Clock;
+    readonly ticker?: Ticker;
+    readonly random?: () => number;
+    /** Frames held while the link is down. */
+    readonly queueCapacity?: number;
+    /**
+     * Extra capability markers for the `link_hello`, beside the built-in `bulk-post`.
+     * Values in an open string list: a peer that does not know one ignores it, so declaring a new
+     * marker is not a protocol change. The list is declarative: the controller is not obliged to act
+     * on any of it (see `LinkWelcome`; negotiation is declared on both sides, honoured by neither).
+     */
+    readonly capabilities?: readonly string[];
+    /**
+     * The values this host runs with, reported on every `link_hello`. Omitted, the hello
+     * reports every member as null: a link composed without one has nothing to say, and says so
+     * rather than guessing.
+     */
+    readonly configuration?: HostConfiguration;
+    /** The keys whose file value is not in effect. Omitted, the hello reports none. */
+    readonly pendingRestart?: readonly string[];
+    readonly heartbeatIntervalMs?: number;
+    /** No pong inside this window and the socket is declared dead, however alive TCP thinks it is. */
+    readonly heartbeatTimeoutMs?: number;
+    /** Above this many buffered bytes the link stops writing and queues instead. */
+    readonly highWaterMarkBytes?: number;
+    /**
+     * How long an ended session's written-but-unacked frames are held. See `ENDED_RETENTION_MS`.
+     *
+     * An option for the same reason the heartbeat's two timings are: the default is the decision, and
+     * a test that had to wait a real minute to observe a bound would be a test nobody runs.
+     */
+    readonly endedRetentionMs?: number;
+    /**
+     * How long a dial may sit in `connecting` before it is abandoned and retried. Without it a
+     * controller that accepts the TCP handshake but never completes the upgrade (an API mid-restart)
+     * holds this link in `connecting` for minutes, until the OS gives up, while sessions wait.
+     */
+    readonly connectTimeoutMs?: number;
+}
+export declare class ControllerLink {
+    #private;
+    constructor(options: LinkOptions);
+    /**
+     * Replace what the next `link_hello` declares. A host that reconfigured itself dials the same
+     * controller with the same identity; only the description moves, and it moves at the next
+     * hello rather than on a frame of its own, because the hello is where a controller reads it.
+     */
+    announce(capabilities: readonly string[], configuration: HostConfiguration, pendingRestart?: readonly string[]): void;
+    get state(): import("./link-state.js").LinkState;
+    /** The version the controller chose at the last accepted handshake; null before one. */
+    get negotiatedVersion(): number | null;
+    get queueStats(): import("./queue.js").QueueStats;
+    /** Cursors of what this side has received: sent to the controller so it replays the right frames. */
+    cursors(): SessionCursor[];
+    start(): void;
+    /** Graceful close. Idempotent, and clears every timer: a stopped link holds no handles. */
+    stop(detail?: string): void;
+    /**
+     * Accept a payload for delivery: retained until acked, written as soon as the link allows.
+     *
+     * A `seq` is minted only when the frame is first written to the wire, so nothing refused or
+     * discarded before that point ever had one — the wire's numbering stays dense whatever happens
+     * here. `ok` means accepted and retained; a refusal names why nothing was accepted, and it is
+     * the caller's pressure signal — a dropped delta and a refused transition are different events
+     * and only the caller knows which one it can live with.
+     */
+    send(sessionId: string, payload: SessionPayload): Result<void>;
+    /**
+     * Release what this session holds. Called at session end, always.
+     *
+     * It does not discard frames the controller has not acked; see `BoundedFrameQueue.forget`.
+     * A session's last frames are its most important ones and are exactly the ones still unacked if
+     * the link is down when it ends. What is released here is everything that cannot still be owed:
+     * pending entries, which never had a seq, and the inbound cursor, which is about what the
+     * controller sent this side rather than what this side owes it.
+     *
+     * The outbound counter outlives the call while anything is still retained, and that is not an
+     * oversight. Resetting it while stamped frames for the same key are awaiting replay would let a
+     * later frame on that key be numbered below one already on the wire: a seq regression, which the
+     * receiver reads as a hole it can never fill. The counter is released by the ack that empties the
+     * retention instead, so the bound this method exists to keep is kept a moment later rather than
+     * abandoned.
+     */
+    forgetSession(sessionId: string): void;
+}
+//# sourceMappingURL=link.d.ts.map