@nylorun/runtime 0.1.1-beta

package/dist/cli.js

@@ -0,0 +1,319 @@
+#!/usr/bin/env node
+import { existsSync } from "node:fs";
+import { loadEnvFile } from "node:process";
+import { cp, mkdir } from "node:fs/promises";
+import { createRequire } from "node:module";
+import { resolve, join, relative, isAbsolute, sep } from "node:path";
+import { pathToFileURL } from "node:url";
+import { serve } from "@hono/node-server";
+import { build, createServer } from "vite";
+import { defineRuntime } from "./config.js";
+import { allowedHost, createRuntime, loopbackHosts } from "./server/host.js";
+import { configureProvider, ConfigurationCancelled, } from "./model/configure.js";
+import { modelSelection } from "./model/settings.js";
+import { modelsFor } from "./model/models.js";
+import { ProjectCredentialStore } from "./model/auth-store.js";
+const usage = `nylorun <dev|studio|configure|inspect|build|start>
+  dev [--no-studio] [--no-open] [--port <n>] [--host <address>] [--allowed-hosts <list>]
+  studio --agent-url <http(s)-url> [--port <n>] [--no-open]
+  start [--port <n>] [--host <address>] [--allowed-hosts <list>]
+Run from the directory containing nylorun.config.ts.
+PORT, HOST and ALLOWED_HOSTS environment variables supply the same settings.`;
+async function studio(agentServerUrl, open, port) {
+    let entry;
+    try {
+        entry = createRequire(join(process.cwd(), "package.json")).resolve("@nylorun/studio");
+    }
+    catch {
+        throw new Error("Install @nylorun/studio in this project, or run nylorun dev --no-studio.");
+    }
+    const module = await import(pathToFileURL(entry).href);
+    return module.startStudio({
+        agentServerUrl,
+        open,
+        ...(port === undefined ? {} : { port }),
+    });
+}
+function port(value, fallback) {
+    const result = value === undefined ? fallback : Number(value);
+    if (!Number.isInteger(result) || result < 1 || result > 65535)
+        throw new Error("Port must be an integer between 1 and 65535.");
+    return result;
+}
+/**
+ * Loopback binds answer only to their own address on the chosen port, so
+ * development needs no setup. A published bind or an explicit allowed-host
+ * list is the deployment decision; "*" accepts any Host header.
+ */
+function bindAddress(host, allowed, hostPort) {
+    const hostname = (host?.trim() || "127.0.0.1").replace(/^\[(.*)\]$/u, "$1");
+    const loopback = ["127.0.0.1", "localhost", "::1"].includes(hostname);
+    const configured = (allowed ?? "")
+        .split(",")
+        .map((entry) => entry.trim())
+        .filter(Boolean);
+    const hosts = configured.length
+        ? [...(loopback ? loopbackHosts(hostPort) : []), ...configured]
+        : loopback
+            ? loopbackHosts(hostPort)
+            : ["*"];
+    const unspecified = ["0.0.0.0", "::"].includes(hostname);
+    const reachable = unspecified
+        ? "127.0.0.1"
+        : hostname.includes(":")
+            ? `[${hostname}]`
+            : hostname;
+    return { hostname, reachable, loopback, hosts };
+}
+async function sourceLoader() {
+    const vite = await createServer({
+        configFile: false,
+        appType: "custom",
+        optimizeDeps: { noDiscovery: true, include: [] },
+        server: { middlewareMode: true, hmr: false, ws: false },
+        ssr: { external: true },
+    });
+    return {
+        vite,
+        async load() {
+            const module = await vite.ssrLoadModule("/nylorun.config.ts");
+            return defineRuntime(module.default);
+        },
+    };
+}
+async function main() {
+    const [command, ...args] = process.argv.slice(2);
+    if (!command || command === "--help" || command === "-h") {
+        console.log(usage);
+        return;
+    }
+    const allowed = {
+        dev: ["--no-studio", "--no-open", "--port", "--host", "--allowed-hosts"],
+        studio: ["--agent-url", "--port", "--no-open"],
+        start: ["--port", "--host", "--allowed-hosts"],
+        configure: [],
+        inspect: [],
+        build: [],
+    };
+    if (!(command in allowed))
+        throw new Error(usage);
+    const flags = new Map();
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (!allowed[command].includes(arg) || flags.has(arg))
+            throw new Error(`Invalid option ${arg}\n${usage}`);
+        if (["--port", "--agent-url", "--host", "--allowed-hosts"].includes(arg)) {
+            const value = args[++i];
+            if (!value || value.startsWith("--"))
+                throw new Error(`${arg} requires a value.`);
+            flags.set(arg, value);
+        }
+        else
+            flags.set(arg, true);
+    }
+    const requestedPort = flags.get("--port");
+    if (command === "configure") {
+        const controller = new AbortController();
+        const onInt = () => controller.abort(new ConfigurationCancelled("SIGINT"));
+        const onTerm = () => controller.abort(new ConfigurationCancelled("SIGTERM"));
+        process.on("SIGINT", onInt);
+        process.on("SIGTERM", onTerm);
+        try {
+            const integrations = join(process.cwd(), ".env", "integrations.env");
+            if (existsSync(integrations))
+                loadEnvFile(integrations);
+            await configureProvider({ signal: controller.signal });
+        }
+        finally {
+            process.removeListener("SIGINT", onInt);
+            process.removeListener("SIGTERM", onTerm);
+        }
+        return;
+    }
+    let stopping = false;
+    const shutdown = [];
+    const stop = async () => {
+        if (stopping)
+            return;
+        stopping = true;
+        const results = await Promise.allSettled(shutdown.map((close) => close()));
+        if (results.some((result) => result.status === "rejected"))
+            process.exitCode = 1;
+    };
+    process.once("SIGINT", () => void stop());
+    process.once("SIGTERM", () => void stop());
+    try {
+        const integrations = join(process.cwd(), ".env", "integrations.env");
+        if (existsSync(integrations))
+            loadEnvFile(integrations);
+        if (command === "studio") {
+            const url = flags.get("--agent-url");
+            if (typeof url !== "string")
+                throw new Error("--agent-url is required.");
+            const dashboard = await studio(url, !flags.has("--no-open"), requestedPort ? port(requestedPort, 0) : undefined);
+            shutdown.push(() => dashboard.close());
+            console.log(`Studio on ${dashboard.address}`);
+            return;
+        }
+        if (command === "build") {
+            await build({
+                configFile: false,
+                build: {
+                    target: "node22",
+                    ssr: "nylorun.config.ts",
+                    outDir: "dist",
+                    rollupOptions: { output: { entryFileNames: "nylorun.config.js" } },
+                },
+                ssr: { external: true },
+            });
+            if (existsSync("agent")) {
+                await mkdir("dist/agent", { recursive: true });
+                await cp("agent", "dist/agent", {
+                    recursive: true,
+                    filter: (source) => !source.split(/[\\/]/).includes("node_modules"),
+                });
+            }
+            return;
+        }
+        let loader;
+        let config;
+        if (command === "start")
+            config = defineRuntime((await import(pathToFileURL(resolve("dist/nylorun.config.js")).href))
+                .default);
+        else {
+            loader = await sourceLoader();
+            shutdown.push(() => loader.vite.close());
+            config = await loader.load();
+        }
+        if (command === "inspect") {
+            let setup = "required";
+            try {
+                const selected = modelSelection();
+                setup = (await modelsFor(selected, new ProjectCredentialStore()).checkAuth(selected.provider))
+                    ? "ready"
+                    : "required";
+            }
+            catch {
+                /* Unconfigured is a valid inspection state. */
+            }
+            console.log(JSON.stringify({ agents: config.agents.map((agent) => agent.manifest), setup }, null, 2));
+            await stop();
+            return;
+        }
+        let current = await createRuntime(config);
+        const retained = [current];
+        shutdown.push(async () => {
+            await Promise.all(retained.map((runtime) => runtime.close()));
+        });
+        const fetch = async (request) => {
+            const path = new URL(request.url).pathname;
+            const collection = path.match(/^\/agents\/([^/]+)\/v1\/sessions$/);
+            if (request.method === "GET" && collection && retained.length > 1) {
+                const response = await current.app.fetch(request);
+                if (!response.ok)
+                    return response;
+                const agentId = collection[1];
+                const document = (await response.json());
+                const summaries = new Map(document.sessions.map((item) => [item.session, item]));
+                // A journal may be shared across reloads, but only the owning runtime
+                // knows whether a retained session is still running or waiting.
+                for (const runtime of retained) {
+                    if (runtime === current)
+                        continue;
+                    const previous = await runtime.app.fetch(request.clone());
+                    if (!previous.ok)
+                        continue;
+                    const history = (await previous.json());
+                    for (const summary of history.sessions) {
+                        if (runtime.hasSession(agentId, summary.session) ||
+                            !summaries.has(summary.session))
+                            summaries.set(summary.session, summary);
+                    }
+                }
+                return new Response(JSON.stringify({
+                    sessions: [...summaries.values()].sort((a, b) => b.startedAt - a.startedAt),
+                }), { status: response.status, headers: response.headers });
+            }
+            const match = path.match(/^\/agents\/([^/]+)\/v1\/(?:sessions|ag-ui\/sessions|media)\/([^/]+)/);
+            let agentId = match?.[1];
+            let sessionId = match?.[2];
+            if (!match && request.method === "POST" && path.endsWith("/v1/ag-ui")) {
+                agentId = path.split("/")[2];
+                const body = await request
+                    .clone()
+                    .json()
+                    .catch(() => ({}));
+                sessionId =
+                    typeof body.threadId === "string" ? body.threadId : undefined;
+            }
+            const runtime = agentId && sessionId
+                ? [...retained]
+                    .reverse()
+                    .find((item) => item.hasSession(agentId, sessionId)) ?? current
+                : current;
+            return runtime.app.fetch(request);
+        };
+        const hostPort = port(requestedPort ?? process.env.PORT, 4111);
+        const binding = bindAddress(flags.get("--host") ?? process.env.HOST, flags.get("--allowed-hosts") ??
+            process.env.ALLOWED_HOSTS, hostPort);
+        const guarded = async (request) => allowedHost(request.headers.get("host") ?? undefined, binding.hosts)
+            ? fetch(request)
+            : Response.json({
+                error: "Host header is not allowed. Set --allowed-hosts or ALLOWED_HOSTS.",
+            }, { status: 421 });
+        const server = serve({
+            fetch: guarded,
+            hostname: binding.hostname,
+            port: hostPort,
+        });
+        shutdown.push(() => new Promise((resolve, reject) => server.close((error) => (error ? reject(error) : resolve()))));
+        await new Promise((resolve, reject) => {
+            server.once("listening", resolve);
+            server.once("error", reject);
+        });
+        const address = `http://${binding.reachable}:${hostPort}`;
+        console.log(`Agent runtime on ${address}`);
+        if (!binding.loopback)
+            console.log(binding.hosts.includes("*")
+                ? "Serving every Host header; add TLS and access control at the network boundary."
+                : `Serving Host headers: ${binding.hosts.join(", ")}`);
+        if (command === "dev" && !flags.has("--no-studio")) {
+            const dashboard = await studio(address, !flags.has("--no-open"));
+            shutdown.push(() => dashboard.close());
+            console.log(`Studio on ${dashboard.address}`);
+        }
+        if (loader) {
+            let reload = Promise.resolve();
+            loader.vite.watcher.on("all", (event, file) => {
+                const path = relative(process.cwd(), file).split(sep).join("/");
+                if (stopping ||
+                    !["add", "change", "unlink"].includes(event) ||
+                    isAbsolute(path) ||
+                    path.startsWith("..") ||
+                    !(path === "nylorun.config.ts" || path.startsWith("agent/")))
+                    return;
+                reload = reload.then(async () => {
+                    try {
+                        loader.vite.moduleGraph.invalidateAll();
+                        const replacement = await createRuntime(await loader.load());
+                        current = replacement;
+                        retained.push(replacement);
+                        console.log(`Reloaded ${path}`);
+                    }
+                    catch (error) {
+                        console.error(`Reload failed; existing agents remain active: ${error instanceof Error ? error.message : String(error)}`);
+                    }
+                });
+            });
+        }
+    }
+    catch (error) {
+        await stop();
+        throw error;
+    }
+}
+void main().catch((error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode =
+        error instanceof ConfigurationCancelled ? error.exitCode : 1;
+});

