@sellable/mcp 0.1.753 → 0.1.755

package/dist/agent-integration-request-context.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Trusted request-actor plumbing for the managed-integration tools.
+ *
+ * WHY THIS IS A SEPARATE MODULE. `server.ts` calls `main()` at import time and
+ * connects a stdio transport, so it cannot be imported by a unit test. The
+ * tool-name set and the fail-closed resolver therefore live here, `server.ts`
+ * imports them, and plan 141-06 imports the same constant when it registers the
+ * three `case` labels. One source of truth, testable in isolation.
+ *
+ * THE ACTOR IS NEVER A TOOL INPUT, and there is exactly one mechanism.
+ * `packages/sellable-install/lib/sellable-agent/mcp-context-proxy.mjs:352-402`
+ * REJECTS any model-supplied `_meta` with `model_metadata_rejected`, validates a
+ * signed single-use descriptor, burns a nonce, and only then injects
+ * `_meta.sellableAgent` itself. Upstream of that,
+ * `packages/sellable-install/lib/sellable-agent/hermes-bridge.mjs:646-665`
+ * patches Hermes at the SHARED generic `server.session.call_tool` dispatch site,
+ * so the injection is per-call and tool-agnostic and a newly registered tool
+ * inherits it with no further change. A model-supplied actor claim is worthless,
+ * so this module reads the actor ONLY from the already-verified credential
+ * boundary context and NEVER from tool arguments. Do not add a second mechanism.
+ *
+ * THE BACKEND-FACING CONSEQUENCE, recorded here because plan 141-06's routes
+ * depend on it: on the `Bearer sat_` middleware branch, `X-authuserid` and
+ * `X-workspaceid` are OVERWRITTEN from `AgentServicePrincipal.subjectUserId`
+ * and the five `x-sellable-*` principal headers are DELETED
+ * (`src/middleware.ts:80-86`, `:134-140`, `:806-809`), so no caller-supplied
+ * identity header can carry the Slack requester. The actor must therefore travel
+ * as an EXPLICIT REQUEST BODY FIELD that the route re-verifies against
+ * `WorkspaceSlackIdentity`. See
+ * `.planning/artifacts/uat/141/current/mcp/actor-propagation.json` for the
+ * measured trace and the exact residual gap.
+ */
+/**
+ * The provider-neutral managed-integration tools. Plan 141-06 registers the
+ * `case` labels and the tool schemas; this set exists in WAVE 2 so the
+ * fail-closed guard is already in place when they arrive, and so the two plans
+ * do not both try to own the dispatch switch.
+ */
+export declare const AGENT_INTEGRATION_CONTEXT_TOOL_NAMES: readonly ["integrations_list_tools", "integrations_describe_tool", "integrations_call_tool"];
+export type AgentIntegrationContextToolName = (typeof AGENT_INTEGRATION_CONTEXT_TOOL_NAMES)[number];
+/** The trusted actor triple a managed-integration call forwards to the backend. */
+export type AgentIntegrationRequestContext = {
+    requesterId: string;
+    channelId: string;
+    providerRequestId: string;
+};
+/**
+ * The boundary context shape `createMcpCredentialBoundary` returns on success.
+ * `undefined` is accepted because the `agent_service` refusal branches at
+ * `agent-service-auth.ts:139-157` return no `context` at all.
+ */
+type BoundaryContext = {
+    requesterId?: string | null;
+    channelId?: string | null;
+    providerRequestId?: string | null;
+} | null | undefined;
+export type AgentIntegrationRequestActor = {
+    /** True when the called tool is one that must have a trusted actor. */
+    required: boolean;
+    /** Present only when the actor is fully resolved. */
+    context: AgentIntegrationRequestContext | null;
+};
+export declare const AGENT_INTEGRATION_CONTEXT_REQUIRED_ERROR = "agent_request_context_required";
+export declare function isAgentIntegrationContextTool(name: string): boolean;
+/**
+ * Resolves the trusted actor for a managed-integration tool call.
+ *
+ * FAILS CLOSED. A tool in the set with no boundary context — a `human`
+ * credential, an `invalid` boundary, or an `agent_service` call whose
+ * `_meta.sellableAgent` never arrived — resolves to `context: null`, and the
+ * dispatch must refuse with `agent_request_context_required` rather than
+ * defaulting to a synthetic or absent actor. `agent-service-auth.ts:128-147`
+ * already refuses every `agent_service` call missing the triple with the same
+ * code; this guard is the belt for tools whose authorization decision is
+ * `AUTO`/read-only and for the non-`agent_service` modes that never reach it.
+ */
+export declare function agentIntegrationRequestActor(name: string, boundaryContext: BoundaryContext): AgentIntegrationRequestActor;
+export {};

