agentlas 0.9.10 → 1.0.1

package/engine/cloud/hub-client.cjs

@@ -0,0 +1,239 @@
+"use strict";
+/*
+ * cloud/hub-client — Agentlas Hub/Cloud HTTP 클라이언트 (v1에서 검증된 강화판 이식).
+ *
+ * 강화 계약(절대 약화 금지 — v1 timeout-regression이 지키던 속성):
+ *  - connect/idle/total 3중 타임아웃 (AGENTLAS_HUB_*_TIMEOUT_MS로 조정)
+ *  - 응답 크기 상한 16MB (HUB_RESPONSE_MAX_BYTES)
+ *  - 업스트림 AbortSignal 전파
+ * 세션 쿠키 해석 순서: AGENTLAS_SESSION env → auth/cli-session.v1.json → (레거시) keytar.
+ */
+const fs = require("node:fs");
+const path = require("node:path");
+const { userDataDir } = require("../core/paths.cjs");
+
+const HUB_RESPONSE_MAX_BYTES = 16 * 1024 * 1024;
+const HUB_TIMEOUT_DEFAULTS = Object.freeze({ connectMs: 15_000, idleMs: 30_000, totalMs: 180_000 });
+
+function mcpBaseUrl() {
+  return (process.env.AGENTLAS_MCP_BASE_URL || "https://agentlas.cloud/api/mcp/v1").replace(/\/$/, "");
+}
+
+function webBaseUrl() {
+  return (process.env.AGENTLAS_WEB_BASE_URL || "https://agentlas.cloud").replace(/\/$/, "");
+}
+
+function finiteTimeoutMs(value, fallback, min, max) {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed)) return fallback;
+  return Math.min(max, Math.max(min, Math.trunc(parsed)));
+}
+
+function hubTimeoutConfig(env = process.env) {
+  const totalMs = finiteTimeoutMs(env.AGENTLAS_HUB_TOTAL_TIMEOUT_MS, HUB_TIMEOUT_DEFAULTS.totalMs, 5_000, 900_000);
+  return {
+    connectMs: Math.min(totalMs, finiteTimeoutMs(env.AGENTLAS_HUB_CONNECT_TIMEOUT_MS, HUB_TIMEOUT_DEFAULTS.connectMs, 1_000, 120_000)),
+    idleMs: Math.min(totalMs, finiteTimeoutMs(env.AGENTLAS_HUB_IDLE_TIMEOUT_MS, HUB_TIMEOUT_DEFAULTS.idleMs, 1_000, 300_000)),
+    totalMs,
+  };
+}
+
+function directHubTimeoutConfig(value = {}) {
+  const totalMs = finiteTimeoutMs(value.totalMs, HUB_TIMEOUT_DEFAULTS.totalMs, 10, 900_000);
+  return {
+    connectMs: Math.min(totalMs, finiteTimeoutMs(value.connectMs, HUB_TIMEOUT_DEFAULTS.connectMs, 10, 120_000)),
+    idleMs: Math.min(totalMs, finiteTimeoutMs(value.idleMs, HUB_TIMEOUT_DEFAULTS.idleMs, 10, 300_000)),
+    totalMs,
+  };
+}
+
+function hubTimeoutError(kind, ms) {
+  const message = kind === "connect"
+    ? `Hub 연결 제한 시간(${ms}ms)을 초과했습니다.`
+    : kind === "idle"
+      ? `Hub 응답이 ${ms}ms 동안 멈췄습니다.`
+      : `Hub 요청 전체 제한 시간(${ms}ms)을 초과했습니다.`;
+  const error = new Error(message);
+  error.code = `AGENTLAS_HUB_${kind.toUpperCase()}_TIMEOUT`;
+  return error;
+}
+
+/** Hub/Cloud fetch + body reader. Headers 전 connect, chunk 사이 idle, 전 구간 total timeout. */
+async function fetchHub(url, init = {}, options = {}) {
+  const fetchImpl = options.fetch || globalThis.fetch;
+  if (typeof fetchImpl !== "function") throw new Error("fetch is unavailable in this runtime.");
+  const timeout = options.timeoutConfig ? directHubTimeoutConfig(options.timeoutConfig) : hubTimeoutConfig(options.env || process.env);
+  const controller = new AbortController();
+  const upstreamSignal = init.signal;
+  let connectTimer = null;
+  let idleTimer = null;
+  let totalTimer = null;
+  let reader = null;
+  let terminalError = null;
+  let rejectTerminal;
+  const terminal = new Promise((_, reject) => { rejectTerminal = reject; });
+  const stop = (error) => {
+    if (terminalError) return;
+    terminalError = error;
+    try { controller.abort(error); } catch { controller.abort(); }
+    rejectTerminal(error);
+  };
+  const onUpstreamAbort = () => {
+    const reason = upstreamSignal && upstreamSignal.reason;
+    const error = reason instanceof Error ? reason : new Error("Hub 요청이 취소되었습니다.");
+    if (!error.code) error.code = "ABORT_ERR";
+    stop(error);
+  };
+  const armIdle = () => {
+    if (idleTimer) clearTimeout(idleTimer);
+    idleTimer = setTimeout(() => stop(hubTimeoutError("idle", timeout.idleMs)), timeout.idleMs);
+  };
+
+  if (upstreamSignal) {
+    if (upstreamSignal.aborted) onUpstreamAbort();
+    else upstreamSignal.addEventListener("abort", onUpstreamAbort, { once: true });
+  }
+  connectTimer = setTimeout(() => stop(hubTimeoutError("connect", timeout.connectMs)), timeout.connectMs);
+  totalTimer = setTimeout(() => stop(hubTimeoutError("total", timeout.totalMs)), timeout.totalMs);
+
+  try {
+    const response = await Promise.race([
+      Promise.resolve().then(() => fetchImpl(url, { ...init, signal: controller.signal })),
+      terminal,
+    ]);
+    if (connectTimer) clearTimeout(connectTimer);
+    connectTimer = null;
+    const chunks = [];
+    let bytes = 0;
+    armIdle();
+    if (response.body && typeof response.body.getReader === "function") {
+      reader = response.body.getReader();
+      while (true) {
+        const part = await Promise.race([reader.read(), terminal]);
+        if (part.done) break;
+        armIdle();
+        const chunk = Buffer.from(part.value || []);
+        bytes += chunk.length;
+        if (bytes > HUB_RESPONSE_MAX_BYTES) {
+          const error = new Error(`Hub 응답이 허용 크기(${HUB_RESPONSE_MAX_BYTES} bytes)를 초과했습니다.`);
+          error.code = "AGENTLAS_HUB_RESPONSE_TOO_LARGE";
+          stop(error);
+          throw error;
+        }
+        chunks.push(chunk);
+      }
+    } else {
+      const raw = Buffer.from(await Promise.race([response.arrayBuffer(), terminal]));
+      bytes = raw.length;
+      if (bytes > HUB_RESPONSE_MAX_BYTES) throw new Error(`Hub response exceeds the allowed size (${HUB_RESPONSE_MAX_BYTES} bytes).`);
+      chunks.push(raw);
+    }
+    if (idleTimer) clearTimeout(idleTimer);
+    idleTimer = null;
+    const text = Buffer.concat(chunks, bytes).toString("utf8");
+    return { ok: response.ok, status: response.status, headers: response.headers, text };
+  } catch (error) {
+    if (terminalError) throw terminalError;
+    throw error;
+  } finally {
+    if (connectTimer) clearTimeout(connectTimer);
+    if (idleTimer) clearTimeout(idleTimer);
+    if (totalTimer) clearTimeout(totalTimer);
+    if (upstreamSignal) upstreamSignal.removeEventListener?.("abort", onUpstreamAbort);
+    if (reader && terminalError) {
+      try { await reader.cancel(terminalError); } catch { /* ignore */ }
+    }
+  }
+}
+
+function parseHubJson(response, label) {
+  try {
+    return JSON.parse(response.text || "null");
+  } catch {
+    throw new Error(`${label} returned invalid JSON.`);
+  }
+}
+
+// ── 세션 쿠키 ──
+function cliSessionPath() {
+  return path.join(userDataDir(), "auth", "cli-session.v1.json");
+}
+
+function readCliSessionValue() {
+  try {
+    const j = JSON.parse(fs.readFileSync(cliSessionPath(), "utf8"));
+    return (j && typeof j.value === "string" && j.value) || null;
+  } catch {
+    return null;
+  }
+}
+
+function readKeytar() {
+  try {
+    return require("keytar");
+  } catch {
+    return null;
+  }
+}
+
+async function cloudSessionCookie() {
+  if (process.env.AGENTLAS_SESSION) return `agentlas_session=${process.env.AGENTLAS_SESSION}`;
+  const fileValue = readCliSessionValue();
+  if (fileValue) return `agentlas_session=${fileValue}`;
+  const keytar = readKeytar();
+  if (!keytar) return null;
+  try {
+    const value = await keytar.getPassword("Agentlas Session", "default");
+    return value ? `agentlas_session=${value}` : null;
+  } catch {
+    return null;
+  }
+}
+
+class HubError extends Error {
+  constructor(message, { code, status } = {}) {
+    super(message);
+    if (code) this.code = code;
+    if (status) this.status = status;
+  }
+}
+
+/**
+ * Hub MCP tool 호출 (POST <mcp base>/tools/call).
+ * 서버가 exact refusal(insufficient_credits 등)을 주면 그 문구를 그대로 전달한다 —
+ * 로컬 대체 실행으로 위장하지 않는다(오너 결정).
+ */
+async function callHubTool(name, args, { requireSession = false, fetch: fetchImpl, timeoutConfig } = {}) {
+  const headers = { "content-type": "application/json" };
+  const cookie = await cloudSessionCookie();
+  if (requireSession && !cookie) {
+    throw new HubError("Agent Cloud sign-in is required. Run `agentlas login` first.", { code: "not_signed_in" });
+  }
+  if (cookie) headers.cookie = cookie;
+  const resp = await fetchHub(`${mcpBaseUrl()}/tools/call`, {
+    method: "POST",
+    headers,
+    body: JSON.stringify({ method: name, params: { name, arguments: args || {} } }),
+  }, { fetch: fetchImpl, timeoutConfig });
+  if (!resp.ok) throw new HubError(`${name} failed with HTTP ${resp.status}`, { status: resp.status });
+  const json = parseHubJson(resp, name);
+  if (json.error) throw new HubError(`${name}: ${json.error.message || "unknown error"}`, { code: json.error.code });
+  return json.result || null;
+}
+
+module.exports = {
+  HUB_RESPONSE_MAX_BYTES,
+  HUB_TIMEOUT_DEFAULTS,
+  mcpBaseUrl,
+  webBaseUrl,
+  hubTimeoutConfig,
+  directHubTimeoutConfig,
+  hubTimeoutError,
+  fetchHub,
+  parseHubJson,
+  cliSessionPath,
+  readCliSessionValue,
+  cloudSessionCookie,
+  callHubTool,
+  HubError,
+};

