@nylorun/agents 0.14.0-beta → 0.16.1-beta

package/dist/files.js

@@ -0,0 +1,60 @@
+/**
+ * Definition files (track R2 M4): `client.files`. A definition names the files it needs by the
+ * SHA-256 of their bytes (a skill's folder, `SkillManifest.files`); the Runtime holds each one
+ * once, uploaded with `PUT /v1/files/sha256:<hex>`, and refuses a definition naming a file it
+ * does not hold (`400 definition_files_missing`). `saveAgent` uploads an agent's files itself.
+ */
+import { isDefinitionFileHash, } from "@nylorun/core/contracts";
+import { RuntimeError } from "./http.js";
+/** `sha256:<hex>` of `bytes`. */
+export async function definitionFileHash(bytes) {
+    const digest = new Uint8Array(await globalThis.crypto.subtle.digest("SHA-256", bytes));
+    return `sha256:${[...digest].map((byte) => byte.toString(16).padStart(2, "0")).join("")}`;
+}
+function pathOf(sha256) {
+    if (!isDefinitionFileHash(sha256))
+        throw new TypeError(`${sha256} is not a definition file's hash: sha256:<64 lowercase hex>`);
+    return `/v1/files/${sha256}`;
+}
+export class FilesClient {
+    transport;
+    constructor(transport) {
+        this.transport = transport;
+    }
+    /** Whether the Runtime holds the file `sha256` (`sha256:<hex>`) names. */
+    async has(sha256, options = {}) {
+        try {
+            await this.transport.request(pathOf(sha256), {
+                method: "HEAD",
+                ...(options.signal ? { signal: options.signal } : {}),
+            });
+            return true;
+        }
+        catch (error) {
+            if (error instanceof RuntimeError && error.status === 404)
+                return false;
+            throw error;
+        }
+    }
+    /**
+     * Uploads one file, at most 10 MiB. The Runtime checks its bytes hash to `sha256` (default:
+     * their hash) and keeps a file it already holds as it is.
+     */
+    async upload(bytes, options = {}) {
+        const response = await this.transport.request(pathOf(options.sha256 ?? (await definitionFileHash(bytes))), {
+            method: "PUT",
+            body: bytes,
+            headers: { "content-type": "application/octet-stream" },
+            ...(options.signal ? { signal: options.signal } : {}),
+        });
+        return (await response.json());
+    }
+    /** Uploads each of `files` the Runtime does not hold yet. */
+    async ensure(files, options = {}) {
+        for (const [sha256, source] of files) {
+            if (await this.has(sha256, options))
+                continue;
+            await this.upload(await source.read(), { sha256, ...options });
+        }
+    }
+}

package/dist/http.d.ts

@@ -51,11 +51,6 @@ export declare class Transport {
      * transport's compatibility check, so a copy made per request does not repeat `/health`.
      */
     withHeaders(headers: Readonly<Record<string, string>>): Transport;
-    /**
-     * The same destination with another bearer (a delivery token for an Action endpoint's
-     * callbacks). Like `withHeaders`, the copy shares this transport's compatibility check.
-     */
-    withKey(key: string): Transport;
     /** Clears the cached Host compatibility result (used after a 426). */
     clearCompatibilityCache(): void;
     private ensureCompatible;

package/dist/http.js

@@ -92,14 +92,6 @@ export class Transport {
             headers: Object.freeze({ ...this.headers, ...headers }),
         });
     }
