@qilin-agent/cli 0.0.0-stage → 3.1.4

package/lib/tenants-roster-Bhr9x2Jw.js

@@ -0,0 +1,252 @@
+import { a as isTenantIdentity } from "./tenant-runtime-ChD53FKq.js";
+import { resolveQilinHome } from "@qilin-agent/home-paths";
+import { mkdir, rm, stat } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { createInterface } from "node:readline/promises";
+import { Writable } from "node:stream";
+import { AccountStore, MIN_PASSWORD_LENGTH, accountsFilePath, isValidEmail, isValidUsername, normalizeEmail, normalizeUsername } from "@qilin-agent/accounts-local";
+//#region lib/types/tenants-roster.js
+/**
+* `qilin tenants` roster operations: the account file every tenant runtime on
+* this Harness home shares, and the tenant directory each account owns.
+*
+* A tenant runtime admits exactly the account it serves, so a new account
+* cannot be created through a tenant's own Web surface (its registration is
+* closed). These commands are how a deployment adds, re-keys, and retires the
+* accounts its tenant runtimes serve.
+* @module @qilin-agent/cli/tenants-roster
+*/
+/** Absolute tenant directory one account owns. */
+function tenantDirectory(home, accountId) {
+	return join(home, "tenants", accountId);
+}
+/** Whether a path exists. */
+async function exists(path) {
+	return await stat(path).then(() => true, () => false);
+}
+/** Open the shared home's roster. */
+async function roster(home) {
+	return await AccountStore.open(accountsFilePath(home));
+}
+/**
+* Every account of one shared home with the tenant directory it owns.
+* @param home - absolute shared Harness home.
+* @returns one entry per account, oldest first.
+*/
+async function rosterEntries(home) {
+	const store = await roster(home);
+	return await Promise.all(store.all().map(async (account) => ({
+		id: account.id,
+		username: account.username,
+		email: account.email,
+		createdAt: account.createdAt,
+		tenantDirectory: tenantDirectory(home, account.id),
+		tenantDataPresent: await exists(tenantDirectory(home, account.id))
+	})));
+}
+/**
+* Create one account in the shared roster.
+* @param home - absolute shared Harness home.
+* @param request - the login name, address, password, and administrator seat.
+* @returns the created account.
+* @throws Error when the name or address is refused or already taken, or when
+* the deployment already has an administrator.
+*/
+async function addAccount(home, request) {
+	const username = normalizeUsername(request.username);
+	if (!isValidUsername(username)) throw new Error(`qilin tenants: '${request.username}' is not an acceptable username: 3-32 characters of a-z, 0-9, '_', '.', or '-', starting with a letter or digit`);
+	if (request.password.length < MIN_PASSWORD_LENGTH) throw new Error(`qilin tenants: a password needs at least ${String(MIN_PASSWORD_LENGTH)} characters`);
+	const store = await roster(home);
+	if (store.byUsername(username) !== void 0) throw new Error(`qilin tenants: the account ${username} already exists`);
+	let email = null;
+	if (request.email !== void 0 && request.email.trim() !== "") {
+		email = normalizeEmail(request.email);
+		if (!isValidEmail(email)) throw new Error(`qilin tenants: '${request.email}' is not an acceptable email address`);
+		if (store.byEmail(email) !== void 0) throw new Error(`qilin tenants: the address ${email} already belongs to an account`);
+	}
+	return await store.add({
+		username,
+		email
+	}, request.password, { admin: request.admin === true });
+}
+/**
+* Replace one account's password, retiring the sessions the previous one issued.
+* @param home - absolute shared Harness home.
+* @param username - the account's login name, normalized before lookup.
+* @param password - the replacement password.
+* @returns the stored successor.
+* @throws Error when no account has that name or the password is too short.
+*/
+async function setAccountPassword(home, username, password) {
+	if (password.length < MIN_PASSWORD_LENGTH) throw new Error(`qilin tenants: a password needs at least ${String(MIN_PASSWORD_LENGTH)} characters`);
+	const store = await roster(home);
+	const account = store.byUsername(normalizeUsername(username));
+	if (account === void 0) throw new Error(`qilin tenants: no account is named ${normalizeUsername(username)}`);
+	return await store.setPassword(account.id, password);
+}
+/**
+* Remove one account from the shared roster.
+*
+* A running tenant runtime keeps serving the account until it is reclaimed or
+* restarted; a runtime started afterwards fails loud, because the overlay
+* admits an account the roster no longer holds.
+* @param home - absolute shared Harness home.
+* @param username - the account's login name, normalized before lookup.
+* @param purgeData - also remove that account's tenant directory.
+* @returns the removed account and, when asked, the removed directory.
+* @throws Error when no account has that name, or when the tenant directory is not where it belongs.
+*/
+async function removeAccount(home, username, purgeData) {
+	const store = await roster(home);
+	const account = store.byUsername(normalizeUsername(username));
+	if (account === void 0) throw new Error(`qilin tenants: no account is named ${normalizeUsername(username)}`);
+	const directory = tenantDirectory(home, account.id);
+	const resolved = resolve(directory);
+	if (purgeData && (!isTenantIdentity(account.id) || dirname(resolved) !== resolve(join(home, "tenants")))) throw new Error(`qilin tenants: refusing to remove ${resolved}, which is not this account's tenant directory`);
+	const removed = await store.remove(account.id);
+	if (!purgeData || !await exists(directory)) return {
+		account: removed,
+		purgedDirectory: void 0
+	};
+	await rm(directory, {
+		recursive: true,
+		force: true
+	});
+	return {
+		account: removed,
+		purgedDirectory: directory
+	};
+}
+/**
+* Read one password from standard input without echoing it.
+* @param prompt - the text shown on standard error before reading.
+* @returns the entered line, without its terminator.
+* @throws Error when standard input is not a terminal, so an unattended run cannot wait for input.
+*/
+async function promptPassword(prompt) {
+	if (!process.stdin.isTTY) throw new Error("qilin tenants: standard input is not a terminal; pipe the password in and pass --password-stdin");
+	const silent = new Writable({ write(_chunk, _encoding, done) {
+		done();
+	} });
+	const prompt_ = createInterface({
+		input: process.stdin,
+		output: silent,
+		terminal: true
+	});
+	try {
+		process.stderr.write(prompt);
+		const entered = await prompt_.question("");
+		process.stderr.write("\n");
+		return entered;
+	} finally {
+		prompt_.close();
+	}
+}
+/**
+* Read the first line of standard input.
+* @returns the line, without its terminator.
+*/
+async function readStandardInput() {
+	const chunks = [];
+	for await (const chunk of process.stdin) chunks.push(Buffer.from(chunk));
+	return (Buffer.concat(chunks).toString("utf8").split("\n")[0] ?? "").replace(/\r$/u, "");
+}
+/**
+* Read the password one mutation applies.
+* @param source - whether to prompt or read standard input.
+* @param label - the account being changed, named in the confirmation prompt.
+* @returns the password.
+* @throws Error when an interactive entry is not confirmed, or when standard input is a terminal without a prompt.
+*/
+async function readPassword(source, label) {
+	if (source.kind === "stdin") return await readStandardInput();
+	const entered = await promptPassword(`Password for ${label}: `);
+	if (entered !== await promptPassword("Repeat password: ")) throw new Error("qilin tenants: the two passwords differ");
+	return entered;
+}
+/** One roster row as the table prints it. */
+function formatRow(entry) {
+	const created = new Date(entry.createdAt).toISOString().slice(0, 10);
+	const data = entry.tenantDataPresent ? "yes" : "no";
+	return `${entry.username.padEnd(20)} ${entry.id} ${created} ${data.padEnd(3)} ${entry.email ?? "-"}`;
+}
+/**
+* Print the roster of one shared home.
+* @param home - absolute shared Harness home.
+* @param write - where each line goes.
+* @returns the printed entries.
+*/
+async function printRoster(home, write) {
+	const entries = await rosterEntries(home);
+	if (entries.length === 0) {
+		write(`qilin tenants: ${home} has no accounts yet; create one with: qilin tenants add <username>`);
+		return entries;
+	}
+	write("USERNAME             ID                                   CREATED    DATA EMAIL");
+	for (const entry of entries) write(formatRow(entry));
+	write(`qilin tenants: ${String(entries.length)} account(s) in ${accountsFilePath(home)}`);
+	return entries;
+}
+/**
+* Create the tenant directory one account owns, so its first runtime starts in
+* a directory that exists even before a browser visits it.
+* @param home - absolute shared Harness home.
+* @param accountId - the account whose directory to create.
+* @returns the absolute directory.
+*/
+async function ensureTenantDirectory(home, accountId) {
+	const directory = tenantDirectory(home, accountId);
+	await mkdir(directory, { recursive: true });
+	return directory;
+}
+/**
+* Run one roster subcommand over this Harness home and print what it did.
+*
+* Failures are reported as a message and a non-zero exit code rather than a
+* stack trace: every refusal here is something the operator can correct.
+* @param request - the roster subcommand and its arguments.
+* @returns the process exit code: 0 when the request was carried out, 1 when it was refused.
+*/
+async function runTenantsRoster(request) {
+	const home = resolveQilinHome();
+	try {
+		switch (request.command) {
+			case "accounts":
+				await printRoster(home, (line) => {
+					process.stdout.write(`${line}\n`);
+				});
+				return 0;
+			case "add": {
+				const password = await readPassword(request.password, request.username);
+				const account = await addAccount(home, {
+					username: request.username,
+					email: request.email,
+					password,
+					admin: request.admin
+				});
+				const directory = await ensureTenantDirectory(home, account.id);
+				process.stdout.write(`qilin tenants: created ${account.username} (${account.id}); its tenant directory is ${directory}\n`);
+				if (account.admin === true) process.stdout.write(`qilin tenants: ${account.username} is this deployment's administrator and reads every account's usage ledger\n`);
+				return 0;
+			}
+			case "passwd": {
+				const password = await readPassword(request.password, request.username);
+				const account = await setAccountPassword(home, request.username, password);
+				process.stdout.write(`qilin tenants: replaced the password of ${account.username}; sessions it issued no longer verify\n`);
+				return 0;
+			}
+			case "remove": {
+				const removed = await removeAccount(home, request.username, request.purgeData);
+				const kept = removed.purgedDirectory === void 0 ? `its Sessions stay in ${tenantDirectory(home, removed.account.id)}` : `its tenant directory ${removed.purgedDirectory} is gone`;
+				process.stdout.write(`qilin tenants: retired ${removed.account.username} (${removed.account.id}); ${kept}\n`);
+				return 0;
+			}
+			default: throw new Error(`qilin tenants: unhandled roster subcommand ${JSON.stringify(request)}`);
+		}
+	} catch (error) {
+		process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+		return 1;
+	}
+}
+//#endregion
+export { runTenantsRoster };

