@qilin-agent/client-connection 0.0.0-stage → 3.1.3

package/lib/types/api-path.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The /api URL prefix — single source for both halves of the web transport.
+ * The node half registers this prefix on the web server.
+ */
+/** Route prefix owning every api request (`/api` and `/api/<anything>`). */
+export declare const API_PATH = "/api";
+//# sourceMappingURL=api-path.d.ts.map

package/lib/types/api-request-trust.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Browser-trust fence for every /api request. Defends the two confused-deputy
+ * paths a browser opens against a local HTTP API — DNS rebinding (Host names
+ * the attacker's domain while the socket reaches this server) and cross-site
+ * requests fired from a malicious page. The Host fence binds every request,
+ * browser-looking or not: over plain HTTP a browser attaches neither Origin
+ * nor Fetch-Metadata to reads (images and navigations — those
+ * headers go only to trustworthy destinations), so an unmarked request may
+ * still be a rebound browser read and Host is the one header rebinding cannot
+ * forge. Non-browser and remote clients pass the same fence via loopback,
+ * deployment-derived LAN IP literals, or a declared `trustedHosts` authority.
+ * Network reachability and authentication stay out of scope: binding policy
+ * belongs to the webserver config, and this fence is not an auth layer.
+ */
+import type { ConnectionTrustRequest } from './rpc.ts';
+/**
+ * Assert one configured `trustedHosts` entry is a bare authority (`host` or
+ * `host:port`) in canonical form: it must survive WHATWG parsing unchanged
+ * (case aside). Anything parsing would silently rewrite is refused as a typo
+ * that must fail the load loudly instead of being ignored until requests 403
+ * or quietly changing the grant: URL parts beyond the authority
+ * (`harness.internal/path`, `user@harness.internal` — which would authorize
+ * the embedded hostname), stripped whitespace, a dangling colon or
+ * zero-padded port (which would broaden an intended exact-port grant to every
+ * port), and non-canonical host spellings (`0x7f.0.0.1`, percent-encoding,
+ * unbracketed IPv6; IDN hosts are declared in punycode, the form the wire
+ * carries).
+ * @param entry - the configured value, verbatim.
+ */
+export declare function assertTrustedAuthority(entry: string): void;
+/**
+ * Decide whether one /api request may reach the RPC bridge.
+ * @param request - Node HTTP or Fetch request facts (headers).
+ * @param trustedHosts - non-loopback authorities this deployment serves: exact `host:port`, or port-less `host` matching any port.
+ * @returns true when the Host is ours (loopback or trusted) and any attached browser markers are same-origin.
+ */
+export declare function isTrustedApiRequest(request: ConnectionTrustRequest, trustedHosts: readonly string[]): boolean;
+//# sourceMappingURL=api-request-trust.d.ts.map

package/lib/types/browser-auth.d.ts

@@ -0,0 +1,68 @@
+/** Browser-session authentication for the Host Connection carrier. */
+import type { CredentialProvider } from '@qilin-agent/credentials';
+import type { ConnectionIndexRequest, ConnectionIndexResponse, ConnectionTrustRequest } from './rpc.ts';
+/**
+ * Process launch-token exchange and persistent signed-cookie verification.
+ * Connection loads the credential provider's signing secret during activation
+ * and retains it for synchronous request authentication.
+ */
+export declare class BrowserAuth {
+    private readonly secret;
+    private readonly launchToken;
+    private readonly maxAgeMilliseconds;
+    private constructor();
+    /**
+     * Initialize browser authentication and create its durable signing secret
+     * when this Harness home has none.
+     * @param processOwner - root application context retaining one token across Connection reloads.
+     * @param credentials - persistent credential provider for the Web profile.
+     * @param maxAgeDays - positive absolute browser-cookie lifetime in days.
+     * @returns initialized authentication owner with the process owner's launch token.
+     */
+    static create(processOwner: object, credentials: CredentialProvider, maxAgeDays: number): Promise<BrowserAuth>;
+    /**
+     * Add this process's launch token to the ordinary application root URL.
+     * @param baseUrl - canonical browser origin without credentials.
+     * @param displayName - optional operator name the exchange carries into the device cookie for display.
+     * @returns root URL carrying the process token as its sole authentication input.
+     */
+    authenticatedUrl(baseUrl: string, displayName?: string): string;
+    /**
+     * Authenticate an index request. A valid entry-path query token mints the
+     * device cookie and redirects to the clean entry path; a valid cookie lets
+     * the caller serve the index; every other request receives the same minimal
+     * 401 response.
+     * @param req - incoming entry or configured-index request.
+     * @param res - response owned when this method returns false.
+     * @returns true only when the caller may serve index.html.
+     */
+    authorizeIndex(req: ConnectionIndexRequest, res: ConnectionIndexResponse): boolean;
+    /**
+     * Mint the device cookie for one valid launch token and redirect to the clean
+     * entry path: the handoff that turns the printed URL into a browser session.
+     * @param req - incoming request; its only token input is the query.
+     * @param res - response owned when the exchange applies.
+     * @returns true when a valid token was exchanged and the redirect written.
+     */
+    exchangeToken(req: ConnectionIndexRequest, res: ConnectionIndexResponse): boolean;
+    /**
+     * Verify the authority-bound browser cookie on a Host request.
+     * @param request - request headers carrying Host and Cookie.
+     * @returns true only for an unexpired cookie signed by this activation's loaded secret.
+     */
+    isAuthenticated(request: ConnectionTrustRequest): boolean;
+    /**
+     * Read the device session behind a Host request: its authentication fact and
+     * the operator display name the launching host attached, if any. This is the
+     * identity channel for deployments without the account gate, and the gate's
+     * own status route stays authoritative wherever that is mounted.
+     * @param request - request headers carrying Host and Cookie.
+     * @returns the session fact and display name of the request's device session.
+     */
+    identity(request: ConnectionTrustRequest): {
+        readonly authenticated: boolean;
+        readonly accountName: string | null;
+    };
+    private writeUnauthorized;
+}
+//# sourceMappingURL=browser-auth.d.ts.map

package/lib/types/client/api.d.ts

@@ -0,0 +1,14 @@
+/** Browser-safe Connection protocol and shared application value exports. */
+export type { ClientRequest, RpcMessage, RpcRequest, RpcResponse, RpcResult, ServerResponse, } from '../rpc.ts';
+export { RpcId, transportError } from '../rpc.ts';
+export type { SessionId, SessionEvent } from '@qilin-agent/session/types';
+export type { MessageId } from '@qilin-agent/llm/brand';
+export type { ContentBlock, StreamChunk } from '@qilin-agent/llm/types';
+import type { RpcResponse, RpcResult } from '../rpc.ts';
+/**
+ * Return the business result carried by an RPC response.
+ * @param response - RPC response to unwrap.
+ * @returns the response's business result.
+ */
+export declare function resultOf<T>(response: RpcResponse<T>): RpcResult<T>;
+//# sourceMappingURL=api.d.ts.map

package/lib/types/client/connection.d.ts

@@ -0,0 +1,80 @@
+/** Connection generation readiness, cancellation, and continuous recovery. */
+import { type ConnectionRecoveryConfig } from '../recovery-config.ts';
+export type { ConnectionRecoveryConfig } from '../recovery-config.ts';
+/** Stable Host facts delivered by one established Remote event generation. */
+export interface ConnectionHostInfo {
+    /** Host account home used only to abbreviate displayed filesystem paths. */
+    readonly home: string;
+}
+/** One successfully established Host generation. */
+export interface ConnectionGeneration {
+    /** Monotone generation number within this Client runtime. */
+    readonly id: number;
+    /** Host facts carried by this generation's opening frame. */
+    readonly host: ConnectionHostInfo;
+}
+/** Connection lifecycle state published after the first attempt has an outcome. */
+export type ConnectionState = 'connected' | 'disconnected' | 'connecting';
+/** Connection-generation callbacks owned by API Gateway. */
+export interface ConnectionSinks {
+    /** After the generation source reports ready, first connect included. */
+    onConnected?: (host: ConnectionHostInfo) => void;
+    /** State transitions after the initial attempt has an outcome. Equivalent states are deduplicated. */
+    onStateChange?: (state: ConnectionState) => void;
+    /** Start one fresh physical-carrier attempt before each logical retry. */
+    onReconnectRequested?: () => void;
+}
+/**
+ * One long-lived source defining a Connection generation. The source must
+ * attach its incremental listeners before calling `ready`, then remain pending
+ * until the generation is lost or `signal` aborts. On abort it must stop
+ * delivery, release its resources, and settle before a replacement can start.
+ * @param signal - cancellation for the current generation.
+ * @param ready - one-shot report that incremental delivery is attached.
+ * @returns a promise settling only when this generation ends or fails.
+ */
+export type ConnectionGenerationSource = (signal: AbortSignal, ready: (host: ConnectionHostInfo) => void) => Promise<void>;
+/**
+ * Opens the registered generation source, reconnecting with exponential backoff on loss.
+ * State (generation/attempt) is instance-private, never in the store.
+ * Sink exceptions do not kill the generation loop.
+ */
+export declare class ConnectionController {
+    private readonly source;
+    private readonly sinks;
+    private generation;
+    private attempt;
+    private current;
+    private retryDelay;
+    private running;
+    private immediateRetry;
+    private networkAvailable;
+    private lastState;
+    private readonly config;
+    constructor(source: ConnectionGenerationSource, sinks?: ConnectionSinks, config?: ConnectionRecoveryConfig);
+    /** Idempotent: begin the connect/pump/reconnect loop. */
+    start(): void;
+    /** Stop the loop and abort the current generation source. */
+    stop(): void;
+    /** Reset the retry sequence and replace the current generation or retry delay immediately. */
+    reconnect(): void;
+    /**
+     * Suspend automatic retries while offline and restart backoff when the network returns.
+     * @param available - whether the browser reports network access.
+     */
+    setNetworkAvailable(available: boolean): void;
+    private backoffCap;
+    private backoffDelay;
+    /** Re-read retry inputs after a potentially reentrant state sink. */
+    private isRetryInterrupted;
+    /** Read through a method: stop() flips the flag across awaits, so narrowing from the loop condition must not stick. */
+    private isRunning;
+    /** Re-read both mutable liveness guards after a potentially reentrant sink. */
+    private isGenerationActive;
+    private loop;
+    /** Deduplicated state emission (sink isolation applies). */
+    private emitState;
+    /** Sink exception isolation: a business-layer throw is logged only, never affecting pump or reconnect semantics. */
+    private callSink;
+}
+//# sourceMappingURL=connection.d.ts.map

package/lib/types/client/index.d.ts

@@ -0,0 +1,136 @@
+/** Browser wire client: Remote transport and connection generations. */
+import type { Context } from '@qilin-agent/kylin';
+import { type ConnectionRecoveryConfig, type ConnectionGeneration, type ConnectionGenerationSource, type ConnectionSinks, type ConnectionState } from './connection.ts';
+import { type RpcFetch, type RpcStreamOpen } from './rpc.ts';
+import type { ClientConnectionRpc } from '../rpc.ts';
+declare module '@qilin-agent/kylin' {
+    interface Events {
+        /**
+         * A connection generation was established. Wire-derived caches must
+         * repull; long-lived streams own their own resume and baseline lifecycle.
+         * @mode emit
+         */
+        'connection/reset'(): void;
+    }
+}
+export type { MessageId, RpcRequest, RpcResponse, RpcResult, ClientRequest, ServerResponse, RpcMessage, SessionId, SessionEvent, ContentBlock, StreamChunk, } from './api.ts';
+export { RpcId, transportError, } from './api.ts';
+export type { ConnectionRecoveryConfig, ConnectionGeneration, ConnectionGenerationSource, ConnectionHostInfo, ConnectionSinks, ConnectionState, } from './connection.ts';
+export type { ClientConnectionRpc, ConnectionRpcFailure, ConnectionRpcResult, } from '../rpc.ts';
+export type { RpcFetch } from './rpc.ts';
+/** Observable identity and Host facts for the active connection generation. */
+export interface ConnectionGenerationState {
+    /** Active generation, or undefined before readiness and while reconnecting. */
+    getSnapshot(): ConnectionGeneration | undefined;
+    /** Subscribe to generation establishment, replacement, and loss. */
+    subscribe(listener: () => void): () => void;
+}
+/** Observable recovery lifecycle of the owned Connection loop. */
+export interface ConnectionStateSource {
+    /** Current state, or undefined before the first connection outcome. */
+    getSnapshot(): ConnectionState | undefined;
+    /** Subscribe to state changes. */
+    subscribe(listener: () => void): () => void;
+}
+/** Required services (none — this is the wire root). */
+export declare const inject: string[];
+/**
+ * Physical carrier selected when the Connection service is installed. The
+ * served web app omits it and gets HTTP + WebSocket; a shell that owns a
+ * different transport (the worker preview's postMessage tunnel) provides both
+ * halves instead of forking this plugin.
+ */
+export interface ClientTransportHooks {
+    /**
+     * Already decoded logical RPC carrier. When present it replaces the HTTP
+     * caller outright: no envelopes, no `fetch`, no `openStream` (an in-process
+     * Host such as a test mock plugs in here).
+     */
+    rpc?: ClientConnectionRpc;
+    /** Transport for generic unary RPC channels (the Typert gateway); unused when `rpc` is present. */
+    fetch?: RpcFetch;
+    /** Worker-local Gateway stream carrier; absent when the page uses the Gateway WebSocket or `rpc` is present. */
+    openStream?: RpcStreamOpen;
+    /**
+     * Bundle transport for the module system, present when the carrier also owns
+     * bundle bytes (the worker tunnel). Absent in the served web app, whose
+     * bundles load over HTTP.
+     */
+    loadBundle?(url: string): Promise<void>;
+    /**
+     * The transport owner declares the page owns the Host outright: the Host
+     * runs inside a worker this page spawned, so no other party can reach it and
+     * the loopback stand-in for "the operator's own machine" is vacuous.
+     * `ctx.connection.isLoopback` then reports the privileged surface reachable
+     * regardless of the page authority. Only a shell that assembles its own
+     * transport can set this; served pages never carry the global at all.
+     */
+    ownsHost?: boolean;
+    /** HTTP origin of a shell-owned Host when its WebSocket uses a different page origin. */
+    streamBaseUrl?: string;
+}
+/** Browser location fields used to classify loopback authority. */
+export interface ConnectionLocation {
+    readonly hostname: string;
+}
+/** Instance-local inputs for installing a Connection service. */
+export interface ConnectionInstallOptions {
+    /** Explicit physical carrier; omit for the browser HTTP + WebSocket carrier. */
+    readonly transport?: ClientTransportHooks;
+    /** Reconnect timing overrides; omitted fields use controller defaults. */
+    readonly recovery?: ConnectionRecoveryConfig;
+    /** Page location; omit for a non-browser composition. */
+    readonly location?: ConnectionLocation;
+}
+/**
+ * The ctx.connection service API. API Gateway supplies generation readiness
+ * and reset callbacks; Connection stays independent of downstream domain state.
+ */
+export interface ConnectionHandle {
+    /**
+     * Whether the privileged surface is reachable: the page authority is
+     * loopback, the transport declares the page owns the Host
+     * ({@link ClientTransportHooks.ownsHost}), or the context is not a browser.
+     */
+    readonly isLoopback: boolean;
+    /** Current Remote event generation and the Host facts carried by its opening frame. */
+    readonly generation: ConnectionGenerationState;
+    /** Current recovery lifecycle for connection-specific consumers. */
+    readonly state: ConnectionStateSource;
+    /** Generic logical RPC channels over the same Connection transport. */
+    readonly rpc: ClientConnectionRpc;
+    /** Reset retry progression and replace the current attempt immediately. */
+    reconnect(): void;
+    /**
+     * Register the sole source defining Host generations. The source reports
+     * ready only after its incremental listeners are attached.
+     * @param source - long-lived generation source owned by the push carrier.
+     * @returns disposer withdrawing the source and stopping an active loop.
+     */
+    registerGenerationSource(source: ConnectionGenerationSource): () => void;
+    /**
+     * Start the connect/reconnect loop with the consumer's state callbacks.
+     * API Gateway owns the loop; a second call throws.
+     * @param sinks - connection-state callbacks.
+     * @param config - explicit timing overrides; omitted fields use Host bootstrap timing.
+     * @returns lifecycle controls for the loop.
+     */
+    start(sinks: ConnectionSinks, config?: ConnectionRecoveryConfig): ConnectionLoop;
+}
+/** Controls retained by the sole owner of a running connection loop. */
+export interface ConnectionLoop {
+    /** Stop the loop and withdraw its active generation. */
+    stop(): void;
+}
+/**
+ * Install one Context-owned Connection service from explicit composition inputs.
+ * @param ctx - client Cordis context.
+ * @param options - physical carrier, reconnect timing, and page location.
+ */
+export declare function installConnection(ctx: Context, options?: ConnectionInstallOptions): void;
+/**
+ * Client plugin body: read the page composition and install its Connection service.
+ * @param ctx - client Cordis context.
+ */
+export declare function apply(ctx: Context): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/client/random-uuid.d.ts

@@ -0,0 +1,7 @@
+/** Browser-safe UUID generation for client-side wire correlation. */
+/**
+ * Generate an RFC 4122 version 4 UUID without requiring a secure context.
+ * @returns a UUID backed by `crypto.getRandomValues()`, which browsers expose on insecure origins.
+ */
+export declare function randomUuid(): string;
+//# sourceMappingURL=random-uuid.d.ts.map

package/lib/types/client/rpc.d.ts

@@ -0,0 +1,14 @@
+/** Browser caller for generic Connection unary RPC channels. */
+import type { ClientConnectionRpc } from '../rpc.ts';
+/** Transport this caller posts through; same signature as the global `fetch`. */
+export type RpcFetch = (input: URL, init: RequestInit) => Promise<Response>;
+/** Worker-local opener for decoded Gateway Remote streams; `uplink` carries the Client's items for the stream. */
+export type RpcStreamOpen = (endpoint: string, payload: unknown, signal: AbortSignal, uplink?: AsyncIterable<unknown>) => AsyncIterable<unknown>;
+/**
+ * Create the browser-backed generic RPC caller.
+ * @param doFetch - transport override; defaults to the page's global fetch.
+ * @param openStream - optional worker-local Gateway stream carrier.
+ * @returns caller that owns request correlation and response-envelope validation.
+ */
+export declare function createWebConnectionRpc(doFetch?: RpcFetch, openStream?: RpcStreamOpen): ClientConnectionRpc;
+//# sourceMappingURL=rpc.d.ts.map

package/lib/types/http-bridge.d.ts

@@ -0,0 +1,21 @@
+/**
+ * node:http ↔ WHATWG fetch bridge for the /api transport (host side of the
+ * web carrier; the fetch-shaped handler itself is transport-agnostic).
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { ConnectionFetchHandler } from './rpc.ts';
+/** Default carrier cap for all HTTP RPC bodies: sized for the default
+ * aggregate image limit (200 MiB) after base64 expansion plus envelope
+ * headroom (~267.7 MiB required), rounded up for slack. The bridge buffers
+ * each body in memory, so this cap is also the per-request resident bound. */
+export declare const DEFAULT_MAX_REQUEST_BODY_BYTES: number;
+/**
+ * Bridge one node:http request to the fetch-shaped handler (client close
+ * aborts; response bodies stream out chunk by chunk).
+ * @param req - incoming node:http request.
+ * @param res - node:http response the bridge writes and owns to completion.
+ * @param apiHandler - fetch-shaped API carrier the request is dispatched to.
+ * @param maxRequestBodyBytes - maximum bytes buffered for a buffered route.
+ */
+export declare function bridge(req: IncomingMessage, res: ServerResponse, apiHandler: ConnectionFetchHandler, maxRequestBodyBytes?: number): Promise<void>;
+//# sourceMappingURL=http-bridge.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,58 @@
+/** Host HTTP bridge for browser-client RPC. */
+import type { Context } from '@qilin-agent/kylin';
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import z from '@qilin-agent/schemastery';
+import { type ConnectionRecoveryConfig } from './recovery-config.ts';
+export type { PeerAdmission, ConnectionFetchMethod, ConnectionFetchHandler, ConnectionFetchRoute, ConnectionIndexRequest, ConnectionIndexResponse, ConnectionSessionAuthority, HostConnectionSession, ConnectionRpcEndpointMatcher, ConnectionRpcFailure, ConnectionRpcHandler, ConnectionRequestRejection, ConnectionRpcResult, ConnectionRequestBodyMode, ConnectionTrustRequest, ClientRequest, HostConnectionHandle, HostConnectionFetch, HostConnectionRpc, RpcMessage, ServerResponse, } from './rpc.ts';
+export type { PeerId, PeerScope, RemoteInvocation } from '@qilin-agent/typert-protocol';
+export { RpcId, transportError } from './rpc.ts';
+export { OperatorPeer } from './operator-peer.ts';
+export { clientRequestSchema, rpcErrorSchema, rpcIdSchema, rpcMessageSchema, rpcResultSchema, serverResponseSchema, } from './rpc-schema.ts';
+export { HostConnectionService } from './rpc-host.ts';
+export { API_PATH } from './api-path.ts';
+export { WEB_ENTRY_PATH } from './web-entry.ts';
+/** Stable Cordis plugin name. */
+export declare const name = "client-connection";
+declare module '@qilin-agent/kylin' {
+    interface Events {
+        /**
+         * Admit or wrap an authenticated shared API request, including body transfer.
+         * Existing requests continue when a listener refuses subsequent requests.
+         * @param request - Authenticated incoming HTTP request.
+         * @param response - Response owned until the delegated bridge settles.
+         * @param next - Delegate to the next listener or the shared API bridge.
+         * @mode waterfall
+         */
+        'connection/request'(request: IncomingMessage, response: ServerResponse, next: () => Promise<void>): Promise<void>;
+    }
+}
+/** Services required before providing Connection. */
+export declare const inject: string[];
+/** Browser authentication, request limits, and connection recovery configuration. */
+export interface ConnectionConfig {
+    /** Browser recovery timing, injected into each served page. */
+    recovery?: ConnectionRecoveryConfig;
+    /**
+     * Authorities this deployment serves beyond loopback: exact `host:port`, or
+     * port-less `host` matching any port. The /api trust fence refuses any
+     * request whose Host is neither loopback nor listed here, so a
+     * non-loopback (`0.0.0.0`) deployment must declare the names it is reached
+     * by; the Web runtime derives LAN IP literals from an active all-interface
+     * bind. An entry that is not a bare, canonical authority fails plugin load.
+     */
+    trustedHosts?: string[];
+    /** Absolute browser-session lifetime in days. Default: 30. */
+    cookieMaxAgeDays?: number;
+    /** Maximum buffered JSON body for every `/api` request. Default: 300 MiB. */
+    maxRequestBodyBytes?: number;
+}
+export declare const Config: z<ConnectionConfig>;
+/**
+ * Provides carrier-neutral RPC and Fetch registries. When `webServer` is
+ * present, the plugin also mounts the `/api` browser transport with Host/Origin
+ * checks and persistent browser authentication.
+ * @param ctx - Host plugin context.
+ * @param config - resolved plugin config (schema defaults applied).
+ */
+export declare function apply(ctx: Context, config?: ConnectionConfig): Promise<void>;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/loopback-hostname.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Browser-safe, zero-dependency loopback classification shared by the `/api`
+ * Host fence and the package's `ctx.connection` state. The predicate stays
+ * package-internal; client plugins consume the derived state through Cordis.
+ */
+/**
+ * Whether a normalized URL hostname names the local loopback authority.
+ * @param hostname - WHATWG URL hostname (IPv6 literals retain brackets).
+ * @returns true for localhost, IPv6 loopback, or any IPv4 address in 127/8.
+ */
+export declare function isLoopbackHostname(hostname: string): boolean;
+//# sourceMappingURL=loopback-hostname.d.ts.map

package/lib/types/operator-peer.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The operator Peer: the one party this Host answers to. Connection owns it
+ * for its own lifetime, admits every request as it, and hands it to each
+ * Remote call as `invocation.peer`.
+ * @module @qilin-agent/client-connection/src/operator-peer
+ */
+import type { Context } from '@qilin-agent/kylin';
+import type { PeerId, PeerScope } from '@qilin-agent/typert-protocol';
+/**
+ * The operator's scope. The instance is its own scope key, so `scopeOf(peer.ctx)`
+ * returns it and events dispatched with `scopeTarget(subject, peer)` reach
+ * listeners registered through `peer.ctx` and nobody else.
+ */
+export declare class OperatorPeer implements PeerScope {
+    readonly id: PeerId;
+    readonly ctx: Context;
+    private readonly scope;
+    /** @param owner - Connection plugin context the scope fiber hangs under. */
+    constructor(owner: Context);
+    /** Tear down every connection-lifetime registration; racing calls share one completion. */
+    dispose(): Promise<void>;
+}
+//# sourceMappingURL=operator-peer.d.ts.map

package/lib/types/recovery-config.d.ts

@@ -0,0 +1,27 @@
+/** Shared validation for Host-configured and browser-local connection recovery. */
+import z from '@qilin-agent/schemastery';
+/** Timing for generation readiness and automatic reconnection. */
+export interface ConnectionRecoveryConfig {
+    /** First-retry delay cap in ms; actual delay is 50–100% of the cap. Default: 500. */
+    backoffBaseMs?: number;
+    /** Finite growth factor of at least 1 per failed attempt; 1 keeps a fixed cap. Default: 2. */
+    backoffFactor?: number;
+    /** Maximum retry delay cap in ms; retries continue at this cap. Default: 10000. */
+    backoffMaxMs?: number;
+    /**
+     * Delay before reporting a slow handshake, without cancelling it. Default: 3000.
+     * Omitted when readiness, failure, cancellation, or the hard deadline occurs first.
+     */
+    generationReadyWarnMs?: number;
+    /** Deadline in ms for readiness, including physical connection setup. Default: 15000. */
+    generationReadyTimeoutMs?: number;
+}
+/** Schema shared by the Host plugin and the Client's recovery input parser. */
+export declare const ConnectionRecoveryConfigSchema: z<ConnectionRecoveryConfig>;
+/**
+ * Validate recovery input and supply every timing default before starting work.
+ * @param config - Host configuration, page bootstrap data, or direct loop options.
+ * @returns validated, complete recovery timing.
+ */
+export declare function resolveConnectionConfig(config?: unknown): Required<ConnectionRecoveryConfig>;
+//# sourceMappingURL=recovery-config.d.ts.map

package/lib/types/rpc-host.d.ts

@@ -0,0 +1,70 @@
+/** Host registry and HTTP adapter for generic Connection RPC channels. */
+import { Context, Service } from '@qilin-agent/kylin';
+import type { PeerScope } from '@qilin-agent/typert-protocol';
+import type { BrowserAuth } from './browser-auth.ts';
+import type { PeerAdmission, ConnectionIndexRequest, ConnectionIndexResponse, ConnectionFetchHandler, HostConnectionFetch, HostConnectionSession, ConnectionRequestRejection, ConnectionTrustRequest, HostConnectionHandle, HostConnectionRpc } from './rpc.ts';
+declare module '@qilin-agent/kylin' {
+    interface Context {
+        /** Host Connection transport and RPC registrations. */
+        connection: HostConnectionHandle;
+    }
+}
+/** Host Connection service whose channel registrations belong to the caller fiber. */
+export declare class HostConnectionService extends Service implements HostConnectionHandle {
+    private readonly trustedHosts;
+    private readonly browserAuth;
+    /** The operator Peer every admitted request speaks for. */
+    readonly operator: PeerScope;
+    private readonly interceptors;
+    private readonly fetchRoutes;
+    private sessionAuthority;
+    /**
+     * Provide the Host half over the active HTTP server.
+     * @param ctx - owning Connection plugin context.
+     * @param trustedHosts - deployment authorities accepted by the Host/Origin fence.
+     * @param browserAuth - process token and persistent browser-session owner.
+     */
+    constructor(ctx: Context, trustedHosts: readonly string[], browserAuth: BrowserAuth);
+    /** Generic channel registry scoped to the Context reading this service. */
+    get rpc(): HostConnectionRpc;
+    /** Exact Fetch-route registry scoped to the Context reading this service. */
+    get fetch(): HostConnectionFetch;
+    /** Request path serving the application document. */
+    get entryPath(): string;
+    /** Account-session gate seat scoped to the Context reading this service. */
+    get session(): HostConnectionSession;
+    /**
+     * Apply the configured Host/Origin fence, then whichever authentication owns
+     * this deployment: an installed account-session authority, or the device
+     * cookie minted by the launch-token exchange.
+     */
+    requestRejection(request: ConnectionTrustRequest): ConnectionRequestRejection;
+    /** A request that passes the fence and authentication speaks for the operator. */
+    admit(request: ConnectionTrustRequest): PeerAdmission;
+    /**
+     * Authenticate an index request: the launch-token exchange first, then the
+     * installed account-session authority, or the device cookie when no
+     * authority claims the seat.
+     */
+    authorizeIndex(request: ConnectionIndexRequest, response: ConnectionIndexResponse): boolean;
+    /** Add this process's launch token, and an optional display name, to the clean application URL. */
+    authenticatedUrl(baseUrl: string, displayName?: string): string;
+    /**
+     * Compose one shared-channel Fetch handler from exact routes and its interceptor.
+     * @param channel - shared channel mounted by Connection.
+     * @returns Fetch handler that selects one owner or returns 404.
+     */
+    createSharedFetchHandler(channel: '/api'): ConnectionFetchHandler;
+    /**
+     * Answer the status read from the device session alone. Exact routes are
+     * consulted first, so a mounted account gate keeps owning this path; this
+     * fallback exists for the forms that disable it and would otherwise leave
+     * the menu without any identity channel.
+     */
+    private deviceStatusAnswer;
+    private installSessionAuthority;
+    private registerFetchRoute;
+    private register;
+    private registerInterceptor;
+}
+//# sourceMappingURL=rpc-host.d.ts.map

package/lib/types/rpc-schema.d.ts

@@ -0,0 +1,30 @@
+/** Runtime validation for Connection RPC envelopes. */
+import { z } from 'zod';
+import type { ClientRequest, RpcId, RpcMessage, ServerResponse } from './rpc.ts';
+/** Correlation id after wire validation. */
+export declare const rpcIdSchema: z.ZodType<RpcId>;
+/** Generic endpoint failure carried in a response envelope. */
+export declare const rpcErrorSchema: z.ZodObject<{
+    code: z.ZodString;
+    message: z.ZodString;
+    details: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, z.core.$strip>;
+/**
+ * Build the result parser for one endpoint value parser.
+ * @param value - endpoint-owned success-value parser.
+ * @returns parser for either a success value or generic failure.
+ */
+export declare function rpcResultSchema<T>(value: z.ZodType<T>): z.ZodType<{
+    readonly ok: true;
+    readonly value: T;
+} | {
+    readonly ok: false;
+    readonly error: z.infer<typeof rpcErrorSchema>;
+}>;
+/** Client request envelope; endpoint payload validation belongs to its owner. */
+export declare const clientRequestSchema: z.ZodType<ClientRequest>;
+/** Server response envelope; endpoint value validation belongs to its caller. */
+export declare const serverResponseSchema: z.ZodType<ServerResponse>;
+/** Either Connection RPC envelope direction. */
+export declare const rpcMessageSchema: z.ZodType<RpcMessage>;
+//# sourceMappingURL=rpc-schema.d.ts.map