@nylorun/agents 0.4.0-beta → 0.6.0-beta

package/dist/connection.d.ts

@@ -0,0 +1,19 @@
+import type { ErrorCode } from "@nylorun/core/compatibility";
+export interface ResolvedConnection {
+    url: string;
+    tenant: string;
+    key: string;
+    role: "application" | "executor";
+    source: "options" | "environment" | "project-link";
+}
+export declare class ConnectionError extends Error {
+    readonly code: ErrorCode;
+    constructor(message: string);
+}
+/** Resolve Tenant API connection: options → environment → project link (D§7.1). */
+export declare function resolveConnection(options?: {
+    url?: string;
+    tenant?: string;
+    key?: string;
+    cwd?: string;
+}): Promise<ResolvedConnection>;

package/dist/connection.js

@@ -0,0 +1,98 @@
+import { readFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { ProjectCredentialsFileSchema, ProjectLinkFileSchema, } from "@nylorun/core/contracts";
+import { env } from "./http.js";
+export class ConnectionError extends Error {
+    code = "connection_missing";
+    constructor(message) {
+        super(message);
+        this.name = "ConnectionError";
+    }
+}
+function missing(tried) {
+    throw new ConnectionError(`connection_missing: no Runtime connection found (tried ${tried.join(", ")})`);
+}
+function stripTrailingSlash(url) {
+    return url.replace(/\/$/, "");
+}
+async function readProjectLink(startDir) {
+    let dir = resolve(startDir);
+    for (;;) {
+        const nylorun = join(dir, ".nylorun");
+        const linkPath = join(nylorun, "link.json");
+        let linkRaw;
+        try {
+            linkRaw = await readFile(linkPath, "utf8");
+        }
+        catch (error) {
+            if (error.code === "ENOENT") {
+                const parent = dirname(dir);
+                if (parent === dir)
+                    return undefined;
+                dir = parent;
+                continue;
+            }
+            throw error;
+        }
+        const link = ProjectLinkFileSchema.parse(JSON.parse(linkRaw));
+        const credentials = ProjectCredentialsFileSchema.parse(JSON.parse(await readFile(join(nylorun, "credentials.json"), "utf8")));
+        return {
+            url: stripTrailingSlash(link.hostUrl),
+            tenant: link.tenantId,
+            key: credentials.applicationKey,
+            role: "application",
+            source: "project-link",
+        };
+    }
+}
+/** Resolve Tenant API connection: options → environment → project link (D§7.1). */
+export async function resolveConnection(options) {
+    const tried = [];
+    const optionUrl = options?.url;
+    const optionTenant = options?.tenant;
+    const optionKey = options?.key;
+    const anyOption = optionUrl !== undefined ||
+        optionTenant !== undefined ||
+        optionKey !== undefined;
+    tried.push("options");
+    if (anyOption) {
+        if (optionUrl && optionTenant && optionKey) {
+            return {
+                url: stripTrailingSlash(optionUrl),
+                tenant: optionTenant,
+                key: optionKey,
+                role: "application",
+                source: "options",
+            };
+        }
+        missing(tried.concat(["environment", "project-link"]));
+    }
+    const envUrl = env("NYLORUN_RUNTIME_URL");
+    const envTenant = env("NYLORUN_TENANT");
+    const envServerKey = env("NYLORUN_SERVER_KEY");
+    const envExecutorKey = env("NYLORUN_EXECUTOR_KEY");
+    const anyEnv = envUrl !== undefined ||
+        envTenant !== undefined ||
+        envServerKey !== undefined ||
+        envExecutorKey !== undefined;
+    tried.push("environment");
+    if (anyEnv) {
+        const key = envExecutorKey ?? envServerKey;
+        if (envUrl && envTenant && key) {
+            return {
+                url: stripTrailingSlash(envUrl),
+                tenant: envTenant,
+                key,
+                role: envExecutorKey !== undefined ? "executor" : "application",
+                source: "environment",
+            };
+        }
+        missing(tried.concat(["project-link"]));
+    }
+    tried.push("project-link");
+    const cwd = options?.cwd ?? (typeof process !== "undefined" ? process.cwd() : ".");
+    const fromLink = await readProjectLink(cwd);
+    if (fromLink)
+        return fromLink;
+    missing(tried);
+}

package/dist/derived-credentials.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Deterministic executor token from an application key (D§7.3).
+ * Same key, Tenant and agent always produce the same token.
+ */
+export declare function deriveExecutorToken(applicationKey: string, tenantId: string, agentId: string): string;

package/dist/derived-credentials.js

@@ -0,0 +1,17 @@
+import { createHmac } from "node:crypto";
+/**
+ * Deterministic executor token from an application key (D§7.3).
+ * Same key, Tenant and agent always produce the same token.
+ */
+export function deriveExecutorToken(applicationKey, tenantId, agentId) {
+    const message = Buffer.concat([
+        Buffer.from("nylorun/executor/v1", "utf8"),
+        Buffer.from([0]),
+        Buffer.from(tenantId, "utf8"),
+        Buffer.from([0]),
+        Buffer.from(agentId, "utf8"),
+    ]);
+    return createHmac("sha256", Buffer.from(applicationKey, "utf8"))
+        .update(message)
+        .digest("hex");
+}

package/dist/execute-action.d.ts

@@ -1,4 +1,10 @@
-import { type BuiltAgent } from "@nylorun/core/define";
+import { type BuiltAgent, type BuiltWorkflow } from "@nylorun/core/define";
 import type { Action, ActionOutcome } from "@nylorun/core/contracts";
+import type { ActionSandbox } from "./sandbox/client.js";
+export type ExecutableDefinition = BuiltAgent | BuiltWorkflow;
+export type ExecuteActionOptions = {
+    /** Claim-scoped sandbox client; omitted when the session has no sandbox. */
+    readonly sandbox?: ActionSandbox;
+};
 /** Executes code only after a host-issued claim. No engine dependency. */
-export declare function executeAction(action: Action, agent: BuiltAgent, signal: AbortSignal): Promise<ActionOutcome>;
+export declare function executeAction(action: Action, root: ExecutableDefinition, signal: AbortSignal, options?: ExecuteActionOptions): Promise<ActionOutcome>;

package/dist/execute-action.js

@@ -1,4 +1,4 @@
-import { implementationsFor, isToolError, normalizeToolDefinition, normalizedSchemasFor, runHookPoint, } from "@nylorun/core/define";
+import { delegateOf, implementationsFor, isBuiltWorkflow, isToolError, normalizeToolDefinition, normalizedSchemasFor, runHookPoint, } from "@nylorun/core/define";
 class Suspend {
     outcome;
     constructor(outcome) {
@@ -9,7 +9,21 @@ const object = (value) => value !== null && typeof value === "object" && !Array.
     ? value
     : {};
 /** Executes code only after a host-issued claim. No engine dependency. */
-export async function executeAction(action, agent, signal) {
+export async function executeAction(action, root, signal, options = {}) {
+    const sandbox = options.sandbox;
+    if (action.kind === "fn" || action.kind === "verify") {
+        if (!isBuiltWorkflow(root))
+            throw new Error(`Action ${action.kind} requires a workflow definition`);
+        return executeWorkflowFn(action, root.getBinding(), signal, sandbox);
+    }
+    if (isBuiltWorkflow(root)) {
+        if (action.kind === "tool" && "key" in action && typeof action.key === "string")
+            return executeWorkflowTool(action, root.getBinding(), signal, sandbox);
+        throw new Error(`Unsupported action kind ${action.kind} on workflow`);
+    }
+    // Work for an agent used as a tool runs that agent's code, served from the root's binding.
+    const agent = action.agent ? delegatedAgent(root, action.agent.id) : root;
+    const ref = action.agent ?? { id: root.id, path: root.id };
     if (action.kind === "hook")
         // All capabilities at this hook point run concurrently in one action. Never throws.
         return {
@@ -17,6 +31,8 @@ export async function executeAction(action, agent, signal) {
                 results: await runHookPoint(implementationsFor(agent), action.hook, action.input),
             },
         };
+    if (action.kind !== "tool" || !("capabilityId" in action))
+        throw new Error(`Unsupported action kind ${action.kind}`);
     const impl = implementationsFor(agent)[action.capabilityId];
     if (!impl)
         throw new Error(`No capability ${action.capabilityId}`);
@@ -24,7 +40,25 @@ export async function executeAction(action, agent, signal) {
     if (!raw)
         throw new Error("Missing tool implementation");
     const tool = normalizeToolDefinition(raw);
-    const schemas = normalizedSchemasFor(tool);
+    return runTool(action, tool, ref, signal, sandbox);
+}
+async function executeWorkflowTool(action, binding, signal, sandbox) {
+    const impl = binding.nodes[action.key];
+    if (!impl || impl.kind !== "tool")
+        throw new Error(`No tool implementation for key ${action.key}`);
+    const path = "path" in action && typeof action.path === "string" ? action.path : action.key;
+    return runTool(action, impl.tool, { id: action.agentId, path }, signal, sandbox);
+}
+async function runTool(action, raw, ref, signal, sandbox) {
+    const tool = "execute" in raw && typeof raw.execute === "function" && "inputSchema" in raw
+        ? raw
+        : normalizeToolDefinition(raw);
+    const schemas = "inputSchema" in tool && tool.inputSchema && "validate" in tool.inputSchema
+        ? {
+            inputSchema: tool.inputSchema,
+            outputSchema: "outputSchema" in tool ? tool.outputSchema : undefined,
+        }
+        : normalizedSchemasFor(tool);
     const input = schemas.inputSchema.validate(action.input);
     if (!input.ok)
         return {
@@ -77,7 +111,9 @@ export async function executeAction(action, agent, signal) {
         signal,
         info: ctx.info,
         session: { id: action.sessionId },
+        agent: ref,
         ...(ctx.resume ? { resume: ctx.resume } : {}),
+        ...(sandbox ? { sandbox } : {}),
         state: {
             get: (key) => state[key],
             set: (key, value) => {
@@ -115,14 +151,17 @@ export async function executeAction(action, agent, signal) {
     };
     try {
         signal.throwIfAborted();
-        if (tool.approval && !gateApproved) {
-            const approval = await tool.approval(input.value);
-            if (approval)
+        const approval = "approval" in tool ? tool.approval : undefined;
+        if (approval && !gateApproved) {
+            const result = await approval(input.value);
+            if (result)
                 throw new Suspend({
                     kind: "interaction-required",
                     interaction: {
                         kind: "approval",
-                        prompt: typeof approval === "string" ? approval : `Approve ${tool.name}?`,
+                        prompt: typeof result === "string"
+                            ? result
+                            : `Approve ${"name" in tool ? tool.name : "tool"}?`,
                     },
                     token: durableToken({ approvalGate: true }),
                 });
@@ -130,7 +169,12 @@ export async function executeAction(action, agent, signal) {
         }
         if (resume.kind === "approval" && resume.approved === false)
             return { value: { kind: "denied", reason: "Approval denied" } };
-        const value = await tool.execute(input.value, context);
+        const execute = "execute" in tool && typeof tool.execute === "function"
+            ? tool.execute
+            : undefined;
+        if (!execute)
+            throw new Error("Missing tool implementation");
+        const value = await execute(input.value, context);
         const tagged = object(value);
         let outcome;
         if ([
@@ -170,6 +214,51 @@ export async function executeAction(action, agent, signal) {
         };
     }
 }
+async function executeWorkflowFn(action, binding, signal, sandbox) {
+    const impl = binding.nodes[action.key];
+    if (!impl || impl.kind !== action.kind)
+        throw new Error(`No ${action.kind} implementation for key ${action.key}`);
+    signal.throwIfAborted();
+    try {
+        // Verify may receive a tool-like context later (L3/L4); tracer passes input only.
+        const value = action.kind === "verify"
+            ? await impl.fn(action.input, {
+                signal,
+                info: action.context.info,
+                session: { id: action.sessionId },
+                ...(sandbox ? { sandbox } : {}),
+                step: async (_name, fn) => fn(),
+                approve: async () => {
+                    throw new Error("Approvals in verify are not available in the tracer");
+                },
+                ask: async () => {
+                    throw new Error("ask in verify is not available in the tracer");
+                },
+                progress() { },
+            })
+            : await impl.fn(action.input);
+        return { value };
+    }
+    catch (error) {
+        if (signal.aborted)
+            throw signal.reason;
+        return {
+            value: {
+                kind: "failed",
+                code: action.kind === "verify" ? "loop.verify-failed" : "fn.failed",
+                message: message(error),
+            },
+        };
+    }
+}
+function delegatedAgent(root, id) {
+    for (const capability of Object.values(implementationsFor(root))) {
+        const child = delegateOf(capability.tools?.[id])?.agent;
+        if (child)
+            return child;
+    }
+    throw new Error(`Agent '${root.id}' does not use '${id}' as a tool`);
+}
 function message(error) {
     return error instanceof Error ? error.message : String(error);
 }

package/dist/executor.d.ts

@@ -1,7 +1,11 @@
-import { type AgentSource } from "./client.js";
+import { type BuiltWorkflow } from "@nylorun/core/define";
+import { AgentsClient, type AgentSource } from "./client.js";
+import { deriveExecutorToken } from "./derived-credentials.js";
 import { type Destination } from "./http.js";
 export interface ConnectOptions {
-    agents: readonly AgentSource[];
+    agents: readonly (AgentSource | BuiltWorkflow)[];
+    /** Application-mode client; when set, connectAgents uses application mode (D§7.2). */
+    application?: AgentsClient;
     runtime?: Destination;
     implementationVersion?: string;
     onError?: (error: unknown) => void;
@@ -13,3 +17,4 @@ export interface AgentConnection {
     close(): Promise<void>;
 }
 export declare function connectAgents(options: ConnectOptions): AgentConnection;
+export { deriveExecutorToken };

package/dist/executor.js

@@ -1,24 +1,53 @@
 import { AgentManifestSchema, ActionSchema, ActionClaimResponseSchema, } from "@nylorun/core/contracts";
-import { assertNoMiddlewareClosures } from "./client.js";
+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";
-export function connectAgents(options) {
-    const transport = new Transport(options.runtime, "executor");
-    const version = options.implementationVersion ??
+import { createActionSandbox, definitionDeclaresSandbox, } from "./sandbox/client.js";
+function implementationVersionOf(options) {
+    return (options.implementationVersion ??
         env("NYLORUN_IMPLEMENTATION_VERSION") ??
-        "dev";
+        "dev");
+}
+function buildAgents(options) {
     const agents = new Map();
-    for (const source of options.agents) {
-        const built = source.build?.() ?? source;
+    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();
@@ -125,7 +154,17 @@ export function connectAgents(options) {
                     report(error);
                 }
             });
-            const outcome = await executeAction(claim.action, agent, work.signal);
+            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",
@@ -214,3 +253,101 @@ export function connectAgents(options) {
         },
     };
 }
+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/http.d.ts

@@ -1,6 +1,8 @@
+import { type Compatibility, type ProtocolRange } from "@nylorun/core/compatibility";
 export interface Destination {
     url?: string;
     key?: string;
+    tenant?: string;
     fetch?: typeof fetch;
 }
 export declare function env(name: string): string | undefined;
@@ -9,12 +11,30 @@ export declare class RuntimeError extends Error {
     readonly body: unknown;
     constructor(status: number, body: unknown);
 }
+export type IncompatibleReason = Extract<Compatibility, {
+    ok: false;
+}>;
+/** Host protocol is outside the client's supported range or missing required features. */
+export declare class IncompatibleRuntimeError extends Error {
+    readonly compatibility: IncompatibleReason;
+    readonly remedy: string;
+    readonly host: ProtocolRange;
+    constructor(compatibility: IncompatibleReason);
+}
 export declare class Transport {
     readonly url: string;
     readonly key: string;
+    readonly tenant: string;
     readonly fetcher: typeof fetch;
+    private compatible;
     constructor(options?: Destination, role?: "server" | "executor");
-    request(path: string, init?: RequestInit): Promise<Response>;
+    /** Clears the cached Host compatibility result (used after a 426). */
+    clearCompatibilityCache(): void;
+    private ensureCompatible;
+    private authHeaders;
+    request(path: string, init?: RequestInit, options?: {
+        retried426?: boolean;
+    }): Promise<Response>;
     json<T>(path: string, method?: string, body?: unknown, signal?: AbortSignal): Promise<T>;
 }
 export declare const id: () => `${string}-${string}-${string}-${string}-${string}`;