package/lib/types/args.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Commander adapter for the `qilin` command line.
+ *
+ * The launcher parses only what it owns — which profile to boot, which extra
+ * patch overlays to apply, and the config dumps — and hands **everything after
+ * its own flags** to the booted tree verbatim, where injected app plugins parse
+ * their own flag families and print their own `--help` (see
+ * `@qilin-agent/cmdline`). Launcher flags therefore come first: the first
+ * token this parser does not recognize starts the inner arguments, so
+ * `qilin --profile tui --resume abc` boots the tui profile with `--resume abc`,
+ * and `qilin --profile web -h` prints the web app's help, not this one's.
+ *
+ * `qilin <name>` abbreviates `qilin --profile <name>`; `plugin` manages a profile's
+ * plugin dependencies by forwarding to pnpm.
+ * @module @qilin-agent/cli/args
+ */
+import type { RosterRequest } from './tenants-roster.ts';
+/** Boot a named profile and hand it the invocation's inner arguments. */
+interface ProfileInvocation {
+    mode: 'profile';
+    profile: string;
+    /** Shipped template used once to initialize a missing profile. */
+    fromDefaultProfile?: string | undefined;
+    /** Extra patch-list overlays applied after the profile's own layer, in argv order. */
+    patches: string[];
+    /** Everything after the launcher's own flags, verbatim, for injected app plugins. */
+    args: string[];
+}
+/** Print a composed profile tree and exit without booting. */
+interface DumpConfigInvocation {
+    mode: 'dump-config';
+    profile: string;
+    /** Shipped template used once to initialize a missing profile. */
+    fromDefaultProfile?: string | undefined;
+    /** Omit the profile's user layer and --patch overlays; print bundle layers only. */
+    defaultOnly: boolean;
+    patches: string[];
+}
+/** Manage a profile's plugins: forward `args` to pnpm inside the profile directory. */
+interface PluginInvocation {
+    mode: 'plugin';
+    profile: string;
+    /** Raw pnpm arguments, verbatim. */
+    args: string[];
+}
+/** What one `qilin tenants` invocation asks for. */
+type TenantsRequest = RosterRequest;
+/** Serve one isolated Web runtime per account, or manage this home's roster. */
+interface TenantsInvocation {
+    mode: 'tenants';
+    /** The validated subcommand and the options it takes. */
+    request: TenantsRequest;
+}
+/** The resolved `qilin` invocation. Help, version, and errors exit inside {@link parseQilinArgs}. */
+export type QilinInvocation = ProfileInvocation | DumpConfigInvocation | PluginInvocation | TenantsInvocation;
+/**
+ * Resolve argv into one invocation, or print and exit for help, version, or an
+ * error.
+ * @param argv - arguments after the Node binary and script.
+ * @param version - version string printed by `--version`.
+ * @returns the resolved invocation.
+ */
+export declare function parseQilinArgs(argv: readonly string[], version: string): QilinInvocation;
+export {};
+//# sourceMappingURL=args.d.ts.map

