@tai42/api-client 16.0.0 → 17.0.0

package/src/client/index.ts

@@ -0,0 +1,122 @@
+/** Composition root: assembles the per-resource sub-clients into the client. */
+import type { ApiConfig } from '../http';
+import { agentsClient } from './agents-client';
+import { authClient } from './auth-client';
+import { backendClient } from './backend-client';
+import { backupClient } from './backup-client';
+import { capabilitiesGetCaps, capabilitiesGetMe } from './capabilities-client';
+import { channelsClient } from './channels-client';
+import { configClient } from './config-client';
+import { connectorsClient } from './connectors-client';
+import { conversationsClient } from './conversations-client';
+import { hooksClient } from './hooks-client';
+import { interactionsClient, interactionsStreamClient } from './interactions-client';
+import { loginClient, logoutClient } from './login-client';
+import { manifestClient, manifestSecretEnvClient } from './manifest-client';
+import { marketplaceClient } from './marketplace-client';
+import { mcpConfigSchemaClient } from './mcp-config-schema-client';
+import { notificationsClient } from './notifications-client';
+import { observabilityClient } from './observability-client';
+import { pluginsClient } from './plugins-client';
+import { policyClient } from './policy-client';
+import { presetsClient } from './presets-client';
+import { profilesClient } from './profiles-client';
+import { schedulesClient } from './schedules-client';
+import { settingsSchemaClient } from './settings-schema-client';
+import { statesClient } from './states-client';
+import { storageClient } from './storage-client';
+import { subMcpClient } from './sub-mcp-client';
+import { systemClient } from './system-client';
+import { templatesClient } from './templates-client';
+import { toolExtensionsClient } from './tool-extensions-client';
+import { toolMetaClient } from './tool-meta-client';
+import { toolsClient } from './tools-client';
+import { makeTransport } from './transport';
+import { triggerLinksClient } from './trigger-links-client';
+import { webEntryGateClient } from './web-entry-gate-client';
+
+export type {
+  AddUrlToScopeBody,
+  ApiKeyBody,
+  ClaimLinkBody,
+  PinRoutePublicBody,
+  RoleCreateBody,
+  RoleUpdateBody,
+} from './auth-client';
+export type { StartConnectArgs } from './connectors-client';
+export type {
+  ConversationMessageSearchQuery,
+  ConversationThreadFilters,
+  ConversationThreadMessageBody,
+  ConversationTranscriptQuery,
+} from './conversations-client';
+export type { TopicVerifierBody } from './hooks-client';
+export { isSafeApiPath } from './login-client';
+export type { ApiToolsListsBody } from './manifest-client';
+export type {
+  MarketplaceInstallBody,
+  MarketplaceInstallPreviewBody,
+  MarketplaceSearchQuery,
+  MarketplaceUninstallBody,
+} from './marketplace-client';
+export type { MetricsQuery, RunsQuery } from './observability-client';
+export type { ValidateConditionBody } from './policy-client';
+export type { CreatePresetBody, SavePresetVersionBody, ValidatePresetBody } from './presets-client';
+export type {
+  StateAttachmentBody,
+  StateDeclarationBody,
+  StatePageQuery,
+  StateSubjectRef,
+  StateTemplateBody,
+} from './states-client';
+export type { StorageUploadBody } from './storage-client';
+export type { ToolMetaPatch } from './tool-meta-client';
+export type { RunToolArgs, ToolAdminArgs } from './tools-client';
+export type { TriggerLinkCreateBody } from './trigger-links-client';
+export type { WebEntryCodeMintBody } from './web-entry-gate-client';
+
+export function createApiClient(config: ApiConfig) {
+  const t = makeTransport(config);
+  return {
+    baseUrl: config.baseUrl ?? '',
+    ...toolsClient(t),
+    ...presetsClient(t),
+    ...statesClient(t),
+    ...toolMetaClient(t),
+    ...storageClient(t),
+    ...backendClient(t),
+    ...toolExtensionsClient(t),
+    ...templatesClient(t),
+    ...manifestClient(t),
+    ...subMcpClient(t),
+    ...configClient(t),
+    ...profilesClient(t),
+    ...manifestSecretEnvClient(t),
+    ...connectorsClient(t),
+    ...pluginsClient(t),
+    ...interactionsClient(t),
+    ...channelsClient(t),
+    ...conversationsClient(t),
+    ...webEntryGateClient(t),
+    ...notificationsClient(t),
+    ...agentsClient(t),
+    ...hooksClient(t),
+    ...triggerLinksClient(t),
+    ...mcpConfigSchemaClient(t),
+    ...settingsSchemaClient(t),
+    ...authClient(t),
+    ...capabilitiesGetMe(t),
+    ...loginClient(t),
+    ...capabilitiesGetCaps(t),
+    ...logoutClient(t),
+    ...policyClient(t),
+    ...backupClient(t),
+    ...schedulesClient(t),
+    ...observabilityClient(t),
+    ...marketplaceClient(t),
+    ...systemClient(t),
+    ...interactionsStreamClient(t),
+  } as const;
+}
+
+export type ApiClient = ReturnType<typeof createApiClient>;

