@topolo/sdk 0.4.9 → 0.5.0

package/src/client.test.ts

@@ -16,20 +16,20 @@ function stubFetch(responses: Array<{ status?: number; body?: unknown; contentTy
 }
 
 const AGENT = { clientName: 'topolo-test', clientVersion: '0.0.0' };
-const SERVICE_LOOKUP = { body: { success: true, data: { service_id: 'service_test' } } };
+const SERVICE_LOOKUP = { body: { success: true, data: { app_id: 'app_test' } } };
 const MAIL_CATALOG = {
   body: {
     data: {
       services: [
         {
-          service_id: 'srv_mail',
+          app_id: 'app_mail',
           app_slug: 'topolo-mail',
           name: 'Topolo Mail',
           api_base_url: 'https://mail-api.topolo.app',
           launch_url: 'https://mail.topolo.app',
           surface_kind: 'api',
           status: 'active',
-          granted_permissions: ['srv_mail.messages:read'],
+          granted_permissions: ['app_mail.messages:read'],
         },
       ],
     },
@@ -40,18 +40,18 @@ const ACTION_CATALOG = {
     data: {
       actions: [
         {
-          action_id: 'srv_mail.messages.list',
+          action_id: 'app_mail.messages.list',
           name: 'messages.list',
           tool_name: 'topolo_mail_messages_list',
           title: 'List messages',
           description: 'List Mail messages',
-          service_id: 'srv_mail',
+          app_id: 'app_mail',
           service_slug: 'topolo-mail',
           service_name: 'Topolo Mail',
           method: 'GET',
           path: '/api/mail/mailboxes/{mailboxId}/messages',
           permission_name: 'messages:read',
-          required_permission: 'srv_mail.messages:read',
+          required_permission: 'app_mail.messages:read',
           input_schema: { type: 'object' },
           output_schema: {},
           read_only: true,
@@ -59,18 +59,18 @@ const ACTION_CATALOG = {
           requires_confirmation: false,
         },
         {
-          action_id: 'srv_mail.messages.get',
+          action_id: 'app_mail.messages.get',
           name: 'messages.get',
           tool_name: 'topolo_mail_messages_get',
           title: 'Get message',
           description: 'Get Mail message',
-          service_id: 'srv_mail',
+          app_id: 'app_mail',
           service_slug: 'topolo-mail',
           service_name: 'Topolo Mail',
           method: 'GET',
           path: '/api/mail/mailboxes/{mailboxId}/messages/{messageId}',
           permission_name: 'messages:read',
-          required_permission: 'srv_mail.messages:read',
+          required_permission: 'app_mail.messages:read',
           input_schema: { type: 'object' },
           output_schema: {},
           read_only: true,
@@ -78,18 +78,18 @@ const ACTION_CATALOG = {
           requires_confirmation: false,
         },
         {
-          action_id: 'srv_mail.messages.send',
+          action_id: 'app_mail.messages.send',
           name: 'messages.send',
           tool_name: 'topolo_mail_messages_send',
           title: 'Send message',
           description: 'Send Mail message',
-          service_id: 'srv_mail',
+          app_id: 'app_mail',
           service_slug: 'topolo-mail',
           service_name: 'Topolo Mail',
           method: 'POST',
           path: '/api/mail/mailboxes/{mailboxId}/messages',
           permission_name: 'messages:send',
-          required_permission: 'srv_mail.messages:send',
+          required_permission: 'app_mail.messages:send',
           input_schema: { type: 'object' },
           output_schema: {},
           read_only: false,
@@ -110,7 +110,7 @@ function requestCalls(calls: Array<{ url: string; init: RequestInit }>) {
 }
 
 beforeEach(() => {
-  TopoloClient.clearServiceIdCache();
+  TopoloClient.clearAppIdCache();
 });
 
 describe('TopoloClient.request', () => {
@@ -120,12 +120,12 @@ describe('TopoloClient.request', () => {
       credential: { kind: 'access_token', accessToken: 'tok_abc' },
       agent: AGENT,
       fetch: impl,
-      serviceIds: { auth: 'service_auth' },
+      appIds: { auth: 'service_auth' },
     });
     await client.request({ service: 'auth', path: '/api/me' });
     const headers = new Headers(requestCalls(calls)[0]!.init.headers);
     expect(headers.get('Authorization')).toBe('Bearer tok_abc');
-    expect(headers.get('X-Service-ID')).toBe('service_auth');
+    expect(headers.get('X-App-ID')).toBe('service_auth');
     expect(headers.get('X-Topolo-Client')).toBe('topolo-test/0.0.0');
     expect(headers.get('X-Topolo-Request-Id')).toMatch(/.+/);
   });
@@ -384,9 +384,9 @@ describe('TopoloClient.debug hook', () => {
   });
 });
 
-describe('TopoloClient.getServiceIdBySlug', () => {
+describe('TopoloClient.getAppIdBySlug', () => {
   function freshClient(impl: typeof fetch, serviceUrls?: Record<string, string>) {
-    TopoloClient.clearServiceIdCache();
+    TopoloClient.clearAppIdCache();
     return new TopoloClient({
       credential: { kind: 'api_key', apiKey: 'x' },
       agent: AGENT,
@@ -402,19 +402,19 @@ describe('TopoloClient.getServiceIdBySlug', () => {
       agent: AGENT,
       fetch: impl,
       serviceUrls: { auth: 'https://auth.example.com', developers: 'https://auth.example.com' } as never,
-      serviceIds: { notify: 'service_notify' },
+      appIds: { notify: 'service_notify' },
     });
-    const id = await client.getServiceIdBySlug('topolo-notify');
+    const id = await client.getAppIdBySlug('topolo-notify');
     expect(id).toBe('service_notify');
     expect(calls).toEqual([]);
   });
 
   it('falls back to /api/services/by-slug/:slug for unknown slugs', async () => {
     const { impl, calls } = stubFetch([
-      { body: { success: true, data: { service_id: 'service_abc123', api_base_url: 'https://x-api' } } },
+      { body: { success: true, data: { app_id: 'service_abc123', api_base_url: 'https://x-api' } } },
     ]);
     const client = freshClient(impl, { auth: 'https://auth.example.com', developers: 'https://auth.example.com' });
-    const id = await client.getServiceIdBySlug('external-service');
+    const id = await client.getAppIdBySlug('external-service');
     expect(id).toBe('service_abc123');
     expect(calls[0]!.url).toBe('https://auth.example.com/api/services/by-slug/external-service');
     // No auth header — endpoint is public.
@@ -426,27 +426,27 @@ describe('TopoloClient.getServiceIdBySlug', () => {
   it('returns null on 404 and caches the negative result', async () => {
     const { impl, calls } = stubFetch([{ status: 404, body: { success: false } }]);
     const client = freshClient(impl, { auth: 'https://auth.example.com', developers: 'https://auth.example.com' });
-    expect(await client.getServiceIdBySlug('nope')).toBeNull();
-    expect(await client.getServiceIdBySlug('nope')).toBeNull();
+    expect(await client.getAppIdBySlug('nope')).toBeNull();
+    expect(await client.getAppIdBySlug('nope')).toBeNull();
     expect(calls.length).toBe(1);
   });
 
   it('caches positive results across calls', async () => {
     const { impl, calls } = stubFetch([
-      { body: { success: true, data: { service_id: 'service_external' } } },
+      { body: { success: true, data: { app_id: 'service_external' } } },
     ]);
     const client = freshClient(impl, { auth: 'https://auth.example.com', developers: 'https://auth.example.com' });
-    expect(await client.getServiceIdBySlug('external-service')).toBe('service_external');
-    expect(await client.getServiceIdBySlug('external-service')).toBe('service_external');
+    expect(await client.getAppIdBySlug('external-service')).toBe('service_external');
+    expect(await client.getAppIdBySlug('external-service')).toBe('service_external');
     expect(calls.length).toBe(1);
   });
 
   it('normalizes slug case + whitespace before hitting the network', async () => {
     const { impl, calls } = stubFetch([
-      { body: { success: true, data: { service_id: 'service_x' } } },
+      { body: { success: true, data: { app_id: 'service_x' } } },
     ]);
     const client = freshClient(impl, { auth: 'https://auth.example.com', developers: 'https://auth.example.com' });
-    await client.getServiceIdBySlug('  EXTERNAL-SERVICE  ');
+    await client.getAppIdBySlug('  EXTERNAL-SERVICE  ');
     expect(calls[0]!.url).toBe('https://auth.example.com/api/services/by-slug/external-service');
   });
 
@@ -457,21 +457,21 @@ describe('TopoloClient.getServiceIdBySlug', () => {
         throws = false;
         throw new Error('ECONNREFUSED');
       }
-      return new Response(JSON.stringify({ success: true, data: { service_id: 'service_y' } }), {
+      return new Response(JSON.stringify({ success: true, data: { app_id: 'service_y' } }), {
         status: 200,
         headers: { 'Content-Type': 'application/json' },
       });
     }) as unknown as typeof fetch;
-    TopoloClient.clearServiceIdCache();
+    TopoloClient.clearAppIdCache();
     const client = new TopoloClient({
       credential: { kind: 'api_key', apiKey: 'x' },
       agent: AGENT,
       fetch: impl,
       serviceUrls: { auth: 'https://auth.example.com', developers: 'https://auth.example.com' } as never,
     });
-    expect(await client.getServiceIdBySlug('flaky')).toBeNull();
+    expect(await client.getAppIdBySlug('flaky')).toBeNull();
     // Second call retries — earlier null was not cached.
-    expect(await client.getServiceIdBySlug('flaky')).toBe('service_y');
+    expect(await client.getAppIdBySlug('flaky')).toBe('service_y');
   });
 });
 
@@ -483,7 +483,7 @@ describe('TopoloClient.listServices', () => {
           data: {
             services: [
               {
-                service_id: 'srv_wRCnLLbtvmVT',
+                app_id: 'app_topolo_director',
                 app_slug: 'topolo-director',
                 name: 'Topolo Director',
                 description: 'Demo control plane',
@@ -512,7 +512,7 @@ describe('TopoloClient.listServices', () => {
                     exceptionPolicy: 'app_or_organization',
                   },
                 ],
-                granted_permissions: ['srv_wRCnLLbtvmVT.dashboard:read'],
+                granted_permissions: ['app_topolo_director.dashboard:read'],
               },
             ],
           },
@@ -528,7 +528,7 @@ describe('TopoloClient.listServices', () => {
     const out = await client.listServices();
     expect(out).toEqual([
       {
-        serviceId: 'srv_wRCnLLbtvmVT',
+        appId: 'app_topolo_director',
         slug: 'topolo-director',
         name: 'Topolo Director',
         description: 'Demo control plane',
@@ -557,7 +557,7 @@ describe('TopoloClient.listServices', () => {
             exceptionPolicy: 'app_or_organization',
           },
         ],
-        permissions: ['srv_wRCnLLbtvmVT.dashboard:read'],
+        permissions: ['app_topolo_director.dashboard:read'],
       },
     ]);
     expect(calls[0]!.url).toBe(
@@ -586,14 +586,14 @@ describe('TopoloClient.listServices', () => {
           data: {
             services: [
               {
-                service_id: 'srv_mail',
+                app_id: 'app_mail',
                 app_slug: 'topolo-mail',
                 name: 'Topolo Mail',
                 api_base_url: 'https://mail-api.topolo.app',
                 launch_url: 'https://mail.topolo.app',
                 surface_kind: 'application',
                 status: 'active',
-                granted_permissions: ['srv_mail.messages:read'],
+                granted_permissions: ['app_mail.messages:read'],
               },
             ],
           },
@@ -621,14 +621,14 @@ describe('TopoloClient.listServices', () => {
           data: {
             services: [
               {
-                service_id: 'srv_crm',
+                app_id: 'app_crm',
                 app_slug: 'topolo-crm',
                 name: 'Topolo CRM',
                 api_base_url: 'https://crm-api.topolo.app',
                 launch_url: 'https://crm.topolo.app',
                 surface_kind: 'application',
                 status: 'active',
-                granted_permissions: ['srv_crm.contacts:read'],
+                granted_permissions: ['app_crm.contacts:read'],
               },
             ],
           },
@@ -671,14 +671,14 @@ describe('TopoloClient.listServices', () => {
           data: {
             services: [
               {
-                service_id: 'srv_future',
+                app_id: 'app_future',
                 app_slug: 'topolo-future',
                 name: 'Future',
                 api_base_url: 'https://future-api.topolo.app',
                 launch_url: 'https://future.topolo.app',
                 surface_kind: 'api',
                 status: 'active',
-                granted_permissions: ['srv_future.read:all'],
+                granted_permissions: ['app_future.read:all'],
               },
             ],
           },
@@ -705,14 +705,14 @@ describe('TopoloClient.listServices', () => {
           data: {
             services: [
               {
-                service_id: 'srv_crm',
+                app_id: 'app_crm',
                 app_slug: 'topolo-crm',
                 name: 'Topolo CRM',
                 api_base_url: 'https://crm-api.topolo.app',
                 launch_url: 'https://crm.topolo.app',
                 surface_kind: 'api',
                 status: 'active',
-                granted_permissions: ['srv_crm.contacts:read'],
+                granted_permissions: ['app_crm.contacts:read'],
               },
             ],
           },
@@ -739,13 +739,13 @@ describe('TopoloClient.listServices', () => {
           data: {
             services: [
               {
-                service_id: 'srv_future_app',
+                app_id: 'app_future_app',
                 app_slug: 'topolo-future-app',
                 name: 'Future App',
                 launch_url: 'https://future-app.topolo.app',
                 surface_kind: 'application',
                 status: 'active',
-                granted_permissions: ['srv_future_app.launch:read'],
+                granted_permissions: ['app_future_app.launch:read'],
                 launchable: true,
               },
             ],
@@ -772,14 +772,14 @@ describe('TopoloClient.listServices', () => {
           data: {
             services: [
               {
-                service_id: 'srv_future',
+                app_id: 'app_future',
                 app_slug: 'topolo-warehouse',
                 name: 'Warehouse',
                 api_base_url: 'https://warehouse.topolo.app',
                 launch_url: 'https://warehouse.topolo.app',
                 surface_kind: 'api',
                 status: 'active',
-                granted_permissions: ['srv_future.read:all'],
+                granted_permissions: ['app_future.read:all'],
               },
             ],
           },
@@ -838,7 +838,7 @@ describe('TopoloClient action catalog', () => {
     expect(url.toString()).toBe('https://mail-api.topolo.app/api/mail/mailboxes/primary/messages?q=Ada&page=2');
     expect(call.init.method).toBe('GET');
     const headers = new Headers(call.init.headers);
-    expect(headers.get('X-Topolo-Action-Id')).toBe('srv_mail.messages.list');
+    expect(headers.get('X-Topolo-Action-Id')).toBe('app_mail.messages.list');
     expect(headers.get('X-Topolo-Action-Name')).toBe('messages.list');
   });
 

package/src/client.ts

@@ -19,8 +19,8 @@ export interface TopoloClientOptions {
   agent: AgentIdentity;
   /** Per-service URL overrides. Useful for staging/dev. */
   serviceUrls?: Record<string, string>;
-  /** Per-service TopoloAuth service id overrides from the owning app/deployment. */
-  serviceIds?: 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.
@@ -98,7 +98,7 @@ const POSITIVE_CACHE_TTL_MS = 5 * 60 * 1000; // 5 minutes
 const NEGATIVE_CACHE_TTL_MS = 60 * 1000; // 1 minute
 const CATALOG_CACHE_TTL_MS = 60 * 1000; // 1 minute
 
-interface ServiceIdCacheEntry {
+interface AppIdCacheEntry {
   value: string | null;
   expiresAt: number;
 }
@@ -109,7 +109,7 @@ interface ServiceIdCacheEntry {
  * from TopoloAuth `GET /api/services/catalog`.
  */
 export interface TopoloServiceCatalogEntry {
-  serviceId: string;
+  appId: string;
   slug: string | null;
   name: string | null;
   description: string | null;
@@ -139,7 +139,7 @@ export interface TopoloActionCatalogEntry {
   toolName: string | null;
   title: string;
   description: string;
-  serviceId: string;
+  appId: string;
   serviceSlug: string | null;
   serviceName: string | null;
   method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
@@ -151,6 +151,8 @@ export interface TopoloActionCatalogEntry {
   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;
 }
@@ -159,7 +161,7 @@ export class TopoloClient {
   private readonly credential: TopoloCredential;
   private readonly agent: AgentIdentity;
   private readonly serviceUrls?: Record<string, string>;
-  private readonly serviceIds?: Record<string, string>;
+  private readonly appIds?: Record<string, string>;
   private readonly requireConfirmForWrites: boolean;
   private readonly timeoutMs: number;
   private readonly fetchImpl: typeof fetch;
@@ -168,19 +170,19 @@ export class TopoloClient {
   private actionCatalogCache: { entries: TopoloActionCatalogEntry[]; expiresAt: number } | null = null;
 
   /**
-   * Process-wide cache for slug → service-id lookups. Keyed by
+   * 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.clearServiceIdCache()` if a test needs it.
+   * Cleared via `TopoloClient.clearAppIdCache()` if a test needs it.
    */
-  private static readonly serviceIdCache = new Map<string, ServiceIdCacheEntry>();
+  private static readonly appIdCache = new Map<string, AppIdCacheEntry>();
 
   /**
-   * Drop the slug→service-id cache. Test-only — production callers should
+   * Drop the slug→app-id cache. Test-only — production callers should
    * let the 5-minute TTL expire naturally.
    */
-  static clearServiceIdCache(): void {
-    TopoloClient.serviceIdCache.clear();
+  static clearAppIdCache(): void {
+    TopoloClient.appIdCache.clear();
   }
 
   constructor(options: TopoloClientOptions) {
@@ -189,7 +191,7 @@ export class TopoloClient {
     this.credential = options.credential;
     this.agent = options.agent;
     this.serviceUrls = options.serviceUrls;
-    this.serviceIds = options.serviceIds;
+    this.appIds = options.appIds;
     this.requireConfirmForWrites = options.requireConfirmForWrites !== false;
     this.timeoutMs = options.timeoutMs ?? 30_000;
     this.fetchImpl = options.fetch ?? fetch;
@@ -231,8 +233,8 @@ export class TopoloClient {
     const headers = new Headers();
     headers.set('Accept', 'application/json');
     if (opts.body !== undefined) headers.set('Content-Type', 'application/json');
-    const platformServiceId = resolveConfiguredServiceId(resolvedService.serviceKey, this.serviceIds);
-    if (platformServiceId) headers.set('X-Service-ID', platformServiceId);
+    const platformAppId = resolveConfiguredAppId(resolvedService.serviceKey, this.appIds);
+    if (platformAppId) headers.set('X-App-ID', platformAppId);
 
     applyAuthHeaders(headers, this.credential);
     const requestId = generateRequestId();
@@ -377,7 +379,7 @@ export class TopoloClient {
   }
 
   /**
-   * Resolve a service-slug → opaque service-id via caller config or TopoloAuth.
+   * 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
@@ -388,19 +390,19 @@ export class TopoloClient {
    * This keeps the resolver usable during early bootstrap before a caller
    * has acquired an access token.
    */
-  async getServiceIdBySlug(slug: string): Promise<string | null> {
+  async getAppIdBySlug(slug: string): Promise<string | null> {
     if (typeof slug !== 'string') return null;
     const normalized = slug.trim().toLowerCase();
     if (!normalized) return null;
 
-    const configuredServiceId = resolveConfiguredServiceId(normalized, this.serviceIds);
-    if (configuredServiceId) return configuredServiceId;
+    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.serviceIdCache.get(cacheKey);
+    const cached = TopoloClient.appIdCache.get(cacheKey);
     if (cached && cached.expiresAt > now) {
       return cached.value;
     }
@@ -422,7 +424,7 @@ export class TopoloClient {
     }
 
     if (res.status === 404) {
-      TopoloClient.serviceIdCache.set(cacheKey, {
+      TopoloClient.appIdCache.set(cacheKey, {
         value: null,
         expiresAt: now + NEGATIVE_CACHE_TTL_MS,
       });
@@ -434,11 +436,11 @@ export class TopoloClient {
     }
 
     const body = (await res.json().catch(() => null)) as
-      | { success?: boolean; data?: { service_id?: unknown } }
+      | { success?: boolean; data?: { app_id?: unknown } }
       | null;
-    const serviceId = body?.data?.service_id;
-    const value = typeof serviceId === 'string' && serviceId ? serviceId : null;
-    TopoloClient.serviceIdCache.set(cacheKey, {
+    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,
     });
@@ -481,13 +483,13 @@ export class TopoloClient {
     const entries: TopoloServiceCatalogEntry[] = [];
     for (const item of raw) {
       const s = item as Record<string, unknown>;
-      const serviceId =
-        typeof s.service_id === 'string'
-          ? s.service_id
+      const appId =
+        typeof s.app_id === 'string'
+          ? s.app_id
           : typeof s.id === 'string'
             ? s.id
             : null;
-      if (!serviceId) continue;
+      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)
@@ -505,7 +507,7 @@ export class TopoloClient {
           ? [apiKeyResource]
           : [];
       entries.push({
-        serviceId,
+        appId,
         slug: typeof s.app_slug === 'string' ? s.app_slug : null,
         name: typeof s.name === 'string' ? s.name : null,
         description:
@@ -539,8 +541,9 @@ export class TopoloClient {
   }
 
   /**
-   * List callable actions from the live Auth catalog. The response is scoped to
-   * the caller's organization and effective permissions; no bundled/static app
+   * 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 listActions(options: { service?: string } = {}): Promise<TopoloActionCatalogEntry[]> {
@@ -553,7 +556,7 @@ export class TopoloClient {
       | { data?: { actions?: unknown[] } }
       | { actions?: unknown[] }
     >({
-      service: 'auth',
+      service: 'developers',
       method: 'GET',
       path: '/api/actions/catalog',
       ...(options.service ? { query: { service: options.service } } : {}),
@@ -600,7 +603,7 @@ export class TopoloClient {
   ): Promise<T> {
     const entry = await this.getAction(action);
     const mapped = mapActionInput(entry, input);
-    const service = entry.serviceSlug || entry.serviceId;
+    const service = entry.serviceSlug || entry.appId;
     return this.request<T>({
       service,
       method: entry.method,
@@ -626,7 +629,7 @@ export class TopoloClient {
       productionUrl?: string | null;
     }>;
     return apps.map((app) => ({
-      serviceId: app.id,
+      appId: app.id,
       slug: app.id,
       name: app.name ?? app.id,
       description: null,
@@ -685,15 +688,15 @@ export class TopoloClient {
   }
 }
 
-function resolveConfiguredServiceId(
+function resolveConfiguredAppId(
   slug: string,
-  serviceIds?: Record<string, string>,
+  appIds?: Record<string, string>,
 ): string | null {
   for (const serviceKey of serviceKeyCandidates(slug)) {
-    const configured = serviceIds?.[serviceKey as ServiceId];
+    const configured = appIds?.[serviceKey as ServiceId];
     if (typeof configured === 'string' && configured.trim()) return configured.trim();
 
-    const envKey = `TOPOLO_SERVICE_ID_${serviceKey.replace(/\./g, '_').toUpperCase()}`;
+    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();
   }
@@ -811,7 +814,7 @@ function catalogEntryMatches(entry: TopoloServiceCatalogEntry, needle: string):
 }
 
 function catalogEntryLookupKeys(entry: TopoloServiceCatalogEntry): string[] {
-  const values = [entry.serviceId, entry.slug, entry.name].filter((value): value is 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>();
@@ -830,10 +833,10 @@ function normalizeActionCatalogEntry(item: unknown): TopoloActionCatalogEntry |
   const a = item as Record<string, unknown>;
   const actionId = pickActionString(a.action_id) ?? pickActionString(a.actionId);
   const name = pickActionString(a.name);
-  const serviceId = pickActionString(a.service_id) ?? pickActionString(a.serviceId);
+  const appId = pickActionString(a.app_id) ?? pickActionString(a.appId);
   const method = pickActionString(a.method)?.toUpperCase();
   const path = pickActionString(a.path);
-  if (!actionId || !name || !serviceId || !method || !path || !isHttpMethod(method)) {
+  if (!actionId || !name || !appId || !method || !path || !isHttpMethod(method)) {
     return null;
   }
 
@@ -843,7 +846,7 @@ function normalizeActionCatalogEntry(item: unknown): TopoloActionCatalogEntry |
     toolName: pickActionString(a.tool_name) ?? pickActionString(a.toolName) ?? null,
     title: pickActionString(a.title) ?? name,
     description: pickActionString(a.description) ?? '',
-    serviceId,
+    appId,
     serviceSlug: pickActionString(a.service_slug) ?? pickActionString(a.serviceSlug) ?? null,
     serviceName: pickActionString(a.service_name) ?? pickActionString(a.serviceName) ?? null,
     method,
@@ -855,6 +858,7 @@ function normalizeActionCatalogEntry(item: unknown): TopoloActionCatalogEntry |
     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),
   };
@@ -868,6 +872,10 @@ 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 plainObject(value: unknown): Record<string, unknown> {
   return value && typeof value === 'object' && !Array.isArray(value)
     ? value as Record<string, unknown>