@topolo/mcp 0.5.0 → 0.7.0

package/dist/index.js

@@ -44,6 +44,12 @@ var TopoloPermissionError = class extends TopoloSdkError {
     this.required = required;
   }
 };
+var TopoloConfirmationRequiredError = class extends TopoloSdkError {
+  constructor(message) {
+    super("confirmation_required", message);
+    this.name = "TopoloConfirmationRequiredError";
+  }
+};
 var TopoloHttpError = class extends TopoloSdkError {
   status;
   body;
@@ -58,7 +64,7 @@ var TopoloHttpError = class extends TopoloSdkError {
     this.path = path;
   }
 };
-var SERVICES = {
+var APP_API_URLS = {
   agent: "https://agent.topolo.app",
   auth: "https://auth.topolo.app",
   backup: "https://backup.topolo.app",
@@ -1106,6 +1112,7 @@ var APPLICATIONS = {
           "topolo.io"
         ],
         "routes": [
+          "one.topolo.io",
           "topolo.io",
           "www.topolo.io"
         ],
@@ -1645,12 +1652,12 @@ var APPLICATION_REQUIREMENTS = [
   {
     id: "shared-auth-boundary",
     title: "Use the shared Topolo auth boundary",
-    summary: "Applications must derive identity, organization, scopes, and service entitlement from TopoloAuth rather than inventing parallel auth state.",
+    summary: "Applications must derive identity, organization, scopes, and app entitlement from TopoloAuth rather than inventing parallel auth state.",
     appliesTo: ["browser", "api", "tooling", "agent_surface"],
     evidence: [
       "@topolo/auth-client or @topolo-io/worker-runtime is used where applicable",
       "No public command, tool, or SDK method accepts orgId",
-      "Service slug and Auth service registration are documented for protected services"
+      "App slug and Auth app registration are documented for protected APIs"
     ],
     implementation: [
       "Use shared auth/runtime packages instead of copying token parsing, gateway, or browser storage flows",
@@ -1683,20 +1690,20 @@ var APPLICATION_REQUIREMENTS = [
     ]
   },
   {
-    id: "service-registration-and-scopes",
-    title: "Register protected APIs as platform services",
-    summary: "Callable app APIs need a stable service ID, service slug, permissions, role bundles, and API-key scopes before agents or users rely on them.",
+    id: "app-registration-and-scopes",
+    title: "Register protected APIs as platform apps",
+    summary: "Callable app APIs need a stable app ID, app slug, permissions, role bundles, and API-key scopes before agents or users rely on them.",
     appliesTo: ["api"],
     evidence: [
-      "Auth service catalog contains the service ID and slug",
-      "Permissions, role bundles, and API-key scopes exist for the service",
-      "SDK, CLI, and MCP service discovery include the callable production API",
-      "CloudControl production HTTP targets classify agent reachability with sdk_service_id or agent_callable:false"
+      "Auth app catalog contains the app ID and slug",
+      "Permissions, role bundles, and API-key scopes exist for the app",
+      "SDK, CLI, and MCP app discovery include the callable production API",
+      "CloudControl production HTTP targets classify agent reachability with sdk_app_id or agent_callable:false"
     ],
     implementation: [
-      "Add production Worker api_url metadata and sdk_service_id for every agent-callable API target",
+      "Add production Worker api_url metadata and sdk_app_id for every agent-callable API target",
       "Mark browser, documentation, and runtime-only Worker targets with agent_callable:false",
-      "Expose stable service IDs through generated DEFAULT_SERVICE_URLS and live catalog discovery",
+      "Expose stable app IDs through generated DEFAULT_APP_URLS and live catalog discovery",
       "Keep typed SDK/CLI/MCP surfaces in sync when an API contract stabilizes"
     ]
   },
@@ -1902,7 +1909,7 @@ function evaluateRequirement(application, requirement) {
         "Catalog metadata cannot verify shared shell, launcher, and account menu adoption.",
         evidence
       );
-    case "service-registration-and-scopes": {
+    case "app-registration-and-scopes": {
       if (application.services.length > 0) {
         evidence.push(`services=${application.services.join(",")}`);
         return finding(
@@ -1912,7 +1919,7 @@ function evaluateRequirement(application, requirement) {
           evidence
         );
       }
-      return finding(requirement, "missing", "No SDK service ID is registered for this callable API surface.", evidence);
+      return finding(requirement, "missing", "No SDK app API id is registered for this callable API surface.", evidence);
     }
     case "organization-scoped-data":
       return finding(
@@ -1997,7 +2004,7 @@ function statusRank(status) {
   if (status === "partial") return 1;
   return 2;
 }
-var DEFAULT_SERVICE_URLS = SERVICES;
+var DEFAULT_APP_URLS = APP_API_URLS;
 function resolveCatalogServiceUrl(entry, options = {}) {
   const keys = catalogServiceKeyCandidates(entry, options.serviceKey);
   const override = resolveServiceUrlOverride(keys, options.overrides);
@@ -2009,7 +2016,7 @@ function resolveCatalogServiceUrl(entry, options = {}) {
 function resolveServiceUrl(service, overrides) {
   const override = resolveServiceUrlOverride([service], overrides);
   if (override) return override;
-  return DEFAULT_SERVICE_URLS[service];
+  return DEFAULT_APP_URLS[service];
 }
 function catalogServiceKeyCandidates(entry, preferred) {
   const values = [preferred, entry.slug, entry.name, entry.appId].filter(
@@ -2040,7 +2047,7 @@ function resolveServiceUrlOverride(keys, overrides) {
     if (envStyle) return envStyle;
   }
   for (const key of keys) {
-    const envKey = `TOPOLO_SERVICE_URL_${key.replace(/\./g, "_").toUpperCase()}`;
+    const envKey = `TOPOLO_APP_URL_${key.replace(/\./g, "_").toUpperCase()}`;
     const envValue = typeof process !== "undefined" ? process.env?.[envKey] : void 0;
     if (envValue) return envValue;
   }
@@ -2059,7 +2066,6 @@ var TOPOLO_RESOURCE_TYPE_HEADER = "X-Topolo-Resource-Type";
 var TOPOLO_RESOURCE_ID_HEADER = "X-Topolo-Resource-ID";
 var POSITIVE_CACHE_TTL_MS = 5 * 60 * 1e3;
 var NEGATIVE_CACHE_TTL_MS = 60 * 1e3;
-var CATALOG_CACHE_TTL_MS = 60 * 1e3;
 var TopoloClient = class _TopoloClient {
   credential;
   agent;
@@ -2068,9 +2074,9 @@ var TopoloClient = class _TopoloClient {
   requireConfirmForWrites;
   timeoutMs;
   fetchImpl;
+  refreshCredential;
+  refreshInFlight = null;
   debug;
-  serviceCatalogCache = null;
-  actionCatalogCache = null;
   /**
    * Process-wide cache for slug → app-id lookups. Keyed by
    * `${authBaseUrl}|${slug}` so multiple `TopoloClient` instances pointing at
@@ -2095,6 +2101,7 @@ var TopoloClient = class _TopoloClient {
     this.requireConfirmForWrites = options.requireConfirmForWrites !== false;
     this.timeoutMs = options.timeoutMs ?? 3e4;
     this.fetchImpl = options.fetch ?? fetch;
+    this.refreshCredential = options.refreshCredential;
     this.debug = options.debug;
   }
   emit(event) {
@@ -2112,11 +2119,11 @@ var TopoloClient = class _TopoloClient {
   async request(opts) {
     const method = opts.method ?? "GET";
     if (this.requireConfirmForWrites && WRITE_METHODS.has(method) && !opts.confirm) {
-      throw new TopoloAuthError(
+      throw new TopoloConfirmationRequiredError(
         `Mutating ${method} requests require { confirm: true }. This guardrail prevents agents from issuing writes without an explicit human-in-the-loop acknowledgement.`
       );
     }
-    const resolvedService = await this.resolveRequestService(opts.service);
+    const resolvedService = opts.baseUrl ? { serviceKey: normalizeLookupKey(opts.service), baseUrl: requireHttpOrigin(opts.baseUrl) } : await this.resolveRequestService(opts.service);
     const baseUrl = resolvedService.baseUrl;
     const url = new URL(opts.path, baseUrl.endsWith("/") ? baseUrl : `${baseUrl}/`);
     if (opts.query) {
@@ -2147,20 +2154,36 @@ var TopoloClient = class _TopoloClient {
       headers.set(TOPOLO_RESOURCE_TYPE_HEADER, resourceType);
       headers.set(TOPOLO_RESOURCE_ID_HEADER, resourceId);
     }
-    const controller = new AbortController();
-    const timeoutId = setTimeout(() => controller.abort(), this.timeoutMs);
-    const signal = opts.signal ? mergeSignals(opts.signal, controller.signal) : controller.signal;
     const urlStr = url.toString();
     const startedAt = Date.now();
     this.emit({ phase: "request", method, service: resolvedService.serviceKey, path: opts.path, url: urlStr, requestId });
+    const fetchOnce = async () => {
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), this.timeoutMs);
+      const signal = opts.signal ? mergeSignals(opts.signal, controller.signal) : controller.signal;
+      try {
+        return await this.fetchImpl(urlStr, {
+          method,
+          headers: new Headers(headers),
+          body: opts.body !== void 0 ? JSON.stringify(opts.body) : null,
+          signal
+        });
+      } finally {
+        clearTimeout(timeoutId);
+      }
+    };
     let res;
     try {
-      res = await this.fetchImpl(urlStr, {
-        method,
-        headers,
-        body: opts.body !== void 0 ? JSON.stringify(opts.body) : null,
-        signal
-      });
+      const attemptedCredential = this.credential;
+      res = await fetchOnce();
+      if (res.status === 401 && attemptedCredential.kind === "access_token" && this.refreshCredential) {
+        await res.body?.cancel().catch(() => void 0);
+        const refreshed = await this.refreshRejectedAccessToken(attemptedCredential.accessToken);
+        if (refreshed) {
+          applyAuthHeaders(headers, refreshed);
+          res = await fetchOnce();
+        }
+      }
     } catch (err) {
       this.emit({
         phase: "error",
@@ -2173,8 +2196,6 @@ var TopoloClient = class _TopoloClient {
         error: err instanceof Error ? err.message : String(err)
       });
       throw err;
-    } finally {
-      clearTimeout(timeoutId);
     }
     const contentType = res.headers.get("Content-Type") ?? "";
     const parsed = contentType.includes("application/json") ? await res.json().catch(() => null) : await res.text().catch(() => null);
@@ -2213,6 +2234,19 @@ var TopoloClient = class _TopoloClient {
     });
     return parsed;
   }
+  async refreshRejectedAccessToken(attemptedAccessToken) {
+    if (this.credential.kind === "access_token" && this.credential.accessToken !== attemptedAccessToken) {
+      return this.credential;
+    }
+    if (!this.refreshCredential) return null;
+    this.refreshInFlight ??= this.refreshCredential().then((credential) => {
+      if (credential) this.credential = credential;
+      return credential;
+    }).catch(() => null).finally(() => {
+      this.refreshInFlight = null;
+    });
+    return this.refreshInFlight;
+  }
   async resolveRequestService(service) {
     const serviceKey = normalizeLookupKey(service);
     if (!serviceKey) {
@@ -2225,7 +2259,7 @@ var TopoloClient = class _TopoloClient {
         const derived = deriveDevelopersFromAuth(resolveConfiguredServiceUrl("auth", this.serviceUrls));
         if (derived) return { serviceKey, baseUrl: derived };
       }
-      return { serviceKey, baseUrl: DEFAULT_SERVICE_URLS[serviceKey] };
+      return { serviceKey, baseUrl: DEFAULT_APP_URLS[serviceKey] };
     }
     const live = await this.resolveLiveCallableService(serviceKey);
     if (live) {
@@ -2234,13 +2268,12 @@ var TopoloClient = class _TopoloClient {
     }
     throw new TopoloSdkError(
       "unknown_service",
-      `Unknown Topolo service "${service}". Run service discovery first and pass a callable service id or slug.`
+      `Unknown Topolo app API "${service}". Run app discovery first and pass a callable app id or slug.`
     );
   }
   async resolveLiveCallableService(serviceKey) {
-    const catalog = await this.listServices();
-    const match = catalog.find((entry) => catalogEntryMatches(entry, serviceKey));
-    if (!match) return null;
+    const match = await this.getService(serviceKey).catch(() => null);
+    if (!match || !catalogEntryMatches(match, serviceKey)) return null;
     const baseUrl = resolveCatalogServiceUrl(match, {
       serviceKey,
       overrides: this.serviceUrls
@@ -2314,12 +2347,13 @@ var TopoloClient = class _TopoloClient {
    * The live Auth catalog is the authority because it is scoped to the caller's
    * organization and effective permissions.
    */
-  async listServices() {
-    const now = Date.now();
-    if (this.serviceCatalogCache && this.serviceCatalogCache.expiresAt > now) {
-      return this.serviceCatalogCache.entries;
-    }
-    const res = await this.request({ service: "developers", method: "GET", path: "/api/services/catalog" });
+  async searchServices(options = {}) {
+    const res = await this.request({
+      service: "developers",
+      method: "GET",
+      path: "/api/services/catalog",
+      query: catalogSearchQuery(options)
+    });
     const raw = res.data?.services ?? res.services;
     if (!Array.isArray(raw)) {
       throw new TopoloSdkError(
@@ -2329,6 +2363,7 @@ var TopoloClient = class _TopoloClient {
     }
     const entries = [];
     for (const item of raw) {
+      if (!isRecord(item)) continue;
       const s = item;
       const appId = typeof s.app_id === "string" ? s.app_id : typeof s.id === "string" ? s.id : null;
       if (!appId) continue;
@@ -2353,11 +2388,30 @@ var TopoloClient = class _TopoloClient {
         apiKeyResources
       });
     }
-    this.serviceCatalogCache = {
-      entries,
-      expiresAt: now + CATALOG_CACHE_TTL_MS
-    };
-    return entries;
+    const page = normalizeCatalogPage(
+      res.data?.page ?? res.page
+    );
+    return { services: entries, page };
+  }
+  /** @deprecated Prefer searchServices() so callers retain the continuation cursor. */
+  async listServices(options = {}) {
+    return (await this.searchServices(options)).services;
+  }
+  async getService(application) {
+    const needle = application.trim();
+    if (!needle) throw new TopoloSdkError("unknown_service", "application is required");
+    const res = await this.request({
+      service: "developers",
+      method: "GET",
+      path: "/api/services/catalog",
+      query: { application: needle }
+    });
+    const raw = res.data?.application ?? res.application;
+    const entry = normalizeServiceCatalogEntry(raw);
+    if (!entry) {
+      throw new TopoloSdkError("unknown_service", `Unknown Topolo application "${application}".`);
+    }
+    return entry;
   }
   /**
    * List callable actions from the live registry-canonical catalog (definitions
@@ -2365,16 +2419,15 @@ var TopoloClient = class _TopoloClient {
    * caller's organization and effective permissions; no bundled/static app
    * action list is used as an authorization source.
    */
-  async listActions(options = {}) {
-    const now = Date.now();
-    if (!options.service && this.actionCatalogCache && this.actionCatalogCache.expiresAt > now) {
-      return this.actionCatalogCache.entries;
+  async searchActions(options) {
+    if (!options.service?.trim()) {
+      throw new TopoloSdkError("service_required", "service is required for bounded action discovery");
     }
     const res = await this.request({
       service: "developers",
       method: "GET",
       path: "/api/actions/catalog",
-      ...options.service ? { query: { service: options.service } } : {}
+      query: { service: options.service, ...catalogSearchQuery(options) }
     });
     const raw = res.data?.actions ?? res.actions;
     if (!Array.isArray(raw)) {
@@ -2384,36 +2437,96 @@ var TopoloClient = class _TopoloClient {
       );
     }
     const entries = raw.map((item) => normalizeActionCatalogEntry(item)).filter((entry) => Boolean(entry));
-    if (!options.service) {
-      this.actionCatalogCache = {
-        entries,
-        expiresAt: now + CATALOG_CACHE_TTL_MS
-      };
+    return {
+      actions: entries,
+      page: normalizeCatalogPage(
+        res.data?.page ?? res.page
+      )
+    };
+  }
+  async getActionCatalogSummary(service) {
+    const boundedService = service.trim();
+    if (!boundedService) {
+      throw new TopoloSdkError("service_required", "service is required for bounded action discovery");
+    }
+    const res = await this.request({
+      service: "developers",
+      method: "GET",
+      path: "/api/actions/catalog",
+      query: { service: boundedService, summary: "true" }
+    });
+    const raw = res.data?.summary ?? res.summary;
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+      throw new TopoloSdkError("action_catalog_summary_unavailable", "Action catalog summary is unavailable.");
+    }
+    const record = raw;
+    if (record.algorithm !== "sha256-v1" || typeof record.digest !== "string" || !/^[a-f0-9]{64}$/.test(record.digest) || !Number.isSafeInteger(record.actionCount) || Number(record.actionCount) < 0) {
+      throw new TopoloSdkError("action_catalog_summary_unavailable", "Action catalog summary is invalid.");
     }
-    return entries;
+    return {
+      algorithm: "sha256-v1",
+      digest: record.digest,
+      actionCount: Number(record.actionCount)
+    };
+  }
+  /** @deprecated Prefer searchActions() so callers retain the continuation cursor. */
+  async listActions(options) {
+    if (!options) {
+      throw new TopoloSdkError("service_required", "service is required for bounded action discovery");
+    }
+    return (await this.searchActions(options)).actions;
   }
   async getAction(action) {
-    const needle = normalizeActionLookupKey(action);
-    const actions = await this.listActions();
-    const match = actions.find((entry) => actionEntryMatches(entry, needle));
-    if (!match) {
+    const actionId = action.trim();
+    if (!actionId) {
       throw new TopoloSdkError(
         "unknown_action",
-        `Unknown Topolo action "${action}". Run action discovery first and pass an action id, name, or tool name.`
+        "action id is required"
       );
     }
+    let res;
+    try {
+      res = await this.request({
+        service: "developers",
+        method: "GET",
+        path: "/api/actions/catalog",
+        query: { actionId }
+      });
+    } catch (error) {
+      if (error instanceof TopoloHttpError && error.status === 404) {
+        throw new TopoloSdkError("unknown_action", `Unknown or unavailable Topolo action "${action}".`);
+      }
+      throw error;
+    }
+    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;
   }
   async callAction(action, input = {}, options = {}) {
     const entry = await this.getAction(action);
+    const agentAccess = entry.agentAccess ?? (entry.destructive ? "off" : entry.readOnly && !entry.requiresConfirmation ? "auto" : "confirm");
+    if (agentAccess === "off") {
+      throw new TopoloPermissionError(
+        `Topolo action "${entry.actionId}" is not available for agent invocation.`,
+        entry.requiredPermission ? [entry.requiredPermission] : []
+      );
+    }
+    if ((agentAccess === "confirm" || entry.requiresConfirmation || entry.destructive) && options.confirm !== true) {
+      throw new TopoloConfirmationRequiredError(
+        `Topolo action "${entry.actionId}" requires { confirm: true } before invocation.`
+      );
+    }
     const mapped = mapActionInput(entry, input);
-    const service = entry.serviceSlug || entry.appId;
+    const service = entry.appSlug || entry.appId;
     return this.request({
       service,
+      ...entry.apiBaseUrl ? { baseUrl: entry.apiBaseUrl } : {},
       method: entry.method,
       path: mapped.path,
       ...mapped.query ? { query: mapped.query } : {},
       ...mapped.body !== void 0 ? { body: mapped.body } : {},
+      ...options.resource ? { resource: options.resource } : {},
       headers: {
         [TOPOLO_ACTION_ID_HEADER]: entry.actionId,
         [TOPOLO_ACTION_NAME_HEADER]: entry.name
@@ -2551,6 +2664,18 @@ function serviceKeyCandidates2(slug) {
 function normalizeLookupKey(value) {
   return String(value || "").trim().toLowerCase().replace(/\s+/g, "-");
 }
+function requireHttpOrigin(value) {
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new TopoloSdkError("invalid_action_target", `Invalid action API origin "${value}".`);
+  }
+  if (url.protocol !== "https:" && url.protocol !== "http:" || url.username || url.password) {
+    throw new TopoloSdkError("invalid_action_target", `Invalid action API origin "${value}".`);
+  }
+  return url.origin;
+}
 function deriveDevelopersFromAuth(authUrl) {
   if (!authUrl) return null;
   try {
@@ -2577,6 +2702,47 @@ function catalogEntryLookupKeys(entry) {
   }
   return [...keys];
 }
+function catalogSearchQuery(options) {
+  const query = {};
+  if (typeof options.query === "string" && options.query.trim()) query.query = options.query.trim();
+  if (typeof options.cursor === "string" && options.cursor.trim()) query.cursor = options.cursor.trim();
+  if (typeof options.limit === "number" && Number.isFinite(options.limit)) query.limit = Math.trunc(options.limit);
+  return query;
+}
+function normalizeCatalogPage(value) {
+  if (!isRecord(value)) return { nextCursor: null, hasMore: false };
+  return {
+    nextCursor: typeof value.nextCursor === "string" && value.nextCursor ? value.nextCursor : null,
+    hasMore: value.hasMore === true
+  };
+}
+function normalizeServiceCatalogEntry(item) {
+  if (!isRecord(item)) return null;
+  const appId = typeof item.app_id === "string" ? item.app_id : typeof item.id === "string" ? item.id : null;
+  if (!appId) return null;
+  const permissions = Array.isArray(item.granted_permissions) ? item.granted_permissions.filter(
+    (permission) => typeof permission === "string" && permission.trim().length > 0
+  ) : [];
+  const catalogApiKeyResources = normalizeApiKeyResourceMetadataList(
+    item.api_key_resources ?? item.apiKeyResources
+  );
+  const apiKeyResource = normalizeApiKeyResourceMetadata(item.api_key_resource ?? item.apiKeyResource) ?? catalogApiKeyResources[0] ?? null;
+  const apiKeyResources = catalogApiKeyResources.length > 0 ? catalogApiKeyResources : apiKeyResource ? [apiKeyResource] : [];
+  return {
+    appId,
+    slug: typeof item.app_slug === "string" ? item.app_slug : null,
+    name: typeof item.name === "string" ? item.name : null,
+    description: typeof item.description === "string" ? item.description : null,
+    apiBaseUrl: typeof item.api_base_url === "string" ? item.api_base_url : typeof item.apiBaseUrl === "string" ? item.apiBaseUrl : null,
+    launchUrl: typeof item.launch_url === "string" ? item.launch_url : typeof item.launchUrl === "string" ? item.launchUrl : null,
+    status: typeof item.status === "string" ? item.status : null,
+    surfaceKind: typeof item.surface_kind === "string" ? item.surface_kind : null,
+    launchable: item.launchable === true,
+    permissions,
+    apiKeyResource,
+    apiKeyResources
+  };
+}
 function normalizeActionCatalogEntry(item) {
   if (!item || typeof item !== "object" || Array.isArray(item)) return null;
   const a = item;
@@ -2590,17 +2756,20 @@ function normalizeActionCatalogEntry(item) {
   }
   return {
     actionId,
+    target: pickActionString(a.target_key) ?? pickActionString(a.target) ?? null,
+    apiBaseUrl: pickActionString(a.api_base_url) ?? pickActionString(a.apiBaseUrl) ?? null,
     name,
     toolName: pickActionString(a.tool_name) ?? pickActionString(a.toolName) ?? null,
     title: pickActionString(a.title) ?? name,
     description: pickActionString(a.description) ?? "",
     appId,
-    serviceSlug: pickActionString(a.service_slug) ?? pickActionString(a.serviceSlug) ?? null,
-    serviceName: pickActionString(a.service_name) ?? pickActionString(a.serviceName) ?? null,
+    appSlug: pickActionString(a.app_slug) ?? pickActionString(a.appSlug) ?? null,
+    appName: pickActionString(a.app_name) ?? pickActionString(a.appName) ?? null,
     method,
     path,
     permissionName: pickActionString(a.permission_name) ?? pickActionString(a.permissionName) ?? "",
     requiredPermission: pickActionString(a.required_permission) ?? pickActionString(a.requiredPermission) ?? "",
+    authorizationMode: pickAuthorizationMode(a.authorization_mode ?? a.authorizationMode),
     inputSchema: plainObject(a.input_schema ?? a.inputSchema),
     outputSchema: plainObject(a.output_schema ?? a.outputSchema),
     readOnly: Boolean(a.read_only ?? a.readOnly),
@@ -2620,16 +2789,12 @@ function pickActionString(value) {
 function pickAgentAccess(value) {
   return value === "auto" || value === "confirm" || value === "off" ? value : null;
 }
+function pickAuthorizationMode(value) {
+  return value === "runtime" ? "runtime" : "static";
+}
 function plainObject(value) {
   return value && typeof value === "object" && !Array.isArray(value) ? value : {};
 }
-function normalizeActionLookupKey(value) {
-  return String(value || "").trim().toLowerCase();
-}
-function actionEntryMatches(entry, needle) {
-  if (!needle) return false;
-  return [entry.actionId, entry.name, entry.toolName].filter((value) => typeof value === "string" && value.length > 0).some((value) => value.toLowerCase() === needle);
-}
 function mapActionInput(action, input) {
   const remaining = { ...input || {} };
   const path = action.path.replace(/\{([a-zA-Z0-9_]+)\}/g, (_match, key) => {
@@ -2711,6 +2876,7 @@ var CrmModule = class {
   constructor(client) {
     this.client = client;
   }
+  client;
   async listContacts(options = {}) {
     const res = await this.client.request({
       service: "crm",
@@ -2756,6 +2922,7 @@ var IdentityModule = class {
   constructor(client) {
     this.client = client;
   }
+  client;
   /** Returns the resolved user, organization, and permission set for the
    *  current credential. Equivalent to `TopoloClient.introspect()` — exposed
    *  on this module for symmetry with the other domain modules. */
@@ -2772,22 +2939,364 @@ function createTopolo(options) {
   };
 }
 
-// src/auth.ts
-function resolveCredentialFromEnv() {
-  const apiKey = process.env.TOPOLO_API_KEY;
+// ../topolo-sdk/dist/node/credential-store.js
+import { mkdir, readFile, writeFile, chmod } from "fs/promises";
+import { existsSync } from "fs";
+import { homedir, platform } from "os";
+import { dirname, join } from "path";
+var TopoloSdkError2 = class extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = "TopoloSdkError";
+    this.code = code;
+  }
+};
+var TopoloAuthError2 = class extends TopoloSdkError2 {
+  constructor(message, code = "auth_error") {
+    super(code, message);
+    this.name = "TopoloAuthError";
+  }
+};
+var TopoloHttpError2 = class extends TopoloSdkError2 {
+  status;
+  body;
+  service;
+  path;
+  constructor(service, path, status, body, message) {
+    super("http_error", message ?? `HTTP ${status} from ${service}${path}`);
+    this.name = "TopoloHttpError";
+    this.status = status;
+    this.body = body;
+    this.service = service;
+    this.path = path;
+  }
+};
+var APP_API_URLS2 = {
+  agent: "https://agent.topolo.app",
+  auth: "https://auth.topolo.app",
+  backup: "https://backup.topolo.app",
+  books: "https://books.topolo.app",
+  bugfix: "https://bugfix.topolo.app",
+  bytes: "https://bytes.topolo.app",
+  calendar: "https://calendar.topolo.app",
+  capacity: "https://capacity.topolo.app",
+  chat: "https://chat.topolo.app",
+  commerce: "https://commerce.topolo.app",
+  compose: "https://compose.topolo.app",
+  consent: "https://consent.topolo.app",
+  crm: "https://crm.topolo.app",
+  developers: "https://developers.topolo.app",
+  director: "https://director.topolo.app",
+  feed: "https://feed.topolo.app",
+  flow: "https://flow.topolo.app",
+  forecast: "https://forecast.topolo.app",
+  forms: "https://forms.topolo.app",
+  home: "https://home.topolo.app",
+  insights: "https://insights.topolo.app",
+  inventory: "https://inventory.topolo.app",
+  learn: "https://learn.topolo.app",
+  localize: "https://localize.topolo.app",
+  mail: "https://mail.topolo.app",
+  mdm: "https://mdm.topolo.app",
+  messages: "https://messages.topolo.app",
+  nexus: "https://nexus.topolo.app",
+  notify: "https://notify.topolo.app",
+  observability_watch: "https://observability-watch.topolo.app",
+  one: "https://www.topolo.app",
+  p2p: "https://p2p.topolo.app",
+  pay: "https://pay.topolo.app",
+  people: "https://people.topolo.app",
+  "quro.api": "https://api.ol0.me",
+  "quro.redirect": "https://ol0.me",
+  roadmapper: "https://roadmapper.topolo.app",
+  sign: "https://sign.topolo.app",
+  social_studio: "https://studio.topolo.app",
+  socialize: "https://socialize.topolo.app",
+  spaces: "https://spaces.topolo.app",
+  status: "https://status.topolo.app",
+  success: "https://success.topolo.app",
+  support: "https://support.topolo.app",
+  survey: "https://survey.topolo.app",
+  voice: "https://voice.topolo.app",
+  web: "https://web.topolo.app"
+};
+var DEFAULT_APP_URLS2 = APP_API_URLS2;
+function resolveServiceUrl2(service, overrides) {
+  const override = resolveServiceUrlOverride2([service], overrides);
+  if (override) return override;
+  return DEFAULT_APP_URLS2[service];
+}
+function resolveServiceUrlOverride2(keys, overrides) {
+  for (const key of keys) {
+    const direct = overrides?.[key];
+    if (direct) return direct;
+    const envStyleKey = key.replace(/\./g, "_");
+    const envStyle = overrides?.[envStyleKey];
+    if (envStyle) return envStyle;
+  }
+  for (const key of keys) {
+    const envKey = `TOPOLO_APP_URL_${key.replace(/\./g, "_").toUpperCase()}`;
+    const envValue = typeof process !== "undefined" ? process.env?.[envKey] : void 0;
+    if (envValue) return envValue;
+  }
+  return null;
+}
+var DEVICE_GRANT = "urn:ietf:params:oauth:grant-type:device_code";
+var TopoloOAuth = class {
+  baseUrl;
+  fetchImpl;
+  constructor(options = {}) {
+    this.baseUrl = resolveServiceUrl2("auth", options.serviceUrls);
+    this.fetchImpl = options.fetch ?? fetch;
+  }
+  /**
+   * RFC 8628 device authorization grant — starts the flow by asking the server
+   * for a device_code + user_code. The caller prints the user_code +
+   * verification_uri and then polls `pollDeviceToken` until approval.
+   */
+  async requestDeviceCode(params) {
+    const body = new URLSearchParams();
+    body.set("client_id", params.clientId);
+    if (params.scope) {
+      body.set("scope", Array.isArray(params.scope) ? params.scope.join(" ") : params.scope);
+    }
+    return this.#postForm("/api/developer-oauth/device_authorization", body);
+  }
+  /**
+   * Polls the token endpoint once. Returns the token pair on success, or
+   * throws a `TopoloAuthError` whose `code` is one of the RFC 8628 poll
+   * states: `authorization_pending`, `slow_down`, `access_denied`,
+   * `expired_token`. Callers should back off on `slow_down`, wait at least
+   * one `interval` on `authorization_pending`, and give up on the rest.
+   */
+  async pollDeviceToken(params) {
+    const body = new URLSearchParams();
+    body.set("grant_type", DEVICE_GRANT);
+    body.set("client_id", params.clientId);
+    body.set("device_code", params.deviceCode);
+    if (params.clientSecret) body.set("client_secret", params.clientSecret);
+    return this.#postForm("/api/developer-oauth/token", body);
+  }
+  /** Exchange an authorization code (with PKCE) for tokens. */
+  async exchangeAuthorizationCode(params) {
+    const body = new URLSearchParams();
+    body.set("grant_type", "authorization_code");
+    body.set("client_id", params.clientId);
+    body.set("code", params.code);
+    body.set("redirect_uri", params.redirectUri);
+    if (params.codeVerifier) body.set("code_verifier", params.codeVerifier);
+    if (params.clientSecret) body.set("client_secret", params.clientSecret);
+    return this.#postForm("/api/developer-oauth/token", body);
+  }
+  /** Rotate a refresh token for a new token pair. */
+  async refreshToken(params) {
+    const body = new URLSearchParams();
+    body.set("grant_type", "refresh_token");
+    body.set("client_id", params.clientId);
+    body.set("refresh_token", params.refreshToken);
+    if (params.clientSecret) body.set("client_secret", params.clientSecret);
+    return this.#postForm("/api/developer-oauth/token", body);
+  }
+  async #postForm(path, body) {
+    const url = new URL(path, this.baseUrl.endsWith("/") ? this.baseUrl : `${this.baseUrl}/`);
+    const res = await this.fetchImpl(url.toString(), {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/x-www-form-urlencoded",
+        Accept: "application/json"
+      },
+      body: body.toString()
+    });
+    const contentType = res.headers.get("Content-Type") ?? "";
+    const parsed = contentType.includes("application/json") ? await res.json().catch(() => null) : await res.text().catch(() => null);
+    if (!res.ok) {
+      if (parsed && typeof parsed === "object" && "error" in parsed) {
+        const err = parsed;
+        throw new TopoloAuthError2(err.error_description || err.error, err.error);
+      }
+      throw new TopoloHttpError2("auth", path, res.status, parsed);
+    }
+    return parsed;
+  }
+};
+var ENVIRONMENT_DEFAULT_SERVICE_URLS = {
+  production: {
+    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 configPath() {
+  const override = process.env.TOPOLO_CONFIG_PATH;
+  if (override) return override;
+  const base = process.env.XDG_CONFIG_HOME || (platform() === "win32" ? join(homedir(), "AppData", "Roaming") : join(homedir(), ".config"));
+  return join(base, "topolo", "config.json");
+}
+async function readConfig() {
+  const path = configPath();
+  if (!existsSync(path)) return {};
+  try {
+    const raw = await readFile(path, "utf8");
+    return JSON.parse(raw);
+  } catch {
+    return {};
+  }
+}
+async function writeConfig(config) {
+  const path = configPath();
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, JSON.stringify(config, null, 2) + "\n", "utf8");
+  if (platform() !== "win32") {
+    try {
+      await chmod(path, 384);
+    } catch {
+    }
+  }
+}
+function normalizeEnvironment(value) {
+  const normalized = (value ?? "production").trim().toLowerCase();
+  if (normalized === "" || normalized === "production" || normalized === "prod") {
+    return "production";
+  }
+  if (normalized === "staging" || normalized === "stage" || normalized === "stg") {
+    return "staging";
+  }
+  if (normalized === "development" || normalized === "dev") {
+    return "development";
+  }
+  if (normalized === "local" || normalized === "localhost") {
+    return "local";
+  }
+  throw new Error(
+    `Unknown Topolo environment "${value}". Expected production, staging, development, or local.`
+  );
+}
+function selectedEnvironment() {
+  return normalizeEnvironment(process.env.TOPOLO_ENV);
+}
+function envVarPrefix(environment) {
+  if (environment === "production") return "TOPOLO_PRODUCTION";
+  if (environment === "staging") return "TOPOLO_STAGING";
+  if (environment === "development") return "TOPOLO_DEVELOPMENT";
+  return "TOPOLO_LOCAL";
+}
+function profileForEnvironment(config, environment = selectedEnvironment()) {
+  const profile = config.profiles?.[environment] ?? {};
+  if (environment === "production") {
+    return {
+      credential: config.credential,
+      oauthClientId: config.oauthClientId,
+      ...profile,
+      serviceUrls: {
+        ...config.serviceUrls ?? {},
+        ...profile.serviceUrls ?? {}
+      },
+      agentName: profile.agentName ?? config.agentName
+    };
+  }
+  return profile;
+}
+function writeProfileConfig(config, environment, profile) {
+  const profiles = { ...config.profiles ?? {} };
+  profiles[environment] = {
+    ...profiles[environment] ?? {},
+    ...profile
+  };
+  return { ...config, profiles };
+}
+async function resolveCredential(environment = selectedEnvironment()) {
+  const prefix = envVarPrefix(environment);
+  const apiKey = process.env[`${prefix}_API_KEY`] ?? process.env.TOPOLO_API_KEY;
   if (apiKey) return { kind: "api_key", apiKey };
-  const accessToken = process.env.TOPOLO_ACCESS_TOKEN;
+  const accessToken = process.env[`${prefix}_ACCESS_TOKEN`] ?? process.env.TOPOLO_ACCESS_TOKEN;
   if (accessToken) return { kind: "access_token", accessToken };
-  return null;
+  const config = await readConfig();
+  return profileForEnvironment(config, environment).credential ?? null;
+}
+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) {
+    return resolveCredential(environment);
+  }
+  const config = await readConfig();
+  const profile = profileForEnvironment(config, environment);
+  const cred = profile.credential;
+  if (!cred || cred.kind !== "access_token") return cred ?? null;
+  if (!cred.refreshToken || !cred.expiresAt || !profile.oauthClientId) return cred;
+  const now = Math.floor(Date.now() / 1e3);
+  if (!options.force && cred.expiresAt - REFRESH_SKEW_SECONDS > now) return cred;
+  try {
+    const oauth = new TopoloOAuth({
+      serviceUrls: resolveServiceUrls(profile.serviceUrls, environment)
+    });
+    const tokens = await oauth.refreshToken({
+      clientId: profile.oauthClientId,
+      refreshToken: cred.refreshToken
+    });
+    const refreshed = {
+      kind: "access_token",
+      accessToken: tokens.access_token,
+      ...tokens.refresh_token ? { refreshToken: tokens.refresh_token } : { refreshToken: cred.refreshToken },
+      expiresAt: Math.floor(Date.now() / 1e3) + tokens.expires_in
+    };
+    const activeContext = profile.activeContext;
+    const activeEntry = activeContext ? profile.contexts?.[activeContext] : void 0;
+    const updated = activeContext && activeEntry ? writeProfileConfig(config, environment, {
+      credential: refreshed,
+      contexts: {
+        ...profile.contexts ?? {},
+        [activeContext]: {
+          ...activeEntry,
+          credential: refreshed,
+          oauthClientId: activeEntry.oauthClientId ?? profile.oauthClientId
+        }
+      }
+    }) : environment === "production" && !config.profiles?.production ? { ...config, credential: refreshed } : writeProfileConfig(config, environment, { credential: refreshed });
+    await writeConfig(updated);
+    return refreshed;
+  } catch {
+    return cred;
+  }
+}
+function resolveAgentName(configAgentName) {
+  return process.env.TOPOLO_AGENT_NAME ?? configAgentName;
 }
-function resolveServiceUrlsFromEnv() {
-  const out = {};
+function resolveServiceUrls(configUrls, environment = selectedEnvironment()) {
+  const merged = {
+    ...ENVIRONMENT_DEFAULT_SERVICE_URLS[environment],
+    ...configUrls ?? {}
+  };
+  const prefix = `${envVarPrefix(environment)}_SERVICE_URL_`;
+  for (const [k, v] of Object.entries(process.env)) {
+    if (k.startsWith(prefix) && v) {
+      merged[k.slice(prefix.length).toLowerCase()] = v;
+    }
+  }
   for (const [k, v] of Object.entries(process.env)) {
     if (k.startsWith("TOPOLO_SERVICE_URL_") && v) {
-      out[k.slice("TOPOLO_SERVICE_URL_".length).toLowerCase()] = v;
+      merged[k.slice("TOPOLO_SERVICE_URL_".length).toLowerCase()] = v;
     }
   }
-  return Object.keys(out).length > 0 ? out : void 0;
+  return Object.keys(merged).length > 0 ? merged : void 0;
+}
+
+// src/auth.ts
+function resolveCredentialFromEnv() {
+  const apiKey = process.env.TOPOLO_API_KEY;
+  if (apiKey) return { kind: "api_key", apiKey };
+  const accessToken = process.env.TOPOLO_ACCESS_TOKEN;
+  if (accessToken) return { kind: "access_token", accessToken };
+  return null;
 }
 
 // src/server.ts
@@ -2837,6 +3346,15 @@ function splitService(servicePart) {
 // src/tools.ts
 var APPLICATION_IDS = Object.keys(APPLICATIONS).sort();
 var HTTP_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE"];
+function optionalResourceContext(args) {
+  const resourceType = typeof args["resourceType"] === "string" ? args["resourceType"].trim() : "";
+  const resourceId = typeof args["resourceId"] === "string" ? args["resourceId"].trim() : "";
+  if (!resourceType && !resourceId) return void 0;
+  if (!resourceType || !resourceId) {
+    throw new Error("resourceType and resourceId must be provided together.");
+  }
+  return { resourceType, resourceId };
+}
 var TOOLS = [
   {
     name: "topolo_whoami",
@@ -2852,18 +3370,27 @@ var TOOLS = [
     handler: async (topolo) => topolo.identity.whoami()
   },
   {
-    name: "topolo_list_services",
-    title: "List every Topolo service the agent can reach",
-    description: "Returns the credential-scoped service registry: one entry per platform service the current credential can use in its organization, with granted permissions, API URL, and launch URL. Use this to discover what `topolo_api_call` can address. This is not the global platform catalog.",
+    name: "topolo_search_applications",
+    title: "Search Topolo applications the agent can reach",
+    description: "Searches the credential-scoped application registry with a bounded page and continuation cursor. Returns granted permissions, API URL, and launch URL without loading the global platform catalog.",
     requiredScopes: [],
     destructive: false,
     inputSchema: {
       type: "object",
-      properties: {},
+      properties: {
+        query: { type: "string" },
+        cursor: { type: "string" },
+        limit: { type: "integer", minimum: 1, maximum: 100, default: 25 }
+      },
       additionalProperties: false
     },
-    handler: async (topolo) => {
-      const services = (await topolo.client.listServices()).map((entry) => {
+    handler: async (topolo, args) => {
+      const result = await topolo.client.searchServices({
+        query: typeof args["query"] === "string" ? args["query"] : void 0,
+        cursor: typeof args["cursor"] === "string" ? args["cursor"] : void 0,
+        limit: typeof args["limit"] === "number" ? args["limit"] : void 0
+      });
+      const applications = result.services.map((entry) => {
         const id = displayAppId(entry);
         return {
           id,
@@ -2880,13 +3407,13 @@ var TOOLS = [
           permissions: [...entry.permissions]
         };
       }).sort((left, right) => left.id.localeCompare(right.id));
-      return { services };
+      return { applications, page: result.page };
     }
   },
   {
-    name: "topolo_list_actions",
-    title: "List every Topolo action the agent can call",
-    description: "Returns the credential-scoped callable action catalog. Actions are published by applications through TopoloDevelopers and filtered by TopoloAuth against the current organization and effective permissions.",
+    name: "topolo_search_actions",
+    title: "Search Topolo actions the agent can call",
+    description: "Searches one application's credential-scoped actions with a bounded page and continuation cursor.",
     requiredScopes: [],
     destructive: false,
     inputSchema: {
@@ -2894,31 +3421,25 @@ var TOOLS = [
       properties: {
         service: {
           type: "string",
-          description: "Optional app id, slug, or name filter."
-        }
+          description: "Required app id, slug, or name."
+        },
+        query: { type: "string" },
+        cursor: { type: "string" },
+        limit: { type: "integer", minimum: 1, maximum: 100, default: 25 }
       },
+      required: ["service"],
       additionalProperties: false
     },
-    handler: async (topolo, args) => ({
-      actions: await topolo.client.listActions({
-        service: typeof args["service"] === "string" ? args["service"] : void 0
-      })
-    })
-  },
-  {
-    name: "topolo_list_applications",
-    title: "List every Topolo platform application",
-    description: "Returns the live Topolo application catalog from the platform registry. Reflects apps as they are registered/removed with no client rebuild. Authenticated callers in an entitled org also see the developer_only apps their role permits. Falls back to a bundled snapshot only if the registry is unreachable.",
-    requiredScopes: [],
-    destructive: false,
-    inputSchema: {
-      type: "object",
-      properties: {},
-      additionalProperties: false
-    },
-    handler: async (topolo) => ({
-      applications: await topolo.client.listServices()
-    })
+    handler: async (topolo, args) => {
+      const service = typeof args["service"] === "string" ? args["service"].trim() : "";
+      if (!service) throw new Error("service is required for bounded action discovery.");
+      return topolo.client.searchActions({
+        service,
+        query: typeof args["query"] === "string" ? args["query"] : void 0,
+        cursor: typeof args["cursor"] === "string" ? args["cursor"] : void 0,
+        limit: typeof args["limit"] === "number" ? args["limit"] : void 0
+      });
+    }
   },
   {
     name: "topolo_get_application",
@@ -2931,7 +3452,7 @@ var TOOLS = [
       properties: {
         application: {
           type: "string",
-          description: "Application identifier: app id, slug, or name from topolo_list_applications."
+          description: "Application identifier: app id, slug, or name from topolo_search_applications."
         }
       },
       required: ["application"],
@@ -2942,18 +3463,98 @@ var TOOLS = [
       if (typeof application !== "string" || !application.trim()) {
         throw new Error("`application` must be a non-empty string.");
       }
-      const needle = application.trim().toLowerCase();
-      const catalog = await topolo.client.listServices();
-      const match = catalog.find(
-        (e) => e.appId.toLowerCase() === needle || e.slug && e.slug.toLowerCase() === needle || e.name && e.name.toLowerCase() === needle
+      return { application: await topolo.client.getService(application) };
+    }
+  },
+  {
+    name: "topolo_get_action",
+    title: "Describe one Topolo action",
+    description: "Returns one credential-scoped action by exact action id.",
+    requiredScopes: [],
+    destructive: false,
+    inputSchema: {
+      type: "object",
+      properties: { actionId: { type: "string", minLength: 1 } },
+      required: ["actionId"],
+      additionalProperties: false
+    },
+    handler: async (topolo, args) => {
+      const actionId = typeof args["actionId"] === "string" ? args["actionId"].trim() : "";
+      if (!actionId) throw new Error("actionId is required.");
+      return { action: await topolo.client.getAction(actionId) };
+    }
+  },
+  {
+    name: "topolo_read_action",
+    title: "Call one read-only Topolo action",
+    description: "Calls one exact action id only when its published contract is read-only and needs no confirmation.",
+    requiredScopes: [],
+    destructive: false,
+    inputSchema: {
+      type: "object",
+      properties: {
+        actionId: { type: "string", minLength: 1 },
+        input: { type: "object", additionalProperties: true },
+        resourceType: { type: "string", description: "Optional app-local resource alias, such as workspace." },
+        resourceId: { type: "string", description: "Resource id. Required when resourceType is provided." }
+      },
+      required: ["actionId"],
+      additionalProperties: false
+    },
+    handler: async (topolo, args) => {
+      const actionId = typeof args["actionId"] === "string" ? args["actionId"].trim() : "";
+      if (!actionId) throw new Error("actionId is required.");
+      const input = args["input"];
+      if (input !== void 0 && (!input || typeof input !== "object" || Array.isArray(input))) {
+        throw new Error("input must be an object.");
+      }
+      const action = await topolo.client.getAction(actionId);
+      const agentAccess = action.agentAccess ?? (action.destructive ? "off" : action.readOnly && !action.requiresConfirmation ? "auto" : "confirm");
+      if (action.method !== "GET" || !action.readOnly || action.destructive || action.requiresConfirmation || agentAccess !== "auto") {
+        throw new Error(`Action "${actionId}" is not an automatic read-only action. Use topolo_call_action with confirmation.`);
+      }
+      const resource = optionalResourceContext(args);
+      return topolo.client.callAction(
+        actionId,
+        input ?? {},
+        resource ? { resource } : {}
+      );
+    }
+  },
+  {
+    name: "topolo_call_action",
+    title: "Call one Topolo action",
+    description: "Calls one exact action id. Mutating actions require confirm:true.",
+    requiredScopes: [],
+    destructive: true,
+    inputSchema: {
+      type: "object",
+      properties: {
+        actionId: { type: "string", minLength: 1 },
+        input: { type: "object", additionalProperties: true },
+        resourceType: { type: "string", description: "Optional app-local resource alias, such as workspace." },
+        resourceId: { type: "string", description: "Resource id. Required when resourceType is provided." },
+        confirm: { type: "boolean" }
+      },
+      required: ["actionId"],
+      additionalProperties: false
+    },
+    handler: async (topolo, args) => {
+      const actionId = typeof args["actionId"] === "string" ? args["actionId"].trim() : "";
+      if (!actionId) throw new Error("actionId is required.");
+      const input = args["input"];
+      if (input !== void 0 && (!input || typeof input !== "object" || Array.isArray(input))) {
+        throw new Error("input must be an object.");
+      }
+      const resource = optionalResourceContext(args);
+      return topolo.client.callAction(
+        actionId,
+        input ?? {},
+        {
+          confirm: args["confirm"] === true,
+          ...resource ? { resource } : {}
+        }
       );
-      if (!match) {
-        const known = catalog.map((e) => e.slug || e.appId).sort().filter((value) => typeof value === "string" && value.length > 0);
-        throw new Error(
-          `Unknown application "${application}". ${formatKnownValues(known, "applications")}`
-        );
-      }
-      return { application: match };
     }
   },
   {
@@ -2967,7 +3568,7 @@ var TOOLS = [
       properties: {
         application: {
           type: "string",
-          description: "Optional application ID from topolo_list_applications."
+          description: "Optional application ID from topolo_search_applications."
         }
       },
       additionalProperties: false
@@ -3007,7 +3608,7 @@ var TOOLS = [
       properties: {
         application: {
           type: "string",
-          description: "Optional application ID from topolo_list_applications."
+          description: "Optional application ID from topolo_search_applications."
         },
         failOn: {
           type: "string",
@@ -3041,7 +3642,7 @@ var TOOLS = [
   {
     name: "topolo_api_call",
     title: "Call any Topolo platform service",
-    description: "Low-level passthrough to any Topolo service. Use when no domain-specific tool exists for the operation you need. The request is signed with the current credential and scoped to the caller's organization \u2014 the target service will return 403 if your scopes do not permit the operation, even though this tool is advertised. Mutating calls (non-GET methods) require confirm:true. Call topolo_list_services first to discover callable service IDs; the SDK can also resolve live Auth-catalog service ids/slugs for newly registered API surfaces.",
+    description: "Low-level passthrough to any Topolo service. Use when no domain-specific tool exists for the operation you need. The request is signed with the current credential and scoped to the caller's organization \u2014 the target service will return 403 if your scopes do not permit the operation, even though this tool is advertised. Mutating calls (non-GET methods) require confirm:true. Call topolo_search_applications first to discover callable app IDs; the SDK can also resolve live Auth-catalog app ids/slugs for newly registered API surfaces.",
     requiredScopes: [],
     destructive: true,
     inputSchema: {
@@ -3049,7 +3650,7 @@ var TOOLS = [
       properties: {
         service: {
           type: "string",
-          description: "Target service ID from the platform registry."
+          description: "Target app ID from the platform registry."
         },
         method: {
           type: "string",
@@ -3072,7 +3673,7 @@ var TOOLS = [
         },
         resourceType: {
           type: "string",
-          description: "Optional workspace resource alias from topolo_list_services apiKeyResources. Aliases are app-defined, e.g. brand, mailbox, venue, merchant, or any other cataloged alias."
+          description: "Optional workspace resource alias from topolo_search_applications apiKeyResources. Aliases are app-defined, e.g. brand, mailbox, venue, merchant, or any other cataloged alias."
         },
         resourceId: {
           type: "string",
@@ -3090,7 +3691,7 @@ var TOOLS = [
       const service = args["service"];
       const path = args["path"];
       if (typeof service !== "string" || !service.trim()) {
-        throw new Error("service is required. Call topolo_list_services first to discover callable services.");
+        throw new Error("service is required. Call topolo_search_applications first to discover callable services.");
       }
       if (typeof path !== "string" || !path) {
         throw new Error("path is required");
@@ -3104,12 +3705,7 @@ var TOOLS = [
       const normalisedQuery = query && typeof query === "object" && !Array.isArray(query) ? Object.fromEntries(
         Object.entries(query).map(([k, v]) => [k, String(v)])
       ) : void 0;
-      const resourceType = typeof args["resourceType"] === "string" ? args["resourceType"].trim() : "";
-      const resourceId = typeof args["resourceId"] === "string" ? args["resourceId"].trim() : "";
-      if (resourceType && !resourceId || !resourceType && resourceId) {
-        throw new Error("resourceType and resourceId must be provided together.");
-      }
-      const resource = resourceType && resourceId ? { resourceType, resourceId } : void 0;
+      const resource = optionalResourceContext(args);
       return topolo.client.request({
         service: service.trim(),
         method,
@@ -3126,58 +3722,8 @@ function filterToolsByScopes(tools, scopes) {
   return tools.filter((t) => hasAnyScope(scopes, t.requiredScopes));
 }
 async function buildTopoloTools(topolo, scopes, tools = TOOLS) {
-  const baseTools = filterToolsByScopes(tools, scopes);
-  const actions = await topolo.client.listActions().catch(() => []);
-  const actionTools = actionsToToolDefs(actions);
-  return filterToolsByScopes([...baseTools, ...actionTools], scopes);
-}
-function effectiveAgentAccess(a) {
-  if (a.agentAccess) return a.agentAccess;
-  if (a.destructive) return "off";
-  if (a.readOnly && !a.requiresConfirmation) return "auto";
-  return "confirm";
-}
-function actionsToToolDefs(actions) {
-  return actions.map((action) => ({ action, access: effectiveAgentAccess(action) })).filter(({ access }) => access !== "off").map(({ action, access }) => ({
-    name: action.toolName || toolNameForAction(action),
-    title: action.title,
-    description: action.description,
-    requiredScopes: action.requiredPermission ? [action.requiredPermission] : [],
-    destructive: access === "confirm",
-    inputSchema: actionInputSchema(action, access),
-    handler: async (topolo, args) => {
-      const confirm = Boolean(args["confirm"]);
-      const input = { ...args };
-      delete input["confirm"];
-      return topolo.client.callAction(action.actionId, input, { confirm });
-    }
-  }));
-}
-function toolNameForAction(action) {
-  const service = (action.serviceSlug || action.appId || "service").replace(/^topolo-/, "").toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/^_+|_+$/g, "");
-  const name = action.name.toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/^_+|_+$/g, "");
-  return ["topolo", service, name].filter(Boolean).join("_").slice(0, 96);
-}
-function actionInputSchema(action, access = "auto") {
-  const schema = {
-    type: "object",
-    properties: {},
-    additionalProperties: false,
-    ...action.inputSchema
-  };
-  const properties = schema.properties && typeof schema.properties === "object" && !Array.isArray(schema.properties) ? { ...schema.properties } : {};
-  if (access === "confirm") {
-    properties.confirm = {
-      type: "boolean",
-      description: "Required for mutating actions. Explicit human-in-the-loop acknowledgement."
-    };
-  }
-  return {
-    ...schema,
-    type: "object",
-    properties,
-    additionalProperties: schema.additionalProperties ?? false
-  };
+  void topolo;
+  return filterToolsByScopes(tools, scopes);
 }
 function evaluateApplicationAuditGate(report, threshold) {
   const counts = {
@@ -3219,7 +3765,7 @@ function displayAppId(entry) {
   for (const value of [entry.slug, entry.name, entry.appId]) {
     if (typeof value !== "string" || !value.trim()) continue;
     for (const candidate of appIdCandidates(value)) {
-      if (Object.prototype.hasOwnProperty.call(DEFAULT_SERVICE_URLS, candidate)) {
+      if (Object.prototype.hasOwnProperty.call(DEFAULT_APP_URLS, candidate)) {
         return candidate;
       }
     }
@@ -3245,14 +3791,14 @@ function formatKnownValues(values, label) {
 
 // src/version.ts
 import { readFileSync } from "fs";
-import { dirname, join } from "path";
+import { dirname as dirname2, join as join2 } from "path";
 import { fileURLToPath } from "url";
 function readMcpVersion() {
   try {
-    const here = dirname(fileURLToPath(import.meta.url));
+    const here = dirname2(fileURLToPath(import.meta.url));
     const candidates = [
-      join(here, "package.json"),
-      join(here, "..", "package.json")
+      join2(here, "package.json"),
+      join2(here, "..", "package.json")
     ];
     for (const path of candidates) {
       try {
@@ -3331,15 +3877,22 @@ function toolError(message) {
 
 // src/index.ts
 async function main() {
-  const credential = resolveCredentialFromEnv();
+  const environment = normalizeEnvironment(process.env.TOPOLO_ENV);
+  const environmentCredential = resolveCredentialFromEnv();
+  let credential = environmentCredential;
+  if (!credential) {
+    credential = await refreshCredentialIfNeeded(environment);
+  }
   if (!credential) {
     process.stderr.write(
-      "TopoloMCP: TOPOLO_API_KEY or TOPOLO_ACCESS_TOKEN must be set in the environment.\n"
+      "TopoloMCP: no Topolo credential. Run `topolo auth login`, or set TOPOLO_API_KEY / TOPOLO_ACCESS_TOKEN.\n"
     );
     process.exit(1);
   }
-  const agentName = process.env.TOPOLO_AGENT_NAME;
-  const serviceUrls = resolveServiceUrlsFromEnv();
+  const config = await readConfig();
+  const profile = profileForEnvironment(config, environment);
+  const agentName = resolveAgentName(profile.agentName);
+  const serviceUrls = resolveServiceUrls(profile.serviceUrls, environment);
   const topolo = createTopolo({
     credential,
     agent: {
@@ -3348,7 +3901,8 @@ async function main() {
       ...agentName ? { agentName } : {}
     },
     serviceUrls,
-    requireConfirmForWrites: true
+    requireConfirmForWrites: true,
+    ...!environmentCredential ? { refreshCredential: () => refreshCredentialIfNeeded(environment, { force: true }) } : {}
   });
   const scopes = await loadScopes(topolo);
   const server = buildServer(topolo, scopes);
@@ -3356,7 +3910,7 @@ async function main() {
   await server.connect(transport);
   const toolNames = await advertisedToolNames(topolo, scopes);
   process.stderr.write(
-    `TopoloMCP v${MCP_VERSION} connected. Tools available: ${toolNames.join(", ") || "(none)"}
+    `TopoloMCP v${MCP_VERSION} connected (${environment}). Tools available: ${toolNames.join(", ") || "(none)"}
 `
   );
 }