package/src/client/interactions-client.ts

@@ -0,0 +1,89 @@
+/** Interaction listing/answer and the SSE stream sub-clients. */
+import { ApiError, ApiUnauthorizedError } from '../errors';
+import { encodeSegment, extractError } from '../http';
+import * as s from '../schemas';
+import { readSseFrames, sseOpenToken } from '../sse';
+import type { Transport } from './transport';
+
+export function interactionsClient(t: Transport) {
+  const { req } = t;
+  return {
+    // One page of the pending interactions (the tail-only stream's paged base). The
+    // door filters by audience before paging — the SAME filter the stream applies —
+    // so `total` is the caller's own count, and every terminal frame it later receives
+    // refers to a question within that `total`.
+    listInteractions: (page: number, pageSize: number, signal?: AbortSignal) =>
+      req('/api/interactions', s.interactionsPage, { signal, query: { page, pageSize } }),
+    answerInteraction: (interactionId: string, answer: unknown) =>
+      req(`/api/interactions/${encodeSegment(interactionId)}/answer`, s.interactionAnswered, {
+        method: 'POST',
+        body: { answer },
+      }),
+    // Withdraw a pending ask WITHOUT answering it (a bodyless POST): the question is
+    // resolved as cancelled and the flow that asked never resumes. Terminal like an
+    // answer, so the loud failure mappings mirror it — a 409 (already answered, so no
+    // longer cancellable) surfaces as `ApiConflictError`, a 404 (unknown/already gone)
+    // and a 403 (not this caller's audience) as `ApiError` — all via the shared
+    // `apiRequest` status handling.
+    cancelInteraction: (interactionId: string) =>
+      req(`/api/interactions/${encodeSegment(interactionId)}/cancel`, s.interactionCancelled, {
+        method: 'POST',
+      }),
+  };
+}
+
+export function interactionsStreamClient(t: Transport) {
+  const { config } = t;
+  return {
+    /**
+     * Open the authed interactions SSE stream. The stream is TAIL-ONLY: its cursor
+     * is the stream tail at connect, so it carries no backlog and no
+     * `interaction.backlog_done` frame — the pending base comes from
+     * `listInteractions`. The caller drives reconnect and refetches that base on
+     * each (re)connect. Returns the raw frame iterator; the interactions feature
+     * maps frames to typed events.
+     *
+     * `lastEventId` (the id of the last frame the caller saw) is sent as the
+     * `Last-Event-ID` header so the server resumes AFTER it and replays any frame —
+     * including a card's `answered` — that landed during a disconnect gap. It is
+     * also sent as a `?last_event_id=` query param so a proxy that strips the header
+     * still resumes; the server reads either. Omitted on a first connect.
+     */
+    streamInteractions: async (signal?: AbortSignal, lastEventId?: string) => {
+      const doFetch = config.fetch ?? globalThis.fetch;
+      const token = config.getToken();
+      const headers: Record<string, string> = { accept: 'text/event-stream' };
+      if (token) headers['x-api-key'] = token;
+      if (lastEventId) headers['last-event-id'] = lastEventId;
+      // Distinct-URL per open — see the canonical constraint on `sseOpenToken`.
+      const resume = lastEventId ? `&last_event_id=${encodeURIComponent(lastEventId)}` : '';
+      const url = `${config.baseUrl ?? ''}/api/interactions/stream?_=${sseOpenToken()}${resume}`;
+      const response = await doFetch(url, {
+        headers,
+        signal,
+      });
+      if (response.status === 401) throw new ApiUnauthorizedError();
+      // A non-ok stream open (5xx/4xx) still carries a body, which would parse to
+      // zero frames and look like a silently-empty stream — surface it loudly so
+      // the caller shows an error instead of hanging on a reconnect loop. Read the
+      // `{ "error" }` envelope so a load-bearing server message (e.g. the OFF
+      // store's 501 remediation line) surfaces verbatim instead of collapsing to
+      // the bare status text.
+      if (!response.ok) {
+        let payload: unknown;
+        try {
+          payload = await response.json();
+        } catch {
+          throw new ApiError(response.statusText || 'stream failed', response.status);
+        }
+        const { message, code } = extractError(payload);
+        throw new ApiError(
+          message ?? (response.statusText || 'stream failed'),
+          response.status,
+          code,
+        );
+      }
+      return readSseFrames(response, signal);
+    },
+  };
+}

