@qilin-agent/cli 3.1.3 → 3.1.4

package/lib/tenant-runtime-ChD53FKq.js

@@ -0,0 +1,489 @@
+import { createRequire } from "node:module";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import "@qilin-agent/http-proxy";
+import { spawn } from "node:child_process";
+import "@qilin-agent/kylin";
+//#region ../../packages/subprocess/subprocess/src/index.ts
+/**
+* Credential-shaped environment names are NOT forwarded to children (the
+* harness's own `DEEPSEEK_API_KEY`/secrets must not leak into a spawned
+* process implicitly). One heuristic for every in-repo spawner; a
+* deliberately supplied entry survives because explicit env layers merge
+* after the scrub.
+*/
+const SENSITIVE_ENV_PATTERN = /KEY|PASSWORD|SECRET|TOKEN/i;
+//#endregion
+//#region lib/types/tenant-runtime.js
+/**
+* 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
+*/
+/** Any startup line whose label is followed by the served URL. */
+const READY_URL = /(?:^|\n)[A-Za-z][\w -]*: (https?:\/\/\S+)/u;
+/** Resolution base for a loader named by a bare specifier. */
+const require = createRequire(import.meta.url);
+/**
+* Workspace path map a source-mode child resolves against.
+*
+* A source launch's entry imports workspace packages by name. The child runs in
+* its own tenant directory, where the loader would otherwise fall back to built
+* `lib` output; this is the same map the repository's own subprocess runner
+* gives a `.ts` entry (see `@qilin-agent/subprocess-local`).
+*/
+const SOURCE_TSCONFIG_PATH = fileURLToPath(new URL("../../../tsconfig.base.json", import.meta.url));
+/** Deadline for one tenant runtime to print its URL. */
+const START_DEADLINE_MS = 12e4;
+/** Node options whose value names a module the child must load. */
+const LOADER_FLAGS = new Set([
+	"--import",
+	"--loader",
+	"--experimental-loader",
+	"-r",
+	"--require"
+]);
+/**
+* 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.
+*/
+function resolveLoaderArguments(execArgv) {
+	const resolved = [];
+	for (const [index, argument] of execArgv.entries()) {
+		const previous = execArgv[index - 1];
+		if (previous !== void 0 && LOADER_FLAGS.has(previous) && !argument.startsWith(".") && !argument.startsWith("/")) try {
+			resolved.push(pathToFileURL(require.resolve(argument)).href);
+			continue;
+		} catch (error) {
+			if (!(error instanceof Error)) throw error;
+		}
+		resolved.push(argument);
+	}
+	return resolved;
+}
+/** Interface a tenant runtime binds when the deployment names none. */
+const DEFAULT_TENANT_HOST = "127.0.0.1";
+/**
+* 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.
+*/
+function tenantChildArguments(launch) {
+	return [
+		"--profile",
+		launch.profile,
+		...launch.patches.flatMap((path) => ["--patch", path]),
+		"--host",
+		launch.host,
+		"--port",
+		"0",
+		"--no-open",
+		...launch.appArguments
+	];
+}
+/** Deadline for one tenant runtime to exit after SIGTERM, before SIGKILL. */
+const STOP_DEADLINE_MS = 15e3;
+/**
+* Ceiling the retry wait reaches. A tenant runtime that cannot start is broken
+* in a way a browser reload does not fix, so the wait grows up to this bound
+* instead of retrying on every visit.
+*/
+const BACKOFF_CEILING_MS = 3e5;
+/**
+* Character set an account identity may use as a tenant directory name. The
+* document each layer carries is built from it, so it never needs quoting.
+*/
+const IDENTITY_PATTERN = /^[A-Za-z0-9._-]+$/u;
+/** Prefix the deployment reserves for directories of its own under `tenants/`. */
+const RESERVED_IDENTITY_PREFIX = ".";
+/**
+* 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.
+*/
+function isTenantIdentity(accountId) {
+	return IDENTITY_PATTERN.test(accountId) && !accountId.startsWith(RESERVED_IDENTITY_PREFIX);
+}
+/** Environment variable naming the deployment home to a tenant runtime. */
+const DEPLOYMENT_HOME_VARIABLE = "QILIN_DEPLOYMENT_HOME";
+/** Environment variable naming the agent-config root (user skills and agent documents). */
+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.
+*/
+const ACCOUNT_VARIABLE = "QILIN_ACCOUNT_ID";
+/** Environment variable naming the deployment's usage endpoint, when it has one. */
+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.
+*/
+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.
+*/
+function tenantChildEnvironment(tenantDir, deploymentHome, base = process.env, accountId, usage) {
+	const inherited = {};
+	for (const [name, value] of Object.entries(base)) {
+		if (value === void 0 || SENSITIVE_ENV_PATTERN.test(name)) continue;
+		inherited[name] = value;
+	}
+	return {
+		...inherited,
+		QILIN_HOME: tenantDir,
+		...accountId === void 0 ? {} : { [ACCOUNT_VARIABLE]: accountId },
+		[TENANT_VARIABLE]: "1",
+		[DEPLOYMENT_HOME_VARIABLE]: deploymentHome,
+		[AGENTS_HOME_VARIABLE]: join(tenantDir, "agents"),
+		...usage === void 0 ? {} : {
+			[USAGE_URL_VARIABLE]: usage.url,
+			[USAGE_TOKEN_VARIABLE]: usage.token
+		}
+	};
+}
+/** Addresses that only the machine itself reaches. */
+const LOOPBACK_HOSTS = [
+	"127.0.0.1",
+	"::1",
+	"localhost"
+];
+/**
+* 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.
+*/
+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.
+*/
+function bootstrapPatchYaml(registration = "open", secureCookies = false) {
+	return [
+		"# First-run layer for a deployment with no accounts yet.",
+		"# This runtime admits whoever the roster holds, so the product can create",
+		"# the first account and, when the deployment accepts new accounts, the ones",
+		"# after it; the hub then routes each of them to a runtime of its own.",
+		"- id: accounts",
+		"  config:",
+		`    qilinHome: !!js process.env.${DEPLOYMENT_HOME_VARIABLE}`,
+		`    registration: ${registration}`,
+		...secureCookies ? ["    sessionCookieSecure: true"] : [],
+		""
+	].join("\n");
+}
+/** Directory name of the runtime a deployment without accounts uses. */
+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.
+*/
+function tenantDirectory(home, name) {
+	return join(home, "tenants", name);
+}
+/**
+* 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.
+*/
+function tenantPatchYaml(accountId, secureCookies = false) {
+	if (!isTenantIdentity(accountId)) throw new Error(`qilin tenants: ${accountId} is not usable as a tenant directory name`);
+	return [
+		`# Tenant harness-home layer for account ${accountId}.`,
+		"# This runtime admits exactly that account and reads the deployment roster;",
+		"# its plugins, model settings, credentials, sessions, and storages live in",
+		"# this tenant home.",
+		"- id: accounts",
+		"  config:",
+		`    qilinHome: !!js process.env.${DEPLOYMENT_HOME_VARIABLE}`,
+		"    admittedAccounts:",
+		`      - '${accountId}'`,
+		"    registration: closed",
+		...secureCookies ? ["    sessionCookieSecure: true"] : [],
+		""
+	].join("\n");
+}
+var TenantRuntime = class {
+	options;
+	child;
+	exited;
+	launchUrl;
+	state = "stopped";
+	detail = "";
+	output = "";
+	starting;
+	consecutiveFailures = 0;
+	retryAt;
+	intentional = false;
+	/** Epoch milliseconds of the last browser handoff; idle reclamation measures it. */
+	lastUsedAt = 0;
+	/** How many times this tenant's runtime has started. */
+	starts = 0;
+	/**
+	* @param options - the shared home, the account this runtime serves, and how to start it.
+	*/
+	constructor(options) {
+		this.options = options;
+	}
+	/**
+	* 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() {
+		if (this.launchUrl === void 0) return void 0;
+		return new URL(this.launchUrl).origin;
+	}
+	/** Absolute path of this tenant's harness-home layer. */
+	get patchPath() {
+		return join(this.tenantDir, "cordis.patch.yml");
+	}
+	/**
+	* 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() {
+		return tenantDirectory(this.options.home, this.options.directoryName ?? this.options.accountId);
+	}
+	/** What the hub's status read reports about this tenant. */
+	status() {
+		return {
+			accountId: this.options.accountId,
+			state: this.state,
+			pid: this.child?.pid,
+			origin: this.launchUrl === void 0 ? void 0 : new URL(this.launchUrl).origin,
+			starts: this.starts,
+			detail: this.detail,
+			consecutiveFailures: this.consecutiveFailures,
+			retryAt: this.retryAt
+		};
+	}
+	/**
+	* 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`.
+	*/
+	async ensure() {
+		this.lastUsedAt = Date.now();
+		if (this.state === "running" && this.launchUrl !== void 0) return this.launchUrl;
+		const retryAt = this.retryAt;
+		if (this.consecutiveFailures > 0 && retryAt !== void 0 && Date.now() < retryAt) throw new Error(`qilin tenants: the runtime for ${this.options.accountId} failed ${String(this.consecutiveFailures)} time(s) and is not retried before ${new Date(retryAt).toISOString()}: ${this.detail}`);
+		this.starting ??= this.start();
+		try {
+			return await this.starting;
+		} finally {
+			this.starting = void 0;
+		}
+	}
+	/**
+	* 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.
+	*/
+	recordFailure(reason) {
+		this.detail = reason;
+		this.consecutiveFailures += 1;
+		const wait = Math.min(this.options.restartBackoffMilliseconds * 2 ** (this.consecutiveFailures - 1), BACKOFF_CEILING_MS);
+		this.retryAt = Date.now() + wait;
+	}
+	/** Ask this tenant's runtime to exit, holding it to the shutdown deadline. */
+	async stop() {
+		const child = this.child;
+		const exited = this.exited;
+		if (child === void 0 || exited === void 0) {
+			if (this.state !== "failed") this.state = "stopped";
+			return;
+		}
+		this.intentional = true;
+		child.kill("SIGTERM");
+		const killed = setTimeout(() => {
+			child.kill("SIGKILL");
+		}, STOP_DEADLINE_MS);
+		try {
+			await exited;
+		} finally {
+			clearTimeout(killed);
+		}
+	}
+	/** Start one child, wait for its URL, and keep its handles. */
+	async start() {
+		await mkdir(this.tenantDir, { recursive: true });
+		await this.writePatch();
+		this.state = "starting";
+		this.detail = "";
+		this.output = "";
+		this.launchUrl = void 0;
+		this.starts += 1;
+		const child = spawn(process.execPath, [
+			...resolveLoaderArguments(this.options.execArgv),
+			this.options.binPath,
+			...tenantChildArguments({
+				profile: this.options.profile,
+				host: this.options.host ?? DEFAULT_TENANT_HOST,
+				patches: this.options.patches,
+				appArguments: this.options.appArguments
+			})
+		], {
+			cwd: this.tenantDir,
+			env: {
+				...tenantChildEnvironment(this.tenantDir, this.options.home, process.env, this.options.bootstrap === true ? void 0 : this.options.accountId, this.options.bootstrap === true ? void 0 : this.options.usage),
+				...this.options.binPath.endsWith(".ts") ? { TSX_TSCONFIG_PATH: SOURCE_TSCONFIG_PATH } : {}
+			},
+			stdio: [
+				"ignore",
+				"pipe",
+				"pipe"
+			]
+		});
+		const ready = Promise.withResolvers();
+		let banner = "";
+		child.stdout.setEncoding("utf8").on("data", (chunk) => {
+			banner += chunk;
+			const lines = banner.split("\n");
+			banner = lines.pop() ?? "";
+			for (const line of lines) {
+				const found = READY_URL.exec(line)?.[1];
+				if (found !== void 0) ready.resolve(found);
+			}
+		});
+		let pending = "";
+		child.stderr.setEncoding("utf8").on("data", (chunk) => {
+			this.output = `${this.output}${chunk}`.slice(-64e3);
+			pending += chunk;
+			const lines = pending.split("\n");
+			pending = lines.pop() ?? "";
+			for (const line of lines) if (line.trim() !== "") this.options.log?.(line);
+		});
+		const exited = Promise.withResolvers();
+		child.once("error", (error) => {
+			this.output = `${this.output}\nspawn failed: ${String(error)}`.slice(-64e3);
+		});
+		child.once("close", (code) => {
+			if (this.child !== child) return;
+			const crashed = this.launchUrl !== void 0 && !this.intentional;
+			this.child = void 0;
+			this.launchUrl = void 0;
+			this.exited = void 0;
+			this.intentional = false;
+			this.state = crashed ? "failed" : "stopped";
+			if (crashed) this.recordFailure(`the runtime for ${this.options.accountId} exited with code ${String(code)} after it was ready`);
+			ready.reject(/* @__PURE__ */ new Error(`qilin tenants: the runtime for ${this.options.accountId} exited before its URL\n${this.output.slice(-2e3)}`));
+			exited.resolve();
+		});
+		this.child = child;
+		this.exited = exited.promise;
+		const deadline = setTimeout(() => {
+			ready.reject(/* @__PURE__ */ new Error(`qilin tenants: the runtime for ${this.options.accountId} printed no URL within ${String(START_DEADLINE_MS)}ms\n${this.output}`));
+		}, START_DEADLINE_MS);
+		try {
+			const url = await ready.promise;
+			this.launchUrl = url;
+			this.state = "running";
+			this.consecutiveFailures = 0;
+			this.retryAt = void 0;
+			this.detail = "";
+			return url;
+		} catch (error) {
+			this.state = "failed";
+			this.recordFailure(error instanceof Error ? error.message : String(error));
+			await this.stop();
+			throw error;
+		} finally {
+			clearTimeout(deadline);
+		}
+	}
+	/** Write this tenant's home layer when the file does not already hold it. */
+	async writePatch() {
+		const secureCookies = this.options.sessionCookieSecure === true;
+		const document = this.options.bootstrap === true ? bootstrapPatchYaml(this.options.registration ?? "open", secureCookies) : tenantPatchYaml(this.options.accountId, secureCookies);
+		if (await readFile(this.patchPath, "utf8").catch(() => void 0) === document) return;
+		await writeFile(this.patchPath, document);
+	}
+};
+//#endregion
+export { isTenantIdentity as a, TenantRuntime as i, LOOPBACK_HOSTS as n, TENANT_VARIABLE as r, BOOTSTRAP_DIRECTORY as t };