@nylorun/agents 0.8.0-beta → 0.10.0-beta

package/dist/executor.js

@@ -1,353 +0,0 @@
-import { AgentManifestSchema, ActionSchema, ActionClaimResponseSchema, } from "@nylorun/core/contracts";
-import { agentFrom, isBuiltWorkflow, } from "@nylorun/core/define";
-import { AgentsClient, assertNoMiddlewareClosures, } from "./client.js";
-import { resolveConnection } from "./connection.js";
-import { deriveExecutorToken } from "./derived-credentials.js";
-import { Transport, RuntimeError, delay, env, id, segment, } from "./http.js";
-import { readSSE } from "./sse.js";
-import { executeAction } from "./execute-action.js";
-import { createActionSandbox, definitionDeclaresSandbox, } from "./sandbox/client.js";
-function implementationVersionOf(options) {
-    return (options.implementationVersion ??
-        env("NYLORUN_IMPLEMENTATION_VERSION") ??
-        "dev");
-}
-function buildAgents(options) {
-    const agents = new Map();
-    const addAgent = (built) => {
-        assertNoMiddlewareClosures(built);
-        AgentManifestSchema.parse(built.manifest);
-        if (agents.has(built.id))
-            throw new Error(`Duplicate connected agent ${built.id}`);
-        agents.set(built.id, built);
-    };
-    for (const source of options.agents) {
-        if (isBuiltWorkflow(source)) {
-            if (agents.has(source.id))
-                throw new Error(`Duplicate connected agent ${source.id}`);
-            agents.set(source.id, source);
-            for (const binding of Object.values(source.getBinding().agents))
-                addAgent(agentFrom(binding.manifest, binding.implementations));
-            continue;
-        }
-        const built = source.build?.() ?? source;
-        if (isBuiltWorkflow(built)) {
-            if (agents.has(built.id))
-                throw new Error(`Duplicate connected agent ${built.id}`);
-            agents.set(built.id, built);
-            for (const binding of Object.values(built.getBinding().agents))
-                addAgent(agentFrom(binding.manifest, binding.implementations));
-            continue;
-        }
-        addAgent(built);
-    }
-    if (!agents.size)
-        throw new Error("connectAgents requires at least one agent");
-    return agents;
-}
-function connectExecutorMode(options, runtime, agents) {
-    const transport = new Transport(runtime, "executor");
-    const version = implementationVersionOf(options);
-    const controller = new AbortController();
-    const signal = controller.signal;
-    const active = new Map();
-    let resolveReady;
-    let rejectReady;
-    const ready = new Promise((resolve, reject) => {
-        resolveReady = resolve;
-        rejectReady = reject;
-    });
-    // Avoid an unhandled rejection for callers that immediately close the handle.
-    void ready.catch(() => { });
-    const report = (error) => {
-        try {
-            options.onError?.(error);
-        }
-        catch { }
-    };
-    let discovering = false, dirty = false;
-    const discover = async () => {
-        dirty = true;
-        if (discovering)
-            return;
-        discovering = true;
-        try {
-            while (dirty && !signal.aborted) {
-                dirty = false;
-                const response = await transport.json("/v1/actions", "GET", undefined, signal);
-                for (const item of response.actions) {
-                    // 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;
-                    const work = new AbortController();
-                    active.set(action.actionId, work);
-                    let delivered = false;
-                    void processAction(action, agent, work)
-                        .then(() => {
-                        delivered = true;
-                    })
-                        .catch((error) => {
-                        if (!signal.aborted)
-                            report(error);
-                    })
-                        .finally(() => {
-                        active.delete(action.actionId);
-                        // Completion-driven discovery drains bounded server pages without periodic polling.
-                        if (delivered && !signal.aborted)
-                            void discover().catch(report);
-                    });
-                }
-            }
-        }
-        finally {
-            discovering = false;
-        }
-    };
-    const processAction = async (action, agent, work) => {
-        const stop = () => work.abort(signal.reason);
-        signal.addEventListener("abort", stop, { once: true });
-        let renewal;
-        let renewing = true;
-        let wakeRenewal;
-        try {
-            const claim = ActionClaimResponseSchema.parse(await transport.json(`/v1/actions/${segment(action.actionId)}/claim`, "POST", {
-                requestId: id(),
-                implementationVersion: version,
-            }, work.signal));
-            if (claim.action.actionId !== action.actionId)
-                throw new Error("Claim definition mismatch");
-            let expires = Date.parse(claim.leaseExpiresAt);
-            renewal = (async () => {
-                while (renewing && !work.signal.aborted) {
-                    const remaining = expires - Date.now();
-                    if (!Number.isFinite(remaining) || remaining <= 0)
-                        throw new Error("Executor lease expired");
-                    await new Promise((resolve) => {
-                        const finish = () => {
-                            clearTimeout(timer);
-                            work.signal.removeEventListener("abort", finish);
-                            resolve();
-                        };
-                        const timer = setTimeout(finish, Math.max(50, Math.floor(remaining / 3)));
-                        wakeRenewal = finish;
-                        work.signal.addEventListener("abort", finish, { once: true });
-                    });
-                    if (!renewing || work.signal.aborted)
-                        return;
-                    const renewed = await transport.json(`/v1/actions/${segment(action.actionId)}/heartbeat`, "POST", {
-                        requestId: id(),
-                        claimId: claim.claimId,
-                        generation: claim.generation,
-                    }, work.signal);
-                    expires = Date.parse(renewed.leaseExpiresAt);
-                }
-            })().catch((error) => {
-                if (renewing && !work.signal.aborted) {
-                    work.abort(error);
-                    report(error);
-                }
-            });
-            const outcome = await executeAction(claim.action, agent, work.signal, {
-                sandbox: definitionDeclaresSandbox(agent.manifest)
-                    ? createActionSandbox({
-                        transport,
-                        actionId: action.actionId,
-                        claimId: claim.claimId,
-                        generation: claim.generation,
-                        signal: work.signal,
-                    })
-                    : undefined,
-            });
-            work.signal.throwIfAborted();
-            const command = {
-                type: "action_result",
-                requestId: id(),
-                idempotencyKey: `action:${action.actionId}:${claim.generation}`,
-                actionId: action.actionId,
-                claimId: claim.claimId,
-                generation: claim.generation,
-                outcome,
-            };
-            // Retrying delivery never re-invokes the tool/hook. Lost acknowledgements use the same receipt key.
-            for (let attempt = 0;; attempt++) {
-                try {
-                    await transport.json(`/v1/sessions/${segment(action.sessionId)}/commands`, "POST", command, work.signal);
-                    break;
-                }
-                catch (error) {
-                    if (work.signal.aborted ||
-                        attempt >= 4 ||
-                        (error instanceof RuntimeError &&
-                            error.status < 500 &&
-                            ![408, 429].includes(error.status)))
-                        throw error;
-                    await delay(Math.min(4000, 250 * 2 ** attempt), work.signal);
-                }
-            }
-        }
-        finally {
-            renewing = false;
-            wakeRenewal?.();
-            await renewal;
-            signal.removeEventListener("abort", stop);
-        }
-    };
-    const loop = (async () => {
-        let retry = 250;
-        while (!signal.aborted) {
-            const subscription = new AbortController();
-            const stop = () => subscription.abort(signal.reason);
-            signal.addEventListener("abort", stop, { once: true });
-            try {
-                const response = await transport.request("/v1/executors/connect", {
-                    signal: subscription.signal,
-                    headers: { Accept: "text/event-stream" },
-                });
-                if (!response.headers.get("content-type")?.includes("text/event-stream"))
-                    throw new Error("Executor endpoint did not return SSE");
-                // Subscription exists before initial discovery; notifications can safely accumulate in its stream.
-                await discover();
-                resolveReady();
-                for await (const frame of readSSE(response, subscription.signal)) {
-                    retry = 250;
-                    if (frame.event === "work_available" ||
-                        (frame.data && JSON.parse(frame.data).type === "work_available"))
-                        await discover();
-                }
-            }
-            catch (error) {
-                if (signal.aborted)
-                    break;
-                report(error);
-                if (error instanceof RuntimeError &&
-                    [400, 401, 403, 404].includes(error.status)) {
-                    rejectReady(error);
-                    controller.abort(error);
-                    break;
-                }
-            }
-            finally {
-                subscription.abort();
-                signal.removeEventListener("abort", stop);
-            }
-            if (!signal.aborted)
-                await delay(retry, signal).catch(() => { });
-            retry = Math.min(30000, retry * 2);
-        }
-        rejectReady(signal.reason ?? new Error("Executor connection closed"));
-    })();
-    return {
-        ready,
-        async close() {
-            controller.abort(new Error("Executor connection closed"));
-            for (const work of active.values())
-                work.abort(signal.reason);
-            await loop;
-        },
-    };
-}
-function connectApplicationMode(options, application, agents) {
-    const version = implementationVersionOf(options);
-    const children = [];
-    let resolveReady;
-    let rejectReady;
-    const ready = new Promise((resolve, reject) => {
-        resolveReady = resolve;
-        rejectReady = reject;
-    });
-    void ready.catch(() => { });
-    const boot = (async () => {
-        for (const agent of agents.values()) {
-            await application.saveAgent(agent, { implementationVersion: version });
-        }
-        const registrations = [...agents.values()].map((agent) => ({
-            agentId: agent.id,
-            token: deriveExecutorToken(application.transport.key, application.transport.tenant, agent.id),
-            implementationVersion: version,
-        }));
-        await application.transport.json("/v1/executors", "PUT", {
-            executors: registrations,
-        });
-        for (const agent of agents.values()) {
-            const token = deriveExecutorToken(application.transport.key, application.transport.tenant, agent.id);
-            const child = connectExecutorMode({
-                agents: [agent],
-                implementationVersion: version,
-                onError: options.onError,
-            }, {
-                url: application.transport.url,
-                tenant: application.transport.tenant,
-                key: token,
-                fetch: application.transport.fetcher,
-            }, new Map([[agent.id, agent]]));
-            children.push(child);
-        }
-        await Promise.all(children.map((child) => child.ready));
-        resolveReady();
-    })().catch((error) => {
-        rejectReady(error);
-    });
-    return {
-        ready,
-        async close() {
-            await boot.catch(() => { });
-            await Promise.allSettled(children.map((child) => child.close()));
-        },
-    };
-}
-export function connectAgents(options) {
-    const agents = buildAgents(options);
-    // D§7.2 mode table: runtime → executor; application → application;
-    // neither → resolveConnection() role.
-    if (options.runtime) {
-        return connectExecutorMode(options, options.runtime, agents);
-    }
-    if (options.application) {
-        return connectApplicationMode(options, options.application, agents);
-    }
-    let resolveReady;
-    let rejectReady;
-    const ready = new Promise((resolve, reject) => {
-        resolveReady = resolve;
-        rejectReady = reject;
-    });
-    void ready.catch(() => { });
-    let handle;
-    const boot = (async () => {
-        const connection = await resolveConnection();
-        if (connection.role === "executor") {
-            handle = connectExecutorMode(options, {
-                url: connection.url,
-                tenant: connection.tenant,
-                key: connection.key,
-            }, agents);
-        }
-        else {
-            const application = new AgentsClient({
-                url: connection.url,
-                tenant: connection.tenant,
-                key: connection.key,
-            });
-            handle = connectApplicationMode(options, application, agents);
-        }
-        await handle.ready;
-        resolveReady();
-    })().catch((error) => {
-        rejectReady(error);
-    });
-    return {
-        ready,
-        async close() {
-            await boot.catch(() => { });
-            await handle?.close();
-        },
-    };
-}
-export { deriveExecutorToken };

package/dist/mcp/mcp.d.ts

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

@@ -1,80 +0,0 @@
-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/sandbox/sandbox.d.ts

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

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