package/src/client/login-client.ts

@@ -0,0 +1,150 @@
+/** Public sign-in aggregator and session-logout sub-clients. */
+import {
+  ApiError,
+  ApiLoginFailedError,
+  ApiSetupFailedError,
+  ApiUnauthorizedError,
+} from '../errors';
+import * as s from '../schemas';
+import type { Transport } from './transport';
+
+/**
+ * Whether a login-method target is a safe same-origin relative API path. The
+ * login screen is the one page where a misconfigured/compromised manifest could
+ * redirect CREDENTIALS off-origin, so a `submit_path`/`href` MUST start `/api/`
+ * — anything else (absolute URL, protocol-relative `//host`, missing prefix) is
+ * rejected. The `/api/` prefix already excludes `//`-prefixed values; the
+ * explicit double-slash clause is kept for readability.
+ */
+export function isSafeApiPath(path: string): boolean {
+  return path.startsWith('/api/') && !path.startsWith('//');
+}
+
+/**
+ * Map a transport error from a login submission onto an `ApiLoginFailedError`
+ * (rendered inline on the login page) or rethrow it unchanged (5xx, schema
+ * drift, network — the page's generic failure branch surfaces it loudly).
+ *
+ * A transport 401 arrives as `ApiUnauthorizedError` before any body is read, so
+ * its message is generic by construction; the domain 4xx statuses carry the
+ * server's informative envelope text (rate-limit, password-policy, or the claim
+ * exchange's uniform "unknown or already used" 404) straight through to the
+ * inline surface.
+ */
+function asLoginError(error: unknown): never {
+  if (error instanceof ApiUnauthorizedError) {
+    throw new ApiLoginFailedError('Sign-in failed — check your credentials.', 401);
+  }
+  if (
+    error instanceof ApiError &&
+    (error.status === 400 ||
+      error.status === 403 ||
+      error.status === 404 ||
+      error.status === 409 ||
+      error.status === 422 ||
+      error.status === 429)
+  ) {
+    throw new ApiLoginFailedError(error.message, error.status);
+  }
+  throw error;
+}
+
+/**
+ * Map a transport error from the setup submission onto an `ApiSetupFailedError`
+ * (rendered inline on the setup entry, keyed on `status`) or rethrow it unchanged
+ * (schema drift, network, any other status — the generic failure branch surfaces
+ * it loudly). The mapped statuses are the setup door's own: 403/429 (a bad or
+ * throttled token — no oracle), 409 (already initialized), 501 (setup
+ * unsupported), and 400/422 (an invalid body).
+ */
+function asSetupError(error: unknown): never {
+  if (
+    error instanceof ApiError &&
+    (error.status === 400 ||
+      error.status === 403 ||
+      error.status === 409 ||
+      error.status === 422 ||
+      error.status === 429 ||
+      error.status === 501)
+  ) {
+    throw new ApiSetupFailedError(error.message, error.status);
+  }
+  throw error;
+}
+
+export function loginClient(t: Transport) {
+  const { req } = t;
+  return {
+    // PUBLIC by design: `apiRequest` attaches `x-api-key` only when a token
+    // exists, so the unauthenticated call carries no auth header — no transport
+    // change needed.
+    getLoginMethods: (options?: { signal?: AbortSignal }) =>
+      req('/api/login/methods', s.loginMethods, { signal: options?.signal }),
+    // Submit a `form` method's field VALUES as a flat top-level JSON body (the
+    // server's request models take the declared field names top-level). `path`
+    // is re-checked with the same relative-`/api/` guard the renderer uses — an
+    // off-origin path is a PROGRAMMING error (loud `Error`), not a login failure.
+    // A refused credential becomes an inline `ApiLoginFailedError`.
+    submitLoginForm: async (path: string, values: Record<string, string>) => {
+      if (!isSafeApiPath(path)) {
+        throw new Error(
+          `login submit_path must be a relative /api/ path; received ${JSON.stringify(path)}`,
+        );
+      }
+      try {
+        return await req(path, s.loginResult, { method: 'POST', body: values });
+      } catch (error) {
+        return asLoginError(error);
+      }
+    },
+    // Exchange a one-time SSO hand-back code for a session (never a token in the
+    // URL). An expired/reused code is a login failure, surfaced inline.
+    exchangeSsoCode: async (code: string) => {
+      try {
+        return await req('/api/login/sso/exchange', s.loginResult, {
+          method: 'POST',
+          body: { code },
+        });
+      } catch (error) {
+        return asLoginError(error);
+      }
+    },
+    // Exchange a one-time claim token (read from the login URL fragment, never a
+    // query param) for a session. PUBLIC. The token is single-use and burns
+    // server-side; a used/unknown/expired token answers the uniform 404, which —
+    // like the SSO leg — maps to an inline `ApiLoginFailedError`, not a global
+    // unauthorized redirect. The caller latches the exchange so it fires once.
+    claimLogin: async (body: { token: string }) => {
+      try {
+        return await req('/api/login/claim', s.loginResult, { method: 'POST', body });
+      } catch (error) {
+        return asLoginError(error);
+      }
+    },
+    // Initialize the deployment: create the owner principal, mint the owner's
+    // first key (returned once), and optionally attach the owner's login. PUBLIC
+    // (anonymous — no credential exists yet). A refused/throttled token, an
+    // already-initialized deployment, an unsupported setup door, or an invalid
+    // body becomes an inline `ApiSetupFailedError`; any other failure rethrows
+    // loudly.
+    submitSetup: async (body: s.SetupBody) => {
+      try {
+        return await req('/api/setup', s.setupResult, { method: 'POST', body });
+      } catch (error) {
+        return asSetupError(error);
+      }
+    },
+  };
+}
+
+export function logoutClient(t: Transport) {
+  const { req } = t;
+  return {
+    // The single authed logout dispatcher — revokes the caller's accounts
+    // session server-side before the shell clears local state. A plain `sk-` key
+    // has nothing to revoke and answers 404 (surfaced as an `ApiError`, quiet at
+    // the call site); a 5xx/network failure is a real revoke failure the shell
+    // surfaces loudly.
+    logout: () => req('/api/auth/logout', s.logoutResult, { method: 'POST' }),
+  };
+}

