@nylorun/cli 0.2.0-beta → 0.3.0-beta

package/dist/model/configure.js

@@ -1,5 +1,7 @@
 import { createInterface } from "node:readline/promises";
-import { modelsFor } from "@nylorun/runtime/configuration";
+import { builtinModels } from "@earendil-works/pi-ai/providers/all";
+import { createProvider, } from "@earendil-works/pi-ai";
+import { stream, streamSimple, } from "@earendil-works/pi-ai/api/openai-completions";
 export class ConfigurationCancelled extends Error {
     signal;
     exitCode;
@@ -9,6 +11,112 @@ export class ConfigurationCancelled extends Error {
         this.exitCode = signal === "SIGINT" ? 130 : 143;
     }
 }
+/**
+ * Build a pi-ai registry for interactive login. Catalog listing prefers the
+ * Tenant API payload when provided (F2-4).
+ */
+function modelsFor(selection, credentials, catalog) {
+    const models = builtinModels({ credentials });
+    if (selection.custom) {
+        const model = {
+            id: selection.model,
+            name: selection.model,
+            api: "openai-completions",
+            provider: "custom",
+            baseUrl: selection.custom.baseUrl,
+            reasoning: false,
+            input: ["text", "image"],
+            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+            contextWindow: 128000,
+            maxTokens: 16384,
+        };
+        models.setProvider(createProvider({
+            id: "custom",
+            name: "Custom OpenAI-compatible",
+            baseUrl: selection.custom.baseUrl,
+            auth: {
+                apiKey: {
+                    label: "Custom API key",
+                    schemas: [],
+                    async resolve() {
+                        const credential = await credentials.read("custom");
+                        if (!credential || credential.type !== "api_key")
+                            return undefined;
+                        const key = credential.key;
+                        if (!key)
+                            return undefined;
+                        return { type: "api_key", auth: { apiKey: key } };
+                    },
+                },
+            },
+            models: [model],
+            api: { stream, streamSimple },
+        }));
+    }
+    return {
+        models,
+        listProviders() {
+            if (catalog?.providers.length) {
+                return catalog.providers.map((provider) => {
+                    const live = models.getProvider(provider.id);
+                    return {
+                        id: provider.id,
+                        name: provider.name,
+                        auth: {
+                            ...(live?.auth?.apiKey || provider.auth?.apiKey
+                                ? { apiKey: live?.auth?.apiKey ?? {} }
+                                : {}),
+                            ...(live?.auth?.oauth || provider.auth?.oauth
+                                ? { oauth: live?.auth?.oauth ?? {} }
+                                : {}),
+                            ...(!live?.auth?.apiKey &&
+                                !live?.auth?.oauth &&
+                                !provider.auth?.apiKey &&
+                                !provider.auth?.oauth
+                                ? { apiKey: {} }
+                                : {}),
+                        },
+                    };
+                });
+            }
+            return models.getProviders().map((provider) => ({
+                id: provider.id,
+                name: provider.name,
+                auth: {
+                    ...(provider.auth?.apiKey ? { apiKey: provider.auth.apiKey } : {}),
+                    ...(provider.auth?.oauth ? { oauth: provider.auth.oauth } : {}),
+                },
+            }));
+        },
+        listModels(providerId) {
+            const fromCatalog = catalog?.providers.find((p) => p.id === providerId);
+            if (fromCatalog?.models.length)
+                return fromCatalog.models;
+            return models.getModels(providerId).map((model) => ({
+                id: model.id,
+                name: model.name,
+            }));
+        },
+    };
+}
+/** Fetch GET /v1/tenant/models when a connection is available. */
+export async function fetchModelCatalog(options) {
+    const fetchImpl = options.fetchImpl ?? fetch;
+    const { PROTOCOL_HEADER, PROTOCOL_VERSION, TENANT_HEADER } = await import("@nylorun/agents");
+    const response = await fetchImpl(`${options.url.replace(/\/$/, "")}/v1/tenant/models`, {
+        headers: {
+            authorization: `Bearer ${options.key}`,
+            [TENANT_HEADER]: options.tenantId,
+            [PROTOCOL_HEADER]: String(PROTOCOL_VERSION),
+            Accept: "application/json",
+        },
+        signal: AbortSignal.timeout(10_000),
+    });
+    if (!response.ok) {
+        throw new Error(`Runtime model catalog returned ${response.status}`);
+    }
+    return (await response.json());
+}
 // Internal options also allow isolated prompt tests without changing process globals.
 export async function configureProvider(options = {}) {
     const output = options.output ?? process.stdout;
@@ -34,10 +142,8 @@ export async function configureProvider(options = {}) {
             return next ?? captured;
         },
     };