-    /**
-     * The same destination with another bearer (a delivery token for an Action endpoint's
-     * callbacks). Like `withHeaders`, the copy shares this transport's compatibility check.
-     */
-    withKey(key) {
-        const copy = Object.create(Transport.prototype);
-        return Object.assign(copy, this, { key });
-    }
     /** Clears the cached Host compatibility result (used after a 426). */
     clearCompatibilityCache() {
         this.check.compatible = false;

package/dist/index.d.ts

@@ -1,20 +1,18 @@
-export { hashManifest, PROTOCOL_VERSION, PROTOCOL_FEATURES, HOST_PROTOCOL, DEFINITION_SCHEMA_VERSION, PROTOCOL_HEADER, SUBJECT_HEADER, SCOPES_HEADER, TENANT_ID_PATTERN, isTenantId, newTenantId, newPrincipalId, checkCompatibility, compareVersions, ERROR_CODES, } from "@nylorun/core/compatibility";
+export { hashManifest, PROTOCOL_VERSION, PROTOCOL_FEATURES, HOST_PROTOCOL, DEFINITION_SCHEMA_VERSION, PROTOCOL_HEADER, SUBJECT_HEADER, SCOPES_HEADER, SESSION_ID_HEADER, TURN_ID_HEADER, AGENT_ID_HEADER, TENANT_ID_PATTERN, isTenantId, newTenantId, newPrincipalId, checkCompatibility, compareVersions, ERROR_CODES, } from "@nylorun/core/compatibility";
 export type { ProtocolFeature, ProtocolRange, Compatibility, ErrorCode, } from "@nylorun/core/compatibility";
 export { Agent, AgentBuilder } from "./builder.js";
-export { AgentBuildError, AgentLifecycleError, Loop, Chain, Switch, Parallel, Map, VerdictSchema, isVerdict, withInstructions, withoutTools, WorkflowBuildError, isBuiltWorkflow, capability, CapabilityBuilder, flow, tool, defineSchema, ToolError, } from "@nylorun/core/define";
-export type { FlowAgentBuilder, Flow, Named, StageArgs, NestedStageArgs, CapabilityIdentity, } from "@nylorun/core/define";
-export type { AgentOptions, AgentManifest, BuiltAgent, BuiltWorkflow, LoopOptions, LoopDecideArgs, LoopVerifyArgs, LoopDecision, ChainOptions, SwitchOptions, ParallelOptions, MapOptions, Verdict, WorkflowBinding, WorkflowManifest, ToolDefinition, ToolExecutionContext, ToolOutcome, Patch, Decision, TurnDecision, HookScope, BeforeHook, AfterHook, JsonValue, JsonObject, } from "@nylorun/core/define";
-export type { LiveEvent, SessionEvent, SessionEventOf, EventType, SessionCommand, Action, ActionOutcome, CredentialInfo, CredentialSelection, VaultInfo, SubjectScope, SandboxView, SandboxEvent, SandboxKind, MessagePart, ArtifactView, ArtifactVersionView, ArtifactLink, UploadArtifactResponse, ArtifactTree, ArtifactDiff, FolderEntry, } from "@nylorun/core/contracts";
+export { AgentBuildError, AgentLifecycleError, VerdictSchema, isVerdict, WorkflowBuildError, isBuiltWorkflow, capability, CapabilityBuilder, flow, tool, http, defineSchema, ToolError, } from "@nylorun/core/define";
+export type { FlowAgentBuilder, Flow, Named, LoopOptions, StageOptions, CapabilityIdentity, HttpTarget, } from "@nylorun/core/define";
+export type { AgentOptions, AgentManifest, BuiltAgent, BuiltWorkflow, Verdict, WorkflowBinding, WorkflowManifest, ToolDefinition, ToolExecutionContext, ToolOutcome, JsonValue, JsonObject, } from "@nylorun/core/define";
+export type { SessionPage, SessionListItem, SessionManifestView, HistoryPage, SessionUsageTotals, ModelCall, ModelCallsPage, SandboxPage, LiveEvent, SessionEvent, SessionEventOf, EventType, SessionCommand, CredentialInfo, CredentialSelection, VaultInfo, SubjectScope, SandboxView, SandboxEvent, SandboxKind, MessagePart, ArtifactView, ArtifactVersionView, ArtifactLink, UploadArtifactResponse, DefinitionFileView, ArtifactTree, ArtifactDiff, FolderEntry, } from "@nylorun/core/contracts";
 export { SUBJECT_SCOPES } from "@nylorun/core/contracts";
 export { AgentsClient, SessionClient, createClient } from "./client.js";
 export { ArtifactsClient } from "./artifacts.js";
+export { FilesClient, definitionFileHash } from "./files.js";
 export type { ArtifactBody, ArtifactLinkWithUrl, UploadArtifactOptions, } from "./artifacts.js";
 export type { ActAsOptions, AgentSource, SessionView, CommandOptions, CreateSessionOptions, SessionSandbox, ForSessionOptions, SandboxSpec, SessionSandboxHandle, } from "./client.js";
 export { SandboxesClient } from "./client.js";
-export { AccessClient, SigningKeysClient } from "./access.js";
-export { createActionHandler } from "./action-handler.js";
-export type { ActionHandler, ActionHandlerOptions, RegisterOptions, } from "./action-handler.js";
-export type { ExecuteActionOptions, ExecutableDefinition, } from "./execute-action.js";
+export { AccessClient } from "./access.js";
 export { resolveConnection, ConnectionError } from "./connection.js";
 export type { ResolvedConnection } from "./connection.js";
 export { RuntimeError, IncompatibleRuntimeError } from "./http.js";
@@ -23,11 +21,8 @@ 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, McpServerSpec } from "./mcp/index.js";
-export type { ActionSandbox, ActionSandboxToolResult, CreateActionSandboxOptions, } from "./sandbox/index.js";
-export { createActionSandbox, definitionDeclaresSandbox, isActionSandboxTool, } from "./sandbox/index.js";
+export type { SessionPageOptions } from "./reads.js";

