@nylorun/runtime 0.5.0-beta → 0.6.0-beta

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## 0.6.0-beta
+
+### Major Changes
+
+- 2898d02: Extract shared definitions and contracts into core and local orchestration into
+  CLI. Harness becomes execution-only; the SDK no longer installs the engine and
+  Runtime no longer depends on the SDK. Author applications through agents and
+  install cli for the unchanged nylorun commands. See the package architecture and
+  migration guide. Cloud installs published packages from npm independently.
+
+### Minor Changes
+
+- 41e613c: Ship the local SDK registry workflow with an independent SQLite Runtime, connected tool executor, authenticated Studio proxy, and a text-and-tool starter. Replace the legacy Hono starter and AG-UI transport. Require Node 24 and include the SDK in exact release compatibility pins.
+
+  Break the Harness execution import from `/engine` to `/run` and rename hosted execution APIs to durable execution APIs, including RunBinding, BoundRunOptions, and createRunState. Update all consumers without compatibility aliases; retain persisted checkpoint fields and version pins.
+
+### Patch Changes
+
+- Pin core to the tested release.
+- Pin harness to the tested release.
+- Updated dependencies [41e613c]
+- Updated dependencies [2898d02]
+- Updated dependencies
+  - @nylorun/core@0.1.1-beta
+  - @nylorun/harness@0.15.0-beta
+
 ## 0.5.0-beta
 
 ### Minor Changes
@@ -18,6 +44,10 @@
 
 ### Patch Changes
 
+- Remove the experimental Cloud Agents API destination client and related
+  `RuntimeConfig.cloud` / `NYLORUN_*` Cloud-mode wiring from OSS Runtime.
+  Local `openSession` remains the only destination. Cloud upgrades published
+  packages from npm independently.
 - Ignore Hono Node `context.env` stream bindings (`incoming`/`outgoing`) when
   resolving model environment so Node `nylorun dev` uses process `.env` /
   `piModel` instead of an empty portable HTTP adapter.

package/README.md

@@ -1,79 +1,47 @@
 # @nylorun/runtime
 
-Optional hosting for stateless Harness agents: session coordination, replaceable storage, Hono routes, model adapters, and the Node CLI. Runtime depends directly on canonical Harness types; Harness does not depend on Runtime.
+The independent OSS HTTP execution host consumes `@nylorun/harness/run` and `@nylorun/core/contracts`. Cloud installs published `@nylorun/harness` from npm and does not import this Runtime package. Client authoring, sessions and connected executors belong to `@nylorun/agents`.
 
-```ts
-import { Hono } from "hono";
-import { Runtime, serveAgents } from "@nylorun/runtime";
-const runtime = new Runtime();
-const app = new Hono();
-app.route("/agents", serveAgents({ agents, runtime }));
-export default app;
-```
-
-The default is `memorySessions()` and no file observer. Portable imports do not initialize the filesystem. `httpModel()` supports text/tool/structured-output requests to OpenAI-compatible and Anthropic HTTP endpoints using injected environment values or process variables where available. It requires API keys; media inputs require a supplied media-aware adapter. The Node CLI installs `piModel()` for its broader provider catalog, local credential fallback, OAuth, and media support. Direct portable imports do not load dotenv or local credentials.
+Requires Node 24+. Build from the repository root:
 