package/engine/cloud-assets/cargo.cjs

@@ -0,0 +1,49 @@
+"use strict";
+/*
+ * cloud-assets/cargo — Agent Cloud(cargo.*) MCP tool 얇은 래퍼.
+ *
+ * cargo.*는 소유자 세션이 필요한 유일한 도구군이다(마켓 검색과 달리).
+ * 여기서는 어떤 폴백/로컬 위장도 하지 않는다 — 서버 거절(insufficient_credits,
+ * agent_not_found 등)은 그대로 중계한다.
+ */
+const { callHubTool } = require("../cloud/hub-client.cjs");
+
+function ownerCall(name, args) {
+  return callHubTool(name, args, { requireSession: true });
+}
+
+/** 소유 자산 검색 (q="" = 전체 나열). */
+function cargoSearchAgents(args = {}) {
+  return ownerCall("cargo.search_agents", args);
+}
+
+/** 소유 자산 나열 — 서버에 별도 list 도구가 없으면 빈 질의 검색과 동치다. */
+function cargoListAgents(limit = 100) {
+  const safeLimit = Math.max(1, Math.min(100, Number.isFinite(limit) ? Math.floor(limit) : 100));
+  return ownerCall("cargo.search_agents", { q: "", limit: safeLimit });
+}
+
+function cargoGetManifest(slug) {
+  return ownerCall("cargo.get_manifest", { slug });
+}
+
+function cargoRestorePackage(slug) {
+  return ownerCall("cargo.restore_package", { slug });
+}
+
+function cargoSaveCombination(payload) {
+  return ownerCall("cargo.save_combination", payload || {});
+}
+
+function cargoDeleteAgent(slug) {
+  return ownerCall("cargo.delete_agent", { slug });
+}
+
+module.exports = {
+  cargoSearchAgents,
+  cargoListAgents,
+  cargoGetManifest,
+  cargoRestorePackage,
+  cargoSaveCombination,
+  cargoDeleteAgent,
+};