package/dist/index.js

@@ -1,18 +1,16 @@
 // Definition authoring and wire contracts are the only harness runtime imports.
-export { hashManifest, PROTOCOL_VERSION, PROTOCOL_FEATURES, HOST_PROTOCOL, DEFINITION_SCHEMA_VERSION, PROTOCOL_HEADER, SUBJECT_HEADER, SCOPES_HEADER, TENANT_ID_PATTERN, isTenantId, newTenantId, newPrincipalId, checkCompatibility, compareVersions, ERROR_CODES, } from "@nylorun/core/compatibility";
+export { hashManifest, PROTOCOL_VERSION, PROTOCOL_FEATURES, HOST_PROTOCOL, DEFINITION_SCHEMA_VERSION, PROTOCOL_HEADER, SUBJECT_HEADER, SCOPES_HEADER, SESSION_ID_HEADER, TURN_ID_HEADER, AGENT_ID_HEADER, TENANT_ID_PATTERN, isTenantId, newTenantId, newPrincipalId, checkCompatibility, compareVersions, ERROR_CODES, } from "@nylorun/core/compatibility";
 export { Agent, AgentBuilder } from "./builder.js";
-export { AgentBuildError, AgentLifecycleError, Loop, Chain, Switch, Parallel, Map, VerdictSchema, isVerdict, withInstructions, withoutTools, WorkflowBuildError, isBuiltWorkflow, capability, CapabilityBuilder, flow, tool, defineSchema, ToolError, } from "@nylorun/core/define";
+export { AgentBuildError, AgentLifecycleError, VerdictSchema, isVerdict, WorkflowBuildError, isBuiltWorkflow, capability, CapabilityBuilder, flow, tool, http, defineSchema, ToolError, } from "@nylorun/core/define";
 export { SUBJECT_SCOPES } from "@nylorun/core/contracts";
 export { AgentsClient, SessionClient, createClient } from "./client.js";
 export { ArtifactsClient } from "./artifacts.js";
+export { FilesClient, definitionFileHash } from "./files.js";
 export { SandboxesClient } from "./client.js";
-export { AccessClient, SigningKeysClient } from "./access.js";
-export { createActionHandler } from "./action-handler.js";
+export { AccessClient } from "./access.js";
 export { resolveConnection, ConnectionError } from "./connection.js";
 export { RuntimeError, IncompatibleRuntimeError } from "./http.js";
 export { plugin } from "./plugins/plugin.js";
 export { loadPlugin, PluginError } from "./plugins/load.js";