-## Storage and coordination
-
-```ts
-import { localSessions, piModel } from "@nylorun/runtime/node";
-const runtime = new Runtime({
-  sessions: localSessions({ root: ".data/sessions" }),
-  onModelCall: piModel(),
-});
+```sh
+npm install
+npm run build --workspace @nylorun/core
+npm run build --workspace @nylorun/harness
+npm run build --workspace @nylorun/runtime
+NYLORUN_SERVER_KEY='<separate-secret-at-least-16-characters>' npm start --workspace @nylorun/runtime
 ```
 
-A `SessionStore` provides `get(agentId, sessionId)`, atomic `put(agentId, sessionId, document)`, and `list(agentId)`. StoredSession includes Runtime metadata, Harness state, an active marker, and committed event history. Stores implement data operations only. The built-in SessionHost serializes inputs, cancels and awaits active work before replacement, persists accepted inputs before execution, and commits terminal state before reporting success. It restores completed and explicitly paused sessions; active markers found after a crash require reconciliation. Legacy event-only records remain archived history.
-
-`localSessions` exclusively owns its root through `.owner.lock`. Multiple owners are rejected, including adapters in the same process. Writes use temporary files and atomic replacement; lost ownership stops writes. Orderly `runtime.close()` releases the matching lock. Locks are never stolen by age or PID: after a crash, confirm the owner stopped before manually removing the lock. No shared-filesystem or multi-replica guarantee is made.
-
-The host's scheduling scope is one process. A shared store is not a distributed scheduler. Advanced applications can use `SessionHost` without Hono, reuse `agUiEvents()` protocol translation, or compose Harness with their own host. Managed Cloud Runtime remains future work.
-
-## Info, delivery, and resources
+Default address: `http://127.0.0.1:8787`. `HOST`, `PORT`, and `NYLORUN_SQLITE_PATH` configure binding and storage. Missing server credentials fail startup. The default model is a credential-free scripted development response. It does not simulate conversations, tools or provider compatibility.
 
-Application middleware authorizes every route. `getInfo(context)` supplies extra application data for each invocation; Runtime adds `sessionId`. `getEnvironment(context)` can supply per-request provider bindings without changing process globals. Neither info nor live resources are implicitly model-visible. `getActor` remains a convenience for userId; use `getInfo` for typed application identity.
+`NYLORUN_EXECUTORS_JSON` is an array of `{token, agentId, manifestHash, implementationVersion}`. Each secret must differ from the application server key and every other executor token. The manifest hash is available from `@nylorun/core/compatibility` or saved definition registration. SDK clients use `NYLORUN_RUNTIME_URL`, `NYLORUN_SERVER_KEY`, and `NYLORUN_EXECUTOR_KEY`; runtime executor scope is configured explicitly, never broadened by client input.
 
-Runtime delivers ordered observations incrementally, separately from committed history. `tokens: true` enables provisional text previews on compatible model adapters; the default is off. `createModel({ environment, media, onPreview })` supplies preview support for custom adapters. Studio shows drafts separately and discards them on settlement; accepted output remains authoritative. Partial tool arguments never dispatch tools.
+For a model gateway, set `NYLORUN_MODEL_GATEWAY_URL`, `NYLORUN_MODEL_GATEWAY_KEY`, and `NYLORUN_MODEL`. The gateway receives `{model, call, context}` and returns a harness ModelCandidate or string. Provider credentials remain host configuration. The generic gateway requires an implementation of this envelope; it does not claim arbitrary provider wire compatibility. Alternatively supply a `ModelProvider` to `startRuntime`.
 
-Delivery limits default to 64 KiB of preview data per model invocation (also bounding queued previews), and 256 events or 1 MiB of queued execution/control data. Configure them with `delivery: { previewBytes, eventCount, eventBytes }`. Preview overflow suppresses further previews for that model invocation and emits an incomplete marker. Authoritative overflow closes the subscription. Neither path blocks model consumption; request-attached execution is cooperatively cancelled on disconnect. Independent execution/reconnection belongs to a custom host.
-
-Runtime owns controllers and its store lifecycle. It does not close application tools, databases, browsers, or subprocesses. The Node launcher drains registered Runtime hosts during orderly shutdown; application resource cleanup remains explicit. Imports never open a listening socket. Root-relative discovery supports ordinary Hono mounts; use `basePath` for a rewriting proxy. Production authentication, CORS, ingress timeouts, and TLS belong to the application and infrastructure.
-
-## 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]`
-
-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
+```ts
+import { startRuntime } from '@nylorun/runtime/core';
+const runtime = await startRuntime({
+  sqlitePath: './nylorun.sqlite',
+  serverToken: process.env.NYLORUN_SERVER_KEY!,
+  executors: [], // Configure exact scoped executor credentials before customer actions.
+  port: 8787,
+});
+// Application owns lifecycle.
+await runtime.close();
 ```
 