package/dist/config.d.ts

@@ -0,0 +1,10 @@
+import type { RuntimeAgent } from "./contracts.js";
+import type { RuntimePersistence } from "./adapters/journal.js";
+import type { RuntimeMedia } from "./adapters/media.js";
+export interface RuntimeConfig {
+    readonly agents: readonly RuntimeAgent[];
+    readonly persistence?: RuntimePersistence;
+    readonly media?: RuntimeMedia;
+    readonly origins?: readonly string[];
+}
+export declare function defineRuntime(config: RuntimeConfig): RuntimeConfig;

package/dist/config.js

@@ -0,0 +1,15 @@
+export function defineRuntime(config) {
+    if (!config || !Array.isArray(config.agents))
+        throw new Error("Runtime config must declare an agents array.");
+    for (const agent of config.agents) {
+        if (!agent ||
+            typeof agent.run !== "function" ||
+            typeof agent.id !== "string" ||
+            !agent.manifest)
+            throw new Error("Every registered agent must satisfy RuntimeAgent.");
+    }
+    return Object.freeze({
+        ...config,
+        agents: Object.freeze([...config.agents]),
+    });
+}

package/dist/contracts.d.ts

@@ -0,0 +1,147 @@
+/** Portable values and callable interfaces. No agent engine is required. */
+export type JsonValue = string | number | boolean | null | JsonObject | readonly JsonValue[];
+export type JsonObject = {
+    readonly [key: string]: JsonValue;
+};
+export type UserContentPart = {
+    readonly type: "text";
+    readonly text: string;
+} | {
+    readonly type: "media";
+    readonly mediaType: string;
+    readonly reference: JsonValue;
+};
+export type MessageInput = string | {
+    readonly text: string;
+    readonly metadata?: JsonObject;
+} | {
+    readonly content: readonly UserContentPart[];
+    readonly metadata?: JsonObject;
+};
+export type InteractionReply = {
+    readonly kind: "approve";
+    readonly interactionId: string;
+    readonly approved: boolean;
+} | {
+    readonly kind: "respond";
+    readonly interactionId: string;
+    readonly value: JsonValue;
+};
+export type RuntimeInput = MessageInput | InteractionReply;
+export type RuntimeInputEvent = InteractionReply | {
+    readonly kind: "user-message" | "interrupt";
+    readonly text?: string;
+    readonly content?: readonly UserContentPart[];
+};
+/** Lifecycle events are delivered in completion order; other events are diagnostics. */
+export interface RuntimeEvent {
+    readonly type: string;
+    readonly output?: JsonValue;
+    readonly event?: RuntimeInputEvent;
+    readonly interaction?: unknown;
+    readonly attributes?: unknown;
+}
+export interface RuntimeCompletion {
+    readonly status: "completed" | "waiting" | "rejected" | "cancelled" | "stopped";
+    readonly events: readonly RuntimeEvent[];
+}
+export interface RuntimeSession {
+    readonly id: string;
+    input(event: RuntimeInput, options?: {
+        readonly signal?: AbortSignal;
+    }): {
+        readonly completed: Promise<RuntimeCompletion>;
+    };
+    stream(): AsyncIterable<RuntimeEvent>;
+    observe(listener: (event: RuntimeEvent) => void | Promise<void>): () => void;
+    stop(reason?: string): Promise<void>;
+}
+export interface RuntimeAgent {
+    readonly id: string;
+    readonly name: string;
+    readonly manifest: {
+        readonly id: string;
+        readonly name: string;
+    };
+    run(options?: {
+        readonly id?: string;
+        readonly userId?: string;
+        readonly context?: JsonObject;
+    }): RuntimeSession;
+    close?(): Promise<void>;
+}
+export type PromptContentPart = UserContentPart | {
+    readonly type: "tool-call";
+    readonly id: string;
+    readonly name: string;
+    readonly args: JsonObject;
+};
+export type PromptItem = {
+    readonly kind: "instructions";
+    readonly role: "system";
+    readonly content: readonly PromptContentPart[];
+} | {
+    readonly kind: "message";
+    readonly role: "user" | "assistant";
+    readonly content: readonly PromptContentPart[];
+} | {
+    readonly kind: "context";
+    readonly role: "user";
+    readonly content: readonly PromptContentPart[];
+} | {
+    readonly kind: "tool-result";
+    readonly toolCallId: string;
+    readonly toolName: string;
+    readonly status: "completed" | "denied" | "failed";
+    readonly content: readonly PromptContentPart[];
+};
+export interface RuntimeModelCall {
+    readonly sessionId: string;
+    readonly prompt: readonly PromptItem[];
+    readonly tools: readonly {
+        readonly name: string;
+        readonly description?: string;
+        readonly inputSchema: JsonObject;
+    }[];
+    readonly outputSchema?: JsonObject;
+    readonly model?: {
+        readonly id?: string;
+        readonly controls?: {
+            readonly temperature?: number;
+            readonly maxOutputTokens?: number;
+        };
+        readonly config?: JsonObject;
+    };
+}
+export interface RuntimeModelCandidate {
+    readonly output: readonly ({
+        readonly type: "text" | "reasoning";
+        readonly text: string;
+    } | {
+        readonly type: "json";
+        readonly value: JsonValue;
+    } | {
+        readonly type: "tool-call";
+        readonly id: string;
+        readonly name: string;
+        readonly args: JsonObject;
+    })[];
+    readonly finishReason?: "stop" | "length" | "tool-calls" | "content-filter" | "other";
+    readonly usage?: {
+        readonly inputTokens?: number;
+        readonly outputTokens?: number;
+        readonly totalTokens?: number;
+        readonly costUsd?: number;
+    };
+    readonly evidence?: {
+        readonly resolvedModel?: string;
+    };
+}
+export interface RuntimeModelContext {
+    readonly signal: AbortSignal;
+    reportPreparedCall?(prepared: {
+        readonly adapter: string;
+        readonly call: JsonValue;
+    }): void;
+}
+export type RuntimeModelAdapter = (call: RuntimeModelCall, context: RuntimeModelContext) => Promise<RuntimeModelCandidate>;