package/dist/agent-integration-request-context.js

@@ -0,0 +1,74 @@
+/**
+ * Trusted request-actor plumbing for the managed-integration tools.
+ *
+ * WHY THIS IS A SEPARATE MODULE. `server.ts` calls `main()` at import time and
+ * connects a stdio transport, so it cannot be imported by a unit test. The
+ * tool-name set and the fail-closed resolver therefore live here, `server.ts`
+ * imports them, and plan 141-06 imports the same constant when it registers the
+ * three `case` labels. One source of truth, testable in isolation.
+ *
+ * THE ACTOR IS NEVER A TOOL INPUT, and there is exactly one mechanism.
+ * `packages/sellable-install/lib/sellable-agent/mcp-context-proxy.mjs:352-402`
+ * REJECTS any model-supplied `_meta` with `model_metadata_rejected`, validates a
+ * signed single-use descriptor, burns a nonce, and only then injects
+ * `_meta.sellableAgent` itself. Upstream of that,
+ * `packages/sellable-install/lib/sellable-agent/hermes-bridge.mjs:646-665`
+ * patches Hermes at the SHARED generic `server.session.call_tool` dispatch site,
+ * so the injection is per-call and tool-agnostic and a newly registered tool
+ * inherits it with no further change. A model-supplied actor claim is worthless,
+ * so this module reads the actor ONLY from the already-verified credential
+ * boundary context and NEVER from tool arguments. Do not add a second mechanism.
+ *
+ * THE BACKEND-FACING CONSEQUENCE, recorded here because plan 141-06's routes
+ * depend on it: on the `Bearer sat_` middleware branch, `X-authuserid` and
+ * `X-workspaceid` are OVERWRITTEN from `AgentServicePrincipal.subjectUserId`
+ * and the five `x-sellable-*` principal headers are DELETED
+ * (`src/middleware.ts:80-86`, `:134-140`, `:806-809`), so no caller-supplied
+ * identity header can carry the Slack requester. The actor must therefore travel
+ * as an EXPLICIT REQUEST BODY FIELD that the route re-verifies against
+ * `WorkspaceSlackIdentity`. See
+ * `.planning/artifacts/uat/141/current/mcp/actor-propagation.json` for the
+ * measured trace and the exact residual gap.
+ */
+/**
+ * The provider-neutral managed-integration tools. Plan 141-06 registers the
+ * `case` labels and the tool schemas; this set exists in WAVE 2 so the
+ * fail-closed guard is already in place when they arrive, and so the two plans
+ * do not both try to own the dispatch switch.
+ */
+export const AGENT_INTEGRATION_CONTEXT_TOOL_NAMES = Object.freeze([
+    "integrations_list_tools",
+    "integrations_describe_tool",
+    "integrations_call_tool",
+]);
+export const AGENT_INTEGRATION_CONTEXT_REQUIRED_ERROR = "agent_request_context_required";
+export function isAgentIntegrationContextTool(name) {
+    return AGENT_INTEGRATION_CONTEXT_TOOL_NAMES.includes(name);
+}
+/**
+ * Resolves the trusted actor for a managed-integration tool call.
+ *
+ * FAILS CLOSED. A tool in the set with no boundary context — a `human`
+ * credential, an `invalid` boundary, or an `agent_service` call whose
+ * `_meta.sellableAgent` never arrived — resolves to `context: null`, and the
+ * dispatch must refuse with `agent_request_context_required` rather than
+ * defaulting to a synthetic or absent actor. `agent-service-auth.ts:128-147`
+ * already refuses every `agent_service` call missing the triple with the same
+ * code; this guard is the belt for tools whose authorization decision is
+ * `AUTO`/read-only and for the non-`agent_service` modes that never reach it.
+ */
+export function agentIntegrationRequestActor(name, boundaryContext) {
+    if (!isAgentIntegrationContextTool(name)) {
+        return { required: false, context: null };
+    }
+    const requesterId = boundaryContext?.requesterId?.trim();
+    const channelId = boundaryContext?.channelId?.trim();
+    const providerRequestId = boundaryContext?.providerRequestId?.trim();
+    if (!requesterId || !channelId || !providerRequestId) {
+        return { required: true, context: null };
+    }
+    return {
+        required: true,
+        context: { requesterId, channelId, providerRequestId },
+    };
+}

