@topolo/sdk 0.10.3 → 0.10.5

package/dist/index.js

@@ -27,6 +27,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;
@@ -34,15 +118,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 {
@@ -53,28 +141,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 record = body;
-  if (typeof record.code === "string" && record.code.trim()) return record.code.trim();
+  const topLevel = canonicalTopoloErrorCode(record.code);
+  if (topLevel) return topLevel;
   const nested = record.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 record = body;
+  let candidate = record.details;
+  const nested = record.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 = record;
+  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 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.";
   }
-  return "http_error";
+  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) {
@@ -89,18 +289,86 @@ var TopoloHttpError = class extends TopoloSdkError {
   path;
   requestId;
   retryAfter;
+  details;
   constructor(service, path, status, body, message, options = {}) {
-    super(extractHttpErrorCode(body), message ?? `HTTP ${status} from ${service}${path}`);
+    super(serviceErrorCode(body, "http_error"), message ?? `HTTP ${status} from ${service}${path}`);
     this.name = "TopoloHttpError";
     this.status = status;
     this.body = body;
     this.service = service;
     this.path = 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 ? body : { details: options.details }
+    );
   }
 };
 
+// src/environment.ts
+var TOPOLO_RUNTIME_ENVIRONMENTS = ["production", "staging", "development", "local"];
+var TOPOLO_ENVIRONMENT_SERVICE_URLS = {
+  production: {
+    auth: "https://auth.topolo.app",
+    developers: "https://developers.topolo.app"
+  },
+  staging: {
+    auth: "https://auth.stg.topolo.us",
+    developers: "https://developers.stg.topolo.us",
+    seed: "https://seed.stg.topolo.us"
+  },
+  development: {
+    auth: "https://auth.topolo.dev",
+    developers: "https://developers.topolo.dev"
+  },
+  local: {}
+};
+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)
+    ])
+  );
+}
+
 // src/bootstrap-services.ts
 var APP_API_URLS = {
   auth: "https://auth.topolo.app",
@@ -2869,6 +3137,7 @@ var TopoloClient = class _TopoloClient {
   credential;
   agent;
   serviceUrls;
+  environment;
   appIds;
   requireConfirmForWrites;
   timeoutMs;
@@ -2897,7 +3166,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;
@@ -2926,9 +3196,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));
@@ -2999,7 +3275,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;
     }
