disk 0.8.17 → 0.8.19

package/dist/src--b7LHPh_.mjs

@@ -0,0 +1,1398 @@
+import { t as toSegments } from "./paths-Br9snUhy.mjs";
+import createClientDefault from "openapi-fetch";
+import { XMLParser } from "fast-xml-parser";
+//#region src/s3xml.ts
+const parser = new XMLParser({
+	isArray: (name) => name === "Contents" || name === "CommonPrefixes",
+	parseTagValue: false,
+	trimValues: true,
+	ignoreAttributes: true
+});
+/** Parse an XML document into a plain object. Returns {} for empty/blank input. */
+function parseXml(xml) {
+	if (!xml.trim()) return {};
+	return parser.parse(xml);
+}
+//#endregion
+//#region src/errors.ts
+/**
+* Base class for every error the SDK throws. Catch with `instanceof ArchilError`
+* to handle control-plane and S3 failures uniformly; `status` is the HTTP status
+* code and `code` a machine-readable error code when the server provided one.
+*/
+var ArchilError = class extends Error {
+	/** HTTP status code associated with the failure. */
+	status;
+	/** Machine-readable error code (e.g. an S3 code like "NoSuchKey"), if known. */
+	code;
+	constructor(message, status, code) {
+		super(message);
+		this.name = "ArchilError";
+		this.status = status;
+		this.code = code;
+	}
+};
+/** Error from the control-plane REST API. */
+var ArchilApiError = class extends ArchilError {
+	constructor(message, status, code) {
+		super(message, status, code);
+		this.name = "ArchilApiError";
+	}
+};
+/**
+* Error from the S3-compatible object API (getObject/putObject/deleteObject/
+* headObject/listObjects). The gateway returns an S3-style XML `<Error>` body;
+* this surfaces its parts as structured fields (`status`, `code`, `requestId`)
+* rather than a raw blob, while keeping the full body on `raw` for debugging.
+*/
+var ArchilS3Error = class extends ArchilError {
+	/** S3 request id, if the gateway returned one. */
+	requestId;
+	/** Raw response body (the XML document), for debugging. */
+	raw;
+	constructor(opts) {
+		const detail = opts.message ?? opts.statusText ?? "";
+		const codePart = opts.code ? ` ${opts.code}` : "";
+		super(`S3 ${opts.operation} failed: ${opts.statusCode}${codePart}${detail ? ` — ${detail}` : ""}`, opts.statusCode, opts.code);
+		this.name = "ArchilS3Error";
+		this.requestId = opts.requestId;
+		this.raw = opts.raw;
+	}
+};
+function tagString(obj, tag) {
+	const value = obj[tag];
+	return value === void 0 || value === null ? void 0 : String(value);
+}
+/** Build an ArchilS3Error from a failed S3 response, parsing the XML body. */
+function parseS3Error(operation, statusCode, statusText, body) {
+	let err = {};
+	try {
+		err = parseXml(body).Error ?? {};
+	} catch {
+		err = {};
+	}
+	return new ArchilS3Error({
+		operation,
+		statusCode,
+		statusText,
+		code: tagString(err, "Code"),
+		message: tagString(err, "Message"),
+		requestId: tagString(err, "RequestId"),
+		raw: body
+	});
+}
+//#endregion
+//#region src/regions.ts
+const REGION_URLS = {
+	"aws-us-east-1": "https://control.green.us-east-1.aws.prod.archil.com",
+	"aws-us-west-2": "https://control.green.us-west-2.aws.prod.archil.com",
+	"aws-eu-west-1": "https://control.green.eu-west-1.aws.prod.archil.com",
+	"gcp-us-central1": "https://control.blue.us-central1.gcp.prod.archil.com"
+};
+function resolveBaseUrl(region) {
+	const url = REGION_URLS[region];
+	if (!url) throw new Error(`Unknown region "${region}". Valid regions: ${Object.keys(REGION_URLS).join(", ")}`);
+	return url;
+}
+/**
+* Derive the S3-compatible endpoint from a control-plane base URL by swapping a
+* leading `control.` hostname segment for `s3.` (e.g.
+* `control.green.us-east-1.…` → `s3.green.us-east-1.…`). Returns undefined if the
+* URL can't be parsed. A host without a `control.` prefix is returned unchanged.
+*/
+function deriveS3BaseUrl(controlBaseUrl) {
+	try {
+		const u = new URL(controlBaseUrl);
+		u.hostname = u.hostname.replace(/^control\./, "s3.");
+		return u.toString().replace(/\/$/, "");
+	} catch {
+		return;
+	}
+}
+//#endregion
+//#region src/version.ts
+const VERSION = "0.8.19";
+const USER_AGENT = `archil-js/${VERSION}`;
+//#endregion
+//#region src/client.ts
+const createClient = typeof createClientDefault === "function" ? createClientDefault : createClientDefault.default;
+function createApiClient(opts) {
+	const baseUrl = opts.baseUrl ?? resolveBaseUrl(opts.region);
+	return createClient({
+		baseUrl,
+		headers: {
+			Authorization: `key-${opts.apiKey.replace(/^key-/, "")}`,
+			"User-Agent": USER_AGENT
+		}
+	});
+}
+/**
+* Unwrap the API envelope: return data on success, throw ArchilApiError on failure.
+*/
+async function unwrap(promise) {
+	const { data: body, error, response } = await promise;
+	if (error || !body) throw new ArchilApiError(error?.error ?? `API request failed with status ${response.status}`, response.status);
+	if (!body.success) throw new ArchilApiError(body.error ?? "Unknown API error", response.status);
+	return body.data;
+}
+/**
+* Unwrap an API response that has no data payload (e.g., delete operations).
+*/
+async function unwrapEmpty(promise) {
+	const { data: body, error, response } = await promise;
+	if (error || !body) throw new ArchilApiError(error?.error ?? `API request failed with status ${response.status}`, response.status);
+	if (!body.success) throw new ArchilApiError(body.error ?? "Unknown API error", response.status);
+}
+//#endregion
+//#region src/disk.ts
+var Disk = class {
+	id;
+	name;
+	organization;
+	status;
+	provider;
+	region;
+	createdAt;
+	fsHandlerStatus;
+	lastAccessed;
+	dataSize;
+	monthlyUsage;
+	mounts;
+	metrics;
+	connectedClients;
+	authorizedUsers;
+	allowedIps;
+	/** @internal */
+	_client;
+	/** @internal */
+	_archilRegion;
+	/** Base URL for the S3-compatible API (port 9000 ingress). Empty if unset. */
+	_s3BaseUrl;
+	/** Lazily-constructed multipart namespace (see {@link multipart}). @internal */
+	_multipart;
+	/** @internal */
+	constructor(data, client, archilRegion, s3BaseUrl) {
+		this.id = data.id;
+		this.name = data.name;
+		this.organization = data.organization;
+		this.status = data.status;
+		this.provider = data.provider;
+		this.region = data.region;
+		this.createdAt = data.createdAt;
+		this.fsHandlerStatus = data.fsHandlerStatus;
+		this.lastAccessed = data.lastAccessed;
+		this.dataSize = data.dataSize;
+		this.monthlyUsage = data.monthlyUsage;
+		this.mounts = data.mounts;
+		this.metrics = data.metrics;
+		this.connectedClients = data.connectedClients;
+		this.authorizedUsers = data.authorizedUsers;
+		this.allowedIps = data.allowedIps;
+		this._client = client;
+		this._archilRegion = archilRegion;
+		this._s3BaseUrl = s3BaseUrl ?? "";
+	}
+	toJSON() {
+		return {
+			id: this.id,
+			name: this.name,
+			organization: this.organization,
+			status: this.status,
+			provider: this.provider,
+			region: this.region,
+			createdAt: this.createdAt,
+			fsHandlerStatus: this.fsHandlerStatus,
+			lastAccessed: this.lastAccessed,
+			dataSize: this.dataSize,
+			monthlyUsage: this.monthlyUsage,
+			mounts: this.mounts,
+			metrics: this.metrics,
+			connectedClients: this.connectedClients,
+			authorizedUsers: this.authorizedUsers,
+			allowedIps: this.allowedIps
+		};
+	}
+	async addUser(user) {
+		return unwrap(this._client.POST("/api/disks/{id}/users", {
+			params: { path: { id: this.id } },
+			body: user
+		}));
+	}
+	async removeUser(userType, identifier) {
+		await unwrapEmpty(this._client.DELETE("/api/disks/{id}/users/{userType}", { params: {
+			path: {
+				id: this.id,
+				userType
+			},
+			query: { identifier }
+		} }));
+	}
+	async createToken(nickname) {
+		const user = await unwrap(this._client.POST("/api/disks/{id}/users", {
+			params: { path: { id: this.id } },
+			body: {
+				type: "token",
+				nickname
+			}
+		}));
+		if (!user.token || !user.identifier) throw new Error("Server did not return a generated token");
+		return user;
+	}
+	async removeTokenUser(identifier) {
+		await this.removeUser("token", identifier);
+	}
+	async getAllowedIPs() {
+		return (await unwrap(this._client.GET("/api/disks/{id}/allowed-ips", { params: { path: { id: this.id } } }))).allowedIps;
+	}
+	async setAllowedIPs(allowedIps) {
+		return (await unwrap(this._client.PUT("/api/disks/{id}/allowed-ips", {
+			params: { path: { id: this.id } },
+			body: { allowedIps }
+		}))).allowedIps;
+	}
+	async addAllowedIP(ip) {
+		const current = await this.getAllowedIPs();
+		if (current.includes(ip)) return current;
+		return this.setAllowedIPs([...current, ip]);
+	}
+	async removeAllowedIP(ip) {
+		const current = await this.getAllowedIPs();
+		return this.setAllowedIPs(current.filter((i) => i !== ip));
+	}
+	async delete() {
+		await unwrapEmpty(this._client.DELETE("/api/disks/{id}", { params: { path: { id: this.id } } }));
+	}
+	/**
+	* Execute a command in a container with this disk mounted.
+	* Blocks until the command completes and returns stdout, stderr, and exit code.
+	*/
+	async exec(command) {
+		return unwrap(this._client.POST("/api/disks/{id}/exec", {
+			params: { path: { id: this.id } },
+			body: { command }
+		}));
+	}
+	/**
+	* Constant-time parallel grep across files on this disk. Listing and
+	* matching are fanned out across ephemeral exec containers; the request
+	* finishes within the supplied time budget regardless of dataset size.
+	*
+	* The returned `stoppedReason` says whether the search ran to completion
+	* or short-circuited on `maxResults` / `maxDurationSeconds`. When
+	* stopping early, the matches returned are a sample (whichever workers
+	* reported first), not the lexicographically first N.
+	*/
+	async grep(opts) {
+		return unwrap(this._client.POST("/api/disks/{id}/grep", {
+			params: { path: { id: this.id } },
+			body: {
+				directory: opts.directory,
+				pattern: opts.pattern,
+				recursive: opts.recursive ?? false,
+				maxDurationSeconds: opts.maxDurationSeconds ?? 30,
+				concurrency: opts.concurrency ?? 50,
+				maxResults: opts.maxResults ?? 1e3
+			}
+		}));
+	}
+	/**
+	* Create a signed, time-limited URL that lets anyone download a single file
+	* from this disk without authentication. The returned URL embeds a
+	* cryptographically signed token carrying the disk, the file's key, and an
+	* expiry — share it directly; no API key is needed to redeem it.
+	*
+	* @param key   Path to the file on the disk (e.g. "reports/2026-01/data.pdf").
+	* @param opts  `expiresIn` sets the URL lifetime in seconds (any positive
+	*              integer, max 604800 = 7 days). Defaults to 24h.
+	*/
+	async share(key, opts = {}) {
+		const body = { key };
+		if (opts.expiresIn !== void 0) body.expiresIn = opts.expiresIn;
+		const call = this._client.POST;
+		return unwrap(call(`/api/disks/${this.id}/share`, { body }));
+	}
+	/**
+	* Read an object from the disk via the S3-compatible GetObject API and return
+	* its full contents as bytes. Throws `ArchilS3Error` if the object does not
+	* exist (status 404, code "NoSuchKey") or the request is rejected; use
+	* `headObject`/`objectExists` to check existence without throwing.
+	*
+	* @param key  Path on the disk (e.g. "reports/2026-01/data.json")
+	*/
+	async getObject(key) {
+		const resp = await this._s3Request("GET", key);
+		if (!resp.ok) throw parseS3Error("GetObject", resp.status, resp.statusText, decodeText(resp.body));
+		return resp.body;
+	}
+	/**
+	* Fetch an object's metadata (size, etag, content type, last-modified) without
+	* downloading its contents, via the S3-compatible HeadObject API. Returns
+	* `null` if the object does not exist.
+	*
+	* @param key  Path on the disk (e.g. "reports/2026-01/data.json")
+	*/
+	async headObject(key) {
+		const resp = await this._s3Request("HEAD", key);
+		if (resp.status === 404) return null;
+		if (!resp.ok) throw parseS3Error("HeadObject", resp.status, resp.statusText, decodeText(resp.body));
+		const lastModified = resp.headers.get("last-modified");
+		return {
+			size: Number(resp.headers.get("content-length") ?? 0),
+			etag: resp.headers.get("etag") ?? void 0,
+			contentType: resp.headers.get("content-type") ?? void 0,
+			lastModified: lastModified ? new Date(lastModified) : void 0
+		};
+	}
+	/** Whether an object exists on the disk (a HeadObject that maps 404 → false). */
+	async objectExists(key) {
+		return await this.headObject(key) !== null;
+	}
+	/**
+	* Write an object to the disk via the S3-compatible API. Handles any size:
+	* bodies at or below `multipartThreshold` (defaults to `partSize`, i.e.
+	* 16 MiB) go through a single PutObject request; larger bodies are uploaded as
+	* a multipart upload — split into `partSize` parts, uploaded with bounded
+	* `concurrency` (default 4), and assembled. A failed part aborts the upload so
+	* nothing is left half-staged. For manual control over the multipart
+	* lifecycle, use the {@link multipart} namespace.
+	*
+	* Faster than exec for large files — no container overhead, no command-length
+	* limits. Returns the entity tag the server assigned (a multipart upload's tag
+	* is S3's `md5(concat(partMd5s))-N` form rather than a plain MD5).
+	*
+	* @param key      Path on the disk (e.g. "reports/2026-01/data.json")
+	* @param body     Contents as a string, Uint8Array/Buffer, or ArrayBuffer
+	* @param options  Either a content-type string, or {@link PutObjectOptions}
+	*                 (`contentType`, `multipartThreshold`, `partSize`,
+	*                 `concurrency`). Content type defaults to
+	*                 "application/octet-stream".
+	*/
+	async putObject(key, body, options) {
+		const opts = typeof options === "string" ? { contentType: options } : options ?? {};
+		const contentType = opts.contentType ?? "application/octet-stream";
+		const partSize = Math.max(opts.partSize ?? DEFAULT_PART_SIZE, MIN_PART_SIZE);
+		const threshold = opts.multipartThreshold ?? partSize;
+		const bytes = toBytes(body);
+		if (bytes.length <= threshold) {
+			const resp = await this._s3Request("PUT", key, {
+				body,
+				contentType
+			});
+			if (!resp.ok) throw parseS3Error("PutObject", resp.status, resp.statusText, decodeText(resp.body));
+			return { etag: resp.headers.get("etag") ?? void 0 };
+		}
+		return this._putMultipart(key, bytes, contentType, partSize, Math.max(1, opts.concurrency ?? DEFAULT_UPLOAD_CONCURRENCY));
+	}
+	/**
+	* Upload a large body through the multipart lifecycle: split into `partSize`
+	* parts, upload them with bounded concurrency, then complete — aborting the
+	* upload if any part fails so nothing is left half-staged. @internal
+	*/
+	async _putMultipart(key, bytes, contentType, partSize, concurrency) {
+		const effectivePartSize = effectiveUploadPartSize(bytes.length, partSize);
+		const mp = this.multipart;
+		const upload = await mp.create(key, contentType);
+		try {
+			const partCount = Math.ceil(bytes.length / effectivePartSize);
+			const parts = new Array(partCount);
+			let next = 0;
+			const worker = async () => {
+				for (;;) {
+					const index = next++;
+					if (index >= partCount) return;
+					const start = index * effectivePartSize;
+					const slice = bytes.subarray(start, Math.min(start + effectivePartSize, bytes.length));
+					parts[index] = await mp.uploadPart(key, upload.uploadId, index + 1, slice);
+				}
+			};
+			await Promise.all(Array.from({ length: Math.min(concurrency, partCount) }, worker));
+			return { etag: (await mp.complete(key, upload.uploadId, parts)).etag };
+		} catch (err) {
+			await mp.abort(key, upload.uploadId).catch(() => {});
+			throw err;
+		}
+	}
+	/**
+	* Append bytes to an object via the S3-compatible PutObject append extension
+	* (`?append=true`). If the object already exists the bytes are appended to it;
+	* if it doesn't, it is created. Returns the entity tag of the full object
+	* after the append.
+	*
+	* Each call may append at most 1 MiB — the server rejects a larger body with
+	* `EntityTooLarge`. To grow an object past that, append in chunks (or use
+	* {@link putObject} for a one-shot large write).
+	*
+	* Unlike most operations this is NOT auto-retried on a transient error:
+	* append isn't idempotent, so retrying a succeeded-but-unacknowledged append
+	* would duplicate the bytes. On a transient failure, re-append yourself only
+	* after confirming the object's size.
+	*
+	* @param key          Path on the disk (e.g. "logs/app.log")
+	* @param body         Bytes to append (string, Uint8Array/Buffer, or ArrayBuffer)
+	* @param contentType  MIME type, applied only when the object is newly created.
+	*/
+	async appendObject(key, body, contentType = "application/octet-stream") {
+		const resp = await this._s3Request("PUT", key, {
+			body,
+			contentType,
+			query: { append: "true" },
+			retry: false
+		});
+		if (!resp.ok) throw parseS3Error("AppendObject", resp.status, resp.statusText, decodeText(resp.body));
+		return { etag: resp.headers.get("etag") ?? void 0 };
+	}
+	/**
+	* Delete an object from the disk via the S3-compatible DeleteObject API.
+	* Idempotent: deleting a key that doesn't exist resolves successfully, per
+	* S3 semantics.
+	*
+	* @param key  Path on the disk (e.g. "project/dist/server.cjs")
+	*/
+	async deleteObject(key) {
+		const resp = await this._s3Request("DELETE", key);
+		if (!resp.ok && resp.status !== 404) throw parseS3Error("DeleteObject", resp.status, resp.statusText, decodeText(resp.body));
+	}
+	/**
+	* List objects on the disk via the S3-compatible ListObjectsV2 API. By
+	* default this follows continuation tokens until the listing is exhausted and
+	* returns every matching key. Use `limit` to cap the total, `singlePage` for a
+	* single request, or {@link listObjectsPages} to stream pages without loading
+	* everything into memory.
+	*
+	* @param prefix  Only return keys beginning with this prefix (omit for all).
+	* @param opts    Listing and pagination options.
+	*/
+	async listObjects(prefix, opts = {}) {
+		if (opts.singlePage) return this._listObjectsPage(prefix, opts);
+		const objects = [];
+		const commonPrefixes = [];
+		const seenPrefixes = /* @__PURE__ */ new Set();
+		let echoedPrefix;
+		let truncated = false;
+		outer: for await (const page of this.listObjectsPages(prefix, opts)) {
+			echoedPrefix = page.prefix;
+			for (const cp of page.commonPrefixes) if (!seenPrefixes.has(cp)) {
+				seenPrefixes.add(cp);
+				commonPrefixes.push(cp);
+			}
+			for (const obj of page.objects) {
+				if (opts.limit !== void 0 && objects.length >= opts.limit) {
+					truncated = true;
+					break outer;
+				}
+				objects.push(obj);
+			}
+		}
+		return {
+			objects,
+			commonPrefixes,
+			isTruncated: truncated,
+			keyCount: objects.length,
+			prefix: echoedPrefix
+		};
+	}
+	/**
+	* Yield ListObjectsV2 pages lazily, following continuation tokens. A
+	* memory-friendly way to process a large listing without materializing it:
+	*
+	* ```ts
+	* for await (const page of disk.listObjectsPages("logs/")) {
+	*   for (const obj of page.objects) process(obj);
+	* }
+	* ```
+	*
+	* @param prefix  Only return keys beginning with this prefix (omit for all).
+	* @param opts    Listing options (`limit` / `singlePage` are ignored here —
+	*                control your own loop).
+	*/
+	async *listObjectsPages(prefix, opts = {}) {
+		const seenTokens = /* @__PURE__ */ new Set();
+		let continuationToken = opts.continuationToken;
+		for (;;) {
+			const page = await this._listObjectsPage(prefix, {
+				...opts,
+				continuationToken
+			});
+			yield page;
+			const next = page.isTruncated ? page.nextContinuationToken : void 0;
+			if (!next || seenTokens.has(next)) break;
+			seenTokens.add(next);
+			continuationToken = next;
+		}
+	}
+	/** Fetch a single ListObjectsV2 page. @internal */
+	async _listObjectsPage(prefix, opts) {
+		const query = { "list-type": 2 };
+		if (prefix !== void 0) query.prefix = prefix;
+		if (!opts.recursive) query.delimiter = "/";
+		if (opts.continuationToken !== void 0) query["continuation-token"] = opts.continuationToken;
+		if (opts.startAfter !== void 0) query["start-after"] = opts.startAfter;
+		const resp = await this._s3Request("GET", "", { query });
+		if (!resp.ok) throw parseS3Error("ListObjectsV2", resp.status, resp.statusText, decodeText(resp.body));
+		return parseListObjectsResult(decodeText(resp.body));
+	}
+	/**
+	* Delete up to many objects in a single S3-compatible DeleteObjects request.
+	* Unlike {@link deleteObject}, failures are reported per key rather than
+	* thrown: the result's `deleted` lists the keys that were removed and
+	* `errors` lists the ones that weren't (with the server's code/message). A
+	* key that didn't exist still counts as deleted, per S3 semantics.
+	*
+	* The server caps a single request at 1000 keys; this method transparently
+	* splits larger inputs into 1000-key batches and merges the results.
+	*
+	* @param keys  Object keys to delete.
+	* @param opts  `quiet` suppresses the per-key success list server-side.
+	*/
+	async deleteObjects(keys, opts = {}) {
+		const deleted = [];
+		const errors = [];
+		for (let i = 0; i < keys.length; i += MAX_DELETE_OBJECTS_PER_REQUEST) {
+			const xml = buildDeleteObjectsXml(keys.slice(i, i + MAX_DELETE_OBJECTS_PER_REQUEST), opts.quiet ?? false);
+			const resp = await this._s3Request("POST", "", {
+				query: { delete: "" },
+				body: xml,
+				contentType: "application/xml"
+			});
+			if (!resp.ok) throw parseS3Error("DeleteObjects", resp.status, resp.statusText, decodeText(resp.body));
+			const parsed = parseDeleteObjectsResult(decodeText(resp.body));
+			deleted.push(...parsed.deleted);
+			errors.push(...parsed.errors);
+		}
+		return {
+			deleted,
+			errors
+		};
+	}
+	/**
+	* The advanced, opt-in multipart-upload API. Drive the raw lifecycle
+	* yourself — `create` → `uploadPart` → `complete` (or `abort`), plus
+	* `listParts` / `listUploads`. Most callers don't need this: {@link putObject}
+	* runs the whole lifecycle automatically for large bodies. Reach for it only
+	* when you need manual control (e.g. uploading parts from separate processes),
+	* and note you then own part-size, memory, and concurrency management.
+	*/
+	get multipart() {
+		return this._multipart ??= new DiskMultipart(this.id, this._s3Request.bind(this));
+	}
+	/**
+	* Send a single request to the disk's S3-compatible endpoint. This reuses the
+	* control-plane client purely for its credential and transport — the same
+	* `Authorization` header is sent and verified by the same code server-side —
+	* pointed at the S3 host. Returns the response status and fully-buffered body
+	* so callers can inspect both regardless of the verb used.
+	*
+	* The S3 routes (`/{diskId}/{key}` for objects, `/{diskId}` for the bucket)
+	* are not part of the typed control-plane API, so the path and per-request
+	* options are passed untyped. An empty `key` targets the bucket itself (used
+	* by listObjects).
+	*
+	* @internal
+	*/
+	async _s3Request(method, key, opts = {}) {
+		if (!this._s3BaseUrl) throw new Error("S3 base URL not configured. Pass s3BaseUrl to new Archil({...}) or set ARCHIL_S3_BASE_URL.");
+		const call = this._client[method];
+		const encodedKey = key.replace(/^\//, "").split("/").map(encodeURIComponent).join("/");
+		const path = encodedKey ? `/${this.id}/${encodedKey}` : `/${this.id}`;
+		const init = {
+			baseUrl: this._s3BaseUrl,
+			parseAs: "stream",
+			...opts.query ? { params: { query: opts.query } } : {},
+			...opts.body !== void 0 ? {
+				body: opts.body,
+				bodySerializer: (b) => b
+			} : {},
+			...opts.contentType ? { headers: { "Content-Type": opts.contentType } } : {}
+		};
+		const hasBody = method === "GET" || method === "POST";
+		const maxRetries = opts.retry === false ? 0 : MAX_S3_RETRIES;
+		for (let attempt = 0;; attempt++) {
+			let error;
+			let response;
+			try {
+				({error, response} = await call(path, init));
+			} catch (transportError) {
+				if (attempt < maxRetries) {
+					await sleep(s3RetryDelayMs(attempt));
+					continue;
+				}
+				throw transportError;
+			}
+			if (!response.ok) {
+				if (isTransientS3Status(response.status) && attempt < maxRetries) {
+					await response.body?.cancel().catch(() => {});
+					await sleep(s3RetryDelayMs(attempt));
+					continue;
+				}
+				const message = typeof error === "string" ? error : error ? JSON.stringify(error) : "";
+				return {
+					ok: false,
+					status: response.status,
+					statusText: response.statusText,
+					headers: response.headers,
+					body: new TextEncoder().encode(message)
+				};
+			}
+			const bytes = hasBody ? new Uint8Array(await response.arrayBuffer()) : /* @__PURE__ */ new Uint8Array(0);
+			return {
+				ok: true,
+				status: response.status,
+				statusText: response.statusText,
+				headers: response.headers,
+				body: bytes
+			};
+		}
+	}
+	/**
+	* Connect to this disk's data plane via the native ArchilClient.
+	*
+	* Requires the native module to be available (platform-specific .node binary).
+	*/
+	async mount(opts) {
+		let ArchilClient;
+		try {
+			const native = await import("@archildata/native");
+			ArchilClient = native.ArchilClient ?? native.default?.ArchilClient;
+			if (!ArchilClient) throw new Error("@archildata/native did not export ArchilClient");
+		} catch {
+			throw new Error("Native client not available. Install @archildata/native (platform-specific binary) or use ArchilClient.connect() directly. mount() is not supported in browsers.");
+		}
+		return ArchilClient.connect({
+			region: this._archilRegion,
+			diskName: `${this.organization}/${this.name}`,
+			authToken: opts?.authToken,
+			logLevel: opts?.logLevel,
+			serverAddress: opts?.serverAddress,
+			insecure: opts?.insecure
+		});
+	}
+};
+/**
+* The advanced, opt-in multipart-upload namespace, reached via {@link Disk.multipart}.
+* Drives the raw S3 multipart lifecycle — `create` → `uploadPart` → `complete`
+* (or `abort`), plus `listParts` / `listUploads`. Prefer {@link Disk.putObject},
+* which runs this lifecycle automatically for large bodies; use this only when
+* you need manual control, in which case you own part-size, memory, and
+* concurrency management.
+*/
+var DiskMultipart = class {
+	diskId;
+	s3Request;
+	/** @internal */
+	constructor(diskId, s3Request) {
+		this.diskId = diskId;
+		this.s3Request = s3Request;
+	}
+	/**
+	* Start a multipart upload (CreateMultipartUpload) and return its `uploadId`.
+	*
+	* @param key          Path on the disk the finished object will live at.
+	* @param contentType  MIME type to store the object with.
+	*/
+	async create(key, contentType) {
+		const resp = await this.s3Request("POST", key, {
+			query: { uploads: "" },
+			contentType
+		});
+		if (!resp.ok) throw parseS3Error("CreateMultipartUpload", resp.status, resp.statusText, decodeText(resp.body));
+		const root = parseXml(decodeText(resp.body)).InitiateMultipartUploadResult ?? {};
+		const uploadId = optionalString(root.UploadId);
+		if (!uploadId) throw new ArchilS3Error({
+			operation: "CreateMultipartUpload",
+			statusCode: resp.status,
+			message: "response did not contain an UploadId",
+			raw: decodeText(resp.body)
+		});
+		return {
+			uploadId,
+			key: optionalString(root.Key) ?? key,
+			bucket: optionalString(root.Bucket) ?? this.diskId
+		};
+	}
+	/**
+	* Upload one part (UploadPart) and return its entity tag, which you must
+	* collect (with its part number) and pass to {@link complete}. Every part
+	* except the last must be at least 5 MiB.
+	*
+	* @param key         The upload's object key.
+	* @param uploadId    The id from {@link create}.
+	* @param partNumber  1-based part number (1..=10000).
+	* @param body        Part contents as a string, Uint8Array/Buffer, or ArrayBuffer.
+	*/
+	async uploadPart(key, uploadId, partNumber, body) {
+		const resp = await this.s3Request("PUT", key, {
+			query: {
+				uploadId,
+				partNumber
+			},
+			body
+		});
+		if (!resp.ok) throw parseS3Error("UploadPart", resp.status, resp.statusText, decodeText(resp.body));
+		return {
+			partNumber,
+			etag: resp.headers.get("etag") ?? ""
+		};
+	}
+	/**
+	* Finish a multipart upload (CompleteMultipartUpload), assembling the listed
+	* parts into one object. Parts are sorted by part number before submission
+	* (the server requires strictly-increasing order).
+	*
+	* Unlike the other operations this is NOT auto-retried on a transient error:
+	* the gateway isn't idempotent for completion, so a retry after a
+	* successful-but-unacknowledged complete would return a spurious NoSuchUpload.
+	* On a transient failure, re-drive completion yourself only after confirming
+	* the object isn't already present.
+	*
+	* @param key       The upload's object key.
+	* @param uploadId  The id from {@link create}.
+	* @param parts     The `{ partNumber, etag }` pairs from {@link uploadPart}.
+	*/
+	async complete(key, uploadId, parts) {
+		const xml = buildCompleteMultipartUploadXml([...parts].sort((a, b) => a.partNumber - b.partNumber));
+		const resp = await this.s3Request("POST", key, {
+			query: { uploadId },
+			body: xml,
+			contentType: "application/xml",
+			retry: false
+		});
+		if (!resp.ok) throw parseS3Error("CompleteMultipartUpload", resp.status, resp.statusText, decodeText(resp.body));
+		const root = parseXml(decodeText(resp.body)).CompleteMultipartUploadResult ?? {};
+		return {
+			etag: optionalString(root.ETag),
+			location: optionalString(root.Location),
+			bucket: optionalString(root.Bucket),
+			key: optionalString(root.Key)
+		};
+	}
+	/**
+	* Abort a multipart upload (AbortMultipartUpload), discarding every staged
+	* part. Idempotent against an upload that's already gone (404 / NoSuchUpload
+	* resolves successfully).
+	*
+	* @param key       The upload's object key.
+	* @param uploadId  The id from {@link create}.
+	*/
+	async abort(key, uploadId) {
+		const resp = await this.s3Request("DELETE", key, { query: { uploadId } });
+		if (!resp.ok && resp.status !== 404) throw parseS3Error("AbortMultipartUpload", resp.status, resp.statusText, decodeText(resp.body));
+	}
+	/**
+	* List the parts already uploaded for an in-progress upload (ListParts).
+	* Returns a single page; follow `nextPartNumberMarker` (when `isTruncated`)
+	* to page through the rest.
+	*
+	* @param key       The upload's object key.
+	* @param uploadId  The id from {@link create}.
+	* @param opts      `maxParts` / `partNumberMarker` pagination controls.
+	*/
+	async listParts(key, uploadId, opts = {}) {
+		const query = { uploadId };
+		if (opts.maxParts !== void 0) query["max-parts"] = opts.maxParts;
+		if (opts.partNumberMarker !== void 0) query["part-number-marker"] = opts.partNumberMarker;
+		const resp = await this.s3Request("GET", key, { query });
+		if (!resp.ok) throw parseS3Error("ListParts", resp.status, resp.statusText, decodeText(resp.body));
+		return parseListPartsResult(decodeText(resp.body));
+	}
+	/**
+	* List in-progress multipart uploads on the disk (ListMultipartUploads).
+	* Returns a single page; follow `nextKeyMarker` / `nextUploadIdMarker` (when
+	* `isTruncated`) for the rest.
+	*
+	* @param opts  Prefix/delimiter filter and pagination markers.
+	*/
+	async listUploads(opts = {}) {
+		const query = { uploads: "" };
+		if (opts.prefix !== void 0) query.prefix = opts.prefix;
+		if (opts.delimiter !== void 0) query.delimiter = opts.delimiter;
+		if (opts.keyMarker !== void 0) query["key-marker"] = opts.keyMarker;
+		if (opts.uploadIdMarker !== void 0) query["upload-id-marker"] = opts.uploadIdMarker;
+		if (opts.maxUploads !== void 0) query["max-uploads"] = opts.maxUploads;
+		const resp = await this.s3Request("GET", "", { query });
+		if (!resp.ok) throw parseS3Error("ListMultipartUploads", resp.status, resp.statusText, decodeText(resp.body));
+		return parseListMultipartUploadsResult(decodeText(resp.body));
+	}
+};
+/** S3's per-request cap on DeleteObjects keys; larger inputs are batched. */
+const MAX_DELETE_OBJECTS_PER_REQUEST = 1e3;
+/** Automatic retries for a transient S3 failure (5xx / 429 / network error). */
+const MAX_S3_RETRIES = 3;
+/** Base backoff for S3 retries (ms); grows exponentially, then full-jittered. */
+const S3_RETRY_BASE_MS = 100;
+/** Ceiling for a single retry backoff (ms). */
+const S3_RETRY_CAP_MS = 2e3;
+/**
+* Statuses worth retrying: throttling (429) and the gateway's transient 5xx
+* (e.g. a journal-commit timeout surfaced as 500). 4xx other than 429 are
+* caller errors and never retried.
+*/
+function isTransientS3Status(status) {
+	return status === 429 || status === 500 || status === 502 || status === 503 || status === 504;
+}
+/** Full-jittered exponential backoff for retry `attempt` (0-based). */
+function s3RetryDelayMs(attempt) {
+	const ceiling = Math.min(S3_RETRY_CAP_MS, S3_RETRY_BASE_MS * 2 ** attempt);
+	return Math.random() * ceiling;
+}
+function sleep(ms) {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/** S3's minimum size for every multipart part but the last (5 MiB). */
+const MIN_PART_SIZE = 5 * 1024 * 1024;
+/** Default part size {@link Disk.putObject} uses on the multipart path (16 MiB). */
+const DEFAULT_PART_SIZE = 16 * 1024 * 1024;
+/** Default number of parts {@link Disk.putObject} uploads in parallel. */
+const DEFAULT_UPLOAD_CONCURRENCY = 4;
+/** The server's cap on parts in a single multipart upload (MAX_PARTS_PER_UPLOAD). */
+const MAX_PARTS_PER_UPLOAD = 1e4;
+/**
+* Choose the part size for a `totalBytes` multipart upload. Returns
+* `requestedPartSize` unless splitting at that size would exceed the server's
+* 10,000-part cap, in which case it grows the part size (rounded up to a whole
+* MiB) so the body fits in ≤ 10,000 parts — mirroring boto3's chunk-size
+* adjustment. Parts only ever get larger, so they stay above the 5 MiB floor.
+*/
+function effectiveUploadPartSize(totalBytes, requestedPartSize) {
+	if (Math.ceil(totalBytes / requestedPartSize) <= MAX_PARTS_PER_UPLOAD) return requestedPartSize;
+	const MiB = 1024 * 1024;
+	const needed = Math.ceil(totalBytes / MAX_PARTS_PER_UPLOAD);
+	return Math.ceil(needed / MiB) * MiB;
+}
+/** Normalize an upload body to bytes so it can be sized and sliced into parts. */
+function toBytes(body) {
+	if (typeof body === "string") return new TextEncoder().encode(body);
+	if (body instanceof Uint8Array) return body;
+	return new Uint8Array(body);
+}
+/** Escape text for safe inclusion in XML element content. */
+function escapeXml(value) {
+	return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+/** Build a `<Delete>` request body for the DeleteObjects API. */
+function buildDeleteObjectsXml(keys, quiet) {
+	return `<?xml version="1.0" encoding="UTF-8"?><Delete>${keys.map((k) => `<Object><Key>${escapeXml(k)}</Key></Object>`).join("")}${quiet ? "<Quiet>true</Quiet>" : ""}</Delete>`;
+}
+/** Build a `<CompleteMultipartUpload>` request body from the uploaded parts. */
+function buildCompleteMultipartUploadXml(parts) {
+	return `<?xml version="1.0" encoding="UTF-8"?><CompleteMultipartUpload>${parts.map((p) => `<Part><PartNumber>${p.partNumber}</PartNumber><ETag>${escapeXml(p.etag)}</ETag></Part>`).join("")}</CompleteMultipartUpload>`;
+}
+/** Coerce a parser value that may be a single object or an array into an array. */
+function asArray(value) {
+	if (value === void 0 || value === null) return [];
+	return Array.isArray(value) ? value : [value];
+}
+function optionalNumber(value) {
+	return value === void 0 || value === null ? void 0 : Number(value);
+}
+function optionalString(value) {
+	return value === void 0 || value === null ? void 0 : String(value);
+}
+function optionalDate(value) {
+	return value === void 0 || value === null ? void 0 : new Date(String(value));
+}
+/** Decode response bytes to a UTF-8 string (used for XML error/result bodies). */
+function decodeText(bytes) {
+	return new TextDecoder().decode(bytes);
+}
+/** Parse an S3 ListObjectsV2 `<ListBucketResult>` XML document. */
+function parseListObjectsResult(xml) {
+	const root = parseXml(xml).ListBucketResult ?? {};
+	const objects = (root.Contents ?? []).map((c) => ({
+		key: String(c.Key ?? ""),
+		size: Number(c.Size ?? 0),
+		etag: optionalString(c.ETag),
+		lastModified: optionalDate(c.LastModified)
+	}));
+	return {
+		objects,
+		commonPrefixes: (root.CommonPrefixes ?? []).map((cp) => optionalString(cp.Prefix)).filter((p) => p !== void 0),
+		isTruncated: root.IsTruncated === "true" || root.IsTruncated === true,
+		nextContinuationToken: optionalString(root.NextContinuationToken),
+		keyCount: root.KeyCount !== void 0 ? Number(root.KeyCount) : objects.length,
+		prefix: optionalString(root.Prefix)
+	};
+}
+function xmlIsTruncated(value) {
+	return value === "true" || value === true;
+}
+/** Parse an S3 DeleteObjects `<DeleteResult>` XML document. */
+function parseDeleteObjectsResult(xml) {
+	const root = parseXml(xml).DeleteResult ?? {};
+	return {
+		deleted: asArray(root.Deleted).map((d) => optionalString(d.Key)).filter((k) => k !== void 0),
+		errors: asArray(root.Error).map((e) => ({
+			key: String(e.Key ?? ""),
+			code: optionalString(e.Code),
+			message: optionalString(e.Message)
+		}))
+	};
+}
+/** Parse an S3 `<ListPartsResult>` XML document. */
+function parseListPartsResult(xml) {
+	const root = parseXml(xml).ListPartsResult ?? {};
+	const parts = asArray(root.Part).map((p) => ({
+		partNumber: Number(p.PartNumber ?? 0),
+		etag: optionalString(p.ETag),
+		size: Number(p.Size ?? 0),
+		lastModified: optionalDate(p.LastModified)
+	}));
+	return {
+		bucket: optionalString(root.Bucket),
+		key: optionalString(root.Key),
+		uploadId: optionalString(root.UploadId),
+		parts,
+		isTruncated: xmlIsTruncated(root.IsTruncated),
+		partNumberMarker: Number(root.PartNumberMarker ?? 0),
+		nextPartNumberMarker: optionalNumber(root.NextPartNumberMarker),
+		maxParts: Number(root.MaxParts ?? parts.length)
+	};
+}
+/** Parse an S3 `<ListMultipartUploadsResult>` XML document. */
+function parseListMultipartUploadsResult(xml) {
+	const root = parseXml(xml).ListMultipartUploadsResult ?? {};
+	const uploads = asArray(root.Upload).map((u) => ({
+		key: String(u.Key ?? ""),
+		uploadId: String(u.UploadId ?? ""),
+		initiated: optionalDate(u.Initiated)
+	}));
+	const commonPrefixes = asArray(root.CommonPrefixes).map((cp) => optionalString(cp.Prefix)).filter((p) => p !== void 0);
+	return {
+		bucket: optionalString(root.Bucket),
+		uploads,
+		commonPrefixes,
+		isTruncated: xmlIsTruncated(root.IsTruncated),
+		keyMarker: optionalString(root.KeyMarker),
+		uploadIdMarker: optionalString(root.UploadIdMarker),
+		nextKeyMarker: optionalString(root.NextKeyMarker),
+		nextUploadIdMarker: optionalString(root.NextUploadIdMarker),
+		prefix: optionalString(root.Prefix),
+		delimiter: optionalString(root.Delimiter),
+		maxUploads: optionalNumber(root.MaxUploads)
+	};
+}
+//#endregion
+//#region src/disks.ts
+var Disks = class {
+	/** @internal */
+	_client;
+	/** @internal */
+	_region;
+	/** @internal */
+	_s3BaseUrl;
+	/** @internal */
+	constructor(client, region, s3BaseUrl) {
+		this._client = client;
+		this._region = region;
+		this._s3BaseUrl = s3BaseUrl;
+	}
+	async list(opts) {
+		return (await unwrap(this._client.GET("/api/disks", { params: { query: {
+			limit: opts?.limit,
+			cursor: opts?.cursor,
+			name: opts?.name
+		} } }))).map((d) => new Disk(d, this._client, this._region, this._s3BaseUrl));
+	}
+	async get(id) {
+		return new Disk(await unwrap(this._client.GET("/api/disks/{id}", { params: { path: { id } } })), this._client, this._region, this._s3BaseUrl);
+	}
+	/**
+	* Create a new disk with an auto-generated mount token.
+	*
+	* Returns the Disk, the one-time token (save it — it cannot be retrieved
+	* again), and the token identifier for later management.
+	*/
+	async create(req) {
+		const resp = await unwrap(this._client.POST("/api/disks", { body: req }));
+		if (!resp.diskId) throw new Error("API returned success but no diskId");
+		const authorizedUsers = resp.authorizedUsers ?? [];
+		const tokenUser = authorizedUsers.find((u) => u.token);
+		return {
+			disk: await this.get(resp.diskId),
+			token: tokenUser?.token ?? null,
+			tokenIdentifier: tokenUser?.identifier ?? null,
+			authorizedUsers
+		};
+	}
+};
+//#endregion
+//#region src/tokens.ts
+var Tokens = class {
+	/** @internal */
+	_client;
+	/** @internal */
+	constructor(client) {
+		this._client = client;
+	}
+	async list(opts) {
+		return (await unwrap(this._client.GET("/api/tokens", { params: { query: {
+			limit: opts?.limit,
+			cursor: opts?.cursor
+		} } }))).tokens ?? [];
+	}
+	async create(req) {
+		return await unwrap(this._client.POST("/api/tokens", { body: req }));
+	}
+	async delete(id) {
+		await unwrapEmpty(this._client.DELETE("/api/tokens/{id}", { params: { path: { id } } }));
+	}
+};
+//#endregion
+//#region src/workspace.ts
+function isExecMountSpec$1(m) {
+	return typeof m === "object" && m !== null && "disk" in m;
+}
+/**
+* A key-routed filesystem spanning several Archil disks. Each disk is mounted
+* under a name and addressed as the first segment of a key (`<name>/...`);
+* `getObject`, `putObject`, `deleteObject`, `listObjects`, and `grep` route to
+* the right disk by that segment (and `listObjects` / `grep` fan out across all
+* of them when the key/prefix doesn't name one). Implements the same
+* {@link FileSystem} surface as a single {@link Disk}, so it works anywhere a
+* disk does. Mounts can be changed at runtime with {@link addDisk} /
+* {@link removeDisk}.
+*/
+var Workspace = class {
+	client;
+	mounts = /* @__PURE__ */ new Map();
+	/** @internal Use `archil.workspace({ ... })`. */
+	constructor(client, mounts) {
+		this.client = client;
+		for (const [name, value] of Object.entries(mounts)) this.addDisk(name, value);
+		if (this.mounts.size === 0) throw new Error("workspace() needs at least one disk");
+	}
+	/** Mount (or replace) a disk at `name`; its objects are addressed as
+	* `<name>/...`. Accepts a `Disk` or a mount spec (read-only / subdirectory /
+	* conditional / delegation checkouts); a bare disk-id string is rejected —
+	* fetch the disk first. */
+	addDisk(name, disk) {
+		const rel = name.replace(/^\/+|\/+$/g, "");
+		if (!rel) throw new Error("workspace mount name must be non-empty");
+		if (rel.includes("/")) throw new Error(`workspace mount name '${name}' must not contain '/'`);
+		if (rel === "." || rel === "..") throw new Error(`workspace mount name '${name}' is reserved ('.' and '..' are path navigation, not disk names)`);
+		let d;
+		let readOnly = false;
+		let subdirectory;
+		let conditional = false;
+		let queueMs;
+		let checkoutPaths;
+		if (isExecMountSpec$1(disk)) {
+			d = disk.disk;
+			readOnly = disk.readOnly ?? false;
+			subdirectory = disk.subdirectory;
+			conditional = disk.conditional ?? false;
+			queueMs = disk.queueMs;
+			checkoutPaths = disk.checkoutPaths;
+		} else d = disk;
+		if (typeof d === "string") throw new Error("workspace needs Disk objects, not disk-id strings; fetch with archil.getDisk(id) first");
+		this.mounts.set(rel, {
+			disk: d,
+			readOnly,
+			subdirectory,
+			conditional,
+			queueMs,
+			checkoutPaths
+		});
+		return this;
+	}
+	/** Unmount the disk at `name`. Returns whether a disk was removed. Refuses to
+	* remove the last disk — a workspace must always have at least one (the same
+	* invariant the constructor enforces), else fan-out/exec would have nothing to
+	* route to. */
+	removeDisk(name) {
+		const rel = name.replace(/^\/+|\/+$/g, "");
+		if (this.mounts.has(rel) && this.mounts.size === 1) throw new Error("cannot remove the last disk from a workspace; a workspace must keep at least one");
+		return this.mounts.delete(rel);
+	}
+	/** The names of the currently-mounted disks. */
+	diskNames() {
+		return [...this.mounts.keys()];
+	}
+	unknownDisk(name) {
+		return /* @__PURE__ */ new Error(`No disk named '${name}'. Address objects by disk: ${this.diskNames().map((n) => `${n}/…`).join(", ")}`);
+	}
+	/** Resolve a workspace key (`<name>/...`) to the disk and the disk-relative key. */
+	route(key) {
+		const segs = toSegments(key);
+		if (segs.length === 0) throw new Error("that key is the workspace root, not an object; name a disk, e.g. data/file.txt");
+		const entry = this.mounts.get(segs[0]);
+		if (!entry) throw this.unknownDisk(segs[0]);
+		return {
+			entry,
+			diskKey: this.diskKey(entry, segs.slice(1).join("/"))
+		};
+	}
+	/** Mounts touched by a key prefix; an empty prefix fans out to all of them. */
+	covered(prefix) {
+		const segs = toSegments(prefix);
+		if (segs.length === 0) return [...this.mounts.entries()].map(([name, entry]) => ({
+			name,
+			entry,
+			rel: this.diskKey(entry, "")
+		}));
+		const entry = this.mounts.get(segs[0]);
+		if (!entry) throw this.unknownDisk(segs[0]);
+		return [{
+			name: segs[0],
+			entry,
+			rel: this.diskKey(entry, segs.slice(1).join("/"))
+		}];
+	}
+	/** Map a workspace-relative key to the disk's key, applying the mount's subdirectory. */
+	diskKey(entry, rel) {
+		const trimmed = rel.replace(/^\/+/, "");
+		const sub = (entry.subdirectory ?? "").replace(/^\/+|\/+$/g, "");
+		if (!sub) return trimmed;
+		return trimmed ? `${sub}/${trimmed}` : sub;
+	}
+	/** Map a disk key back to its workspace key (`<name>/...`), stripping the mount subdirectory. */
+	abs(name, entry, diskKey) {
+		const sub = (entry.subdirectory ?? "").replace(/^\/+|\/+$/g, "");
+		let rel = diskKey;
+		if (sub && diskKey.startsWith(sub + "/")) rel = diskKey.slice(sub.length + 1);
+		else if (sub && diskKey === sub) rel = "";
+		rel = rel.replace(/^\/+|\/+$/g, "");
+		return rel ? `${name}/${rel}` : name;
+	}
+	async getObject(key) {
+		const { entry, diskKey } = this.route(key);
+		return entry.disk.getObject(diskKey);
+	}
+	async putObject(key, body, contentType) {
+		const { entry, diskKey } = this.route(key);
+		if (entry.readOnly) throw new Error(`${key} is on a read-only disk and cannot be written.`);
+		return entry.disk.putObject(diskKey, body, contentType);
+	}
+	async deleteObject(key) {
+		const { entry, diskKey } = this.route(key);
+		if (entry.readOnly) throw new Error(`${key} is on a read-only disk and cannot be deleted.`);
+		await entry.disk.deleteObject(diskKey);
+	}
+	async listObjects(prefix, opts = {}) {
+		if (toSegments(prefix ?? "").length === 0 && !opts.recursive) return {
+			objects: [],
+			commonPrefixes: this.diskNames().map((n) => `${n}/`).sort(),
+			isTruncated: false,
+			keyCount: 0
+		};
+		const covered = this.covered(prefix ?? "");
+		const listings = await Promise.allSettled(covered.map(({ entry, rel }) => {
+			const p = rel ? rel.endsWith("/") ? rel : `${rel}/` : void 0;
+			return entry.disk.listObjects(p, { recursive: opts.recursive });
+		}));
+		const objects = [];
+		const commonPrefixes = [];
+		let isTruncated = false;
+		let keyCount = 0;
+		covered.forEach(({ name, entry }, i) => {
+			const settled = listings[i];
+			if (settled.status === "rejected") {
+				isTruncated = true;
+				return;
+			}
+			const listing = settled.value;
+			for (const cp of listing.commonPrefixes) commonPrefixes.push(`${this.abs(name, entry, cp.replace(/\/+$/, ""))}/`);
+			for (const obj of listing.objects) objects.push({
+				...obj,
+				key: this.abs(name, entry, obj.key)
+			});
+			isTruncated = isTruncated || listing.isTruncated;
+			keyCount += listing.keyCount;
+		});
+		objects.sort((a, b) => a.key < b.key ? -1 : a.key > b.key ? 1 : 0);
+		commonPrefixes.sort();
+		return {
+			objects,
+			commonPrefixes,
+			isTruncated,
+			keyCount
+		};
+	}
+	async grep(opts) {
+		const covered = this.covered(opts.directory ?? "");
+		const results = await Promise.allSettled(covered.map(({ entry, rel }) => entry.disk.grep({
+			...opts,
+			directory: rel
+		})));
+		const matches = [];
+		let filesScanned = 0;
+		let containersDispatched = 0;
+		let computeSecondsUsed = 0;
+		let durationMs = 0;
+		let listingMs = 0;
+		let grepMs = 0;
+		const reasons = /* @__PURE__ */ new Set();
+		covered.forEach(({ name, entry }, i) => {
+			const settled = results[i];
+			if (settled.status === "rejected") {
+				reasons.add("list_failed");
+				return;
+			}
+			const r = settled.value;
+			filesScanned += r.filesScanned;
+			containersDispatched += r.containersDispatched ?? 0;
+			computeSecondsUsed += r.computeSecondsUsed ?? 0;
+			durationMs = Math.max(durationMs, r.durationMs ?? 0);
+			listingMs = Math.max(listingMs, r.listingMs ?? 0);
+			grepMs = Math.max(grepMs, r.grepMs ?? 0);
+			reasons.add(r.stoppedReason);
+			for (const m of r.matches) matches.push({
+				file: this.abs(name, entry, m.file),
+				line: m.line,
+				text: m.text
+			});
+		});
+		const cap = opts.maxResults ?? 1e3;
+		if (matches.length > cap) reasons.add("max_results");
+		const priority = [
+			"list_failed",
+			"incomplete",
+			"deadline",
+			"max_results"
+		];
+		const stoppedReason = [...reasons].every((x) => x === "completed") ? "completed" : priority.find((x) => reasons.has(x)) ?? "completed";
+		return {
+			matches: matches.slice(0, cap),
+			stoppedReason,
+			filesScanned,
+			containersDispatched,
+			computeSecondsUsed,
+			durationMs,
+			listingMs,
+			grepMs
+		};
+	}
+	exec(command) {
+		const disks = {};
+		for (const [name, entry] of this.mounts) disks[name] = entry.readOnly || entry.subdirectory || entry.conditional || entry.queueMs !== void 0 || entry.checkoutPaths !== void 0 ? {
+			disk: entry.disk,
+			subdirectory: entry.subdirectory,
+			readOnly: entry.readOnly,
+			conditional: entry.conditional,
+			queueMs: entry.queueMs,
+			checkoutPaths: entry.checkoutPaths
+		} : entry.disk;
+		return this.client.exec({
+			disks,
+			command
+		});
+	}
+};
+//#endregion
+//#region src/archil.ts
+/**
+* Read an environment variable in a way that is safe in browsers, where the
+* `process` global does not exist. Returns undefined when there is no process
+* environment, so the SDK can be bundled and run client-side as long as
+* credentials are passed explicitly to `new Archil({ ... })`.
+*/
+function envVar(name) {
+	return typeof process !== "undefined" && process.env ? process.env[name] : void 0;
+}
+function isExecMountSpec(m) {
+	return typeof m === "object" && m !== null && "disk" in m;
+}
+function diskIdFromMount(m) {
+	return typeof m === "string" ? m : m.id;
+}
+var Archil = class {
+	disks;
+	tokens;
+	/** @internal */
+	_client;
+	constructor(opts = {}) {
+		const apiKey = opts.apiKey ?? envVar("ARCHIL_API_KEY");
+		const region = opts.region ?? envVar("ARCHIL_REGION");
+		if (!apiKey) throw new Error("Missing API key: pass apiKey in options or set ARCHIL_API_KEY environment variable");
+		if (!region) throw new Error("Missing region: pass region in options or set ARCHIL_REGION environment variable");
+		const controlBaseUrl = opts.baseUrl ?? resolveBaseUrl(region);
+		const client = createApiClient({
+			apiKey,
+			region,
+			baseUrl: controlBaseUrl
+		});
+		const s3BaseUrl = opts.s3BaseUrl ?? envVar("ARCHIL_S3_BASE_URL") ?? deriveS3BaseUrl(controlBaseUrl);
+		this._client = client;
+		this.disks = new Disks(client, region, s3BaseUrl);
+		this.tokens = new Tokens(client);
+	}
+	/**
+	* Run a command in a container with multiple disks mounted simultaneously,
+	* each at its own relative path under `/mnt/archil`. Blocks until the
+	* command completes and returns its stdout, stderr, exit code, and timing.
+	*/
+	async exec(opts) {
+		const disks = {};
+		for (const [relPath, mount] of Object.entries(opts.disks)) if (isExecMountSpec(mount)) {
+			const entry = {
+				disk: diskIdFromMount(mount.disk),
+				readOnly: mount.readOnly ?? false,
+				conditional: mount.conditional ?? false
+			};
+			if (mount.subdirectory !== void 0) entry.subdirectory = mount.subdirectory;
+			if (mount.queueMs !== void 0) entry.queueMs = mount.queueMs;
+			if (mount.checkoutPaths !== void 0) entry.checkoutPaths = mount.checkoutPaths;
+			disks[relPath] = entry;
+		} else disks[relPath] = diskIdFromMount(mount);
+		return unwrap(this._client.POST("/api/exec", { body: {
+			disks,
+			command: opts.command
+		} }));
+	}
+	/**
+	* Build an agent filesystem toolset spanning several disks at once. `mounts`
+	* maps a relative path to a disk (or `ExecMountSpec`), exactly like
+	* {@link exec}; each disk appears under `/mnt/archil/<path>`. Hand the result
+	* to a framework adapter (`createDiskTools(workspace)`) to get tools that route
+	* file operations by path and fan `grep`/`list_files` out across the disks.
+	*/
+	workspace(mounts) {
+		return new Workspace(this, mounts);
+	}
+};
+//#endregion
+//#region src/index.ts
+let _options;
+let _instance;
+function configure(options) {
+	_options = options;
+	_instance = void 0;
+}
+function archil() {
+	if (!_instance) _instance = new Archil(_options);
+	return _instance;
+}
+function createDisk(req) {
+	return archil().disks.create(req);
+}
+function listDisks(opts) {
+	return archil().disks.list(opts);
+}
+function getDisk(id) {
+	return archil().disks.get(id);
+}
+function listApiKeys(opts) {
+	return archil().tokens.list(opts);
+}
+function createApiKey(req) {
+	return archil().tokens.create(req);
+}
+function deleteApiKey(id) {
+	return archil().tokens.delete(id);
+}
+/**
+* Run a command in a container with multiple disks mounted simultaneously,
+* each at its own relative path under `/mnt/archil`. Blocks until the
+* command completes and returns its stdout, stderr, exit code, and timing.
+*/
+function exec(opts) {
+	return archil().exec(opts);
+}
+/**
+* Build an agent filesystem toolset spanning several disks, using the
+* module-level client. See {@link Archil.workspace}.
+*/
+function workspace(mounts) {
+	return archil().workspace(mounts);
+}
+//#endregion
+export { USER_AGENT as _, exec as a, ArchilError as b, listDisks as c, Workspace as d, Tokens as f, effectiveUploadPartSize as g, DiskMultipart as h, deleteApiKey as i, workspace as l, Disk as m, createApiKey as n, getDisk as o, Disks as p, createDisk as r, listApiKeys as s, configure as t, Archil as u, VERSION as v, ArchilS3Error as x, ArchilApiError as y };