@nylorun/agents 0.2.0-beta → 0.4.0-beta

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # @nylorun/agents
 
+## 0.4.0-beta
+
+### Minor Changes
+
+- b8d822a: Add `mcp(...)` to declare MCP servers as one capability for `Agent.use`, matching agent-plugins / manifest v3 `mcpServers` shape.
+- b8d822a: Add `skills(path)` to load an agentskills.io catalog folder into `Agent.use` without duplicating `skills` and `skillRecords`. Parse `SKILL.md` frontmatter with `gray-matter`.
+- b8d822a: Add `sandbox()`: one `.use(sandbox())` gives an agent Runtime-executed `bash`, `read`, `write`, `edit`, `grep` and `glob` tools on an isolated machine with a persistent `/workspace`. The Runtime selects a microsandbox microVM where available, otherwise an in-process virtual shell, enforces deny-by-default egress presets, owns sandbox lifecycle, and reports its choice through `GET /v1/host/sandbox`, the `nylorun dev` banner and `nylorun doctor sandbox`.
+- b8d822a: Breaking beta: replace `beforeModelCall` / `afterModelCall` with scoped hooks. Register `before("turn" | "step", fn)` and `after("step" | "turn", fn)` on the agent, or `before: { turn, step }` / `after: { step, turn }` on a capability. `before("turn")` runs once per turn and its `Patch` applies to every model call in the turn; the new `after("turn")` returns a `TurnDecision` for the final answer. `after` hooks take one argument and receive `attempt`, and `retry` now retries instead of failing the run. The manifest moves to `manifestSchemaVersion: 4` with `capabilities[].hooks`, and `BeforeModelCallFn`, `AfterModelCallFn` and the `beforeModelCall` / `afterModelCall` action kinds are removed. Every capability registered at a hook point now runs in one `hook` executor action, an expired hook claim is offered again instead of becoming uncertain, and the durable engine version is `hosted-2`. Hook toggles now hide a capability's tools, or one tool of a multi-tool capability, instead of having no effect or failing. Studio lists each capability's hooks with how often they run and labels hook actions. See MIGRATION.md.
+
+### Patch Changes
+
+- Pin core to the tested release.
+- Updated dependencies [b8d822a]
+- Updated dependencies [b8d822a]
+- Updated dependencies [b8d822a]
+- Updated dependencies [b8d822a]
+  - @nylorun/core@0.3.0-beta
+
+## 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

@@ -49,12 +49,73 @@ await connection.ready;
 await connection.close();
 ```
 
+Load Agent Skills from a local catalog folder with `skills(path)`:
+
+```ts
+import { Agent, skills } from "@nylorun/agents";
+
+const assistant = Agent({
+  id: "assistant",
+  name: "Order assistant",
+  instructions: "Use lookup_order for orders.",
+  tools: [lookupOrder],
+}).use(skills("./assistant-skills"));
+```
+
+Each subdirectory under the catalog must contain a `SKILL.md` with YAML frontmatter (`name`, `description`) per [Agent Skills](https://agentskills.io/home). Supporting files (for example `references/`) are available through `read_skill_resource` after `load_skill`. The helper sets both the manifest skill catalog and the on-disk skill records so you do not duplicate content.
+
+Declare MCP servers with `mcp(...)` (same map shape as agent-plugins `mcpServers` / manifest v3):
+
+```ts
+import { Agent, mcp } from "@nylorun/agents";
+
+const assistant = Agent({
+  id: "assistant",
+  name: "Assistant",
+  instructions: "Use the available tools.",
+}).use(
+  mcp({
+    github: {
+      name: "github",
+      type: "streamable-http",
+      url: "https://mcp.example.com/github",
+    },
+  })
+);
+```
+
+Each key must equal that server's `name`. Transports follow [Agent Plugins MCP servers](https://agent-plugins.org/plugin-authors/mcp-servers): `stdio`, `streamable-http`, and `sse`. Pass `{ id: "…" }` as the second argument to override the default capability id `"mcp"`.
+
+Give an agent an isolated computer with `sandbox()`:
+
+```ts
+import { Agent, sandbox } from "@nylorun/agents";
+
+const analyst = Agent({
+  id: "analyst",
+  instructions: "Analyse the data the user gives you. Use Python.",
+}).use(sandbox());
+```
+
+The model gets `bash`, `read`, `write`, `edit`, `grep` and `glob` on a Linux machine with a persistent `/workspace`. These tools run in the Runtime, not in your process, so sandbox-only agents need no connected executor. The agent declares what it needs; the Runtime decides where it runs (a microsandbox VM where the machine supports it, otherwise an emulated shell). Every option is optional plain data:
+
+```ts
+.use(sandbox({
+  image: "python:3.13",                           // any OCI image; default python:3.13-slim
+  network: { preset: "dev", allow: ["api.example.com"] }, // "none" | "dev" (default) | "open"
+  resources: { cpus: 2, memory: "2GiB" },
+  idle: "15m",                                    // stop compute when idle; files persist
+}))
+```
+
+The `dev` preset allows package registries and code hosts. Private networks, loopback, the host and cloud metadata endpoints are always blocked. Options from the full design that are not in this version (`setup`, `files`, `secrets`, `mount`, `onStart`, `scope`, ...) throw a `SandboxError` that says so. See [the sandbox design](../docs/design/sandboxes.md).
+
 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`.
