@nylorun/agents 0.18.0-beta → 0.19.1-beta

package/CHANGELOG.md

@@ -1,5 +1,40 @@
 # @nylorun/agents
 
+## 0.19.1-beta
+
+### Patch Changes
+
+- Pin core to the tested release.
+- Updated dependencies [212364b]
+  - @nylorun/core@0.19.0-beta
+
+## 0.19.0-beta
+
+### Minor Changes
+
+- 7780b2f: **One client and connection layer.** The Project link and credentials are read one way, and every Runtime client shares one `/health` probe.
+
+  - `@nylorun/core`: `@nylorun/core/project` (Node only, the one Core subpath that imports Node modules) reads the Nylorun home, a local Tenant's Host root (`tenantHostRoot`), the Project root (`findProjectRoot`) and the Project link and credentials (`findLinkedProject`, `readProjectLink`, `readCredentialsFile`), validated with `ProjectLinkFileSchema` and `ProjectCredentialsFileSchema`; a broken or newer file throws `ProjectFileError`. `@nylorun/core/transport` (browser-safe) holds the `/health` compatibility probe (`checkHealth`), `parseProtocolRange` (on `ProtocolRangeSchema`, ignoring fields a newer Host adds), `describeIncompatibility`, `requestHeaders` and `readBody`.
+  - `@nylorun/agents`: `resolveConnection` and `createClient()` find the Project as every reader does: the nearest directory with `.nylorun/` from `cwd` upwards, never the home directory or above it (they used to walk to the filesystem root, and past a `.nylorun/` without a link). A link without `credentials.json`, or a link or credentials file that does not validate, is now `connection_missing` naming the file and `npx nylorun start`, instead of a raw file-system or parse error. `@nylorun/agents/client` loads the link reader only when `createClient()` resolves a connection, so it imports no Node module. The root entry re-exports `checkHealth`, `describeIncompatibility` and `parseProtocolRange`.
+  - `@nylorun/admin`: `createAdmin` reads the Project link with the same reader. A link that does not validate is now refused like one from an older nylorun (when nothing else names the Host root), and a linked Project's `credentials.json` that does not validate is `connection_missing` instead of being skipped. `@nylorun/admin/project` re-exports `@nylorun/core/project` for tools that depend on this package. The `/health` check and request headers come from `@nylorun/core/transport`.
+  - `nylorun`: reads the Project link and credentials with `@nylorun/core/project`; a credentials file whose keys are not 64 hex characters is replaced by `start`, as an unreadable one was. No command changes.
+  - `@nylorun/cli`: `nylo` reads the Project root, link and credentials through `@nylorun/admin/project` instead of its own copies, with the same messages. No command changes.
+  - `@nylorun/studio`: the server's Runtime compatibility probe is `checkHealth` from `@nylorun/agents`.
+
+### Patch Changes
+
+- 070674d: **One source of truth for the manifest and Harness API schemas.**
+
+  - `@nylorun/core`: `Agent.from` (`agentFrom`) checks a manifest with `AgentManifestSchema`, the Runtime's own check, instead of a validator of its own, and refuses with `agent.build-failed` and the schema's messages (each prefixed with its path, such as `capabilities.0.tools.0.name: …`). It now refuses what the Runtime refuses at registration and it let through, such as unknown fields (it dropped them) or a tool or MCP server name that not every model provider accepts. The schema names a top-level `model` or `schemaVersion` and a capability's `model` as before, and the skill whose `files` are wrong (`Skill 'triage' files must include SKILL.md`). The rebuilt manifest is a frozen copy; the object passed in is no longer frozen. `AgentManifestSchema` and `WorkflowManifestSchema` are no longer force-cast to their types: the build checks that each accepts exactly `AgentManifest` and `WorkflowManifest`. `@nylorun/core/contracts` exports `McpServerManifestSchema`, `HEADER_NAME_PATTERN` and `LOOPBACK_HOSTS`. The Harness API's types (`@nylorun/core/harness-api`) are inferred from the schemas that validate its frames, so they match them: `TurnStart.manifest`, `TurnStart.checkpoint` and `RunRouting.rootManifest` are `object`, `WorkspaceCall.tool` is a sandbox tool name, `ABORT_REASONS` is a tuple, and properties are no longer `readonly` (arrays that were stay so).
+  - `@nylorun/harness`: `runDurable` checks the manifest once, when it rebuilds the agent, instead of twice. The unpublished, stale `schemas/manifest.schema.json` (manifest `schemaVersion` 2) is gone; `z.toJSONSchema(AgentManifestSchema)` is the manifest's JSON Schema.
+  - `@nylorun/agents`: a plugin's MCP servers are checked with core's `McpServerManifestSchema`, header-name pattern and loopback hosts. A server whose key is not a name every model provider accepts is skipped with a `plugin.mcp-server-skipped` warning, since the Runtime would refuse the manifest declaring it.
+  - `@nylorun/runtime`: the stack configuration reads its four listeners (`NYLORUN_LISTEN_*`, `NYLORUN_GATES_LISTEN_*`, `NYLORUN_HARNESS_LISTEN_*`, `NYLORUN_EGRESS_LISTEN_*`) with one parser; the variables and their errors are unchanged.
+
+- Pin core to the tested release.
+- Updated dependencies [7780b2f]
+- Updated dependencies [070674d]
+  - @nylorun/core@0.18.0-beta
+
 ## 0.18.0-beta
 
 ### Major Changes