package/src/client/manifest-client.ts

@@ -0,0 +1,118 @@
+/** Manifest / MCP section, env-ref and config-reload sub-clients. */
+import { encodeSegment } from '../http';
+import * as s from '../schemas';
+import type { Transport } from './transport';
+
+/**
+ * Names to add to / remove from the manifest `api_tools` include and exclude
+ * lists (`POST /api/api-tools`). Each field is a bare name list; the server
+ * refuses a body whose four lists are all empty.
+ */
+export interface ApiToolsListsBody {
+  readonly include_add?: string[];
+  readonly include_remove?: string[];
+  readonly exclude_add?: string[];
+  readonly exclude_remove?: string[];
+}
+
+/**
+ * Body for the combined env+manifest secret op (POST `/api/mcp-config/secret-env`).
+ * The server generates the env key from `value` (shaping the name from `key_hint`),
+ * then writes the env value and the literal `!ENV ${KEY}` manifest leaf at
+ * `manifest_pointer` atomically. `manifest_pointer`'s head segment MUST be `mcp`
+ * (the server refuses any other with a loud 400).
+ */
+export interface SetMcpSecretEnvBody {
+  readonly value: string;
+  readonly key_hint: string;
+  readonly manifest_pointer: string;
+}
+
+export function manifestClient(t: Transport) {
+  const { req } = t;
+  return {
+    getManifest: (signal?: AbortSignal) => req('/api/manifest', s.manifestView, { signal }),
+    setMcpConfig: (mcp: unknown[]) =>
+      req('/api/mcp-config', s.reloadConfigResult, { method: 'POST', body: { mcp } }),
+    getMcpStatus: (signal?: AbortSignal) => req('/api/mcp-status', s.mcpStatus, { signal }),
+    reloadMcp: (title: string) =>
+      req(`/api/mcp-status/${encodeSegment(title)}/reload`, s.mcpReloadResult, {
+        method: 'POST',
+      }),
+
+    // Granular manifest-section entry edits — add/replace or remove ONE entry by
+    // title, leaving the rest of the section untouched (the surgical counterpart to
+    // the whole-section `setMcpConfig`). Each crosses the config pipeline and returns
+    // the shared apply-result (`status` + `env_keys` + fleet `fanout`). `replace` lets
+    // an entry whose title already exists swap in; without it a collision is refused.
+    addToolsEntries: (entries: readonly unknown[], replace = false) =>
+      req('/api/tools-config/entries', s.reloadConfigResult, {
+        method: 'POST',
+        body: { entries, replace },
+      }),
+    removeToolsEntry: (title: string) =>
+      req(`/api/tools-config/entries/${encodeSegment(title)}`, s.reloadConfigResult, {
+        method: 'DELETE',
+      }),
+    addAgentsEntries: (entries: readonly unknown[], replace = false) =>
+      req('/api/agents-config/entries', s.reloadConfigResult, {
+        method: 'POST',
+        body: { entries, replace },
+      }),
+    removeAgentsEntry: (title: string) =>
+      req(`/api/agents-config/entries/${encodeSegment(title)}`, s.reloadConfigResult, {
+        method: 'DELETE',
+      }),
+    // Edit the manifest `api_tools` include/exclude name lists by delta (add/remove
+    // names on either list). Absent fields default to empty; the server refuses a body
+    // whose four lists are all empty. Returns the shared apply-result.
+    updateApiTools: (body: ApiToolsListsBody) =>
+      req('/api/api-tools', s.reloadConfigResult, {
+        method: 'POST',
+        body: {
+          include_add: body.include_add ?? [],
+          include_remove: body.include_remove ?? [],
+          exclude_add: body.exclude_add ?? [],
+          exclude_remove: body.exclude_remove ?? [],
+        },
+      }),
+
+    // The MCP servers skipped by the viability check, plus their remediation ops. The
+    // LIST rides the fleet fan-out primitive (each worker's failed roster arrives as
+    // its own report payload; `failedMcpsFromReport` unions them). Reload-all re-probes
+    // every failed server; deregister detaches one server's tools by title. Each op
+    // returns the bare per-worker `fleetResult`.
+    listFailedMcps: (signal?: AbortSignal) =>
+      req('/api/mcp-status/failed', s.fleetResult, { signal }),
+    reloadFailedMcps: () =>
+      req('/api/mcp-status/reload-failed', s.fleetResult, {
+        method: 'POST',
+        body: { targets: null },
+      }),
+    deregisterMcp: (title: string) =>
+      req(`/api/mcp-status/${encodeSegment(title)}/deregister`, s.fleetResult, {
+        method: 'POST',
+        body: { targets: null },
+      }),
+  };
+}
+
+export function manifestSecretEnvClient(t: Transport) {
+  const { req } = t;
+  return {
+    // The SecretRefField server half: one atomic env-value + `!ENV` manifest
+    // write, returning the shared apply-result shape (reload + fleet fanout).
+    setMcpSecretEnv: (body: SetMcpSecretEnvBody) =>
+      req('/api/mcp-config/secret-env', s.reloadConfigResult, { method: 'POST', body }),
+    // The PRESERVED manifest (`!ENV` markers intact, no resolved secrets) — the
+    // connectors page's McpServersSection reads this so round-trips never inline
+    // resolved values.
+    getManifestPreserved: (signal?: AbortSignal) =>
+      req('/api/manifest/preserved', s.manifestView, { signal }),
+    // The manifest MCP section's `!ENV ${VAR[:default]}` marker refs — NAMES and
+    // set/unset BOOLEANS only, never values. Drives the McpServersSection env-refs
+    // checklist on the connectors page.
+    getMcpEnvRefs: (signal?: AbortSignal) =>
+      req('/api/manifest/mcp-env-refs', s.mcpEnvRefs, { signal }),
+  };
+}

