@nylorun/agents 0.2.0-beta → 0.3.0-beta

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @nylorun/agents
 
+## 0.3.0-beta
+
+### Minor Changes
+
+- 3a88f51: Ship Agent-Plugins (`plugin()` / `loadPlugin`), Skills (`load_skill` / skill resources), Runtime MCP pool + vault credentials, and manifest v3 capability fields. Validate completed tool `output` against the tool output schema so ordinary tools with `outputSchema` no longer false-fail as `tool.invalid-output`.
+
+### Patch Changes
+
+- Pin core to the tested release.
+- Updated dependencies [3a88f51]
+  - @nylorun/core@0.2.0-beta
+
 ## 0.2.0-beta
 
 ### Minor Changes

package/README.md

@@ -51,9 +51,9 @@ await connection.close();
 
 Use `session.observe({ cursor, signal })` for resumable canonical events, `session.inspect()` for waiting/uncertain state, and `approve`, `respond`, or `cancel` with an explicit stable idempotency key. Retry the same semantic command with the same key. `ownerUserId` must come from trusted server authentication. Application credentials are not browser credentials; browser applications need an authorized backend. Definition authoring is browser-bundleable.
 
-The Runtime destination is explicit, or defaults from `NYLORUN_RUNTIME_URL`. Application and executor keys default from `NYLORUN_SERVER_KEY` and `NYLORUN_EXECUTOR_KEY`. Implementation version defaults from `NYLORUN_IMPLEMENTATION_VERSION`, then `dev`. A host must provision executor scope for the exact agent ID, manifest hash and implementation version. Model selection and model credentials belong to the Runtime.
+The Runtime destination is explicit, or defaults from `NYLORUN_RUNTIME_URL`. Application and executor keys default from `NYLORUN_SERVER_KEY` and `NYLORUN_EXECUTOR_KEY`. Implementation version defaults from `NYLORUN_IMPLEMENTATION_VERSION`, then `dev`. A host must provision executor scope for the agent id. Agents do not hash the manifest, and an in-flight action stays claimable after the registered digest changes. Model selection and model credentials belong to the Runtime.
 
-`connectAgents({ agents })` opens authenticated fetch SSE before discovering actions, rediscovers after reconnection, and claims only matching definitions. It renews leases while executing, then retries HTTP result delivery with the same recorded outcome and idempotency key. Reconnect delay is bounded at 30 seconds. Notifications confer no execution authority. There is no periodic action-discovery polling. Close aborts the stream, HTTP requests and lease timers and signals running functions; JavaScript cannot forcibly terminate a function that ignores its signal. The host makes expired in-flight actions uncertain instead of automatically repeating external effects.
+`connectAgents({ agents })` opens authenticated fetch SSE before discovering actions, rediscovers after reconnection, and claims pending actions for a connected agent id. It renews leases while executing, then retries HTTP result delivery with the same recorded outcome and idempotency key. Reconnect delay is bounded at 30 seconds. Notifications confer no execution authority. There is no periodic action-discovery polling. Close aborts the stream, HTTP requests and lease timers and signals running functions; JavaScript cannot forcibly terminate a function that ignores its signal. The host makes expired in-flight actions uncertain instead of automatically repeating external effects.
 
 Tools receive state, info, identity, resume, signal, approval/response helpers and memoized `step`. Step outcomes survive a persisted wait result; they do not establish exactly-once external effects after an unacknowledged crash. `sleep` and `waitFor` currently return inspectable deferred outcomes; automatic timer/event wakeups remain runtime implementation work. Remote `onModelCall` convenience and progress-event transport are not supplied in this pass. Arbitrary middleware closures are rejected for durable definitions; use before/after hooks. Agent definitions have no `.run()`; explicit local execution is available through `@nylorun/harness/run`.
 

package/dist/client.d.ts

@@ -1,12 +1,14 @@
 import type { AgentManifest, BuiltAgent, JsonValue } from "@nylorun/core/define";
