@nylorun/agents 0.20.0-beta → 0.21.0-beta

package/dist/environments.js

@@ -1,16 +1,20 @@
 /**
  * Environments (protocol 11, D55, D56): `client.environments`. An Environment is one sandbox
- * (kind `virtual`, `pod` or `none`) with a recipe that can change, and one vault of secrets for
- * its shell, MCP servers and HTTP tools. It has its own id and outlives the sessions that name
- * it; whether it serves one session, one person or a project is the app's choice, made here:
+ * (kind `virtual`, `pod` or `none`) made from an environment manifest's version or from inline
+ * fields, and one vault of secrets for its shell, MCP servers and HTTP tools. It never changes
+ * what it runs after it is made (protocol 14, D63): a new version reaches an agent through a new
+ * Environment. It has its own id and outlives the sessions that name it; whether it serves one
+ * session, one person or a project is the app's choice, made here:
  *
  * - `environments.forSession(...)`: one Environment for one session. It creates the
  *   Environment, opens the session on it, and `release()` deletes the Environment (and its
  *   vault) when the session is done.
- * - `environments.put(id, recipe)`: one Environment per person or per project, by a
- *   deterministic id (`users/alice/web`); get-or-create, or change its recipe, in one call.
- *   Write its secrets with `environments.secrets.put(id, name, secret)` and open sessions on it
- *   with `createSession({ environment: id })`.
+ * - `environments.put(id, { manifest: "analyst-box" })` (or inline fields): one Environment per
+ *   person or per project, by a deterministic id (`users/alice/web`); get-or-create in one call.
+ *   Write its secrets with `environments.secrets.put(id, name, { value })` and open sessions on
+ *   it with `createSession({ environment: id })`.
+ * - `environments.manifests.save(manifest)`: save an environment manifest's next version, like
+ *   `saveAgent`; `plan(manifest)` answers what a save would do and saves nothing.
  *
  * Ids may hold `/`; they are sent percent-encoded as one path segment. Secret values are
  * write-only: no call reads one back.
@@ -18,9 +22,22 @@
  * Disk versions (Host feature `environment-disk-versions`): `snapshot(id)` keeps a version of
  * the Environment's disk between turns, `restore(id, version)` puts one back, and
  * `put(id, { from: { environment, version } })` creates a new Environment from another's version.
+ *
+ * `fork(id, { id: next })` is how an Environment gets a new manifest version (Q15): a new
+ * Environment made from it, with the source's disk and secrets; `planFork` answers what it would do.
  */
-import { EnvironmentPageSchema, isEnvironmentId, } from "@nylorun/core/contracts";
+import { ENVIRONMENT_MANIFEST_SCHEMA_VERSION, EnvironmentManifestSchema, EnvironmentPageSchema, isEnvironmentId, isEnvironmentManifestName, } from "@nylorun/core/contracts";
+import { definitionFileHash, FilesClient } from "./files.js";
 import { id, segment } from "./http.js";