package/src/client/marketplace-client.ts

@@ -0,0 +1,122 @@
+/** Marketplace search, install, update and advisory sub-client. */
+import { encodeSegment } from '../http';
+import * as s from '../schemas';
+import type { Transport } from './transport';
+
+/**
+ * The marketplace search filter (GET `/api/marketplace/search` query params).
+ * `tags` is sent as REPEATED `tags` params, one per value; `page` is supplied
+ * per-request by the infinite query, never from the URL. `tier`, `namespace`,
+ * `contract`, and `page_size` are accepted by the route but the v1 UI sends none
+ * of them (every v1 row is official/tai42; the page size stays the server
+ * default) — they exist for contract completeness.
+ */
+export interface MarketplaceSearchQuery {
+  readonly q?: string;
+  readonly kind?: string;
+  readonly category?: string;
+  readonly tags?: string[];
+  readonly namespace?: string;
+  readonly tier?: string;
+  readonly contract?: string;
+  readonly sort?: 'downloads' | 'updated' | 'name' | 'relevance';
+  readonly page?: number;
+  readonly page_size?: number;
+}
+
+/**
+ * Body for installing / updating a plugin. `ref` is `namespace/name`.
+ *
+ * `env` / `secret_keys` satisfy an mcp-server entry's required `!ENV` markers in
+ * the same transaction that writes the entry: `env` supplies the values,
+ * `secret_keys` marks which land in the secret band. Both omitted for a plain
+ * install (no required markers).
+ *
+ * `route_mounts` maps a route-carrying item name to the base prefix its routes
+ * mount under (the default or the operator's remap); `accept_public_routes`
+ * explicitly consents to the routes served without authentication. Omitted for a
+ * plugin that registers no routes.
+ */
+export interface MarketplaceInstallBody {
+  readonly ref: string;
+  readonly version?: string;
+  readonly env?: Record<string, string>;
+  readonly secret_keys?: string[];
+  readonly route_mounts?: Record<string, string>;
+  readonly accept_public_routes?: boolean;
+}
+
+/**
+ * Body for previewing an install / update (`POST /api/marketplace/install/preview`):
+ * resolves the spec and computes the routes, collisions, and public rows WITHOUT
+ * side effects. `route_mounts` applies base overrides so the operator sees the
+ * effect of a remap before committing.
+ */
+export interface MarketplaceInstallPreviewBody {
+  readonly ref: string;
+  readonly version?: string;
+  readonly route_mounts?: Record<string, string>;
+}
+
+/** Body for uninstalling a plugin. */
+export interface MarketplaceUninstallBody {
+  readonly ref: string;
+}
+
+export function marketplaceClient(t: Transport) {
+  const { req } = t;
+  return {
+    // Browse/search proxy the registry through the app (one origin, one auth);
+    // install/uninstall/update mutate the RUNNING app (pip install + manifest
+    // patch + reload) and return synchronous receipts.
+    searchMarketplace: (query: MarketplaceSearchQuery = {}, signal?: AbortSignal) =>
+      req('/api/marketplace/search', s.marketplaceSearchPage, {
+        query: {
+          q: query.q,
+          kind: query.kind,
+          category: query.category,
+          tags: query.tags,
+          namespace: query.namespace,
+          tier: query.tier,
+          contract: query.contract,
+          sort: query.sort,
+          page: query.page,
+          page_size: query.page_size,
+        },
+        signal,
+      }),
+    getMarketplacePlugin: (namespace: string, name: string, signal?: AbortSignal) =>
+      req(
+        `/api/marketplace/plugins/${encodeSegment(namespace)}/${encodeSegment(name)}`,
+        s.marketplacePluginDetail,
+        { signal },
+      ),
+    listMarketplaceCategories: (signal?: AbortSignal) =>
+      req('/api/marketplace/categories', s.marketplaceCategories, { signal }),
+    listMarketplaceKinds: (signal?: AbortSignal) =>
+      req('/api/marketplace/kinds', s.marketplaceKinds, { signal }),
+    listInstalledMarketplacePlugins: (signal?: AbortSignal) =>
+      req('/api/marketplace/installed', s.marketplaceInstalled, { signal }),
+    // Preview resolves the spec and computes routes/collisions/public rows with
+    // NO side effects, so the install dialog can show absolute paths, block on a
+    // collision, and surface the public routes before the operator commits.
+    previewMarketplaceInstall: (body: MarketplaceInstallPreviewBody, signal?: AbortSignal) =>
+      req('/api/marketplace/install/preview', s.marketplaceInstallPreview, {
+        method: 'POST',
+        body,
+        signal,
+      }),
+    installMarketplacePlugin: (body: MarketplaceInstallBody) =>
+      req('/api/marketplace/install', s.marketplaceInstallResult, { method: 'POST', body }),
+    uninstallMarketplacePlugin: (body: MarketplaceUninstallBody) =>
+      req('/api/marketplace/uninstall', s.marketplaceUninstallResult, { method: 'POST', body }),
+    updateMarketplacePlugin: (body: MarketplaceInstallBody) =>
+      req('/api/marketplace/update', s.marketplaceInstallResult, { method: 'POST', body }),
+    // Upgrade EVERY installed plugin to its newest compatible version in one
+    // pass; the response is the per-plugin outcome readout.
+    upgradeAllMarketplacePlugins: () =>
+      req('/api/marketplace/upgrade-all', s.marketplaceUpgradeAllResult, { method: 'POST' }),
+    getMarketplaceAdvisories: (signal?: AbortSignal) =>
+      req('/api/marketplace/advisories', s.marketplaceAdvisories, { signal }),
+  };
+}

package/src/client/mcp-config-schema-client.ts

@@ -0,0 +1,11 @@
+/** MCP config-schema read sub-client. */
+import * as s from '../schemas';
+import type { Transport } from './transport';
+
+export function mcpConfigSchemaClient(t: Transport) {
+  const { req } = t;
+  return {
+    getMcpConfigSchema: (signal?: AbortSignal) =>
+      req('/api/mcp-config/schema', s.jsonSchema, { signal }),
+  };
+}

package/src/client/notifications-client.ts

@@ -0,0 +1,13 @@
+/** Notification-sink listing sub-client. */
+import * as s from '../schemas';
+import type { Transport } from './transport';
+
+export function notificationsClient(t: Transport) {
+  const { req } = t;
+  return {
+    // The internal notifications sink, newest-first — the messages the `notify_user`
+    // operation records with no channel, so they surface only in this inbox.
+    listNotifications: (signal?: AbortSignal) =>
+      req('/api/notifications', s.notifications, { signal }),
+  };
+}