@qilin-agent/cli 3.1.3 → 3.1.5

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

@@ -0,0 +1,338 @@
+/**
+ * One tenant's Web runtime: its own Harness home under the deployment home, the
+ * child process that serves it, and the launch-token URL a browser follows into
+ * it.
+ *
+ * A tenant is a deployment of its own. The child runs with `QILIN_HOME` set to
+ * this tenant's directory, so plugins, model settings, credentials, sessions,
+ * storages, attachments, skills, and presets all resolve inside it and nowhere
+ * else. The only shared file is the deployment's account roster, which the
+ * tenant's home layer points at while admitting exactly its own account.
+ * @module @qilin-agent/cli/tenant-runtime
+ */
+/**
+ * Resolve every bare module name in the hub's own Node options to an absolute
+ * path.
+ *
+ * The child starts in its own tenant directory, so a bare specifier such as the
+ * `tsx/esm` a source launch passes to `--import` resolves against the wrong
+ * tree and the child dies before it prints anything. Resolving here keeps the
+ * child on the hub's own loader regardless of where it runs.
+ * @param execArgv - the hub's `process.execArgv`.
+ * @returns the same options with loader values made absolute.
+ */
+export declare function resolveLoaderArguments(execArgv: readonly string[]): string[];
+/** What one tenant runtime's child process is launched with. */
+export interface TenantLaunch {
+    /** Profile the child boots. */
+    readonly profile: string;
+    /** Interface the child binds. */
+    readonly host: string;
+    /** Overlay files the child composes with, as absolute paths. */
+    readonly patches: readonly string[];
+    /** Arguments the served application receives, in argv order. */
+    readonly appArguments: readonly string[];
+}
+/**
+ * One tenant runtime's arguments, after the Node executable.
+ *
+ * The launcher stops reading its own flags at the first token it does not own,
+ * and `--host` belongs to the served application: everything from there on
+ * reaches that application. An overlay belongs to the launcher, so it travels
+ * before it, and the deployment's own application arguments follow `--no-open`
+ * so a runtime never opens a browser of its own.
+ * @param launch - the profile, interface, overlays, and application arguments.
+ * @returns argv for one child process.
+ */
+export declare function tenantChildArguments(launch: TenantLaunch): string[];
+/** Lifecycle state of one tenant runtime, as the hub's status read reports it. */
+export type TenantRuntimeState = 'stopped' | 'starting' | 'running' | 'failed';
+/** What one tenant runtime needs from the hub. */
+export interface TenantRuntimeOptions {
+    /**
+     * Deployment home: it holds the account roster and one directory per tenant,
+     * and every tenant runtime's own harness home lives under it.
+     */
+    readonly home: string;
+    /** Account identity this runtime serves, which also names its tenant directory. */
+    readonly accountId: string;
+    /**
+     * Directory this runtime's harness home lives in, when it is not the account
+     * identity: a deployment with no accounts yet has no identity to name one.
+     */
+    readonly directoryName?: string;
+    /**
+     * Whether this runtime exists so a deployment with no accounts can be
+     * initialized, which selects the first-run layer it boots with.
+     */
+    readonly bootstrap?: boolean;
+    /**
+     * Registration policy the first-run runtime applies: a deployment that
+     * accepts new accounts lets the product create them there, one that does
+     * not admits only the accounts its roster already holds.
+     */
+    readonly registration?: 'open' | 'closed';
+    /**
+     * Whether the browser reaches this runtime through an address that terminates
+     * TLS, so its account surface marks every session cookie `Secure`.
+     */
+    readonly sessionCookieSecure?: boolean;
+    /** Endpoint this runtime reports its account's token spend to, and its token. */
+    readonly usage?: {
+        readonly url: string;
+        readonly token: string;
+    } | undefined;
+    /** Profile each runtime boots. */
+    readonly profile: string;
+    /**
+     * Overlay files each runtime's composition applies, as absolute paths: the
+     * child starts in its own tenant directory, where an operator's relative path
+     * names nothing.
+     */
+    readonly patches: readonly string[];
+    /** Arguments the served application receives, in argv order. */
+    readonly appArguments: readonly string[];
+    /** Node entry of the qilin CLI the hub re-executes. */
+    readonly binPath: string;
+    /**
+     * Node options the hub itself started with, so the child runs the same way.
+     *
+     * A source launch reaches the CLI through a loader named by a bare specifier
+     * (`--import tsx/esm`). The child starts in its own tenant directory, where
+     * that name does not resolve, so the hub resolves every bare loader name to an
+     * absolute path before spawning. See {@link resolveLoaderArguments}.
+     */
+    readonly execArgv: readonly string[];
+    /**
+     * Interface this runtime binds. It defaults to loopback, which is what a
+     * single-address deployment wants: the hub's address is the only reachable
+     * one. A deployment that gives every account an origin of its own names the
+     * interface a browser reaches instead.
+     */
+    readonly host?: string | undefined;
+    /**
+     * First wait before retrying a runtime that failed to start. It doubles per
+     * consecutive failure, up to {@link BACKOFF_CEILING_MS}.
+     */
+    readonly restartBackoffMilliseconds: number;
+    /**
+     * Where one line of this runtime's own diagnostics goes.
+     * @param line - one line the runtime wrote to its standard error.
+     */
+    readonly log?: (line: string) => void;
+}
+/** What the hub's status read reports about one tenant runtime. */
+export interface TenantRuntimeStatus {
+    /** Account identity this runtime serves. */
+    readonly accountId: string;
+    /** Lifecycle state. */
+    readonly state: TenantRuntimeState;
+    /** Process id while a child is running. */
+    readonly pid: number | undefined;
+    /** Origin the browser is handed to, without the launch token. */
+    readonly origin: string | undefined;
+    /** How many times this tenant's runtime has started. */
+    readonly starts: number;
+    /** Why the last start failed, when it did. */
+    readonly detail: string;
+    /** Consecutive failed starts since the last one that reached its URL. */
+    readonly consecutiveFailures: number;
+    /** Epoch milliseconds before which a start is refused, after failures. */
+    readonly retryAt: number | undefined;
+}
+/**
+ * Whether an account identity may name one tenant directory.
+ *
+ * A leading dot is reserved: the deployment keeps its own directories beside the
+ * tenants (`tenants/.usage` holds the token ledger, `tenants/.bootstrap` the
+ * first-run runtime), so an identity that read as one would take over the
+ * deployment's own bookkeeping instead of a home of its own.
+ *
+ * The account file is a shared document, so its ids reach path construction in
+ * more than one process; an id that is a path segment or names a directory would
+ * place a tenant's home somewhere other than under the deployment's own tenants.
+ * @param accountId - the identity stored in the roster.
+ * @returns true when the identity is one plain directory name.
+ */
+export declare function isTenantIdentity(accountId: string): boolean;
+/** Environment variable naming the deployment home to a tenant runtime. */
+export declare const DEPLOYMENT_HOME_VARIABLE = "QILIN_DEPLOYMENT_HOME";
+/** Environment variable naming the agent-config root (user skills and agent documents). */
+export declare const AGENTS_HOME_VARIABLE = "QILIN_AGENTS_HOME";
+/**
+ * Environment variable naming the account one tenant runtime serves.
+ *
+ * The served document carries it back to the browser, and the client keeps its
+ * own local storage inside that account's space: one origin can serve several
+ * accounts behind this deployment, so a storage name that does not carry an
+ * account would be shared by all of them. Absent for the first-run runtime,
+ * which serves no account yet.
+ */
+export declare const ACCOUNT_VARIABLE = "QILIN_ACCOUNT_ID";
+/** Environment variable naming the deployment's usage endpoint, when it has one. */
+export declare const USAGE_URL_VARIABLE = "QILIN_USAGE_URL";
+/**
+ * Environment variable carrying the token that endpoint accepts.
+ *
+ * It identifies the runtime that presents it, so the hub books the report to the
+ * account that token was minted for rather than to whatever the body claims.
+ */
+export declare const USAGE_TOKEN_VARIABLE = "QILIN_USAGE_TOKEN";
+/**
+ * The environment one tenant runtime starts with.
+ *
+ * The tenant's harness home is the isolation: every root the runtime resolves
+ * comes from `QILIN_HOME`. The agent-config root is the exception that has to be
+ * named explicitly, because it defaults to the shared `~/.agents` (or whatever
+ * the hub inherited), and user skills and agent documents belong to one account.
+ * The deployment home arrives by name so the roster layer can read the shared
+ * account file; nothing else of the deployment's is exposed.
+ *
+ * Credential-shaped names do not cross either: a key the hub was launched with
+ * authenticates the hub, and handing it to every account would bill one
+ * account's requests to whoever started the deployment. A tenant reaches a
+ * provider through its own credential record, or through an entry the
+ * deployment layers for that tenant on purpose. The rule is the harness's one
+ * credential heuristic; every other inherited name, including the deployment's
+ * own `QILIN_*` policy, still crosses.
+ * @param tenantDir - the tenant's own harness home.
+ * @param deploymentHome - the shared deployment home holding the account roster.
+ * The account this runtime serves is named too, so the document it hands the
+ * browser can say whose storage the page may use.
+ * @param base - the environment the hub itself runs with.
+ * @param accountId - the account this runtime serves, or undefined for the
+ * first-run runtime that serves no account yet.
+ * @param usage - endpoint the runtime reports its account's token spend to, and
+ * the token that endpoint accepts; absent when the deployment keeps no ledger.
+ * @returns the environment mapping for the child process.
+ */
+export declare function tenantChildEnvironment(tenantDir: string, deploymentHome: string, base?: NodeJS.ProcessEnv, accountId?: string, usage?: {
+    readonly url: string;
+    readonly token: string;
+}): NodeJS.ProcessEnv;
+/** Addresses that only the machine itself reaches. */
+export declare const LOOPBACK_HOSTS: readonly string[];
+/**
+ * Marks the process as one account's runtime rather than the entry that serves
+ * the public address. The supervisor sets it for every child it starts; a
+ * deployment that starts a single-account runtime directly sets it too.
+ */
+export declare const TENANT_VARIABLE = "QILIN_TENANT";
+/**
+ * Layer of the runtime a deployment uses before it has any account.
+ *
+ * That runtime reads and writes the same roster, and admits whoever the roster
+ * holds: the product's own first-run form creates the first account, and the
+ * hub then serves it from a runtime of its own.
+ * @param secureCookies - whether the browser reaches this deployment over
+ * TLS, so its account surface marks session cookies `Secure`.
+ * @returns the layer document as YAML.
+ */
+export declare function bootstrapPatchYaml(registration?: 'open' | 'closed', secureCookies?: boolean): string;
+/** Directory name of the runtime a deployment without accounts uses. */
+export declare const BOOTSTRAP_DIRECTORY = ".bootstrap";
+/**
+ * One tenant's harness home under the deployment home.
+ *
+ * The name is one path segment — an account identity, or the first-run
+ * directory — so a tenant home is always a sibling of every other one.
+ * @param home - deployment home.
+ * @param name - account identity or first-run directory name.
+ * @returns the tenant's harness home.
+ */
+export declare function tenantDirectory(home: string, name: string): string;
+/**
+ * Build one tenant's harness-home layer: the account roster it reads and the
+ * single account it admits.
+ *
+ * The roster stays in the deployment home so one command manages every account,
+ * while the tenant's own home holds everything else. The deployment home
+ * arrives through the environment rather than as a literal, so a path with
+ * quotes or a trailing backslash cannot change the document's meaning.
+ * @param accountId - account identity this tenant serves.
+ * @param secureCookies - whether the browser reaches this deployment over
+ * TLS, so its account surface marks session cookies `Secure`.
+ * @returns the layer document as YAML.
+ * @throws Error when the identity is not usable as one tenant directory name.
+ */
+export declare function tenantPatchYaml(accountId: string, secureCookies?: boolean): string;
+/** One tenant's Web runtime, started on demand and reclaimed when idle. */
+/**
+ * What a deployment supervisor needs from one account's runtime: the handoff
+ * clock, the lifecycle facts its status read reports, starting and stopping it,
+ * and the origin to forward a browser request to.
+ *
+ * {@link TenantRuntime} is the process-spawning implementation. A caller that
+ * owns the process boundary — a deployment embedding the supervisor, or a test
+ * driving the routing, the cap, and the handoffs — supplies its own.
+ */
+export interface TenantHandle {
+    /** Epoch milliseconds of the last browser handoff; idle reclamation measures it. */
+    lastUsedAt: number;
+    /** Lifecycle and diagnostic facts the status read reports. */
+    status(): TenantRuntimeStatus;
+    /** Start this runtime if it is not serving, resolving once it answers its URL. */
+    ensure(): Promise<string>;
+    /** Stop it and wait until it is gone. */
+    stop(): Promise<void>;
+    /** Origin to forward one browser request to, when it is serving. */
+    proxyTarget(): string | undefined;
+}
+export declare class TenantRuntime implements TenantHandle {
+    private readonly options;
+    private child;
+    private exited;
+    private launchUrl;
+    private state;
+    private detail;
+    private output;
+    private starting;
+    private consecutiveFailures;
+    private retryAt;
+    private intentional;
+    /** Epoch milliseconds of the last browser handoff; idle reclamation measures it. */
+    lastUsedAt: number;
+    /** How many times this tenant's runtime has started. */
+    starts: number;
+    /**
+     * @param options - the shared home, the account this runtime serves, and how to start it.
+     */
+    constructor(options: TenantRuntimeOptions);
+    /**
+     * Where the hub sends this runtime's traffic.
+     *
+     * The runtime's own URL carries a launch token, which the hub never spends:
+     * every request keeps the path the browser asked for, so the application's
+     * account gate answers it. Only the origin is a target.
+     * @returns the runtime's origin, or undefined when it is not serving yet.
+     */
+    proxyTarget(): string | undefined;
+    /** Absolute path of this tenant's harness-home layer. */
+    get patchPath(): string;
+    /**
+     * This tenant's harness home: everything the runtime owns lives under it,
+     * and the deployment home holds only the roster and these directories.
+     */
+    get tenantDir(): string;
+    /** What the hub's status read reports about this tenant. */
+    status(): TenantRuntimeStatus;
+    /**
+     * Return this tenant's launch URL, starting the runtime when it is not serving.
+     * @returns the launch-token URL of the running runtime.
+     * @throws Error when the runtime did not become ready; the state then reports `failed`.
+     */
+    ensure(): Promise<string>;
+    /**
+     * Count one failed start or one crash of a runtime that had been serving, and
+     * schedule the earliest time the next attempt may run.
+     * @param reason - what to report as the current detail.
+     */
+    private recordFailure;
+    /** Ask this tenant's runtime to exit, holding it to the shutdown deadline. */
+    stop(): Promise<void>;
+    /** Start one child, wait for its URL, and keep its handles. */
+    private start;
+    /** Write this tenant's home layer when the file does not already hold it. */
+    private writePatch;
+}
+//# sourceMappingURL=tenant-runtime.d.ts.map