package/dist/agent-tool-names.d.ts

@@ -3,4 +3,4 @@
  * manifests. Keep this free of tool implementation imports so Next can bundle
  * it; registry parity is enforced in sellable-agent-tool-policy.test.ts.
  */
-export declare const SELLABLE_MCP_TOOL_NAMES: readonly ["add_column", "add_on_demand_leads", "add_rubric_item", "add_teammate", "add_to_comment_campaign", "add_to_connection_campaign", "add_to_inmail_campaign", "archive_campaign", "attach_recommended_sequence", "attach_sequence", "bootstrap_create_campaign", "bootstrap_engage", "bootstrap_engage_multi", "bootstrap_find_leads", "bulk_enrich_with_prospeo", "calculate_linkedin_hook_preview", "cancel_campaign_message_preparation", "cancel_find_leads", "cancel_lead_import", "capture_post_idea", "check_inbox_reply_eligibility", "check_rubric", "commit_blueprint", "complete_sender_research", "confirm_harvest_job_companies", "confirm_lead_list", "confirm_prospeo_company_accounts", "copy_sender_config", "create_campaign", "create_on_demand_campaign", "create_on_demand_table", "create_workflow_table", "create_workspace", "delete_column", "delete_rubric_item", "draft_rubrics", "duplicate_campaign", "enrich_with_prospeo", "export_table_csv", "export_workspace_csv", "fetch_company", "fetch_company_posts", "fetch_linkedin_posts", "fetch_linkedin_profile", "fetch_post_engagers", "fill_campaign_horizon", "get_active_workspace", "get_auth_status", "get_campaign", "get_campaign_context", "get_campaign_framework", "get_campaign_message_preparation_status", "get_campaign_messages_preview", "get_campaign_navigation_state", "get_campaign_refill_state", "get_campaign_table_schema", "get_campaign_waterfall", "get_campaigns", "get_column_schema", "get_company_info", "get_engage_memory", "get_engage_state", "get_engaged_posts", "get_find_leads_run", "get_inbox_thread", "get_linkedin_profile", "get_or_create_direct_campaign_table", "get_post_draft", "get_post_find_leads_scout_registry", "get_post_idea", "get_prospeo_credits", "get_provider_prompt", "get_published_post", "get_refill_plan_v2", "get_refill_target_plan", "get_rows", "get_rows_minimal", "get_runtime_identity", "get_scheduler_fill_capacity", "get_sender", "get_sender_routing", "get_source_scout_registry", "get_subskill_asset", "get_subskill_prompt", "get_table_rows", "get_user_posts", "get_workspace", "import_leads", "init_on_demand_sequence", "list_column_types", "list_dnc_entries", "list_post_draft_iterations", "list_post_drafts", "list_post_ideas", "list_published_posts", "list_senders", "list_subskill_prompts", "list_tables", "list_workspaces", "load_csv_dnc_entries", "load_csv_domains", "load_csv_linkedin_leads", "lookup_sales_nav_filter", "mark_post_published", "migrate_flat_configs", "pause_campaign", "pause_direct_campaign", "pause_on_demand_campaign", "preflight_find_leads_provider", "prepare_campaign_ab_test", "queue_campaign_cells", "queue_cells", "record_campaign_review_batch", "record_engage_proven_search", "refill_sends", "refill_sends_v2", "refresh_paid_inmail_credits", "refresh_sender_engagement", "reissue_find_leads_watch_link", "render_linkedin_post_preview", "reorder_columns", "resolve_campaign_fill_route", "revise_message_template_and_rerun", "run_scheduler_sweep", "save_domain_filters", "save_hook_research", "save_post_draft", "save_rubrics", "search_apollo", "search_engagement_posts", "search_harvest_jobs", "search_inbox_threads", "search_prospeo", "search_prospeo_companies", "search_sales_nav", "search_signals", "search_subskill_prompts", "select_campaign_cells", "select_necessary_rubrics", "select_promising_posts", "send_inbox_draft", "send_inbox_manual_reply", "set_active_workspace", "set_campaign_waterfall_order", "set_company_info", "set_engage_state", "set_engage_style_guide", "set_headline_icp_criteria", "set_sender_calendar_link", "set_sender_routing", "setup_evergreen_campaigns", "start_campaign", "start_campaign_message_preparation", "start_cli_login", "start_direct_campaign", "start_on_demand_campaign", "update_campaign", "update_campaign_brief", "update_cell", "update_column", "update_find_leads_run", "update_inbox_draft", "update_post_draft", "update_published_post_metrics", "update_rubric_item", "upsert_engage_tracked_person", "upsert_rubric", "validate_campaign1_kickoff_handoff", "verify_table_row", "wait_for_campaign_processing", "wait_for_campaign_table_ready", "wait_for_cli_login", "wait_for_find_leads_run", "wait_for_lead_list_ready", "wait_for_rubric_results"];
+export declare const SELLABLE_MCP_TOOL_NAMES: readonly ["add_column", "add_on_demand_leads", "add_rubric_item", "add_teammate", "add_to_comment_campaign", "add_to_connection_campaign", "add_to_inmail_campaign", "archive_campaign", "attach_recommended_sequence", "attach_sequence", "bootstrap_create_campaign", "bootstrap_engage", "bootstrap_engage_multi", "bootstrap_find_leads", "bulk_enrich_with_prospeo", "calculate_linkedin_hook_preview", "cancel_campaign_message_preparation", "cancel_find_leads", "cancel_lead_import", "capture_post_idea", "check_inbox_reply_eligibility", "check_rubric", "commit_blueprint", "complete_sender_research", "confirm_harvest_job_companies", "confirm_lead_list", "confirm_prospeo_company_accounts", "copy_sender_config", "create_campaign", "create_on_demand_campaign", "create_on_demand_table", "create_workflow_table", "create_workspace", "delete_column", "delete_rubric_item", "draft_rubrics", "duplicate_campaign", "enrich_with_prospeo", "export_table_csv", "export_workspace_csv", "fetch_company", "fetch_company_posts", "fetch_linkedin_posts", "fetch_linkedin_profile", "fetch_post_engagers", "fill_campaign_horizon", "get_active_workspace", "get_auth_status", "get_campaign", "get_campaign_context", "get_campaign_framework", "get_campaign_message_preparation_status", "get_campaign_messages_preview", "get_campaign_navigation_state", "get_campaign_refill_state", "get_campaign_table_schema", "get_campaign_waterfall", "get_campaigns", "get_column_schema", "get_company_info", "get_engage_memory", "get_engage_state", "get_engaged_posts", "get_find_leads_run", "get_inbox_thread", "get_linkedin_profile", "get_or_create_direct_campaign_table", "get_post_draft", "get_post_find_leads_scout_registry", "get_post_idea", "get_prospeo_credits", "get_provider_prompt", "get_published_post", "get_refill_plan_v2", "get_refill_target_plan", "get_rows", "get_rows_minimal", "get_runtime_identity", "get_scheduler_fill_capacity", "get_sender", "get_sender_routing", "get_source_scout_registry", "get_subskill_asset", "get_subskill_prompt", "get_table_rows", "get_user_posts", "get_workspace", "import_leads", "init_on_demand_sequence", "integrations_call_tool", "integrations_describe_tool", "integrations_list_tools", "list_column_types", "list_dnc_entries", "list_post_draft_iterations", "list_post_drafts", "list_post_ideas", "list_published_posts", "list_senders", "list_subskill_prompts", "list_tables", "list_workspaces", "load_csv_dnc_entries", "load_csv_domains", "load_csv_linkedin_leads", "lookup_sales_nav_filter", "mark_post_published", "migrate_flat_configs", "pause_campaign", "pause_direct_campaign", "pause_on_demand_campaign", "preflight_find_leads_provider", "prepare_campaign_ab_test", "queue_campaign_cells", "queue_cells", "record_campaign_review_batch", "record_engage_proven_search", "refill_sends", "refill_sends_v2", "refresh_paid_inmail_credits", "refresh_sender_engagement", "reissue_find_leads_watch_link", "render_linkedin_post_preview", "reorder_columns", "resolve_campaign_fill_route", "revise_message_template_and_rerun", "run_scheduler_sweep", "save_domain_filters", "save_hook_research", "save_post_draft", "save_rubrics", "search_apollo", "search_engagement_posts", "search_harvest_jobs", "search_inbox_threads", "search_prospeo", "search_prospeo_companies", "search_sales_nav", "search_signals", "search_subskill_prompts", "select_campaign_cells", "select_necessary_rubrics", "select_promising_posts", "send_inbox_draft", "send_inbox_manual_reply", "set_active_workspace", "set_campaign_waterfall_order", "set_company_info", "set_engage_state", "set_engage_style_guide", "set_headline_icp_criteria", "set_sender_calendar_link", "set_sender_routing", "setup_evergreen_campaigns", "start_campaign", "start_campaign_message_preparation", "start_cli_login", "start_direct_campaign", "start_on_demand_campaign", "update_campaign", "update_campaign_brief", "update_cell", "update_column", "update_find_leads_run", "update_inbox_draft", "update_post_draft", "update_published_post_metrics", "update_rubric_item", "upsert_engage_tracked_person", "upsert_rubric", "validate_campaign1_kickoff_handoff", "verify_table_row", "wait_for_campaign_processing", "wait_for_campaign_table_ready", "wait_for_cli_login", "wait_for_find_leads_run", "wait_for_lead_list_ready", "wait_for_rubric_results"];

