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

package/lib/types/rpc.d.ts

@@ -0,0 +1,262 @@
+/** Generic unary RPC contracts shared by the Host and Client Connection halves. */
+import type { Branded } from '@qilin-agent/brand';
+import type { PeerScope } from '@qilin-agent/typert-protocol';
+/** Correlation id minted by a caller and echoed by the Connection response. */
+export type RpcId = Branded<'rpc-id'>;
+/**
+ * Brand one validated string as a Connection correlation id.
+ * @param id - validated wire identity.
+ * @returns the same string with the correlation-id brand.
+ */
+export declare function RpcId(id: string): RpcId;
+/** Carrier-neutral failure returned by one logical RPC endpoint. */
+export interface ConnectionRpcFailure {
+    readonly code: string;
+    readonly message: string;
+    readonly details: object;
+}
+/** Carrier-neutral result returned by one logical RPC endpoint. */
+export type ConnectionRpcResult<T> = {
+    readonly ok: true;
+    readonly value: T;
+} | {
+    readonly ok: false;
+    readonly error: ConnectionRpcFailure;
+};
+/** Historical short name for a generic Connection result. */
+export type RpcResult<T> = ConnectionRpcResult<T>;
+/**
+ * Convert a rejected transport operation into a generic failure result.
+ * @param error - rejected transport value.
+ * @returns an `internal` failure preserving the available message.
+ */
+export declare function transportError<T>(error: unknown): RpcResult<T>;
+/** Narrow request form used by direct fixture adapters. */
+export interface RpcRequest<P> {
+    readonly rpcId: RpcId;
+    readonly payload: P;
+}
+/** Narrow response form used by direct fixture adapters. */
+export interface RpcResponse<T> {
+    readonly rpcId: RpcId;
+    readonly result: RpcResult<T>;
+}
+/** Full request envelope carried by Connection RPC transports. */
+export interface ClientRequest {
+    readonly type: 'client-request';
+    readonly rpcId: RpcId;
+    readonly method: string;
+    readonly payload: unknown;
+}
+/** Full response envelope carried by Connection RPC transports. */
+export interface ServerResponse {
+    readonly type: 'server-response';
+    readonly rpcId: RpcId;
+    readonly result: ConnectionRpcResult<unknown>;
+}
+/** Complete Connection RPC envelope union. */
+export type RpcMessage = ClientRequest | ServerResponse;
+/** HTTP request facts consumed by browser trust and authentication. */
+export interface ConnectionTrustRequest {
+    /** Request headers supplied by either the Fetch or node:http representation. */
+    readonly headers: Headers | Readonly<Record<string, string | readonly string[] | undefined>>;
+    /** Request method as received; node:http and Fetch callers always supply it. */
+    readonly method?: string | undefined;
+    /** Request target as received; node:http and Fetch callers always supply it. */
+    readonly url?: string | undefined;
+}
+/** HTTP status returned before dispatch, or undefined when the request may proceed. */
+export type ConnectionRequestRejection = 401 | 403 | undefined;
+/** Entry and configured-index request facts used by the browser-token exchange and the account-session gate. */
+export type ConnectionIndexRequest = ConnectionTrustRequest;
+/** Root/index response operations owned by the browser-token exchange. */
+export interface ConnectionIndexResponse {
+    writeHead(status: number, headers?: Readonly<Record<string, string>>): unknown;
+    end(body?: string): unknown;
+}
+/** Outcome of admitting one request: the operator Peer it speaks for, or the status refusing it. */
+export type PeerAdmission = {
+    readonly peer: PeerScope;
+} | {
+    readonly rejection: 401 | 403;
+};
+/**
+ * Handler invoked after Connection has decoded the transport envelope.
+ * `peer` is the Peer the request was admitted as: the operator.
+ */
+export type ConnectionRpcHandler = (endpoint: string, payload: unknown, signal: AbortSignal, peer: PeerScope) => Promise<ConnectionRpcResult<unknown>>;
+/** Synchronous ownership test for one endpoint on a shared RPC channel. */
+export type ConnectionRpcEndpointMatcher = (endpoint: string) => boolean;
+/** HTTP methods supported by exact Fetch routes on the shared API channel. */
+export type ConnectionFetchMethod = 'GET' | 'HEAD' | 'POST';
+/** How the node:http bridge presents one request body to its Fetch route. */
+export type ConnectionRequestBodyMode = 'buffered' | 'streaming';
+/** One exact, transport-independent Fetch route owned by a Host feature. */
+export interface ConnectionFetchRoute {
+    /** Absolute path below `/api`; query parameters remain available on the request URL. */
+    readonly path: string;
+    /** Methods this route owns. Other methods continue through normal shared-channel dispatch. */
+    readonly methods: readonly ConnectionFetchMethod[];
+    /** Buffered requests obey the configured JSON cap; streaming requests arrive with backpressure and no aggregate cap. */
+    readonly requestBody: ConnectionRequestBodyMode;
+    /** Handle one request after the physical carrier has applied its trust and authentication policy. */
+    readonly fetch: (request: Request) => Promise<Response>;
+}
+/** Host registry for exact Fetch routes that cannot use JSON Remote invocation. */
+export interface HostConnectionFetch {
+    /**
+     * Register one exact route on the shared API channel.
+     * @param route - path, methods, and Fetch-shaped implementation.
+     * @returns asynchronous disposer removing this exact contribution.
+     */
+    register(route: ConnectionFetchRoute): () => Promise<void>;
+}
+/** Host registry for logical RPC channels carried by the current transport. */
+export interface HostConnectionRpc {
+    /**
+     * Register one authenticated absolute channel prefix.
+     * @param channel - absolute logical channel such as `/rpc`.
+     * @param handler - decoded endpoint handler returning the existing RPC result shape.
+     * @returns asynchronous disposer removing the channel and its physical route.
+     */
+    handle(channel: string, handler: ConnectionRpcHandler): () => 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.
+     * @returns asynchronous disposer removing the interceptor.
+     */
+    intercept(channel: '/api', matches: ConnectionRpcEndpointMatcher, handler: ConnectionRpcHandler): () => Promise<void>;
+}
+/**
+ * One account session's verdicts for the transport gates. The authentication
+ * plugin owns them; Connection owns the enforcement points (every configured
+ * index path and the shared `/api` route) and never inspects session state
+ * itself.
+ */
+export interface ConnectionSessionAuthority {
+    /**
+     * Own the browser response for one gated index request.
+     * @param request - entry or configured-index HTTP request.
+     * @param response - response owned when this returns false.
+     * @returns true when the caller may serve the index document.
+     */
+    authorizeIndex(request: ConnectionIndexRequest, response: ConnectionIndexResponse): boolean;
+    /**
+     * Whether one `/api` request needs no session because it belongs to the
+     * authentication surface itself.
+     * @param request - incoming request headers and target.
+     * @returns true when the request may proceed without an account session.
+     */
+    isPublicApiRequest(request: ConnectionTrustRequest): boolean;
+    /**
+     * Verify the request's account session.
+     * @param request - incoming request headers.
+     * @returns true only for an unexpired session this authority issued.
+     */
+    verify(request: ConnectionTrustRequest): boolean;
+}
+/** Registration seat for the one account-session authority of this transport. */
+export interface HostConnectionSession {
+    /**
+     * Install the account-session authority consulted by the index and `/api`
+     * gates. One owner: a second installation fails the installing plugin's
+     * load, because two session authorities cannot compose. The seat belongs to
+     * the installing plugin's fiber, so disposing it releases the seat.
+     * @param authority - the authentication capability's verdicts.
+     */
+    install(authority: ConnectionSessionAuthority): void;
+}
+/** Host `ctx.connection` members consumed by transport-independent adapters. */
+export interface HostConnectionHandle {
+    /** Generic RPC channel registry. */
+    readonly rpc: HostConnectionRpc;
+    /** Exact Fetch routes for streaming or browser-native responses. */
+    readonly fetch: HostConnectionFetch;
+    /** The operator Peer every admitted request speaks for; its scope lives as long as Connection. */
+    readonly operator: PeerScope;
+    /** Account-session gate seat; unclaimed keeps device-token authentication. */
+    readonly session: HostConnectionSession;
+    /**
+     * Request path serving the application document: the launch-token handoff
+     * target, and therefore the index path every dist server must mount.
+     */
+    readonly entryPath: string;
+    /**
+     * Compose exact Fetch routes and the shared-channel RPC interceptor.
+     * @param channel - shared channel mounted by Connection.
+     * @returns Fetch handler for trusted, authenticated requests.
+     */
+    createSharedFetchHandler(channel: '/api'): ConnectionFetchHandler;
+    /**
+     * Apply Connection's Host/Origin checks and browser authentication to
+     * another Web route.
+     * @param request - request headers from the HTTP or upgrade request.
+     * @returns rejection status, or undefined when the route may accept the request.
+     */
+    requestRejection(request: ConnectionTrustRequest): ConnectionRequestRejection;
+    /**
+     * Admit one request: it passes {@link requestRejection} and speaks for the
+     * operator, or it is refused with that status.
+     * @param request - request headers from the HTTP or upgrade request.
+     * @returns the operator Peer, or the rejection status.
+     */
+    admit(request: ConnectionTrustRequest): PeerAdmission;
+    /**
+     * Authenticate one frontend index request, owning a token redirect or 401.
+     * @param request - root or configured-index HTTP request.
+     * @param response - response owned when the result is false.
+     * @returns true only when the frontend may serve index.html.
+     */
+    authorizeIndex(request: ConnectionIndexRequest, response: ConnectionIndexResponse): boolean;
+    /**
+     * Add the fresh process token to an ordinary Web application URL.
+     * @param baseUrl - clean canonical browser origin.
+     * @param displayName - optional operator name carried into the device cookie for display.
+     * @returns root URL accepted by {@link authorizeIndex} for initial login.
+     */
+    authenticatedUrl(baseUrl: string, displayName?: string): string;
+}
+/** Transport-independent Fetch handler used by HTTP and worker carriers. */
+export interface ConnectionFetchHandler {
+    /**
+     * Resolve body handling before the bridge reads any request bytes.
+     * @param request - request method and URL available from node:http headers.
+     * @returns the registered route's body handling mode.
+     */
+    requestBodyMode(request: {
+        readonly method: string;
+        readonly url: URL;
+    }): ConnectionRequestBodyMode;
+    /**
+     * Dispatch one already-authenticated request.
+     * @param request - Fetch request below the shared channel.
+     * @returns the registered response or a 404 response.
+     */
+    fetch(request: Request): Promise<Response>;
+}
+/** 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 endpoint-owned success/error result; correlation stays inside Connection.
+     */
+    call(channel: string, endpoint: string, payload: unknown, signal?: AbortSignal): Promise<ConnectionRpcResult<unknown>>;
+    /**
+     * Open an in-process logical stream when the selected carrier supplies one.
+     * Browser transports omit this method; API Gateway owns their WebSocket mux.
+     * @param channel - absolute logical channel such as `/api`.
+     * @param endpoint - channel-relative endpoint such as `session/follow`.
+     * @param payload - channel-owned request payload.
+     * @param signal - caller cancellation for this logical stream.
+     * @param uplink - Client uplink items the Host method reads through `invocation.uplink()`.
+     * @returns decoded stream values from the in-process carrier.
+     */
+    readonly open?: (channel: string, endpoint: string, payload: unknown, signal: AbortSignal, uplink?: AsyncIterable<unknown>) => AsyncIterable<unknown>;
+}
+//# sourceMappingURL=rpc.d.ts.map

