@agentorg/cli 0.0.0-stage → 0.0.1

package/dist/src/runtime/services.js

@@ -0,0 +1,174 @@
+/** One executable as a user service, through launchd on macOS or systemd on Linux. */
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { homedir, userInfo } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { setTimeout as sleep } from "node:timers/promises";
+import { home } from "../home.js";
+import { launcherPath, writeLauncher } from "./launcher.js";
+/** Each executable owns its service; an alternate home adds its hash to the name. */
+export function service(program, title) {
+    const ownHome = join(userInfo().homedir, ".local", "share", "agentorg");
+    const name = resolve(home()) === resolve(ownHome)
+        ? program
+        : `${program}-${createHash("sha256").update(resolve(home())).digest("hex").slice(0, 8)}`;
+    return { name, program, title };
+}
+/** Run a command and return its status and output, never throwing on a non-zero exit. */
+function run(command, args) {
+    try {
+        return { status: 0, output: execFileSync(command, args, { encoding: "utf8", stdio: "pipe" }) };
+    }
+    catch (error) {
+        const { status, stdout, stderr, code } = error;
+        if (code === "ENOENT")
+            throw new Error(`${command} is not on PATH`);
+        return { status: status ?? 1, output: `${stdout ?? ""}${stderr ?? ""}` };
+    }
+}
+function check(command, args) {
+    const { status, output } = run(command, args);
+    if (status !== 0)
+        throw new Error(`${command} ${args.join(" ")} failed: ${output.trim()}`);
+    return output;
+}
+const escapeXml = (text) => text.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
+const domain = () => `gui/${process.getuid?.()}`;
+const logFile = (service) => join(home(), "logs", `${service.program}.log`);
+const launchd = {
+    file: (name) => join(homedir(), "Library", "LaunchAgents", `${name}.plist`),
+    text(service, launcher) {
+        const log = escapeXml(logFile(service));
+        return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<!-- ${service.title}, written by \`${service.program} service install\`. -->
+<plist version="1.0">
+<dict>
+	<key>Label</key>
+	<string>${escapeXml(service.name)}</string>
+	<key>ProgramArguments</key>
+	<array>
+		<string>${escapeXml(launcher)}</string>
+	</array>
+	<key>RunAtLoad</key>
+	<true/>
+	<key>KeepAlive</key>
+	<true/>
+	<key>StandardOutPath</key>
+	<string>${log}</string>
+	<key>StandardErrorPath</key>
+	<string>${log}</string>
+</dict>
+</plist>
+`;
+    },
+    async load(name, file) {
+        run("launchctl", ["bootout", `${domain()}/${name}`]);
+        // launchd may still be removing the job it just booted out, and refuses until it has.
+        for (let attempt = 1;; attempt++) {
+            const { status, output } = run("launchctl", ["bootstrap", domain(), file]);
+            if (status === 0)
+                return;
+            if (attempt === 10)
+                throw new Error(`launchctl bootstrap ${file} failed: ${output.trim()}`);
+            await sleep(500);
+        }
+    },
+    unload(name, file) {
+        run("launchctl", ["bootout", `${domain()}/${name}`]);
+        rmSync(file, { force: true });
+    },
+    loaded(name) {
+        const { status, output } = run("launchctl", ["print", `${domain()}/${name}`]);
+        if (status !== 0)
+            return undefined;
+        const field = (key) => new RegExp(`^\\t${key} = (.*)$`, "m").exec(output)?.[1];
+        return { running: field("state") === "running", program: field("program") };
+    },
+    logs: (service) => logFile(service),
+};
+/** A word for systemd's ExecStart, quoted, with its specifiers and variables escaped. */
+const systemdWord = (text) => `"${text.replace(/[\\"]/g, "\\$&").replaceAll("%", "%%").replaceAll("$", "$$$$")}"`;
+const unit = (name) => `${name}.service`;
+const systemd = {
+    file: (name) => join(process.env.XDG_CONFIG_HOME || join(homedir(), ".config"), "systemd", "user", unit(name)),
+    text: (service, launcher) => `# ${service.title}, written by \`${service.program} service install\`.
+[Unit]
+Description=AgentOrg's ${service.title}
+
+[Service]
+ExecStart=${systemdWord(launcher)}
+Restart=always
+RestartSec=5
+
+[Install]
+WantedBy=default.target
+`,
+    async load(name) {
+        check("systemctl", ["--user", "daemon-reload"]);
+        check("systemctl", ["--user", "enable", unit(name)]);
+        check("systemctl", ["--user", "restart", unit(name)]);
+    },
+    unload(name, file) {
+        run("systemctl", ["--user", "disable", "--now", unit(name)]);
+        rmSync(file, { force: true });
+        run("systemctl", ["--user", "daemon-reload"]);
+    },
+    loaded(name) {
+        const { status, output } = run("systemctl", [
+            "--user",
+            "show",
+            unit(name),
+            "--property=LoadState,ActiveState,ExecStart",
+        ]);
+        const field = (key) => new RegExp(`^${key}=(.*)$`, "m").exec(output)?.[1];
+        if (status !== 0 || field("LoadState") !== "loaded")
+            return undefined;
+        return {
+            running: field("ActiveState") === "active",
+            program: /path=(\S+)/.exec(field("ExecStart") ?? "")?.[1],
+        };
+    },
+    logs: (service) => `journalctl --user -u ${service.name}`,
+};
+const MANAGERS = { darwin: launchd, linux: systemd };
+/** This system's service manager, or an error naming the systems AgentOrg's services run on. */
+export function manager() {
+    const found = Object.hasOwn(MANAGERS, process.platform) ? MANAGERS[process.platform] : undefined;
+    if (found === undefined) {
+        throw new Error(`services run on macOS (launchd) and Linux (systemd), not ${process.platform}`);
+    }
+    return found;
+}
+/**
+ * Refuse to replace or stop a service of the same name that runs something other than this home's
+ * launcher, such as one installed by hand or for another home.
+ */
+function guard(managing, service, launcher) {
+    const loaded = managing.loaded(service.name);
+    if (loaded === undefined || loaded.program === launcher)
+        return;
+    throw new Error(`a service named ${service.name} runs ${loaded.program ?? "something else"}, not ${launcher}; stop and remove it first`);
+}
+/**
+ * Write the executable's launcher, then load its service and wait for it to answer.
+ */
+export async function installService(service, managing, ready) {
+    guard(managing, service, launcherPath(service.program));
+    const launcher = writeLauncher(service.program);
+    mkdirSync(join(home(), "logs"), { recursive: true, mode: 0o700 });
+    const file = managing.file(service.name);
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, managing.text(service, launcher));
+    await managing.load(service.name, file);
+    await ready();
+}
+/** Stop and remove only this executable's service; return whether it was present. */
+export function uninstallService(service, managing) {
+    guard(managing, service, launcherPath(service.program));
+    const file = managing.file(service.name);
+    const present = existsSync(file) || managing.loaded(service.name) !== undefined;
+    managing.unload(service.name, file);
+    return present;
+}