package/README.md

@@ -86,9 +86,13 @@ only on the Runtime (a local `run()` reports `http.runtime-only`).
 2. Environment — if `NYLORUN_RUNTIME_URL` or `NYLORUN_SERVER_KEY` is set, both
    must be present
 3. Project link — `.nylorun/link.json` + `credentials.json` (the application
-   key), written by `npx nylorun start`. A link from an older nylorun
-   (format 0 to 2) fails with `connection_missing`: run `npx nylorun start` in
-   the project again.
+   key), written by `npx nylorun start`, in the nearest directory with
+   `.nylorun/` from `cwd` upwards (never the home directory or above it, whose
+   `.nylorun/` is the Nylorun home). A link from an older nylorun
+   (format 0 to 2), a link without credentials, or a file that does not
+   validate fails with `connection_missing`: run `npx nylorun start` in the
+   project again. The Project files are read by `@nylorun/core/project`, as
+   `@nylorun/admin`, `nylorun` and `nylo` read them.
 
 Sources never mix. Partial environment fails with `connection_missing`. A
 Runtime serves one Tenant, so nothing names it: the `tenant` option is gone

package/dist/client.d.ts

@@ -5,7 +5,8 @@ import type { Destination } from "./http.js";
  * Build a Tenant API client.
  * Explicit connection fields keep today's sync Transport resolution (including
  * environment fill-ins). With no connection fields, resolves via