-import { type SessionCommand } from "@nylorun/core/contracts";
+import { type CredentialInfo, type CredentialSelection, type SessionCommand, type VaultInfo } from "@nylorun/core/contracts";
 import { Transport, type Destination } from "./http.js";
 export interface AgentSource {
     readonly id: string;
     readonly manifest: AgentManifest;
-    readonly hash: string;
     build?(): BuiltAgent;
+    getBinding?: BuiltAgent["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;
@@ -41,7 +43,71 @@ export declare class AgentsClient {
         ownerUserId: string;
         info?: Record<string, unknown>;
         requestId?: string;
+        vaultIds?: readonly string[];
+        credentialSelections?: readonly CredentialSelection[];
     }): Promise<SessionClient>;
+    createVault(options: {
+        name: string;
+        ownerUserId: string;
+        metadata?: Record<string, string>;
+        idempotencyKey: string;
+        requestId?: string;
+    }): Promise<VaultInfo>;
+    listVaults(ownerUserId: string, signal?: AbortSignal): Promise<{
+        vaults: VaultInfo[];
+    }>;
+    getVault(vaultId: string, signal?: AbortSignal): Promise<VaultInfo>;
+    deleteVault(vaultId: string): Promise<{
+        id: string;
+    }>;
+    createCredential(vaultId: string, options: {
+        name: string;
+        idempotencyKey: string;
+        requestId?: string;
+        auth: {
+            type: "bearer";
+            url: string;
+            token: string;
+        } | {
+            type: "oauth";
+            url: string;
+            accessToken: string;
+            expiresAt?: string | null;
+            refresh?: {
+                tokenEndpoint: string;
+                clientId: string;
+                refreshToken: string;
+                tokenEndpointAuth: {
+                    type: "none";
+                } | {
+                    type: "client_secret_basic";
+                    clientSecret: string;
+                } | {
+                    type: "client_secret_post";
+                    clientSecret: string;
+                };
+            };
+        };
+    }): Promise<CredentialInfo>;
+    listCredentials(vaultId: string, signal?: AbortSignal): Promise<{
+        credentials: CredentialInfo[];
+    }>;
+    getCredential(vaultId: string, credentialId: string, signal?: AbortSignal): Promise<CredentialInfo>;
+    rotateCredential(vaultId: string, credentialId: string, options: {
+        idempotencyKey: string;
+        requestId?: string;
+        auth: {
+            type: "bearer";
+            token: string;
+        } | {
+            type: "oauth";
+            accessToken: string;
+            expiresAt?: string | null;
+        };
+    }): Promise<CredentialInfo>;
+    deleteCredential(vaultId: string, credentialId: string): Promise<{
+        id: string;
+    }>;
     session(sessionId: string): SessionClient;
 }
 export type CommandOptions = {

package/dist/client.js

@@ -1,6 +1,23 @@
 import { LiveEventSchema, SessionItemsResponseSchema, } from "@nylorun/core/contracts";
 import { Transport, id, segment } from "./http.js";
 import { observeSSE } from "./sse.js";
+const middlewareClosure = "Hosted definitions support declarative capabilities and before/after hooks, not middleware closures";
+function pluginRootsOf(agent) {
+    const built = agent.build?.() ?? agent;
+    const declarations = built.getBinding?.().declarations ?? [];
+    const roots = {};
+    for (const item of declarations) {
+        if (item.pluginRoot)
+            roots[item.id] = item.pluginRoot;
+    }
+    return Object.keys(roots).length === 0 ? undefined : roots;
+}
+/** Closures stay on the live binding. The published manifest cannot name them. */
+export function assertNoMiddlewareClosures(agent) {
+    const built = agent.build?.() ?? agent;
+    if (built.getBinding?.().declarations.some((item) => item.hasMiddleware))
+        throw new Error(middlewareClosure);
+}
 export class AgentsClient {
     transport;
     constructor(destination = {}) {
@@ -16,10 +33,13 @@ export class AgentsClient {
         return this.transport.json(`/v1/sessions${query}`, "GET", undefined, options.signal);
     }
     saveAgent(agent, options) {
+        assertNoMiddlewareClosures(agent);
+        const pluginRoots = pluginRootsOf(agent);
         return this.transport.json(`/v1/agents/${segment(agent.id)}`, "PUT", {
             requestId: options.requestId ?? id(),
             manifest: agent.manifest,
             implementationVersion: options.implementationVersion,
+            ...(pluginRoots === undefined ? {} : { pluginRoots }),
         });
     }
     async createSession(options) {
@@ -29,9 +49,55 @@ export class AgentsClient {
             agentId: options.agentId,
             ownerUserId: options.ownerUserId,
             ...(options.info ? { info: options.info } : {}),
+            ...(options.vaultIds ? { vaultIds: options.vaultIds } : {}),
+            ...(options.credentialSelections
+                ? { credentialSelections: options.credentialSelections }
+                : {}),
         });
         return this.session(sessionId);
     }
+    createVault(options) {
+        return this.transport.json("/v1/vaults", "POST", {
+            requestId: options.requestId ?? id(),
+            idempotencyKey: options.idempotencyKey,
+            name: options.name,
+            ownerUserId: options.ownerUserId,
+            ...(options.metadata ? { metadata: options.metadata } : {}),
+        });
+    }
+    listVaults(ownerUserId, signal) {
+        return this.transport.json(`/v1/vaults?ownerUserId=${encodeURIComponent(ownerUserId)}`, "GET", undefined, signal);
+    }
+    getVault(vaultId, signal) {
+        return this.transport.json(`/v1/vaults/${segment(vaultId)}`, "GET", undefined, signal);
+    }
+    deleteVault(vaultId) {
+        return this.transport.json(`/v1/vaults/${segment(vaultId)}`, "DELETE");
+    }
+    createCredential(vaultId, options) {
+        return this.transport.json(`/v1/vaults/${segment(vaultId)}/credentials`, "POST", {
+            requestId: options.requestId ?? id(),
+            idempotencyKey: options.idempotencyKey,
+            name: options.name,
+            auth: options.auth,
+        });
+    }
+    listCredentials(vaultId, signal) {
+        return this.transport.json(`/v1/vaults/${segment(vaultId)}/credentials`, "GET", undefined, signal);
+    }
+    getCredential(vaultId, credentialId, signal) {
+        return this.transport.json(`/v1/vaults/${segment(vaultId)}/credentials/${segment(credentialId)}`, "GET", undefined, signal);
+    }
+    rotateCredential(vaultId, credentialId, options) {
+        return this.transport.json(`/v1/vaults/${segment(vaultId)}/credentials/${segment(credentialId)}`, "POST", {
+            requestId: options.requestId ?? id(),
+            idempotencyKey: options.idempotencyKey,
+            auth: options.auth,
+        });
+    }
+    deleteCredential(vaultId, credentialId) {
+        return this.transport.json(`/v1/vaults/${segment(vaultId)}/credentials/${segment(credentialId)}`, "DELETE");
+    }
     session(sessionId) {
         return new SessionClient(this.transport, sessionId);
     }

package/dist/executor.d.ts

@@ -1,4 +1,4 @@
-import type { AgentSource } from "./client.js";
+import { type AgentSource } from "./client.js";
 import { type Destination } from "./http.js";
 export interface ConnectOptions {
     agents: readonly AgentSource[];

package/dist/executor.js

@@ -1,4 +1,5 @@
 import { AgentManifestSchema, ActionSchema, ActionClaimResponseSchema, } from "@nylorun/core/contracts";
+import { assertNoMiddlewareClosures } from "./client.js";
 import { Transport, RuntimeError, delay, env, id, segment, } from "./http.js";
 import { readSSE } from "./sse.js";
 import { executeAction } from "./execute-action.js";
@@ -10,6 +11,7 @@ export function connectAgents(options) {
     const agents = new Map();
     for (const source of options.agents) {
         const built = source.build?.() ?? source;
+        assertNoMiddlewareClosures(built);
         AgentManifestSchema.parse(built.manifest);
         if (agents.has(built.id))
             throw new Error(`Duplicate connected agent ${built.id}`);
@@ -47,11 +49,7 @@ export function connectAgents(options) {
                 for (const item of response.actions) {
                     const action = ActionSchema.parse(item);
                     const agent = agents.get(action.agentId);
-                    if (!agent ||
-                        agent.hash !== action.manifestHash ||
-                        action.implementationVersion !== version ||
-                        action.status !== "pending" ||
-                        active.has(action.actionId))
+                    if (!agent || action.status !== "pending" || active.has(action.actionId))
                         continue;
                     const work = new AbortController();
                     active.set(action.actionId, work);
@@ -86,12 +84,9 @@ export function connectAgents(options) {
         try {
             const claim = ActionClaimResponseSchema.parse(await transport.json(`/v1/actions/${segment(action.actionId)}/claim`, "POST", {
                 requestId: id(),
-                manifestHash: agent.hash,
                 implementationVersion: version,
             }, work.signal));
-            if (claim.action.actionId !== action.actionId ||
-                claim.action.manifestHash !== agent.hash ||
-                claim.action.implementationVersion !== version)
+            if (claim.action.actionId !== action.actionId)
                 throw new Error("Claim definition mismatch");
             let expires = Date.parse(claim.leaseExpiresAt);
             renewal = (async () => {

package/dist/index.d.ts

@@ -1,9 +1,15 @@
 export { Agent, AgentBuilder, AgentBuildError, AgentLifecycleError, capability, tool, defineSchema, ToolError, } from "@nylorun/core/define";
 export type { AgentOptions, AgentManifest, BuiltAgent, ToolDefinition, ToolExecutionContext, ToolOutcome, Patch, Decision, JsonValue, JsonObject, } from "@nylorun/core/define";
-export type { LiveEvent, SessionCommand, Action, ActionOutcome, } from "@nylorun/core/contracts";
+export type { LiveEvent, SessionCommand, Action, ActionOutcome, CredentialInfo, CredentialSelection, VaultInfo, } from "@nylorun/core/contracts";
 export { AgentsClient, SessionClient, createClient } from "./client.js";
 export type { AgentSource, SessionView, CommandOptions } from "./client.js";
 export { connectAgents } from "./executor.js";
 export type { ConnectOptions, AgentConnection } from "./executor.js";
 export { RuntimeError } from "./http.js";
 export type { Destination } 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 { prepareStdioLaunch, expandPluginPlaceholders } from "./plugins/launch.js";
+export type { StdioLaunch } from "./plugins/launch.js";

package/dist/index.js

@@ -3,3 +3,6 @@ export { Agent, AgentBuilder, AgentBuildError, AgentLifecycleError, capability,
 export { AgentsClient, SessionClient, createClient } from "./client.js";
 export { connectAgents } from "./executor.js";
 export { RuntimeError } from "./http.js";
+export { plugin } from "./plugins/plugin.js";
+export { loadPlugin, PluginError } from "./plugins/load.js";
+export { prepareStdioLaunch, expandPluginPlaceholders } from "./plugins/launch.js";

package/dist/plugins/launch.d.ts

@@ -0,0 +1,17 @@
+import type { McpServerManifest } from "@nylorun/core/define";
+/** Single-pass replacement. Text inserted for a token is not scanned again. */
+export declare function expandPluginPlaceholders(value: string, pluginRoot: string, pluginData: string): string;
+export interface StdioLaunch {
+    readonly command: string;
+    readonly args: readonly string[];
+    readonly cwd: string;
+    readonly env: Readonly<Record<string, string>>;
+}
+export declare function prepareStdioLaunch(server: Extract<McpServerManifest, {
+    type: "stdio";
+}>, options: {
+    readonly pluginRoot: string;
+    readonly pluginData: string;
+    readonly baseEnv?: Readonly<Record<string, string | undefined>>;
+}): StdioLaunch;
+export declare function resolveContainedCwd(cwd: string, pluginRoot: string, pluginData: string): string;

package/dist/plugins/launch.js

@@ -0,0 +1,71 @@
+import { mkdirSync } from "node:fs";
+import { isAbsolute, relative, resolve, sep } from "node:path";
+const ROOT_TOKEN = "${PLUGIN_ROOT}";
+const DATA_TOKEN = "${PLUGIN_DATA}";
+/** Single-pass replacement. Text inserted for a token is not scanned again. */
+export function expandPluginPlaceholders(value, pluginRoot, pluginData) {
+    let out = "";
+    for (let index = 0; index < value.length;) {
+        if (value.startsWith(ROOT_TOKEN, index)) {
+            out += pluginRoot;
+            index += ROOT_TOKEN.length;
+            continue;
+        }
+        if (value.startsWith(DATA_TOKEN, index)) {
+            out += pluginData;
+            index += DATA_TOKEN.length;
+            continue;
+        }
+        out += value[index];
+        index += 1;
+    }
+    return out;
+}
+export function prepareStdioLaunch(server, options) {
+    const pluginRoot = options.pluginRoot;
+    const pluginData = options.pluginData;
+    mkdirSync(pluginData, { recursive: true });
+    const command = resolveCommand(server.command, pluginRoot);
+    const args = (server.args ?? []).map((arg) => expandPluginPlaceholders(arg, pluginRoot, pluginData));
+    const cwd = server.cwd
+        ? resolveContainedCwd(server.cwd, pluginRoot, pluginData)
+        : pluginRoot;
+    const env = {};
+    for (const [key, value] of Object.entries(options.baseEnv ?? {})) {
+        if (typeof value === "string")
+            setEnv(env, key, value);
+    }
+    for (const [key, value] of Object.entries(server.env ?? {}))
+        setEnv(env, key, expandPluginPlaceholders(value, pluginRoot, pluginData));
+    setEnv(env, "PLUGIN_ROOT", pluginRoot);
+    setEnv(env, "PLUGIN_DATA", pluginData);
+    return { command, args, cwd, env };
+}
+function resolveCommand(command, pluginRoot) {
+    if (command.startsWith("./"))
+        return resolve(pluginRoot, command);
+    return command;
+}
+export function resolveContainedCwd(cwd, pluginRoot, pluginData) {
+    const expanded = expandPluginPlaceholders(cwd, pluginRoot, pluginData);
+    const absolute = isAbsolute(expanded) ? expanded : resolve(pluginRoot, expanded);
+    const root = cwdTargetsData(cwd) ? pluginData : pluginRoot;
+    if (!isInside(root, absolute))
+        throw new Error(`Working directory escapes ${root}`);
+    return absolute;
+}
+function cwdTargetsData(cwd) {
+    return cwd === DATA_TOKEN || cwd.startsWith(`${DATA_TOKEN}/`);
+}
+function isInside(root, target) {
+    const rel = relative(root, target);
+    return rel === "" || (!rel.startsWith(`..${sep}`) && rel !== ".." && !isAbsolute(rel));
+}
+function setEnv(env, key, value) {
+    if (process.platform === "win32") {
+        const existing = Object.keys(env).find((name) => name.toLowerCase() === key.toLowerCase());
+        if (existing && existing !== key)
+            delete env[existing];
+    }
+    env[key] = value;
+}

package/dist/plugins/load.d.ts

@@ -0,0 +1,23 @@
+import type { McpServerManifest, SkillRecord } from "@nylorun/core/define";
+export declare const PLUGIN_SCHEMA = "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json";
+export declare const MCP_SCHEMA = "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json";
+export interface PluginDiagnostic {
+    readonly severity: "info" | "warning";
+    readonly code: string;
+    readonly message: string;
+    readonly path?: string;
+}
+export declare class PluginError extends Error {
+    readonly code: string;
+    readonly diagnostics: readonly PluginDiagnostic[];
+    constructor(code: string, message: string, diagnostics?: readonly PluginDiagnostic[]);
+}
+export interface LoadedPlugin {
+    readonly root: string;
+    readonly name: string;
+    readonly description?: string;
+    readonly skills: Readonly<Record<string, SkillRecord>>;
+    readonly mcpServers: Readonly<Record<string, McpServerManifest>>;
+    readonly diagnostics: readonly PluginDiagnostic[];
+}
+export declare function loadPlugin(directory: string): LoadedPlugin;

package/dist/plugins/load.js

@@ -0,0 +1,491 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, statSync, } from "node:fs";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { expandPluginPlaceholders } from "./launch.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";
+const PLUGIN_FIELDS = new Set([
+    "$schema",
+    "name",
+    "version",
+    "description",
+    "author",
+    "homepage",
+    "repository",
+    "license",
+    "keywords",
+    "extensions",
+]);
+const AUTHOR_FIELDS = new Set(["name", "email", "url"]);
+const RESERVED_ENV = new Set(["PLUGIN_ROOT", "PLUGIN_DATA"]);
+const SKILL_NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+export class PluginError extends Error {
+    code;
+    diagnostics;
+    constructor(code, message, diagnostics = []) {
+        super(message);
+        this.name = "PluginError";
+        this.code = code;
+        this.diagnostics = diagnostics;
+    }
+}
+export function loadPlugin(directory) {
+    const root = resolveRoot(directory);
+    const manifestPath = join(root, "plugin.json");
+    const manifestReal = realInside(root, manifestPath);
+    if (!manifestReal || !existsSync(manifestReal) || !statSync(manifestReal).isFile())
+        throw new PluginError("plugin.manifest-missing", `plugin.json must be a file inside ${root}`, [{ severity: "warning", code: "plugin.manifest-missing", message: "plugin.json is missing or escapes the package root", path: manifestPath }]);
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(manifestReal, "utf8"));
+    }
+    catch {
+        throw new PluginError("plugin.manifest-invalid", "plugin.json is not valid JSON");
+    }
+    if (!isRecord(parsed))
+        throw new PluginError("plugin.manifest-invalid", "plugin.json must be a JSON object");
+    const diagnostics = [];
+    for (const key of Object.keys(parsed)) {
+        if (!PLUGIN_FIELDS.has(key))
+            diagnostics.push({
+                severity: "warning",
+                code: "plugin.unknown-field",
+                message: `Ignored unknown plugin.json field '${key}'`,
+                path: manifestPath,
+            });
+    }
+    if (parsed.$schema !== PLUGIN_SCHEMA)
+        throw new PluginError("plugin.schema-unsupported", "plugin.json $schema must be the Agent Plugins 1.0.0 plugin schema", diagnostics);
+    if (!isPluginName(parsed.name))
+        throw new PluginError("plugin.name-invalid", "plugin.json name must be 1-64 characters of lowercase letters, digits, hyphens, and periods", diagnostics);
+    validateMetadata(parsed, diagnostics);
+    const extensions = parsed.extensions;
+    if (extensions !== undefined && !isRecord(extensions))
+        diagnostics.push({
+            severity: "warning",
+            code: "plugin.extensions-ignored",
+            message: "Ignored non-object extensions field",
+            path: manifestPath,
+        });
+    else if (isRecord(extensions)) {
+        for (const namespace of Object.keys(extensions))
+            diagnostics.push({
+                severity: "info",
+                code: "plugin.extension-ignored",
+                message: `Ignored unimplemented extension namespace '${namespace}'`,
+                path: manifestPath,
+            });
+    }
+    const skills = loadSkills(root, diagnostics);
+    const mcpServers = loadMcp(root, parsed.name, diagnostics);
+    return {
+        root,
+        name: parsed.name,
+        ...(typeof parsed.description === "string" ? { description: parsed.description } : {}),
+        skills,
+        mcpServers,
+        diagnostics,
+    };
+}
+function resolveRoot(directory) {
+    const resolved = resolve(directory);
+    if (!existsSync(resolved))
+        throw new PluginError("plugin.missing", `Plugin directory does not exist: ${directory}`);
+    const real = realpathSync(resolved);
+    if (!statSync(real).isDirectory())
+        throw new PluginError("plugin.missing", `Plugin path is not a directory: ${directory}`);
+    return real;
+}
+function validateMetadata(manifest, diagnostics) {
+    for (const field of ["version", "description", "homepage", "repository", "license"]) {
+        if (manifest[field] !== undefined && typeof manifest[field] !== "string")
+            throw new PluginError("plugin.manifest-invalid", `plugin.json ${field} must be a string`, diagnostics);
+    }
+    if (manifest.keywords !== undefined) {
+        if (!Array.isArray(manifest.keywords) || manifest.keywords.some((item) => typeof item !== "string"))
+            throw new PluginError("plugin.manifest-invalid", "plugin.json keywords must be an array of strings", diagnostics);
+    }
+    if (manifest.author !== undefined) {
+        if (!isRecord(manifest.author))
+            throw new PluginError("plugin.manifest-invalid", "plugin.json author must be an object", diagnostics);
+        for (const key of Object.keys(manifest.author)) {
+            if (!AUTHOR_FIELDS.has(key) || typeof manifest.author[key] !== "string")
+                throw new PluginError("plugin.manifest-invalid", "plugin.json author contains an invalid field", diagnostics);
+        }
+    }
+}
+function loadSkills(root, diagnostics) {
+    const location = join(root, "skills");
+    if (!existsSync(location))
+        return {};
+    const real = realInside(root, location);
+    if (!real || !statSync(real).isDirectory()) {
+        diagnostics.push({
+            severity: "warning",
+            code: "plugin.skills-invalid",
+            message: "skills/ is not a directory inside the package",
+            path: location,
+        });
+        return {};
+    }
+    const skills = {};
+    for (const entry of readdirSync(real, { withFileTypes: true })) {
+        if (!entry.isDirectory() || entry.name.startsWith("."))
+            continue;
+        const directory = join(real, entry.name);
+        const directoryReal = realInside(root, directory);
+        if (!directoryReal) {
+            diagnostics.push({
+                severity: "warning",
+                code: "plugin.skill-skipped",
+                message: `Skipped skill '${entry.name}' because its directory escapes the package`,
+                path: directory,
+            });
+            continue;
+        }
+        const skillFile = join(directoryReal, "SKILL.md");
+        if (!existsSync(skillFile))
+            continue;
+        const skillReal = realInside(root, skillFile);
+        if (!skillReal || !statSync(skillReal).isFile()) {
+            diagnostics.push({
+                severity: "warning",
+                code: "plugin.skill-skipped",
+                message: `Skipped skill '${entry.name}' because SKILL.md escapes the package`,
+                path: skillFile,
+            });
+            continue;
+        }
+        const parsed = parseSkill(readFileSync(skillReal, "utf8"), entry.name);
+        if (!parsed) {
+            diagnostics.push({
+                severity: "warning",
+                code: "plugin.skill-skipped",
+                message: `Skipped skill '${entry.name}' because SKILL.md is not a valid Agent Skill`,
+                path: skillFile,
+            });
+            continue;
+        }
+        if (skills[parsed.name]) {
+            diagnostics.push({
+                severity: "warning",
+                code: "plugin.skill-skipped",
+                message: `Skipped duplicate skill '${parsed.name}'`,
+                path: skillFile,
+            });
+            continue;
+        }
+        const resources = readResources(root, directoryReal, diagnostics);
+        skills[parsed.name] = {
+            name: parsed.name,
+            description: parsed.description,
+            instructions: parsed.instructions,
+            ...(Object.keys(resources).length === 0 ? {} : { resources }),
+        };
+    }
+    return skills;
+}
+function parseSkill(text, directoryName) {
+    const match = /^-{3}\r?\n([\s\S]*?)\r?\n-{3}(?:\r?\n|$)/.exec(text);
+    if (!match)
+        return undefined;
+    const fields = {};
+    for (const raw of (match[1] ?? "").split(/\r?\n/)) {
+        if (!raw.trim() || raw.trimStart().startsWith("#"))
+            continue;
+        const line = /^([\w-]+)\s*:\s*(.*)$/.exec(raw);
+        if (!line || line[1] === "metadata")
+            continue;
+        fields[line[1]] = unquote(line[2] ?? "");
+    }
+    const name = fields.name?.trim() ?? "";
+    const description = fields.description?.trim() ?? "";
+    if (!name || !description || description.length > 1024)
+        return undefined;
+    if (name.length > 64 || !SKILL_NAME.test(name) || name !== directoryName)
+        return undefined;
+    return { name, description, instructions: text.slice(match[0].length).replace(/^\r?\n/, "") };
+}
+function readResources(root, directory, diagnostics) {
+    const resources = {};
+    const walk = (current, depth) => {
+        if (depth > 6)
+            return;
+        for (const entry of readdirSync(current, { withFileTypes: true })) {
+            if (entry.name.startsWith(".") || entry.name === "node_modules")
+                continue;
+            const full = join(current, entry.name);
+            if (entry.isDirectory()) {
+                const real = realInside(root, full);
+                if (!real)
+                    continue;
+                walk(real, depth + 1);
+                continue;
+            }
+            if (!entry.isFile() && !entry.isSymbolicLink())
+                continue;
+            if (depth === 0 && entry.name === "SKILL.md")
+                continue;
+            const real = realInside(root, full);
+            if (!real || !statSync(real).isFile()) {
+                diagnostics.push({
+                    severity: "warning",
+                    code: "plugin.resource-denied",
+                    message: `Denied resource outside the package: ${entry.name}`,
+                    path: full,
+                });
+                continue;
+            }
+            const bytes = readFileSync(real);
+            if (bytes.includes(0))
+                continue;
+            const rel = relative(directory, real).split(sep).join("/");
+            if (!rel || rel.startsWith(".."))
+                continue;
+            resources[rel] = bytes.toString("utf8");
+        }
+    };
+    walk(directory, 0);
+    return resources;
+}
+function loadMcp(root, pluginName, diagnostics) {
+    const location = join(root, "mcp.json");
+    if (!existsSync(location))
+        return {};
+    const real = realInside(root, location);
+    if (!real || !statSync(real).isFile()) {
+        diagnostics.push({
+            severity: "warning",
+            code: "plugin.mcp-invalid",
+            message: "mcp.json is not a file inside the package",
+            path: location,
+        });
+        return {};
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(real, "utf8"));
+    }
+    catch {
+        diagnostics.push({
+            severity: "warning",
+            code: "plugin.mcp-invalid",
+            message: "mcp.json is not valid JSON",
+            path: location,
+        });
+        return {};
+    }
+    if (!isRecord(parsed) || Object.keys(parsed).some((key) => key !== "$schema" && key !== "mcpServers")) {
+        diagnostics.push({
+            severity: "warning",
+            code: "plugin.mcp-invalid",
+            message: "mcp.json must contain only $schema and mcpServers",
+            path: location,
+        });
+        return {};
+    }
+    if (parsed.$schema !== MCP_SCHEMA) {
+        diagnostics.push({
+            severity: "warning",
+            code: "plugin.mcp-invalid",
+            message: "mcp.json $schema does not match the plugin schema version",
+            path: location,
+        });
+        return {};
+    }
+    if (!isRecord(parsed.mcpServers)) {
+        diagnostics.push({
+            severity: "warning",
+            code: "plugin.mcp-invalid",
+            message: "mcp.json mcpServers must be an object",
+            path: location,
+        });
+        return {};
+    }
+    const pluginData = join(dirname(root), ".nylorun", "plugin-data", pluginName);
+    const servers = {};
+    for (const [name, value] of Object.entries(parsed.mcpServers)) {
+        const server = validateServer(name, value, root, pluginData);
+        if (!server) {
+            diagnostics.push({
+                severity: "warning",
+                code: "plugin.mcp-server-skipped",
+                message: `Skipped invalid MCP server '${name}'`,
+                path: location,
+            });
+            continue;
+        }
+        if (server.type === "stdio")
+            mkdirSync(pluginData, { recursive: true });
+        servers[name] = server;
+    }
+    return servers;
+}
+function validateServer(name, value, root, pluginData) {
+    if (!isRecord(value) || typeof value.type !== "string")
+        return undefined;
+    if (value.type === "stdio")
+        return validateStdio(name, value, root, pluginData);
+    if (value.type === "streamable-http" || value.type === "sse")
+        return validateRemote(name, value);
+    return undefined;
+}
+function validateStdio(name, value, root, pluginData) {
+    const allowed = new Set(["type", "command", "args", "env", "cwd"]);
+    if (Object.keys(value).some((key) => !allowed.has(key)))
+        return undefined;
+    if (typeof value.command !== "string" || !isCommandToken(value.command))
+        return undefined;
+    if (value.command.startsWith("./") && !commandStaysInside(root, value.command))
+        return undefined;
+    let args;
+    if (value.args !== undefined) {
+        if (!Array.isArray(value.args) || value.args.some((item) => typeof item !== "string"))
+            return undefined;
+        args = value.args;
+    }
+    let env;
+    if (value.env !== undefined) {
+        if (!isRecord(value.env))
+            return undefined;
+        env = {};
+        for (const [key, item] of Object.entries(value.env)) {
+            if (typeof item !== "string" || RESERVED_ENV.has(key))
+                return undefined;
+            env[key] = item;
+        }
+    }
+    let cwd;
+    if (value.cwd !== undefined) {
+        if (typeof value.cwd !== "string" || !isCwdForm(value.cwd))
+            return undefined;
+        const expanded = expandPluginPlaceholders(value.cwd, root, pluginData);
+        const absolute = expanded.startsWith("/") || /^[A-Za-z]:[\\/]/.test(expanded)
+            ? expanded
+            : resolve(root, expanded);
+        const boundary = value.cwd === "${PLUGIN_DATA}" || value.cwd.startsWith("${PLUGIN_DATA}/")
+            ? pluginData
+            : root;
+        if (!isInside(boundary, absolute))
+            return undefined;
+        cwd = value.cwd;
+    }
+    return {
+        name,
+        type: "stdio",
+        command: value.command,
+        ...(args === undefined ? {} : { args }),
+        ...(env === undefined ? {} : { env }),
+        ...(cwd === undefined ? {} : { cwd }),
+    };
+}
+function validateRemote(name, value) {
+    const allowed = new Set(["type", "url", "headers"]);
+    if (Object.keys(value).some((key) => !allowed.has(key)))
+        return undefined;
+    if (typeof value.url !== "string" || !isRemoteUrl(value.url))
+        return undefined;
+    let headers;
+    if (value.headers !== undefined) {
+        if (!isRecord(value.headers))
+            return undefined;
+        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 undefined;
+            const folded = key.toLowerCase();
+            if (seen.has(folded))
+                return undefined;
+            seen.add(folded);
+            headers[key] = item;
+        }
+    }
+    return {
+        name,
+        type: value.type,
+        url: value.url,
+        ...(headers === undefined ? {} : { headers }),
+    };
+}
+function commandStaysInside(root, command) {
+    const lexical = resolve(root, command);
+    if (!isInside(root, lexical))
+        return false;
+    return !existsSync(lexical) || realInside(root, lexical) !== undefined;
+}
+function isCommandToken(command) {
+    if (!command || /\s/.test(command))
+        return false;
+    if (command.startsWith("./"))
+        return !command.split("/").includes("..");
+    return !command.includes("/") && !command.includes("\\") && !command.includes("${");
+}
+function isCwdForm(cwd) {
+    return (cwd.startsWith("./") ||
+        cwd === "${PLUGIN_ROOT}" ||
+        cwd.startsWith("${PLUGIN_ROOT}/") ||
+        cwd === "${PLUGIN_DATA}" ||
+        cwd.startsWith("${PLUGIN_DATA}/"));
+}
+function isRemoteUrl(value) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        return false;
+    }
+    if (url.username || url.password || url.hash)
+        return false;
+    if (url.protocol === "https:")
+        return true;
+    if (url.protocol !== "http:")
+        return false;
+    return isLoopback(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;
+    if (!/^[a-z0-9](?:[a-z0-9.-]*[a-z0-9])?$/.test(value) && value.length !== 1)
+        return false;
+    if (value.length === 1)
+        return /^[a-z0-9]$/.test(value);
+    return !value.includes("--") && !value.includes("..");
+}
+function realInside(root, candidate) {
+    if (!existsSync(candidate))
+        return undefined;
+    try {
+        const real = realpathSync(candidate);
+        return isInside(root, real) ? real : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function isInside(root, target) {
+    const rel = relative(root, target);
+    return rel === "" || (!rel.startsWith(`..${sep}`) && rel !== ".." && !isAbsolute(rel));
+}
+function isRecord(value) {
+    return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function unquote(value) {
+    const trimmed = value.trim();
+    if ((trimmed.startsWith('"') && trimmed.endsWith('"')) ||
+        (trimmed.startsWith("'") && trimmed.endsWith("'")))
+        return trimmed.slice(1, -1);
+    return trimmed;
+}

package/dist/plugins/plugin.d.ts

@@ -0,0 +1,8 @@
+import type { CapabilityDeclaration } from "@nylorun/core/define";
+import { type LoadedPlugin, type PluginDiagnostic } from "./load.js";
+export interface PluginCapability extends CapabilityDeclaration {
+    readonly diagnostics: readonly PluginDiagnostic[];
+}
+/** Read an Agent Plugin package and return one capability for `Agent.use`. */
+export declare function plugin(directory: string): PluginCapability;
+export declare function capabilityFromPlugin(loaded: LoadedPlugin): PluginCapability;

package/dist/plugins/plugin.js

@@ -0,0 +1,45 @@
+import { loadPlugin, } from "./load.js";
+const SKILL_USAGE = "The following skills provide specialized instructions. When a task matches a skill description, call load_skill with that name before proceeding.";
+/** Read an Agent Plugin package and return one capability for `Agent.use`. */
+export function plugin(directory) {
+    const loaded = loadPlugin(directory);
+    return capabilityFromPlugin(loaded);
+}
+export function capabilityFromPlugin(loaded) {
+    const names = Object.values(loaded.skills);
+    const instructions = names.length === 0
+        ? undefined
+        : [SKILL_USAGE, formatCatalog(names.map((skill) => ({
+                name: skill.name,
+                description: skill.description,
+            })))];
+    const skills = Object.fromEntries(names.map((skill) => [
+        skill.name,
+        { name: skill.name, description: skill.description },
+    ]));
+    return {
+        id: loaded.name,
+        type: "agent-plugin",
+        pluginRoot: loaded.root,
+        ...(loaded.description === undefined ? {} : { description: loaded.description }),
+        ...(instructions === undefined ? {} : { instructions }),
+        ...(names.length === 0 ? {} : { skills, skillRecords: loaded.skills }),
+        ...(Object.keys(loaded.mcpServers).length === 0
+            ? {}
+            : { mcpServers: loaded.mcpServers }),
+        diagnostics: loaded.diagnostics,
+    };
+}
+function formatCatalog(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;");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nylorun/agents",
-  "version": "0.2.0-beta",
+  "version": "0.3.0-beta",
   "description": "Nylorun agent definitions, session client and connected executor",
   "type": "module",
   "license": "Apache-2.0",
@@ -35,15 +35,15 @@
     "test": "vitest run --passWithNoTests"
   },
   "dependencies": {
-    "@nylorun/core": "0.1.1-beta"
+    "@nylorun/core": "0.2.0-beta"
   },
   "peerDependencies": {
-    "zod": "^4.5.4"
+    "zod": "^4.6.5"
   },
   "devDependencies": {
-    "typescript": "npm:@typescript/typescript6@^6.0.2",
     "@types/node": "^24.0.0",
-    "vitest": "^5.0.0"
+    "typescript": "npm:@typescript/typescript6@^6.0.2",
+    "vitest": "^5.0.1"
   },
   "engines": {
     "node": ">=24"