@topolo/sdk 0.8.0 → 0.8.2

package/src/client.ts

@@ -1,1246 +0,0 @@
-import {
-  applyAuditHeaders,
-  applyAuthHeaders,
-  generateRequestId,
-  type AgentIdentity,
-  type TopoloCredential,
-} from './auth.js';
-import {
-  TopoloAuthError,
-  TopoloConfirmationRequiredError,
-  TopoloHttpError,
-  TopoloPermissionError,
-  TopoloSdkError,
-} from './errors.js';
-import {
-  DEFAULT_APP_URLS,
-  APPLICATIONS,
-  resolveCatalogServiceUrl,
-  resolveServiceUrl,
-  type AppApiId,
-} from './services.js';
-
-export interface TopoloClientOptions {
-  credential: TopoloCredential;
-  agent: AgentIdentity;
-  /** Per-service URL overrides. Useful for staging/dev. */
-  serviceUrls?: Record<string, string>;
-  /** Per-service TopoloAuth app id overrides from the owning app/deployment. */
-  appIds?: Record<string, string>;
-  /**
-   * When true, mutating helpers (POST/PUT/PATCH/DELETE) require callers to pass
-   * `{ confirm: true }`. Defaults to true. Set false only for trusted surfaces.
-   */
-  requireConfirmForWrites?: boolean;
-  /** HTTP request timeout (ms). Default 30s. */
-  timeoutMs?: number;
-  /** Injected fetch, for testing. Defaults to global fetch. */
-  fetch?: typeof fetch;
-  /**
-   * Refresh a rejected access-token credential. When supplied, the client
-   * retries one 401 response with the returned credential. Concurrent 401s
-   * share one refresh operation. API keys are never refreshed.
-   */
-  refreshCredential?: () => Promise<TopoloCredential | null>;
-  /**
-   * Observability hook. Fires once per request lifecycle (`request` at start,
-   * then exactly one of `response` or `error`). Safe to leave unset — off by
-   * default. Intended for CLI/MCP hosts to surface request-level diagnostics
-   * and for consumers building their own logging/tracing.
-   */
-  debug?: (event: TopoloDebugEvent) => void;
-}
-
-export type TopoloDebugEvent =
-  | {
-      phase: 'request';
-      method: string;
-      service: string;
-      path: string;
-      url: string;
-      requestId: string;
-    }
-  | {
-      phase: 'response';
-      method: string;
-      service: string;
-      path: string;
-      url: string;
-      requestId: string;
-      status: number;
-      durationMs: number;
-    }
-  | {
-      phase: 'error';
-      method: string;
-      service: string;
-      path: string;
-      url: string;
-      requestId: string;
-      durationMs: number;
-      error: string;
-      status?: number;
-    };
-
-export interface RequestOptions {
-  service: string;
-  /** Catalog-resolved origin for an action target. */
-  baseUrl?: string;
-  path: string;
-  method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
-  query?: Record<string, string | number | boolean | undefined>;
-  body?: unknown;
-  /** Workspace-boundary resource context for resource-scoped API keys. */
-  resource?: {
-    resourceType: string;
-    resourceId: string;
-  };
-  /** Explicit write-acknowledgement for mutating calls. */
-  confirm?: boolean;
-  /** Extra headers appended after auth/audit headers. */
-  headers?: Record<string, string>;
-  signal?: AbortSignal;
-}
-
-const WRITE_METHODS = new Set(['POST', 'PUT', 'PATCH', 'DELETE']);
-const TOPOLO_ACTION_ID_HEADER = 'X-Topolo-Action-Id';
-const TOPOLO_ACTION_NAME_HEADER = 'X-Topolo-Action-Name';
-const TOPOLO_RESOURCE_TYPE_HEADER = 'X-Topolo-Resource-Type';
-const TOPOLO_RESOURCE_ID_HEADER = 'X-Topolo-Resource-ID';
-
-const POSITIVE_CACHE_TTL_MS = 5 * 60 * 1000; // 5 minutes
-const NEGATIVE_CACHE_TTL_MS = 60 * 1000; // 1 minute
-
-interface AppIdCacheEntry {
-  value: string | null;
-  expiresAt: number;
-}
-
-/**
- * A single entry from the live platform service catalog. Returned by
- * {@link TopoloClient.listServices}. Shape mirrors the public-safe projection
- * from TopoloAuth `GET /api/services/catalog`.
- */
-export interface TopoloServiceCatalogEntry {
-  appId: string;
-  slug: string | null;
-  name: string | null;
-  description: string | null;
-  apiBaseUrl?: string | null;
-  launchUrl?: string | null;
-  status: string | null;
-  surfaceKind: string | null;
-  launchable: boolean;
-  permissions: string[];
-  apiKeyResource: TopoloApiKeyResourceMetadata | null;
-  apiKeyResources: TopoloApiKeyResourceMetadata[];
-}
-
-export interface TopoloApiKeyResourceMetadata {
-  resourceType: string;
-  label: string;
-  emptyLabel: string;
-  resourceConcept: 'workspace';
-  canonicalResourceType: 'workspace';
-  defaultEntitlement: 'enterprise';
-  exceptionPolicy: 'app_or_organization';
-}
-
-export interface TopoloActionCatalogEntry {
-  actionId: string;
-  target: string | null;
-  apiBaseUrl: string | null;
-  name: string;
-  toolName: string | null;
-  title: string;
-  description: string;
-  appId: string;
-  appSlug: string | null;
-  appName: string | null;
-  method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
-  path: string;
-  permissionName: string;
-  requiredPermission: string;
-  /** Static catalog permission or target-enforced input-dependent authorization. */
-  authorizationMode?: 'static' | 'runtime';
-  inputSchema: Record<string, unknown>;
-  outputSchema: Record<string, unknown>;
-  readOnly: boolean;
-  destructive: boolean;
-  requiresConfirmation: boolean;
-  /** Agent access tier. null/absent when the catalog does not specify one (consumers derive a default). */
-  agentAccess?: 'auto' | 'confirm' | 'off' | null;
-  status: string | null;
-  sourceRevision: string | null;
-}
-
-export interface TopoloCatalogPage {
-  nextCursor: string | null;
-  hasMore: boolean;
-}
-
-export interface TopoloServiceCatalogPage {
-  services: TopoloServiceCatalogEntry[];
-  page: TopoloCatalogPage;
-}
-
-export interface TopoloActionCatalogPage {
-  actions: TopoloActionCatalogEntry[];
-  page: TopoloCatalogPage;
-}
-
-export interface TopoloCatalogSearchOptions {
-  query?: string;
-  cursor?: string;
-  limit?: number;
-}
-
-export class TopoloClient {
-  private credential: TopoloCredential;
-  private readonly agent: AgentIdentity;
-  private readonly serviceUrls?: Record<string, string>;
-  private readonly appIds?: Record<string, string>;
-  private readonly requireConfirmForWrites: boolean;
-  private readonly timeoutMs: number;
-  private readonly fetchImpl: typeof fetch;
-  private readonly refreshCredential?: () => Promise<TopoloCredential | null>;
-  private refreshInFlight: Promise<TopoloCredential | null> | null = null;
-  private readonly debug?: (event: TopoloDebugEvent) => void;
-
-  /**
-   * Process-wide cache for slug → app-id lookups. Keyed by
-   * `${authBaseUrl}|${slug}` so multiple `TopoloClient` instances pointing at
-   * the same Auth share, but staging vs prod don't poison each other.
-   * Cleared via `TopoloClient.clearAppIdCache()` if a test needs it.
-   */
-  private static readonly appIdCache = new Map<string, AppIdCacheEntry>();
-
-  /**
-   * Drop the slug→app-id cache. Test-only — production callers should
-   * let the 5-minute TTL expire naturally.
-   */
-  static clearAppIdCache(): void {
-    TopoloClient.appIdCache.clear();
-  }
-
-  constructor(options: TopoloClientOptions) {
-    if (!options.credential) throw new TopoloAuthError('credential is required');
-    if (!options.agent?.clientName) throw new TopoloAuthError('agent.clientName is required');
-    this.credential = options.credential;
-    this.agent = options.agent;
-    this.serviceUrls = options.serviceUrls;
-    this.appIds = options.appIds;
-    this.requireConfirmForWrites = options.requireConfirmForWrites !== false;
-    this.timeoutMs = options.timeoutMs ?? 30_000;
-    this.fetchImpl = options.fetch ?? fetch;
-    this.refreshCredential = options.refreshCredential;
-    this.debug = options.debug;
-  }
-
-  private emit(event: TopoloDebugEvent): void {
-    if (!this.debug) return;
-    try {
-      this.debug(event);
-    } catch {
-      // Never let a debug consumer crash the request path.
-    }
-  }
-
-  /**
-   * Low-level JSON request. Prefer the typed module helpers (identity, crm, ...)
-   * for anything a caller would reach for; this stays exported for escape-hatch
-   * use and for the generic `topolo api` / MCP passthrough tool.
-   */
-  async request<T = unknown>(opts: RequestOptions): Promise<T> {
-    const method = opts.method ?? 'GET';
-    if (this.requireConfirmForWrites && WRITE_METHODS.has(method) && !opts.confirm) {
-      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 = 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) {
-      for (const [k, v] of Object.entries(opts.query)) {
-        if (v !== undefined) url.searchParams.set(k, String(v));
-      }
-    }
-
-    const headers = new Headers();
-    headers.set('Accept', 'application/json');
-    if (opts.body !== undefined) headers.set('Content-Type', 'application/json');
-    const platformAppId = resolveConfiguredAppId(resolvedService.serviceKey, this.appIds);
-    if (platformAppId) headers.set('X-App-ID', platformAppId);
-
-    applyAuthHeaders(headers, this.credential);
-    const requestId = generateRequestId();
-    applyAuditHeaders(headers, this.agent, requestId);
-
-    if (opts.headers) {
-      for (const [k, v] of Object.entries(opts.headers)) headers.set(k, v);
-    }
-    if (opts.resource) {
-      const resourceType = opts.resource.resourceType.trim();
-      const resourceId = opts.resource.resourceId.trim();
-      if (!resourceType || !resourceId) {
-        throw new TopoloSdkError(
-          'invalid_resource_context',
-          'Both resource.resourceType and resource.resourceId are required when resource context is provided.',
-        );
-      }
-      headers.set(TOPOLO_RESOURCE_TYPE_HEADER, resourceType);
-      headers.set(TOPOLO_RESOURCE_ID_HEADER, resourceId);
-    }
-
-    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 (): Promise<Response> => {
-      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 !== undefined ? JSON.stringify(opts.body) : null,
-          signal,
-        });
-      } finally {
-        clearTimeout(timeoutId);
-      }
-    };
-
-    let res: Response;
-    try {
-      const attemptedCredential = this.credential;
-      res = await fetchOnce();
-      if (
-        res.status === 401
-        && attemptedCredential.kind === 'access_token'
-        && this.refreshCredential
-      ) {
-        await res.body?.cancel().catch(() => undefined);
-        const refreshed = await this.refreshRejectedAccessToken(attemptedCredential.accessToken);
-        if (refreshed) {
-          applyAuthHeaders(headers, refreshed);
-          res = await fetchOnce();
-        }
-      }
-    } catch (err) {
-      this.emit({
-        phase: 'error',
-        method,
-        service: resolvedService.serviceKey,
-        path: opts.path,
-        url: urlStr,
-        requestId,
-        durationMs: Date.now() - startedAt,
-        error: err instanceof Error ? err.message : String(err),
-      });
-      throw err;
-    }
-
-    const contentType = res.headers.get('Content-Type') ?? '';
-    const parsed: unknown = contentType.includes('application/json')
-      ? await res.json().catch(() => null)
-      : await res.text().catch(() => null);
-
-    if (!res.ok) {
-      const durationMs = Date.now() - startedAt;
-      const message = describeError(parsed, `HTTP ${res.status}`);
-      this.emit({
-        phase: 'error',
-        method,
-        service: resolvedService.serviceKey,
-        path: opts.path,
-        url: urlStr,
-        requestId,
-        durationMs,
-        error: message,
-        status: res.status,
-      });
-      if (res.status === 401) throw new TopoloAuthError(describeError(parsed, 'Unauthorized'));
-      if (res.status === 403) {
-        throw new TopoloPermissionError(
-          describeError(parsed, 'Permission denied'),
-          extractRequired(parsed),
-        );
-      }
-      throw new TopoloHttpError(resolvedService.serviceKey, opts.path, res.status, parsed);
-    }
-
-    this.emit({
-      phase: 'response',
-      method,
-      service: resolvedService.serviceKey,
-      path: opts.path,
-      url: urlStr,
-      requestId,
-      status: res.status,
-      durationMs: Date.now() - startedAt,
-    });
-
-    return parsed as T;
-  }
-
-  private async refreshRejectedAccessToken(attemptedAccessToken: string): Promise<TopoloCredential | null> {
-    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;
-  }
-
-  private async resolveRequestService(service: string): Promise<{ serviceKey: string; baseUrl: string }> {
-    const serviceKey = normalizeLookupKey(service);
-    if (!serviceKey) {
-      throw new TopoloSdkError('unknown_service', 'service is required');
-    }
-
-    // auth + developers are DIRECT services resolved without a catalog lookup:
-    // developers serves the catalog itself, so resolving it via the catalog would
-    // recurse infinitely.
-    if (serviceKey === 'auth' || serviceKey === 'developers') {
-      const overrideUrl = resolveConfiguredServiceUrl(serviceKey, this.serviceUrls);
-      if (overrideUrl) return { serviceKey, baseUrl: overrideUrl };
-      // The catalog host (developers) defaults to the SAME environment as auth.
-      // Apps configure only `auth` per-env; derive developers from it (auth.X ->
-      // developers.X) so the catalog cutover needs no per-app config change.
-      if (serviceKey === 'developers') {
-        const derived = deriveDevelopersFromAuth(resolveConfiguredServiceUrl('auth', this.serviceUrls));
-        if (derived) return { serviceKey, baseUrl: derived };
-      }
-      return { serviceKey, baseUrl: DEFAULT_APP_URLS[serviceKey as 'auth' | 'developers'] };
-    }
-
-    const live = await this.resolveLiveCallableService(serviceKey);
-    if (live) {
-      const overrideUrl = resolveConfiguredServiceUrl(serviceKey, this.serviceUrls);
-      return overrideUrl ? { ...live, baseUrl: overrideUrl } : live;
-    }
-
-    throw new TopoloSdkError(
-      'unknown_service',
-      `Unknown Topolo app API "${service}". Run app discovery first and pass a callable app id or slug.`,
-    );
-  }
-
-  private async resolveLiveCallableService(serviceKey: string): Promise<{ serviceKey: string; baseUrl: string } | null> {
-    const match = await this.getService(serviceKey).catch(() => null);
-    if (!match || !catalogEntryMatches(match, serviceKey)) return null;
-    const baseUrl = resolveCatalogServiceUrl(match, {
-      serviceKey,
-      overrides: this.serviceUrls,
-    });
-    return baseUrl ? { serviceKey, baseUrl } : null;
-  }
-
-  /**
-   * Resolve a service-slug → opaque app-id via caller config or TopoloAuth.
-   *
-   * Cache: 5 minutes per process per `(slug, auth_base_url)`. Negative
-   * results (404) are cached for 60s so a typo doesn't hot-loop the
-   * resolver. Returns null when the slug isn't registered — callers decide
-   * whether to throw.
-   *
-   * No credential is sent: the endpoint is public (slugs aren't secret).
-   * This keeps the resolver usable during early bootstrap before a caller
-   * has acquired an access token.
-   */
-  async getAppIdBySlug(slug: string): Promise<string | null> {
-    if (typeof slug !== 'string') return null;
-    const normalized = slug.trim().toLowerCase();
-    if (!normalized) return null;
-
-    const configuredAppId = resolveConfiguredAppId(normalized, this.appIds);
-    if (configuredAppId) return configuredAppId;
-
-    // app-catalog greenfield: by-slug resolver lives on the Catalog (developers).
-    const authBase = resolveServiceUrl('developers', this.serviceUrls);
-    const cacheKey = `${authBase}|${normalized}`;
-    const now = Date.now();
-    const cached = TopoloClient.appIdCache.get(cacheKey);
-    if (cached && cached.expiresAt > now) {
-      return cached.value;
-    }
-
-    const url = new URL(
-      `/api/services/by-slug/${encodeURIComponent(normalized)}`,
-      authBase.endsWith('/') ? authBase : `${authBase}/`,
-    ).toString();
-
-    let res: Response;
-    try {
-      res = await this.fetchImpl(url, {
-        method: 'GET',
-        headers: { Accept: 'application/json' },
-      });
-    } catch {
-      // Network-level failure — don't poison cache; let the caller retry.
-      return null;
-    }
-
-    if (res.status === 404) {
-      TopoloClient.appIdCache.set(cacheKey, {
-        value: null,
-        expiresAt: now + NEGATIVE_CACHE_TTL_MS,
-      });
-      return null;
-    }
-
-    if (!res.ok) {
-      return null;
-    }
-
-    const body = (await res.json().catch(() => null)) as
-      | { success?: boolean; data?: { app_id?: unknown } }
-      | null;
-    const appId = body?.data?.app_id;
-    const value = typeof appId === 'string' && appId ? appId : null;
-    TopoloClient.appIdCache.set(cacheKey, {
-      value,
-      expiresAt: now + POSITIVE_CACHE_TTL_MS,
-    });
-    return value;
-  }
-
-  /**
-   * List the platform service catalog from the live registry
-   * (`GET /api/services/catalog` on TopoloAuth). Credential-aware: the
-   * caller's credential is attached, so the result only includes services the
-   * credential's organization and effective permissions can use.
-   *
-   * Security boundary: this never falls back to the generated global snapshot.
-   * The live Auth catalog is the authority because it is scoped to the caller's
-   * organization and effective permissions.
-   */
-  async searchServices(options: TopoloCatalogSearchOptions = {}): Promise<TopoloServiceCatalogPage> {
-    // app-catalog greenfield: the catalog moved to the Catalog (developers)
-    // service. Auth no longer owns the registry; it only provides scoping, which
-    // the Catalog composes server-side. Consumers pass the per-env developers URL.
-    const res = await this.request<
-      | { data?: { services?: unknown[]; page?: unknown } }
-      | { services?: unknown[]; page?: unknown }
-    >({
-      service: 'developers',
-      method: 'GET',
-      path: '/api/services/catalog',
-      query: catalogSearchQuery(options),
-    });
-    const raw =
-      (res as { data?: { services?: unknown[] } }).data?.services ??
-      (res as { services?: unknown[] }).services;
-    if (!Array.isArray(raw)) {
-      throw new TopoloSdkError(
-        'service_catalog_unavailable',
-        'TopoloAuth did not return a service catalog for the current credential.',
-      );
-    }
-
-    const entries: TopoloServiceCatalogEntry[] = [];
-    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;
-      const permissions = Array.isArray(s.granted_permissions)
-        ? s.granted_permissions
-            .filter((permission): permission is string => typeof permission === 'string' && permission.trim().length > 0)
-        : [];
-      const catalogApiKeyResources = normalizeApiKeyResourceMetadataList(
-        s.api_key_resources ?? s.apiKeyResources,
-      );
-      const apiKeyResource =
-        normalizeApiKeyResourceMetadata(s.api_key_resource ?? s.apiKeyResource) ??
-        catalogApiKeyResources[0] ??
-        null;
-      const apiKeyResources = catalogApiKeyResources.length > 0
-        ? catalogApiKeyResources
-        : apiKeyResource
-          ? [apiKeyResource]
-          : [];
-      entries.push({
-        appId,
-        slug: typeof s.app_slug === 'string' ? s.app_slug : null,
-        name: typeof s.name === 'string' ? s.name : null,
-        description:
-          typeof s.description === 'string' ? s.description : null,
-        apiBaseUrl:
-          typeof s.api_base_url === 'string'
-            ? s.api_base_url
-            : typeof s.apiBaseUrl === 'string'
-              ? s.apiBaseUrl
-              : null,
-        launchUrl:
-          typeof s.launch_url === 'string'
-            ? s.launch_url
-            : typeof s.launchUrl === 'string'
-              ? s.launchUrl
-              : null,
-        status: typeof s.status === 'string' ? s.status : null,
-        surfaceKind:
-          typeof s.surface_kind === 'string' ? s.surface_kind : null,
-        launchable: s.launchable === true,
-        permissions,
-        apiKeyResource,
-        apiKeyResources,
-      });
-    }
-    const page = normalizeCatalogPage(
-      (res as { data?: { page?: unknown } }).data?.page ?? (res as { page?: unknown }).page,
-    );
-    return { services: entries, page };
-  }
-
-  /** @deprecated Prefer searchServices() so callers retain the continuation cursor. */
-  async listServices(options: TopoloCatalogSearchOptions = {}): Promise<TopoloServiceCatalogEntry[]> {
-    return (await this.searchServices(options)).services;
-  }
-
-  async getService(application: string): Promise<TopoloServiceCatalogEntry> {
-    const needle = application.trim();
-    if (!needle) throw new TopoloSdkError('unknown_service', 'application is required');
-    const res = await this.request<
-      | { data?: { application?: unknown } }
-      | { application?: unknown }
-    >({
-      service: 'developers',
-      method: 'GET',
-      path: '/api/services/catalog',
-      query: { application: needle },
-    });
-    const raw = (res as { data?: { application?: unknown } }).data?.application
-      ?? (res as { application?: unknown }).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
-   * from the Catalog registry, scoping from Auth). The response is scoped to the
-   * caller's organization and effective permissions; no bundled/static app
-   * action list is used as an authorization source.
-   */
-  async searchActions(
-    options: TopoloCatalogSearchOptions & { service: string },
-  ): Promise<TopoloActionCatalogPage> {
-    if (!options.service?.trim()) {
-      throw new TopoloSdkError('service_required', 'service is required for bounded action discovery');
-    }
-    const res = await this.request<
-      | { data?: { actions?: unknown[]; page?: unknown } }
-      | { actions?: unknown[]; page?: unknown }
-    >({
-      service: 'developers',
-      method: 'GET',
-      path: '/api/actions/catalog',
-      query: { service: options.service, ...catalogSearchQuery(options) },
-    });
-    const raw =
-      (res as { data?: { actions?: unknown[] } }).data?.actions ??
-      (res as { actions?: unknown[] }).actions;
-    if (!Array.isArray(raw)) {
-      throw new TopoloSdkError(
-        'action_catalog_unavailable',
-        'TopoloAuth did not return an action catalog for the current credential.',
-      );
-    }
-
-    const entries = raw
-      .map((item) => normalizeActionCatalogEntry(item))
-      .filter((entry): entry is TopoloActionCatalogEntry => Boolean(entry));
-    return {
-      actions: entries,
-      page: normalizeCatalogPage(
-        (res as { data?: { page?: unknown } }).data?.page ?? (res as { page?: unknown }).page,
-      ),
-    };
-  }
-
-  /** @deprecated Prefer searchActions() so callers retain the continuation cursor. */
-  async listActions(options?: TopoloCatalogSearchOptions & { service: string }): Promise<TopoloActionCatalogEntry[]> {
-    if (!options) {
-      throw new TopoloSdkError('service_required', 'service is required for bounded action discovery');
-    }
-    return (await this.searchActions(options)).actions;
-  }
-
-  async getAction(action: string): Promise<TopoloActionCatalogEntry> {
-    const actionId = action.trim();
-    if (!actionId) {
-      throw new TopoloSdkError(
-        'unknown_action',
-        'action id is required',
-      );
-    }
-    const res = await this.request<
-      | { data?: { action?: unknown } }
-      | { action?: unknown }
-    >({
-      service: 'developers',
-      method: 'GET',
-      path: '/api/actions/catalog',
-      query: { actionId },
-    });
-    const raw = (res as { data?: { action?: unknown } }).data?.action
-      ?? (res as { action?: unknown }).action;
-    const match = normalizeActionCatalogEntry(raw);
-    if (!match) throw new TopoloSdkError('unknown_action', `Unknown Topolo action "${action}".`);
-    return match;
-  }
-
-  async callAction<T = unknown>(
-    action: string,
-    input: Record<string, unknown> = {},
-    options: {
-      confirm?: boolean;
-      resource?: { resourceType: string; resourceId: string };
-    } = {},
-  ): Promise<T> {
-    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<T>({
-      service,
-      ...(entry.apiBaseUrl ? { baseUrl: entry.apiBaseUrl } : {}),
-      method: entry.method,
-      path: mapped.path,
-      ...(mapped.query ? { query: mapped.query } : {}),
-      ...(mapped.body !== undefined ? { body: mapped.body } : {}),
-      ...(options.resource ? { resource: options.resource } : {}),
-      headers: {
-        [TOPOLO_ACTION_ID_HEADER]: entry.actionId,
-        [TOPOLO_ACTION_NAME_HEADER]: entry.name,
-      },
-      confirm: options.confirm === true,
-    });
-  }
-
-  /**
-   * Bundled generated registry for tooling that audits platform packaging, not
-   * for deciding what the current credential may use.
-   */
-  listBundledServices(): TopoloServiceCatalogEntry[] {
-    const apps = Object.values(APPLICATIONS) as ReadonlyArray<{
-      id: string;
-      name?: string;
-      productionUrl?: string | null;
-    }>;
-    return apps.map((app) => ({
-      appId: app.id,
-      slug: app.id,
-      name: app.name ?? app.id,
-      description: null,
-      apiBaseUrl: null,
-      launchUrl: app.productionUrl ?? null,
-      status: 'bundled',
-      surfaceKind: 'application',
-      launchable: Boolean(app.productionUrl),
-      permissions: [],
-      apiKeyResource: null,
-      apiKeyResources: [],
-    }));
-  }
-
-  /**
-   * Introspect the current credential. Returns the caller's resolved identity,
-   * organization, and permission set. Used by CLI `whoami` and by MCP to gate
-   * advertised tools by scope.
-   *
-   * Both JWT access tokens and platform API keys are resolved via the unified
-   * `GET /api/auth/me` endpoint on TopoloAuth, which does not require service
-   * credentials. The caller's possession of the credential secret is proof.
-   */
-  async introspect(): Promise<CredentialIntrospection> {
-    const res = await this.request<{ data: AuthMePayload } | AuthMePayload>({
-      service: 'auth',
-      method: 'GET',
-      path: '/api/auth/me',
-    });
-
-    const payload: AuthMePayload = (res as { data?: AuthMePayload }).data ?? (res as AuthMePayload);
-    const user = payload.user;
-    const organization = payload.organization;
-    const kind: CredentialIntrospection['kind'] =
-      payload.credentialType === 'api_key' ? 'api_key' : 'access_token';
-
-    return {
-      kind,
-      user: {
-        id: user.id,
-        email: user.email,
-        name: user.name ?? null,
-        role: user.role ?? (kind === 'api_key' ? 'service' : 'member'),
-        permissions: payload.permissions ?? user.permissions ?? [],
-      },
-      organization: organization
-        ? {
-            id: organization.id,
-            slug: organization.slug,
-            name: organization.name ?? organization.slug,
-          }
-        : user.orgId && user.orgSlug
-          ? { id: user.orgId, slug: user.orgSlug, name: user.orgSlug }
-          : null,
-    };
-  }
-}
-
-function resolveConfiguredAppId(
-  slug: string,
-  appIds?: Record<string, string>,
-): string | null {
-  for (const serviceKey of serviceKeyCandidates(slug)) {
-    const configured = appIds?.[serviceKey as AppApiId];
-    if (typeof configured === 'string' && configured.trim()) return configured.trim();
-
-    const envKey = `TOPOLO_APP_ID_${serviceKey.replace(/\./g, '_').toUpperCase()}`;
-    const envValue = typeof process !== 'undefined' ? process.env?.[envKey] : undefined;
-    if (typeof envValue === 'string' && envValue.trim()) return envValue.trim();
-  }
-
-  return null;
-}
-
-function normalizeApiKeyResourceMetadata(input: unknown): TopoloApiKeyResourceMetadata | null {
-  if (!isRecord(input)) return null;
-  const resourceType = readString(input.resourceType ?? input.resource_type);
-  const label = readString(input.label);
-  const emptyLabel = readString(input.emptyLabel ?? input.empty_label);
-  const resourceConcept = readString(input.resourceConcept ?? input.resource_concept);
-  const canonicalResourceType = readString(input.canonicalResourceType ?? input.canonical_resource_type);
-  const defaultEntitlement = readString(input.defaultEntitlement ?? input.default_entitlement);
-  const exceptionPolicy = readString(input.exceptionPolicy ?? input.exception_policy);
-
-  if (
-    !resourceType ||
-    !label ||
-    !emptyLabel ||
-    resourceConcept !== 'workspace' ||
-    canonicalResourceType !== 'workspace' ||
-    defaultEntitlement !== 'enterprise' ||
-    exceptionPolicy !== 'app_or_organization'
-  ) {
-    return null;
-  }
-
-  return {
-    resourceType,
-    label,
-    emptyLabel,
-    resourceConcept,
-    canonicalResourceType,
-    defaultEntitlement,
-    exceptionPolicy,
-  };
-}
-
-function normalizeApiKeyResourceMetadataList(input: unknown): TopoloApiKeyResourceMetadata[] {
-  if (!Array.isArray(input)) return [];
-  const resources: TopoloApiKeyResourceMetadata[] = [];
-  const seenTypes = new Set<string>();
-  for (const item of input) {
-    const resource = normalizeApiKeyResourceMetadata(item);
-    if (!resource || seenTypes.has(resource.resourceType)) continue;
-    seenTypes.add(resource.resourceType);
-    resources.push(resource);
-  }
-  return resources;
-}
-
-function readString(value: unknown): string {
-  return typeof value === 'string' ? value.trim() : '';
-}
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
-
-function resolveConfiguredServiceUrl(
-  slug: string,
-  serviceUrls?: Record<string, string>,
-): string | null {
-  for (const serviceKey of serviceKeyCandidates(slug)) {
-    const configured = serviceUrls?.[serviceKey];
-    if (typeof configured === 'string' && configured.trim()) return configured.trim();
-
-    const envKey = `TOPOLO_SERVICE_URL_${serviceKey.replace(/\./g, '_').toUpperCase()}`;
-    const envValue = typeof process !== 'undefined' ? process.env?.[envKey] : undefined;
-    if (typeof envValue === 'string' && envValue.trim()) return envValue.trim();
-  }
-
-  return null;
-}
-
-function serviceKeyCandidates(slug: string): string[] {
-  const normalized = normalizeLookupKey(slug);
-  const withoutTopolo = normalized.startsWith('topolo-')
-    ? normalized.slice('topolo-'.length)
-    : normalized;
-  return [...new Set([
-    normalized,
-    normalized.replace(/-/g, '_'),
-    withoutTopolo,
-    withoutTopolo.replace(/-/g, '_'),
-  ])];
-}
-
-function normalizeLookupKey(value: string): string {
-  return String(value || '').trim().toLowerCase().replace(/\s+/g, '-');
-}
-
-function requireHttpOrigin(value: string): string {
-  let url: 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;
-}
-
-/**
- * Derive the Catalog (developers) base URL from a configured auth base URL by
- * swapping the leading `auth` host label for `developers` (auth.stg.topolo.us ->
- * developers.stg.topolo.us). Returns null if the auth URL is absent or doesn't
- * start with the `auth.` label, so the caller falls back to the bundled default.
- */
-function deriveDevelopersFromAuth(authUrl: string | null | undefined): string | null {
-  if (!authUrl) return null;
-  try {
-    const url = new URL(authUrl);
-    if (!/^auth\./i.test(url.hostname)) return null;
-    url.hostname = url.hostname.replace(/^auth\./i, 'developers.');
-    return url.origin;
-  } catch {
-    return null;
-  }
-}
-
-function catalogEntryMatches(entry: TopoloServiceCatalogEntry, needle: string): boolean {
-  return catalogEntryLookupKeys(entry).includes(needle);
-}
-
-function catalogEntryLookupKeys(entry: TopoloServiceCatalogEntry): string[] {
-  const values = [entry.appId, entry.slug, entry.name].filter((value): value is string => (
-    typeof value === 'string' && value.trim().length > 0
-  ));
-  const keys = new Set<string>();
-  for (const value of values) {
-    const normalized = normalizeLookupKey(value);
-    if (!normalized) continue;
-    for (const candidate of serviceKeyCandidates(normalized)) {
-      keys.add(candidate);
-    }
-  }
-  return [...keys];
-}
-
-function catalogSearchQuery(options: TopoloCatalogSearchOptions): Record<string, string | number> {
-  const query: Record<string, string | number> = {};
-  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: unknown): TopoloCatalogPage {
-  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: unknown): TopoloServiceCatalogEntry | null {
-  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): permission is string => 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: unknown): TopoloActionCatalogEntry | null {
-  if (!item || typeof item !== 'object' || Array.isArray(item)) return null;
-  const a = item as Record<string, unknown>;
-  const actionId = pickActionString(a.action_id) ?? pickActionString(a.actionId);
-  const name = pickActionString(a.name);
-  const appId = pickActionString(a.app_id) ?? pickActionString(a.appId);
-  const method = pickActionString(a.method)?.toUpperCase();
-  const path = pickActionString(a.path);
-  if (!actionId || !name || !appId || !method || !path || !isHttpMethod(method)) {
-    return null;
-  }
-
-  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,
-    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),
-    destructive: Boolean(a.destructive),
-    requiresConfirmation: Boolean(a.requires_confirmation ?? a.requiresConfirmation),
-    agentAccess: pickAgentAccess(a.agent_access ?? a.agentAccess),
-    status: pickActionString(a.status),
-    sourceRevision: pickActionString(a.source_revision) ?? pickActionString(a.sourceRevision),
-  };
-}
-
-function isHttpMethod(value: string): value is TopoloActionCatalogEntry['method'] {
-  return value === 'GET' || value === 'POST' || value === 'PUT' || value === 'PATCH' || value === 'DELETE';
-}
-
-function pickActionString(value: unknown): string | null {
-  return typeof value === 'string' && value.trim() ? value.trim() : null;
-}
-
-function pickAgentAccess(value: unknown): 'auto' | 'confirm' | 'off' | null {
-  return value === 'auto' || value === 'confirm' || value === 'off' ? value : null;
-}
-
-function pickAuthorizationMode(value: unknown): 'static' | 'runtime' {
-  return value === 'runtime' ? 'runtime' : 'static';
-}
-
-function plainObject(value: unknown): Record<string, unknown> {
-  return value && typeof value === 'object' && !Array.isArray(value)
-    ? value as Record<string, unknown>
-    : {};
-}
-
-function normalizeActionLookupKey(value: string): string {
-  return String(value || '').trim().toLowerCase();
-}
-
-function actionEntryMatches(entry: TopoloActionCatalogEntry, needle: string): boolean {
-  if (!needle) return false;
-  return [entry.actionId, entry.name, entry.toolName]
-    .filter((value): value is string => typeof value === 'string' && value.length > 0)
-    .some((value) => value.toLowerCase() === needle);
-}
-
-function mapActionInput(
-  action: TopoloActionCatalogEntry,
-  input: Record<string, unknown>,
-): { path: string; query?: Record<string, string | number | boolean>; body?: unknown } {
-  const remaining: Record<string, unknown> = { ...(input || {}) };
-  const path = action.path.replace(/\{([a-zA-Z0-9_]+)\}/g, (_match, key: string) => {
-    const value = remaining[key];
-    if (value === undefined || value === null || value === '') {
-      throw new TopoloSdkError(
-        'invalid_action_input',
-        `Action "${action.name}" requires path parameter "${key}".`,
-      );
-    }
-    delete remaining[key];
-    return encodeURIComponent(String(value));
-  });
-
-  const explicitQuery = plainObject(remaining.query);
-  delete remaining.query;
-  const explicitBody = Object.prototype.hasOwnProperty.call(remaining, 'body')
-    ? remaining.body
-    : undefined;
-  delete remaining.body;
-
-  if (action.method === 'GET') {
-    return {
-      path,
-      query: objectToQuery({ ...remaining, ...explicitQuery }),
-    };
-  }
-
-  const query = objectToQuery(explicitQuery);
-  const body = explicitBody !== undefined ? explicitBody : remaining;
-  return {
-    path,
-    ...(query ? { query } : {}),
-    body,
-  };
-}
-
-function objectToQuery(value: Record<string, unknown>): Record<string, string | number | boolean> | undefined {
-  const query: Record<string, string | number | boolean> = {};
-  for (const [key, raw] of Object.entries(value)) {
-    if (raw === undefined || raw === null) continue;
-    if (typeof raw === 'string' || typeof raw === 'number' || typeof raw === 'boolean') {
-      query[key] = raw;
-    } else {
-      query[key] = JSON.stringify(raw);
-    }
-  }
-  return Object.keys(query).length > 0 ? query : undefined;
-}
-
-interface AuthMePayload {
-  credentialType?: 'access_token' | 'api_key';
-  user: RawUser;
-  organization?: RawOrg | null;
-  permissions?: string[];
-}
-
-export interface CredentialIntrospection {
-  kind: 'api_key' | 'access_token';
-  user: {
-    id: string;
-    email: string;
-    name: string | null;
-    role: string;
-    permissions: string[];
-  };
-  organization: {
-    id: string;
-    slug: string;
-    name: string;
-  } | null;
-}
-
-interface RawUser {
-  id: string;
-  email: string;
-  name?: string;
-  role?: string;
-  permissions?: string[];
-  orgId?: string;
-  orgSlug?: string;
-  organization?: { id: string; slug: string; name: string } | null;
-}
-
-interface RawOrg {
-  id: string;
-  slug: string;
-  name?: string;
-}
-
-function describeError(body: unknown, fallback: string): string {
-  if (body && typeof body === 'object') {
-    const maybe = body as { error?: unknown; message?: unknown };
-    const resolved = pickString(maybe.message) ?? pickString(maybe.error);
-    if (resolved) return resolved;
-  }
-  return fallback;
-}
-
-function pickString(value: unknown): string | undefined {
-  if (typeof value === 'string' && value.trim().length > 0) return value;
-  if (value && typeof value === 'object') {
-    const nested = value as { message?: unknown; description?: unknown };
-    if (typeof nested.message === 'string' && nested.message.trim().length > 0) return nested.message;
-    if (typeof nested.description === 'string' && nested.description.trim().length > 0)
-      return nested.description;
-  }
-  return undefined;
-}
-
-function extractRequired(body: unknown): string[] {
-  if (body && typeof body === 'object') {
-    const maybe = body as { required?: unknown };
-    if (Array.isArray(maybe.required)) return maybe.required.map(String);
-  }
-  return [];
-}
-
-function mergeSignals(a: AbortSignal, b: AbortSignal): AbortSignal {
-  if (a.aborted) return a;
-  if (b.aborted) return b;
-  const controller = new AbortController();
-  const onAbort = () => controller.abort();
-  a.addEventListener('abort', onAbort, { once: true });
-  b.addEventListener('abort', onAbort, { once: true });
-  return controller.signal;
-}