-`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.
+The session-first `/v1` API is specified in [HOST_CONTRACT.md](../harness/HOST_CONTRACT.md). `/health` confirms HTTP liveness; `/ready` checks SQLite and scheduler availability. Readiness is not a provider connectivity probe or functional correctness claim. Application tokens authorize definition/session APIs, while exact scoped executor credentials authorize authenticated SSE `/v1/executors/connect`, action discovery, claims, renewal and results. Session observers cannot claim actions.
 
-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.
+SQLite transactions persist session checkpoints, command receipts, individual effects/actions, waits and canonical history. Actions are committed before notifications. Accepted execution is detached from HTTP request lifetime. Restart schedules persisted runnable sessions; model intents lacking recorded outcomes become uncertain. Expired customer claims become uncertain and are not automatically repeated. `GET /v1/sessions/:id` exposes waits, outstanding actions and uncertain effect summaries. Cancellation ends the current turn; a later message can start another turn from the state preceding the cancelled turn. Canonical events and uncertain external work remain inspectable. Reconciliation operations are not implemented in this pass.
 
-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.
+One process owns each SQLite database. A local PID lock rejects concurrent owners and recovers only when the recorded process no longer exists. Shared/network filesystems and multiple replicas are unsupported. Keep the database and its WAL/journal together; do not delete persisted effects separately from checkpoints. Invalid lock contents or PID reuse fail closed and require operator inspection. TLS and external ingress belong to deployment infrastructure.
 
-### Upgrading an existing starter
+## Local project workflow
 
-Migration is manual; the CLI will not replace a legacy `.env` directory.
+Install `@nylorun/cli` (generated projects already include it). Use `npm run configure`, then `nylorun dev` in a generated project. It loads the exported `agents` registry from `agents/index.ts`, starts this Runtime in a separate process, registers manifests, connects scoped SDK executors, and opens Studio. Use `--no-studio` or `--no-open` as needed. Runtime binds loopback on port 8787 (`PORT` override). The CLI creates separate server and executor credentials with mode 0600 in `.nylorun/local-credentials.json`; SQLite defaults to `.nylorun/runtime.sqlite`.
 
-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.
+`nylorun start [entry]` loads `dist/agents/index.js` by default and runs without Studio/watch. `nylorun studio --runtime-url http://127.0.0.1:8787` attaches using the project's local server credential (or `NYLORUN_SERVER_KEY`). Provider selection uses the existing `MODEL_PROVIDER`, `MODEL`, `MODEL_PROVIDER_API_KEY`, and optional `MODEL_PROVIDER_BASE_URL` configuration. No provider request occurs during configuration.
 
-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.
+Definitions have no `agent.run()`; applications use `@nylorun/agents`. Remove old Hono `src/index.ts`, `Runtime`, `serveAgents`, and `openSession` usage from supported starters. Historical implementations remain internal for regression coverage and advanced examples; they are not root exports or supported hosting alternatives.
 
-The exported app follows Hono composition conventions. See [deployment verification and limits](../DEPLOYMENT.md) and the [breaking migration guide](../MIGRATION.md). Node-only `projectAsset()` resolves bundled assets from source or compiled deployments.
+Source changes restart the local stack. Start a new session after definition or implementation edits; live upgrades are deferred. `GET /v1/agents` and `GET /v1/sessions?agentId=...` are server-authenticated local discovery conveniences. See the repository handoff for verification and remaining scope.

package/dist/config.d.ts

@@ -1,4 +1,4 @@
-import type { ModelAdapter } from "@nylorun/harness";
+import type { ModelAdapter } from "@nylorun/core/define";
 import type { SessionStore } from "./sessions/store.js";
 import type { RuntimeMedia } from "./media.js";
 import type { ModelEnvironment } from "./model/http-model.js";

package/dist/configuration.d.ts

