@nylorun/agents 0.4.0-beta → 0.6.0-beta

package/dist/http.js

@@ -1,3 +1,4 @@
+import { PROTOCOL_FEATURES, PROTOCOL_HEADER, PROTOCOL_VERSION, TENANT_HEADER, checkCompatibility, } from "@nylorun/core/compatibility";
 export function env(name) {
     return typeof process !== "undefined" ? process.env[name] : undefined;
 }
@@ -10,40 +11,156 @@ export class RuntimeError extends Error {
         this.body = body;
     }
 }
+/** Host protocol is outside the client's supported range or missing required features. */
+export class IncompatibleRuntimeError extends Error {
+    compatibility;
+    remedy;
+    host;
+    constructor(compatibility) {
+        const remedy = remedyFor(compatibility);
+        const detail = compatibility.reason === "version"
+            ? `client protocol ${compatibility.client} is outside Host range ${compatibility.host.min}–${compatibility.host.max}`
+            : `Host is missing required features: ${compatibility.missing.join(", ")}`;
+        super(`Incompatible Runtime: ${detail}. ${remedy}`);
+        this.name = "IncompatibleRuntimeError";
+        this.compatibility = compatibility;
+        this.remedy = remedy;
+        this.host = compatibility.host;
+    }
+}
+function remedyFor(compatibility) {
+    if (compatibility.reason === "feature") {
+        return "Upgrade the Runtime Host (nylorun runtime restart from a newer CLI) so it advertises the required features.";
+    }
+    if (compatibility.client < compatibility.host.min) {
+        return "Upgrade this client (npm i -D @nylorun/agents@latest) or use a CLI that matches the Host protocol.";
+    }
+    return "Upgrade the Runtime Host with nylorun runtime restart from a newer CLI, or install a matching older client (npm i -D @nylorun/cli@<compatible>).";
+}
+function parseProtocolRange(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return undefined;
+    const record = value;
+    if (typeof record.min !== "number" ||
+        typeof record.max !== "number" ||
+        !Array.isArray(record.features) ||
+        !record.features.every((f) => typeof f === "string"))
+        return undefined;
+    return {
+        min: record.min,
+        max: record.max,
+        features: record.features,
+    };
+}
 export class Transport {
     url;
     key;
+    tenant;
     fetcher;
+    compatible = false;
     constructor(options = {}, role = "server") {
         const url = options.url ?? env("NYLORUN_RUNTIME_URL");
         const key = options.key ??
             env(role === "server" ? "NYLORUN_SERVER_KEY" : "NYLORUN_EXECUTOR_KEY");
+        const tenant = options.tenant ?? env("NYLORUN_TENANT");
         if (!url || !key)
             throw new Error(`Set Runtime url and ${role} key explicitly or via NYLORUN_RUNTIME_URL / NYLORUN_${role.toUpperCase()}_KEY`);
+        if (!tenant)
+            throw new Error("Set tenant explicitly or via NYLORUN_TENANT");
         const parsed = new URL(url);
         if (!["http:", "https:"].includes(parsed.protocol))
             throw new Error("Runtime requires an HTTP(S) URL");
         this.url = url.replace(/\/$/, "");
         this.key = key;
+        this.tenant = tenant;
         this.fetcher = options.fetch ?? globalThis.fetch;
     }
-    async request(path, init = {}) {
+    /** Clears the cached Host compatibility result (used after a 426). */
+    clearCompatibilityCache() {
+        this.compatible = false;
+    }
+    async ensureCompatible(signal) {
+        if (this.compatible)
+            return;
+        const response = await this.fetcher(`${this.url}/health`, {
+            method: "GET",
+            redirect: "error",
+            signal,
+        });
+        const text = await response.text();
+        let body = text;
+        try {
+            body = JSON.parse(text);
+        }
+        catch {
+            /* keep text */
+        }
+        if (!response.ok)
+            throw new RuntimeError(response.status, body);
+        const protocol = parseProtocolRange(body && typeof body === "object" && !Array.isArray(body)
+            ? body.protocol
+            : undefined);
+        if (!protocol)
+            throw new IncompatibleRuntimeError({
+                ok: false,
+                reason: "feature",
+                missing: [...PROTOCOL_FEATURES],
+                host: { min: 0, max: 0, features: [] },
+            });
+        const result = checkCompatibility({ version: PROTOCOL_VERSION, required: [...PROTOCOL_FEATURES] }, protocol);
+        if (!result.ok)
+            throw new IncompatibleRuntimeError(result);
+        this.compatible = true;
+    }
+    authHeaders(init = {}) {
         const headers = new Headers(init.headers);
         headers.set("Authorization", `Bearer ${this.key}`);
+        headers.set(TENANT_HEADER, this.tenant);
+        headers.set(PROTOCOL_HEADER, String(PROTOCOL_VERSION));
         if (init.body)
             headers.set("Content-Type", "application/json");
+        return headers;
+    }
+    async request(path, init = {}, options = {}) {
+        await this.ensureCompatible(init.signal === null ? undefined : init.signal);
         const response = await this.fetcher(this.url + path, {
             ...init,
-            headers,
+            headers: this.authHeaders(init),
             redirect: "error",
         });
+        if (response.status === 426) {
+            this.clearCompatibilityCache();
+            if (!options.retried426) {
+                await this.ensureCompatible(init.signal === null ? undefined : init.signal);
+                return this.request(path, init, { retried426: true });
+            }
+            const text = await response.text();
+            let body = text;
+            try {
+                body = JSON.parse(text);
+            }
+            catch {
+                /* keep text */
+            }
+            const protocol = parseProtocolRange(body && typeof body === "object" && !Array.isArray(body)
+                ? body.protocol
+                : undefined);
+            if (protocol) {
+                const result = checkCompatibility({ version: PROTOCOL_VERSION, required: [...PROTOCOL_FEATURES] }, protocol);
+                if (!result.ok)
+                    throw new IncompatibleRuntimeError(result);
+            }
+            throw new RuntimeError(426, body);
+        }
         if (!response.ok) {
             const text = await response.text();
             let body = text;
             try {
                 body = JSON.parse(text);
             }
-            catch { }
+            catch {
+                /* keep text */
+            }
             throw new RuntimeError(response.status, body);
         }
         return response;

package/dist/index.d.ts

@@ -1,12 +1,18 @@
-export { Agent, AgentBuilder, AgentBuildError, AgentLifecycleError, capability, tool, defineSchema, ToolError, } 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 { hashManifest, PROTOCOL_VERSION, PROTOCOL_FEATURES, HOST_PROTOCOL, DEFINITION_SCHEMA_VERSION, TENANT_HEADER, PROTOCOL_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, AgentBuildError, AgentLifecycleError, Loop, Chain, Switch, Parallel, Map, VerdictSchema, isVerdict, withInstructions, withoutTools, WorkflowBuildError, isBuiltWorkflow, capability, tool, defineSchema, ToolError, } 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, 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 type { AgentSource, SessionView, CommandOptions, SessionSandbox, } 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 type { ExecuteActionOptions, ExecutableDefinition, } from "./execute-action.js";
+export { resolveConnection, ConnectionError } from "./connection.js";
+export type { ResolvedConnection } from "./connection.js";
+export { deriveExecutorToken } from "./derived-credentials.js";
+export { RuntimeError, IncompatibleRuntimeError } from "./http.js";
+export type { Destination, IncompatibleReason } from "./http.js";
 export { plugin } from "./plugins/plugin.js";
 export type { PluginCapability } from "./plugins/plugin.js";
 export { loadPlugin, PluginError } from "./plugins/load.js";
@@ -18,4 +24,5 @@ export type { SkillsCapability, SkillsOptions, SkillDiagnostic, } from "./skills
 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";
+export type { SandboxCapability, SandboxCapabilityOptions, SandboxOptions, ActionSandbox, ActionSandboxToolResult, CreateActionSandboxOptions, } from "./sandbox/index.js";
+export { createActionSandbox, definitionDeclaresSandbox, isActionSandboxTool, } from "./sandbox/index.js";

package/dist/index.js

@@ -1,11 +1,15 @@
 // Definition authoring and wire contracts are the only harness runtime imports.
-export { Agent, AgentBuilder, AgentBuildError, AgentLifecycleError, capability, tool, defineSchema, ToolError, } from "@nylorun/core/define";
+export { hashManifest, PROTOCOL_VERSION, PROTOCOL_FEATURES, HOST_PROTOCOL, DEFINITION_SCHEMA_VERSION, TENANT_HEADER, PROTOCOL_HEADER, TENANT_ID_PATTERN, isTenantId, newTenantId, newPrincipalId, checkCompatibility, compareVersions, ERROR_CODES, } from "@nylorun/core/compatibility";
+export { Agent, AgentBuilder, AgentBuildError, AgentLifecycleError, Loop, Chain, Switch, Parallel, Map, VerdictSchema, isVerdict, withInstructions, withoutTools, WorkflowBuildError, isBuiltWorkflow, capability, tool, defineSchema, ToolError, } from "@nylorun/core/define";
 export { AgentsClient, SessionClient, createClient } from "./client.js";
 export { connectAgents } from "./executor.js";
-export { RuntimeError } from "./http.js";
+export { resolveConnection, ConnectionError } from "./connection.js";
+export { deriveExecutorToken } from "./derived-credentials.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 { sandbox, SandboxError } from "./sandbox/index.js";
+export { createActionSandbox, definitionDeclaresSandbox, isActionSandboxTool, } from "./sandbox/index.js";

package/dist/sandbox/client.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Claim-scoped sandbox client for executor actions (`ctx.sandbox`).
+ * Calls `POST /v1/actions/:id/sandbox/:tool` with the live claim.
+ */
+import { type SandboxToolName } from "@nylorun/core/define";
+import { type Transport } from "../http.js";
+export type ActionSandboxToolResult = {
+    readonly kind: "completed";
+    readonly output: unknown;
+} | {
+    readonly kind: "failed";
+    readonly code: string;
+    readonly message: string;
+};
+export type ActionSandbox = {
+    readonly bash: (input: {
+        command: string;
+        timeout?: number;
+    }) => Promise<ActionSandboxToolResult>;
+    readonly read: (input: {
+        path: string;
+        offset?: number;
+        limit?: number;
+    }) => Promise<ActionSandboxToolResult>;
+    readonly write: (input: {
+        path: string;
+        content: string;
+    }) => Promise<ActionSandboxToolResult>;
+    readonly edit: (input: {
+        path: string;
+        old_string: string;
+        new_string: string;
+        replace_all?: boolean;
+    }) => Promise<ActionSandboxToolResult>;
+    readonly grep: (input: {
+        pattern: string;
+        path?: string;
+        glob?: string;
+        ignore_case?: boolean;
+        max_results?: number;
+    }) => Promise<ActionSandboxToolResult>;
+    readonly glob: (input: {
+        pattern: string;
+        path?: string;
+    }) => Promise<ActionSandboxToolResult>;
+};
+export type CreateActionSandboxOptions = {
+    readonly transport: Transport;
+    readonly actionId: string;
+    readonly claimId: string;
+    readonly generation: number;
+    readonly signal?: AbortSignal;
+};
+/** Build `ctx.sandbox` for one claimed action. Undefined callers skip when the session has none. */
+export declare function createActionSandbox(options: CreateActionSandboxOptions): ActionSandbox;
+export declare function isActionSandboxTool(name: string): name is SandboxToolName;
+/** True when the executable declares a sandbox the Runtime can share. */
+export declare function definitionDeclaresSandbox(manifest: {
+    kind?: string;
+    sandbox?: unknown;
+    capabilities?: readonly {
+        sandbox?: unknown;
+    }[];
+}): boolean;

package/dist/sandbox/client.js

@@ -0,0 +1,33 @@
+/**
+ * Claim-scoped sandbox client for executor actions (`ctx.sandbox`).
+ * Calls `POST /v1/actions/:id/sandbox/:tool` with the live claim.
+ */
+import { SANDBOX_TOOL_NAMES, } from "@nylorun/core/define";
+import { segment } from "../http.js";
+/** Build `ctx.sandbox` for one claimed action. Undefined callers skip when the session has none. */
+export function createActionSandbox(options) {
+    const call = (tool, input) => options.transport.json(`/v1/actions/${segment(options.actionId)}/sandbox/${tool}`, "POST", {
+        claimId: options.claimId,
+        generation: options.generation,
+        ...input,
+    }, options.signal);
+    const sandbox = {
+        bash: (input) => call("bash", input),
+        read: (input) => call("read", input),
+        write: (input) => call("write", input),
+        edit: (input) => call("edit", input),
+        grep: (input) => call("grep", input),
+        glob: (input) => call("glob", input),
+    };
+    // Freeze so tools cannot replace built-ins.
+    return Object.freeze(sandbox);
+}
+export function isActionSandboxTool(name) {
+    return SANDBOX_TOOL_NAMES.includes(name);
+}
+/** True when the executable declares a sandbox the Runtime can share. */
+export function definitionDeclaresSandbox(manifest) {
+    if (manifest.kind === "workflow")
+        return manifest.sandbox !== undefined;
+    return (manifest.capabilities ?? []).some((item) => item.sandbox !== undefined);
+}

package/dist/sandbox/index.d.ts

@@ -1,2 +1,4 @@
 export { sandbox, SandboxError } from "./sandbox.js";
 export type { SandboxCapability, SandboxCapabilityOptions, SandboxOptions, } from "./sandbox.js";
+export { createActionSandbox, definitionDeclaresSandbox, isActionSandboxTool, } from "./client.js";
+export type { ActionSandbox, ActionSandboxToolResult, CreateActionSandboxOptions, } from "./client.js";

package/dist/sandbox/index.js

@@ -1 +1,2 @@
 export { sandbox, SandboxError } from "./sandbox.js";
+export { createActionSandbox, definitionDeclaresSandbox, isActionSandboxTool, } from "./client.js";

package/package.json

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