@nylorun/agents 0.19.1-beta → 0.21.0-beta

package/dist/builder.d.ts

@@ -1,13 +1,12 @@
 import { Agent as CoreAgent, AgentBuilder as CoreAgentBuilder } from "@nylorun/core/define";
 import type { AgentOptions, ToolSchemaSource } from "@nylorun/core/define";
-import { type SkillsOptions } from "./skills/index.js";
 /**
- * The agent builder with the capabilities that read files: `.skills()` and `.plugin()`.
+ * The agent builder with the methods that read files: `.skills()` and `.plugin()`.
  * `@nylorun/agents/define` exports the portable builder from core, without them.
  */
 export declare class AgentBuilder<Info = unknown, Schema extends ToolSchemaSource | undefined = undefined, Id extends string = string> extends CoreAgentBuilder<Info, Schema, Id> {
     /** Load an Agent Skills folder. */
-    skills(directory: string, options?: SkillsOptions): this;
+    skills(directory: string): this;
     /** Attach an Agent Plugin package. */
     plugin(directory: string): this;
     output<S extends ToolSchemaSource>(schema: S): AgentBuilder<Info, S, Id>;

package/dist/builder.js

@@ -1,18 +1,18 @@
 import { Agent as CoreAgent, AgentBuilder as CoreAgentBuilder, } from "@nylorun/core/define";
-import { skills } from "./skills/index.js";
+import { skills } from "./skills/skills.js";
 import { plugin } from "./plugins/plugin.js";
 /**
- * The agent builder with the capabilities that read files: `.skills()` and `.plugin()`.
+ * The agent builder with the methods that read files: `.skills()` and `.plugin()`.
  * `@nylorun/agents/define` exports the portable builder from core, without them.
  */
 export class AgentBuilder extends CoreAgentBuilder {
     /** Load an Agent Skills folder. */
-    skills(directory, options) {
-        return this.capability(skills(directory, options));
+    skills(directory) {
+        return this.withPart(skills(directory), "skills()");
     }
     /** Attach an Agent Plugin package. */
     plugin(directory) {
-        return this.capability(plugin(directory));
+        return this.withPart(plugin(directory), "plugin()");
     }
     output(schema) {
         return super.output(schema);

package/dist/environments.d.ts

@@ -0,0 +1,387 @@
+/**
+ * Environments (protocol 11, D55, D56): `client.environments`. An Environment is one sandbox
+ * (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, { 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.
+ *
+ * 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 { 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 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;
+    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">;
+    /**
+     * 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>`. */
+    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`. 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;
+    }): 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;
+    }>;
+}
+/**
+ * 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. */
+    private readonly createSession;
+    constructor(transport: Transport, 
+    /** `AgentsClient.createSession`, bound. */
+    createSession: (options: CreateSessionOptions) => Promise<SessionClient>);
+    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}`), 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?: EnvironmentInput, 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>;
+            manifest: {
+                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;
+                } | {
+                    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;
+            state: string;
+            pod?: {
+                desired: "deleted" | "running" | "suspended";
+                observed: "creating" | "deleting" | "failed" | "lost" | "running" | "suspended";
+                volumeGeneration: number;
+                hostEpoch: number;
+                reason?: string | undefined;
+                imageDigest?: 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>;
+    /**
+     * 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;
+    }): 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 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[]>;
+    /**
+     * 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>;
+}