package/lib/types/bin.d.ts

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+/**
+ * Command-line entry for qilin.
+ * @module @qilin-agent/cli/bin
+ */
+/**
+ * Run the public qilin command-line interface.
+ * @returns a promise that settles when the selected command mode finishes.
+ */
+export declare function runCli(): Promise<void>;
+//# sourceMappingURL=bin.d.ts.map

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

@@ -0,0 +1,18 @@
+/**
+ * Config-dump entry for `qilin --profile <name> --dump-config`: compose the
+ * profile's patch layers through the include plugin's patch algorithm without
+ * booting or evaluating `!!js`, with one source layer per bundle, the
+ * profile's own patch file, and each `--patch` overlay.
+ * @module @qilin-agent/cli/dump-config
+ */
+/**
+ * Print a profile composition with comments naming each source file and patch layer.
+ * @param profile - the profile name.
+ * @param defaultOnly - omit the profile's user layer and `--patch` overlays
+ * (the recovery diagnostic for a broken `cordis.patch.yml`, which is then
+ * never parsed).
+ * @param patches - `--patch` overlay paths, in argv order.
+ * @param fromDefaultProfile - shipped template used once to initialize a missing profile.
+ */
+export declare function runDumpConfig(profile: string, defaultOnly: boolean, patches: readonly string[], fromDefaultProfile?: string): void;
+//# sourceMappingURL=dump-config.d.ts.map

