@nylorun/agents 0.19.1-beta → 0.20.0-beta

package/dist/session-client.js

@@ -1,10 +1,10 @@
-import { SANDBOX_TOOL_NAMES, codeToolRefusal, delegateOf, isBuiltWorkflow, isSandboxToolName, } from "@nylorun/core/define";
+import { SANDBOX_TOOL_NAMES, approvalRefusal, codeToolRefusal, delegateOf, isBuiltWorkflow, isSandboxToolName, } from "@nylorun/core/define";
 import { z } from "zod";
 import { SCOPES_HEADER, SUBJECT_HEADER } from "@nylorun/core/compatibility";
-import { SessionManifestViewSchema, SessionUsageTotalsSchema, ModelCallsPageSchema, parseSessionEvent, parseSubjectHeaders, } from "@nylorun/core/contracts";
+import { SessionManifestViewSchema, SessionUsageTotalsSchema, ModelCallsPageSchema, ToolCallsPageSchema, TurnTraceSchema, parseSessionEvent, parseSubjectHeaders, } from "@nylorun/core/contracts";
 import { SessionsReadClient } from "./reads.js";
 import { AccessClient } from "./access.js";
-import { SandboxesClient } from "./sandboxes.js";
+import { EnvironmentsClient } from "./environments.js";
 import { ArtifactsClient } from "./artifacts.js";
 import { FilesClient } from "./files.js";
 import { Transport, env, id, segment } from "./http.js";
