@nylorun/agents 0.20.0-beta → 0.22.0-beta

package/dist/environments.d.ts

@@ -1,16 +1,20 @@
 /**
  * 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:
+ * (kind `virtual`, `pod` or `none`) made from an environment manifest's version or from inline
+ * fields, and one vault of secrets for its shell, MCP servers and HTTP tools. It never changes
+ * what it runs after it is made (protocol 14, D63): a new version reaches an agent through a new
+ * Environment. 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 })`.
+ * - `environments.put(id, { manifest: "analyst-box" })` (or inline fields): one Environment per
+ *   person or per project, by a deterministic id (`users/alice/web`); get-or-create in one call.
+ *   Write its secrets with `environments.secrets.put(id, name, { value })` and open sessions on
+ *   it with `createSession({ environment: id })`.
+ * - `environments.manifests.save(manifest)`: save an environment manifest's next version, like
+ *   `saveAgent`; `plan(manifest)` answers what a save would do and saves nothing.
  *
  * Ids may hold `/`; they are sent percent-encoded as one path segment. Secret values are
  * write-only: no call reads one back.
@@ -18,14 +22,39 @@
  * 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.
+ *
+ * `fork(id, { id: next })` is how an Environment gets a new manifest version (Q15): a new
+ * Environment made from it, with the source's disk and secrets; `planFork` answers what it would do.
  */