@@ -0,0 +1,3 @@
+export { modelsFor, type Selection } from "./model/models.js";
+export { modelSelection, projectSecrets } from "./model/settings.js";
+export { ProjectCredentialStore } from "./model/auth-store.js";

package/dist/configuration.js

@@ -0,0 +1,3 @@
+export { modelsFor } from "./model/models.js";
+export { modelSelection, projectSecrets } from "./model/settings.js";
+export { ProjectCredentialStore } from "./model/auth-store.js";

package/dist/contracts.d.ts

@@ -1,3 +1,5 @@
 /** Execution contracts are owned by Harness. */
-export type { JsonValue, JsonObject, MessageInput, UserContentPart, PromptContentPart, PromptItem, ModelCall as RuntimeModelCall, ModelCandidate as RuntimeModelCandidate, ModelAdapter as RuntimeModelAdapter, ModelAdapterContext as RuntimeModelContext, ExecutionInput as RuntimeInput, InputEvent as RuntimeInputEvent, RunResult as RuntimeCompletion, ExecutionEvent as RuntimeEvent, } from "@nylorun/harness";
-export type RuntimeAgent = import("@nylorun/harness").BuiltAgent<any, any>;
+export type { JsonValue, JsonObject, MessageInput, UserContentPart, PromptContentPart, PromptItem, ModelCall as RuntimeModelCall, ModelCandidate as RuntimeModelCandidate, ModelAdapter as RuntimeModelAdapter, ModelAdapterContext as RuntimeModelContext, InputEvent as RuntimeInputEvent } from "@nylorun/core/define";
+export type { ExecutionInput as RuntimeInput, RunResult as RuntimeCompletion, ExecutionEvent as RuntimeEvent, Session, Turn, Event, Result, InputAccepted, AgentIdentity } from "@nylorun/harness";
+export type { RunBinding, BoundRunOptions, } from "@nylorun/harness/run";
+export type RuntimeAgent = import("@nylorun/core/define").BuiltAgent<any, any>;

package/dist/core/main.js

@@ -0,0 +1,40 @@
+import { piModel } from "../model/pi-model.js";
+import { startRuntime } from "./runtime.js";
+import { gatewayModel, scriptedModel, toolFixtureModel } from "./provider.js";
+const serverToken = process.env.NYLORUN_SERVER_KEY;
+if (!serverToken)
+    throw new Error("Set NYLORUN_SERVER_KEY (at least 16 characters)");
+const executors = JSON.parse(process.env.NYLORUN_EXECUTORS_JSON ?? "[]");
+const configured = piModel();
+const projectModel = (effect, signal) => configured(effect.input, {
+    request: effect.context.request,
+    invocationId: String(effect.context.invocationId),
+    signal,
+    reportPreparedCall() { },
+});
+const model = process.env.NYLORUN_DEV_MODEL === "fixture"
+    ? toolFixtureModel()
+    : process.env.NYLORUN_PROJECT_PROVIDER === "1"
+        ? projectModel
+        : process.env.NYLORUN_MODEL_GATEWAY_URL
+            ? gatewayModel({
+                url: process.env.NYLORUN_MODEL_GATEWAY_URL,
+                token: process.env.NYLORUN_MODEL_GATEWAY_KEY ?? "",
+                model: process.env.NYLORUN_MODEL ?? "",
+            })
+            : scriptedModel(process.env.NYLORUN_SCRIPTED_OUTPUT);
+const runtime = await startRuntime({
+    sqlitePath: process.env.NYLORUN_SQLITE_PATH ?? "./nylorun.sqlite",
+    serverToken,
+    executors,
+    model,
+    port: Number(process.env.PORT ?? 8787),
+    hostname: process.env.HOST ?? "127.0.0.1",
+});
+console.log(`Nylorun Runtime listening at ${runtime.url}`);
+process.send?.({ type: "ready", url: runtime.url });
+let closing;
+for (const signal of ["SIGINT", "SIGTERM"])
+    process.on(signal, () => {
+        closing ??= runtime.close().then(() => { process.exit(0); });
+    });

