@nylorun/agents 0.3.0-beta → 0.4.0-beta

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @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

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

@@ -47,7 +47,13 @@ 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 || action.status !== "pending" || active.has(action.actionId))
                         continue;

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 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 { 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";
@@ -13,3 +13,9 @@ 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

@@ -6,3 +6,6 @@ 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/load.js

@@ -1,5 +1,6 @@
-import { existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, statSync, } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, realpathSync, statSync, } from "node:fs";
 import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { loadSkillsFromDirectory } from "../skills/load.js";
 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";
@@ -17,7 +18,6 @@ const PLUGIN_FIELDS = new Set([
 ]);
 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;
@@ -127,125 +127,10 @@ function loadSkills(root, diagnostics) {
         });
         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;
+    return loadSkillsFromDirectory(real, diagnostics, {
+        boundary: root,
+        codePrefix: "plugin",
+    });
 }
 function loadMcp(root, pluginName, diagnostics) {
     const location = join(root, "mcp.json");
@@ -482,10 +367,3 @@ function isInside(root, target) {
 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.js

@@ -1,5 +1,5 @@
+import { formatSkillCatalog, SKILLS_USAGE } from "../skills/catalog.js";
 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);
@@ -9,10 +9,13 @@ export function capabilityFromPlugin(loaded) {
     const names = Object.values(loaded.skills);
     const instructions = names.length === 0
         ? undefined
-        : [SKILL_USAGE, formatCatalog(names.map((skill) => ({
+        : [
+            SKILLS_USAGE,
+            formatSkillCatalog(names.map((skill) => ({
                 name: skill.name,
                 description: skill.description,
-            })))];
+            }))),
+        ];
     const skills = Object.fromEntries(names.map((skill) => [
         skill.name,
         { name: skill.name, description: skill.description },
@@ -30,16 +33,3 @@ export function capabilityFromPlugin(loaded) {
         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/dist/sandbox/index.d.ts

@@ -0,0 +1,2 @@
+export { sandbox, SandboxError } from "./sandbox.js";
+export type { SandboxCapability, SandboxCapabilityOptions, SandboxOptions, } from "./sandbox.js";

package/dist/sandbox/index.js

@@ -0,0 +1 @@
+export { sandbox, SandboxError } from "./sandbox.js";

package/dist/sandbox/sandbox.d.ts

@@ -0,0 +1,28 @@
+import type { CapabilityDeclaration, SandboxManifest, ToolDefinition } from "@nylorun/core/define";
+/** What computer the agent needs. The Runtime decides where it runs. */
+export type SandboxOptions = SandboxManifest;
+export interface SandboxCapabilityOptions {
+    /** Capability id. Defaults to `"sandbox"`. */
+    readonly id?: string;
+}
+export interface SandboxCapability extends CapabilityDeclaration {
+    readonly sandbox: SandboxManifest;
+    readonly tools: readonly ToolDefinition[];
+}
+export declare class SandboxError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+/**
+ * Give the agent an isolated Linux machine with a persistent `/workspace`.
+ *
+ * Adds the built-in `bash`, `read`, `write`, `edit`, `grep` and `glob` tools. They run in the
+ * Nylorun Runtime, which picks the backend (a microsandbox VM where available). Agent code
+ * declares requirements only.
+ *
+ * ```ts
+ * Agent({ id: "analyst", instructions: "..." }).use(sandbox())
+ * Agent({ ... }).use(sandbox({ image: "node:24", network: { allow: ["api.github.com"] } }))
+ * ```
+ */
+export declare function sandbox(options?: SandboxOptions, capability?: SandboxCapabilityOptions): SandboxCapability;

package/dist/sandbox/sandbox.js

@@ -0,0 +1,93 @@
+import { SANDBOX_DEFERRED_FIELDS, SANDBOX_FIELDS, SANDBOX_INSTRUCTIONS, SANDBOX_NETWORK_PRESETS, createSandboxTools, isSandboxHostPattern, parseSandboxDuration, parseSandboxSize, } from "@nylorun/core/define";
+export class SandboxError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "SandboxError";
+        this.code = code;
+    }
+}
+/**
+ * Give the agent an isolated Linux machine with a persistent `/workspace`.
+ *
+ * Adds the built-in `bash`, `read`, `write`, `edit`, `grep` and `glob` tools. They run in the
+ * Nylorun Runtime, which picks the backend (a microsandbox VM where available). Agent code
+ * declares requirements only.
+ *
+ * ```ts
+ * Agent({ id: "analyst", instructions: "..." }).use(sandbox())
+ * Agent({ ... }).use(sandbox({ image: "node:24", network: { allow: ["api.github.com"] } }))
+ * ```
+ */
+export function sandbox(options = {}, capability = {}) {
+    const id = capability.id ?? "sandbox";
+    if (!isRecord(options))
+        throw new SandboxError("sandbox.invalid", "sandbox() expects an options object");
+    for (const key of Object.keys(options)) {
+        if (SANDBOX_DEFERRED_FIELDS.includes(key))
+            throw new SandboxError("sandbox.unsupported", `sandbox({ ${key} }) is not supported in this version. ` +
+                `Supported options: ${SANDBOX_FIELDS.join(", ")}. See docs/design/sandboxes.md for what is planned.`);
+        if (!SANDBOX_FIELDS.includes(key))
+            throw new SandboxError("sandbox.unknown-option", `Unknown sandbox option '${key}'. Supported options: ${SANDBOX_FIELDS.join(", ")}`);
+    }
+    return Object.freeze({
+        id,
+        instructions: Object.freeze([SANDBOX_INSTRUCTIONS]),
+        tools: createSandboxTools(),
+        sandbox: freezeOptions(options),
+    });
+}
+function freezeOptions(options) {
+    const result = {};
+    if (options.image !== undefined) {
+        if (typeof options.image !== "string" || options.image.trim().length === 0)
+            throw new SandboxError("sandbox.invalid-image", "sandbox({ image }) must be a non-empty OCI image reference");
+        result.image = options.image;
+    }
+    if (options.network !== undefined) {
+        if (!isRecord(options.network))
+            throw new SandboxError("sandbox.invalid-network", "sandbox({ network }) must be an object");
+        for (const key of Object.keys(options.network))
+            if (key !== "preset" && key !== "allow")
+                throw new SandboxError("sandbox.invalid-network", `Unknown network option '${key}'. Use preset and allow.`);
+        const { preset, allow } = options.network;
+        if (preset !== undefined && !SANDBOX_NETWORK_PRESETS.includes(preset))
+            throw new SandboxError("sandbox.invalid-network", `network.preset must be one of ${SANDBOX_NETWORK_PRESETS.join(", ")}`);
+        if (allow !== undefined) {
+            if (!Array.isArray(allow))
+                throw new SandboxError("sandbox.invalid-network", "network.allow must be an array of host names");
+            for (const host of allow)
+                if (typeof host !== "string" || !isSandboxHostPattern(host))
+                    throw new SandboxError("sandbox.invalid-network", `network.allow entry '${String(host)}' must be a host name such as api.github.com or *.example.com (no scheme, port or path)`);
+        }
+        result.network = Object.freeze({
+            ...(preset === undefined ? {} : { preset: preset }),
+            ...(allow === undefined ? {} : { allow: Object.freeze([...allow]) }),
+        });
+    }
+    if (options.resources !== undefined) {
+        if (!isRecord(options.resources))
+            throw new SandboxError("sandbox.invalid-resources", "sandbox({ resources }) must be an object");
+        for (const key of Object.keys(options.resources))
+            if (key !== "cpus" && key !== "memory")
+                throw new SandboxError("sandbox.invalid-resources", `resources.${key} is not supported in this version. Use cpus and memory.`);
+        const { cpus, memory } = options.resources;
+        if (cpus !== undefined && (!Number.isInteger(cpus) || cpus < 1 || cpus > 64))
+            throw new SandboxError("sandbox.invalid-resources", "resources.cpus must be an integer from 1 to 64");
+        if (memory !== undefined && (typeof memory !== "string" || parseSandboxSize(memory) === undefined))
+            throw new SandboxError("sandbox.invalid-resources", "resources.memory must be a size such as 512MiB or 2GiB");
+        result.resources = Object.freeze({
+            ...(cpus === undefined ? {} : { cpus }),
+            ...(memory === undefined ? {} : { memory }),
+        });
+    }
+    if (options.idle !== undefined) {
+        if (typeof options.idle !== "string" || parseSandboxDuration(options.idle) === undefined)
+            throw new SandboxError("sandbox.invalid-idle", "sandbox({ idle }) must be a duration such as 30s, 15m or 1h");
+        result.idle = options.idle;
+    }
+    return Object.freeze(result);
+}
+function isRecord(value) {
+    return !!value && typeof value === "object" && !Array.isArray(value);
+}

package/dist/skills/catalog.d.ts

@@ -0,0 +1,5 @@
+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

@@ -0,0 +1,14 @@
+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;");
+}

package/dist/skills/index.d.ts

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

package/dist/skills/index.js

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

package/dist/skills/load.d.ts

@@ -0,0 +1,27 @@
+import type { SkillRecord } from "@nylorun/core/define";
+export interface SkillDiagnostic {
+    readonly severity: "info" | "warning";
+    readonly code: string;
+    readonly message: string;
+    readonly path?: string;
+}
+export declare class SkillsError extends Error {
+    readonly code: string;
+    readonly diagnostics: readonly SkillDiagnostic[];
+    constructor(code: string, message: string, diagnostics?: readonly SkillDiagnostic[]);
+}
+/** Resolve a skills catalog directory; throws when missing or not a directory. */
+export declare function resolveSkillsRoot(directory: string): string;
+/**
+ * Load Agent Skills (agentskills.io) from a catalog directory.
+ * Each immediate subdirectory with a valid SKILL.md becomes one skill.
+ */
+export declare function loadSkillsFromDirectory(directory: string, diagnostics: SkillDiagnostic[], options?: {
+    readonly boundary?: string;
+    readonly codePrefix?: string;
+}): Readonly<Record<string, SkillRecord>>;
+export declare function parseSkill(text: string, directoryName: string): {
+    name: string;
+    description: string;
+    instructions: string;
+} | undefined;

package/dist/skills/load.js

@@ -0,0 +1,171 @@
+import { existsSync, readdirSync, readFileSync, realpathSync, statSync, } from "node:fs";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+import matter from "gray-matter";
+const SKILL_NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+export class SkillsError extends Error {
+    code;
+    diagnostics;
+    constructor(code, message, diagnostics = []) {
+        super(message);
+        this.name = "SkillsError";
+        this.code = code;
+        this.diagnostics = diagnostics;
+    }
+}
+/** Resolve a skills catalog directory; throws when missing or not a directory. */
+export function resolveSkillsRoot(directory) {
+    const resolved = resolve(directory);
+    if (!existsSync(resolved))
+        throw new SkillsError("skills.missing", `Skills directory does not exist: ${directory}`);
+    const real = realpathSync(resolved);
+    if (!statSync(real).isDirectory())
+        throw new SkillsError("skills.missing", `Skills path is not a directory: ${directory}`);
+    return real;
+}
+/**
+ * Load Agent Skills (agentskills.io) from a catalog directory.
+ * Each immediate subdirectory with a valid SKILL.md becomes one skill.
+ */
+export function loadSkillsFromDirectory(directory, diagnostics, options = {}) {
+    const root = resolveSkillsRoot(directory);
+    const boundary = options.boundary ?? root;
+    const prefix = options.codePrefix ?? "skills";
+    const skills = {};
+    for (const entry of readdirSync(root, { withFileTypes: true })) {
+        if (!entry.isDirectory() || entry.name.startsWith("."))
+            continue;
+        if (entry.name === "node_modules" || entry.name === ".git")
+            continue;
+        const skillDir = join(root, entry.name);
+        const directoryReal = realInside(boundary, skillDir);
+        if (!directoryReal) {
+            diagnostics.push({
+                severity: "warning",
+                code: `${prefix}.skill-skipped`,
+                message: `Skipped skill '${entry.name}' because its directory escapes the package`,
+                path: skillDir,
+            });
+            continue;
+        }
+        const skillFile = join(directoryReal, "SKILL.md");
+        if (!existsSync(skillFile))
+            continue;
+        const skillReal = realInside(boundary, skillFile);
+        if (!skillReal || !statSync(skillReal).isFile()) {
+            diagnostics.push({
+                severity: "warning",
+                code: `${prefix}.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: `${prefix}.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: `${prefix}.skill-skipped`,
+                message: `Skipped duplicate skill '${parsed.name}'`,
+                path: skillFile,
+            });
+            continue;
+        }
+        const resources = readResources(boundary, directoryReal, diagnostics, prefix);
+        skills[parsed.name] = {
+            name: parsed.name,
+            description: parsed.description,
+            instructions: parsed.instructions,
+            ...(Object.keys(resources).length === 0 ? {} : { resources }),
+        };
+    }
+    return skills;
+}
+export function parseSkill(text, directoryName) {
+    let parsed;
+    try {
+        parsed = matter(text);
+    }
+    catch {
+        return undefined;
+    }
+    const name = asTrimmedString(parsed.data.name);
+    const description = asTrimmedString(parsed.data.description);
+    if (!name || !description || description.length > 1024)
+        return undefined;
+    if (name.length > 64 || !SKILL_NAME.test(name) || name !== directoryName)
+        return undefined;
+    return {
+        name,
+        description,
+        instructions: parsed.content.replace(/^\r?\n/, ""),
+    };
+}
+function asTrimmedString(value) {
+    return typeof value === "string" ? value.trim() : "";
+}
+function readResources(boundary, directory, diagnostics, prefix) {
+    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(boundary, 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(boundary, full);
+            if (!real || !statSync(real).isFile()) {
+                diagnostics.push({
+                    severity: "warning",
+                    code: `${prefix}.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 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)));
+}

package/dist/skills/skills.d.ts

@@ -0,0 +1,28 @@
+import type { CapabilityDeclaration } from "@nylorun/core/define";
+import { type SkillDiagnostic } from "./load.js";
+export interface SkillsOptions {
+    /** Capability id. Defaults to the catalog directory basename. */
+    readonly id?: string;
+}
+export interface SkillsCapability extends CapabilityDeclaration {
+    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`.
+ *
+ * Expected layout:
+ * ```
+ * assistant-skills/
+ *   lookup-order/SKILL.md
+ *   refund/
+ *     SKILL.md
+ *     references/policy.md
+ * ```
+ *
+ * Sets both `skills` (manifest names/descriptions) and `skillRecords` (bodies +
+ * resources) so callers do not duplicate content. The harness injects
+ * `load_skill` / `read_skill_resource` from the records.
+ */
+export declare function skills(directory: string, options?: SkillsOptions): SkillsCapability;

package/dist/skills/skills.js

@@ -0,0 +1,47 @@
+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`.
+ *
+ * Expected layout:
+ * ```
+ * assistant-skills/
+ *   lookup-order/SKILL.md
+ *   refund/
+ *     SKILL.md
+ *     references/policy.md
+ * ```
+ *
+ * Sets both `skills` (manifest names/descriptions) and `skillRecords` (bodies +
+ * resources) so callers do not duplicate content. The harness injects
+ * `load_skill` / `read_skill_resource` from the records.
+ */
+export function skills(directory, options = {}) {
+    const root = resolveSkillsRoot(directory);
+    const diagnostics = [];
+    const records = loadSkillsFromDirectory(root, diagnostics);
+    const listed = Object.values(records);
+    const id = options.id ?? basename(root);
+    if (listed.length === 0) {
+        return { id, root, diagnostics };
+    }
+    const skillManifest = Object.fromEntries(listed.map((skill) => [
+        skill.name,
+        { name: skill.name, description: skill.description },
+    ]));
+    return {
+        id,
+        root,
+        instructions: [
+            SKILLS_USAGE,
+            formatSkillCatalog(listed.map((skill) => ({
+                name: skill.name,
+                description: skill.description,
+            }))),
+        ],
+        skills: skillManifest,
+        skillRecords: records,
+        diagnostics,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nylorun/agents",
-  "version": "0.3.0-beta",
+  "version": "0.4.0-beta",
   "description": "Nylorun agent definitions, session client and connected executor",
   "type": "module",
   "license": "Apache-2.0",
@@ -35,7 +35,8 @@
     "test": "vitest run --passWithNoTests"
   },
   "dependencies": {
-    "@nylorun/core": "0.2.0-beta"
+    "@nylorun/core": "0.3.0-beta",
+    "gray-matter": "^4.0.3"
   },
   "peerDependencies": {
     "zod": "^4.6.5"