@nylorun/runtime 0.2.1-beta → 0.4.0-beta

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.4.0-beta
+
+### Minor Changes
+
+- fa1860a: Use standard MODEL_PROVIDER, MODEL, MODEL_PROVIDER_API_KEY, and MODEL_PROVIDER_BASE_URL environment configuration. Export starter Hono apps and provide CLI development and production Node launchers. Existing starters require manual migration. Release preparation must update the creator Runtime compatibility pin with this release.
+
+## 0.3.0-beta
+
+### Minor Changes
+
+- 9c350be: Provide `nylorun dev` with optional Studio and browser opening, automatic development loopback CORS, and inferred Hono mount paths. Move local model selection to `.env/model.json` with legacy fallback and migration. Generate starters without copied launcher scripts, a top-level config directory, or a separate TypeScript build config. Release preparation must update the creator's Runtime compatibility pin together with these changes.
+
 ## 0.2.1-beta
 
 ### Patch Changes

package/README.md

@@ -8,7 +8,7 @@ import { Runtime, serveAgents } from "@nylorun/runtime";
 const runtime = new Runtime();
 app.route(
   "/agents",
-  serveAgents({ agents, runtime, basePath: "/agents" })
+  serveAgents({ agents, runtime })
 );
 ```
 
@@ -16,22 +16,50 @@ app.route(
 
 The application owns Hono composition, authentication, CORS, logging, process lifecycle, and deployment. Runtime owns agent sessions, durability, media, and AG-UI/session protocol routes. Graceful shutdown is optional: if the application installs signal handlers and wants to drain live sessions, flush pending journal writes, and run optional agent cleanup, it should await `runtime.close()`. An application that does not install handlers exits normally on its host's shutdown policy; `runtime.close()` does not run on crash, OOM, or SIGKILL.
 
-Runtime publishes root-relative discovery and endpoint URLs. `basePath` must match the Hono mount path so advertised manifests and AG-UI endpoints resolve. Agent-scoped routes are `/:id/...` inside the router, so mounting at `/agents` with `basePath: "/agents"` yields `/agents/:id/...`. Pass the same prefix for other mounts:
+Runtime publishes root-relative discovery and endpoint URLs. It infers the Hono
+mount from each request URL (so a separate consumer `hono` install still works).
+Mount at `/agents` or `/api/agents` without repeating that path in `serveAgents`.
+Pass explicit `basePath` when a reverse proxy rewrites the public prefix.
 
-```ts
-app.route(
-  "/api/agents",
-  serveAgents({ agents, runtime, basePath: "/api/agents" })
-);
-```
+`nylorun dev` enables local Studio connections automatically by setting `NYLORUN_DEV=1` for its child application. This allows HTTP/HTTPS browser origins on `localhost`, `127.0.0.1`, or `[::1]`, including Studio's fallback ports. Ordinary production startup does not enable this policy; the application owns production CORS and authorization.
 
 `getActor(context)` supplies an optional actor id and session context for newly created sessions. `getRequestMetadata(context)` supplies JSON-safe metadata for inbound messages. Application middleware remains responsible for authorizing every agent route.
 
 ## Commands
 
 - `nylorun configure`
+- `nylorun dev [--no-studio] [--no-open]`
+- `nylorun start [entry]` (default: `dist/src/index.js`)
 - `nylorun studio --agent-url http://localhost:3000/agents [--port 4161] [--no-open]`
 
