@ornncompute/cli 0.2.24 → 1.0.34

package/src/external-bucket-commands.mjs

@@ -0,0 +1,1374 @@
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+
+import { CliApiError, computeEndpoint } from "./api-client.mjs";
+import { isRecoverableWaitFailure } from "./interaction-runtime.mjs";
+import {
+  codeOf,
+  fetchDrives,
+  fetchDrivePage,
+  idempotencyHeaders,
+  normalizedNameKey,
+  safeIdentifier,
+  safeTimestamp,
+  StorageCommandError,
+} from "./storage-commands.mjs";
+
+const IMPORT_POLL_INTERVAL_MS = 10_000;
+const DEFAULT_IMPORT_TIMEOUT_MS = 30 * 60 * 1_000;
+const STORAGE_PREFIX = "/nodes/storage-drives";
+const PROVIDERS = new Set(["gcs", "s3", "r2"]);
+
+function usage(message, field, code = "usage_error") {
+  throw new StorageCommandError(message, { code, exitCode: 2, field });
+}
+
+function requiredText(value, label, field) {
+  const normalized = String(value ?? "")
+    .normalize("NFKC")
+    .trim();
+  if (!normalized) usage(`${label} is required.`, field);
+  if (/\p{Cc}/u.test(normalized)) usage(`${label} cannot contain control characters.`, field);
+  return normalized;
+}
+
+function positions(input, count, usageText) {
+  const values = input.$positionals ?? [];
+  if (values.length !== count) usage(`Usage: ${usageText}`);
+  return values;
+}
+
+function externalKind(drive) {
+  const source = drive?.source ?? {};
+  const sourceProvider = String(source.provider ?? drive?.source_provider ?? "").toLowerCase();
+  if (sourceProvider === "external_gcs") return "gcs";
+  if (sourceProvider !== "s3") return null;
+  return String(source.s3_provider ?? drive?.external_s3_provider ?? "").toLowerCase() ===
+    "cloudflare_r2"
+    ? "r2"
+    : "s3";
+}
+
+function bucketRows(rows) {
+  return rows.filter((drive) => externalKind(drive) !== null);
+}
+
+function safeName(value) {
+  const name = String(value ?? "")
+    .normalize("NFKC")
+    .trim();
+  if (!name || /\p{Cc}/u.test(name)) {
+    throw new StorageCommandError("Ornn returned an unexpected external bucket name.", {
+      code: "invalid_gateway_response",
+    });
+  }
+  return name;
+}
+
+function safeOptionalText(value) {
+  if (typeof value !== "string") return null;
+  const normalized = value.normalize("NFKC").trim();
+  return normalized && !/\p{Cc}/u.test(normalized) ? normalized : null;
+}
+
+function verificationPhase(source) {
+  const status = String(source?.connection_status ?? "registered").toLowerCase();
+  if (status === "verified") return "verified";
+  if (status === "verification_failed" || status === "failed") return "failed";
+  return "unverified";
+}
+
+function verificationCode(source) {
+  const code = source?.verification_error?.code;
+  return typeof code === "string" && /^[A-Za-z][A-Za-z0-9_.-]{0,127}$/.test(code) ? code : null;
+}
+
+function safeExternalBucket(drive, { forceUnverified = false } = {}) {
+  const source = drive?.source ?? {};
+  const kind = externalKind(drive);
+  if (!kind) {
+    throw new StorageCommandError("The selected resource is not an external bucket.", {
+      code: "external_bucket_not_found",
+    });
+  }
+  const bucket = safeOptionalText(source.bucket ?? drive?.external_bucket);
+  if (!bucket) {
+    throw new StorageCommandError("Ornn returned an incomplete external bucket record.", {
+      code: "invalid_gateway_response",
+    });
+  }
+  const phase = forceUnverified ? "unverified" : verificationPhase(source);
+  return {
+    id: safeIdentifier(drive?.id),
+    name: safeName(drive?.name),
+    kind,
+    location: {
+      bucket,
+      prefix: safeOptionalText(source.prefix ?? drive?.external_prefix),
+      region: safeOptionalText(source.region ?? drive?.external_region),
+    },
+    access: {
+      mode: source.read_only === false ? "read-write" : "read-only",
+      credentials_configured: kind === "gcs" ? false : source.credentials_configured === true,
+    },
+    verification: {
+      phase,
+      checked_at: phase === "unverified" ? null : safeTimestamp(source.last_verified_at),
+      ...(phase === "failed" && verificationCode(source)
+        ? { error_code: verificationCode(source) }
+        : {}),
+    },
+    created_at: safeTimestamp(drive?.created_at),
+    updated_at: safeTimestamp(drive?.updated_at),
+  };
+}
+
+function activeMountReservations(drive) {
+  const mounts = Array.isArray(drive?.active_mounts) ? drive.active_mounts : [];
+  return [
+    ...new Set(
+      mounts
+        .filter(
+          (mount) =>
+            !["detached", "ended", "failed", "error", "cancelled"].includes(
+              String(mount?.state ?? "").toLowerCase()
+            )
+        )
+        .map((mount) => safeIdentifier(mount?.reservation_id))
+    ),
+  ];
+}
+
+function resolveExternalBucket(rows, reference) {
+  const ref = requiredText(reference, "An external bucket reference", "external-bucket");
+  const external = bucketRows(rows);
+  const byId = external.filter((drive) => String(drive?.id) === ref);
+  if (byId.length === 1) return byId[0];
+  const key = normalizedNameKey(ref);
+  const byName = external.filter((drive) => normalizedNameKey(drive?.name) === key);
+  if (byName.length === 1) return byName[0];
+  if (byName.length > 1) {
+    throw new StorageCommandError(
+      `More than one external bucket has the exact name “${ref}”. Use its canonical ID.`,
+      { code: "ambiguous_external_bucket", field: "external-bucket" }
+    );
+  }
+  throw new StorageCommandError(`External bucket not found: ${ref}`, {
+    code: "external_bucket_not_found",
+    field: "external-bucket",
+  });
+}
+
+function providerName(kind) {
+  if (kind === "gcs") return "GCS";
+  if (kind === "r2") return "Cloudflare R2";
+  return "AWS S3";
+}
+
+function providerFrom(value) {
+  const provider = String(value ?? "")
+    .trim()
+    .toLowerCase();
+  if (!PROVIDERS.has(provider)) usage("Choose one external bucket kind: gcs, s3, or r2.", "kind");
+  return provider;
+}
+
+function normalizePrefix(value) {
+  if (value === undefined || value === null || String(value).trim() === "") return null;
+  const normalized = String(value)
+    .normalize("NFKC")
+    .trim()
+    .replace(/^\/+|\/+$/g, "");
+  const segments = normalized.split("/");
+  if (
+    !normalized ||
+    segments.some(
+      (segment) => !segment || segment === "." || segment === ".." || /\p{Cc}/u.test(segment)
+    )
+  ) {
+    usage("--prefix must be a relative bucket prefix without empty, . or .. segments.", "prefix");
+  }
+  return normalized;
+}
+
+function validateBucketName(value) {
+  const bucket = requiredText(value, "A bucket name", "bucket");
+  if (
+    bucket.length > 222 ||
+    !/^[A-Za-z0-9][A-Za-z0-9._-]*[A-Za-z0-9]$/.test(bucket) ||
+    bucket.includes("..")
+  ) {
+    usage("--bucket must name one bucket without a path.", "bucket");
+  }
+  return bucket;
+}
+
+function locationFromBucket(kind, raw) {
+  const normalized = requiredText(raw, "--bucket", "bucket");
+  const scheme = normalized.match(/^([a-z0-9]+):\/\//i)?.[1]?.toLowerCase();
+  const allowedScheme =
+    scheme === kind || (kind === "gcs" && scheme === "gs") || (kind === "r2" && scheme === "s3");
+  if (scheme && !allowedScheme) {
+    usage(`The bucket URI does not match the selected ${providerName(kind)} kind.`, "bucket");
+  }
+  const withoutScheme = normalized.replace(/^[a-z0-9]+:\/\//i, "").replace(/^\/+|\/+$/g, "");
+  const [bucket, ...prefix] = withoutScheme.split("/");
+  return { bucket: validateBucketName(bucket), prefix: normalizePrefix(prefix.join("/")) };
+}
+
+function safeDecodedPath(value) {
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    usage("--url contains an invalid escaped path.", "url");
+  }
+}
+
+function locationFromConsoleUrl(kind, raw) {
+  let url;
+  try {
+    url = new URL(requiredText(raw, "--url", "url"));
+  } catch {
+    usage("--url must be a valid HTTPS cloud-console URL.", "url");
+  }
+  if (url.protocol !== "https:") usage("--url must use HTTPS.", "url");
+  const host = url.hostname.toLowerCase();
+  const parts = url.pathname.split("/").filter(Boolean).map(safeDecodedPath);
+  if (kind === "gcs") {
+    if (host !== "console.cloud.google.com") usage("Use a GCS console URL for kind gcs.", "url");
+    const browser = parts.indexOf("browser");
+    if (browser < 0 || !parts[browser + 1]) usage("GCS console URL must name one bucket.", "url");
+    return {
+      bucket: validateBucketName(parts[browser + 1]),
+      prefix: normalizePrefix(url.searchParams.get("prefix")),
+      region: null,
+      accountId: null,
+    };
+  }
+  if (kind === "s3") {
+    if (!host.endsWith(".console.aws.amazon.com") && host !== "console.aws.amazon.com") {
+      usage("Use an AWS S3 console URL for kind s3.", "url");
+    }
+    const buckets = parts.indexOf("buckets");
+    if (buckets < 0 || !parts[buckets + 1])
+      usage("AWS S3 console URL must name one bucket.", "url");
+    const hostRegion = host.split(".console.aws.amazon.com")[0];
+    return {
+      bucket: validateBucketName(parts[buckets + 1]),
+      prefix: normalizePrefix(url.searchParams.get("prefix")),
+      region: safeOptionalText(url.searchParams.get("region")) ?? safeOptionalText(hostRegion),
+      accountId: null,
+    };
+  }
+  if (host !== "dash.cloudflare.com") usage("Use a Cloudflare R2 console URL for kind r2.", "url");
+  const r2 = parts.indexOf("r2");
+  const buckets = parts.indexOf("buckets", r2 + 1);
+  if (r2 < 1 || buckets < 0 || !parts[buckets + 1]) {
+    usage("Cloudflare R2 console URL must name one account and bucket.", "url");
+  }
+  return {
+    bucket: validateBucketName(parts[buckets + 1]),
+    prefix: null,
+    region: "auto",
+    accountId: requiredText(parts[0], "A Cloudflare account ID", "account-id"),
+  };
+}
+
+function endpointForR2(accountId, endpointUrl) {
+  if (accountId && endpointUrl) usage("Use only one of --account-id or --endpoint-url.");
+  if (endpointUrl) {
+    let parsed;
+    try {
+      parsed = new URL(requiredText(endpointUrl, "--endpoint-url", "endpoint-url"));
+    } catch {
+      usage("--endpoint-url must be a valid Cloudflare R2 HTTPS URL.", "endpoint-url");
+    }
+    const host = parsed.hostname.toLowerCase();
+    if (
+      parsed.protocol !== "https:" ||
+      (host !== "r2.cloudflarestorage.com" && !host.endsWith(".r2.cloudflarestorage.com")) ||
+      parsed.username ||
+      parsed.password ||
+      parsed.search ||
+      parsed.hash
+    ) {
+      usage("--endpoint-url must be a credential-free Cloudflare R2 HTTPS origin.", "endpoint-url");
+    }
+    return `${parsed.protocol}//${parsed.host}`;
+  }
+  const account = requiredText(
+    accountId,
+    "Cloudflare R2 requires --account-id or --endpoint-url",
+    "account-id"
+  );
+  if (!/^[A-Za-z0-9_-]{3,128}$/.test(account)) usage("--account-id is invalid.", "account-id");
+  return `https://${account}.r2.cloudflarestorage.com`;
+}
+
+async function readCredentialFile(pathValue) {
+  const path = requiredText(pathValue, "--secret-access-key-file", "secret-access-key-file");
+  let secret;
+  try {
+    secret = (await readFile(path, "utf8")).trim();
+  } catch {
+    usage("The secret access key file could not be read.", "secret-access-key-file");
+  }
+  if (!secret || secret.length > 16_384 || /[\r\n]/.test(secret)) {
+    usage(
+      "The secret access key file must contain exactly one non-empty credential.",
+      "secret-access-key-file"
+    );
+  }
+  return secret;
+}
+
+async function connectionIntent(input) {
+  const [rawKind] = positions(
+    input,
+    1,
+    "ornn external-buckets connect <gcs|s3|r2> --bucket <bucket> [provider options]"
+  );
+  const kind = providerFrom(rawKind);
+  if (Boolean(input.bucket) === Boolean(input.url)) {
+    usage("Choose exactly one of --bucket or --url.");
+  }
+  if (input.readOnly && input.readWrite) usage("Choose only one of --read-only or --read-write.");
+  const parsed = input.bucket
+    ? locationFromBucket(kind, input.bucket)
+    : locationFromConsoleUrl(kind, input.url);
+  const suppliedPrefix = normalizePrefix(input.prefix);
+  if (suppliedPrefix && parsed.prefix && suppliedPrefix !== parsed.prefix) {
+    usage("The URI prefix and --prefix differ. Supply the intended prefix once.", "prefix");
+  }
+  const prefix = suppliedPrefix ?? parsed.prefix;
+  const region = safeOptionalText(input.region) ?? parsed.region ?? (kind === "r2" ? "auto" : null);
+  let endpoint = null;
+  let accessKeyId = null;
+  let secretAccessKey = null;
+  if (kind === "gcs") {
+    if (
+      input.accountId ||
+      input.endpointUrl ||
+      input.region ||
+      input.accessKeyId ||
+      input.secretAccessKeyFile
+    ) {
+      usage("GCS connect does not accept S3 or R2 region, endpoint, or credential options.");
+    }
+  } else {
+    accessKeyId = requiredText(input.accessKeyId, "--access-key-id", "access-key-id");
+    secretAccessKey = await readCredentialFile(input.secretAccessKeyFile);
+    if (kind === "s3" && (input.accountId || input.endpointUrl)) {
+      usage("--account-id and --endpoint-url are only valid for Cloudflare R2.");
+    }
+    if (kind === "r2") {
+      endpoint = endpointForR2(input.accountId ?? parsed.accountId, input.endpointUrl);
+    }
+  }
+  const name = safeName(input.name ?? parsed.bucket);
+  return {
+    accessKeyId,
+    bucket: parsed.bucket,
+    endpoint,
+    kind,
+    name,
+    prefix,
+    readOnly: input.readWrite !== true,
+    region,
+    secretAccessKey,
+  };
+}
+
+function credentialFingerprint(accessKeyId, secret) {
+  return createHash("sha256").update(accessKeyId).update("\0").update(secret).digest("hex");
+}
+
+function keyHintMatches(source, accessKeyId) {
+  if (!accessKeyId) return source.credentials_configured !== true;
+  const hint = safeOptionalText(source.access_key_id_hint);
+  return source.credentials_configured === true && (!hint || hint.endsWith(accessKeyId.slice(-4)));
+}
+
+function connectionEquivalent(drive, intent) {
+  const source = drive?.source ?? {};
+  return (
+    externalKind(drive) === intent.kind &&
+    safeOptionalText(source.bucket) === intent.bucket &&
+    (safeOptionalText(source.prefix) ?? null) === intent.prefix &&
+    (safeOptionalText(source.region) ?? null) === intent.region &&
+    (source.read_only !== false) === intent.readOnly &&
+    (safeOptionalText(source.endpoint_url) ?? null) === intent.endpoint &&
+    keyHintMatches(source, intent.accessKeyId)
+  );
+}
+
+function requireMutationPreflight(input, runtime, { consent = false } = {}) {
+  const noninteractive = runtime.interaction.machine || runtime.interaction.redirected;
+  if (noninteractive && !String(input.idempotencyKey ?? "").trim()) {
+    usage(
+      "Noninteractive mutations require --idempotency-key <caller-stable-key>.",
+      "idempotency-key"
+    );
+  }
+  if (noninteractive && consent && input.yes !== true) {
+    usage(
+      "Consent is required. Review the exact intent and supply --yes.",
+      "yes",
+      "consent_required"
+    );
+  }
+}
+
+async function reviewed(runtime, options) {
+  const accepted = await runtime.interaction.review(options);
+  if (accepted) return null;
+  return runtime.interaction.result({
+    data: null,
+    exitCode: 1,
+    outcome: { class: "ended", phase: "declined" },
+  });
+}
+
+const SAFE_EXTERNAL_ERRORS = {
+  external_bucket_required: "The external bucket record is incomplete.",
+  external_endpoint_url_invalid: "The Cloudflare R2 endpoint is invalid.",
+  external_endpoint_url_required: "Cloudflare R2 requires an account endpoint.",
+  external_s3_credentials_required: "Current S3-compatible credentials are required.",
+  storage_drive_attached_elsewhere:
+    "This working volume is already attached to a different reservation.",
+  storage_drive_attached_to_reservation:
+    "Detach the working volume from every reservation before disconnecting the source.",
+  storage_location_unavailable:
+    "No managed destination is available for this reservation. The source bucket was not changed.",
+  storage_regional_bucket_unconfigured:
+    "Managed destination storage is temporarily unavailable. The source bucket was not changed.",
+  storage_reservation_node_offline:
+    "A reservation machine is offline, so the import destination was not changed.",
+  storage_source_client_unavailable: "The external bucket client is temporarily unavailable.",
+  storage_source_list_failed: "Ornn could not read the external bucket.",
+  storage_source_not_verified: "Verify this external bucket before importing it.",
+  storage_source_verification_unsupported: "This external bucket kind cannot be verified.",
+};
+
+function safeExternalError(error, fallback, { action, forcePartial = false } = {}) {
+  if (error instanceof StorageCommandError) return error;
+  if (error instanceof CliApiError && (error.status === 401 || error.status === 403)) {
+    return new StorageCommandError(
+      error.status === 401
+        ? "Sign in to continue."
+        : "This organization cannot perform that operation.",
+      {
+        code: error.status === 401 ? "authentication_required" : "authorization_denied",
+        exitCode: 5,
+      }
+    );
+  }
+  const code = codeOf(error);
+  const unavailable = error?.status === undefined || error?.status >= 500;
+  return new StorageCommandError(SAFE_EXTERNAL_ERRORS[code] ?? fallback, {
+    action,
+    code: code ?? (unavailable ? "service_unavailable" : "external_bucket_operation_failed"),
+    exitCode: forcePartial ? 4 : unavailable ? 6 : 1,
+    outcomeClass: forcePartial ? "partial" : unavailable ? "failed" : "failed",
+    retryable: forcePartial || unavailable,
+  });
+}
+
+async function listBuckets(input, runtime) {
+  positions(input, 0, "ornn external-buckets list [--limit <1-100>] [--cursor <cursor>]");
+  const limit = Number(input.limit ?? 25);
+  const page = await fetchDrivePage(runtime, { limit, cursor: input.cursor, scope: "external" });
+  const rows = bucketRows(page.drives).map((drive) => safeExternalBucket(drive));
+  return runtime.interaction.result({
+    data: { external_buckets: rows },
+    page: { limit, returned: rows.length, next_cursor: page.next_cursor },
+  });
+}
+
+async function showBucket(input, runtime) {
+  const [reference] = positions(input, 1, "ornn external-buckets show <external-bucket>");
+  const bucket = resolveExternalBucket(await fetchDrives(runtime), reference);
+  return runtime.interaction.result({ data: { external_bucket: safeExternalBucket(bucket) } });
+}
+
+async function connectBucket(input, runtime) {
+  const intent = await connectionIntent(input);
+  requireMutationPreflight(input, runtime, { consent: true });
+  const fingerprint =
+    intent.accessKeyId && intent.secretAccessKey
+      ? credentialFingerprint(intent.accessKeyId, intent.secretAccessKey)
+      : null;
+  const declined = await reviewed(runtime, {
+    title: "Connect external bucket",
+    terms: [
+      { label: "Kind", value: providerName(intent.kind) },
+      { label: "Name", value: intent.name },
+      { label: "Bucket", value: intent.bucket },
+      { label: "Prefix", value: intent.prefix ?? "(bucket root)" },
+      { label: "Access", value: intent.readOnly ? "read-only" : "read-write" },
+      {
+        label: "Credentials",
+        value: fingerprint ? `fingerprint ${fingerprint.slice(0, 12)}` : "ambient GCS access",
+      },
+      { label: "Verification", value: "separate command required" },
+    ],
+    prompt: "Connect this external bucket?",
+  });
+  if (declined) return declined;
+
+  const rows = await fetchDrives(runtime);
+  const sameName = bucketRows(rows).filter(
+    (drive) => normalizedNameKey(drive?.name) === normalizedNameKey(intent.name)
+  );
+  if (sameName.length > 1) {
+    throw new StorageCommandError(
+      `More than one external bucket has the exact name “${intent.name}”. Use a different name.`,
+      { code: "ambiguous_external_bucket", field: "name" }
+    );
+  }
+  if (sameName.length === 1) {
+    if (!connectionEquivalent(sameName[0], intent)) {
+      throw new StorageCommandError(
+        "That external bucket name already has different source, access, or credential intent. Review the existing connection or choose a new name.",
+        { code: "external_bucket_name_conflict", field: "name" }
+      );
+    }
+    const safe = safeExternalBucket(sameName[0]);
+    return runtime.interaction.result({
+      data: {
+        external_bucket: safe,
+        replayed: true,
+        verification_required: safe.verification.phase !== "verified",
+      },
+      outcome: {
+        class: safe.verification.phase === "failed" ? "failed" : "ready",
+        phase: "replayed",
+      },
+      presentation: {
+        lines: [
+          `External bucket connection replayed: ${safe.name} (${safe.id})`,
+          "Connection and verification are separate operations.",
+        ],
+        next: `ornn external-buckets verify ${safe.id}`,
+      },
+    });
+  }
+
+  let created;
+  try {
+    created = await runtime.fetch(computeEndpoint(STORAGE_PREFIX), {
+      body: {
+        name: intent.name,
+        provider: "ornn_volume",
+        source_provider: intent.kind === "gcs" ? "external_gcs" : "s3",
+        external_bucket: intent.bucket,
+        external_prefix: intent.prefix,
+        external_region: intent.region,
+        external_read_only: intent.readOnly,
+        ...(intent.kind === "s3" ? { external_s3_provider: "aws_s3" } : {}),
+        ...(intent.kind === "r2" ? { external_s3_provider: "cloudflare_r2" } : {}),
+        ...(intent.endpoint ? { external_endpoint_url: intent.endpoint } : {}),
+        ...(intent.accessKeyId ? { external_access_key_id: intent.accessKeyId } : {}),
+        ...(intent.secretAccessKey ? { external_secret_access_key: intent.secretAccessKey } : {}),
+      },
+      headers: idempotencyHeaders(input),
+      method: "POST",
+    });
+  } catch (error) {
+    throw safeExternalError(error, "The external bucket could not be connected safely.");
+  }
+  const safe = safeExternalBucket(created, { forceUnverified: true });
+  return runtime.interaction.result({
+    data: { external_bucket: safe, replayed: false, verification_required: true },
+    outcome: { class: "ready", phase: "connected" },
+    presentation: {
+      lines: [
+        `External bucket connected: ${safe.name} (${safe.id})`,
+        "Connection recorded; access has not been verified.",
+      ],
+      next: `ornn external-buckets verify ${safe.id}`,
+    },
+  });
+}
+
+async function verifyBucket(input, runtime) {
+  const [reference] = positions(input, 1, "ornn external-buckets verify <external-bucket>");
+  requireMutationPreflight(input, runtime);
+  const source = resolveExternalBucket(await fetchDrives(runtime), reference);
+  const id = safeIdentifier(source.id);
+  let verified;
+  try {
+    verified = await runtime.fetch(
+      computeEndpoint(`${STORAGE_PREFIX}/${encodeURIComponent(id)}/verify-source`),
+      {
+        headers: idempotencyHeaders(input),
+        method: "POST",
+      }
+    );
+  } catch (error) {
+    throw safeExternalError(error, "External bucket verification could not be completed safely.");
+  }
+  const safe = safeExternalBucket(verified);
+  if (safe.verification.phase === "failed") {
+    const action = { kind: "retry", command: `ornn external-buckets verify ${safe.id}` };
+    return runtime.interaction.result({
+      action,
+      data: { external_bucket: safe },
+      errors: [
+        {
+          code: "external_bucket_verification_failed",
+          message: "Ornn could not verify current access to this external bucket.",
+          retryable: true,
+        },
+      ],
+      exitCode: 1,
+      outcome: { class: "failed", phase: "verification_failed" },
+      presentation: {
+        lines: [`External bucket verification failed: ${safe.name} (${safe.id})`],
+        next: action.command,
+      },
+    });
+  }
+  return runtime.interaction.result({
+    data: { external_bucket: safe },
+    outcome: { class: "ready", phase: "verified" },
+    presentation: { lines: [`External bucket verified: ${safe.name} (${safe.id})`] },
+  });
+}
+
+async function updateCredentials(input, runtime) {
+  const [reference] = positions(
+    input,
+    1,
+    "ornn external-buckets update-credentials <external-bucket> --access-key-id <id> --secret-access-key-file <path>"
+  );
+  const accessKeyId = requiredText(input.accessKeyId, "--access-key-id", "access-key-id");
+  const secret = await readCredentialFile(input.secretAccessKeyFile);
+  requireMutationPreflight(input, runtime, { consent: true });
+  const fingerprint = credentialFingerprint(accessKeyId, secret);
+  const source = resolveExternalBucket(await fetchDrives(runtime), reference);
+  const kind = externalKind(source);
+  if (kind === "gcs") {
+    usage(
+      "GCS connections use ambient access and do not accept S3 credentials.",
+      "external-bucket"
+    );
+  }
+  const id = safeIdentifier(source.id);
+  const declined = await reviewed(runtime, {
+    title: "Update external bucket credentials",
+    terms: [
+      { label: "External bucket", value: `${safeName(source.name)} (${id})` },
+      { label: "Kind", value: providerName(kind) },
+      { label: "Credential fingerprint", value: fingerprint.slice(0, 12) },
+      { label: "Verification", value: "must be run again" },
+    ],
+    prompt: "Replace these credentials?",
+  });
+  if (declined) return declined;
+  let updated;
+  try {
+    updated = await runtime.fetch(
+      computeEndpoint(`${STORAGE_PREFIX}/${encodeURIComponent(id)}/source-credentials`),
+      {
+        body: {
+          external_access_key_id: accessKeyId,
+          external_secret_access_key: secret,
+        },
+        headers: idempotencyHeaders(input),
+        method: "PATCH",
+      }
+    );
+  } catch (error) {
+    throw safeExternalError(error, "External bucket credentials could not be updated safely.");
+  }
+  const safe = safeExternalBucket(updated, { forceUnverified: true });
+  return runtime.interaction.result({
+    data: { external_bucket: safe, credentials_updated: true, verification_required: true },
+    outcome: { class: "ready", phase: "credentials_updated" },
+    presentation: {
+      lines: [
+        `Credentials updated for external bucket: ${safe.name} (${safe.id})`,
+        "Stored credential values are never included in command output.",
+      ],
+      next: `ornn external-buckets verify ${safe.id}`,
+    },
+  });
+}
+
+async function disconnectBucket(input, runtime) {
+  const [reference] = positions(input, 1, "ornn external-buckets disconnect <external-bucket>");
+  requireMutationPreflight(input, runtime, { consent: true });
+  const source = resolveExternalBucket(await fetchDrives(runtime), reference);
+  const safe = safeExternalBucket(source);
+  const declined = await reviewed(runtime, {
+    title: "Disconnect external bucket",
+    terms: [
+      { label: "External bucket", value: `${safe.name} (${safe.id})` },
+      { label: "Kind", value: providerName(safe.kind) },
+      { label: "Source writeback", value: "disabled" },
+      { label: "Consequence", value: "source access is removed after all mounts are detached" },
+    ],
+    prompt: "Disconnect this external bucket?",
+  });
+  if (declined) return declined;
+  const attachedReservations = activeMountReservations(source);
+  if (attachedReservations.length > 0) {
+    throw new StorageCommandError(
+      `Detach this external bucket from ${attachedReservations.join(", ")} before disconnecting it.`,
+      {
+        action: {
+          kind: "detach",
+          command: `ornn volume-mounts detach ${attachedReservations[0]}`,
+        },
+        code: "storage_drive_attached_to_reservation",
+      }
+    );
+  }
+  try {
+    await runtime.fetch(computeEndpoint(`${STORAGE_PREFIX}/${encodeURIComponent(safe.id)}`), {
+      headers: idempotencyHeaders(input),
+      method: "DELETE",
+    });
+  } catch (error) {
+    throw safeExternalError(error, "The external bucket could not be disconnected safely.");
+  }
+  return runtime.interaction.result({
+    data: {
+      external_bucket: { id: safe.id, name: safe.name, kind: safe.kind },
+      disconnected: true,
+      source_writeback: false,
+    },
+    outcome: { class: "ended", phase: "disconnected" },
+    presentation: { lines: [`External bucket disconnected: ${safe.name} (${safe.id})`] },
+  });
+}
+
+function canonicalReservation(value) {
+  const reservation = requiredText(value, "--reservation", "reservation");
+  if (
+    !/^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(reservation)
+  ) {
+    usage("--reservation must be a canonical reservation ID.", "reservation");
+  }
+  return reservation.toLowerCase();
+}
+
+function parseTimeout(value) {
+  if (value === undefined) return DEFAULT_IMPORT_TIMEOUT_MS;
+  const match = String(value)
+    .trim()
+    .match(/^(\d+(?:\.\d+)?)(ms|s|m|h)?$/i);
+  if (!match) usage("--timeout must be a positive duration such as 30s or 20m.", "timeout");
+  const amount = Number(match[1]);
+  const units = { ms: 1, s: 1_000, m: 60_000, h: 3_600_000 };
+  const milliseconds = amount * units[(match[2] ?? "s").toLowerCase()];
+  if (!Number.isFinite(milliseconds) || milliseconds <= 0 || milliseconds > 24 * 3_600_000) {
+    usage("--timeout must be greater than zero and no more than 24h.", "timeout");
+  }
+  return milliseconds;
+}
+
+function attachmentFrom(payload) {
+  // A detached reservation answers {"attachment": null}; without this the
+  // wrapper itself reads as an attachment and every import fails closed.
+  if (payload && typeof payload === "object" && "attachment" in payload) {
+    return payload.attachment ?? null;
+  }
+  return payload ?? null;
+}
+
+async function fetchImportAttachment(runtime, reservationId, { signal } = {}) {
+  try {
+    const payload = await runtime.fetch(
+      computeEndpoint(
+        `/nodes/reservations/${encodeURIComponent(reservationId)}/storage-attachment`
+      ),
+      { method: "GET", ...(signal ? { signal } : {}) }
+    );
+    return attachmentFrom(payload);
+  } catch (error) {
+    if (error instanceof CliApiError && error.status === 404) return null;
+    throw error;
+  }
+}
+
+function safeCount(value) {
+  const count = Number(value);
+  return Number.isFinite(count) && count >= 0 ? count : 0;
+}
+
+function transferProjection(attachment) {
+  const placement = attachment?.placement ?? {};
+  const transfer = placement.transfer ?? {};
+  const legacy = placement.transfer_progress ?? {};
+  const rawState = String(
+    transfer.state ??
+      placement.transfer_status ??
+      attachment?.transfer_state ??
+      attachment?.state ??
+      "queued"
+  ).toLowerCase();
+  const failed =
+    ["failed", "error", "cancelled"].includes(rawState) ||
+    ["failed", "error"].includes(String(attachment?.state ?? "").toLowerCase());
+  const ready =
+    ["ready", "complete", "completed", "succeeded"].includes(rawState) ||
+    (!failed && ["ready", "attached"].includes(String(attachment?.state ?? "").toLowerCase()));
+  const phase = failed ? "failed" : ready ? "ready" : "working";
+  return {
+    phase,
+    objects: {
+      copied: safeCount(transfer.objects_copied ?? legacy.completed_objects),
+      total: safeCount(transfer.objects_total ?? legacy.total_objects),
+    },
+    bytes: {
+      copied: safeCount(transfer.bytes_copied ?? legacy.completed_bytes),
+      total: safeCount(transfer.bytes_total ?? legacy.total_bytes),
+    },
+  };
+}
+
+function importFailureKind(attachment) {
+  const error =
+    attachment?.placement?.transfer?.error ?? attachment?.placement?.error ?? attachment?.error;
+  const raw = typeof error === "string" ? error : error?.code;
+  const normalized = String(raw ?? "").toLowerCase();
+  if (normalized.includes("source") || normalized.includes("credential")) return "source";
+  if (
+    normalized.includes("destination") ||
+    normalized.includes("location") ||
+    normalized.includes("regional") ||
+    normalized.includes("target")
+  ) {
+    return "destination";
+  }
+  return "transfer";
+}
+
+function importData(bucket, reservationId, attachment) {
+  const transfer = transferProjection(attachment);
+  return {
+    external_bucket: bucket,
+    working_volume: {
+      id: bucket.id,
+      name: bucket.name,
+      phase: transfer.phase,
+      reservation_id: reservationId,
+      isolated: true,
+      source_writeback: false,
+    },
+    transfer,
+  };
+}
+
+function resumeImport(bucketId, reservationId, kind) {
+  const command = `ornn external-buckets import ${kind} ${bucketId} --reservation ${reservationId} --wait --timeout 30m`;
+  return {
+    action: { kind: "resume", command },
+    resume: { kind: "managed_volume", ref: bucketId },
+  };
+}
+
+function withProgress(runtime, init, progress) {
+  const execution = runtime.interaction.result(init);
+  execution.progress = progress;
+  return execution;
+}
+
+function transferProgressMessage(data, phase) {
+  const transfer = data.transfer;
+  const objects = transfer.objects.total
+    ? `${transfer.objects.copied}/${transfer.objects.total} objects`
+    : `${transfer.objects.copied} objects`;
+  const bytes = transfer.bytes.total
+    ? `${transfer.bytes.copied}/${transfer.bytes.total} bytes`
+    : `${transfer.bytes.copied} bytes`;
+  return `Import ${phase.replaceAll("_", " ")}: ${objects}, ${bytes}`;
+}
+
+function progressEvent(runtime, data, phase, sequence) {
+  return {
+    data,
+    message: transferProgressMessage(data, phase),
+    observedAt: new Date(runtime.now?.() ?? Date.now()).toISOString(),
+    outcome: {
+      class: phase === "ready" ? "ready" : phase === "failed" ? "partial" : "working",
+      phase,
+    },
+    resume: { kind: "managed_volume", ref: data.working_volume.id },
+    sequence,
+  };
+}
+
+function reportHumanProgress(runtime, data) {
+  if (runtime.interaction.format !== "human" || !runtime.interaction.eligibleHuman) return;
+  const progress = data.transfer;
+  const objects = progress.objects.total
+    ? `${progress.objects.copied}/${progress.objects.total} objects`
+    : `${progress.objects.copied} objects`;
+  const bytes = progress.bytes.total
+    ? `${progress.bytes.copied}/${progress.bytes.total} bytes`
+    : `${progress.bytes.copied} bytes`;
+  runtime.stderr.write(
+    `Import ${progress.phase}: ${objects}, ${bytes}; working volume ${data.working_volume.id}\n`
+  );
+}
+
+function terminalImportExecution(runtime, bucket, reservationId, attachment, progress) {
+  const data = importData(bucket, reservationId, attachment);
+  if (data.transfer.phase === "ready") {
+    return withProgress(
+      runtime,
+      {
+        data,
+        outcome: { class: "ready", phase: "imported" },
+        presentation: {
+          lines: [
+            `Managed working volume ready: ${bucket.name} (${bucket.id})`,
+            "Source writeback is disabled; later volume changes stay only in the managed copy.",
+          ],
+          next: `ornn volume-mounts show ${reservationId}`,
+        },
+        resume: { kind: "managed_volume", ref: bucket.id },
+      },
+      progress
+    );
+  }
+  if (data.transfer.phase !== "failed") return null;
+  const failureKind = importFailureKind(attachment);
+  const recovery = resumeImport(bucket.id, reservationId, bucket.kind);
+  return withProgress(
+    runtime,
+    {
+      ...recovery,
+      data,
+      errors: [
+        {
+          code: `external_bucket_import_${failureKind}_failed`,
+          message:
+            failureKind === "source"
+              ? "The source could not be read. The managed working-volume reference is preserved."
+              : failureKind === "destination"
+                ? "The managed destination could not be completed atomically. The working-volume reference is preserved."
+                : "The managed copy did not complete. The working-volume reference is preserved.",
+          retryable: true,
+        },
+      ],
+      exitCode: 4,
+      outcome: { class: "partial", phase: `${failureKind}_failed` },
+      presentation: {
+        lines: [
+          `Managed working volume preserved: ${bucket.name} (${bucket.id})`,
+          "Source writeback remains disabled.",
+        ],
+        next: recovery.action.command,
+      },
+    },
+    progress
+  );
+}
+
+function stoppedImportExecution(runtime, bucket, reservationId, attachment, progress, kind) {
+  const interrupted = kind === "interrupted";
+  const data = importData(bucket, reservationId, attachment);
+  const recovery = resumeImport(bucket.id, reservationId, bucket.kind);
+  if (!interrupted) {
+    progress.push(progressEvent(runtime, data, "local_timeout", progress.length + 1));
+  }
+  return withProgress(
+    runtime,
+    {
+      ...recovery,
+      data,
+      errors: [
+        {
+          code: interrupted ? "interrupted" : "local_timeout",
+          message: interrupted
+            ? "Local waiting stopped; the managed import continues remotely."
+            : "Local waiting timed out; the managed import continues remotely.",
+          retryable: true,
+        },
+      ],
+      exitCode: interrupted ? 130 : 124,
+      outcome: { class: "working", phase: interrupted ? "interrupted" : "local_timeout" },
+      presentation: {
+        lines: [
+          `Managed working volume preserved: ${bucket.name} (${bucket.id})`,
+          "Source writeback remains disabled.",
+        ],
+        next: recovery.action.command,
+      },
+    },
+    progress
+  );
+}
+
+async function waitForImport(runtime, bucket, reservationId, initial, timeoutMs) {
+  let attachment = initial;
+  const progress = [];
+  let outcome;
+  try {
+    outcome = await runtime.interaction.waitForGoal({
+      command: "ornn external-buckets import",
+      emitProgress: false,
+      initial,
+      intervalMs: IMPORT_POLL_INTERVAL_MS,
+      isReady: (current) =>
+        Boolean(
+          current &&
+          String(current.drive_id ?? "") === bucket.id &&
+          transferProjection(current).phase === "ready"
+        ),
+      isTerminal: (current) =>
+        !current ||
+        String(current.drive_id ?? "") !== bucket.id ||
+        transferProjection(current).phase === "failed",
+      message: () => "Waiting for the managed bucket import.",
+      onObserve: (current) => {
+        attachment = current;
+        const data = importData(bucket, reservationId, current);
+        progress.push(progressEvent(runtime, data, data.transfer.phase, progress.length + 1));
+        reportHumanProgress(runtime, data);
+      },
+      poll: ({ signal }) => fetchImportAttachment(runtime, reservationId, { signal }),
+      pollImmediately: true,
+      timeoutMs,
+    });
+  } catch (error) {
+    if (!isRecoverableWaitFailure(error)) throw error;
+    const data = {
+      ...importData(bucket, reservationId, attachment),
+      remote_work_cancelled: false,
+    };
+    const recovery = resumeImport(bucket.id, reservationId, bucket.kind);
+    const status = Number(error?.status);
+    const authentication = status === 401;
+    const authorization = status === 403;
+    const action = authentication
+      ? {
+          kind: "login",
+          command: "ornn login",
+          description: "Restore an authorized session, then resume the exact accepted import.",
+          type: "command",
+        }
+      : recovery.action;
+    const code = authentication
+      ? "authentication_required"
+      : authorization
+        ? "authorization_denied"
+        : "service_unavailable";
+    return withProgress(
+      runtime,
+      {
+        ...recovery,
+        action,
+        data,
+        errors: [
+          {
+            code,
+            message: authentication
+              ? "Sign in to resume status checks for the accepted import."
+              : authorization
+                ? "This organization can no longer read the accepted import."
+                : "Import status could not be loaded. The managed working-volume reference is preserved.",
+            retryable: !authorization,
+          },
+        ],
+        exitCode: authorization || authentication ? 5 : 6,
+        outcome: { class: "working", phase: "status_unavailable" },
+        presentation: {
+          lines: [
+            `Managed working volume preserved: ${bucket.name} (${bucket.id})`,
+            "Source writeback remains disabled.",
+          ],
+          next: action.command,
+        },
+      },
+      progress
+    );
+  }
+
+  attachment = outcome.value;
+  if (outcome.kind === "interrupted" || outcome.kind === "timeout") {
+    return stoppedImportExecution(
+      runtime,
+      bucket,
+      reservationId,
+      attachment,
+      progress,
+      outcome.kind
+    );
+  }
+  if (!attachment || String(attachment.drive_id ?? "") !== bucket.id) {
+    const data = importData(bucket, reservationId, attachment);
+    const recovery = resumeImport(bucket.id, reservationId, bucket.kind);
+    return withProgress(
+      runtime,
+      {
+        ...recovery,
+        data,
+        errors: [
+          {
+            code: "external_bucket_import_destination_missing",
+            message:
+              "The managed destination was not published; the source bucket was not changed.",
+            retryable: true,
+          },
+        ],
+        exitCode: 4,
+        outcome: { class: "partial", phase: "destination_missing" },
+        presentation: {
+          lines: [
+            `Managed working volume preserved: ${bucket.name} (${bucket.id})`,
+            "Source writeback remains disabled.",
+          ],
+          next: recovery.action.command,
+        },
+      },
+      progress
+    );
+  }
+  return terminalImportExecution(runtime, bucket, reservationId, attachment, progress);
+}
+
+async function importBucket(input, runtime) {
+  const [rawKind, reference] = positions(
+    input,
+    2,
+    "ornn external-buckets import <gcs|s3|r2> <external-bucket> --reservation <canonical-reservation-id> [--wait --timeout <duration>]"
+  );
+  const kind = providerFrom(rawKind);
+  if (kind === "r2") {
+    usage(
+      "Cloudflare R2 import is not supported. R2 buckets can be connected, verified, updated, and disconnected.",
+      "kind",
+      "external_bucket_import_unsupported"
+    );
+  }
+  if (input.wait && input.noWait) usage("Choose only one of --wait or --no-wait.");
+  const reservationId = canonicalReservation(input.reservation);
+  const wait = input.wait === true || (runtime.interaction.eligibleHuman && input.noWait !== true);
+  if (!wait && input.timeout !== undefined)
+    usage("--timeout requires waiting for the import.", "timeout");
+  if (
+    (runtime.interaction.machine || runtime.interaction.redirected) &&
+    wait &&
+    input.timeout === undefined
+  ) {
+    usage("Noninteractive --wait requires --timeout <duration>.", "timeout");
+  }
+  const timeoutMs = parseTimeout(input.timeout);
+  requireMutationPreflight(input, runtime, { consent: true });
+
+  const source = resolveExternalBucket(await fetchDrives(runtime), reference);
+  const bucket = safeExternalBucket(source);
+  if (bucket.kind !== kind) {
+    throw new StorageCommandError(
+      `The selected external bucket is ${providerName(bucket.kind)}, not ${providerName(kind)}. Review the import intent.`,
+      { code: "external_bucket_kind_conflict", field: "kind" }
+    );
+  }
+  if (bucket.verification.phase !== "verified") {
+    throw new StorageCommandError("Verify this external bucket before importing it.", {
+      action: { kind: "verify", command: `ornn external-buckets verify ${bucket.id}` },
+      code: "external_bucket_not_verified",
+      exitCode: 3,
+      outcomeClass: "action_required",
+    });
+  }
+  const otherReservation = (Array.isArray(source.active_mounts) ? source.active_mounts : [])
+    .filter(
+      (mount) =>
+        !["detached", "ended", "failed"].includes(String(mount?.state ?? "").toLowerCase()) &&
+        String(mount?.reservation_id ?? "") !== reservationId
+    )
+    .map((mount) => safeIdentifier(mount.reservation_id))[0];
+  if (otherReservation) {
+    throw new StorageCommandError(
+      "This external bucket already has a working volume on another reservation. Detach it before changing import intent.",
+      {
+        action: {
+          kind: "detach",
+          command: `ornn volume-mounts detach ${otherReservation}`,
+        },
+        code: "external_bucket_import_goal_conflict",
+      }
+    );
+  }
+
+  let existing;
+  try {
+    existing = await fetchImportAttachment(runtime, reservationId);
+  } catch (error) {
+    throw safeExternalError(
+      error,
+      "The current managed destination could not be inspected safely."
+    );
+  }
+  if (
+    existing &&
+    String(existing.drive_id ?? "") !== bucket.id &&
+    !["detached", "ended"].includes(String(existing.state ?? "").toLowerCase())
+  ) {
+    throw new StorageCommandError(
+      "This reservation already has a different working volume. Detach it before changing import intent.",
+      {
+        action: { kind: "detach", command: `ornn volume-mounts detach ${reservationId}` },
+        code: "external_bucket_import_goal_conflict",
+      }
+    );
+  }
+
+  const existingState = String(existing?.state ?? "").toLowerCase();
+  let attachment =
+    existing &&
+    String(existing.drive_id ?? "") === bucket.id &&
+    !["detached", "ended", "failed", "error", "cancelled"].includes(existingState)
+      ? existing
+      : null;
+  const replayed = attachment !== null;
+  if (!attachment) {
+    const declined = await reviewed(runtime, {
+      title: "Import external bucket",
+      terms: [
+        { label: "Source", value: `${providerName(bucket.kind)} ${bucket.location.bucket}` },
+        { label: "Working volume", value: `${bucket.name} (${bucket.id})` },
+        { label: "Reservation", value: reservationId },
+        { label: "Isolation", value: "one Ornn-managed working copy" },
+        { label: "Source writeback", value: "disabled" },
+      ],
+      prompt: "Create this managed working copy?",
+    });
+    if (declined) return declined;
+    try {
+      const payload = await runtime.fetch(
+        computeEndpoint(
+          `/nodes/reservations/${encodeURIComponent(reservationId)}/storage-deployment`
+        ),
+        {
+          body: {
+            drive_id: bucket.id,
+            mount_path: "/home/tenant/volume",
+            mount_mode: "fuse",
+            access_mode: "read-write",
+          },
+          headers: idempotencyHeaders(input),
+          method: "POST",
+          signal: runtime.signal,
+        }
+      );
+      attachment = attachmentFrom(payload);
+      if (!attachment || String(attachment.drive_id ?? "") !== bucket.id) {
+        attachment = await fetchImportAttachment(runtime, reservationId).catch(() => null);
+      }
+    } catch (error) {
+      attachment = await fetchImportAttachment(runtime, reservationId).catch(() => null);
+      if (!attachment || String(attachment.drive_id ?? "") !== bucket.id) {
+        const data = importData(bucket, reservationId, {
+          drive_id: bucket.id,
+          state: "pre_positioning",
+          placement: { transfer: { state: "queued" } },
+        });
+        const recovery = resumeImport(bucket.id, reservationId, bucket.kind);
+        return runtime.interaction.result({
+          ...recovery,
+          data,
+          errors: [
+            {
+              code: "external_bucket_import_acceptance_unknown",
+              message:
+                "Import acceptance could not be confirmed. Re-run the exact command to reconcile it.",
+              retryable: true,
+            },
+          ],
+          exitCode: 4,
+          outcome: { class: "partial", phase: "acceptance_unknown" },
+          presentation: {
+            lines: [
+              `Managed working-volume reference preserved: ${bucket.name} (${bucket.id})`,
+              "Source writeback remains disabled.",
+            ],
+            next: recovery.action.command,
+          },
+        });
+      }
+    }
+  }
+
+  const data = importData(bucket, reservationId, attachment);
+  if (!wait) {
+    const terminal = terminalImportExecution(runtime, bucket, reservationId, attachment, []);
+    if (terminal) return terminal;
+    return runtime.interaction.result({
+      data: { ...data, replayed },
+      outcome: { class: "working", phase: replayed ? "replayed" : "accepted" },
+      presentation: {
+        lines: [
+          `Managed import ${replayed ? "replayed" : "accepted"}: ${bucket.name} (${bucket.id})`,
+          "Source writeback is disabled; later volume changes stay only in the managed copy.",
+        ],
+        next: `ornn external-buckets import ${bucket.kind} ${bucket.id} --reservation ${reservationId} --wait --timeout 30m`,
+      },
+      resume: { kind: "managed_volume", ref: bucket.id },
+    });
+  }
+  return waitForImport(runtime, bucket, reservationId, attachment, timeoutMs);
+}
+
+export async function executeExternalBucketCommand(command, input, runtime) {
+  const adapter = {
+    ...runtime,
+    signal: runtime.signal,
+    sleep:
+      runtime.sleep ??
+      ((milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds))),
+    stderr: runtime.stderr ?? process.stderr,
+  };
+  if (command === "storage.external-buckets.list") return listBuckets(input, adapter);
+  if (command === "storage.external-buckets.show") return showBucket(input, adapter);
+  if (command === "storage.external-buckets.connect") return connectBucket(input, adapter);
+  if (command === "storage.external-buckets.update-credentials") {
+    return updateCredentials(input, adapter);
+  }
+  if (command === "storage.external-buckets.verify") return verifyBucket(input, adapter);
+  if (command === "storage.external-buckets.import") return importBucket(input, adapter);
+  if (command === "storage.external-buckets.disconnect") return disconnectBucket(input, adapter);
+  throw new StorageCommandError("Unsupported external bucket command.", {
+    code: "unsupported_capability",
+    exitCode: 2,
+  });
+}
+
+export function writeExternalBucketResultHuman(stdout, stderr, capabilityId, execution) {
+  const data = execution.data;
+  if (capabilityId === "storage.external-buckets.list") {
+    const rows = data?.external_buckets ?? [];
+    if (!rows.length) {
+      stdout.write("No external buckets connected.\n");
+      return;
+    }
+    for (const bucket of rows) {
+      stdout.write(
+        `${bucket.name}  ${bucket.kind}  ${bucket.verification.phase}  ${bucket.access.mode}  ${bucket.id}\n`
+      );
+    }
+    if (execution.page?.next_cursor) {
+      stdout.write(`Next cursor: ${execution.page.next_cursor}\n`);
+    }
+    return;
+  }
+  if (execution.presentation?.lines) {
+    for (const line of execution.presentation.lines) stdout.write(`${line}\n`);
+    if (execution.presentation.next) stdout.write(`Next: ${execution.presentation.next}\n`);
+  } else if (data?.external_bucket) {
+    const bucket = data.external_bucket;
+    stdout.write(`${bucket.name} (${bucket.id})\n`);
+    stdout.write(`Kind: ${providerName(bucket.kind)}\n`);
+    stdout.write(`Bucket: ${bucket.location.bucket}\n`);
+    if (bucket.location.prefix) stdout.write(`Prefix: ${bucket.location.prefix}\n`);
+    stdout.write(`Access: ${bucket.access.mode}\n`);
+    stdout.write(`Verification: ${bucket.verification.phase}\n`);
+  }
+  for (const error of execution.errors ?? []) stderr.write(`${error.message}\n`);
+}