package/lib/types/web-entry.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The one request path that serves the harness application document. The site
+ * root keeps the public landing page and the sign-in screens have their own
+ * documents, so every entry URL, redirect, and deployment index path names
+ * this constant instead of repeating the literal.
+ */
+/** Request path serving the harness application document. */
+export declare const WEB_ENTRY_PATH = "/workspace";
+//# sourceMappingURL=web-entry.d.ts.map

package/package.json

@@ -1,6 +1,68 @@
 {
   "name": "@qilin-agent/client-connection",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "description": "Authenticated RPC transport and generation lifecycle",
+  "version": "3.1.3",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kkutysllb/QiLin.git",
+    "directory": "packages/client/connection"
+  },
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./client": {
+      "types": "./lib/types/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "qilin": {
+    "client": {
+      "inject": [],
+      "platform": "web",
+      "immediately": true
+    }
+  },
+  "license": "MIT",
+  "dependencies": {
+    "zod": "^4.4.3",
+    "@qilin-agent/credentials": "3.1.3",
+    "@qilin-agent/schemastery": "~3.18.3"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/client.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "peerDependencies": {
+    "@qilin-agent/scope": "3.1.3",
+    "@qilin-agent/kylin": "~4.0.3"
+  },
+  "devDependencies": {
+    "@qilin-agent/kylin": "~4.0.3",
+    "@qilin-agent/attachment": "3.1.3",
+    "@qilin-agent/brand": "3.1.3",
+    "@qilin-agent/host-webserver": "3.1.3",
+    "@qilin-agent/llm": "3.1.3",
+    "@qilin-agent/scope": "3.1.3",
+    "@qilin-agent/session": "3.1.3",
+    "@qilin-agent/typert-protocol": "3.1.3",
+    "@qilin-agent/tool-todo": "3.1.3",
+    "@qilin-agent/util-values": "3.1.3",
+    "@qilin-agent/commands": "3.1.3",
+    "@qilin-agent/settings": "3.1.3",
+    "@qilin-agent/host-directory-picker": "3.1.3"
+  }
 }