-Studio attaches to an application you run. Use your own TypeScript/build tooling and a Node adapter such as `@hono/node-server` when applicable. `projectAsset("agents/skills/catalog")` resolves bundled application assets from source or a compiled `dist/` deployment.
+Export your Hono application with `export default app`. The CLI supplies the Node server adapter. `nylorun dev` watches `src/index.ts`, waits for `/agents/v1/agents`, and starts project-local Studio. `PORT` defaults to 3000. `--no-studio` runs only the application; `--no-open` keeps the browser closed. Ctrl-C stops both processes. `nylorun start` serves the built app without Studio or development CORS.
+
+### Environment configuration
+
+Copy `.env.example` to `.env` and fill it in, or run `nylorun configure` before your agent graph is importable:
+
+```dotenv
+MODEL_PROVIDER=custom
+MODEL=your-model-id
+MODEL_PROVIDER_API_KEY=your-key
+MODEL_PROVIDER_BASE_URL=https://your-provider.example/v1
+```
+
+`MODEL_PROVIDER_BASE_URL` is required only for `MODEL_PROVIDER=custom`; omit it for built-in providers. `configure`, `dev`, and `start` load `.env` before importing the app. Existing process variables win; a missing `.env` is valid. `.env.local` is ignored by Git but is not automatically loaded. Direct imports of Runtime do not load dotenv files.
+
+Explicit `piModel({ selection })` options take precedence over environment selection. Environment selection takes precedence over legacy files; incomplete selection produces an error. `MODEL_PROVIDER_API_KEY` overrides provider-native variables such as `OPENAI_API_KEY` and `ANTHROPIC_API_KEY`, which override stored credentials. API-key deployments require no credential files. Supply the same variables through your hosting provider's environment settings.
+
+The optional wizard writes selection and entered API keys to `.env`, preserving unrelated configuration. It reuses environment credentials without copying them into the file. OAuth is an alternative where supported; its credentials and refresh state live in ignored `.nylorun/auth.json`. Keep `.env` and `.nylorun/` private.
+
+### Upgrading an existing starter
+
+Migration is manual; the CLI will not replace a legacy `.env` directory.
+
+1. Back up the existing `.env/` directory to a private location outside the project before replacing it with a file. Preserve any `config/model.json` too.
+2. Translate `model.json` fields `provider`, `model`, and `custom.baseUrl` into `MODEL_PROVIDER`, `MODEL`, and `MODEL_PROVIDER_BASE_URL`. Copy API keys into `MODEL_PROVIDER_API_KEY` or provider-native variables. Replace the old `NYLO_CUSTOM_API_KEY` variable with `MODEL_PROVIDER_API_KEY`.
+3. Merge `integrations.env` variables into `.env`. Move OAuth records into `.nylorun/auth.json`. Add `.env`, `.env.local`, and `.nylorun/` to `.gitignore`; remove the old `.env/` exceptions.
+4. Replace the entrypoint's `serve(...)` call and Node adapter import with `export default app`. Set scripts to `"dev": "nylorun dev"` and `"start": "nylorun start"`. Remove the application's `@hono/node-server` dependency if unused elsewhere. Keep your build and asset-copy steps.
+
+Runtime retains legacy `.env/model.json`, `config/model.json`, and `.env/auth.json` reads for existing applications using their own launcher. It does not automatically move or delete these files. Use the matching Runtime release pinned by the new creator; older releases cannot launch an exported app.
 
-Provider credentials are stored in `.env/auth.json`, and selection in `config/model.json`. `nylorun configure` can run before an agent graph is importable.
+The exported app follows Hono composition conventions. This change does not establish verified serverless persistence, execution lifetime, or Workers support. `projectAsset()` resolves bundled assets from source or compiled deployments.

package/dist/cli.js

@@ -1,11 +1,13 @@
 #!/usr/bin/env node
-import { existsSync } from "node:fs";
-import { loadEnvFile } from "node:process";
 import { join } from "node:path";
 import { pathToFileURL } from "node:url";
 import { createRequire } from "node:module";