package/lib/types/tenants-roster.d.ts

@@ -0,0 +1,138 @@
+/**
+ * `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
+ */
+import { type AccountRecord } from '@qilin-agent/accounts-local';
+/** One roster row: one account and the tenant directory it owns. */
+export interface RosterEntry {
+    /** Opaque account identity, which also names the tenant directory. */
+    readonly id: string;
+    /** Login name. */
+    readonly username: string;
+    /** Stored address, or null. */
+    readonly email: string | null;
+    /** Epoch milliseconds when the account was created. */
+    readonly createdAt: number;
+    /** Absolute tenant directory under the shared home. */
+    readonly tenantDirectory: string;
+    /** Whether that directory exists, which is whether the account ever ran. */
+    readonly tenantDataPresent: boolean;
+}
+/** What one roster mutation was asked to do. */
+export interface AddAccountRequest {
+    /** Login name, normalized before validation. */
+    readonly username: string;
+    /** Address, normalized before validation; omitted stores none. */
+    readonly email?: string | undefined;
+    /** Plaintext password, validated against the shared minimum length. */
+    readonly password: string;
+    /** Create this deployment's administrator, which may already have one. */
+    readonly admin?: boolean | undefined;
+}
+/** Where a mutation reads the password it applies. */
+export type PasswordSource = {
+    readonly kind: 'prompt';
+} | {
+    readonly kind: 'stdin';
+};
+/** One roster subcommand of `qilin tenants`. */
+export type RosterRequest = {
+    readonly command: 'accounts';
+} | {
+    readonly command: 'add';
+    readonly username: string;
+    readonly email: string | undefined;
+    readonly admin: boolean;
+    readonly password: PasswordSource;
+} | {
+    readonly command: 'passwd';
+    readonly username: string;
+    readonly password: PasswordSource;
+} | {
+    readonly command: 'remove';
+    readonly username: string;
+    readonly purgeData: boolean;
+};
+/**
+ * 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.
+ */
+export declare function rosterEntries(home: string): Promise<RosterEntry[]>;
+/**
+ * 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.
+ */
+export declare function addAccount(home: string, request: AddAccountRequest): Promise<AccountRecord>;
+/**
+ * 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.
+ */
+export declare function setAccountPassword(home: string, username: string, password: string): Promise<AccountRecord>;
+/** What one removal did. */
+export interface RemovalResult {
+    /** The removed account. */
+    readonly account: AccountRecord;
+    /** Tenant directory removed with `--purge-data`, when one existed. */
+    readonly purgedDirectory: string | undefined;
+}
+/**
+ * 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.
+ */
+export declare function removeAccount(home: string, username: string, purgeData: boolean): Promise<RemovalResult>;
+/**
+ * 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.
+ */
+export declare function readPassword(source: PasswordSource, label: string): Promise<string>;
+/**
+ * Print the roster of one shared home.
+ * @param home - absolute shared Harness home.
+ * @param write - where each line goes.
+ * @returns the printed entries.
+ */
+export declare function printRoster(home: string, write: (line: string) => void): Promise<RosterEntry[]>;
+/**
+ * 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.
+ */
+export declare function ensureTenantDirectory(home: string, accountId: string): Promise<string>;
+/**
+ * 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.
+ */
+export declare function runTenantsRoster(request: RosterRequest): Promise<number>;
+//# sourceMappingURL=tenants-roster.d.ts.map