package/dist/src/runtime/status.d.ts

@@ -0,0 +1,10 @@
+/** Read-back of executable launchers and one application's service. */
+import { type Service } from "./services.ts";
+export interface Report {
+    lines: string[];
+    fault: boolean;
+}
+export declare const printReport: (report: Report) => number;
+export declare function answers(url: string): Promise<boolean>;
+export declare function launcherStatus(program: string, repair: string): Report;
+export declare function serviceStatus(service: Service, url: string): Promise<Report>;

package/dist/src/runtime/status.js

@@ -0,0 +1,81 @@
+/** Read-back of executable launchers and one application's service. */
+import { existsSync } from "node:fs";
+import { VERSION } from "../version.js";
+import { launcherCurrent, launcherPath, MINIMUM_NODE_TEXT, nodeSupported, PACKAGE, readLauncher, } from "./launcher.js";
+import { manager } from "./services.js";
+export const printReport = (report) => {
+    process.stdout.write(`${report.lines.join("\n")}\n`);
+    return report.fault ? 1 : 0;
+};
+export async function answers(url) {
+    try {
+        await fetch(url, { signal: AbortSignal.timeout(2000) });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function launcherStatus(program, repair) {
+    const lines = [
+        program +
+            " " +
+            VERSION +
+            " at " +
+            PACKAGE +
+            ", on Node " +
+            process.versions.node +
+            " at " +
+            process.execPath,
+    ];
+    let fault = false;
+    if (!nodeSupported(process.versions.node)) {
+        lines.push(`  Node ${process.versions.node} is older than ${MINIMUM_NODE_TEXT}`);
+        fault = true;
+    }
+    const path = launcherPath(program);
+    const pinned = readLauncher(program);
+    if (pinned === undefined || !launcherCurrent(program, pinned)) {
+        lines.push(`launcher: ${path} is not pinned to this executable; ${repair}`);
+        fault = true;
+    }
+    else
+        lines.push(`launcher: ${path}, on Node at ${pinned.node}`);
+    return { lines, fault };
+}
+export async function serviceStatus(service, url) {
+    const repair = `run ${service.program} service install`;
+    const report = launcherStatus(service.program, repair);
+    let managing;
+    try {
+        managing = manager();
+    }
+    catch { }
+    const loaded = managing?.loaded(service.name);
+    const up = await answers(url);
+    let state;
+    if (managing === undefined)
+        state = "no service on this system";
+    else if (loaded === undefined) {
+        const installed = existsSync(managing.file(service.name));
+        state = installed
+            ? `service is installed but not loaded; ${repair}`
+            : `no service; ${repair} to keep it running`;
+        report.fault ||= installed;
+    }
+    else if (loaded.program !== launcherPath(service.program)) {
+        state = `service ${service.name} runs ${loaded.program}, not the launcher`;
+        report.fault = true;
+    }
+    else {
+        state =
+            "service " +
+                service.name +
+                (loaded.running ? ", logs in " : " is not running; see ") +
+                managing.logs(service);
+        report.fault ||= !loaded.running;
+    }
+    report.lines.push(`${service.title}: ${up ? "answering" : "not answering"} at ${url}; ${state}`);
+    report.fault ||= !up;
+    return report;
+}

package/dist/src/schema.d.ts

@@ -0,0 +1,4 @@
+/** Local JSON Schema validation for Actor interfaces and Provider configuration. */
+export declare function validSchema(schema: unknown): boolean;
+/** A value's schema violation; invalid schema diagnostics never include schema contents. */
+export declare function violation(schema: object, value: unknown): string | undefined;

package/dist/src/schema.js

@@ -0,0 +1,55 @@
+/** Local JSON Schema validation for Actor interfaces and Provider configuration. */
+import { Ajv } from "ajv";
+import { Ajv2020 } from "ajv/dist/2020.js";
+import addFormatsModule from "ajv-formats";
+// ajv-formats is CommonJS; its function is the default export, or the module itself.
+const addFormats = (addFormatsModule.default ??
+    addFormatsModule);
+const options = {
+    strict: false,
+    validateFormats: true,
+    allErrors: true,
+    addUsedSchema: false,
+    logger: false,
+};
+const draft7 = addFormats(new Ajv(options));
+const draft2020 = addFormats(new Ajv2020(options));
+const compiled = new Map();
+/** Each schema resolves its own definitions; compilation never loads a remote reference. */
+function validator(schema) {
+    if (!schema || typeof schema !== "object" || Array.isArray(schema))
+        return undefined;
+    let key;
+    try {
+        key = JSON.stringify(schema);
+        if (compiled.has(key))
+            return compiled.get(key) ?? undefined;
+        const dialect = schema.$schema;
+        const ajv = typeof dialect === "string" &&
+            /^https?:\/\/json-schema\.org\/draft\/2020-12\/schema#?$/.test(dialect)
+            ? draft2020
+            : draft7;
+        const check = ajv.compile(JSON.parse(key));
+        if ("$async" in check && check.$async === true) {
+            compiled.set(key, null);
+            return undefined;
+        }
+        compiled.set(key, check);
+        return check;
+    }
+    catch {
+        if (key !== undefined)
+            compiled.set(key, null);
+        return undefined;
+    }
+}
+export function validSchema(schema) {
+    return validator(schema) !== undefined;
+}
+/** A value's schema violation; invalid schema diagnostics never include schema contents. */
+export function violation(schema, value) {
+    const check = validator(schema);
+    if (!check)
+        return "the schema itself is invalid";
+    return check(value) ? undefined : "the value does not match the schema";
+}

package/dist/src/server/bin.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/src/server/bin.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { run } from "../runtime/command.js";
+import { main } from "./command.js";
+process.exitCode = await run("agentorg-server", process.argv.slice(2), main);

package/dist/src/server/command.d.ts

@@ -0,0 +1,2 @@
+/** The server process and its own user-service lifecycle. */
+export declare function main(args: string[]): Promise<number>;

package/dist/src/server/command.js

@@ -0,0 +1,65 @@
+/** The server process and its own user-service lifecycle. */
+import { once } from "node:events";
+import { parseArgs } from "node:util";
+import { databasePath, ensureHome, rootCredentialPath } from "../home.js";
+import { coreUrl, DEFAULT_CORE_PORT } from "../network/index.js";
+import { help } from "../runtime/command.js";
+import { serviceCommand, serviceHelp } from "../runtime/hosting.js";
+import { service } from "../runtime/services.js";
+import { printReport, serviceStatus } from "../runtime/status.js";
+import { loadProviders } from "./config.js";
+const PROGRAM = "agentorg-server";
+const SERVICE = () => service(PROGRAM, "the core");
+const HELP = `usage: agentorg-server [--port <n>]
+       agentorg-server service install|uninstall
+       agentorg-server status
+
+Run the organization's core on 127.0.0.1 at --port, else AGENTORG_PORT, else ${DEFAULT_CORE_PORT}. Its records and root credential are in AGENTORG_HOME, default ~/.local/share/agentorg. The first start creates the root. A missing root credential file is replaced on startup.
+
+service manages only the core's user service. status reports its executable, launcher, service and availability.`;
+/** Suppress only Node 22's experimental SQLite notice while loading the store. */
+async function storeModule() {
+    const emitWarning = process.emitWarning;
+    process.emitWarning = ((warning, ...rest) => {
+        const options = rest[0];
+        const type = typeof options === "string" ? options : options?.type;
+        const message = typeof warning === "string" ? warning : warning.message;
+        if (type === "ExperimentalWarning" && message.startsWith("SQLite"))
+            return;
+        return emitWarning.call(process, warning, ...rest);
+    });
+    try {
+        return await import("../storage/sqlite/index.js");
+    }
+    finally {
+        process.emitWarning = emitWarning;
+    }
+}
+export async function main(args) {
+    const asked = args.includes("--help") || args.includes("-h");
+    if (args[0] === "service") {
+        return asked ? help(serviceHelp(PROGRAM)) : serviceCommand(SERVICE(), coreUrl(), args.slice(1));
+    }
+    if (asked)
+        return help(HELP);
+    if (args[0] === "status") {
+        parseArgs({ args: args.slice(1), strict: true });
+        return printReport(await serviceStatus(SERVICE(), coreUrl()));
+    }
+    const { values } = parseArgs({ args, options: { port: { type: "string" } }, strict: true });
+    const configured = loadProviders(ensureHome());
+    const { SqliteStore } = await storeModule();
+    const { rootCredential, startCore } = await import("./index.js");
+    const store = new SqliteStore(databasePath());
+    const core = await startCore(store, {
+        port: Number(values.port ?? (process.env.AGENTORG_PORT || DEFAULT_CORE_PORT)),
+        providers: configured,
+        onError: (actor, error) => process.stderr.write(`${PROGRAM}: the channel of ${actor} failed to start: ${error.message}\n`),
+    });
+    await rootCredential(core.organization.registry, rootCredentialPath());
+    process.stderr.write(`${PROGRAM}: core serving on ${core.url}; the root's credential is in ${rootCredentialPath()}\n`);
+    await Promise.race([once(process, "SIGINT"), once(process, "SIGTERM")]);
+    await core.close();
+    store.close();
+    return 0;
+}

package/dist/src/server/config.d.ts

@@ -0,0 +1,4 @@
+/** Private, preconfigured Provider identities supplied by the server administrator. */
+import { type ProviderIdentity } from "../domain/providers.ts";
+/** Enrollment is explicit; an absent file admits no Providers. */
+export declare function loadProviders(directory: string): ProviderIdentity[];

package/dist/src/server/config.js

@@ -0,0 +1,31 @@
+/** Private, preconfigured Provider identities supplied by the server administrator. */
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { providers } from "../domain/providers.js";
+import { readPrivate } from "../home.js";
+/** Enrollment is explicit; an absent file admits no Providers. */
+export function loadProviders(directory) {
+    const path = join(directory, "providers.json");
+    if (!existsSync(path))
+        return [];
+    try {
+        const configured = JSON.parse(readPrivate(path));
+        if (!Array.isArray(configured) ||
+            configured.some((entry) => !entry ||
+                typeof entry !== "object" ||
+                Array.isArray(entry) ||
+                Object.keys(entry).length !== 2 ||
+                !("providerId" in entry) ||
+                typeof entry.providerId !== "string" ||
+                !("credentialHash" in entry) ||
+                typeof entry.credentialHash !== "string")) {
+            throw new Error();
+        }
+        const identities = configured;
+        providers(identities);
+        return identities;
+    }
+    catch {
+        throw new Error("providers.json must be private and contain an array of unique Provider identities with only providerId and a SHA-256 credentialHash");
+    }
+}

package/dist/src/server/index.d.ts

@@ -0,0 +1,44 @@
+/**
+ * The core process's composition root, the one place the layers meet: the domain over its store,
+ * served in MCP through the network's listener.
+ *
+ * - `src/domain/`: the organization and its built-ins, behind ports.
+ * - `src/storage/sqlite/`: the domain's store.
+ * - `src/bindings/mcp/`: the domain's operations in MCP.
+ * - `src/network/`: the listener and its channels.
+ * - `src/connection/`: identity admission and immutable connection context.
+ * - `src/provider/`: the fixed factory client on Provider-initiated connections.
+ */
+import { type Principal } from "../connection/index.ts";
+import { type Organization, type OrganizationOptions } from "../domain/index.ts";
+import type { Store } from "../domain/ports.ts";
+import { type ProviderIdentity } from "../domain/providers.ts";
+import type { Registry } from "../domain/registry.ts";
+import { ProviderClient } from "../provider/index.ts";
+export interface CoreOptions extends OrganizationOptions {
+    /** How long a Provider factory request may take. */
+    timeoutMs?: number;
+    onError?: (party: string, error: Error) => void;
+    providers?: readonly ProviderIdentity[];
+    /** Explicit admission policy for omitted credentials; supplied credentials are always checked. */
+    allowCredentialOmission?: (principal: Principal) => boolean;
+}
+export interface RunningCore {
+    organization: Organization;
+    /** Internal factory lookup; no lifetime Actor-to-executor association is kept. */
+    provider(providerId: string): ProviderClient | undefined;
+    url: string;
+    /** End every actor's channel, as a lost network would. */
+    drop(): void;
+    close(): Promise<void>;
+}
+/** Serve the organization over `store` on 127.0.0.1 at `port`, 0 for a free one. */
+export declare function startCore(store: Store, options: CoreOptions & {
+    port: number;
+    hostname?: string;
+}): Promise<RunningCore>;
+/**
+ * The root's credential, kept in `file`: written with the root on the first start, and minted
+ * again when the file is gone, since only its hash is stored.
+ */
+export declare function rootCredential(registry: Registry, file: string): Promise<string>;

package/dist/src/server/index.js

@@ -0,0 +1,148 @@
+/**
+ * The core process's composition root, the one place the layers meet: the domain over its store,
+ * served in MCP through the network's listener.
+ *
+ * - `src/domain/`: the organization and its built-ins, behind ports.
+ * - `src/storage/sqlite/`: the domain's store.
+ * - `src/bindings/mcp/`: the domain's operations in MCP.
+ * - `src/network/`: the listener and its channels.
+ * - `src/connection/`: identity admission and immutable connection context.
+ * - `src/provider/`: the fixed factory client on Provider-initiated connections.
+ */
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { serveConnection } from "../bindings/mcp/index.js";
+import { accept, CONNECTION_PATH } from "../connection/index.js";
+import { organization as createOrganization, } from "../domain/index.js";
+import { providers } from "../domain/providers.js";
+import { readPrivate, writePrivate } from "../home.js";
+import { CLOSE_REVOKED, listen } from "../network/index.js";
+import { ProviderClient } from "../provider/index.js";
+import { VERSION } from "../version.js";
+/** Serve the organization over `store` on 127.0.0.1 at `port`, 0 for a free one. */
+export async function startCore(store, options) {
+    const providerClients = new Map();
+    const providerIdentities = providers(options.providers ?? []);
+    const organization = createOrganization(store, {
+        ...options,
+        provider: (providerId) => providerClients.get(providerId),
+        runtime: {
+            version: VERSION,
+            nodeVersion: process.version,
+            providerIds: providerIdentities.ids(),
+        },
+    });
+    const listening = await listen({
+        port: options.port,
+        ...(options.hostname === undefined ? {} : { hostname: options.hostname }),
+        path: CONNECTION_PATH,
+        channel: (channel) => accept(channel, {
+            observe: (code) => organization.diagnostics.record({
+                code,
+                stage: "admission",
+                outcome: code === "admission_refused" ? "refused" : "unknown",
+            }),
+            admit: async (identity) => {
+                if ("providerId" in identity) {
+                    return identity.credential === undefined
+                        ? providerIdentities.has(identity.providerId) &&
+                            options.allowCredentialOmission?.({ providerId: identity.providerId }) === true
+                        : providerIdentities.admit(identity.providerId, identity.credential);
+                }
+                const authenticated = identity.credential === undefined
+                    ? options.allowCredentialOmission?.({ actorId: identity.actorId }) === true
+                    : (await organization.registry.byCredential(identity.credential))?.id ===
+                        identity.actorId;
+                const actor = organization.registry.get(identity.actorId);
+                return authenticated && actor !== undefined && actor.closed_at === null;
+            },
+        }, ({ connectionId, principal, channel: admitted }) => {
+            const observe = (code) => organization.diagnostics.record({
+                code,
+                stage: "providerId" in principal ? "transport" : "mcp",
+                outcome: "observed",
+                connectionId,
+                ...principal,
+            });
+            const ended = (code) => {
+                organization.connections.remove(connectionId);
+                organization.diagnostics.record({
+                    code: "connection_closed",
+                    stage: "transport",
+                    outcome: "observed",
+                    connectionId,
+                    ...principal,
+                    ...(code === undefined ? {} : { closeCode: code }),
+                });
+            };
+            if ("providerId" in principal) {
+                const client = new ProviderClient(admitted, {
+                    timeoutMs: options.timeoutMs ?? 60_000,
+                    holdCreation: () => organization.connections.beginCreation(connectionId),
+                    invalidProtocol: () => observe("protocol_invalid"),
+                });
+                providerClients.set(principal.providerId, client);
+                organization.connections.admit(connectionId, principal, {
+                    detach: () => admitted.close(1000, "connection detached"),
+                    revoke: () => admitted.close(CLOSE_REVOKED, "connection revoked"),
+                    pendingFactoryRequests: () => client.pendingRequests,
+                    selectedForCreation: () => providerClients.get(principal.providerId) === client,
+                });
+                admitted.whenClosed((code) => {
+                    ended(code);
+                    if (providerClients.get(principal.providerId) === client)
+                        providerClients.delete(principal.providerId);
+                });
+            }
+            else {
+                const actorId = principal.actorId;
+                if (organization.registry.get(actorId)?.closed_at !== null) {
+                    admitted.close(CLOSE_REVOKED, "the Actor was closed");
+                    return;
+                }
+                organization.connections.admit(connectionId, principal, {
+                    detach: () => admitted.close(1000, "connection detached"),
+                    revoke: () => admitted.close(CLOSE_REVOKED, "the Actor was closed"),
+                });
+                admitted.whenClosed(ended);
+                serveConnection(organization, actorId, admitted, {
+                    connectionId,
+                    observe,
+                    ...(options.onError === undefined ? {} : { onError: options.onError }),
+                });
+            }
+        }),
+    });
+    return {
+        organization,
+        provider: (providerId) => providerClients.get(providerId),
+        url: listening.url,
+        drop: listening.drop,
+        close: listening.close,
+    };
+}
+/**
+ * The root's credential, kept in `file`: written with the root on the first start, and minted
+ * again when the file is gone, since only its hash is stored.
+ */
+export async function rootCredential(registry, file) {
+    const root = registry.root();
+    if (!root) {
+        const { credential } = await registry.createRoot();
+        writePrivate(file, credential);
+        writePrivate(join(dirname(file), "root-actor"), registry.root()?.id ?? "");
+        return credential;
+    }
+    if (!existsSync(file)) {
+        const credential = await registry.rotateCredential(root.id);
+        writePrivate(file, credential);
+        writePrivate(join(dirname(file), "root-actor"), root.id);
+        return credential;
+    }
+    const credential = readPrivate(file);
+    if ((await registry.byCredential(credential))?.id !== root.id) {
+        throw new Error(`${file} does not hold the root's credential; delete it and start the core again to mint a new one`);
+    }
+    writePrivate(join(dirname(file), "root-actor"), root.id);
+    return credential;
+}