@topolo/cli 0.7.3 → 0.7.4

package/dist/index.js

@@ -9,7 +9,7 @@ import { platform as platform2 } from "os";
 import { createInterface } from "readline/promises";
 import { stdin as input } from "process";
 
-// ../topolo-sdk/dist/index.js
+// ../../../development-workflow-acceleration/node_modules/.pnpm/@topolo+sdk@0.10.4/node_modules/@topolo/sdk/dist/index.js
 function applyAuthHeaders(headers, credential) {
   if (credential.kind === "api_key") {
     headers.set("X-Api-Key", credential.apiKey);
@@ -36,6 +36,90 @@ var TopoloSdkError = class extends Error {
     this.code = code;
   }
 };
+var PUBLIC_ERROR_CODES = /* @__PURE__ */ new Set([
+  "action_app_identity_unavailable",
+  "action_authentication_required",
+  "action_catalog_summary_unavailable",
+  "action_catalog_unavailable",
+  "action_contract_mismatch",
+  "action_permission_required",
+  "action_runtime_authorization_required",
+  "action_service_not_allowed",
+  "auth_error",
+  "authentication_required",
+  "authorization_pending",
+  "bad_sig",
+  "confirmation_required",
+  "dependency_unavailable",
+  "environment_mismatch",
+  "environment_service_url_required",
+  "expired_token",
+  "forbidden",
+  "http_error",
+  "immutable_drift",
+  "integration_dependency_unavailable",
+  "integration_misconfigured",
+  "invalid_action",
+  "invalid_action_input",
+  "invalid_grant",
+  "invalid_input",
+  "invalid_token",
+  "mcp_error",
+  "membership_required",
+  "network_error",
+  "organization_context_required",
+  "organization_enrollment_required",
+  "permission_denied",
+  "rate_limited",
+  "request_failed",
+  "service_catalog_unavailable",
+  "service_path_origin_mismatch",
+  "service_required",
+  "slow_down",
+  "state_conflict",
+  "unauthorized",
+  "unknown_action",
+  "unknown_service"
+]);
+var ERROR_CODE_PATTERN = /^[a-z][a-z0-9_]{0,63}$/;
+var TOPOLO_REQUEST_ID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+var CLOUDFLARE_RAY_ID_PATTERN = /^[0-9a-f]{16}-[A-Z]{3}$/;
+var PERMISSION_PATTERN = /^[a-z][a-z0-9_-]{0,63}(?:\.[a-z][a-z0-9_-]{0,63})*:(?:[a-z][a-z0-9_-]{0,63}|\*)$/;
+var RETRY_AFTER_DATE_PATTERN = /^(?:Mon|Tue|Wed|Thu|Fri|Sat|Sun), \d{2} (?:Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec) \d{4} \d{2}:\d{2}:\d{2} GMT$/;
+var PUBLIC_DETAIL_SOURCES = /* @__PURE__ */ new Set([
+  "api_key_introspection",
+  "api_key_validation",
+  "auth_context",
+  "auth_validate",
+  "catalog",
+  "credential",
+  "runtime",
+  "service_token_provider",
+  "service_verify_key",
+  "token_validation",
+  "upstream"
+]);
+function canonicalTopoloErrorCode(value) {
+  if (typeof value !== "string") return null;
+  const candidate = value.trim().toLowerCase();
+  if (!ERROR_CODE_PATTERN.test(candidate) || !PUBLIC_ERROR_CODES.has(candidate)) return null;
+  return candidate;
+}
+function canonicalTopoloRequestId(value) {
+  if (typeof value !== "string") return void 0;
+  const candidate = value.trim();
+  return TOPOLO_REQUEST_ID_PATTERN.test(candidate) || CLOUDFLARE_RAY_ID_PATTERN.test(candidate) ? candidate : void 0;
+}
+function canonicalTopoloRetryAfter(value) {
+  if (typeof value !== "string") return void 0;
+  const candidate = value.trim();
+  if (/^\d{1,10}$/.test(candidate) || RETRY_AFTER_DATE_PATTERN.test(candidate)) return candidate;
+  return void 0;
+}
+function canonicalTopoloRequired(value) {
+  if (!Array.isArray(value)) return [];
+  return [...new Set(value.filter((item) => typeof item === "string" && PERMISSION_PATTERN.test(item)))].slice(0, 32);
+}
 var TopoloAuthError = class extends TopoloSdkError {
   status;
   body;
@@ -43,15 +127,19 @@ var TopoloAuthError = class extends TopoloSdkError {
   path;
   requestId;
   retryAfter;
+  details;
   constructor(message, code = "auth_error", options = {}) {
-    super(code, message);
+    super(canonicalTopoloErrorCode(code) ?? "auth_error", message);
     this.name = "TopoloAuthError";
     this.status = options.status ?? 401;
     this.body = options.body;
     this.service = options.service;
     this.path = options.path;
-    this.requestId = options.requestId;
-    this.retryAfter = options.retryAfter;
+    this.requestId = canonicalTopoloRequestId(options.requestId);
+    this.retryAfter = canonicalTopoloRetryAfter(options.retryAfter);
+    this.details = extractTopoloServiceErrorDetails(
+      options.details === void 0 ? options.body : { details: options.details }
+    );
   }
 };
 var TopoloPermissionError = class extends TopoloSdkError {
@@ -62,28 +150,140 @@ var TopoloPermissionError = class extends TopoloSdkError {
   path;
   requestId;
   retryAfter;
+  details;
   constructor(message, required, options = {}) {
-    super("permission_denied", message);
+    super(
+      canonicalTopoloErrorCode(options.code) ?? serviceErrorCode(options.body, "permission_denied"),
+      message
+    );
     this.name = "TopoloPermissionError";
-    this.required = required;
+    this.required = canonicalTopoloRequired(required);
     this.status = options.status ?? 403;
     this.body = options.body;
     this.service = options.service;
     this.path = options.path;
-    this.requestId = options.requestId;
-    this.retryAfter = options.retryAfter;
+    this.requestId = canonicalTopoloRequestId(options.requestId);
+    this.retryAfter = canonicalTopoloRetryAfter(options.retryAfter);
+    this.details = extractTopoloServiceErrorDetails(
+      options.details === void 0 ? options.body : { details: options.details }
+    );
   }
 };
-function extractHttpErrorCode(body) {
-  if (!body || typeof body !== "object" || Array.isArray(body)) return "http_error";
+function extractTopoloServiceErrorCode(body) {
+  if (!body || typeof body !== "object" || Array.isArray(body)) return null;
   const record4 = body;
-  if (typeof record4.code === "string" && record4.code.trim()) return record4.code.trim();
+  const topLevel = canonicalTopoloErrorCode(record4.code);
+  if (topLevel) return topLevel;
   const nested = record4.error;
+  const nestedString = canonicalTopoloErrorCode(nested);
+  if (nestedString) return nestedString;
   if (nested && typeof nested === "object" && !Array.isArray(nested)) {
     const code = nested.code;
-    if (typeof code === "string" && code.trim()) return code.trim();
+    const nestedCode = canonicalTopoloErrorCode(code);
+    if (nestedCode) return nestedCode;
+  }
+  return null;
+}
+function serviceErrorCode(body, fallback) {
+  return extractTopoloServiceErrorCode(body) ?? fallback;
+}
+function extractTopoloServiceErrorDetails(body) {
+  if (!body || typeof body !== "object" || Array.isArray(body)) return void 0;
+  const record4 = body;
+  let candidate = record4.details;
+  const nested = record4.error;
+  if (nested && typeof nested === "object" && !Array.isArray(nested)) {
+    const nestedRecord = nested;
+    if (candidate === void 0) candidate = nestedRecord.details ?? nestedRecord;
+  }
+  if (candidate === void 0) candidate = record4;
+  if (!candidate || typeof candidate !== "object" || Array.isArray(candidate)) return void 0;
+  const source = candidate;
+  const safe = {};
+  for (const [key, value] of Object.entries(source)) {
+    if (/present$/i.test(key) && typeof value === "boolean") {
+      safe[key] = value;
+      continue;
+    }
+    if (key === "retryable" && typeof value === "boolean") {
+      safe.retryable = value;
+      continue;
+    }
+    if (key === "code") {
+      const sanitized = canonicalTopoloErrorCode(value);
+      if (sanitized) safe.code = sanitized;
+      continue;
+    }
+    if (key === "source") {
+      const sanitized = typeof value === "string" ? value.trim().toLowerCase() : "";
+      if (PUBLIC_DETAIL_SOURCES.has(sanitized)) safe.source = sanitized;
+      continue;
+    }
+    if (key === "dependency" || key === "platform") {
+      safe[`${key}Present`] = value !== null && value !== void 0;
+      continue;
+    }
+    if (key === "error" && !safe.code) {
+      const sanitized = canonicalTopoloErrorCode(value);
+      if (sanitized) safe.code = sanitized;
+      continue;
+    }
+    if (key === "required" && Array.isArray(value)) {
+      const required = canonicalTopoloRequired(value);
+      if (required.length) safe.required = required;
+      continue;
+    }
+    if (["missingFields", "fields", "paths"].includes(key) && Array.isArray(value)) {
+      const paths = value.filter((item) => typeof item === "string" && /^[$.a-z0-9_[\]-]{1,160}$/i.test(item));
+      if (paths.length) safe[key] = paths;
+    }
   }
-  return "http_error";
+  return Object.keys(safe).length ? safe : void 0;
+}
+function publicTopoloErrorMessage(error) {
+  const code = canonicalTopoloErrorCode(
+    typeof error === "string" ? error : error.code ?? extractTopoloServiceErrorCode(error.body)
+  ) ?? "request_failed";
+  if (/(?:organization|org).*(?:enroll|membership|member|admission)/.test(code)) {
+    return "Organization or application enrollment is required.";
+  }
+  if (/(?:organization|org).*(?:context|required|missing|invalid|unknown|not_found)/.test(code)) {
+    return "Organization context is unavailable.";
+  }
+  if (["auth_error", "authentication_required", "unauthorized", "invalid_token", "expired_token"].includes(code)) {
+    return "Authentication failed.";
+  }
+  if (code === "permission_denied" || code === "forbidden") return "Permission denied.";
+  if (code === "confirmation_required") return "Confirmation is required.";
+  return `Topolo request failed (${code}).`;
+}
+function topoloErrorHint(error) {
+  const code = canonicalTopoloErrorCode(
+    typeof error === "string" ? error : error.code ?? extractTopoloServiceErrorCode(error.body)
+  );
+  if (!code) return void 0;
+  if (code === "auth_error" || code === "authentication_required" || code === "unauthorized" || code === "invalid_token" || code === "expired_token") {
+    return "Run `topolo auth login`, then verify the effective Topolo identity and organization.";
+  }
+  if (code === "confirmation_required") {
+    return "Review the unchanged action plan, obtain approval, and retry once with --confirm or confirm:true.";
+  }
+  if (code === "enrollment_required" || code === "membership_required" || /(?:organization|org).*(?:enroll|membership|member|admission)|(?:enroll|membership).*(?:organization|org)/.test(code)) {
+    return "The current identity is not enrolled for this organization or application. Use an enrolled identity or ask an organization administrator to complete enrollment.";
+  }
+  if (/(?:organization|org).*(?:context|required|missing|invalid|unknown|not_found)/.test(code)) {
+    return "Select a signed-in organization context, then verify the effective identity and organization before retrying.";
+  }
+  if (code === "permission_denied" || code === "forbidden") {
+    return "The current identity or resource context is not authorized. Review the structured details and published authorization contract.";
+  }
+  if (code === "environment_mismatch") {
+    return "Use service origins and credentials from one explicit Topolo environment only.";
+  }
+  if (code === "invalid_action_input" || code === "invalid_input") {
+    return "Correct only the reported schema paths, then prepare the action again.";
+  }
+  return void 0;
 }
 var TopoloConfirmationRequiredError = class extends TopoloSdkError {
   constructor(message) {
@@ -98,17 +298,66 @@ var TopoloHttpError = class extends TopoloSdkError {
   path;
   requestId;
   retryAfter;
+  details;
   constructor(service, path9, status, body, message, options = {}) {
-    super(extractHttpErrorCode(body), message ?? `HTTP ${status} from ${service}${path9}`);
+    super(serviceErrorCode(body, "http_error"), message ?? `HTTP ${status} from ${service}${path9}`);
     this.name = "TopoloHttpError";
     this.status = status;
     this.body = body;
     this.service = service;
     this.path = path9;
-    this.requestId = options.requestId;
-    this.retryAfter = options.retryAfter;
+    this.requestId = canonicalTopoloRequestId(options.requestId);
+    this.retryAfter = canonicalTopoloRetryAfter(options.retryAfter);
+    this.details = extractTopoloServiceErrorDetails(
+      options.details === void 0 ? body : { details: options.details }
+    );
   }
 };
+function hostnameHasSuffix(hostname, suffix) {
+  return hostname === suffix || hostname.endsWith(`.${suffix}`);
+}
+function workersDevAccountMatches(hostname, account) {
+  if (!hostname.endsWith(".workers.dev")) return false;
+  const labels = hostname.slice(0, -".workers.dev".length).split(".");
+  return labels.length >= 2 && labels.at(-1) === account;
+}
+function originMatchesEnvironment(url, environment) {
+  const hostname = url.hostname.toLowerCase();
+  if (environment === "local") {
+    return hostname === "localhost" || hostname.endsWith(".localhost") || hostname === "127.0.0.1" || hostname === "[::1]";
+  }
+  if (url.protocol !== "https:") return false;
+  if (environment === "production") {
+    return hostnameHasSuffix(hostname, "topolo.app") || hostnameHasSuffix(hostname, "topolo.io") || workersDevAccountMatches(hostname, "topolo");
+  }
+  if (environment === "staging") {
+    return hostnameHasSuffix(hostname, "stg.topolo.us") || workersDevAccountMatches(hostname, "topolo-staging");
+  }
+  return hostnameHasSuffix(hostname, "topolo.dev") || workersDevAccountMatches(hostname, "topolo-development");
+}
+function assertTopoloServiceUrlEnvironment(service, value, environment) {
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new TopoloSdkError("invalid_service_url", `Invalid URL configured for Topolo service "${service}".`);
+  }
+  if (url.protocol !== "https:" && url.protocol !== "http:" || url.username || url.password || !originMatchesEnvironment(url, environment)) {
+    throw new TopoloSdkError(
+      "environment_mismatch",
+      `Refusing Topolo service "${service}": ${url.origin} does not belong to ${environment}.`
+    );
+  }
+  return url.origin;
+}
+function topoloServiceOrigins(serviceUrls, environment) {
+  return Object.fromEntries(
+    Object.entries(serviceUrls ?? {}).sort(([left], [right]) => left.localeCompare(right)).map(([service, value]) => [
+      service,
+      assertTopoloServiceUrlEnvironment(service, value, environment)
+    ])
+  );
+}
 var APP_API_URLS = {
   auth: "https://auth.topolo.app",
   developers: "https://developers.topolo.app"
@@ -2857,6 +3106,7 @@ var TopoloClient = class _TopoloClient {
   credential;
   agent;
   serviceUrls;
+  environment;
   appIds;
   requireConfirmForWrites;
   timeoutMs;
@@ -2885,7 +3135,8 @@ var TopoloClient = class _TopoloClient {
     if (!options.agent?.clientName) throw new TopoloAuthError("agent.clientName is required");
     this.credential = options.credential;
     this.agent = options.agent;
-    this.serviceUrls = options.serviceUrls;
+    this.environment = options.environment;
+    this.serviceUrls = options.environment ? topoloServiceOrigins(options.serviceUrls, options.environment) : options.serviceUrls;
     this.appIds = options.appIds;
     this.requireConfirmForWrites = options.requireConfirmForWrites !== false;
     this.timeoutMs = options.timeoutMs ?? 3e4;
@@ -2914,9 +3165,15 @@ var TopoloClient = class _TopoloClient {
       );
     }
     await this.loadCurrentCredential();
-    const resolvedService = opts.baseUrl ? { serviceKey: normalizeLookupKey(opts.service), baseUrl: requireHttpOrigin(opts.baseUrl) } : await this.resolveRequestService(opts.service);
+    const resolvedService = opts.baseUrl ? { serviceKey: normalizeLookupKey(opts.service), baseUrl: this.validatedServiceOrigin(opts.service, opts.baseUrl) } : await this.resolveRequestService(opts.service);
     const baseUrl = resolvedService.baseUrl;
     const url = new URL(opts.path, baseUrl.endsWith("/") ? baseUrl : `${baseUrl}/`);
+    if (url.origin !== new URL(baseUrl).origin) {
+      throw new TopoloSdkError(
+        "service_path_origin_mismatch",
+        `Refusing Topolo request path because it changes the resolved ${resolvedService.serviceKey || opts.service} service origin.`
+      );
+    }
     if (opts.query) {
       for (const [k, v] of Object.entries(opts.query)) {
         if (v !== void 0) url.searchParams.set(k, String(v));
@@ -2987,7 +3244,7 @@ var TopoloClient = class _TopoloClient {
         url: urlStr,
         requestId,
         durationMs: Date.now() - startedAt,
-        error: err instanceof Error ? err.message : String(err)
+        error: "network_error"
       });
       throw err;
     }
@@ -2996,6 +3253,7 @@ var TopoloClient = class _TopoloClient {
     if (!res.ok) {
       const durationMs = Date.now() - startedAt;
       const message = describeError(parsed, `HTTP ${res.status}`);
+      const publicCode = extractTopoloServiceErrorCode(parsed) ?? "http_error";
       this.emit({
         phase: "error",
         method,
@@ -3004,7 +3262,7 @@ var TopoloClient = class _TopoloClient {
         url: urlStr,
         requestId,
         durationMs,
-        error: message,
+        error: publicCode,
         status: res.status
       });
       const errorContext = {
@@ -3012,17 +3270,21 @@ var TopoloClient = class _TopoloClient {
         body: parsed,
         service: resolvedService.serviceKey,
         path: opts.path,
-        requestId: res.headers.get("X-Topolo-Request-Id") || requestId,
-        retryAfter: res.headers.get("Retry-After") || void 0
+        requestId: canonicalTopoloRequestId(res.headers.get("X-Topolo-Request-Id")) ?? requestId,
+        retryAfter: canonicalTopoloRetryAfter(res.headers.get("Retry-After"))
       };
       if (res.status === 401) {
-        throw new TopoloAuthError(describeError(parsed, "Unauthorized"), "auth_error", errorContext);
+        throw new TopoloAuthError(
+          describeError(parsed, "Unauthorized"),
+          extractTopoloServiceErrorCode(parsed) ?? "auth_error",
+          errorContext
+        );
       }
       if (res.status === 403) {
         throw new TopoloPermissionError(
           describeError(parsed, "Permission denied"),
           extractRequired(parsed),
-          errorContext
+          { ...errorContext, code: extractTopoloServiceErrorCode(parsed) ?? "permission_denied" }
         );
       }
       throw new TopoloHttpError(
@@ -3072,6 +3334,17 @@ var TopoloClient = class _TopoloClient {
     });
     return this.refreshInFlight;
   }
+  validatedServiceOrigin(service, value) {
+    const origin = requireHttpOrigin(value);
+    return this.environment ? assertTopoloServiceUrlEnvironment(service, origin, this.environment) : origin;
+  }
+  validatedActionEntry(entry) {
+    if (!entry.apiBaseUrl) return entry;
+    return {
+      ...entry,
+      apiBaseUrl: this.validatedServiceOrigin(entry.appSlug || entry.appId, entry.apiBaseUrl)
+    };
+  }
   async resolveRequestService(service) {
     const serviceKey = normalizeLookupKey(service);
     if (!serviceKey) {
@@ -3079,17 +3352,20 @@ var TopoloClient = class _TopoloClient {
     }
     if (serviceKey === "auth" || serviceKey === "developers") {
       const overrideUrl = resolveConfiguredServiceUrl(serviceKey, this.serviceUrls);
-      if (overrideUrl) return { serviceKey, baseUrl: overrideUrl };
+      if (overrideUrl) return { serviceKey, baseUrl: this.validatedServiceOrigin(serviceKey, overrideUrl) };
       if (serviceKey === "developers") {
         const derived = deriveDevelopersFromAuth(resolveConfiguredServiceUrl("auth", this.serviceUrls));
-        if (derived) return { serviceKey, baseUrl: derived };
+        if (derived) return { serviceKey, baseUrl: this.validatedServiceOrigin(serviceKey, derived) };
       }
-      return { serviceKey, baseUrl: DEFAULT_APP_URLS[serviceKey] };
+      return {
+        serviceKey,
+        baseUrl: this.validatedServiceOrigin(serviceKey, DEFAULT_APP_URLS[serviceKey])
+      };
     }
     const live = await this.resolveLiveCallableService(serviceKey);
     if (live) {
       const overrideUrl = resolveConfiguredServiceUrl(serviceKey, this.serviceUrls);
-      return overrideUrl ? { ...live, baseUrl: overrideUrl } : live;
+      return overrideUrl ? { ...live, baseUrl: this.validatedServiceOrigin(serviceKey, overrideUrl) } : { ...live, baseUrl: this.validatedServiceOrigin(serviceKey, live.baseUrl) };
     }
     throw new TopoloSdkError(
       "unknown_service",
@@ -3103,10 +3379,10 @@ var TopoloClient = class _TopoloClient {
       serviceKey,
       overrides: this.serviceUrls
     });
-    if (baseUrl) return { serviceKey, baseUrl };
+    if (baseUrl) return { serviceKey, baseUrl: this.validatedServiceOrigin(serviceKey, baseUrl) };
     const actionPage = await this.searchActions({ service: match.appId, limit: 1 }).catch(() => null);
     const actionBaseUrl = actionPage?.actions.find((action) => action.apiBaseUrl)?.apiBaseUrl ?? null;
-    return actionBaseUrl ? { serviceKey, baseUrl: requireHttpOrigin(actionBaseUrl) } : null;
+    return actionBaseUrl ? { serviceKey, baseUrl: this.validatedServiceOrigin(serviceKey, actionBaseUrl) } : null;
   }
   /**
    * Resolve a service-slug → opaque app-id via caller config or TopoloAuth.
@@ -3126,7 +3402,7 @@ var TopoloClient = class _TopoloClient {
     if (!normalized) return null;
     const configuredAppId = resolveConfiguredAppId(normalized, this.appIds);
     if (configuredAppId) return configuredAppId;
-    const authBase = resolveServiceUrl("developers", this.serviceUrls);
+    const authBase = this.validatedServiceOrigin("developers", resolveServiceUrl("developers", this.serviceUrls));
     const cacheKey = `${authBase}|${normalized}`;
     const now = Date.now();
     const cached = _TopoloClient.appIdCache.get(cacheKey);
@@ -3302,7 +3578,7 @@ var TopoloClient = class _TopoloClient {
         "TopoloAuth did not return an action catalog for the current credential."
       );
     }
-    const entries = raw.map((item) => normalizeActionCatalogEntry(item)).filter((entry) => Boolean(entry));
+    const entries = raw.map((item) => normalizeActionCatalogEntry(item)).filter((entry) => Boolean(entry)).map((entry) => this.validatedActionEntry(entry));
     return {
       actions: entries,
       page: normalizeCatalogPage(
@@ -3367,7 +3643,7 @@ var TopoloClient = class _TopoloClient {
     const raw = res.data?.action ?? res.action;
     const match = normalizeActionCatalogEntry(raw);
     if (!match) throw new TopoloSdkError("unknown_action", `Unknown or unavailable Topolo action "${action}".`);
-    return match;
+    return this.validatedActionEntry(match);
   }
   async callAction(action, input3 = {}, options = {}) {
     const entry = await this.getAction(action);
@@ -3444,6 +3720,25 @@ var TopoloClient = class _TopoloClient {
   }
   async planAction(action, input3 = {}, options = {}) {
     const entry = await this.getAction(action);
+    return this.planResolvedAction(entry, input3, options);
+  }
+  async prepareAction(action, input3, options = {}) {
+    const entry = await this.getAction(action);
+    const example = (entry.agentContract?.examples ?? []).find((candidate) => Boolean(candidate?.input) && typeof candidate.input === "object" && !Array.isArray(candidate.input) && validateTopoloActionInput(entry.inputSchema, candidate.input).valid) ?? null;
+    const selectedInput = input3 ?? example?.input ?? {};
+    const plan = this.planResolvedAction(entry, selectedInput, options);
+    return {
+      action: entry,
+      example,
+      input: selectedInput,
+      inputSource: input3 ? "provided" : example ? "example" : "empty",
+      missingFields: [...new Set(
+        plan.validation.errors.filter((issue) => issue.code === "required").map((issue) => issue.path)
+      )],
+      plan
+    };
+  }
+  planResolvedAction(entry, input3, options) {
     const validation = validateTopoloActionInput(entry.inputSchema, input3);
     const agentAccess = entry.agentAccess ?? (entry.destructive ? "off" : entry.readOnly && !entry.requiresConfirmation ? "auto" : "confirm");
     const confirmationRequired = agentAccess === "confirm" || entry.requiresConfirmation || entry.destructive;
@@ -3901,7 +4196,16 @@ function pickString(value) {
 function extractRequired(body) {
   if (body && typeof body === "object") {
     const maybe = body;
-    if (Array.isArray(maybe.required)) return maybe.required.map(String);
+    if (Array.isArray(maybe.required)) return canonicalTopoloRequired(maybe.required);
+    for (const nested of [maybe.details, maybe.error]) {
+      if (!nested || typeof nested !== "object" || Array.isArray(nested)) continue;
+      const record4 = nested;
+      if (Array.isArray(record4.required)) return canonicalTopoloRequired(record4.required);
+      if (record4.details && typeof record4.details === "object" && !Array.isArray(record4.details)) {
+        const required = record4.details.required;
+        if (Array.isArray(required)) return canonicalTopoloRequired(required);
+      }
+    }
   }
   return [];
 }
@@ -3949,6 +4253,72 @@ function compactActionPlan(plan) {
     nextActionIds: plan.nextActionIds
   };
 }
+function requiredContextText(value, field) {
+  if (typeof value !== "string" || !value.trim() || value.trim().toLowerCase() === "unknown") {
+    throw new TopoloSdkError("invalid_identity_context", `Effective Topolo ${field} is incomplete.`);
+  }
+  return value.trim();
+}
+function createTopoloAgentExecutionContext(input3) {
+  if (input3.contextKey !== null && input3.contextKey !== "personal" && !/^org:[^:]+$/.test(input3.contextKey)) {
+    throw new TopoloSdkError("invalid_identity_context", "Effective Topolo context key is invalid.");
+  }
+  const user = Object.freeze({
+    id: requiredContextText(input3.identity.user.id, "user id"),
+    email: requiredContextText(input3.identity.user.email, "user email"),
+    name: input3.identity.user.name?.trim() || null,
+    role: requiredContextText(input3.identity.user.role, "user role")
+  });
+  const organization = input3.identity.organization ? Object.freeze({
+    id: requiredContextText(input3.identity.organization.id, "organization id"),
+    slug: requiredContextText(input3.identity.organization.slug, "organization slug"),
+    name: requiredContextText(input3.identity.organization.name, "organization name")
+  }) : null;
+  if (input3.contextKey === "personal" && organization) {
+    throw new TopoloSdkError("identity_context_mismatch", "Personal Topolo context resolved an organization.");
+  }
+  if (input3.contextKey?.startsWith("org:")) {
+    const expectedOrganizationId = input3.contextKey.slice("org:".length);
+    if (!organization || organization.id !== expectedOrganizationId) {
+      throw new TopoloSdkError("identity_context_mismatch", "Pinned Topolo organization does not match the effective identity.");
+    }
+  }
+  return Object.freeze({
+    environment: input3.environment,
+    contextKey: input3.contextKey,
+    user,
+    organization,
+    serviceOrigins: Object.freeze(topoloServiceOrigins(input3.serviceUrls, input3.environment))
+  });
+}
+function compactActionPreparationCore(preparation) {
+  const example = preparation.example ? { title: preparation.example.title ?? null, input: preparation.example.input } : null;
+  const effectiveInput = preparation.inputSource === "example" ? { source: "example" } : { source: preparation.inputSource, value: preparation.input };
+  return {
+    action: {
+      id: preparation.action.actionId,
+      title: preparation.action.title,
+      docsUrl: preparation.action.agentContract?.docsUrl ?? null
+    },
+    example,
+    input: effectiveInput,
+    missingFields: preparation.missingFields,
+    valid: preparation.plan.validation.valid,
+    errors: preparation.plan.validation.errors,
+    request: preparation.plan.request,
+    confirmation: {
+      required: preparation.plan.confirmationRequired,
+      provided: preparation.plan.confirmationProvided
+    },
+    executable: preparation.plan.executable,
+    verification: preparation.plan.verification,
+    rollbackActionId: preparation.plan.rollbackActionId
+  };
+}
+function compactActionPreparation(preparation, context) {
+  const compact = compactActionPreparationCore(preparation);
+  return context ? { context, ...compact } : compact;
+}
 function compactApplicationAudit(report) {
   return {
     version: report.version,
@@ -4165,7 +4535,7 @@ function createTopolo(options) {
   };
 }
 
-// ../topolo-sdk/dist/node/credential-store.js
+// ../../../development-workflow-acceleration/node_modules/.pnpm/@topolo+sdk@0.10.4/node_modules/@topolo/sdk/dist/node/credential-store.js
 import { mkdir, readFile, writeFile, chmod } from "fs/promises";
 import { existsSync } from "fs";
 import { homedir, platform } from "os";
@@ -4178,6 +4548,90 @@ var TopoloSdkError2 = class extends Error {
     this.code = code;
   }
 };
+var PUBLIC_ERROR_CODES2 = /* @__PURE__ */ new Set([
+  "action_app_identity_unavailable",
+  "action_authentication_required",
+  "action_catalog_summary_unavailable",
+  "action_catalog_unavailable",
+  "action_contract_mismatch",
+  "action_permission_required",
+  "action_runtime_authorization_required",
+  "action_service_not_allowed",
+  "auth_error",
+  "authentication_required",
+  "authorization_pending",
+  "bad_sig",
+  "confirmation_required",
+  "dependency_unavailable",
+  "environment_mismatch",
+  "environment_service_url_required",
+  "expired_token",
+  "forbidden",
+  "http_error",
+  "immutable_drift",
+  "integration_dependency_unavailable",
+  "integration_misconfigured",
+  "invalid_action",
+  "invalid_action_input",
+  "invalid_grant",
+  "invalid_input",
+  "invalid_token",
+  "mcp_error",
+  "membership_required",
+  "network_error",
+  "organization_context_required",
+  "organization_enrollment_required",
+  "permission_denied",
+  "rate_limited",
+  "request_failed",
+  "service_catalog_unavailable",
+  "service_path_origin_mismatch",
+  "service_required",
+  "slow_down",
+  "state_conflict",
+  "unauthorized",
+  "unknown_action",
+  "unknown_service"
+]);
+var ERROR_CODE_PATTERN2 = /^[a-z][a-z0-9_]{0,63}$/;
+var TOPOLO_REQUEST_ID_PATTERN2 = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+var CLOUDFLARE_RAY_ID_PATTERN2 = /^[0-9a-f]{16}-[A-Z]{3}$/;
+var PERMISSION_PATTERN2 = /^[a-z][a-z0-9_-]{0,63}(?:\.[a-z][a-z0-9_-]{0,63})*:(?:[a-z][a-z0-9_-]{0,63}|\*)$/;
+var RETRY_AFTER_DATE_PATTERN2 = /^(?:Mon|Tue|Wed|Thu|Fri|Sat|Sun), \d{2} (?:Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec) \d{4} \d{2}:\d{2}:\d{2} GMT$/;
+var PUBLIC_DETAIL_SOURCES2 = /* @__PURE__ */ new Set([
+  "api_key_introspection",
+  "api_key_validation",
+  "auth_context",
+  "auth_validate",
+  "catalog",
+  "credential",
+  "runtime",
+  "service_token_provider",
+  "service_verify_key",
+  "token_validation",
+  "upstream"
+]);
+function canonicalTopoloErrorCode2(value) {
+  if (typeof value !== "string") return null;
+  const candidate = value.trim().toLowerCase();
+  if (!ERROR_CODE_PATTERN2.test(candidate) || !PUBLIC_ERROR_CODES2.has(candidate)) return null;
+  return candidate;
+}
+function canonicalTopoloRequestId2(value) {
+  if (typeof value !== "string") return void 0;
+  const candidate = value.trim();
+  return TOPOLO_REQUEST_ID_PATTERN2.test(candidate) || CLOUDFLARE_RAY_ID_PATTERN2.test(candidate) ? candidate : void 0;
+}
+function canonicalTopoloRetryAfter2(value) {
+  if (typeof value !== "string") return void 0;
+  const candidate = value.trim();
+  if (/^\d{1,10}$/.test(candidate) || RETRY_AFTER_DATE_PATTERN2.test(candidate)) return candidate;
+  return void 0;
+}
+function canonicalTopoloRequired2(value) {
+  if (!Array.isArray(value)) return [];
+  return [...new Set(value.filter((item) => typeof item === "string" && PERMISSION_PATTERN2.test(item)))].slice(0, 32);
+}
 var TopoloAuthError2 = class extends TopoloSdkError2 {
   status;
   body;
@@ -4185,27 +4639,91 @@ var TopoloAuthError2 = class extends TopoloSdkError2 {
   path;
   requestId;
   retryAfter;
+  details;
   constructor(message, code = "auth_error", options = {}) {
-    super(code, message);
+    super(canonicalTopoloErrorCode2(code) ?? "auth_error", message);
     this.name = "TopoloAuthError";
     this.status = options.status ?? 401;
     this.body = options.body;
     this.service = options.service;
     this.path = options.path;
-    this.requestId = options.requestId;
-    this.retryAfter = options.retryAfter;
+    this.requestId = canonicalTopoloRequestId2(options.requestId);
+    this.retryAfter = canonicalTopoloRetryAfter2(options.retryAfter);
+    this.details = extractTopoloServiceErrorDetails2(
+      options.details === void 0 ? options.body : { details: options.details }
+    );
   }
 };
-function extractHttpErrorCode2(body) {
-  if (!body || typeof body !== "object" || Array.isArray(body)) return "http_error";
+function extractTopoloServiceErrorCode2(body) {
+  if (!body || typeof body !== "object" || Array.isArray(body)) return null;
   const record4 = body;
-  if (typeof record4.code === "string" && record4.code.trim()) return record4.code.trim();
+  const topLevel = canonicalTopoloErrorCode2(record4.code);
+  if (topLevel) return topLevel;
   const nested = record4.error;
+  const nestedString = canonicalTopoloErrorCode2(nested);
+  if (nestedString) return nestedString;
   if (nested && typeof nested === "object" && !Array.isArray(nested)) {
     const code = nested.code;
-    if (typeof code === "string" && code.trim()) return code.trim();
+    const nestedCode = canonicalTopoloErrorCode2(code);
+    if (nestedCode) return nestedCode;
+  }
+  return null;
+}
+function serviceErrorCode2(body, fallback) {
+  return extractTopoloServiceErrorCode2(body) ?? fallback;
+}
+function extractTopoloServiceErrorDetails2(body) {
+  if (!body || typeof body !== "object" || Array.isArray(body)) return void 0;
+  const record4 = body;
+  let candidate = record4.details;
+  const nested = record4.error;
+  if (nested && typeof nested === "object" && !Array.isArray(nested)) {
+    const nestedRecord = nested;
+    if (candidate === void 0) candidate = nestedRecord.details ?? nestedRecord;
+  }
+  if (candidate === void 0) candidate = record4;
+  if (!candidate || typeof candidate !== "object" || Array.isArray(candidate)) return void 0;
+  const source = candidate;
+  const safe = {};
+  for (const [key, value] of Object.entries(source)) {
+    if (/present$/i.test(key) && typeof value === "boolean") {
+      safe[key] = value;
+      continue;
+    }
+    if (key === "retryable" && typeof value === "boolean") {
+      safe.retryable = value;
+      continue;
+    }
+    if (key === "code") {
+      const sanitized = canonicalTopoloErrorCode2(value);
+      if (sanitized) safe.code = sanitized;
+      continue;
+    }
+    if (key === "source") {
+      const sanitized = typeof value === "string" ? value.trim().toLowerCase() : "";
+      if (PUBLIC_DETAIL_SOURCES2.has(sanitized)) safe.source = sanitized;
+      continue;
+    }
+    if (key === "dependency" || key === "platform") {
+      safe[`${key}Present`] = value !== null && value !== void 0;
+      continue;
+    }
+    if (key === "error" && !safe.code) {
+      const sanitized = canonicalTopoloErrorCode2(value);
+      if (sanitized) safe.code = sanitized;
+      continue;
+    }
+    if (key === "required" && Array.isArray(value)) {
+      const required = canonicalTopoloRequired2(value);
+      if (required.length) safe.required = required;
+      continue;
+    }
+    if (["missingFields", "fields", "paths"].includes(key) && Array.isArray(value)) {
+      const paths = value.filter((item) => typeof item === "string" && /^[$.a-z0-9_[\]-]{1,160}$/i.test(item));
+      if (paths.length) safe[key] = paths;
+    }
   }
-  return "http_error";
+  return Object.keys(safe).length ? safe : void 0;
 }
 var TopoloHttpError2 = class extends TopoloSdkError2 {
   status;
@@ -4214,15 +4732,19 @@ var TopoloHttpError2 = class extends TopoloSdkError2 {
   path;
   requestId;
   retryAfter;
+  details;
   constructor(service, path9, status, body, message, options = {}) {
-    super(extractHttpErrorCode2(body), message ?? `HTTP ${status} from ${service}${path9}`);
+    super(serviceErrorCode2(body, "http_error"), message ?? `HTTP ${status} from ${service}${path9}`);
     this.name = "TopoloHttpError";
     this.status = status;
     this.body = body;
     this.service = service;
     this.path = path9;
-    this.requestId = options.requestId;
-    this.retryAfter = options.retryAfter;
+    this.requestId = canonicalTopoloRequestId2(options.requestId);
+    this.retryAfter = canonicalTopoloRetryAfter2(options.retryAfter);
+    this.details = extractTopoloServiceErrorDetails2(
+      options.details === void 0 ? body : { details: options.details }
+    );
   }
 };
 var APP_API_URLS2 = {
@@ -4328,11 +4850,9 @@ var TopoloOAuth2 = class {
     return parsed;
   }
 };
-function contextKey(contextType, organizationId) {
-  return contextType === "organization" && organizationId ? `org:${organizationId}` : "personal";
-}
-var ENVIRONMENT_DEFAULT_SERVICE_URLS = {
+var TOPOLO_ENVIRONMENT_SERVICE_URLS = {
   production: {
+    auth: "https://auth.topolo.app",
     developers: "https://developers.topolo.app"
   },
   staging: {
@@ -4346,6 +4866,55 @@ var ENVIRONMENT_DEFAULT_SERVICE_URLS = {
   },
   local: {}
 };
+function hostnameHasSuffix2(hostname, suffix) {
+  return hostname === suffix || hostname.endsWith(`.${suffix}`);
+}
+function workersDevAccountMatches2(hostname, account) {
+  if (!hostname.endsWith(".workers.dev")) return false;
+  const labels = hostname.slice(0, -".workers.dev".length).split(".");
+  return labels.length >= 2 && labels.at(-1) === account;
+}
+function originMatchesEnvironment2(url, environment) {
+  const hostname = url.hostname.toLowerCase();
+  if (environment === "local") {
+    return hostname === "localhost" || hostname.endsWith(".localhost") || hostname === "127.0.0.1" || hostname === "[::1]";
+  }
+  if (url.protocol !== "https:") return false;
+  if (environment === "production") {
+    return hostnameHasSuffix2(hostname, "topolo.app") || hostnameHasSuffix2(hostname, "topolo.io") || workersDevAccountMatches2(hostname, "topolo");
+  }
+  if (environment === "staging") {
+    return hostnameHasSuffix2(hostname, "stg.topolo.us") || workersDevAccountMatches2(hostname, "topolo-staging");
+  }
+  return hostnameHasSuffix2(hostname, "topolo.dev") || workersDevAccountMatches2(hostname, "topolo-development");
+}
+function assertTopoloServiceUrlEnvironment2(service, value, environment) {
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new TopoloSdkError2("invalid_service_url", `Invalid URL configured for Topolo service "${service}".`);
+  }
+  if (url.protocol !== "https:" && url.protocol !== "http:" || url.username || url.password || !originMatchesEnvironment2(url, environment)) {
+    throw new TopoloSdkError2(
+      "environment_mismatch",
+      `Refusing Topolo service "${service}": ${url.origin} does not belong to ${environment}.`
+    );
+  }
+  return url.origin;
+}
+function topoloServiceOrigins2(serviceUrls, environment) {
+  return Object.fromEntries(
+    Object.entries(serviceUrls ?? {}).sort(([left], [right]) => left.localeCompare(right)).map(([service, value]) => [
+      service,
+      assertTopoloServiceUrlEnvironment2(service, value, environment)
+    ])
+  );
+}
+function contextKey(contextType, organizationId) {
+  return contextType === "organization" && organizationId ? `org:${organizationId}` : "personal";
+}
+var ENVIRONMENT_DEFAULT_SERVICE_URLS = TOPOLO_ENVIRONMENT_SERVICE_URLS;
 function configPath() {
   const override = process.env.TOPOLO_CONFIG_PATH;
   if (override) return override;
@@ -4453,15 +5022,17 @@ function credentialSourceFromConfig(config, environment = selectedEnvironment())
   const prefix = envVarPrefix(environment);
   if (process.env[`${prefix}_API_KEY`]) return `env:${prefix}_API_KEY`;
   if (process.env[`${prefix}_ACCESS_TOKEN`]) return `env:${prefix}_ACCESS_TOKEN`;
-  if (process.env.TOPOLO_API_KEY) return "env:TOPOLO_API_KEY";
-  if (process.env.TOPOLO_ACCESS_TOKEN) return "env:TOPOLO_ACCESS_TOKEN";
+  if (environment === "production" && process.env.TOPOLO_API_KEY) return "env:TOPOLO_API_KEY";
+  if (environment === "production" && process.env.TOPOLO_ACCESS_TOKEN) {
+    return "env:TOPOLO_ACCESS_TOKEN";
+  }
   return profileForEnvironment(config, environment).credential ? "config-file" : "none";
 }
 async function resolveCredential(environment = selectedEnvironment()) {
   const prefix = envVarPrefix(environment);
-  const apiKey = process.env[`${prefix}_API_KEY`] ?? process.env.TOPOLO_API_KEY;
+  const apiKey = process.env[`${prefix}_API_KEY`] ?? (environment === "production" ? process.env.TOPOLO_API_KEY : void 0);
   if (apiKey) return { kind: "api_key", apiKey };
-  const accessToken = process.env[`${prefix}_ACCESS_TOKEN`] ?? process.env.TOPOLO_ACCESS_TOKEN;
+  const accessToken = process.env[`${prefix}_ACCESS_TOKEN`] ?? (environment === "production" ? process.env.TOPOLO_ACCESS_TOKEN : void 0);
   if (accessToken) return { kind: "access_token", accessToken };
   const config = await readConfig();
   return profileForEnvironment(config, environment).credential ?? null;
@@ -4469,7 +5040,7 @@ async function resolveCredential(environment = selectedEnvironment()) {
 var REFRESH_SKEW_SECONDS = 60;
 async function refreshCredentialIfNeeded(environment = selectedEnvironment(), options = {}) {
   const prefix = envVarPrefix(environment);
-  if (process.env[`${prefix}_API_KEY`] || process.env[`${prefix}_ACCESS_TOKEN`] || process.env.TOPOLO_API_KEY || process.env.TOPOLO_ACCESS_TOKEN) {
+  if (process.env[`${prefix}_API_KEY`] || process.env[`${prefix}_ACCESS_TOKEN`] || environment === "production" && process.env.TOPOLO_API_KEY || environment === "production" && process.env.TOPOLO_ACCESS_TOKEN) {
     return resolveCredential(environment);
   }
   const config = await readConfig();
@@ -4479,9 +5050,16 @@ async function refreshCredentialIfNeeded(environment = selectedEnvironment(), op
   if (!cred.refreshToken || !profile.oauthClientId) return cred;
   const now = Math.floor(Date.now() / 1e3);
   if (!options.force && cred.expiresAt && cred.expiresAt - REFRESH_SKEW_SECONDS > now) return cred;
+  const serviceUrls = resolveServiceUrls(profile.serviceUrls, environment);
+  if (environment === "local" && !serviceUrls?.auth) {
+    throw new TopoloSdkError2(
+      "environment_service_url_required",
+      "Local Topolo credential refresh requires an explicit local Auth service origin."
+    );
+  }
   try {
     const oauth = new TopoloOAuth2({
-      serviceUrls: resolveServiceUrls(profile.serviceUrls, environment)
+      serviceUrls
     });
     const tokens = await oauth.refreshToken({
       clientId: profile.oauthClientId,
@@ -4522,9 +5100,16 @@ async function refreshContextCredentialIfNeeded(environment, key, options = {})
   if (!credential.refreshToken || !oauthClientId) return credential;
   const now = Math.floor(Date.now() / 1e3);
   if (!options.force && credential.expiresAt && credential.expiresAt - REFRESH_SKEW_SECONDS > now) return credential;
+  const serviceUrls = resolveServiceUrls(profile.serviceUrls, environment);
+  if (environment === "local" && !serviceUrls?.auth) {
+    throw new TopoloSdkError2(
+      "environment_service_url_required",
+      "Local Topolo context refresh requires an explicit local Auth service origin."
+    );
+  }
   try {
     const oauth = new TopoloOAuth2({
-      serviceUrls: resolveServiceUrls(profile.serviceUrls, environment)
+      serviceUrls
     });
     const tokens = await oauth.refreshToken({
       clientId: oauthClientId,
@@ -4571,7 +5156,12 @@ function resolveServiceUrls(configUrls, environment = selectedEnvironment()) {
       merged[k.slice("TOPOLO_SERVICE_URL_".length).toLowerCase()] = v;
     }
   }
-  return Object.keys(merged).length > 0 ? merged : void 0;
+  const origins = topoloServiceOrigins2(merged, environment);
+  return Object.keys(origins).length > 0 ? origins : void 0;
+}
+function assertServiceUrlForEnvironment(service, serviceUrl, environment = selectedEnvironment()) {
+  if (!serviceUrl) return;
+  assertTopoloServiceUrlEnvironment2(service, serviceUrl, environment);
 }
 function resolvedProfileConfig(config, environment = selectedEnvironment()) {
   const profile = profileForEnvironment(config, environment);
@@ -4612,24 +5202,6 @@ function resolveOAuthClientId(config, environment = selectedEnvironment()) {
   if (process.env.TOPOLO_CLI_CLIENT_ID) return process.env.TOPOLO_CLI_CLIENT_ID;
   return DEFAULT_CLI_CLIENT_IDS[environment] ?? profileForEnvironment(config, environment).oauthClientId;
 }
-var NON_PROD_URL_MARKERS = {
-  staging: [".stg.topolo.us", "topolo-staging"],
-  development: [".topolo.dev", "topolo-development"]
-};
-function assertServiceUrlForEnvironment(service, serviceUrl, environment = selectedEnvironment()) {
-  const markers = NON_PROD_URL_MARKERS[environment];
-  if (!markers) return;
-  if (!serviceUrl) {
-    throw new Error(`No ${environment} URL is configured for Topolo service "${service}".`);
-  }
-  const url = serviceUrl.toLowerCase();
-  if (markers.some((marker) => url.includes(marker)) || url.includes("localhost") || url.includes("127.0.0.1")) {
-    return;
-  }
-  throw new Error(
-    `Refusing to call ${service} in ${environment} because its effective URL is not a ${environment} endpoint: ${serviceUrl}`
-  );
-}
 
 // src/output.ts
 function resolveOutputMode(override) {
@@ -4677,23 +5249,25 @@ function fail(err, mode) {
 function normalizeError(err) {
   if (err instanceof Error) {
     const code = err.code;
-    const hintMap = {
-      auth_error: "Run `topolo auth login` or set TOPOLO_API_KEY.",
-      confirmation_required: "Review the action and rerun with --confirm to allow it.",
-      permission_denied: "Check your API key scopes or role assignments in TopoloDevelopers.",
+    const fallbackHintMap = {
       immutable_drift: "Restore the manifest identity fields to the registered values; immutable ids cannot be updated."
     };
+    const body = err.body;
+    const status = err.status;
+    const suppliedDetails = err.details;
     return {
-      message: err.message,
+      message: status !== void 0 || body !== void 0 ? publicTopoloErrorMessage({ code, body, status, message: err.message }) : err.message,
       code,
-      status: err.status,
+      status,
       service: err.service,
       path: err.path,
       requestId: err.requestId,
       retryAfter: err.retryAfter,
-      details: err.body,
-      hint: code ? hintMap[code] : void 0,
-      exitCode: code === "auth_error" || code === "confirmation_required" ? 2 : code === "permission_denied" ? 3 : code === "immutable_drift" ? 4 : 1
+      details: extractTopoloServiceErrorDetails(
+        suppliedDetails === void 0 ? body : { details: suppliedDetails }
+      ),
+      hint: topoloErrorHint({ code, body }) ?? (code ? fallbackHintMap[code] : void 0),
+      exitCode: status === 401 || code === "auth_error" || code === "confirmation_required" ? 2 : status === 403 || code === "permission_denied" ? 3 : code === "immutable_drift" ? 4 : 1
     };
   }
   return { message: String(err), exitCode: 1 };
@@ -4872,7 +5446,12 @@ async function runDeviceFlow(options) {
     ...token.refresh_token ? { refreshToken: token.refresh_token } : {},
     expiresAt: Math.floor(Date.now() / 1e3) + token.expires_in
   };
-  const context = await resolveLoginContext(credential, resolved.serviceUrls, options.clientId);
+  const context = await resolveLoginContext(
+    credential,
+    resolved.serviceUrls,
+    options.clientId,
+    options.environment
+  );
   const updated = await readConfig();
   await writeConfig(writeContextCredential(updated, options.environment, context));
   emit(
@@ -4889,10 +5468,11 @@ async function runDeviceFlow(options) {
     () => "\n  \u2713 Signed in. Run `topolo whoami` to see your identity."
   );
 }
-async function resolveLoginContext(credential, serviceUrls, clientId) {
+async function resolveLoginContext(credential, serviceUrls, clientId, environment) {
   try {
     const topolo = createTopolo({
       credential,
+      environment,
       agent: { clientName: "topolo-cli", clientVersion: CLI_VERSION },
       serviceUrls
     });
@@ -4985,6 +5565,7 @@ async function buildClient(options) {
   const profile = resolvedProfileConfig(config, environment);
   return createTopolo({
     credential,
+    environment,
     agent: {
       clientName: "topolo-cli",
       clientVersion: CLI_VERSION,
@@ -5002,23 +5583,25 @@ function isDebugEnabled() {
   return v !== "0" && v.toLowerCase() !== "false";
 }
 function stderrDebugLogger(event) {
+  const requestId = canonicalTopoloRequestId(event.requestId) ?? "unavailable";
   if (event.phase === "request") {
     process.stderr.write(
-      `[topolo] \u2192 ${event.method} ${event.service} ${event.path} (req=${event.requestId})
+      `[topolo] \u2192 ${event.method} ${event.service} ${event.path} (req=${requestId})
 `
     );
     return;
   }
   if (event.phase === "response") {
     process.stderr.write(
-      `[topolo] \u2190 ${event.status} ${event.method} ${event.service} ${event.path} (${event.durationMs}ms, req=${event.requestId})
+      `[topolo] \u2190 ${event.status} ${event.method} ${event.service} ${event.path} (${event.durationMs}ms, req=${requestId})
 `
     );
     return;
   }
   const statusPart = event.status ? ` ${event.status}` : "";
+  const errorCode = canonicalTopoloErrorCode(event.error) ?? "request_failed";
   process.stderr.write(
-    `[topolo] \u2717${statusPart} ${event.method} ${event.service} ${event.path} (${event.durationMs}ms, req=${event.requestId}): ${event.error}
+    `[topolo] \u2717${statusPart} ${event.method} ${event.service} ${event.path} (${event.durationMs}ms, req=${requestId}, code=${errorCode})
 `
   );
 }
@@ -5251,6 +5834,22 @@ function registerActionsCommand(program2) {
       fail(err, mode);
     }
   });
+  actions.command("prepare <action>").description("Prepare one action with identity, example, validation, exact request, verification, and rollback").option("-d, --data <json-or-@file>", "JSON action input or @path; defaults to one valid published example").option("--resource-type <type>", "App-local resource alias, such as workspace").option("--resource-id <id>", "Resource id for the selected resource type").option("--confirm", "Include confirmation in the plan without executing it").option("--json", "Output compact JSON").option("--no-json", "Output human-readable text").action(async (action, opts, command) => {
+    const mode = resolveOutputMode(opts.json ?? command.parent?.opts().json);
+    try {
+      const topolo = await requiredClient();
+      const resource = parseResourceOption(opts.resourceType, opts.resourceId);
+      const preparation = await topolo.client.prepareAction(
+        action,
+        opts.data === void 0 ? void 0 : parseJsonObject(opts.data),
+        { confirm: opts.confirm === true, ...resource ? { resource } : {} }
+      );
+      const output2 = compactActionPreparation(preparation, await actionExecutionContext(topolo));
+      emit(output2, mode, () => formatActionPreparation(output2));
+    } catch (err) {
+      fail(err, mode);
+    }
+  });
   actions.command("plan <action>").description("Validate and preview the exact request, confirmation, verification, and rollback plan").option("-d, --data <json-or-@file>", "JSON action input or @path to a JSON file", "{}").option("--resource-type <type>", "App-local resource alias, such as workspace").option("--resource-id <id>", "Resource id for the selected resource type").option("--confirm", "Include confirmation in the plan without executing it").option("--detail", "Include the full action contract").option("--json", "Output JSON").option("--no-json", "Output human-readable text").action(async (action, opts, command) => {
     const mode = resolveOutputMode(opts.json ?? command.parent?.opts().json);
     try {
@@ -5316,6 +5915,43 @@ function registerActionsCommand(program2) {
     }
   });
 }
+async function actionExecutionContext(topolo) {
+  const environment = selectedEnvironment();
+  const config = await readConfig();
+  const profile = profileForEnvironment(config, environment);
+  const source = credentialSourceFromConfig(config, environment);
+  return createTopoloAgentExecutionContext({
+    environment,
+    contextKey: source.startsWith("env:") ? null : profile.activeContext ?? null,
+    identity: await topolo.identity.whoami(),
+    serviceUrls: resolvedProfileConfig(config, environment).serviceUrls
+  });
+}
+function formatActionPreparation(preparation) {
+  const context = preparation.context;
+  const lines = [
+    `Environment:  ${context.environment}`,
+    `User:         ${context.user.email} (${context.user.role})`,
+    `Organization: ${context.organization ? `${context.organization.name} (${context.organization.slug})` : "(personal)"}`,
+    `Action:       ${preparation.action.id}`,
+    `Input source: ${preparation.input.source}`,
+    `Valid:        ${preparation.valid ? "yes" : "no"}`,
+    `Confirmation: ${preparation.confirmation.required ? preparation.confirmation.provided ? "provided" : "required" : "not required"}`
+  ];
+  if (preparation.example) {
+    lines.push(`Example:      ${JSON.stringify(preparation.example.input)}`);
+  }
+  if ("value" in preparation.input) {
+    lines.push(`Input:        ${JSON.stringify(preparation.input.value)}`);
+  }
+  if (preparation.request) {
+    lines.push(`Request:      ${preparation.request.method} ${preparation.request.apiBaseUrl || preparation.request.service}${preparation.request.path}`);
+  }
+  if (preparation.missingFields.length) lines.push(`Missing:      ${preparation.missingFields.join(", ")}`);
+  if (preparation.verification.length) lines.push(`Verify:       ${preparation.verification.join(" | ")}`);
+  lines.push(`Rollback:     ${preparation.rollbackActionId || "(not published)"}`);
+  return lines.join("\n");
+}
 function summarizeActionCapabilities(service, actions) {
   return {
     service,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@topolo/cli",
-  "version": "0.7.3",
-  "topoloPublishedVersion": "0.7.3",
+  "version": "0.7.4",
+  "topoloPublishedVersion": "0.7.4",
   "description": "Command-line interface for Topolo developers, operators, and agents, with internal first-party scaffolding available under the topolo platform namespace.",
   "type": "module",
   "bin": {
@@ -12,24 +12,19 @@
     "skills"
   ],
   "scripts": {
-    "build:sdk": "python3 ../../tooling/with-resource-lock.py ../topolo-sdk -- pnpm --dir ../topolo-sdk build",
-    "prebuild": "pnpm run build:sdk",
     "build": "tsup && node scripts/vendor-generator.mjs",
     "dev": "tsup --watch",
-    "pretypecheck": "pnpm run build:sdk",
     "typecheck": "tsc --noEmit",
     "start": "node dist/index.js",
-    "pretest": "pnpm run build:sdk",
     "test": "vitest run",
     "test:watch": "vitest",
-    "precoverage": "pnpm run build:sdk",
     "coverage": "vitest run --coverage"
   },
   "dependencies": {
     "commander": "^12.1.0"
   },
   "devDependencies": {
-    "@topolo/sdk": "file:../topolo-sdk",
+    "@topolo/sdk": "0.10.4",
     "@types/node": "^20.12.0",
     "@vitest/coverage-v8": "3.2.6",
     "tsup": "^8.0.0",