@ornncompute/cli 0.2.24 → 1.0.34

package/src/storage-commands.mjs

@@ -0,0 +1,1164 @@
+import { createHash } from "node:crypto";
+import { createReadStream } from "node:fs";
+import { stat } from "node:fs/promises";
+import { basename } from "node:path";
+import { Readable } from "node:stream";
+
+import {
+  CliApiError,
+  computeEndpoint,
+  loadRequiredSession,
+  raiseForFailedResponse,
+  resolveApiBaseUrl,
+  userCredentialHeaders,
+} from "./api-client.mjs";
+import {
+  assertAtomicOutputAvailable,
+  AtomicOutputExistsError,
+  writeAtomicOutput,
+} from "./atomic-output.mjs";
+
+const DEFAULT_PAGE_LIMIT = 50;
+const MAX_PAGE_LIMIT = 500;
+const STORAGE_PREFIX = "/nodes/storage-drives";
+const UNSAFE_CONTENT_COMMANDS = new Set([
+  "storage.volumes.clear",
+  "storage.volumes.files.delete",
+  "storage.volumes.folders.delete",
+]);
+
+/**
+ * Narrow CLI adapter expected by executeStorageCommand:
+ * - `interaction` is context.cli.interaction from interaction-runtime.mjs;
+ * - `fetch` is the authenticated customer CapabilityTransport;
+ * - `fetchImpl` and `env` are injected runner dependencies used only for the
+ *   allowlisted signed upload and streamed gateway download.
+ *
+ * The shell installs this adapter as context.cli.interaction.storage(command,
+ * input). The capability package stays transport-agnostic and no owner service
+ * is called directly.
+ */
+
+export class StorageCommandError extends Error {
+  constructor(
+    message,
+    { action, code = "usage_error", exitCode = 2, field, outcomeClass, retryable = false } = {}
+  ) {
+    super(message);
+    this.name = "StorageCommandError";
+    this.action = action;
+    this.code = code;
+    this.exitCode = exitCode;
+    this.field = field;
+    this.outcomeClass = outcomeClass;
+    this.retryable = retryable;
+  }
+}
+
+function usage(message, field) {
+  throw new StorageCommandError(message, { field });
+}
+
+function positionals(input, expected, usageText) {
+  const values = input.$positionals ?? [];
+  if (values.length !== expected) usage(usageText);
+  return values;
+}
+
+function requiredText(value, flag) {
+  const normalized = String(value ?? "")
+    .normalize("NFKC")
+    .trim();
+  if (!normalized) usage(`${flag} requires a value.`, flag.replace(/^--/, ""));
+  if (/\p{Cc}/u.test(normalized))
+    usage(`${flag} cannot contain control characters.`, flag.replace(/^--/, ""));
+  return normalized;
+}
+
+export function safeIdentifier(value) {
+  const id = String(value ?? "");
+  if (!/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(id)) {
+    throw new StorageCommandError("Ornn returned an unexpected storage identifier.", {
+      code: "invalid_gateway_response",
+      exitCode: 1,
+    });
+  }
+  return id;
+}
+
+export function safeTimestamp(value) {
+  if (typeof value !== "string") return null;
+  const timestamp = new Date(value);
+  return Number.isNaN(timestamp.getTime()) ? null : timestamp.toISOString();
+}
+
+function safeRemotePath(value) {
+  const path = String(value ?? "");
+  const segments = path.split("/");
+  if (
+    !path ||
+    path.startsWith("/") ||
+    path.endsWith("/") ||
+    segments.some(
+      (segment) => !segment || segment === "." || segment === ".." || /\p{Cc}/u.test(segment)
+    )
+  ) {
+    throw new StorageCommandError("Ornn returned an unexpected volume file path.", {
+      code: "invalid_gateway_response",
+      exitCode: 1,
+    });
+  }
+  return path;
+}
+
+function normalizeVolumeName(value) {
+  const name = requiredText(value, "--name").replace(/\s+/gu, " ");
+  if (name.length > 128) usage("--name must be at most 128 characters.", "name");
+  return name;
+}
+
+export function normalizedNameKey(value) {
+  return String(value ?? "")
+    .normalize("NFKC")
+    .trim()
+    .replace(/\s+/gu, " ")
+    .toLocaleLowerCase("en-US");
+}
+
+function normalizeRemotePath(value, { allowEmpty = false, field = "path" } = {}) {
+  const normalized = String(value ?? "")
+    .normalize("NFKC")
+    .trim()
+    .replaceAll("\\", "/");
+  if (allowEmpty && !normalized) return "";
+  const segments = normalized.split("/");
+  if (
+    !normalized ||
+    normalized.startsWith("/") ||
+    normalized.endsWith("/") ||
+    segments.some(
+      (segment) => !segment || segment === "." || segment === ".." || /\p{Cc}/u.test(segment)
+    )
+  ) {
+    usage(
+      "Remote paths must be relative, non-empty, and cannot contain empty, . or .. segments.",
+      field
+    );
+  }
+  return segments.join("/");
+}
+
+function encodedRemotePath(path) {
+  return path
+    .split("/")
+    .map((segment) => encodeURIComponent(segment))
+    .join("/");
+}
+
+function isManagedVolume(drive) {
+  const provider = String(drive?.provider ?? "").toLocaleLowerCase("en-US");
+  const sourceProvider = String(
+    drive?.source?.provider ?? drive?.source_provider ?? ""
+  ).toLocaleLowerCase("en-US");
+  return provider !== "nfs" && sourceProvider !== "external_gcs" && sourceProvider !== "s3";
+}
+
+export function volumeRows(payload) {
+  return Array.isArray(payload) ? payload : Array.isArray(payload?.drives) ? payload.drives : [];
+}
+
+function stableVolumePhase(status) {
+  const value = String(status ?? "").toLocaleLowerCase("en-US");
+  if (["active", "ready"].includes(value)) return "ready";
+  if (["failed", "error"].includes(value)) return "failed";
+  if (["deleted", "ended"].includes(value)) return "ended";
+  if (["creating", "copying", "importing", "updating"].includes(value)) return "working";
+  return "pending";
+}
+
+export function safeVolume(drive) {
+  const sourceId = drive?.source_drive_id ?? drive?.source?.source_drive_id;
+  const name = String(drive?.name ?? "")
+    .normalize("NFKC")
+    .trim();
+  if (!name || /\p{Cc}/u.test(name)) {
+    throw new StorageCommandError("Ornn returned an unexpected volume name.", {
+      code: "invalid_gateway_response",
+      exitCode: 1,
+    });
+  }
+  return {
+    id: safeIdentifier(drive?.id),
+    name,
+    phase: stableVolumePhase(drive?.status),
+    size_bytes: Number.isFinite(Number(drive?.size_bytes)) ? Number(drive.size_bytes) : 0,
+    source_volume_id: typeof sourceId === "string" ? safeIdentifier(sourceId) : null,
+    created_at: safeTimestamp(drive?.created_at),
+    updated_at: safeTimestamp(drive?.updated_at),
+  };
+}
+
+function safeFile(entry) {
+  return {
+    path: safeRemotePath(entry?.path ?? entry?.name),
+    size_bytes: Number.isFinite(Number(entry?.size_bytes)) ? Number(entry.size_bytes) : 0,
+    updated_at: safeTimestamp(entry?.updated_at),
+  };
+}
+
+function parseLimit(value) {
+  if (value === undefined) return DEFAULT_PAGE_LIMIT;
+  const limit = Number(value);
+  if (!Number.isInteger(limit) || limit < 1 || limit > MAX_PAGE_LIMIT) {
+    usage("--limit must be an integer from 1 through 500.", "limit");
+  }
+  return limit;
+}
+
+function encodeCursor(offset) {
+  return Buffer.from(`storage:${offset}`, "utf8").toString("base64url");
+}
+
+function decodeCursor(value) {
+  if (value === undefined) return 0;
+  try {
+    const decoded = Buffer.from(requiredText(value, "--cursor"), "base64url").toString("utf8");
+    const match = decoded.match(/^storage:(\d+)$/);
+    if (!match) throw new Error("invalid cursor");
+    const offset = Number(match[1]);
+    if (!Number.isSafeInteger(offset)) throw new Error("invalid cursor");
+    return offset;
+  } catch {
+    usage("--cursor is not a valid volume page cursor.", "cursor");
+  }
+}
+
+function boundedPage(rows, input) {
+  const limit = parseLimit(input.limit);
+  const offset = decodeCursor(input.cursor);
+  const items = rows.slice(offset, offset + limit);
+  const nextOffset = offset + items.length;
+  return {
+    items,
+    page: {
+      limit,
+      returned: items.length,
+      next_cursor: nextOffset < rows.length ? encodeCursor(nextOffset) : null,
+    },
+  };
+}
+
+export function detailOf(error) {
+  const value = error?.detail?.detail ?? error?.detail?.error ?? error?.detail;
+  return value && typeof value === "object" && !Array.isArray(value) ? value : null;
+}
+
+export function codeOf(error) {
+  const detail = detailOf(error);
+  if (typeof detail?.code === "string" && /^[a-z][a-z0-9_]*$/.test(detail.code)) return detail.code;
+  const nested = typeof error?.detail === "string" ? error.detail : null;
+  return nested && /^[a-z][a-z0-9_]*$/.test(nested) ? nested : null;
+}
+
+const SAFE_ERROR_MESSAGES = {
+  storage_content_busy: "The volume content is still changing. Inspect the volume and try again.",
+  storage_drive_attached_to_reservation:
+    "This volume still has a reservation relationship. Detach every volume mount before deleting it.",
+  storage_drive_mounted: "This volume is mounted. Detach it before changing its files.",
+  storage_drive_not_found: "The requested volume was not found.",
+  storage_file_not_found: "The requested volume file was not found.",
+  storage_folder_not_found: "The requested volume folder was not found.",
+  storage_object_file_api_unsupported: "This volume does not support nested file operations.",
+  storage_pending_uploads:
+    "This volume has an upload still being finalized. Inspect it and try again.",
+};
+
+function safeStorageError(error, fallback, { action } = {}) {
+  if (error instanceof StorageCommandError) return error;
+  if (error instanceof AtomicOutputExistsError) {
+    return new StorageCommandError(
+      "The output path already exists. Choose another path or pass --overwrite.",
+      { code: "destination_exists", field: "output" }
+    );
+  }
+  if (error instanceof CliApiError && [401, 403, 426].includes(error.status)) return error;
+  const code =
+    codeOf(error) ??
+    (error?.status >= 500 || error?.status === undefined
+      ? "service_unavailable"
+      : "storage_operation_failed");
+  const unavailable = code === "service_unavailable";
+  const ownerMessage = detailOf(error)?.message;
+  return new StorageCommandError(
+    SAFE_ERROR_MESSAGES[code] ??
+      (typeof ownerMessage === "string" && ownerMessage.trim() ? ownerMessage : fallback),
+    {
+      action,
+      code,
+      exitCode: unavailable ? 6 : 1,
+      retryable: unavailable,
+    }
+  );
+}
+
+export function idempotencyHeaders(input) {
+  const key = String(input.idempotencyKey ?? "").trim();
+  return key ? { "Idempotency-Key": key } : undefined;
+}
+
+function requireMachineMutationKey(input, runtime) {
+  if (!runtime.interaction.machine) return;
+  const key = String(input.idempotencyKey ?? "").trim();
+  if (!key) {
+    usage("Machine mutations require --idempotency-key <caller-stable-key>.", "idempotency-key");
+  }
+}
+
+export async function fetchDrivePage(runtime, { limit = 25, cursor, scope = "all" } = {}) {
+  if (!Number.isInteger(Number(limit)) || Number(limit) < 1 || Number(limit) > 100) {
+    usage("--limit must be an integer from 1 through 100.", "limit");
+  }
+  const params = new URLSearchParams({ limit: String(limit), scope });
+  if (cursor) params.set("cursor", cursor);
+  try {
+    const payload = await runtime.fetch(computeEndpoint(`${STORAGE_PREFIX}?${params}`), {
+      method: "GET",
+    });
+    return { drives: volumeRows(payload), next_cursor: payload?.next_cursor ?? null };
+  } catch (error) {
+    throw safeStorageError(error, "Volumes could not be loaded safely.");
+  }
+}
+
+// Exact-name resolution and write reconciliation need the complete catalog.
+// Listing commands use fetchDrivePage directly and never take this path.
+export async function fetchDrives(runtime) {
+  const drives = [];
+  const seen = new Set();
+  let cursor;
+  do {
+    const page = await fetchDrivePage(runtime, { limit: 100, cursor });
+    drives.push(...page.drives);
+    cursor = page.next_cursor;
+    if (cursor && (typeof cursor !== "string" || seen.has(cursor))) {
+      throw new StorageCommandError("Storage pagination did not advance. Try again.", {
+        code: "invalid_gateway_response",
+      });
+    }
+    seen.add(cursor);
+  } while (cursor);
+  return drives;
+}
+
+function resolveFromRows(rows, reference, { source = false } = {}) {
+  const ref = requiredText(reference, source ? "--source" : "volume");
+  const managed = rows.filter(isManagedVolume);
+  const idMatches = managed.filter((drive) => String(drive?.id) === ref);
+  if (idMatches.length === 1) return idMatches[0];
+  const key = normalizedNameKey(ref);
+  const nameMatches = managed.filter((drive) => normalizedNameKey(drive?.name) === key);
+  if (nameMatches.length === 1) return nameMatches[0];
+  if (nameMatches.length > 1) {
+    throw new StorageCommandError(
+      `More than one volume has the exact name “${ref}”. Use a canonical volume ID.`,
+      { code: "ambiguous_volume", field: source ? "source" : "volume" }
+    );
+  }
+  throw new StorageCommandError(`Volume not found: ${ref}`, {
+    code: source ? "source_volume_not_found" : "volume_not_found",
+    field: source ? "source" : "volume",
+  });
+}
+
+export async function resolveVolume(runtime, reference) {
+  if (/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(reference)) {
+    const drive = await runtime.fetch(
+      computeEndpoint(`${STORAGE_PREFIX}/${encodeURIComponent(reference)}`),
+      { method: "GET" }
+    );
+    return resolveFromRows([drive], reference);
+  }
+  return resolveFromRows(await fetchDrives(runtime), reference);
+}
+
+async function review(runtime, options) {
+  const accepted = await runtime.interaction.review(options);
+  if (accepted !== false) return null;
+  return runtime.interaction.result({
+    data: null,
+    exitCode: 1,
+    outcome: { class: "ended", phase: "declined" },
+  });
+}
+
+async function unsafeReview(command, input, runtime, reference, remotePath) {
+  if (!UNSAFE_CONTENT_COMMANDS.has(command)) return null;
+  const title =
+    command === "storage.volumes.clear"
+      ? "Clear volume contents"
+      : command === "storage.volumes.files.delete"
+        ? "Delete volume file"
+        : "Delete volume folder";
+  const terms = [
+    { label: "Volume", value: reference },
+    ...(remotePath ? [{ label: "Remote path", value: remotePath }] : []),
+    {
+      label: "Consequence",
+      value:
+        command === "storage.volumes.clear"
+          ? "Every file and folder will be permanently deleted"
+          : "The selected content will be permanently deleted",
+    },
+  ];
+  return review(runtime, {
+    prompt: "Continue?",
+    requireLive: true,
+    terms,
+    title,
+  });
+}
+
+async function createVolume(input, runtime) {
+  positionals(
+    input,
+    0,
+    "Usage: ornn volumes create --name <name> [--source <volume>] [--yes] [--idempotency-key <key>]"
+  );
+  requireMachineMutationKey(input, runtime);
+  const name = normalizeVolumeName(input.name);
+  const rows = await fetchDrives(runtime);
+  const source =
+    input.source === undefined ? null : resolveFromRows(rows, input.source, { source: true });
+  const effective = { name, source_volume_id: source ? String(source.id) : null };
+  const matches = rows.filter(
+    (drive) => normalizedNameKey(drive?.name) === normalizedNameKey(name)
+  );
+  if (matches.length > 1) {
+    throw new StorageCommandError(
+      "Volume creation cannot be replayed because the normalized name is not unique.",
+      { code: "volume_name_ambiguous", field: "name" }
+    );
+  }
+  const declined = await review(runtime, {
+    prompt: "Create this volume?",
+    terms: [
+      { label: "Volume name", value: name },
+      { label: "Source", value: source ? String(source.id) : "empty volume" },
+      {
+        label: "Consequence",
+        value: source
+          ? "Create a durable managed volume copied from the selected source"
+          : "Create an empty durable managed volume",
+      },
+    ],
+    title: "Create volume",
+  });
+  if (declined) return declined;
+  if (matches.length === 1) {
+    const existing = matches[0];
+    const existingSource = existing?.source_drive_id ?? existing?.source?.source_drive_id ?? null;
+    if (
+      !isManagedVolume(existing) ||
+      String(existingSource ?? "") !== String(effective.source_volume_id ?? "")
+    ) {
+      throw new StorageCommandError(
+        "A volume with this normalized name already exists with different creation input.",
+        { code: "volume_creation_conflict", exitCode: 1, field: "name" }
+      );
+    }
+    return runtime.interaction.result({
+      data: { effective_input: effective, replayed: true, volume: safeVolume(existing) },
+      outcome: { class: "ready", phase: "replayed" },
+      resume: { kind: "volume", ref: String(existing.id) },
+    });
+  }
+
+  const body = { name, source_drive_id: source ? String(source.id) : null };
+  try {
+    const created = await runtime.fetch(computeEndpoint(STORAGE_PREFIX), {
+      body,
+      headers: idempotencyHeaders(input),
+      method: "POST",
+    });
+    return runtime.interaction.result({
+      data: { effective_input: effective, replayed: false, volume: safeVolume(created) },
+      outcome: { class: "ready", phase: "created" },
+      resume: { kind: "volume", ref: String(created?.id ?? "") },
+    });
+  } catch (error) {
+    if (error instanceof CliApiError && (error.status === undefined || error.status >= 500)) {
+      try {
+        const reconciled = resolveFromRows(await fetchDrives(runtime), name);
+        const reconciledSource =
+          reconciled?.source_drive_id ?? reconciled?.source?.source_drive_id ?? null;
+        if (String(reconciledSource ?? "") === String(effective.source_volume_id ?? "")) {
+          return runtime.interaction.result({
+            data: { effective_input: effective, replayed: true, volume: safeVolume(reconciled) },
+            outcome: { class: "ready", phase: "replayed" },
+            resume: { kind: "volume", ref: String(reconciled.id) },
+          });
+        }
+      } catch (reconciliationError) {
+        if (
+          reconciliationError instanceof StorageCommandError &&
+          reconciliationError.code !== "volume_not_found"
+        ) {
+          throw reconciliationError;
+        }
+      }
+    }
+    throw safeStorageError(error, "The volume could not be created safely.");
+  }
+}
+
+async function listVolumes(input, runtime) {
+  positionals(input, 0, "Usage: ornn volumes list [--limit <1-100>] [--cursor <cursor>]");
+  const limit = Number(input.limit ?? 25);
+  const page = await fetchDrivePage(runtime, { limit, cursor: input.cursor, scope: "managed" });
+  const rows = page.drives.filter(isManagedVolume).map(safeVolume);
+  return runtime.interaction.result({
+    data: { volumes: rows },
+    page: { limit, returned: rows.length, next_cursor: page.next_cursor },
+    outcome: { class: "ready", phase: rows.length ? "listed" : "empty" },
+  });
+}
+
+async function showVolume(input, runtime, { refresh = false } = {}) {
+  const [reference] = positionals(
+    input,
+    1,
+    `Usage: ornn volumes ${refresh ? "refresh" : "show"} <volume>`
+  );
+  const drive = await resolveVolume(runtime, reference);
+  if (!refresh) {
+    return runtime.interaction.result({ data: { volume: safeVolume(drive) } });
+  }
+  try {
+    const refreshed = await runtime.fetch(
+      computeEndpoint(`${STORAGE_PREFIX}/${encodeURIComponent(String(drive.id))}/refresh`),
+      { method: "POST" }
+    );
+    return runtime.interaction.result({
+      data: { volume: safeVolume(refreshed) },
+      outcome: { class: "ready", phase: "refreshed" },
+      resume: { kind: "volume", ref: String(drive.id) },
+    });
+  } catch (error) {
+    throw safeStorageError(error, "The volume could not be refreshed safely.");
+  }
+}
+
+async function clearVolume(input, runtime) {
+  const [reference] = positionals(input, 1, "Usage: ornn volumes clear <volume>");
+  const declined = await unsafeReview("storage.volumes.clear", input, runtime, reference);
+  if (declined) return declined;
+  const drive = await resolveVolume(runtime, reference);
+  try {
+    const payload = await runtime.fetch(
+      computeEndpoint(`${STORAGE_PREFIX}/${encodeURIComponent(String(drive.id))}/contents`),
+      { method: "DELETE" }
+    );
+    return runtime.interaction.result({
+      data: {
+        cleared: true,
+        deleted_count: Number(payload?.contents?.deleted ?? 0),
+        volume: safeVolume(drive),
+      },
+      outcome: { class: "ready", phase: "cleared" },
+    });
+  } catch (error) {
+    const ambiguous =
+      error instanceof CliApiError && (error.status === undefined || error.status >= 500);
+    if (ambiguous) {
+      throw new StorageCommandError(
+        "The clear request had an ambiguous outcome. Inspect the volume before doing anything else.",
+        {
+          action: {
+            command: `ornn volumes files list ${String(drive.id)}`,
+            type: "command",
+          },
+          code: "content_mutation_outcome_unknown",
+          exitCode: 6,
+          retryable: false,
+        }
+      );
+    }
+    throw safeStorageError(error, "The volume could not be cleared safely.");
+  }
+}
+
+async function deleteVolume(input, runtime) {
+  const [reference] = positionals(input, 1, "Usage: ornn volumes delete <volume>");
+  requireMachineMutationKey(input, runtime);
+  const declined = await review(runtime, {
+    prompt: "Delete this volume?",
+    terms: [
+      { label: "Volume", value: reference },
+      { label: "Consequence", value: "The volume and all data in it will be permanently deleted" },
+    ],
+    title: "Delete volume",
+  });
+  if (declined) return declined;
+  const drive = await resolveVolume(runtime, reference);
+  try {
+    await runtime.fetch(
+      computeEndpoint(`${STORAGE_PREFIX}/${encodeURIComponent(String(drive.id))}`),
+      {
+        headers: idempotencyHeaders(input),
+        method: "DELETE",
+      }
+    );
+    return runtime.interaction.result({
+      data: { deleted: true, volume: safeVolume(drive) },
+      outcome: { class: "ended", phase: "deleted" },
+    });
+  } catch (error) {
+    if (error instanceof CliApiError && (error.status === undefined || error.status >= 500)) {
+      try {
+        const remaining = await fetchDrives(runtime);
+        if (!remaining.some((candidate) => String(candidate?.id) === String(drive.id))) {
+          return runtime.interaction.result({
+            data: { deleted: true, reconciled: true, volume: safeVolume(drive) },
+            outcome: { class: "ended", phase: "deleted" },
+          });
+        }
+      } catch {
+        // Preserve the original ambiguous delete error when reconciliation is unavailable.
+      }
+    }
+    const detail = detailOf(error);
+    const reservations = Array.isArray(detail?.reservation_ids)
+      ? detail.reservation_ids.filter(
+          (value) => typeof value === "string" && /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(value)
+        )
+      : [];
+    throw safeStorageError(error, "The volume could not be deleted safely.", {
+      action:
+        codeOf(error) === "storage_drive_attached_to_reservation"
+          ? {
+              command: reservations[0]
+                ? `ornn volume-mounts detach ${reservations[0]}`
+                : `ornn volumes show ${String(drive.id)}`,
+              type: "command",
+            }
+          : undefined,
+    });
+  }
+}
+
+async function fetchFileRows(runtime, drive, prefix) {
+  const folder = prefix.includes("/") ? prefix.slice(0, prefix.lastIndexOf("/")) : "";
+  const entries = [];
+  let cursor = 0;
+  while (cursor !== null) {
+    const query = new URLSearchParams({ recursive: "true" });
+    if (folder) query.set("path", folder);
+    if (cursor) query.set("cursor", String(cursor));
+    let page;
+    try {
+      page = await runtime.fetch(
+        computeEndpoint(
+          `${STORAGE_PREFIX}/${encodeURIComponent(String(drive.id))}/contents?${query}`
+        ),
+        { method: "GET" }
+      );
+    } catch (error) {
+      throw safeStorageError(error, "Volume files could not be listed safely.");
+    }
+    entries.push(...(Array.isArray(page?.entries) ? page.entries : []));
+    const next = page?.next_cursor;
+    cursor = Number.isInteger(next) || (typeof next === "string" && next) ? next : null;
+  }
+  return entries
+    .filter((entry) => entry?.kind === "file")
+    .map(safeFile)
+    .filter((entry) => entry.path && entry.path.startsWith(prefix))
+    .sort(
+      (left, right) =>
+        (Date.parse(right.updated_at ?? "") || 0) - (Date.parse(left.updated_at ?? "") || 0) ||
+        left.path.localeCompare(right.path)
+    );
+}
+
+async function listFiles(input, runtime) {
+  const [reference] = positionals(
+    input,
+    1,
+    "Usage: ornn volumes files list <volume> [--prefix <remote-path>] [--limit <1-500>] [--cursor <cursor>]"
+  );
+  const prefix = normalizeRemotePath(input.prefix, { allowEmpty: true, field: "prefix" });
+  const drive = await resolveVolume(runtime, reference);
+  const rows = await fetchFileRows(runtime, drive, prefix);
+  const page = boundedPage(rows, input);
+  return runtime.interaction.result({
+    data: { files: page.items, prefix, volume: safeVolume(drive) },
+    page: page.page,
+    outcome: { class: "ready", phase: rows.length ? "listed" : "empty" },
+  });
+}
+
+async function putSignedUpload({
+  contentType,
+  fetchImpl,
+  headers,
+  localFile,
+  sizeBytes,
+  uploadUrl,
+}) {
+  let url;
+  try {
+    url = new URL(uploadUrl);
+  } catch {
+    throw new StorageCommandError("Ornn returned an invalid upload link. Start the upload again.", {
+      code: "unsafe_upload_link",
+      exitCode: 1,
+    });
+  }
+  if (
+    url.protocol !== "https:" ||
+    !(url.hostname === "storage.googleapis.com" || url.hostname.endsWith(".storage.googleapis.com"))
+  ) {
+    throw new StorageCommandError("Ornn returned an unsafe upload link. Start the upload again.", {
+      code: "unsafe_upload_link",
+      exitCode: 1,
+    });
+  }
+  const approved = new Headers();
+  for (const [name, value] of Object.entries(headers ?? {})) {
+    if (name.toLocaleLowerCase("en-US") === "content-type" && typeof value === "string") {
+      approved.set("content-type", value);
+    }
+  }
+  if (!approved.has("content-type")) approved.set("content-type", contentType);
+  approved.set("content-length", String(sizeBytes));
+  const hash = createHash("sha256");
+  let bytesHashed = 0;
+  const source = Readable.from(
+    (async function* () {
+      for await (const chunk of createReadStream(localFile)) {
+        hash.update(chunk);
+        bytesHashed += chunk.byteLength;
+        yield chunk;
+      }
+    })()
+  );
+  let response;
+  try {
+    response = await fetchImpl(url, {
+      body: source,
+      duplex: "half",
+      headers: approved,
+      method: "PUT",
+      redirect: "manual",
+    });
+  } catch {
+    return {
+      generation: null,
+      sha256: bytesHashed === sizeBytes ? hash.digest("hex") : null,
+    };
+  }
+  if (!response.ok) {
+    throw new StorageCommandError(
+      response.status === 403
+        ? "The upload link expired before the file finished uploading. Start the upload again."
+        : response.status === 409 || response.status === 412
+          ? "The destination changed while the upload was in progress. Refresh the volume and try again."
+          : "Storage could not accept the file. Start the upload again.",
+      {
+        code:
+          response.status === 403
+            ? "upload_link_expired"
+            : response.status === 409 || response.status === 412
+              ? "storage_file_changed"
+              : "upload_rejected",
+        exitCode: 1,
+      }
+    );
+  }
+  return { generation: response.headers.get("x-goog-generation"), sha256: hash.digest("hex") };
+}
+
+async function cancelUpload(runtime, driveId, uploadId) {
+  try {
+    await runtime.fetch(
+      computeEndpoint(
+        `${STORAGE_PREFIX}/${encodeURIComponent(driveId)}/file-uploads/${encodeURIComponent(uploadId)}`
+      ),
+      { method: "DELETE" }
+    );
+  } catch {
+    // Preserve the transfer error. Finalizing sessions are owner-reconciled.
+  }
+}
+
+async function uploadFile(input, runtime) {
+  const [reference, localFile] = positionals(
+    input,
+    2,
+    "Usage: ornn volumes files upload <volume> <local-file> [--path <remote-path>] [--content-type <type>] [--yes] [--idempotency-key <key>]"
+  );
+  requireMachineMutationKey(input, runtime);
+  let fileInfo;
+  try {
+    fileInfo = await stat(localFile);
+  } catch {
+    throw new StorageCommandError("The local upload file was not found.", {
+      code: "local_file_not_found",
+      field: "local-file",
+    });
+  }
+  if (!fileInfo.isFile()) {
+    throw new StorageCommandError("The upload source must be a file, not a directory.", {
+      code: "local_file_not_regular",
+      field: "local-file",
+    });
+  }
+  const remotePath = normalizeRemotePath(input.path ?? basename(localFile));
+  const contentType = input.contentType
+    ? requiredText(input.contentType, "--content-type")
+    : "application/octet-stream";
+  const drive = await resolveVolume(runtime, reference);
+  const declined = await review(runtime, {
+    prompt: "Upload this file?",
+    terms: [
+      { label: "Volume", value: `${drive.name} (${drive.id})` },
+      { label: "Local file", value: localFile },
+      { label: "Remote path", value: remotePath },
+      { label: "Bytes", value: String(fileInfo.size) },
+      {
+        label: "Consequence",
+        value: "Create or replace the selected path in the managed volume",
+      },
+    ],
+    title: "Upload volume file",
+  });
+  if (declined) return declined;
+  const requestHash = createHash("sha256");
+  for await (const chunk of createReadStream(localFile)) requestHash.update(chunk);
+  const sha256 = requestHash.digest("hex");
+  let session;
+  try {
+    session = await runtime.fetch(
+      computeEndpoint(`${STORAGE_PREFIX}/${encodeURIComponent(String(drive.id))}/file-upload-url`),
+      {
+        body: { content_type: contentType, path: remotePath, size_bytes: fileInfo.size, sha256 },
+        headers: idempotencyHeaders(input),
+        method: "POST",
+      }
+    );
+  } catch (error) {
+    throw safeStorageError(error, "The upload could not be staged safely.");
+  }
+  const uploadId =
+    typeof session?.upload_id === "string" ? safeIdentifier(session.upload_id) : null;
+  if (uploadId && session.state === "complete") {
+    return runtime.interaction.result({
+      data: {
+        file: safeFile({ path: remotePath, size_bytes: fileInfo.size }),
+        integrity: { sha256 },
+        upload_id: uploadId,
+        volume: safeVolume(drive),
+      },
+      outcome: { class: "ready", phase: "uploaded" },
+      resume: { kind: "volume-upload", ref: uploadId },
+    });
+  }
+  if (!uploadId || typeof session?.upload_url !== "string") {
+    if (uploadId) await cancelUpload(runtime, String(drive.id), uploadId);
+    throw new StorageCommandError("Ornn returned an invalid upload session.", {
+      code: "invalid_upload_session",
+      exitCode: 1,
+    });
+  }
+  try {
+    const uploaded = await putSignedUpload({
+      contentType,
+      fetchImpl: runtime.fetchImpl,
+      headers: session.headers,
+      localFile,
+      sizeBytes: fileInfo.size,
+      uploadUrl: session.upload_url,
+    });
+    const completionPath = computeEndpoint(
+      `${STORAGE_PREFIX}/${encodeURIComponent(String(drive.id))}/file-uploads/${encodeURIComponent(uploadId)}/complete`
+    );
+    let completed;
+    try {
+      completed = await runtime.fetch(completionPath, {
+        body: { uploaded_generation: uploaded.generation },
+        headers: idempotencyHeaders(input),
+        method: "POST",
+      });
+    } catch (error) {
+      if (!(error instanceof CliApiError) || (error.status !== undefined && error.status < 500))
+        throw error;
+      completed = await runtime.fetch(completionPath, {
+        body: { uploaded_generation: uploaded.generation },
+        headers: idempotencyHeaders(input),
+        method: "POST",
+      });
+    }
+    const file = safeFile(completed?.file ?? { path: remotePath, size_bytes: fileInfo.size });
+    return runtime.interaction.result({
+      data: {
+        file,
+        integrity: { sha256: uploaded.sha256 },
+        upload_id: uploadId,
+        volume: safeVolume(drive),
+      },
+      outcome: { class: "ready", phase: "uploaded" },
+      resume: { kind: "volume-upload", ref: uploadId },
+    });
+  } catch (error) {
+    await cancelUpload(runtime, String(drive.id), uploadId);
+    throw safeStorageError(error, "The upload could not be finalized safely.");
+  }
+}
+
+async function downloadResponseError(response, runtime, url, accessToken) {
+  const text = await response.text().catch(() => "");
+  if (response.status === 401) {
+    await raiseForFailedResponse({
+      accessToken,
+      env: runtime.env,
+      fallbackMessage: "The CLI session expired. Run `ornn login` and try again.",
+      response,
+      text,
+      url,
+    });
+  }
+  let code;
+  try {
+    const parsed = JSON.parse(text);
+    const detail = parsed?.detail?.detail ?? parsed?.detail;
+    code =
+      typeof detail?.code === "string" ? detail.code : typeof detail === "string" ? detail : null;
+  } catch {
+    code = null;
+  }
+  throw new StorageCommandError(
+    code === "storage_file_not_found"
+      ? "The requested volume file was not found."
+      : "The volume file could not be downloaded safely.",
+    {
+      code: /^[a-z][a-z0-9_]*$/.test(code ?? "") ? code : "download_failed",
+      exitCode: response.status >= 500 ? 6 : 1,
+      retryable: response.status >= 500,
+    }
+  );
+}
+
+async function downloadFile(input, runtime) {
+  const [reference, rawRemotePath] = positionals(
+    input,
+    2,
+    "Usage: ornn volumes files download <volume> <remote-path> --output <local-path> [--overwrite]"
+  );
+  const remotePath = normalizeRemotePath(rawRemotePath);
+  const output = requiredText(input.output, "--output");
+  try {
+    await assertAtomicOutputAvailable(output, { overwrite: input.overwrite === true });
+  } catch (error) {
+    throw safeStorageError(error, "The output path cannot be used safely.");
+  }
+  const drive = await resolveVolume(runtime, reference);
+  const session = await loadRequiredSession({ env: runtime.env });
+  const baseUrl = resolveApiBaseUrl({ env: runtime.env, session });
+  const endpoint = computeEndpoint(
+    `${STORAGE_PREFIX}/${encodeURIComponent(String(drive.id))}/files/${encodedRemotePath(remotePath)}`
+  );
+  const url = new URL(endpoint, `${baseUrl}/`);
+  let response;
+  try {
+    response = await runtime.fetchImpl(url, {
+      headers: userCredentialHeaders(session),
+      method: "GET",
+    });
+  } catch {
+    throw new StorageCommandError("The volume file could not be downloaded safely.", {
+      code: "service_unavailable",
+      exitCode: 6,
+      retryable: true,
+    });
+  }
+  if (!response.ok)
+    await downloadResponseError(response, runtime, url.toString(), session.accessToken);
+  if (!response.body) {
+    throw new StorageCommandError("Ornn returned an empty download stream.", {
+      code: "download_stream_missing",
+      exitCode: 1,
+    });
+  }
+  const hash = createHash("sha256");
+  const digesting = Readable.from(
+    (async function* () {
+      for await (const chunk of Readable.fromWeb(response.body)) {
+        hash.update(chunk);
+        yield chunk;
+      }
+    })()
+  );
+  try {
+    await writeAtomicOutput(output, digesting, {
+      mode: 0o644,
+      overwrite: input.overwrite === true,
+    });
+  } catch (error) {
+    throw safeStorageError(error, "The download could not be written safely.");
+  }
+  return runtime.interaction.result({
+    data: {
+      integrity: { sha256: hash.digest("hex") },
+      output,
+      path: remotePath,
+      volume: safeVolume(drive),
+    },
+    outcome: { class: "ready", phase: "downloaded" },
+  });
+}
+
+async function deleteContent(command, input, runtime) {
+  const kind = command === "storage.volumes.files.delete" ? "file" : "folder";
+  const [reference, rawRemotePath] = positionals(
+    input,
+    2,
+    `Usage: ornn volumes ${kind === "file" ? "files" : "folders"} delete <volume> <remote-path>`
+  );
+  const remotePath = normalizeRemotePath(rawRemotePath);
+  const declined = await unsafeReview(command, input, runtime, reference, remotePath);
+  if (declined) return declined;
+  const drive = await resolveVolume(runtime, reference);
+  const endpoint = computeEndpoint(
+    `${STORAGE_PREFIX}/${encodeURIComponent(String(drive.id))}/${kind}s/${encodedRemotePath(remotePath)}`
+  );
+  try {
+    const payload = await runtime.fetch(endpoint, { method: "DELETE" });
+    return runtime.interaction.result({
+      data: {
+        deleted: true,
+        path: remotePath,
+        ...(kind === "folder" ? { deleted_count: Number(payload?.folder?.deleted ?? 0) } : {}),
+        volume: safeVolume(drive),
+      },
+      outcome: { class: "ready", phase: `${kind}_deleted` },
+    });
+  } catch (error) {
+    const ambiguous =
+      error instanceof CliApiError && (error.status === undefined || error.status >= 500);
+    if (ambiguous) {
+      throw new StorageCommandError(
+        `The ${kind} deletion had an ambiguous outcome. Inspect the volume before doing anything else.`,
+        {
+          action: {
+            command: `ornn volumes files list ${String(drive.id)}`,
+            type: "command",
+          },
+          code: "content_mutation_outcome_unknown",
+          exitCode: 6,
+          retryable: false,
+        }
+      );
+    }
+    throw safeStorageError(error, `The volume ${kind} could not be deleted safely.`);
+  }
+}
+
+export async function executeStorageCommand(command, input, runtime) {
+  switch (command) {
+    case "storage.volumes.list":
+      return listVolumes(input, runtime);
+    case "storage.volumes.show":
+      return showVolume(input, runtime);
+    case "storage.volumes.create":
+      return createVolume(input, runtime);
+    case "storage.volumes.refresh":
+      return showVolume(input, runtime, { refresh: true });
+    case "storage.volumes.clear":
+      return clearVolume(input, runtime);
+    case "storage.volumes.delete":
+      return deleteVolume(input, runtime);
+    case "storage.volumes.files.list":
+      return listFiles(input, runtime);
+    case "storage.volumes.files.upload":
+      return uploadFile(input, runtime);
+    case "storage.volumes.files.download":
+      return downloadFile(input, runtime);
+    case "storage.volumes.files.delete":
+    case "storage.volumes.folders.delete":
+      return deleteContent(command, input, runtime);
+    default:
+      throw new StorageCommandError("Unknown storage command.", { code: "unknown_command" });
+  }
+}
+
+export function writeStorageResultHuman(stdout, capabilityId, execution) {
+  const data = execution?.data;
+  if (execution?.outcome?.phase === "declined") {
+    stdout.write("No changes made.\n");
+    return;
+  }
+  if (capabilityId === "storage.volumes.list") {
+    const volumes = data?.volumes ?? [];
+    if (!volumes.length) {
+      stdout.write("No volumes found.\n");
+      return;
+    }
+    for (const volume of volumes) {
+      stdout.write(`${volume.name}  ${volume.id}  ${volume.phase}  ${volume.size_bytes} bytes\n`);
+    }
+    if (execution.page?.next_cursor) {
+      stdout.write(
+        `Next: ornn volumes list --cursor ${execution.page.next_cursor} --format human\n`
+      );
+    }
+    return;
+  }
+  if (capabilityId === "storage.volumes.files.list") {
+    const files = data?.files ?? [];
+    if (!files.length) {
+      stdout.write("No files found.\n");
+      return;
+    }
+    for (const file of files) stdout.write(`${file.path}  ${file.size_bytes} bytes\n`);
+    if (execution.page?.next_cursor) {
+      stdout.write(
+        `Next: ornn volumes files list ${data.volume.id} --cursor ${execution.page.next_cursor} --format human\n`
+      );
+    }
+    return;
+  }
+  if (capabilityId === "storage.volumes.show" || capabilityId === "storage.volumes.refresh") {
+    const volume = data?.volume;
+    stdout.write(`${volume.name}  ${volume.id}  ${volume.phase}  ${volume.size_bytes} bytes\n`);
+    return;
+  }
+  if (capabilityId === "storage.volumes.create") {
+    stdout.write(
+      `${data.replayed ? "Found" : "Created"} volume ${data.volume.name} (${data.volume.id}).\n`
+    );
+    return;
+  }
+  if (capabilityId === "storage.volumes.clear") {
+    stdout.write(`Cleared volume ${data.volume.name}.\n`);
+    return;
+  }
+  if (capabilityId === "storage.volumes.delete") {
+    stdout.write(`Deleted volume ${data.volume.name}.\n`);
+    return;
+  }
+  if (capabilityId === "storage.volumes.files.upload") {
+    stdout.write(`Uploaded ${data.file.path} to ${data.volume.name}.\n`);
+    return;
+  }
+  if (capabilityId === "storage.volumes.files.download") {
+    stdout.write(`Downloaded ${data.path} to ${data.output}.\n`);
+    return;
+  }
+  if (capabilityId.endsWith("files.delete")) {
+    stdout.write(`Deleted file ${data.path}.\n`);
+    return;
+  }
+  if (capabilityId.endsWith("folders.delete")) {
+    stdout.write(`Deleted folder ${data.path}.\n`);
+  }
+}