package/engine/cloud-assets/cas.cjs

@@ -0,0 +1,235 @@
+"use strict";
+/*
+ * cloud-assets/cas — Agent Cloud 조건부(Compare-And-Swap) 등록/삭제 클라이언트.
+ *
+ * 멀티 호스트 계약 (약화 금지 — v1 cloud-cas-client가 지키던 속성):
+ *  - 새 자산 생성은 If-None-Match: "*" — 다른 PC가 먼저 만든 자산을 절대 덮지 않는다.
+ *  - 갱신/삭제는 관측한 베이스 리비전의 If-Match + x-agentlas-cloud-id 를 함께 보낸다.
+ *    관측한 베이스가 없으면 갱신을 시도조차 하지 않는다 (조용한 덮어쓰기 금지).
+ *  - 412(cloud_agent_revision_conflict)는 "다른 PC가 먼저 변경"의 정직한 신호:
+ *    서버 리비전을 자동 채택하지 않고 restore→병합을 안내한다.
+ *  - 503 + cloud_mutations_maintenance(WRITE_MODE blocked)는 fail-closed 거절.
+ *    서버가 그 코드를 줄 때만 maintenance 문구를 쓴다 — 일반 503을 "점검"으로
+ *    추측 번역하지 않고 서버 error 본문을 그대로 전달한다.
+ *  - 2xx라도 영수증(schema/operation/scope/hash/revision/ETag/no-store)이 전부
+ *    맞아야 성공이다. 어긋나면 합성 성공으로 승격하지 않는다.
+ */
+const fs = require("node:fs");
+const crypto = require("node:crypto");
+const { fetchHub, parseHubJson, cloudSessionCookie, webBaseUrl } = require("../cloud/hub-client.cjs");
+const { cloudRevisionEtag, normalizeCloudAssetDescriptor } = require("../hub/install.cjs");
+const state = require("./state.cjs");
+
+function cloudScopeForVisibility(visibility) {
+  return visibility === "marketplace" ? "hub-public" : "owner-private";
+}
+
+/**
+ * 같은 논리 변이의 재시도는 같은 키를 공유하도록 결정론적으로 만든다.
+ * (scope/slug/패키지 정체성/베이스 리비전이 같으면 같은 요청이다 —
+ *  네트워크 재시도가 서버에서 이중 커밋되는 것을 막는 멱등성 힌트.)
+ */
+function cloudIdempotencyKey(kind, scope, slug, packageHash, packageHashVersion, baseRevision) {
+  return crypto.createHash("sha256")
+    .update(`agentlas-cloud-${kind}:${scope}:${slug}:${packageHash}:${packageHashVersion}:${baseRevision || "*"}`)
+    .digest("hex");
+}
+
+function cloudCasResponseError(response, label) {
+  let body = null;
+  try { body = JSON.parse(response.text || "null"); } catch { /* generic below */ }
+  const code = body && typeof body.code === "string" ? body.code : "cloud_request_failed";
+  let message = `${label} failed with HTTP ${response.status}`;
+  if (response.status === 412 && code === "cloud_agent_revision_conflict") {
+    const current = body && body.current ? body.current : body && body.conflict && body.conflict.current;
+    message = current
+      ? `다른 PC에서 이 Agent Cloud 자산이 변경되었습니다. 자동 덮어쓰기는 중단했습니다. \`agentlas cloud list\`로 최신 revision을 확인하고 \`agentlas cloud restore ${current.slug || "<slug>"}\`로 복원한 뒤 변경 사항을 병합하세요.`
+      : "이 Agent Cloud 자산은 다른 PC에서 삭제되었거나 다른 식별자로 다시 생성되었습니다. 자동 재생성은 중단했습니다. `agentlas cloud list`로 현재 상태를 확인하세요.";
+  } else if (response.status === 428 && code === "client_upgrade_required") {
+    message = "No base revision is available to safely update the existing Cloud asset. The server revision will not be copied automatically. Check `agentlas cloud list`, restore with `agentlas cloud restore <slug>`, then save again.";
+  } else if (response.status === 503 && code === "cloud_mutations_maintenance") {
+    const retryAfter = response.headers && typeof response.headers.get === "function" ? response.headers.get("retry-after") : null;
+    message = `Agent Cloud save/delete is temporarily under maintenance${retryAfter ? ` (retry in about ${retryAfter} seconds)` : ""}. Read, list, and restore remain available.`;
+  } else if (body && typeof body.error === "string") {
+    // WRITE_MODE=blocked 등 서버의 fail-closed 거절 — 문구를 그대로 중계한다.
+    message = `${label} failed with HTTP ${response.status}: ${body.error.slice(0, 300)}`;
+  }
+  const error = new Error(message);
+  error.code = code;
+  error.status = response.status;
+  if (body && body.current) error.current = body.current;
+  if (body && body.conflict) error.conflict = body.conflict;
+  return error;
+}
+
+/** 등록(생성/갱신). 성공 시 검증된 리비전 디스크립터(+operation/url)를 반환한다. */
+async function registerCloudAgent(manifest, bundlePath, review, visibility, options = {}) {
+  const cookie = await cloudSessionCookie();
+  if (!cookie) throw new Error("Agent Cloud sign-in is required. Sign in through Desktop or set AGENTLAS_SESSION.");
+  if (typeof fetch !== "function") throw new Error("fetch is unavailable in this runtime (run through the app runtime).");
+  const base = webBaseUrl();
+  const bundle = JSON.parse(fs.readFileSync(bundlePath, "utf8"));
+  const expectedScope = cloudScopeForVisibility(visibility);
+  const baseDescriptor = options.baseDescriptor
+    ? normalizeCloudAssetDescriptor(options.baseDescriptor, "base revision")
+    : null;
+  if (baseDescriptor && (baseDescriptor.slug !== manifest.slug || baseDescriptor.scope !== expectedScope)) {
+    throw new Error("Agent Cloud base revision does not match the requested slug/scope.");
+  }
+  const headers = {
+    "content-type": "application/json",
+    cookie,
+    origin: base,
+    "idempotency-key": cloudIdempotencyKey(
+      "register", expectedScope, manifest.slug, manifest.packageHash, manifest.packageHashVersion,
+      baseDescriptor && baseDescriptor.revision,
+    ),
+  };
+  if (baseDescriptor) {
+    headers["if-match"] = baseDescriptor.etag;
+    headers["x-agentlas-cloud-id"] = baseDescriptor.cloudId;
+  } else {
+    headers["if-none-match"] = "*";
+  }
+  const resp = await fetchHub(`${base}/api/cloud-agents/v1/register`, {
+    method: "POST",
+    headers,
+    body: JSON.stringify({ manifest, bundle, review, visibility, billing: { modelCallsPaidBy: review.costOwner, localRuntime: review.runtimeLabel || null } }),
+  });
+  if (!resp.ok) throw cloudCasResponseError(resp, "Agentlas Cloud 등록");
+  const json = parseHubJson(resp, "Agentlas Cloud 등록");
+  const expectedSource = visibility === "marketplace" ? "hub" : "agent-cloud";
+  const expectedVisibility = visibility === "marketplace" ? "marketplace" : "owner-private";
+  const etag = resp.headers && typeof resp.headers.get === "function" ? resp.headers.get("etag") : null;
+  const cacheControl = resp.headers && typeof resp.headers.get === "function" ? resp.headers.get("cache-control") : null;
+  const expectedOperations = baseDescriptor ? new Set(["updated", "unchanged"]) : new Set(["created"]);
+  if (
+    json.schema !== "agentlas.agent_cloud.registration.v1" ||
+    !expectedOperations.has(json.operation) ||
+    json.source !== expectedSource ||
+    json.visibility !== expectedVisibility ||
+    json.scope !== expectedScope ||
+    json.owner !== true ||
+    json.publicHubPublished !== (visibility === "marketplace") ||
+    json.dryRun !== false ||
+    typeof json.cloudId !== "string" || !json.cloudId.trim() ||
+    json.slug !== manifest.slug ||
+    json.packageHash !== manifest.packageHash ||
+    json.packageHashVersion !== manifest.packageHashVersion ||
+    typeof json.revision !== "string" || etag !== cloudRevisionEtag(json.revision) ||
+    typeof json.registeredAt !== "string" || !Number.isFinite(Date.parse(json.registeredAt)) ||
+    !String(cacheControl || "").toLowerCase().includes("no-store") ||
+    (baseDescriptor && json.cloudId !== baseDescriptor.cloudId)
+  ) {
+    throw new Error("Agentlas Cloud register returned an invalid or mismatched registration receipt.");
+  }
+  const descriptor = normalizeCloudAssetDescriptor({
+    cloudId: json.cloudId,
+    slug: json.slug,
+    scope: json.scope,
+    packageHash: json.packageHash,
+    packageHashVersion: json.packageHashVersion,
+    revision: json.revision,
+    etag,
+    updatedAt: json.savedAt || json.registeredAt,
+  }, "registration receipt");
+  return {
+    ...descriptor,
+    operation: json.operation,
+    ...(typeof json.url === "string" ? { url: json.url } : {}),
+    ...(typeof json.marketplaceUrl === "string" ? { marketplaceUrl: json.marketplaceUrl } : {}),
+    registeredAt: json.registeredAt,
+    dryRun: false,
+  };
+}
+
+/** 관측한 정확한 리비전 하나만 조건부 삭제. 성공 시 상태 저널/마커에서 베이스를 걷어낸다. */
+async function deleteCloudAgent(slug, options = {}) {
+  // cloudSlug()의 "agentlas-cloud-agent" 폴백을 쓰면 빈 인자가 실존 슬러그로 위장된다 — 인라인 정규화 유지(v1 동일).
+  const safeSlug = String(slug || "").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 64);
+  if (!safeSlug) throw new Error("usage: agentlas cloud delete <slug> [--json]");
+  const cookie = await cloudSessionCookie();
+  if (!cookie) throw new Error("Agent Cloud sign-in is required. Sign in through Desktop or set AGENTLAS_SESSION.");
+  if (typeof fetch !== "function") throw new Error("fetch is unavailable in this runtime (run through the app runtime).");
+  const scope = options.scope == null ? null : state.normalizeCloudScopeFlag(options.scope);
+  if (options.scope != null && !scope) throw new Error("--scope must be owner-private or hub-public");
+  const localEntry = state.findCloudAssetDescriptor(safeSlug, scope);
+  if (!localEntry) {
+    // 베이스 리비전을 관측한 적 없으면 삭제하지 않는다 — 다른 PC의 자산 오폭 방지.
+    throw new Error(`No observed base revision for ${safeSlug}${scope ? ` (${scope})` : ""}. Run \`agentlas cloud list\` first, then retry the exact asset deletion.`);
+  }
+  const descriptor = localEntry.descriptor;
+  const base = webBaseUrl();
+  const query = new URLSearchParams({ slug: safeSlug, scope: descriptor.scope, cloudId: descriptor.cloudId });
+  const resp = await fetchHub(`${base}/api/cloud-agents/v1/register?${query.toString()}`, {
+    method: "DELETE",
+    headers: {
+      "content-type": "application/json",
+      cookie,
+      origin: base,
+      "if-match": descriptor.etag,
+      "x-agentlas-cloud-id": descriptor.cloudId,
+      "idempotency-key": cloudIdempotencyKey(
+        "delete", descriptor.scope, descriptor.slug, descriptor.packageHash, descriptor.packageHashVersion, descriptor.revision,
+      ),
+    },
+  });
+  if (!resp.ok) throw cloudCasResponseError(resp, "Agentlas Cloud 삭제");
+  const json = parseHubJson(resp, "Agentlas Cloud 삭제");
+  const responseEtag = resp.headers && typeof resp.headers.get === "function" ? resp.headers.get("etag") : null;
+  const cacheControl = resp.headers && typeof resp.headers.get === "function" ? resp.headers.get("cache-control") : null;
+  const expectedSource = descriptor.scope === "hub-public" ? "hub" : "agent-cloud";
+  const expectedVisibility = descriptor.scope === "hub-public" ? "marketplace" : "owner-private";
+  const deletionTimestamp = descriptor.scope === "hub-public" ? json.unpublishedAt : json.deletedAt;
+  if (
+    json.schema !== "agentlas.agent_cloud.delete.v1" || json.ok !== true ||
+    json.source !== expectedSource || json.visibility !== expectedVisibility ||
+    json.scope !== descriptor.scope || json.cloudId !== descriptor.cloudId || json.slug !== descriptor.slug ||
+    json.packageHash !== descriptor.packageHash || json.packageHashVersion !== descriptor.packageHashVersion ||
+    json.revision !== descriptor.revision ||
+    responseEtag !== descriptor.etag || !String(cacheControl || "").toLowerCase().includes("no-store") ||
+    (descriptor.scope === "hub-public" && json.operation !== "unpublished") ||
+    typeof deletionTimestamp !== "string" || !Number.isFinite(Date.parse(deletionTimestamp))
+  ) {
+    throw new Error("Agentlas Cloud delete returned an invalid or mismatched deletion receipt.");
+  }
+  const stateValue = state.readCloudAssetState();
+  const key = state.cloudDescriptorKey(descriptor);
+  const roots = stateValue.assets[key]?.sourceRoots || [];
+  const warnings = [];
+  for (const rootPath of roots) {
+    // 톰스톤: 삭제된 베이스는 재저장 시 절대 If-Match 베이스로 재사용되지 않는다.
+    stateValue.deletedBases.push({ rootPath, slug: descriptor.slug, scope: descriptor.scope, cloudId: descriptor.cloudId, revision: descriptor.revision });
+  }
+  delete stateValue.assets[key];
+  stateValue.deletedBases = stateValue.deletedBases.slice(-256);
+  try {
+    state.writeCloudAssetState(stateValue);
+  } catch (error) {
+    const stateError = new Error(
+      `Cloud delete committed on the server, but this machine could not persist the deletion tombstone. ` +
+      "Run `agentlas cloud list` before saving this slug again. " +
+      `Local state error: ${error.message || error}`,
+    );
+    stateError.code = "AGENTLAS_CLOUD_LOCAL_STATE_COMMIT_FAILED";
+    stateError.receipt = json;
+    throw stateError;
+  }
+  for (const rootPath of roots) {
+    try {
+      const marker = state.readCloudSourceMarker(rootPath);
+      if (marker) state.writeCloudSourceMarker(rootPath, null, null, { previousMarker: marker, removeDescriptor: descriptor });
+    } catch (error) {
+      warnings.push(`Could not clear ${rootPath}: ${error.message || error}`);
+    }
+  }
+  return { ...json, ...(warnings.length ? { localStateWarnings: warnings } : {}) };
+}
+
+module.exports = {
+  cloudScopeForVisibility,
+  cloudIdempotencyKey,
+  cloudCasResponseError,
+  registerCloudAgent,
+  deleteCloudAgent,
+};