@ethisyscore/plugin-ui 1.93.0 → 1.95.0

package/dist/connector-mappings/index.d.cts

@@ -0,0 +1,1274 @@
+import { T as ToolInvoker } from '../mcpService-4h3sKDpW.cjs';
+import { C as ConnectorCanonicalField, h as MappingCompletenessResult, c as ConnectorMappingSuggestionResult, m as TestToolMappingResult, i as MappingReadiness, g as MappingCompletenessItem, d as ConnectorMappingTranslationEditorProps, f as MappingCompletenessBannerProps } from '../mappingQueryKeys-BcbA0TGy.cjs';
+export { a as CONNECTOR_CONTROL_LABEL, b as ConnectorCanonicalFieldKind, P as PLUGIN_PROVIDER_CONTROL_LABEL, j as PROVIDER_CONTROL_LABEL, k as PROVIDER_OPTION_LABEL, T as TestToolMappingExtractedField, l as TestToolMappingRequest, n as connectorMappingCompletenessQueryKey, o as connectorMappingsQueryKey, p as connectorMappingsRootQueryKey, q as pluginTargetMappingsQueryKey, s as selectIncompleteOperations, r as selectMappingReadiness, t as selectOptionalIncompleteOperations, u as selectRequiredIncompleteOperations } from '../mappingQueryKeys-BcbA0TGy.cjs';
+import { UseMutationResult } from '@tanstack/react-query';
+import 'react';
+
+/**
+ * Wire shapes for the connector tool-mapping surface — the DTOs the host's `connectors:mappings:*`
+ * tools return, plus the argument shapes the hooks in this module accept.
+ *
+ * Declared here rather than in a plugin's generated contracts for the same reason the completeness
+ * shapes moved to `components/connectors/types`: this package sits BELOW the plugins, and three of
+ * them held their own copy of every type below. The copies are what let the surfaces drift.
+ *
+ * The rendering-side shapes (`MappingCompletenessItem`, `ConnectorCanonicalField`,
+ * `TestToolMappingRequest`, …) are NOT redeclared here. They already live in
+ * `components/connectors/types` next to the components that consume them, and are re-exported by
+ * this module's barrel so a consumer needs one import.
+ */
+
+/** How a mapping came to exist. Mirrors the backend `ToolMappingSource` enum (snake_case wire). */
+declare const MAPPING_SOURCE: {
+    readonly keyword: "keyword";
+    readonly ai: "ai";
+    readonly manual: "manual";
+};
+type ConnectorMappingSource = (typeof MAPPING_SOURCE)[keyof typeof MAPPING_SOURCE];
+/** Why the AI matcher was unavailable for an auto-match run. `null` means it was available. */
+declare const AI_UNAVAILABLE_REASON: {
+    readonly Timeout: "timeout";
+    readonly ProviderError: "provider_error";
+    readonly ParseError: "parse_error";
+    readonly ContextTooLarge: "context_too_large";
+    readonly NoConnectorConfigured: "no_connector_configured";
+};
+type ConnectorAiUnavailableReason = (typeof AI_UNAVAILABLE_REASON)[keyof typeof AI_UNAVAILABLE_REASON] | null;
+/** Why a concurrent auto-match request was refused. `null` means no conflict. */
+declare const AUTO_MATCH_CONFLICT_REASON: {
+    readonly AnotherAutoMatchInProgress: "another_auto_match_in_progress";
+};
+type ConnectorAutoMatchConflictReason = (typeof AUTO_MATCH_CONFLICT_REASON)[keyof typeof AUTO_MATCH_CONFLICT_REASON] | null;
+/**
+ * What a mapping resolves to, as this surface spells it: a connector to a third-party system, or
+ * another installed application.
+ *
+ * Lower-case, and NOT the string the host stores. The host persists its `ToolMappingTargetKind` by
+ * NAME and case (`"Connector"` / `"Plugin"`), so the two vocabularies are declared separately and
+ * converted by `toWireTargetKind` / `fromWireTargetKind` in `targetSelection`. Sharing one literal
+ * would make a render-side comparison and a wire value the same string by coincidence, and the
+ * first time either side changed case the other would fail silently - the stored value matching
+ * neither branch of the host's resolver nor its CHECK constraint.
+ */
+declare const MAPPING_TARGET_KIND: {
+    readonly connector: "connector";
+    readonly plugin: "plugin";
+};
+type MappingTargetKind = (typeof MAPPING_TARGET_KIND)[keyof typeof MAPPING_TARGET_KIND];
+/**
+ * Which kind of thing serves a module. The wire values are the host's
+ * `ToolMappingTargetKind` member NAMES, so they are a contract rather than a display label.
+ */
+declare const MODULE_PROVIDER_KIND: {
+    readonly Connector: "Connector";
+    readonly Plugin: "Plugin";
+};
+type ModuleProviderKind = (typeof MODULE_PROVIDER_KIND)[keyof typeof MODULE_PROVIDER_KIND];
+/**
+ * The same vocabulary as the host stores and matches it, keyed the way the UI spells its kinds so a
+ * render-side value converts without a cast. See {@link MAPPING_TARGET_KIND}.
+ *
+ * The STRINGS come from {@link MODULE_PROVIDER_KIND} rather than being retyped, because this file
+ * arrived at the same contract twice - once for the per-operation target and once for the
+ * per-module provider - and two literal copies of a value the host matches by name is the drift
+ * this vocabulary split exists to prevent, not an instance of it.
+ */
+declare const MAPPING_TARGET_KIND_WIRE: {
+    readonly connector: "Connector";
+    readonly plugin: "Plugin";
+};
+type MappingTargetKindWire = (typeof MAPPING_TARGET_KIND_WIRE)[keyof typeof MAPPING_TARGET_KIND_WIRE];
+/**
+ * The operator-editable translation attached to one mapping row.
+ *
+ * @remarks
+ * All three members are `null`-able and **all three must be sent on every write**. The host's
+ * `connectors:mappings:set` treats an omitted or null member as "no operator override" and writes
+ * NULL, so a partial write silently destroys whichever members it left out. This is not a style
+ * point: picking a tool used to clear an operator's field translations, confirmed against the
+ * production database. {@link ConnectorMappingWriteArgs} and `useConnectorMappingMutations` are what
+ * make a write complete; see the fill-in in `useConnectorMappingMutations`.
+ */
+interface ConnectorMappingTranslationState {
+    /** Canonical request field → tool input field name. `null` ⇒ identity translation. */
+    requestFieldMap: Record<string, string> | null;
+    /** Canonical response field → JSON path against the tool's response. `null` ⇒ identity. */
+    responseFieldPaths: Record<string, string> | null;
+    /**
+     * Constant tool-request parameters injected into every call regardless of the canonical input
+     * (tool field name → literal value, e.g. `method: "get_reviews"`). `null` ⇒ none configured.
+     */
+    staticRequestFields: Record<string, string> | null;
+}
+/** One row of the operation → tool mapping table, as `connectors:mappings:list` returns it. */
+interface ConnectorMappingItem {
+    /** Canonical operation key, e.g. `list-commits`. */
+    operationKey: string;
+    /** Human label, from the module's catalogue. */
+    label: string;
+    /** Whether the module declares this operation as required. */
+    isRequired: boolean;
+    /** Tool the operation currently resolves to, or `null` when unmapped. */
+    mappedToolName: string | null;
+    source: ConnectorMappingSource | null;
+    /** AI match confidence in `0..1`, or `null` for keyword/manual matches. */
+    confidence: number | null;
+    /**
+     * Opaque concurrency token. The host declares it as `byte[]`, which crosses the wire as base64:
+     * read one here and hand the same string back on write. `null` means no stored row exists yet,
+     * which callers send as `""` so the host upserts.
+     */
+    rowVersion: string | null;
+    /** True when the row is an AI match below the auto-accept threshold and wants an operator's eye. */
+    requiresReview?: boolean;
+    /**
+     * Canonical request schema declared by the operation's owning module. `null` when the operation
+     * declares none, in which case there is nothing operator-meaningful to translate and the
+     * translation affordance stays hidden.
+     */
+    canonicalRequestFields?: ConnectorCanonicalField[] | null;
+    /** Canonical response schema. Same null semantics as {@link canonicalRequestFields}. */
+    canonicalResponseFields?: ConnectorCanonicalField[] | null;
+    requestFieldMap?: Record<string, string> | null;
+    responseFieldPaths?: Record<string, string> | null;
+    staticRequestFields?: Record<string, string> | null;
+}
+/** One operation's outcome from an auto-match run. Mirrors `ConnectorAutoMatchItem`. */
+interface ConnectorAutoMatchItem {
+    operationKey: string;
+    /**
+     * `null` when this operation matched nothing. An item is returned for EVERY operation regardless,
+     * so `items.length` is the operation count and not the match count — reading it as the latter
+     * reports success on a run that mapped nothing.
+     */
+    mappedToolName: string | null;
+    source: ConnectorMappingSource | null;
+    confidence: number | null;
+    requiresReview?: boolean;
+    /**
+     * A tool that keyword-matched but was rejected, and the required parameters it could not be
+     * satisfied with. The host has always returned both; the types this was promoted from omitted
+     * them in two of three plugins, which discarded the only machine-readable explanation of why an
+     * auto-match came back empty.
+     */
+    discardedToolName?: string | null;
+    unsatisfiedToolParameters?: string[] | null;
+}
+/** Raw auto-match result, before {@link AutoMatchSummary} reduces it for the banner. */
+interface AutoMatchResponse {
+    items: ConnectorAutoMatchItem[];
+    aiAvailable: boolean;
+    aiUnavailableReason: ConnectorAiUnavailableReason;
+    unmatchedRequiredCount: number;
+    conflictReason: ConnectorAutoMatchConflictReason;
+}
+/** Per-source counts reduced from an {@link AutoMatchResponse}, for the outcome banner. */
+interface AutoMatchSummary {
+    aiAvailable: boolean;
+    aiUnavailableReason: ConnectorAiUnavailableReason;
+    unmatchedRequiredCount: number;
+    matchedByKeyword: number;
+    matchedByAi: number;
+    conflictReason: ConnectorAutoMatchConflictReason;
+}
+/**
+ * Arguments for one mapping write.
+ *
+ * The three translation members are OPTIONAL here and required on the wire, and the gap between
+ * those two facts is deliberate: a caller that is only changing the tool omits them, and
+ * `useConnectorMappingMutations` fills each one from the row it already holds before the write
+ * leaves. Omitting a member therefore means "leave it as it is", never "clear it". A caller that
+ * genuinely wants to clear one passes an explicit `null`.
+ */
+interface ConnectorMappingWriteArgs {
+    operationKey: string;
+    /** `""` is the unmap request; the hooks route it to `connectors:mappings:delete`. */
+    toolName: string;
+    /** Row version read from {@link ConnectorMappingItem.rowVersion}, or `""` for a fresh row. */
+    rowVersion: string;
+    requestFieldMap?: Record<string, string> | null;
+    responseFieldPaths?: Record<string, string> | null;
+    staticRequestFields?: Record<string, string> | null;
+}
+/** Body for the per-operation AI translation suggestion. */
+interface SuggestMappingTranslationBody {
+    operationKey: string;
+    toolName: string;
+    /** Sample values the operator typed. The host declares this non-nullable; absent ⇒ `{}`. */
+    sampleArgs?: Record<string, unknown>;
+}
+/** Body for the translation dry-run. `connectorId` / `moduleKey` are passed alongside, not here. */
+interface TestMappingBody {
+    operationKey: string;
+    toolName: string;
+    requestFieldMap: Record<string, string> | null;
+    responseFieldPaths: Record<string, string> | null;
+    /** The DRAFT static params, so the dry-run exercises the discriminator the operator is testing. */
+    staticRequestFields: Record<string, string> | null;
+    sampleArgs: Record<string, unknown>;
+}
+/** A connector as `settings:list-connectors` projects it. */
+interface ConnectorSummary {
+    id: string;
+    name: string;
+    slug?: string | null;
+    isEnabled: boolean;
+}
+/** One tool a connector exposes, as `settings:get-connector` projects it. */
+interface ConnectorToolSummary {
+    toolName: string;
+    description?: string | null;
+    isEnabled: boolean;
+}
+/**
+ * Which provider an organisation has chosen to serve a module.
+ *
+ * @remarks
+ * `targetKind` is `null` when the organisation has made NO choice, and the host deliberately does
+ * not default it to `"Connector"`. "Nobody has chosen yet" and "chose a connector that has no
+ * mapping yet" call for different remedies, and a surface that cannot tell them apart shows a
+ * choice nobody made.
+ */
+interface ModuleProvider {
+    targetKind: ModuleProviderKind | null;
+    connectorId: string | null;
+    targetExtensionId: string | null;
+    /**
+     * Concurrency token of the stored selection, `null` when there is none yet.
+     *
+     * Opaque, exactly like a mapping's: read it here and hand the same string back to
+     * `setModuleProvider`. Nothing on this side parses or constructs one.
+     */
+    rowVersion: string | null;
+}
+/** One tool an installed application exposes, as the provider picker renders it. */
+interface PluginProviderTool {
+    /** Fully namespaced, e.g. `hr:get-employees-by-ids`. A plugin tool routes under this name verbatim. */
+    toolName: string;
+    description?: string | null;
+}
+/**
+ * One installed application an operator may choose to serve a module, with the tools it can answer
+ * the module's operations with.
+ *
+ * @remarks
+ * **The candidate set is narrower than "every tool that routes", and has to be.** The host's write
+ * path refuses a plugin-target mapping naming a tool the CONSUMING application did not declare in
+ * its own manifest `mcpToolDependencies`, because such a row is authority to invoke another
+ * application's tool with no per-tool permission check. A picker offering a wider list offers
+ * choices the save will reject, so whatever supplies this must apply the same bound - and must also
+ * filter by the caller's own permissions, which the host's routable-tool listing explicitly does
+ * not.
+ *
+ * There is no endpoint that returns this, in any transport, which is why it is an INPUT to
+ * `useConnectorToolMappings` rather than something this package fetches.
+ */
+interface PluginProviderCandidate {
+    extensionId: string;
+    /** Display name of the installed application. */
+    name: string;
+    tools: PluginProviderTool[];
+}
+/**
+ * A mapping row whose target is another installed application, as the plugin-mode table renders it.
+ *
+ * Same shape as {@link ConnectorMappingItem} plus the providing extension, which a connector-scoped
+ * row has no need of because the connector is the scope of the read.
+ */
+interface PluginTargetMappingItem extends ConnectorMappingItem {
+    /** The providing extension, or `null` when the operation is unmapped. */
+    targetExtensionId: string | null;
+}
+/** Arguments for one plugin-target mapping write. */
+interface SetPluginTargetMappingArgs {
+    operationKey: string;
+    /** The PROVIDING extension. Required by the host even on an unmap, which is how it finds the row. */
+    targetExtensionId: string;
+    /** `""` is the unmap request, matching {@link ConnectorMappingWriteArgs.toolName}. */
+    toolName: string;
+    /** Row version, or `""` for a fresh row. Not enforced by the host on the unmap branch. */
+    rowVersion: string;
+}
+/** The stored plugin-target mapping after a write. */
+interface SetPluginTargetMappingResult {
+    /** `null` when the operation is now unmapped. */
+    toolName: string | null;
+    targetExtensionId: string | null;
+    /** `""` after an unmap, where there is no row left to hold a token. */
+    rowVersion: string;
+}
+
+/**
+ * The mapping transport the hooks in this module require.
+ *
+ * Narrow on purpose: exactly the seven host tools a Tool Mappings page reads and writes, and nothing
+ * about connectors themselves. Connector enumeration differs genuinely between plugins — one reads
+ * `settings:list-connectors`, another pages a full connector CRUD service — so it is a SEPARATE
+ * interface ({@link IConnectorEnumerationService}) that a consumer takes only if it wants the
+ * default implementation.
+ *
+ * Declared as an interface rather than assumed to be {@link ConnectorMappingService} so a consumer
+ * can supply a mock, or its own transport, without subclassing.
+ */
+interface IConnectorMappingService {
+    /** `connectors:mappings:list` */
+    getMappings(connectorId: string, moduleKey: string): Promise<ConnectorMappingItem[]>;
+    /**
+     * `connectors:mappings:set`
+     *
+     * Every translation member is sent, including nulls, because the host writes NULL for a null
+     * member. Callers must pass the COMPLETE translation; `useConnectorMappingMutations` is where
+     * that is guaranteed.
+     *
+     * @returns the replacement row version, or `null` when the host returned none.
+     */
+    updateMapping(connectorId: string, moduleKey: string, operationKey: string, toolName: string, rowVersion: string, requestFieldMap: Record<string, string> | null, responseFieldPaths: Record<string, string> | null, staticRequestFields: Record<string, string> | null): Promise<string | null>;
+    /**
+     * `connectors:mappings:delete`
+     *
+     * Distinct from an empty-tool-name write: the host's set validator rejects an empty tool name, so
+     * a clear has to be a delete.
+     */
+    deleteMapping(connectorId: string, moduleKey: string, operationKey: string, rowVersion: string): Promise<void>;
+    /**
+     * `connectors:mappings:auto-match`
+     *
+     * The MCP namespace is derived server-side from `connectorId`. A slug parameter used to sit here
+     * and was a live bug: the implementation forwarded it as `moduleKey`, so the tool received no
+     * slug and rejected every call, which is what made the Auto-match button appear to do nothing.
+     */
+    autoMatch(connectorId: string, moduleKey: string): Promise<AutoMatchResponse>;
+    /**
+     * `connectors:mappings:completeness`
+     *
+     * Per-operation completeness of the module's canonical operations against the connector's LIVE
+     * tools. An operation with a non-empty `unmappedRequiredCanonicalFields` is incomplete whether or
+     * not it has a tool mapped.
+     */
+    getMappingCompleteness(connectorId: string, moduleKey: string): Promise<MappingCompletenessResult>;
+    /**
+     * `connectors:mappings:suggest-translation`
+     *
+     * Opt-in AI suggestion for one operation's field translation. Row-independent — the caller
+     * supplies the tool name — so it works before anything is saved. `success: false` carries a
+     * human-readable `error`; it is not an exception.
+     */
+    suggestMappingTranslation(connectorId: string, moduleKey: string, body: SuggestMappingTranslationBody): Promise<ConnectorMappingSuggestionResult>;
+    /**
+     * `connectors:mappings:test`
+     *
+     * Dry-run of a tool + translation through the production path. Also row-independent: the caller
+     * supplies the tool name AND the translation being tried, which is what makes testing an UNSAVED
+     * edit possible. A tool-invocation or extraction failure comes back as `success: false`, not as a
+     * thrown error.
+     */
+    testMapping(connectorId: string, moduleKey: string, body: TestMappingBody): Promise<TestToolMappingResult>;
+    /**
+     * `connectors:mappings:get-provider`
+     *
+     * Which provider the organisation has chosen for a module. This is the ORGANISATION's answer,
+     * which is the point: before it existed, a plugin had to keep the choice in browser storage, so
+     * one operator's selection was invisible to a colleague and the two never reconciled.
+     */
+    getModuleProvider(moduleKey: string): Promise<ModuleProvider>;
+    /**
+     * `connectors:mappings:set-provider`
+     *
+     * Choose the provider. Mappings stay per-connector, so switching provider and switching back
+     * preserves the translation work already done against each.
+     *
+     * `rowVersion` is the token from {@link getModuleProvider}, or `null` for a module that has never
+     * had a selection; the host rejects a mismatch rather than overwriting a concurrent change. The
+     * response carries the refreshed token, so two writes in a row need no re-read between them.
+     */
+    setModuleProvider(moduleKey: string, targetKind: ModuleProviderKind, connectorId: string | null, targetExtensionId: string | null, rowVersion: string | null): Promise<ModuleProvider>;
+}
+/**
+ * Connector enumeration for the mapping picker — deliberately separate from
+ * {@link IConnectorMappingService}.
+ *
+ * Only two of these calls exist because only two are needed: list the connectors, and read one
+ * connector's tools. A plugin that already has a connector CRUD service should keep using it and
+ * ignore this interface entirely; a plugin that only needs to populate a picker can take the
+ * default implementation on {@link ConnectorMappingService} instead of porting a CRUD subsystem
+ * that would have no other caller.
+ */
+interface IConnectorEnumerationService {
+    /** `settings:list-connectors` — enumeration only, never edits a connector. */
+    listConnectors(): Promise<ConnectorSummary[]>;
+    /**
+     * `settings:get-connector` — one connector's tools.
+     *
+     * The DETAIL call, not the list one: the list projection carries only tool COUNTS and no names,
+     * so a picker built on it renders an empty dropdown beside a connector advertising twelve tools.
+     */
+    listConnectorTools(connectorId: string): Promise<ConnectorToolSummary[]>;
+}
+
+/**
+ * The connector tool-mapping surface, served entirely by the host's `connectors:mappings:*` tools.
+ *
+ * ## Why the host store and not a plugin table
+ *
+ * A plugin resolves its operations at runtime through the platform's `resolve-mapping`, so the rows
+ * have to live in the platform store. Three plugins each owned their mappings in their own schema
+ * first, and every platform-side tool was blind to them: Super Admin could not inspect or repair
+ * them, and platform mapping completeness did not cover them.
+ *
+ * ## Transport is injected
+ *
+ * The constructor takes a {@link ToolInvoker} — the same shape `BaseMcpService` takes — rather than
+ * importing one. That keeps this class free of `@ethisyscore/extension-runtime`, so it is unit
+ * testable with a plain function, and it is why this does not extend `BaseMcpService`: the base
+ * class exists to give a lifted REST service a `this.tool(...)`, and there is no REST ancestry here
+ * to accommodate. A plugin constructs it exactly as before:
+ *
+ * ```ts
+ * const invoker = useToolInvokerMap(CONNECTOR_MAPPING_TOOLS);
+ * const service = useMemo(() => new ConnectorMappingService(invoker), [invoker]);
+ * ```
+ *
+ * ## Row versions are opaque
+ *
+ * The host declares them as `byte[]`, which crosses the wire as base64. Read one from
+ * {@link getMappings} and hand the same string back on write; nothing on this side parses or
+ * constructs one.
+ *
+ * ## Translation is NOT a patch on this surface
+ *
+ * The host writes NULL for a null member, so every save must carry the complete translation.
+ * Sending only the field being changed silently clears the other two — that defect reached
+ * production and had to be fixed three times, once per plugin, which is the reason this class is
+ * here. `useConnectorMappingMutations` is where completeness is enforced; this class sends what it
+ * is given, and does not paper over a partial write.
+ *
+ * ## Every read is null-tolerant
+ *
+ * Promoted from the three copies, taking the most hardened behaviour of each. A `Result` with no
+ * value is representable on the wire, so `response.items` on an absent payload throws inside a
+ * react-query `queryFn` or, worse, inside an `onSuccess` where the rejection is unhandled. A page
+ * that reports nothing beats a page that crashed.
+ */
+declare class ConnectorMappingService implements IConnectorMappingService, IConnectorEnumerationService {
+    private readonly invoker;
+    constructor(invoker: ToolInvoker);
+    /** Single seam every method goes through, so a subclass can wrap logging or retries in one place. */
+    protected tool<TRes>(name: string, args?: unknown): Promise<TRes>;
+    getMappings(connectorId: string, moduleKey: string): Promise<ConnectorMappingItem[]>;
+    updateMapping(connectorId: string, moduleKey: string, operationKey: string, toolName: string, rowVersion: string, requestFieldMap: Record<string, string> | null, responseFieldPaths: Record<string, string> | null, staticRequestFields: Record<string, string> | null): Promise<string | null>;
+    deleteMapping(connectorId: string, moduleKey: string, operationKey: string, rowVersion: string): Promise<void>;
+    autoMatch(connectorId: string, moduleKey: string): Promise<AutoMatchResponse>;
+    getMappingCompleteness(connectorId: string, moduleKey: string): Promise<MappingCompletenessResult>;
+    suggestMappingTranslation(connectorId: string, moduleKey: string, body: SuggestMappingTranslationBody): Promise<ConnectorMappingSuggestionResult>;
+    testMapping(connectorId: string, moduleKey: string, body: TestMappingBody): Promise<TestToolMappingResult>;
+    listConnectors(): Promise<ConnectorSummary[]>;
+    getModuleProvider(moduleKey: string): Promise<ModuleProvider>;
+    setModuleProvider(moduleKey: string, targetKind: ModuleProviderKind, connectorId: string | null, targetExtensionId: string | null, rowVersion: string | null): Promise<ModuleProvider>;
+    listConnectorTools(connectorId: string): Promise<ConnectorToolSummary[]>;
+    /**
+     * Whether this transport can serve the plugin-target methods below. `false` here, and the three
+     * methods throw, for the reasons in the block comment above.
+     *
+     * A property and not a guess: "the method exists" and "the method works" are different facts, and
+     * a caller that probed by calling and catching would turn a known gap into a request, an error
+     * toast and a support ticket.
+     */
+    readonly isPluginTargetSurfaceAvailable = false;
+    listPluginProviders(moduleKey: string): Promise<PluginProviderCandidate[]>;
+    getPluginTargetMappings(moduleKey: string): Promise<PluginTargetMappingItem[]>;
+    setPluginTargetMapping(moduleKey: string, args: SetPluginTargetMappingArgs): Promise<SetPluginTargetMappingResult>;
+}
+/** Every host tool this service dispatches, for `useToolInvokerMap`. Frozen and constant-length. */
+declare const CONNECTOR_MAPPING_TOOLS: readonly ["connectors:mappings:list", "connectors:mappings:set", "connectors:mappings:delete", "connectors:mappings:auto-match", "connectors:mappings:completeness", "connectors:mappings:suggest-translation", "connectors:mappings:test", "connectors:mappings:get-provider", "connectors:mappings:set-provider"];
+/**
+ * The two enumeration tools, listed separately so a plugin that has its own connector service does
+ * not have to declare invokers for tools it never calls. Spread both when using the default
+ * enumeration implementation.
+ */
+declare const CONNECTOR_ENUMERATION_TOOLS: readonly ["settings:list-connectors", "settings:get-connector"];
+
+/**
+ * What every hook in this module needs to address one connector + module pair.
+ *
+ * `moduleKey` is a plain input, never a constant baked into the hook, and that is what makes
+ * multi-module usage first-class rather than an afterthought: a consumer with twelve catalogues
+ * passes whichever the operator selected and the query keys, the invalidation and the auto-match
+ * trigger all re-key with it. A consumer with one catalogue passes a module-scope constant. Two of
+ * the three plugins this was promoted from hardcoded their single module INSIDE the hook, which is
+ * why the twelve-module one could not reuse them.
+ */
+interface ConnectorMappingScope {
+    /** Mapping transport. Injected so a consumer can supply a mock or its own. */
+    service: IConnectorMappingService;
+    /**
+     * Selected connector, or `undefined` before the operator has chosen one. Reads stay disabled
+     * while it is absent rather than firing against a placeholder id.
+     */
+    connectorId: string | undefined;
+    /** Wire key the platform stores mappings under, e.g. `repo-monitoring`. */
+    moduleKey: string;
+}
+/** Return shape of {@link useConnectorMappings}. */
+interface UseConnectorMappingsResult {
+    mappings: ConnectorMappingItem[];
+    isLoading: boolean;
+    isFetching: boolean;
+    /**
+     * When the current data was fetched. A real timestamp, not a placeholder: the auto-match trigger
+     * gates on this being newer than the last connector switch, so a constant would either fire on
+     * stale data or never fire at all.
+     */
+    dataUpdatedAt: number;
+    error: Error | undefined;
+    refetch: () => void;
+}
+/**
+ * The mapping rows for one connector + module. Pure read state; pair it with
+ * `useConnectorMappingMutations` for the write side, which reads this hook's cache entry to keep a
+ * partial write from destroying a translation.
+ *
+ * @remarks
+ * No `placeholderData`. The auto-match trigger inspects `mappings.length` immediately after a
+ * connector switch, and keeping the previous connector's rows visible would make an unmapped
+ * connector look mapped and skip the trigger.
+ */
+declare function useConnectorMappings({ service, connectorId, moduleKey, }: ConnectorMappingScope): UseConnectorMappingsResult;
+/** Return shape of {@link useConnectorMappingCompleteness}. */
+interface UseConnectorMappingCompletenessResult {
+    operations: MappingCompletenessResult["operations"];
+    /**
+     * Readiness over REQUIRED operations only, so a correctly configured connector can reach 100%.
+     * Counting optional operations would leave it permanently short, for operations the operator was
+     * never expected to map. See `selectMappingReadiness`.
+     */
+    readiness: MappingReadiness;
+    isLoading: boolean;
+    isFetching: boolean;
+}
+/**
+ * Per-operation mapping completeness — the data behind `MappingCompletenessBanner`.
+ *
+ * @remarks
+ * Keyed with {@link connectorMappingCompletenessQueryKey}, which is a CHILD of the mappings key.
+ * That nesting is load-bearing: completeness is the mappings joined against the live tool schemas,
+ * so every write can change it, and as sibling keys a mutation had to remember to invalidate two.
+ * One plugin invalidated only the mappings key and its banner went stale after every save, clear
+ * and auto-match until the operator navigated away.
+ */
+declare function useConnectorMappingCompleteness({ service, connectorId, moduleKey, }: ConnectorMappingScope): UseConnectorMappingCompletenessResult;
+
+/**
+ * Per-call outcome callbacks for one mapping write.
+ *
+ * Additive and optional, for a caller that SEQUENCES this write after another and has to know which
+ * of the two failed — "the scope saved but the pin did not" is a different situation for the
+ * operator than either write failing alone. The shared error toast still fires either way; these
+ * only let the caller record which half it was.
+ */
+interface MappingWriteCallbacks {
+    onSuccess?: () => void;
+    onError?: () => void;
+}
+/** Options for {@link useConnectorMappingMutations}. */
+interface UseConnectorMappingMutationsOptions extends ConnectorMappingScope {
+    /**
+     * Called after any mutation that SAVES a mapping, with the connector and module it was saved
+     * against.
+     *
+     * @remarks
+     * Exists so a consumer can mirror the operator's connector choice into its own state. One plugin
+     * must: its transcription and feed-poll tasks are background workers with no caller identity, so
+     * they cannot enumerate connectors to discover which one holds the mapping, and without this
+     * write-through they report themselves unconfigured no matter what the Tool Mappings page shows.
+     * Taken as a callback so this hook keeps no domain knowledge of what a consumer stores.
+     *
+     * **It hangs off the mutations rather than the page's click handlers deliberately.** There are
+     * three distinct ways to save a mapping — picking a tool, auto-matching, and saving field
+     * translations — and the third was originally missed, which left an operator who had just fixed a
+     * field mapping with a lane that still reported itself unconfigured and no way to tell why. Every
+     * save funnels through here, so a fourth route cannot reintroduce that.
+     *
+     * Deliberately NOT called by a delete: clearing a mapping is not choosing a connector. Leaving
+     * the recorded id in place makes the lane report "a connector is chosen but has no tool mapped",
+     * which is both accurate and the actionable half.
+     */
+    onMappingSaved?: (connectorId: string, moduleKey: string) => void;
+    /**
+     * Success-toast sink. Defaults to the SDK's `showSuccessToast`, which dispatches the host's
+     * `ethisys:toast` event and no-ops outside a host that wired the listener. Override only to
+     * silence it or to route it somewhere else — the three plugins this was promoted from all
+     * ultimately reached the same host event.
+     */
+    showSuccessToast?: (title: string, description?: string) => void;
+}
+/** Return shape of {@link useConnectorMappingMutations}. */
+interface UseConnectorMappingMutationsResult {
+    /** Runs auto-match for the whole module. No-ops without a connector. */
+    triggerAutoMatch: () => void;
+    isAutoMatching: boolean;
+    /**
+     * Saves one mapping, or clears it when `toolName` is `""`. See the fill-in in the implementation
+     * for why omitting a translation member means "leave it alone" and not "clear it".
+     */
+    updateMapping: (args: ConnectorMappingWriteArgs, callbacks?: MappingWriteCallbacks) => void;
+    isUpdating: boolean;
+    /** Outcome of the most recent auto-match run, or `null` before one has completed. */
+    autoMatchSummary: AutoMatchSummary | null;
+}
+/**
+ * The write side of the connector tool-mapping surface: auto-match, per-operation save, and clear.
+ *
+ * **This hook is the reason this module exists.** It was duplicated byte-for-byte across three
+ * plugins and both production defects on this surface lived inside it:
+ *
+ * 1. **A stale completeness banner.** Two plugins declared their own query keys, one as siblings,
+ *    and its mutations invalidated only the mappings key. Fixed by nesting the completeness key
+ *    beneath the mappings key so one prefix invalidation covers both — see
+ *    {@link connectorMappingsQueryKey} — and there is nothing left for a mutation to forget.
+ *
+ * 2. **Silently destroyed field translations.** The tool-level save omitted the three translation
+ *    members, and because `connectors:mappings:set` treats an omitted member as "no operator
+ *    override" and writes NULL, picking a tool wiped the operator's field mapping and any pinned
+ *    static parameter with it. Confirmed against the production database. Fixed by the fill-in
+ *    below. It had to be fixed three times, in three repos, because this function was identical in
+ *    each — and one of the three never received the fix at all.
+ *
+ * 3. **The translation editor could not CLEAR a side**, which is (2)'s fix taken one step too far.
+ *    See {@link resolveTranslationMember}: it was present in all three repos and was found by this
+ *    module's tests rather than in production.
+ */
+declare function useConnectorMappingMutations({ service, connectorId, moduleKey, onMappingSaved, showSuccessToast, }: UseConnectorMappingMutationsOptions): UseConnectorMappingMutationsResult;
+
+/** Variables for one suggest-translation call. */
+interface SuggestMappingTranslationVars {
+    connectorId: string;
+    moduleKey: string;
+    body: SuggestMappingTranslationBody;
+}
+/** Variables for one dry-run call. */
+interface TestMappingVars {
+    connectorId: string;
+    moduleKey: string;
+    body: TestMappingBody;
+}
+/**
+ * The opt-in "Suggest with AI" action.
+ *
+ * Read-only inference: it invalidates NOTHING, because nothing was written. The caller decides what
+ * to do with the proposal — every consumer so far opens the translation editor seeded with it so
+ * the operator reviews before saving.
+ *
+ * @remarks
+ * A soft failure — AI not configured, or no confident suggestion — comes back as
+ * `{ success: false, error }` rather than an HTTP error. This hook THROWS on it, so the consumer's
+ * shared `meta.errorTitle` handler surfaces the reason. Resolving successfully instead is what made
+ * "Suggest with AI" silently do nothing in the copy this was promoted from: the mutation settled
+ * happily, `result.success` was false, and the caller's `onSuccess` returned early without telling
+ * anyone why.
+ *
+ * The service itself never throws for this case (see `ConnectorMappingService`), so a consumer that
+ * wants to render the soft failure inline rather than as a toast can call the service directly.
+ */
+declare function useSuggestMappingTranslation(service: IConnectorMappingService): UseMutationResult<ConnectorMappingSuggestionResult, Error, SuggestMappingTranslationVars>;
+/**
+ * The "Test mapping" dry-run behind the translation editor's Test panel.
+ *
+ * Never throws for a tool-invocation or extraction failure: those come back as
+ * `{ success: false, error }` and the editor renders them in its own panel, next to the raw
+ * response the operator needs in order to fix the JSON path. Converting that into a toast would
+ * discard the raw response, which is the only actionable half.
+ *
+ * Invalidates nothing — a dry run writes nothing.
+ */
+declare function useTestMapping(service: IConnectorMappingService): UseMutationResult<TestToolMappingResult, Error, TestMappingVars>;
+
+/** Options for {@link useMappingTranslationEditor}. */
+interface UseMappingTranslationEditorOptions {
+    service: IConnectorMappingService;
+    /** `undefined` before a connector is selected; every action no-ops until then. */
+    connectorId: string | undefined;
+    moduleKey: string;
+    /** The rows the editor looks a row up in — pass `useConnectorMappings`' `mappings` straight in. */
+    mappings: ConnectorMappingItem[];
+    /**
+     * The write. Pass `useConnectorMappingMutations`' `updateMapping`, which is what routes the save
+     * through the translation-preserving fill and reports it to `onMappingSaved`.
+     */
+    updateMapping: (args: ConnectorMappingWriteArgs, callbacks?: MappingWriteCallbacks) => void;
+}
+/** Return shape of {@link useMappingTranslationEditor}. */
+interface UseMappingTranslationEditorResult {
+    /** The row being edited, or `undefined` when the editor is closed or the row vanished. */
+    editorRow: ConnectorMappingItem | undefined;
+    /** True when a row is being edited. Gate the dialog's mount on this, not on `editorRow`. */
+    isOpen: boolean;
+    /** Wire to `ConnectorMappingViewProps.onEditTranslation` — the per-row settings icon. */
+    onEditTranslation: (operationKey: string, current: ConnectorMappingTranslationState) => void;
+    /** Wire to `MappingCompletenessBannerProps.onOpenMappingEditor`. */
+    onOpenMappingEditor: (operation: MappingCompletenessItem, seed?: ConnectorMappingTranslationState) => void;
+    /** Wire to `MappingCompletenessBannerProps.onSuggestWithAi`. */
+    onSuggestWithAi: (operation: MappingCompletenessItem) => void;
+    /** Wire to `MappingCompletenessBannerProps.suggestingOperationKey` — drives the per-row spinner. */
+    suggestingOperationKey: string | null;
+    /**
+     * Ready-to-spread props for `ConnectorMappingTranslationEditorView`, valid only while
+     * {@link isOpen}. Mount the dialog conditionally: the component initialises its inputs lazily on
+     * each mount, which is what keeps an operator's in-flight edits sovereign against a concurrent
+     * refresh of the row.
+     */
+    editorProps: ConnectorMappingTranslationEditorProps;
+}
+/**
+ * The translation editor's state machine: which row is open, what it was seeded with, and the three
+ * ways it can be opened.
+ *
+ * This was identical in all three plugins that had a Tool Mappings page, down to the comments, and
+ * it needs nothing plugin-specific — no routing, no identity, no persistence. It is therefore the
+ * part of the page hook that could move wholesale, and the part where a fourth copy would be pure
+ * loss.
+ *
+ * The three entry points and why they differ:
+ *
+ * - **`onEditTranslation`** — the per-row icon. The view already holds the row's persisted
+ *   translation and passes it, so this seeds from the argument.
+ * - **`onOpenMappingEditor`** — the completeness banner's "Open mapping editor". The banner holds a
+ *   completeness item, not a mapping row, so this looks the row up and seeds from it.
+ * - **`onSuggestWithAi`** — the banner's AI assist. Seeds from the model's PROPOSAL for the two
+ *   field maps, while keeping the row's persisted `staticRequestFields`: the advisor reasons about
+ *   canonical field names and has no opinion on a pinned discriminator, so overwriting it with
+ *   nothing would silently drop a static parameter the operator set by hand.
+ *
+ * @remarks
+ * **Save re-issues the write with the row's EXISTING tool name and row version**, which the host
+ * treats as a normal set that leaves the tool selection alone. That route is also why
+ * `onMappingSaved` belongs on the mutation and not on a page's click handlers: saving field
+ * translations is a save, and it was the one of the three save routes originally missed.
+ */
+declare function useMappingTranslationEditor({ service, connectorId, moduleKey, mappings, updateMapping, }: UseMappingTranslationEditorOptions): UseMappingTranslationEditorResult;
+
+/** Options for {@link useAutoMatchOnConnectorSwitch}. */
+interface UseAutoMatchOnConnectorSwitchOptions {
+    connectorId: string | undefined;
+    /**
+     * The module the rows belong to. Part of the latch key, not decoration: one connector commonly
+     * serves several modules, and without this the hook cannot tell "already auto-matched this
+     * scope" from "auto-matched a different module on the same connector".
+     */
+    moduleKey: string;
+    /** The rows as last fetched. Their emptiness is what decides whether to trigger. */
+    mappings: ConnectorMappingItem[];
+    isLoading: boolean;
+    isAutoMatching: boolean;
+    /** `dataUpdatedAt` from `useConnectorMappings` — the fetch-freshness gate. */
+    dataUpdatedAt: number;
+    triggerAutoMatch: () => void;
+    /**
+     * `true` when the consumer arrived with a connector ALREADY selected — a `?connectorId=` deep
+     * link, or a restored/preselected choice. Seeds the switch timestamp to mount time.
+     *
+     * @remarks
+     * The three plugins this was promoted from all carry a comment saying this seed exists "so the
+     * auto-match trigger effect still fires on the first fetch". That is backwards, and the tests
+     * make it plain: seeding raises the bar the fetch timestamp has to clear, so it can only ever
+     * SUPPRESS a trigger, never cause one. A fresh fetch resolves after mount and clears it either
+     * way.
+     *
+     * What it actually does is refuse data that predates the mount. React-query can serve a cached
+     * entry immediately — the operator was on this page a moment ago, or another surface primed the
+     * same key — and with the ref at zero that stale snapshot is enough to fire an auto-match against
+     * a connector nobody has looked at since. Seeding says "wait for a fetch that happened after I
+     * arrived", which is the same statement `markConnectorChanged` makes about a switch. Set it
+     * whenever the connector was chosen before this hook mounted.
+     */
+    initiallySelected?: boolean;
+}
+/** Return shape of {@link useAutoMatchOnConnectorSwitch}. */
+interface UseAutoMatchOnConnectorSwitchResult {
+    /**
+     * Call this whenever the consumer changes the selected connector, from inside its own setter.
+     * The hook cannot observe the change itself in time: it needs the timestamp recorded BEFORE the
+     * new connector's fetch resolves.
+     */
+    markConnectorChanged: () => void;
+}
+/**
+ * Runs auto-match once, automatically, when a freshly selected connector turns out to have nothing
+ * mapped.
+ *
+ * Identical in all three plugins this was promoted from, comments included, and it is entirely
+ * mechanical — no identity, no routing, no persistence — so it moves whole.
+ *
+ * The four gates, each of which was added in response to something:
+ *
+ * 1. **`dataUpdatedAt > connectorChangedAt`.** Only mappings fetched AFTER the latest switch are
+ *    inspected. Without it the previous connector's data briefly reads as empty mid-transition and
+ *    auto-match fires against the wrong connector's emptiness.
+ * 2. **`autoMatchedRef !== connectorId`.** Once per connector. Auto-match that legitimately matches
+ *    nothing would otherwise re-fire on every refetch, forever.
+ * 3. **Something already mapped.** Never overwrite an operator's existing choices. A connector with
+ *    any mapped tool is one a human has already been through.
+ * 4. **Not loading, not already matching.** Obvious, and the reason the button used to appear to do
+ *    nothing when pressed during a fetch.
+ */
+declare function useAutoMatchOnConnectorSwitch({ connectorId, moduleKey, mappings, isLoading, isAutoMatching, dataUpdatedAt, triggerAutoMatch, initiallySelected, }: UseAutoMatchOnConnectorSwitchOptions): UseAutoMatchOnConnectorSwitchResult;
+
+/** Return shape of {@link useMappingBannerDismissal}. */
+interface UseMappingBannerDismissalResult {
+    dismissed: boolean;
+    dismiss: () => void;
+    /** Un-dismisses. Call it when the selected connector changes — see the remarks. */
+    reset: () => void;
+}
+declare function useMappingBannerDismissal(organisationId: string | undefined, moduleKey: string): UseMappingBannerDismissalResult;
+
+/** Query key for one module's provider selection. */
+declare function moduleProviderQueryKey(moduleKey: string): readonly ["connector-mappings", "module-provider", string];
+interface UseModuleProviderOptions {
+    service: IConnectorMappingService;
+    moduleKey: string;
+    /**
+     * Called after a successful write, with the provider as stored. Lets a page invalidate its own
+     * reads — the mappings list is keyed on the connector, so a provider change is a different
+     * connector's rows.
+     */
+    onProviderChanged?: (provider: ModuleProvider) => void;
+}
+interface UseModuleProviderResult {
+    /** The organisation's stored choice, or the unconfigured state while loading or unset. */
+    provider: ModuleProvider;
+    /**
+     * The chosen connector id, or `""` when the module is unconfigured or served by a plugin.
+     *
+     * Shaped to drop straight into `useConnectorToolMappings`'s `connectorId`, which is the whole
+     * point of this hook: that surface already takes the selection as an input, so adopting the
+     * organisation-wide answer is a change of SOURCE and not a change to the surface.
+     */
+    connectorId: string;
+    isLoading: boolean;
+    /** Point the module at a connector. Pass `""` to clear the selection back to unconfigured. */
+    selectConnector: (connectorId: string) => void;
+    /** Point the module at another installed extension. */
+    selectExtension: (extensionId: string) => void;
+    isSaving: boolean;
+    error?: unknown;
+}
+/**
+ * Reads and writes WHICH PROVIDER serves a module, as the organisation's own stored answer.
+ *
+ * @remarks
+ * **This replaces a browser-local selection, and that is the entire point.** Before the host had
+ * somewhere to put it, each plugin kept the operator's connector choice in `localStorage` — so the
+ * answer was per-device rather than per-organisation. One operator selected a provider, a colleague
+ * still saw the old one, and the two never reconciled. Worse, the two mechanisms could disagree
+ * about a module that a plugin now serves, which is the situation the whole provider-selection
+ * concept exists to end.
+ *
+ * **A clear is a first-class outcome.** `selectConnector("")` writes the unconfigured state rather
+ * than silently doing nothing, because "no provider chosen" and "chose a connector with no mappings
+ * yet" are different situations with different remedies — the host deliberately does not default
+ * one to the other, and neither does this.
+ *
+ * **The row version is handled here so callers never see it.** It is read from the query, sent on
+ * the write, and refreshed from the write's response. A caller that has to thread a concurrency
+ * token through its own state is a caller that will eventually send a stale one.
+ */
+declare function useModuleProvider({ service, moduleKey, onProviderChanged, }: UseModuleProviderOptions): UseModuleProviderResult;
+
+/**
+ * What a canonical operation resolves to, and what happens to its field translation when that
+ * changes.
+ *
+ * The Tool Mappings surface used to have one answer: a connector's tool. The platform now also
+ * lets a mapping target another installed application's MCP tool, so "Projects reads employees
+ * from the HR app" and "Projects reads them from Workday" are the same configuration with a
+ * different provider. That makes the target a two-part thing - WHO provides it, and WHICH of their
+ * tools - and this module owns the rules that follow from it.
+ *
+ * Pure by design. No react, no react-query, no transport: every rule here is a function of its
+ * arguments, so the rules that were previously comments inside a mutation hook are now things a
+ * test can fail.
+ */
+
+/**
+ * The UI-side kind as the host spells it.
+ *
+ * The host persists this string VERBATIM and matches it by name and case against its own
+ * `ToolMappingTargetKind`, so a differently-cased value is stored as something that matches neither
+ * branch of the resolver nor the database CHECK constraint. Converting in one named function is
+ * what keeps that from being retyped as a literal at a call site.
+ */
+declare function toWireTargetKind(kind: MappingTargetKind): MappingTargetKindWire;
+/**
+ * The host's kind as this surface spells it, or `null`.
+ *
+ * `null` covers two cases on purpose, because the UI does the same thing in both: the module has no
+ * selection at all (the host returns a null `targetKind` for an unconfigured module, and
+ * deliberately does NOT default it to `"Connector"`), or the stored string matched neither member.
+ * An unrecognised value is NOT guessed into a kind - rendering a choice nobody made is the exact
+ * failure the host's own null is there to avoid, and a guess here would reintroduce it one layer up.
+ */
+declare function fromWireTargetKind(value: string | null | undefined): MappingTargetKind | null;
+/**
+ * Who answers a module's operations: a connector to a third-party system, or another installed
+ * application.
+ *
+ * The plugin arm carries the providing extension rather than inferring it from the tool name's
+ * prefix. That is the host's requirement and its reasoning is worth keeping here: the router
+ * resolves a plugin tool by SCANNING the enabled extensions for a name match, breaking a duplicate
+ * module-key collision by lowest extension id. A scan result is not a choice, and this type is
+ * about recording a choice.
+ */
+type MappingProvider = {
+    kind: "connector";
+    connectorId: string;
+} | {
+    kind: "plugin";
+    targetExtensionId: string;
+};
+/**
+ * A provider plus the specific tool of theirs that answers one operation.
+ *
+ * `toolName` means different things per arm, and both are the host's shape rather than this
+ * module's invention: a connector target stores the BARE vendor verb, because the
+ * `integrations:{slug}:` prefix is a function of the connector and not of the row; a plugin target
+ * stores the FULLY NAMESPACED name (`hr:get-employees-by-ids`), because a plugin tool has no slug
+ * to prefix and already routes verbatim.
+ *
+ * `""` is the unmap request, exactly as on the connector-only surface.
+ */
+type MappingTarget = MappingProvider & {
+    toolName: string;
+};
+/**
+ * The stored mapping a write is replacing, reduced to the parts that decide what happens to the
+ * translation.
+ *
+ * Both provider ids are optional because a caller assembles this from a row plus whatever it knows
+ * about where the row came from - the connector-scoped list read, for instance, returns rows that
+ * do not repeat the connector id the caller passed to fetch them. Absent is treated as "not the
+ * same provider"; see {@link isSameTarget} for why that direction is the safe one.
+ */
+interface ExistingMappingTarget extends Partial<ConnectorMappingTranslationState> {
+    operationKey: string;
+    targetKind: MappingTargetKind;
+    /** The tool currently mapped, or `null` when the operation is unmapped. */
+    mappedToolName: string | null;
+    connectorId?: string | null;
+    targetExtensionId?: string | null;
+}
+/**
+ * One mapping write, with every translation member decided.
+ *
+ * The three translation members are REQUIRED and nullable rather than optional, matching
+ * `IConnectorMappingService.updateMapping` and for the same reason: on this surface an omitted
+ * member and a null member both write NULL host-side, so a type that lets a member be omitted lets
+ * a caller destroy a translation without saying so.
+ *
+ * The two provider ids ARE optional, and exactly one of them is ever present. Absent rather than
+ * null: "there is no connector here" and "clear the connector" are different statements, and only
+ * one of them is true of a plugin target.
+ */
+interface MappingUpdate extends ConnectorMappingTranslationState {
+    targetKind: MappingTargetKind;
+    toolName: string;
+    connectorId?: string;
+    targetExtensionId?: string;
+}
+/**
+ * Does the write land on the SAME tool the stored translation was written against?
+ *
+ * Identity is the whole target - kind, provider, and tool name - not the tool name alone, and that
+ * is deliberately stricter than a literal reading of the rule it serves. A bare vendor verb is not
+ * unique: `get_file_contents` names a different tool with a different parameter shape in every
+ * connector that has one, so comparing names alone would carry a translation from one vendor's tool
+ * onto another's and call it unchanged.
+ *
+ * Unknown provenance counts as a different target. When a caller supplies no provider id on
+ * {@link ExistingMappingTarget}, this returns `false` and the translation is discarded. That is the
+ * safe direction of an unavoidable choice: a discarded translation is visibly absent and the
+ * operator re-enters it, a carried-over one is silently wrong and nothing on the page says so.
+ */
+declare function isSameTarget(existing: ExistingMappingTarget | null | undefined, next: MappingTarget): boolean;
+/** Arguments for {@link buildMappingUpdate}. */
+interface BuildMappingUpdateArgs {
+    /** The stored mapping, or `null` when the operation has never been mapped. */
+    existing: ExistingMappingTarget | null;
+    /** Where the operation is being pointed now. */
+    next: MappingTarget;
+    /**
+     * The translation the caller is EXPLICITLY setting, member by member.
+     *
+     * Read with `!== undefined`, never `??`, and the difference is the whole point:
+     *
+     * - a member left `undefined` is the caller not talking about it, and it is decided by the
+     *   target-change rule below;
+     * - a member set to `null` is the caller SAYING clear it, and it survives untouched.
+     *
+     * `??` collapses those two into one, which is the defect this surface has shipped three times -
+     * once as "picking a tool wiped the operator's field mapping", once as "the editor could not
+     * clear a side at all", and once in each of three plugin repos.
+     */
+    translation?: Partial<ConnectorMappingTranslationState>;
+}
+/**
+ * Builds the write for pointing one operation at a target, deciding what happens to its translation.
+ *
+ * Two rules, and they are separate because they answer different questions:
+ *
+ * 1. **A translation belongs to ONE tool.** When the target changes, `requestFieldMap`,
+ *    `responseFieldPaths` and `staticRequestFields` are DISCARDED rather than carried across. They
+ *    are a map onto one tool's parameter names, and against a different tool they do not degrade -
+ *    they silently mean something else. Switching provider necessarily changes the tool, so this
+ *    fires on every provider switch and not only on a tool edit within a provider.
+ *
+ * 2. **Omitted is not cleared.** Whatever the caller states in `translation` wins, including an
+ *    explicit `null`. An operator supplying a translation for the new tool in the same action is
+ *    not fighting rule 1; rule 1 exists because nobody said anything about the translation, and
+ *    here somebody did.
+ *
+ * The order matters and is asserted by the tests: an explicit member beats the discard, and the
+ * discard beats the carry-forward.
+ */
+declare function buildMappingUpdate({ existing, next, translation, }: BuildMappingUpdateArgs): MappingUpdate;
+/**
+ * The provider half of a target, for the per-module selection. Drops the tool, because the module
+ * selection is a choice about WHO serves the module and every operation under it keeps its own tool.
+ */
+declare function providerOf(target: MappingTarget): MappingProvider;
+/**
+ * The provider's id, whichever half it is. For a caller that only needs to know whether the choice
+ * changed, rather than which kind it is.
+ */
+declare function providerIdOf(provider: MappingProvider): string;
+
+/** A connector as the mapping picker renders it. */
+interface ConnectorOption {
+    id: string;
+    name: string;
+}
+/** A tool as the per-row mapping autocomplete renders it. */
+interface ConnectorToolOption {
+    name: string;
+    description: string;
+}
+/**
+ * Project the organisation's connectors down to the picker's option shape.
+ *
+ * @remarks
+ * **Deliberately unfiltered.** One plugin filtered this list to MCP connectors, because its
+ * connector service returned every type; another reads `settings:list-connectors`, whose projection
+ * does not carry a connector type at all, so the same filter compared against `undefined` and hid
+ * every connector — a picker that is empty for a reason no operator could work out. The host
+ * already scopes the list to the current organisation, and a mapping against a connector that
+ * cannot serve it fails loudly at Test. A consumer whose own service returns types it must exclude
+ * should filter BEFORE calling this, where it can name what it is excluding and why.
+ */
+declare function mapConnectorsToOptions(connectors: readonly ConnectorSummary[]): ConnectorOption[];
+/**
+ * Project a connector's tools down to the mapping autocomplete's option shape.
+ *
+ * Disabled tools are dropped: an operator can only map an operation to a tool the connector is
+ * currently exposing, and offering a switched-off one produces a mapping that resolves to nothing
+ * at runtime. The service returns them unfiltered on purpose — see
+ * `ConnectorMappingService.listConnectorTools` — so the distinction stays visible one layer down.
+ */
+declare function mapConnectorToolsToOptions(tools: readonly ConnectorToolSummary[]): ConnectorToolOption[];
+
+/** Options for {@link useConnectorToolMappings}. */
+interface UseConnectorToolMappingsOptions {
+    /** Mapping transport. See `ConnectorMappingService` for the default implementation. */
+    service: IConnectorMappingService;
+    /** `""` or `undefined` before the operator has chosen one. */
+    connectorId: string | undefined;
+    /**
+     * Selected module. A plain input, so a consumer with ONE catalogue passes a module-scope constant
+     * and a consumer with twelve passes whichever the operator selected — every query key, the
+     * invalidation, the auto-match trigger and the banner dismissal re-key with it.
+     */
+    moduleKey: string;
+    /** Human label for the module, for the view's own header and empty state. */
+    moduleLabel: string;
+    /**
+     * The connectors to offer. Injected because connector enumeration differs genuinely between
+     * consumers — one reads `settings:list-connectors`, one pages a full connector CRUD service, one
+     * has no source yet — and none of those belongs in a mapping hook. `mapConnectorsToOptions`
+     * projects the default service's shape.
+     */
+    connectors: ConnectorOption[];
+    /**
+     * Whether the CONNECTORS query is still in flight. Folded into the view's `isLoading` because the
+     * mappings query is disabled until a connector is chosen and therefore reports `isLoading: false`
+     * on first load — which made the view skip its skeleton and render the picker as an EMPTY
+     * dropdown while the connector list was still loading. It read as "this organisation has no
+     * connectors", and then they appeared.
+     */
+    isConnectorsLoading?: boolean;
+    /** The selected connector's mappable tools. `mapConnectorToolsToOptions` projects them. */
+    availableTools: ConnectorToolOption[];
+    /**
+     * The consumer's connector setter — bare `setState`, a persisting setter, a URL write, whatever
+     * it owns. Wrapped here so the auto-match trigger learns of the switch; the consumer wires the
+     * returned `view.onConnectorChange` to its picker and never calls its own setter directly.
+     */
+    onConnectorChange: (connectorId: string) => void;
+    /** `true` when a connector was already selected on mount (deep link / restored / preselected). */
+    initiallySelected?: boolean;
+    /**
+     * Opts this hook into the per-module provider choice: it reads and writes the organisation's
+     * stored provider through {@link useModuleProvider} on the `service` already passed above, and
+     * hands the view the picker's props.
+     *
+     * Defaults to `false`, and the default is the load-bearing part. The transport exists -
+     * `connectors:mappings:get-provider` and `connectors:mappings:set-provider` are real tools - but
+     * only on a host that has them DEPLOYED, and this package is pinned independently by every
+     * plugin. Turning the read on for every existing consumer would fire a tool call an older host
+     * answers with an error toast, on a surface that worked. A consumer opts in when its host is
+     * ready, and adds the two tool names to its `useToolInvokerMap`.
+     */
+    providerSelectionEnabled?: boolean;
+    /**
+     * The installed applications on offer, with the tools each can answer this module's operations
+     * with.
+     *
+     * An INPUT rather than something this hook fetches, matching {@link connectors} and for the same
+     * reason: the candidate set is a server-side authorisation decision (see
+     * {@link PluginProviderCandidate}), and no consumer should be able to widen it by filtering
+     * client-side. Supply it from whatever surface the host eventually exposes - there is no
+     * candidate-list endpoint in any transport today, which is why this cannot be fetched here.
+     *
+     * Left empty, the app arm of the picker has nothing to offer, so the view renders the connector
+     * arm only.
+     */
+    pluginProviders?: PluginProviderCandidate[];
+    /** Whether the candidate list is still in flight. Folded into the view's `isLoading`. */
+    isPluginProvidersLoading?: boolean;
+    /**
+     * Current organisation, for the per-tenant banner dismissal. Injected because identity differs:
+     * one plugin reads `useHostIdentity`, two read a local `useAuth`. Absent is handled — dismissal
+     * simply does not persist until identity resolves.
+     */
+    organisationId?: string;
+    /** Href of the host's AI-providers settings page. Routing is never owned here. */
+    aiProvidersHref: string;
+    /** Href of the selected connector's settings page, already scoped to `connectorId`. */
+    connectorSettingsHref: string;
+    /** Passed through to the view. See `ConnectorMappingViewProps.withHeader`. */
+    withHeader?: boolean;
+    /**
+     * Called after any save. See `useConnectorMappingMutations` — this is the hook a consumer needs
+     * in order to mirror the connector into its own settings, without which a background worker
+     * cannot find a connector at all.
+     */
+    onMappingSaved?: (connectorId: string, moduleKey: string) => void;
+    /** Success-toast sink. Defaults to the SDK's host-event toast. */
+    showSuccessToast?: (title: string, description?: string) => void;
+}
+/**
+ * Props for `ConnectorMappingView`, minus nothing — spread this straight onto it.
+ *
+ * Declared structurally rather than imported from the component so this module stays free of
+ * `@mui/material`: a consumer can take the hooks without installing MUI, and the view's own props
+ * type is assignable to this.
+ */
+interface ConnectorMappingViewBundle {
+    isLoading: boolean;
+    moduleKey: string;
+    moduleLabel: string;
+    withHeader?: boolean;
+    connectors: ConnectorOption[];
+    selectedConnectorId: string;
+    onConnectorChange: (connectorId: string) => void;
+    providerKind?: MappingTargetKind;
+    onProviderKindChange?: (kind: MappingTargetKind) => void;
+    pluginProviders?: {
+        extensionId: string;
+        name: string;
+    }[];
+    selectedPluginExtensionId?: string;
+    onPluginProviderChange?: (extensionId: string) => void;
+    mappings: ConnectorMappingItem[];
+    availableTools: ConnectorToolOption[];
+    onUpdateMapping: (operationKey: string, toolName: string, rowVersion: string) => void;
+    onAutoMatch: () => void;
+    isUpdating: boolean;
+    isAutoMatching: boolean;
+    bannerState: ReturnType<typeof useConnectorMappingMutations>["autoMatchSummary"];
+    onDismissBanner: () => void;
+    aiProvidersHref: string;
+    connectorSettingsHref: string;
+    onEditTranslation: (operationKey: string, current: ConnectorMappingTranslationState) => void;
+}
+/** Return shape of {@link useConnectorToolMappings}. */
+interface UseConnectorToolMappingsResult {
+    /** Spread onto `ConnectorMappingView`. */
+    view: ConnectorMappingViewBundle;
+    /**
+     * Spread onto `MappingCompletenessBanner`.
+     *
+     * Render it whenever `banner.isProviderUnconfigured` is true, and otherwise only when a provider
+     * is selected. Gating the mount on a selected CONNECTOR - which the pre-provider guidance here
+     * said, because a connector was the only provider there was - would hide the one message that
+     * tells an operator how to select one.
+     */
+    banner: MappingCompletenessBannerProps;
+    /** Spread onto `ConnectorMappingTranslationEditorView`. Mount it only when `isEditorOpen`. */
+    editor: ConnectorMappingTranslationEditorProps;
+    /** Gate the editor dialog's MOUNT on this, so it reseeds from the row each time it opens. */
+    isEditorOpen: boolean;
+    /** The row the editor is open for, or `undefined`. Exposed for a consumer's own render guards. */
+    editorRow: ConnectorMappingItem | undefined;
+    /** The rows, for a consumer that renders something of its own alongside the table. */
+    mappings: ConnectorMappingItem[];
+    /** Per-operation completeness, for a consumer that wants it outside the banner. */
+    completenessOperations: MappingCompletenessItem[];
+    /** Readiness over REQUIRED operations only — for a progress indicator or a "ready" badge. */
+    readiness: MappingReadiness;
+    /** True while either query is loading, connectors included. */
+    isLoading: boolean;
+}
+/**
+ * The whole Tool Mappings surface for one connector + module, assembled from the parts in this
+ * module.
+ *
+ * ## What this is, and what it deliberately is not
+ *
+ * Three plugins each had a ~300-line page hook, and roughly 85% of each was identical. This is that
+ * 85%: the reads, the writes, the translation editor, the auto-match trigger, the banner dismissal,
+ * and the three prop bundles a page spreads. What is NOT here is the 15% that genuinely differs —
+ * **which** connector and module are selected, where the selection is remembered, where identity
+ * comes from, how hrefs are built, and how connectors are enumerated. Those arrive as inputs.
+ *
+ * That split is not a compromise, it is the finding: every one of those five is a real difference
+ * between the three consumers, and every attempt to absorb one would have imported a plugin's
+ * router, auth module or connector service into this package. A consumer's remaining page hook is
+ * the selection logic and nothing else.
+ *
+ * ## Multi-module is not a special case
+ *
+ * `moduleKey` and `moduleLabel` are ordinary inputs, so a page with a module selector re-renders
+ * this hook with the new key and everything downstream re-keys — including the auto-match trigger,
+ * which will then evaluate the new module's emptiness rather than the old one's. A page with one
+ * module passes a constant and pays nothing.
+ *
+ * @example Single-module consumer
+ * ```ts
+ * const surface = useConnectorToolMappings({
+ *   service,
+ *   connectorId,
+ *   moduleKey: MODULE_KEY,
+ *   moduleLabel: "Repo Monitoring",
+ *   connectors: mapConnectorsToOptions(connectors),
+ *   isConnectorsLoading,
+ *   availableTools: mapConnectorToolsToOptions(connectorDetail?.tools ?? []),
+ *   onConnectorChange: setConnectorId,
+ *   organisationId: user?.organisationId,
+ *   aiProvidersHref: routes.settings.aiProviders.root(),
+ *   connectorSettingsHref: connectorId
+ *     ? routes.settings.connectors.details(connectorId)
+ *     : routes.settings.connectors.root(),
+ * });
+ * ```
+ */
+declare function useConnectorToolMappings({ service, connectorId, moduleKey, moduleLabel, connectors, isConnectorsLoading, availableTools, onConnectorChange, initiallySelected, organisationId, aiProvidersHref, connectorSettingsHref, withHeader, onMappingSaved, showSuccessToast, providerSelectionEnabled, pluginProviders, isPluginProvidersLoading, }: UseConnectorToolMappingsOptions): UseConnectorToolMappingsResult;
+
+export { AI_UNAVAILABLE_REASON, AUTO_MATCH_CONFLICT_REASON, type AutoMatchResponse, type AutoMatchSummary, type BuildMappingUpdateArgs, CONNECTOR_ENUMERATION_TOOLS, CONNECTOR_MAPPING_TOOLS, type ConnectorAiUnavailableReason, type ConnectorAutoMatchConflictReason, type ConnectorAutoMatchItem, ConnectorCanonicalField, type ConnectorMappingItem, type ConnectorMappingScope, ConnectorMappingService, type ConnectorMappingSource, ConnectorMappingSuggestionResult, type ConnectorMappingTranslationState, type ConnectorMappingViewBundle, type ConnectorMappingWriteArgs, type ConnectorOption, type ConnectorSummary, type ConnectorToolOption, type ConnectorToolSummary, type ExistingMappingTarget, type IConnectorEnumerationService, type IConnectorMappingService, MAPPING_SOURCE, MAPPING_TARGET_KIND, MAPPING_TARGET_KIND_WIRE, MODULE_PROVIDER_KIND, MappingCompletenessItem, MappingCompletenessResult, type MappingProvider, MappingReadiness, type MappingTarget, type MappingTargetKind, type MappingTargetKindWire, type MappingUpdate, type MappingWriteCallbacks, type ModuleProvider, type ModuleProviderKind, type PluginProviderCandidate, type PluginProviderTool, type PluginTargetMappingItem, type SetPluginTargetMappingArgs, type SetPluginTargetMappingResult, type SuggestMappingTranslationBody, type SuggestMappingTranslationVars, type TestMappingBody, type TestMappingVars, TestToolMappingResult, type UseAutoMatchOnConnectorSwitchOptions, type UseAutoMatchOnConnectorSwitchResult, type UseConnectorMappingCompletenessResult, type UseConnectorMappingMutationsOptions, type UseConnectorMappingMutationsResult, type UseConnectorMappingsResult, type UseConnectorToolMappingsOptions, type UseConnectorToolMappingsResult, type UseMappingBannerDismissalResult, type UseMappingTranslationEditorOptions, type UseMappingTranslationEditorResult, type UseModuleProviderOptions, type UseModuleProviderResult, buildMappingUpdate, fromWireTargetKind, isSameTarget, mapConnectorToolsToOptions, mapConnectorsToOptions, moduleProviderQueryKey, providerIdOf, providerOf, toWireTargetKind, useAutoMatchOnConnectorSwitch, useConnectorMappingCompleteness, useConnectorMappingMutations, useConnectorMappings, useConnectorToolMappings, useMappingBannerDismissal, useMappingTranslationEditor, useModuleProvider, useSuggestMappingTranslation, useTestMapping };