- * `resolveConnection` (environment → project link).
+ * `resolveConnection` (environment → project link), which reads the Project's files: it is
+ * loaded only then, so this entry point imports no Node module (Studio's web bundle uses it).
  */
 export declare function createClient(destination: Destination): AgentsClient;
 export declare function createClient(destination?: undefined): Promise<AgentsClient>;

package/dist/client.js

@@ -1,13 +1,15 @@
 export * from "./session-client.js";
 import { AgentsClient } from "./session-client.js";
-import { resolveConnection } from "./connection.js";
 export function createClient(destination = {}) {
     if (destination.url !== undefined || destination.key !== undefined) {
         return new AgentsClient(destination);
     }
-    return resolveConnection().then((connection) => new AgentsClient({
-        url: connection.url,
-        key: connection.key,
-        ...(destination.fetch ? { fetch: destination.fetch } : {}),
-    }));
+    return import("./connection.js").then(async ({ resolveConnection }) => {
+        const connection = await resolveConnection();
+        return new AgentsClient({
+            url: connection.url,
+            key: connection.key,
+            ...(destination.fetch ? { fetch: destination.fetch } : {}),
+        });
+    });
 }

package/dist/connection.js

@@ -1,6 +1,4 @@
-import { readFile } from "node:fs/promises";
-import { dirname, join, resolve } from "node:path";
-import { ProjectCredentialsFileSchema, ProjectLinkFileSchema, } from "@nylorun/core/contracts";
+import { ProjectFileError, findLinkedProject } from "@nylorun/core/project";
 import { env } from "./http.js";
 export class ConnectionError extends Error {
     code = "connection_missing";
@@ -17,37 +15,31 @@ function missing(tried) {
 function stripTrailingSlash(url) {
     return url.replace(/\/$/, "");
 }
-async function readProjectLink(startDir) {
-    let dir = resolve(startDir);
-    for (;;) {
-        const nylorun = join(dir, ".nylorun");
-        const linkPath = join(nylorun, "link.json");
-        let linkRaw;
-        try {
-            linkRaw = await readFile(linkPath, "utf8");
-        }
-        catch (error) {
-            if (error.code === "ENOENT") {
-                const parent = dirname(dir);
-                if (parent === dir)
-                    return undefined;
-                dir = parent;
-                continue;
-            }
-            throw error;
-        }
-        const link = ProjectLinkFileSchema.parse(JSON.parse(linkRaw));
-        // Formats 0 to 2 are from older releases.
-        if (link.format < 3)
-            throw new ConnectionError(`connection_missing: the Project link at ${linkPath} is from an older nylorun. ` +
-                `Run "npx nylorun start" in this project to link it again.`);
-        const credentials = ProjectCredentialsFileSchema.parse(JSON.parse(await readFile(join(nylorun, "credentials.json"), "utf8")));
-        return {
-            url: stripTrailingSlash(link.hostUrl),
-            key: credentials.applicationKey,
-            source: "project-link",
-        };
+/** The application key of the linked Project from `cwd` upwards (`@nylorun/core/project`). */
+function readProjectLink(cwd) {
+    let project;
+    try {
+        project = findLinkedProject(cwd);
+    }
+    catch (error) {
+        if (error instanceof ProjectFileError)
+            throw new ConnectionError(`connection_missing: ${error.message}`);
+        throw error;
     }
+    if (!project)
+        return undefined;
+    // Formats 0 to 2 are from older releases.
+    if (project.link.format < 3)
+        throw new ConnectionError(`connection_missing: the Project link at ${project.linkPath} is from an older nylorun. ` +
+            `Run "npx nylorun start" in this project to link it again.`);
+    if (!project.credentials)
+        throw new ConnectionError(`connection_missing: the Project at ${project.root} has a link but no credentials ` +
+            `(.nylorun/credentials.json). Run "npx nylorun start" in this project to link it again.`);
+    return {
+        url: project.link.hostUrl,
+        key: project.credentials.applicationKey,
+        source: "project-link",
+    };
 }
 /**
  * Resolve Tenant API connection: options → environment → project link (D§7.1). A connection is a
@@ -83,7 +75,7 @@ export async function resolveConnection(options) {
     }
     tried.push("project-link");
     const cwd = options?.cwd ?? (typeof process !== "undefined" ? process.cwd() : ".");
-    const fromLink = await readProjectLink(cwd);
+    const fromLink = readProjectLink(cwd);
     if (fromLink)
         return fromLink;
     missing(tried);

package/dist/http.d.ts

@@ -1,4 +1,5 @@
-import { type Compatibility, type ProtocolRange } from "@nylorun/core/compatibility";
+import { type ProtocolRange } from "@nylorun/core/compatibility";
+import { type Incompatibility } from "@nylorun/core/transport";
 /**
  * Bearer tokens for a client that holds no Tenant key: a trusted issuer's tokens (Host feature
  * `trusted-issuers`), from the operator's identity provider. `get` returns a current token and
@@ -26,9 +27,7 @@ export declare class RuntimeError extends Error {
     readonly body: unknown;
     constructor(status: number, body: unknown);
 }
-export type IncompatibleReason = Extract<Compatibility, {
-    ok: false;
-}>;
+export type IncompatibleReason = Incompatibility;
 /** Host protocol is outside the client's supported range or missing required features. */
 export declare class IncompatibleRuntimeError extends Error {
     readonly compatibility: IncompatibleReason;

package/dist/http.js

@@ -1,4 +1,5 @@
-import { PROTOCOL_FEATURES, PROTOCOL_HEADER, PROTOCOL_VERSION, checkCompatibility, } from "@nylorun/core/compatibility";
+import { PROTOCOL_FEATURES, } from "@nylorun/core/compatibility";
+import { advertisedProtocol, checkHealth, clientCompatibility, describeIncompatibility, readBody, requestHeaders, } from "@nylorun/core/transport";
 export function env(name) {
     return typeof process !== "undefined" ? process.env[name] : undefined;
 }
@@ -18,10 +19,7 @@ export class IncompatibleRuntimeError extends Error {
     host;
     constructor(compatibility) {
         const remedy = remedyFor(compatibility);
-        const detail = compatibility.reason === "version"
-            ? `client protocol ${compatibility.client} is outside Host range ${compatibility.host.min}–${compatibility.host.max}`
-            : `Host is missing required features: ${compatibility.missing.join(", ")}`;
-        super(`Incompatible Runtime: ${detail}. ${remedy}`);
+        super(`Incompatible Runtime: ${describeIncompatibility(compatibility)}. ${remedy}`);
         this.name = "IncompatibleRuntimeError";
         this.compatibility = compatibility;
         this.remedy = remedy;
@@ -37,21 +35,6 @@ function remedyFor(compatibility) {
     }
     return "Upgrade the Runtime Host with nylorun runtime restart from a newer CLI, or install a matching older client (npm i -D @nylorun/cli@<compatible>).";
 }
-function parseProtocolRange(value) {
-    if (!value || typeof value !== "object" || Array.isArray(value))
-        return undefined;
-    const record = value;
-    if (typeof record.min !== "number" ||
-        typeof record.max !== "number" ||
-        !Array.isArray(record.features) ||
-        !record.features.every((f) => typeof f === "string"))
-        return undefined;
-    return {
-        min: record.min,
-        max: record.max,
-        features: record.features,
-    };
-}
 export class Transport {
     url;
     /** The Tenant key; empty for a client that uses issuer tokens. */
@@ -99,36 +82,23 @@ export class Transport {
     async ensureCompatible(signal) {
         if (this.check.compatible)
             return;
-        const response = await this.fetcher(`${this.url}/health`, {
-            method: "GET",
-            redirect: "error",
-            signal,
+        const health = await checkHealth(this.url, {
+            fetch: this.fetcher,
+            ...(signal ? { signal } : {}),
         });
-        const text = await response.text();
-        let body = text;
-        try {
-            body = JSON.parse(text);
-        }
-        catch {
-            /* keep text */
-        }
-        if (!response.ok)
-            throw new RuntimeError(response.status, body);
-        const protocol = parseProtocolRange(body && typeof body === "object" && !Array.isArray(body)
-            ? body.protocol
-            : undefined);
-        if (!protocol)
+        if (health.result === "failed")
+            throw new RuntimeError(health.status, health.body);
+        if (health.result === "unadvertised")
             throw new IncompatibleRuntimeError({
                 ok: false,
                 reason: "feature",
                 missing: [...PROTOCOL_FEATURES],
                 host: { min: 0, max: 0, features: [] },
             });
-        const result = checkCompatibility({ version: PROTOCOL_VERSION, required: [...PROTOCOL_FEATURES] }, protocol);
-        if (!result.ok)
-            throw new IncompatibleRuntimeError(result);
-        this.check.features = [...protocol.features];
-        this.check.range = protocol;
+        if (health.result === "incompatible")
+            throw new IncompatibleRuntimeError(health.compatibility);
+        this.check.features = [...health.protocol.features];
+        this.check.range = health.protocol;
         this.check.compatible = true;
     }
     /** Throws `IncompatibleRuntimeError` before anything is sent when the Host lacks `feature`. */
@@ -154,8 +124,8 @@ export class Transport {
         const bearer = this.token
             ? await this.token.get(init.signal ?? undefined)
             : this.key;
-        headers.set("Authorization", `Bearer ${bearer}`);
-        headers.set(PROTOCOL_HEADER, String(PROTOCOL_VERSION));
+        for (const [name, value] of Object.entries(requestHeaders(bearer)))
+            headers.set(name, value);
         // JSON unless the caller says otherwise (an artifact upload sends the file's type).
         if (init.body && !headers.has("content-type"))
             headers.set("Content-Type", "application/json");
@@ -183,35 +153,17 @@ export class Transport {
                 await this.ensureCompatible(init.signal === null ? undefined : init.signal);
                 return this.request(path, init, { retried426: true });
             }
-            const text = await response.text();
-            let body = text;
-            try {
-                body = JSON.parse(text);
-            }
-            catch {
-                /* keep text */
-            }
-            const protocol = parseProtocolRange(body && typeof body === "object" && !Array.isArray(body)
-                ? body.protocol
-                : undefined);
+            const body = await readBody(response);
+            const protocol = advertisedProtocol(body);
             if (protocol) {
-                const result = checkCompatibility({ version: PROTOCOL_VERSION, required: [...PROTOCOL_FEATURES] }, protocol);
+                const result = clientCompatibility(protocol);
                 if (!result.ok)
                     throw new IncompatibleRuntimeError(result);
             }
             throw new RuntimeError(426, body);
         }
-        if (!response.ok) {
-            const text = await response.text();
-            let body = text;
-            try {
-                body = JSON.parse(text);
-            }
-            catch {
-                /* keep text */
-            }
-            throw new RuntimeError(response.status, body);
-        }
+        if (!response.ok)
+            throw new RuntimeError(response.status, await readBody(response));
         return response;
     }
     /**

package/dist/index.d.ts

@@ -1,5 +1,7 @@
 export { hashManifest, PROTOCOL_VERSION, PROTOCOL_FEATURES, HOST_PROTOCOL, DEFINITION_SCHEMA_VERSION, PROTOCOL_HEADER, SUBJECT_HEADER, SCOPES_HEADER, SESSION_ID_HEADER, TURN_ID_HEADER, AGENT_ID_HEADER, TENANT_ID_PATTERN, isTenantId, newTenantId, newPrincipalId, checkCompatibility, compareVersions, ERROR_CODES, } from "@nylorun/core/compatibility";
 export type { ProtocolFeature, ProtocolRange, Compatibility, ErrorCode, } from "@nylorun/core/compatibility";
+export { checkHealth, describeIncompatibility, parseProtocolRange, } from "@nylorun/core/transport";
+export type { HealthCheck, Incompatibility } from "@nylorun/core/transport";
 export { Agent, AgentBuilder } from "./builder.js";
 export { AgentBuildError, AgentLifecycleError, VerdictSchema, isVerdict, WorkflowBuildError, isBuiltWorkflow, capability, CapabilityBuilder, flow, tool, http, defineSchema, ToolError, } from "@nylorun/core/define";
 export type { FlowAgentBuilder, Flow, Named, LoopOptions, StageOptions, CapabilityIdentity, HttpTarget, } from "@nylorun/core/define";

package/dist/index.js

@@ -1,5 +1,7 @@
 // Definition authoring and wire contracts are the only harness runtime imports.
 export { hashManifest, PROTOCOL_VERSION, PROTOCOL_FEATURES, HOST_PROTOCOL, DEFINITION_SCHEMA_VERSION, PROTOCOL_HEADER, SUBJECT_HEADER, SCOPES_HEADER, SESSION_ID_HEADER, TURN_ID_HEADER, AGENT_ID_HEADER, TENANT_ID_PATTERN, isTenantId, newTenantId, newPrincipalId, checkCompatibility, compareVersions, ERROR_CODES, } from "@nylorun/core/compatibility";
+// The `/health` compatibility probe every Runtime client shares (Studio's server uses it).
+export { checkHealth, describeIncompatibility, parseProtocolRange, } from "@nylorun/core/transport";
 export { Agent, AgentBuilder } from "./builder.js";
 export { AgentBuildError, AgentLifecycleError, VerdictSchema, isVerdict, WorkflowBuildError, isBuiltWorkflow, capability, CapabilityBuilder, flow, tool, http, defineSchema, ToolError, } from "@nylorun/core/define";
 export { SUBJECT_SCOPES } from "@nylorun/core/contracts";

package/dist/plugins/load.js

@@ -1,6 +1,7 @@
 import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
 import { isAbsolute, join, relative, resolve, sep } from "node:path";
 import { stdioMcpRefusal } from "@nylorun/core/define";
+import { HEADER_NAME_PATTERN, LOOPBACK_HOSTS, McpServerManifestSchema, } from "@nylorun/core/contracts";
 import { loadSkillsFromDirectory } from "../skills/load.js";
 export const PLUGIN_SCHEMA = "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json";
 export const MCP_SCHEMA = "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json";
@@ -211,38 +212,34 @@ function validateServer(name, value) {
         return validateRemote(name, value);
     return `type '${value.type}' is not streamable-http or sse`;
 }
+/**
+ * A plugin's server as a manifest declares it (`McpServerManifestSchema`), named by its key. A
+ * plugin may set only type, url and headers, and the URL and headers must be fit to send.
+ */
 function validateRemote(name, value) {
     const allowed = new Set(["type", "url", "headers"]);
     const unknown = Object.keys(value).filter((key) => !allowed.has(key));
     if (unknown.length > 0)
         return `${value.type} servers take only type, url and headers, not ${unknown.join(", ")}`;
-    if (typeof value.url !== "string")
-        return "url must be a string";
-    const problem = remoteUrlProblem(value.url);
+    const parsed = McpServerManifestSchema.safeParse({ ...value, name });
+    if (!parsed.success)
+        return parsed.error.issues
+            .map((issue) => (issue.path.length ? `${issue.path.join(".")}: ${issue.message}` : issue.message))
+            .join("; ");
+    const server = parsed.data;
+    const problem = remoteUrlProblem(server.url);
     if (problem)
         return problem;
-    let headers;
-    if (value.headers !== undefined) {
-        if (!isRecord(value.headers))
-            return "headers must be an object";
-        const seen = new Set();
-        headers = {};
-        for (const [key, item] of Object.entries(value.headers)) {
-            if (typeof item !== "string" || !isHeaderName(key) || /[\r\n\0]/.test(item))
-                return `header '${key}' is not a valid header`;
-            const folded = key.toLowerCase();
-            if (seen.has(folded))
-                return `header '${key}' is repeated`;
-            seen.add(folded);
-            headers[key] = item;
-        }
+    const seen = new Set();
+    for (const [key, item] of Object.entries(server.headers ?? {})) {
+        if (!HEADER_NAME_PATTERN.test(key) || /[\r\n\0]/.test(item))
+            return `header '${key}' is not a valid header`;
+        const folded = key.toLowerCase();
+        if (seen.has(folded))
+            return `header '${key}' is repeated`;
+        seen.add(folded);
     }
-    return {
-        name,
-        type: value.type,
-        url: value.url,
-        ...(headers === undefined ? {} : { headers }),
-    };
+    return server;
 }
 /**
  * Why `value` is not a remote server URL: https, or plain http to this machine's loopback (a
@@ -264,22 +261,10 @@ function remoteUrlProblem(value) {
         return undefined;
     if (url.protocol !== "http:")
         return `url must be https, not ${url.protocol.slice(0, -1)}`;
-    if (isLoopback(url.hostname))
+    if (LOOPBACK_HOSTS.test(url.hostname))
         return undefined;
     return `plain http is allowed only for localhost, 127.0.0.1 or [::1]; use https for ${url.hostname}`;
 }
-function isLoopback(hostname) {
-    const host = hostname.replace(/^\[|\]$/g, "");
-    if (host === "localhost" || host === "::1")
-        return true;
-    const match = /^127\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(host);
-    if (!match)
-        return false;
-    return match.slice(1).every((part) => Number(part) <= 255);
-}
-function isHeaderName(name) {
-    return /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/.test(name);
-}
 function isPluginName(value) {
     if (typeof value !== "string" || value.length < 1 || value.length > 64)
         return false;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nylorun/agents",
-  "version": "0.18.0-beta",
+  "version": "0.19.1-beta",
   "description": "Nylorun agent definitions and session client",
   "type": "module",
   "license": "Apache-2.0",
@@ -43,7 +43,7 @@
     "test": "vitest run --passWithNoTests"
   },
   "dependencies": {
-    "@nylorun/core": "0.17.0-beta",
+    "@nylorun/core": "0.19.0-beta",
     "gray-matter": "^4.0.3"
   },
   "peerDependencies": {