-    const models = modelsFor({ provider: "", model: "" }, store, {
-        environment: false,
-    });
-    const providers = models.getProviders();
+    const registry = modelsFor({ provider: "", model: "" }, store, options.catalog);
+    const providers = registry.listProviders();
     const prompt = createInterface({
         input: options.input ?? process.stdin,
         output,
@@ -72,21 +178,21 @@ export async function configureProvider(options = {}) {
                 model,
                 custom: { baseUrl },
             };
-            const customModels = modelsFor(selection, store, { environment: false });
-            if (!(await customModels.checkAuth("custom", { signal })))
-                await customModels.login("custom", "api_key", interaction());
+            const custom = modelsFor(selection, store, options.catalog);
+            if (!(await custom.models.checkAuth("custom", { signal })))
+                await custom.models.login("custom", "api_key", interaction());
             return prompted(selection);
         }
         else {
             const chosen = providers[choice - 1];
             if (!chosen)
                 throw new Error("Choose a listed provider.");
-            const available = models.getModels(chosen.id);
+            const available = registry.listModels(chosen.id);
             available.forEach((model, index) => output.write(`${index + 1}. ${model.name} (${model.id})\n`));
             const model = available[Number(await question("Choose a model: ")) - 1];
             if (!model)
                 throw new Error("Choose a listed model.");
-            if (!(await models.checkAuth(chosen.id, { signal }))) {
+            if (!(await registry.models.checkAuth(chosen.id, { signal }))) {
                 let method = chosen.auth.apiKey
                     ? "api_key"
                     : "oauth";
@@ -97,7 +203,7 @@ export async function configureProvider(options = {}) {
                     if (answer === "2")
                         method = "oauth";
                 }
-                await models.login(chosen.id, method, interaction());
+                await registry.models.login(chosen.id, method, interaction());
             }
             return prompted({ provider: chosen.id, model: model.id });
         }

package/dist/model/host-model.d.ts

@@ -1,5 +1,5 @@
 import { type PromptedModel } from "./configure.js";
-/** Wire shape of GET/PUT `/v1/host/model` — local copy so CLI stays off `@nylorun/core`. */
+/** Wire shape of GET/PUT `/v1/tenant/model` — local copy so CLI stays off `@nylorun/core`. */
 type HostModelView = {
     readonly configured: false;
 } | {
@@ -9,12 +9,14 @@ type HostModelView = {
     readonly authType: "api_key" | "oauth";
     readonly baseUrl?: string;
 };
-export declare function getHostModel(runtimeUrl: string, serverKey: string): Promise<HostModelView>;
-export declare function putHostModel(runtimeUrl: string, serverKey: string, model: PromptedModel): Promise<HostModelView>;
+export declare function getHostModel(runtimeUrl: string, serverKey: string, tenantId?: string): Promise<HostModelView>;
+export declare function putHostModel(runtimeUrl: string, serverKey: string, model: PromptedModel, tenantId?: string): Promise<HostModelView>;
 export declare function ensureHostModel(options: {
     runtimeUrl: string;
     serverKey: string;
+    tenantId: string;
     root?: string;
+    env?: Readonly<Record<string, string>>;
     signal?: AbortSignal;
 }): Promise<void>;
 export {};

package/dist/model/host-model.js

@@ -1,20 +1,38 @@
 import { randomUUID } from "node:crypto";
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
+import { PROTOCOL_HEADER, PROTOCOL_VERSION, TENANT_HEADER, } from "@nylorun/agents";
 import { configureProvider } from "./configure.js";
-export async function getHostModel(runtimeUrl, serverKey) {
-    const response = await fetch(`${runtimeUrl}/v1/host/model`, {
-        headers: { authorization: `Bearer ${serverKey}` },
+import { loadProjectEnvironment } from "../environment.js";
+function tenantHeaders(serverKey, tenantId) {
+    return {
+        authorization: `Bearer ${serverKey}`,
+        [TENANT_HEADER]: tenantId,
+        [PROTOCOL_HEADER]: String(PROTOCOL_VERSION),
+    };
+}
+function resolveTenantId(explicit) {
+    const tenant = explicit?.trim() || process.env.NYLORUN_TENANT?.trim();
+    if (!tenant) {
+        throw new Error("Set NYLORUN_TENANT (or pass tenant via Project link) before calling Tenant model routes");
+    }
+    return tenant;
+}
+export async function getHostModel(runtimeUrl, serverKey, tenantId) {
+    const tenant = resolveTenantId(tenantId);
+    const response = await fetch(`${runtimeUrl}/v1/tenant/model`, {
+        headers: tenantHeaders(serverKey, tenant),
     });
     if (!response.ok)
         throw new Error(`Runtime model status returned ${response.status}`);
     return response.json();
 }
-export async function putHostModel(runtimeUrl, serverKey, model) {
-    const response = await fetch(`${runtimeUrl}/v1/host/model`, {
+export async function putHostModel(runtimeUrl, serverKey, model, tenantId) {
+    const tenant = resolveTenantId(tenantId);
+    const response = await fetch(`${runtimeUrl}/v1/tenant/model`, {
         method: "PUT",
         headers: {
-            authorization: `Bearer ${serverKey}`,
+            ...tenantHeaders(serverKey, tenant),
             "content-type": "application/json",
         },
         body: JSON.stringify({
@@ -32,12 +50,15 @@ export async function putHostModel(runtimeUrl, serverKey, model) {
     return body;
 }
 export async function ensureHostModel(options) {
-    const current = await getHostModel(options.runtimeUrl, options.serverKey);
+    const current = await getHostModel(options.runtimeUrl, options.serverKey, options.tenantId);
     if (current.configured)
         return;
-    const seeded = seedFromProject(options.root ?? process.cwd());
+    const env = options.env ?? loadProjectEnvironment(options.root ?? process.cwd());
+    if (env.NYLORUN_DEV_MODEL?.trim() === "fixture")
+        return;
+    const seeded = seedFromEnv(env, options.root ?? process.cwd());
     if (seeded) {
-        await putHostModel(options.runtimeUrl, options.serverKey, seeded);
+        await putHostModel(options.runtimeUrl, options.serverKey, seeded, options.tenantId);
         return;
     }
     if (process.stdin.isTTY && process.stdout.isTTY) {
@@ -45,18 +66,18 @@ export async function ensureHostModel(options) {
             root: options.root,
             signal: options.signal,
         });
-        await putHostModel(options.runtimeUrl, options.serverKey, prompted);
+        await putHostModel(options.runtimeUrl, options.serverKey, prompted, options.tenantId);
         return;
     }
     throw new Error("Model provider is not configured. Run nylorun dev in a terminal to set it up, or open Studio.");
 }
-function seedFromProject(root) {
-    const provider = process.env.MODEL_PROVIDER?.trim();
-    const model = process.env.MODEL?.trim();
+function seedFromEnv(env, root) {
+    const provider = env.MODEL_PROVIDER?.trim();
+    const model = env.MODEL?.trim();
     if (!provider || !model)
         return undefined;
-    const baseUrl = process.env.MODEL_PROVIDER_BASE_URL?.trim();
-    const key = process.env.MODEL_PROVIDER_API_KEY;
+    const baseUrl = env.MODEL_PROVIDER_BASE_URL?.trim();
+    const key = env.MODEL_PROVIDER_API_KEY;
     const auth = key
         ? { type: "api_key", key }
         : legacyCredential(root, provider);

package/dist/project/attach.d.ts

@@ -0,0 +1,32 @@
+import { type ProjectCredentials } from "./credentials.js";
+import { type ProjectLink } from "./link.js";
+export interface UpResult {
+    url: string;
+    hostId: string;
+    pid: number;
+    version: string;
+    started: boolean;
+}
+export interface AttachedProject {
+    projectRoot: string;
+    link: ProjectLink;
+    credentials: ProjectCredentials;
+    host: UpResult;
+    tenantName: string;
+    hostStarted: boolean;
+    home: string;
+}
+export interface AttachOptions {
+    projectRoot: string;
+    home?: string;
+    /** Interactive stdin; defaults to process.stdin when TTY. */
+    input?: NodeJS.ReadableStream;
+    output?: NodeJS.WritableStream;
+    fetchImpl?: typeof fetch;
+}
+/**
+ * Ensure the local Runtime is up and a Project link authenticates (D§12 step 2).
+ */
+export declare function attachProject(options: AttachOptions): Promise<AttachedProject>;
+/** Three `export` lines for `runtime status --env` (F2-7). */
+export declare function printLinkedEnvExports(projectRoot?: string): Promise<void>;

package/dist/project/attach.js

@@ -0,0 +1,241 @@
+import { createInterface } from "node:readline/promises";
+import { createAdmin } from "@nylorun/admin";
+import { PROTOCOL_HEADER, PROTOCOL_VERSION, TENANT_HEADER, } from "@nylorun/agents";
+import { CliError } from "../errors.js";
+import { launcher, resolveHome, throwOnLauncherFailure, } from "../runtime/launcher.js";
+import { readCredentials, removeCredentials, } from "./credentials.js";
+import { createProjectTenant } from "./create-tenant.js";
+import { readLink, removeLink, writeLink, } from "./link.js";
+function tenantHeaders(key, tenantId) {
+    return {
+        authorization: `Bearer ${key}`,
+        [TENANT_HEADER]: tenantId,
+        [PROTOCOL_HEADER]: String(PROTOCOL_VERSION),
+    };
+}
+async function probeTenant(hostUrl, tenantId, applicationKey, fetchImpl) {
+    try {
+        const response = await fetchImpl(`${hostUrl}/v1/tenant`, {
+            headers: tenantHeaders(applicationKey, tenantId),
+            signal: AbortSignal.timeout(5_000),
+        });
+        return response.ok ? "ok" : "rejected";
+    }
+    catch {
+        return "rejected";
+    }
+}
+async function healthHostId(hostUrl, fetchImpl) {
+    try {
+        const response = await fetchImpl(`${hostUrl}/health`, {
+            signal: AbortSignal.timeout(3_000),
+        });
+        if (!response.ok)
+            return undefined;
+        const body = (await response.json());
+        return typeof body.hostId === "string" ? body.hostId : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Ensure the local Runtime is up and a Project link authenticates (D§12 step 2).
+ */
+export async function attachProject(options) {
+    const fetchImpl = options.fetchImpl ?? fetch;
+    const projectRoot = options.projectRoot;
+    const home = resolveHome(options.home);
+    const handle = await launcher(home);
+    const upOutcome = await handle.invoke(["up"]);
+    throwOnLauncherFailure(upOutcome);
+    const host = upResultFromInvoke(upOutcome);
+    const hostUrl = host.url.replace(/\/$/, "");
+    const hostId = host.hostId ||
+        (await healthHostId(hostUrl, fetchImpl)) ||
+        "";
+    if (!hostId) {
+        throw new CliError(`Runtime Host at ${hostUrl} did not report a hostId. Restart with "nylorun runtime restart".`, 1);
+    }
+    const admin = createAdmin({ home });
+    let link = await readLink(projectRoot);
+    let credentials = await readCredentials(projectRoot);
+    if (!link || !credentials) {
+        const created = await createProjectTenant({
+            admin,
+            hostId,
+            hostUrl,
+            projectRoot,
+        });
+        return {
+            projectRoot,
+            link: created.link,
+            credentials: created.credentials,
+            host,
+            tenantName: created.envelope.name,
+            hostStarted: host.started,
+            home,
+        };
+    }
+    if (link.hostUrl.replace(/\/$/, "") !== hostUrl) {
+        const liveId = await healthHostId(hostUrl, fetchImpl);
+        if (liveId && liveId === link.hostId) {
+            link = { ...link, hostUrl, format: 1 };
+            await writeLink(projectRoot, link);
+        }
+    }
+    const liveId = await healthHostId(hostUrl, fetchImpl);
+    if (liveId && liveId !== link.hostId) {
+        throw new CliError(`Project link points at Host ${link.hostId}, but ${hostUrl} is ${liveId}. Relink: remove .nylorun/link.json and run nylorun dev.`, 1);
+    }
+    const auth = await probeTenant(hostUrl, link.tenantId, credentials.applicationKey, fetchImpl);
+    if (auth === "ok") {
+        const tenants = await admin.listTenants();
+        const match = tenants.find((t) => t.id === link.tenantId);
+        return {
+            projectRoot,
+            link: { ...link, hostUrl, hostId: liveId ?? link.hostId, format: 1 },
+            credentials,
+            host,
+            tenantName: match?.name ?? match?.envelope?.name ?? link.tenantId,
+            hostStarted: host.started,
+            home,
+        };
+    }
+    const tenants = await admin.listTenants();
+    const known = tenants.some((t) => t.id === link.tenantId);
+    if (known) {
+        throw new CliError(`Application credential rejected for Tenant ${link.tenantId} on Host ${link.hostId}. Relink: remove .nylorun/link.json and .nylorun/credentials.json, then run nylorun dev.`, 1);
+    }
+    const choice = await chooseUnknownTenantRecovery({
+        tenantId: link.tenantId,
+        tenants,
+        input: options.input,
+        output: options.output,
+    });
+    if (choice === "remove") {
+        await removeLink(projectRoot);
+        await removeCredentials(projectRoot);
+        throw new CliError("Removed Project link. Run nylorun dev again to create a new Tenant.", 1);
+    }
+    if (choice === "create") {
+        await removeLink(projectRoot);
+        await removeCredentials(projectRoot);
+        const created = await createProjectTenant({
+            admin,
+            hostId: liveId ?? hostId,
+            hostUrl,
+            projectRoot,
+        });
+        return {
+            projectRoot,
+            link: created.link,
+            credentials: created.credentials,
+            host,
+            tenantName: created.envelope.name,
+            hostStarted: host.started,
+            home,
+        };
+    }
+    const selected = choice.tenant;
+    await writeLink(projectRoot, {
+        format: 1,
+        hostUrl,
+        hostId: liveId ?? hostId,
+        tenantId: selected.id,
+    });
+    const retry = await probeTenant(hostUrl, selected.id, credentials.applicationKey, fetchImpl);
+    if (retry !== "ok") {
+        throw new CliError(`Credentials do not authorize Tenant ${selected.id}. Remove .nylorun/credentials.json and create a new Tenant with nylorun dev.`, 1);
+    }
+    return {
+        projectRoot,
+        link: {
+            format: 1,
+            hostUrl,
+            hostId: liveId ?? hostId,
+            tenantId: selected.id,
+        },
+        credentials,
+        host,
+        tenantName: selected.name ?? selected.envelope?.name ?? selected.id,
+        hostStarted: host.started,
+        home,
+    };
+}
+async function chooseUnknownTenantRecovery(options) {
+    const message = `Linked Tenant ${options.tenantId} is unknown on this Host.`;
+    const tty = options.input === undefined
+        ? Boolean(process.stdin.isTTY && process.stdout.isTTY)
+        : true;
+    if (!tty) {
+        throw new CliError(`${message} Create a new Tenant (remove .nylorun/link.json), choose another with "nylorun tenant use", or remove the link.`, 1);
+    }
+    const input = options.input ?? process.stdin;
+    const output = options.output ?? process.stdout;
+    const rl = createInterface({ input, output });
+    try {
+        output.write(`${message}\n`);
+        output.write("  1) Create a new Tenant\n");
+        output.write("  2) Choose another Tenant on this Host\n");
+        output.write("  3) Remove the Project link\n");
+        const answer = (await rl.question("Choose [1/2/3]: ")).trim();
+        if (answer === "1")
+            return "create";
+        if (answer === "3")
+            return "remove";
+        if (answer === "2") {
+            const open = options.tenants.filter((t) => t.state === "open" && t.name);
+            if (open.length === 0) {
+                throw new CliError("No open Tenants on this Host to choose. Create a new one instead.", 1);
+            }
+            for (let i = 0; i < open.length; i += 1) {
+                const t = open[i];
+                output.write(`  ${i + 1}) ${t.name ?? "(unnamed)"}  ${t.id}\n`);
+            }
+            const pick = Number((await rl.question(`Choose Tenant [1-${open.length}]: `)).trim());
+            if (!Number.isInteger(pick) || pick < 1 || pick > open.length) {
+                throw new CliError("Invalid Tenant choice.", 2);
+            }
+            return { tenant: open[pick - 1] };
+        }
+        throw new CliError("Invalid choice.", 2);
+    }
+    finally {
+        rl.close();
+    }
+}
+/** Three `export` lines for `runtime status --env` (F2-7). */
+export async function printLinkedEnvExports(projectRoot = process.cwd()) {
+    const { findProjectRoot } = await import("./root.js");
+    const root = findProjectRoot(projectRoot) ?? projectRoot;
+    const link = await readLink(root);
+    const credentials = await readCredentials(root);
+    if (!link || !credentials) {
+        console.log("# No Project link in this directory. Run nylorun dev to create one.");
+        return;
+    }
+    console.log(`export NYLORUN_RUNTIME_URL=${shellQuote(link.hostUrl)}`);
+    console.log(`export NYLORUN_SERVER_KEY=${shellQuote(credentials.applicationKey)}`);
+    console.log(`export NYLORUN_TENANT=${shellQuote(link.tenantId)}`);
+}
+function upResultFromInvoke(outcome) {
+    const result = outcome.result ?? {};
+    const url = typeof result.url === "string" ? result.url : "";
+    const hostId = typeof result.hostId === "string" ? result.hostId : "";
+    if (!url) {
+        throw new CliError("Runtime up succeeded without a URL.", 1);
+    }
+    return {
+        url,
+        hostId,
+        pid: typeof result.pid === "number" ? result.pid : 0,
+        version: typeof result.version === "string" ? result.version : "",
+        started: Boolean(result.started),
+    };
+}
+function shellQuote(value) {
+    if (/^[A-Za-z0-9_./:-]+$/.test(value))
+        return value;
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}

package/dist/project/create-tenant.d.ts

@@ -0,0 +1,26 @@
+import { type Admin } from "@nylorun/admin";
+import { type ProjectCredentials } from "./credentials.js";
+import { type ProjectLink } from "./link.js";
+export interface CreateTenantOptions {
+    /** Prefer an already-resolved Admin (local Host or explicit). */
+    admin: Admin;
+    hostId: string;
+    projectRoot: string;
+    name?: string;
+    /** Override Host URL written into the link (defaults to admin.url). */
+    hostUrl?: string;
+}
+export interface CreateTenantResult {
+    link: ProjectLink;
+    credentials: ProjectCredentials;
+    envelope: {
+        id: string;
+        name: string;
+    };
+}
+/**
+ * Create a Tenant via `@nylorun/admin` and write format-1 link + credentials.
+ */
+export declare function createProjectTenant(options: CreateTenantOptions): Promise<CreateTenantResult>;
+/** Resolve Admin from the local Host root (after launcher `up`). */
+export declare function localAdmin(home?: string): Admin;

package/dist/project/create-tenant.js

@@ -0,0 +1,65 @@
+import { readFile } from "node:fs/promises";
+import { basename, join } from "node:path";
+import { createAdmin } from "@nylorun/admin";
+import { newPrincipalId } from "@nylorun/agents";
+import { CliError } from "../errors.js";
+import { writeCredentials, } from "./credentials.js";
+import { writeLink } from "./link.js";
+async function defaultTenantName(projectRoot) {
+    try {
+        const pkg = JSON.parse(await readFile(join(projectRoot, "package.json"), "utf8"));
+        if (typeof pkg.name === "string" && pkg.name.trim())
+            return pkg.name.trim();
+    }
+    catch {
+        /* fall through */
+    }
+    const base = basename(projectRoot);
+    return base && base.length > 0 ? base : "project";
+}
+/**
+ * Create a Tenant via `@nylorun/admin` and write format-1 link + credentials.
+ */
+export async function createProjectTenant(options) {
+    const name = options.name ?? (await defaultTenantName(options.projectRoot));
+    const admin = options.admin;
+    let created;
+    try {
+        created = await admin.createTenant({ name });
+    }
+    catch (error) {
+        throw new CliError(error instanceof Error
+            ? error.message
+            : `Could not create Tenant: ${String(error)}`, 1);
+    }
+    const hostUrl = (options.hostUrl ?? admin.url).replace(/\/$/, "");
+    // CLIENTS-CCR: admin.createTenant should also return principalId (D§4.2 /
+    // credentials.json). Until then, mint a local id for the credentials file;
+    // agents resolveConnection only needs applicationKey.
+    const principalId = "principalId" in created &&
+        typeof created.principalId === "string"
+        ? created.principalId
+        : newPrincipalId();
+    const credentials = {
+        format: 1,
+        applicationKey: created.applicationKey,
+        principalId,
+    };
+    const link = {
+        format: 1,
+        hostUrl,
+        hostId: options.hostId,
+        tenantId: created.tenant.id,
+    };
+    await writeCredentials(options.projectRoot, credentials);
+    await writeLink(options.projectRoot, link);
+    return {
+        link,
+        credentials,
+        envelope: { id: created.tenant.id, name: created.tenant.name },
+    };
+}
+/** Resolve Admin from the local Host root (after launcher `up`). */
+export function localAdmin(home) {
+    return createAdmin(home ? { home } : undefined);
+}

package/dist/project/credentials.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Project-local credentials (mode 0600). Format 1 drops `executors`.
+ * Format 0 may still contain an executors map; readers ignore it (D§3.7).
+ */
+export interface ProjectCredentials {
+    format: 0 | 1;
+    applicationKey: string;
+    principalId: string;
+    /** Present only on format 0 files; ignored by version 1. */
+    executors?: Record<string, string>;
+}
+export declare function readCredentials(projectRoot: string): Promise<ProjectCredentials | undefined>;
+export declare function writeCredentials(projectRoot: string, credentials: {
+    applicationKey: string;
+    principalId: string;
+    format?: 0 | 1;
+}): Promise<void>;
+export declare function removeCredentials(projectRoot: string): Promise<void>;