@nylorun/agents 0.11.0-beta → 0.13.0-beta

package/CHANGELOG.md

@@ -1,5 +1,69 @@
 # @nylorun/agents
 
+## 0.13.0-beta
+
+### Major Changes
+
+- b352feb: **File artifacts, message parts and capability links (protocol 6).** Upgrade these with the Runtime: they speak protocol 6, which this Runtime serves beside 4 and 5. See MIGRATION.md.
+
+  - **`@nylorun/runtime`: file artifacts.** A file is an artifact: an `af_` id, a name and numbered immutable versions, with rows in the new `artifacts` and `artifact_versions` tables (migration `0004_artifacts`) and bytes in the Object store (`BlobStore`). `POST /v1/artifacts?name=&sessionId=` uploads a file in one streamed request and `POST /v1/artifacts/{id}/versions` adds a version, within the Tenant's limits (`GET`/`PUT /v1/tenant/artifacts`: 100 MiB per file and 10 GiB in all by default); a body past either is `413 limit_exceeded`, refused mid-stream with nothing stored. `GET /v1/artifacts` lists them (by session), `GET /v1/artifacts/{id}` reads one with its versions, `GET /v1/artifacts/{id}/versions/{n|latest}/content` downloads through the Runtime with HTTP Range (`206`, `Content-Range`, `416`), and `DELETE /v1/artifacts/{id}` deletes it with its bytes. A session's artifacts go with it on a sessions reset, and appear in its history as `artifact.created`, `artifact.version.created` and `artifact.deleted` (new in the event catalog). A subject reaches only the artifacts of their own sessions.
+  - **`@nylorun/runtime`: capability links.** `POST /v1/artifacts/{id}/links` mints a short-lived path, `/v1/artifact-links/<token>`, that downloads one version (with Range) with no credential and no `Nylorun-Protocol`: an ES256 JWT (`typ: nylorun-artifact+jwt`) signed with the Tenant's signing key, at most 15 minutes, and dead once the artifact is deleted. The Host logs its path without the token.
+  - **Breaking (`@nylorun/core`, `@nylorun/runtime`): message `parts`.** A user message may carry `parts`: `text`, and `file` by `artifactId` (and `version`, else the latest, pinned when the message is accepted). Model-gate reads the file from the Object store: an image goes to the model as image input, a text file as text, and any other file fails the call (`invalid_request`). The record and the transcript hold only the reference. The gateway builds its `BlobStore` from `NYLORUN_OBJECT_STORE_*` (the Tenant's `fs` store without it). `PROTOCOL_VERSION` is 6; `HOST_PROTOCOL` is 4–6 and protocol 6 clients require the feature `artifacts`.
+  - **`@nylorun/runtime`: `save_artifact`.** A session with a sandbox gets the `nylorun.artifacts` capability, whose `save_artifact` tool saves a sandbox file (`path`) or text (`content`) as an artifact of the session, carrying the turn and tool call on its event.
+  - **Breaking (`@nylorun/runtime`): `MediaStore` is removed.** `MediaStore` and `localMedia` leave `@nylorun/runtime/node`, and `piModel` takes `files` (a resolver from an artifact reference to its bytes) instead of `media`; images are file artifacts. The image checks (`decodeImageBase64`, `validateImageBytes`, `IMAGE_MEDIA_TYPES`, `MAX_IMAGE_BYTES`) stay.
+  - **`@nylorun/agents`:** `client.artifacts` (`upload`, `uploadVersion`, `list`, `get`, `download` with a range, `link`, `delete`), also on `BrowserClient`, and `session.inputParts(parts)`. A request with a body of its own type keeps it.
+  - `@nylorun/admin`, `@nylorun/cli`, `nylorun`, `@nylorun/studio`: speak protocol 6.
+
+### Minor Changes
+
+- 6077272: **Folder artifacts and the turn-end outputs export (F8.2).** Part of protocol 6, with file artifacts.
+
+  - **`@nylorun/runtime`: the turn-end export.** When an agent's turn completes, the Runtime reads `/workspace/outputs` of the session's sandbox and keeps it as a version of the session's folder artifact `outputs`: the first export creates it, and each later turn whose outputs changed adds a version (`artifact.created` / `artifact.version.created` with `kind: "folder"`, `source: "export"`, `fileCount` and `claimed: true`, since the listing and bytes are what the sandbox supplied). Nothing is exported without a sandbox or without outputs. An export past 10,000 files, 1 GiB, the per-file limit or the Tenant total stores nothing and records `artifact.export.skipped` with its reason; a failure records `artifact.export.failed`. Neither fails the turn. Core reads the workspace through one seam, `WorkspaceReader`, which the Harness API and pod sandboxes will implement later.
+  - **`@nylorun/runtime`: folder artifacts.** A folder version is a manifest of paths to content-addressed files: each file's bytes are stored once at `blobs/sha256/<hex>`, so an unchanged file is never stored again, and the Tenant total (`GET /v1/tenant/artifacts` `usedBytes`) counts it once. New routes: `GET /v1/artifacts/{id}/versions/{n|latest}/tree` (the manifest), `…/files/{path}` (one file by its percent-encoded path, with Range), `…/diff?from=n` (files added, removed and changed) and `…/zip` (a streamed zip). `POST /v1/artifacts/{id}/links` takes `file` to link one file of a folder; a folder's link without it opens the zip. A folder's `/content`, a new version uploaded to a folder, and a message part naming a folder are `400`. Deleting a folder removes the files no other version names. Migration `0006_folder_artifacts` allows the `folder` kind and adds the `artifact_content` table.
+  - **`@nylorun/core`:** `ArtifactKindSchema` (`file`, `folder`), the `export` source, `FolderEntrySchema`, `FolderManifestSchema`, `ArtifactTreeSchema`, `ArtifactDiffSchema`, the `artifact.export.skipped` and `artifact.export.failed` events, and `fileCount` and `claimed` on `artifact.created` / `artifact.version.created`.
+  - **`@nylorun/agents`:** `client.artifacts.tree()`, `file()`, `diff()` and `zip()`, and `link(id, { file })`.
+
+- 926711b: **Sandboxes are a resource (F7.1, blueprint D39; Host feature `sandboxes`).** A sandbox has its own id, a kind, a spec and labels, and outlives the sessions attached to it. Additive: protocol 5 is unchanged.
+
+  - `PUT /v1/sandboxes/{id}` creates a sandbox or finds the one with that id (get-or-create in one call); `GET /v1/sandboxes/{id}`, `GET /v1/sandboxes?label=key=value` (repeatable), `GET /v1/sandboxes/{id}/events` and `DELETE /v1/sandboxes/{id}`. Ids are `/`-separated segments (`team-a/proj-42`), sent percent-encoded as one path segment. Only kind `virtual` runs; `pod` is refused with `sandbox_unavailable`. The spec is resolved against the Tenant's limits and fixed once the sandbox exists; labels can change.
+  - A session attaches with `sandbox: { id }` and shares the sandbox's `/workspace` with every other session attached to it. Turns are serial per sandbox: a second session's turn is refused with `409 sandbox_busy` while another runs. Deleting a session (a sessions reset) only detaches it. Deleting a sandbox is refused while a turn runs in it; afterwards an attached session's next turn is refused with `sandbox_unavailable` until a sandbox with that id exists again.
+  - Subject tokens carry an `sbx` claim: `POST /v1/tokens` takes `sandboxes`, exact ids or prefixes ending in `/*` (at most 16). A token reaches only the sandboxes they match, checked when a session attaches and at every turn start (`403 sandbox_not_granted`); any other sandbox is the 404 of a missing one. The new scope `sandboxes:write` lets a role create and delete the sandboxes its grants reach. Application keys reach every sandbox.
+  - The Tenant holds at most `limits.sandboxes` sandboxes (`PUT /v1/tenant/sandbox`, default 100); one more is `409 limit_exceeded`.
+  - Lifecycle events (`sandbox.created`, `sandbox.attached`, `sandbox.detached`, `sandbox.deleted`) go to the sandbox's own stream in the record, through the record module; the session's log records `sandbox.attached`. The sandbox stream is not relayed to S2.
+  - New error codes `sandbox_not_granted`, `sandbox_busy` and `sandbox_unavailable`; the session view gains `sandboxId` and `sandboxSource: "sandbox"`. Migration `0004_sandbox_resources` adds `sandbox_resources`, `nylorun_streams.sandbox_events` and the sessions' `sandbox_id` column.
+  - `@nylorun/agents`: `client.sandboxes` with `ensure(id, spec)`, `get`, `list({ labels })`, `delete`, `events`, and `forSession({ session, spec })`, which creates a sandbox for one session, opens the session on it, and deletes it with `release()`. It replaces sharing through another session (`sandbox: { session }` and the view's `sandboxOwnerId`, now deprecated). `client.tokens.create` takes `sandboxes`.
+  - `nylorun sandbox ls [--label key=value]... [--json]` and `nylorun sandbox rm <id>` list and delete the running local Tenant's sandboxes.
+
+### Patch Changes
+
+- Pin core to the tested release.
+- Updated dependencies [b352feb]
+- Updated dependencies [6077272]
+- Updated dependencies [b6bf1f5]
+- Updated dependencies [8ed4ea6]
+- Updated dependencies [678e085]
+- Updated dependencies [926711b]
+  - @nylorun/core@0.12.0-beta
+
+## 0.12.0-beta
+
+### Minor Changes
+
+- 4b9906f: **Breaking: "Tenant" replaces "stack", and `nylorun start` works anywhere.** Each local installation holds one Tenant, and its name is the Tenant's name, so help, output, errors and docs say Tenant. See MIGRATION.md.
+
+  - **Breaking (`nylorun`): selection.** Every command acts on the Tenant `--tenant <name>` names (replaces `--name`, which is removed), else `NYLORUN_TENANT` (replaces `NYLORUN_STACK`), else the Project link's `tenant`; `start` in a project names a new one after the project directory. Outside a project, or with `start --no-link`, commands act on the Tenant `default`. In a project without a link, commands other than `start` exit 2 and list the machine's Tenants. A name starting with `tn_` (a Tenant id) is refused.
+  - **Breaking (`nylorun`): files.** Host roots are under `~/.nylorun/tenants/<name>/` (was `~/.nylorun/stacks/<name>/`) with `tenant.json` (was `stack.json`); the `.env` key is `NYLORUN_TENANT_NAME` (was `NYLORUN_STACK_NAME`); `NYLORUN_COMPOSE_PROJECT` replaces `NYLORUN_STACK_PROJECT`. Compose projects stay `nylorun-<name>`. Every command first moves 0.4 Host roots from `~/.nylorun/stacks/` to `~/.nylorun/tenants/` (renaming `stack.json` and the `.env` key), so they keep their volumes and keys. `nylorun ls` lists only directories with `tenant.json`.
+  - **Breaking (`nylorun`): removed.** `nylorun legacy` and all handling of the single stack of releases before 0.4; the hidden `nylorun stack <cmd>` alias; `nylorun doctor stack|runtime`. Output says Tenant: `ls` prints `TENANT` and JSON `{ "tenants": [...] }`, `status` prints the Tenant id on its own line, and `doctor`'s row is `tenant`.
+  - **Breaking: Project link format 3.** `.nylorun/link.json` is `{ "format": 3, "tenant", "tenantId", "hostUrl", "hostId" }`; `tenant` replaces `stack`. `@nylorun/agents`, `@nylorun/cli` and `@nylorun/admin` refuse an older link and name `npx nylorun start`, which rewrites it. `@nylorun/core`'s `ProjectLinkFileSchema` parses formats 0–3 with `tenant`.
+  - **Breaking (`@nylorun/admin`):** `createAdmin({ tenant })` replaces `{ stack }`, `tenantHostRoot(name)` replaces `stackHostRoot(name)`, and local resolution reads `NYLORUN_TENANT` and the link's `tenant`.
+  - `@nylorun/cli`: `status` and `endpoints` drop the `stack` line and JSON key; messages say Tenant. `@nylorun/agents`: a Runtime too old for the client says "update the Runtime (npx nylorun@latest start)". `@nylorun/studio`: setup hints say Tenant. `@nylorun/create-agent`: the next steps describe `npx nylorun@beta start` as this project's Tenant and its link.
+
+### Patch Changes
+
+- Pin core to the tested release.
+- Updated dependencies [4b9906f]
+  - @nylorun/core@0.11.0-beta
+
 ## 0.11.0-beta
 
 ### Major Changes

package/README.md

@@ -30,7 +30,7 @@ reads the Tenant's public keys. Mark a long tool
 posts the result. `npx @nylorun/cli endpoints` shows each endpoint and how its
 deliveries are doing.
 
-The URL must be one the Runtime can reach: `localhost` on the local stack
+The URL must be one the Runtime can reach: `localhost` on a local Tenant
 (its Runtime runs in Docker and maps `localhost` to this machine), a public URL
 in production, or a tunnel (ngrok, Cloudflare Tunnel) for a remote Runtime.
 
@@ -49,13 +49,14 @@ for upgrading from `nylorun serve`.
 2. Environment — if `NYLORUN_RUNTIME_URL` or `NYLORUN_SERVER_KEY` is set, both
    must be present
 3. Project link — `.nylorun/link.json` + `credentials.json` (the application
-   key), written by `npx nylorun start`. A link from before one Tenant per
-   installation (format 0 or 1) fails with `connection_missing`: run
-   `npx nylorun start` in the project again.
+   key), written by `npx nylorun start`. A link from an older nylorun
+   (format 0 to 2) fails with `connection_missing`: run `npx nylorun start` in
+   the project again.
 
 Sources never mix. Partial environment fails with `connection_missing`. A
-Runtime serves one Tenant, so nothing names it: the `tenant` option and
-`NYLORUN_TENANT` are gone (protocol 5).
+Runtime serves one Tenant, so nothing names it: the `tenant` option is gone
+(protocol 5), and `NYLORUN_TENANT`, which picks a local Tenant for `nylorun`,
+is ignored.
 
 ```ts
 import { Agent, createActionHandler, createClient, tool } from "@nylorun/agents";
@@ -106,7 +107,7 @@ eval "$(npx @nylorun/cli env)"
 # → NYLORUN_RUNTIME_URL, NYLORUN_SERVER_KEY
 ```
 
-Every request sets `Nylorun-Protocol` (5) and no `Nylorun-Tenant`: the Runtime
+Every request sets `Nylorun-Protocol` (6) and no `Nylorun-Tenant`: the Runtime
 serves one Tenant. Before the first authenticated
 request, `Transport` fetches `/health` once, checks protocol compatibility, and
 throws `IncompatibleRuntimeError` / `incompatible_host` when the Host range or
@@ -155,7 +156,22 @@ const session = await client.createSession({
 
 The model gets `bash`, `read`, `write`, `edit`, `grep` and `glob` on a persistent `/workspace`. These tools run in the Runtime, not in your process, so sandbox-only agents need no Action endpoint. The Runtime decides where the sandbox runs: today an emulated shell in the Runtime process, which is not a VM boundary and takes no `image`.
 
-`sandbox` takes `false` for none, `{ session }` to share another session's sandbox, or an inline sandbox as above; omit it for the Tenant's default. The Runtime checks it against the Tenant's limits (`GET`/`PUT /v1/tenant/sandbox`: a network ceiling, a resource maximum, the idle timeout) and answers `400` with every problem it finds. A caller acting for a user (`app.as(...)`) can't define one inline; it gets the Tenant's default or `false`. Private networks, loopback, the host and cloud metadata endpoints are always blocked.
+`sandbox` takes `false` for none, `{ id }` to attach a sandbox resource (below), or an inline sandbox as above; omit it for the Tenant's default. `{ session }`, sharing another session's sandbox, still works and is deprecated. The Runtime checks it against the Tenant's limits (`GET`/`PUT /v1/tenant/sandbox`: a network ceiling, a resource maximum, the idle timeout) and answers `400` with every problem it finds. A caller acting for a user (`app.as(...)`) can't define one inline; it gets the Tenant's default or `false`. Private networks, loopback, the host and cloud metadata endpoints are always blocked.
+
+A sandbox can also be a resource with its own id, which outlives the sessions attached to it (Host feature `sandboxes`). Whether it serves one session, one person or a project is your choice:
+
+```ts
+// One per session: created with the session, deleted by release().
+const { session, release } = await client.sandboxes.forSession({
+  session: { agentId: "analyst", ownerUserId },
+  spec: { network: { allow: ["pypi.org"] } },
+});
+// One per person or project: get-or-create by id, then attach sessions to it.
+await client.sandboxes.ensure("team-a/proj-42", { labels: { project: "acme" } });
+await client.createSession({ agentId: "analyst", ownerUserId, sandbox: { id: "team-a/proj-42" } });
+```
+
+Sessions attached to one sandbox share its `/workspace`, and one turn runs in it at a time: a second session's turn is refused with `409 sandbox_busy` until the first ends. Deleting a session only detaches it. A spec is fixed once the sandbox exists; `labels` can change. `client.sandboxes.list({ labels })`, `get(id)` and `delete(id)` manage them, and `npx nylorun sandbox ls | rm` does the same on a local Tenant. A subject token reaches only the sandboxes it is minted for, checked at every turn start: `client.tokens.create({ subject, role, sandboxes: ["team-a/*", "user-42"] })` takes exact ids or prefixes ending in `/*`. Creating and deleting through a subject token needs a role with `sandboxes:write`. The Tenant holds at most `limits.sandboxes` of them (`PUT /v1/tenant/sandbox`, default 100).
 
 Add an agent with `.subagents()` to let the model delegate to it:
 
@@ -262,7 +278,8 @@ directly and run as before; a flow agent can't be a child of them.
 
 The agents in a flow share one sandbox: open the flow's session with it,
 `createSession({ …, sandbox: { … } })`, and every agent, tool step and `verify` in the
-flow uses it. Share it with another session with `sandbox: { session }`, and call
+flow uses it. Share it with other sessions by opening them all on one sandbox resource
+(`sandbox: { id }`, see `client.sandboxes`), and call
 built-ins via `session.sandbox` (application) or `ctx.sandbox` (a tool).
 Observe with `session.observe({ follow: true })` to merge linked agent streams;
 `pending()` lists waits across the tree. Studio renders the manifest tree and
@@ -425,6 +442,56 @@ What the Runtime answers (Host feature `a2a-endpoint`):
   no header the partner chose except `A2A-Version` and `A2A-Extensions`. Without
   `a2a-endpoint` on the Runtime it answers `502` (`runtime_feature_missing`).
 
+## Files: artifacts and message parts
+
+Files users upload or agents make are **artifacts** (protocol 6): an id, a name and
+numbered versions, kept by the Runtime. `client.artifacts` uploads a file in one
+streamed request, lists, downloads with Range, mints capability links and deletes;
+a message names files in its `parts`, and the model reads an image as an image and
+a text file as text:
+
+```ts
+const { artifact } = await client.artifacts.upload(file, { name: "room.png", sessionId });
+await session.inputParts(
+  [{ type: "text", text: "Redesign this room" }, { type: "file", artifactId: artifact.artifactId }],
+  { idempotencyKey: crypto.randomUUID() },
+);
+
+const files = await client.artifacts.list({ sessionId }); // what the user and the agent saved
+const part = await client.artifacts.download(files[0].artifactId, { range: { start: 0, end: 1023 } });
+const { url } = await client.artifacts.link(files[0].artifactId); // no credential needed, 5 minutes
+```
+
+A session with a sandbox gives the agent `save_artifact`, which saves a file it
+made as an artifact of the session; each new artifact or version appears in the
+session's events as `artifact.created` or `artifact.version.created`. The Tenant's
+limits (`PUT /v1/tenant/artifacts`: 100 MiB per file and 10 GiB in all by default)
+refuse a larger upload with `413 limit_exceeded`, and nothing is stored. Acting for
+a person (`as()`, a subject token), a client reaches only the artifacts of that
+person's sessions, and an upload names one of them.
+
+### Outputs: folder artifacts
+
+At the end of each turn, the Runtime exports the files the agent wrote into
+`/workspace/outputs` of its sandbox as a version of the session's **folder**
+artifact `outputs` (kind `folder`): the first export creates it, and each later
+turn whose outputs changed adds a version, announced by `artifact.created` or
+`artifact.version.created` with `source: "export"`. A file that did not change is
+stored once. Read a folder as a tree, one file by path, a diff or a zip:
+
+```ts
+const outputs = (await client.artifacts.list({ sessionId })).find((a) => a.kind === "folder");
+const { entries } = await client.artifacts.tree(outputs.artifactId); // [{ path, size, sha256, contentType }]
+const page = await client.artifacts.file(outputs.artifactId, "app/index.html", { range: { start: 0 } });
+const { added, removed, changed } = await client.artifacts.diff(outputs.artifactId, { from: 1 });
+const zip = await client.artifacts.zip(outputs.artifactId); // a streamed Response
+const { url } = await client.artifacts.link(outputs.artifactId, { file: "app/index.html" }); // or the zip without `file`
+```
+
+An export past a limit (10,000 files, 1 GiB, the per-file limit or the Tenant
+total) stores nothing and records `artifact.export.skipped`; the turn still
+completes.
+
 ## Acting for a person (app servers)
 
 A server that signs people in and calls the Runtime for them (an "app server")
@@ -450,7 +517,7 @@ compatibility check, so calling `as()` per request is cheap.
 
 | Scope | Allows |
 | --- | --- |
-| `sessions:own` | The person's own sessions: create, list, read, stream, message, approve, respond, cancel |
+| `sessions:own` | The person's own sessions: create, list, read, stream, message, approve, respond, cancel; and their artifacts |
 | `vaults:own` | The person's own vaults and credentials |
 | `agents:read` | Listing the Tenant's agents |
 | `agents:write` | Saving agents; listing agents, models and providers |

package/dist/a2a/handler.js

@@ -45,7 +45,7 @@ export function createA2aHandler(options) {
             const client = await (options.client ?? createClient());
             const features = await client.hostFeatures();
             if (!features.includes(REQUIRED_FEATURE))
-                throw new Problem(502, `The Runtime does not support ${REQUIRED_FEATURE}; upgrade the stack (nylorun up).`, "runtime_feature_missing");
+                throw new Problem(502, `The Runtime does not support ${REQUIRED_FEATURE}; update the Runtime (npx nylorun@latest start).`, "runtime_feature_missing");
             return client;
         })();
         ready.catch(() => {

package/dist/access.d.ts

@@ -15,6 +15,11 @@ export interface CreateTokenOptions {
     scopes?: readonly TokenScope[];
     /** Narrow the role's agents. Default: all of the role's agents. */
     agents?: readonly string[];
+    /**
+     * The sandboxes the token reaches (its `sbx` claim): exact ids, or prefixes ending in `/*`
+     * (`team-a/*`). Default: none (Host feature `sandboxes`).
+     */
+    sandboxes?: readonly string[];
     /** 60 to 900 seconds, at most the policy's `maxTtlSeconds`. Default: that maximum. */
     ttlSeconds?: number;
     signal?: AbortSignal;

package/dist/access.js

@@ -14,6 +14,7 @@ export class TokensClient {
             role: options.role,
             ...(options.scopes ? { scopes: [...options.scopes] } : {}),
             ...(options.agents ? { agents: [...options.agents] } : {}),
+            ...(options.sandboxes ? { sandboxes: [...options.sandboxes] } : {}),
             ...(options.ttlSeconds === undefined ? {} : { ttlSeconds: options.ttlSeconds }),
         }, options.signal);
     }

package/dist/ag-ui/handler.js

@@ -65,7 +65,7 @@ export function createAgUiHandler(options) {
             const features = await client.hostFeatures();
             const missing = REQUIRED_FEATURES.filter((f) => !features.includes(f));
             if (missing.length > 0)
-                throw new Problem(502, `The Runtime does not support ${missing.join(", ")}; upgrade the stack (nylorun up).`, "runtime_feature_missing");
+                throw new Problem(502, `The Runtime does not support ${missing.join(", ")}; update the Runtime (npx nylorun@latest start).`, "runtime_feature_missing");
             return client;
         })();
         ready.catch(() => {

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`, a subject 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/browser.d.ts

@@ -1,6 +1,7 @@
 import type { CredentialSelection, VaultInfo } from "@nylorun/core/contracts";
 import type { TokenSource } from "./http.js";
 import { AgentsClient, type SessionClient } from "./session-client.js";
+import type { ArtifactsClient } from "./artifacts.js";
 /** What the token callback returns: the token, or the app server's `{ token, expiresAt }`. */
 export type TokenReply = string | {
     token: string;
@@ -58,12 +59,18 @@ export declare class BrowserClient {
         sessions: import("./session-client.js").SessionView[];
     }>;
     session(sessionId: string): SessionClient;
+    /** The person's file artifacts, in their own sessions (protocol 6). */
+    get artifacts(): ArtifactsClient;
     /** A session of the person's own; the owner is always the token's subject. */
     createSession(options: {
         id?: string;
         agentId: string;
         vaultIds?: readonly string[];
         credentialSelections?: readonly CredentialSelection[];
+        /** A sandbox the token's `sandboxes` grants reach (Host feature `sandboxes`). */
+        sandbox?: {
+            id: string;
+        };
     }): Promise<SessionClient>;
     createVault(options: {
         name: string;

package/dist/browser.js

@@ -153,6 +153,10 @@ export class BrowserClient {
     session(sessionId) {
         return this.client.session(sessionId);
     }
+    /** The person's file artifacts, in their own sessions (protocol 6). */
+    get artifacts() {
+        return this.client.artifacts;
+    }
     /** A session of the person's own; the owner is always the token's subject. */
     async createSession(options) {
         return this.client.createSession({

package/dist/connection.js

@@ -11,7 +11,7 @@ export class ConnectionError extends Error {
 }
 function missing(tried) {
     throw new ConnectionError(`connection_missing: no Runtime connection found (tried ${tried.join(", ")}). ` +
-        `Run "npx nylorun start" in this project to start its stack and link it, ` +
+        `Run "npx nylorun start" in this project to start its Tenant and link it, ` +
         `or set NYLORUN_RUNTIME_URL and NYLORUN_SERVER_KEY.`);
 }
 function stripTrailingSlash(url) {
@@ -37,11 +37,10 @@ async function readProjectLink(startDir) {
             throw error;
         }
         const link = ProjectLinkFileSchema.parse(JSON.parse(linkRaw));
-        // Formats 0 and 1 named a Tenant on a multi-Tenant Host of an older Runtime.
-        if (link.format < 2)
-            throw new ConnectionError(`connection_missing: the Project link at ${linkPath} is for a stack of an older ` +
-                `Runtime, before one Tenant per installation. Run "npx nylorun start" in this project ` +
-                `to start its own stack and link it again.`);
+        // Formats 0 to 2 are from older releases.
+        if (link.format < 3)
+            throw new ConnectionError(`connection_missing: the Project link at ${linkPath} is from an older nylorun. ` +
+                `Run "npx nylorun start" in this project to link it again.`);
         const credentials = ProjectCredentialsFileSchema.parse(JSON.parse(await readFile(join(nylorun, "credentials.json"), "utf8")));
         return {
             url: stripTrailingSlash(link.hostUrl),

package/dist/http.js

@@ -168,7 +168,8 @@ export class Transport {
         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;
     }

package/dist/index.d.ts

@@ -4,10 +4,13 @@ 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 { 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, PublishableKeysClient, SigningKeysClient, TokensClient, } from "./access.js";
 export type { CreateTokenOptions } from "./access.js";
 export { createTokenEndpoint } from "./token-endpoint.js";

package/dist/index.js

@@ -4,6 +4,8 @@ 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 { ArtifactsClient } from "./artifacts.js";
+export { SandboxesClient } from "./client.js";
 export { AccessClient, PublishableKeysClient, SigningKeysClient, TokensClient, } from "./access.js";
 export { createTokenEndpoint } from "./token-endpoint.js";
 export { createActionHandler } from "./action-handler.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),
+        };
+    }
+}

package/dist/session-client.d.ts

@@ -4,8 +4,10 @@
  * connection from the environment or the Project link.
  */
 import type { AgentManifest, BuiltAgent, BuiltWorkflow, JsonValue, SandboxToolName, WorkflowManifest } from "@nylorun/core/define";
-import { type SubjectScope, type CredentialInfo, type CredentialSelection, type SandboxRequest, type SessionCommand, type VaultInfo } from "@nylorun/core/contracts";
+import { type SubjectScope, type CredentialInfo, type CredentialSelection, type MessagePart, type SandboxRequest, type SessionCommand, type VaultInfo } from "@nylorun/core/contracts";
 import { AccessClient, TokensClient } from "./access.js";
+import { SandboxesClient } from "./sandboxes.js";
+import { ArtifactsClient } from "./artifacts.js";
 import { Transport, type Destination } from "./http.js";
 /** Application-principal access to a session's sandbox built-ins (workflows.md §8). */
 export type SessionSandbox = {
@@ -28,6 +30,24 @@ export interface SessionView {
     waits?: unknown;
     [key: string]: unknown;
 }
+/** `AgentsClient.createSession`'s options. */
+export interface CreateSessionOptions {
+    id?: string;
+    agentId: string;
+    ownerUserId: string;
+    info?: Record<string, unknown>;
+    requestId?: string;
+    vaultIds?: readonly string[];
+    credentialSelections?: readonly CredentialSelection[];
+    /**
+     * The session's sandbox: omit for the Tenant default, `false` for none, `{ id }` to attach a
+     * sandbox resource (`client.sandboxes`, Host feature `sandboxes`), or an inline sandbox
+     * (`image`, `network.allow`, `resources`) checked against the Tenant's limits. `{ session }`
+     * shares another session's and is deprecated: use `client.sandboxes.forSession()` or
+     * `ensure()` and `{ id }`. Fixed once the session exists.
+     */
+    sandbox?: SandboxRequest;
+}
 export interface ActAsOptions {
     /** What the subject may do; the Runtime grants nothing else. Default `["sessions:own"]`. */
     scopes?: readonly SubjectScope[];
@@ -51,6 +71,13 @@ export declare class AgentsClient {
     get tokens(): TokensClient;
     /** The access policy, signing keys and revocations (Host feature `subject-tokens`). */
     get access(): AccessClient;
+    /**
+     * Sandboxes as a resource (Host feature `sandboxes`): `ensure` one by id, `list` them by
+     * label, `delete` one, or give a session its own with `forSession`.
+     */
+    get sandboxes(): SandboxesClient;
+    /** File artifacts: upload, list, download with Range, capability links (protocol 6). */
+    get artifacts(): ArtifactsClient;
     /** The Runtime's protocol features, including optional ones such as `transcript-events`. */
     hostFeatures(options?: {
         signal?: AbortSignal;
@@ -72,21 +99,7 @@ export declare class AgentsClient {
         implementationVersion: string;
         requestId?: string;
     }): Promise<unknown>;
-    createSession(options: {
-        id?: string;
-        agentId: string;
-        ownerUserId: string;
-        info?: Record<string, unknown>;
-        requestId?: string;
-        vaultIds?: readonly string[];
-        credentialSelections?: readonly CredentialSelection[];
-        /**
-         * The session's sandbox: omit for the Tenant default, `false` for none, `{ session }` to share
-         * another session's, or an inline sandbox (`image`, `network.allow`, `resources`) checked
-         * against the Tenant's limits. Fixed once the session exists.
-         */
-        sandbox?: SandboxRequest;
-    }): Promise<SessionClient>;
+    createSession(options: CreateSessionOptions): Promise<SessionClient>;
     createVault(options: {
         name: string;
         ownerUserId: string;
@@ -181,6 +194,17 @@ export declare class SessionClient {
         cursor: string | null;
         requestId: string;
     }>;
+    /**
+     * Start a turn with text and file parts (protocol 6): a file part names an artifact (upload
+     * it with `client.artifacts.upload`), at a version or its latest, and the model reads it, an
+     * image as an image and a text file as text.
+     */
+    inputParts(parts: readonly MessagePart[], options: CommandOptions): Promise<{
+        status: "accepted";
+        turnId: string | null;
+        cursor: string | null;
+        requestId: string;
+    }>;
     approve(interactionId: string, approved: boolean, options: CommandOptions): Promise<{
         status: "accepted";
         turnId: string | null;
@@ -280,3 +304,5 @@ export { RuntimeError, IncompatibleRuntimeError } from "./http.js";
 export type { Destination, IncompatibleReason } from "./http.js";
 export type { LiveEvent } from "@nylorun/core/contracts";
 export { AccessClient, PublishableKeysClient, SigningKeysClient, TokensClient, } from "./access.js";
+export { SandboxesClient } from "./sandboxes.js";
+export type { ForSessionOptions, SandboxSpec, SessionSandboxHandle } from "./sandboxes.js";

package/dist/session-client.js

@@ -3,6 +3,8 @@ import { z } from "zod";
 import { SCOPES_HEADER, SUBJECT_HEADER } from "@nylorun/core/compatibility";
 import { parseSessionEvent, parseSubjectHeaders, } from "@nylorun/core/contracts";
 import { AccessClient, TokensClient } from "./access.js";
+import { SandboxesClient } from "./sandboxes.js";
+import { ArtifactsClient } from "./artifacts.js";
 import { Transport, id, segment } from "./http.js";
 import { observeSSE } from "./sse.js";
 function sessionSandboxOf(transport, sessionId) {
@@ -104,6 +106,17 @@ export class AgentsClient {
     get access() {
         return new AccessClient(this.transport);
     }
+    /**
+     * Sandboxes as a resource (Host feature `sandboxes`): `ensure` one by id, `list` them by
+     * label, `delete` one, or give a session its own with `forSession`.
+     */
+    get sandboxes() {
+        return new SandboxesClient(this.transport, (options) => this.createSession(options));
+    }
+    /** File artifacts: upload, list, download with Range, capability links (protocol 6). */
+    get artifacts() {
+        return new ArtifactsClient(this.transport);
+    }
     /** The Runtime's protocol features, including optional ones such as `transcript-events`. */
     hostFeatures(options = {}) {
         return this.transport.hostFeatures(options.signal);
@@ -255,6 +268,19 @@ export class SessionClient {
             ? { ...base, content: value }
             : { ...base, data: value }, options.signal);
     }
+    /**
+     * Start a turn with text and file parts (protocol 6): a file part names an artifact (upload
+     * it with `client.artifacts.upload`), at a version or its latest, and the model reads it, an
+     * image as an image and a text file as text.
+     */
+    inputParts(parts, options) {
+        return this.command({
+            type: "message",
+            requestId: options.requestId ?? id(),
+            idempotencyKey: options.idempotencyKey,
+            parts: [...parts],
+        }, options.signal);
+    }
     approve(interactionId, approved, options) {
         return this.command({
             type: "approve",
@@ -373,3 +399,4 @@ export class SessionClient {
 }
 export { RuntimeError, IncompatibleRuntimeError } from "./http.js";
 export { AccessClient, PublishableKeysClient, SigningKeysClient, TokensClient, } from "./access.js";
+export { SandboxesClient } from "./sandboxes.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nylorun/agents",
-  "version": "0.11.0-beta",
+  "version": "0.13.0-beta",
   "description": "Nylorun agent definitions, session client and Action endpoint",
   "type": "module",
   "license": "Apache-2.0",
@@ -47,7 +47,7 @@
     "test": "vitest run --passWithNoTests"
   },
   "dependencies": {
-    "@nylorun/core": "0.10.0-beta",
+    "@nylorun/core": "0.12.0-beta",
     "gray-matter": "^4.0.3"
   },
   "peerDependencies": {
@@ -56,7 +56,7 @@
   "devDependencies": {
     "@types/node": "^24.0.0",
     "typescript": "npm:@typescript/typescript6@^6.0.2",
-    "vitest": "^5.0.1"
+    "vitest": "^5.0.2"
   },
   "engines": {
     "node": ">=24"