package/dist/contracts.js

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

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+export { defineRuntime } from "./config.js";
+export type { RuntimeConfig } from "./config.js";
+export type * from "./contracts.js";
+export { createRuntime } from "./server/host.js";
+export { piModel } from "./model/pi-model.js";
+export type { PiModelOptions } from "./model/pi-model.js";
+export { localJsonl, memoryHistory, JsonlJournal } from "./adapters/journal.js";
+export type { RuntimePersistence, CanonicalEvent, SessionSummary, } from "./adapters/journal.js";
+export { localMedia, MediaStore, IMAGE_MEDIA_TYPES, MAX_IMAGE_BYTES, decodeImageBase64, validateImageBytes, } from "./adapters/media.js";
+export type { RuntimeMedia, MediaAsset, MediaReference, } from "./adapters/media.js";
+export { projectAsset } from "./assets.js";

package/dist/index.js

@@ -0,0 +1,6 @@
+export { defineRuntime } from "./config.js";
+export { createRuntime } from "./server/host.js";
+export { piModel } from "./model/pi-model.js";
+export { localJsonl, memoryHistory, JsonlJournal } from "./adapters/journal.js";
+export { localMedia, MediaStore, IMAGE_MEDIA_TYPES, MAX_IMAGE_BYTES, decodeImageBase64, validateImageBytes, } from "./adapters/media.js";
+export { projectAsset } from "./assets.js";

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