-import { ConfigurationCancelled, configureProvider } from "./model/configure.js";
-const usage = `nylorun <configure|studio>
+import { ConfigurationCancelled, configureProvider, } from "./model/configure.js";
+import { loadProjectEnvironment } from "./environment.js";
+import { develop } from "./dev.js";
+const usage = `nylorun <configure|dev|start|studio>
+  dev [--no-studio] [--no-open]
+  start [entry]
   configure
   studio --agent-url <http(s)-url> [--port <n>] [--no-open]`;
 async function startStudio(agentServerUrl, open, port) {
@@ -17,7 +19,11 @@ async function startStudio(agentServerUrl, open, port) {
         throw new Error("Install @nylorun/studio to use the Studio dashboard.");
     }
     const studio = await import(pathToFileURL(entry).href);
-    return studio.startStudio({ agentServerUrl, open, ...(port === undefined ? {} : { port }) });
+    return studio.startStudio({
+        agentServerUrl,
+        open,
+        ...(port === undefined ? {} : { port }),
+    });
 }
 function parsePort(value) {
     if (value === undefined)
@@ -31,6 +37,18 @@ async function main() {
     const [command, ...args] = process.argv.slice(2);
     if (!command || command === "--help" || command === "-h")
         return void console.log(usage);
+    if (["configure", "dev", "start"].includes(command))
+        loadProjectEnvironment();
+    if (command === "start") {
+        if (args.length > 1 || args[0]?.startsWith("--"))
+            throw new Error(usage);
+        await (await import("./launcher.js")).start(args[0]);
+        return;
+    }
+    if (command === "dev") {
+        process.exitCode = await develop(args);
+        return;
+    }
     if (command === "configure") {
         if (args.length)
             throw new Error(usage);
@@ -38,9 +56,6 @@ async function main() {
         const cancel = (signal) => controller.abort(new ConfigurationCancelled(signal));
         process.once("SIGINT", () => cancel("SIGINT"));
         process.once("SIGTERM", () => cancel("SIGTERM"));
-        const integrations = join(process.cwd(), ".env", "integrations.env");
-        if (existsSync(integrations))
-            loadEnvFile(integrations);
         await configureProvider({ signal: controller.signal });
         return;
     }
@@ -80,5 +95,6 @@ async function main() {
 }
 void main().catch((error) => {
     console.error(error instanceof Error ? error.message : String(error));
-    process.exitCode = error instanceof ConfigurationCancelled ? error.exitCode : 1;
+    process.exitCode =
+        error instanceof ConfigurationCancelled ? error.exitCode : 1;
 });

package/dist/dev-entry.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/dev-entry.js

@@ -0,0 +1,2 @@
+import { start } from "./launcher.js";
+await start(process.argv[2] ?? "src/index.ts", true);

package/dist/dev.d.ts

@@ -0,0 +1,2 @@
+/** Runs project development tooling without copying a supervisor into each application. */
+export declare function develop(args: readonly string[]): Promise<number>;

package/dist/dev.js

@@ -0,0 +1,126 @@
+import { spawn } from "node:child_process";
+import { createRequire } from "node:module";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { setTimeout as delay } from "node:timers/promises";
+/** Runs project development tooling without copying a supervisor into each application. */
+export async function develop(args) {
+    const usage = "Usage: nylorun dev [--no-studio] [--no-open]";
+    if (new Set(args).size !== args.length ||
+        args.some((arg) => !["--no-studio", "--no-open"].includes(arg)))
+        throw new Error(usage);
+    const port = Number(process.env.PORT ?? "3000");
+    if (!Number.isInteger(port) || port < 1 || port > 65535)
+        throw new Error("PORT must be an integer between 1 and 65535.");
+    const require = createRequire(join(process.cwd(), "package.json"));
+    let tsx;
+    try {
+        tsx = require.resolve("tsx/cli");
+    }
+    catch {
+        throw new Error("Install tsx in your project to use nylorun dev.");
+    }
+    if (!args.includes("--no-studio")) {
+        try {
+            require.resolve("@nylorun/studio");
+        }
+        catch {
+            throw new Error("Install @nylorun/studio or use nylorun dev --no-studio.");
+        }
+    }
+    const controller = new AbortController();
+    const children = new Set();
+    const exits = [];
+    let result = 0;
+    let force;
+    const stop = (code, signal = "SIGTERM") => {
+        if (controller.signal.aborted)
+            return;
+        result = code;
+        controller.abort();
+        for (const child of children)
+            child.kill(signal);
+        force = setTimeout(() => {
+            for (const child of children)
+                child.kill("SIGKILL");
+        }, 5_000);
+        force.unref();
+    };
+    const interrupt = () => stop(130, "SIGINT");
+    const terminate = () => stop(143);
+    process.once("SIGINT", interrupt);
+    process.once("SIGTERM", terminate);
+    const launch = (argv) => {
+        const child = spawn(process.execPath, argv, {
+            stdio: "inherit",
+            env: { ...process.env, NYLORUN_DEV: "1" },
+        });
+        children.add(child);
+        exits.push(new Promise((resolve) => {
+            child.once("error", (error) => {
+                console.error(`Could not start development process: ${error.message}`);
+                stop(1);
+            });
+            child.once("close", (code, signal) => {
+                children.delete(child);
+                stop(code ?? (signal === "SIGINT" ? 130 : signal === "SIGTERM" ? 143 : 1));
+                resolve();
+            });
+        }));
+    };
+    try {
+        launch([
+            tsx,
+            "watch",
+            fileURLToPath(new URL("./dev-entry.js", import.meta.url)),
+            "src/index.ts",
+        ]);
+        if (!args.includes("--no-studio")) {
+            const url = `http://127.0.0.1:${port}/agents/v1/agents`;
+            const deadline = Date.now() + 20_000;
+            let ready = false;
+            while (!controller.signal.aborted && Date.now() < deadline) {
+                try {
+                    const response = await fetch(url, {
+                        signal: AbortSignal.any([
+                            controller.signal,
+                            AbortSignal.timeout(500),
+                        ]),
+                    });
+                    ready = response.ok;
+                    await response.body?.cancel();
+                    if (ready)
+                        break;
+                }
+                catch {
+                    /* Watch mode may still be compiling or restarting the app. */
+                }
+                await delay(50, undefined, { signal: controller.signal }).catch(() => { });
+            }
+            if (!controller.signal.aborted) {
+                if (!ready)
+                    throw new Error(`Application did not become ready at ${url} within 20 seconds.`);
+                launch([
+                    fileURLToPath(new URL("./cli.js", import.meta.url)),
+                    "studio",
+                    "--agent-url",
+                    `http://localhost:${port}/agents`,
+                    ...(args.includes("--no-open") ? ["--no-open"] : []),
+                ]);
+            }
+        }
+        await Promise.all(exits);
+    }
+    catch (error) {
+        stop(1);
+        await Promise.all(exits);
+        throw error;
+    }
+    finally {
+        if (force !== undefined)
+            clearTimeout(force);
+        process.removeListener("SIGINT", interrupt);
+        process.removeListener("SIGTERM", terminate);
+    }
+    return result;
+}