package/lib/types/plugin.d.ts

@@ -0,0 +1,29 @@
+/**
+ * `qilin plugin [--profile <name>] <args...>` — profile plugin management.
+ *
+ * `list` and `doctor` are the launcher's own verbs and never mutate anything:
+ * `list` prints the profile's bundle layers, and `doctor` reports one plugin
+ * package's DSH-era compatibility. `version-exemptions`, `allow-version`, and
+ * `revoke-version` read and write the profile's own `compatibility.json` under
+ * its file lock and never become pnpm arguments. Every other argument list
+ * forwards to pnpm in the profile directory: refuse the packages it names that
+ * the running runtime version rejects, initialize the profile on first use, run
+ * `pnpm <args...>`, then reconcile the `qilin.profile.bundles` layer list
+ * against the installed state (a dependency resolving to a package that
+ * declares `qilin.bundle` joins the layer stack; a removed or bundle-less
+ * dependency leaves it). Reconciling by installed state, not by dependency
+ * diff, means `update` activates a package that gained its `qilin.bundle`
+ * declaration in a newer version. A profile that installed an upstream DSH-era
+ * engine package is refused before any layer changes, with the removal command
+ * in the diagnostic.
+ * @module @qilin-agent/cli/plugin
+ */
+/**
+ * Run one `qilin plugin` invocation: report or list, grant or revoke one
+ * exact-version exemption, or forward to pnpm and reconcile.
+ * @param profile - the profile name.
+ * @param args - the subcommand and its arguments, or pnpm arguments with relative path specs anchored to the invoking directory.
+ * @returns the process exit code, or 1 when a report, an exemption, or the reconcile refused the profile.
+ */
+export declare function runPlugin(profile: string, args: readonly string[]): Promise<number>;
+//# sourceMappingURL=plugin.d.ts.map

package/lib/types/process-shutdown.d.ts