package/dist/core/provider.d.ts

@@ -0,0 +1,12 @@
+import type { HostEffect } from "@nylorun/harness/run";
+/** Providers are runtime-owned; neither credentials nor model selection enter manifests. */
+export type ModelProvider = (effect: HostEffect, signal: AbortSignal) => Promise<unknown>;
+export declare function scriptedModel(output?: string): ModelProvider;
+/** A configured gateway receives the complete harness model call, including history and schemas. */
+export declare function gatewayModel(options: {
+    url: string;
+    token: string;
+    model: string;
+}): ModelProvider;
+/** Deterministic release fixture; still uses the real engine and remote customer tool. */
+export declare function toolFixtureModel(): ModelProvider;

package/dist/core/provider.js

@@ -0,0 +1,60 @@
+export function scriptedModel(output = "Scripted development response") {
+    return async () => ({ output: [{ type: "text", text: output }] });
+}
+/** A configured gateway receives the complete harness model call, including history and schemas. */
+export function gatewayModel(options) {
+    return async (effect, signal) => {
+        const response = await fetch(options.url, {
+            method: "POST",
+            signal,
+            headers: {
+                authorization: `Bearer ${options.token}`,
+                "content-type": "application/json",
+            },
+            body: JSON.stringify({
+                model: options.model,
+                call: effect.input,
+                context: effect.context,
+            }),
+        });
+        if (!response.ok)
+            throw new Error(`Model gateway returned ${response.status}`);
+        return response.json();
+    };
+}
+/** Deterministic release fixture; still uses the real engine and remote customer tool. */
+export function toolFixtureModel() {
+    return async (effect) => {
+        const call = effect.input;
+        const last = call.prompt.at(-1);
+        if (last?.kind === "tool-result")
+            return {
+                output: [
+                    {
+                        type: "text",
+                        text: `Order lookup complete: ${last.content.map((part) => (part.type === "text" ? part.text : JSON.stringify(part))).join(" ")}`,
+                    },
+                ],
+            };
+        const users = call.prompt.filter((p) => p.kind === "message" && p.role === "user");
+        if (users.length > 1)
+            return {
+                output: [
+                    {
+                        type: "text",
+                        text: `I remember: ${users[0].content.map((part) => (part.type === "text" ? part.text : "")).join(" ")}`,
+                    },
+                ],
+            };
+        return {
+            output: [
+                {
+                    type: "tool-call",
+                    id: "fixture_lookup",
+                    name: "lookup_order",
+                    args: { orderId: "demo-123" },
+                },
+            ],
+        };
+    };
+}

package/dist/core/runtime.d.ts

@@ -0,0 +1,50 @@
+import { type ExecutorScope } from "@nylorun/core/contracts";
+import { type ModelProvider } from "./provider.js";
+export interface RuntimeOptions {
+    sqlitePath: string;
+    serverToken: string;
+    executors: readonly (ExecutorScope & {
+        token: string;
+    })[];
+    model?: ModelProvider;
+    leaseMs?: number;
+}
+export declare class CoreRuntime {
+    private readonly options;
+    private readonly store;
+    private readonly running;
+    private readonly pending;
+    private readonly observers;
+    private readonly executors;
+    private server?;
+    private closing;
+    private readonly lockPath?;
+    private readonly timer;
+    constructor(options: RuntimeOptions);
+    private session;
+    private publish;
+    private send;
+    private notify;
+    private expireClaims;
+    private schedule;
+    private execute;
+    private resolveEffect;
+    private scope;
+    private scoped;
+    private body;
+    private command;
+    private sse;
+    private handle;
+    private view;
+    listen(port?: number, hostname?: string): Promise<{
+        url: string;
+    }>;
+    close(): Promise<void>;
+}
+export declare function createRuntime(options: RuntimeOptions): CoreRuntime;
+export declare function startRuntime(options: RuntimeOptions & {
+    port?: number;
+    hostname?: string;
+}): Promise<CoreRuntime & {
+    url: string;
+}>;