@topolo/mcp 0.6.0 → 0.7.1

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;
@@ -66,6 +72,7 @@ var APP_API_URLS = {
   bugfix: "https://bugfix.topolo.app",
   bytes: "https://bytes.topolo.app",
   calendar: "https://calendar.topolo.app",
+  campaigns: "https://campaigns.topolo.app",
   capacity: "https://capacity.topolo.app",
   chat: "https://chat.topolo.app",
   commerce: "https://commerce.topolo.app",
@@ -324,6 +331,38 @@ var APPLICATIONS = {
       }
     ]
   },
+  "campaigns": {
+    "id": "campaigns",
+    "appDir": "TopoloCampaigns",
+    "name": "topolo-campaigns",
+    "packageName": "topolo-campaigns",
+    "productionUrl": "https://campaigns.topolo.app",
+    "services": [
+      "campaigns"
+    ],
+    "deployTargets": [
+      {
+        "name": "topolo-campaigns",
+        "kind": "worker",
+        "apiUrl": "https://campaigns.topolo.app",
+        "domains": [
+          "campaigns.topolo.app"
+        ],
+        "routes": [
+          "campaigns.topolo.app"
+        ],
+        "appId": "campaigns"
+      },
+      {
+        "name": "topolo-campaigns-api",
+        "kind": "worker",
+        "apiUrl": null,
+        "domains": [],
+        "routes": [],
+        "appId": null
+      }
+    ]
+  },
   "capacity": {
     "id": "capacity",
     "appDir": "TopoloCapacity",
@@ -1106,6 +1145,7 @@ var APPLICATIONS = {
           "topolo.io"
         ],
         "routes": [
+          "one.topolo.io",
           "topolo.io",
           "www.topolo.io"
         ],
@@ -2059,7 +2099,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 +2107,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 +2134,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 +2152,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 +2187,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 +2229,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 +2267,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) {
@@ -2238,9 +2305,8 @@ var TopoloClient = class _TopoloClient {
     );
   }
   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 +2380,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 +2396,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 +2421,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 +2452,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 +2470,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 {
+      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 entries;
+    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.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 +2697,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 +2735,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,6 +2789,8 @@ 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,
@@ -2601,6 +2802,7 @@ function normalizeActionCatalogEntry(item) {
     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 +2822,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) => {
@@ -2815,6 +3013,7 @@ var APP_API_URLS2 = {
   bugfix: "https://bugfix.topolo.app",
   bytes: "https://bytes.topolo.app",
   calendar: "https://calendar.topolo.app",
+  campaigns: "https://campaigns.topolo.app",
   capacity: "https://capacity.topolo.app",
   chat: "https://chat.topolo.app",
   commerce: "https://commerce.topolo.app",
@@ -3058,7 +3257,7 @@ async function resolveCredential(environment = selectedEnvironment()) {
   return profileForEnvironment(config, environment).credential ?? null;
 }
 var REFRESH_SKEW_SECONDS = 60;
-async function refreshCredentialIfNeeded(environment = selectedEnvironment()) {
+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);
@@ -3069,7 +3268,7 @@ async function refreshCredentialIfNeeded(environment = selectedEnvironment()) {
   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 (cred.expiresAt - REFRESH_SKEW_SECONDS > now) return cred;
+  if (!options.force && cred.expiresAt - REFRESH_SKEW_SECONDS > now) return cred;
   try {
     const oauth = new TopoloOAuth({
       serviceUrls: resolveServiceUrls(profile.serviceUrls, environment)
@@ -3084,9 +3283,20 @@ async function refreshCredentialIfNeeded(environment = selectedEnvironment()) {
       ...tokens.refresh_token ? { refreshToken: tokens.refresh_token } : { refreshToken: cred.refreshToken },
       expiresAt: Math.floor(Date.now() / 1e3) + tokens.expires_in
     };
-    await writeConfig(
-      environment === "production" && !config.profiles?.production ? { ...config, credential: refreshed } : writeProfileConfig(config, environment, { credential: refreshed })
-    );
+    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;
@@ -3170,6 +3380,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",
@@ -3185,22 +3404,32 @@ 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 actionService as the canonical selector for topolo_search_actions, plus 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,
           appId: entry.appId,
+          actionService: entry.appId,
           slug: entry.slug,
           name: entry.name,
           apiBaseUrl: entry.apiBaseUrl,
@@ -3213,13 +3442,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: {
@@ -3227,31 +3456,25 @@ var TOOLS = [
       properties: {
         service: {
           type: "string",
-          description: "Optional app id, slug, or name filter."
-        }
+          description: "Required application selector. Prefer actionService from topolo_search_applications; canonical app id, slug, and name are also accepted."
+        },
+        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",
@@ -3264,7 +3487,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"],
@@ -3275,18 +3498,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 };
     }
   },
   {
@@ -3300,7 +3603,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
@@ -3340,7 +3643,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",
@@ -3374,7 +3677,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 app IDs; the SDK can also resolve live Auth-catalog app 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: {
@@ -3405,7 +3708,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",
@@ -3423,7 +3726,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");
@@ -3437,12 +3740,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,
@@ -3459,58 +3757,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.appSlug || 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 = {
@@ -3665,7 +3913,8 @@ function toolError(message) {
 // src/index.ts
 async function main() {
   const environment = normalizeEnvironment(process.env.TOPOLO_ENV);
-  let credential = resolveCredentialFromEnv();
+  const environmentCredential = resolveCredentialFromEnv();
+  let credential = environmentCredential;
   if (!credential) {
     credential = await refreshCredentialIfNeeded(environment);
   }
@@ -3687,7 +3936,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);