@@ -0,0 +1,20 @@
+/** Bounded, escalating process shutdown for the long-lived CLI surfaces. */
+/** Maximum grace allowed for the application tree to dispose before process exit. */
+export declare const PROCESS_SHUTDOWN_TIMEOUT_MS = 5000;
+/** Process-exit controller shared by normal completion and Unix signal handlers. */
+export interface ProcessShutdown {
+    /** Start or join graceful disposal before allowing natural completion with `code`. */
+    shutdown(code: number): Promise<void>;
+    /** Start graceful disposal followed by exit, or force exit when shutdown is already running. */
+    interrupt(code: number): void;
+}
+/**
+ * Create one process-exit controller around an application disposer.
+ * @param dispose - Whole-application teardown that resolves at quiescence.
+ * @param forceExit - Function that exits the process immediately, replaceable by tests.
+ * @param complete - Function that records the natural completion code, replaceable by tests.
+ * @param timeoutMs - Grace before forced exit, replaceable by tests.
+ * @returns A controller whose normal calls coalesce and whose repeated signal call escalates.
+ */
+export declare function createProcessShutdown(dispose: () => Promise<void>, forceExit?: (code: number) => void, complete?: (code: number) => void, timeoutMs?: number): ProcessShutdown;
+//# sourceMappingURL=process-shutdown.d.ts.map

package/lib/types/profile-boot.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Shared profile boot for every `qilin` surface: resolve the profile, stack its
+ * patch layers (bundle layers in `qilin.profile.bundles` order, the profile's
+ * own `cordis.patch.yml`, `--patch` overlays, the telemetry switch), mount the
+ * tree over the profile's empty root config, and wire fail-loud plus bounded shutdown.
+ *
+ * App flags are not the launcher's business: the invocation's inner arguments
+ * are provided to the tree through `ctx.cmdlineArgs`, where any injected app
+ * plugin may read the same immutable snapshot.
+ * @module @qilin-agent/cli/profile-boot
+ */
+import { type Context } from '@qilin-agent/kylin';
+import { type ProfileContext, type Profile, type ProfileResolutionMode } from '@qilin-agent/app-boot';
+import { type LaunchEnvironmentSnapshot } from '@qilin-agent/launch-environment';
+import { type ProcessShutdown } from './process-shutdown.ts';
+/**
+ * The home-level user patch layer (`$QILIN_HOME/cordis.patch.yml`), applied
+ * over every profile's own layer. Resolved per call, not at module load:
+ * `$QILIN_HOME` may be set by the test or launcher after import.
+ * @returns the absolute patch-file path.
+ */
+export declare function homePatchPath(): string;
+/** Absolute path of this qilin installation's package.json (both anchors: src/ and lib/ sit one level under apps/cli). */
+export declare const INSTALL_ANCHOR: string;
+/** Root config filename inside a profile directory. */
+export declare const PROFILE_ROOT_FILENAME = "cordis.yml";
+/**
+ * Initialize a missing profile from one shipped template. This copies only
+ * the template's bundle list; local state from the
+ * same-named shipped profile is not read, and no inheritance metadata is
+ * persisted. Shipped profile names are reserved, and the target directory is
+ * claimed exclusively so existing or concurrent state is never reused.
+ * @param name - the new profile name.
+ * @param fromDefaultProfile - shipped profile template to copy.
+ * @param home - Harness home containing the profile directory.
+ * @throws when the template is unknown, the target name is shipped, or the target directory exists.
+ */
+export declare function initializeProfileFromDefault(name: string, fromDefaultProfile: string, home?: string): void;
+/**
+ * Load a resolved profile for `name` and (re)write the empty root config. The
+ * root is always rewritten: the whole composition is patch layers, and the
+ * vendored Loader's tree write-back (a plugin self-disposing persists the
+ * current tree) can bake composed rows into this file — which would duplicate
+ * every bundle insert on the next boot. The file exists on disk only because
+ * the Loader needs a real include root to anchor `baseUrl` at the profile
+ * directory (the config dump anchors on the same file, so both compose over
+ * the identical base).
+ * @param name - the profile name.
+ * @param userLayer - `false` skips parsing `cordis.patch.yml` (the default dump).
+ * @param fromDefaultProfile - shipped template used once to initialize a missing profile.
+ * @returns the loaded profile.
+ * @throws when explicit initialization names an unknown template or an existing profile.
+ */
+export declare function prepareProfile(name: string, userLayer?: boolean, fromDefaultProfile?: string): Profile;
+/** An application-owned profile and its independent installation fallback. */
+export interface ResolvedProfileRuntime {
+    /** Profile already loaded from the application's own directory. */
+    profile: Profile;
+    /** Absolute package.json path of the application's qilin installation. */
+    installAnchor: string;
+}
+/** Options for {@link runProfile}. */
+export interface RunProfileOptions {
+    /** This run's frozen environment snapshot, provided before any entry mounts. */
+    environment: LaunchEnvironmentSnapshot;
+    /** The profile name to boot. */
+    profile: string;
+    /** Loaded application profile; bypasses named profile initialization when supplied. */
+    resolvedProfile?: ResolvedProfileRuntime | undefined;
+    /** Shipped template used once to initialize a missing profile. */
+    fromDefaultProfile?: string | undefined;
+    /** `--patch` overlay paths, in argv order. */
+    patchFiles: readonly string[];
+    /** The invocation's inner arguments, handed to the tree through `ctx.cmdlineArgs`. */
+    args: readonly string[];
+    /** Application-owned package runtime, scoped to plugin package operations. */
+    packageManager?: ProfileContext['packageManager'];
+    /** Module fallback backend; defaults to runtime. Plain Node callers may override it; pkg executables always use runtime. */
+    resolutionMode?: ProfileResolutionMode;
+}
+/**
+ * Boot one profile invocation end to end and leave process lifetime to the
+ * mounted plugins (or to a one-shot runner the composition mounts).
+ * @param options - environment snapshot, profile name, overlays, and the booted app's own arguments.
+ * @returns the settled root context and the shutdown controller.
+ * @throws after disposing startup resources; cleanup failures retain the original error.
+ */
+export declare function runProfile(options: RunProfileOptions): Promise<{
+    ctx: Context;
+    shutdown: ProcessShutdown;
+}>;
+//# sourceMappingURL=profile-boot.d.ts.map