+/**
+ * An environment manifest (protocol 14, D63): checked now against the schema the Runtime
+ * enforces, with `manifestSchemaVersion` filled in and `$schema` dropped. Save it with
+ * `client.environments.manifests.save()`, or make an Environment from it inline.
+ */
+export function environmentManifest(input) {
+    const { $schema: _, ...rest } = input;
+    return EnvironmentManifestSchema.parse({ manifestSchemaVersion: ENVIRONMENT_MANIFEST_SCHEMA_VERSION, ...rest });
+}
 /** An Environment's secrets: `client.environments.secrets`. */
 export class EnvironmentSecretsClient {
     transport;
@@ -32,7 +49,9 @@ export class EnvironmentSecretsClient {
     /**
      * Creates or replaces secret `name` (`PUT /v1/environments/{id}/secrets/{name}`): for
      * `environment_secret` and `environment_variable` the name is the variable's. A second
-     * credential for a host or a URL is a 409 `credential_conflict`.
+     * credential for a host or a URL is a 409 `credential_conflict`. When what the Environment
+     * runs declares the secret's slot (D64), send only `{ value }` (or `{ headers }`); a name it
+     * does not declare is `409 secret_not_in_manifest`.
      */
     async put(environmentId, name, secret, options = {}) {
         return this.transport.json(`${this.path(environmentId)}/secrets/${segment(name)}`, "PUT", { requestId: id(), ...secret }, options.signal);
@@ -49,6 +68,71 @@ export class EnvironmentSecretsClient {
         return this.transport.json(`${this.path(environmentId)}/secrets/${segment(name)}`, "DELETE", undefined, options.signal);
     }
 }
+/**
+ * A manifest `files` entry by content hash (Q6): `contents` (each file's path under `path` and
+ * its bytes or text) hashed, as `entry` for the manifest and `bytes` for `manifests.save`'s
+ * `files`, which uploads them. Each file holds at most 10 MiB.
+ */
+export async function environmentFiles(path, contents) {
+    const files = {};
+    const bytes = {};
+    for (const [name, content] of Object.entries(contents).sort(([a], [b]) => a.localeCompare(b))) {
+        const data = typeof content === "string" ? new TextEncoder().encode(content) : content;
+        const sha256 = await definitionFileHash(data);
+        files[name] = sha256;
+        bytes[sha256] = data;
+    }
+    return { entry: { path, files }, bytes };
+}
+export class EnvironmentManifestsClient {
+    transport;
+    constructor(transport) {
+        this.transport = transport;
+    }
+    path(name) {
+        if (!isEnvironmentManifestName(name))
+            throw new TypeError(`${name} is not an environment manifest's name: 1-64 letters, digits, '.', '_' and '-'`);
+        return `/v1/environment-manifests/${segment(name)}`;
+    }
+    async send(manifest, query, options) {
+        const { ifMatch, signal } = options;
+        const body = environmentManifest(manifest);
+        // Its files by hash (Q6): uploaded first, each only when the Runtime does not hold it.
+        if (options.files)
+            await new FilesClient(this.transport).ensure(new Map(Object.entries(options.files).map(([sha256, bytes]) => [sha256, { size: bytes.byteLength, read: async () => bytes }])), signal ? { signal } : {});
+        const transport = ifMatch === undefined ? this.transport : this.transport.withHeaders({ "If-Match": String(ifMatch) });
+        return transport.json(`${this.path(body.name)}${query}`, "PUT", { requestId: id(), ...body }, signal);
+    }
+    /**
+     * Saves `manifest` (`PUT /v1/environment-manifests/{name}`). `ifMatch`: the version you read
+     * (`0` for none yet); a save over a newer one is `412 manifest_changed`. `files`: the bytes of
+     * its files by hash (`environmentFiles(...).bytes`), uploaded first when the Runtime lacks them.
+     */
+    async save(manifest, options = {}) {
+        return this.send(manifest, "", options);
+    }
+    /** What saving `manifest` would do (`?dryRun=true`): changes, errors, warnings, and the Environments behind. */
+    async plan(manifest, options = {}) {
+        return this.send(manifest, "?dryRun=true", options);
+    }
+    /** The latest version of manifest `name`, or version `version`. */
+    async get(name, options = {}) {
+        return this.transport.json(`${this.path(name)}${options.version === undefined ? "" : `/versions/${options.version}`}`, "GET", undefined, options.signal);
+    }
+    /** Each manifest's latest version. */
+    async list(options = {}) {
+        const reply = await this.transport.json("/v1/environment-manifests", "GET", undefined, options.signal);
+        return reply.manifests;
+    }
+    /** Every version of manifest `name`, newest first. */
+    async versions(name, options = {}) {
+        return this.transport.json(`${this.path(name)}/versions`, "GET", undefined, options.signal);
+    }
+    /** Deletes every version; refused while an Environment was made from one (`409 manifest_in_use`). */
+    async delete(name, options = {}) {
+        return this.transport.json(this.path(name), "DELETE", undefined, options.signal);
+    }
+}
 export class EnvironmentsClient {
     transport;
     createSession;
@@ -67,11 +151,17 @@ export class EnvironmentsClient {
     get secrets() {
         return new EnvironmentSecretsClient(this.transport, (environmentId) => this.path(environmentId));
     }
+    /** Environment manifests (protocol 14, D63): named, versioned definitions of a kind of Environment. */
+    get manifests() {
+        return new EnvironmentManifestsClient(this.transport);
+    }
     /**
      * Creates the Environment and its vault, or finds the one with this id
-     * (`PUT /v1/environments/{id}`). On an existing one, `kind` and `storage` are fixed (a
-     * different one is a 409), labels replace, and any other change writes the recipe and bumps
-     * its `version`: a pod's image and resources apply when it next starts from stopped.
+     * (`PUT /v1/environments/{id}`), from an environment manifest (`{ manifest: "name" }` takes
+     * the latest version, `"name@n"` version n) or from inline fields. It never changes what it
+     * runs after that (protocol 14): on an existing one, labels replace and `ownerUserId` sets or
+     * clears the owner guard, fields that match are accepted, and anything else is
+     * `409 environment_immutable`.
      */
     async put(environmentId, recipe = {}, options = {}) {
         return this.transport.json(this.path(environmentId), "PUT", { requestId: id(), ...recipe }, options.signal);
@@ -121,6 +211,26 @@ export class EnvironmentsClient {
         await this.transport.requireFeature("environment-disk-versions", options.signal);
         return this.transport.json(`${this.path(environmentId)}/restore`, "POST", { requestId: id(), version }, options.signal);
     }
+    /**
+     * Forks the Environment into a new one, `options.id` (Q15): how an Environment gets a new
+     * manifest version, since none ever changes what it runs. It is made from `options.manifest`
+     * (default the source's manifest at its latest version), its disk starts from `options.disk`
+     * (`latest`, the default, snapshots first; a version; or `empty`) and the secrets the new
+     * manifest declares are copied (`options.secrets: "none"` copies none). The source keeps what
+     * it runs, its disk and its sessions. Answers the new Environment and the plan it ran.
+     */
+    async fork(environmentId, options) {
+        const { signal, ...body } = options;
+        await this.transport.requireFeature("environment-manifests", signal);
+        return this.transport.json(`${this.path(environmentId)}/fork`, "POST", { requestId: id(), ...body }, signal);
+    }
+    /** What `fork` would do (the disk, the secrets copied and left behind, the changes), making nothing. */
+    async planFork(environmentId, options) {
+        const { signal, ...body } = options;
+        await this.transport.requireFeature("environment-manifests", signal);
+        const answer = await this.transport.json(`${this.path(environmentId)}/fork`, "POST", { ...body, dryRun: true }, signal);
+        return answer.plan;
+    }
     /** The Environment's disk versions, newest first. */
     async versions(environmentId, options = {}) {
         await this.transport.requireFeature("environment-disk-versions", options.signal);
@@ -134,9 +244,24 @@ export class EnvironmentsClient {
     async delete(environmentId, options = {}) {
         return this.transport.json(this.path(environmentId), "DELETE", undefined, options.signal);
     }
-    /** The Environment's lifecycle events, from `from` on. */
+    /**
+     * The Environment's events, from `from` on: its lifecycle, and `environment.egress` for every
+     * connection its sandbox opens (with the turns that were running). `types` keeps only those
+     * types; `since` and `until` keep events recorded in that window (ISO times or `Date`s).
+     */
     async events(environmentId, options = {}) {
-        const reply = await this.transport.json(`${this.path(environmentId)}/events${options.from === undefined ? "" : `?from=${options.from}`}`, "GET", undefined, options.signal);
+        const query = new URLSearchParams();
+        if (options.from !== undefined)
+            query.set("from", String(options.from));
+        if (options.types !== undefined && options.types.length > 0)
+            query.set("types", options.types.join(","));
+        const iso = (at) => (at instanceof Date ? at.toISOString() : at);
+        if (options.since !== undefined)
+            query.set("since", iso(options.since));
+        if (options.until !== undefined)
+            query.set("until", iso(options.until));
+        const search = query.toString();
+        const reply = await this.transport.json(`${this.path(environmentId)}/events${search === "" ? "" : `?${search}`}`, "GET", undefined, options.signal);
         return reply.events;
     }
     /**

package/dist/http.js

@@ -28,12 +28,12 @@ export class IncompatibleRuntimeError extends Error {
 }
 function remedyFor(compatibility) {
     if (compatibility.reason === "feature") {
-        return "Upgrade the Runtime Host (nylorun runtime restart from a newer CLI) so it advertises the required features.";
+        return "Upgrade the Runtime so it advertises the required features (a local Tenant: npx nylorun@latest start).";
     }
     if (compatibility.client < compatibility.host.min) {
         return "Upgrade this client (npm i -D @nylorun/agents@latest) or use a CLI that matches the Host protocol.";
     }
-    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>).";
+    return "Upgrade the Runtime (a local Tenant: npx nylorun@latest start), or install a matching older client (npm i -D @nylorun/agents@<compatible>).";
 }
 export class Transport {
     url;

package/dist/index.d.ts

@@ -3,28 +3,26 @@ export type { ProtocolFeature, ProtocolRange, Compatibility, ErrorCode, } from "
 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";
+export { AgentBuildError, AgentLifecycleError, VerdictSchema, isVerdict, WorkflowBuildError, isBuiltWorkflow, flow, tool, http, defineSchema, ToolError, } from "@nylorun/core/define";
+export type { FlowAgentBuilder, Flow, Named, LoopOptions, StageOptions, HttpTarget, } from "@nylorun/core/define";
 export type { AgentOptions, AgentManifest, BuiltAgent, BuiltWorkflow, Verdict, WorkflowBinding, WorkflowManifest, ToolDefinition, ToolExecutionContext, ToolOutcome, JsonValue, JsonObject, } from "@nylorun/core/define";
-export type { SessionPage, SessionListItem, SessionManifestView, HistoryPage, SessionUsageTotals, ModelCall, ModelCallsPage, EnvironmentPage, ToolCall, ToolCallsPage, LiveEvent, SessionEvent, SessionEventOf, EventType, SessionCommand, SubjectScope, EnvironmentView, EnvironmentEvent, EnvironmentKind, EnvironmentRecipe, EnvironmentSecretView, EnvironmentSnapshot, EnvironmentRestore, EnvironmentVersions, RestoreEnvironmentRequest, MessagePart, ArtifactView, ArtifactKind, ArtifactListItem, ArtifactPage, ArtifactVersionView, ArtifactLink, UploadArtifactResponse, DefinitionFileView, ArtifactTree, ArtifactDiff, FolderEntry, } from "@nylorun/core/contracts";
-export { SUBJECT_SCOPES } from "@nylorun/core/contracts";
+export type { SessionPage, SessionListItem, SessionManifestView, HistoryPage, SessionUsageTotals, ModelCall, ModelCallsPage, EnvironmentPage, ToolCall, ToolCallsPage, LiveEvent, SessionEvent, SessionEventOf, EventType, SessionCommand, SubjectScope, EnvironmentView, EnvironmentEvent, EnvironmentEventType, EgressRunningTurn, EnvironmentKind, EnvironmentRecipe, EnvironmentSecretView, EnvironmentSnapshot, EnvironmentRestore, EnvironmentVersions, RestoreEnvironmentRequest, EnvironmentForkPlan, ForkEnvironmentRequest, ForkEnvironmentResponse, EnvironmentManifest, EnvironmentManifestPlan, EnvironmentManifestView, EnvironmentManifestVersions, SaveEnvironmentManifestResponse, MessagePart, ArtifactView, ArtifactKind, ArtifactListItem, ArtifactPage, ArtifactVersionView, ArtifactLink, UploadArtifactResponse, DefinitionFileView, ArtifactTree, ArtifactDiff, FolderEntry, } from "@nylorun/core/contracts";
+export { ENVIRONMENT_EVENT_TYPES, SUBJECT_SCOPES } from "@nylorun/core/contracts";
 export { AgentsClient, SessionClient, createClient } from "./client.js";
 export { ArtifactsClient } from "./artifacts.js";
 export { FilesClient, definitionFileHash } from "./files.js";
 export type { ArtifactBody, ArtifactPageOptions, ArtifactLinkWithUrl, UploadArtifactOptions, } from "./artifacts.js";
-export type { ActAsOptions, AgentSource, SessionView, CommandOptions, CreateSessionOptions, SessionSandbox, ForSessionOptions, EnvironmentRecipeInput, EnvironmentSecretInput, SessionEnvironmentHandle, } from "./client.js";
-export { EnvironmentsClient, EnvironmentSecretsClient } from "./client.js";
+export type { ActAsOptions, AgentSource, SessionView, CommandOptions, CreateSessionOptions, SessionSandbox, ForSessionOptions, EnvironmentFileBytes, EnvironmentInput, EnvironmentManifestInput, EnvironmentSecretInput, SessionEnvironmentHandle, } from "./client.js";
+export { EnvironmentManifestsClient, EnvironmentsClient, EnvironmentSecretsClient, environmentFiles, environmentManifest, } from "./client.js";
 export { AccessClient } from "./access.js";
 export { resolveConnection, ConnectionError } from "./connection.js";
 export type { ResolvedConnection } from "./connection.js";
 export { RuntimeError, IncompatibleRuntimeError } from "./http.js";
 export type { Destination, IncompatibleReason, TokenSource } from "./http.js";
-export { plugin } from "./plugins/plugin.js";
-export type { PluginCapability } from "./plugins/plugin.js";
 export { loadPlugin, PluginError } from "./plugins/load.js";
 export type { LoadedPlugin, PluginDiagnostic } from "./plugins/load.js";
-export { skills, loadSkillsFromDirectory, resolveSkillsRoot, parseSkill, SkillsError, formatSkillCatalog, SKILLS_USAGE, } from "./skills/index.js";
-export type { SkillsCapability, SkillsOptions, SkillDiagnostic, } from "./skills/index.js";
-export { mcp, McpError } from "./mcp/index.js";
-export type { McpCapability, McpOptions, McpServerSpec } from "./mcp/index.js";
+export { loadSkillsFromDirectory, resolveSkillsRoot, parseSkill, SkillsError, formatSkillCatalog, SKILLS_USAGE, } from "./skills/index.js";
+export type { SkillDiagnostic } from "./skills/index.js";
+export { McpError } from "./mcp/index.js";
+export type { McpServerSpec } from "./mcp/index.js";
 export type { SessionPageOptions } from "./reads.js";

package/dist/index.js

@@ -3,16 +3,15 @@ export { hashManifest, PROTOCOL_VERSION, PROTOCOL_FEATURES, HOST_PROTOCOL, DEFIN
 // 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";
+export { AgentBuildError, AgentLifecycleError, VerdictSchema, isVerdict, WorkflowBuildError, isBuiltWorkflow, flow, tool, http, defineSchema, ToolError, } from "@nylorun/core/define";
+export { ENVIRONMENT_EVENT_TYPES, SUBJECT_SCOPES } from "@nylorun/core/contracts";
 export { AgentsClient, SessionClient, createClient } from "./client.js";
 export { ArtifactsClient } from "./artifacts.js";
 export { FilesClient, definitionFileHash } from "./files.js";
-export { EnvironmentsClient, EnvironmentSecretsClient } from "./client.js";
+export { EnvironmentManifestsClient, EnvironmentsClient, EnvironmentSecretsClient, environmentFiles, environmentManifest, } from "./client.js";
 export { AccessClient } from "./access.js";
 export { resolveConnection, ConnectionError } from "./connection.js";
 export { RuntimeError, IncompatibleRuntimeError } from "./http.js";
-export { plugin } from "./plugins/plugin.js";
 export { loadPlugin, PluginError } from "./plugins/load.js";
-export { skills, loadSkillsFromDirectory, resolveSkillsRoot, parseSkill, SkillsError, formatSkillCatalog, SKILLS_USAGE, } from "./skills/index.js";
-export { mcp, McpError } from "./mcp/index.js";
+export { loadSkillsFromDirectory, resolveSkillsRoot, parseSkill, SkillsError, formatSkillCatalog, SKILLS_USAGE, } from "./skills/index.js";
+export { McpError } from "./mcp/index.js";

package/dist/mcp/index.d.ts

@@ -1,2 +1,2 @@
-export { mcp, McpError, normalizeMcpServers } from "@nylorun/core/define";
-export type { McpCapability, McpOptions, McpServerSpec } from "@nylorun/core/define";
+export { McpError, normalizeMcpServers } from "@nylorun/core/define";
+export type { McpServerSpec } from "@nylorun/core/define";

package/dist/mcp/index.js

@@ -1 +1 @@
-export { mcp, McpError, normalizeMcpServers } from "@nylorun/core/define";
+export { McpError, normalizeMcpServers } from "@nylorun/core/define";

package/dist/plugins/load.d.ts

@@ -16,6 +16,7 @@ export declare class PluginError extends Error {
 export interface LoadedPlugin {
     readonly root: string;
     readonly name: string;
+    readonly version?: string;
     readonly description?: string;
     readonly skills: Readonly<Record<string, LoadedSkill>>;
     readonly mcpServers: Readonly<Record<string, McpServerManifest>>;

package/dist/plugins/load.js

@@ -80,6 +80,7 @@ export function loadPlugin(directory) {
     return {
         root,
         name: parsed.name,
+        ...(typeof parsed.version === "string" ? { version: parsed.version } : {}),
         ...(typeof parsed.description === "string" ? { description: parsed.description } : {}),
         skills,
         mcpServers,

package/dist/plugins/plugin.d.ts

@@ -1,13 +1,17 @@
-import type { CapabilityDeclaration } from "@nylorun/core/define";
+import type { PartDeclaration } from "@nylorun/core/define";
 import { type LoadedPlugin, type PluginDiagnostic } from "./load.js";
-export interface PluginCapability extends CapabilityDeclaration {
+export interface PluginPart extends PartDeclaration {
     readonly diagnostics: readonly PluginDiagnostic[];
 }
 /**
- * Read an Agent Plugin package and return one capability for `Agent.use`. Each part it skips
+ * Read an Agent Plugin package as one part of an agent, for `.plugin()`. Each part it skips
  * (an invalid MCP server or skill) is a process warning, so building or registering the agent
  * says why the agent has less than the package declares. A stdio MCP server throws: Nylorun
  * accepts remote servers only.
  */
-export declare function plugin(directory: string): PluginCapability;
-export declare function capabilityFromPlugin(loaded: LoadedPlugin): PluginCapability;
+export declare function plugin(directory: string): PluginPart;
+/**
+ * The part a plugin adds: its skills and remote MCP servers, each labelled with the plugin's name
+ * and version. The plugin itself is not in the manifest; the labels say where each part came from.
+ */
+export declare function partFromPlugin(loaded: LoadedPlugin): PluginPart;

package/dist/plugins/plugin.js

@@ -1,8 +1,7 @@
-import { formatSkillCatalog, SKILLS_USAGE } from "../skills/catalog.js";
 import { skillsDeclaration } from "../skills/skills.js";
 import { loadPlugin, } from "./load.js";
 /**
- * Read an Agent Plugin package and return one capability for `Agent.use`. Each part it skips
+ * Read an Agent Plugin package as one part of an agent, for `.plugin()`. Each part it skips
  * (an invalid MCP server or skill) is a process warning, so building or registering the agent
  * says why the agent has less than the package declares. A stdio MCP server throws: Nylorun
  * accepts remote servers only.
@@ -10,7 +9,7 @@ import { loadPlugin, } from "./load.js";
 export function plugin(directory) {
     const loaded = loadPlugin(directory);
     warn(loaded);
-    return capabilityFromPlugin(loaded);
+    return partFromPlugin(loaded);
 }
 function warn(loaded) {
     for (const diagnostic of loaded.diagnostics) {
@@ -23,26 +22,25 @@ function warn(loaded) {
         });
     }
 }
-export function capabilityFromPlugin(loaded) {
-    const names = Object.values(loaded.skills);
-    const instructions = names.length === 0
-        ? undefined
-        : [
-            SKILLS_USAGE,
-            formatSkillCatalog(names.map((skill) => ({
-                name: skill.name,
-                description: skill.description,
-            }))),
-        ];
+/**
+ * The part a plugin adds: its skills and remote MCP servers, each labelled with the plugin's name
+ * and version. The plugin itself is not in the manifest; the labels say where each part came from.
+ */
+export function partFromPlugin(loaded) {
+    const label = {
+        name: loaded.name,
+        ...(loaded.version === undefined ? {} : { version: loaded.version }),
+    };
+    const skills = Object.values(loaded.skills);
+    const servers = Object.entries(loaded.mcpServers);
     return {
-        id: loaded.name,
-        type: "agent-plugin",
-        ...(loaded.description === undefined ? {} : { description: loaded.description }),
-        ...(instructions === undefined ? {} : { instructions }),
-        ...(names.length === 0 ? {} : skillsDeclaration(names)),
-        ...(Object.keys(loaded.mcpServers).length === 0
+        id: `plugin:${loaded.name}`,
+        ...(skills.length === 0 ? {} : skillsDeclaration(skills, label)),
+        ...(servers.length === 0
             ? {}
-            : { mcpServers: loaded.mcpServers }),
+            : {
+                mcpServers: Object.fromEntries(servers.map(([name, server]) => [name, { ...server, plugin: label }])),
+            }),
         diagnostics: loaded.diagnostics,
     };
 }

package/dist/session-client.d.ts

@@ -20,8 +20,6 @@ export interface AgentSource {
     build?(): BuiltAgent | BuiltWorkflow;
     getBinding?: BuiltAgent["getBinding"] | BuiltWorkflow["getBinding"];
 }
-/** Closures stay on the live binding. The published manifest cannot name them. */
-export declare function assertNoMiddlewareClosures(agent: AgentSource): void;
 export interface SessionView {
     id: string;
     agentId: string;
@@ -96,11 +94,13 @@ export declare class AgentsClient {
      * it names that the Runtime does not hold. A definition with a tool that runs your code
      * (`tool({ run })`, a flow's tool stage) is refused before anything is sent: the Runtime runs
      * agents from their manifests alone. `implementationVersion` defaults to
-     * `NYLORUN_IMPLEMENTATION_VERSION`, else `dev`.
+     * `NYLORUN_IMPLEMENTATION_VERSION`, else `dev`. `dryRun` (protocol 14) runs every check and
+     * saves nothing; the skill files are still uploaded, since they are stored by content.
      */
     saveAgent(agent: AgentSource | BuiltWorkflow, options?: {
         implementationVersion?: string;
         requestId?: string;
+        dryRun?: boolean;
     }): Promise<unknown>;
     createSession(options: CreateSessionOptions): Promise<SessionClient>;
     session(sessionId: string): SessionClient;
@@ -241,10 +241,14 @@ export declare class SessionClient {
             effectId: string;
             turnId: string;
             callId: string | null;
-            capabilityId: string | null;
             toolName: string | null;
-            kind: "http" | "mcp" | "platform" | "sandbox" | null;
+            kind: "harness" | "http" | "mcp" | "platform" | "sandbox" | null;
             server: string | null;
+            skill: string | null;
+            plugin: {
+                name: string;
+                version?: string | undefined;
+            } | null;
             status: "cancelled" | "completed" | "failed" | "held" | "invoking" | "uncertain";
             attempts: number;
             input: unknown;
@@ -369,5 +373,5 @@ export { RuntimeError, IncompatibleRuntimeError } from "./http.js";
 export type { Destination, IncompatibleReason } from "./http.js";
 export type { LiveEvent } from "@nylorun/core/contracts";
 export { AccessClient } from "./access.js";
-export { EnvironmentSecretsClient, EnvironmentsClient } from "./environments.js";
-export type { EnvironmentRecipeInput, EnvironmentSecretInput, ForSessionOptions, SessionEnvironmentHandle, } from "./environments.js";
+export { EnvironmentManifestsClient, EnvironmentSecretsClient, EnvironmentsClient, environmentFiles, environmentManifest, } from "./environments.js";
+export type { EnvironmentFileBytes, EnvironmentInput, EnvironmentManifestInput, EnvironmentSecretInput, ForSessionOptions, SessionEnvironmentHandle, } from "./environments.js";

package/dist/session-client.js

@@ -30,7 +30,6 @@ function linkedSessionId(event) {
         ? sessionId
         : undefined;
 }
-const middlewareClosure = "Hosted definitions support declarative capabilities, not middleware closures";
 /** The agent's declarations, then those of each agent it uses as a tool. */
 function declarationsOf(agent) {
     if (isBuiltWorkflow(agent) || agent.manifest.kind === "workflow")
@@ -39,15 +38,15 @@ function declarationsOf(agent) {
     if (isBuiltWorkflow(built))
         return [];
     const binding = built.getBinding?.();
-    if (!binding || !("declarations" in binding))
+    if (!binding || !("parts" in binding))
         return [];
-    const found = [...(binding.declarations ?? [])];
+    const found = [...(binding.parts ?? [])];
     for (const tool of binding.tools ?? []) {
         const delegate = delegateOf(tool);
-        found.push(...(delegate?.agent?.getBinding().declarations ?? []));
+        found.push(...(delegate?.agent?.getBinding().parts ?? []));
         // A flow agent used as a tool: its agents' declarations.
         for (const leaf of Object.values(delegate?.workflow?.getBinding().agents ?? {}))
-            found.push(...(leaf.declarations ?? []));
+            found.push(...(leaf.parts ?? []));
     }
     return found;
 }
@@ -58,11 +57,6 @@ function skillFilesOf(agent, into = new Map()) {
             into.set(sha256, source);
     return into;
 }
-/** Closures stay on the live binding. The published manifest cannot name them. */
-export function assertNoMiddlewareClosures(agent) {
-    if (declarationsOf(agent).some((item) => item.hasMiddleware))
-        throw new Error(middlewareClosure);
-}
 export class AgentsClient {
     transport;
     /** The subject this client acts for (`as`), or `undefined` for the principal itself. */
@@ -134,7 +128,8 @@ export class AgentsClient {
      * it names that the Runtime does not hold. A definition with a tool that runs your code
      * (`tool({ run })`, a flow's tool stage) is refused before anything is sent: the Runtime runs
      * agents from their manifests alone. `implementationVersion` defaults to
-     * `NYLORUN_IMPLEMENTATION_VERSION`, else `dev`.
+     * `NYLORUN_IMPLEMENTATION_VERSION`, else `dev`. `dryRun` (protocol 14) runs every check and
+     * saves nothing; the skill files are still uploaded, since they are stored by content.
      */
     async saveAgent(agent, options = {}) {
         const files = new Map();
@@ -142,12 +137,10 @@ export class AgentsClient {
             // A flow agent embeds its agents: one document, carrying their files.
             for (const binding of Object.values(agent.getBinding().agents)) {
                 const leaf = { id: binding.manifest.id, manifest: binding.manifest, getBinding: () => binding };
-                assertNoMiddlewareClosures(leaf);
                 skillFilesOf(leaf, files);
             }
         }
         else {
-            assertNoMiddlewareClosures(agent);
             skillFilesOf(agent, files);
         }
         const refusal = codeToolRefusal(agent.manifest) ??
@@ -155,7 +148,7 @@ export class AgentsClient {
         if (refusal)
             throw new Error(refusal);
         await this.files.ensure(files);
-        return this.transport.json(`/v1/agents/${segment(agent.id)}`, "PUT", {
+        return this.transport.json(`/v1/agents/${segment(agent.id)}${options.dryRun ? "?dryRun=true" : ""}`, "PUT", {
             requestId: options.requestId ?? id(),
             manifest: agent.manifest,
             implementationVersion: options.implementationVersion ?? env("NYLORUN_IMPLEMENTATION_VERSION") ?? "dev",
@@ -392,4 +385,4 @@ export class SessionClient {
 }
 export { RuntimeError, IncompatibleRuntimeError } from "./http.js";
 export { AccessClient } from "./access.js";
-export { EnvironmentSecretsClient, EnvironmentsClient } from "./environments.js";
+export { EnvironmentManifestsClient, EnvironmentSecretsClient, EnvironmentsClient, environmentFiles, environmentManifest, } from "./environments.js";

package/dist/skills/index.d.ts

@@ -1,5 +1,3 @@
-export { skills } from "./skills.js";
-export type { SkillsCapability, SkillsOptions } from "./skills.js";
 export { loadSkillsFromDirectory, resolveSkillsRoot, parseSkill, SkillsError, } from "./load.js";
 export type { LoadedSkill, SkillDiagnostic } from "./load.js";
-export { formatSkillCatalog, SKILLS_USAGE } from "./catalog.js";
+export { formatSkillCatalog, SKILLS_USAGE } from "@nylorun/core/define";

package/dist/skills/index.js

@@ -1,3 +1,2 @@
-export { skills } from "./skills.js";
 export { loadSkillsFromDirectory, resolveSkillsRoot, parseSkill, SkillsError, } from "./load.js";
-export { formatSkillCatalog, SKILLS_USAGE } from "./catalog.js";
+export { formatSkillCatalog, SKILLS_USAGE } from "@nylorun/core/define";

package/dist/skills/skills.d.ts

@@ -1,16 +1,12 @@
-import type { CapabilityDeclaration } from "@nylorun/core/define";
+import type { PartDeclaration, PluginLabel } from "@nylorun/core/define";
 import { type LoadedSkill, type SkillDiagnostic } from "./load.js";
-export interface SkillsOptions {
-    /** Capability id. Defaults to the catalog directory basename. */
-    readonly id?: string;
-}
-export interface SkillsCapability extends CapabilityDeclaration {
+export interface SkillsPart extends PartDeclaration {
     readonly diagnostics: readonly SkillDiagnostic[];
     /** Absolute catalog directory that was loaded. */
     readonly root: string;
 }
 /**
- * Load an agentskills.io catalog folder and return one capability for `Agent.use`.
+ * Load an agentskills.io catalog folder as one part of an agent, for `.skills()`.
  *
  * Expected layout:
  * ```
@@ -23,8 +19,12 @@ export interface SkillsCapability extends CapabilityDeclaration {
  *
  * Sets `skills`: each skill's name, description and files (every file of its folder, binary
  * included, by content hash). The client uploads the files the Runtime lacks when it registers
- * the agent, and the Runtime serves `load_skill` / `read_skill_resource` from them.
+ * the agent; the Runtime adds the skill catalog and serves `load_skill` / `read_skill_resource`
+ * from them.
+ */
+export declare function skills(directory: string): SkillsPart;
+/**
+ * The manifest's skills and the bytes behind their files. A plugin's skills carry its label, so
+ * a tool call can be traced to the plugin that brought the skill.
  */
-export declare function skills(directory: string, options?: SkillsOptions): SkillsCapability;
-/** The manifest's skills and the bytes behind their files, for a capability declaration. */
-export declare function skillsDeclaration(listed: readonly LoadedSkill[]): Required<Pick<CapabilityDeclaration, "skills" | "skillFiles">>;
+export declare function skillsDeclaration(listed: readonly LoadedSkill[], plugin?: PluginLabel): Required<Pick<PartDeclaration, "skills" | "skillFiles">>;