-import { type DeleteEnvironmentResponse, type EnvironmentEvent, type EnvironmentRestore, type EnvironmentSecretView, type EnvironmentSnapshot, type EnvironmentVersions, type EnvironmentView, type PutEnvironmentRequest, type PutEnvironmentSecretRequest } from "@nylorun/core/contracts";
+import { ENVIRONMENT_MANIFEST_SCHEMA_VERSION, type DeleteEnvironmentManifestResponse, type EnvironmentManifest, type EnvironmentManifestPlan, type EnvironmentManifestVersions, type EnvironmentForkPlan, type EnvironmentManifestView, type ForkEnvironmentRequest, type SaveEnvironmentManifestResponse, type DeleteEnvironmentResponse, type EnvironmentEvent, type EnvironmentEventType, 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;
+/**
+ * What an Environment is made from: an environment manifest (`manifest: "name"` or `"name@n"`)
+ * or the inline fields, and its labels, owner guard and `from`.
+ */
+export type EnvironmentInput = Omit<PutEnvironmentRequest, "requestId">;
+/**
+ * One secret of an Environment's vault, as written: typed, or only its value (`{ value }`, or
+ * `{ headers }` for a `headers` secret) when what the Environment runs declares its slot (D64).
+ */
+export type EnvironmentSecretInput = PutEnvironmentSecretRequest | {
+    readonly value: string;
+} | {
+    readonly headers: Readonly<Record<string, string>>;
+};
+/** An environment manifest as authored: `manifestSchemaVersion` may be left out. */
+export type EnvironmentManifestInput = Omit<EnvironmentManifest, "manifestSchemaVersion"> & {
+    readonly manifestSchemaVersion?: typeof ENVIRONMENT_MANIFEST_SCHEMA_VERSION;
+    /** For editors; dropped here, as the CLI drops it. */
+    readonly $schema?: string;
+};
+/**
+ * An environment manifest (protocol 14, D63): checked now against the schema the Runtime
+ * enforces, with `manifestSchemaVersion` filled in and `$schema` dropped. Save it with
+ * `client.environments.manifests.save()`, or make an Environment from it inline.
+ */
+export declare function environmentManifest(input: EnvironmentManifestInput): EnvironmentManifest;
 /** A session opened on an Environment of its own (`environments.forSession`). */
 export interface SessionEnvironmentHandle {
     readonly session: SessionClient;
@@ -38,8 +67,11 @@ export interface SessionEnvironmentHandle {
 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;
+    /**
+     * What the Environment is made from (a `manifest` or inline fields) and its labels. Default: a
+     * virtual one within the Tenant's defaults.
+     */
+    readonly recipe?: EnvironmentInput;
     /** Secrets to write before the session opens, by name. */
     readonly secrets?: Readonly<Record<string, EnvironmentSecretInput>>;
     /** The Environment's id. Default: `sessions/<session id>`. */
@@ -54,7 +86,9 @@ export declare class EnvironmentSecretsClient {
     /**
      * 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`.
+     * credential for a host or a URL is a 409 `credential_conflict`. When what the Environment
+     * runs declares the secret's slot (D64), send only `{ value }` (or `{ headers }`); a name it
+     * does not declare is `409 secret_not_in_manifest`.
      */
     put(environmentId: string, name: string, secret: EnvironmentSecretInput, options?: {
         signal?: AbortSignal;
@@ -72,6 +106,64 @@ export declare class EnvironmentSecretsClient {
         id: string;
     }>;
 }
+/**
+ * Environment manifests (protocol 14, D63): `client.environments.manifests`. A save writes the
+ * manifest's next version, or answers the latest unchanged, and changes no Environment: an
+ * Environment keeps the version it was made from.
+ */
+/** The bytes of files by hash, by `sha256:<hex>` (`environmentFiles(...).bytes`). */
+export type EnvironmentFileBytes = Readonly<Record<string, Uint8Array>>;
+/**
+ * A manifest `files` entry by content hash (Q6): `contents` (each file's path under `path` and
+ * its bytes or text) hashed, as `entry` for the manifest and `bytes` for `manifests.save`'s
+ * `files`, which uploads them. Each file holds at most 10 MiB.
+ */
+export declare function environmentFiles(path: string, contents: Readonly<Record<string, Uint8Array | string>>): Promise<{
+    entry: {
+        path: string;
+        files: Record<string, string>;
+    };
+    bytes: Record<string, Uint8Array>;
+}>;
+export declare class EnvironmentManifestsClient {
+    private readonly transport;
+    constructor(transport: Transport);
+    private path;
+    private send;
+    /**
+     * Saves `manifest` (`PUT /v1/environment-manifests/{name}`). `ifMatch`: the version you read
+     * (`0` for none yet); a save over a newer one is `412 manifest_changed`. `files`: the bytes of
+     * its files by hash (`environmentFiles(...).bytes`), uploaded first when the Runtime lacks them.
+     */
+    save(manifest: EnvironmentManifestInput, options?: {
+        ifMatch?: number;
+        files?: EnvironmentFileBytes;
+        signal?: AbortSignal;
+    }): Promise<SaveEnvironmentManifestResponse>;
+    /** What saving `manifest` would do (`?dryRun=true`): changes, errors, warnings, and the Environments behind. */
+    plan(manifest: EnvironmentManifestInput, options?: {
+        ifMatch?: number;
+        files?: EnvironmentFileBytes;
+        signal?: AbortSignal;
+    }): Promise<EnvironmentManifestPlan>;
+    /** The latest version of manifest `name`, or version `version`. */
+    get(name: string, options?: {
+        version?: number;
+        signal?: AbortSignal;
+    }): Promise<EnvironmentManifestView>;
+    /** Each manifest's latest version. */
+    list(options?: {
+        signal?: AbortSignal;
+    }): Promise<EnvironmentManifestView[]>;
+    /** Every version of manifest `name`, newest first. */
+    versions(name: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<EnvironmentManifestVersions>;
+    /** Deletes every version; refused while an Environment was made from one (`409 manifest_in_use`). */
+    delete(name: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<DeleteEnvironmentManifestResponse>;
+}
 export declare class EnvironmentsClient {
     private readonly transport;
     /** `AgentsClient.createSession`, bound. */
@@ -82,13 +174,17 @@ export declare class EnvironmentsClient {
     private path;
     /** The Environment's secrets. */
     get secrets(): EnvironmentSecretsClient;
+    /** Environment manifests (protocol 14, D63): named, versioned definitions of a kind of Environment. */
+    get manifests(): EnvironmentManifestsClient;
     /**
      * 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 /v1/environments/{id}`), from an environment manifest (`{ manifest: "name" }` takes
+     * the latest version, `"name@n"` version n) or from inline fields. It never changes what it
+     * runs after that (protocol 14): on an existing one, labels replace and `ownerUserId` sets or
+     * clears the owner guard, fields that match are accepted, and anything else is
+     * `409 environment_immutable`.
      */
-    put(environmentId: string, recipe?: EnvironmentRecipeInput, options?: {
+    put(environmentId: string, recipe?: EnvironmentInput, options?: {
         signal?: AbortSignal;
     }): Promise<EnvironmentView>;
     get(environmentId: string, options?: {
@@ -109,7 +205,7 @@ export declare class EnvironmentsClient {
             id: string;
             kind: "none" | "pod" | "virtual";
             labels: Record<string, string>;
-            recipe: {
+            manifest: {
                 image?: string | undefined;
                 resources?: {
                     cpus: number;
@@ -129,12 +225,60 @@ export declare class EnvironmentsClient {
                     cwd?: string | undefined;
                     timeout?: string | undefined;
                 }[] | undefined;
-                files?: {
+                files?: ({
                     artifactId: string;
                     version: number;
                     path: string;
-                }[] | undefined;
+                } | {
+                    path: string;
+                    files: Record<string, string>;
+                })[] | undefined;
+                secrets?: Record<string, {
+                    required?: boolean | undefined;
+                    description?: string | undefined;
+                    type: "environment_secret";
+                    allowedHosts: string[];
+                    inject?: {
+                        header: string;
+                        format: string;
+                    } | undefined;
+                } | {
+                    required?: boolean | undefined;
+                    description?: string | undefined;
+                    type: "environment_variable";
+                } | {
+                    via?: string | undefined;
+                    identity?: {
+                        header: string;
+                    } | undefined;
+                    required?: boolean | undefined;
+                    description?: string | undefined;
+                    type: "bearer";
+                    url: string;
+                } | {
+                    via?: string | undefined;
+                    identity?: {
+                        header: string;
+                    } | undefined;
+                    required?: boolean | undefined;
+                    description?: string | undefined;
+                    type: "headers";
+                    url: string;
+                }> | undefined;
             };
+            manifestName?: string | undefined;
+            manifestVersion?: number | undefined;
+            manifestHash?: string | undefined;
+            forkedFrom?: {
+                environment: string;
+                disk: number | null;
+            } | undefined;
+            slots?: {
+                name: string;
+                type: string;
+                required: boolean;
+                set: boolean;
+            }[] | undefined;
             version: number;
             appliedVersion: number;
             ownerUserId: string | null;
@@ -145,6 +289,7 @@ export declare class EnvironmentsClient {
                 volumeGeneration: number;
                 hostEpoch: number;
                 reason?: string | undefined;
+                imageDigest?: string | undefined;
             } | undefined;
             lastUsedAt: string;
             disk?: {
@@ -186,6 +331,24 @@ export declare class EnvironmentsClient {
     restore(environmentId: string, version: number | "latest", options?: {
         signal?: AbortSignal;
     }): Promise<EnvironmentRestore>;
+    /**
+     * Forks the Environment into a new one, `options.id` (Q15): how an Environment gets a new
+     * manifest version, since none ever changes what it runs. It is made from `options.manifest`
+     * (default the source's manifest at its latest version), its disk starts from `options.disk`
+     * (`latest`, the default, snapshots first; a version; or `empty`) and the secrets the new
+     * manifest declares are copied (`options.secrets: "none"` copies none). The source keeps what
+     * it runs, its disk and its sessions. Answers the new Environment and the plan it ran.
+     */
+    fork(environmentId: string, options: Omit<ForkEnvironmentRequest, "requestId" | "dryRun"> & {
+        signal?: AbortSignal;
+    }): Promise<{
+        environment: EnvironmentView;
+        plan: EnvironmentForkPlan;
+    }>;
+    /** What `fork` would do (the disk, the secrets copied and left behind, the changes), making nothing. */
+    planFork(environmentId: string, options: Omit<ForkEnvironmentRequest, "requestId" | "dryRun"> & {
+        signal?: AbortSignal;
+    }): Promise<EnvironmentForkPlan>;
     /** The Environment's disk versions, newest first. */
     versions(environmentId: string, options?: {
         signal?: AbortSignal;
@@ -202,9 +365,16 @@ export declare class EnvironmentsClient {
     delete(environmentId: string, options?: {
         signal?: AbortSignal;
     }): Promise<DeleteEnvironmentResponse>;
-    /** The Environment's lifecycle events, from `from` on. */
+    /**
+     * The Environment's events, from `from` on: its lifecycle, and `environment.egress` for every
+     * connection its sandbox opens (with the turns that were running). `types` keeps only those
+     * types; `since` and `until` keep events recorded in that window (ISO times or `Date`s).
+     */
     events(environmentId: string, options?: {
         from?: number;
+        types?: readonly EnvironmentEventType[];
+        since?: string | Date;
+        until?: string | Date;
         signal?: AbortSignal;
     }): Promise<EnvironmentEvent[]>;
     /**

package/dist/environments.js

@@ -1,16 +1,20 @@
 /**
  * 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:
+ * (kind `virtual`, `pod` or `none`) made from an environment manifest's version or from inline
+ * fields, and one vault of secrets for its shell, MCP servers and HTTP tools. It never changes
+ * what it runs after it is made (protocol 14, D63): a new version reaches an agent through a new
+ * Environment. 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 })`.
+ * - `environments.put(id, { manifest: "analyst-box" })` (or inline fields): one Environment per
+ *   person or per project, by a deterministic id (`users/alice/web`); get-or-create in one call.
+ *   Write its secrets with `environments.secrets.put(id, name, { value })` and open sessions on
+ *   it with `createSession({ environment: id })`.
+ * - `environments.manifests.save(manifest)`: save an environment manifest's next version, like
+ *   `saveAgent`; `plan(manifest)` answers what a save would do and saves nothing.
  *
  * Ids may hold `/`; they are sent percent-encoded as one path segment. Secret values are
  * write-only: no call reads one back.
@@ -18,9 +22,22 @@
  * 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.
+ *
+ * `fork(id, { id: next })` is how an Environment gets a new manifest version (Q15): a new
+ * Environment made from it, with the source's disk and secrets; `planFork` answers what it would do.
  */
-import { EnvironmentPageSchema, isEnvironmentId, } from "@nylorun/core/contracts";
+import { ENVIRONMENT_MANIFEST_SCHEMA_VERSION, EnvironmentManifestSchema, EnvironmentPageSchema, isEnvironmentId, isEnvironmentManifestName, } from "@nylorun/core/contracts";
+import { definitionFileHash, FilesClient } from "./files.js";
 import { id, segment } from "./http.js";
+/**
+ * An environment manifest (protocol 14, D63): checked now against the schema the Runtime
+ * enforces, with `manifestSchemaVersion` filled in and `$schema` dropped. Save it with
+ * `client.environments.manifests.save()`, or make an Environment from it inline.
+ */
+export function environmentManifest(input) {
+    const { $schema: _, ...rest } = input;
+    return EnvironmentManifestSchema.parse({ manifestSchemaVersion: ENVIRONMENT_MANIFEST_SCHEMA_VERSION, ...rest });
+}
 /** An Environment's secrets: `client.environments.secrets`. */
 export class EnvironmentSecretsClient {
     transport;
@@ -32,7 +49,9 @@ export class EnvironmentSecretsClient {
     /**
      * 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`.
+     * credential for a host or a URL is a 409 `credential_conflict`. When what the Environment
+     * runs declares the secret's slot (D64), send only `{ value }` (or `{ headers }`); a name it
+     * does not declare is `409 secret_not_in_manifest`.
      */
     async put(environmentId, name, secret, options = {}) {
         return this.transport.json(`${this.path(environmentId)}/secrets/${segment(name)}`, "PUT", { requestId: id(), ...secret }, options.signal);
@@ -49,6 +68,71 @@ export class EnvironmentSecretsClient {
         return this.transport.json(`${this.path(environmentId)}/secrets/${segment(name)}`, "DELETE", undefined, options.signal);
     }
 }
+/**
+ * A manifest `files` entry by content hash (Q6): `contents` (each file's path under `path` and
+ * its bytes or text) hashed, as `entry` for the manifest and `bytes` for `manifests.save`'s
+ * `files`, which uploads them. Each file holds at most 10 MiB.
+ */
+export async function environmentFiles(path, contents) {
+    const files = {};
+    const bytes = {};
+    for (const [name, content] of Object.entries(contents).sort(([a], [b]) => a.localeCompare(b))) {
+        const data = typeof content === "string" ? new TextEncoder().encode(content) : content;
+        const sha256 = await definitionFileHash(data);
+        files[name] = sha256;
+        bytes[sha256] = data;
+    }
+    return { entry: { path, files }, bytes };
+}
+export class EnvironmentManifestsClient {
+    transport;
+    constructor(transport) {
+        this.transport = transport;
+    }
+    path(name) {
+        if (!isEnvironmentManifestName(name))
+            throw new TypeError(`${name} is not an environment manifest's name: 1-64 letters, digits, '.', '_' and '-'`);
+        return `/v1/environment-manifests/${segment(name)}`;
+    }
+    async send(manifest, query, options) {
+        const { ifMatch, signal } = options;
+        const body = environmentManifest(manifest);
+        // Its files by hash (Q6): uploaded first, each only when the Runtime does not hold it.
+        if (options.files)
+            await new FilesClient(this.transport).ensure(new Map(Object.entries(options.files).map(([sha256, bytes]) => [sha256, { size: bytes.byteLength, read: async () => bytes }])), signal ? { signal } : {});
+        const transport = ifMatch === undefined ? this.transport : this.transport.withHeaders({ "If-Match": String(ifMatch) });
+        return transport.json(`${this.path(body.name)}${query}`, "PUT", { requestId: id(), ...body }, signal);
+    }
+    /**
+     * Saves `manifest` (`PUT /v1/environment-manifests/{name}`). `ifMatch`: the version you read
+     * (`0` for none yet); a save over a newer one is `412 manifest_changed`. `files`: the bytes of
+     * its files by hash (`environmentFiles(...).bytes`), uploaded first when the Runtime lacks them.
+     */
+    async save(manifest, options = {}) {
+        return this.send(manifest, "", options);
+    }
+    /** What saving `manifest` would do (`?dryRun=true`): changes, errors, warnings, and the Environments behind. */
+    async plan(manifest, options = {}) {
+        return this.send(manifest, "?dryRun=true", options);
+    }
+    /** The latest version of manifest `name`, or version `version`. */
+    async get(name, options = {}) {
+        return this.transport.json(`${this.path(name)}${options.version === undefined ? "" : `/versions/${options.version}`}`, "GET", undefined, options.signal);
+    }
+    /** Each manifest's latest version. */
+    async list(options = {}) {
+        const reply = await this.transport.json("/v1/environment-manifests", "GET", undefined, options.signal);
+        return reply.manifests;
+    }
+    /** Every version of manifest `name`, newest first. */
+    async versions(name, options = {}) {
+        return this.transport.json(`${this.path(name)}/versions`, "GET", undefined, options.signal);
+    }
+    /** Deletes every version; refused while an Environment was made from one (`409 manifest_in_use`). */
+    async delete(name, options = {}) {
+        return this.transport.json(this.path(name), "DELETE", undefined, options.signal);
+    }
+}
 export class EnvironmentsClient {
     transport;
     createSession;
@@ -67,11 +151,17 @@ export class EnvironmentsClient {
     get secrets() {
         return new EnvironmentSecretsClient(this.transport, (environmentId) => this.path(environmentId));
     }
+    /** Environment manifests (protocol 14, D63): named, versioned definitions of a kind of Environment. */
+    get manifests() {
+        return new EnvironmentManifestsClient(this.transport);
+    }
     /**
      * 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 /v1/environments/{id}`), from an environment manifest (`{ manifest: "name" }` takes
+     * the latest version, `"name@n"` version n) or from inline fields. It never changes what it
+     * runs after that (protocol 14): on an existing one, labels replace and `ownerUserId` sets or
+     * clears the owner guard, fields that match are accepted, and anything else is
+     * `409 environment_immutable`.
      */
     async put(environmentId, recipe = {}, options = {}) {
         return this.transport.json(this.path(environmentId), "PUT", { requestId: id(), ...recipe }, options.signal);
@@ -121,6 +211,26 @@ export class EnvironmentsClient {
         await this.transport.requireFeature("environment-disk-versions", options.signal);
         return this.transport.json(`${this.path(environmentId)}/restore`, "POST", { requestId: id(), version }, options.signal);
     }
+    /**
+     * Forks the Environment into a new one, `options.id` (Q15): how an Environment gets a new
+     * manifest version, since none ever changes what it runs. It is made from `options.manifest`
+     * (default the source's manifest at its latest version), its disk starts from `options.disk`
+     * (`latest`, the default, snapshots first; a version; or `empty`) and the secrets the new
+     * manifest declares are copied (`options.secrets: "none"` copies none). The source keeps what
+     * it runs, its disk and its sessions. Answers the new Environment and the plan it ran.
+     */
+    async fork(environmentId, options) {
+        const { signal, ...body } = options;
+        await this.transport.requireFeature("environment-manifests", signal);
+        return this.transport.json(`${this.path(environmentId)}/fork`, "POST", { requestId: id(), ...body }, signal);
+    }
+    /** What `fork` would do (the disk, the secrets copied and left behind, the changes), making nothing. */
+    async planFork(environmentId, options) {
+        const { signal, ...body } = options;
+        await this.transport.requireFeature("environment-manifests", signal);
+        const answer = await this.transport.json(`${this.path(environmentId)}/fork`, "POST", { ...body, dryRun: true }, signal);
+        return answer.plan;
+    }
     /** The Environment's disk versions, newest first. */
     async versions(environmentId, options = {}) {
         await this.transport.requireFeature("environment-disk-versions", options.signal);
@@ -134,9 +244,24 @@ export class EnvironmentsClient {
     async delete(environmentId, options = {}) {
         return this.transport.json(this.path(environmentId), "DELETE", undefined, options.signal);
     }
-    /** The Environment's lifecycle events, from `from` on. */
+    /**
+     * The Environment's events, from `from` on: its lifecycle, and `environment.egress` for every
+     * connection its sandbox opens (with the turns that were running). `types` keeps only those
+     * types; `since` and `until` keep events recorded in that window (ISO times or `Date`s).
+     */
     async events(environmentId, options = {}) {
-        const reply = await this.transport.json(`${this.path(environmentId)}/events${options.from === undefined ? "" : `?from=${options.from}`}`, "GET", undefined, options.signal);
+        const query = new URLSearchParams();
+        if (options.from !== undefined)
+            query.set("from", String(options.from));
+        if (options.types !== undefined && options.types.length > 0)
+            query.set("types", options.types.join(","));
+        const iso = (at) => (at instanceof Date ? at.toISOString() : at);
+        if (options.since !== undefined)
+            query.set("since", iso(options.since));
+        if (options.until !== undefined)
+            query.set("until", iso(options.until));
+        const search = query.toString();
+        const reply = await this.transport.json(`${this.path(environmentId)}/events${search === "" ? "" : `?${search}`}`, "GET", undefined, options.signal);
         return reply.events;
     }
     /**

package/dist/http.js

@@ -28,12 +28,12 @@ export class IncompatibleRuntimeError extends Error {
 }
 function remedyFor(compatibility) {
     if (compatibility.reason === "feature") {
-        return "Upgrade the Runtime Host (nylorun runtime restart from a newer CLI) so it advertises the required features.";
+        return "Upgrade the Runtime so it advertises the required features (a local Tenant: npx nylorun@latest start).";
     }
     if (compatibility.client < compatibility.host.min) {
         return "Upgrade this client (npm i -D @nylorun/agents@latest) or use a CLI that matches the Host protocol.";
     }
-    return "Upgrade the Runtime Host with nylorun runtime restart from a newer CLI, or install a matching older client (npm i -D @nylorun/cli@<compatible>).";
+    return "Upgrade the Runtime (a local Tenant: npx nylorun@latest start), or install a matching older client (npm i -D @nylorun/agents@<compatible>).";
 }
 export class Transport {
     url;

package/dist/index.d.ts

@@ -3,28 +3,26 @@ export type { ProtocolFeature, ProtocolRange, Compatibility, ErrorCode, } from "
 export { checkHealth, describeIncompatibility, parseProtocolRange, } from "@nylorun/core/transport";
 export type { HealthCheck, Incompatibility } from "@nylorun/core/transport";
 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 { AgentBuildError, AgentLifecycleError, VerdictSchema, isVerdict, WorkflowBuildError, isBuiltWorkflow, flow, tool, http, defineSchema, ToolError, } from "@nylorun/core/define";
+export type { FlowAgentBuilder, Flow, Named, LoopOptions, StageOptions, 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, 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 type { SessionPage, SessionListItem, SessionManifestView, HistoryPage, SessionUsageTotals, ModelCall, ModelCallsPage, EnvironmentPage, ToolCall, ToolCallsPage, LiveEvent, SessionEvent, SessionEventOf, EventType, SessionCommand, SubjectScope, EnvironmentView, EnvironmentEvent, EnvironmentEventType, EgressRunningTurn, EnvironmentKind, EnvironmentRecipe, EnvironmentSecretView, EnvironmentSnapshot, EnvironmentRestore, EnvironmentVersions, RestoreEnvironmentRequest, EnvironmentForkPlan, ForkEnvironmentRequest, ForkEnvironmentResponse, EnvironmentManifest, EnvironmentManifestPlan, EnvironmentManifestView, EnvironmentManifestVersions, SaveEnvironmentManifestResponse, MessagePart, ArtifactView, ArtifactKind, ArtifactListItem, ArtifactPage, ArtifactVersionView, ArtifactLink, UploadArtifactResponse, DefinitionFileView, ArtifactTree, ArtifactDiff, FolderEntry, } from "@nylorun/core/contracts";
+export { ENVIRONMENT_EVENT_TYPES, 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, 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 type { ActAsOptions, AgentSource, SessionView, CommandOptions, CreateSessionOptions, SessionSandbox, ForSessionOptions, EnvironmentFileBytes, EnvironmentInput, EnvironmentManifestInput, EnvironmentSecretInput, SessionEnvironmentHandle, } from "./client.js";
+export { EnvironmentManifestsClient, EnvironmentsClient, EnvironmentSecretsClient, environmentFiles, environmentManifest, } from "./client.js";
 export { AccessClient } from "./access.js";
 export { resolveConnection, ConnectionError } from "./connection.js";
 export type { ResolvedConnection } from "./connection.js";
 export { RuntimeError, IncompatibleRuntimeError } from "./http.js";
 export type { Destination, IncompatibleReason, TokenSource } from "./http.js";
-export { plugin } from "./plugins/plugin.js";
-export type { PluginCapability } from "./plugins/plugin.js";
 export { loadPlugin, PluginError } from "./plugins/load.js";
 export type { LoadedPlugin, PluginDiagnostic } from "./plugins/load.js";
-export { skills, loadSkillsFromDirectory, resolveSkillsRoot, parseSkill, SkillsError, formatSkillCatalog, SKILLS_USAGE, } from "./skills/index.js";
-export type { SkillsCapability, SkillsOptions, SkillDiagnostic, } from "./skills/index.js";
-export { mcp, McpError } from "./mcp/index.js";
-export type { McpCapability, McpOptions, McpServerSpec } from "./mcp/index.js";
+export { loadSkillsFromDirectory, resolveSkillsRoot, parseSkill, SkillsError, formatSkillCatalog, SKILLS_USAGE, } from "./skills/index.js";
+export type { SkillDiagnostic } from "./skills/index.js";
+export { McpError } from "./mcp/index.js";
+export type { McpServerSpec } from "./mcp/index.js";
 export type { SessionPageOptions } from "./reads.js";

package/dist/index.js

@@ -3,16 +3,15 @@ export { hashManifest, PROTOCOL_VERSION, PROTOCOL_FEATURES, HOST_PROTOCOL, DEFIN
 // The `/health` compatibility probe every Runtime client shares (Studio's server uses it).
 export { checkHealth, describeIncompatibility, parseProtocolRange, } from "@nylorun/core/transport";
 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 { SUBJECT_SCOPES } from "@nylorun/core/contracts";
+export { AgentBuildError, AgentLifecycleError, VerdictSchema, isVerdict, WorkflowBuildError, isBuiltWorkflow, flow, tool, http, defineSchema, ToolError, } from "@nylorun/core/define";
+export { ENVIRONMENT_EVENT_TYPES, 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 { EnvironmentsClient, EnvironmentSecretsClient } from "./client.js";
+export { EnvironmentManifestsClient, EnvironmentsClient, EnvironmentSecretsClient, environmentFiles, environmentManifest, } from "./client.js";
 export { AccessClient } from "./access.js";
 export { resolveConnection, ConnectionError } from "./connection.js";
 export { RuntimeError, IncompatibleRuntimeError } from "./http.js";
-export { plugin } from "./plugins/plugin.js";
 export { loadPlugin, PluginError } from "./plugins/load.js";
-export { skills, loadSkillsFromDirectory, resolveSkillsRoot, parseSkill, SkillsError, formatSkillCatalog, SKILLS_USAGE, } from "./skills/index.js";
-export { mcp, McpError } from "./mcp/index.js";
+export { loadSkillsFromDirectory, resolveSkillsRoot, parseSkill, SkillsError, formatSkillCatalog, SKILLS_USAGE, } from "./skills/index.js";
+export { McpError } from "./mcp/index.js";

package/dist/mcp/index.d.ts

@@ -1,2 +1,2 @@
-export { mcp, McpError, normalizeMcpServers } from "@nylorun/core/define";
-export type { McpCapability, McpOptions, McpServerSpec } from "@nylorun/core/define";
+export { McpError, normalizeMcpServers } from "@nylorun/core/define";
+export type { McpServerSpec } from "@nylorun/core/define";

package/dist/mcp/index.js

@@ -1 +1 @@
-export { mcp, McpError, normalizeMcpServers } from "@nylorun/core/define";
+export { McpError, normalizeMcpServers } from "@nylorun/core/define";

package/dist/plugins/load.d.ts

@@ -16,6 +16,7 @@ export declare class PluginError extends Error {
 export interface LoadedPlugin {
     readonly root: string;
     readonly name: string;
+    readonly version?: string;
     readonly description?: string;
     readonly skills: Readonly<Record<string, LoadedSkill>>;
     readonly mcpServers: Readonly<Record<string, McpServerManifest>>;

package/dist/plugins/load.js

@@ -80,6 +80,7 @@ export function loadPlugin(directory) {
     return {
         root,
         name: parsed.name,
+        ...(typeof parsed.version === "string" ? { version: parsed.version } : {}),
         ...(typeof parsed.description === "string" ? { description: parsed.description } : {}),
         skills,
         mcpServers,