@@ -3008,6 +3284,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,
@@ -3016,7 +3293,7 @@ var TopoloClient = class _TopoloClient {
         url: urlStr,
         requestId,
         durationMs,
-        error: message,
+        error: publicCode,
         status: res.status
       });
       const errorContext = {
@@ -3024,17 +3301,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(
@@ -3084,6 +3365,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) {
@@ -3091,17 +3383,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",
@@ -3115,10 +3410,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.
@@ -3138,7 +3433,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);
@@ -3314,7 +3609,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(
@@ -3379,7 +3674,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, input = {}, options = {}) {
     const entry = await this.getAction(action);
@@ -3456,6 +3751,25 @@ var TopoloClient = class _TopoloClient {
   }
   async planAction(action, input = {}, options = {}) {
     const entry = await this.getAction(action);
+    return this.planResolvedAction(entry, input, options);
+  }
+  async prepareAction(action, input, 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 = input ?? example?.input ?? {};
+    const plan = this.planResolvedAction(entry, selectedInput, options);
+    return {
+      action: entry,
+      example,
+      input: selectedInput,
+      inputSource: input ? "provided" : example ? "example" : "empty",
+      missingFields: [...new Set(
+        plan.validation.errors.filter((issue) => issue.code === "required").map((issue) => issue.path)
+      )],
+      plan
+    };
+  }
+  planResolvedAction(entry, input, options) {
     const validation = validateTopoloActionInput(entry.inputSchema, input);
     const agentAccess = entry.agentAccess ?? (entry.destructive ? "off" : entry.readOnly && !entry.requiresConfirmation ? "auto" : "confirm");
     const confirmationRequired = agentAccess === "confirm" || entry.requiresConfirmation || entry.destructive;
@@ -3804,6 +4118,7 @@ function normalizeActionCatalogEntry(item) {
     path,
     permissionName: pickActionString(a.permission_name) ?? pickActionString(a.permissionName) ?? "",
     requiredPermission: pickActionString(a.required_permission) ?? pickActionString(a.requiredPermission) ?? "",
+    principalAccess: pickPrincipalAccess(a.principal_access ?? a.principalAccess),
     authorizationMode: pickAuthorizationMode(a.authorization_mode ?? a.authorizationMode),
     allowedServices: stringArray(a.allowed_services ?? a.allowedServices),
     inputSchema: plainObject(a.input_schema ?? a.inputSchema),
@@ -3820,6 +4135,9 @@ function normalizeActionCatalogEntry(item) {
 function isHttpMethod(value) {
   return value === "GET" || value === "POST" || value === "PUT" || value === "PATCH" || value === "DELETE";
 }
+function pickPrincipalAccess(value) {
+  return value === "platform_admin" || value === "platform_super_admin" ? value : null;
+}
 function pickActionString(value) {
   return typeof value === "string" && value.trim() ? value.trim() : null;
 }
@@ -3913,7 +4231,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 record = nested;
+      if (Array.isArray(record.required)) return canonicalTopoloRequired(record.required);
+      if (record.details && typeof record.details === "object" && !Array.isArray(record.details)) {
+        const required = record.details.required;
+        if (Array.isArray(required)) return canonicalTopoloRequired(required);
+      }
+    }
   }
   return [];
 }
@@ -3963,6 +4290,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(input) {
+  if (input.contextKey !== null && input.contextKey !== "personal" && !/^org:[^:]+$/.test(input.contextKey)) {
+    throw new TopoloSdkError("invalid_identity_context", "Effective Topolo context key is invalid.");
+  }
+  const user = Object.freeze({
+    id: requiredContextText(input.identity.user.id, "user id"),
+    email: requiredContextText(input.identity.user.email, "user email"),
+    name: input.identity.user.name?.trim() || null,
+    role: requiredContextText(input.identity.user.role, "user role")
+  });
+  const organization = input.identity.organization ? Object.freeze({
+    id: requiredContextText(input.identity.organization.id, "organization id"),
+    slug: requiredContextText(input.identity.organization.slug, "organization slug"),
+    name: requiredContextText(input.identity.organization.name, "organization name")
+  }) : null;
+  if (input.contextKey === "personal" && organization) {
+    throw new TopoloSdkError("identity_context_mismatch", "Personal Topolo context resolved an organization.");
+  }
+  if (input.contextKey?.startsWith("org:")) {
+    const expectedOrganizationId = input.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: input.environment,
+    contextKey: input.contextKey,
+    user,
+    organization,
+    serviceOrigins: Object.freeze(topoloServiceOrigins(input.serviceUrls, input.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,
@@ -3997,6 +4390,7 @@ async function digestTopoloActionCatalog(actions, appId) {
     const allowedServices = [...action.allowedServices || []].map((service) => service.trim()).filter(Boolean).sort();
     return {
       actionId: action.actionId || `${appId}.${action.name}`,
+      principalAccess: action.principalAccess ?? null,
       authorizationMode,
       allowedServices: authorizationMode === "service" || authorizationMode === "runtime" ? allowedServices : [],
       inputSchema: action.inputSchema,
@@ -4982,6 +5376,8 @@ export {
   DEFAULT_APP_URLS,
   IdentityModule,
   P2PModule,
+  TOPOLO_ENVIRONMENT_SERVICE_URLS,
+  TOPOLO_RUNTIME_ENVIRONMENTS,
   TOPOLO_WIDGET_ENDPOINT,
   TOPOLO_WIDGET_REFRESH_INTERVAL_MS,
   TopoloAuthError,
@@ -4995,14 +5391,21 @@ export {
   actionContractCompleteness,
   applicationEntryFromCatalog,
   applicationRequirementScopes,
+  assertTopoloServiceUrlEnvironment,
   auditAllApplicationRequirements,
   auditApplicationEntries,
   auditApplicationRequirements,
+  canonicalTopoloErrorCode,
+  canonicalTopoloRequestId,
+  canonicalTopoloRequired,
+  canonicalTopoloRetryAfter,
   compactActionCatalogEntry,
   compactActionPlan,
+  compactActionPreparation,
   compactActionValidation,
   compactApplicationAudit,
   createTopolo,
+  createTopoloAgentExecutionContext,
   createTopoloWidgetError,
   createTopoloWidgetResponse,
   defineTopoloChartWidget,
@@ -5012,17 +5415,22 @@ export {
   defineTopoloStatsWidget,
   digestTopoloActionCatalog,
   enrichActionContract,
+  extractTopoloServiceErrorCode,
+  extractTopoloServiceErrorDetails,
   formatDirectoryApplicationIds,
   friendlyAppId,
   listApplicationDirectory,
   parseTopoloActionUploadContract,
   prepareTopoloActionBase64UploadInput,
   prepareTopoloActionUploadInput,
+  publicTopoloErrorMessage,
   requirementsForApplication,
   resolveApplicationDirectoryEntry,
   resolveCatalogServiceUrl,
   resolveServiceUrl,
   staticApplicationDirectory,
+  topoloErrorHint,
+  topoloServiceOrigins,
   validateTopoloActionInput,
   validateTopoloWidgetResponse
 };