package/dist/agent-tool-names.js

@@ -93,6 +93,9 @@ export const SELLABLE_MCP_TOOL_NAMES = [
     "get_workspace",
     "import_leads",
     "init_on_demand_sequence",
+    "integrations_call_tool",
+    "integrations_describe_tool",
+    "integrations_list_tools",
     "list_column_types",
     "list_dnc_entries",
     "list_post_draft_iterations",

package/dist/api.d.ts

@@ -11,6 +11,21 @@ export interface DownloadToFileResult {
 export interface ApiRequestOptions {
     workspaceId?: string | null;
     agentEffectId?: string;
+    /**
+     * An OPT-IN client-side deadline, in milliseconds.
+     *
+     * Added by plan 141-06 because this client previously set no `timeout`, no
+     * `AbortSignal`, and no `signal` anywhere. The old deadline came from
+     * `timeout: 120` on a per-binding `mcp_servers` entry in the Hermes profile;
+     * that entry no longer exists, so a hung backend would hang the Slack turn
+     * forever with nothing on the client side to end it.
+     *
+     * It is OPTIONAL and defaults to undefined ON PURPOSE: the existing 175 tools
+     * keep their current unbounded behaviour byte-for-byte (some legitimately run
+     * against 240 s and 300 s backend routes), and only the callers that opt in get
+     * a bound. The three `integrations_*` tools opt in.
+     */
+    timeoutMs?: number;
 }
 export declare class SellableApiError extends Error {
     status: number;

package/dist/api.js

@@ -48,18 +48,43 @@ export class SellableApi {
         const workspaceId = options && Object.prototype.hasOwnProperty.call(options, "workspaceId")
             ? resolveWorkspaceIdForRequest(requestedWorkspaceId, `${method} ${path}`)
             : requestedWorkspaceId;
-        const response = await fetch(url, {
-            method,
-            headers: {
-                "Content-Type": "application/json",
-                Authorization: `Bearer ${config.token}`,
-                ...(workspaceId ? { "x-workspaceid": workspaceId } : {}),
-                ...(options?.agentEffectId
-                    ? { "x-sellable-agent-effect-id": options.agentEffectId }
-                    : {}),
-            },
-            ...(body && { body: JSON.stringify(body) }),
-        });
+        // Opt-in only: no `signal` is attached unless the caller asked for a bound,
+        // so every existing tool's request is byte-identical to before.
+        const controller = typeof options?.timeoutMs === "number" && options.timeoutMs > 0
+            ? new AbortController()
+            : null;
+        const timer = controller
+            ? setTimeout(() => controller.abort(), options.timeoutMs)
+            : null;
+        let response;
+        try {
+            response = await fetch(url, {
+                method,
+                headers: {
+                    "Content-Type": "application/json",
+                    Authorization: `Bearer ${config.token}`,
+                    ...(workspaceId ? { "x-workspaceid": workspaceId } : {}),
+                    ...(options?.agentEffectId
+                        ? { "x-sellable-agent-effect-id": options.agentEffectId }
+                        : {}),
+                },
+                ...(controller ? { signal: controller.signal } : {}),
+                ...(body && { body: JSON.stringify(body) }),
+            });
+        }
+        catch (error) {
+            if (controller?.signal.aborted) {
+                throw new SellableApiError(504, JSON.stringify({
+                    error: "integration_client_timeout",
+                    timeoutMs: options?.timeoutMs ?? null,
+                }), "The Sellable API did not respond inside the client deadline. Retry, or report the tool name if it keeps happening.");
+            }
+            throw error;
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+        }
         if (!response.ok) {
             const errorText = await response.text();
             throw this.buildError(response.status, errorText);

package/dist/server.js

@@ -1,12 +1,14 @@
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, GetPromptRequestSchema, ListPromptsRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { HttpAgentApprovalEffectPort } from "./agent-approval-effect-port.js";
+import { AGENT_INTEGRATION_CONTEXT_REQUIRED_ERROR, agentIntegrationRequestActor, } from "./agent-integration-request-context.js";
 import { createMcpCredentialBoundary, resolveMcpCredentialIntent, } from "./agent-service-auth.js";
-import { getConfig, getConfiguredCredentialIntent } from "./auth.js";
 import { compileAgentToolPolicy, createAgentMcpAuthorizationHandlers, } from "./agent-tool-policy.js";
-import { HttpAgentApprovalEffectPort } from "./agent-approval-effect-port.js";
+import { getConfig, getConfiguredCredentialIntent } from "./auth.js";
 import { MCP_RUNTIME_IDENTITY } from "./runtime-identity.js";
 import { getSkillByName, listSkills } from "./skills.js";
+import { toMcpToolResult } from "./tool-result-envelope.js";
 import { getAuthStatus } from "./tools/auth.js";
 import { handleAddColumn, handleCommitBlueprint, } from "./tools/blueprint-commit.js";
 import { bootstrapCreateCampaign } from "./tools/bootstrap.js";
@@ -37,6 +39,7 @@ import { bootstrapFindLeads, cancelFindLeads, getFindLeadsRun, reissueFindLeadsW
 import { getCampaignFramework } from "./tools/framework.js";
 import { confirmHarvestJobCompanies, searchHarvestJobs, } from "./tools/harvest-jobs.js";
 import { checkInboxReplyEligibility, getInboxThread, searchInboxThreads, sendInboxDraft, sendInboxManualReply, updateInboxDraft, } from "./tools/inbox.js";
+import { integrationsCallTool, integrationsDescribeTool, integrationsListTools, } from "./tools/integrations.js";
 import { cancelLeadImport, confirmLeadList, confirmProspeoCompanyAccounts, getProviderPrompt, importLeads, listDncEntriesTool, loadCsvDncEntriesTool, loadCsvDomains, loadCsvLinkedinLeads, lookupSalesNavFilter, saveDomainFilters, searchApollo, searchProspeo, searchProspeoCompanies, searchSalesNav, searchSignals, selectPromisingPosts, setHeadlineICPCriteria, } from "./tools/leads.js";
 import { fetchCompany, fetchCompanyPosts, fetchLinkedInPosts, fetchLinkedInProfile, fetchPostEngagers, getLinkedInProfile, getUserPosts, } from "./tools/linkedin.js";
 import { getCampaignNavigationState } from "./tools/navigation.js";
@@ -61,7 +64,6 @@ import { attachRecommendedSequence, attachSequence, createWorkflowTable, } from
 import { setupEvergreenCampaigns } from "./tools/setup-evergreen-campaigns.js";
 import { exportTableCsv, listTables } from "./tools/tables.js";
 import { handleVerifyTableRow } from "./tools/verify-row.js";
-import { sanitizeWatchUrlsForMcpResult } from "./tools/watch-url-security.js";
 import { getCampaignWaterfall, setCampaignWaterfallOrder, } from "./tools/waterfalls.js";
 import { exportWorkspaceCsv } from "./tools/workspace-export.js";
 import { addTeammate, createWorkspace, getActiveWorkspace, getWorkspace, listWorkspaces, setActiveWorkspace, } from "./tools/workspaces.js";
@@ -132,11 +134,6 @@ function formatSubskillPromptText(result) {
         : "";
     return `${header}${result.prompt}${footer}`;
 }
-function isStructuredToolResult(result) {
-    return (!!result &&
-        typeof result === "object" &&
-        Array.isArray(result.content));
-}
 const agentApprovalPort = new HttpAgentApprovalEffectPort();
 const agentMcpAuthorization = createAgentMcpAuthorizationHandlers({
     allTools,
@@ -208,7 +205,40 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     ],
                 };
             }
-            agentEffectId = boundary.authorization.effectId;
+            agentEffectId = boundary.authorization
+                .effectId;
+        }
+        // TRUSTED ACTOR PLUMBING FOR THE MANAGED-INTEGRATION TOOLS, keyed on the
+        // TOOL-NAME SET rather than on a `case` label, so plan 141-06's registration
+        // inherits the guard instead of re-implementing it. Plan 141-06 owns the
+        // three `case` labels and consumes `integrationActor.context`; this wave owns
+        // the plumbing and its fail-closed refusal. The two plans must not both try
+        // to own the switch.
+        //
+        // The actor comes ONLY from `boundary.context`, which is derived from
+        // `_meta.sellableAgent` — metadata `mcp-context-proxy.mjs:352-402` injects
+        // itself after REJECTING any model-supplied `_meta`. It is never read from
+        // tool ARGUMENTS, because a model-supplied actor claim is worthless.
+        //
+        // FAIL CLOSED, never default: a `human` credential, an `invalid` boundary, or
+        // a missing actor triple all refuse. A managed-integration call without a
+        // resolved Slack requester has no way to be authorized against a PERSONAL
+        // connection, so proceeding would be strictly worse than refusing.
+        const integrationActor = agentIntegrationRequestActor(name, boundary.mode === "agent_service" ? boundary.context : null);
+        if (integrationActor.required && !integrationActor.context) {
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            ok: false,
+                            error: AGENT_INTEGRATION_CONTEXT_REQUIRED_ERROR,
+                            decision: "DENY",
+                        }),
+                    },
+                ],
+            };
         }
         let result;
         switch (name) {
@@ -636,6 +666,19 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             case "set_sender_routing":
                 result = await setSenderRoutingTool(args);
                 break;
+            // Plan 141-06 owns these three `case` labels ONLY. The fail-closed actor
+            // guard above is plan 141-04 T2's and is keyed on the tool-name SET, so it
+            // already ran before this switch and `integrationActor.context` is verified.
+            // Phase 142-05 adds its connect-tool cases to this same switch additively.
+            case "integrations_list_tools":
+                result = await integrationsListTools(args, integrationActor.context, agentEffectId);
+                break;
+            case "integrations_describe_tool":
+                result = await integrationsDescribeTool(args, integrationActor.context, agentEffectId);
+                break;
+            case "integrations_call_tool":
+                result = await integrationsCallTool(args, integrationActor.context, agentEffectId);
+                break;
             case "get_company_info":
                 result = await getCompanyInfoTool();
                 if (boundary.mode === "agent_service" &&
@@ -853,18 +896,10 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             default:
                 throw new Error(`Unknown tool: ${name}`);
         }
-        const safeResult = sanitizeWatchUrlsForMcpResult(result);
-        if (isStructuredToolResult(safeResult)) {
-            return safeResult;
-        }
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: JSON.stringify(safeResult),
-                },
-            ],
-        };
+        // A tool that DECLARES an `outputSchema` must answer with `structuredContent`,
+        // or the client discards the whole response. `toMcpToolResult` owns that,
+        // keyed on the tool's own declaration. See tool-result-envelope.ts.
+        return toMcpToolResult(name, result);
     }
     catch (error) {
         const message = error instanceof Error ? error.message : "Unknown error";

package/dist/tool-result-envelope.d.ts

@@ -0,0 +1,34 @@
+/**
+ * THE MCP WIRE RESULT. One place shapes it, because the CONTRACT that governs it is
+ * declared per tool and enforced by the CLIENT, not by us.
+ *
+ * A tool that declares an `outputSchema` and answers without `structuredContent` has
+ * its ENTIRE response thrown away by the client, whatever the server actually said:
+ *
+ *   - python `mcp/client/session.py`: `if not result.isError:
+ *     _validate_tool_result(...)`, which raises
+ *     `Tool <name> has an output schema but did not return structured content`;
+ *   - typescript `@modelcontextprotocol/sdk` `client/index.js:499-520`: the same
+ *     rule, then ajv validation of the payload against that schema.
+ *
+ * That is not a theoretical hazard. It took the three `integrations_*` tools down on
+ * the live customer runtime for every Slack turn — success and refusal alike, since
+ * neither sets `isError` — and three consecutive failures then tripped Hermes' MCP
+ * circuit breaker, which reported the whole server as "unreachable".
+ *
+ * The declaration and the payload therefore cannot be maintained in two places by
+ * two conventions. `inbox.ts`, `senders.ts`, and `runtime-identity.ts` each hand-built
+ * `{ content, structuredContent }` correctly and `integrations.ts` returned a bare
+ * envelope; keying off the tool's own declaration removes the chance to get it wrong.
+ */
+export type McpToolTextContent = {
+    type: "text";
+    text: string;
+};
+export type McpToolResult = {
+    content: McpToolTextContent[];
+    structuredContent?: unknown;
+    isError?: boolean;
+};
+export declare function isStructuredToolResult(result: unknown): result is McpToolResult;
+export declare function toMcpToolResult(name: string, result: unknown): McpToolResult;

package/dist/tool-result-envelope.js

@@ -0,0 +1,37 @@
+import { allTools } from "./tools/registry.js";
+import { sanitizeWatchUrlsForMcpResult } from "./tools/watch-url-security.js";
+/**
+ * Read off the REAL tool table, so a tool that adds an `outputSchema` is covered the
+ * moment it is registered and cannot be forgotten here.
+ */
+const OUTPUT_SCHEMA_TOOL_NAMES = new Set(allTools
+    .filter((tool) => tool.outputSchema)
+    .map((tool) => tool.name));
+export function isStructuredToolResult(result) {
+    return (!!result &&
+        typeof result === "object" &&
+        Array.isArray(result.content));
+}
+function isPlainObject(value) {
+    return !!value && typeof value === "object" && !Array.isArray(value);
+}
+export function toMcpToolResult(name, result) {
+    const safeResult = sanitizeWatchUrlsForMcpResult(result);
+    if (isStructuredToolResult(safeResult)) {
+        return safeResult;
+    }
+    const content = [
+        { type: "text", text: JSON.stringify(safeResult) },
+    ];
+    if (!OUTPUT_SCHEMA_TOOL_NAMES.has(name)) {
+        return { content };
+    }
+    if (!isPlainObject(safeResult)) {
+        // `structuredContent` must be an OBJECT, so a non-object can never satisfy an
+        // object schema. FAIL CLOSED as an error the client will still deliver, instead
+        // of a well-formed response the client discards wholesale — the operator gets
+        // the payload and a visible error rather than a bare protocol complaint.
+        return { content, isError: true };
+    }
+    return { content, structuredContent: safeResult };
+}