-export { 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 { createActionSandbox, definitionDeclaresSandbox, isActionSandboxTool, } from "./sandbox/index.js";

package/dist/plugins/load.d.ts

@@ -1,4 +1,5 @@
-import type { McpServerManifest, SkillRecord } from "@nylorun/core/define";
+import { type McpServerManifest } from "@nylorun/core/define";
+import { type LoadedSkill } from "../skills/load.js";
 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 {
@@ -16,7 +17,7 @@ export interface LoadedPlugin {
     readonly root: string;
     readonly name: string;
     readonly description?: string;
-    readonly skills: Readonly<Record<string, SkillRecord>>;
+    readonly skills: Readonly<Record<string, LoadedSkill>>;
     readonly mcpServers: Readonly<Record<string, McpServerManifest>>;
     readonly diagnostics: readonly PluginDiagnostic[];
 }

package/dist/plugins/load.js

@@ -1,7 +1,7 @@
-import { existsSync, mkdirSync, readFileSync, realpathSync, statSync, } from "node:fs";
-import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+import { stdioMcpRefusal } from "@nylorun/core/define";
 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";
 const PLUGIN_FIELDS = new Set([
@@ -17,7 +17,6 @@ const PLUGIN_FIELDS = new Set([
     "extensions",
 ]);
 const AUTHOR_FIELDS = new Set(["name", "email", "url"]);
-const RESERVED_ENV = new Set(["PLUGIN_ROOT", "PLUGIN_DATA"]);
 export class PluginError extends Error {
     code;
     diagnostics;
@@ -76,7 +75,7 @@ export function loadPlugin(directory) {
             });
     }
     const skills = loadSkills(root, diagnostics);
-    const mcpServers = loadMcp(root, parsed.name, diagnostics);
+    const mcpServers = loadMcp(root, diagnostics);
     return {
         root,
         name: parsed.name,
@@ -132,7 +131,7 @@ function loadSkills(root, diagnostics) {
         codePrefix: "plugin",
     });
 }
-function loadMcp(root, pluginName, diagnostics) {
+function loadMcp(root, diagnostics) {
     const location = join(root, "mcp.json");
     if (!existsSync(location))
         return {};
@@ -186,101 +185,54 @@ function loadMcp(root, pluginName, diagnostics) {
         });
         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) {
+        if (isRecord(value) && value.type === "stdio")
+            throw new PluginError("plugin.mcp-stdio", stdioMcpRefusal(name), diagnostics);
+        const server = validateServer(name, value);
+        if (typeof server === "string") {
             diagnostics.push({
                 severity: "warning",
                 code: "plugin.mcp-server-skipped",
-                message: `Skipped invalid MCP server '${name}'`,
+                message: `Skipped invalid MCP server '${name}': ${server}`,
                 path: location,
             });
             continue;
         }
-        if (server.type === "stdio")
-            mkdirSync(pluginData, { recursive: true });
         servers[name] = server;
     }
     return servers;
 }
-function validateServer(name, value, root, pluginData) {
+/** The server, or why it is skipped. */
+function validateServer(name, value) {
     if (!isRecord(value) || typeof value.type !== "string")
-        return undefined;
-    if (value.type === "stdio")
-        return validateStdio(name, value, root, pluginData);
+        return "it has no type";
     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 }),
-    };
+    return `type '${value.type}' is not streamable-http or sse`;
 }
 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;
+    const unknown = Object.keys(value).filter((key) => !allowed.has(key));
+    if (unknown.length > 0)
+        return `${value.type} servers take only type, url and headers, not ${unknown.join(", ")}`;
+    if (typeof value.url !== "string")
+        return "url must be a string";
+    const problem = remoteUrlProblem(value.url);
+    if (problem)
+        return problem;
     let headers;
     if (value.headers !== undefined) {
         if (!isRecord(value.headers))
-            return undefined;
+            return "headers must be an object";
         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;
+                return `header '${key}' is not a valid header`;
             const folded = key.toLowerCase();
             if (seen.has(folded))
-                return undefined;
+                return `header '${key}' is repeated`;
             seen.add(folded);
             headers[key] = item;
         }