package/lib/types/tenants.d.ts

@@ -0,0 +1,175 @@
+/**
+ * `qilin tenants serve`: one hub over a shared Harness home, one isolated Web
+ * runtime per account. Sessions, tasks, and workspaces stay with the account
+ * that owns them; plugins, model settings, credentials, and the account file
+ * stay shared, so every tenant runtime is that one deployment.
+ *
+ * The hub authenticates nobody: a handoff is a redirect, not a credential.
+ * Each tenant runtime keeps the shared home's account gate and admits only its
+ * own account, so the sign-in happens at the runtime and the runtime is the
+ * boundary. The hub must be reachable where its account list is not a secret —
+ * it binds loopback by default and lists usernames.
+ *
+ * Idle reclamation counts from the last handoff. A browser that reached a tenant
+ * origin keeps talking to that origin directly, which the hub cannot observe, so
+ * a deployment that leaves long-lived tabs open raises `--idle-ms` or disables
+ * reclamation with 0; `--single-origin` moves that same traffic through the hub
+ * instead, and reclamation then counts proxied requests.
+ *
+ * With `--single-origin` the hub serves one origin and routes by a routing
+ * cookie it sets at the handoff: `/api`, the mux upgrade, and media requests are
+ * absolute paths on the page origin, so only cookie routing can attribute them
+ * to a tenant. The cookie selects a runtime, it does not authorize: the runtime
+ * still answers with its own account gate, so a forged cookie reaches a
+ * runtime that does not recognize the caller.
+ *
+ * `--max-tenants` bounds how many runtimes live at once: a handoff that would
+ * exceed the bound reclaims the least recently used one, and every tenant's
+ * Sessions stay on disk. A runtime that fails to start is not retried on every
+ * visit: the hub doubles a wait per consecutive failure, and `/status` reports
+ * the count and the earliest retry.
+ * @module @qilin-agent/cli/tenants
+ */
+import { type TenantHandle, type TenantRuntimeOptions } from './tenant-runtime.ts';
+/** Certificate and key the public address terminates TLS with. */
+export interface DeploymentTlsFiles {
+    /** PEM certificate chain file. */
+    readonly certFile: string;
+    /** Unencrypted PEM private key file. */
+    readonly keyFile: string;
+}
+/** What `qilin tenants serve` was asked to do. */
+export interface TenantsServeOptions {
+    /** Interface the hub binds. */
+    readonly host: string;
+    /** Port the hub binds; 0 picks a free one. */
+    readonly port: number;
+    /** Profile each tenant runtime boots. */
+    readonly profile: string;
+    /** Idle window after which a tenant runtime is reclaimed. */
+    readonly idleMilliseconds: number;
+    /**
+     * Most tenant runtimes the hub keeps alive at once. 0 keeps every one;
+     * starting a runtime past a positive count reclaims the least recently used.
+     */
+    readonly maxTenants: number;
+    /**
+     * First wait before retrying a runtime that failed to start; one runtime
+     * doubles it per consecutive failure. {@link TenantRuntime} owns the ceiling.
+     */
+    readonly restartBackoffMilliseconds: number;
+    /**
+     * Serve every tenant through the hub's own origin instead of redirecting to a
+     * runtime's port: the hub routes each request to the tenant its routing
+     * cookie names, so one browser drives one tenant at a time, and reclamation
+     * counts real traffic rather than a handoff.
+     */
+    readonly singleOrigin: boolean;
+    /**
+     * Whether the deployment lets the product create accounts beyond the
+     * roster's first. Closed admits only the accounts the roster holds, so the
+     * operator creates them with `qilin tenants add`.
+     */
+    readonly registration: 'open' | 'closed';
+    /**
+     * Overlay files each runtime composes with, as absolute paths: a child starts
+     * in its own tenant directory, whatever directory the operator launched from.
+     */
+    readonly patches: readonly string[];
+    /** Arguments the served application receives, in argv order. */
+    readonly appArguments: readonly string[];
+    /**
+     * TLS the public address terminates with. Account runtimes stay on loopback
+     * and speak plain HTTP behind it, which is why this is only served when every
+     * account is reached through this address.
+     */
+    readonly tls?: DeploymentTlsFiles | undefined;
+    /**
+     * Interface every tenant runtime binds. It defaults to loopback, which is the
+     * only reachable interface when {@link singleOrigin} is set: the hub's
+     * address is the deployment's only address. A deployment that gives every
+     * account an origin of its own names the interface a browser reaches, and
+     * each account's cookies then live in their own jar.
+     */
+    readonly tenantHost?: string | undefined;
+    /**
+     * Called once the address is serving, with the address itself, so the caller
+     * that owns the deployment's user-facing behavior can act on it.
+     */
+    readonly onListening?: ((url: string) => void) | undefined;
+    /**
+     * Deployment home holding the roster and every tenant directory. Defaults to
+     * {@link resolveQilinHome}, which is the home the process was started with.
+     */
+    readonly home?: string | undefined;
+    /**
+     * How one account's runtime is created. Defaults to {@link TenantRuntime},
+     * which spawns a child process; a caller that owns the process boundary
+     * supplies its own implementation of {@link TenantHandle}.
+     */
+    readonly createRuntime?: ((options: TenantRuntimeOptions) => TenantHandle) | undefined;
+    /**
+     * Aborting this ends the deployment the way a termination signal does: the
+     * hub stops accepting, every runtime stops, and the returned promise resolves
+     * with 0.
+     */
+    readonly signal?: AbortSignal | undefined;
+}
+/**
+ * Whether every runtime of this deployment must mark its session cookies
+ * `Secure`.
+ *
+ * The browser reaches the deployment through the hub, so a deployment that
+ * terminates TLS itself is the one case where the client's own connection is
+ * encrypted; a runtime behind a plain-HTTP hub cannot know otherwise, and it
+ * never guesses.
+ * @param options - the deployment's own TLS material, when it terminates TLS.
+ * @returns true only when this deployment terminates TLS.
+ */
+export declare function secureSessionCookies(options: {
+    readonly tls?: DeploymentTlsFiles | undefined;
+}): boolean;
+/**
+ * Serve the hub until it is asked to stop.
+ * @param options - the interface, port, tenant profile, and idle window.
+ * @returns the process exit code, 0 after a clean shutdown.
+ */
+/**
+ * What the deployment's own address and its tenant interface mean for reaching
+ * them, as the lines a start prints.
+ *
+ * A hub on loopback is reachable from this machine only, and account runtimes
+ * bind loopback unless `--tenant-host` names another interface. Naming a
+ * reachable one exposes every runtime there directly — plain HTTP, no entry in
+ * between — which an operator has to know before treating the hub address as the
+ * only door.
+ * @param host - interface the entry bound.
+ * @param tenantHost - interface each account runtime binds, when the invocation named one.
+ * @param port - port the entry bound.
+ * @returns one line per fact the operator needs, in print order.
+ */
+export declare function addressNotices(host: string, tenantHost: string | undefined, port: number): string[];
+/**
+ * The runtime a handoff stops to make room, or undefined when there is room or
+ * nothing may be reclaimed yet.
+ *
+ * Only a running runtime is a candidate: one that is still starting has no last
+ * use to compare, so the next handoff reclaims it once it is serving. The
+ * runtime about to start is never its own candidate.
+ * @param live - every runtime holding a child, in any state.
+ * @param target - the runtime about to start.
+ * @param maxTenants - cap on live runtimes; zero or less means no cap.
+ * @returns the runtime to stop, if any.
+ */
+export declare function reclaimFor(live: readonly TenantHandle[], target: TenantHandle, maxTenants: number): TenantHandle | undefined;
+/**
+ * One queue that runs handoffs one at a time.
+ *
+ * Two handoffs that passed the cap together would both start a runtime, so each
+ * handoff's make-room-and-start runs behind the previous one. A handoff that
+ * fails settles its own promise and leaves the queue ready for the next.
+ * @returns a function that queues one handoff.
+ */
+export declare function createHandoffQueue(): <T>(work: () => Promise<T>) => Promise<T>;
+export declare function runTenantsServe(options: TenantsServeOptions): Promise<number>;
+//# sourceMappingURL=tenants.d.ts.map