package/lib/types/scheduler-yield.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Host fallback for the Web Scheduler API global.
+ * @module @qilin-agent/cli/scheduler-yield
+ */
+/**
+ * Install `globalThis.scheduler.yield` unless the host already defines a
+ * `scheduler`.
+ *
+ * The fallback resolves on the next `setImmediate` — the API's "yield to the
+ * event loop once, then continue" semantic — and a host-provided `scheduler`
+ * is left untouched. Call it before importing anything that may read the
+ * global; `bin.ts` calls it at the top of the entry, ahead of every mode
+ * module. Rationale: [the host-shim Agent
+ * Note](../../../.agents/notes/implemented/architecture/2026-10-07-web-scheduler-yield-host-shim.md).
+ *
+ * @returns whether this call installed the fallback.
+ */
+export declare function installSchedulerYield(): boolean;
+//# sourceMappingURL=scheduler-yield.d.ts.map

package/lib/types/startup-diagnostics.d.ts

@@ -0,0 +1,19 @@
+/** Save original startup diagnostics while keeping the terminal report concise. */
+import type { StartupError } from '@qilin-agent/app-boot';
+/** Launcher-owned context; no environment values or plugin configurations are collected. */
+interface StartupDiagnosticContext {
+    home: string;
+    version: string;
+    profile: string;
+}
+/**
+ * Print the startup summary and save a private, uniquely named report under QILIN_HOME/logs.
+ * Failed writes print the complete report to stderr instead of claiming a saved path.
+ * @param error - startup audit failure retaining plugin metadata and original errors.
+ * @param context - resolved Harness home, application version, and selected profile.
+ * @param write - terminal output sink; awaited before returning, defaults to stderr.
+ * @returns after saving or printing the report and completing terminal writes.
+ */
+export declare function reportStartupFailure(error: StartupError, context: StartupDiagnosticContext, write?: (text: string) => void | Promise<void>): Promise<void>;
+export {};
+//# sourceMappingURL=startup-diagnostics.d.ts.map

package/lib/types/tenant-proxy.d.ts