package/dist/environment.d.ts

@@ -0,0 +1,2 @@
+export declare function loadProjectEnvironment(root?: string): void;
+export declare function saveEnvironment(root: string, updates: Record<string, string | undefined>, signal?: AbortSignal): Promise<void>;

package/dist/environment.js

@@ -0,0 +1,64 @@
+import { readFileSync, statSync } from "node:fs";
+import { writeFile, rename, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { loadEnvFile } from "node:process";
+export function loadProjectEnvironment(root = process.cwd()) {
+    const file = join(root, ".env");
+    try {
+        if (statSync(file).isDirectory())
+            throw new Error("The .env directory must be migrated manually: back it up, create a .env file with MODEL_PROVIDER, MODEL and MODEL_PROVIDER_API_KEY, and move OAuth credentials to .nylorun/auth.json. See the Runtime migration guide.");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return;
+        throw error;
+    }
+    loadEnvFile(file);
+}
+// Match complete dotenv assignments, including quoted multiline values.
+const assignment = /^(?:export\s+)?([\w]+)[\t ]*=[\t ]*(?:"[^"]*"|'[^']*'|`[^`]*`|[^#\r\n]*)([^\r\n]*)(?:\r?\n|$)/gm;
+export async function saveEnvironment(root, updates, signal) {
+    const file = join(root, ".env");
+    let contents = "";
+    try {
+        contents = readFileSync(file, "utf8");
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+    const encode = (value) => {
+        // Node's dotenv parser has no general quote-escaping syntax. Select a
+        // delimiter absent from the value rather than changing the credential.
+        for (const quote of ["'", '"', "`"]) {
+            if (!value.includes(quote) && !(quote === '"' && /\\[nr]/.test(value)))
+                return quote + value + quote;
+        }
+        throw new Error("This value contains all dotenv quote delimiters; set it through your process environment instead.");
+    };
+    const remaining = new Set(Object.keys(updates));
+    contents = contents.replace(assignment, (whole, key, suffix) => {
+        if (!(key in updates))
+            return whole;
+        if (!remaining.delete(key))
+            return "";
+        return updates[key] === undefined
+            ? ""
+            : `${key}=${encode(updates[key])}${suffix}\n`;
+    });
+    if (contents && !contents.endsWith("\n"))
+        contents += "\n";
+    for (const key of remaining)
+        if (updates[key] !== undefined)
+            contents += `${key}=${encode(updates[key])}\n`;
+    const temporary = join(root, `.env-${randomUUID()}.tmp`);
+    try {
+        await writeFile(temporary, contents, { mode: 0o600, signal });
+        signal?.throwIfAborted();
+        await rename(temporary, file);
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
+}

package/dist/launcher.d.ts

@@ -0,0 +1 @@
+export declare function start(entry?: string, development?: boolean): Promise<void>;

package/dist/launcher.js

@@ -0,0 +1,28 @@
+import { serve } from "@hono/node-server";
+import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { loadProjectEnvironment } from "./environment.js";
+export async function start(entry = "dist/src/index.js", development = false) {
+    loadProjectEnvironment();
+    if (development)
+        process.env.NYLORUN_DEV = "1";
+    else
+        delete process.env.NYLORUN_DEV;
+    const port = Number(process.env.PORT ?? "3000");
+    if (!Number.isInteger(port) || port < 1 || port > 65535)
+        throw new Error("PORT must be an integer between 1 and 65535.");
+    const { default: app } = await import(pathToFileURL(resolve(entry)).href);
+    if (!app || typeof app.fetch !== "function")
+        throw new Error(`${entry} must export a Hono application with 'export default app' and a callable fetch.`);
+    const server = serve({ fetch: app.fetch.bind(app), port }, (info) => {
+        console.log(`Server is running on http://localhost:${info.port}`);
+    });
+    const stop = () => {
+        process.removeListener("SIGINT", stop);
+        process.removeListener("SIGTERM", stop);
+        server.close(() => process.exit(0));
+        setTimeout(() => process.exit(0), 5_000).unref();
+    };
+    process.once("SIGINT", stop);
+    process.once("SIGTERM", stop);
+}

package/dist/model/auth-store.d.ts

@@ -2,7 +2,8 @@ import type { Credential, CredentialInfo, CredentialStore } from "@earendil-work
 export declare class ProjectCredentialStore implements CredentialStore {
     #private;
     private readonly file;
-    constructor(file?: string);
+    private readonly legacyFile?;
+    constructor(file?: string, legacyFile?: string | undefined);
     read(providerId: string): Promise<Credential | undefined>;
     list(): Promise<readonly CredentialInfo[]>;
     modify(providerId: string, fn: (current: Credential | undefined) => Promise<Credential | undefined>): Promise<Credential | undefined>;

package/dist/model/auth-store.js

@@ -1,10 +1,13 @@
+var _a;
 import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 export class ProjectCredentialStore {
     file;
+    legacyFile;
     #chain = Promise.resolve();
-    constructor(file = join(process.cwd(), ".env", "auth.json")) {
+    constructor(file = join(process.cwd(), ".nylorun", "auth.json"), legacyFile) {
         this.file = file;
+        this.legacyFile = legacyFile;
     }
     async read(providerId) {
         return (await this.#all())[providerId];
@@ -54,8 +57,11 @@ export class ProjectCredentialStore {
             return JSON.parse(await readFile(this.file, "utf8"));
         }
         catch (error) {
-            if (error.code === "ENOENT")
+            if (["ENOENT", "ENOTDIR"].includes(error.code ?? "")) {
+                if (this.legacyFile)
+                    return new _a(this.legacyFile).#all();
                 return {};
+            }
             throw error;
         }
     }
@@ -83,3 +89,4 @@ export class ProjectCredentialStore {
         }
     }
 }
+_a = ProjectCredentialStore;

package/dist/model/configure.js

@@ -1,7 +1,6 @@
-import { mkdir, writeFile, rename, rm } from "node:fs/promises";
-import { randomUUID } from "node:crypto";
 import { join } from "node:path";
 import { createInterface } from "node:readline/promises";
+import { saveEnvironment } from "../environment.js";
 import { ProjectCredentialStore } from "./auth-store.js";
 import { modelsFor } from "./models.js";
 export class ConfigurationCancelled extends Error {
@@ -21,7 +20,25 @@ export async function configureProvider(options = {}) {
     const signal = controller.signal;
     const forwardAbort = () => controller.abort(options.signal.reason);
     options.signal?.throwIfAborted();
-    const store = new ProjectCredentialStore(join(root, ".env", "auth.json"));
+    let enteredKey;
+    let enteredEnvironment = {};
+    const oauthStore = new ProjectCredentialStore(join(root, ".nylorun", "auth.json"), join(root, ".env", "auth.json"));
+    const store = {
+        read: (id) => oauthStore.read(id),
+        list: () => oauthStore.list(),
+        delete: (id) => oauthStore.delete(id),
+        async modify(id, fn) {
+            const next = await fn(await oauthStore.read(id));
+            if (next?.type === "api_key") {
+                if (next.key === "")
+                    throw new Error("An API key is required.");
+                enteredKey = next.key;
+                enteredEnvironment = { ...next.env };
+                return next;
+            }
+            return oauthStore.modify(id, async () => next);
+        },
+    };
     const models = modelsFor({ provider: "", model: "" }, store);
     const providers = models.getProviders();
     const prompt = createInterface({
@@ -59,7 +76,8 @@ export async function configureProvider(options = {}) {
                 custom: { baseUrl },
             };
             const customModels = modelsFor(selection, store);
-            await customModels.login("custom", "api_key", interaction());
+            if (!(await customModels.checkAuth("custom", { signal })))
+                await customModels.login("custom", "api_key", interaction());
             await save(selection);
         }
         else {
@@ -72,7 +90,17 @@ export async function configureProvider(options = {}) {
             if (!model)
                 throw new Error("Choose a listed model.");
             if (!(await models.checkAuth(chosen.id, { signal }))) {
-                await models.login(chosen.id, chosen.auth.oauth ? "oauth" : "api_key", interaction());
+                let method = chosen.auth.apiKey
+                    ? "api_key"
+                    : "oauth";
+                if (chosen.auth.apiKey && chosen.auth.oauth) {
+                    const answer = (await question("Choose authentication: 1. API key (default), 2. OAuth: ")).trim();
+                    if (answer && !["1", "2"].includes(answer))
+                        throw new Error("Choose authentication 1 or 2.");
+                    if (answer === "2")
+                        method = "oauth";
+                }
+                await models.login(chosen.id, method, interaction());
             }
             await save({ provider: chosen.id, model: model.id });
         }
@@ -92,24 +120,36 @@ export async function configureProvider(options = {}) {
     function interaction() {
         return {
             signal,
-            prompt: async (item) => question(item.message + ": "),
-            notify: (event) => output.write((event.url ?? event.verificationUri ?? event.message) + "\n"),
+            prompt: async (item) => {
+                if (item.type !== "select")
+                    return question(item.message + ": ");
+                item.options.forEach((option, index) => output.write(`${index + 1}. ${option.label}\n`));
+                const answer = (await question(item.message + " ")).trim();
+                const option = item.options.find((option) => option.id === answer) ??
+                    item.options[Number(answer) - 1];
+                if (!option)
+                    throw new Error("Choose a listed authentication option.");
+                return option.id;
+            },
+            notify: (event) => {
+                output.write(("url" in event
+                    ? event.url
+                    : "verificationUri" in event
+                        ? event.verificationUri
+                        : event.message) + "\n");
+            },
         };
     }
     async function save(selection) {
         signal.throwIfAborted();
-        const directory = join(root, "config");
-        const temporary = join(directory, `.model-${randomUUID()}.json`);
-        try {
-            await mkdir(directory, { recursive: true });
-            await writeFile(temporary, JSON.stringify(selection, null, 2) + "\n", {
-                signal,
-            });
-            signal.throwIfAborted();
-            await rename(temporary, join(directory, "model.json"));
-        }
-        finally {
-            await rm(temporary, { force: true });
-        }
+        await saveEnvironment(root, {
+            ...enteredEnvironment,
+            MODEL_PROVIDER: selection.provider,
+            MODEL: selection.model,
+            MODEL_PROVIDER_BASE_URL: selection.custom?.baseUrl,
+            ...(enteredKey === undefined
+                ? {}
+                : { MODEL_PROVIDER_API_KEY: enteredKey }),
+        }, signal);
     }
 }

package/dist/model/models.d.ts

@@ -1,4 +1,4 @@
-import type { ProjectCredentialStore } from "./auth-store.js";
+import { type CredentialStore } from "@earendil-works/pi-ai";
 export type Selection = Readonly<{
     provider: string;
     model: string;
@@ -6,4 +6,4 @@ export type Selection = Readonly<{
         baseUrl: string;
     }>;
 }>;
-export declare function modelsFor(selection: Selection, credentials: ProjectCredentialStore): import("@earendil-works/pi-ai").MutableModels;
+export declare function modelsFor(selection: Selection, credentials: CredentialStore): import("@earendil-works/pi-ai").MutableModels;

package/dist/model/models.js

@@ -1,8 +1,29 @@
-import { createProvider, envApiKeyAuth, } from "@earendil-works/pi-ai";
+import { createProvider, defaultProviderAuthContext, envApiKeyAuth, } from "@earendil-works/pi-ai";
 import { stream, streamSimple, } from "@earendil-works/pi-ai/api/openai-completions";
 import { builtinModels } from "@earendil-works/pi-ai/providers/all";
 export function modelsFor(selection, credentials) {
-    const models = builtinModels({ credentials });
+    const environmentFirst = {
+        async read(providerId, options) {
+            const explicit = process.env.MODEL_PROVIDER_API_KEY;
+            if (explicit &&
+                (!selection.provider || selection.provider === providerId))
+                return { type: "api_key", key: explicit };
+            const provider = models
+                .getProviders()
+                .find((item) => item.id === providerId);
+            const ambient = await provider?.auth.apiKey?.resolve({
+                ctx: defaultProviderAuthContext(),
+                signal: options?.signal ?? new AbortController().signal,
+            });
+            if (ambient)
+                return undefined;
+            return credentials.read(providerId, options);
+        },
+        list: (options) => credentials.list(options),
+        modify: (id, fn, options) => credentials.modify(id, fn, options),
+        delete: (id, options) => credentials.delete(id, options),
+    };
+    const models = builtinModels({ credentials: environmentFirst });
     if (!selection.custom)
         return models;
     const model = {
@@ -22,7 +43,7 @@ export function modelsFor(selection, credentials) {
         name: "Custom OpenAI-compatible",
         baseUrl: selection.custom.baseUrl,
         auth: {
-            apiKey: envApiKeyAuth("Custom API key", ["NYLO_CUSTOM_API_KEY"]),
+            apiKey: envApiKeyAuth("Custom API key", ["MODEL_PROVIDER_API_KEY"]),
         },
         models: [model],
         api: { stream, streamSimple },

package/dist/model/pi-model.js

@@ -17,7 +17,7 @@ export function piModel(options = {}) {
         context.signal.throwIfAborted();
         const root = options.root ?? process.cwd();
         const selection = options.selection ?? modelSelection(root);
-        const registry = modelsFor(selection, new ProjectCredentialStore(join(root, ".env", "auth.json")));
+        const registry = modelsFor(selection, new ProjectCredentialStore(join(root, ".nylorun", "auth.json"), join(root, ".env", "auth.json")));
         const selected = registry.getModel(selection.provider, selection.model);
         if (!selected)
             throw new Error("Unknown model. Run nylorun configure.");

package/dist/model/settings.js

@@ -1,8 +1,40 @@
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
 export function modelSelection(root = process.cwd()) {
+    const { MODEL_PROVIDER: provider, MODEL: model, MODEL_PROVIDER_BASE_URL: baseUrl, } = process.env;
+    if (provider !== undefined || model !== undefined || baseUrl !== undefined) {
+        if (!provider?.trim() || !model?.trim())
+            throw new Error("Set both MODEL_PROVIDER and MODEL, or run nylorun configure.");
+        if (provider === "custom" && !baseUrl?.trim())
+            throw new Error("Set MODEL_PROVIDER_BASE_URL for MODEL_PROVIDER=custom.");
+        if (baseUrl && provider !== "custom")
+            throw new Error("MODEL_PROVIDER_BASE_URL requires MODEL_PROVIDER=custom.");
+        if (baseUrl) {
+            let url;
+            try {
+                url = new URL(baseUrl);
+            }
+            catch {
+                throw new Error("MODEL_PROVIDER_BASE_URL must be an HTTP(S) URL.");
+            }
+            if (!["http:", "https:"].includes(url.protocol))
+                throw new Error("MODEL_PROVIDER_BASE_URL must be an HTTP(S) URL.");
+        }
+        return { provider, model, ...(baseUrl ? { custom: { baseUrl } } : {}) };
+    }
     try {
-        const value = JSON.parse(readFileSync(join(root, "config", "model.json"), "utf8"));
+        let contents;
+        try {
+            contents = readFileSync(join(root, ".env", "model.json"), "utf8");
+        }
+        catch (error) {
+            if (!(error instanceof Error) ||
+                !("code" in error) ||
+                !["ENOENT", "ENOTDIR"].includes(String(error.code)))
+                throw error;
+            contents = readFileSync(join(root, "config", "model.json"), "utf8");
+        }
+        const value = JSON.parse(contents);
         if (typeof value.provider === "string" &&
             value.provider &&
             typeof value.model === "string" &&
@@ -19,17 +51,18 @@ export function projectSecrets(root = process.cwd()) {
     const values = Object.entries(process.env)
         .filter(([key]) => /key|token|secret|password|credential/i.test(key))
         .flatMap(([, value]) => (value ? [value] : []));
-    try {
-        const collect = (value) => {
-            if (typeof value === "string")
-                values.push(value);
-            else if (value && typeof value === "object")
-                Object.values(value).forEach(collect);
-        };
-        collect(JSON.parse(readFileSync(join(root, ".env", "auth.json"), "utf8")));
-    }
-    catch {
-        /* The vault may not exist before setup. */
-    }
+    for (const directory of [".nylorun", ".env"])
+        try {
+            const collect = (value) => {
+                if (typeof value === "string")
+                    values.push(value);
+                else if (value && typeof value === "object")
+                    Object.values(value).forEach(collect);
+            };
+            collect(JSON.parse(readFileSync(join(root, directory, "auth.json"), "utf8")));
+        }
+        catch {
+            /* The vault may not exist before setup. */
+        }
     return values;
 }

package/dist/server/host.d.ts

@@ -6,7 +6,7 @@ export type RuntimeActor = Readonly<{
     context?: Record<string, JsonValue>;
 }>;
 export type AgentRouterOptions = Readonly<{
-    /** Public URL prefix of this router, matching the Hono mount path. */
+    /** Override the public URL prefix; defaults to the current Hono mount path. */
     basePath?: string;
     getActor?: (context: Context) => RuntimeActor | undefined | Promise<RuntimeActor | undefined>;
     getRequestMetadata?: (context: Context) => Record<string, JsonValue> | undefined | Promise<Record<string, JsonValue> | undefined>;

package/dist/server/host.js

@@ -1,5 +1,6 @@
 import { randomUUID } from "node:crypto";
 import { Hono } from "hono";
+import { cors } from "hono/cors";
 import { HTTPException } from "hono/http-exception";
 import { agUiEvents, sse } from "./ag-ui.js";
 import { observedPayload } from "./digests.js";
@@ -38,9 +39,34 @@ export class Runtime {
         const configuredObserver = this.#config.observer;
         const redact = (value) => scrub(value, projectSecrets());
         const live = new Map();
-        let publicPath = (path) => path;
         const routerOptions = options;
         const app = new Hono();
+        if (process.env.NYLORUN_DEV === "1") {
+            app.use("*", cors({
+                origin: (origin) => {
+                    try {
+                        const url = new URL(origin);
+                        return ["http:", "https:"].includes(url.protocol) &&
+                            ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname) &&
+                            url.origin === origin
+                            ? origin
+                            : undefined;
+                    }
+                    catch {
+                        return undefined;
+                    }
+                },
+                allowMethods: [
+                    "GET",
+                    "HEAD",
+                    "POST",
+                    "PUT",
+                    "PATCH",
+                    "DELETE",
+                    "OPTIONS",
+                ],
+            }));
+        }
         app.onError((error, context) => context.json({ error: String(redact(error.message)) }, error instanceof HTTPException ? error.status : 500));
         app.use("*", async (context, next) => {
             await next();
@@ -52,19 +78,22 @@ export class Runtime {
                 });
             }
         });
-        publicPath = (path) => `${normalizeBasePath(routerOptions.basePath)}${path}`;
+        // Infer the public mount from this request URL and the local route path.
+        // Do not use hono/route basePath: consumers often install a separate `hono`
+        // copy, and that helper's match-result Symbol then misses the parent's match.
+        const publicPath = (context, routePath, path) => `${normalizeBasePath(routerOptions.basePath ?? inferMountPath(context, routePath))}${path}`;
         app.get("/v1/agents", (context) => context.json({
             protocolVersion: 2,
             agents: agents.map((agent) => ({
                 id: agent.id,
-                manifestUrl: publicPath(`/${agent.id}/manifest.json`),
+                manifestUrl: publicPath(context, "/v1/agents", `/${agent.id}/manifest.json`),
             })),
         }));
         app.get("/:agentId/manifest.json", (context) => {
             const agent = byId.get(context.req.param("agentId"));
             return agent === undefined
                 ? context.json({ error: "unknown agent" }, 404)
-                : context.json(manifest(agent, media !== undefined, publicPath));
+                : context.json(manifest(agent, media !== undefined, (path) => publicPath(context, "/:agentId/manifest.json", path)));
         });
         app.get("/:agentId/v1/media/:session/:assetId", async (context) => {
             const agent = requireAgent(context.req.param("agentId"));
@@ -602,3 +631,20 @@ function normalizeBasePath(value) {
         throw new Error("basePath must start with / and must not end with /.");
     return value;
 }
+/** Public mount prefix for this request, derived without hono/route Symbols. */
+function inferMountPath(context, routePath) {
+    const pathname = new URL(context.req.url).pathname;
+    const suffix = routePath.replace(/:([A-Za-z0-9_]+)/g, (_, key) => {
+        const value = context.req.param(key);
+        if (value === undefined)
+            throw new Error(`Unable to infer Runtime mount path from ${pathname}. Pass basePath matching the Hono mount.`);
+        return value;
+    });
+    if (suffix !== "/" && pathname.endsWith(suffix)) {
+        const base = pathname.slice(0, -suffix.length);
+        return base === "" ? "/" : base;
+    }
+    if (pathname === suffix || `${pathname}/` === suffix)
+        return "/";
+    throw new Error(`Unable to infer Runtime mount path from ${pathname}. Pass basePath matching the Hono mount.`);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nylorun/runtime",
-  "version": "0.2.1-beta",
+  "version": "0.4.0-beta",
   "description": "Portable agent runtime, Hono protocol router, model providers, and the Nylorun CLI.",
   "type": "module",
   "license": "Apache-2.0",
@@ -39,7 +39,8 @@
     "prepack": "npm run build"
   },
   "dependencies": {
-    "@earendil-works/pi-ai": "0.85.1"
+    "@earendil-works/pi-ai": "0.85.1",
+    "@hono/node-server": "^2.1.1"
   },
   "peerDependencies": {
     "hono": "^4.13.7"