@nylorun/agents 0.19.1-beta → 0.20.0-beta

package/dist/artifacts.js

@@ -1,3 +1,17 @@
+/**
+ * Artifacts (protocol 6): `client.artifacts`. A file is uploaded in one streamed request and
+ * kept as an artifact with numbered versions; a session's artifacts appear in its history as
+ * `artifact.*` events. Download through the Runtime (with Range), or mint a capability link: a
+ * short-lived URL that needs no credential, for `<img>` tags and sharing. A message names an
+ * artifact in a file part (`session.inputParts`), and the model reads it.
+ *
+ * Folders (F8.2): at the end of each turn the Runtime exports `/workspace/outputs` of the
+ * session's sandbox as a version of its `outputs` folder. Read one as a tree, one file by path,
+ * a diff between versions or a zip.
+ *
+ * Acting for a person (`client.as`, or a trusted issuer's token), only the artifacts of their own sessions.
+ */
+import { ArtifactPageSchema, } from "@nylorun/core/contracts";
 import { segment } from "./http.js";
 function contentTypeOf(body, declared) {
     if (declared)
@@ -46,6 +60,20 @@ export class ArtifactsClient {
         const reply = await this.transport.json(`/v1/artifacts${query}`, "GET", undefined, options.signal);
         return reply.artifacts;
     }
+    /** Newest first, with metadata only (Host feature `artifact-reads`). */
+    async page(options = {}) {
+        await this.transport.requireFeature("artifact-reads", options.signal);
+        const query = new URLSearchParams({ limit: String(options.limit ?? 50) });
+        if (options.cursor !== undefined)
+            query.set("cursor", options.cursor);
+        if (options.sessionId !== undefined)
+            query.set("sessionId", options.sessionId);
+        if (options.kind !== undefined)
+            query.set("kind", options.kind);
+        for (const [key, value] of Object.entries(options.labels ?? {}))
+            query.append("label", `${key}=${value}`);
+        return ArtifactPageSchema.parse(await this.transport.json(`/v1/artifacts?${query}`, "GET", undefined, options.signal));
+    }
     /** The artifact, with every version. */
     get(artifactId, options = {}) {
         return this.transport.json(`/v1/artifacts/${segment(artifactId)}`, "GET", undefined, options.signal);

package/dist/environments.d.ts

@@ -0,0 +1,217 @@
+/**
+ * Environments (protocol 11, D55, D56): `client.environments`. An Environment is one sandbox
+ * (kind `virtual`, `pod` or `none`) with a recipe that can change, and one vault of secrets for
+ * its shell, MCP servers and HTTP tools. It has its own id and outlives the sessions that name
+ * it; whether it serves one session, one person or a project is the app's choice, made here:
+ *
+ * - `environments.forSession(...)`: one Environment for one session. It creates the
+ *   Environment, opens the session on it, and `release()` deletes the Environment (and its
+ *   vault) when the session is done.
+ * - `environments.put(id, recipe)`: one Environment per person or per project, by a
+ *   deterministic id (`users/alice/web`); get-or-create, or change its recipe, in one call.
+ *   Write its secrets with `environments.secrets.put(id, name, secret)` and open sessions on it
+ *   with `createSession({ environment: id })`.
+ *
+ * Ids may hold `/`; they are sent percent-encoded as one path segment. Secret values are
+ * write-only: no call reads one back.
+ *
+ * Disk versions (Host feature `environment-disk-versions`): `snapshot(id)` keeps a version of
+ * the Environment's disk between turns, `restore(id, version)` puts one back, and
+ * `put(id, { from: { environment, version } })` creates a new Environment from another's version.
+ */
+import { type DeleteEnvironmentResponse, type EnvironmentEvent, type EnvironmentRestore, type EnvironmentSecretView, type EnvironmentSnapshot, type EnvironmentVersions, type EnvironmentView, type PutEnvironmentRequest, type PutEnvironmentSecretRequest } from "@nylorun/core/contracts";
+import { type Transport } from "./http.js";
+import type { CreateSessionOptions, SessionClient } from "./session-client.js";
+/** What an Environment is made of: its kind, recipe, labels and owner guard. */
+export type EnvironmentRecipeInput = Omit<PutEnvironmentRequest, "requestId">;
+/** One secret of an Environment's vault, as written. */
+export type EnvironmentSecretInput = PutEnvironmentSecretRequest;
+/** A session opened on an Environment of its own (`environments.forSession`). */
+export interface SessionEnvironmentHandle {
+    readonly session: SessionClient;
+    readonly environment: EnvironmentView;
+    /** Deletes the Environment, its vault and its files; call it when the session is done. */
+    release(options?: {
+        signal?: AbortSignal;
+    }): Promise<DeleteEnvironmentResponse>;
+}
+export interface ForSessionOptions {
+    /** The session to open, as `createSession` takes it, without `environment`. */
+    readonly session: Omit<CreateSessionOptions, "environment">;
+    /** The Environment's recipe and labels. Default: a virtual one within the Tenant's defaults. */
+    readonly recipe?: EnvironmentRecipeInput;
+    /** Secrets to write before the session opens, by name. */
+    readonly secrets?: Readonly<Record<string, EnvironmentSecretInput>>;
+    /** The Environment's id. Default: `sessions/<session id>`. */
+    readonly environmentId?: string;
+    readonly signal?: AbortSignal;
+}
+/** An Environment's secrets: `client.environments.secrets`. */
+export declare class EnvironmentSecretsClient {
+    private readonly transport;
+    private readonly path;
+    constructor(transport: Transport, path: (environmentId: string) => string);
+    /**
+     * Creates or replaces secret `name` (`PUT /v1/environments/{id}/secrets/{name}`): for
+     * `environment_secret` and `environment_variable` the name is the variable's. A second
+     * credential for a host or a URL is a 409 `credential_conflict`.
+     */
+    put(environmentId: string, name: string, secret: EnvironmentSecretInput, options?: {
+        signal?: AbortSignal;
+    }): Promise<EnvironmentSecretView>;
+    /** The secrets' names, types and bindings; never a value. */
+    list(environmentId: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<EnvironmentSecretView[]>;
+    get(environmentId: string, name: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<EnvironmentSecretView>;
+    delete(environmentId: string, name: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<{
+        id: string;
+    }>;
+}
+export declare class EnvironmentsClient {
+    private readonly transport;
+    /** `AgentsClient.createSession`, bound. */
+    private readonly createSession;
+    constructor(transport: Transport, 
+    /** `AgentsClient.createSession`, bound. */
+    createSession: (options: CreateSessionOptions) => Promise<SessionClient>);
+    private path;
+    /** The Environment's secrets. */
+    get secrets(): EnvironmentSecretsClient;
+    /**
+     * Creates the Environment and its vault, or finds the one with this id
+     * (`PUT /v1/environments/{id}`). On an existing one, `kind` and `storage` are fixed (a
+     * different one is a 409), labels replace, and any other change writes the recipe and bumps
+     * its `version`: a pod's image and resources apply when it next starts from stopped.
+     */
+    put(environmentId: string, recipe?: EnvironmentRecipeInput, options?: {
+        signal?: AbortSignal;
+    }): Promise<EnvironmentView>;
+    get(environmentId: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<EnvironmentView>;
+    /** The Environments with every label in `labels` that this client reaches. */
+    list(options?: {
+        labels?: Readonly<Record<string, string>>;
+        signal?: AbortSignal;
+    }): Promise<EnvironmentView[]>;
+    page(options?: {
+        labels?: Readonly<Record<string, string>>;
+        limit?: number;
+        cursor?: string;
+        signal?: AbortSignal;
+    }): Promise<{
+        environments: {
+            id: string;
+            kind: "none" | "pod" | "virtual";
+            labels: Record<string, string>;
+            recipe: {
+                image?: string | undefined;
+                resources?: {
+                    cpus: number;
+                    memory: string;
+                } | undefined;
+                storage?: string | undefined;
+                network?: {
+                    allowedHosts: string[];
+                } | undefined;
+                harness: string;
+                lifecycle: {
+                    idle?: string | undefined;
+                    deleteAfter?: string | undefined;
+                };
+                setup?: {
+                    command: string;
+                    cwd?: string | undefined;
+                    timeout?: string | undefined;
+                }[] | undefined;
+                files?: {
+                    artifactId: string;
+                    version: number;
+                    path: string;
+                }[] | undefined;
+            };
+            version: number;
+            appliedVersion: number;
+            ownerUserId: string | null;
+            state: string;
+            pod?: {
+                desired: "deleted" | "running" | "suspended";
+                observed: "creating" | "deleting" | "failed" | "lost" | "running" | "suspended";
+                volumeGeneration: number;
+                hostEpoch: number;
+                reason?: string | undefined;
+            } | undefined;
+            lastUsedAt: string;
+            disk?: {
+                latestVersion: number | null;
+                operation?: {
+                    kind: "restore" | "seed" | "snapshot";
+                    version?: number | undefined;
+                    startedAt: string;
+                } | undefined;
+            } | undefined;
+            sessions: {
+                id: string;
+                activeTurnId: string | null;
+            }[];
+            createdAt: string;
+            updatedAt: string;
+        }[];
+        nextCursor: string | null;
+    }>;
+    /** Stops a pod Environment: its volume is kept, and the next turn starts it again. */
+    stop(environmentId: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<EnvironmentView>;
+    /** Resets a pod Environment: a new pod on a new, empty volume, with its recipe applied. */
+    reset(environmentId: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<EnvironmentView>;
+    /**
+     * Keeps a version of the Environment's disk (`POST /v1/environments/{id}/snapshot`), between
+     * turns; `unchanged` when the disk is as the latest version has it.
+     */
+    snapshot(environmentId: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<EnvironmentSnapshot>;
+    /**
+     * Puts disk version `version` back: at once for a virtual Environment (`done`), on a new volume
+     * seeded before the next turn for a pod (`pending`).
+     */
+    restore(environmentId: string, version: number | "latest", options?: {
+        signal?: AbortSignal;
+    }): Promise<EnvironmentRestore>;
+    /** The Environment's disk versions, newest first. */
+    versions(environmentId: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<EnvironmentVersions>;
+    /** Deletes disk version `version`; `deleted` is false when there was none. */
+    deleteVersion(environmentId: string, version: number, options?: {
+        signal?: AbortSignal;
+    }): Promise<{
+        environmentId: string;
+        version: number;
+        deleted: boolean;
+    }>;
+    /** Deletes the Environment, its vault and its files; `deleted` is false when there was none. */
+    delete(environmentId: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<DeleteEnvironmentResponse>;
+    /** The Environment's lifecycle events, from `from` on. */
+    events(environmentId: string, options?: {
+        from?: number;
+        signal?: AbortSignal;
+    }): Promise<EnvironmentEvent[]>;
+    /**
+     * One Environment for one session: creates the Environment (`sessions/<session id>` unless
+     * `environmentId` names another), writes `secrets`, opens the session on it, and returns both
+     * with `release()`, which deletes the Environment. If the session cannot be opened, the
+     * Environment is deleted again.
+     */
+    forSession(options: ForSessionOptions): Promise<SessionEnvironmentHandle>;
+}

package/dist/environments.js

@@ -0,0 +1,174 @@
+/**
+ * Environments (protocol 11, D55, D56): `client.environments`. An Environment is one sandbox
+ * (kind `virtual`, `pod` or `none`) with a recipe that can change, and one vault of secrets for
+ * its shell, MCP servers and HTTP tools. It has its own id and outlives the sessions that name
+ * it; whether it serves one session, one person or a project is the app's choice, made here:
+ *
+ * - `environments.forSession(...)`: one Environment for one session. It creates the
+ *   Environment, opens the session on it, and `release()` deletes the Environment (and its
+ *   vault) when the session is done.
+ * - `environments.put(id, recipe)`: one Environment per person or per project, by a
+ *   deterministic id (`users/alice/web`); get-or-create, or change its recipe, in one call.
+ *   Write its secrets with `environments.secrets.put(id, name, secret)` and open sessions on it
+ *   with `createSession({ environment: id })`.
+ *
+ * Ids may hold `/`; they are sent percent-encoded as one path segment. Secret values are
+ * write-only: no call reads one back.
+ *
+ * Disk versions (Host feature `environment-disk-versions`): `snapshot(id)` keeps a version of
+ * the Environment's disk between turns, `restore(id, version)` puts one back, and
+ * `put(id, { from: { environment, version } })` creates a new Environment from another's version.
+ */
+import { EnvironmentPageSchema, isEnvironmentId, } from "@nylorun/core/contracts";
+import { id, segment } from "./http.js";
+/** An Environment's secrets: `client.environments.secrets`. */
+export class EnvironmentSecretsClient {
+    transport;
+    path;
+    constructor(transport, path) {
+        this.transport = transport;
+        this.path = path;
+    }
+    /**
+     * Creates or replaces secret `name` (`PUT /v1/environments/{id}/secrets/{name}`): for
+     * `environment_secret` and `environment_variable` the name is the variable's. A second
+     * credential for a host or a URL is a 409 `credential_conflict`.
+     */
+    async put(environmentId, name, secret, options = {}) {
+        return this.transport.json(`${this.path(environmentId)}/secrets/${segment(name)}`, "PUT", { requestId: id(), ...secret }, options.signal);
+    }
+    /** The secrets' names, types and bindings; never a value. */
+    async list(environmentId, options = {}) {
+        const reply = await this.transport.json(`${this.path(environmentId)}/secrets`, "GET", undefined, options.signal);
+        return reply.secrets;
+    }
+    async get(environmentId, name, options = {}) {
+        return this.transport.json(`${this.path(environmentId)}/secrets/${segment(name)}`, "GET", undefined, options.signal);
+    }
+    async delete(environmentId, name, options = {}) {
+        return this.transport.json(`${this.path(environmentId)}/secrets/${segment(name)}`, "DELETE", undefined, options.signal);
+    }
+}
+export class EnvironmentsClient {
+    transport;
+    createSession;
+    constructor(transport, 
+    /** `AgentsClient.createSession`, bound. */
+    createSession) {
+        this.transport = transport;
+        this.createSession = createSession;
+    }
+    path(environmentId) {
+        if (!isEnvironmentId(environmentId))
+            throw new TypeError(`${environmentId} is not an Environment id: up to 200 characters, /-separated segments of letters, digits, '.', '_' and '-'`);
+        return `/v1/environments/${segment(environmentId)}`;
+    }
+    /** The Environment's secrets. */
+    get secrets() {
+        return new EnvironmentSecretsClient(this.transport, (environmentId) => this.path(environmentId));
+    }
+    /**
+     * Creates the Environment and its vault, or finds the one with this id
+     * (`PUT /v1/environments/{id}`). On an existing one, `kind` and `storage` are fixed (a
+     * different one is a 409), labels replace, and any other change writes the recipe and bumps
+     * its `version`: a pod's image and resources apply when it next starts from stopped.
+     */
+    async put(environmentId, recipe = {}, options = {}) {
+        return this.transport.json(this.path(environmentId), "PUT", { requestId: id(), ...recipe }, options.signal);
+    }
+    async get(environmentId, options = {}) {
+        return this.transport.json(this.path(environmentId), "GET", undefined, options.signal);
+    }
+    /** The Environments with every label in `labels` that this client reaches. */
+    async list(options = {}) {
+        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/environments${search ? `?${search}` : ""}`, "GET", undefined, options.signal);
+        return reply.environments;
+    }
+    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 EnvironmentPageSchema.parse(await this.transport.json(`/v1/environments?${query}`, "GET", undefined, options.signal));
+    }
+    /** Stops a pod Environment: its volume is kept, and the next turn starts it again. */
+    async stop(environmentId, options = {}) {
+        return this.transport.json(`${this.path(environmentId)}/stop`, "POST", {}, options.signal);
+    }
+    /** Resets a pod Environment: a new pod on a new, empty volume, with its recipe applied. */
+    async reset(environmentId, options = {}) {
+        return this.transport.json(`${this.path(environmentId)}/reset`, "POST", {}, options.signal);
+    }
+    /**
+     * Keeps a version of the Environment's disk (`POST /v1/environments/{id}/snapshot`), between
+     * turns; `unchanged` when the disk is as the latest version has it.
+     */
+    async snapshot(environmentId, options = {}) {
+        await this.transport.requireFeature("environment-disk-versions", options.signal);
+        return this.transport.json(`${this.path(environmentId)}/snapshot`, "POST", {}, options.signal);
+    }
+    /**
+     * Puts disk version `version` back: at once for a virtual Environment (`done`), on a new volume
+     * seeded before the next turn for a pod (`pending`).
+     */
+    async restore(environmentId, version, options = {}) {
+        await this.transport.requireFeature("environment-disk-versions", options.signal);
+        return this.transport.json(`${this.path(environmentId)}/restore`, "POST", { requestId: id(), version }, options.signal);
+    }
+    /** The Environment's disk versions, newest first. */
+    async versions(environmentId, options = {}) {
+        await this.transport.requireFeature("environment-disk-versions", options.signal);
+        return this.transport.json(`${this.path(environmentId)}/versions`, "GET", undefined, options.signal);
+    }
+    /** Deletes disk version `version`; `deleted` is false when there was none. */
+    async deleteVersion(environmentId, version, options = {}) {
+        return this.transport.json(`${this.path(environmentId)}/versions/${version}`, "DELETE", undefined, options.signal);
+    }
+    /** Deletes the Environment, its vault and its files; `deleted` is false when there was none. */
+    async delete(environmentId, options = {}) {
+        return this.transport.json(this.path(environmentId), "DELETE", undefined, options.signal);
+    }
+    /** The Environment's lifecycle events, from `from` on. */
+    async events(environmentId, options = {}) {
+        const reply = await this.transport.json(`${this.path(environmentId)}/events${options.from === undefined ? "" : `?from=${options.from}`}`, "GET", undefined, options.signal);
+        return reply.events;
+    }
+    /**
+     * One Environment for one session: creates the Environment (`sessions/<session id>` unless
+     * `environmentId` names another), writes `secrets`, opens the session on it, and returns both
+     * with `release()`, which deletes the Environment. If the session cannot be opened, the
+     * Environment is deleted again.
+     */
+    async forSession(options) {
+        const sessionId = options.session.id ?? id();
+        const environmentId = options.environmentId ??
+            (isEnvironmentId(`sessions/${sessionId}`) ? `sessions/${sessionId}` : `sessions/${id()}`);
+        const signal = options.signal ? { signal: options.signal } : {};
+        const environment = await this.put(environmentId, options.recipe ?? {}, signal);
+        let session;
+        try {
+            for (const [name, secret] of Object.entries(options.secrets ?? {}))
+                await this.secrets.put(environmentId, name, secret, signal);
+            session = await this.createSession({
+                ...options.session,
+                id: sessionId,
+                environment: environmentId,
+            });
+        }
+        catch (error) {
+            await this.delete(environmentId).catch(() => undefined);
+            throw error;
+        }
+        return {
+            session,
+            environment,
+            release: (release = {}) => this.delete(environmentId, release),
+        };
+    }
+}

package/dist/index.d.ts

@@ -6,14 +6,14 @@ export { Agent, AgentBuilder } from "./builder.js";
 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 type { SessionPage, SessionListItem, SessionManifestView, HistoryPage, SessionUsageTotals, ModelCall, ModelCallsPage, EnvironmentPage, ToolCall, ToolCallsPage, LiveEvent, SessionEvent, SessionEventOf, EventType, SessionCommand, SubjectScope, EnvironmentView, EnvironmentEvent, EnvironmentKind, EnvironmentRecipe, EnvironmentSecretView, EnvironmentSnapshot, EnvironmentRestore, EnvironmentVersions, RestoreEnvironmentRequest, MessagePart, ArtifactView, ArtifactKind, ArtifactListItem, ArtifactPage, 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 type { ArtifactBody, ArtifactPageOptions, ArtifactLinkWithUrl, UploadArtifactOptions, } from "./artifacts.js";
+export type { ActAsOptions, AgentSource, SessionView, CommandOptions, CreateSessionOptions, SessionSandbox, ForSessionOptions, EnvironmentRecipeInput, EnvironmentSecretInput, SessionEnvironmentHandle, } from "./client.js";
+export { EnvironmentsClient, EnvironmentSecretsClient } from "./client.js";
 export { AccessClient } from "./access.js";
 export { resolveConnection, ConnectionError } from "./connection.js";
 export type { ResolvedConnection } from "./connection.js";

package/dist/index.js

@@ -8,7 +8,7 @@ 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 { EnvironmentsClient, EnvironmentSecretsClient } from "./client.js";
 export { AccessClient } from "./access.js";
 export { resolveConnection, ConnectionError } from "./connection.js";
 export { RuntimeError, IncompatibleRuntimeError } from "./http.js";

package/dist/reads.d.ts

@@ -4,7 +4,7 @@ import type { Transport } from "./http.js";
 export type SessionPageOptions = {
     agentId?: string;
     status?: SessionListItem["status"];
-    sandboxId?: string;
+    environmentId?: string;
     ownerUserId?: string;
     limit?: number;
     cursor?: string;

package/dist/session-client.d.ts

@@ -3,10 +3,10 @@
  * which resolves the connection from the environment or the Project link.
  */
 import type { AgentManifest, BuiltAgent, BuiltWorkflow, JsonValue, SandboxToolName, WorkflowManifest } from "@nylorun/core/define";
-import { type SessionItemsResponse, type SessionSummary, type ListAgentsResponse, type ListPublicAgentsResponse, type SubjectScope, type CredentialSelection, type MessagePart, type SandboxRequest, type SessionCommand } from "@nylorun/core/contracts";
+import { type SessionItemsResponse, type SessionSummary, type ListAgentsResponse, type ListPublicAgentsResponse, type SubjectScope, type MessagePart, type SessionCommand } 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, type Destination } from "./http.js";
@@ -38,16 +38,12 @@ export interface CreateSessionOptions {
     ownerUserId: string;
     info?: Record<string, unknown>;
     requestId?: string;
-    vaultIds?: readonly string[];
-    credentialSelections?: readonly CredentialSelection[];
     /**
-     * The session's sandbox: omit for the Tenant default, `false` for none, `{ id }` to attach a
-     * sandbox resource (`client.sandboxes`, Host feature `sandboxes`), or an inline sandbox
-     * (`image`, `network.allow`, `resources`) checked against the Tenant's limits. `{ session }`
-     * shares another session's and is deprecated: use `client.sandboxes.forSession()` or
-     * `ensure()` and `{ id }`. Fixed once the session exists.
+     * The Environment the session runs in (`client.environments`): its sandbox, and its vault's
+     * credentials for the session's shell, MCP servers and HTTP tools. Omit for no sandbox and no
+     * credentials. Fixed once the session exists.
      */
-    sandbox?: SandboxRequest;
+    environment?: string;
 }
 export interface ActAsOptions {
     /** What the subject may do; the Runtime grants nothing else. Default `["sessions:own"]`. */
@@ -61,17 +57,18 @@ export declare 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: string, options?: ActAsOptions): AgentsClient;
     /** The public keys that verify the tokens the Tenant signs. */
     get access(): AccessClient;
     /**
-     * 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(): SandboxesClient;
+    get environments(): EnvironmentsClient;
     /** File artifacts: upload, list, download with Range, capability links (protocol 6). */
     get artifacts(): ArtifactsClient;
     /** Definition files: the skill files a definition names, by content hash. */
@@ -98,7 +95,7 @@ export declare 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`.
      */
     saveAgent(agent: AgentSource | BuiltWorkflow, options?: {
@@ -206,6 +203,7 @@ export declare class SessionClient {
     }): Promise<{
         calls: {
             id: string;
+            effectId: string;
             sessionId: string;
             turnId: string;
             agentId: string;
@@ -229,6 +227,87 @@ export declare class SessionClient {
         nextCursor: string | null;
         asOf: string;
     }>;
+    /**
+     * 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.
+     */
+    toolCalls(options?: {
+        turnId?: string;
+        limit?: number;
+        cursor?: string;
+        signal?: AbortSignal;
+    }): Promise<{
+        calls: {
+            effectId: string;
+            turnId: string;
+            callId: string | null;
+            capabilityId: string | null;
+            toolName: string | null;
+            kind: "http" | "mcp" | "platform" | "sandbox" | null;
+            server: string | null;
+            status: "cancelled" | "completed" | "failed" | "held" | "invoking" | "uncertain";
+            attempts: number;
+            input: unknown;
+            error: {
+                code: string;
+                message: string;
+            } | null;
+            startedAt: string | null;
+            settledAt: string | null;
+            durationMs: number | null;
+        }[];
+        nextCursor: string | null;
+        asOf: string;
+    }>;
+    /**
+     * 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.
+     */
+    trace(turnId: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<{
+        [x: string]: unknown;
+        resourceSpans: {
+            [x: string]: unknown;
+            resource: {
+                [x: string]: unknown;
+                attributes: {
+                    [x: string]: unknown;
+                    key: string;
+                    value: Record<string, unknown>;
+                }[];
+            };
+            scopeSpans: {
+                [x: string]: unknown;
+                scope: {
+                    [x: string]: unknown;
+                    name: string;
+                    version?: string | undefined;
+                };
+                spans: {
+                    [x: string]: unknown;
+                    traceId: string;
+                    spanId: string;
+                    parentSpanId?: string | undefined;
+                    name: string;
+                    kind: number;
+                    startTimeUnixNano: string;
+                    endTimeUnixNano: string;
+                    attributes: {
+                        [x: string]: unknown;
+                        key: string;
+                        value: Record<string, unknown>;
+                    }[];
+                    status: {
+                        [x: string]: unknown;
+                        code: number;
+                        message?: string | undefined;
+                    };
+                }[];
+            }[];
+        }[];
+    }>;
     /** `agent` narrows to one agent used as a tool: its delegationId or its path. */
     history(options: {
         cursor?: string;
@@ -261,10 +340,14 @@ export declare class SessionClient {
         time: string;
         schemaVersion: number;
         source: {
-            kind: "api" | "controller" | "edge" | "egress-gate" | "evidence" | "harness" | "human" | "init" | "loop" | "model-gate" | "operator" | "sandboxes" | "supervisor" | "tool-gate";
+            kind: "api" | "client" | "controller" | "core" | "edge" | "egress-gate" | "evidence" | "harness" | "human" | "init" | "loop" | "model-gate" | "operator" | "sandboxes" | "supervisor" | "tool-gate";
             id: string;
         };
         evidence: "asserted" | "attested" | "claimed" | "measured" | "observed";
+        principal?: {
+            kind: "application" | "core" | "flow-host" | "subject";
+            id: string;
+        } | undefined;
         trace?: {
             traceId: string;
             spanId: string;
@@ -286,5 +369,5 @@ export { RuntimeError, IncompatibleRuntimeError } from "./http.js";
 export type { Destination, IncompatibleReason } from "./http.js";
 export type { LiveEvent } from "@nylorun/core/contracts";
 export { AccessClient } from "./access.js";
-export { SandboxesClient } from "./sandboxes.js";
-export type { ForSessionOptions, SandboxSpec, SessionSandboxHandle } from "./sandboxes.js";
+export { EnvironmentSecretsClient, EnvironmentsClient } from "./environments.js";
+export type { EnvironmentRecipeInput, EnvironmentSecretInput, ForSessionOptions, SessionEnvironmentHandle, } from "./environments.js";