@sellable/mcp 0.1.752 → 0.1.754

package/dist/tools/integrations.d.ts

@@ -0,0 +1,322 @@
+import type { AgentIntegrationRequestContext } from "../agent-integration-request-context.js";
+/**
+ * The THREE provider-neutral managed-integration tools.
+ *
+ * ## PROVIDER TOOL NAMES ARE ARGUMENTS. That is the architecture in one sentence.
+ *
+ * `gmail-find-email` is a `toolName` STRING passed at call time. Nothing writes it
+ * into a config file, a Hermes profile, a `tools.include` list, or an MCP tool name.
+ * A source scan in `tests/mcp/integration-tools.test.ts` asserts no provider action
+ * key appears under `packages/sellable-install/**` or in any generated config, so
+ * the deleted materialization design cannot creep back.
+ *
+ * Three problems disappear from this phase as a consequence, worth recording so
+ * nobody re-solves them: the `profile-materializer` tool-name regex (no hyphens,
+ * 128 chars, sorted, duplicate-free) never has to accept a hyphenated provider key;
+ * the global-flat-list mutation hazard has no list to mutate; and the context-bloat
+ * problem of materializing N provider tools into every prompt does not exist.
+ *
+ * ## THE ACTOR IS NOT A TOOL INPUT
+ *
+ * No `inputSchema` here carries a requester, a channel, or an actor field, and this
+ * module DESIGNS NO ACTOR MECHANISM — it CONSUMES plan 141-04 T2's. The trusted
+ * triple arrives from `boundary.context` (which the MCP context proxy injects only
+ * after REJECTING any model-supplied `_meta`) and `server.ts` passes it here, where
+ * it becomes an explicit versioned BODY field the route re-verifies against
+ * `WorkspaceSlackIdentity`. A model-supplied actor claim is worthless, so the model
+ * is never offered a place to put one.
+ *
+ * ## WHY `registry.ts` AND `server.ts` ARE SHARED, NOT OWNED
+ *
+ * Phase 142 plan 142-05 adds three CONNECT tools to the same two files. Phase 141
+ * merges first, so 142's edits are additive to this plan's landed set. Neither plan
+ * may claim exclusive ownership of `registry.ts` or `server.ts`, and neither may
+ * reorder the other's entries.
+ *
+ * Registering three tools also grows `SELLABLE_MCP_TOOL_NAMES`, and
+ * `src/lib/sellable-agent/worker-broker.ts:832-837` computes `toolInclude` from it
+ * into the runtime revision manifest — so `toolsHash` moves ONCE. That is expected:
+ * plan 141-04 T1's drift test classifies a moved `toolsHash` as `RELOAD_MCP`, a
+ * one-time installer-version event exercised by plan 141-09's canary. It is NOT a
+ * per-connect event; 141-04's zero-drift proof is about connects.
+ *
+ * Release versioning is not tool registration: `mcp/sellable/package.json` is
+ * UNTOUCHED here and plan 141-09 T2 owns the `@sellable/mcp` WIP version.
+ */
+/**
+ * THE PUBLISHED RESULT ENVELOPE — a cross-phase contract, not prose.
+ *
+ * Plan 142-05 T1 carries `SA142-52`, which requires the connect tools' envelopes to
+ * MIRROR this one key-for-key, and instructs its executor to STOP and report rather
+ * than guess if the contract "is not importable from the MCP package". So it is
+ * exported, frozen, and structurally asserted against every handler result.
+ *
+ * The key set is STABLE across success and failure — `error` and `guidance` are
+ * present as `null` rather than omitted — which is what makes a structural
+ * comparison possible at all.
+ *
+ * | key           | meaning                                                        |
+ * | ------------- | -------------------------------------------------------------- |
+ * | `ok`          | the success/failure DISCRIMINATOR                              |
+ * | `outcome`     | snake_case: `ok`, `refused`, `approval_required`, `catalog_incomplete`, `not_connected`, `upstream_degraded` |
+ * | `attribution` | snake_case: `provider`, `configuration`, `policy`, `sellable`   |
+ * | `error`       | the snake_case code, forwarded VERBATIM from the route          |
+ * | `guidance`    | one human sentence, or `null`                                   |
+ * | `result`      | the payload                                                     |
+ *
+ * `approval_required` and `catalog_incomplete` are RESULTS inside this envelope, not
+ * errors: the Agent must be able to explain them, not just fail.
+ */
+export declare const INTEGRATIONS_RESULT_ENVELOPE_KEYS: readonly ["ok", "outcome", "attribution", "error", "guidance", "result"];
+export type IntegrationsResultEnvelopeKey = (typeof INTEGRATIONS_RESULT_ENVELOPE_KEYS)[number];
+export type IntegrationsResultEnvelope = {
+    ok: boolean;
+    outcome: string;
+    attribution: string;
+    error: string | null;
+    guidance: string | null;
+    result: unknown;
+};
+export declare const integrationsToolDefinitions: ({
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            readonly appSlug: {
+                readonly type: "string";
+                readonly minLength: 1;
+                readonly maxLength: 64;
+                readonly description: "The connected app, e.g. 'gmail'. Use this when the workspace has exactly one connected account for the app; if it has more than one, the call is refused as ambiguous and you must pass accountLabel instead.";
+            };
+            readonly bindingId: {
+                readonly type: "string";
+                readonly minLength: 1;
+                readonly maxLength: 64;
+                readonly description: "An exact integration binding id, as returned by a previous integrations_list_tools call.";
+            };
+            readonly accountLabel: {
+                readonly type: "string";
+                readonly minLength: 1;
+                readonly maxLength: 120;
+                readonly description: "The human label the user gave the connected account. This is the ONLY way to tell two connections over the same inbox apart, because the provider's own account name can be byte-identical for both.";
+            };
+        };
+        required: never[];
+        additionalProperties: boolean;
+    };
+    outputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly ok: {
+                readonly type: "boolean";
+            };
+            readonly outcome: {
+                readonly type: "string";
+                readonly enum: readonly ["ok", "refused", "approval_required", "catalog_incomplete", "not_connected", "upstream_degraded"];
+            };
+            readonly attribution: {
+                readonly type: "string";
+                readonly enum: readonly ["provider", "configuration", "policy", "sellable"];
+            };
+            readonly error: {
+                readonly type: readonly ["string", "null"];
+            };
+            readonly guidance: {
+                readonly type: readonly ["string", "null"];
+            };
+            readonly result: {};
+        };
+        readonly required: readonly ["ok", "outcome", "attribution", "error", "guidance", "result"];
+        readonly additionalProperties: false;
+    };
+    annotations: {
+        title: string;
+        readOnlyHint: boolean;
+        destructiveHint: boolean;
+        idempotentHint: boolean;
+        openWorldHint: boolean;
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            toolName: {
+                type: string;
+                minLength: number;
+                maxLength: number;
+                description: string;
+            };
+            propName: {
+                type: string;
+                minLength: number;
+                maxLength: number;
+                description: string;
+            };
+            optionQuery: {
+                type: string;
+                minLength: number;
+                maxLength: number;
+                description: string;
+            };
+            appSlug: {
+                readonly type: "string";
+                readonly minLength: 1;
+                readonly maxLength: 64;
+                readonly description: "The connected app, e.g. 'gmail'. Use this when the workspace has exactly one connected account for the app; if it has more than one, the call is refused as ambiguous and you must pass accountLabel instead.";
+            };
+            bindingId: {
+                readonly type: "string";
+                readonly minLength: 1;
+                readonly maxLength: 64;
+                readonly description: "An exact integration binding id, as returned by a previous integrations_list_tools call.";
+            };
+            accountLabel: {
+                readonly type: "string";
+                readonly minLength: 1;
+                readonly maxLength: 120;
+                readonly description: "The human label the user gave the connected account. This is the ONLY way to tell two connections over the same inbox apart, because the provider's own account name can be byte-identical for both.";
+            };
+        };
+        required: string[];
+        additionalProperties: boolean;
+    };
+    outputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly ok: {
+                readonly type: "boolean";
+            };
+            readonly outcome: {
+                readonly type: "string";
+                readonly enum: readonly ["ok", "refused", "approval_required", "catalog_incomplete", "not_connected", "upstream_degraded"];
+            };
+            readonly attribution: {
+                readonly type: "string";
+                readonly enum: readonly ["provider", "configuration", "policy", "sellable"];
+            };
+            readonly error: {
+                readonly type: readonly ["string", "null"];
+            };
+            readonly guidance: {
+                readonly type: readonly ["string", "null"];
+            };
+            readonly result: {};
+        };
+        readonly required: readonly ["ok", "outcome", "attribution", "error", "guidance", "result"];
+        readonly additionalProperties: false;
+    };
+    annotations: {
+        title: string;
+        readOnlyHint: boolean;
+        destructiveHint: boolean;
+        idempotentHint: boolean;
+        openWorldHint: boolean;
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            toolName: {
+                type: string;
+                minLength: number;
+                maxLength: number;
+                description: string;
+            };
+            arguments: {
+                type: string;
+                description: string;
+                additionalProperties: boolean;
+            };
+            approvalId: {
+                type: string;
+                minLength: number;
+                maxLength: number;
+                description: string;
+            };
+            appSlug: {
+                readonly type: "string";
+                readonly minLength: 1;
+                readonly maxLength: 64;
+                readonly description: "The connected app, e.g. 'gmail'. Use this when the workspace has exactly one connected account for the app; if it has more than one, the call is refused as ambiguous and you must pass accountLabel instead.";
+            };
+            bindingId: {
+                readonly type: "string";
+                readonly minLength: 1;
+                readonly maxLength: 64;
+                readonly description: "An exact integration binding id, as returned by a previous integrations_list_tools call.";
+            };
+            accountLabel: {
+                readonly type: "string";
+                readonly minLength: 1;
+                readonly maxLength: 120;
+                readonly description: "The human label the user gave the connected account. This is the ONLY way to tell two connections over the same inbox apart, because the provider's own account name can be byte-identical for both.";
+            };
+        };
+        required: string[];
+        additionalProperties: boolean;
+    };
+    outputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly ok: {
+                readonly type: "boolean";
+            };
+            readonly outcome: {
+                readonly type: "string";
+                readonly enum: readonly ["ok", "refused", "approval_required", "catalog_incomplete", "not_connected", "upstream_degraded"];
+            };
+            readonly attribution: {
+                readonly type: "string";
+                readonly enum: readonly ["provider", "configuration", "policy", "sellable"];
+            };
+            readonly error: {
+                readonly type: readonly ["string", "null"];
+            };
+            readonly guidance: {
+                readonly type: readonly ["string", "null"];
+            };
+            readonly result: {};
+        };
+        readonly required: readonly ["ok", "outcome", "attribution", "error", "guidance", "result"];
+        readonly additionalProperties: false;
+    };
+    annotations: {
+        title: string;
+        /**
+         * DECLARED HONESTLY as `false`, even though every v1-allowlisted Gmail
+         * action is `readOnlyHint: true`.
+         *
+         * This tool is PROVIDER-NEUTRAL and its allowlist is DATA: the moment a
+         * mutating action is promoted on any binding, a `true` here becomes a lie
+         * that no test would catch, because nothing would have changed in this file.
+         * A false negative on an annotation costs a little caution; a false positive
+         * costs a silent write.
+         */
+        readOnlyHint: boolean;
+        destructiveHint: boolean;
+        idempotentHint: boolean;
+        openWorldHint: boolean;
+    };
+})[];
+type SelectorInput = {
+    appSlug?: unknown;
+    bindingId?: unknown;
+    accountLabel?: unknown;
+};
+export declare function integrationsListTools(input?: SelectorInput, actor?: AgentIntegrationRequestContext | null, agentEffectId?: string): Promise<IntegrationsResultEnvelope>;
+export declare function integrationsDescribeTool(input?: SelectorInput & {
+    toolName?: unknown;
+    propName?: unknown;
+    optionQuery?: unknown;
+}, actor?: AgentIntegrationRequestContext | null, agentEffectId?: string): Promise<IntegrationsResultEnvelope>;
+export declare function integrationsCallTool(input?: SelectorInput & {
+    toolName?: unknown;
+    arguments?: unknown;
+    approvalId?: unknown;
+}, actor?: AgentIntegrationRequestContext | null, agentEffectId?: string): Promise<IntegrationsResultEnvelope>;
+export {};