@@ -0,0 +1,10 @@
+import type { Credential, CredentialInfo, CredentialStore } from "@earendil-works/pi-ai";
+export declare class ProjectCredentialStore implements CredentialStore {
+    #private;
+    private readonly file;
+    constructor(file?: string);
+    read(providerId: string): Promise<Credential | undefined>;
+    list(): Promise<readonly CredentialInfo[]>;
+    modify(providerId: string, fn: (current: Credential | undefined) => Promise<Credential | undefined>): Promise<Credential | undefined>;
+    delete(providerId: string): Promise<void>;
+}

package/dist/model/auth-store.js

@@ -0,0 +1,85 @@
+import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+export class ProjectCredentialStore {
+    file;
+    #chain = Promise.resolve();
+    constructor(file = join(process.cwd(), ".env", "auth.json")) {
+        this.file = file;
+    }
+    async read(providerId) {
+        return (await this.#all())[providerId];
+    }
+    async list() {
+        return Object.entries(await this.#all()).map(([providerId, credential]) => ({ providerId, type: credential.type }));
+    }
+    async modify(providerId, fn) {
+        let result;
+        await this.#serialized(async () => {
+            const all = await this.#all();
+            const current = all[providerId];
+            const next = await fn(current);
+            // The pi-ai contract: undefined leaves the entry unchanged.
+            result = next ?? current;
+            if (next === undefined)
+                return;
+            all[providerId] = next;
+            await this.#write(all);
+        });
+        return result;
+    }
+    async delete(providerId) {
+        await this.#serialized(async () => {
+            const all = await this.#all();
+            if (!(providerId in all))
+                return;
+            delete all[providerId];
+            await this.#write(all);
+        });
+    }
+    async #serialized(operation) {
+        const work = this.#chain.then(() => this.#locked(operation));
+        this.#chain = work.catch(() => undefined);
+        await work;
+    }
+    async #write(all) {
+        await mkdir(dirname(this.file), { recursive: true });
+        const temporary = this.file + ".tmp";
+        await writeFile(temporary, JSON.stringify(all, null, 2) + "\n", {
+            mode: 0o600,
+        });
+        await rename(temporary, this.file);
+    }
+    async #all() {
+        try {
+            return JSON.parse(await readFile(this.file, "utf8"));
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return {};
+            throw error;
+        }
+    }
+    async #locked(operation) {
+        await mkdir(dirname(this.file), { recursive: true });
+        const lock = this.file + ".lock";
+        for (let attempt = 0; attempt < 100; attempt += 1) {
+            try {
+                await mkdir(lock);
+                break;
+            }
+            catch (error) {
+                if (error.code !== "EEXIST")
+                    throw error;
+                await new Promise((resolve) => setTimeout(resolve, 25));
+            }
+            if (attempt === 99)
+                throw new Error("Timed out waiting for the credential store.");
+        }
+        try {
+            return await operation();
+        }
+        finally {
+            await rm(lock, { recursive: true, force: true });
+        }
+    }
+}

package/dist/model/configure.d.ts

@@ -0,0 +1,12 @@
+import type { Readable, Writable } from "node:stream";
+export declare class ConfigurationCancelled extends Error {
+    readonly signal: "SIGINT" | "SIGTERM";
+    readonly exitCode: number;
+    constructor(signal: "SIGINT" | "SIGTERM");
+}
+export declare function configureProvider(options?: {
+    signal?: AbortSignal;
+    root?: string;
+    input?: Readable;
+    output?: Writable;
+}): Promise<void>;