@hydraharness/harness-client-connection 0.1.1-rc.10

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

@@ -0,0 +1,43 @@
+/**
+ * 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 { IncomingHttpHeaders } from 'node:http';
+/** The request facts the fence reads from either HTTP representation. */
+interface ApiTrustRequest {
+    headers: IncomingHttpHeaders | Headers;
+}
+/**
+ * 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: ApiTrustRequest, trustedHosts: readonly string[]): boolean;
+export {};
+//# sourceMappingURL=api-request-trust.d.ts.map

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

@@ -0,0 +1,20 @@
+export type { ConversationRevision, SessionVersionState, ApiProxy, SessionsApi, SessionSearchItem, SessionSummary, PromptContentPart, HostApi, EventsApi, MuxFrame, HostFrame, ApprovalResponsePayload, QuestionResponsePayload, HistoryEntry, ToolEventView, DirectoryEntry, DirectoryListing, ResponseValue, WorkspaceApi, WorkspaceId, WorkspaceView, SkillsApi, SkillEntry, ModelCatalogFailure, ModelCatalogModel, ModelProviderGroup, ModelReasoning, ModelReasoningEffort, ModelSelection, QueueAction, QueuedInboxItem, SessionModels, GoalsApi, GoalRef, SettingsApi, SettingsNamespaceView, SettingsPathOpView, SettingsSecretView, WorkspaceSettingsStatus, CredentialsApi, CredentialView, ConfigurableProviderView, DiscoveredModelView, LlmApi, AuthorizationAccountView, AuthorizationApi, AuthorizationAttemptView, AuthorizationEntryView, AuthorizationNoticeView, AuthorizationPromptView, AuthorizationUsageView, SubagentsApi, SubagentAddress, SubagentCatalog, SubagentListEntry, SubagentPromptReceipt, JobView, } from '@hydraharness/harness-host-apiproxy/api';
+export type { ToolCallView, ToolResultView } from '@hydraharness/harness-tools/presentation';
+export type { RpcRequest, RpcResponse, RpcResult, RpcError, RpcErrorCode, ClientRequest, ServerResponse, ServerRequest, ClientResponse, RpcMessage, RpcReceipt, } from '@hydraharness/harness-host-apiproxy/api';
+export { RpcId, SESSION_SEARCH_RESULT_LIMIT, transportError, } from '@hydraharness/harness-host-apiproxy/api';
+export { AbstractApiClient } from '@hydraharness/harness-host-apiproxy/client';
+export type { IApiClient } from '@hydraharness/harness-host-apiproxy/client';
+export type { SessionId, SessionEvent } from '@hydraharness/harness-session/types';
+export type { MessageId } from '@hydraharness/harness-llm/brand';
+export type { ContentBlock, StreamChunk } from '@hydraharness/harness-llm/types';
+/** Successful value returned by the connection-generation host handshake. */
+export type HostDescription = import('@hydraharness/harness-host-apiproxy/api').ResponseValue<'host.describe'>;
+import type { RpcResponse, RpcResult } from '@hydraharness/harness-host-apiproxy/api';
+/**
+ * Unwrap a unary response: RpcResponse<T> -> RpcResult<T> (business code only
+ * cares about the result slot).
+ * @param response - the unary response.
+ * @returns its result slot.
+ */
+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,64 @@
+import type { HostDescription, IApiClient, HostFrame, MuxFrame, RpcRequest } from './api.ts';
+/** Reconnect/backoff tunables (deployment-varying — no hardcoded tunables; these become the
+ *  future `ctx.connection` plugin's Config). All fields optional; defaults below. */
+export interface ConnectionConfig {
+    /** First-retry backoff cap in ms (jittered: actual delay is cap/2..cap). */
+    backoffBaseMs?: number;
+    /** Exponential growth factor per consecutive failed attempt. */
+    backoffFactor?: number;
+    /** Upper bound for the backoff cap in ms. */
+    backoffMaxMs?: number;
+    /** Cap on waiting for both streams' onOpen before onConnected, in ms. The strict handshake
+     *  waits for mux+host stream establishment plus describe; a carrier that never
+     *  fires onOpen (misbehaving proxy) must not wedge the connection forever — on timeout the
+     *  generation proceeds as connected and the live-gap repair path covers stragglers. */
+    streamOpenTimeoutMs?: number;
+}
+/** Coarse connection state for the UI: 'connected' after each generation's handshake,
+ *  'reconnecting' the moment the generation fails (covers the whole backoff+retry span). */
+export type ConnectionState = 'connected' | 'reconnecting';
+/** Frame sink callbacks: the Controller owns the physical streams; business dispatch belongs to
+ *  SessionManager. */
+export interface ConnectionSinks {
+    onMuxEnvelope?: (envelope: RpcRequest<MuxFrame>) => void;
+    onHostEnvelope?: (envelope: RpcRequest<HostFrame>) => void;
+    /** After each connection generation is established (both streams open + describe succeeded), first connect included. */
+    onConnected?: (description: HostDescription) => void;
+    /** Coarse state transitions (deduplicated: fires only on change). The initial pre-connect
+     *  span reports nothing — the UI treats "no state yet" as connecting, not as an outage. */
+    onStateChange?: (state: ConnectionState) => void;
+}
+/**
+ * Opens both streams and keeps iterating (pull mode: nothing reads the socket and the tap
+ * never fires unless someone for-awaits), reconnecting with exponential backoff on loss.
+ * State (generation/attempt) is instance-private, never in the store.
+ * The pump body feeds each frame to a sink (sink exceptions must
+ * not kill the pump — a broken business layer must not drag down the connection layer).
+ */
+export declare class ConnectionController {
+    private readonly api;
+    private readonly sinks;
+    private generation;
+    private attempt;
+    private current;
+    private running;
+    private lastState;
+    private readonly config;
+    constructor(api: IApiClient, sinks?: ConnectionSinks, config?: ConnectionConfig);
+    /** Idempotent: begin the connect/pump/reconnect loop. */
+    start(): void;
+    /** Stop the loop and abort the current generation's streams. */
+    stop(): void;
+    private backoffDelay;
+    /** 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;
+    private pumpStream;
+    /** 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/fixture.d.ts

@@ -0,0 +1,68 @@
+import type { SessionId } from '@hydraharness/harness-session/types';
+import type { ApiProxy, ClientResponse, HostFrame, MuxFrame, RpcReceipt, RpcRequest, RpcResponse } from './api.ts';
+import type { RequestPayload, ResponseValue, RpcMethodMap } from '@hydraharness/harness-host-apiproxy/api';
+import { AbstractApiClient } from './api.ts';
+import type { ClientConnectionRpc } from '../rpc.ts';
+/** Deterministic fixture branches used by keyless Web assembly tests. */
+export interface FixtureOptions {
+    /** Start with no real Workspace or Session. */
+    empty?: boolean;
+    /** Reject every prompt before appending its user event. */
+    rejectPrompt?: boolean;
+    /** Publish the Session but fail its Workspace account write. */
+    failWorkspaceAttach?: boolean;
+    /** Publish and frame the Session, then throw instead of returning create. */
+    dropSessionCreateResponse?: boolean;
+    /** Order of the two successful create frames. */
+    createFrameOrder?: 'session-first' | 'workspace-first';
+}
+/**
+ * In-memory fake host: fx-alpha carries history and replay scripts; fx-beta is fx-alpha's child session (lineage indent material).
+ * @param options - fixture branches for empty state and failure timing.
+ * @returns an ApiProxy backed entirely by in-memory state — no host process, no network.
+ */
+export declare function createFixtureApi(options?: FixtureOptions): ApiProxy;
+/** Both fixture faces over one state graph. */
+export interface FixtureWorld {
+    /** Legacy unary/stream API the fixture still answers. */
+    readonly api: ApiProxy;
+    /** Generic Remote caller for the endpoints business services own. */
+    readonly rpc: ClientConnectionRpc;
+}
+/**
+ * Build both fixture faces so a caller can drive the Remote endpoints and the
+ * legacy API against one in-memory state graph.
+ * @param options - fixture branches for empty state and failure timing.
+ * @returns the legacy API face and the Remote RPC face.
+ */
+export declare function createFixtureFaces(options?: FixtureOptions): FixtureWorld;
+/**
+ * Fixture platform subclass: there is no HTTP at all, so instead of a doFetch transport it
+ * overrides the protocol-level virtuals (callUnary/openMux/openHost/respond) to dispatch
+ * straight into the in-memory ApiProxy — while still minting rpcIds, fabricating the four
+ * named full forms, and feeding the same tap as a real carrier. TODO: delete when the fixture
+ * moves to the isomorphic pipeline (InProcessApiClient over toFetchHandler(fixtureImpl)).
+ */
+export declare class FixtureApiClient extends AbstractApiClient {
+    private readonly api;
+    /** Generic Remote caller backed by the same in-memory state as the legacy fixture API. */
+    readonly rpc: ClientConnectionRpc;
+    constructor();
+    protected doFetch(): Promise<Response>;
+    protected callUnary<K extends keyof RpcMethodMap>(method: K, payload: RequestPayload<K>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<K>>>;
+    /** Method-key dispatch into the in-memory contract impl (a real carrier routes by URL path instead). */
+    private dispatch;
+    protected openMux(payload: {
+        since?: Record<SessionId, number>;
+    }, signal: AbortSignal, onOpen?: () => void): AsyncIterable<RpcRequest<MuxFrame>>;
+    protected openHost(payload: Record<never, never>, signal: AbortSignal, onOpen?: () => void): AsyncIterable<RpcRequest<HostFrame>>;
+    private tapStream;
+    /**
+     * Deliver a client response to the in-memory contract impl (no HTTP POST),
+     * echoing the envelope to the observation tap like every other path.
+     * @param message - the client-response envelope answering a server request.
+     * @returns the carrier receipt from the fixture impl.
+     */
+    respond(message: ClientResponse): Promise<RpcReceipt>;
+}
+//# sourceMappingURL=fixture.d.ts.map

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

@@ -0,0 +1,74 @@
+/**
+ * Browser wire client. The plugin selects fixture or HTTP transport, provides
+ * the shared API client, and lets the runtime object layer start the stream
+ * controller with its sinks.
+ */
+import type { Context } from '@hydraharness/cordis';
+import type { HostDescription, IApiClient } from './api.ts';
+import { type ConnectionConfig, type ConnectionSinks, type ConnectionState } from './connection.ts';
+import { type RpcFetch } from './rpc.ts';
+import type { ClientConnectionRpc } from '../rpc.ts';
+export type { ConversationRevision, SessionVersionState, ApiProxy, SessionsApi, SessionSearchItem, SessionSummary, PromptContentPart, HostApi, EventsApi, MuxFrame, HostFrame, ApprovalResponsePayload, QuestionResponsePayload, HistoryEntry, ToolEventView, DirectoryEntry, DirectoryListing, ToolCallView, ToolResultView, WorkspaceApi, WorkspaceId, WorkspaceView, SkillsApi, SkillEntry, ModelCatalogFailure, ModelCatalogModel, ModelProviderGroup, ModelReasoning, MessageId, ModelReasoningEffort, ModelSelection, QueueAction, QueuedInboxItem, SessionModels, SubagentsApi, SubagentAddress, SubagentCatalog, SubagentListEntry, SubagentPromptReceipt, JobView, RpcRequest, RpcResponse, RpcResult, RpcError, RpcErrorCode, ClientRequest, ServerResponse, ServerRequest, ClientResponse, RpcMessage, RpcReceipt, HostDescription, IApiClient, SessionId, SessionEvent, ContentBlock, StreamChunk, GoalsApi, GoalRef, SettingsApi, SettingsNamespaceView, SettingsPathOpView, SettingsSecretView, WorkspaceSettingsStatus, CredentialsApi, CredentialView, ConfigurableProviderView, DiscoveredModelView, LlmApi, AuthorizationAccountView, AuthorizationApi, AuthorizationAttemptView, AuthorizationEntryView, AuthorizationNoticeView, AuthorizationPromptView, AuthorizationUsageView, } from './api.ts';
+export { RpcId, AbstractApiClient, transportError, } from './api.ts';
+export type { ConnectionConfig, ConnectionSinks, ConnectionState };
+export type { ClientConnectionRpc } from '../rpc.ts';
+export type { RpcFetch } from './rpc.ts';
+/** Observable Host description published by each completed connection handshake. */
+export interface HostDescriptionSource {
+    /** Latest connected-generation description; absent before connect and while reconnecting. */
+    getSnapshot(): HostDescription | undefined;
+    /** Subscribe to description replacement and connection loss. */
+    subscribe(listener: () => void): () => void;
+}
+/** Required services (none — this is the wire root). */
+export declare const inject: string[];
+/**
+ * Carrier override installed on the page global before plugin boot. The served
+ * web app leaves it unset and gets HTTP + WebSocket; a shell that owns a
+ * different physical transport (the worker preview's postMessage tunnel)
+ * provides both halves here instead of forking this plugin.
+ */
+export interface ClientTransportHooks {
+    /** Build the API carrier: unary calls plus the two downstream event streams. */
+    createApiClient(): IApiClient;
+    /** Transport for generic unary RPC channels (the Typert gateway). */
+    fetch: RpcFetch;
+    /**
+     * 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 ctx.connection service API: the API client plus a one-shot
+ * controller starter (the runtime plugin supplies sinks when its object layer
+ * is ready — connection stays consumer-agnostic).
+ */
+export interface ConnectionHandle {
+    /** Shared api client (fixture or real, decided at boot from the page URL). */
+    readonly api: IApiClient;
+    /** Whether the current page authority is loopback; non-browser contexts default to true. */
+    readonly isLoopback: boolean;
+    /** Generation-scoped Host facts, including the account home and native path-open capability. */
+    readonly hostDescription: HostDescriptionSource;
+    /** Generic logical RPC channels over the same Connection transport. */
+    readonly rpc: ClientConnectionRpc;
+    /**
+     * Start the connect/pump/reconnect loop with the consumer's frame sinks.
+     * One consumer owns the streams (the runtime object layer); a second call
+     * throws.
+     * @param sinks - frame/state callbacks.
+     * @param config - reconnect/backoff tunables.
+     * @returns stop handle for the loop.
+     */
+    start(sinks: ConnectionSinks, config?: ConnectionConfig): {
+        stop(): void;
+    };
+}
+/**
+ * Client plugin body: pick the api by page mode and provide ctx.connection.
+ * @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,11 @@
+/** 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>;
+/**
+ * Create the browser-backed generic RPC caller.
+ * @param doFetch - transport override; defaults to the page's global fetch.
+ * @returns caller that owns request correlation and response-envelope validation.
+ */
+export declare function createWebConnectionRpc(doFetch?: RpcFetch): ClientConnectionRpc;
+//# sourceMappingURL=rpc.d.ts.map

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

@@ -0,0 +1,11 @@
+/** Browser API carrier: HTTP upstream plus one WebSocket per downstream event stream. */
+import type { ApiProxy, HostFrame, MuxFrame, RpcRequest } from './api.ts';
+import { AbstractApiClient } from './api.ts';
+/** Browser platform subclass: unary/respond use fetch; mux/host use downlink-only WebSockets. */
+export declare class WebApiClient extends AbstractApiClient {
+    protected doFetch(input: URL, init?: RequestInit): Promise<Response>;
+    protected openMux(_payload: Parameters<ApiProxy['events']['mux']>[0]['payload'], signal: AbortSignal, onOpen?: () => void): AsyncIterable<RpcRequest<MuxFrame>>;
+    protected openHost(_payload: Parameters<ApiProxy['events']['host']>[0]['payload'], signal: AbortSignal, onOpen?: () => void): AsyncIterable<RpcRequest<HostFrame>>;
+    private readWebSocket;
+}
+//# sourceMappingURL=web-api-client.d.ts.map

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

@@ -0,0 +1,29 @@
+/**
+ * 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';
+/** Default carrier cap for all HTTP RPC bodies: sized for the default
+ * aggregate image limit (100 MiB) after base64 expansion plus envelope
+ * headroom (~134.3 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;
+/** Transport-independent request handler consumed by the Host HTTP bridge. */
+export interface FetchHandler {
+    /**
+     * Handle one standard Fetch request.
+     * @param request - request produced by the active transport bridge.
+     * @returns complete or streaming Fetch response.
+     */
+    fetch(request: Request): Promise<Response>;
+}
+/**
+ * Bridge one node:http request to the fetch-shaped handler (client close
+ * aborts; SSE bodies stream out chunk by chunk).
+ * @param req - incoming node:http request (fully read before dispatch).
+ * @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 body bytes buffered before dispatch.
+ */
+export declare function bridge(req: IncomingMessage, res: ServerResponse, apiHandler: FetchHandler, maxRequestBodyBytes?: number): Promise<void>;
+//# sourceMappingURL=http-bridge.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,36 @@
+/** Host HTTP bridge for browser-client RPC. */
+import type { Context } from '@hydraharness/cordis';
+import z from '@hydraharness/schemastery';
+export type { ConnectionRpcAuthority, ConnectionRpcEndpointMatcher, ConnectionRpcHandler, ConnectionRpcHandlerOptions, HostConnectionHandle, HostConnectionRpc, } from './rpc.ts';
+export { HostConnectionService } from './rpc-host.ts';
+export { API_PATH, HOST_EVENTS_PATH, MUX_EVENTS_PATH } from './api-path.ts';
+/** Stable Cordis plugin name. */
+export declare const name = "client-connection";
+/** Services required before providing Connection; API Proxy is an optional `/api` fallback. */
+export declare const inject: string[];
+/** Plugin config: the deployment's non-loopback serving authorities. */
+export interface ConnectionConfig {
+    /**
+     * 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 hydra CLI derives the machine's LAN IP literals itself). An entry
+     * that is not a bare, canonical authority fails the plugin load.
+     */
+    trustedHosts?: string[];
+    /** Maximum buffered JSON body for every `/api` request. */
+    maxRequestBodyBytes?: number;
+}
+export declare const Config: z<ConnectionConfig>;
+/**
+ * Mounts the API gateway under the browser transport prefix. Every request on
+ * the prefix passes the browser-trust fence first (DNS-rebinding and
+ * cross-site defense — [api-request-trust](./api-request-trust.ts));
+ * privileged methods additionally pass it with an empty trust list, which
+ * pins them to loopback.
+ * @param ctx - Host plugin context.
+ * @param config - resolved plugin config (schema defaults applied).
+ */
+export declare function apply(ctx: Context, config?: ConnectionConfig): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@hydraharness/harness-client-connection`.
+ * @module @hydraharness/harness-client-connection/invariant
+ */
+import type { Context } from '@hydraharness/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "client-connection-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.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/rpc-host.d.ts

@@ -0,0 +1,34 @@
+/** Host registry and HTTP adapter for generic Connection RPC channels. */
+import { Context, Service } from '@hydraharness/cordis';
+import { type FetchHandler } from './http-bridge.ts';
+import type { HostConnectionHandle, HostConnectionRpc } from './rpc.ts';
+declare module '@hydraharness/cordis' {
+    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 interceptors;
+    /**
+     * Provide the Host half over the active HTTP server.
+     * @param ctx - owning Connection plugin context.
+     * @param trustedHosts - deployment authorities accepted by trusted-host channels.
+     */
+    constructor(ctx: Context, trustedHosts: readonly string[]);
+    /** Generic channel registry scoped to the Context reading this service. */
+    get rpc(): HostConnectionRpc;
+    /**
+     * Compose one shared-channel Fetch handler from its interceptor and fallback.
+     * @param channel - shared channel mounted by Connection.
+     * @param privilegedEndpoints - endpoints pinned to loopback before target selection.
+     * @param fallback - handler for endpoints not claimed by the interceptor.
+     * @returns Fetch handler that selects exactly one target for each request.
+     */
+    createSharedFetchHandler(channel: '/api', privilegedEndpoints: ReadonlySet<string>, fallback: FetchHandler): FetchHandler;
+    private register;
+    private registerInterceptor;
+}
+//# sourceMappingURL=rpc-host.d.ts.map

package/lib/types/rpc.d.ts

@@ -0,0 +1,51 @@
+/** Generic unary RPC contracts shared by the Host and Client Connection halves. */
+import type { RpcResult } from '@hydraharness/harness-host-apiproxy/api';
+/** Trust fence applied before a Host RPC channel reaches its handler. */
+export type ConnectionRpcAuthority = 'trusted-host' | 'loopback';
+/** Registration policy for one logical RPC channel. */
+export interface ConnectionRpcHandlerOptions {
+    /** Browser authority accepted by every endpoint in this channel. */
+    readonly authority: ConnectionRpcAuthority;
+}
+/** Handler invoked after Connection has decoded the transport envelope. */
+export type ConnectionRpcHandler = (endpoint: string, payload: unknown, signal: AbortSignal) => Promise<RpcResult<unknown>>;
+/** Synchronous ownership test for one endpoint on a shared RPC channel. */
+export type ConnectionRpcEndpointMatcher = (endpoint: string) => boolean;
+/** Host registry for logical RPC channels carried by the current transport. */
+export interface HostConnectionRpc {
+    /**
+     * Register one absolute channel prefix and its trust policy.
+     * @param channel - absolute logical channel such as `/rpc`.
+     * @param handler - decoded endpoint handler returning the existing RPC result shape.
+     * @param options - channel trust policy.
+     * @returns asynchronous disposer removing the channel and its physical route.
+     */
+    handle(channel: string, handler: ConnectionRpcHandler, options: ConnectionRpcHandlerOptions): () => Promise<void>;
+    /**
+     * Intercept owned endpoints on the shared `/api` channel before its fallback.
+     * @param channel - reserved shared channel; currently `/api`.
+     * @param matches - synchronous endpoint ownership test.
+     * @param handler - decoded endpoint handler returning the existing RPC result shape.
+     * @param options - trust policy for every endpoint claimed by this interceptor.
+     * @returns asynchronous disposer removing the interceptor.
+     */
+    intercept(channel: '/api', matches: ConnectionRpcEndpointMatcher, handler: ConnectionRpcHandler, options: ConnectionRpcHandlerOptions): () => Promise<void>;
+}
+/** Host `ctx.connection` shape consumed by transport-independent adapters. */
+export interface HostConnectionHandle {
+    /** Generic RPC channel registry. */
+    readonly rpc: HostConnectionRpc;
+}
+/** Client caller for logical RPC channels carried by the current transport. */
+export interface ClientConnectionRpc {
+    /**
+     * Call one endpoint through an already registered logical channel.
+     * @param channel - absolute logical channel such as `/api`.
+     * @param endpoint - channel-relative endpoint such as `goals/create`.
+     * @param payload - channel-owned request payload.
+     * @param signal - optional caller cancellation.
+     * @returns the existing RPC success/error result; correlation stays inside Connection.
+     */
+    call(channel: string, endpoint: string, payload: unknown, signal?: AbortSignal): Promise<RpcResult<unknown>>;
+}
+//# sourceMappingURL=rpc.d.ts.map

package/lib/types/websocket-downlink.d.ts

@@ -0,0 +1,43 @@
+/** Host-side WebSocket carrier for the two server-to-browser event streams. */
+import type { IncomingMessage } from 'node:http';
+import type { Duplex } from 'node:stream';
+import type { ApiProxy } from '@hydraharness/harness-host-apiproxy/api';
+/**
+ * Owns WebSocket negotiation and frame pumping for the connection plugin's
+ * two downlinks. Client messages are a protocol violation: upstream traffic
+ * remains on HTTP.
+ */
+export declare class WebSocketDownlinks {
+    private readonly api;
+    private readonly server;
+    private readonly pumps;
+    /** @param api - host API supplying the typed event streams. */
+    constructor(api: ApiProxy);
+    /**
+     * Upgrade one socket and pump the mux stream until either side closes.
+     * @param req - HTTP upgrade request.
+     * @param socket - Raw socket transferred by the HTTP server.
+     * @param head - Bytes already read after the upgrade headers.
+     */
+    handleMux(req: IncomingMessage, socket: Duplex, head: Buffer): void;
+    /**
+     * Upgrade one socket and pump the host stream until either side closes.
+     * @param req - HTTP upgrade request.
+     * @param socket - Raw socket transferred by the HTTP server.
+     * @param head - Bytes already read after the upgrade headers.
+     */
+    handleHost(req: IncomingMessage, socket: Duplex, head: Buffer): void;
+    /**
+     * Terminate owned sockets and await the no-server acceptor plus frame pumps.
+     * @returns A promise resolving after every socket and source iterator stops.
+     */
+    close(): Promise<void>;
+    private upgrade;
+    private pump;
+}
+/**
+ * Reject an untrusted upgrade before protocol negotiation.
+ * @param socket - Raw HTTP socket that remains owned by the caller.
+ */
+export declare function rejectWebSocketUpgrade(socket: Duplex): void;
+//# sourceMappingURL=websocket-downlink.d.ts.map

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "@hydraharness/harness-client-connection",
+  "description": "Wire consumer layer: HTTP-up/WebSocket-down client, ConnectionController dual streams with reconnect, and fixture api",
+  "version": "0.1.1-rc.10",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MaiHongPhong2010/Hydra-Harness.git",
+    "directory": "packages/client/connection"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./client": {
+      "types": "./lib/types/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "hydra": {
+    "plugin": {
+      "application": "Send interface actions to the Host and receive live updates, including after a reconnect."
+    },
+    "client": {
+      "inject": [],
+      "platform": "web",
+      "immediately": true
+    }
+  },
+  "license": "MIT",
+  "dependencies": {
+    "ws": "^8.21.0",
+    "@hydraharness/schemastery": "^3.18.2"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/client.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "peerDependencies": {
+    "@hydraharness/harness-host-webserver": "^0.1.1-rc.10",
+    "@hydraharness/harness-invariants": "^0.1.1-rc.10",
+    "@hydraharness/cordis": "^4.0.2",
+    "@hydraharness/harness-attachment": "^0.1.1-rc.10",
+    "@hydraharness/harness-host-apiproxy": "^0.1.1-rc.10",
+    "@hydraharness/harness-commands": "^0.1.1-rc.10",
+    "@hydraharness/harness-session": "^0.1.1-rc.10",
+    "@hydraharness/harness-tools": "^0.1.1-rc.10",
+    "@hydraharness/harness-llm": "^0.1.1-rc.10"
+  },
+  "devDependencies": {
+    "@types/ws": "^8.18.1",
+    "@hydraharness/harness-host-webserver": "^0.1.1-rc.10",
+    "@hydraharness/harness-invariants": "^0.1.1-rc.10",
+    "@hydraharness/cordis": "^4.0.2",
+    "@hydraharness/harness-host-apiproxy": "^0.1.1-rc.10",
+    "@hydraharness/harness-attachment": "^0.1.1-rc.10",
+    "@hydraharness/harness-commands": "^0.1.1-rc.10",
+    "@hydraharness/harness-llm": "^0.1.1-rc.10",
+    "@hydraharness/harness-session": "^0.1.1-rc.10",
+    "@hydraharness/harness-tools": "^0.1.1-rc.10"
+  }
+}