@nylorun/agents 0.12.0-beta → 0.14.0-beta

package/dist/ag-ui/handler.d.ts

@@ -5,8 +5,8 @@
  * person, so the Runtime keeps one person out of another's threads and does all the protocol
  * work. The browser never sees the Tenant key, the Runtime's URL or the Tenant id.
  *
- * The same threads are reachable directly from a browser with a subject token: each thread is
- * one session per subject, agent and thread on both paths.
+ * The same threads are reachable directly from a browser with a trusted issuer's token (through
+ * the operator's proxy): each thread is one session per subject, agent and thread on both paths.
  */
 import { type SubjectScope } from "@nylorun/core/contracts";
 import type { BuiltWorkflow } from "@nylorun/core/define";
@@ -27,10 +27,7 @@ export interface AgUiHandlerOptions {
     basePath?: string;
     /** Application client. Default: `createClient()`, from the environment or the Project link. */
     client?: AgentsClient | Promise<AgentsClient>;
-    /**
-     * What each subject may do through this endpoint. Default `["sessions:own"]`; add
-     * `vaults:own` if `session()` attaches the person's vaults.
-     */
+    /** What each subject may do through this endpoint. Default `["sessions:own"]`. */
     scopes?: readonly SubjectScope[];
     /** Optional per-session parameters, e.g. the person's vault for connected accounts. */
     session?(subject: string, agentId: string): AgUiSessionOptions | Promise<AgUiSessionOptions>;

package/dist/ag-ui/handler.js

@@ -5,8 +5,8 @@
  * person, so the Runtime keeps one person out of another's threads and does all the protocol
  * work. The browser never sees the Tenant key, the Runtime's URL or the Tenant id.
  *
- * The same threads are reachable directly from a browser with a subject token: each thread is
- * one session per subject, agent and thread on both paths.
+ * The same threads are reachable directly from a browser with a trusted issuer's token (through
+ * the operator's proxy): each thread is one session per subject, agent and thread on both paths.
  */
 import { parseSubjectHeaders } from "@nylorun/core/contracts";
 import { createClient, } from "../client.js";

package/dist/artifacts.d.ts

@@ -0,0 +1,116 @@
+/**
+ * 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 type { ArtifactDiff, ArtifactLink, ArtifactTree, ArtifactView, DeleteArtifactResponse, UploadArtifactResponse } from "@nylorun/core/contracts";
+import { type Transport } from "./http.js";
+/** What an upload sends: bytes, a `Blob` or `File`, text, or a stream of bytes. */
+export type ArtifactBody = Uint8Array | ArrayBuffer | Blob | string | ReadableStream<Uint8Array>;
+export interface UploadArtifactOptions {
+    /** The file's name, e.g. `brief.pdf`. */
+    readonly name: string;
+    /** The session it belongs to; required when acting for a person. */
+    readonly sessionId?: string;
+    /** The media type. Default: a `Blob`'s type, else what the name implies. */
+    readonly contentType?: string;
+    readonly labels?: Readonly<Record<string, string>>;
+    readonly signal?: AbortSignal;
+}
+/** A capability link, with the absolute URL to open on this Runtime. */
+export type ArtifactLinkWithUrl = ArtifactLink & {
+    readonly url: string;
+};
+export declare class ArtifactsClient {
+    private readonly transport;
+    constructor(transport: Transport);
+    private send;
+    /**
+     * Uploads a file as a new artifact (`POST /v1/artifacts`), in one streamed request. A file past
+     * the Tenant's per-file limit, or past its total, is refused with `413 limit_exceeded`.
+     */
+    upload(body: ArtifactBody, options: UploadArtifactOptions): Promise<UploadArtifactResponse>;
+    /** Uploads the artifact's next version. */
+    uploadVersion(artifactId: string, body: ArtifactBody, options?: {
+        contentType?: string;
+        signal?: AbortSignal;
+    }): Promise<UploadArtifactResponse>;
+    /** The artifacts of one session, or of every session this client reaches; oldest first. */
+    list(options?: {
+        sessionId?: string;
+        signal?: AbortSignal;
+    }): Promise<ArtifactView[]>;
+    /** The artifact, with every version. */
+    get(artifactId: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<ArtifactView>;
+    /**
+     * A version's bytes as the Runtime's response, to stream (`response.body`) or read. With
+     * `range`, only those bytes (`206`, `Content-Range`). Default: the latest version.
+     */
+    download(artifactId: string, options?: {
+        version?: number;
+        /** Bytes `start` to `end`, both inclusive; without `end`, to the end. */
+        range?: {
+            start: number;
+            end?: number;
+        };
+        signal?: AbortSignal;
+    }): Promise<Response>;
+    /**
+     * A capability link to one version (default: the latest): anyone holding the URL may download
+     * it, with no credential, until it expires (default 5 minutes, at most 15) or the artifact is
+     * deleted. A folder's link opens its zip, or with `file` that one file.
+     */
+    link(artifactId: string, options?: {
+        version?: number;
+        expiresIn?: number;
+        file?: string;
+        signal?: AbortSignal;
+    }): Promise<ArtifactLinkWithUrl>;
+    /** A folder version's files (default: the latest), sorted by path. */
+    tree(artifactId: string, options?: {
+        version?: number;
+        signal?: AbortSignal;
+    }): Promise<ArtifactTree>;
+    /**
+     * One file of a folder version (default: the latest) by its path in the folder, as the
+     * Runtime's response; with `range`, only those bytes (`206`).
+     */
+    file(artifactId: string, path: string, options?: {
+        version?: number;
+        /** Bytes `start` to `end`, both inclusive; without `end`, to the end. */
+        range?: {
+            start: number;
+            end?: number;
+        };
+        signal?: AbortSignal;
+    }): Promise<Response>;
+    /**
+     * What changed in a folder from version `from` (default: the one before) to `version`
+     * (default: the latest): files added, removed and changed.
+     */
+    diff(artifactId: string, options?: {
+        version?: number;
+        from?: number;
+        signal?: AbortSignal;
+    }): Promise<ArtifactDiff>;
+    /** A folder version (default: the latest) as a zip archive, streamed: the Runtime's response. */
+    zip(artifactId: string, options?: {
+        version?: number;
+        signal?: AbortSignal;
+    }): Promise<Response>;
+    private versionPath;
+    /** Deletes the artifact, every version and its bytes; its links stop working. */
+    delete(artifactId: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<DeleteArtifactResponse>;
+}

package/dist/artifacts.js

@@ -0,0 +1,116 @@
+import { segment } from "./http.js";
+function contentTypeOf(body, declared) {
+    if (declared)
+        return declared;
+    if (typeof Blob !== "undefined" && body instanceof Blob && body.type)
+        return body.type;
+    return typeof body === "string" ? "text/plain; charset=utf-8" : "application/octet-stream";
+}
+export class ArtifactsClient {
+    transport;
+    constructor(transport) {
+        this.transport = transport;
+    }
+    async send(path, body, contentType, signal) {
+        const response = await this.transport.request(path, {
+            method: "POST",
+            headers: { "content-type": contentType },
+            body: body,
+            // A stream is sent as it is read (Node's fetch needs this said).
+            ...(typeof ReadableStream !== "undefined" && body instanceof ReadableStream
+                ? { duplex: "half" }
+                : {}),
+            ...(signal ? { signal } : {}),
+        });
+        return (await response.json());
+    }
+    /**
+     * Uploads a file as a new artifact (`POST /v1/artifacts`), in one streamed request. A file past
+     * the Tenant's per-file limit, or past its total, is refused with `413 limit_exceeded`.
+     */
+    upload(body, options) {
+        const query = new URLSearchParams({ name: options.name });
+        if (options.sessionId !== undefined)
+            query.set("sessionId", options.sessionId);
+        for (const [key, value] of Object.entries(options.labels ?? {}))
+            query.append("label", `${key}=${value}`);
+        return this.send(`/v1/artifacts?${query}`, body, contentTypeOf(body, options.contentType), options.signal);
+    }
+    /** Uploads the artifact's next version. */
+    uploadVersion(artifactId, body, options = {}) {
+        return this.send(`/v1/artifacts/${segment(artifactId)}/versions`, body, contentTypeOf(body, options.contentType), options.signal);
+    }
+    /** The artifacts of one session, or of every session this client reaches; oldest first. */
+    async list(options = {}) {
+        const query = options.sessionId === undefined ? "" : `?sessionId=${segment(options.sessionId)}`;
+        const reply = await this.transport.json(`/v1/artifacts${query}`, "GET", undefined, options.signal);
+        return reply.artifacts;
+    }
+    /** The artifact, with every version. */
+    get(artifactId, options = {}) {
+        return this.transport.json(`/v1/artifacts/${segment(artifactId)}`, "GET", undefined, options.signal);
+    }
+    /**
+     * A version's bytes as the Runtime's response, to stream (`response.body`) or read. With
+     * `range`, only those bytes (`206`, `Content-Range`). Default: the latest version.
+     */
+    download(artifactId, options = {}) {
+        const range = options.range;
+        return this.transport.request(`/v1/artifacts/${segment(artifactId)}/versions/${options.version ?? "latest"}/content`, {
+            method: "GET",
+            ...(range ? { headers: { range: `bytes=${range.start}-${range.end ?? ""}` } } : {}),
+            ...(options.signal ? { signal: options.signal } : {}),
+        });
+    }
+    /**
+     * A capability link to one version (default: the latest): anyone holding the URL may download
+     * it, with no credential, until it expires (default 5 minutes, at most 15) or the artifact is
+     * deleted. A folder's link opens its zip, or with `file` that one file.
+     */
+    async link(artifactId, options = {}) {
+        const link = await this.transport.json(`/v1/artifacts/${segment(artifactId)}/links`, "POST", {
+            ...(options.version === undefined ? {} : { version: options.version }),
+            ...(options.expiresIn === undefined ? {} : { expiresIn: options.expiresIn }),
+            ...(options.file === undefined ? {} : { file: options.file }),
+        }, options.signal);
+        return { ...link, url: `${this.transport.url}${link.path}` };
+    }
+    /** A folder version's files (default: the latest), sorted by path. */
+    tree(artifactId, options = {}) {
+        return this.transport.json(`${this.versionPath(artifactId, options.version)}/tree`, "GET", undefined, options.signal);
+    }
+    /**
+     * One file of a folder version (default: the latest) by its path in the folder, as the
+     * Runtime's response; with `range`, only those bytes (`206`).
+     */
+    file(artifactId, path, options = {}) {
+        const range = options.range;
+        return this.transport.request(`${this.versionPath(artifactId, options.version)}/files/${encodeURIComponent(path)}`, {
+            method: "GET",
+            ...(range ? { headers: { range: `bytes=${range.start}-${range.end ?? ""}` } } : {}),
+            ...(options.signal ? { signal: options.signal } : {}),
+        });
+    }
+    /**
+     * What changed in a folder from version `from` (default: the one before) to `version`
+     * (default: the latest): files added, removed and changed.
+     */
+    diff(artifactId, options = {}) {
+        const query = options.from === undefined ? "" : `?from=${options.from}`;
+        return this.transport.json(`${this.versionPath(artifactId, options.version)}/diff${query}`, "GET", undefined, options.signal);
+    }
+    /** A folder version (default: the latest) as a zip archive, streamed: the Runtime's response. */
+    zip(artifactId, options = {}) {
+        return this.transport.request(`${this.versionPath(artifactId, options.version)}/zip`, {
+            method: "GET",
+            ...(options.signal ? { signal: options.signal } : {}),
+        });
+    }
+    versionPath(artifactId, version) {
+        return `/v1/artifacts/${segment(artifactId)}/versions/${version ?? "latest"}`;
+    }
+    /** Deletes the artifact, every version and its bytes; its links stop working. */
+    delete(artifactId, options = {}) {
+        return this.transport.json(`/v1/artifacts/${segment(artifactId)}`, "DELETE", undefined, options.signal);
+    }
+}

package/dist/delivery-token.js

@@ -5,9 +5,9 @@
  * WebCrypto's ECDSA verifies.
  */
 import { PROTOCOL_HEADER, PROTOCOL_VERSION, isTenantId } from "@nylorun/core/compatibility";
-import { DELIVERY_TOKEN_TYPE, subjectTokenIssuer } from "@nylorun/core/contracts";
+import { DELIVERY_TOKEN_TYPE, tenantTokenIssuer } from "@nylorun/core/contracts";
 /** The issuer prefix of a Tenant's tokens: `urn:nylorun:tenant:<tenantId>`. */
-const ISSUER_PREFIX = subjectTokenIssuer("");
+const ISSUER_PREFIX = tenantTokenIssuer("");
 /** Why a delivery was refused; `code` is sent back to the Runtime. */
 export class DeliveryVerificationError extends Error {
     code;
@@ -60,7 +60,7 @@ export async function verifyDeliveryToken(token, options) {
     if (!claims.iss.startsWith(ISSUER_PREFIX) ||
         !isTenantId(claims.iss.slice(ISSUER_PREFIX.length)))
         throw invalid("The token was not issued by a Tenant");
-    if (options.tenantId !== undefined && claims.iss !== subjectTokenIssuer(options.tenantId))
+    if (options.tenantId !== undefined && claims.iss !== tenantTokenIssuer(options.tenantId))
         throw invalid("The token is for another Tenant");
     if (options.audience !== undefined && claims.aud !== options.audience)
         throw invalid(`The token is for ${claims.aud}, not ${options.audience}`);

package/dist/http.d.ts

@@ -1,8 +1,9 @@
 import { type Compatibility, type ProtocolRange } from "@nylorun/core/compatibility";
 /**
- * Subject tokens for a client that holds no Tenant key (a browser or an app; Host feature
- * `subject-tokens`). `get` returns a current token and may fetch a new one; `invalidate`
- * drops the cached one after the Runtime answered `401 token_expired`.
+ * Bearer tokens for a client that holds no Tenant key: a trusted issuer's tokens (Host feature
+ * `trusted-issuers`), from the operator's identity provider. `get` returns a current token and
+ * may fetch a new one; `invalidate` drops the cached one after the Runtime answered
+ * `401 token_expired`.
  */
 export interface TokenSource {
     get(signal?: AbortSignal): Promise<string>;
@@ -16,10 +17,8 @@ export interface Destination {
     url?: string;
     key?: string;
     fetch?: typeof fetch;
-    /** Instead of `key`: subject tokens. The client then skips the `/health` check. */
+    /** Instead of `key`: a trusted issuer's tokens. The client then skips the `/health` check. */
     token?: TokenSource;
-    /** A publishable key (Host feature `browser-access`): names the app and its origins. */
-    publishableKey?: string;
 }
 export declare function env(name: string): string | undefined;
 export declare class RuntimeError extends Error {
@@ -39,10 +38,9 @@ export declare class IncompatibleRuntimeError extends Error {
 }
 export declare class Transport {
     readonly url: string;
-    /** The Tenant key; empty for a client that uses subject tokens. */
+    /** The Tenant key; empty for a client that uses issuer tokens. */
     readonly key: string;
     readonly token: TokenSource | undefined;
-    readonly publishableKey: string | undefined;
     readonly fetcher: typeof fetch;
     /** Sent on every request, e.g. `Nylorun-Subject` and `Nylorun-Scopes` (`withHeaders`). */
     readonly headers: Readonly<Record<string, string>>;

package/dist/http.js

@@ -1,4 +1,4 @@
-import { PROTOCOL_FEATURES, PROTOCOL_HEADER, PROTOCOL_VERSION, PUBLISHABLE_KEY_HEADER, checkCompatibility, } from "@nylorun/core/compatibility";
+import { PROTOCOL_FEATURES, PROTOCOL_HEADER, PROTOCOL_VERSION, checkCompatibility, } from "@nylorun/core/compatibility";
 export function env(name) {
     return typeof process !== "undefined" ? process.env[name] : undefined;
 }
@@ -54,10 +54,9 @@ function parseProtocolRange(value) {
 }
 export class Transport {
     url;
-    /** The Tenant key; empty for a client that uses subject tokens. */
+    /** The Tenant key; empty for a client that uses issuer tokens. */
     key;
     token;
-    publishableKey;
     fetcher;
     /** Sent on every request, e.g. `Nylorun-Subject` and `Nylorun-Scopes` (`withHeaders`). */
     headers = {};
@@ -69,14 +68,13 @@ export class Transport {
         if (!url || (!token && !key))
             throw new Error("Set Runtime url and server key explicitly or via NYLORUN_RUNTIME_URL / NYLORUN_SERVER_KEY");
         if (token && options.key)
-            throw new Error("Use a Tenant key or subject tokens, not both");
+            throw new Error("Use a Tenant key or issuer tokens, not both");
         const parsed = new URL(url);
         if (!["http:", "https:"].includes(parsed.protocol))
             throw new Error("Runtime requires an HTTP(S) URL");
         this.url = url.replace(/\/$/, "");
         this.key = key;
         this.token = token;
-        this.publishableKey = options.publishableKey;
         // Browsers may not call `/health` (it refuses `Origin`); token clients rely on `426`.
         if (token)
             this.check.compatible = true;
@@ -165,10 +163,9 @@ export class Transport {
             ? await this.token.get(init.signal ?? undefined)
             : this.key;
         headers.set("Authorization", `Bearer ${bearer}`);
-        if (this.publishableKey)
-            headers.set(PUBLISHABLE_KEY_HEADER, this.publishableKey);
         headers.set(PROTOCOL_HEADER, String(PROTOCOL_VERSION));
-        if (init.body)
+        // JSON unless the caller says otherwise (an artifact upload sends the file's type).
+        if (init.body && !headers.has("content-type"))
             headers.set("Content-Type", "application/json");
         return headers;
     }
@@ -179,7 +176,7 @@ export class Transport {
             headers: await this.authHeaders(init),
             redirect: "error",
         });
-        // An expired or revoked subject token: get a new one and try once more.
+        // An expired token: get a new one and try once more.
         if (response.status === 401 && this.token && !options.retried401) {
             const body = (await response.clone().json().catch(() => undefined));
             if (body?.code === "token_expired") {

package/dist/index.d.ts

@@ -4,14 +4,14 @@ export { Agent, AgentBuilder } from "./builder.js";
 export { AgentBuildError, AgentLifecycleError, Loop, Chain, Switch, Parallel, Map, VerdictSchema, isVerdict, withInstructions, withoutTools, WorkflowBuildError, isBuiltWorkflow, capability, CapabilityBuilder, flow, tool, defineSchema, ToolError, } from "@nylorun/core/define";
 export type { FlowAgentBuilder, Flow, Named, StageArgs, NestedStageArgs, CapabilityIdentity, } from "@nylorun/core/define";
 export type { AgentOptions, AgentManifest, BuiltAgent, BuiltWorkflow, LoopOptions, LoopDecideArgs, LoopVerifyArgs, LoopDecision, ChainOptions, SwitchOptions, ParallelOptions, MapOptions, Verdict, WorkflowBinding, WorkflowManifest, ToolDefinition, ToolExecutionContext, ToolOutcome, Patch, Decision, TurnDecision, HookScope, BeforeHook, AfterHook, JsonValue, JsonObject, } from "@nylorun/core/define";
-export type { LiveEvent, SessionEvent, SessionEventOf, EventType, SessionCommand, Action, ActionOutcome, CredentialInfo, CredentialSelection, VaultInfo, SubjectScope, } from "@nylorun/core/contracts";
+export type { LiveEvent, SessionEvent, SessionEventOf, EventType, SessionCommand, Action, ActionOutcome, CredentialInfo, CredentialSelection, VaultInfo, SubjectScope, SandboxView, SandboxEvent, SandboxKind, MessagePart, ArtifactView, ArtifactVersionView, ArtifactLink, UploadArtifactResponse, ArtifactTree, ArtifactDiff, FolderEntry, } from "@nylorun/core/contracts";
 export { SUBJECT_SCOPES } from "@nylorun/core/contracts";
 export { AgentsClient, SessionClient, createClient } from "./client.js";
-export type { ActAsOptions, AgentSource, SessionView, CommandOptions, SessionSandbox, } from "./client.js";
-export { AccessClient, PublishableKeysClient, SigningKeysClient, TokensClient, } from "./access.js";
-export type { CreateTokenOptions } from "./access.js";
-export { createTokenEndpoint } from "./token-endpoint.js";
-export type { TokenEndpointOptions } from "./token-endpoint.js";
+export { ArtifactsClient } from "./artifacts.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 { AccessClient, SigningKeysClient } from "./access.js";
 export { createActionHandler } from "./action-handler.js";
 export type { ActionHandler, ActionHandlerOptions, RegisterOptions, } from "./action-handler.js";
 export type { ExecuteActionOptions, ExecutableDefinition, } from "./execute-action.js";

package/dist/index.js

@@ -4,8 +4,9 @@ export { Agent, AgentBuilder } from "./builder.js";
 export { AgentBuildError, AgentLifecycleError, Loop, Chain, Switch, Parallel, Map, VerdictSchema, isVerdict, withInstructions, withoutTools, WorkflowBuildError, isBuiltWorkflow, capability, CapabilityBuilder, flow, tool, defineSchema, ToolError, } from "@nylorun/core/define";
 export { SUBJECT_SCOPES } from "@nylorun/core/contracts";
 export { AgentsClient, SessionClient, createClient } from "./client.js";
-export { AccessClient, PublishableKeysClient, SigningKeysClient, TokensClient, } from "./access.js";
-export { createTokenEndpoint } from "./token-endpoint.js";
+export { ArtifactsClient } from "./artifacts.js";
+export { SandboxesClient } from "./client.js";
+export { AccessClient, SigningKeysClient } from "./access.js";
 export { createActionHandler } from "./action-handler.js";
 export { resolveConnection, ConnectionError } from "./connection.js";
 export { RuntimeError, IncompatibleRuntimeError } from "./http.js";

package/dist/sandboxes.d.ts

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

package/dist/sandboxes.js

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