@@ -292,41 +244,29 @@ function validateRemote(name, value) {
         ...(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) {
+/**
+ * Why `value` is not a remote server URL: https, or plain http to this machine's loopback (a
+ * local Tenant in Docker reaches it on the Docker host). No credentials or fragment.
+ */
+function remoteUrlProblem(value) {
     let url;
     try {
         url = new URL(value);
     }
     catch {
-        return false;
+        return `url '${value}' is not a URL`;
     }
-    if (url.username || url.password || url.hash)
-        return false;
+    if (url.username || url.password)
+        return "url must not carry credentials; use headers";
+    if (url.hash)
+        return "url must not have a fragment";
     if (url.protocol === "https:")
-        return true;
+        return undefined;
     if (url.protocol !== "http:")
-        return false;
-    return isLoopback(url.hostname);
+        return `url must be https, not ${url.protocol.slice(0, -1)}`;
+    if (isLoopback(url.hostname))
+        return undefined;
+    return `plain http is allowed only for localhost, 127.0.0.1 or [::1]; use https for ${url.hostname}`;
 }
 function isLoopback(hostname) {
     const host = hostname.replace(/^\[|\]$/g, "");

package/dist/plugins/plugin.d.ts

@@ -3,6 +3,11 @@ 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`. */
+/**
+ * Read an Agent Plugin package and return one capability for `Agent.use`. Each part it skips
+ * (an invalid MCP server or skill) is a process warning, so building or registering the agent
+ * says why the agent has less than the package declares. A stdio MCP server throws: Nylorun
+ * accepts remote servers only.
+ */
 export declare function plugin(directory: string): PluginCapability;
 export declare function capabilityFromPlugin(loaded: LoadedPlugin): PluginCapability;

package/dist/plugins/plugin.js

@@ -1,10 +1,28 @@
 import { formatSkillCatalog, SKILLS_USAGE } from "../skills/catalog.js";
+import { skillsDeclaration } from "../skills/skills.js";
 import { loadPlugin, } from "./load.js";
-/** Read an Agent Plugin package and return one capability for `Agent.use`. */
+/**
+ * Read an Agent Plugin package and return one capability for `Agent.use`. Each part it skips
+ * (an invalid MCP server or skill) is a process warning, so building or registering the agent
+ * says why the agent has less than the package declares. A stdio MCP server throws: Nylorun
+ * accepts remote servers only.
+ */
 export function plugin(directory) {
     const loaded = loadPlugin(directory);
+    warn(loaded);
     return capabilityFromPlugin(loaded);
 }
+function warn(loaded) {
+    for (const diagnostic of loaded.diagnostics) {
+        if (diagnostic.severity !== "warning")
+            continue;
+        process.emitWarning(`Plugin '${loaded.name}': ${diagnostic.message}`, {
+            type: "NylorunPluginWarning",
+            code: diagnostic.code,
+            ...(diagnostic.path === undefined ? {} : { detail: diagnostic.path }),
+        });
+    }
+}
 export function capabilityFromPlugin(loaded) {
     const names = Object.values(loaded.skills);
     const instructions = names.length === 0
@@ -16,17 +34,12 @@ export function capabilityFromPlugin(loaded) {
                 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 }),
+        ...(names.length === 0 ? {} : skillsDeclaration(names)),
         ...(Object.keys(loaded.mcpServers).length === 0
             ? {}
             : { mcpServers: loaded.mcpServers }),

package/dist/reads.d.ts

@@ -0,0 +1,17 @@
+/** Optional public reads shared by Studio, CLI and custom clients. */
+import { type SessionListItem, type SessionPage } from "@nylorun/core/contracts";
+import type { Transport } from "./http.js";
+export type SessionPageOptions = {
+    agentId?: string;
+    status?: SessionListItem["status"];
+    sandboxId?: string;
+    ownerUserId?: string;
+    limit?: number;
+    cursor?: string;
+    signal?: AbortSignal;
+};
+export declare class SessionsReadClient {
+    private readonly transport;
+    constructor(transport: Transport);
+    page(options?: SessionPageOptions): Promise<SessionPage>;
+}

package/dist/reads.js

@@ -0,0 +1,17 @@
+/** Optional public reads shared by Studio, CLI and custom clients. */
+import { SessionPageSchema, } from "@nylorun/core/contracts";
+export class SessionsReadClient {
+    transport;
+    constructor(transport) {
+        this.transport = transport;
+    }
+    async page(options = {}) {
+        await this.transport.requireFeature("session-reads", options.signal);
+        const { signal, ...filters } = options;
+        const query = new URLSearchParams({ limit: String(options.limit ?? 50) });
+        for (const [key, value] of Object.entries(filters))
+            if (value !== undefined)
+                query.set(key, String(value));
+        return SessionPageSchema.parse(await this.transport.json(`/v1/sessions?${query}`, "GET", undefined, signal));
+    }
+}

package/dist/sandboxes.d.ts

@@ -58,6 +58,35 @@ export declare class SandboxesClient {
         labels?: Readonly<Record<string, string>>;
         signal?: AbortSignal;
     }): Promise<SandboxView[]>;
+    page(options?: {
+        labels?: Readonly<Record<string, string>>;
+        limit?: number;
+        cursor?: string;
+        signal?: AbortSignal;
+    }): Promise<{
+        sandboxes: {
+            id: string;
+            kind: "pod" | "virtual";
+            labels: Record<string, string>;
+            spec: Record<string, unknown>;
+            state: "creating" | "ready" | "running" | "stopped";
+            pod?: {
+                desired: "deleted" | "running" | "suspended";
+                observed: "creating" | "deleting" | "expired" | "failed" | "lost" | "running" | "suspended";
+                volumeGeneration: number;
+                hostEpoch: number;
+                expiresAt?: string | undefined;
+                reason?: string | undefined;
+            } | undefined;
+            sessions: {
+                id: string;
+                activeTurnId: string | null;
+            }[];
+            createdAt: string;
+            updatedAt: string;
+        }[];
+        nextCursor: string | null;
+    }>;
     /** Deletes the sandbox and its files; `deleted` is false when there was none. */
     delete(sandboxId: string, options?: {
         signal?: AbortSignal;

package/dist/sandboxes.js

@@ -12,7 +12,7 @@
  *
  * Ids may hold `/`; they are sent percent-encoded as one path segment.
  */
-import { isSandboxId, } from "@nylorun/core/contracts";
+import { SandboxPageSchema, isSandboxId, } from "@nylorun/core/contracts";
 import { id, segment } from "./http.js";
 const FEATURE = "sandboxes";
 export class SandboxesClient {
@@ -53,6 +53,15 @@ export class SandboxesClient {
         const reply = await this.transport.json(`/v1/sandboxes${search ? `?${search}` : ""}`, "GET", undefined, options.signal);
         return reply.sandboxes;
     }
+    async page(options = {}) {
+        await this.transport.requireFeature("session-reads", options.signal);
+        const query = new URLSearchParams({ limit: String(options.limit ?? 50) });
+        if (options.cursor !== undefined)
+            query.set("cursor", options.cursor);
+        for (const [key, value] of Object.entries(options.labels ?? {}))
+            query.append("label", `${key}=${value}`);
+        return SandboxPageSchema.parse(await this.transport.json(`/v1/sandboxes?${query}`, "GET", undefined, options.signal));
+    }
     /** Deletes the sandbox and its files; `deleted` is false when there was none. */
     async delete(sandboxId, options = {}) {
         const path = this.path(sandboxId);