@nylorun/agents 0.20.0-beta → 0.22.0-beta

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

@@ -1,5 +1,5 @@
 /**
- * The Tenant API client classes, with no Node-only imports. `client.ts` adds `createClient`,
+ * The Runtime API client classes, with no Node-only imports. `client.ts` adds `createClient`,
  * which resolves the connection from the environment or the Project link.
  */
 import type { AgentManifest, BuiltAgent, BuiltWorkflow, JsonValue, SandboxToolName, WorkflowManifest } from "@nylorun/core/define";
@@ -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">>;

package/dist/skills/skills.js

@@ -1,8 +1,7 @@
 import { basename } from "node:path";
-import { formatSkillCatalog, SKILLS_USAGE } from "./catalog.js";
 import { loadSkillsFromDirectory, resolveSkillsRoot, } from "./load.js";
 /**
- * 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:
  * ```
@@ -15,39 +14,34 @@ import { loadSkillsFromDirectory, resolveSkillsRoot, } from "./load.js";
  *
  * 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 function skills(directory, options = {}) {
+export function skills(directory) {
     const root = resolveSkillsRoot(directory);
     const diagnostics = [];
     const loaded = loadSkillsFromDirectory(root, diagnostics);
     const listed = Object.values(loaded);
-    const id = options.id ?? basename(root);
+    const id = `skills:${basename(root)}`;
     if (listed.length === 0) {
         return { id, root, diagnostics };
     }
-    const { skills: skillManifest, skillFiles } = skillsDeclaration(listed);
-    return {
-        id,
-        root,
-        instructions: [
-            SKILLS_USAGE,
-            formatSkillCatalog(listed.map((skill) => ({
-                name: skill.name,
-                description: skill.description,
-            }))),
-        ],
-        skills: skillManifest,
-        skillFiles,
-        diagnostics,
-    };
+    return { id, root, ...skillsDeclaration(listed), diagnostics };
 }
-/** The manifest's skills and the bytes behind their files, for a capability declaration. */
-export function skillsDeclaration(listed) {
+/**
+ * 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 function skillsDeclaration(listed, plugin) {
     return {
         skills: Object.fromEntries(listed.map((skill) => [
             skill.name,
-            { name: skill.name, description: skill.description, files: skill.files },
+            {
+                name: skill.name,
+                description: skill.description,
+                files: skill.files,
+                ...(plugin === undefined ? {} : { plugin }),
+            },
         ])),
         skillFiles: Object.assign({}, ...listed.map((skill) => skill.sources)),
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nylorun/agents",
-  "version": "0.20.0-beta",
+  "version": "0.22.0-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.20.0-beta",
+    "@nylorun/core": "0.22.0-beta",
     "gray-matter": "^4.0.3"
   },
   "peerDependencies": {

package/dist/skills/catalog.d.ts

@@ -1,5 +0,0 @@
-export declare const SKILLS_USAGE = "The following skills provide specialized instructions. When a task matches a skill description, call load_skill with that name before proceeding.";
-export declare function formatSkillCatalog(skills: readonly {
-    name: string;
-    description: string;
-}[]): string;

package/dist/skills/catalog.js

@@ -1,14 +0,0 @@
-export const SKILLS_USAGE = "The following skills provide specialized instructions. When a task matches a skill description, call load_skill with that name before proceeding.";
-export function formatSkillCatalog(skills) {
-    const entries = skills
-        .map((skill) => `  <skill>\n    <name>${escapeXml(skill.name)}</name>\n    <description>${escapeXml(skill.description)}</description>\n  </skill>`)
-        .join("\n");
-    return `<available_skills>\n${entries}\n</available_skills>`;
-}
-function escapeXml(value) {
-    return value
-        .replaceAll("&", "&amp;")
-        .replaceAll("<", "&lt;")
-        .replaceAll(">", "&gt;")
-        .replaceAll('"', "&quot;");
-}