@nylorun/runtime 0.2.1-beta → 0.3.0-beta

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 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,31 @@ 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 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.
 
-Provider credentials are stored in `.env/auth.json`, and selection in `config/model.json`. `nylorun configure` can run before an agent graph is importable.
+Provider credentials are stored in `.env/auth.json`, and selection in `.env/model.json`. `nylorun configure` can run before an agent graph is importable.
+
+`nylorun dev` runs project-local `tsx watch src/index.ts`, waits for `/agents/v1/agents`, then starts project-local Studio. `PORT` defaults to 3000. `--no-studio` runs just the application; `--no-open` keeps the browser closed. Both flags can be combined. Ctrl-C stops both processes.
+
+### Upgrading an existing starter
+
+After upgrading Runtime to a release containing `nylorun dev`, change the development script to `"dev": "nylorun dev"` and remove `dev:app` and `scripts/dev.mjs`. Remove the duplicated `basePath` option for normal Hono mounts.
+
+Run `npm run configure` to move model selection to `.env/model.json`. Runtime reads the legacy `config/model.json` only when the new file is absent. Successful configuration removes the legacy file and its directory only if empty; credentials remain in `.env/auth.json`. Do not set `NYLORUN_DEV` in production.
+
+The starter now uses one `tsconfig.json` with `rootDir: "."` and `outDir: "dist"`. Remove `noEmit` from that file and use `tsc --noEmit` for checks. Change the build's compiler invocation to `tsc -p tsconfig.json` before deleting `tsconfig.build.json`. Keep your existing asset-copy step. Projects whose checks include tests may retain separate build configuration.

package/dist/cli.js

@@ -4,8 +4,10 @@ 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 { develop } from "./dev.js";
+const usage = `nylorun <configure|dev|studio>
+  dev [--no-studio] [--no-open]
   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,10 @@ async function main() {
     const [command, ...args] = process.argv.slice(2);
     if (!command || command === "--help" || command === "-h")
         return void console.log(usage);
+    if (command === "dev") {
+        process.exitCode = await develop(args);
+        return;
+    }
     if (command === "configure") {
         if (args.length)
             throw new Error(usage);
@@ -80,5 +90,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.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,121 @@
+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", "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/model/configure.js

@@ -1,4 +1,4 @@
-import { mkdir, writeFile, rename, rm } from "node:fs/promises";
+import { mkdir, writeFile, rename, rm, rmdir } from "node:fs/promises";
 import { randomUUID } from "node:crypto";
 import { join } from "node:path";
 import { createInterface } from "node:readline/promises";
@@ -98,7 +98,7 @@ export async function configureProvider(options = {}) {
     }
     async function save(selection) {
         signal.throwIfAborted();
-        const directory = join(root, "config");
+        const directory = join(root, ".env");
         const temporary = join(directory, `.model-${randomUUID()}.json`);
         try {
             await mkdir(directory, { recursive: true });
@@ -107,6 +107,16 @@ export async function configureProvider(options = {}) {
             });
             signal.throwIfAborted();
             await rename(temporary, join(directory, "model.json"));
+            await rm(join(root, "config", "model.json"), { force: true });
+            try {
+                await rmdir(join(root, "config"));
+            }
+            catch (error) {
+                if (!(error instanceof Error) ||
+                    !("code" in error) ||
+                    !["ENOENT", "ENOTEMPTY", "EEXIST"].includes(String(error.code)))
+                    throw error;
+            }
         }
         finally {
             await rm(temporary, { force: true });

package/dist/model/settings.js

@@ -2,7 +2,18 @@ import { readFileSync } from "node:fs";
 import { join } from "node:path";
 export function modelSelection(root = process.cwd()) {
     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) ||
+                error.code !== "ENOENT")
+                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" &&

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.3.0-beta",
   "description": "Portable agent runtime, Hono protocol router, model providers, and the Nylorun CLI.",
   "type": "module",
   "license": "Apache-2.0",