+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. The executor runs every capability registered at a hook point in one action. Agent definitions have no `.run()`; explicit local execution is available through `@nylorun/harness/run`.
 
-The SDK depends only on core within the Nylorun packages; installing it does not install harness. Use `/define`, `/client`, or `/executor` for focused imports, or the root for convenience. Studio uses `/client`. See [the adopted host contract](../harness/HOST_CONTRACT.md) and the repository handoff for the verification boundary.
+The SDK depends only on core within the Nylorun packages; installing it does not install harness. Use `/define`, `/client`, or `/executor` for focused imports, or the root for convenience. Studio uses `/client`. See [the adopted host contract](../harness/HOST_CONTRACT.md).

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/execute-action.js

@@ -1,4 +1,4 @@
-import { implementationsFor, isToolError, normalizeToolDefinition, normalizedSchemasFor, } from "@nylorun/core/define";
+import { implementationsFor, isToolError, normalizeToolDefinition, normalizedSchemasFor, runHookPoint, } from "@nylorun/core/define";
 class Suspend {
     outcome;
     constructor(outcome) {
@@ -10,32 +10,17 @@ const object = (value) => value !== null && typeof value === "object" && !Array.
     : {};
 /** Executes code only after a host-issued claim. No engine dependency. */
 export async function executeAction(action, agent, signal) {
+    if (action.kind === "hook")
+        // All capabilities at this hook point run concurrently in one action. Never throws.
+        return {
+            value: {
+                results: await runHookPoint(implementationsFor(agent), action.hook, action.input),
+            },
+        };
     const impl = implementationsFor(agent)[action.capabilityId];
     if (!impl)
         throw new Error(`No capability ${action.capabilityId}`);
-    if (action.kind === "beforeModelCall") {
-        if (!impl.beforeModelCall)
-            throw new Error("Missing beforeModelCall implementation");
-        try {
-            return { value: (await impl.beforeModelCall(action.input)) ?? {} };
-        }
-        catch (error) {
-            return { value: { block: message(error) } };
-        }
-    }
-    if (action.kind === "afterModelCall") {
-        if (!impl.afterModelCall)
-            throw new Error("Missing afterModelCall implementation");
-        try {
-            return {
-                value: (await impl.afterModelCall(action.input, action.context)) ?? {},
-            };
-        }
-        catch (error) {
-            return { value: { block: message(error) } };
-        }
-    }
-    const raw = impl.tools?.[action.toolName ?? ""];
+    const raw = impl.tools?.[action.toolName];
     if (!raw)
         throw new Error("Missing tool implementation");
     const tool = normalizeToolDefinition(raw);

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}`);
@@ -45,13 +47,15 @@ export function connectAgents(options) {
                 dirty = false;
                 const response = await transport.json("/v1/actions", "GET", undefined, signal);
                 for (const item of response.actions) {
-                    const action = ActionSchema.parse(item);
+                    // Skip actions this SDK cannot run (e.g. from an older Runtime) instead of stalling discovery.
+                    const parsed = ActionSchema.safeParse(item);
+                    if (!parsed.success) {
+                        report(parsed.error);
+                        continue;
+                    }
+                    const action = parsed.data;
                     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 +90,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,21 @@
 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 { AgentOptions, AgentManifest, BuiltAgent, ToolDefinition, ToolExecutionContext, ToolOutcome, Patch, Decision, TurnDecision, HookScope, BeforeHook, AfterHook, JsonValue, JsonObject, } from "@nylorun/core/define";
+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";
+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 } from "./mcp/index.js";
+export { sandbox, SandboxError } from "./sandbox/index.js";
+export type { SandboxCapability, SandboxCapabilityOptions, SandboxOptions, } from "./sandbox/index.js";

package/dist/index.js

@@ -3,3 +3,9 @@ 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";
+export { skills, loadSkillsFromDirectory, resolveSkillsRoot, parseSkill, SkillsError, formatSkillCatalog, SKILLS_USAGE, } from "./skills/index.js";
+export { mcp, McpError } from "./mcp/index.js";
+export { sandbox, SandboxError } from "./sandbox/index.js";

package/dist/mcp/index.d.ts

@@ -0,0 +1,2 @@
+export { mcp, McpError } from "./mcp.js";
+export type { McpCapability, McpOptions } from "./mcp.js";

package/dist/mcp/index.js

@@ -0,0 +1 @@
+export { mcp, McpError } from "./mcp.js";

package/dist/mcp/mcp.d.ts

@@ -0,0 +1,30 @@
+import type { CapabilityDeclaration, McpServerManifest } from "@nylorun/core/define";
+export interface McpOptions {
+    /** Capability id. Defaults to `"mcp"`. */
+    readonly id?: string;
+}
+export interface McpCapability extends CapabilityDeclaration {
+    readonly mcpServers: Readonly<Record<string, McpServerManifest>>;
+}
+export declare class McpError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+/**
+ * Declare MCP servers as one capability for `Agent.use`.
+ *
+ * The map shape matches agent-plugins `mcpServers` and manifest v3: each key
+ * must equal that server's `name`. Supported transports are `stdio`,
+ * `streamable-http`, and `sse` (see https://agent-plugins.org/plugin-authors/mcp-servers).
+ *
+ * ```ts
+ * Agent({...}).use(mcp({
+ *   github: {
+ *     name: "github",
+ *     type: "streamable-http",
+ *     url: "https://mcp.example.com/github",
+ *   },
+ * }))
+ * ```
+ */
+export declare function mcp(servers: Readonly<Record<string, McpServerManifest>>, options?: McpOptions): McpCapability;

package/dist/mcp/mcp.js

@@ -0,0 +1,80 @@
+export class McpError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "McpError";
+        this.code = code;
+    }
+}
+/**
+ * Declare MCP servers as one capability for `Agent.use`.
+ *
+ * The map shape matches agent-plugins `mcpServers` and manifest v3: each key
+ * must equal that server's `name`. Supported transports are `stdio`,
+ * `streamable-http`, and `sse` (see https://agent-plugins.org/plugin-authors/mcp-servers).
+ *
+ * ```ts
+ * Agent({...}).use(mcp({
+ *   github: {
+ *     name: "github",
+ *     type: "streamable-http",
+ *     url: "https://mcp.example.com/github",
+ *   },
+ * }))
+ * ```
+ */
+export function mcp(servers, options = {}) {
+    const id = options.id ?? "mcp";
+    if (!isRecord(servers)) {
+        throw new McpError("mcp.invalid", "mcp() expects a non-empty map of MCP servers");
+    }
+    const entries = Object.entries(servers);
+    if (entries.length === 0) {
+        throw new McpError("mcp.empty", "mcp() requires at least one MCP server");
+    }
+    const mcpServers = {};
+    for (const [key, server] of entries) {
+        if (!isMcpServer(server)) {
+            throw new McpError("mcp.invalid-server", `MCP server '${key}' is not a valid stdio, streamable-http, or sse declaration`);
+        }
+        if (server.name !== key) {
+            throw new McpError("mcp.name-mismatch", `MCP server key '${key}' must equal the server name '${server.name}'`);
+        }
+        mcpServers[key] = freezeServer(server);
+    }
+    return { id, mcpServers: Object.freeze(mcpServers) };
+}
+function freezeServer(server) {
+    if (server.type === "stdio") {
+        return Object.freeze({
+            name: server.name,
+            type: "stdio",
+            command: server.command,
+            ...(server.args === undefined ? {} : { args: Object.freeze([...server.args]) }),
+            ...(server.env === undefined
+                ? {}
+                : { env: Object.freeze({ ...server.env }) }),
+            ...(server.cwd === undefined ? {} : { cwd: server.cwd }),
+        });
+    }
+    return Object.freeze({
+        name: server.name,
+        type: server.type,
+        url: server.url,
+        ...(server.headers === undefined
+            ? {}
+            : { headers: Object.freeze({ ...server.headers }) }),
+    });
+}
+function isMcpServer(value) {
+    if (!isRecord(value) || typeof value.name !== "string" || !value.name)
+        return false;
+    if (value.type === "stdio")
+        return typeof value.command === "string" && value.command.length > 0;
+    if (value.type === "streamable-http" || value.type === "sse")
+        return typeof value.url === "string" && value.url.length > 0;
+    return false;
+}
+function isRecord(value) {
+    return !!value && typeof value === "object" && !Array.isArray(value);
+}

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;
+}