@@ -0,0 +1,101 @@
+/**
+ * The hub's transport hop into one tenant runtime: an HTTP request forwarded
+ * with that runtime's own authority, and an upgraded socket piped the same way.
+ *
+ * The hop changes transport facts only. It rewrites `Host` to the tenant's
+ * authority — the tenant's session cookie is named after the authority it was
+ * issued for, so one browser can hold one cookie per tenant on one origin —
+ * and rewrites `Origin` to that same authority after checking the browser's
+ * own Origin names the hub, which keeps the tenant's same-origin fence as
+ * strong as it is without a proxy. Everything else, including `Range`,
+ * `Set-Cookie`, `Location`, and partial-content answers, crosses unchanged.
+ *
+ * The hop decides no access: the tenant runtime's own account gate answers
+ * every request, so a forged routing cookie reaches a runtime that does not
+ * recognize the caller.
+ * @module @qilin-agent/cli/tenant-proxy
+ */
+import { type IncomingHttpHeaders, type IncomingMessage, type ServerResponse } from 'node:http';
+import { Readable, type Duplex } from 'node:stream';
+/** One request the hub forwards. */
+export interface ProxyRequestOptions {
+    /** Origin the runtime serves, such as `http://127.0.0.1:41234`. */
+    readonly origin: string;
+    /** Request method, verbatim. */
+    readonly method: string;
+    /** Path and query to request upstream, exactly the path the browser asked for. */
+    readonly path: string;
+    /** Browser headers, verbatim. */
+    readonly headers: IncomingHttpHeaders;
+    /** Browser authority that reached the hub, checked against the Origin fence. */
+    readonly hubAuthority: string;
+    /** Incoming body, when the request carries one. */
+    readonly body?: Readable | undefined;
+}
+/** One upstream answer, still streaming. */
+export interface ProxyAnswer {
+    /** Status code the runtime answered. */
+    readonly status: number;
+    /** Answer headers, hop-by-hop entries removed. */
+    readonly headers: IncomingHttpHeaders;
+    /** Answer body. */
+    readonly stream: Readable;
+}
+/**
+ * Whether a browser-labeled request may be forwarded at all.
+ *
+ * Over plain HTTP a read carries neither Origin nor Fetch-Metadata, so an
+ * absent Origin is accepted and the tenant's own Host fence still binds the
+ * request. A present Origin must name the hub exactly, and an explicit
+ * cross-site marker is refused: the hub is the outermost hop, so this is the
+ * only place those markers can be read before the tenant's authority replaces
+ * them.
+ * @param headers - browser headers, verbatim.
+ * @param hubAuthority - authority the browser used to reach the hub.
+ * @returns true when the request may be forwarded.
+ */
+export declare function hubAcceptsOrigin(headers: IncomingHttpHeaders, hubAuthority: string): boolean;
+/**
+ * Headers to forward upstream: the browser's own, minus connection-scoped
+ * entries, with the authority-bearing ones rewritten to the tenant.
+ * @param headers - browser headers, verbatim.
+ * @param tenantAuthority - the runtime's own `host:port`.
+ * @param deploymentAuthority - authority the browser used to reach the hub, and
+ * therefore the one the runtime names its sessions for; empty when the request
+ * reached a runtime directly, which then keeps its own authority as the name.
+ * Required rather than optional because every hop of this deployment knows it,
+ * and an upgrade that forgot it authenticates against a cookie no browser holds.
+ * @returns the forwarded header set.
+ */
+export declare function forwardedHeaders(headers: IncomingHttpHeaders, tenantAuthority: string, deploymentAuthority: string): IncomingHttpHeaders;
+/**
+ * Send one request to a tenant runtime and hand back its streaming answer.
+ *
+ * The hub's own origin fence runs here, in the operation that would forward the
+ * request, so no caller can forward a browser request whose Origin names
+ * another site.
+ * @param options - the runtime, the path, headers, and body to forward.
+ * @returns the runtime's status, headers, and body, or the refusal.
+ * @throws Error when the runtime is unreachable or refuses the connection.
+ */
+export declare function proxyRequest(options: ProxyRequestOptions): Promise<ProxyAnswer>;
+/**
+ * Write one upstream answer to the browser, streaming the body.
+ * @param answer - the runtime's status, headers, and body.
+ * @param response - the browser's response.
+ */
+export declare function relayAnswer(answer: ProxyAnswer, response: ServerResponse): void;
+/**
+ * Pipe one upgraded browser socket to the same path on a tenant runtime, with
+ * the tenant's authority in place of the hub's.
+ *
+ * The upgrade is piped, never terminated: the hub holds no copy of the frames,
+ * so the tenant's own mux and its trust fence stay in charge of the stream.
+ * @param request - the browser's upgrade request.
+ * @param socket - the browser's socket.
+ * @param head - bytes already read from the browser.
+ * @param target - origin of the runtime the socket belongs to.
+ * @param headers - already-forwarded headers, with the tenant's authority set.
+ */
+export declare function relayUpgrade(request: IncomingMessage, socket: Duplex, head: Buffer, target: string, headers: IncomingHttpHeaders): void;
+//# sourceMappingURL=tenant-proxy.d.ts.map