@@ -74,7 +74,7 @@ export class AgentsClient {
     /**
      * A client that acts for `subject`: every call sends `Nylorun-Subject` and
      * `Nylorun-Scopes`, and the Runtime limits it to the scopes and to the subject's own sessions
-     * and vaults (Host feature `subject-headers`). For app servers, which authenticate the person
+     * (Host feature `subject-headers`). For app servers, which authenticate the person
      * themselves and hold the key; nothing is minted, cached or refreshed.
      */
     as(subject, options = {}) {
@@ -98,11 +98,12 @@ export class AgentsClient {
         return new AccessClient(this.transport);
     }
     /**
-     * Sandboxes as a resource (Host feature `sandboxes`): `ensure` one by id, `list` them by
-     * label, `delete` one, or give a session its own with `forSession`.
+     * Environments (protocol 11): `put` one by id (create, find or change), write its `secrets`,
+     * `list` them by label, `stop`, `reset` or `delete` one, or give a session its own with
+     * `forSession`.
      */
-    get sandboxes() {
-        return new SandboxesClient(this.transport, (options) => this.createSession(options));
+    get environments() {
+        return new EnvironmentsClient(this.transport, (options) => this.createSession(options));
     }
     /** File artifacts: upload, list, download with Range, capability links (protocol 6). */
     get artifacts() {
@@ -132,7 +133,7 @@ export class AgentsClient {
      * Registers the agent's definition (`PUT /v1/agents/{id}`), first uploading the skill files
      * it names that the Runtime does not hold. A definition with a tool that runs your code
      * (`tool({ run })`, a flow's tool stage) is refused before anything is sent: the Runtime runs
-     * no code of yours during a session. `implementationVersion` defaults to
+     * agents from their manifests alone. `implementationVersion` defaults to
      * `NYLORUN_IMPLEMENTATION_VERSION`, else `dev`.
      */
     async saveAgent(agent, options = {}) {
@@ -149,7 +150,8 @@ export class AgentsClient {
             assertNoMiddlewareClosures(agent);
             skillFilesOf(agent, files);
         }
-        const refusal = codeToolRefusal(agent.manifest);
+        const refusal = codeToolRefusal(agent.manifest) ??
+            approvalRefusal(agent.manifest);
         if (refusal)
             throw new Error(refusal);
         await this.files.ensure(files);
@@ -166,11 +168,7 @@ export class AgentsClient {
             agentId: options.agentId,
             ownerUserId: options.ownerUserId,
             ...(options.info ? { info: options.info } : {}),
-            ...(options.vaultIds ? { vaultIds: options.vaultIds } : {}),
-            ...(options.credentialSelections
-                ? { credentialSelections: options.credentialSelections }
-                : {}),
-            ...(options.sandbox === undefined ? {} : { sandbox: options.sandbox }),
+            ...(options.environment === undefined ? {} : { environment: options.environment }),
         });
         return this.session(sessionId);
     }
@@ -274,6 +272,28 @@ export class SessionClient {
             query.set("cursor", options.cursor);
         return ModelCallsPageSchema.parse(await this.transport.json(`${this.path}/calls/model?${query}`, "GET", undefined, options.signal));
     }
+    /**
+     * The session's tool calls (R5, Host feature `tool-calls`), in the order they were first sent:
+     * each one's tool, input, status and sends. `attempts` above 1: a crash re-sent it.
+     */
+    async toolCalls(options = {}) {
+        await this.transport.requireFeature("tool-calls", options.signal);
+        const query = new URLSearchParams({ limit: String(options.limit ?? 50) });
+        if (options.turnId !== undefined)
+            query.set("turnId", options.turnId);
+        if (options.cursor !== undefined)
+            query.set("cursor", options.cursor);
+        return ToolCallsPageSchema.parse(await this.transport.json(`${this.path}/calls/tool?${query}`, "GET", undefined, options.signal));
+    }
+    /**
+     * A turn's trace (R7, Host feature `traces`): its spans as OTLP/HTTP JSON (`resourceSpans`), as
+     * the Runtime posts them to an OTLP collector. Post it to a collector's `/v1/traces` to backfill
+     * one, or read it without one.
+     */
+    async trace(turnId, options = {}) {
+        await this.transport.requireFeature("traces", options.signal);
+        return TurnTraceSchema.parse(await this.transport.json(`${this.path}/turns/${encodeURIComponent(turnId)}/trace`, "GET", undefined, options.signal));
+    }
     async history(options = {}) {
         const query = new URLSearchParams();
         if (options.cursor)
@@ -372,4 +392,4 @@ export class SessionClient {
 }
 export { RuntimeError, IncompatibleRuntimeError } from "./http.js";
 export { AccessClient } from "./access.js";
-export { SandboxesClient } from "./sandboxes.js";
+export { EnvironmentSecretsClient, EnvironmentsClient } from "./environments.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nylorun/agents",
-  "version": "0.19.1-beta",
+  "version": "0.20.0-beta",
   "description": "Nylorun agent definitions and session client",
   "type": "module",
   "license": "Apache-2.0",
@@ -43,14 +43,14 @@
     "test": "vitest run --passWithNoTests"
   },
   "dependencies": {
-    "@nylorun/core": "0.19.0-beta",
+    "@nylorun/core": "0.20.0-beta",
     "gray-matter": "^4.0.3"
   },
   "peerDependencies": {
     "zod": "^4.6.5"
   },
   "devDependencies": {
-    "@types/node": "^24.0.0",
+    "@types/node": "^26.6.4",
     "typescript": "npm:@typescript/typescript6@^6.0.2",
     "vitest": "^5.0.2"
   },
@@ -60,7 +60,7 @@
   "repository": {
     "type": "git",
     "url": "git+https://github.com/nylorun/agents.git",
-    "directory": "agents"
+    "directory": "sdks/agents"
   },
   "publishConfig": {
     "access": "public",

package/dist/sandboxes.d.ts

@@ -1,106 +0,0 @@
-/**
- * Sandboxes as a resource (Host feature `sandboxes`): `client.sandboxes`. A sandbox has its own
- * id and outlives the sessions attached to it; whether it serves one session, one person or a
- * project is the app's choice, made here:
- *
- * - `sandboxes.forSession(...)`: one sandbox for one session. It creates the sandbox, opens the
- *   session attached to it, and `release()` deletes the sandbox when the session is done. It
- *   replaces sharing through another session (`sandbox: { session }`, `sandboxOwnerId`).
- * - `sandboxes.ensure(id, spec)`: one sandbox per person or per project, by a deterministic id
- *   (`user-42`, `team-a/proj-42`); get-or-create in one call. Attach sessions to it with
- *   `createSession({ sandbox: { id } })`.
- *
- * Ids may hold `/`; they are sent percent-encoded as one path segment.
- */
-import { type DeleteSandboxResponse, type PutSandboxRequest, type SandboxEvent, type SandboxView } from "@nylorun/core/contracts";
-import { type Transport } from "./http.js";
-import type { CreateSessionOptions, SessionClient } from "./session-client.js";
-/** What a sandbox is made of: fixed once it exists, except its labels. */
-export type SandboxSpec = Omit<PutSandboxRequest, "requestId">;
-/** A session opened on a sandbox of its own (`sandboxes.forSession`). */
-export interface SessionSandboxHandle {
-    readonly session: SessionClient;
-    readonly sandbox: SandboxView;
-    /** Deletes the sandbox and its files; call it when the session is done. */
-    release(options?: {
-        signal?: AbortSignal;
-    }): Promise<DeleteSandboxResponse>;
-}
-export interface ForSessionOptions {
-    /** The session to open, as `createSession` takes it, without `sandbox`. */
-    readonly session: Omit<CreateSessionOptions, "sandbox">;
-    /** The sandbox's spec and labels. Default: a virtual sandbox within the Tenant's defaults. */
-    readonly spec?: SandboxSpec;
-    /** The sandbox's id. Default: `sessions/<session id>`. */
-    readonly sandboxId?: string;
-    readonly signal?: AbortSignal;
-}
-export declare class SandboxesClient {
-    private readonly transport;
-    /** `AgentsClient.createSession`, bound. */
-    private readonly createSession;
-    constructor(transport: Transport, 
-    /** `AgentsClient.createSession`, bound. */
-    createSession: (options: CreateSessionOptions) => Promise<SessionClient>);
-    private path;
-    /**
-     * Creates the sandbox, or finds the one with this id (`PUT /v1/sandboxes/{id}`). Its spec is
-     * fixed once it exists: a different one is a 409. Labels, when given, replace its labels.
-     */
-    ensure(sandboxId: string, spec?: SandboxSpec, options?: {
-        signal?: AbortSignal;
-    }): Promise<SandboxView>;
-    get(sandboxId: string, options?: {
-        signal?: AbortSignal;
-    }): Promise<SandboxView>;
-    /** The sandboxes with every label in `labels` that this client reaches. */
-    list(options?: {
-        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;
-    }): Promise<DeleteSandboxResponse>;
-    /** The sandbox's lifecycle events, from `from` on. */
-    events(sandboxId: string, options?: {
-        from?: number;
-        signal?: AbortSignal;
-    }): Promise<SandboxEvent[]>;
-    /**
-     * One sandbox for one session: creates the sandbox (`sessions/<session id>` unless
-     * `sandboxId` names another), opens the session attached to it, and returns both with
-     * `release()`, which deletes the sandbox. If the session cannot be opened, the sandbox is
-     * deleted again.
-     */
-    forSession(options: ForSessionOptions): Promise<SessionSandboxHandle>;
-}

package/dist/sandboxes.js

@@ -1,109 +0,0 @@
-/**
- * Sandboxes as a resource (Host feature `sandboxes`): `client.sandboxes`. A sandbox has its own
- * id and outlives the sessions attached to it; whether it serves one session, one person or a
- * project is the app's choice, made here:
- *
- * - `sandboxes.forSession(...)`: one sandbox for one session. It creates the sandbox, opens the
- *   session attached to it, and `release()` deletes the sandbox when the session is done. It
- *   replaces sharing through another session (`sandbox: { session }`, `sandboxOwnerId`).
- * - `sandboxes.ensure(id, spec)`: one sandbox per person or per project, by a deterministic id
- *   (`user-42`, `team-a/proj-42`); get-or-create in one call. Attach sessions to it with
- *   `createSession({ sandbox: { id } })`.
- *
- * Ids may hold `/`; they are sent percent-encoded as one path segment.
- */
-import { SandboxPageSchema, isSandboxId, } from "@nylorun/core/contracts";
-import { id, segment } from "./http.js";
-const FEATURE = "sandboxes";
-export class SandboxesClient {
-    transport;
-    createSession;
-    constructor(transport, 
-    /** `AgentsClient.createSession`, bound. */
-    createSession) {
-        this.transport = transport;
-        this.createSession = createSession;
-    }
-    path(sandboxId) {
-        if (!isSandboxId(sandboxId))
-            throw new TypeError(`${sandboxId} is not a sandbox id: up to 200 characters, /-separated segments of letters, digits, '.', '_' and '-'`);
-        return `/v1/sandboxes/${segment(sandboxId)}`;
-    }
-    /**
-     * Creates the sandbox, or finds the one with this id (`PUT /v1/sandboxes/{id}`). Its spec is
-     * fixed once it exists: a different one is a 409. Labels, when given, replace its labels.
-     */
-    async ensure(sandboxId, spec = {}, options = {}) {
-        const path = this.path(sandboxId);
-        await this.transport.requireFeature(FEATURE, options.signal);
-        return this.transport.json(path, "PUT", { requestId: id(), ...spec }, options.signal);
-    }
-    async get(sandboxId, options = {}) {
-        const path = this.path(sandboxId);
-        await this.transport.requireFeature(FEATURE, options.signal);
-        return this.transport.json(path, "GET", undefined, options.signal);
-    }
-    /** The sandboxes with every label in `labels` that this client reaches. */
-    async list(options = {}) {
-        await this.transport.requireFeature(FEATURE, options.signal);
-        const query = new URLSearchParams();
-        for (const [key, value] of Object.entries(options.labels ?? {}))
-            query.append("label", `${key}=${value}`);
-        const search = query.toString();
-        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);
-        await this.transport.requireFeature(FEATURE, options.signal);
-        return this.transport.json(path, "DELETE", undefined, options.signal);
-    }
-    /** The sandbox's lifecycle events, from `from` on. */
-    async events(sandboxId, options = {}) {
-        const path = this.path(sandboxId);
-        await this.transport.requireFeature(FEATURE, options.signal);
-        const reply = await this.transport.json(`${path}/events${options.from === undefined ? "" : `?from=${options.from}`}`, "GET", undefined, options.signal);
-        return reply.events;
-    }
-    /**
-     * One sandbox for one session: creates the sandbox (`sessions/<session id>` unless
-     * `sandboxId` names another), opens the session attached to it, and returns both with
-     * `release()`, which deletes the sandbox. If the session cannot be opened, the sandbox is
-     * deleted again.
-     */
-    async forSession(options) {
-        const sessionId = options.session.id ?? id();
-        const sandboxId = options.sandboxId ??
-            (isSandboxId(`sessions/${sessionId}`) ? `sessions/${sessionId}` : `sessions/${id()}`);
-        const sandbox = await this.ensure(sandboxId, options.spec ?? {}, {
-            ...(options.signal ? { signal: options.signal } : {}),
-        });
-        let session;
-        try {
-            session = await this.createSession({
-                ...options.session,
-                id: sessionId,
-                sandbox: { id: sandboxId },
-            });
-        }
-        catch (error) {
-            await this.delete(sandboxId).catch(() => undefined);
-            throw error;
-        }
-        return {
-            session,
-            sandbox,
-            release: (release = {}) => this.delete(sandboxId, release),
-        };
-    }
-}