import { assertAgentToolAssignmentInteractions } from "./connection-management.js"; import { isNewHumanIntentAfterToolRejection } from "./tool-action-replay-intent.js"; import { approvalSnapshotsMatch, approvalTargetChangeMessage, oauthApprovalConfig, approvalGrantTenantIdentity, externalCredentialApprovalIdentity } from "./tool-approval-target.js"; import { isToolApprovalConnectionError, toolApprovalConnectionRevision, toolApprovalConnectionCanResume, TOOL_APPROVAL_CONNECTION_MESSAGE, TOOL_APPROVAL_CONNECTION_REQUIRED } from "./tool-approval-connection.js"; import { notifyChatRunMilestones } from "./chat-run-milestone-notifications.js"; import { McpSkillVerificationError, mcpSkillContentBytes, mcpSkillManifestFile, mcpSkillsService, verifyMcpSkillFileBytes, verifyMcpSkillFrontmatter, type McpSkillRow } from "./mcp-skills.js"; import { writeToolConnectionHealthChange } from "./tool-connection-health-notifications.js"; import { writeApprovalChange } from "./approval-work-notifications.js"; import { toolReviewProjectionService } from "./tool-review-projection.js"; import { toolReviewInterruptionService } from "./tool-review-interruption.js"; import { bindVerifiedToolApprovalArguments, claimToolTestApproval, releaseToolApproval, persistToolTestOutcome, startToolInvocation, type ToolApprovalClaim } from "./tool-approval-execution.js"; import { approvedToolReviewCompanies, prepareApprovedToolReview, recoverApprovedToolReviews } from "./tool-review-recovery.js"; import { toolReviewExpiryService } from "./tool-review-expiry.js"; import { notifyToolReviewChange, writeToolReviewChange } from "./tool-review-work-notifications.js"; import { restConnectorFor } from "./connectors/rest-registry.js"; import type { runPromptInjectionProvider } from "./prompt-injection-provider.js"; import { promptInjectionPreventionService } from "./prompt-injection-prevention.js"; import { adapterExecutionControls } from "./adapter-execution-control.js"; import type { BudgetServiceHooks } from "./budgets.js"; import type { PromptInjectionDetectorMetadata } from "@paperclipai/shared"; import { connectionManagementService, type ConnectionManagementContext } from "./connection-management.js"; import { notifyDeliveryWork, DELIVERY_QUEUES } from "./delivery-work-notifications.js"; import { measureToolDiscovery, measureRunPhase } from "./execution-preparation-timing.js"; import { nativeProviderCatalogFor } from "./native-provider-catalogs.js"; import { composeConnectionInstructions } from "./connection-instructions.js"; import { googleWorkspaceToolTarget, googleWorkspaceGrantedScopes, isGoogleWorkspaceToolGranted } from "@paperclipai/shared"; import { isInsufficientConnectionScope, INSUFFICIENT_CONNECTION_SCOPE_MESSAGE } from "./connection-permission-errors.js"; import { githubAccessDeniedInstructions, githubAccessError } from "./tool-access/github-access-errors.js"; import { githubDefaultOwnerApplies, githubDefaultOwnerArguments } from "./tool-access/github-default-owner.js"; import { toolSourceTemplateKeySql } from "./tool-access/source-template-key.js"; import { usesClientCredentials } from "./tool-access/oauth/client-credentials.js"; import { boundedMcpToolName } from "./mcp-tool-names.js"; import { browserUseService } from "./browser-use.js"; import { isBrowserUseConnection } from "./browser-use-client.js"; import { COGNEE_STDIO_TEMPLATE, cogneeCloudUrl, callCogneeCloud } from "./cognee-connection.js"; import { HttpError } from "../errors.js"; import { authorizationService, canActorReadIssuePrivacy, type AuthorizationActor } from "./authorization.js"; import { claimSlackRateLimitRetry } from "./connectors/slack-retry.js"; import { resolveSlackTaskAuthority } from "./connectors/slack-authority.js"; import { SLACK_TOOLS } from "@paperclipai/shared"; import { MCP_APPS_CLIENT_CAPABILITY, MCP_APP_MAX_HTML_BYTES, mcpAppToolCallableFromApp, mcpAppToolVisibleToModel, readMcpAppResource, type McpAppCallToolResult, type McpAppResource, type McpAppToolUi } from "@paperclipai/shared"; import { mcpAppCallToolResult, recordMcpAppView } from "./mcp-app-views.js"; import { slackToolsForSession } from "./connectors/slack-catalog.js"; import { boundRunIssueIdSql } from "./run-task-binding.js"; import { executeSlackTool } from "./connectors/slack.js"; import { githubGuestBotConnectionForSession, githubBotToolsForSession } from "./chat-github-tools.js"; import { githubChatReviewService } from "./chat-github-reviews.js"; import { runIdentityContexts } from "@paperclipai/db"; import { executeSpekoVoiceTool, spekoToolsForSession } from "./voice/speko-agent-tools.js"; import { captureRunIdentity } from "./run-identity.js"; import { emitConnectionInvoked } from "./connector-telemetry.js"; import { resolveManagedGitHubIdentitySelection } from "./git-credentials.js"; import { extractRemoteMcpPending } from "./remote-mcp-pending.js"; import { backgroundPollDelayMs, cancelMcpTask, getMcpTask, inlinePollDelayMs, isMcpTaskTerminal, mcpCreatedTask, mcpTaskEndpointHash, mcpTaskExpiresAt, mcpTaskIdIndex, mcpTaskRequestHash, McpTaskRequestError, openMcpTaskId, sealMcpTaskId, sendMcpTaskRequest, waitForPoll, type McpTaskRecordStatus, type McpTaskState, type McpTaskTransport, } from "./mcp-tasks.js"; import { logger } from "../middleware/logger.js"; import { getAppDefinitionForApplicationKey, isConnectorFeatureEnabled } from "@paperclipai/shared"; import { requestConfirmationPayloadSchema } from "@paperclipai/shared"; import { instanceSettingsService } from "./instance-settings.js"; import { redactSensitiveText } from "../redaction.js"; import { spawn } from "node:child_process"; import { createHash, createHmac, randomBytes, randomUUID } from "node:crypto"; import { isDeepStrictEqual } from "node:util"; import { and, asc, desc, eq, gt, inArray, isNull, lt, lte, ne, or, sql, } from "drizzle-orm"; import type { Db } from "@paperclipai/db"; import { agents, agentWakeupRequests, approvals, companies, companyMemberships, companySecrets, connectionGrantMembers, connectionGrantDelegations, connectionGrants, documents, heartbeatRuns, issueApprovals, issueComments, issueDocuments, issueThreadInteractions, issues, projects, toolActionRequests, toolActionDeliveries, toolAccessAuditEvents, toolApplications, toolCallEvents, toolCatalogEntries, toolConnections, toolGatewayRateLimitCounters, toolGatewaySessions, toolInvocations, toolMcpGateways, toolMcpGatewayTokens, toolMcpSkills, toolMcpTasks, toolMcpElicitations, toolPolicies, toolProfileBindings, toolProfileEntries, toolProfiles, toolStdioCommandTemplates, } from "@paperclipai/db"; import type { ToolRunContext } from "@paperclipai/plugin-sdk"; import type { CreateToolMcpGateway, CreateToolMcpGatewayToken, DeploymentExposure, DeploymentMode, McpConnectionCredentialRef, SecretVersionSelector, ToolAccessDecision, ToolAccessDecisionInput, ToolConnectionTestCallStatus, ToolUpstreamPending, ToolConnectionTestCallStatusPhase, ToolCredentialSecretRef, ToolMcpGateway, ToolMcpGatewayClientSnippet, ToolMcpGatewayToken, ToolMcpGatewayTokenAction, ToolMcpGatewayTokenCreated, ToolMcpGatewayWithTokens, UpdateToolMcpGateway, } from "@paperclipai/shared"; import { checkOAuthEndpointUrl, getConnectableAppDefinition, isGitHubConnectorProfileId, isGoogleWorkspaceConnectorProfileId, type GitHubConnectorProfileId, type GoogleWorkspaceConnectorProfileId, } from "@paperclipai/shared"; import type { AgentToolDescriptor, PluginToolDispatcher, } from "./plugin-tool-dispatcher.js"; import { logActivity, publishActivity, type ActivityPublication, type LogActivityInput } from "./activity-log.js"; import { secretService } from "./secrets.js"; import { connectionGrantCredentialRef, resolveConnectionGrantSecret } from "./connection-credentials.js"; import { railwayCommandBudgetMs, createRailwayClient, isRailwayConnection, isRailwayEndpoint, isRailwayToolBlocked, normalizeRailwayToolName, RAILWAY_API_URL, RAILWAY_TOOL_PREFIX, RailwayError } from "./railway.js"; import { RAILWAY_SSH_SECRET_PATH, runRailwaySshCommand } from "./railway-ssh.js"; import { saveMcpNegotiation } from "./tool-access/mcp-protocol-config.js"; import { initializeMcpHttpSession, getMcpHttpSession, forgetMcpHttpSession, forgetMcpProtocolVersion, isModernMcpProtocolVersion, knownMcpProtocolVersion, MCP_ERROR_UNSUPPORTED_PROTOCOL_VERSION, mcpEraKey, mcpHttpRequestInit, mcpInputRequired, mcpProtocolVersionOf, McpResultCache, MCP_MODERN_PROTOCOL_VERSION, MCP_PROTOCOL_VERSION, mcpClientCapabilities, mcpModernErrorOf, mcpCacheHint, mcpCredentialFingerprint, negotiateMcpProtocolVersion, readMcpHttpResponse, readMcpModernError, rememberMcpProtocolVersion, selectMcpProtocolVersion, McpHttpResponseError, McpHttpInitializationError, type McpHttpResponseProgress, type McpInputRequired, mcpHttpRequestHeaders, parseMcpHttpResponseBody, mcpProgressNotificationOf, } from "./mcp-http.js"; import { createToolCallProgressReporter, saveToolCallProgress, type ToolCallProgressReporter } from "./tool-call-progress.js"; import { buildElicitationQuestionSet, elicitationQuestionHash, elicitationResponseForCard, formElicitationOf, MCP_ELICITATION_MAX_FORMS_PER_ROUND, openElicitationState, sealElicitationState, type McpElicitationResponse, type McpFormElicitation, } from "./mcp-elicitation.js"; import { projectedConnectionHeaders, projectedConnectionToolArguments, projectedConnectionToolInputSchema, } from "./tool-access.js"; import { assertGoogleChatToolArgumentsSupported, googleChatToolDescription } from "./google-chat-tool-policy.js"; import { assertGmailArchiveToolArgumentsSupported, gmailArchiveToolDescription } from "./gmail-archive-tool-policy.js"; import { parseRemoteHttpEndpoint } from "./remote-http-endpoint-guard.js"; import { guardedRemoteHttpFetch, DEFAULT_REMOTE_HTTP_RESPONSE_TIMEOUT_MS, type GuardedRemoteHttpFetchOptions, } from "./remote-http-fetch.js"; import { REMOTE_URL_SECRET_CONFIG_PATH, remoteUrlCredentialMatchesPublicUrl, } from "./remote-url-credentials.js"; import { createToolAccessDecisionCache, runContextSnapshotString, toolAccessPolicyService, type ToolAccessDecisionCache, } from "./tool-access-policy.js"; import { toolDiscoveryScheduler, ToolDiscoveryBusyError } from "./tool-discovery-scheduler.js"; import { commitToolActionReview } from "./tool-action-review.js"; import { issueThreadInteractionService } from "./issue-thread-interactions.js"; import { createToolRuntimeSupervisor, ToolRuntimeSupervisorError, type ToolRuntimeSupervisorOptions, type ToolRuntimeSlotView, } from "./tool-runtime-supervisor.js"; import { recordToolRuntimeAuditWriteFailure } from "./tool-runtime-metrics.js"; import { unresolvedRecoveryToolInvocation } from "./recovery-effect-receipts.js"; import { isRetiredComposioConnection, RETIRED_COMPOSIO_MESSAGE } from "@paperclipai/shared"; import { createPaperclipCloudConnector, isPaperclipCloudConnectorStrategy, paperclipCloudConnectorConfigFromEnv, PaperclipCloudConnectorError, type PaperclipCloudConnector, } from "./paperclip-cloud-connector.js"; import { createVercelConnectClient, vercelGrantReference, vercelTokenRequest, VercelConnectClientError, type VercelConnectClient, } from "./vercel-connect.js"; import { canonicalToolArguments, readSignedToolArgumentsPayload, resolveToolActionSigningSecret, signToolArguments, summarizeToolValue, toolRequestIdentityHash, TOOL_ACTION_REQUEST_SIGNING_GRACE_MS, ToolActionSigningSecretMissingError, ToolContentValidationError, validateToolContent, verifyToolArgumentsSignature, } from "./tool-content-guards.js"; import { extendApprovedExecutionWaitDeadline } from "./approved-execution-wait.js"; const DEFAULT_SESSION_TTL_MS = 15 * 60 * 1000; const MAX_SESSION_TTL_MS = 60 * 60 * 1000; const DEFAULT_TOOL_TIMEOUT_MS = 10_000; export function resolveCredentialGrantKind( policy: "shared" | "per_user" | "per_user_with_fallback" | "per_agent", actingUserId: string | null, hasUserGrant: boolean, ): "organization" | "user" | "user_authorization_required" { if (policy === "per_agent") return "user_authorization_required"; if (policy === "shared") return "organization"; if (actingUserId && hasUserGrant) return "user"; return policy === "per_user" ? "user_authorization_required" : "organization"; } export function isConnectionGrantAudienceAllowed( memberUserIds: string[], actingUserId: string | null, actingUserIsActiveMember: boolean, ): boolean { if (actingUserId !== null && !actingUserIsActiveMember) return false; return ( memberUserIds.length === 0 || (actingUserId !== null && memberUserIds.includes(actingUserId)) ); } // When a human approves a parked write, the server carries it out on their // behalf with no interactive caller left to raise `timeoutMs`. Remote write // providers (e.g. Zapier Google Sheets `add_row`) routinely take longer than // the 10s interactive default, so an approved action would otherwise abort with // `tool_timeout` even though the approval succeeded. Give approved executions // the full permitted headroom instead. const APPROVED_EXECUTION_TIMEOUT_MS = 60_000; const GITHUB_BOT_TOOL_TIMEOUT_MS = 60_000; const ACTION_REQUEST_EXECUTION_POLL_MS = 25; // Approval execution performs live target, signature, managed-argument, and // issue-state checks before provider dispatch. Give that preparation a // separate bounded window so it cannot consume the provider's execution // budget for concurrent consumers. const ACTION_REQUEST_PREPARATION_WAIT_MS = 2 * 60 * 1000; // Concurrent consumers must wait at least as long as the provider execution // they are joining. The extra grace lets the owner persist the terminal request // state after the provider timeout/result settles. const ACTION_REQUEST_EXECUTION_WAIT_MS = APPROVED_EXECUTION_TIMEOUT_MS + 5_000; // The gateway creates an ask-first request in two steps: it inserts the row // with a null signature, then it signs the row and sets the expiry. A concurrent // matching call can observe the row in this window. A null signature alone does // not prove the create stopped; the create can still run in another request. Only // treat an unsigned row as abandoned after this grace time from createdAt. This // grace must exceed the normal sign path (approval-snapshot fetch + interaction // create) so a live create keeps its own row. const MAX_REMOTE_MCP_RESPONSE_BYTES = 1_000_000; const ACTIVE_GATEWAY_RUN_STATUSES = new Set(["running"]); // A tool listing decides access for every tool in the company. The decisions // of one listing share a read cache, so this cap only limits how many of them // (and their uncached reads, such as rate-limit counters) run at the same time. const LISTING_DECISION_CONCURRENCY = 16; const uuidPattern = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i; type McpGatewayProtocolMethod = | "initialize" | "tools/list" | "tools/call" | "resources/list" | "resources/read" | "prompts/list" | "prompts/get"; type McpGatewayRateLimitConfig = { windowMs: number; max: number }; type McpGatewayRateLimitState = { limited: boolean; count: number; retryAfterMs: number; }; type McpGatewayProtocolLimitOptions = { authFailures: McpGatewayRateLimitConfig; gatewayRequests: McpGatewayRateLimitConfig; tokenRequests: McpGatewayRateLimitConfig; sessionSetup: McpGatewayRateLimitConfig; }; const DEFAULT_MCP_GATEWAY_PROTOCOL_LIMITS: McpGatewayProtocolLimitOptions = { authFailures: { windowMs: 5 * 60 * 1000, max: 20 }, gatewayRequests: { windowMs: 60 * 1000, max: 300 }, tokenRequests: { windowMs: 60 * 1000, max: 120 }, sessionSetup: { windowMs: 60 * 1000, max: 30 }, }; const TOOL_APPROVAL_DESCRIPTION_SUFFIX = "Requires human approval: calling it posts an approval card on your task and you will be woken with the result once decided."; export type ToolGatewayProviderType = | "mcp_http_fixture" | "mcp_stdio_fixture" | "provider_rest" | "mcp_remote_http" | "mcp_local_stdio" | "paperclip_self" | "paperclip_plugin" | "paperclip_virtual" | "paperclip_github_chat" | "paperclip_slack_chat" | "paperclip_speko_voice"; export interface ConnectedMcpGatewayMetadata { applicationId: string; applicationKey: string | null; applicationDisplayName: string; connectionId: string; catalogEntryId: string; transport: "mcp_remote" | "local_stdio" | "rest_api"; gatewayToolName: string; upstreamToolName: string; catalogName: string; inputSchema: Record; outputSchema: Record | null; annotations: Record; /** MCP Apps view declaration, when the tool renders a `ui://` view. */ ui?: McpAppToolUi | null; risk: { level: string; isReadOnly: boolean; isWrite: boolean; isDestructive: boolean; }; onDemandTools?: boolean; } /** MCP Apps: a tool whose `_meta.ui.visibility` omits "model" is callable only from its view. */ export function isModelVisibleTool(tool: ToolGatewayDescriptor): boolean { return mcpAppToolVisibleToModel(asRecord(tool.providerMetadata)?.ui as McpAppToolUi | null | undefined); } export interface ToolGatewayDescriptor extends AgentToolDescriptor { providerType: ToolGatewayProviderType; risk: "read" | "write" | "destructive"; applicationId?: string | null; applicationKey?: string | null; applicationDisplayName?: string | null; connectionId?: string | null; catalogEntryId?: string | null; upstreamToolName?: string | null; providerMetadata?: ConnectedMcpGatewayMetadata | Record; } export interface ToolGatewaySession { id: string; token: string; companyId: string; agentId: string | null; runId: string | null; issueId: string | null; projectId: string | null; originatingAgentId?: string | null; gatewayId?: string | null; gatewayPublicId?: string | null; gatewayName?: string | null; gatewayProfileId?: string | null; gatewayTokenId?: string | null; gatewayTokenAllowedActions?: ToolMcpGatewayTokenAction[]; actorType?: "agent" | "user" | "system" | "plugin"; actorId?: string | null; /** Human whose personal connection grant applies to this execution. */ responsibleUserId?: string | null; /** Captured by the controller for this request, never accepted from tool arguments. */ identityContextId?: string | null; /** Set only after verifying the signed approved action. */ approvedSlackInvocationId?: string; /** Set only after the signed review is verified. */ approvedInvocationId?: string; createdAt: Date; expiresAt: Date; } export type ToolGatewayRuntimeSlot = ToolRuntimeSlotView; export class ToolGatewayHttpError extends Error { constructor( public readonly status: number, message: string, public readonly reasonCode: string, public readonly details: Record = {}, ) { super(message); } } /** Repeated discovery rows are one tool; conflicting bindings stay ambiguous. */ export function deduplicateToolDescriptors(tools: readonly ToolGatewayDescriptor[]): ToolGatewayDescriptor[] { const unique = new Map(); for (const tool of tools) { const previous = unique.get(tool.name); if (previous) { if (!isDeepStrictEqual(previous, tool)) { throw new ToolGatewayHttpError(409, `Conflicting tool definitions share the name ${JSON.stringify(tool.name)} (connections ${JSON.stringify([previous.connectionId ?? null, tool.connectionId ?? null])}).`, "tool_name_collision"); } continue; } unique.set(tool.name, tool); } return [...unique.values()]; } interface ExecuteGatewayToolInput { signal?: AbortSignal; sessionToken: string; gatewayId?: string | null; gatewayPublicId?: string | null; tool: string; parameters?: unknown; timeoutMs?: number; approvedActionRequestId?: string | null; idempotencyKey?: string | null; callerHeaders?: Record; } interface ExecuteTestCallInput { signal?: AbortSignal; managementContext?: ConnectionManagementContext; companyId: string; connectionId: string; agentId: string; userId: string; toolName: string; parameters?: unknown; timeoutMs?: number; /** MCP Apps view calls only: return the redacted provider `_meta`. Never set for agent-reachable callers. */ includeResultMeta?: boolean; /** MCP Apps view calls only: the task (and its project) the view belongs to, so task- and project-scoped rules apply. */ issueId?: string | null; projectId?: string | null; } interface ExecutePluginToolInput { signal?: AbortSignal; actor: { type: "agent" | "board"; agentId?: string | null; companyId?: string | null; userId?: string | null; runId?: string | null; }; tool: string; parameters: unknown; runContext: ToolRunContext; } type HeaderPolicyConfig = { staticHeaders: Array<{ name: string; value: string }>; passthroughAllowlist: string[]; metadataHeaders: Array< | "company_id" | "agent_id" | "issue_id" | "project_id" | "run_id" | "gateway_session_id" | "correlation_id" >; }; type HeaderPolicySummary = { staticHeaderNames: string[]; credentialHeaderNames: string[]; passthroughHeaderNames: string[]; droppedPassthroughHeaderNames: string[]; metadataHeaderNames: string[]; collisionRules: Array<{ header: string; source: string; action: string }>; }; type RemoteHttpExecutionResult = { result: unknown; failureInstructions?: string; headerSummary?: HeaderPolicySummary; execution?: RemoteHttpExecutionAudit; }; type RemoteHttpExecutionAudit = { transport: "mcp_remote"; request: { protocol: "MCP JSON-RPC 2.0" | "Railway GraphQL" | "Railway GraphQL + SSH"; httpMethod: "POST"; endpoint: string; mcpMethod: "tools/call"; requestId: string; upstreamToolName: string; dispatched: true; }; response?: { httpStatus: number; contentType: string | null; bodySizeBytes: number; upstreamRequestId: string | null; }; failureKind?: "invocation_timeout" | "transport_failure" | "protocol_failure"; error?: RemoteHttpErrorEvidence; deadline?: { timeoutMs: number; aborted: boolean }; stream?: McpHttpResponseProgress; /** The provider answered with a task (MCP Tasks); no provider task ID is kept here. */ task?: { recordId: string; attached: boolean; polls: number; status: string }; }; type RemoteHttpErrorEvidence = { name: string | null; message: string; code: string | null; stack: string | null; cause: RemoteHttpErrorEvidence | null; }; // Deliberate stops of a remote tool call. They are not failures, and a deadline // that passes while they are recorded must not turn them into a timeout. const REMOTE_TOOL_CALL_WORKFLOW_REASON_CODES = new Set([ "elicitation_required", "elicitation_sensitive_refused", "elicitation_unsupported", "elicitation_limit_reached", "provider_interaction_required", "provider_input_required", "provider_retry_requested", "oauth_insufficient_scope", "oauth_refreshed_retry_required", "provider_task_pending", "provider_task_cancelled", "provider_task_expired", "provider_task_failed", ]); const REMOTE_TOOL_CALL_PROTOCOL_REASON_CODES = new Set([ "mcp_remote_invalid_json", "remote_mcp_malformed_response", "mcp_remote_response_too_large", ]); function remoteToolCallFailureKind(reasonCode: string): RemoteHttpExecutionAudit["failureKind"] { if (reasonCode === "tool_timeout") return "invocation_timeout"; if (REMOTE_TOOL_CALL_PROTOCOL_REASON_CODES.has(reasonCode)) return "protocol_failure"; if (reasonCode === "mcp_remote_fetch_failed" || reasonCode.startsWith("remote_http_")) return "transport_failure"; return undefined; } function remoteHttpErrorEvidence(error: unknown, seen = new Set()): RemoteHttpErrorEvidence { if (seen.has(error)) return { name: null, message: "[Circular cause]", code: null, stack: null, cause: null }; const record = asRecord(error); seen.add(error); return { name: typeof record?.name === "string" ? redactSensitiveText(record.name) : null, message: redactSensitiveText(typeof record?.message === "string" ? record.message : String(error)), code: typeof record?.code === "string" ? redactSensitiveText(record.code) : null, stack: typeof record?.stack === "string" ? redactSensitiveText(record.stack) : null, cause: record?.cause == null ? null : remoteHttpErrorEvidence(record.cause, seen), }; } type LocalStdioRuntimeTemplate = { templateId: string; command: string | null; args: string[]; envKeys: string[]; }; const BUILTIN_LOCAL_STDIO_RUNTIME_TEMPLATES: Record< string, Omit > = { "paperclip.cognee-cloud": COGNEE_STDIO_TEMPLATE, "paperclip.google-sheets": { command: "paperclip-google-sheets-mcp-server", args: [], envKeys: [ "GOOGLE_SHEETS_SERVICE_ACCOUNT_JSON", "GOOGLE_SHEETS_SERVICE_ACCOUNT_JSON_PATH", "GOOGLE_SHEETS_ALLOWED_SPREADSHEET_IDS", ], }, "paperclip.echo-calculator-time": { command: null, args: [], envKeys: [], }, "paperclip.synthetic-todo-kv": { command: null, args: [], envKeys: [], }, }; function asRecord(value: unknown): Record | null { if (!value || typeof value !== "object" || Array.isArray(value)) return null; return value as Record; } function connectionRequiresMcpSession(connection: { config: unknown }): boolean { const config = asRecord(connection.config); if (config?.mcpSessionRequired === true) return true; const sourceTemplateKey = typeof config?.sourceTemplateKey === "string" ? config.sourceTemplateKey : null; const connectionMethodKey = typeof config?.connectionMethodKey === "string" ? config.connectionMethodKey : null; if (!sourceTemplateKey || !connectionMethodKey) return false; return getConnectableAppDefinition(sourceTemplateKey)?.methods.some((method) => method.key === connectionMethodKey && method.defaults?.mcpSessionRequired === true ) ?? false; } const MCP_CONTINUATION_TTL_MS = 30 * 60_000; /** The most provider links one pending step shows (matches the legacy link flow). */ const MCP_MAX_INPUT_LINKS = 8; /** * JSON-RPC errors that show a server refused a call before running it: an * unknown method, an invalid request, or a server that was never initialized. * Anything else (an internal error, invalid params) may come after the tool * ran, so such a call is never replayed. */ function callNeverRan(error: unknown): boolean { const record = asRecord(error); if (!record || typeof record.code !== "number") return false; if (record.code === -32600 || record.code === -32601) return true; return typeof record.message === "string" && /not\s+(?:been\s+)?initiali[sz]ed/i.test(record.message); } /** How long a stdio server may stay silent on `server/discover` before it is treated as legacy. */ const STDIO_DISCOVER_PROBE_TIMEOUT_MS = 2_000; /** Context reads whose results carry the server's freshness hint. */ const MCP_CACHEABLE_CONTEXT_METHODS = new Set(["resources/list", "resources/read", "resources/templates/list", "prompts/list"]); /** * Turn a multi round-trip `input_required` result into what Paperclip can do * with it today. URL requests become the provider link the person opens, as * for older servers. Paperclip never answers them on the person's behalf: no * person action is recorded, so claiming "accept" would assert consent nobody * gave. The next call goes out fresh and the server, which tracks out-of-band * steps itself, decides. A bare `requestState` (try again) is kept for the * retry because it asserts nothing. Form questions in a task go to a person * first (see askElicitationRound); sampling and roots are not collected. */ export function mcpInputRequiredPending(inputRequired: McpInputRequired): { answerable: boolean; /** State to send back on the next identical call; never a user answer. */ retryState?: string; upstreamPending?: ToolUpstreamPending; } { const links: ToolUpstreamPending["links"] = []; let message: string | undefined; let forms = 0; for (const request of Object.values(inputRequired.inputRequests)) { // A form beside a link waits: the link goes first, and the server asks // for the form again on the next call (spec: re-ask for missing input). if (request.method === "elicitation/create" && (request.params.mode === undefined || request.params.mode === "form")) { forms += 1; continue; } if (request.method !== "elicitation/create" || request.params.mode !== "url") return { answerable: false }; const checked = checkOAuthEndpointUrl(request.params.url); if (!checked.ok) return { answerable: false }; if (!links.some((link) => link.url === checked.url)) links.push({ url: checked.url, host: checked.host }); if (!message && typeof request.params.message === "string") message = redactSensitiveText(request.params.message).slice(0, 4000); } if (!links.length) { return inputRequired.requestState && !forms ? { answerable: true, retryState: inputRequired.requestState } : { answerable: false }; } // The link flow shows up to eight; more is a clear stop, never a partial step. if (links.length > MCP_MAX_INPUT_LINKS) return { answerable: false }; return { answerable: true, upstreamPending: { kind: "authorization", links, ...(message ? { message } : {}) } }; } async function mapWithConcurrency( items: readonly T[], concurrency: number, mapper: (item: T) => Promise, signal?: AbortSignal, ): Promise { const results = new Array(items.length); let nextIndex = 0; let failed = false; async function worker() { while (!failed && nextIndex < items.length) { const index = nextIndex; nextIndex += 1; try { signal?.throwIfAborted(); results[index] = await mapper(items[index]!); } catch (error) { // The batch fails with this error, so the other workers stop. failed = true; throw error; } } } const workers = await Promise.allSettled( Array.from({ length: Math.min(concurrency, items.length) }, () => worker()), ); const failure = workers.find((result) => result.status === "rejected"); if (failure?.status === "rejected") throw failure.reason; signal?.throwIfAborted(); return results; } const sensitivePassthroughHeaderPattern = /(^|[-_])(auth|authorization|cookie|secret|session|token)([-_]|$)|(^|[-_])api[-_]?key([-_]|$)/i; const sensitivePassthroughHeaderNames = new Set([ "authorization", "proxy-authorization", "cookie", "set-cookie", "x-paperclip-tool-gateway-token", ]); function isSensitivePassthroughHeader(name: string) { return ( name.startsWith("x-paperclip-") || sensitivePassthroughHeaderNames.has(name) || sensitivePassthroughHeaderPattern.test(name) ); } function stringValue(value: unknown): string | null { return typeof value === "string" && value.trim().length > 0 ? value : null; } function auditSafeEndpoint(endpoint: string): string { try { const url = new URL(endpoint); return `${url.origin}${url.pathname}`; } catch { return "configured remote MCP endpoint"; } } function executionAuditFromError( error: unknown, ): RemoteHttpExecutionAudit | undefined { if (!(error instanceof ToolGatewayHttpError)) return undefined; const execution = error.details.execution; if (!execution || typeof execution !== "object" || Array.isArray(execution)) return undefined; return execution as RemoteHttpExecutionAudit; } function generateGatewayToken(sessionId: string) { return `pcgt_${sessionId}.${randomBytes(32).toString("base64url")}`; } interface NamedGatewayTokenInput { companyId: string; gatewayId: string; body: CreateToolMcpGatewayToken; actor?: { agentId?: string | null; userId?: string | null }; managementContext?: ConnectionManagementContext; } function generateNamedGatewayToken(tokenId: string) { return `pcgw_${tokenId}.${randomBytes(32).toString("base64url")}`; } function hashGatewayToken(token: string) { return createHash("sha256").update(token).digest("hex"); } function sessionIdFromGatewayToken(token: string) { const match = token.match(/^pcgt_([0-9a-fA-F-]{36})\.[A-Za-z0-9_-]+$/); return match?.[1] ?? null; } function namedGatewayTokenId(token: string) { const match = token.match(/^pcgw_([0-9a-fA-F-]{36})\.[A-Za-z0-9_-]+$/); return match?.[1] ?? null; } function positiveInt(value: string | undefined, fallback: number) { const parsed = Number.parseInt(value ?? "", 10); return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback; } function mergeLimitConfig( defaults: McpGatewayRateLimitConfig, overrides: Partial | undefined, ): McpGatewayRateLimitConfig { return { windowMs: overrides?.windowMs && overrides.windowMs > 0 ? overrides.windowMs : defaults.windowMs, max: overrides?.max && overrides.max > 0 ? overrides.max : defaults.max, }; } function mcpGatewayProtocolLimits( overrides: | Partial<{ authFailures: Partial; gatewayRequests: Partial; tokenRequests: Partial; sessionSetup: Partial; }> | undefined, ): McpGatewayProtocolLimitOptions { const envDefaults: McpGatewayProtocolLimitOptions = { authFailures: { windowMs: positiveInt( process.env.PAPERCLIP_MCP_GATEWAY_AUTH_FAILURE_WINDOW_MS, DEFAULT_MCP_GATEWAY_PROTOCOL_LIMITS.authFailures.windowMs, ), max: positiveInt( process.env.PAPERCLIP_MCP_GATEWAY_AUTH_FAILURE_LIMIT, DEFAULT_MCP_GATEWAY_PROTOCOL_LIMITS.authFailures.max, ), }, gatewayRequests: { windowMs: positiveInt( process.env.PAPERCLIP_MCP_GATEWAY_REQUEST_WINDOW_MS, DEFAULT_MCP_GATEWAY_PROTOCOL_LIMITS.gatewayRequests.windowMs, ), max: positiveInt( process.env.PAPERCLIP_MCP_GATEWAY_REQUEST_LIMIT, DEFAULT_MCP_GATEWAY_PROTOCOL_LIMITS.gatewayRequests.max, ), }, tokenRequests: { windowMs: positiveInt( process.env.PAPERCLIP_MCP_GATEWAY_TOKEN_REQUEST_WINDOW_MS, DEFAULT_MCP_GATEWAY_PROTOCOL_LIMITS.tokenRequests.windowMs, ), max: positiveInt( process.env.PAPERCLIP_MCP_GATEWAY_TOKEN_REQUEST_LIMIT, DEFAULT_MCP_GATEWAY_PROTOCOL_LIMITS.tokenRequests.max, ), }, sessionSetup: { windowMs: positiveInt( process.env.PAPERCLIP_MCP_GATEWAY_SESSION_SETUP_WINDOW_MS, DEFAULT_MCP_GATEWAY_PROTOCOL_LIMITS.sessionSetup.windowMs, ), max: positiveInt( process.env.PAPERCLIP_MCP_GATEWAY_SESSION_SETUP_LIMIT, DEFAULT_MCP_GATEWAY_PROTOCOL_LIMITS.sessionSetup.max, ), }, }; return { authFailures: mergeLimitConfig( envDefaults.authFailures, overrides?.authFailures, ), gatewayRequests: mergeLimitConfig( envDefaults.gatewayRequests, overrides?.gatewayRequests, ), tokenRequests: mergeLimitConfig( envDefaults.tokenRequests, overrides?.tokenRequests, ), sessionSetup: mergeLimitConfig( envDefaults.sessionSetup, overrides?.sessionSetup, ), }; } function tokenPrefixFromNamedBearer(token: string) { const tokenId = namedGatewayTokenId(token); if (tokenId) return `pcgw_${tokenId.slice(0, 8)}`; return token.startsWith("pcgw_") ? "pcgw_malformed" : "unknown"; } function safeHeaderValue( headers: Record | undefined, name: string, maxLength = 160, ) { const value = headers?.[name] ?? headers?.[name.toLowerCase()]; const raw = Array.isArray(value) ? value[0] : value; if (!raw) return null; const sanitized = raw.replace(/[\r\n\t]/g, " ").trim(); return sanitized ? sanitized.slice(0, maxLength) : null; } function safeClientMetadata( headers: Record | undefined, ) { const clientName = safeHeaderValue(headers, "x-paperclip-client-name", 120) ?? safeHeaderValue(headers, "mcp-client-name", 120) ?? null; const correlationId = safeHeaderValue(headers, "x-request-id", 120) ?? safeHeaderValue(headers, "x-correlation-id", 120) ?? null; return { clientName, correlationId, userAgent: safeHeaderValue(headers, "user-agent", 200), }; } function rateLimitWindowStart(current: number, windowMs: number) { return new Date(Math.floor(current / windowMs) * windowMs); } function gatewaySessionFromRow( row: typeof toolGatewaySessions.$inferSelect, ): ToolGatewaySession { return { id: row.id, token: "", companyId: row.companyId, agentId: row.agentId, runId: row.runId, issueId: row.issueId, projectId: row.projectId, createdAt: row.createdAt, expiresAt: row.expiresAt, }; } function timeoutMs(value: number | undefined, tool?: ToolGatewayDescriptor) { if (!Number.isFinite(value)) return tool?.providerType === "paperclip_github_chat" ? GITHUB_BOT_TOOL_TIMEOUT_MS : DEFAULT_TOOL_TIMEOUT_MS; return Math.max( 1, Math.min(60_000, Math.floor(value ?? DEFAULT_TOOL_TIMEOUT_MS)), ); } function sessionTtlMs(value: number | undefined) { if (!Number.isFinite(value)) return DEFAULT_SESSION_TTL_MS; return Math.max( 1_000, Math.min(MAX_SESSION_TTL_MS, Math.floor(value ?? DEFAULT_SESSION_TTL_MS)), ); } function summarizeResult(result: unknown): Record { const record = asRecord(result); if (!record) return { type: typeof result }; const content = typeof record.content === "string" ? record.content : null; return { hasContent: content !== null, contentLength: content?.length ?? 0, hasData: record.data !== undefined, hasError: Boolean(record.error), }; } function inferToolRisk(toolName: string): ToolGatewayDescriptor["risk"] { const lower = toolName.toLowerCase(); if ( /\b(delete|destroy|remove|drop|truncate|wipe|purge)\b|(^|[:._-])(delete|destroy|remove|drop|truncate|wipe|purge)([:._-]|$)/.test( lower, ) ) { return "destructive"; } if ( /\b(create|update|write|edit|patch|post|send|publish|merge|commit|apply)\b|(^|[:._-])(create|update|write|edit|patch|post|send|publish|merge|commit|apply)([:._-]|$)/.test( lower, ) ) { return "write"; } return "read"; } function riskFromCatalogEntry( entry: Pick< typeof toolCatalogEntries.$inferSelect, "riskLevel" | "isReadOnly" | "isWrite" | "isDestructive" >, ): ToolGatewayDescriptor["risk"] { if ( entry.riskLevel === "destructive" || entry.isDestructive || entry.riskLevel === "critical" || entry.riskLevel === "high" ) { return "destructive"; } if ( entry.riskLevel === "write" || entry.isWrite || entry.riskLevel === "medium" ) { return "write"; } return "read"; } export function slugSegment( value: string | null | undefined, fallback: string, ): string { const slug = String(value ?? "") .trim() .toLowerCase() .replace(/[^a-z0-9]+/g, "-") .replace(/^-+|-+$/g, "") .slice(0, 64); return slug || fallback; } export function shortStableId(id: string): string { return id.replace(/-/g, "").slice(0, 8); } function toolRequiresFormalApproval(tool: ToolGatewayDescriptor): boolean { return tool.risk === "destructive"; } function toolAuditMetadata( tool: ToolGatewayDescriptor, ): Record { return { applicationId: tool.applicationId ?? null, applicationKey: tool.applicationKey ?? null, connectionId: tool.connectionId ?? null, catalogEntryId: tool.catalogEntryId ?? null, upstreamToolName: tool.upstreamToolName ?? tool.name, providerType: tool.providerType, risk: tool.risk, riskLevel: tool.risk, }; } function stableSerialize(value: unknown): string { if (value === null || typeof value !== "object") return JSON.stringify(value); if (Array.isArray(value)) return `[${value.map(stableSerialize).join(",")}]`; return `{${Object.keys(value as Record) .sort() .map( (key) => `${JSON.stringify(key)}:${stableSerialize((value as Record)[key])}`, ) .join(",")}}`; } function stableHash(value: unknown): string { return createHash("sha256").update(stableSerialize(value)).digest("hex"); } type ConnectedCredentialVersionSnapshot = { refHash: string; versionSelector: string; resolvedVersion: number; identityEpoch?: number; }; const REDACTED_ARGUMENT_SENTINEL = "***REDACTED***"; /** Turn a machine field key (`note_body`, `noteBody`, `note-body`) into a Title-Cased label. */ function humanizeArgumentKey(key: string): string { const words = key .replace(/([a-z0-9])([A-Z])/g, "$1 $2") .replace(/[_-]+/g, " ") .trim() .split(/\s+/) .filter(Boolean); if (words.length === 0) return key; return words .map((word) => word.charAt(0).toUpperCase() + word.slice(1)) .join(" "); } /** Identifier-ish fields leak raw IDs into the prosumer card; the vocab gate forbids them. */ function isIdentifierArgumentKey(key: string): boolean { return /(^|[_-])(id|ids|uuid|guid|key|token|hash|sha\d*)$/i.test(key); } /** Render a single argument value as short, plain text — or null if it shouldn't be shown. */ function humanizeArgumentValue(value: unknown): string | null { if (typeof value === "string") { const trimmed = value.trim(); if (!trimmed) return null; if (trimmed === REDACTED_ARGUMENT_SENTINEL) return "hidden for privacy"; return trimmed.length > 140 ? `${trimmed.slice(0, 137)}…` : trimmed; } if (typeof value === "number" || typeof value === "boolean") return String(value); return null; } /** * Build the prosumer-facing "Ask first" preview (M5/M7/M9). Deliberately free of the * words tool/risk/transport/arguments and of raw JSON — those only belong on the * Advanced surfaces (M8a/M8b) and the board-only formal-approval interaction. */ function buildHumanizedActionPreview(input: { tool: ToolGatewayDescriptor; argumentsSummary: ReturnType; }): string { const actionName = input.tool.displayName?.trim() || input.tool.name; const trustLine = input.tool.risk === "destructive" ? `${actionName}. This can permanently change or remove data.` : actionName; let parsed: unknown; try { parsed = JSON.parse(input.argumentsSummary.summary); } catch { return trustLine; } if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return trustLine; const fieldLines: string[] = []; for (const [key, value] of Object.entries( parsed as Record, )) { if (fieldLines.length >= 6) break; if (isIdentifierArgumentKey(key)) continue; const rendered = humanizeArgumentValue(value); if (rendered === null) continue; fieldLines.push(`**${humanizeArgumentKey(key)}:** ${rendered}`); } if (fieldLines.length === 0) return trustLine; return [trustLine, ...fieldLines].join(" · "); } const BUILTIN_TOOLS: ToolGatewayDescriptor[] = [ { name: "mcp-remote-fixture:echo", displayName: "Remote fixture echo", description: "Remote HTTP MCP fixture that echoes a message without spawning a local process.", parametersSchema: { type: "object", properties: { message: { type: "string" } }, required: ["message"], additionalProperties: false, }, pluginId: "mcp-remote-fixture", providerType: "mcp_http_fixture", risk: "read", }, { name: "mcp-remote-fixture:add", displayName: "Remote fixture add", description: "Remote HTTP MCP fixture that adds two numbers without spawning a local process.", parametersSchema: { type: "object", properties: { a: { type: "number" }, b: { type: "number" } }, required: ["a", "b"], additionalProperties: false, }, pluginId: "mcp-remote-fixture", providerType: "mcp_http_fixture", risk: "read", }, { name: "mcp-remote-fixture:update_note", displayName: "Remote fixture update note", description: "Remote HTTP MCP fixture that simulates a side-effecting write.", parametersSchema: { type: "object", properties: { noteId: { type: "string" }, body: { type: "string" } }, required: ["noteId", "body"], additionalProperties: false, }, pluginId: "mcp-remote-fixture", providerType: "mcp_http_fixture", risk: "write", }, { name: "paperclip-self:list_my_issues", displayName: "List my Paperclip issues", description: "Paperclip self-MCP read fixture that lists the authenticated agent's current issues.", parametersSchema: { type: "object", properties: { limit: { type: "number" } }, additionalProperties: false, }, pluginId: "paperclip-self", providerType: "paperclip_self", risk: "read", }, { name: "paperclip-self:get_issue_context", displayName: "Get issue context", description: "Paperclip self-MCP read fixture that returns scoped issue context and plan document metadata.", parametersSchema: { type: "object", properties: { issueId: { type: "string" } }, additionalProperties: false, }, pluginId: "paperclip-self", providerType: "paperclip_self", risk: "read", }, { name: "mcp-stdio-fixture:increment_counter", displayName: "Stdio runtime counter", description: "Local stdio MCP fixture that lazy-starts a supervised runtime slot and increments slot-local state.", parametersSchema: { type: "object", properties: {}, additionalProperties: false, }, pluginId: "mcp-stdio-fixture", providerType: "mcp_stdio_fixture", risk: "read", }, { name: "mcp-stdio-fixture:runtime_status", displayName: "Stdio runtime status", description: "Local stdio MCP fixture that reports the reused runtime slot state.", parametersSchema: { type: "object", properties: {}, additionalProperties: false, }, pluginId: "mcp-stdio-fixture", providerType: "mcp_stdio_fixture", risk: "read", }, ]; const VIRTUAL_SEARCH_TOOLS: ToolGatewayDescriptor = { name: "search_tools", displayName: "Search available tools", description: "Search the tools available through this Paperclip gateway without loading every target tool into the tool list.", parametersSchema: { type: "object", properties: { query: { type: "string" }, limit: { type: "number" }, }, additionalProperties: false, }, pluginId: "paperclip-gateway", providerType: "paperclip_virtual", risk: "read", }; const VIRTUAL_RUN_TOOL: ToolGatewayDescriptor = { name: "run_tool", displayName: "Run a selected tool", description: "Run a target tool by name after Paperclip applies the target tool's profile, policy, approval, and rate-limit checks.", parametersSchema: { type: "object", properties: { tool: { type: "string" }, arguments: { type: "object" }, }, required: ["tool"], additionalProperties: false, }, pluginId: "paperclip-gateway", providerType: "paperclip_virtual", risk: "write", }; const VIRTUAL_TOOLS = [VIRTUAL_SEARCH_TOOLS, VIRTUAL_RUN_TOOL]; export function createToolGatewayService( db: Db, options: { pluginToolDispatcher?: PluginToolDispatcher; budgetHooks?: BudgetServiceHooks; /** Internal test seam for classification; never accepted from tool inputs. */ promptInjectionProvider?: typeof runPromptInjectionProvider; deploymentMode?: DeploymentMode; deploymentExposure?: DeploymentExposure; trustedLocalStdioRuntimeHost?: string | null; runtimeSupervisor?: ToolRuntimeSupervisorOptions; toolActionSigningSecret?: string; onToolActionSettled?: (actionRequestId: string) => Promise; /** Test seam for deterministic remote MCP protocol fixtures. */ remoteHttpRequest?: (url: string, init: RequestInit) => Promise; /** Test seam for refreshing personal Gmail grants. */ paperclipCloudConnector?: PaperclipCloudConnector | null; /** @deprecated Use paperclipCloudConnector. */ paperclipIdGmailConnector?: PaperclipCloudConnector | null; /** Refreshes customer-owned/DCR OAuth grants before remote MCP execution. */ oauthGrantRefresher?: (input: { companyId: string; connectionId: string; grantId: string; forceRefresh?: boolean; actor?: { actorType?: "agent" | "user" | "system" | "plugin"; actorId?: string | null; }; issueId?: string | null; heartbeatRunId?: string | null; }) => Promise; /** Test seam for resolving Vercel Connect credentials. */ vercelConnectClient?: VercelConnectClient | null; /** Test seam for reproducing the managed-argument drift expiry race. */ beforeManagedArgumentDriftExpiry?: () => Promise; /** Test seam for pausing a legacy approved request before its execution claim. */ beforeLegacyApprovedActionClaim?: () => Promise; mcpGatewayProtocolLimits?: Partial<{ authFailures: Partial; gatewayRequests: Partial; tokenRequests: Partial; sessionSetup: Partial; }>; now?: () => number; } = {}, ) { const injectionPrevention = promptInjectionPreventionService(db, { budgetHooks: options.budgetHooks, provider: options.promptInjectionProvider }); function resultClassifier(session: ToolGatewaySession, tool: ToolGatewayDescriptor, toolInvocationId: string | null, { approvedAction = false, signal: callerSignal }: { approvedAction?: boolean; signal?: AbortSignal } = {}) { // Approved actions retain historical run attribution, not that run's lifetime. const runSignal = session.runId && !approvedAction ? adapterExecutionControls.get(session.runId)?.controller.signal : undefined; const signal = callerSignal && runSignal ? AbortSignal.any([callerSignal, runSignal]) : callerSignal ?? runSignal; return async (content: string) => { signal?.throwIfAborted(); // Legacy/plugin sessions may not carry identity fields. Resolve them from // the admitted run, never from parameters. Signed approvals keep their origin. let identity = session.originatingAgentId ? { ...session, agentId: session.originatingAgentId } : session; if (session.runId && !approvedAction && !session.identityContextId) { const [run] = await db.select({ responsibleUserId: heartbeatRuns.responsibleUserId }).from(heartbeatRuns) .where(and(eq(heartbeatRuns.id, session.runId), eq(heartbeatRuns.companyId, session.companyId))); identity = await captureSessionIdentity({ ...identity, responsibleUserId: run?.responsibleUserId ?? session.responsibleUserId }); } return injectionPrevention.classify({ companyId: identity.companyId, source: "gateway", actorType: identity.actorType === "user" ? "user" : identity.agentId ? "agent" : "system", actorId: identity.actorId ?? identity.agentId ?? identity.gatewayTokenId ?? identity.companyId, responsibleUserId: identity.responsibleUserId ?? null, agentId: identity.agentId, issueId: identity.issueId, projectId: identity.projectId, runId: identity.runId, identityContextId: identity.identityContextId, toolInvocationId, toolName: tool.name, toolType: tool.providerType, approvedAction, }, content, signal); }; } // Authorization links can contain one-time codes. Keep them briefly in memory; // persist only the redacted request and execution identifiers for recovery. const upstreamHandoffs = new Map(); // A server's "try again" state, returned on the next identical call. It is // in memory: after a restart the server simply asks again. // MCP Apps view documents can reach MCP_APP_MAX_HTML_BYTES; larger results are not cached. const mcpContextCache = new McpResultCache(500, Date.now, 32 * 1024 * 1024, MCP_APP_MAX_HTML_BYTES + 64 * 1024); const mcpContinuations = new McpResultCache<{ requestState: string }>(512); async function persistMcpProtocolVersion(connection: typeof toolConnections.$inferSelect, protocolVersion: string) { if (asRecord(connection.config)?.mcpProtocolVersion === protocolVersion) return; const saved = await saveMcpNegotiation(db, connection, { mcpProtocolVersion: protocolVersion }); if (saved) { connection.config = saved.config; connection.transportConfig = saved.transportConfig; } } async function retainUpstreamHandoff(invocationId: string, pending: ToolUpstreamPending) { for (const [id, value] of upstreamHandoffs) if (value.expires <= Date.now()) upstreamHandoffs.delete(id); while (upstreamHandoffs.size >= 256) upstreamHandoffs.delete(upstreamHandoffs.keys().next().value!); upstreamHandoffs.set(invocationId, { pending, expires: Date.now() + 15 * 60_000 }); const summary = (await validateToolContent({ value: { upstreamPending: { ...pending, links: [] } }, direction: "result", sensitiveMode: "redact", promptInjectionMode: "ignore", })).summary; await db.update(toolInvocations).set({ resultSummary: summary }).where(eq(toolInvocations.id, invocationId)); } function recoverUpstreamHandoff(invocation: typeof toolInvocations.$inferSelect): ToolUpstreamPending | undefined { if (invocation.errorCode !== "provider_interaction_required") return undefined; const cached = upstreamHandoffs.get(invocation.id); if (cached && cached.expires > Date.now()) return cached.pending; upstreamHandoffs.delete(invocation.id); const stored = asRecord(storedInvocationResult(invocation)); const pending = asRecord(stored?.upstreamPending); if (!pending || !["approval", "authorization"].includes(String(pending.kind))) return undefined; return { ...pending, links: [] } as unknown as ToolUpstreamPending; } const runtimeSupervisor = createToolRuntimeSupervisor(db, { deploymentMode: options.deploymentMode, deploymentExposure: options.deploymentExposure, trustedLocalStdioRuntimeHost: options.trustedLocalStdioRuntimeHost, ...options.runtimeSupervisor, }); const pluginToolDispatcher = options.pluginToolDispatcher; const interactions = issueThreadInteractionService(db); const basePolicyService = toolAccessPolicyService(db, { toolActionSigningSecret: options.toolActionSigningSecret }); const issuerDecisionCaches = new WeakMap(); async function decideGatewayPolicy( input: ToolAccessDecisionInput, decisionOptions: NonNullable[1]> & { requiredGatewayAction?: ToolMcpGatewayTokenAction } = {}, policy: Pick = basePolicyService, database: Db = db, ): Promise { const issuerId = input.runContext?.originatingAgentId; if (!issuerId || !input.runContext?.gatewayId || input.actor.actorType !== "agent") return policy.decide(input, decisionOptions); if (!input.runContext.gatewayTokenId) throw new ToolGatewayHttpError(403, "Delegated gateway token is no longer available", "gateway_token_run_context_invalid"); let issuerCache: ToolAccessDecisionCache | undefined; if (decisionOptions.cache) { issuerCache = issuerDecisionCaches.get(decisionOptions.cache); if (!issuerCache) { issuerCache = createToolAccessDecisionCache(); issuerDecisionCaches.set(decisionOptions.cache, issuerCache); } } const requiredAction = decisionOptions.requiredGatewayAction ?? (input.consumeRateLimit ? "tools/call" : undefined); const authorityKey = `gateway-issuer:${input.companyId}:${input.runContext.gatewayTokenId}:${issuerId}:${requiredAction ?? "inspect"}`; let authority = issuerCache?.get(authorityKey); if (!authority) { authority = assertGatewayIssuerAuthority(input, requiredAction, database); issuerCache?.set(authorityKey, authority); } await authority; if (issuerId === input.actor.agentId) { const decision = await policy.decide(input, decisionOptions); return { ...decision, policyExplanation: { ...decision.policyExplanation, delegatedGatewayIssuer: issuerId } }; } const issuerInput = { ...input, actor: { ...input.actor, agentId: issuerId } }; const issuer = await policy.decide(issuerInput, { ...decisionOptions, cache: issuerCache }); const target = await policy.decide(input, { ...decisionOptions, sharedRateDecision: issuer }); const chosen = !issuer.allowed && issuer.decision !== "require_approval" ? issuer : !target.allowed ? target : issuer.decision === "require_approval" ? issuer : target; if (input.consumeRateLimit) await policy.writeAudit(issuerInput, issuer); return { ...chosen, matchedPolicyIds: [...new Set([...issuer.matchedPolicyIds, ...target.matchedPolicyIds])], policyExplanation: { ...chosen.policyExplanation, consumedRateAdmissions: target.policyExplanation?.consumedRateAdmissions, delegatedCallerConsumedRateAdmissions: issuer.policyExplanation?.consumedRateAdmissions, delegatedGatewayIssuer: issuerId, } }; } const policyService = { ...basePolicyService, decide: decideGatewayPolicy, admitInvocation(input: ToolAccessDecisionInput, invocationId: string, claim?: ToolApprovalClaim) { return basePolicyService.admitInvocation(input, invocationId, claim, (policy, admissionInput, transaction) => decideGatewayPolicy(admissionInput, { admittedInvocationId: invocationId, requiredGatewayAction: "tools/call" }, policy, transaction)); }, }; async function assertGatewayIssuerAuthority(input: ToolAccessDecisionInput, requiredAction?: ToolMcpGatewayTokenAction, database: Db = db) { const [row] = await database.select({ token: toolMcpGatewayTokens, gateway: toolMcpGateways }).from(toolMcpGatewayTokens) .innerJoin(toolMcpGateways, eq(toolMcpGateways.id, toolMcpGatewayTokens.gatewayId)) .where(and(eq(toolMcpGatewayTokens.id, input.runContext!.gatewayTokenId!), eq(toolMcpGatewayTokens.companyId, input.companyId))); const issuerId = input.runContext!.originatingAgentId!; if (!row || row.token.subjectType !== "gateway_client" || row.token.createdByAgentId !== issuerId || !row.token.responsibleUserId || input.actor.actorId !== issuerId || row.gateway.id !== input.runContext?.gatewayId || row.gateway.status !== "active" || row.token.revokedAt || (row.token.expiresAt && row.token.expiresAt <= new Date()) || (row.gateway.agentId && row.gateway.agentId !== input.actor.agentId)) { throw new ToolGatewayHttpError(403, "Delegated gateway authority is no longer current", "gateway_token_run_context_invalid"); } if (requiredAction && !normalizeGatewayTokenActions(row.token.allowedActions).includes(requiredAction)) throw new ToolGatewayHttpError(403, "The gateway token no longer allows this action", "gateway_token_action_not_allowed"); const actor = { type: "agent" as const, companyId: input.companyId, agentId: issuerId, onBehalfOfUserId: row.token.responsibleUserId }; const resource = { type: "connection_management" as const, companyId: input.companyId, gatewayId: row.gateway.id, profileId: row.gateway.profileId, purpose: "tool" as const, operation: "gateway_token.use", targetAgentId: row.gateway.agentId, projectId: row.gateway.projectId, issueId: row.gateway.issueId }; await connectionManagementService(database).authorize(actor, "connections:gateway", resource, { mutation: false }); await connectionManagementService(database).authorize(actor, "connections:test", resource, { mutation: false }); } async function recordToolInvocation(input: ToolAccessDecisionInput, decision: ToolAccessDecision) { try { return await policyService.recordInvocation(input, decision); } catch (error) { const details = error instanceof HttpError ? asRecord(error.details) : null; if (error instanceof HttpError && error.status === 409 && details?.reasonCode === "legacy_tool_idempotency_unverifiable") { throw new ToolGatewayHttpError(error.status, error.message, details.reasonCode, details); } throw error; } } const secrets = secretService(db); // Authentication produces a new session object for every operation. Keep // credential acquisition scoped to that object and out of persisted inputs. const githubOperationCredentials = new WeakMap< ToolGatewaySession, { grant: typeof connectionGrants.$inferSelect; headers: Record; } >(); const configuredCloudConnector = options.paperclipCloudConnector ?? options.paperclipIdGmailConnector; const connectorWasProvided = options.paperclipCloudConnector !== undefined || options.paperclipIdGmailConnector !== undefined; let cachedCloudConnector = configuredCloudConnector ?? null; const currentCloudConnector = (): PaperclipCloudConnector | null => { if (cachedCloudConnector || connectorWasProvided) return cachedCloudConnector; const config = paperclipCloudConnectorConfigFromEnv(); cachedCloudConnector = config ? createPaperclipCloudConnector({ config, now: options.now }) : null; return cachedCloudConnector; }; const gmailRefreshFlights = new Map< string, Promise >(); const vercelConnect = options.vercelConnectClient === undefined ? createVercelConnectClient() : options.vercelConnectClient; const protocolLimits = mcpGatewayProtocolLimits( options.mcpGatewayProtocolLimits, ); let nextProtocolRateLimitPruneAt = 0; async function pruneExpiredProtocolRateLimitCounters(current: number) { if (current < nextProtocolRateLimitPruneAt) return; nextProtocolRateLimitPruneAt = current + 60_000; await db .delete(toolGatewayRateLimitCounters) .where(lte(toolGatewayRateLimitCounters.resetAt, new Date(current))); } async function consumeProtocolRateLimit(input: { companyId: string; counterKey: string; config: McpGatewayRateLimitConfig; }): Promise { const current = options.now?.() ?? Date.now(); const windowStartAt = rateLimitWindowStart(current, input.config.windowMs); const resetAt = new Date(windowStartAt.getTime() + input.config.windowMs); const nowDate = new Date(current); const windowStartIso = windowStartAt.toISOString(); const resetIso = resetAt.toISOString(); const nowIso = nowDate.toISOString(); await pruneExpiredProtocolRateLimitCounters(current); const rows = Array.from( await db.execute(sql<{ count: number | string }>` INSERT INTO "tool_gateway_rate_limit_counters" ( "company_id", "counter_key", "window_start_at", "window_ms", "limit", "count", "reset_at", "created_at", "updated_at" ) VALUES ( ${input.companyId}, ${input.counterKey}, ${windowStartIso}::timestamptz, ${input.config.windowMs}, ${input.config.max}, 1, ${resetIso}::timestamptz, ${nowIso}::timestamptz, ${nowIso}::timestamptz ) ON CONFLICT ("company_id", "counter_key", "window_start_at") DO UPDATE SET "count" = "tool_gateway_rate_limit_counters"."count" + 1, "window_ms" = ${input.config.windowMs}, "limit" = ${input.config.max}, "reset_at" = ${resetIso}::timestamptz, "updated_at" = ${nowIso}::timestamptz RETURNING "count" `), ); const count = Number(rows[0]?.count ?? 1); return { limited: count > input.config.max, count, retryAfterMs: Math.max(0, resetAt.getTime() - current), }; } function pluginTools(): ToolGatewayDescriptor[] { return (pluginToolDispatcher?.listToolsForAgent() ?? []).map((tool) => ({ ...tool, providerType: "paperclip_plugin" as const, risk: inferToolRisk(tool.name), })); } function allTools(): ToolGatewayDescriptor[] { return [...BUILTIN_TOOLS, ...pluginTools()]; } function connectedMcpConnectionFilter(companyId: string) { return and( eq(toolConnections.companyId, companyId), inArray(toolConnections.transport, ["mcp_remote", "local_stdio", "rest_api"]), eq(toolConnections.status, "active"), eq(toolConnections.enabled, true), // A personal connection has no company-level credential to probe. A // credential-less health sweep can therefore mark it as errored even // while the responsible user's grant is valid. Keep its cached active // catalog discoverable; execution resolves and validates that user's // grant, and a successful call restores the shared health indicator. or( inArray(toolConnections.healthStatus, ["ok", "healthy"]), eq(toolConnections.credentialPolicy, "per_user"), ), eq(toolApplications.companyId, companyId), inArray(toolApplications.type, ["mcp_http", "mcp_stdio", "rest_api"]), eq(toolApplications.status, "active"), ); } async function connectedMcpToolsForCompany( companyId: string, selectedConnectionIds?: string[], ): Promise { if (selectedConnectionIds?.length === 0) return []; // Read each connection and application row once. Selecting them in the // catalog join repeats the full connection row (config included) for // every tool, and one connection can expose hundreds of tools. Both reads // share one read-only snapshot, so they agree like a single join, and the // second read gets only the connections that have listed tools. const { connectionRows, catalogRows } = await db.transaction( async (tx) => { const catalogRows = await tx .select({ catalogEntry: toolCatalogEntries }) .from(toolCatalogEntries) .innerJoin( toolConnections, eq(toolCatalogEntries.connectionId, toolConnections.id), ) .innerJoin( toolApplications, eq(toolConnections.applicationId, toolApplications.id), ) .where( and( eq(toolCatalogEntries.companyId, companyId), eq(toolCatalogEntries.entryKind, "tool"), eq(toolCatalogEntries.status, "active"), isNull(toolCatalogEntries.quarantinedAt), connectedMcpConnectionFilter(companyId), selectedConnectionIds ? inArray(toolConnections.id, selectedConnectionIds) : undefined, ), ) .orderBy(toolConnections.name, toolCatalogEntries.name); const connectionIds = [ ...new Set( catalogRows.map(({ catalogEntry }) => catalogEntry.connectionId), ), ]; if (connectionIds.length === 0) return { connectionRows: [], catalogRows }; const connectionRows = await tx .select({ connection: toolConnections, application: toolApplications, }) .from(toolConnections) .innerJoin( toolApplications, eq(toolConnections.applicationId, toolApplications.id), ) .where( and( inArray(toolConnections.id, connectionIds), connectedMcpConnectionFilter(companyId), ), ); return { connectionRows, catalogRows }; }, { isolationLevel: "repeatable read", accessMode: "read only" }, ); const connectionRowsById = new Map( connectionRows.map((row) => [row.connection.id, row]), ); const rows = catalogRows.flatMap(({ catalogEntry }) => { const connectionRow = connectionRowsById.get(catalogEntry.connectionId); return connectionRow ? [{ catalogEntry, ...connectionRow }] : []; }); const featureSettings = connectionRows.some(({ application }) => getAppDefinitionForApplicationKey(application.applicationKey)?.experimentalFeatureKey) ? await instanceSettingsService(db).getExperimental() : undefined; const eligibleRows = rows.filter( ({ catalogEntry, connection, application }) => (!featureSettings || isConnectorFeatureEnabled(getAppDefinitionForApplicationKey(application.applicationKey), featureSettings)) && !isRetiredComposioConnection(connection) && !(nativeProviderCatalogFor(connection) && !nativeProviderCatalogFor(connection)!.isCurrentEntry(catalogEntry)) && !(restConnectorFor(connection) && !restConnectorFor(connection)!.isCurrent(catalogEntry)) && !(isRailwayEndpoint(connection.config.url) && (isRailwayToolBlocked(catalogEntry.toolName) || (normalizeRailwayToolName(catalogEntry.toolName).startsWith(RAILWAY_TOOL_PREFIX) && connection.config.railwayApiStatus !== "available"))) && (((isBrowserUseConnection(connection) || nativeProviderCatalogFor(connection) || restConnectorFor(connection)) && application.type === "rest_api") || (connection.transport === "mcp_remote" && application.type === "mcp_http") || (connection.transport === "local_stdio" && application.type === "mcp_stdio")), ); const baseNames = eligibleRows.map( ({ catalogEntry, connection, application }) => { const applicationKey = application.applicationKey ?? null; const connectionNamespace = `${slugSegment(applicationKey ?? connection.name ?? application.name, "mcp")}-${shortStableId(connection.id)}`; const toolSlug = slugSegment(catalogEntry.toolName, "tool"); return `${connection.transport === "rest_api" ? "app" : "mcp"}.${connectionNamespace}:${toolSlug}`; }, ); const baseNameCounts = baseNames.reduce>( (counts, name) => { counts.set(name, (counts.get(name) ?? 0) + 1); return counts; }, new Map(), ); return eligibleRows.map( ({ catalogEntry, connection, application }, index) => { if ( connection.transport !== "mcp_remote" && connection.transport !== "local_stdio" && !isBrowserUseConnection(connection) && !nativeProviderCatalogFor(connection) && !restConnectorFor(connection) ) { throw new Error( `Non-MCP connection ${connection.id} cannot be exposed through the MCP gateway`, ); } const baseName = baseNames[index]!; const unboundedGatewayToolName = baseNameCounts.get(baseName)! > 1 ? `${baseName}-${shortStableId(catalogEntry.id)}` : baseName; const gatewayToolName = boundedMcpToolName(unboundedGatewayToolName, [ connection.id, application.id, catalogEntry.toolName, ...(baseNameCounts.get(baseName)! > 1 ? [catalogEntry.id] : []), ]); const applicationKey = application.applicationKey ?? null; const inputSchema = projectedConnectionToolInputSchema( connection, catalogEntry.inputSchema ?? {}, catalogEntry.toolName, ); const outputSchema = catalogEntry.outputSchema ?? null; const annotations = catalogEntry.annotations ?? {}; const risk = riskFromCatalogEntry(catalogEntry); const onDemandTools = readOnDemandToolsEnabled(connection); const providerMetadata: ConnectedMcpGatewayMetadata = { applicationId: application.id, applicationKey, applicationDisplayName: application.name, connectionId: connection.id, catalogEntryId: catalogEntry.id, transport: connection.transport as ConnectedMcpGatewayMetadata["transport"], gatewayToolName, upstreamToolName: catalogEntry.toolName, catalogName: catalogEntry.name, inputSchema, outputSchema, annotations, ui: catalogEntry.uiMeta ?? null, risk: { level: catalogEntry.riskLevel, isReadOnly: catalogEntry.isReadOnly, isWrite: catalogEntry.isWrite, isDestructive: catalogEntry.isDestructive, }, onDemandTools, }; return { name: gatewayToolName, displayName: catalogEntry.title ?? catalogEntry.toolName, description: gmailArchiveToolDescription( connection, catalogEntry.toolName, googleChatToolDescription(connection, catalogEntry.toolName, catalogEntry.description), ) ?? `Connected MCP tool ${catalogEntry.toolName} from ${connection.name}.`, parametersSchema: inputSchema, pluginId: `mcp:${applicationKey ?? application.id}`, providerType: connection.transport === "rest_api" ? "provider_rest" : connection.transport === "local_stdio" ? "mcp_local_stdio" : "mcp_remote_http", risk, applicationId: application.id, applicationKey, applicationDisplayName: application.name, connectionId: connection.id, catalogEntryId: catalogEntry.id, upstreamToolName: catalogEntry.toolName, providerMetadata, }; }, ); } async function connectedMcpToolsForConnection( companyId: string, connectionId: string, ): Promise { return (await connectedMcpToolsForCompany(companyId)).filter( (tool) => tool.connectionId === connectionId, ); } async function assertAgentInCompany( companyId: string, agentId: string, ): Promise { const [agent] = await db .select({ companyId: agents.companyId, }) .from(agents) .where(eq(agents.id, agentId)) .limit(1); if (!agent || agent.companyId !== companyId) { throw new ToolGatewayHttpError( 404, "Agent not found for company", "agent_not_found", ); } } /** * "Last changed by {Actor} · {relativeTime}" audit hint for the Test tab Off * side panel. Looks across the configuration that governs this agent's access * to the connection — the policies that matched, the profiles in effect, the * entries that scope them to this connection, and the bindings that assigned * those profiles to the agent — and reports the most recent edit. Only * policies and bindings carry an actor, so the attributed agent name is best * effort: when the latest edit was a profile/entry toggle (no actor column), * the timestamp is still returned but the actor is null. */ async function summarizeAccessLastChange(input: { companyId: string; connectionId: string; agentId: string; policyIds: string[]; profileIds: string[]; }): Promise<{ lastChangedAt: string | null; lastChangedByAgentId: string | null; lastChangedByName: string | null; }> { const empty = { lastChangedAt: null, lastChangedByAgentId: null, lastChangedByName: null, }; const candidates: Array<{ updatedAt: Date; agentId: string | null }> = []; if (input.policyIds.length > 0) { const policies = await db .select({ updatedAt: toolPolicies.updatedAt, agentId: toolPolicies.createdByAgentId, }) .from(toolPolicies) .where( and( eq(toolPolicies.companyId, input.companyId), inArray(toolPolicies.id, input.policyIds), ), ); candidates.push( ...policies.map((row) => ({ updatedAt: row.updatedAt, agentId: row.agentId, })), ); } if (input.profileIds.length > 0) { const [profiles, entries, bindings] = await Promise.all([ db .select({ updatedAt: toolProfiles.updatedAt }) .from(toolProfiles) .where( and( eq(toolProfiles.companyId, input.companyId), inArray(toolProfiles.id, input.profileIds), ), ), db .select({ updatedAt: toolProfileEntries.updatedAt }) .from(toolProfileEntries) .where( and( eq(toolProfileEntries.companyId, input.companyId), inArray(toolProfileEntries.profileId, input.profileIds), eq(toolProfileEntries.connectionId, input.connectionId), ), ), db .select({ updatedAt: toolProfileBindings.updatedAt, agentId: toolProfileBindings.createdByAgentId, }) .from(toolProfileBindings) .where( and( eq(toolProfileBindings.companyId, input.companyId), inArray(toolProfileBindings.profileId, input.profileIds), eq(toolProfileBindings.targetType, "agent"), eq(toolProfileBindings.targetId, input.agentId), ), ), ]); candidates.push( ...profiles.map((row) => ({ updatedAt: row.updatedAt, agentId: null })), ); candidates.push( ...entries.map((row) => ({ updatedAt: row.updatedAt, agentId: null })), ); candidates.push( ...bindings.map((row) => ({ updatedAt: row.updatedAt, agentId: row.agentId, })), ); } if (candidates.length === 0) return empty; const latest = candidates.reduce((a, b) => b.updatedAt.getTime() > a.updatedAt.getTime() ? b : a, ); let lastChangedByName: string | null = null; if (latest.agentId) { const [actor] = await db .select({ name: agents.name }) .from(agents) .where(eq(agents.id, latest.agentId)) .limit(1); lastChangedByName = actor?.name ?? null; } return { lastChangedAt: latest.updatedAt.toISOString(), lastChangedByAgentId: latest.agentId, lastChangedByName, }; } async function resolveRunContext(input: { companyId: string; agentId: string; runId: string; issueId?: string | null; projectId?: string | null; }): Promise<{ issueId: string | null; projectId: string | null }> { const [run] = await db .select({ companyId: heartbeatRuns.companyId, agentId: heartbeatRuns.agentId, status: heartbeatRuns.status, issueId: boundRunIssueIdSql(), projectId: runContextSnapshotString("projectId"), }) .from(heartbeatRuns) .where(eq(heartbeatRuns.id, input.runId)) .limit(1); if (!run || run.companyId !== input.companyId) { throw new ToolGatewayHttpError( 403, "Run does not belong to company", "run_company_mismatch", ); } if (run.agentId !== input.agentId) { throw new ToolGatewayHttpError( 403, "Run does not belong to agent", "run_agent_mismatch", ); } if (!ACTIVE_GATEWAY_RUN_STATUSES.has(run.status)) { throw new ToolGatewayHttpError(403, "Run is not active", "run_inactive"); } const snapshotIssueId = stringValue(run.issueId); const snapshotProjectId = stringValue(run.projectId); if ( (input.issueId && snapshotIssueId && input.issueId !== snapshotIssueId) || (input.projectId && snapshotProjectId && input.projectId !== snapshotProjectId) ) { throw new ToolGatewayHttpError( 403, "Supplied run context does not match stored heartbeat context", "run_context_mismatch", ); } const issueId = snapshotIssueId ?? input.issueId ?? null; let projectId = snapshotProjectId ?? input.projectId ?? null; if (issueId) { const [issue] = await db .select({ companyId: issues.companyId, projectId: issues.projectId }) .from(issues) .where(eq(issues.id, issueId)) .limit(1); if (!issue || issue.companyId !== input.companyId) { throw new ToolGatewayHttpError( 403, "Issue context is outside the run company", "run_context_mismatch", ); } if (projectId && issue.projectId && projectId !== issue.projectId) { throw new ToolGatewayHttpError( 403, "Project context does not match issue context", "run_context_mismatch", ); } projectId = projectId ?? issue.projectId; } if (projectId) { const [project] = await db .select({ companyId: projects.companyId }) .from(projects) .where(eq(projects.id, projectId)) .limit(1); if (!project || project.companyId !== input.companyId) { throw new ToolGatewayHttpError( 403, "Project context is outside the run company", "run_context_mismatch", ); } } return { issueId, projectId, }; } async function writeAudit(input: { session?: ToolGatewaySession | null; companyId: string; agentId: string | null; runId: string | null; issueId: string | null; actorType?: LogActivityInput["actorType"]; actorId?: string; action: string; details: Record; }) { const dedicatedAuditAction = input.action === "tool_gateway.discovery" ? "discovery" : input.action === "tool_gateway.session_revoked" ? "session_revoked" : input.action === "tool_gateway.call_allowed" || input.action === "tool_gateway.session_created" ? "policy_decision" : input.action === "tool_gateway.call_completed" ? "call_completed" : input.action === "tool_gateway.call_denied" || input.action === "tool_gateway.session_rejected" ? "call_denied" : input.action === "tool_gateway.call_deferred" ? "call_failed" : "call_failed"; const dedicatedOutcome = input.action === "tool_gateway.session_revoked" ? "success" : input.action === "tool_gateway.call_denied" || input.action === "tool_gateway.session_rejected" ? "denied" : input.action === "tool_gateway.call_deferred" ? "timeout" : input.action === "tool_gateway.call_failed" ? "failure" : "success"; try { const tokenId = input.session?.gatewayTokenId && uuidPattern.test(input.session.gatewayTokenId) ? input.session.gatewayTokenId : typeof input.details.gatewayTokenId === "string" && uuidPattern.test(input.details.gatewayTokenId) ? input.details.gatewayTokenId : null; await db.insert(toolAccessAuditEvents).values({ companyId: input.companyId, gatewayId: input.session?.gatewayId ?? (typeof input.details.gatewayId === "string" && uuidPattern.test(input.details.gatewayId) ? input.details.gatewayId : null), // Cleanup can remove a token after request admission. Resolve the FK // inside this INSERT and lock a surviving row until the statement ends. // A plain existence read before insertion still races with deletion. gatewayTokenId: tokenId ? sql`(select ${toolMcpGatewayTokens.id} from ${toolMcpGatewayTokens} where ${toolMcpGatewayTokens.id} = ${tokenId} and ${toolMcpGatewayTokens.companyId} = ${input.companyId} for key share)` : null, gatewayPublicId: typeof input.details.gatewayPublicId === "string" ? input.details.gatewayPublicId : null, clientName: typeof input.details.clientName === "string" ? input.details.clientName : null, correlationId: typeof input.details.correlationId === "string" ? input.details.correlationId : null, connectionId: typeof input.details.connectionId === "string" ? input.details.connectionId : null, catalogEntryId: typeof input.details.catalogEntryId === "string" ? input.details.catalogEntryId : null, actorType: input.actorType ?? input.session?.actorType ?? (input.agentId ? "agent" : "system"), actorId: input.actorId ?? input.session?.actorId ?? input.agentId ?? input.session?.gatewayTokenId ?? input.companyId, action: dedicatedAuditAction, outcome: dedicatedOutcome, reasonCode: typeof input.details.reasonCode === "string" ? input.details.reasonCode : null, details: { source: input.action, agentId: input.agentId, issueId: input.issueId, projectId: input.session?.projectId ?? null, runId: input.runId, gatewaySessionId: input.session?.id ?? null, identityContextId: input.session?.identityContextId ?? null, gatewayId: input.session?.gatewayId ?? null, gatewayPublicId: input.session?.gatewayPublicId ?? null, gatewayName: input.session?.gatewayName ?? null, gatewayTokenId: input.session?.gatewayTokenId ?? null, ...input.details, }, }); } catch (error) { await recordToolRuntimeAuditWriteFailure(db, input.companyId); throw error; } const entityType = input.issueId ? "issue" : input.session?.gatewayId ? "tool_mcp_gateway" : "agent"; const entityId = input.issueId ?? input.session?.gatewayId ?? input.agentId ?? input.companyId; await logActivity(db, { companyId: input.companyId, actorType: input.actorType ?? input.session?.actorType ?? (input.agentId ? "agent" : "system"), actorId: input.actorId ?? input.session?.actorId ?? input.agentId ?? input.session?.gatewayTokenId ?? input.companyId, action: input.action, entityType, entityId, agentId: input.agentId, runId: input.runId, issueId: input.issueId, details: { gatewaySessionId: input.session?.id ?? null, gatewayId: input.session?.gatewayId ?? null, gatewayPublicId: input.session?.gatewayPublicId ?? null, issueId: input.issueId, projectId: input.session?.projectId ?? null, runId: input.runId, ...input.details, }, }); } async function writeSessionAuthFailure( row: typeof toolGatewaySessions.$inferSelect, reasonCode: string, details: Record = {}, ) { const session = gatewaySessionFromRow(row); await writeAudit({ session, companyId: session.companyId, agentId: session.agentId, runId: session.runId, issueId: session.issueId, action: "tool_gateway.session_rejected", details: { decision: "deny", reasonCode, expiresAt: session.expiresAt.toISOString(), revokedAt: row.revokedAt?.toISOString() ?? null, ...details, }, }); } async function assertSessionRunIsActive( row: typeof toolGatewaySessions.$inferSelect, ) { const [run] = await db .select({ companyId: heartbeatRuns.companyId, agentId: heartbeatRuns.agentId, status: heartbeatRuns.status, }) .from(heartbeatRuns) .where(eq(heartbeatRuns.id, row.runId)) .limit(1); if ( !run || run.companyId !== row.companyId || run.agentId !== row.agentId || !ACTIVE_GATEWAY_RUN_STATUSES.has(run.status) ) { await writeSessionAuthFailure(row, "session_run_inactive", { runStatus: run?.status ?? null, }); throw new ToolGatewayHttpError( 401, "Tool gateway session is expired or invalid", "session_run_inactive", ); } } async function getActiveSession( sessionToken: string, namedGatewayProtocol?: { gatewayId?: string | null; gatewayPublicId?: string | null; protocolMethod: McpGatewayProtocolMethod; callerHeaders?: Record; }, ): Promise { const token = sessionToken.trim(); if (!token) { throw new ToolGatewayHttpError( 401, "Tool gateway session is expired or invalid", "session_invalid", ); } if (namedGatewayTokenId(token)) { return namedGatewaySessionFromBearer({ gatewayId: namedGatewayProtocol?.gatewayId ?? null, gatewayPublicId: namedGatewayProtocol?.gatewayPublicId ?? null, bearerToken: token, protocolMethod: namedGatewayProtocol?.protocolMethod ?? "tools/call", callerHeaders: namedGatewayProtocol?.callerHeaders, }); } const tokenHash = hashGatewayToken(token); const [row] = await db .select() .from(toolGatewaySessions) .where(eq(toolGatewaySessions.tokenHash, tokenHash)) .limit(1); if (!row) { const sessionId = sessionIdFromGatewayToken(token); if (sessionId) { const [candidate] = await db .select() .from(toolGatewaySessions) .where(eq(toolGatewaySessions.id, sessionId)) .limit(1); if (candidate) { await writeSessionAuthFailure(candidate, "session_invalid"); } } throw new ToolGatewayHttpError( 401, "Tool gateway session is expired or invalid", "session_invalid", ); } if (row.revokedAt) { await writeSessionAuthFailure(row, "session_revoked"); throw new ToolGatewayHttpError( 401, "Tool gateway session is expired or invalid", "session_revoked", ); } if (row.expiresAt.getTime() <= Date.now()) { await writeSessionAuthFailure(row, "session_expired"); throw new ToolGatewayHttpError( 401, "Tool gateway session is expired or invalid", "session_expired", ); } await assertSessionRunIsActive(row); const now = new Date(); await db .update(toolGatewaySessions) .set({ lastUsedAt: now, updatedAt: now }) .where(eq(toolGatewaySessions.id, row.id)); const session = gatewaySessionFromRow({ ...row, lastUsedAt: now, updatedAt: now, }); return captureSessionIdentity(session); } async function captureSessionIdentity( session: ToolGatewaySession, ): Promise { // Authentication creates a fresh operation snapshot on every invocation. // Never trust a previously attached context on a reusable transport session. // Approved operations restore their signed origin after authentication. if (!session.runId || !session.agentId) return session; const [run] = await db .select({ activeIdentityContextId: heartbeatRuns.activeIdentityContextId, }) .from(heartbeatRuns) .where( and( eq(heartbeatRuns.id, session.runId), eq(heartbeatRuns.companyId, session.companyId), ), ); if (!run?.activeIdentityContextId) return session; const captured = await captureRunIdentity(db, { companyId: session.companyId, agentId: session.agentId, runId: session.runId, }, { readScope: "identity" }); return { ...session, identityContextId: captured.context?.id, responsibleUserId: captured.context?.cause === "company_default" ? null : captured.context?.responsibleUserId, }; } function normalizeGatewayTokenActions( value: unknown, ): ToolMcpGatewayTokenAction[] { const known = new Set([ "tools/list", "tools/call", "resources/list", "resources/read", "prompts/list", "prompts/get", ]); const actions = Array.isArray(value) ? value.filter((action): action is ToolMcpGatewayTokenAction => known.has(action as ToolMcpGatewayTokenAction), ) : []; return actions.length > 0 ? actions : [...known]; } async function assertGatewayTokenAction( session: ToolGatewaySession, action: ToolMcpGatewayTokenAction, ) { const allowedActions = session.gatewayTokenAllowedActions; if (!allowedActions || allowedActions.includes(action)) return; await writeAudit({ session, companyId: session.companyId, agentId: session.agentId, runId: session.runId, issueId: session.issueId, action: action.endsWith("/list") ? "tool_gateway.discovery" : "tool_gateway.call_denied", details: { decision: "deny", reasonCode: "gateway_token_action_denied", requestedAction: action, allowedActions, }, }); throw new ToolGatewayHttpError( 403, "Gateway bearer token is not allowed to perform this MCP action", "gateway_token_action_denied", { requestedAction: action, }, ); } async function writeToolCallEvent(input: { invocationId?: string | null; actionRequestId?: string | null; session: ToolGatewaySession; eventType: | "policy_decision" | "invocation_created" | "approval_requested" | "approval_resolved" | "call_started" | "call_completed" | "call_failed" | "call_denied"; outcome: "pending" | "success" | "failure" | "denied" | "timeout" | "cancelled"; toolName: string; policyDecision?: "allow" | "deny" | "require_approval" | "defer_runtime" | null; reasonCode?: string | null; argumentsSummary?: ReturnType | null; resultSummary?: ReturnType | null; detectorMetadata?: PromptInjectionDetectorMetadata; metadata?: Record | null; tool?: ToolGatewayDescriptor | null; }) { const metadata = input.tool ? toolAuditMetadata(input.tool) : {}; await db.insert(toolCallEvents).values({ companyId: input.session.companyId, invocationId: input.invocationId ?? null, actionRequestId: input.actionRequestId ?? null, eventType: input.eventType, outcome: input.outcome, actorType: input.session.actorType ?? (input.session.agentId ? "agent" : "system"), actorId: input.session.actorId ?? input.session.agentId ?? input.session.gatewayTokenId ?? input.session.companyId, agentId: input.session.agentId, issueId: input.session.issueId, runId: input.session.runId, applicationId: input.tool?.applicationId ?? null, connectionId: input.tool?.connectionId ?? null, catalogEntryId: input.tool?.catalogEntryId ?? null, toolName: input.toolName, decision: input.policyDecision ?? null, reasonCode: input.reasonCode ?? null, matchedPolicyIds: [], requestHash: input.argumentsSummary?.sha256 ?? null, requestSummary: input.argumentsSummary ?? null, resultHash: input.resultSummary?.sha256 ?? null, resultSummary: input.resultSummary ?? null, resultSizeBytes: input.resultSummary?.sizeBytes ?? null, metadata: Object.keys(metadata).length > 0 || input.metadata || input.detectorMetadata || input.session.projectId || input.session.identityContextId ? { ...metadata, identityContextId: input.session.identityContextId ?? null, gatewayId: input.session.gatewayId ?? null, gatewayName: input.session.gatewayName ?? null, projectId: input.session.projectId ?? null, ...(input.metadata ?? {}), ...(input.detectorMetadata ? { promptInjection: input.detectorMetadata } : {}), } : null, }); } async function reflectToolActionInteractionLifecycle(input: { actionRequestId: string; status: | "approved" | "executing" | "executed" | "failed" | "expired" | "cancelled"; errorCode?: string | null; errorMessage?: string | null; resultSummary?: string | null; }): Promise { const [linked] = await db .select({ companyId: toolActionRequests.companyId, interactionId: toolActionRequests.interactionId, issueId: toolActionRequests.issueId, }) .from(toolActionRequests) .where(eq(toolActionRequests.id, input.actionRequestId)) .limit(1); if (!linked?.interactionId) return; const interactionId = linked.interactionId; const changed = await db.transaction(async (tx) => { const [interaction] = await tx .select({ status: issueThreadInteractions.status, result: issueThreadInteractions.result, }) .from(issueThreadInteractions) .where( and( eq(issueThreadInteractions.id, interactionId), eq(issueThreadInteractions.companyId, linked.companyId), ), ) .for("update") .limit(1); const [currentRequest] = await tx .select({ status: toolActionRequests.status }) .from(toolActionRequests) .where(eq(toolActionRequests.id, input.actionRequestId)) .for("update"); if (currentRequest?.status !== input.status) return false; if (!interaction) return; const currentResult = interaction.result && typeof interaction.result === "object" ? (interaction.result as unknown as Record) : null; const outcome = typeof currentResult?.outcome === "string" ? currentResult.outcome : interaction.status === "accepted" ? "accepted" : interaction.status === "rejected" ? "rejected" : interaction.status === "expired" || input.status === "expired" || input.status === "cancelled" ? "stale_target" : null; if (!outcome) return; const projection = asRecord(currentResult?.toolAction); if (projection?.status === (input.status === "cancelled" ? "expired" : input.status) && projection.errorCode === (input.errorCode ?? null) && projection.errorMessage === (input.errorMessage ?? null) && projection.resultSummary === (input.resultSummary ?? null)) return false; const now = new Date(); if (linked.issueId && interaction.status === "pending" && ["expired", "cancelled"].includes(input.status)) { await notifyChatRunMilestones(tx, { companyId: linked.companyId, issueId: linked.issueId }); } await tx .update(issueThreadInteractions) .set({ ...(["expired", "cancelled"].includes(input.status) && interaction.status === "pending" ? { status: input.status, resolvedAt: now } : {}), result: { ...(currentResult ?? { version: 1, outcome }), toolAction: { ...asRecord(currentResult?.toolAction), version: 1, status: input.status === "cancelled" ? "expired" : input.status, errorCode: input.errorCode ?? null, errorMessage: input.errorMessage ?? null, resultSummary: input.resultSummary ?? null, updatedAt: now.toISOString(), }, } as unknown as NonNullable< typeof issueThreadInteractions.$inferInsert.result >, updatedAt: now, }) .where(eq(issueThreadInteractions.id, interactionId)); return true; }); if (!changed) return; await logActivity(db, { companyId: linked.companyId, actorType: "system", actorId: "tool-gateway", action: "issue.thread_interaction_updated", entityType: "issue", entityId: linked.issueId!, details: { interactionId: linked.interactionId, actionRequestId: input.actionRequestId, executionStatus: input.status, }, }); if (["executed", "failed", "expired", "cancelled"].includes(input.status)) await options .onToolActionSettled?.(input.actionRequestId) .catch((error) => logger.warn( { err: error, actionRequestId: input.actionRequestId }, "Tool review continuation will be retried", ), ); } async function approvalRequiredInstructions( issueId: string, ): Promise { const [issue] = await db .select({ identifier: issues.identifier }) .from(issues) .where(eq(issues.id, issueId)) .limit(1); const task = issue?.identifier ?? issueId; return `A human approval card was posted on task ${task}. Do not retry this call now. Wrap up other work and end your run noting you are waiting on tool approval (status in_review). You will be woken when it is decided; if approved, the action runs automatically and your wake includes the result.`; } async function throwApprovalRequired(input: { invocationId: string; actionRequestId: string; interactionId?: string | null; issueId: string; toolName: string; argumentsHash: string; }): Promise { throw new ToolGatewayHttpError( 409, "Tool action requires approval", "approval_required", { invocationId: input.invocationId, actionRequestId: input.actionRequestId, interactionId: input.interactionId ?? null, issueId: input.issueId, tool: input.toolName, argumentsHash: input.argumentsHash, instructions: await approvalRequiredInstructions(input.issueId), }, ); } async function requestApprovalForRecordedToolCall(input: { invocation: typeof toolInvocations.$inferSelect; actionRequest: typeof toolActionRequests.$inferSelect | null; session: ToolGatewaySession; tool: ToolGatewayDescriptor; parameters: unknown; argumentsSummary: ReturnType; policyDecision: ToolAccessDecision; }): Promise { const canonicalArguments = canonicalToolArguments(input.parameters); const canonicalArgumentsHash = toolRequestIdentityHash(input.parameters, options.toolActionSigningSecret); const approvalSnapshot = await connectedRemoteApprovalSnapshot( input.session, input.tool, { requireResolvedCredentials: true, }, ); if (!input.session.issueId) { await db .update(toolInvocations) .set({ status: "denied", approvalState: "required", errorCode: "approval_path_missing", errorMessage: "Approval-required tool calls need an issue-scoped gateway session", completedAt: new Date(), updatedAt: new Date(), }) .where(eq(toolInvocations.id, input.invocation.id)); void emitConnectionInvoked(db, input.invocation.id); await writeToolCallEvent({ invocationId: input.invocation.id, actionRequestId: input.actionRequest?.id ?? null, session: input.session, eventType: "call_denied", outcome: "denied", toolName: input.tool.name, policyDecision: "deny", reasonCode: "approval_path_missing", argumentsSummary: input.argumentsSummary, tool: input.tool, }); throw new ToolGatewayHttpError( 409, "Tool action requires approval, but this gateway session is not attached to an issue", "approval_path_missing", { invocationId: input.invocation.id, tool: input.tool.name, instructions: "This session is not attached to a task, so an approval card cannot be posted. Re-run this action from a run that has the task checked out.", }, ); } if (!input.actionRequest) { await db .update(toolInvocations) .set({ status: "denied", errorCode: "approval_request_missing", errorMessage: "Approval-required policy decision did not create an action request", completedAt: new Date(), updatedAt: new Date(), }) .where(eq(toolInvocations.id, input.invocation.id)); void emitConnectionInvoked(db, input.invocation.id); throw new ToolGatewayHttpError( 500, "Approval request was not created", "approval_request_missing", { invocationId: input.invocation.id, tool: input.tool.name, }, ); } const actionRequest = input.actionRequest; // Human review has no implicit token/session deadline. Explicit action // deadlines, task closure and current authorization still gate execution. const expiresAt = actionRequest.expiresAt; let signedArguments: ReturnType; try { signedArguments = signToolArguments({ invocationId: input.invocation.id, toolName: input.tool.name, canonicalArguments, approvalSnapshot: approvalSnapshot ?? undefined, executionOnApprove: true, identityContextId: input.session.identityContextId ?? undefined, signingSecret: options.toolActionSigningSecret, }); } catch (error) { await writeToolReviewChange(db, actionRequest.companyId, tx => tx .update(toolActionRequests) .set({ status: "cancelled", resolvedAt: new Date(), updatedAt: new Date(), }) .where( and( eq(toolActionRequests.id, actionRequest.id), eq(toolActionRequests.status, "pending"), ), )); if (error instanceof ToolActionSigningSecretMissingError) { await db .update(toolInvocations) .set({ status: "failed", errorCode: "signing_secret_unconfigured", errorMessage: error.message, completedAt: new Date(), updatedAt: new Date(), }) .where(eq(toolInvocations.id, input.invocation.id)); void emitConnectionInvoked(db, input.invocation.id); throw new ToolGatewayHttpError( 500, error.message, "signing_secret_unconfigured", { invocationId: input.invocation.id, tool: input.tool.name, }, ); } throw error; } // Board-only technical detail for the formal-approval interaction (target=custom). const detailsMarkdown = [ `Tool: \`${input.tool.name}\``, `Risk: \`${input.tool.risk}\``, "", "Arguments reviewed for execution:", "", "```json", input.argumentsSummary.summary, "```", ].join("\n"); // Prosumer-facing card preview (M5/M7/M9). Respect an already-set custom preview // (e.g. OpenClaw-supplied), otherwise emit plain language with no technical vocab. const previewMarkdown = actionRequest.previewMarkdown?.trim() || buildHumanizedActionPreview({ tool: input.tool, argumentsSummary: input.argumentsSummary, }); let formalApprovalId: string | null = null; if (toolRequiresFormalApproval(input.tool)) { const [approval] = await writeApprovalChange(db, input.session.companyId, tx => tx .insert(approvals) .values({ companyId: input.session.companyId, type: "request_board_approval", requestedByAgentId: input.session.originatingAgentId ?? input.session.agentId, payload: { title: `Approve high-risk tool action: ${input.tool.name}`, summary: `${input.tool.name} is classified as ${input.tool.risk} and requires formal board approval before execution.`, recommendedAction: "Approve only if the reviewed arguments match the intended operation.", risks: [ "The tool may perform irreversible or externally visible side effects.", "Execution will use the stored reviewed arguments exactly once.", ], source: "tool_gateway", invocationId: input.invocation.id, actionRequestId: actionRequest.id, tool: input.tool.name, risk: input.tool.risk, argumentsHash: canonicalArgumentsHash, }, }) .returning()); formalApprovalId = approval.id; const approvalIssueId = input.session.issueId; await writeApprovalChange(db, input.session.companyId, tx => tx .insert(issueApprovals) .values({ companyId: input.session.companyId, issueId: approvalIssueId, approvalId: approval.id, linkedByAgentId: input.session.agentId, }) .onConflictDoNothing(), { issueIds: [approvalIssueId] }); } const interaction = await interactions.create( { id: input.session.issueId, companyId: input.session.companyId }, { kind: "request_confirmation", idempotencyKey: `tool-action:${actionRequest.id}`, title: "Approve tool action", resolverPolicy: "human_only", sourceRunId: input.session.runId ?? undefined, summary: "This action needs your approval before it runs.", continuationPolicy: "wake_assignee", payload: { version: 1, prompt: `Approve ${input.tool.displayName?.trim() || input.tool.name}?`, acceptLabel: "Approve action", rejectLabel: "Reject action", rejectRequiresReason: false, allowDeclineReason: true, supersedeOnUserComment: false, detailsMarkdown, target: { type: "custom", key: `tool-action:${actionRequest.id}`, revisionId: canonicalArgumentsHash, label: input.tool.name, }, toolAction: { version: 1, actionRequestId: actionRequest.id, invocationId: input.invocation.id, toolName: input.tool.name, toolDisplayName: input.tool.displayName?.trim() || input.tool.name, connectionId: input.tool.connectionId ?? null, applicationId: input.tool.applicationId ?? null, appDisplayName: input.tool.applicationDisplayName?.trim() || null, risk: input.tool.risk === "read" ? "read" : input.tool.risk === "destructive" ? "destructive" : "write", ...(!formalApprovalId && input.session.agentId && input.tool.connectionId ? { rememberActionScope: `This agent may use this action with different arguments on this connection${input.session.projectId ? " within this project" : ""}.`, } : {}), previewMarkdown, argumentsSummaryJson: input.argumentsSummary.summary, argumentsHash: canonicalArgumentsHash, expiresAt: expiresAt?.toISOString() ?? null, }, }, }, { agentId: input.session.agentId }, ); // Sign the row only while it is still pending. A concurrent matching call can // expire this row when the create runs longer than the abandon grace time. // Guard the update with the pending status so the sign step never resurrects // an expired row. When the guard matches no row, the row is already resolved. // Do not emit an approval card for a dead row; throw a retriable conflict so // the retry finds the live request or creates a fresh, signable one. const signedRows = await writeToolReviewChange(db, actionRequest.companyId, tx => tx .update(toolActionRequests) .set({ interactionId: interaction.id, canonicalArgumentsHash, canonicalArgumentsSummary: input.argumentsSummary, signedArguments, previewMarkdown, approvalId: formalApprovalId, expiresAt, updatedAt: new Date(), }) .where( and( eq(toolActionRequests.id, actionRequest.id), eq(toolActionRequests.status, "pending"), ), ) .returning({ id: toolActionRequests.id })); if (signedRows.length === 0) { await db .update(toolInvocations) .set({ status: "failed", approvalState: "expired", errorCode: "approval_request_superseded", errorMessage: "The approval request was resolved before it could be signed", completedAt: new Date(), updatedAt: new Date(), }) .where(eq(toolInvocations.id, input.invocation.id)); void emitConnectionInvoked(db, input.invocation.id); throw new ToolGatewayHttpError( 409, "The approval request was resolved before it could be signed", "approval_request_superseded", { invocationId: input.invocation.id, actionRequestId: actionRequest.id, tool: input.tool.name, instructions: "A parallel call already handled this approval. Retry the same call now to reach the live approval request.", }, ); } await db.transaction(async tx => { await notifyDeliveryWork(tx, DELIVERY_QUEUES.toolAction); await tx .insert(toolActionDeliveries) .values({ companyId: input.session.companyId, actionRequestId: actionRequest.id, issueId: input.session.issueId!, interactionId: interaction.id, }) .onConflictDoNothing(); }); await writeToolCallEvent({ invocationId: input.invocation.id, actionRequestId: actionRequest.id, session: input.session, eventType: "approval_requested", outcome: "pending", toolName: input.tool.name, policyDecision: "require_approval", reasonCode: "requires_approval_policy", argumentsSummary: input.argumentsSummary, metadata: { actionRequestId: actionRequest.id, interactionId: interaction.id, approvalId: formalApprovalId, }, tool: input.tool, }); await writeAudit({ session: input.session, companyId: input.session.companyId, agentId: input.session.agentId, runId: input.session.runId, issueId: input.session.issueId, action: "tool_gateway.approval_requested", details: { invocationId: input.invocation.id, actionRequestId: actionRequest.id, interactionId: interaction.id, approvalId: formalApprovalId, decision: "require_approval", reasonCode: "requires_approval_policy", matchedPolicyIds: input.policyDecision.matchedPolicyIds, tool: input.tool.name, ...toolAuditMetadata(input.tool), argumentsSummary: input.argumentsSummary, }, }); return throwApprovalRequired({ invocationId: input.invocation.id, actionRequestId: actionRequest.id, interactionId: interaction.id, issueId: input.session.issueId, toolName: input.tool.name, argumentsHash: canonicalArgumentsHash, }); } function policyInputForTool(input: { session: ToolGatewaySession; tool: ToolGatewayDescriptor; parameters?: unknown; idempotencyKey?: string | null; consumeRateLimit?: boolean; }): ToolAccessDecisionInput { return policyInputForAgentTool({ companyId: input.session.companyId, agentId: input.session.agentId, actorType: input.session.actorType, actorId: input.session.actorId ?? input.session.gatewayTokenId ?? null, tool: input.tool, parameters: input.parameters, idempotencyKey: input.idempotencyKey, consumeRateLimit: input.consumeRateLimit, heartbeatRunId: input.session.runId, originatingAgentId: input.session.originatingAgentId, gatewayTokenId: input.session.gatewayTokenId, issueId: input.session.issueId, projectId: input.session.projectId, gatewayId: input.session.gatewayId ?? null, }); } function policyInputForAgentTool(input: { companyId: string; agentId: string | null; actorType?: "agent" | "user" | "system" | "plugin"; actorId?: string | null; tool: ToolGatewayDescriptor; parameters?: unknown; idempotencyKey?: string | null; consumeRateLimit?: boolean; heartbeatRunId?: string | null; originatingAgentId?: string | null; gatewayTokenId?: string | null; issueId?: string | null; projectId?: string | null; gatewayId?: string | null; }): ToolAccessDecisionInput { const actorType = input.actorType ?? (input.agentId ? "agent" : "system"); const actorId = input.actorId ?? input.agentId ?? input.gatewayId ?? input.companyId; return { companyId: input.companyId, actor: { actorType, actorId, agentId: input.agentId, }, runContext: { heartbeatRunId: input.heartbeatRunId ?? null, originatingAgentId: input.originatingAgentId ?? null, issueId: input.issueId ?? null, projectId: input.projectId ?? null, gatewayId: input.gatewayId ?? null, gatewayTokenId: input.gatewayTokenId ?? null, }, request: { toolName: input.tool.name, applicationId: input.tool.applicationId ?? null, applicationKey: input.tool.applicationKey ?? null, connectionId: input.tool.connectionId ?? null, catalogEntryId: input.tool.catalogEntryId ?? null, providerType: input.tool.providerType, upstreamToolName: input.tool.upstreamToolName ?? input.tool.name, riskLevel: input.tool.risk, arguments: input.parameters ?? {}, idempotencyKey: input.idempotencyKey ?? null, sideEffecting: input.tool.risk !== "read", }, consumeRateLimit: input.consumeRateLimit === true, }; } /** * Decides access for each tool of one listing. All decisions of the listing * share one actor and run context, so they share one read cache: a listing * reads the agent, run, profiles and policies once, not once per tool. */ async function decideToolsForListing( tools: readonly T[], inputForTool: (tool: T) => ToolAccessDecisionInput, cache: ToolAccessDecisionCache = createToolAccessDecisionCache(), signal?: AbortSignal, ): Promise> { return mapWithConcurrency(tools, LISTING_DECISION_CONCURRENCY, async (tool) => ({ tool, decision: await policyService.decide(inputForTool(tool), { cache }), }), signal); } function policyErrorStatus(decision: ToolAccessDecision) { if (decision.decision === "rate_limited") return 429; return 403; } function findStaticTool(toolName: string): ToolGatewayDescriptor { const tool = allTools().find((candidate) => candidate.name === toolName); if (!tool) { throw new ToolGatewayHttpError( 404, `Tool "${toolName}" not found`, "tool_not_found", { tool: toolName }, ); } return tool; } async function findToolForSession( session: ToolGatewaySession, toolName: string, ): Promise { const connectedTools = (await connectedMcpToolsForCompany(session.companyId)).filter(isModelVisibleTool); const hasOnDemandTargets = connectedTools.some(isOnDemandRemoteTool); const virtualTools = hasOnDemandTargets ? VIRTUAL_TOOLS : []; const githubBotTools = await githubBotToolsForSession(db, session); const tool = [...allTools(), ...connectedTools, ...virtualTools, ...githubBotTools, ...await slackToolsForSession(db, session), ...await spekoToolsForSession(db, session)] .filter( (candidate) => session.agentId || (candidate.providerType !== "paperclip_self" && candidate.providerType !== "paperclip_plugin"), ) .find((candidate) => candidate.name === toolName); if (!tool) { throw new ToolGatewayHttpError( 404, `Tool "${toolName}" not found`, "tool_not_found", { tool: toolName }, ); } const guestBotConnection = await githubGuestBotConnectionForSession(db, session); if (guestBotConnection && tool.connectionId && (tool.connectionId !== guestBotConnection || tool.providerType !== "paperclip_github_chat")) throw new ToolGatewayHttpError(403, "Sponsored GitHub runs can only use their bot's governed connection; sponsorship does not grant personal credentials", "guest_connection_denied"); if (session.identityContextId && session.agentId && tool.connectionId) { const [connection] = await db .select() .from(toolConnections) .where( and( eq(toolConnections.id, tool.connectionId), eq(toolConnections.companyId, session.companyId), ), ); if ( connection?.config.sourceTemplateKey === "github" || connection?.transportConfig?.sourceTemplateKey === "github" ) { let selected = await resolveManagedGitHubIdentitySelection( db, session.companyId, { agentId: session.agentId, responsibleUserId: session.responsibleUserId, allowStandingDelegation: false, }, ); if (!selected.grant) throw new ToolGatewayHttpError( 409, selected.error ?? "No GitHub identity connected", "github_identity_unavailable", ); const original = selected.grant; // Acquire before policy evaluation or dispatch. An alternate connection // gets its own catalog descriptor and policy checks; never replay a call. for (let attempt = 0; attempt < 2; attempt += 1) { const grant = selected.grant!; const target = connectedTools.find( (candidate) => candidate.connectionId === grant.connectionId && candidate.upstreamToolName === tool.upstreamToolName && candidate.providerType === tool.providerType, ); if (!target) throw new ToolGatewayHttpError( 404, "This GitHub tool is unavailable for the responsible person", "github_tool_unavailable", ); const [selectedConnection] = await db .select() .from(toolConnections) .where( and( eq(toolConnections.id, grant.connectionId), eq(toolConnections.companyId, session.companyId), ), ); if (!selectedConnection) throw new ToolGatewayHttpError( 409, "GitHub connection is unavailable", "github_identity_unavailable", ); if (attempt === 0) await resolveConnectionGrant(session, selectedConnection); try { const headers = await resolveCredentialHeaders( session, selectedConnection, grant, ); githubOperationCredentials.set(session, { grant, headers }); return target; } catch (error) { if (attempt !== 0) throw error; const alternate = await resolveManagedGitHubIdentitySelection( db, session.companyId, { agentId: session.agentId, responsibleUserId: session.responsibleUserId, allowStandingDelegation: false, excludeGrantId: original.id, }, ); const accountId = original.providerTenant?.github?.userId; if ( !accountId || !alternate.grant || alternate.grant.providerTenant?.github?.userId !== accountId || alternate.grant.subjectUserId !== original.subjectUserId || alternate.grant.subjectAgentId !== original.subjectAgentId ) throw error; selected = alternate; } } throw new ToolGatewayHttpError( 409, "GitHub credentials are unavailable", "github_identity_unavailable", ); } } return tool; } function virtualRunToolInput(parameters: unknown): { targetToolName: string; targetParameters: unknown; } { const params = asRecord(parameters) ?? {}; const targetToolName = typeof params.tool === "string" ? params.tool.trim() : ""; if (!targetToolName) { throw new ToolGatewayHttpError( 400, "run_tool requires a target tool name", "invalid_parameters", ); } return { targetToolName, targetParameters: params.arguments ?? {}, }; } async function searchableOnDemandTools( session: ToolGatewaySession, ): Promise { const tools = (await connectionToolsForContext(session)).filter( isOnDemandRemoteTool, ); const decisions = await decideToolsForListing(tools, (tool) => policyInputForTool({ session, tool }), ); return decisions .filter( ({ decision }) => decision.allowed || decision.decision === "require_approval", ) .map(({ tool }) => tool); } async function executeVirtualSearchTools( session: ToolGatewaySession, parameters: unknown, ) { const params = asRecord(parameters) ?? {}; const query = typeof params.query === "string" ? params.query.trim().toLowerCase() : ""; const limit = Math.max(1, Math.min(50, Number(params.limit ?? 10) || 10)); const tools = (await searchableOnDemandTools(session)) .filter((tool) => { if (!query) return true; return [ tool.name, tool.displayName, tool.description, tool.applicationKey, tool.upstreamToolName, ] .filter((value): value is string => typeof value === "string") .some((value) => value.toLowerCase().includes(query)); }) .slice(0, limit) .map((tool) => ({ name: tool.name, displayName: tool.displayName ?? tool.name, description: tool.description ?? null, parametersSchema: tool.parametersSchema, applicationId: tool.applicationId ?? null, connectionId: tool.connectionId ?? null, catalogEntryId: tool.catalogEntryId ?? null, upstreamToolName: tool.upstreamToolName ?? tool.name, risk: tool.risk, })); return { content: JSON.stringify({ tools }), data: { tools }, }; } async function listToolsForContext( session: ToolGatewaySession, signal?: AbortSignal, ): Promise { try { return await measureToolDiscovery(work => toolDiscoveryScheduler.run(work, signal), () => buildToolsForContext(session, signal)); } catch (error) { if (error instanceof ToolDiscoveryBusyError) { throw new ToolGatewayHttpError(503, error.message, "tool_discovery_busy"); } throw error; } } /** Shared connection descriptors and task restrictions; no provider calls. */ async function connectionToolsForContext(session: ToolGatewaySession): Promise { const guestBotConnection = await measureRunPhase("connectors.discovery.github", () => githubGuestBotConnectionForSession(db, session)); let connectedTools = (await measureRunPhase("connectors.discovery.connections", () => connectedMcpToolsForCompany(session.companyId))) .filter(isModelVisibleTool) .filter(tool => !guestBotConnection || !tool.connectionId || (tool.connectionId === guestBotConnection && tool.providerType === "paperclip_github_chat")); const connectionIds = [...new Set(connectedTools.flatMap((tool) => tool.connectionId ? [tool.connectionId] : []))]; if (connectionIds.length) { const connections = await db.select().from(toolConnections).where(and( eq(toolConnections.companyId, session.companyId), inArray(toolConnections.id, connectionIds), )); for (const connection of connections.filter((item) => item.config.sourceTemplateKey === "google-workspace")) { let scopes: string[] = []; try { scopes = googleWorkspaceGrantedScopes(await resolveConnectionGrant(session, connection, false)); } catch { /* Missing identity or consent never contributes tools. */ } connectedTools = connectedTools.filter((tool) => tool.connectionId !== connection.id || isGoogleWorkspaceToolGranted(tool.upstreamToolName ?? "", scopes)); } } return [ ...await measureRunPhase("connectors.discovery.github", () => githubBotToolsForSession(db, session)), ...await measureRunPhase("connectors.discovery.slack", () => slackToolsForSession(db, session)), ...await measureRunPhase("connectors.discovery.speko", () => spekoToolsForSession(db, session)), ...connectedTools, ]; } async function buildToolsForContext( session: ToolGatewaySession, signal?: AbortSignal, ): Promise { signal?.throwIfAborted(); if (session.agentId) { await measureRunPhase("connectors.discovery.agent", () => assertAgentInCompany(session.companyId, session.agentId!)); } const connectionTools = await connectionToolsForContext(session); const onDemandTargets = connectionTools.filter(isOnDemandRemoteTool); const tools = [ ...allTools(), ...connectionTools.filter((tool) => !isOnDemandRemoteTool(tool)), ].filter( (tool) => session.agentId || (tool.providerType !== "paperclip_self" && tool.providerType !== "paperclip_plugin"), ); const decisionCache = createToolAccessDecisionCache(); const decisions = await measureRunPhase("connectors.discovery.policy", () => decideToolsForListing( tools, (tool) => policyInputForTool({ session, tool }), decisionCache, signal, )); const visibleTools = decisions .filter( ({ decision }) => decision.allowed || decision.decision === "require_approval", ) .map(({ tool, decision }) => decision.decision === "require_approval" ? { ...tool, description: [ tool.description?.trim(), TOOL_APPROVAL_DESCRIPTION_SUFFIX, ] .filter(Boolean) .join(" "), } : tool, ); if (onDemandTargets.length > 0) { const targetDecisions = await measureRunPhase("connectors.discovery.on_demand_policy", () => decideToolsForListing( onDemandTargets, (tool) => policyInputForTool({ session, tool }), decisionCache, signal, )); if ( targetDecisions.some( ({ decision }) => decision.allowed || decision.decision === "require_approval", ) ) { visibleTools.push(...VIRTUAL_TOOLS); } } return deduplicateToolDescriptors(visibleTools); } async function executeBuiltinTool( session: ToolGatewaySession, tool: ToolGatewayDescriptor, parameters: unknown, invocationId?: string, ) { const params = asRecord(parameters) ?? {}; if (tool.providerType === "paperclip_speko_voice") { try { const data = await executeSpekoVoiceTool(db, session, String(asRecord(tool.providerMetadata)?.endpointId ?? ""), parameters, invocationId); return { content: JSON.stringify(data), data }; } catch (error) { if (error instanceof HttpError) throw new ToolGatewayHttpError(error.status, error.message, "speko_operation_rejected", asRecord(error.details) ?? {}); throw error; } } if (tool.providerType === "paperclip_slack_chat") { if (!session.agentId || !session.runId || !session.issueId) throw new ToolGatewayHttpError(403, "Slack task binding required", "slack_task_required"); try { const data = await executeSlackTool(db, { companyId: session.companyId, agentId: session.agentId, runId: session.runId, issueId: session.issueId, endpointId: String(asRecord(tool.providerMetadata)?.endpointId ?? ""), identityContextId: session.identityContextId, approvedInvocationId: session.approvedSlackInvocationId }, tool.upstreamToolName ?? "", parameters, fetch, invocationId); return { content: JSON.stringify(data), data }; } catch (error) { if (error instanceof HttpError) { const details = asRecord(error.details) ?? {}; throw new ToolGatewayHttpError(error.status, error.message, typeof details.code === "string" ? details.code : "slack_operation_rejected", details); } throw error; } } if (tool.providerType === "paperclip_github_chat") { try { const data = await githubChatReviewService(db).execute(session, tool.upstreamToolName ?? "", parameters, invocationId); return { content: JSON.stringify(data), data }; } catch (error) { // Complete request identities can reach the publication owner through // fresh execution instead of receipt replay. Preserve the same conflict // category for changed content without reclassifying stale-head or // assessment-coverage conflicts from that owner. if (error instanceof HttpError && error.status === 409 && asRecord(error.details)?.reasonCode === "github_idempotency_conflict") { throw new ToolGatewayHttpError(error.status, error.message, "github_idempotency_conflict", asRecord(error.details) ?? {}); } throw error; } } if (tool.name === "mcp-remote-fixture:echo") { return { content: String(params.message ?? ""), data: { transport: "mcp_http", spawnedLocalProcess: false, }, }; } if (tool.name === "mcp-remote-fixture:add") { const a = Number(params.a); const b = Number(params.b); if (!Number.isFinite(a) || !Number.isFinite(b)) { throw new ToolGatewayHttpError( 400, "Parameters a and b must be finite numbers", "invalid_parameters", ); } return { content: String(a + b), data: { result: a + b, transport: "mcp_http", spawnedLocalProcess: false, }, }; } if (tool.name === "mcp-remote-fixture:update_note") { const noteId = typeof params.noteId === "string" ? params.noteId.trim() : ""; const body = typeof params.body === "string" ? params.body : ""; if (!noteId || !body) { throw new ToolGatewayHttpError( 400, "Parameters noteId and body are required", "invalid_parameters", ); } return { content: JSON.stringify({ noteId, updated: true }), data: { noteId, bodyLength: body.length, transport: "mcp_http", spawnedLocalProcess: false, }, }; } if (tool.name === "paperclip-self:list_my_issues") { if (!session.agentId) { throw new ToolGatewayHttpError( 403, "Paperclip self tools require an agent-scoped gateway session", "agent_context_required", ); } const limit = Math.max(1, Math.min(50, Number(params.limit ?? 10) || 10)); const rows = await db .select({ id: issues.id, identifier: issues.identifier, title: issues.title, status: issues.status, priority: issues.priority, }) .from(issues) .where( and( eq(issues.companyId, session.companyId), eq(issues.assigneeAgentId, session.agentId), ), ) .orderBy(desc(issues.updatedAt)) .limit(limit); return { content: JSON.stringify(rows), data: { issues: rows }, }; } if (tool.name === "paperclip-self:get_issue_context") { if (!session.agentId) { throw new ToolGatewayHttpError( 403, "Paperclip self tools require an agent-scoped gateway session", "agent_context_required", ); } const issueId = typeof params.issueId === "string" ? params.issueId : session.issueId; if (!issueId) { throw new ToolGatewayHttpError( 400, "issueId is required when the session is not issue-scoped", "missing_issue_id", ); } const [issue] = await db .select({ id: issues.id, identifier: issues.identifier, title: issues.title, description: issues.description, status: issues.status, priority: issues.priority, }) .from(issues) .where( and(eq(issues.companyId, session.companyId), eq(issues.id, issueId)), ) .limit(1); if (!issue) { throw new ToolGatewayHttpError( 404, "Issue not found", "issue_not_found", ); } const [planDocument] = await db .select({ documentId: documents.id, title: documents.title, latestRevisionId: documents.latestRevisionId, latestRevisionNumber: documents.latestRevisionNumber, }) .from(issueDocuments) .innerJoin(documents, eq(issueDocuments.documentId, documents.id)) .where( and( eq(issueDocuments.issueId, issue.id), eq(issueDocuments.key, "plan"), ), ) .limit(1); return { content: JSON.stringify({ issue, planDocument: planDocument ?? null }), data: { issue, planDocument: planDocument ?? null }, }; } if (tool.providerType === "mcp_stdio_fixture") { return runtimeSupervisor.useFixtureSlot( { companyId: session.companyId, connectionKey: `${session.companyId}:mcp-stdio-fixture:default`, runId: session.runId, issueId: session.issueId, agentId: session.agentId, }, async (handle) => { const priorUseCount = Number(handle.metadata.useCount ?? 0) || 0; let counter = Number(handle.metadata.counter ?? 0) || 0; if (tool.name === "mcp-stdio-fixture:increment_counter") { counter += 1; handle.metadata.counter = counter; handle.appendLog("stdout", `increment_counter counter=${counter}`); } else { handle.appendLog("stdout", `runtime_status counter=${counter}`); } const nextUseCount = priorUseCount + 1; return { content: JSON.stringify({ slotId: handle.slot.id, status: handle.slot.status, counter, useCount: nextUseCount, }), data: { slotId: handle.slot.id, status: handle.slot.status, counter, useCount: nextUseCount, lazyStarted: priorUseCount === 0, reusedRuntimeSlot: priorUseCount > 0, }, }; }, ); } throw new ToolGatewayHttpError( 404, `Tool "${tool.name}" not found`, "tool_not_found", ); } function remoteEndpoint(config: Record): string { const value = config.url ?? config.endpoint ?? config.remoteUrl; const parsed = parseRemoteHttpEndpoint( value, (message, code) => new ToolGatewayHttpError(422, message, code), ); return parsed.toString(); } async function resolvedRemoteEndpoint( session: ToolGatewaySession, connection: typeof toolConnections.$inferSelect, grant: typeof connectionGrants.$inferSelect, ): Promise { const publicEndpoint = remoteEndpoint(connection.config ?? {}); const ref = (connection.credentialRefs ?? []).find( (candidate) => candidate.placement === "url", ); if (!ref) return publicEndpoint; const grantRef = grantRefForCredential(grant, ref); if (!grantRef) { throw new ToolGatewayHttpError( 422, "A configured credential secret could not be resolved.", "mcp_remote_missing_secret", { connectionId: connection.id, credential: REMOTE_URL_SECRET_CONFIG_PATH, }, ); } const value = await resolveGrantSecretValue( session, connection, grant, grantRef, ); if (!remoteUrlCredentialMatchesPublicUrl(publicEndpoint, value)) { throw new ToolGatewayHttpError( 422, "The stored MCP URL credential no longer matches this connection.", "mcp_remote_url_credential_mismatch", { connectionId: connection.id }, ); } return parseRemoteHttpEndpoint( value, (message, code) => new ToolGatewayHttpError(422, message, code), ).toString(); } function allowPrivateRemoteEndpoints() { return ( options.deploymentMode !== "authenticated" || options.deploymentExposure !== "public" ); } /** * Guard options for every outbound call to an operator-supplied MCP endpoint. * * The private-network check no longer runs as a standalone pre-flight: it is * part of `guardedRemoteHttpFetch`, which keeps the approved address and dials * it directly. Splitting validation from dispatch is what created the * DNS-rebinding TOCTOU in PAP-17098. */ function remoteHttpFetchOptions(): GuardedRemoteHttpFetchOptions { return { allowPrivateNetwork: allowPrivateRemoteEndpoints(), error: (message, code) => new ToolGatewayHttpError(422, message, code), }; } function headerName(value: unknown): string | null { if (typeof value !== "string") return null; const trimmed = value.trim(); if (!/^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/.test(trimmed)) return null; return trimmed.toLowerCase(); } function headerValue(value: unknown): string | null { if (typeof value !== "string") return null; if (/[\r\n]/.test(value)) return null; return value; } function stringArray(value: unknown): string[] { if (!Array.isArray(value)) return []; return value.filter((entry): entry is string => typeof entry === "string"); } function readHeaderPolicy( connection: typeof toolConnections.$inferSelect, ): HeaderPolicyConfig { const config = asRecord(connection.config) ?? {}; const transportConfig = asRecord(connection.transportConfig) ?? {}; const rawPolicy = asRecord(config.headerPolicy) ?? asRecord(transportConfig.headerPolicy) ?? {}; const passthrough = asRecord(rawPolicy.passthrough) ?? {}; const staticHeaders = rawPolicy.staticHeaders; const parsedStaticHeaders: Array<{ name: string; value: string }> = []; if (Array.isArray(staticHeaders)) { for (const entry of staticHeaders) { const record = asRecord(entry); const name = headerName(record?.name); const value = headerValue(record?.value); if (name && value !== null) parsedStaticHeaders.push({ name, value }); } } else { const record = asRecord(staticHeaders); if (record) { for (const [rawName, rawValue] of Object.entries(record)) { const name = headerName(rawName); const value = headerValue(rawValue); if (name && value !== null) parsedStaticHeaders.push({ name, value }); } } } const passthroughAllowlist = [ ...stringArray(passthrough.allow), ...stringArray(passthrough.allowedHeaders), ...stringArray(rawPolicy.allowedPassthroughHeaders), ] .map(headerName) .filter((name): name is string => Boolean(name)) .filter((name) => !isSensitivePassthroughHeader(name)); const metadata = asRecord(rawPolicy.metadata) ?? {}; const metadataHeaders = [ ...stringArray(metadata.forward), ...stringArray(metadata.headers), ...stringArray(rawPolicy.forwardContextHeaders), ].filter( (value): value is HeaderPolicyConfig["metadataHeaders"][number] => value === "company_id" || value === "agent_id" || value === "issue_id" || value === "project_id" || value === "run_id" || value === "gateway_session_id" || value === "correlation_id", ); return { staticHeaders: parsedStaticHeaders, passthroughAllowlist: [...new Set(passthroughAllowlist)], metadataHeaders: [...new Set(metadataHeaders)], }; } function readOnDemandToolsEnabled( connectionOrConfig: typeof toolConnections.$inferSelect | Record, ): boolean { const config = "config" in connectionOrConfig ? (asRecord(connectionOrConfig.config) ?? {}) : connectionOrConfig; const raw = asRecord(config.onDemandTools) ?? asRecord(config.loadToolsOnDemand); return ( config.onDemandTools === true || config.loadToolsOnDemand === true || raw?.enabled === true ); } function isOnDemandRemoteTool(tool: ToolGatewayDescriptor): boolean { const metadata = asRecord(tool.providerMetadata); return ( tool.providerType === "mcp_remote_http" && metadata?.onDemandTools === true ); } function normalizeCallerHeaders( input: ExecuteGatewayToolInput["callerHeaders"], ): Record { const headers: Record = {}; for (const [rawName, rawValue] of Object.entries(input ?? {})) { const name = headerName(rawName); if (!name) continue; const value = Array.isArray(rawValue) ? rawValue.join(", ") : rawValue; const normalizedValue = headerValue(value); if (normalizedValue !== null) headers[name] = normalizedValue; } return headers; } function metadataHeadersForSession( session: ToolGatewaySession, policy: HeaderPolicyConfig, ): Record { const headers: Record = {}; const values: Record< HeaderPolicyConfig["metadataHeaders"][number], string | null > = { company_id: session.companyId, agent_id: session.agentId, issue_id: session.issueId, project_id: session.projectId, run_id: session.runId, gateway_session_id: session.id, correlation_id: randomUUID(), }; for (const key of policy.metadataHeaders) { const value = values[key]; if (value) headers[`x-paperclip-${key.replace(/_/g, "-")}`] = value; } return headers; } function buildRemoteHeaders(input: { session: ToolGatewaySession; connection: typeof toolConnections.$inferSelect; credentialHeaders: Record; callerHeaders?: ExecuteGatewayToolInput["callerHeaders"]; }): { headers: Record; summary: HeaderPolicySummary } { const policy = readHeaderPolicy(input.connection); const caller = normalizeCallerHeaders(input.callerHeaders); const credentialHeaders: Record = {}; for (const [name, value] of Object.entries(input.credentialHeaders)) { const normalized = headerName(name); if (normalized) credentialHeaders[normalized] = value; } const reservedHeaders = new Set([ "accept", "content-type", "content-length", "host", "connection", ]); const managedCredentialHeaders = new Set(Object.keys(credentialHeaders)); const headers: Record = {}; const summary: HeaderPolicySummary = { staticHeaderNames: [], credentialHeaderNames: Object.keys(credentialHeaders).sort(), passthroughHeaderNames: [], droppedPassthroughHeaderNames: [], metadataHeaderNames: [], collisionRules: [], }; for (const [name, value] of Object.entries(caller)) { if (reservedHeaders.has(name)) { summary.droppedPassthroughHeaderNames.push(name); summary.collisionRules.push({ header: name, source: "caller", action: "dropped_reserved_header", }); continue; } if (managedCredentialHeaders.has(name)) { summary.droppedPassthroughHeaderNames.push(name); summary.collisionRules.push({ header: name, source: "caller", action: "kept_managed_credential", }); continue; } if (isSensitivePassthroughHeader(name)) { summary.droppedPassthroughHeaderNames.push(name); summary.collisionRules.push({ header: name, source: "caller", action: "dropped_sensitive_header", }); continue; } if (!policy.passthroughAllowlist.includes(name)) { summary.droppedPassthroughHeaderNames.push(name); continue; } headers[name] = value; summary.passthroughHeaderNames.push(name); } for (const { name, value } of policy.staticHeaders) { if (reservedHeaders.has(name)) { summary.collisionRules.push({ header: name, source: "static", action: "dropped_reserved_header", }); continue; } if (managedCredentialHeaders.has(name)) { summary.collisionRules.push({ header: name, source: "static", action: "kept_managed_credential", }); continue; } if (headers[name] !== undefined) { summary.collisionRules.push({ header: name, source: "static", action: "overrode_passthrough", }); } headers[name] = value; summary.staticHeaderNames.push(name); } const metadataHeaders = metadataHeadersForSession(input.session, policy); for (const [name, value] of Object.entries(metadataHeaders)) { if (reservedHeaders.has(name)) continue; if (managedCredentialHeaders.has(name)) { summary.collisionRules.push({ header: name, source: "metadata", action: "kept_managed_credential", }); continue; } if (headers[name] !== undefined) { summary.collisionRules.push({ header: name, source: "metadata", action: "overrode_previous_header", }); } headers[name] = value; summary.metadataHeaderNames.push(name); } for (const [name, value] of Object.entries(credentialHeaders)) { if (headers[name] !== undefined) { summary.collisionRules.push({ header: name, source: "credential", action: "overrode_previous_header", }); } headers[name] = value; } summary.staticHeaderNames.sort(); summary.passthroughHeaderNames.sort(); summary.droppedPassthroughHeaderNames = [ ...new Set(summary.droppedPassthroughHeaderNames), ].sort(); summary.metadataHeaderNames.sort(); return { headers, summary }; } async function markRemoteConnectionHealth( connection: typeof toolConnections.$inferSelect, status: "ok" | "error" | "missing_secret" | "degraded", message: string | null, ) { const now = new Date(); await writeToolConnectionHealthChange(db, connection, tx => tx .update(toolConnections) .set({ healthStatus: status, healthMessage: message, healthCheckedAt: now, lastHealthAt: now, lastError: status === "ok" ? null : message, updatedAt: now, }) .where(eq(toolConnections.id, connection.id))); } function grantRefForCredential( grant: typeof connectionGrants.$inferSelect, ref: McpConnectionCredentialRef, ): ToolCredentialSecretRef | undefined { return connectionGrantCredentialRef(grant, ref); } async function resolveGrantSecretValue( session: ToolGatewaySession, connection: typeof toolConnections.$inferSelect, grant: typeof connectionGrants.$inferSelect, ref: ToolCredentialSecretRef, ): Promise { try { return (await resolveConnectionGrantSecret(db, connection, grant, ref, { consumerType: "tool_connection", consumerId: connection.id, actorType: "system", actorId: session.originatingAgentId ?? session.agentId, responsibleUserId: grant.subjectUserId, issueId: session.issueId, heartbeatRunId: session.runId, })).value; } catch (error) { if (error instanceof HttpError) throw new ToolGatewayHttpError(error.status, error.message, String(asRecord(error.details)?.code ?? "mcp_remote_missing_secret"), asRecord(error.details) ?? {}); throw error; } } async function maybeRefreshPaperclipCloudGrant( session: ToolGatewaySession, connection: typeof toolConnections.$inferSelect, grant: typeof connectionGrants.$inferSelect, forceRefresh = false, ): Promise { const oauth = asRecord(asRecord(connection.config)?.oauth); if (!oauth || !isPaperclipCloudConnectorStrategy(oauth.strategy)) return grant; const configuredProfile = oauth.connectorProfile; const connectorProfile: GoogleWorkspaceConnectorProfileId | GitHubConnectorProfileId = configuredProfile === undefined ? "gmail.draft" : typeof configuredProfile === "string" && (isGoogleWorkspaceConnectorProfileId(configuredProfile) || isGitHubConnectorProfileId(configuredProfile)) ? configuredProfile : (() => { throw new ToolGatewayHttpError( 422, "Managed authorization has an invalid connector profile", "connector_profile_invalid", { connectionId: connection.id, grantId: grant.id, }, ); })(); const connectorSubject = typeof oauth.connectorSubjectAgentId === "string" ? `agent:${oauth.connectorSubjectAgentId}` : typeof oauth.connectorSubjectUserId === "string" ? oauth.connectorSubjectUserId : grant.kind === "agent" && grant.subjectAgentId ? `agent:${grant.subjectAgentId}` : grant.subjectUserId; const grantOauth = asRecord(asRecord(grant.providerTenant)?.oauth); const expiresAt = typeof grantOauth?.accessTokenExpiresAt === "string" ? Date.parse(grantOauth.accessTokenExpiresAt) : Number.NaN; const currentTime = options.now?.() ?? Date.now(); // The preferred GitHub App policy yields a non-expiring ghu_ token and no // refresh token. Absence of an expiry is deliberate, not an invitation to // enter the rotation path. if ( grantOauth?.accessTokenExpiresAt === null || grantOauth?.accessTokenExpiresAt === undefined ) return grant; const refreshedAt = typeof grantOauth.refreshedAt === "string" ? Date.parse(grantOauth.refreshedAt) : Number.NaN; const rotationDue = !Number.isFinite(refreshedAt) || refreshedAt <= currentTime - 30 * 24 * 60 * 60_000; if ( !forceRefresh && Number.isFinite(expiresAt) && expiresAt > currentTime + 60 * 60_000 && !rotationDue ) return grant; if (oauth.strategy === "paperclip_id_connector") { // Paperclip ID used different endpoints, signing metadata, envelope // purposes, and a different Google client. Its refresh token cannot be // exchanged through Paperclip Cloud. Let an unexpired access token finish // its useful life, then require an explicit managed-connector enrollment // and provider reconnect instead of sending it to the wrong client. await db .update(connectionGrants) .set({ status: "needs_reauthorization", updatedAt: new Date(currentTime), }) .where(eq(connectionGrants.id, grant.id)); throw new ToolGatewayHttpError( 409, "Legacy authorization must be reconnected through Paperclip Cloud", "connector_reauthorization_required", { connectionId: connection.id, grantId: grant.id, }, ); } const existingFlight = gmailRefreshFlights.get(grant.id); if (existingFlight) return existingFlight; const refresh = (async () => { const cloudConnector = currentCloudConnector(); if (!cloudConnector || !connectorSubject) { await db .update(connectionGrants) .set({ status: "needs_reauthorization", updatedAt: new Date(currentTime), }) .where(eq(connectionGrants.id, grant.id)); throw new ToolGatewayHttpError( 409, "Managed authorization must be reconnected", "connector_reauthorization_required", { connectionId: connection.id, grantId: grant.id, }, ); } const accessRef = grant.credentialSecretRefs.find( (ref) => ref.configPath === "oauth.access_token", ); const refreshRef = grant.credentialSecretRefs.find( (ref) => ref.configPath === "oauth.refresh_token", ); if (!accessRef || !refreshRef) { await db .update(connectionGrants) .set({ status: "needs_reauthorization", updatedAt: new Date(currentTime), }) .where(eq(connectionGrants.id, grant.id)); throw new ToolGatewayHttpError( 409, "Managed authorization must be reconnected", "connector_reauthorization_required", { connectionId: connection.id, grantId: grant.id, }, ); } const refreshToken = await resolveGrantSecretValue( session, connection, grant, refreshRef, ); try { const credentials = await cloudConnector.refresh({ subject: connectorSubject, companyId: connection.companyId, profile: connectorProfile, refreshToken, }); await secrets.rotate(accessRef.secretId, { value: credentials.accessToken, }); if (credentials.refreshToken) { await secrets.rotate(refreshRef.secretId, { value: credentials.refreshToken, }); } const providerTenant = { ...(grant.providerTenant ?? {}), oauth: { ...(grant.providerTenant?.oauth ?? {}), strategy: "paperclip_cloud_connector", accessTokenExpiresAt: credentials.accessTokenExpiresAt, scopes: credentials.scopes, tokenType: credentials.tokenType, refreshedAt: new Date(options.now?.() ?? Date.now()).toISOString(), ...(credentials.refreshTokenExpiresAt ? { refreshTokenExpiresAt: credentials.refreshTokenExpiresAt } : {}), }, }; const [updated] = await db .update(connectionGrants) .set({ providerTenant, updatedAt: new Date(options.now?.() ?? Date.now()), }) .where( and( eq(connectionGrants.id, grant.id), eq(connectionGrants.status, "active"), ), ) .returning(); if (!updated) { throw new ToolGatewayHttpError( 409, "Managed authorization is no longer active", "connector_reauthorization_required", { connectionId: connection.id, grantId: grant.id, }, ); } return updated; } catch (error) { if (error instanceof ToolGatewayHttpError) throw error; if ( error instanceof PaperclipCloudConnectorError && error.code === "REAUTHORIZATION_REQUIRED" ) { await db .update(connectionGrants) .set({ status: "needs_reauthorization", updatedAt: new Date(options.now?.() ?? Date.now()), }) .where(eq(connectionGrants.id, grant.id)); throw new ToolGatewayHttpError( 409, "Managed authorization must be reconnected", "connector_reauthorization_required", { connectionId: connection.id, grantId: grant.id, }, ); } throw new ToolGatewayHttpError( 502, "Managed authorization could not be refreshed", "connector_refresh_failed", { connectionId: connection.id, grantId: grant.id, }, ); } })(); gmailRefreshFlights.set(grant.id, refresh); try { return await refresh; } finally { if (gmailRefreshFlights.get(grant.id) === refresh) gmailRefreshFlights.delete(grant.id); } } async function resolveCredentialHeaders( session: ToolGatewaySession, connection: typeof toolConnections.$inferSelect, grant: typeof connectionGrants.$inferSelect, resolveOptions: { forceRefresh?: boolean } = {}, ): Promise> { const tracked = session.identityContextId && (connection.config.sourceTemplateKey === "github" || connection.transportConfig?.sourceTemplateKey === "github"); try { const captured = githubOperationCredentials.get(session); const headers = !resolveOptions.forceRefresh && captured?.grant.id === grant.id ? captured.headers : await resolveCredentialHeadersUnrecorded( session, connection, grant, resolveOptions, ); if (tracked) await db .update(runIdentityContexts) .set({ github: { status: "available", login: grant.providerTenant?.github?.login, source: grant.kind === "agent" ? "dedicated" : "personal", connectionId: connection.id, grantId: grant.id, authenticationMode: "managed", }, }) .where( and( eq(runIdentityContexts.id, session.identityContextId!), eq(runIdentityContexts.companyId, session.companyId), ), ); return headers; } catch (error) { if (tracked) await db .update(runIdentityContexts) .set({ github: { status: "unavailable", reason: "GitHub authorization is unavailable", source: grant.kind === "agent" ? "dedicated" : "personal", }, }) .where( and( eq(runIdentityContexts.id, session.identityContextId!), eq(runIdentityContexts.companyId, session.companyId), ), ); throw error; } } async function resolveCredentialHeadersUnrecorded( session: ToolGatewaySession, connection: typeof toolConnections.$inferSelect, grant: typeof connectionGrants.$inferSelect, resolveOptions: { forceRefresh?: boolean } = {}, ): Promise> { if (connection.credentialSource === "vercel_connect") { if (!connection.externalCredential || !vercelConnect) { throw new ToolGatewayHttpError( 503, "Vercel Connect is not configured", "vercel_connect_unavailable", { connectionId: connection.id, grantId: grant.id, }, ); } const request = vercelTokenRequest({ credential: connection.externalCredential, grant, connectionId: connection.id, companyId: connection.companyId, }); try { const token = await vercelConnect.getToken(request, resolveOptions); if ( token.connector.id !== connection.externalCredential.connectorId && token.connector.uid !== connection.externalCredential.connectorUid ) { throw new VercelConnectClientError( "vercel_connect_request_failed", 502, ); } await db .update(connectionGrants) .set({ externalCredential: vercelGrantReference({ credential: connection.externalCredential, token, subjectId: grant.externalCredential?.subjectId, verifiedAt: new Date(options.now?.() ?? Date.now()), }), status: "active", revokedAt: null, updatedAt: new Date(options.now?.() ?? Date.now()), }) .where( and( eq(connectionGrants.id, grant.id), eq(connectionGrants.companyId, connection.companyId), eq(connectionGrants.connectionId, connection.id), ), ); return { [connection.externalCredential.headerName]: `${connection.externalCredential.headerPrefix ?? ""}${token.token}`, }; } catch (error) { if ( error instanceof VercelConnectClientError && error.code === "vercel_connect_authorization_required" ) { await db .update(connectionGrants) .set({ status: "needs_reauthorization", updatedAt: new Date(options.now?.() ?? Date.now()), }) .where( and( eq(connectionGrants.id, grant.id), eq(connectionGrants.companyId, connection.companyId), ), ); const responsibleUserId = grant.kind === "user" ? grant.subjectUserId : session.responsibleUserId; if (responsibleUserId) { await createUserAuthorizationInteraction( session, connection, responsibleUserId, grant.kind === "user" ? "user" : "organization", ); } } const code = error instanceof VercelConnectClientError ? error.code : "vercel_connect_request_failed"; const status = error instanceof VercelConnectClientError ? error.status : 502; const message = error instanceof VercelConnectClientError ? error.message : "Vercel Connect could not resolve this credential."; await markRemoteConnectionHealth( connection, code === "vercel_connect_unavailable" || code === "vercel_connect_auth_failed" || code === "vercel_connect_installation_required" ? "degraded" : "error", message, ); throw new ToolGatewayHttpError(status, message, code, { connectionId: connection.id, grantId: grant.id, }); } } const oauth = asRecord(asRecord(connection.config)?.oauth); if ( isPaperclipCloudConnectorStrategy(oauth?.strategy) && !options.oauthGrantRefresher ) { // Compatibility fallback for isolated service consumers. The production // app supplies tool-access's lease/CAS refresher below. grant = await maybeRefreshPaperclipCloudGrant( session, connection, grant, resolveOptions.forceRefresh === true, ); } if ( connection.authKind === "oauth" && connection.credentialSource === "paperclip_vault" && options.oauthGrantRefresher ) { try { grant = await options.oauthGrantRefresher({ companyId: connection.companyId, connectionId: connection.id, grantId: grant.id, forceRefresh: resolveOptions.forceRefresh, actor: { actorType: session.actorType ?? (session.agentId ? "agent" : "system"), actorId: session.actorId ?? session.agentId, }, issueId: session.issueId, heartbeatRunId: session.runId, }); } catch (error) { if (error instanceof ToolGatewayHttpError) throw error; const record = asRecord(error); const details = asRecord(record?.details) ?? {}; const status = typeof record?.status === "number" ? record.status : 502; const reasonCode = typeof details.code === "string" ? details.code : "oauth_refresh_failed"; const message = error instanceof Error ? error.message : "OAuth authorization could not be refreshed"; throw new ToolGatewayHttpError(status, message, reasonCode, { ...details, connectionId: connection.id, grantId: grant.id, }); } } const headers: Record = {}; for (const ref of connection.credentialRefs ?? []) { if (ref.placement !== "header") continue; const grantRef = grantRefForCredential(grant, ref); if (!grantRef) continue; try { const value = await resolveGrantSecretValue( session, connection, grant, grantRef, ); headers[ref.key] = `${ref.prefix ?? ""}${value}`; } catch (error) { await markRemoteConnectionHealth( connection, "missing_secret", "A configured credential secret could not be resolved.", ); if (error instanceof ToolGatewayHttpError && error.reasonCode === "grant_credential_invalid") throw error; throw new ToolGatewayHttpError( 422, "A configured credential secret could not be resolved.", "mcp_remote_missing_secret", { connectionId: connection.id, credential: ref.name }, ); } } const oauthAccessRef = grant.credentialSecretRefs.find( (ref) => ref.configPath === "oauth.access_token", ); if (oauthAccessRef && headers.Authorization === undefined) { try { const value = await resolveGrantSecretValue( session, connection, grant, oauthAccessRef, ); headers.Authorization = `Bearer ${value}`; } catch (error) { await markRemoteConnectionHealth( connection, "missing_secret", "A configured credential secret could not be resolved.", ); if (error instanceof ToolGatewayHttpError && error.reasonCode === "grant_credential_invalid") throw error; throw new ToolGatewayHttpError( 422, "A configured credential secret could not be resolved.", "mcp_remote_missing_secret", { connectionId: connection.id, credential: oauthAccessRef.configPath, }, ); } } return headers; } function credentialVersionRefHash(value: Record): string { return stableHash(value); } async function resolveConnectedCredentialVersion( connection: typeof toolConnections.$inferSelect, input: { secretId: string; versionSelector: SecretVersionSelector | undefined; configPath: string; refHash: string; requireResolved: boolean; }, ): Promise { const versionSelector = input.versionSelector ?? "latest"; try { const identity = await secrets.resolveSecretVersionIdentity( connection.companyId, input.secretId, versionSelector, ); return { refHash: input.refHash, versionSelector: String(versionSelector), resolvedVersion: identity.version, ...(connection.authKind === "oauth" && versionSelector === "latest" && ["oauth.access_token", "oauth.refresh_token"].includes(input.configPath) ? { identityEpoch: identity.identityEpoch } : {}), }; } catch { await markRemoteConnectionHealth( connection, "missing_secret", "A configured credential secret could not be resolved.", ); if (input.requireResolved) { throw new ToolGatewayHttpError( 422, "A configured credential secret could not be resolved.", "mcp_remote_missing_secret", { connectionId: connection.id, credential: input.configPath }, ); } return { refHash: input.refHash, versionSelector: String(versionSelector), resolvedVersion: -1, }; } } async function connectedCredentialVersionSnapshots( connection: typeof toolConnections.$inferSelect, grant: typeof connectionGrants.$inferSelect, options: { requireResolved: boolean }, ): Promise<{ headerCredentialVersions: ConnectedCredentialVersionSnapshot[]; credentialSecretVersions: ConnectedCredentialVersionSnapshot[]; }> { const headerCredentialVersions: ConnectedCredentialVersionSnapshot[] = []; const credentialSecretVersions: ConnectedCredentialVersionSnapshot[] = []; for (const ref of connection.credentialRefs ?? []) { if (ref.placement !== "header" && ref.placement !== "url") continue; const typedRef = ref as McpConnectionCredentialRef; const grantRef = grantRefForCredential(grant, typedRef); if (!grantRef) continue; const configPath = typedRef.placement === "url" ? REMOTE_URL_SECRET_CONFIG_PATH : grantRef.configPath; headerCredentialVersions.push( await resolveConnectedCredentialVersion(connection, { secretId: grantRef.secretId, versionSelector: grantRef.versionSelector, configPath, refHash: credentialVersionRefHash({ kind: typedRef.placement === "url" ? "url" : "header", name: typedRef.name, secretId: grantRef.secretId, placement: typedRef.placement, key: typedRef.key, prefix: typedRef.prefix ?? null, configPath, }), requireResolved: options.requireResolved, }), ); } for (const ref of grant.credentialSecretRefs ?? []) { const typedRef = ref as ToolCredentialSecretRef; credentialSecretVersions.push( await resolveConnectedCredentialVersion(connection, { secretId: typedRef.secretId, versionSelector: typedRef.versionSelector, configPath: typedRef.configPath, refHash: credentialVersionRefHash({ kind: "secret_ref", secretId: typedRef.secretId, configPath: typedRef.configPath, required: typedRef.required ?? true, label: typedRef.label ?? null, }), requireResolved: options.requireResolved, }), ); } return { headerCredentialVersions, credentialSecretVersions }; } async function createUserAuthorizationInteraction( session: ToolGatewaySession, connection: typeof toolConnections.$inferSelect, userId: string, grantKind: "organization" | "user" = "user", ) { if (!session.issueId || !session.agentId || !session.runId) return; const [company] = await db .select({ issuePrefix: companies.issuePrefix }) .from(companies) .where(eq(companies.id, session.companyId)) .limit(1); const href = `/${company?.issuePrefix ?? ""}/apps/${connection.id}/permissions`; const idempotencyKey = `connection-authorization:${connection.id}:${userId}`; const payload = requestConfirmationPayloadSchema.parse({ version: 1 as const, prompt: grantKind === "organization" ? `Reconnect the ${connection.name} organization identity to continue` : `Connect your ${connection.name} account to continue`, acceptLabel: grantKind === "organization" ? "Reconnect organization" : "Connect account", rejectLabel: "Not now", detailsMarkdown: grantKind === "organization" ? "Vercel Connect reports that the shared organization identity needs authorization." : "This run needs your personal authorization. Paperclip will not use another user's identity.", target: { type: "custom" as const, key: `connection-authorization:${createHash("sha256").update(idempotencyKey).digest("hex")}`, revisionId: connection.updatedAt.toISOString(), label: `Connect ${connection.name}`.slice(0, 120), href, }, }); const [existing] = await db .select({ id: issueThreadInteractions.id }) .from(issueThreadInteractions) .where( and( eq(issueThreadInteractions.companyId, session.companyId), eq(issueThreadInteractions.issueId, session.issueId), eq(issueThreadInteractions.idempotencyKey, idempotencyKey), ), ) .limit(1); if (existing) { await db .update(issueThreadInteractions) .set({ status: "pending", continuationPolicy: "wake_assignee", requestedResolverPolicy: "human_only", effectiveResolverPolicy: "human_only", resolverPolicyProvenance: "explicit", effectiveResolverPolicySource: "requested", addresseeUserId: userId, payload, result: null, resolvedAt: null, updatedAt: new Date(), }) .where(eq(issueThreadInteractions.id, existing.id)); return; } await db.insert(issueThreadInteractions).values({ companyId: session.companyId, issueId: session.issueId, kind: "request_confirmation", status: "pending", continuationPolicy: "wake_assignee", requestedResolverPolicy: "human_only", effectiveResolverPolicy: "human_only", resolverPolicyProvenance: "explicit", effectiveResolverPolicySource: "requested", idempotencyKey, sourceRunId: session.runId, title: grantKind === "organization" ? `Reconnect ${connection.name}` : `Connect your ${connection.name}`, summary: grantKind === "organization" ? "Organization authorization is required before this run can continue." : "Personal authorization is required before this run can continue.", createdByAgentId: session.agentId, addresseeUserId: userId, payload, }); } async function resolveConnectionGrant( session: ToolGatewaySession, connection: typeof toolConnections.$inferSelect, allowInteraction = true, ): Promise { const [run] = session.runId && !session.identityContextId ? await db .select({ responsibleUserId: heartbeatRuns.responsibleUserId, invocationSource: heartbeatRuns.invocationSource, }) .from(heartbeatRuns) .where( and( eq(heartbeatRuns.id, session.runId), eq(heartbeatRuns.companyId, session.companyId), ), ) .limit(1) : []; const actingUserId = session.identityContextId ? (session.responsibleUserId ?? null) : (run?.responsibleUserId ?? session.responsibleUserId ?? null); if ( session.identityContextId && session.agentId && (connection.config.sourceTemplateKey === "github" || connection.transportConfig?.sourceTemplateKey === "github") ) { const captured = githubOperationCredentials.get(session); const selected = captured ? { grant: captured.grant, error: undefined } : await resolveManagedGitHubIdentitySelection(db, session.companyId, { agentId: session.agentId, responsibleUserId: session.responsibleUserId, allowStandingDelegation: false, }); if (!selected.grant || selected.grant.connectionId !== connection.id) { throw new ToolGatewayHttpError( 409, selected.error ?? "GitHub identity changed; retry through the managed tool", "github_identity_unavailable", ); } if (selected.grant.kind === "user") { const [member] = await db .select({ role: companyMemberships.membershipRole }) .from(companyMemberships) .where( and( eq(companyMemberships.companyId, session.companyId), eq(companyMemberships.principalType, "user"), eq(companyMemberships.principalId, selected.grant.subjectUserId!), eq(companyMemberships.status, "active"), ), ) .limit(1); if (!member || member.role === "viewer") { throw new ToolGatewayHttpError( 403, "The personal grant owner is not an authorized company member", "grant_owner_membership_inactive", ); } } // Managed GitHub selection is final: a legacy shared policy cannot replace // the captured person's grant with an organization or teammate's account. return selected.grant; } const autonomous = !session.identityContextId && (run?.invocationSource === "automation" || run?.invocationSource === "timer"); const findUserGrant = async () => { if (!actingUserId) return undefined; const [membership] = await db .select({ id: companyMemberships.id }) .from(companyMemberships) .where( and( eq(companyMemberships.companyId, connection.companyId), eq(companyMemberships.principalType, "user"), eq(companyMemberships.principalId, actingUserId), eq(companyMemberships.status, "active"), ), ) .limit(1); if (!membership) { throw new ToolGatewayHttpError( 403, "The personal grant owner is not an active company member", "grant_owner_membership_inactive", { connectionId: connection.id, actingUserId, remediation: { action: "restore_membership_or_reconnect" }, }, ); } const [grant] = await db .select() .from(connectionGrants) .where( and( eq(connectionGrants.companyId, connection.companyId), eq(connectionGrants.connectionId, connection.id), eq(connectionGrants.kind, "user"), eq(connectionGrants.subjectUserId, actingUserId), eq(connectionGrants.status, "active"), ), ) .limit(1); return grant; }; const findOrganizationGrant = async () => { const [grant] = await db .select() .from(connectionGrants) .where( and( eq(connectionGrants.companyId, connection.companyId), eq(connectionGrants.connectionId, connection.id), eq(connectionGrants.kind, "organization"), eq(connectionGrants.isDefault, true), eq(connectionGrants.status, "active"), ), ) .limit(1); if (!grant) { throw new ToolGatewayHttpError( 409, "Organization authorization is required", "organization_authorization_required", { connectionId: connection.id, }, ); } const members = await db .select({ subjectId: connectionGrantMembers.subjectId }) .from(connectionGrantMembers) .where( and( eq(connectionGrantMembers.companyId, connection.companyId), eq(connectionGrantMembers.grantId, grant.id), eq(connectionGrantMembers.subjectType, "user"), ), ); const activeAudienceMember = actingUserId ? await db .select({ id: companyMemberships.id }) .from(companyMemberships) .where( and( eq(companyMemberships.companyId, connection.companyId), eq(companyMemberships.principalType, "user"), eq(companyMemberships.principalId, actingUserId), eq(companyMemberships.status, "active"), ), ) .limit(1) .then((rows) => rows[0] ?? null) : null; if ( !isConnectionGrantAudienceAllowed( members.map((member) => member.subjectId), actingUserId, Boolean(activeAudienceMember), ) ) { throw new ToolGatewayHttpError( 403, "The acting user is not in this grant's audience", "grant_audience_denied", { connectionId: connection.id, grantId: grant.id, actingUserId, }, ); } return grant; }; if (connection.credentialPolicy === "per_agent") { if (!session.agentId) { throw new ToolGatewayHttpError( 409, "A dedicated agent authorization is required", "agent_authorization_required", { connectionId: connection.id, }, ); } const [agentGrant] = await db .select() .from(connectionGrants) .where( and( eq(connectionGrants.companyId, connection.companyId), eq(connectionGrants.connectionId, connection.id), eq(connectionGrants.kind, "agent"), eq(connectionGrants.subjectAgentId, session.agentId), eq(connectionGrants.status, "active"), ), ) .limit(1); if (!agentGrant) { throw new ToolGatewayHttpError( 409, "This agent's dedicated authorization is not connected", "agent_authorization_required", { connectionId: connection.id, agentId: session.agentId, }, ); } return agentGrant; } // The owner-selected connection install is the consent boundary for agent use. // `responsibleUserId` is resolved and persisted by the control plane, never // accepted from agent input, so a run carrying it uses that owner's grant // directly. Delegation is reserved for genuinely ownerless unattended runs. let userGrant = connection.credentialPolicy === "shared" ? undefined : await findUserGrant(); if ( !userGrant && !actingUserId && autonomous && session.agentId && connection.credentialPolicy !== "shared" ) { const delegated = await db .select({ grant: connectionGrants }) .from(connectionGrantDelegations) .innerJoin( connectionGrants, and( eq(connectionGrants.id, connectionGrantDelegations.grantId), eq( connectionGrants.companyId, connectionGrantDelegations.companyId, ), ), ) .where( and( eq(connectionGrantDelegations.companyId, connection.companyId), eq(connectionGrantDelegations.agentId, session.agentId), eq(connectionGrants.connectionId, connection.id), eq(connectionGrants.kind, "user"), eq(connectionGrants.status, "active"), ), ); if (delegated.length > 1) { throw new ToolGatewayHttpError( 409, "More than one delegated personal authorization matches this autonomous run", "ambiguous_personal_grant", { connectionId: connection.id, agentId: session.agentId, }, ); } userGrant = delegated[0]?.grant; if (userGrant?.subjectUserId) { const [membership] = await db .select({ id: companyMemberships.id }) .from(companyMemberships) .where( and( eq(companyMemberships.companyId, connection.companyId), eq(companyMemberships.principalType, "user"), eq(companyMemberships.principalId, userGrant.subjectUserId), eq(companyMemberships.status, "active"), ), ) .limit(1); if (!membership) { throw new ToolGatewayHttpError( 403, "The delegated personal grant owner is not an active company member", "grant_owner_membership_inactive", { connectionId: connection.id, grantId: userGrant.id, }, ); } } } const resolution = userGrant ? "user" : resolveCredentialGrantKind( connection.credentialPolicy, actingUserId, false, ); if (resolution === "user" && userGrant) return userGrant; if (resolution === "user_authorization_required") { if (actingUserId && allowInteraction) await createUserAuthorizationInteraction( session, connection, actingUserId, ); throw new ToolGatewayHttpError( 409, "User authorization is required", "user_authorization_required", { connectionId: connection.id, actingUserId, }, ); } return findOrganizationGrant(); } async function resolveConnectedRemoteTool( session: ToolGatewaySession, tool: ToolGatewayDescriptor, ) { if ( (tool.providerType !== "mcp_remote_http" && tool.providerType !== "provider_rest") || !tool.connectionId || !tool.catalogEntryId ) { throw new ToolGatewayHttpError( 404, `Tool "${tool.name}" not found`, "tool_not_found", ); } const [entry] = await db .select() .from(toolCatalogEntries) .where( and( eq(toolCatalogEntries.id, tool.catalogEntryId), eq(toolCatalogEntries.companyId, session.companyId), ), ) .limit(1); if (!entry || entry.status !== "active" || entry.entryKind !== "tool") { throw new ToolGatewayHttpError( 404, `Tool "${tool.name}" not found`, "tool_not_found", ); } const [connected] = await db .select({ connection: toolConnections, sourceTemplateKey: toolSourceTemplateKeySql }) .from(toolConnections) .innerJoin(toolApplications, and( eq(toolApplications.id, toolConnections.applicationId), eq(toolApplications.companyId, toolConnections.companyId), )) .where( and( eq(toolConnections.id, entry.connectionId), eq(toolConnections.companyId, session.companyId), ), ) .limit(1); const connection = connected?.connection; if (!connection || (connection.transport !== "mcp_remote" && !isBrowserUseConnection(connection) && !nativeProviderCatalogFor(connection) && !restConnectorFor(connection))) { throw new ToolGatewayHttpError( 404, `Tool "${tool.name}" not found`, "tool_not_found", ); } if (isRetiredComposioConnection(connection)) { throw new ToolGatewayHttpError(422, RETIRED_COMPOSIO_MESSAGE, "composio_broker_retired"); } if (!connection.enabled || connection.status !== "active") { throw new ToolGatewayHttpError( 403, "Connection is disabled.", "mcp_remote_connection_disabled", { connectionId: connection.id, }, ); } if (isRailwayEndpoint(connection.config.url) && isRailwayToolBlocked(entry.toolName)) { throw new ToolGatewayHttpError(403, "This Railway action cannot bind its effects to an approved target. Use redeploy, restart, or rollback for an existing deployment.", "railway_action_blocked"); } const nativeProvider = nativeProviderCatalogFor(connection); if (nativeProvider && !nativeProvider.isCurrentEntry(entry)) { throw new ToolGatewayHttpError(409, `${nativeProvider.name}'s action catalog changed. Review the updated actions in Permissions.`, `${nativeProvider.slug}_catalog_changed`); } const restConnector = restConnectorFor(connection); if (restConnector && !restConnector.isCurrent(entry)) { throw new ToolGatewayHttpError(409, `${restConnector.name}'s action catalog changed. Review the updated actions in Permissions.`, "provider_catalog_changed"); } return { entry, connection, sourceTemplateKey: connected?.sourceTemplateKey ?? null }; } async function governedToolArguments( session: ToolGatewaySession, tool: ToolGatewayDescriptor, parameters: unknown, ): Promise { if (tool.providerType !== "mcp_remote_http" && tool.providerType !== "provider_rest") return parameters; const { connection, entry } = await resolveConnectedRemoteTool(session, tool); const projected = projectedConnectionToolArguments(connection, parameters, entry.toolName, entry.inputSchema ?? {}); if (!githubDefaultOwnerApplies(connection, entry.toolName, entry.inputSchema, projected)) return projected; // An unavailable credential keeps the call unchanged and fails with its own // error at dispatch. const grant = await resolveConnectionGrant(session, connection, false).catch(() => null); return githubDefaultOwnerArguments(entry.toolName, projected, grant?.providerTenant?.github); } async function approvedManagedArgumentsRemainCurrent( session: ToolGatewaySession, tool: ToolGatewayDescriptor, reviewedParameters: unknown, ): Promise { const currentParameters = await governedToolArguments( session, tool, reviewedParameters, ); return ( stableSerialize(currentParameters) === stableSerialize(reviewedParameters) ); } async function resolveConnectedLocalStdioTool( session: ToolGatewaySession, tool: ToolGatewayDescriptor, ) { if ( tool.providerType !== "mcp_local_stdio" || !tool.connectionId || !tool.catalogEntryId ) { throw new ToolGatewayHttpError( 404, `Tool "${tool.name}" not found`, "tool_not_found", ); } const [entry] = await db .select() .from(toolCatalogEntries) .where( and( eq(toolCatalogEntries.id, tool.catalogEntryId), eq(toolCatalogEntries.companyId, session.companyId), ), ) .limit(1); if (!entry || entry.status !== "active" || entry.entryKind !== "tool") { throw new ToolGatewayHttpError( 404, `Tool "${tool.name}" not found`, "tool_not_found", ); } const [connection] = await db .select() .from(toolConnections) .where( and( eq(toolConnections.id, entry.connectionId), eq(toolConnections.companyId, session.companyId), ), ) .limit(1); if (!connection || connection.transport !== "local_stdio") { throw new ToolGatewayHttpError( 404, `Tool "${tool.name}" not found`, "tool_not_found", ); } if (isRetiredComposioConnection(connection)) { throw new ToolGatewayHttpError(422, RETIRED_COMPOSIO_MESSAGE, "composio_broker_retired"); } if (!connection.enabled || connection.status !== "active") { throw new ToolGatewayHttpError( 403, "Connection is disabled.", "local_stdio_connection_disabled", { connectionId: connection.id, }, ); } return { entry, connection }; } function localStdioTemplateId( connection: typeof toolConnections.$inferSelect, ): string { const config = asRecord(connection.config) ?? {}; const templateId = config.templateId; if (typeof templateId !== "string" || templateId.trim().length === 0) { throw new ToolGatewayHttpError( 422, "Local stdio MCP connection requires an approved templateId", "local_stdio_template_missing", { connectionId: connection.id, }, ); } return templateId.trim(); } async function resolveLocalStdioRuntimeTemplate( connection: typeof toolConnections.$inferSelect, ): Promise { const templateId = localStdioTemplateId(connection); const builtIn = BUILTIN_LOCAL_STDIO_RUNTIME_TEMPLATES[templateId]; if (builtIn) return { templateId, ...builtIn }; const [template] = await db .select() .from(toolStdioCommandTemplates) .where( and( eq(toolStdioCommandTemplates.companyId, connection.companyId), eq(toolStdioCommandTemplates.templateKey, templateId), ), ) .limit(1); if (!template || template.status !== "active") { throw new ToolGatewayHttpError( 422, "Local stdio MCP connection requires an active approved template", "local_stdio_template_invalid", { connectionId: connection.id, templateId, }, ); } return { templateId, command: template.command, args: template.args ?? [], envKeys: template.envKeys ?? [], }; } async function localStdioEnvironment( session: ToolGatewaySession, connection: typeof toolConnections.$inferSelect, template: LocalStdioRuntimeTemplate, grant: typeof connectionGrants.$inferSelect, ): Promise { const env: NodeJS.ProcessEnv = {}; for (const key of [ "PATH", "Path", "SystemRoot", "WINDIR", "COMSPEC", "PATHEXT", ]) { const value = process.env[key]; if (typeof value === "string" && value.length > 0) { env[key] = value; } } for (const key of template.envKeys) { const grantRef = grant.credentialSecretRefs.find( (ref) => ref.configPath === `env.${key}`, ); if (!grantRef) continue; try { env[key] = await resolveGrantSecretValue( session, connection, grant, grantRef, ); } catch { await markRemoteConnectionHealth( connection, "missing_secret", "A configured local stdio credential could not be resolved.", ); throw new ToolGatewayHttpError( 422, "A configured local stdio credential could not be resolved.", "local_stdio_missing_secret", { connectionId: connection.id, credential: grantRef.configPath }, ); } } if (template.templateId === "paperclip.cognee-cloud") { try { cogneeCloudUrl(env.COGNEE_BASE_URL ?? ""); } catch { throw new ToolGatewayHttpError(422, "Reconnect Cognee with the tenant API Base URL from its API Keys page.", "cognee_cloud_url_invalid"); } } return env; } function stdioProtocolError( message: string, details: Record = {}, ) { return new ToolGatewayHttpError( 502, message, "local_stdio_protocol_error", details, ); } async function callLocalStdioMcp(input: { connection: typeof toolConnections.$inferSelect; entry?: typeof toolCatalogEntries.$inferSelect; template: LocalStdioRuntimeTemplate; env: NodeJS.ProcessEnv; parameters?: unknown; protocolMethod?: string; protocolParams?: Record; timeoutMs: number; /** Receives the call's `notifications/progress`; its token is sent with tools/call. */ progressReporter?: ToolCallProgressReporter | null; }, /** One restart and one deadline are shared by every protocol recovery in a call. */ recovery: { restarted: boolean; deadline: number } = { restarted: false, deadline: Date.now() + input.timeoutMs }, ): Promise { if (input.template.templateId === "paperclip.cognee-cloud") { if (input.protocolMethod === "resources/list") return { resources: [] }; if (input.protocolMethod === "prompts/list") return { prompts: [] }; if (input.protocolMethod && input.protocolMethod !== "tools/call") { throw stdioProtocolError("Cognee does not expose this context operation"); } return callCogneeCloud({ baseUrl: input.env.COGNEE_BASE_URL ?? "", apiKey: input.env.COGNEE_API_KEY ?? "", tool: input.entry?.toolName ?? "", parameters: asRecord(input.parameters) ?? {}, signal: AbortSignal.timeout(input.timeoutMs), request: async (url, init) => { const response = await guardedRemoteHttpFetch(url, init, remoteHttpFetchOptions()); const body = await readBoundedRemoteResponse(response); if (!response.ok) throw new ToolGatewayHttpError(502, `Cognee Cloud request failed (HTTP ${response.status}).`, "cognee_api_error"); if (!body) return { status: "success" }; try { return JSON.parse(body); } catch { throw new ToolGatewayHttpError(502, "Cognee Cloud returned invalid JSON.", "cognee_api_error"); } }, }); } if (!input.template.command) { throw new ToolGatewayHttpError( 501, "Local stdio template does not define an executable command", "local_stdio_command_unavailable", { connectionId: input.connection.id, templateId: input.template.templateId, }, ); } const child = spawn(input.template.command, input.template.args, { env: input.env, stdio: ["pipe", "pipe", "pipe"], }); let stdout = ""; let stderr = ""; let nextId = 1; const pending = new Map< number, { resolve: (value: unknown) => void; reject: (error: Error) => void; } >(); const timer = setTimeout(() => { child.kill("SIGTERM"); for (const { reject } of pending.values()) { reject( new ToolGatewayHttpError( 504, "Local stdio MCP tool call timed out", "tool_timeout", { connectionId: input.connection.id, catalogEntryId: input.entry?.id ?? null, }, ), ); } pending.clear(); }, input.timeoutMs); timer.unref?.(); child.stdout.setEncoding("utf8"); child.stderr.setEncoding("utf8"); child.stdout.on("data", (chunk: string) => { stdout += chunk; let newline = stdout.indexOf("\n"); while (newline >= 0) { const line = stdout.slice(0, newline).trim(); stdout = stdout.slice(newline + 1); if (line) { try { const message = JSON.parse(line) as Record; const id = typeof message.id === "number" ? message.id : null; const progressUpdate = mcpProgressNotificationOf(message, input.progressReporter?.token); if (progressUpdate) input.progressReporter!.report(progressUpdate); if (id !== null && pending.has(id)) { const waiter = pending.get(id)!; pending.delete(id); if (message.error !== undefined) { waiter.reject( stdioProtocolError( "Local stdio MCP server returned a JSON-RPC error", { connectionId: input.connection.id, catalogEntryId: input.entry?.id ?? null, error: message.error, }, ), ); } else { waiter.resolve(message.result); } } } catch { for (const { reject } of pending.values()) { reject( stdioProtocolError( "Local stdio MCP server returned invalid JSON", { connectionId: input.connection.id, catalogEntryId: input.entry?.id ?? null, }, ), ); } pending.clear(); } } newline = stdout.indexOf("\n"); } }); child.stderr.on("data", (chunk: string) => { stderr = `${stderr}${chunk}`.slice(-4_000); }); const exitPromise = new Promise((resolve, reject) => { child.on("error", (error) => { const gatewayError = new ToolGatewayHttpError( 502, "Local stdio MCP command failed to start", "local_stdio_spawn_failed", { connectionId: input.connection.id, templateId: input.template.templateId, message: error.message, }, ); for (const { reject: rejectPending } of pending.values()) { rejectPending(gatewayError); } pending.clear(); reject(gatewayError); }); child.on("exit", (code, signal) => { if (pending.size === 0) { resolve(); return; } for (const { reject: rejectPending } of pending.values()) { rejectPending( new ToolGatewayHttpError( 502, "Local stdio MCP command exited before responding", "local_stdio_process_exited", { connectionId: input.connection.id, catalogEntryId: input.entry?.id ?? null, code, signal, stderr, }, ), ); } pending.clear(); resolve(); }); }); const request = (method: string, params: Record) => { const id = nextId; nextId += 1; const promise = new Promise((resolve, reject) => { pending.set(id, { resolve, reject }); }); child.stdin.write( `${JSON.stringify({ jsonrpc: "2.0", id, method, params })}\n`, ); return promise; }; // stdio has no status codes to tell eras apart, so the spec's probe is // `server/discover`: a modern server answers it (or with a modern error); // anything else, or silence, means a legacy server that needs `initialize`. // The answer is remembered, since processes are started for each call. const eraKey = mcpEraKey(input.connection.id, `stdio:${input.template.templateId}`); const clientInfo = { name: "paperclip-tool-gateway", version: "0.3.1" }; const withMeta = (protocolVersion: string, params: Record) => isModernMcpProtocolVersion(protocolVersion) ? { ...params, _meta: { ...asRecord(params._meta), "io.modelcontextprotocol/protocolVersion": protocolVersion, "io.modelcontextprotocol/clientCapabilities": mcpClientCapabilities(protocolVersion), "io.modelcontextprotocol/clientInfo": clientInfo } } : params; const probe = async (): Promise => { const id = nextId; const answer = request("server/discover", withMeta(MCP_MODERN_PROTOCOL_VERSION, {})); let probeTimer: NodeJS.Timeout | undefined; const silent = new Promise<"silent">((resolve) => { probeTimer = setTimeout(() => resolve("silent"), STDIO_DISCOVER_PROBE_TIMEOUT_MS); probeTimer.unref?.(); }); try { const outcome = await Promise.race([answer, silent]); if (outcome === "silent") { pending.delete(id); answer.catch(() => undefined); return MCP_PROTOCOL_VERSION; } const versions = asRecord(outcome)?.supportedVersions; if (!Array.isArray(versions)) return MCP_PROTOCOL_VERSION; const selected = selectMcpProtocolVersion(versions); if (!selected) throw stdioProtocolError("This app uses an MCP version Paperclip does not support yet.", { connectionId: input.connection.id }); return selected; } catch (error) { if (!(error instanceof ToolGatewayHttpError) || error.reasonCode !== "local_stdio_protocol_error") throw error; const modernError = mcpModernErrorOf({ error: error.details.error }); if (!modernError) return MCP_PROTOCOL_VERSION; if (modernError.code !== MCP_ERROR_UNSUPPORTED_PROTOCOL_VERSION || !modernError.supported) return MCP_MODERN_PROTOCOL_VERSION; const selected = selectMcpProtocolVersion(modernError.supported); if (!selected) throw stdioProtocolError("This app uses an MCP version Paperclip does not support yet.", { connectionId: input.connection.id }); return selected; } finally { clearTimeout(probeTimer); } }; let probing = false; let probeEndedProcess = false; let rememberedHandshakeRefused = false; let recoveryError: unknown; let result: unknown; try { const remembered = knownMcpProtocolVersion(eraKey); let protocolVersion = remembered; if (!protocolVersion) { probing = true; protocolVersion = await probe(); probing = false; rememberMcpProtocolVersion(eraKey, protocolVersion); } if (!isModernMcpProtocolVersion(protocolVersion)) { try { await request("initialize", { protocolVersion, capabilities: mcpClientCapabilities(protocolVersion), clientInfo, }); } catch (error) { // A remembered handshake server that now refuses `initialize` may have // moved to stateless MCP (same template, new executable). Probe again. if (remembered && error instanceof ToolGatewayHttpError && (error.reasonCode === "local_stdio_protocol_error" || error.reasonCode === "local_stdio_process_exited")) { rememberedHandshakeRefused = true; } throw error; } child.stdin.write( `${JSON.stringify({ jsonrpc: "2.0", method: "notifications/initialized", params: {} })}\n`, ); } try { result = await request( input.protocolMethod ?? "tools/call", withMeta(protocolVersion, input.protocolParams ?? { name: input.entry?.toolName, arguments: input.parameters ?? {}, ...(input.progressReporter ? { _meta: { progressToken: input.progressReporter.token } } : {}), }), ); } catch (error) { // A remembered stateless server replaced by a handshake build answers // a call without a handshake with a JSON-RPC error, before running it. // Probe again. A process exit is not retried: the tool may have run. if (isModernMcpProtocolVersion(remembered) && error instanceof ToolGatewayHttpError && error.reasonCode === "local_stdio_protocol_error" && callNeverRan(error.details.error)) { rememberedHandshakeRefused = true; } throw error; } } catch (error) { // A legacy server may exit on a method it does not know. Start it again // for the handshake rather than failing the call. if (probing && error instanceof ToolGatewayHttpError && error.reasonCode === "local_stdio_process_exited") probeEndedProcess = true; else if (!rememberedHandshakeRefused) throw error; recoveryError = error; } finally { clearTimeout(timer); child.stdin.end(); child.kill("SIGTERM"); await exitPromise.catch(() => undefined); } if (probeEndedProcess || rememberedHandshakeRefused) { // A legacy server that exited on the probe is remembered as legacy; a // remembered one that refused the handshake is probed again. Either way // the call starts one more process at most, within its original deadline, // so a server that keeps failing reports its error instead of looping. if (probeEndedProcess) rememberMcpProtocolVersion(eraKey, MCP_PROTOCOL_VERSION); else forgetMcpProtocolVersion(eraKey); const remainingMs = recovery.deadline - Date.now(); if (recovery.restarted || remainingMs <= 0) throw recoveryError; return callLocalStdioMcp({ ...input, timeoutMs: remainingMs }, { restarted: true, deadline: recovery.deadline }); } if (mcpInputRequired(result)) { throw new ToolGatewayHttpError( 409, "This app needs information Paperclip can't collect yet. Complete the step in the app, then try again.", "provider_input_required", { connectionId: input.connection.id, catalogEntryId: input.entry?.id ?? null }, ); } return result; } async function assertApplicationFeatureAvailable(applicationKey: unknown) { const app = getAppDefinitionForApplicationKey(applicationKey); if (app?.experimentalFeatureKey && !isConnectorFeatureEnabled(app, await instanceSettingsService(db).getExperimental())) { throw new ToolGatewayHttpError(403, "This connector is unavailable on this instance.", "connector_unavailable"); } } async function fullyAssignedMcpConnections(session: ToolGatewaySession) { if (!session.gatewayProfileId) return []; const rows = await db .select({ connection: toolConnections, applicationKey: toolApplications.applicationKey }) .from(toolProfileEntries) .innerJoin( toolConnections, eq(toolProfileEntries.connectionId, toolConnections.id), ) .innerJoin(toolApplications, eq(toolConnections.applicationId, toolApplications.id)) .where( and( eq(toolProfileEntries.companyId, session.companyId), eq(toolProfileEntries.profileId, session.gatewayProfileId), eq(toolProfileEntries.selectorType, "connection"), eq(toolProfileEntries.effect, "include"), eq(toolConnections.companyId, session.companyId), eq(toolApplications.companyId, session.companyId), eq(toolConnections.enabled, true), eq(toolConnections.status, "active"), inArray(toolConnections.transport, ["mcp_remote", "local_stdio"]), ), ); const settings = rows.some(row => getAppDefinitionForApplicationKey(row.applicationKey)?.experimentalFeatureKey) ? await instanceSettingsService(db).getExperimental() : undefined; return rows.filter(row => !settings || isConnectorFeatureEnabled(getAppDefinitionForApplicationKey(row.applicationKey), settings)) .map(row => row.connection); } async function callRemoteConnectionProtocol(input: { session: ToolGatewaySession; connection: typeof toolConnections.$inferSelect; method: string; params: Record; callerHeaders?: Record; /** Larger limit for MCP Apps view documents, which go to the browser, never to an agent. */ maxResponseBytes?: number; /** False for reads whose failure says nothing about the connection (an MCP Apps view document). */ markHealth?: boolean; }): Promise { const grant = await resolveConnectionGrant(input.session, input.connection); const endpoint = await resolvedRemoteEndpoint( input.session, input.connection, grant, ); const credentialHeaders = { ...projectedConnectionHeaders(input.connection), ...(await resolveCredentialHeaders( input.session, input.connection, grant, )), }; const { headers } = buildRemoteHeaders({ session: input.session, connection: input.connection, credentialHeaders, callerHeaders: input.callerHeaders, }); const requestId = `paperclip-context-${randomUUID()}`; const dispatch = (init: RequestInit) => options.remoteHttpRequest ? options.remoteHttpRequest(endpoint, init) : guardedRemoteHttpFetch(endpoint, init, remoteHttpFetchOptions()); const eraKey = mcpEraKey(input.connection.id, endpoint); const savedProtocolVersion = asRecord(input.connection.config)?.mcpProtocolVersion; if (!knownMcpProtocolVersion(eraKey)) { if (typeof savedProtocolVersion === "string") rememberMcpProtocolVersion(eraKey, savedProtocolVersion); else if (connectionRequiresMcpSession(input.connection)) rememberMcpProtocolVersion(eraKey, MCP_PROTOCOL_VERSION); } let protocolVersion = knownMcpProtocolVersion(eraKey); // Fresh cacheable results (ttlMs/cacheScope) are reused. Private results // stay with the credential that read them; retries carrying multi // round-trip answers are never cached. const cacheable = MCP_CACHEABLE_CONTEXT_METHODS.has(input.method) && input.params.inputResponses === undefined && input.params.requestState === undefined; const cacheKey = (scope: string) => `${eraKey}:${input.method}:${JSON.stringify(input.params)}:${scope}`; const privateScope = mcpCredentialFingerprint(headers); if (cacheable && isModernMcpProtocolVersion(protocolVersion)) { const cached = mcpContextCache.get(cacheKey(privateScope)) ?? mcpContextCache.get(cacheKey("public")); if (cached !== undefined) return structuredClone(cached); } const sendForNegotiation = (init: RequestInit) => dispatch({ ...init, redirect: "manual" }); // Stateful (handshake) servers need the same MCP session setup as tool calls. let sessionScope = connectionRequiresMcpSession(input.connection) ? `${input.connection.id}:grant:${grant.id}:actor:${input.session.agentId}:${endpoint}` : null; // The session this read used. On a 400/404 only that session is dropped: // other identities' sessions and in-flight initializations are untouched. let usedSession: { scope: string; headers: Record; sessionId: string } | null = null; const send = async (fresh: boolean) => { let requestHeaders: Record = isModernMcpProtocolVersion(protocolVersion) ? { ...headers, "MCP-Protocol-Version": protocolVersion } : headers; if (sessionScope && !isModernMcpProtocolVersion(protocolVersion)) { if (fresh && usedSession) forgetMcpHttpSession(usedSession); requestHeaders = await getMcpHttpSession({ scope: sessionScope, send: sendForNegotiation, headers, requestId, eraKey }); const sessionId = new Headers(requestHeaders).get("mcp-session-id"); usedSession = sessionId ? { scope: sessionScope, headers, sessionId } : null; // A handshake server that moved to stateless MCP comes back without a session. const negotiated = mcpProtocolVersionOf(requestHeaders); if (isModernMcpProtocolVersion(negotiated)) { protocolVersion = negotiated; await persistMcpProtocolVersion(input.connection, negotiated); } } return dispatch({ ...mcpHttpRequestInit(requestHeaders, { id: requestId, method: input.method, params: input.params }), redirect: "manual", }); }; let response = await send(false); // Context reads are read-only, so a request a stateless server rejected for // its version or shape is retried once with a negotiated version. const modernRejection = await readMcpModernError(response); const rolledBack = !modernRejection && response.status === 400 && isModernMcpProtocolVersion(protocolVersion); if (modernRejection || rolledBack) { const retryVersion = modernRejection?.code === MCP_ERROR_UNSUPPORTED_PROTOCOL_VERSION && modernRejection.supported ? selectMcpProtocolVersion(modernRejection.supported) : rolledBack || !isModernMcpProtocolVersion(protocolVersion) ? (forgetMcpProtocolVersion(eraKey), await negotiateMcpProtocolVersion({ send: sendForNegotiation, headers, requestId: `${requestId}-version`, eraKey })) : null; const usable = retryVersion !== null && retryVersion !== protocolVersion && (isModernMcpProtocolVersion(retryVersion) || isModernMcpProtocolVersion(protocolVersion)); if (usable) { rememberMcpProtocolVersion(eraKey, retryVersion!); await persistMcpProtocolVersion(input.connection, retryVersion!); // Back on the handshake, the read needs a session like a tool call. if (!isModernMcpProtocolVersion(retryVersion)) { sessionScope ??= `${input.connection.id}:grant:${grant.id}:actor:${input.session.agentId}:${endpoint}`; } protocolVersion = retryVersion; if (usedSession) forgetMcpHttpSession(usedSession); await response.body?.cancel().catch(() => undefined); response = await send(false); } } else if (sessionScope && !isModernMcpProtocolVersion(protocolVersion) && (response.status === 404 || response.status === 400)) { // An expired or unknown session: start a new one once. await response.body?.cancel().catch(() => undefined); response = await send(true); } const body = await readBoundedRemoteResponse(response, undefined, input.maxResponseBytes); if (!response.ok) { if (input.markHealth !== false) await markRemoteConnectionHealth( input.connection, "error", `Remote MCP server failed ${input.method}.`, ); throw new ToolGatewayHttpError( 502, "Remote MCP context request failed", "mcp_remote_status", { status: response.status, connectionId: input.connection.id, method: input.method, }, ); } let payload: unknown; try { payload = parseMcpHttpResponseBody( body, response.headers.get("content-type"), ); } catch { throw new ToolGatewayHttpError( 502, "Remote MCP context response was invalid", "mcp_remote_invalid_json", { connectionId: input.connection.id, method: input.method, }, ); } const record = asRecord(payload); if ( !record || record.error !== undefined || !Object.prototype.hasOwnProperty.call(record, "result") ) { throw new ToolGatewayHttpError( 502, "Remote MCP context request returned an error", "remote_mcp_error", { connectionId: input.connection.id, method: input.method, // Resource not found is -32602 from stateless servers, -32002 before. code: typeof asRecord(record?.error)?.code === "number" ? asRecord(record?.error)!.code : null, }, ); } if (mcpInputRequired(record.result)) { throw new ToolGatewayHttpError( 409, "This app needs information Paperclip can't collect yet. Complete the step in the app, then try again.", "provider_input_required", { connectionId: input.connection.id, method: input.method }, ); } if (input.markHealth !== false) await markRemoteConnectionHealth( input.connection, "ok", `Remote MCP server responded to ${input.method}.`, ); const hint = cacheable && isModernMcpProtocolVersion(protocolVersion) ? mcpCacheHint(record.result) : null; if (hint) mcpContextCache.set(cacheKey(hint.scope === "public" ? "public" : privateScope), structuredClone(record.result), hint.ttlMs); return record.result; } async function callAssignedConnectionProtocol(input: { session: ToolGatewaySession; connection: typeof toolConnections.$inferSelect; method: string; params?: Record; callerHeaders?: Record; maxResponseBytes?: number; markHealth?: boolean; }): Promise { const [application] = await db.select({ applicationKey: toolApplications.applicationKey }).from(toolApplications) .where(and(eq(toolApplications.id, input.connection.applicationId), eq(toolApplications.companyId, input.session.companyId))).limit(1); if (!application) throw new ToolGatewayHttpError(404, "MCP connection not found", "connection_not_found"); await assertApplicationFeatureAvailable(application.applicationKey); if (input.connection.transport === "mcp_remote") { return callRemoteConnectionProtocol({ ...input, params: input.params ?? {}, }); } if (input.connection.transport !== "local_stdio") { throw new ToolGatewayHttpError( 501, "Assigned MCP connection transport is unsupported", "mcp_transport_unsupported", ); } const template = await resolveLocalStdioRuntimeTemplate(input.connection); const grant = await resolveConnectionGrant(input.session, input.connection); const env = await localStdioEnvironment( input.session, input.connection, template, grant, ); if (template.templateId === "paperclip.cognee-cloud") { return callLocalStdioMcp({ connection: input.connection, template, env, protocolMethod: input.method, protocolParams: input.params ?? {}, timeoutMs: DEFAULT_TOOL_TIMEOUT_MS }); } return runtimeSupervisor.useConnectionSlot( { companyId: input.session.companyId, applicationId: input.connection.applicationId, connectionId: input.connection.id, connectionKey: `mcp:${input.session.companyId}:${input.connection.id}`, runId: input.session.runId, issueId: input.session.issueId, agentId: input.session.agentId, commandTemplateKey: template.templateId, metadata: { source: "native-runtime-context", protocolMethod: input.method, }, }, async () => callLocalStdioMcp({ connection: input.connection, template, env, protocolMethod: input.method, protocolParams: input.params ?? {}, timeoutMs: DEFAULT_TOOL_TIMEOUT_MS, }), ); } const mcpSkills = mcpSkillsService(db); /** How long a run waits for connected-app skills before starting without the late ones. */ const MCP_SKILL_LOAD_BUDGET_MS = 3_000; /** * One verified file of an approved MCP skill, read with this session's own * access to the skill's connection. Only files in the approved manifest are * read; cached bytes are re-hashed. Content that fails verification is never * returned: the entry is refreshed with `skills/get` and leaves use until the * board approves it again. */ async function readVerifiedMcpSkillFile(session: ToolGatewaySession, connection: typeof toolConnections.$inferSelect, skill: McpSkillRow, relativePath: string): Promise { const resource = mcpSkillManifestFile(skill, relativePath); if (!resource) { throw new ToolGatewayHttpError(404, "That file is not part of this skill.", "mcp_skill_file_not_listed"); } try { const cached = await mcpSkills.cachedFile(skill, resource); if (cached) { // Cached bytes match the digest, but the listed frontmatter may have // changed since; check it on every load, not only on fetch. if (resource.uri === skill.skillUri) verifyMcpSkillFrontmatter(cached.toString("utf8"), skill.frontmatter, skill.skillUri); return cached; } const result = await callAssignedConnectionProtocol({ session, connection, method: "resources/read", params: { uri: resource.uri }, // JSON or SSE framing escapes the bytes; leave headroom over the listed size. maxResponseBytes: Math.max(256 * 1024, resource.size * 2 + 64 * 1024), markHealth: false, }); const bytes = mcpSkillContentBytes(result, resource.uri); if (!bytes) throw new McpSkillVerificationError("The app returned no content for a listed file.", resource.uri); verifyMcpSkillFileBytes(bytes, resource); if (resource.uri === skill.skillUri) verifyMcpSkillFrontmatter(bytes.toString("utf8"), skill.frontmatter, skill.skillUri); await mcpSkills.cacheFile(skill, resource, bytes); return bytes; } catch (error) { if (!(error instanceof McpSkillVerificationError)) throw error; await refreshMcpSkillAfterFailure(session, connection, skill, error.message); throw new ToolGatewayHttpError(409, "This skill changed in its app and needs to be reviewed again.", "mcp_skill_verification_failed"); } } /** * After a verification failure the skill leaves use unless a refresh shows * a different manifest (which already needs review). Anything else, including * an answer for another URI or no usable entry, takes this skill out of use. */ async function refreshMcpSkillAfterFailure(session: ToolGatewaySession, connection: typeof toolConnections.$inferSelect, skill: McpSkillRow, detail: string) { const actor = { actorType: "system" as const, actorId: "mcp-skills", agentId: session.agentId, runId: session.runId }; let refreshed: McpSkillRow | null = null; try { const result = asRecord(await callAssignedConnectionProtocol({ session, connection, method: "skills/get", params: { uri: skill.skillUri }, markHealth: false, })); const entry = asRecord(result?.skill); if (entry?.uri === skill.skillUri) refreshed = await mcpSkills.applyEntry(connection, entry, actor); } catch (error) { if (error instanceof ToolGatewayHttpError && asRecord(error.details)?.code === -32602) { await mcpSkills.markRemoved(skill, actor); return; } } if (refreshed && refreshed.id === skill.id && refreshed.status !== "approved") return; await mcpSkills.markVerificationFailed(refreshed?.id === skill.id ? refreshed : skill, actor, detail); } /** A run-bound session for an agent, as connection instructions use. */ async function agentRunSession(binding: { companyId: string; agentId: string; runId: string }) { const runContext = await resolveRunContext(binding); await assertAgentInCompany(binding.companyId, binding.agentId); return captureSessionIdentity({ ...binding, ...runContext, id: randomUUID(), token: "", createdAt: new Date(), expiresAt: new Date(Date.now() + 60_000), }); } /** Connections whose tools this agent may use now (allowed or ask first) and whose grant resolves. */ async function usableConnectionsForAgent(session: ToolGatewaySession, candidates: Array) { const candidateIds = new Set(candidates.map((connection) => connection.id)); const tools = (await connectionToolsForContext(session)) .filter((tool) => tool.connectionId && candidateIds.has(tool.connectionId)); const decisions = await decideToolsForListing(tools, (tool) => policyInputForTool({ session, tool })); const visible = new Set(decisions.flatMap(({ tool, decision }) => (decision.allowed || decision.decision === "require_approval") && tool.connectionId ? [tool.connectionId] : [], )); const usable: Array = []; for (const connection of candidates) { if (!visible.has(connection.id)) continue; try { await resolveConnectionGrant(session, connection, false); usable.push(connection); } catch (error) { if (!(error instanceof ToolGatewayHttpError) && !(error instanceof HttpError)) throw error; if (error.status >= 500) throw error; } } return usable; } async function approvedMcpSkillConnections(companyId: string, connectionId?: string) { return db.select().from(toolConnections).where(and( eq(toolConnections.companyId, companyId), eq(toolConnections.enabled, true), eq(toolConnections.status, "active"), ...(connectionId ? [eq(toolConnections.id, connectionId)] : []), inArray(toolConnections.id, db.select({ id: toolMcpSkills.connectionId }).from(toolMcpSkills) .where(and(eq(toolMcpSkills.companyId, companyId), eq(toolMcpSkills.status, "approved")))), )); } function contextHandle( kind: "resource" | "prompt", connectionId: string, value: string, ) { return `paperclip-${kind}://${connectionId}/${Buffer.from(value, "utf8").toString("base64url")}`; } function parseContextHandle(kind: "resource" | "prompt", value: unknown) { if (typeof value !== "string") return null; const match = value.match( new RegExp(`^paperclip-${kind}://([0-9a-f-]{36})/([A-Za-z0-9_-]+)$`, "i"), ); if (!match) return null; try { return { connectionId: match[1]!, value: Buffer.from(match[2]!, "base64url").toString("utf8"), }; } catch { return null; } } async function namedGatewayContextProtocol(input: { gatewayId?: string | null; gatewayPublicId?: string | null; bearerToken: string; method: "resources/list" | "resources/read" | "prompts/list" | "prompts/get"; params?: Record; callerHeaders?: Record; }) { const session = await namedGatewaySessionFromBearer({ gatewayId: input.gatewayId ?? null, gatewayPublicId: input.gatewayPublicId ?? null, bearerToken: input.bearerToken, protocolMethod: input.method, callerHeaders: input.callerHeaders, }); await assertGatewayTokenAction(session, input.method); const connections = await fullyAssignedMcpConnections(session); if (input.method === "resources/list") { const resources = [] as Array>; for (const connection of connections) { const result = asRecord( await callAssignedConnectionProtocol({ ...input, session, connection, method: input.method, }), ); for (const resource of Array.isArray(result?.resources) ? result.resources : []) { const record = asRecord(resource); if (!record || typeof record.uri !== "string") continue; resources.push({ ...record, uri: contextHandle("resource", connection.id, record.uri), name: `${connection.name}: ${typeof record.name === "string" ? record.name : record.uri}`, }); } } return { resources }; } if (input.method === "prompts/list") { const prompts = [] as Array>; for (const connection of connections) { const result = asRecord( await callAssignedConnectionProtocol({ ...input, session, connection, method: input.method, }), ); for (const prompt of Array.isArray(result?.prompts) ? result.prompts : []) { const record = asRecord(prompt); if (!record || typeof record.name !== "string") continue; prompts.push({ ...record, name: contextHandle("prompt", connection.id, record.name), title: `${connection.name}: ${typeof record.title === "string" ? record.title : record.name}`, }); } } return { prompts }; } const kind = input.method === "resources/read" ? "resource" : "prompt"; const handle = parseContextHandle( kind, input.params?.[kind === "resource" ? "uri" : "name"], ); const connection = handle ? connections.find((candidate) => candidate.id === handle.connectionId) : null; if (!handle || !connection) { throw new ToolGatewayHttpError( 404, `Assigned MCP ${kind} was not found`, `mcp_${kind}_not_found`, ); } const params = kind === "resource" ? { uri: handle.value } : { name: handle.value, arguments: input.params?.arguments ?? {} }; const result = asRecord( await callAssignedConnectionProtocol({ ...input, session, connection, method: input.method, params, }), ); if (kind === "resource" && Array.isArray(result?.contents)) { return { ...result, contents: result.contents.map((content) => { const record = asRecord(content); return record && typeof record.uri === "string" ? { ...record, uri: contextHandle("resource", connection.id, record.uri), } : content; }), }; } return result ?? {}; } async function connectedRemoteApprovalSnapshot( session: ToolGatewaySession, tool: ToolGatewayDescriptor, options: { requireResolvedCredentials?: boolean } = {}, ): Promise | null> { if (tool.providerType === "paperclip_slack_chat") { if (!session.agentId || !session.runId || !session.issueId) throw new ToolGatewayHttpError(403, "Slack task binding required", "slack_task_required"); const authority = await resolveSlackTaskAuthority(db, { companyId: session.companyId, agentId: session.agentId, runId: session.runId, issueId: session.issueId, endpointId: String(asRecord(tool.providerMetadata)?.endpointId ?? ""), identityContextId: session.identityContextId, approvedInvocationId: session.approvedSlackInvocationId }); return { endpointId: authority.endpoint.id, userId: authority.userId, revision: authority.revision, identityContextId: authority.identityContextId }; } if ( (tool.providerType !== "mcp_remote_http" && tool.providerType !== "provider_rest") || !tool.connectionId || !tool.catalogEntryId ) { return null; } const [row] = await db .select({ entry: toolCatalogEntries, connection: toolConnections, application: toolApplications, }) .from(toolCatalogEntries) .innerJoin( toolConnections, eq(toolCatalogEntries.connectionId, toolConnections.id), ) .innerJoin( toolApplications, eq(toolConnections.applicationId, toolApplications.id), ) .where( and( eq(toolCatalogEntries.id, tool.catalogEntryId), eq(toolCatalogEntries.companyId, session.companyId), eq(toolConnections.id, tool.connectionId), eq(toolConnections.companyId, session.companyId), eq(toolApplications.companyId, session.companyId), ), ) .limit(1); if (!row) return null; const grant = await resolveConnectionGrant(session, row.connection); const credentialVersions = await connectedCredentialVersionSnapshots( row.connection, grant, { requireResolved: options.requireResolvedCredentials === true, }, ); return { approvalSnapshotVersion: 2, connectionIdentityHash: stableHash({ authKind: row.connection.authKind, credentialSource: row.connection.credentialSource, credentialPolicy: row.connection.credentialPolicy, externalCredential: row.connection.externalCredential }), connectionAuthorizationConfigHash: stableHash(row.connection.authKind === "oauth" ? oauthApprovalConfig(row.connection.config ?? {}) : row.connection.config ?? {}), connectionAuthorizationTransportConfigHash: stableHash(row.connection.authKind === "oauth" ? oauthApprovalConfig(row.connection.transportConfig ?? {}) : row.connection.transportConfig ?? {}), credentialGrantIdentityHash: stableHash({ kind: grant.kind, subjectUserId: grant.subjectUserId, subjectAgentId: grant.subjectAgentId, externalCredential: externalCredentialApprovalIdentity(grant.externalCredential), providerTenant: row.connection.authKind === "oauth" ? approvalGrantTenantIdentity(grant.providerTenant, row.connection.config.oauth) : grant.providerTenant }), applicationId: row.application.id, applicationKey: row.application.applicationKey ?? null, applicationStatus: row.application.status, applicationType: row.application.type, connectionId: row.connection.id, connectionStatus: row.connection.status, connectionEnabled: row.connection.enabled, connectionTransport: row.connection.transport, connectionConfigHash: stableHash(row.connection.config ?? {}), connectionTransportConfigHash: stableHash( row.connection.transportConfig ?? {}, ), credentialRefsHash: stableHash(row.connection.credentialRefs ?? []), credentialSecretRefsHash: stableHash( row.connection.credentialSecretRefs ?? [], ), ...(isBrowserUseConnection(row.connection) ? { browserSettingsHash: stableHash(await browserUseService(db).getSettings(session.companyId, grant.id)) } : {}), credentialGrantId: grant.id, credentialGrantRefsHash: stableHash(grant.credentialSecretRefs ?? []), headerCredentialVersions: credentialVersions.headerCredentialVersions, credentialSecretVersions: credentialVersions.credentialSecretVersions, catalogEntryId: row.entry.id, catalogStatus: row.entry.status, catalogEntryKind: row.entry.entryKind, catalogVersionHash: row.entry.versionHash, catalogSchemaHash: row.entry.schemaHash ?? null, upstreamToolName: row.entry.toolName, providerType: tool.providerType, gatewayToolName: tool.name, riskLevel: tool.risk, }; } async function prepareApprovedConnectionAuthorization(session: ToolGatewaySession, tool: ToolGatewayDescriptor, reviewedSnapshot: unknown) { if (tool.providerType !== "mcp_remote_http" && tool.providerType !== "provider_rest") return; const { connection } = await resolveConnectedRemoteTool(session, tool); if (connection.authKind !== "oauth") return; // Never send a refresh credential to a changed endpoint. Validate the saved // target before refresh, then let the caller revalidate its resulting grant. const beforeRefresh = await connectedRemoteApprovalSnapshot(session, tool); if (!approvalSnapshotsMatch(reviewedSnapshot, beforeRefresh)) throw new ToolGatewayHttpError(409, approvalTargetChangeMessage(reviewedSnapshot, beforeRefresh), "approved_tool_target_changed"); const grant = await resolveConnectionGrant(session, connection); // Discover refresh/sign-in failures before startToolInvocation records a // provider dispatch. No action is sent during this credential preparation. await resolveCredentialHeaders(session, connection, grant); } function responseTooLargeError() { return new ToolGatewayHttpError( 502, "Remote MCP response exceeded the gateway size limit. Request a smaller result, for example a narrower query or a smaller page size.", "mcp_remote_response_too_large", { maxBytes: MAX_REMOTE_MCP_RESPONSE_BYTES }, ); } async function readBoundedRemoteResponse( response: Response, onBytes?: (bytes: number) => void, maxBytes = MAX_REMOTE_MCP_RESPONSE_BYTES, ): Promise { const contentLength = response.headers.get("content-length"); if ( contentLength && Number(contentLength) > maxBytes ) { throw responseTooLargeError(); } const reader = response.body?.getReader(); // Injected HTTP transports can expose a buffered text response rather than a // Web ReadableStream. Keep the same size check for that form. if (!reader) { const body = await response.text(); onBytes?.(Buffer.byteLength(body, "utf8")); if (Buffer.byteLength(body, "utf8") > maxBytes) { throw responseTooLargeError(); } return body; } // Count each chunk as it arrives, so a body that fails partway still // reports the bytes that were read. const decoder = new TextDecoder(); let body = ""; let bytes = 0; try { while (true) { const { value, done } = await reader.read(); if (done) break; bytes += value.byteLength; onBytes?.(bytes); if (bytes > maxBytes) throw responseTooLargeError(); body += decoder.decode(value, { stream: true }); } return body + decoder.decode(); } finally { await reader.cancel().catch(() => undefined); reader.releaseLock(); } } function malformedRemoteMcpResponse(): ToolGatewayHttpError { return new ToolGatewayHttpError( 502, "Remote MCP server returned a malformed tools/call response", "remote_mcp_malformed_response", ); } type McpElicitationRequest = { message: string; requestedSchema: Record | null; raw: Record; }; function extractMcpElicitationRequest( value: unknown, ): McpElicitationRequest | null { const record = asRecord(value); if (!record) return null; const meta = asRecord(record._meta); const candidate = (record.method === "elicitation/create" ? asRecord(record.params) : null) ?? asRecord(record.elicitation) ?? asRecord(record.elicitationRequest) ?? asRecord(meta?.elicitation) ?? asRecord(meta?.elicitationRequest); if (!candidate) return null; const message = stringValue(candidate.message) ?? stringValue(candidate.prompt) ?? stringValue(candidate.title) ?? "The MCP tool needs more information before it can continue."; const requestedSchema = asRecord( candidate.requestedSchema ?? candidate.schema ?? candidate.inputSchema, ); return { message, requestedSchema, raw: candidate }; } /** The connection's name, as the person knows the app. */ async function elicitationAppName(companyId: string, connectionId: string | null | undefined, tool?: ToolGatewayDescriptor) { const named = tool?.applicationDisplayName?.trim(); if (named) return named; if (connectionId) { const [connection] = await db.select({ name: toolConnections.name }).from(toolConnections) .where(and(eq(toolConnections.id, connectionId), eq(toolConnections.companyId, companyId))).limit(1); if (connection?.name.trim()) return connection.name.trim(); } return "The app"; } /** Why a provider's form was not shown; the agent reads this, the person sees no card. */ function elicitationRefusedError(appName: string, built: { reason: "sensitive" | "unsupported" }, invocationId?: string) { return built.reason === "sensitive" ? new ToolGatewayHttpError(409, `${appName} asked for a password, key, or other secret in a form. Paperclip doesn't collect secrets that way, so nothing was shown. The app must ask for it through a secure link instead.`, "elicitation_sensitive_refused", invocationId ? { invocationId } : undefined) : new ToolGatewayHttpError(409, `${appName} asked a question Paperclip can't show in the task chat. Complete this step in ${appName}, then try again.`, "elicitation_unsupported", invocationId ? { invocationId } : undefined); } /** * The question card a provider's form becomes. Only people answer it: an * agent answering its own tool's question would consent on nobody's behalf. * Answering wakes the assignee through the question-response outbox. */ async function createElicitationCard(input: { companyId: string; issueId: string; agentId: string | null; appName: string; request: McpFormElicitation; idempotencyKey: string; }) { const built = buildElicitationQuestionSet({ appName: input.appName, request: input.request }); if (!built.ok) throw elicitationRefusedError(input.appName, built); return interactions.create( { id: input.issueId, companyId: input.companyId }, { kind: "ask_user_questions", idempotencyKey: input.idempotencyKey, title: built.questionSet.title, summary: built.questionSet.description, continuationPolicy: "wake_assignee", resolverPolicy: "human_only", payload: { version: 1, supersedeOnUserComment: false, questionSet: built.questionSet }, }, { agentId: input.agentId }, // Each provider question is independent: a new one must never expire // another that is still waiting, which would read as a decline. { supersedePendingSiblingInteractions: false }, ); } /** What the agent reads while a person has the app's question. */ function elicitationWaitError(appName: string, details: Record) { return new ToolGatewayHttpError( 409, `${appName} asked a question, and it is waiting for a person in the task chat. Paperclip wakes you when it is answered; then call this tool again with the same arguments to continue. Don't ask the question yourself.`, "elicitation_required", details, ); } async function markInvocationAwaitingElicitation(invocationId: string) { await db.update(toolInvocations).set({ status: "awaiting_approval", errorCode: "elicitation_required", errorMessage: "The app asked a question; Paperclip put it in the task chat for a person to answer.", updatedAt: new Date(), }).where(eq(toolInvocations.id, invocationId)); } /** Record that the call stopped for a person's answer, then end it. */ async function stopForElicitation(input: { session: ToolGatewaySession; tool: ToolGatewayDescriptor; invocationId: string; appName: string; interactionIds: string[]; requests: McpFormElicitation[]; }): Promise { await markInvocationAwaitingElicitation(input.invocationId); await writeToolCallEvent({ invocationId: input.invocationId, session: input.session, eventType: "call_failed", outcome: "pending", toolName: input.tool.name, policyDecision: "defer_runtime", reasonCode: "elicitation_required", metadata: { interactionId: input.interactionIds[0] ?? null, interactionIds: input.interactionIds, // The question's words and shape, never an answer. elicitation: input.requests.map((request) => ({ message: request.message, requestedSchema: request.requestedSchema })), }, tool: input.tool, }); await writeAudit({ session: input.session, companyId: input.session.companyId, agentId: input.session.agentId, runId: input.session.runId, issueId: input.session.issueId, action: "tool_gateway.elicitation_requested", details: { invocationId: input.invocationId, interactionId: input.interactionIds[0] ?? null, interactionIds: input.interactionIds, decision: "defer_runtime", reasonCode: "elicitation_required", tool: input.tool.name, ...toolAuditMetadata(input.tool), }, }); throw elicitationWaitError(input.appName, { invocationId: input.invocationId, interactionId: input.interactionIds[0] ?? null, interactionIds: input.interactionIds, tool: input.tool.name, }); } /** * A provider question with no way to send an answer back (a vendor result * shape, or an MCP Task's question shown inline). The card is shown and the * call ends; answering wakes the agent. */ async function requestElicitationForRecordedToolCall(input: { session: ToolGatewaySession; tool: ToolGatewayDescriptor; invocationId: string; request: McpElicitationRequest; /** One card per provider input request; defaults to one per call. */ idempotencyKey?: string; connectionId?: string | null; }): Promise { if (!input.session.issueId) { throw new ToolGatewayHttpError( 409, "MCP elicitation is not supported for non-interactive gateway clients", "elicitation_not_supported", { invocationId: input.invocationId, tool: input.tool.name }, ); } const appName = await elicitationAppName(input.session.companyId, input.connectionId ?? input.tool.connectionId, input.tool); const interaction = await createElicitationCard({ companyId: input.session.companyId, issueId: input.session.issueId, agentId: input.session.agentId, appName, request: input.request, idempotencyKey: input.idempotencyKey ?? `mcp-elicitation:${input.invocationId}`, }); return stopForElicitation({ session: input.session, tool: input.tool, invocationId: input.invocationId, appName, interactionIds: [interaction.id], requests: [input.request], }); } /** How long a question round can wait for its answers before the call starts over. */ const MCP_ELICITATION_TTL_MS = 24 * 60 * 60_000; /** Open question rounds per task; more is a clear stop, never a wall of cards. */ const MCP_ELICITATION_MAX_OPEN_ROUNDS = 10; type McpElicitationRow = typeof toolMcpElicitations.$inferSelect; type McpElicitationCall = { session: ToolGatewaySession & { issueId: string }; tool: ToolGatewayDescriptor; connectionId: string; grantId: string; /** Keyed identity of the call, including forwarded routing headers; only the same call collects its round. */ callIdentity: string; /** Keyed identity of the full arguments, checked before a keyed retry runs again. */ argumentsIdentity: string; appName: string; }; const mcpElicitationScope = (row: Pick) => ({ companyId: row.companyId, connectionId: row.connectionId }); const mcpElicitationCallIdentity = (continuationKey: string, routingIdentity: string) => createHmac("sha256", mcpTaskSecret()).update("paperclip:mcp-elicitation-call:v1\0").update(continuationKey).update("\0").update(routingIdentity).digest("hex"); const mcpElicitationCardKey = (roundId: string, key: string) => `mcp-elicit:${roundId}:${createHash("sha256").update(key).digest("hex").slice(0, 32)}`; /** * Save a round of form questions, then put each on a card, then end the * call. The round is saved first: a crash before a card exists is repaired * on the next call, which makes the missing card under the same key. * Forms are checked before anything is saved or shown. */ async function askElicitationRound(call: McpElicitationCall, input: { invocationId: string; era: "modern" | "legacy"; requestState: string | null; forms: Array<{ key: string; request: McpFormElicitation }>; /** An answered round this call just sent: spent in the same transaction that saves the next one. */ spend?: { row: McpElicitationRow; responses: Record }; }): Promise { const { session } = call; // The app already has the answered round's answers, even if this next one is refused. const spendFirst = async () => { if (input.spend) await settleElicitationRound(input.spend.row, call, input.spend.responses, input.invocationId); }; for (const form of input.forms) { const built = buildElicitationQuestionSet({ appName: call.appName, request: form.request }); if (!built.ok) { await spendFirst(); await writeAudit({ session, companyId: session.companyId, agentId: session.agentId, runId: session.runId, issueId: session.issueId, action: "tool_gateway.elicitation_refused", details: { invocationId: input.invocationId, tool: call.tool.name, reason: built.reason, ...(built.reason === "sensitive" ? { fields: built.fields.slice(0, 10) } : {}), }, }); throw elicitationRefusedError(call.appName, built, input.invocationId); } } if (input.forms.length > MCP_ELICITATION_MAX_FORMS_PER_ROUND) { await spendFirst(); throw elicitationRefusedError(call.appName, { reason: "unsupported" }, input.invocationId); } const [open] = await db.select({ count: sql`count(*)::int` }).from(toolMcpElicitations).where(and( eq(toolMcpElicitations.companyId, session.companyId), eq(toolMcpElicitations.issueId, session.issueId), eq(toolMcpElicitations.status, "waiting"), gt(toolMcpElicitations.expiresAt, new Date()), // The answered round this one replaces is not counted: it is spent as this is saved. ...(input.spend ? [ne(toolMcpElicitations.id, input.spend.row.id)] : []), )); if ((open?.count ?? 0) >= MCP_ELICITATION_MAX_OPEN_ROUNDS) { await spendFirst(); throw new ToolGatewayHttpError(409, `This task already has ${MCP_ELICITATION_MAX_OPEN_ROUNDS} app questions waiting for a person. Wait for those to be answered before trying again.`, "elicitation_limit_reached", { invocationId: input.invocationId }); } // One waiting round per call (per question for older servers, which ask // one at a time): two matching calls at once share one set of cards. const dedupeKey = createHash("sha256").update(JSON.stringify([ input.era, call.connectionId, call.grantId, call.callIdentity, ...(input.era === "legacy" ? input.forms.map((form) => elicitationQuestionHash(form.request)) : []), ])).digest("hex"); let row: McpElicitationRow | undefined; for (let attempt = 0; attempt < 2 && !row; attempt += 1) { const id = randomUUID(); const questions: McpElicitationRow["questions"] = input.forms.map((form) => ({ key: form.key, questionHash: elicitationQuestionHash(form.request), cardKey: mcpElicitationCardKey(id, form.key), message: form.request.message, requestedSchema: form.request.requestedSchema, })); // The answered round is spent only together with saving the next one, // so a stop between the two never loses the way to continue. // If saving fails, the answered round is released, not left held, so the next call sends it again. [row] = await db.transaction(async (tx) => { if (input.spend && attempt === 0) { await tx.update(toolMcpElicitations).set({ status: "sent", sentAt: new Date(), claimedUntil: null, updatedAt: new Date() }) .where(eq(toolMcpElicitations.id, input.spend.row.id)); } return tx.insert(toolMcpElicitations).values({ id, companyId: session.companyId, issueId: session.issueId, agentId: session.agentId, runId: session.runId, invocationId: input.invocationId, connectionId: call.connectionId, grantId: call.grantId, catalogToolName: call.tool.name, callIdentity: call.callIdentity, argumentsIdentity: call.argumentsIdentity, dedupeKey, era: input.era, sealedRequestState: input.requestState === null ? null : sealElicitationState(mcpTaskSecret(), { companyId: session.companyId, connectionId: call.connectionId }, input.requestState), questions, status: "waiting", expiresAt: new Date(Date.now() + MCP_ELICITATION_TTL_MS), }).onConflictDoNothing().returning(); }).catch(async (error: unknown) => { if (input.spend) await releaseElicitationRound(input.spend.row).catch(() => undefined); throw error; }); if (input.spend && attempt === 0) await writeElicitationSentAudit(input.spend.row, call, input.spend.responses, input.invocationId); if (row) break; // Another matching call saved the round first: show its cards. An // expired one is ended so this call can save a fresh round. const [existing] = await db.select().from(toolMcpElicitations).where(and( eq(toolMcpElicitations.companyId, session.companyId), eq(toolMcpElicitations.issueId, session.issueId), eq(toolMcpElicitations.dedupeKey, dedupeKey), eq(toolMcpElicitations.status, "waiting"), )).limit(1); if (existing && existing.expiresAt > new Date()) row = existing; else if (existing) await expireElicitationRound(existing, call); } if (!row) throw elicitationWaitError(call.appName, { invocationId: input.invocationId, tool: call.tool.name }); const cards = await ensureElicitationCards(row, call); return stopForElicitation({ session, tool: call.tool, invocationId: input.invocationId, appName: call.appName, interactionIds: cards.map((card) => card.id), requests: input.forms.map((form) => form.request), }); } /** * The round's cards, found by their keys. A card that is missing (the * process stopped between saving the round and showing it) is made now * under the same key, so a question is never lost or shown twice. */ async function ensureElicitationCards(row: McpElicitationRow, call: McpElicitationCall) { const keys = row.questions.map((question) => question.cardKey); const found = keys.length ? await db.select({ id: issueThreadInteractions.id, idempotencyKey: issueThreadInteractions.idempotencyKey, status: issueThreadInteractions.status, result: issueThreadInteractions.result, payload: issueThreadInteractions.payload, }).from(issueThreadInteractions).where(and( eq(issueThreadInteractions.companyId, row.companyId), eq(issueThreadInteractions.issueId, row.issueId), inArray(issueThreadInteractions.idempotencyKey, keys), )) : []; const cards: Array<{ id: string; status: string; result: unknown; payload: unknown }> = []; let made = false; for (const question of row.questions) { let card: { id: string; status: string; result: unknown; payload: unknown } | undefined = found.find((candidate) => candidate.idempotencyKey === question.cardKey); if (!card) { const created = await createElicitationCard({ companyId: row.companyId, issueId: row.issueId, agentId: row.agentId, appName: call.appName, request: { message: question.message, requestedSchema: question.requestedSchema }, idempotencyKey: question.cardKey, }); card = { id: created.id, status: created.status, result: created.result ?? null, payload: created.payload }; made = true; } cards.push(card); } if (made || row.questions.some((question, index) => question.interactionId !== cards[index]!.id)) { const questions = row.questions.map((question, index) => ({ ...question, interactionId: cards[index]!.id })); await db.update(toolMcpElicitations).set({ questions, updatedAt: new Date() }).where(eq(toolMcpElicitations.id, row.id)); row.questions = questions; } return cards; } /** The card's answer for each question of a round; null while any waits. */ async function elicitationRoundResponses(row: McpElicitationRow, call: McpElicitationCall) { const cards = await ensureElicitationCards(row, call); const responses: Record = {}; for (const [index, question] of row.questions.entries()) { const response = elicitationResponseForCard({ message: question.message, requestedSchema: question.requestedSchema }, cards[index]); if (!response) return null; responses[question.key] = response; } return responses; } /** End a round nobody answered in time; its cards are withdrawn so nobody answers a dead question. */ async function expireElicitationRound(row: McpElicitationRow, call: McpElicitationCall) { const [expired] = await db.update(toolMcpElicitations).set({ status: "expired", claimedUntil: null, updatedAt: new Date() }) .where(and(eq(toolMcpElicitations.id, row.id), eq(toolMcpElicitations.status, "waiting"))).returning({ id: toolMcpElicitations.id }); if (!expired) return; for (const question of row.questions) { if (!question.interactionId) continue; await interactions.withdrawInteraction({ id: row.issueId, companyId: row.companyId }, question.interactionId, { reason: "The app's question expired before it was answered." }, { agentId: row.agentId, runId: call.session.runId }) .catch(() => undefined); } await writeAudit({ session: call.session, companyId: row.companyId, agentId: call.session.agentId, runId: call.session.runId, issueId: row.issueId, action: "tool_gateway.elicitation_expired", details: { roundId: row.id, invocationId: row.invocationId, tool: row.catalogToolName }, }); } /** * The waiting round for this exact call. Before every card is resolved the * call stops again without contacting the app. Once they are, the round is * claimed (so two repeated calls never both send) and its answers returned. */ async function collectElicitationRound(call: McpElicitationCall, input: { invocationId: string; era: "modern" | "legacy"; questionHash?: string; claimMs: number; }): Promise<{ row: McpElicitationRow; requestState: string | null; responses: Record } | null> { const { session } = call; const rows = await db.select().from(toolMcpElicitations).where(and( eq(toolMcpElicitations.companyId, session.companyId), eq(toolMcpElicitations.issueId, session.issueId), eq(toolMcpElicitations.connectionId, call.connectionId), eq(toolMcpElicitations.grantId, call.grantId), eq(toolMcpElicitations.callIdentity, call.callIdentity), eq(toolMcpElicitations.era, input.era), eq(toolMcpElicitations.status, "waiting"), )).orderBy(desc(toolMcpElicitations.createdAt)).limit(MCP_ELICITATION_MAX_OPEN_ROUNDS); const now = new Date(); for (const row of rows) { if (input.questionHash && !row.questions.some((question) => question.questionHash === input.questionHash)) continue; if (row.expiresAt <= now) { await expireElicitationRound(row, call); continue; } const responses = await elicitationRoundResponses(row, call); if (!responses) { await markInvocationAwaitingElicitation(input.invocationId); throw elicitationWaitError(call.appName, { invocationId: input.invocationId, interactionId: row.questions[0]?.interactionId ?? null, interactionIds: row.questions.map((question) => question.interactionId).filter(Boolean), tool: call.tool.name, }); } const [claimed] = await db.update(toolMcpElicitations) .set({ claimedUntil: new Date(Date.now() + input.claimMs), updatedAt: new Date() }) .where(and(eq(toolMcpElicitations.id, row.id), eq(toolMcpElicitations.status, "waiting"), or(isNull(toolMcpElicitations.claimedUntil), lt(toolMcpElicitations.claimedUntil, new Date())))) .returning(); if (!claimed) { // Another call is sending these answers right now. await markInvocationAwaitingElicitation(input.invocationId); throw elicitationWaitError(call.appName, { invocationId: input.invocationId, tool: call.tool.name }); } const requestState = claimed.sealedRequestState === null ? null : openElicitationState(mcpTaskSecret(), mcpElicitationScope(claimed), claimed.sealedRequestState); if (claimed.sealedRequestState !== null && requestState === null) { // Not readable here (a rotated secret): start over rather than send a guess. await db.update(toolMcpElicitations).set({ status: "expired", claimedUntil: null, updatedAt: new Date() }).where(eq(toolMcpElicitations.id, claimed.id)); return null; } return { row: claimed, requestState, responses }; } return null; } /** The round's answers reached the app and the call finished: it is spent. */ async function settleElicitationRound(row: McpElicitationRow, call: McpElicitationCall, responses: Record, invocationId: string) { await db.update(toolMcpElicitations).set({ status: "sent", sentAt: new Date(), claimedUntil: null, updatedAt: new Date() }) .where(eq(toolMcpElicitations.id, row.id)); await writeElicitationSentAudit(row, call, responses, invocationId); } async function writeElicitationSentAudit(row: McpElicitationRow, call: McpElicitationCall, responses: Record, invocationId: string) { await writeAudit({ session: call.session, companyId: row.companyId, agentId: call.session.agentId, runId: call.session.runId, issueId: row.issueId, action: "tool_gateway.elicitation_sent", details: { roundId: row.id, invocationId, askedInvocationId: row.invocationId, tool: row.catalogToolName, // Which kind of answer went back, never what the person wrote. responses: Object.values(responses).map((response) => response.action), }, }); } /** The app did not finish with these answers: the next identical call uses them again. */ async function releaseElicitationRound(row: McpElicitationRow) { await db.update(toolMcpElicitations).set({ claimedUntil: null, updatedAt: new Date() }) .where(and(eq(toolMcpElicitations.id, row.id), eq(toolMcpElicitations.status, "waiting"))); } /** * A keyed retry of a call that stopped for an app's question runs again only * when it is the same request: same tool and full arguments as the round. */ async function elicitationRetryMatches(companyId: string, invocationId: string, toolName: string, parameters: unknown) { const [row] = await db.select({ id: toolMcpElicitations.id }).from(toolMcpElicitations).where(and( eq(toolMcpElicitations.companyId, companyId), eq(toolMcpElicitations.invocationId, invocationId), eq(toolMcpElicitations.catalogToolName, toolName), eq(toolMcpElicitations.argumentsIdentity, mcpTaskArgumentsIdentity(parameters)), eq(toolMcpElicitations.status, "waiting"), )).limit(1); return Boolean(row); } function normalizeMcpContent(content: unknown): string { if (!Array.isArray(content)) throw malformedRemoteMcpResponse(); return content .map((item) => { const record = asRecord(item); if (!record || typeof record.type !== "string") throw malformedRemoteMcpResponse(); if (record.type === "text") { if (typeof record.text !== "string") throw malformedRemoteMcpResponse(); return record.text; } return JSON.stringify(record); }) .join("\n"); } const mcpResultMetaByResult = new WeakMap>(); /** The provider `_meta` of a normalized MCP result, redacted, for MCP Apps views only. */ async function redactedMcpResultMeta(result: unknown): Promise | undefined> { const meta = result && typeof result === "object" ? mcpResultMetaByResult.get(result) : undefined; if (!meta) return undefined; const validation = await validateToolContent({ value: meta, direction: "result", sensitiveMode: "redact", promptInjectionMode: "ignore" }); return asRecord(validation.value) ?? undefined; } function normalizeMcpToolResult( result: unknown, transport: "mcp_http" | "local_stdio" | "cognee_cloud" = "mcp_http", spawnedLocalProcess = false, sourceTemplateKey?: string | null, ) { const record = asRecord(result); if (!record) throw malformedRemoteMcpResponse(); const providerContent = normalizeMcpContent(record.content); const githubFailure = record.isError === true ? githubAccessError(sourceTemplateKey, providerContent) : null; const googleWorkspacePermissionDenied = record.isError === true && (sourceTemplateKey === "gmail" || sourceTemplateKey?.startsWith("google-") === true) && /caller does not have permission/i.test(providerContent); const content = googleWorkspacePermissionDenied ? "Google rejected this call. Google Workspace MCP is a Developer Preview: enroll the signed-in Workspace account and this OAuth client's Google Cloud project in Google's Developer Preview Program, wait for Google's registration confirmation, then reconnect and try again." : providerContent; const normalized = { content, data: { content: record.content, structuredContent: record.structuredContent ?? null, isError: record.isError === true, transport, spawnedLocalProcess, }, ...(record.isError === true ? { error: "MCP tool returned an error result", ...githubFailure } : {}), }; // `_meta` is for MCP Apps views only. It rides beside the result, never in // it, so no agent-facing path can return it. const meta = asRecord(record._meta); if (meta) mcpResultMetaByResult.set(normalized, meta); return normalized; } function toolResultErrorMessage(result: Record, failureInstructions?: string) { const message = String(result.content || result.error); return failureInstructions ? `${message}\n\n${failureInstructions}` : message; } // ── MCP Tasks (io.modelcontextprotocol/tasks) ───────────────────────────── // A provider may answer tools/call with a durable task. The live call waits // on it up to the normal tool timeout; past that the row keeps it, background // work keeps polling, and the same call (same request, grant, and agent) // attaches to it instead of starting the work again. One owner at a time // holds a task (a lease): a live call or the background worker. type McpTaskRow = typeof toolMcpTasks.$inferSelect; type McpTaskWake = (task: { companyId: string; agentId: string; issueId: string; taskRecordId: string; toolName: string; status: string; /** Distinct per reason, so one wake is requested per settlement or new question. */ wakeKey: string; }) => Promise; /** A call that ended with one of these may attach to its task on a retry with the same key. */ const MCP_TASK_RETRY_CODES = new Set(["provider_task_pending", "provider_interaction_required", "provider_input_required", "elicitation_required"]); /** How long a settled task waits for the agent's run to end before a wake is reconsidered. */ const MCP_TASK_WAKE_RECHECK_MS = 2 * 60_000; /** How long a settled, undelivered task can still be collected by the same call. */ const MCP_TASK_SETTLED_ATTACH_MS = 60 * 60_000; /** A completed result is held for the call recording it; if that call dies, the task is collectable again after this. */ const MCP_TASK_DELIVERY_LEASE_MS = 2 * 60_000; /** The background worker's hold on a task, and its bound on one provider request. */ const MCP_TASK_WORKER_LEASE_MS = 60_000; const MCP_TASK_WORKER_REQUEST_MS = 30_000; /** At most this many wakes per task for new input requests, this far apart. */ const MCP_TASK_MAX_INPUT_WAKES = 3; const MCP_TASK_INPUT_WAKE_SPACING_MS = 30 * 60_000; /** At most this many question cards per task, whatever keys the provider sends. */ const MCP_TASK_MAX_CARDS = 10; /** Provider-chosen keys kept per task; older ones drop off first. */ const boundedMcpTaskKeys = (keys: Iterable) => [...new Set(keys)].slice(-64); const mcpTaskSecret = () => options.toolActionSigningSecret?.trim() || resolveToolActionSigningSecret(); /** The experimental setting (default off). Off: the extension is never declared and nothing about tasks runs. */ const mcpTasksEnabled = async () => (await instanceSettingsService(db).getExperimental().catch(() => null))?.enableMcpTasks === true; const mcpTaskScope = (row: Pick) => ({ companyId: row.companyId, connectionId: row.connectionId }); const mcpTaskInputKey = (row: McpTaskRow, key: string) => `mcp-task-input:${row.id}:${createHash("sha256").update(key).digest("hex").slice(0, 32)}`; const mcpTaskArgumentsIdentity = (parameters: unknown) => toolRequestIdentityHash(parameters ?? {}, options.toolActionSigningSecret); function mcpTaskPendingError() { return new ToolGatewayHttpError(504, "The app is still working on this. Paperclip keeps track of it: call this tool again with the same arguments to get the result. Changing the arguments starts the work over.", "provider_task_pending"); } function mcpTaskExpiredError() { return new ToolGatewayHttpError(410, "The app no longer has this action's result: it expired or was removed. Run the action again to start it over.", "provider_task_expired"); } function mcpTaskCancelledError(byRun = false) { return new ToolGatewayHttpError(409, byRun ? "The run was stopped, so Paperclip asked the app to cancel this action." : "This action was cancelled before it finished. Run it again if it is still needed.", "provider_task_cancelled"); } function mcpTaskFailedError(error: McpTaskState["error"]) { const detail = error?.message ? redactSensitiveText(error.message).replace(/\s+/g, " ").trim().slice(0, 500) : ""; return new ToolGatewayHttpError(502, detail ? `The app reported that this action failed: ${detail}` : "The app reported that this action failed.", "provider_task_failed", { code: error?.code ?? null }); } function mcpTaskNeedsInputError() { return new ToolGatewayHttpError(409, "This app needs information Paperclip can't collect yet. Complete the step in the app, then call this tool again with the same arguments.", "provider_input_required"); } function mcpTaskTransport(input: { protocolVersion: string; headers: (forceRefresh: boolean) => Promise>; refreshable: boolean; send: (init: RequestInit) => Promise; }): McpTaskTransport { const withVersion = async (forceRefresh: boolean) => ({ ...(await input.headers(forceRefresh)), "MCP-Protocol-Version": input.protocolVersion }); return { headers: () => withVersion(false), ...(input.refreshable ? { refreshHeaders: () => withVersion(true) } : {}), send: input.send, maxBytes: MAX_REMOTE_MCP_RESPONSE_BYTES, }; } /** * Update a task row. With `owner`, the write applies only while that owner * still holds the task; the result says whether it did. */ async function updateMcpTask(row: McpTaskRow, patch: Partial, opts: { notify?: boolean; owner?: string } = {}) { const write = async (tx: Db) => { if (opts.notify) await notifyDeliveryWork(tx, DELIVERY_QUEUES.mcpTasks); const [updated] = await tx.update(toolMcpTasks).set({ ...patch, updatedAt: new Date() }) .where(and( eq(toolMcpTasks.id, row.id), eq(toolMcpTasks.companyId, row.companyId), ...(opts.owner ? [eq(toolMcpTasks.leaseOwner, opts.owner)] : []), )).returning(); if (updated) Object.assign(row, updated); return Boolean(updated); }; return opts.notify ? db.transaction(async (tx) => write(tx as unknown as Db)) : write(db); } /** Take an undelivered task for `owner` unless someone else holds it. */ async function claimMcpTask(row: McpTaskRow, owner: string, leaseMs: number, patch: Partial = {}) { const now = new Date(); const [claimed] = await db.update(toolMcpTasks).set({ ...patch, leaseOwner: owner, leaseExpiresAt: new Date(now.getTime() + leaseMs), updatedAt: now }) .where(and( eq(toolMcpTasks.id, row.id), eq(toolMcpTasks.companyId, row.companyId), isNull(toolMcpTasks.deliveredAt), or(isNull(toolMcpTasks.leaseExpiresAt), lte(toolMcpTasks.leaseExpiresAt, now), eq(toolMcpTasks.leaseOwner, owner)), )).returning(); return claimed ?? null; } function mcpTaskStatePatch(row: McpTaskRow, state: McpTaskState): Partial { return { status: state.status, lastPolledAt: new Date(), pollFailures: 0, ...(state.pollIntervalMs !== null ? { pollIntervalMs: state.pollIntervalMs } : {}), // The TTL may change over a task's life; it counts from creation, and // the seven-day cap counts from when Paperclip first saw the task. ...(state.ttlMs !== null && state.ttlMs !== row.ttlMs ? { ttlMs: state.ttlMs, expiresAt: mcpTaskExpiresAt({ createdAt: state.createdAt ?? row.createdAt, ttlMs: state.ttlMs }, Date.now(), row.createdAt) } : {}), }; } /** Mark a task finished and release it. `delivered` when this call reported the outcome. */ function settleMcpTask(row: McpTaskRow, status: McpTaskRecordStatus, input: { errorCode?: string | null; delivered?: boolean; invocationId?: string; owner?: string } = {}) { return updateMcpTask(row, { status, nextPollAt: null, leaseExpiresAt: null, leaseOwner: null, errorCode: input.errorCode ?? null, ...(input.delivered ? { deliveredAt: new Date() } : {}), ...(input.invocationId ? { lastInvocationId: input.invocationId } : {}), }, { owner: input.owner }); } /** Hand a task the live call stopped waiting on to background polling. */ function releaseMcpTask(row: McpTaskRow, owner: string) { return updateMcpTask(row, { leaseExpiresAt: null, leaseOwner: null, nextPollAt: new Date(Date.now() + backgroundPollDelayMs({ pollIntervalMs: row.pollIntervalMs, status: row.status as McpTaskRecordStatus })), }, { notify: true, owner }); } /** * Record that the call `invocationId` has recorded a task's result. Until * then a completed task stays collectable, so a crash between reading the * result and recording it loses nothing. */ async function markMcpTaskDelivered(companyId: string, invocationId: string) { await db.update(toolMcpTasks).set({ deliveredAt: new Date(), nextPollAt: null, leaseExpiresAt: null, leaseOwner: null, updatedAt: new Date() }) .where(and(eq(toolMcpTasks.companyId, companyId), eq(toolMcpTasks.lastInvocationId, invocationId), isNull(toolMcpTasks.deliveredAt))); } async function createMcpTaskRecord(input: { session: ToolGatewaySession; connection: typeof toolConnections.$inferSelect; grant: typeof connectionGrants.$inferSelect; catalogToolName: string; invocationId: string; requestHash: string; argumentsIdentity: string; endpointHash: string; callerHeaders: Record; protocolVersion: string; state: McpTaskState; owner: string; leaseMs: number; }): Promise { const secret = mcpTaskSecret(); const scope = mcpTaskScope({ companyId: input.connection.companyId, connectionId: input.connection.id }); const providerTaskIdHash = mcpTaskIdIndex(secret, scope, input.state.taskId); // The person whose grant applied: carried by the session, or by its run. const [run] = !input.session.responsibleUserId && input.session.runId ? await db.select({ responsibleUserId: heartbeatRuns.responsibleUserId }).from(heartbeatRuns) .where(and(eq(heartbeatRuns.id, input.session.runId), eq(heartbeatRuns.companyId, input.session.companyId))).limit(1) : []; const responsibleUserId = input.session.responsibleUserId ?? run?.responsibleUserId ?? null; const now = Date.now(); const inserted = await db.transaction(async (tx) => { await notifyDeliveryWork(tx, DELIVERY_QUEUES.mcpTasks); const [row] = await tx.insert(toolMcpTasks).values({ companyId: input.connection.companyId, invocationId: input.invocationId, lastInvocationId: input.invocationId, connectionId: input.connection.id, grantId: input.grant.id, agentId: input.session.agentId, issueId: input.session.issueId, runId: input.session.runId, actorType: input.session.actorType ?? "agent", actorId: input.session.actorId ?? null, responsibleUserId, identityContextId: input.session.identityContextId ?? null, catalogToolName: input.catalogToolName, requestHash: input.requestHash, argumentsIdentity: input.argumentsIdentity, endpointHash: input.endpointHash, sealedCallerHeaders: Object.keys(input.callerHeaders).length ? sealMcpTaskId(secret, scope, JSON.stringify(input.callerHeaders)) : null, protocolVersion: input.protocolVersion, sealedProviderTaskId: sealMcpTaskId(secret, scope, input.state.taskId), providerTaskIdHash, status: input.state.status, pollIntervalMs: input.state.pollIntervalMs, ttlMs: input.state.ttlMs, expiresAt: mcpTaskExpiresAt(input.state, now), nextPollAt: new Date(now + backgroundPollDelayMs({ pollIntervalMs: input.state.pollIntervalMs, status: input.state.status })), leaseOwner: input.owner, leaseExpiresAt: new Date(now + input.leaseMs), }).onConflictDoNothing().returning(); return row; }); if (inserted) { await writeAudit({ session: input.session, companyId: input.session.companyId, agentId: input.session.agentId, runId: input.session.runId, issueId: input.session.issueId, action: "tool_gateway.task_started", details: { invocationId: input.invocationId, taskRecordId: inserted.id, connectionId: input.connection.id, tool: input.catalogToolName }, }); return inserted; } // A server that hands out a task it already gave Paperclip must have given // it for the same request and credentials; anything else is refused. const [existing] = await db.select().from(toolMcpTasks).where(and( eq(toolMcpTasks.companyId, input.connection.companyId), eq(toolMcpTasks.connectionId, input.connection.id), eq(toolMcpTasks.providerTaskIdHash, providerTaskIdHash))); if (!existing || existing.grantId !== input.grant.id || existing.requestHash !== input.requestHash) throw malformedRemoteMcpResponse(); const claimed = await claimMcpTask(existing, input.owner, input.leaseMs, { lastInvocationId: input.invocationId, runId: input.session.runId }); if (!claimed) throw mcpTaskPendingError(); return claimed; } /** The forwarded caller headers a connection allows, normalized: they route a call, so they are part of a task's identity. */ function mcpTaskCallerHeaders(connection: typeof toolConnections.$inferSelect, callerHeaders: ExecuteGatewayToolInput["callerHeaders"]) { const allowed = new Set(readHeaderPolicy(connection).passthroughAllowlist.map((name) => name.toLowerCase())); return Object.fromEntries(Object.entries(normalizeCallerHeaders(callerHeaders)) .filter(([name]) => allowed.has(name.toLowerCase())) .map(([name, value]) => [name.toLowerCase(), value] as const) .sort(([a], [b]) => a.localeCompare(b))); } /** Undelivered, and still worth collecting: active, or settled recently. */ const mcpTaskCollectable = () => and( isNull(toolMcpTasks.deliveredAt), // A settled task is collected soon after it settles; an old one is not // silently handed to what may be a deliberate new run of the same call. or(inArray(toolMcpTasks.status, ["working", "input_required"]), gt(toolMcpTasks.updatedAt, new Date(Date.now() - MCP_TASK_SETTLED_ATTACH_MS))), ); /** An undelivered task this exact call already started, for this grant, agent, and task. */ async function findAttachableMcpTask(input: { session: ToolGatewaySession; connectionId: string; grantId: string; requestHash: string; rowId?: string; }): Promise { const [row] = await db.select().from(toolMcpTasks).where(and( eq(toolMcpTasks.companyId, input.session.companyId), ...(input.rowId ? [eq(toolMcpTasks.id, input.rowId)] : []), eq(toolMcpTasks.connectionId, input.connectionId), eq(toolMcpTasks.requestHash, input.requestHash), eq(toolMcpTasks.grantId, input.grantId), input.session.agentId ? eq(toolMcpTasks.agentId, input.session.agentId) : isNull(toolMcpTasks.agentId), input.session.issueId ? eq(toolMcpTasks.issueId, input.session.issueId) : isNull(toolMcpTasks.issueId), eq(toolMcpTasks.actorType, input.session.actorType ?? "agent"), input.session.actorId ? eq(toolMcpTasks.actorId, input.session.actorId) : isNull(toolMcpTasks.actorId), mcpTaskCollectable(), )).orderBy(desc(toolMcpTasks.createdAt)).limit(1); return row ?? null; } /** * The task a keyed retry should collect, checked before the call changes * anything. A call interrupted mid-wait (a crash) left its invocation * executing with no error; that counts too. A different request under the * same key is a conflict and leaves the original retry intact. */ async function mcpTaskForKeyedRetry(companyId: string, invocation: typeof toolInvocations.$inferSelect, current: { connectionId: string | null; argumentsIdentity: string; callerHeaders: ExecuteGatewayToolInput["callerHeaders"]; }) { const interrupted = invocation.status === "executing" && !invocation.errorCode; if (!interrupted && (!invocation.errorCode || !MCP_TASK_RETRY_CODES.has(invocation.errorCode))) return null; const [row] = await db.select({ id: toolMcpTasks.id, companyId: toolMcpTasks.companyId, connectionId: toolMcpTasks.connectionId, argumentsIdentity: toolMcpTasks.argumentsIdentity, sealedCallerHeaders: toolMcpTasks.sealedCallerHeaders }) .from(toolMcpTasks).where(and( eq(toolMcpTasks.companyId, companyId), or(eq(toolMcpTasks.invocationId, invocation.id), eq(toolMcpTasks.lastInvocationId, invocation.id)), mcpTaskCollectable(), )).orderBy(desc(toolMcpTasks.createdAt)).limit(1); if (!row) return null; // The forwarded routing headers (such as a tenant) must match too, checked // before anything changes so a mismatch leaves the original retry intact. const [connection] = await db.select().from(toolConnections) .where(and(eq(toolConnections.id, row.connectionId), eq(toolConnections.companyId, companyId))).limit(1); const stored = row.sealedCallerHeaders ? openMcpTaskId(mcpTaskSecret(), mcpTaskScope(row), row.sealedCallerHeaders) : "{}"; const sameRouting = Boolean(connection) && stored !== null && JSON.stringify(mcpTaskCallerHeaders(connection!, current.callerHeaders)) === JSON.stringify(JSON.parse(stored)); if (row.connectionId !== current.connectionId || row.argumentsIdentity !== current.argumentsIdentity || !sameRouting) { throw new ToolGatewayHttpError(409, "This idempotency key belongs to an earlier call with different arguments. Use a new key to start new work.", "idempotency_key_conflict"); } return row.id; } type McpTaskInputPlan = { /** Responses ready to send with tasks/update. */ responses: Record; links: ToolUpstreamPending["links"]; linkKeys: string[]; linkMessage?: string; /** The first form still waiting for a person. */ waitingForm?: { key: string; request: McpElicitationRequest; hasCard: boolean }; unsupported: boolean; }; /** * Decide what Paperclip can do with a task's input requests. URL requests * become the provider link a person opens; Paperclip never answers them, as * for a direct request. Form requests become a question card, and only a * person's answer on that card is sent back. Anything else needs the app. */ async function planMcpTaskInput(row: McpTaskRow, state: McpTaskState, answered: ReadonlySet): Promise { const plan: McpTaskInputPlan = { responses: {}, links: [], linkKeys: [], unsupported: false }; for (const [key, request] of Object.entries(state.inputRequests ?? {})) { if (answered.has(key)) continue; const mode = request.params.mode; if (request.method === "elicitation/create" && mode === "url") { const checked = checkOAuthEndpointUrl(request.params.url); if (!checked.ok) return { ...plan, unsupported: true }; if (!plan.links.some((link) => link.url === checked.url)) plan.links.push({ url: checked.url, host: checked.host }); plan.linkKeys.push(key); if (!plan.linkMessage && typeof request.params.message === "string") plan.linkMessage = redactSensitiveText(request.params.message).slice(0, 4000); continue; } if (request.method !== "elicitation/create" || (mode !== undefined && mode !== "form") || !row.issueId) return { ...plan, unsupported: true }; const form = { key, request: { message: stringValue(request.params.message) ?? "The app needs more information before it can continue.", requestedSchema: asRecord(request.params.requestedSchema), raw: request.params, }, }; // A secret or a shape the card can't show is never put on a card. if (!buildElicitationQuestionSet({ appName: "app", request: form.request }).ok) return { ...plan, unsupported: true }; const [card] = await db.select({ status: issueThreadInteractions.status, result: issueThreadInteractions.result, payload: issueThreadInteractions.payload }) .from(issueThreadInteractions).where(and( eq(issueThreadInteractions.companyId, row.companyId), eq(issueThreadInteractions.issueId, row.issueId), eq(issueThreadInteractions.idempotencyKey, mcpTaskInputKey(row, key)), )).limit(1); const response = elicitationResponseForCard(form.request, card); if (!response) { plan.waitingForm ??= { ...form, hasCard: Boolean(card) }; continue; } plan.responses[key] = response; } if (plan.links.length > MCP_MAX_INPUT_LINKS) plan.unsupported = true; return plan; } async function sendMcpTaskResponses(row: McpTaskRow, owner: string, session: ToolGatewaySession, transport: McpTaskTransport, taskId: string, plan: McpTaskInputPlan, answered: Set, signal?: AbortSignal) { const keys = Object.keys(plan.responses); if (!keys.length) return; await sendMcpTaskRequest(transport, "tasks/update", { taskId, inputResponses: plan.responses }, signal); for (const key of keys) answered.add(key); await updateMcpTask(row, { answeredInputKeys: boundedMcpTaskKeys(answered) }, { owner }); await writeAudit({ session, companyId: row.companyId, agentId: row.agentId, runId: row.runId, issueId: row.issueId, action: "tool_gateway.task_input_sent", details: { invocationId: row.invocationId, taskRecordId: row.id, connectionId: row.connectionId, tool: row.catalogToolName, // Which kind of answer went back, never what the person wrote. responses: keys.map((key) => asRecord(plan.responses[key])?.action ?? null), }, }); } async function cancelMcpTaskRecord(row: McpTaskRow, owner: string, transport: McpTaskTransport | null, taskId: string | null, reason: "run_cancelled" | "issue_closed", session: ToolGatewaySession, delivered: boolean) { const acknowledged = transport && taskId ? await cancelMcpTask(transport, taskId) : false; await settleMcpTask(row, "cancelled", { errorCode: reason, delivered, owner }); await writeAudit({ session, companyId: row.companyId, agentId: row.agentId, runId: row.runId, issueId: row.issueId, action: "tool_gateway.task_cancelled", details: { invocationId: row.invocationId, taskRecordId: row.id, connectionId: row.connectionId, tool: row.catalogToolName, reason, acknowledged }, }); } /** * Wait on a task inside a live call that holds it (`owner`). Returns the * provider's final tool result, exactly what a synchronous call would have * returned, or throws the error the caller should see. The task stays * durable when the wait ends; a completed one stays collectable until the * caller records its result (markMcpTaskDelivered). */ async function waitForMcpTask(wait: { row: McpTaskRow; owner: string; taskId: string; initial?: McpTaskState; session: ToolGatewaySession; tool: ToolGatewayDescriptor; invocationId: string; transport: McpTaskTransport; deadline: AbortSignal; runSignal?: AbortSignal; callerSignal?: AbortSignal; execution: RemoteHttpExecutionAudit; }): Promise> { const { row, owner } = wait; const stop = AbortSignal.any([wait.deadline, ...(wait.callerSignal ? [wait.callerSignal] : []), ...(wait.runSignal ? [wait.runSignal] : [])]); const answered = new Set(row.answeredInputKeys ?? []); const audit = { recordId: row.id, attached: !wait.initial, polls: 0, status: row.status }; wait.execution.task = audit; const own = (patch: Partial) => updateMcpTask(row, patch, { owner }); const settle = (status: McpTaskRecordStatus, errorCode?: string | null) => settleMcpTask(row, status, { errorCode, delivered: true, invocationId: wait.invocationId, owner }); const cancelForRun = async (): Promise => { await cancelMcpTaskRecord(row, owner, wait.transport, wait.taskId, "run_cancelled", wait.session, true); throw mcpTaskCancelledError(true); }; try { // Paperclip's own outcomes are reported as they are: an expired task is // gone, and a task Paperclip cancelled is never revived by a later poll. if (row.status === "expired") { await settle("expired", row.errorCode ?? "ttl_expired"); throw mcpTaskExpiredError(); } if (row.status === "cancelled") { await settle("cancelled", row.errorCode); throw mcpTaskCancelledError(row.errorCode === "run_cancelled"); } let delay = wait.initial?.status === "working" ? inlinePollDelayMs(row.pollIntervalMs) : 0; let failures = 0; for (;;) { if (delay > 0 && !(await waitForPoll(delay, stop))) { if (wait.runSignal?.aborted) return await cancelForRun(); throw mcpTaskPendingError(); } if (wait.runSignal?.aborted) return await cancelForRun(); if (row.expiresAt.getTime() <= Date.now()) { await settle("expired", "ttl_expired"); throw mcpTaskExpiredError(); } let state: McpTaskState; try { state = await getMcpTask(wait.transport, wait.taskId, stop); audit.polls += 1; failures = 0; } catch (error) { if (wait.runSignal?.aborted) return await cancelForRun(); if (stop.aborted) throw mcpTaskPendingError(); if (error instanceof McpTaskRequestError && error.taskNotFound) { await settle("expired", "provider_task_unknown"); throw mcpTaskExpiredError(); } if (error instanceof ToolGatewayHttpError) throw error; // A transient failure: the task is still durable, so back off and // leave it to background polling if the app stays unreachable. failures += 1; await own({ pollFailures: row.pollFailures + 1 }); if (failures >= 3) throw mcpTaskPendingError(); delay = inlinePollDelayMs(row.pollIntervalMs) * 2 ** failures; continue; } // Losing the task to another owner (a long stall past the lease) ends this wait. if (!(await own(mcpTaskStatePatch(row, state)))) throw mcpTaskPendingError(); audit.status = state.status; if (state.status === "completed") { // Held for this call until its result is recorded; not yet delivered. // If this process dies first, background work finds it when the hold // ends and wakes the agent to collect it. const holdUntil = new Date(Date.now() + MCP_TASK_DELIVERY_LEASE_MS); await own({ nextPollAt: holdUntil, errorCode: null, lastInvocationId: wait.invocationId, leaseExpiresAt: holdUntil }); return state.result!; } if (state.status === "failed") { await settle("failed"); throw mcpTaskFailedError(state.error); } if (state.status === "cancelled") { await settle("cancelled"); throw mcpTaskCancelledError(); } if (state.status === "input_required") { const plan = await planMcpTaskInput(row, state, answered); if (plan.unsupported) throw mcpTaskNeedsInputError(); try { await sendMcpTaskResponses(row, owner, wait.session, wait.transport, wait.taskId, plan, answered, stop); } catch (error) { if (error instanceof McpTaskRequestError && error.taskNotFound) { await settle("expired", "provider_task_unknown"); throw mcpTaskExpiredError(); } // Unsent answers stay unanswered and are sent on the next poll. if (stop.aborted) throw mcpTaskPendingError(); } // A form counts as shown only once its card exists. if (plan.waitingForm && !plan.waitingForm.hasCard && row.issueId) { await createElicitationCard({ companyId: row.companyId, issueId: row.issueId, agentId: row.agentId, appName: await elicitationAppName(row.companyId, row.connectionId, wait.tool), request: plan.waitingForm.request, idempotencyKey: mcpTaskInputKey(row, plan.waitingForm.key), }); } const shown = [...plan.linkKeys, ...(plan.waitingForm ? [plan.waitingForm.key] : [])]; if (shown.length) await own({ surfacedInputKeys: boundedMcpTaskKeys([...(row.surfacedInputKeys ?? []), ...shown]) }); if (plan.links.length) { const pending: ToolUpstreamPending = { kind: "authorization", links: plan.links, ...(plan.linkMessage ? { message: plan.linkMessage } : {}) }; await retainUpstreamHandoff(wait.invocationId, pending); throw new ToolGatewayHttpError(409, "Complete the provider's authorization or approval, then call this tool again with the same arguments to continue.", "provider_interaction_required", { upstreamPending: pending, invocationId: wait.invocationId }); } if (plan.waitingForm) { await requestElicitationForRecordedToolCall({ session: wait.session, tool: wait.tool, invocationId: wait.invocationId, request: plan.waitingForm.request, idempotencyKey: mcpTaskInputKey(row, plan.waitingForm.key), connectionId: row.connectionId, }); } } delay = inlinePollDelayMs(row.pollIntervalMs); } } finally { if (!isMcpTaskTerminal(row.status as McpTaskRecordStatus)) await releaseMcpTask(row, owner); } } /** The credentials, endpoint, and identity a stored task was created with, if they all still hold. */ async function storedMcpTaskContext(row: McpTaskRow): Promise< { session: ToolGatewaySession; transport: McpTaskTransport; taskId: string } | { closed: string } > { const taskId = openMcpTaskId(mcpTaskSecret(), mcpTaskScope(row), row.sealedProviderTaskId); if (!taskId) return { closed: "task_unreadable" }; const [connection] = await db.select().from(toolConnections) .where(and(eq(toolConnections.id, row.connectionId), eq(toolConnections.companyId, row.companyId))).limit(1); if (!connection || !connection.enabled || connection.status !== "active" || connection.transport !== "mcp_remote") return { closed: "connection_unavailable" }; const session: ToolGatewaySession = { id: `mcp-task:${row.id}`, token: "", companyId: row.companyId, agentId: row.agentId, runId: row.runId, issueId: row.issueId, projectId: null, actorType: row.actorType as ToolGatewaySession["actorType"], actorId: row.actorId, responsibleUserId: row.responsibleUserId, identityContextId: row.identityContextId, createdAt: new Date(), expiresAt: new Date(Date.now() + 5 * 60_000), }; // The same access check a live call makes, as the same caller: audience, // delegation, and the grant itself. Removing any of them stops the work; // any other failure (a database blip) is retried with backoff. let grant: typeof connectionGrants.$inferSelect; try { grant = await resolveConnectionGrant(session, connection, false); } catch (error) { if (error instanceof ToolGatewayHttpError) return { closed: "access_removed" }; throw error; } if (grant.id !== row.grantId || grant.status !== "active") return { closed: "access_removed" }; const workspaceTarget = connection.config.sourceTemplateKey === "google-workspace" ? googleWorkspaceToolTarget(row.catalogToolName) : null; const endpoint = workspaceTarget?.serverUrl ?? await resolvedRemoteEndpoint(session, connection, grant); if (mcpTaskEndpointHash(String(endpoint)) !== row.endpointHash) return { closed: "endpoint_changed" }; // The allowed forwarded headers the call was made with, so background polls route the same way. const openedCallerHeaders = row.sealedCallerHeaders ? openMcpTaskId(mcpTaskSecret(), mcpTaskScope(row), row.sealedCallerHeaders) : null; if (row.sealedCallerHeaders && !openedCallerHeaders) return { closed: "task_unreadable" }; const callerHeaders = openedCallerHeaders ? JSON.parse(openedCallerHeaders) as Record : undefined; const transport = mcpTaskTransport({ protocolVersion: row.protocolVersion, refreshable: connection.authKind === "oauth", headers: async (forceRefresh) => buildRemoteHeaders({ session, connection, callerHeaders, credentialHeaders: { ...projectedConnectionHeaders(connection), ...(await resolveCredentialHeaders(session, connection, grant, { forceRefresh })) }, }).headers, send: (init) => options.remoteHttpRequest ? options.remoteHttpRequest(String(endpoint), init) : guardedRemoteHttpFetch(String(endpoint), init, remoteHttpFetchOptions()), }); return { session, transport, taskId }; } /** Why a task nobody waits on should be cancelled: its task closed or its run was stopped. */ async function mcpTaskStopReason(row: McpTaskRow): Promise<"issue_closed" | "run_cancelled" | null> { if (row.issueId) { const [issue] = await db.select({ status: issues.status }).from(issues) .where(and(eq(issues.id, row.issueId), eq(issues.companyId, row.companyId))).limit(1); if (!issue || issue.status === "done" || issue.status === "cancelled") return "issue_closed"; } if (row.runId) { const [run] = await db.select({ status: heartbeatRuns.status }).from(heartbeatRuns) .where(and(eq(heartbeatRuns.id, row.runId), eq(heartbeatRuns.companyId, row.companyId))).limit(1); if (run?.status === "cancelled") return "run_cancelled"; } return null; } /** * Wake the task's agent once its run has ended, so the agent's repeated call * collects the outcome or shows a new question. "deferred" while the run is * still going, "skipped" when nobody should be woken. */ async function wakeAgentForMcpTask(row: McpTaskRow, wake: McpTaskWake | undefined, wakeKey: string): Promise<"woken" | "deferred" | "skipped"> { if (!wake || !row.issueId || !row.agentId || row.expiresAt.getTime() <= Date.now()) return "skipped"; const [issue] = await db.select({ status: issues.status, assigneeAgentId: issues.assigneeAgentId }).from(issues) .where(and(eq(issues.id, row.issueId), eq(issues.companyId, row.companyId))).limit(1); if (!issue || issue.status === "done" || issue.status === "cancelled" || issue.assigneeAgentId !== row.agentId) return "skipped"; if (row.runId) { const [run] = await db.select({ status: heartbeatRuns.status }).from(heartbeatRuns) .where(and(eq(heartbeatRuns.id, row.runId), eq(heartbeatRuns.companyId, row.companyId))).limit(1); if (run && ["queued", "running", "scheduled_retry"].includes(run.status)) return "deferred"; } // The wake request row is the durable receipt: a pass that crashed after // waking (before recording it here) finds it and never wakes twice. const [receipt] = await db.select({ id: agentWakeupRequests.id }).from(agentWakeupRequests).where(and( eq(agentWakeupRequests.companyId, row.companyId), eq(agentWakeupRequests.agentId, row.agentId), eq(agentWakeupRequests.idempotencyKey, wakeKey))).limit(1); if (!receipt) await wake({ companyId: row.companyId, agentId: row.agentId, issueId: row.issueId, taskRecordId: row.id, toolName: row.catalogToolName, status: row.status, wakeKey }); return "woken"; } /** A task settled while nobody was waiting: wake its agent once. */ async function wakeForSettledMcpTask(row: McpTaskRow, owner: string, wake?: McpTaskWake) { const done = () => updateMcpTask(row, { nextPollAt: null, leaseExpiresAt: null, leaseOwner: null }, { owner }); if (row.deliveredAt || row.wakeRequestedAt || row.status === "expired" || row.status === "cancelled" || row.updatedAt.getTime() < Date.now() - MCP_TASK_SETTLED_ATTACH_MS) return done(); const outcome = await wakeAgentForMcpTask(row, wake, `mcp-task:${row.id}:settled`); if (outcome === "deferred") { return updateMcpTask(row, { leaseExpiresAt: null, leaseOwner: null, nextPollAt: new Date(Date.now() + MCP_TASK_WAKE_RECHECK_MS) }, { owner }); } return updateMcpTask(row, { ...(outcome === "woken" ? { wakeRequestedAt: new Date() } : {}), nextPollAt: null, leaseExpiresAt: null, leaseOwner: null }, { owner }); } /** One background step for a task the worker holds (`owner`). */ async function pollStoredMcpTask(row: McpTaskRow, owner: string, wake: McpTaskWake | undefined, signal?: AbortSignal) { const settle = (status: McpTaskRecordStatus, errorCode: string) => settleMcpTask(row, status, { errorCode, owner }); if (row.deliveredAt) return updateMcpTask(row, { nextPollAt: null, leaseExpiresAt: null, leaseOwner: null }, { owner }); if (isMcpTaskTerminal(row.status as McpTaskRecordStatus)) return wakeForSettledMcpTask(row, owner, wake); if (row.expiresAt.getTime() <= Date.now()) return settle("expired", "ttl_expired"); const context = await storedMcpTaskContext(row); if ("closed" in context) return settle("expired", context.closed); const stopReason = await mcpTaskStopReason(row); if (stopReason) return cancelMcpTaskRecord(row, owner, context.transport, context.taskId, stopReason, context.session, false); // One slow or endless response must not hold the worker past its lease or the task past its TTL. const bound = Math.max(1_000, Math.min(MCP_TASK_WORKER_REQUEST_MS, row.expiresAt.getTime() - Date.now())); const requestSignal = AbortSignal.any([AbortSignal.timeout(bound), ...(signal ? [signal] : [])]); let state: McpTaskState; try { state = await getMcpTask(context.transport, context.taskId, requestSignal); } catch (error) { if (error instanceof McpTaskRequestError && error.taskNotFound) return settle("expired", "provider_task_unknown"); return updateMcpTask(row, { leaseExpiresAt: null, leaseOwner: null, pollFailures: row.pollFailures + 1, nextPollAt: new Date(Date.now() + backgroundPollDelayMs({ pollIntervalMs: row.pollIntervalMs, status: row.status as McpTaskRecordStatus, failures: row.pollFailures + 1 })), }, { owner }); } if (!(await updateMcpTask(row, { ...mcpTaskStatePatch(row, state), errorCode: null }, { owner }))) return; // The result stays with the provider; the agent's repeated call reads it. if (isMcpTaskTerminal(state.status)) return wakeForSettledMcpTask(row, owner, wake); if (state.status === "input_required") { const answered = new Set(row.answeredInputKeys ?? []); const plan = await planMcpTaskInput(row, state, answered); // A person may have answered the question card since the call ended. if (!plan.unsupported) { await sendMcpTaskResponses(row, owner, context.session, context.transport, context.taskId, plan, answered, requestSignal).catch(() => undefined); } // A new question or link nobody has seen: wake the agent, whose call // shows it. Keys come from the provider, so wakes per task are capped // and spaced; a provider rotating keys cannot keep waking the agent. const surfaced = new Set(row.surfacedInputKeys ?? []); // A form question is put on a card right away, so a person sees it even // when no wake is left for this task; answering the card wakes the agent. // A missing card is (re)created even if the question was marked shown: a // crash between marking and creating must not hide it. const cardCount = plan.waitingForm && row.issueId && !plan.waitingForm.hasCard ? (await db.select({ count: sql`count(*)::int` }).from(issueThreadInteractions).where(and( eq(issueThreadInteractions.companyId, row.companyId), eq(issueThreadInteractions.issueId, row.issueId), sql`${issueThreadInteractions.idempotencyKey} like ${`mcp-task-input:${row.id}:%`}`)))[0]?.count ?? 0 : Infinity; if (!plan.unsupported && plan.waitingForm && row.issueId && cardCount < MCP_TASK_MAX_CARDS) { const card = await createElicitationCard({ companyId: row.companyId, issueId: row.issueId, agentId: row.agentId, appName: await elicitationAppName(row.companyId, row.connectionId), request: plan.waitingForm.request, idempotencyKey: mcpTaskInputKey(row, plan.waitingForm.key), }); surfaced.add(plan.waitingForm.key); await updateMcpTask(row, { surfacedInputKeys: boundedMcpTaskKeys(surfaced) }, { owner }); await writeAudit({ session: context.session, companyId: row.companyId, agentId: row.agentId, runId: row.runId, issueId: row.issueId, action: "tool_gateway.elicitation_requested", details: { invocationId: row.invocationId, taskRecordId: row.id, interactionId: card.id, tool: row.catalogToolName, reasonCode: "elicitation_required" }, }); } const unseen = Object.keys(state.inputRequests ?? {}).filter((key) => !answered.has(key) && !surfaced.has(key)).sort(); const wakeAllowed = row.inputWakeCount < MCP_TASK_MAX_INPUT_WAKES && (!row.inputWakeAt || row.inputWakeAt.getTime() <= Date.now() - MCP_TASK_INPUT_WAKE_SPACING_MS); if (unseen.length && wakeAllowed) { const outcome = await wakeAgentForMcpTask(row, wake, `mcp-task:${row.id}:input:${row.inputWakeCount + 1}`); if (outcome === "woken" || outcome === "skipped") { await updateMcpTask(row, { surfacedInputKeys: boundedMcpTaskKeys([...surfaced, ...unseen]), ...(outcome === "woken" ? { inputWakeCount: row.inputWakeCount + 1, inputWakeAt: new Date() } : {}), }, { owner }); } if (outcome === "deferred") { return updateMcpTask(row, { leaseExpiresAt: null, leaseOwner: null, nextPollAt: new Date(Date.now() + MCP_TASK_WAKE_RECHECK_MS) }, { owner }); } } } return updateMcpTask(row, { leaseExpiresAt: null, leaseOwner: null, nextPollAt: new Date(Date.now() + backgroundPollDelayMs({ pollIntervalMs: row.pollIntervalMs, status: row.status as McpTaskRecordStatus })), }, { owner }); } async function executeRemoteHttpTool( session: ToolGatewaySession, tool: ToolGatewayDescriptor, parameters: unknown, ms: number, invocationId: string, callerHeaders?: ExecuteGatewayToolInput["callerHeaders"], useDefaultTimeout = false, /** `run` aborts when the run is stopped (the task is cancelled); `caller` when the caller leaves (it is kept). */ taskSignals: { run?: AbortSignal; caller?: AbortSignal; attachToTaskRecordId?: string | null } = {}, ): Promise { const { entry, connection, sourceTemplateKey } = await resolveConnectedRemoteTool( session, tool, ); await assertApplicationFeatureAvailable(tool.applicationKey); // Recheck immediately before dispatch, including previously approved calls // and connections whose stored grant/catalog predates scope reduction. assertGoogleChatToolArgumentsSupported(connection, entry.toolName, parameters); assertGmailArchiveToolArgumentsSupported(connection, entry.toolName, parameters); if (useDefaultTimeout) ms = DEFAULT_REMOTE_HTTP_RESPONSE_TIMEOUT_MS; if (useDefaultTimeout && isRailwayConnection(connection) && entry.toolName === `${RAILWAY_TOOL_PREFIX}run-command`) { ms = railwayCommandBudgetMs(parameters); } const grant = await resolveConnectionGrant(session, connection); const restConnector = restConnectorFor(connection); if (restConnector) { const budgetMs = Math.min(ms, 30_000); const deadlineAt = Date.now() + budgetMs; const signal = AbortSignal.timeout(budgetMs); const client = restConnector.client(connection, await resolveCredentialHeaders(session, connection, grant), (url, init) => options.remoteHttpRequest ? options.remoteHttpRequest(url, init) : guardedRemoteHttpFetch(url, init, remoteHttpFetchOptions()), signal, deadlineAt); const data = await client.invoke(entry.toolName, parameters); return { result: { content: JSON.stringify(data), data: { structuredContent: data, transport: "rest_api" } } }; } const nativeProvider = nativeProviderCatalogFor(connection); if (nativeProvider) { const budgetMs = Math.min(ms, 30_000); const deadlineAt = Date.now() + budgetMs; const signal = AbortSignal.timeout(budgetMs); const data = await nativeProvider.execute({ binding: session, connection, headers: await resolveCredentialHeaders(session, connection, grant), request: (url, init) => options.remoteHttpRequest ? options.remoteHttpRequest(url, init) : guardedRemoteHttpFetch(url, init, remoteHttpFetchOptions()), toolName: entry.toolName, parameters, signal, deadlineAt }); return { result: { content: JSON.stringify(data), data: { structuredContent: data, transport: "rest_api" } } }; } if (isBrowserUseConnection(connection)) { const data = await browserUseService(db, options.remoteHttpRequest).execute(session, grant, invocationId!, entry.toolName, parameters); return { result: { content: JSON.stringify(data), data: { structuredContent: data, transport: "rest_api" } } }; } const workspaceTarget = connection.config.sourceTemplateKey === "google-workspace" ? googleWorkspaceToolTarget(entry.toolName) : null; // One service's call failure is not evidence that every Google endpoint is // unhealthy. The invocation still records/returns its error; catalog refresh // handles service availability, and grant checks remain authoritative. const markCallHealth = (status: Parameters[1], message: string) => workspaceTarget && status !== "ok" ? Promise.resolve() : markRemoteConnectionHealth(connection, status, message); if (connection.config.sourceTemplateKey === "google-workspace" && (!workspaceTarget || !isGoogleWorkspaceToolGranted(entry.toolName, googleWorkspaceGrantedScopes(grant)))) { throw new ToolGatewayHttpError(403, "This Google action needs a permission you have not granted. Reconnect Google Workspace to change access.", "oauth_insufficient_scope"); } const endpoint = workspaceTarget?.serverUrl ?? await resolvedRemoteEndpoint(session, connection, grant); const upstreamToolName = workspaceTarget?.upstreamName ?? entry.toolName; // Method-defined headers are trusted catalog configuration. Treat them as // managed headers so callers cannot override the scope that was reviewed // during tools/list. Credentials remain authoritative on collisions. let credentialHeaders = { ...projectedConnectionHeaders(connection), ...(await resolveCredentialHeaders(session, connection, grant)), }; let builtHeaders = buildRemoteHeaders({ session, connection, credentialHeaders, callerHeaders, }); let headers = builtHeaders.headers; let headerSummary = builtHeaders.summary; const requestId = `paperclip-tool-${randomUUID()}`; const execution: RemoteHttpExecutionAudit = { transport: "mcp_remote", request: { protocol: "MCP JSON-RPC 2.0", httpMethod: "POST", endpoint: auditSafeEndpoint(endpoint), mcpMethod: "tools/call", requestId, upstreamToolName, dispatched: true, }, }; const controller = new AbortController(); const timer = setTimeout(() => controller.abort(), ms); timer.unref?.(); const progressReporter = toolCallProgressReporterFor(session, tool, invocationId); // The cached MCP session this call used, so a failure resets only this // identity's session and leaves other agents on the connection alone. let mcpSession: { scope: string; headers: Record; sessionId: string } | undefined; // Answers to an app's question that this call is carrying back, until the app has them. let elicitationClaim: Awaited> = null; // An older app may ask several questions in turn; each answer is spent // only when the whole call finishes, so a later stop never loses one. const legacyAnswered: Array<{ row: McpElicitationRow; responses: Record }> = []; try { const dispatchRemote = async (target: string, init: RequestInit) => { // Refresh can reduce consent. Recheck the selected grant after refreshing // credentials and before every dispatch (including an authorization retry). if (workspaceTarget) { const [currentGrant] = await db.select().from(connectionGrants).where(and( eq(connectionGrants.id, grant.id), eq(connectionGrants.companyId, connection.companyId), eq(connectionGrants.connectionId, connection.id), eq(connectionGrants.status, "active"), )); if (!currentGrant || !isGoogleWorkspaceToolGranted(entry.toolName, googleWorkspaceGrantedScopes(currentGrant))) { throw new ToolGatewayHttpError(403, "This Google action is not covered by the current permission grant.", "oauth_insufficient_scope"); } } return options.remoteHttpRequest ? options.remoteHttpRequest(target, init) : guardedRemoteHttpFetch(target, init, { ...remoteHttpFetchOptions(), // This call site owns a caller-set budget that can exceed the // transport's default response deadline, so hand it down rather than // letting the tighter default cut a legitimately slow tool short. responseTimeoutMs: ms, }); }; const requireExplicitRetryAfterOAuthRefresh = async (refreshedResponse: Response): Promise => { // The provider rejected this dispatch, but automatic replay is unsafe: // a server can apply a request before returning 401. A caller retry // starts a fresh credential-scoped MCP session and dispatches once. if (mcpSession) forgetMcpHttpSession(mcpSession); await refreshedResponse.body?.cancel().catch(() => undefined); execution.response = { httpStatus: refreshedResponse.status, contentType: refreshedResponse.headers.get("content-type"), bodySizeBytes: 0, upstreamRequestId: refreshedResponse.headers.get("x-request-id") ?? refreshedResponse.headers.get("traceparent"), }; throw new ToolGatewayHttpError( 409, "The provider rejected the saved OAuth token, which has now been refreshed. Retry the action explicitly; the original call was not replayed.", "oauth_refreshed_retry_required", { connectionId: connection.id, catalogEntryId: entry.id, execution }, ); }; if (isRailwayEndpoint(connection.config.url) && normalizeRailwayToolName(entry.toolName).startsWith(RAILWAY_TOOL_PREFIX)) { if (!isRailwayConnection(connection) || connection.config.railwayApiStatus !== "available") { throw new ToolGatewayHttpError(422, "Railway API access is not verified. Refresh actions or reconnect this Railway connection.", "railway_api_not_verified"); } const ssh = asRecord(connection.config.railwaySsh); const sshRef = grant.credentialSecretRefs.find((ref) => ref.configPath === RAILWAY_SSH_SECRET_PATH); execution.request.endpoint = RAILWAY_API_URL; execution.request.protocol = entry.toolName === `${RAILWAY_TOOL_PREFIX}run-command` ? "Railway GraphQL + SSH" : "Railway GraphQL"; const client = createRailwayClient({ authorization: credentialHeaders.Authorization ?? "", signal: controller.signal, request: dispatchRemote, runCommand: ssh?.grantId === grant.id && ssh?.enabled === true && sshRef ? async (input) => runRailwaySshCommand({ ...input, privateKey: await resolveGrantSecretValue(session, connection, grant, sshRef), knownHosts: typeof ssh.knownHosts === "string" ? ssh.knownHosts : "", }) : undefined, }); const data = await client.call(entry.toolName, parameters); const record = asRecord(data); const failedCommand = entry.toolName === `${RAILWAY_TOOL_PREFIX}run-command` && (record?.exitCode !== 0 || record?.timedOut === true || record?.truncated === true); return { result: normalizeMcpToolResult({ content: [{ type: "text", text: JSON.stringify(data) }], structuredContent: data, isError: failedCommand }, "mcp_http", entry.toolName === `${RAILWAY_TOOL_PREFIX}run-command`, "railway"), headerSummary, execution, }; } // The version negotiated at catalog refresh is saved on the connection, so // a stateless (2026-07-28) server is called directly: no handshake, no // extra round trip before the tool runs. const eraKey = mcpEraKey(connection.id, endpoint); const savedProtocolVersion = asRecord(connection.config)?.mcpProtocolVersion; if (!knownMcpProtocolVersion(eraKey)) { // A connection saved as needing a session is a handshake server; it is // probed again only if it ever refuses the handshake. if (typeof savedProtocolVersion === "string") rememberMcpProtocolVersion(eraKey, savedProtocolVersion); else if (connectionRequiresMcpSession(connection)) rememberMcpProtocolVersion(eraKey, MCP_PROTOCOL_VERSION); } const sendForNegotiation = (init: RequestInit) => dispatchRemote(endpoint, { ...init, redirect: "manual", signal: controller.signal }); let requestHeaders = headers; const knownVersion = knownMcpProtocolVersion(eraKey); if (isModernMcpProtocolVersion(knownVersion)) { requestHeaders = { ...headers, "MCP-Protocol-Version": knownVersion }; } else if (connectionRequiresMcpSession(connection)) { // Tool calls answer an older server's questions, so their session // declares form questions; it is kept apart from sessions that only // read (resources, prompts, listing), which declare none. const scope = `${connection.id}:grant:${grant.id}:actor:${session.agentId}:elicit-form:${endpoint}`; requestHeaders = await getMcpHttpSession({ scope, send: sendForNegotiation, headers, requestId, eraKey, elicitationForm: true, }); const sessionId = new Headers(requestHeaders).get("mcp-session-id"); if (sessionId) mcpSession = { scope, headers, sessionId }; const negotiated = mcpProtocolVersionOf(requestHeaders); if (isModernMcpProtocolVersion(negotiated)) await persistMcpProtocolVersion(connection, negotiated); } // The server's "try again" state from the previous identical call, if any. // Tied to the server that issued the state: a changed URL starts fresh. const continuationKey = `${connection.id}:${createHash("sha256").update(String(endpoint)).digest("hex")}:${grant.id}:${session.agentId}:${upstreamToolName}:${createHash("sha256").update(JSON.stringify(parameters ?? {})).digest("hex")}`; const continuation = mcpContinuations.get(continuationKey); // A person can answer the app's questions only when the call belongs to a task. const elicitationCall: McpElicitationCall | null = session.issueId ? { session: session as ToolGatewaySession & { issueId: string }, tool, connectionId: connection.id, grantId: grant.id, // Forwarded routing headers (such as a tenant) are part of the call: // one tenant's answers never go out with another tenant's headers. callIdentity: mcpElicitationCallIdentity(continuationKey, mcpTaskArgumentsIdentity(mcpTaskCallerHeaders(connection, callerHeaders))), argumentsIdentity: mcpTaskArgumentsIdentity(parameters), appName: tool.applicationDisplayName?.trim() || connection.name.trim() || "The app", } : null; // A question round this exact call left for a person (stateless MCP). // Until every card is resolved the call stops again without contacting // the app; then this call carries the answers and the app's exact state. if (elicitationCall && isModernMcpProtocolVersion(mcpProtocolVersionOf(requestHeaders))) { elicitationClaim = await collectElicitationRound(elicitationCall, { invocationId, era: "modern", claimMs: ms + 60_000 }); } /** * An older server asks over the open stream and waits for the reply. * The first time, the question goes on a card and the server is told * "cancel" at once, so it never hangs. When the person has answered, * the same question on this same call is answered from the card, once. */ const answerLegacyElicitation = async (messageId: unknown, form: McpFormElicitation) => { const respond = (result: McpElicitationResponse) => dispatchRemote(endpoint, { method: "POST", headers: mcpHttpRequestHeaders(requestHeaders), body: JSON.stringify({ jsonrpc: "2.0", id: messageId, result }), }); const cancel = () => respond({ action: "cancel" }).catch(() => undefined); if (!elicitationCall) { await cancel(); throw new ToolGatewayHttpError(409, "MCP elicitation is not supported for non-interactive gateway clients", "elicitation_not_supported", { invocationId, tool: tool.name }); } const questionHash = elicitationQuestionHash(form); // The app asks a question it already had an answer to in this call // (to have it corrected, or a second time): that answer is spent and // the person is asked again on a fresh card. const earlier = legacyAnswered.findIndex((used) => used.row.questions.some((question) => question.questionHash === questionHash)); if (earlier >= 0) { const [used] = legacyAnswered.splice(earlier, 1); try { await askElicitationRound(elicitationCall, { invocationId, era: "legacy", requestState: null, forms: [{ key: "question", request: form }], spend: used }); } finally { await cancel(); } } let answered: Awaited>; try { answered = await collectElicitationRound(elicitationCall, { invocationId, era: "legacy", questionHash, claimMs: ms + 60_000 }); } catch (error) { await cancel(); throw error; } if (answered) { const key = answered.row.questions.find((question) => question.questionHash === questionHash)!.key; const response = answered.responses[key]!; legacyAnswered.push({ row: answered.row, responses: { [key]: response } }); const delivered = await respond(response); // An app that refused the reply never got the answer: keep it for the next call. if (!delivered.ok) { throw new ToolGatewayHttpError(502, `${elicitationCall.appName} did not accept the answer to its question. Try the call again.`, "mcp_remote_status", { status: delivered.status, connectionId: connection.id, catalogEntryId: entry.id }); } return; } try { await askElicitationRound(elicitationCall, { invocationId, era: "legacy", requestState: null, forms: [{ key: "question", request: form }] }); } finally { await cancel(); } }; let callRequestId = requestId; let callParams: Record = { name: upstreamToolName, arguments: parameters, ...(elicitationClaim ? { inputResponses: elicitationClaim.responses, ...(elicitationClaim.requestState !== null ? { requestState: elicitationClaim.requestState } : {}) } : continuation ? { requestState: continuation.requestState } : {}), }; // The guard runs inside this call and the connection is pinned to the // address it approved, so an operator-supplied hostname cannot be rebound // onto a loopback or metadata address between validation and dispatch // (PAP-17098). // MCP Tasks are off unless the experimental setting is on; off, the call is exactly as before. const tasksOn = await mcpTasksEnabled(); const toolCallInit = (): RequestInit => ({ ...mcpHttpRequestInit(requestHeaders, { id: callRequestId, method: "tools/call", params: callParams }, { toolInputSchema: entry.inputSchema ?? undefined, // Paperclip can wait on a task here, durably (see waitForMcpTask). declareTasks: tasksOn, progressToken: progressReporter?.token, // A person can answer the app's form questions in the task chat. elicitationForm: Boolean(elicitationCall), declareClientCredentials: usesClientCredentials(connection), }), redirect: "manual", signal: controller.signal, }); // A stateless server may answer with a task. The same call (request, // grant, agent, and task) attaches to an undelivered one instead of // sending tools/call again, so retries and recovered runs never repeat work. const taskArgumentsIdentity = mcpTaskArgumentsIdentity(parameters); // Forwarded caller headers the connection allows (such as a tenant) // route the call too, so they are part of a task's identity. Per-run // metadata headers and credentials are not: they change on recovery. const taskCallerHeaders = mcpTaskCallerHeaders(connection, callerHeaders); const taskRoutingIdentity = mcpTaskArgumentsIdentity(taskCallerHeaders); // Built from the version a request actually used: a version retry can // move a saved legacy connection to stateless MCP mid-call. const taskIdentityFor = (headersUsed: Record) => { const version = mcpProtocolVersionOf(headersUsed); return tasksOn && isModernMcpProtocolVersion(version) ? { protocolVersion: version, requestHash: mcpTaskRequestHash({ connectionId: connection.id, endpoint: String(endpoint), toolName: upstreamToolName, argumentsIdentity: taskArgumentsIdentity, routingIdentity: taskRoutingIdentity, }), endpointHash: mcpTaskEndpointHash(String(endpoint)), } : null; }; const taskIdentity = taskIdentityFor(requestHeaders); // This call's hold on a task it starts or attaches to. const taskOwner = `call:${invocationId}:${randomUUID()}`; const taskTransport = (protocolVersion: string) => mcpTaskTransport({ protocolVersion, refreshable: connection.authKind === "oauth", headers: async (forceRefresh) => forceRefresh ? buildRemoteHeaders({ session, connection, callerHeaders, credentialHeaders: { ...projectedConnectionHeaders(connection), ...(await resolveCredentialHeaders(session, connection, grant, { forceRefresh: true })) }, }).headers : headers, send: (init) => dispatchRemote(endpoint, { ...init, signal: init.signal ?? controller.signal }), }); const waitOnTask = (row: typeof toolMcpTasks.$inferSelect, taskId: string, initial?: McpTaskState) => waitForMcpTask({ row, owner: taskOwner, taskId, initial, session, tool, invocationId, transport: taskTransport(row.protocolVersion), deadline: controller.signal, runSignal: taskSignals.run, callerSignal: taskSignals.caller, execution, }); if (taskIdentity) { const attachable = await findAttachableMcpTask({ session, connectionId: connection.id, grantId: grant.id, requestHash: taskIdentity.requestHash, rowId: taskSignals.attachToTaskRecordId ?? undefined, }); const attachedTaskId = attachable ? openMcpTaskId(mcpTaskSecret(), mcpTaskScope(attachable), attachable.sealedProviderTaskId) : null; if (attachable && attachedTaskId) { // Only one caller collects a task at a time; another one waiting on // it means this call is told to try again, never handed a copy. const claimed = await claimMcpTask(attachable, taskOwner, ms + 15_000, { lastInvocationId: invocationId, runId: session.runId ?? attachable.runId }); if (!claimed) throw mcpTaskPendingError(); return await completeRemoteMcpCall(await waitOnTask(claimed, attachedTaskId)); } } if (taskSignals.attachToTaskRecordId) { // The keyed retry's task is no longer collectable here (its grant or // endpoint changed): report it rather than start the work again. throw mcpTaskExpiredError(); } let response = await dispatchRemote(endpoint, toolCallInit()); // A stateless server rejects a request it cannot accept before running // anything (wrong version, or legacy request shape), so one retry with a // supported version is safe. // A plain 400 to a stateless request means the server went back to the // handshake (it rejected the request shape before running it). const modernRejection = await readMcpModernError(response); const sentVersion = mcpProtocolVersionOf(requestHeaders); const rolledBack = !modernRejection && response.status === 400 && isModernMcpProtocolVersion(sentVersion); if (modernRejection || rolledBack) { let retryVersion: string | null = null; if (modernRejection?.code === MCP_ERROR_UNSUPPORTED_PROTOCOL_VERSION && modernRejection.supported) { retryVersion = selectMcpProtocolVersion(modernRejection.supported); } else if (rolledBack || !isModernMcpProtocolVersion(sentVersion)) { forgetMcpProtocolVersion(eraKey); retryVersion = await negotiateMcpProtocolVersion({ send: sendForNegotiation, headers, requestId, eraKey }); } // A legacy version only helps when the stateless request was the problem. const usable = retryVersion !== null && retryVersion !== sentVersion && (isModernMcpProtocolVersion(retryVersion) || isModernMcpProtocolVersion(sentVersion)); if (usable && rolledBack) { // A plain 400 does not prove the tool never ran, so the call is not // sent again. Repair the saved version for the next explicit call: // a server that refused a stateless request needs the handshake. if (!isModernMcpProtocolVersion(retryVersion)) { rememberMcpProtocolVersion(eraKey, retryVersion!); const saved = await saveMcpNegotiation(db, connection, { mcpProtocolVersion: retryVersion!, mcpSessionRequired: true }); if (saved) { connection.config = saved.config; connection.transportConfig = saved.transportConfig; } } } else if (usable) { rememberMcpProtocolVersion(eraKey, retryVersion!); await persistMcpProtocolVersion(connection, retryVersion!); if (mcpSession) forgetMcpHttpSession(mcpSession); mcpSession = undefined; await response.body?.cancel().catch(() => undefined); if (isModernMcpProtocolVersion(retryVersion)) { requestHeaders = { ...headers, "MCP-Protocol-Version": retryVersion }; } else { // The same form-capable tool session as a first call (see above). const scope = `${connection.id}:grant:${grant.id}:actor:${session.agentId}:elicit-form:${endpoint}`; requestHeaders = await getMcpHttpSession({ scope, send: sendForNegotiation, headers, requestId: `${requestId}-version`, eraKey, elicitationForm: true }); const sessionId = new Headers(requestHeaders).get("mcp-session-id"); if (sessionId) mcpSession = { scope, headers, sessionId }; } callRequestId = `${requestId}-version`; response = await dispatchRemote(endpoint, toolCallInit()); } } if (isInsufficientConnectionScope(response)) { await response.body?.cancel().catch(() => undefined); await markCallHealth("degraded", INSUFFICIENT_CONNECTION_SCOPE_MESSAGE); throw new ToolGatewayHttpError(403, INSUFFICIENT_CONNECTION_SCOPE_MESSAGE, "oauth_insufficient_scope", { connectionId: connection.id }); } const oauth = asRecord(asRecord(connection.config)?.oauth); if ( response.status === 401 && connection.authKind === "oauth" && connection.credentialSource === "paperclip_vault" && isPaperclipCloudConnectorStrategy(oauth?.strategy) ) { credentialHeaders = { ...projectedConnectionHeaders(connection), ...(await resolveCredentialHeaders(session, connection, grant, { forceRefresh: true, })), }; builtHeaders = buildRemoteHeaders({ session, connection, credentialHeaders, callerHeaders, }); headers = builtHeaders.headers; headerSummary = builtHeaders.summary; await requireExplicitRetryAfterOAuthRefresh(response); } if ( response.status === 401 && connection.authKind === "oauth" && connection.credentialSource === "paperclip_vault" && !isPaperclipCloudConnectorStrategy(oauth?.strategy) && options.oauthGrantRefresher ) { credentialHeaders = { ...projectedConnectionHeaders(connection), ...(await resolveCredentialHeaders(session, connection, grant, { forceRefresh: true, })), }; builtHeaders = buildRemoteHeaders({ session, connection, credentialHeaders, callerHeaders, }); headers = builtHeaders.headers; headerSummary = builtHeaders.summary; await requireExplicitRetryAfterOAuthRefresh(response); } if ( response.status === 401 && connection.credentialSource === "vercel_connect" ) { if (!connection.externalCredential || !vercelConnect) { throw new ToolGatewayHttpError( 503, "Vercel Connect is not configured", "vercel_connect_unavailable", { connectionId: connection.id, }, ); } const tokenRequest = vercelTokenRequest({ credential: connection.externalCredential, grant, connectionId: connection.id, companyId: connection.companyId, }); vercelConnect.evict(tokenRequest); credentialHeaders = { ...projectedConnectionHeaders(connection), ...(await resolveCredentialHeaders(session, connection, grant, { forceRefresh: true, })), }; builtHeaders = buildRemoteHeaders({ session, connection, credentialHeaders, callerHeaders, }); headers = builtHeaders.headers; headerSummary = builtHeaders.summary; await requireExplicitRetryAfterOAuthRefresh(response); } const sessionExpired = response.status === 404 && new Headers(requestHeaders).has("mcp-session-id"); if (sessionExpired) { // The next explicit call initializes again. Never replay a tools/call // automatically: the failed call may have changed app data. if (mcpSession) forgetMcpHttpSession(mcpSession); } // Record the response headers before the body is read, so a body that // fails partway still has its status and content type in the evidence. execution.response = { httpStatus: response.status, contentType: response.headers.get("content-type"), bodySizeBytes: 0, upstreamRequestId: response.headers.get("x-request-id") ?? response.headers.get("x-zapier-request-id") ?? response.headers.get("traceparent"), }; const body = response.ok ? JSON.stringify(await readMcpHttpResponse(response, callRequestId, { maxBytes: MAX_REMOTE_MCP_RESPONSE_BYTES, // The call has a deadline (controller), so progress may outlast the total limit. limitPerMessage: true, onProgress: (progress) => { execution.stream = progress; }, onNotification: (message) => { const update = mcpProgressNotificationOf(message, progressReporter?.token); if (update) progressReporter!.report(update); }, onRequest: async (message) => { const pending = extractRemoteMcpPending(message); if (pending) { await retainUpstreamHandoff(invocationId, pending); // Defer this interaction to the user. Do not claim that consent // was granted or repeat a potentially state-changing tool call. await dispatchRemote(endpoint, { method: "POST", headers: mcpHttpRequestHeaders(requestHeaders), body: JSON.stringify({ jsonrpc: "2.0", id: message.id, result: { action: "cancel" } }), }); throw new ToolGatewayHttpError(409, "This tool needs authorization in the provider.", "provider_interaction_required", { upstreamPending: pending, invocationId }); } const form = message.method === "elicitation/create" ? formElicitationOf(asRecord(message.params) ?? {}) : null; if (form) await answerLegacyElicitation(message.id, form); else { const request = extractMcpElicitationRequest(message); if (request) await requestElicitationForRecordedToolCall({ session, tool, invocationId, request }); } }, })) : await readBoundedRemoteResponse(response, (bytes) => { execution.response!.bodySizeBytes = bytes; }); execution.response.bodySizeBytes = Buffer.byteLength(body, "utf8"); if (isInsufficientConnectionScope(response, body)) { await markCallHealth("degraded", INSUFFICIENT_CONNECTION_SCOPE_MESSAGE); throw new ToolGatewayHttpError(403, INSUFFICIENT_CONNECTION_SCOPE_MESSAGE, "oauth_insufficient_scope", { connectionId: connection.id, catalogEntryId: entry.id, }); } if (!response.ok) { // Session expiration is recoverable on an explicit retry. Marking the // connection unhealthy here would hide every tool and prevent it. if (response.status === 401 || response.status === 403) { await markCallHealth("error", "Remote MCP server returned an HTTP error."); } throw new ToolGatewayHttpError( 502, sessionExpired ? "Remote MCP session expired. Retry the action explicitly to start a new session." : "Remote MCP server returned an HTTP error", "mcp_remote_status", { status: response.status, ...(sessionExpired ? { sessionExpired: true } : {}), connectionId: connection.id, catalogEntryId: entry.id, execution, }, ); } let payload: unknown; try { payload = JSON.parse(body); } catch { throw new ToolGatewayHttpError( 502, "Remote MCP server returned invalid JSON", "mcp_remote_invalid_json", { connectionId: connection.id, catalogEntryId: entry.id, execution, }, ); } const payloadRecord = asRecord(payload); if (!payloadRecord) throw malformedRemoteMcpResponse(); // The server has answered this attempt, so saved multi round-trip input is // spent (a new input request saves its own below). A rejected attempt, // such as a 401 before an OAuth refresh, keeps it for the explicit retry. if (continuation) mcpContinuations.delete(continuationKey); // The app answered this call. If it asks a new form round, the answered // round is spent together with saving that one (askElicitationRound). const nextInput = mcpInputRequired(asRecord(payloadRecord.result)); const asksNextForms = Boolean(nextInput && Object.values(nextInput.inputRequests).length && Object.values(nextInput.inputRequests).every((request) => request.method === "elicitation/create" && formElicitationOf(request.params))); if (elicitationClaim && !asksNextForms) { const sent = elicitationClaim; elicitationClaim = null; await settleElicitationRound(sent.row, elicitationCall!, sent.responses, invocationId); } // The older app finished the call: the answers it used are spent. for (const used of legacyAnswered.splice(0)) await settleElicitationRound(used.row, elicitationCall!, used.responses, invocationId); const upstreamPending = extractRemoteMcpPending(payloadRecord, String(connection.config.sourceTemplateKey ?? ""), entry.toolName); if (upstreamPending) { await retainUpstreamHandoff(invocationId, upstreamPending); throw new ToolGatewayHttpError(409, "Complete the provider's authorization or approval before continuing. The original call has not been replayed.", "provider_interaction_required", { upstreamPending, invocationId }); } const topLevelElicitation = extractMcpElicitationRequest(payloadRecord); if (topLevelElicitation) { await requestElicitationForRecordedToolCall({ session, tool, invocationId, request: topLevelElicitation, }); } if (payloadRecord.error !== undefined) { const errorRecord = asRecord(payloadRecord.error); throw new ToolGatewayHttpError( 502, "Remote MCP server returned an error", "remote_mcp_error", { code: typeof errorRecord?.code === "number" ? errorRecord.code : null, connectionId: connection.id, catalogEntryId: entry.id, execution, }, ); } if (!Object.prototype.hasOwnProperty.call(payloadRecord, "result")) { throw malformedRemoteMcpResponse(); } if (asRecord(payloadRecord.result)?.resultType === "task") { // Only a stateless call declared tasks, and the server must send a // well-formed task; anything else is not a result Paperclip can use. const created = mcpCreatedTask(payloadRecord.result); const usedIdentity = taskIdentityFor(requestHeaders); if (!created || !usedIdentity) throw malformedRemoteMcpResponse(); const row = await createMcpTaskRecord({ session, connection, grant, catalogToolName: entry.toolName, invocationId, requestHash: usedIdentity.requestHash, argumentsIdentity: taskArgumentsIdentity, endpointHash: usedIdentity.endpointHash, callerHeaders: taskCallerHeaders, protocolVersion: usedIdentity.protocolVersion, state: created, owner: taskOwner, leaseMs: ms + 15_000, }); return await completeRemoteMcpCall(await waitOnTask(row, created.taskId, created)); } const inputRequired = mcpInputRequired(payloadRecord.result); if (inputRequired) { // Stateless servers ask for input by returning it as a result. The call // is retried later, with the answers and the server's opaque state. // Form questions alone go to a person in the task chat; the repeated // call carries their answers (see collectElicitationRound). const forms = Object.entries(inputRequired.inputRequests).flatMap(([key, request]) => { const form = request.method === "elicitation/create" ? formElicitationOf(request.params) : null; return form ? [{ key, request: form }] : []; }); if (elicitationCall && forms.length && forms.length === Object.keys(inputRequired.inputRequests).length) { const spend = elicitationClaim ?? undefined; // From here the answered round is spent with the next one saved; never released. elicitationClaim = null; await askElicitationRound(elicitationCall, { invocationId, era: "modern", requestState: inputRequired.requestState, forms, spend }); } const pending = mcpInputRequiredPending(inputRequired); if (!pending.answerable) { throw new ToolGatewayHttpError( 409, "This app needs information Paperclip can't collect yet. Complete the step in the app, then try again.", "provider_input_required", { connectionId: connection.id, catalogEntryId: entry.id, execution }, ); } if (pending.retryState) mcpContinuations.set(continuationKey, { requestState: pending.retryState }, MCP_CONTINUATION_TTL_MS); if (pending.upstreamPending) { await retainUpstreamHandoff(invocationId, pending.upstreamPending); throw new ToolGatewayHttpError(409, "Complete the provider's authorization or approval before continuing. The original call has not been replayed.", "provider_interaction_required", { upstreamPending: pending.upstreamPending, invocationId }); } throw new ToolGatewayHttpError( 409, "The app asked for this action to be tried again. Retry it to continue.", "provider_retry_requested", { connectionId: connection.id, catalogEntryId: entry.id, execution }, ); } return await completeRemoteMcpCall(payloadRecord.result); // A provider's final tool result, whether it came back directly or from a task. async function completeRemoteMcpCall(callResult: unknown): Promise { const resultElicitation = extractMcpElicitationRequest(callResult); if (resultElicitation) { await requestElicitationForRecordedToolCall({ session, tool, invocationId, request: resultElicitation, }); } const result = normalizeMcpToolResult( callResult, "mcp_http", false, sourceTemplateKey, ); const failureInstructions = result.errorCode === "github_access_denied" ? githubAccessDeniedInstructions(entry.toolName, connection.config.connectionMethodKey ?? connection.transportConfig.connectionMethodKey) : undefined; await markCallHealth( "ok", "Remote MCP server responded to tools/call.", ); return { result, failureInstructions, headerSummary, execution }; } } catch (error) { // The app never got the answers this call carried: the next identical call sends them. if (elicitationClaim) await releaseElicitationRound(elicitationClaim.row).catch(() => undefined); for (const used of legacyAnswered.splice(0)) await releaseElicitationRound(used.row).catch(() => undefined); execution.error = remoteHttpErrorEvidence(error); execution.deadline = { timeoutMs: ms, aborted: controller.signal.aborted }; if (execution.response && execution.stream) execution.response.bodySizeBytes = execution.stream.bytesReceived; // A deliberate workflow stop, such as a tool question for the user, keeps // its own reason even when the deadline passes while it is recorded. if (error instanceof ToolGatewayHttpError && REMOTE_TOOL_CALL_WORKFLOW_REASON_CODES.has(error.reasonCode)) { throw new ToolGatewayHttpError(error.status, error.message, error.reasonCode, { ...error.details, execution: error.details.execution ?? execution, }); } if (controller.signal.aborted || (error instanceof Error && error.name === "AbortError")) { if (mcpSession) forgetMcpHttpSession(mcpSession); execution.failureKind = "invocation_timeout"; throw new ToolGatewayHttpError(504, "Remote MCP tool call timed out", "tool_timeout", { connectionId: connection.id, catalogEntryId: entry.id, execution, failureKind: "invocation_timeout", }); } if (error instanceof McpHttpResponseError) { execution.failureKind = "protocol_failure"; const failure = error.reason === "too_large" ? responseTooLargeError() : error.reason === "malformed_response" ? malformedRemoteMcpResponse() : new ToolGatewayHttpError(502, "Remote MCP server returned invalid JSON", "mcp_remote_invalid_json"); // These describe one response body, not the connection: the server // answered with HTTP 2xx. Marking the connection unhealthy would hide // every tool, and only a successful call restores health. // The reader may have cancelled the stream partway, and the server can // then drop its session. Start a fresh session on the next call. if (mcpSession) forgetMcpHttpSession(mcpSession); throw new ToolGatewayHttpError(failure.status, failure.message, failure.reasonCode, { ...failure.details, connectionId: connection.id, catalogEntryId: entry.id, execution, }); } if (error instanceof RailwayError) { throw new ToolGatewayHttpError(error.status, error.message, error.code, { connectionId: connection.id, catalogEntryId: entry.id, execution }); } if (error instanceof ToolGatewayHttpError) { const failureKind = remoteToolCallFailureKind(error.reasonCode); if (failureKind) execution.failureKind = failureKind; throw new ToolGatewayHttpError( error.status, error.message, error.reasonCode, { ...error.details, execution: error.details.execution ?? execution, }, ); } execution.failureKind = "transport_failure"; if (error instanceof McpHttpInitializationError && (error.status === 401 || error.status === 403)) { await markCallHealth("error", "Remote MCP session authorization failed."); } if (mcpSession) forgetMcpHttpSession(mcpSession); throw new ToolGatewayHttpError( 502, "Remote MCP tool call failed", "mcp_remote_fetch_failed", { connectionId: connection.id, catalogEntryId: entry.id, execution, }, ); } finally { clearTimeout(timer); progressReporter?.finish(); } } /** Progress is shown to the run's viewers, so only a call made by a run reports it. */ function toolCallProgressReporterFor(session: ToolGatewaySession, tool: ToolGatewayDescriptor, invocationId: string | undefined) { if (!session.runId || !invocationId) return null; return createToolCallProgressReporter({ companyId: session.companyId, runId: session.runId, issueId: session.issueId, agentId: session.agentId, invocationId, toolName: tool.name, save: saveToolCallProgress(db, session.companyId, invocationId), }); } async function executeLocalStdioTool( session: ToolGatewaySession, tool: ToolGatewayDescriptor, parameters: unknown, ms: number, useProviderDefaultTimeout = false, invocationId?: string, ): Promise { const { entry, connection } = await resolveConnectedLocalStdioTool( session, tool, ); const grant = await resolveConnectionGrant(session, connection); const template = await resolveLocalStdioRuntimeTemplate(connection); const env = await localStdioEnvironment( session, connection, template, grant, ); const progressReporter = template.templateId === "paperclip.cognee-cloud" ? null : toolCallProgressReporterFor(session, tool, invocationId); const invoke = () => callLocalStdioMcp({ connection, entry, template, env, parameters, progressReporter, timeoutMs: useProviderDefaultTimeout && template.templateId === "paperclip.cognee-cloud" ? 60_000 : ms }) .finally(() => progressReporter?.finish()); // Cognee is a bundled HTTP client. Provider failures are tool failures, not // crashed local processes, and must never consume slots or restart budgets. const result = template.templateId === "paperclip.cognee-cloud" ? await invoke() : await runtimeSupervisor.useConnectionSlot( { companyId: session.companyId, applicationId: tool.applicationId ?? null, connectionId: connection.id, connectionKey: `mcp:${session.companyId}:${connection.id}`, runId: session.runId, issueId: session.issueId, agentId: session.agentId, commandTemplateKey: template.templateId, metadata: { fixture: "connected-local-stdio", applicationId: tool.applicationId ?? null, connectionId: connection.id, catalogEntryId: entry.id, }, }, async (handle) => { handle.appendLog("stdout", `calling ${entry.toolName}`); return invoke(); }, ); return { result: normalizeMcpToolResult(result, template.templateId === "paperclip.cognee-cloud" ? "cognee_cloud" : "local_stdio", template.templateId !== "paperclip.cognee-cloud"), }; } async function runWithTimeout( promise: Promise, ms: number, ): Promise { let timer: ReturnType | null = null; try { return await Promise.race([ promise, new Promise((_resolve, reject) => { timer = setTimeout(() => { reject( new ToolGatewayHttpError( 504, "Tool execution timed out", "tool_timeout", ), ); }, ms); timer.unref?.(); }), ]); } finally { if (timer) clearTimeout(timer); } } function gatewayEndpointPath(gatewayPublicId: string) { return `/mcp/gateways/${gatewayPublicId}`; } function gatewayClientSnippets( gateway: Pick< typeof toolMcpGateways.$inferSelect, "gatewayPublicId" | "name" >, ): ToolMcpGatewayClientSnippet[] { const endpoint = gatewayEndpointPath(gateway.gatewayPublicId); const bearerPlaceholder = "pcgw_..."; return [ { client: "cursor", label: "Cursor", config: { mcpServers: { [gateway.name]: { url: endpoint, headers: { Authorization: `Bearer ${bearerPlaceholder}` }, }, }, }, notes: ["Use the full Paperclip origin before the endpoint path."], }, { client: "claude_desktop", label: "Claude Desktop", config: { mcpServers: { [gateway.name]: { url: endpoint, headers: { Authorization: `Bearer ${bearerPlaceholder}` }, }, }, }, notes: [ "Recent Claude Desktop builds support remote HTTP MCP servers.", ], }, { client: "vscode", label: "VS Code", config: { servers: { [gateway.name]: { type: "http", url: endpoint, headers: { Authorization: `Bearer ${bearerPlaceholder}` }, }, }, }, notes: ["Place this under your MCP extension or editor MCP settings."], }, { client: "claude_code", label: "Claude Code", config: { command: "claude", args: [ "mcp", "add", gateway.name, endpoint, "--header", `Authorization: Bearer ${bearerPlaceholder}`, ], }, notes: [ "Use the equivalent remote HTTP MCP add command for your installed version.", ], }, { client: "opencode", label: "OpenCode", config: { mcp: { [gateway.name]: { url: endpoint, headers: { Authorization: `Bearer ${bearerPlaceholder}` }, }, }, }, notes: ["Use the full Paperclip origin before the endpoint path."], }, ]; } function toGateway(row: typeof toolMcpGateways.$inferSelect): ToolMcpGateway { return { id: row.id, companyId: row.companyId, gatewayPublicId: row.gatewayPublicId, name: row.name, displaySlug: row.displaySlug || row.slug, slug: row.slug, description: row.description, status: row.status, profileId: row.profileId, defaultProfileMode: row.defaultProfileMode, contextScopeType: row.contextScopeType, contextScopeId: row.contextScopeId, agentId: row.agentId, projectId: row.projectId, issueId: row.issueId, approvalIssueId: row.approvalIssueId, endpointPath: gatewayEndpointPath(row.gatewayPublicId), authConfig: row.authConfig, headerPolicy: row.headerPolicy, metadataPolicy: row.metadataPolicy, onDemandToolsConfig: row.onDemandToolsConfig, metadata: row.metadata ?? {}, createdByAgentId: row.createdByAgentId, createdByUserId: row.createdByUserId, archivedAt: row.archivedAt, createdAt: row.createdAt, updatedAt: row.updatedAt, }; } async function insertNamedGatewayToken(input: NamedGatewayTokenInput, pendingReveal: boolean) { await input.managementContext?.reauthorize(); const [gateway] = await db .select() .from(toolMcpGateways) .where( and( eq(toolMcpGateways.companyId, input.companyId), eq(toolMcpGateways.id, input.gatewayId), ), ) .limit(1); if (!gateway) throw new ToolGatewayHttpError( 404, "MCP gateway not found", "gateway_not_found", ); if (input.actor?.agentId && !input.managementContext && input.body.subjectType !== "heartbeat_run") { throw new ToolGatewayHttpError(403, "Agent client tokens require delegated authority", "gateway_token_run_context_invalid"); } if (input.managementContext?.actor.type === "agent" && input.body.subjectType === "heartbeat_run" && (!input.managementContext.actor.runId || input.body.subjectId !== input.managementContext.actor.runId)) { throw new ToolGatewayHttpError(403, "Heartbeat tokens must bind the authenticated run", "gateway_token_run_context_invalid"); } const tokenId = randomUUID(); const token = generateNamedGatewayToken(tokenId); const tokenPrefix = `pcgw_${tokenId.slice(0, 8)}`; const now = new Date(); const [row] = await db.transaction(async tx => { if (input.body.expiresAt) await notifyDeliveryWork(tx, DELIVERY_QUEUES.gatewayCredentialExpiry); return tx .insert(toolMcpGatewayTokens) .values({ id: tokenId, companyId: input.companyId, gatewayId: input.gatewayId, name: input.body.name, // A pending token's stored hash is of a value nobody receives. tokenHash: hashGatewayToken(token), tokenPrefix, pendingReveal, subjectType: input.body.subjectType ?? "gateway_client", subjectId: input.body.subjectId ?? null, clientLabel: input.body.clientLabel, ownerNote: input.body.ownerNote, allowedActions: input.body.allowedActions ?? [ "tools/list", "tools/call", "resources/list", "resources/read", "prompts/list", "prompts/get", ], expiresAt: input.body.expiresAt ?? null, expiryOverrideReason: input.body.expiryOverrideReason ?? null, expiryOverrideByAgentId: input.actor?.agentId && input.body.expiryOverrideReason ? input.actor.agentId : null, expiryOverrideByUserId: input.actor?.userId && input.body.expiryOverrideReason ? input.actor.userId : null, expiryOverrideAt: input.body.expiryOverrideReason ? now : null, responsibleUserId: input.managementContext?.actor.type === "agent" ? input.managementContext.responsibleUserId : null, createdByAgentId: input.actor?.agentId ?? null, createdByUserId: input.actor?.userId ?? null, createdAt: now, updatedAt: now, }) .returning(); }); if (input.managementContext) await logActivity(db, { companyId: input.companyId, ...input.managementContext.audit, action: "tool_gateway.token_created", entityType: "tool_mcp_gateway", entityId: input.gatewayId, details: { tokenId: row.id, subjectType: row.subjectType, allowedActions: row.allowedActions, ...(pendingReveal ? { pendingReveal } : {}) } }); return { row, token }; } function toGatewayToken( row: typeof toolMcpGatewayTokens.$inferSelect, ): ToolMcpGatewayToken { return { id: row.id, companyId: row.companyId, gatewayId: row.gatewayId, name: row.name, tokenPrefix: row.tokenPrefix, subjectType: row.subjectType, subjectId: row.subjectId, clientLabel: row.clientLabel, ownerNote: row.ownerNote, allowedActions: row.allowedActions, expiresAt: row.expiresAt, expiryOverrideReason: row.expiryOverrideReason, expiryOverrideByUserId: row.expiryOverrideByUserId, expiryOverrideByAgentId: row.expiryOverrideByAgentId, expiryOverrideAt: row.expiryOverrideAt, lastUsedAt: row.lastUsedAt, revokedAt: row.revokedAt, createdByAgentId: row.createdByAgentId, createdByUserId: row.createdByUserId, responsibleUserId: row.responsibleUserId, pendingReveal: row.pendingReveal, createdAt: row.createdAt, updatedAt: row.updatedAt, }; } async function getGatewayWithTokens( companyId: string, gatewayId: string, ): Promise { const [gateway] = await db .select() .from(toolMcpGateways) .where( and( eq(toolMcpGateways.companyId, companyId), eq(toolMcpGateways.id, gatewayId), ), ) .limit(1); if (!gateway) { throw new ToolGatewayHttpError( 404, "MCP gateway not found", "gateway_not_found", ); } const tokens = await db .select() .from(toolMcpGatewayTokens) .where( and( eq(toolMcpGatewayTokens.companyId, companyId), eq(toolMcpGatewayTokens.gatewayId, gatewayId), ), ) .orderBy(desc(toolMcpGatewayTokens.createdAt)); return { ...toGateway(gateway), tokens: tokens.map(toGatewayToken), clientSnippets: gatewayClientSnippets(gateway), }; } async function assertGatewayContext(input: { companyId: string; profileId?: string | null; agentId?: string | null; projectId?: string | null; issueId?: string | null; }) { if (input.profileId) { const [profile] = await db .select({ id: toolProfiles.id }) .from(toolProfiles) .where( and( eq(toolProfiles.companyId, input.companyId), eq(toolProfiles.id, input.profileId), ), ) .limit(1); if (!profile) throw new ToolGatewayHttpError( 422, "Gateway profile must belong to the company", "gateway_profile_invalid", ); } if (input.agentId) await assertAgentInCompany(input.companyId, input.agentId); if (input.projectId) { const [project] = await db .select({ id: projects.id }) .from(projects) .where( and( eq(projects.companyId, input.companyId), eq(projects.id, input.projectId), ), ) .limit(1); if (!project) throw new ToolGatewayHttpError( 422, "Gateway project must belong to the company", "gateway_project_invalid", ); } if (input.issueId) { const [issue] = await db .select({ id: issues.id, projectId: issues.projectId }) .from(issues) .where( and( eq(issues.companyId, input.companyId), eq(issues.id, input.issueId), ), ) .limit(1); if (!issue) throw new ToolGatewayHttpError( 422, "Gateway issue must belong to the company", "gateway_issue_invalid", ); if ( input.projectId && issue.projectId && issue.projectId !== input.projectId ) { throw new ToolGatewayHttpError( 422, "Gateway issue must belong to the selected project", "gateway_issue_project_mismatch", ); } } } async function findGatewayForProtocolLocator(input: { gatewayId?: string | null; gatewayPublicId?: string | null; }) { if (input.gatewayId) { const [gateway] = await db .select() .from(toolMcpGateways) .where(eq(toolMcpGateways.id, input.gatewayId)) .limit(1); return gateway ?? null; } if (input.gatewayPublicId) { const [gateway] = await db .select() .from(toolMcpGateways) .where(eq(toolMcpGateways.gatewayPublicId, input.gatewayPublicId)) .limit(1); return gateway ?? null; } return null; } function protocolLimiterKeyClass(method: McpGatewayProtocolMethod) { return method === "initialize" ? "session_setup" : method; } async function writeProtocolRateLimitAudit(input: { session: ToolGatewaySession; method: McpGatewayProtocolMethod; limiterKeyClass: "token" | "gateway"; count: number; limit: McpGatewayRateLimitConfig; retryAfterMs: number; clientMetadata: ReturnType; }) { await writeAudit({ session: input.session, companyId: input.session.companyId, agentId: input.session.agentId, runId: input.session.runId, issueId: input.session.issueId, action: "tool_gateway.call_denied", details: { decision: "rate_limited", reasonCode: "gateway_rate_limited", reasonText: "The MCP gateway request was rate limited before the protocol action ran.", limiterKeyClass: input.limiterKeyClass, protocolMethod: input.method, protocolAction: protocolLimiterKeyClass(input.method), requestCount: input.count, limit: input.limit.max, windowMs: input.limit.windowMs, retryAfterMs: input.retryAfterMs, gatewayId: input.session.gatewayId ?? null, gatewayPublicId: input.session.gatewayPublicId ?? null, gatewayTokenId: input.session.gatewayTokenId ?? null, tokenPrefix: typeof input.session.gatewayTokenId === "string" ? `pcgw_${input.session.gatewayTokenId.slice(0, 8)}` : null, ...input.clientMetadata, }, }); } async function assertNamedGatewayProtocolLimit( session: ToolGatewaySession, method: McpGatewayProtocolMethod, clientMetadata: ReturnType, ) { const action = protocolLimiterKeyClass(method); const tokenLimit = method === "initialize" ? protocolLimits.sessionSetup : protocolLimits.tokenRequests; const tokenKey = `mcp_gateway_protocol:token:${session.gatewayTokenId ?? session.actorId ?? "unknown"}:${action}`; const tokenState = await consumeProtocolRateLimit({ companyId: session.companyId, counterKey: tokenKey, config: tokenLimit, }); if (tokenState.limited) { await writeProtocolRateLimitAudit({ session, method, limiterKeyClass: "token", count: tokenState.count, limit: tokenLimit, retryAfterMs: tokenState.retryAfterMs, clientMetadata, }); throw new ToolGatewayHttpError( 429, "MCP gateway request was rate limited", "gateway_rate_limited", { reasonText: "The MCP gateway request was rate limited before the protocol action ran.", limiterKeyClass: "token", protocolMethod: method, retryAfterMs: tokenState.retryAfterMs, }, ); } const gatewayLimit = method === "initialize" ? protocolLimits.sessionSetup : protocolLimits.gatewayRequests; const gatewayKey = `mcp_gateway_protocol:gateway:${session.gatewayId ?? session.gatewayPublicId ?? "unknown"}:${action}`; const gatewayState = await consumeProtocolRateLimit({ companyId: session.companyId, counterKey: gatewayKey, config: gatewayLimit, }); if (gatewayState.limited) { await writeProtocolRateLimitAudit({ session, method, limiterKeyClass: "gateway", count: gatewayState.count, limit: gatewayLimit, retryAfterMs: gatewayState.retryAfterMs, clientMetadata, }); throw new ToolGatewayHttpError( 429, "MCP gateway request was rate limited", "gateway_rate_limited", { reasonText: "The MCP gateway request was rate limited before the protocol action ran.", limiterKeyClass: "gateway", protocolMethod: method, retryAfterMs: gatewayState.retryAfterMs, }, ); } } async function recordNamedGatewayAuthFailure(input: { gatewayId?: string | null; gatewayPublicId?: string | null; bearerToken: string; reasonCode: string; clientMetadata: ReturnType; }): Promise { const token = input.bearerToken.trim(); const tokenId = namedGatewayTokenId(token); const gatewayKey = input.gatewayId ? `id:${input.gatewayId}` : `public:${input.gatewayPublicId ?? "unknown"}`; const tokenKey = tokenId ? `id:${tokenId}` : `hash:${hashGatewayToken(token).slice(0, 24)}`; const gateway = await findGatewayForProtocolLocator(input); if (!gateway) { throw new ToolGatewayHttpError( 401, "Gateway bearer token is expired or invalid", input.reasonCode, ); } const gatewayState = await consumeProtocolRateLimit({ companyId: gateway.companyId, counterKey: `mcp_gateway_auth_failure:gateway:${gatewayKey}`, config: protocolLimits.authFailures, }); const tokenState = await consumeProtocolRateLimit({ companyId: gateway.companyId, counterKey: `mcp_gateway_auth_failure:token:${gatewayKey}:${tokenKey}`, config: protocolLimits.authFailures, }); const limited = gatewayState.limited || tokenState.limited; if (limited) { const limiterKeyClass = gatewayState.limited ? "gateway_auth" : "token_auth"; const count = gatewayState.limited ? gatewayState.count : tokenState.count; const retryAfterMs = gatewayState.limited ? gatewayState.retryAfterMs : tokenState.retryAfterMs; await writeAudit({ session: { id: `gateway:${gateway.id}`, token: "", companyId: gateway.companyId, agentId: gateway.agentId, runId: null, issueId: gateway.issueId, projectId: gateway.projectId, gatewayId: gateway.id, gatewayPublicId: gateway.gatewayPublicId, gatewayName: gateway.name, gatewayTokenId: null, actorType: "system", actorId: gateway.id, createdAt: new Date(), expiresAt: new Date(), }, companyId: gateway.companyId, agentId: gateway.agentId, runId: null, issueId: gateway.issueId, action: "tool_gateway.session_rejected", details: { decision: "deny", reasonCode: "gateway_auth_throttled", reasonText: "The MCP gateway authentication attempt was throttled after repeated failures.", limiterKeyClass, failedReasonCode: input.reasonCode, requestCount: count, limit: protocolLimits.authFailures.max, windowMs: protocolLimits.authFailures.windowMs, retryAfterMs, gatewayId: gateway.id, gatewayPublicId: gateway.gatewayPublicId, tokenPrefix: tokenPrefixFromNamedBearer(token), ...input.clientMetadata, }, }); } if (limited) { throw new ToolGatewayHttpError( 429, "MCP gateway authentication was throttled", "gateway_auth_throttled", { reasonText: "The MCP gateway authentication attempt was throttled after repeated failures.", retryAfterMs: Math.max( gatewayState.retryAfterMs, tokenState.retryAfterMs, ), }, ); } throw new ToolGatewayHttpError( 401, "Gateway bearer token is expired or invalid", input.reasonCode, ); } async function namedGatewaySessionFromBearer(input: { gatewayId?: string | null; gatewayPublicId?: string | null; bearerToken: string; protocolMethod: McpGatewayProtocolMethod; callerHeaders?: Record; }): Promise { const clientMetadata = safeClientMetadata(input.callerHeaders); const bearerToken = input.bearerToken.trim(); const tokenId = namedGatewayTokenId(bearerToken.trim()); const tokenHash = hashGatewayToken(bearerToken.trim()); const conditions = [eq(toolMcpGatewayTokens.tokenHash, tokenHash)]; if (input.gatewayId) conditions.push(eq(toolMcpGatewayTokens.gatewayId, input.gatewayId)); if (input.gatewayPublicId) conditions.push( eq(toolMcpGateways.gatewayPublicId, input.gatewayPublicId), ); const [row] = await db .select({ gateway: toolMcpGateways, token: toolMcpGatewayTokens }) .from(toolMcpGatewayTokens) .innerJoin( toolMcpGateways, eq(toolMcpGatewayTokens.gatewayId, toolMcpGateways.id), ) .where(and(...conditions)) .limit(1); if (!row) { await recordNamedGatewayAuthFailure({ gatewayId: input.gatewayId, gatewayPublicId: input.gatewayPublicId, bearerToken, reasonCode: "gateway_token_invalid", clientMetadata, }); } if (row.gateway.status !== "active") { await recordNamedGatewayAuthFailure({ gatewayId: input.gatewayId, gatewayPublicId: input.gatewayPublicId, bearerToken, reasonCode: "gateway_disabled", clientMetadata, }); } if (row.token.revokedAt) { await recordNamedGatewayAuthFailure({ gatewayId: input.gatewayId, gatewayPublicId: input.gatewayPublicId, bearerToken, reasonCode: "gateway_token_revoked", clientMetadata, }); } if (row.token.pendingReveal) { await recordNamedGatewayAuthFailure({ gatewayId: input.gatewayId, gatewayPublicId: input.gatewayPublicId, bearerToken, reasonCode: "gateway_token_invalid", clientMetadata, }); } if (row.token.expiresAt && row.token.expiresAt.getTime() <= Date.now()) { await recordNamedGatewayAuthFailure({ gatewayId: input.gatewayId, gatewayPublicId: input.gatewayPublicId, bearerToken, reasonCode: "gateway_token_expired", clientMetadata, }); } const nativeMetadata = row.gateway.metadata; const [profile] = await db.select({ profileKey: toolProfiles.profileKey, status: toolProfiles.status, source: sql`${toolProfiles.metadata}->>'source'`, agentId: sql`${toolProfiles.metadata}->>'agentId'`, assignmentDigest: sql`${toolProfiles.metadata}->>'assignmentDigest'`, }).from(toolProfiles).where(and( eq(toolProfiles.id, row.gateway.profileId), eq(toolProfiles.companyId, row.gateway.companyId), )).limit(1); // The immutable native profile also identifies legacy assignments when an // update has cleared the gateway metadata. Missing metadata must fail closed. const nativeAssignment = Object.hasOwn(nativeMetadata ?? {}, "nativeRuntimeAssignmentDigest") || profile?.profileKey.startsWith("native:") || profile?.source === "paperclip_runner"; const nativeOwner = nativeMetadata?.agentId; if (nativeAssignment && ( typeof nativeOwner !== "string" || !uuidPattern.test(nativeOwner) || typeof nativeMetadata?.nativeRuntimeAssignmentDigest !== "string" || !/^[a-f0-9]{64}$/.test(nativeMetadata.nativeRuntimeAssignmentDigest) || (row.gateway.agentId && row.gateway.agentId !== nativeOwner) || row.token.subjectType !== "heartbeat_run" )) { return recordNamedGatewayAuthFailure({ gatewayId: input.gatewayId, gatewayPublicId: input.gatewayPublicId, bearerToken, reasonCode: "gateway_token_run_context_invalid", clientMetadata, }); } if (nativeAssignment) { if (profile?.status !== "active" || profile.source !== "paperclip_runner" || profile.agentId !== nativeOwner || profile.assignmentDigest !== nativeMetadata!.nativeRuntimeAssignmentDigest) { return recordNamedGatewayAuthFailure({ gatewayId: input.gatewayId, gatewayPublicId: input.gatewayPublicId, bearerToken, reasonCode: "gateway_token_run_context_invalid", clientMetadata, }); } } let agentId = row.gateway.agentId ?? (nativeAssignment ? nativeOwner as string : null); let runId: string | null = null; let responsibleUserId: string | null = null; let issueId = row.gateway.issueId; let projectId = row.gateway.projectId; if (row.token.subjectType === "heartbeat_run") { const tokenRunId = row.token.subjectId; if (!tokenRunId || !uuidPattern.test(tokenRunId)) { return recordNamedGatewayAuthFailure({ gatewayId: input.gatewayId, gatewayPublicId: input.gatewayPublicId, bearerToken, reasonCode: "gateway_token_run_invalid", clientMetadata, }); } const [run] = await db .select({ companyId: heartbeatRuns.companyId, agentId: heartbeatRuns.agentId, status: heartbeatRuns.status, responsibleUserId: heartbeatRuns.responsibleUserId, }) .from(heartbeatRuns) .where(eq(heartbeatRuns.id, tokenRunId)) .limit(1); if (!run || run.companyId !== row.gateway.companyId) { return recordNamedGatewayAuthFailure({ gatewayId: input.gatewayId, gatewayPublicId: input.gatewayPublicId, bearerToken, reasonCode: "gateway_token_run_invalid", clientMetadata, }); } if (!ACTIVE_GATEWAY_RUN_STATUSES.has(run.status)) { return recordNamedGatewayAuthFailure({ gatewayId: input.gatewayId, gatewayPublicId: input.gatewayPublicId, bearerToken, reasonCode: "gateway_token_run_inactive", clientMetadata, }); } if (agentId && agentId !== run.agentId) { return recordNamedGatewayAuthFailure({ gatewayId: input.gatewayId, gatewayPublicId: input.gatewayPublicId, bearerToken, reasonCode: "gateway_token_run_context_invalid", clientMetadata, }); } try { const runContext = await resolveRunContext({ companyId: row.gateway.companyId, agentId: run.agentId, runId: tokenRunId, issueId: row.gateway.issueId, projectId: row.gateway.projectId, }); agentId = run.agentId; runId = tokenRunId; responsibleUserId = run.responsibleUserId; issueId = runContext.issueId; projectId = runContext.projectId; } catch { return recordNamedGatewayAuthFailure({ gatewayId: input.gatewayId, gatewayPublicId: input.gatewayPublicId, bearerToken, reasonCode: "gateway_token_run_context_invalid", clientMetadata, }); } } if (row.token.subjectType === "gateway_client" && (row.token.createdByAgentId || row.token.responsibleUserId)) { // Durable clients inherit current issuer/user authority, not the setup run's lifetime. // The issuer FK is cleared on agent deletion. Retain the responsible-user // marker so deletion cannot turn delegated credentials into system clients. if (!row.token.createdByAgentId || !row.token.responsibleUserId) return recordNamedGatewayAuthFailure({ gatewayId: input.gatewayId, gatewayPublicId: input.gatewayPublicId, bearerToken, reasonCode: "gateway_token_run_context_invalid", clientMetadata, }); const delegatedActor = { type: "agent" as const, companyId: row.gateway.companyId, agentId: row.token.createdByAgentId, onBehalfOfUserId: row.token.responsibleUserId }; const resource = { type: "connection_management" as const, companyId: row.gateway.companyId, gatewayId: row.gateway.id, profileId: row.gateway.profileId, purpose: "tool" as const, operation: "gateway_token.use", targetAgentId: row.gateway.agentId, projectId: row.gateway.projectId, issueId: row.gateway.issueId }; try { await connectionManagementService(db).authorize(delegatedActor, "connections:gateway", resource, { mutation: false }); await connectionManagementService(db).authorize(delegatedActor, "connections:test", resource, { mutation: false }); } catch { return recordNamedGatewayAuthFailure({ gatewayId: input.gatewayId, gatewayPublicId: input.gatewayPublicId, bearerToken, reasonCode: "gateway_token_run_context_invalid", clientMetadata }); } agentId ??= row.token.createdByAgentId; responsibleUserId = row.token.responsibleUserId; } const now = new Date(); await db .update(toolMcpGatewayTokens) .set({ lastUsedAt: now, updatedAt: now }) .where(eq(toolMcpGatewayTokens.id, row.token.id)); const session: ToolGatewaySession = { id: `gateway:${row.gateway.id}`, token: "", companyId: row.gateway.companyId, agentId, runId, issueId, projectId, gatewayId: row.gateway.id, gatewayPublicId: row.gateway.gatewayPublicId, gatewayName: row.gateway.name, gatewayProfileId: row.gateway.profileId, gatewayTokenId: row.token.id || tokenId, originatingAgentId: row.token.subjectType === "gateway_client" && row.token.responsibleUserId ? row.token.createdByAgentId : null, gatewayTokenAllowedActions: normalizeGatewayTokenActions( row.token.allowedActions, ), actorType: runId || responsibleUserId ? "agent" : "system", actorId: runId ? agentId : responsibleUserId ? row.token.createdByAgentId : row.token.id, responsibleUserId, createdAt: row.token.createdAt, expiresAt: row.token.expiresAt ?? new Date(Date.now() + 3650 * 24 * 60 * 60 * 1000), }; await assertNamedGatewayProtocolLimit( session, input.protocolMethod, clientMetadata, ); return captureSessionIdentity(session); } /** * A "test-origin" invocation is one created by the Apps → Test tab's * impersonated test call: an out-of-band `actorType: "user"` invocation with * no heartbeat run, issue, or gateway behind it. We key off the durable * invocation columns rather than audit metadata so the signal survives a * reload — and so the live test panel can drive an approved test call to * completion without a real agent run re-invoking it. */ function isTestOriginInvocation( invocation: typeof toolInvocations.$inferSelect, ): boolean { if (invocation.policyExplanation?.delegatedConnectionTest) return invocation.connectionId !== null && invocation.gatewayId === null; // An MCP Apps view's tool call is a test-path call that carries its task, // so its approval runs through the test path with that task's rules. if (invocation.policyExplanation?.mcpAppViewCall) { return invocation.actorType === "user" && invocation.runId === null && invocation.gatewayId === null && invocation.connectionId !== null; } return ( invocation.actorType === "user" && invocation.runId === null && invocation.issueId === null && invocation.gatewayId === null && invocation.connectionId !== null ); } function delegatedTestCallerSession(session: ToolGatewaySession): ToolGatewaySession | null { const callerId = session.originatingAgentId; return callerId && callerId !== session.agentId ? { ...session, agentId: callerId } : null; } async function assertDelegatedTestCredentialAccess(session: ToolGatewaySession, tool: ToolGatewayDescriptor) { const caller = delegatedTestCallerSession(session); if (!caller || !tool.connectionId) return; const [connection] = await db.select().from(toolConnections).where(and( eq(toolConnections.companyId, session.companyId), eq(toolConnections.id, tool.connectionId), )); if (!connection) throw new ToolGatewayHttpError(404, "Tool connection not found", "connection_not_found"); // Resolve consent metadata before any vault read. Testing another agent // cannot select that agent's dedicated credential or a different identity. const callerGrant = await resolveConnectionGrant(caller, connection, false); const targetGrant = await resolveConnectionGrant(session, connection, false); if (callerGrant.id !== targetGrant.id) { throw new ToolGatewayHttpError(403, "Delegated calls cannot use another agent's credential identity", session.gatewayTokenId ? "gateway_credential_identity_mismatch" : "test_credential_identity_mismatch"); } } async function assertCurrentDelegatedTestCaller(session: ToolGatewaySession, tool: ToolGatewayDescriptor, parameters: unknown, invocationId: string) { const caller = delegatedTestCallerSession(session); if (!caller) return; const current = await policyService.decide(policyInputForTool({ session: caller, tool, parameters }), { admittedInvocationId: invocationId }); if (!current.allowed && !(session.approvedInvocationId && current.decision === "require_approval")) { throw new ToolGatewayHttpError(403, current.explanation, current.reasonCode); } await assertDelegatedTestCredentialAccess(session, tool); } async function assertCurrentGatewayIssuer(session: ToolGatewaySession, tool: ToolGatewayDescriptor, parameters: unknown, invocationId: string, approved: boolean) { if (!session.gatewayId || !session.originatingAgentId) return; const current = await policyService.decide(policyInputForTool({ session, tool, parameters }), { admittedInvocationId: invocationId, requiredGatewayAction: "tools/call" }); if (!current.allowed && !(approved && current.decision === "require_approval")) throw new ToolGatewayHttpError(policyErrorStatus(current), current.explanation, current.reasonCode); await assertDelegatedTestCredentialAccess(session, tool); } /** * Execute an already-authorized test-tab tool call against the connected MCP * server and record the result/error onto the invocation. Shared by * {@link executeTestCall} (the allow path) and the approval-driven execution * of a parked ask-first request, so both produce identical persistence, * events, and audit entries. */ async function runTestToolInvocation(args: { session: ToolGatewaySession; tool: ToolGatewayDescriptor; parameters: unknown; invocationId: string; companyId: string; agentId: string; userId: string; argumentsSummary: ReturnType; reasonCode: string; matchedPolicyIds: string[]; timeoutMs?: number; signal?: AbortSignal; approvedClaim?: ToolApprovalClaim; managementContext?: ConnectionManagementContext; }): Promise< | { decision: "allowed"; invocationId: string; result: unknown; resultMeta?: Record } | { decision: "allowed"; invocationId: string; error: { message: string; reasonCode: string }; } > { if (!(await startToolInvocation(db, args.invocationId, args.approvedClaim))) { throw new ToolGatewayHttpError(409, "Tool action execution claim is no longer current", "action_already_consumed"); } await writeAudit({ session: args.session, companyId: args.companyId, agentId: args.agentId, runId: args.session.runId, issueId: args.session.issueId, actorType: args.session.actorType, actorId: args.session.actorId ?? args.userId, action: "tool_gateway.call_allowed", details: { source: "test", invocationId: args.invocationId, decision: "allow", reasonCode: args.reasonCode, matchedPolicyIds: args.matchedPolicyIds, tool: args.tool.name, ...toolAuditMetadata(args.tool), argumentsSummary: args.argumentsSummary, }, }); const startedAt = Date.now(); let connectedMcpExecution: Awaited> | Awaited> | null; let resultValidation: Awaited>; try { await args.managementContext?.reauthorize(); if (args.managementContext?.actor.type === "agent") { Object.assign(args.session, args.managementContext.workContext); await assertCurrentDelegatedTestCaller(args.session, args.tool, args.parameters, args.invocationId); const current = await policyService.decide(policyInputForTool({ session: args.session, tool: args.tool, parameters: args.parameters }), { admittedInvocationId: args.invocationId }); if (!current.allowed && !(args.session.approvedInvocationId && current.decision === "require_approval")) { throw new ToolGatewayHttpError(403, current.explanation, current.reasonCode); } } const executionTimeoutMs = timeoutMs(args.timeoutMs, args.tool); connectedMcpExecution = (args.tool.providerType === "mcp_remote_http" || args.tool.providerType === "provider_rest") ? await executeRemoteHttpTool( args.session, args.tool, args.parameters, executionTimeoutMs, args.invocationId, undefined, args.timeoutMs === undefined, ) : args.tool.providerType === "mcp_local_stdio" ? await executeLocalStdioTool( args.session, args.tool, args.parameters, executionTimeoutMs, args.timeoutMs === undefined, args.invocationId, ) : null; if (!connectedMcpExecution) { throw new ToolGatewayHttpError( 404, `Tool "${args.tool.name}" not found`, "tool_not_found", { tool: args.tool.name, }, ); } const result = connectedMcpExecution.result; resultValidation = await validateToolContent({ value: result, direction: "result", sensitiveMode: "redact", promptInjectionMode: "block", classifier: resultClassifier(args.session, args.tool, args.invocationId, { signal: args.signal, approvedAction: Boolean(args.session.approvedInvocationId) }), }); const providerResult = asRecord(resultValidation.value); if (providerResult?.error) { throw new ToolGatewayHttpError(providerResult.errorCode === "github_access_denied" ? 403 : 502, toolResultErrorMessage(providerResult, connectedMcpExecution.failureInstructions), providerResult.errorCode === "github_access_denied" ? "github_access_denied" : "tool_error", { execution: connectedMcpExecution.execution }); } } catch (err) { const status = err instanceof ToolGatewayHttpError ? err.status : 502; const reasonCode = err instanceof ToolContentValidationError ? err.reasonCode : err instanceof ToolGatewayHttpError ? err.reasonCode : "tool_execution_failed"; const message = err instanceof Error ? err.message : String(err); await persistToolTestOutcome(db, args.invocationId, { status: status === 504 ? "timed_out" : status === 429 ? "rate_limited" : "failed", errorCode: reasonCode, errorMessage: message, }, args.approvedClaim); void emitConnectionInvoked(db, args.invocationId); await writeToolCallEvent({ invocationId: args.invocationId, session: args.session, eventType: "call_failed", outcome: status === 504 ? "timeout" : "failure", toolName: args.tool.name, policyDecision: status === 504 ? "defer_runtime" : "deny", reasonCode, argumentsSummary: args.argumentsSummary, metadata: { source: "test", ...(err instanceof ToolContentValidationError ? { findings: err.findings, promptInjection: err.detectorMetadata } : {}), ...(executionAuditFromError(err) ? { execution: executionAuditFromError(err) } : {}), }, tool: args.tool, }); await writeAudit({ session: args.session, companyId: args.companyId, agentId: args.agentId, runId: args.session.runId, issueId: args.session.issueId, actorType: args.session.actorType, actorId: args.session.actorId ?? args.userId, action: status === 504 ? "tool_gateway.call_deferred" : "tool_gateway.call_failed", details: { source: "test", invocationId: args.invocationId, decision: status === 504 ? "defer_runtime" : "deny", reasonCode, tool: args.tool.name, ...toolAuditMetadata(args.tool), argumentsSummary: args.argumentsSummary, durationMs: Date.now() - startedAt, error: message, ...(err instanceof ToolContentValidationError ? { promptInjection: err.detectorMetadata } : {}), ...(executionAuditFromError(err) ? { execution: executionAuditFromError(err) } : {}), }, }); return { decision: "allowed" as const, invocationId: args.invocationId, error: { message, reasonCode }, ...(err instanceof ToolGatewayHttpError && err.reasonCode === "provider_interaction_required" ? { upstreamPending: err.details.upstreamPending as ToolUpstreamPending } : {}), }; } await persistToolTestOutcome(db, args.invocationId, { status: "succeeded", result: resultValidation.summary, }, args.approvedClaim); // A provider task's result is now recorded; only now is it delivered. await markMcpTaskDelivered(args.session.companyId, args.invocationId); await writeToolCallEvent({ invocationId: args.invocationId, session: args.session, eventType: "call_completed", outcome: "success", toolName: args.tool.name, policyDecision: "allow", reasonCode: "tool_completed", argumentsSummary: args.argumentsSummary, resultSummary: resultValidation.summary, detectorMetadata: resultValidation.detectorMetadata, metadata: { source: "test", headerSummary: connectedMcpExecution.headerSummary ?? undefined, execution: connectedMcpExecution.execution, }, tool: args.tool, }); await writeAudit({ session: args.session, companyId: args.companyId, agentId: args.agentId, runId: args.session.runId, issueId: args.session.issueId, actorType: args.session.actorType, actorId: args.session.actorId ?? args.userId, action: "tool_gateway.call_completed", details: { source: "test", invocationId: args.invocationId, decision: "allow", reasonCode: "tool_completed", tool: args.tool.name, ...toolAuditMetadata(args.tool), durationMs: Date.now() - startedAt, argumentsSummary: args.argumentsSummary, result: summarizeResult(resultValidation.value), resultSummary: resultValidation.summary, promptInjection: resultValidation.detectorMetadata, headerSummary: connectedMcpExecution.headerSummary ?? undefined, execution: connectedMcpExecution.execution, }, }); void emitConnectionInvoked(db, args.invocationId); const resultMeta = await redactedMcpResultMeta(connectedMcpExecution?.result); return { decision: "allowed" as const, invocationId: args.invocationId, result: resultValidation.value, // Provider `_meta`, redacted, for MCP Apps views only. ...(resultMeta ? { resultMeta } : {}), }; } function isApprovalPreparationRejection(error: unknown) { return error instanceof ToolContentValidationError || (error instanceof ToolGatewayHttpError || error instanceof HttpError) && error.status >= 400 && error.status < 500 && ![408, 425, 429].includes(error.status); } async function bindVerifiedApprovalArguments(invocation: typeof toolInvocations.$inferSelect, claim: ToolApprovalClaim, parameters: unknown) { const preview = summarizeToolValue(parameters).sha256; const verified = toolRequestIdentityHash(parameters, options.toolActionSigningSecret); if (invocation.argumentsHash === preview && invocation.argumentsHash !== verified && !await bindVerifiedToolApprovalArguments(db, claim, { preview, verified })) { throw new ToolGatewayHttpError(409, "Tool action execution claim is no longer current", "action_already_consumed"); } } async function runApprovedTestInvocation( invocation: typeof toolInvocations.$inferSelect, signedPayload: NonNullable>, actionRequestId: string, ): Promise { const claim = await claimToolTestApproval(db, actionRequestId, invocation.id); if (!claim) return; claim.enforceDeadline = asRecord(signedPayload.approvalSnapshot)?.approvalSnapshotVersion === 2; let execution: Parameters[0]; let connectionRevision: string | null = null; try { const agentId = invocation.agentId; if (!invocation.connectionId || !agentId) { throw new ToolGatewayHttpError(409, "Test action context is no longer available", "action_origin_invalid"); } const delegated = invocation.policyExplanation?.delegatedConnectionTest as { agentId: string; responsibleUserId: string; runId: string | null; keyId: string | null; resource: ConnectionManagementContext["resource"]; } | undefined; const userId = delegated?.responsibleUserId ?? invocation.actorId ?? "board"; const mcpAppViewCall = asRecord(invocation.policyExplanation?.mcpAppViewCall); const session: ToolGatewaySession = { id: "test-call", token: "test-call", companyId: invocation.companyId, agentId, runId: null, issueId: mcpAppViewCall && typeof mcpAppViewCall.issueId === "string" ? mcpAppViewCall.issueId : null, projectId: mcpAppViewCall && typeof mcpAppViewCall.projectId === "string" ? mcpAppViewCall.projectId : null, actorType: delegated ? "agent" : "user", actorId: delegated?.agentId ?? userId, responsibleUserId: userId, createdAt: new Date(), expiresAt: new Date(Date.now() + DEFAULT_SESSION_TTL_MS), }; let managementContext: ConnectionManagementContext | undefined; if (delegated) { managementContext = await connectionManagementService(db).authorize({ type: "agent", companyId: invocation.companyId, agentId: delegated.agentId, onBehalfOfUserId: delegated.responsibleUserId, runId: delegated.runId, keyId: delegated.keyId, }, "connections:test", delegated.resource, { targetAgentIds: [agentId], afterHumanAction: true }); Object.assign(session, managementContext.workContext, { originatingAgentId: delegated.agentId, approvedInvocationId: invocation.id }); } connectionRevision = await toolApprovalConnectionRevision(db, invocation.companyId, invocation.connectionId, signedPayload.approvalSnapshot); const tool = (await connectedMcpToolsForConnection(invocation.companyId, invocation.connectionId)) .find(candidate => candidate.name === invocation.toolName || candidate.upstreamToolName === invocation.toolName); if (!tool) throw new ToolGatewayHttpError(404, `Tool "${invocation.toolName}" is no longer connected`, "tool_not_found"); // A view's held call runs only while its tool is still callable from apps. if (mcpAppViewCall && !mcpAppToolCallableFromApp((asRecord(tool.providerMetadata)?.ui ?? null) as McpAppToolUi | null)) { throw new ToolGatewayHttpError(409, `Tool "${tool.upstreamToolName ?? tool.name}" is no longer available to this app`, "mcp_app_tool_not_callable"); } await prepareApprovedConnectionAuthorization(session, tool, signedPayload.approvalSnapshot); const liveApprovalSnapshot = await connectedRemoteApprovalSnapshot(session, tool); if (!approvalSnapshotsMatch(signedPayload.approvalSnapshot, liveApprovalSnapshot)) { throw new ToolGatewayHttpError(409, approvalTargetChangeMessage(signedPayload.approvalSnapshot, liveApprovalSnapshot), "approved_tool_target_changed"); } if (!(await approvedManagedArgumentsRemainCurrent(session, tool, signedPayload.arguments))) { throw new ToolGatewayHttpError(409, "Approved tool action managed arguments changed after review", "approved_tool_managed_arguments_changed"); } await bindVerifiedApprovalArguments(invocation, claim, signedPayload.arguments); const access = await basePolicyService.admitInvocation( policyInputForTool({ session, tool, parameters: signedPayload.arguments, consumeRateLimit: false }), invocation.id, claim, async (policy, admissionInput) => { const callerSession = delegatedTestCallerSession(session); const callerInput = callerSession ? policyInputForTool({ session: callerSession, tool, parameters: signedPayload.arguments, consumeRateLimit: true }) : null; const options = { admittedInvocationId: invocation.id }; const caller = callerInput ? await policy.decide(callerInput, options) : null; const target = await policy.decide(admissionInput, { ...options, sharedRateDecision: caller ?? undefined }); const chosen = caller && !caller.allowed && caller.decision !== "require_approval" ? caller : !target.allowed ? target : caller?.decision === "require_approval" ? caller : target; if (callerInput && caller) await policy.writeAudit(callerInput, caller); return { ...chosen, policyExplanation: { ...chosen.policyExplanation, consumedRateAdmissions: target.policyExplanation?.consumedRateAdmissions, delegatedCallerConsumedRateAdmissions: caller?.policyExplanation?.consumedRateAdmissions, } }; }, ); if (!access.allowed && access.decision !== "require_approval") { throw new ToolGatewayHttpError(403, access.explanation, access.reasonCode); } const argumentsSummary = (await validateToolContent({ value: signedPayload.arguments, direction: "arguments", sensitiveMode: "redact", promptInjectionMode: "ignore" })).summary; execution = { session, managementContext, tool, parameters: signedPayload.arguments, invocationId: invocation.id, companyId: invocation.companyId, agentId, userId, argumentsSummary, reasonCode: "approval_granted", approvedClaim: claim, matchedPolicyIds: invocation.matchedPolicyIds ?? [] }; } catch (err) { if (connectionRevision !== null && isToolApprovalConnectionError(err)) { if (await releaseToolApproval(db, claim, connectionRevision)) { await reflectToolActionInteractionLifecycle({ actionRequestId, status: "approved", errorCode: TOOL_APPROVAL_CONNECTION_REQUIRED, errorMessage: TOOL_APPROVAL_CONNECTION_MESSAGE }); } return; } if (!isApprovalPreparationRejection(err)) { // Preparation has not entered runTestToolInvocation. Preserve approval // through dependency failures; the claim owner still verifies no dispatch. await releaseToolApproval(db, claim); throw err; } const message = err instanceof Error ? err.message : String(err); const errorCode = err instanceof ToolGatewayHttpError || err instanceof ToolContentValidationError ? err.reasonCode : "tool_execution_failed"; const settled = await persistToolTestOutcome(db, invocation.id, { status: "failed", errorCode, errorMessage: message }, claim); if (settled) void emitConnectionInvoked(db, invocation.id); return; } await runTestToolInvocation(execution); } async function waitForActionRequestExecution(actionRequestId: string) { let deadline = Date.now() + ACTION_REQUEST_EXECUTION_WAIT_MS; while (true) { const [match] = await db .select({ actionRequest: toolActionRequests, invocationStatus: toolInvocations.status, invocationStartedAt: toolInvocations.startedAt, }) .from(toolActionRequests) .innerJoin( toolInvocations, eq(toolInvocations.id, toolActionRequests.invocationId), ) .where(eq(toolActionRequests.id, actionRequestId)) .limit(1); const row = match?.actionRequest; if (!row || row.status !== "executing") return row ?? null; deadline = extendApprovedExecutionWaitDeadline({ currentDeadlineMs: deadline, invocationStatus: match.invocationStatus, invocationStartedAt: match.invocationStartedAt, preparationStartedAt: row.updatedAt, preparationWaitMs: ACTION_REQUEST_PREPARATION_WAIT_MS, executionWaitMs: ACTION_REQUEST_EXECUTION_WAIT_MS, }); const remainingMs = deadline - Date.now(); if (remainingMs <= 0) break; await new Promise((resolve) => setTimeout( resolve, Math.min(ACTION_REQUEST_EXECUTION_POLL_MS, remainingMs), ), ); } throw new ToolGatewayHttpError( 409, "Approved tool action is still executing", "action_execution_in_progress", { actionRequestId, preparationWaitMs: ACTION_REQUEST_PREPARATION_WAIT_MS, executionWaitMs: ACTION_REQUEST_EXECUTION_WAIT_MS, }, ); } function storedInvocationResult( invocation: typeof toolInvocations.$inferSelect, ): unknown { const summary = invocation.resultSummary?.summary; if (typeof summary !== "string") return null; try { return JSON.parse(summary); } catch { return summary; } } async function actionRequestResolution( actionRequest: typeof toolActionRequests.$inferSelect, ) { if ( actionRequest.status !== "executed" && actionRequest.status !== "failed" ) return actionRequest; const [invocation] = await db .select() .from(toolInvocations) .where(eq(toolInvocations.id, actionRequest.invocationId)) .limit(1); return { ...actionRequest, resultSummary: invocation?.resultSummary?.summary ?? null, error: invocation?.errorMessage ?? null, }; } /** * Return a claimed approved action to approved, under the same claim, when * its call stopped without finishing: the provider's task is still running, * or the app asked the person a question. The next execution continues it * (attaches to the task, or sends the answer) without asking for approval again. */ async function resumeApprovedActionForPendingTask(input: { actionRequestId: string; invocationId: string; claimUpdatedAt: Date; message: string; errorCode?: "provider_task_pending" | "elicitation_required"; }) { const now = new Date(); const errorCode = input.errorCode ?? "provider_task_pending"; return db.transaction(async (tx) => { const [invocation] = await tx.select({ status: toolInvocations.status }).from(toolInvocations) .where(eq(toolInvocations.id, input.invocationId)).for("update").limit(1); // A question stop already marked the invocation as waiting. const resumable = invocation?.status === "executing" || (errorCode === "elicitation_required" && invocation?.status === "awaiting_approval"); if (!resumable) return false; const [actionRequest] = await tx.select({ companyId: toolActionRequests.companyId, status: toolActionRequests.status, updatedAt: toolActionRequests.updatedAt }) .from(toolActionRequests).where(eq(toolActionRequests.id, input.actionRequestId)).for("update").limit(1); if (actionRequest?.status !== "executing" || actionRequest.updatedAt.getTime() !== input.claimUpdatedAt.getTime()) return false; await notifyToolReviewChange(tx, actionRequest.companyId); await tx.update(toolInvocations).set({ status: "awaiting_approval", startedAt: null, errorCode, errorMessage: input.message, updatedAt: now, }).where(and(eq(toolInvocations.id, input.invocationId), inArray(toolInvocations.status, ["executing", "awaiting_approval"]))); await tx.update(toolActionRequests).set({ status: "approved", updatedAt: now }) .where(and(eq(toolActionRequests.id, input.actionRequestId), eq(toolActionRequests.status, "executing"), eq(toolActionRequests.updatedAt, input.claimUpdatedAt))); return true; }); } async function markApprovedActionFailed(input: { actionRequestId: string; invocationId: string; claimUpdatedAt: Date; expectedInvocationStatus: "awaiting_approval" | "executing"; error: unknown; }) { const reasonCode = (input.error instanceof ToolGatewayHttpError || input.error instanceof ToolContentValidationError) ? input.error.reasonCode : "tool_execution_failed"; const message = input.error instanceof Error ? input.error.message : String(input.error); const now = new Date(); const settled = await db.transaction(async (tx) => { // Lock in the same invocation -> request order used by the normal // execution settlement path. The claim timestamp is the ownership token: // a consumer that merely read an approved row cannot settle another // consumer's claim, and a pre-dispatch failure cannot overwrite a call // that has already entered provider execution or completed successfully. const [invocation] = await tx .select({ status: toolInvocations.status }) .from(toolInvocations) .where(eq(toolInvocations.id, input.invocationId)) .for("update") .limit(1); if (invocation?.status !== input.expectedInvocationStatus) return false; const [actionRequest] = await tx .select({ companyId: toolActionRequests.companyId, status: toolActionRequests.status, updatedAt: toolActionRequests.updatedAt, }) .from(toolActionRequests) .where(eq(toolActionRequests.id, input.actionRequestId)) .for("update") .limit(1); if ( actionRequest?.status !== "executing" || actionRequest.updatedAt.getTime() !== input.claimUpdatedAt.getTime() ) { return false; } await notifyToolReviewChange(tx, actionRequest.companyId); await tx .update(toolInvocations) .set({ status: "failed", idempotencyKey: null, errorCode: reasonCode, errorMessage: message, completedAt: now, updatedAt: now, }) .where( and( eq(toolInvocations.id, input.invocationId), eq(toolInvocations.status, input.expectedInvocationStatus), ), ); await tx .update(toolActionRequests) .set({ status: "failed", resolvedAt: now, updatedAt: now, }) .where( and( eq(toolActionRequests.id, input.actionRequestId), eq(toolActionRequests.status, "executing"), eq(toolActionRequests.updatedAt, input.claimUpdatedAt), ), ); return true; }); if (!settled) return { reasonCode, message, settled: false }; void emitConnectionInvoked(db, input.invocationId); await reflectToolActionInteractionLifecycle({ actionRequestId: input.actionRequestId, status: "failed", errorCode: reasonCode, errorMessage: message, }); return { reasonCode, message, settled: true }; } async function expireApprovedActionForManagedArgumentDrift(input: { companyId: string; actionRequestId: string; invocationId: string; toolName: string; ownsExecutingClaim?: boolean; }) { const error = new ToolGatewayHttpError( 409, "Approved tool action managed arguments changed after review; request a new approval", "approved_tool_managed_arguments_changed", { actionRequestId: input.actionRequestId, invocationId: input.invocationId, tool: input.toolName, }, ); const now = new Date(); await options.beforeManagedArgumentDriftExpiry?.(); const [expired] = await writeToolReviewChange(db, input.companyId, tx => tx .update(toolActionRequests) .set({ status: "expired", resolvedAt: now, updatedAt: now }) .where( and( eq(toolActionRequests.id, input.actionRequestId), input.ownsExecutingClaim ? inArray(toolActionRequests.status, ["approved", "executing"]) : eq(toolActionRequests.status, "approved"), ), ) .returning({ id: toolActionRequests.id })); if (!expired) return error; await db .update(toolInvocations) .set({ status: "failed", approvalState: "expired", idempotencyKey: null, errorCode: error.reasonCode, errorMessage: error.message, completedAt: now, updatedAt: now, }) .where(eq(toolInvocations.id, input.invocationId)); void emitConnectionInvoked(db, input.invocationId); await reflectToolActionInteractionLifecycle({ actionRequestId: expired.id, status: "expired", errorCode: error.reasonCode, errorMessage: error.message, }); return error; } // Guard for approved-action execution: the issue must still be open. Expires // the claimed request and reflects the interaction lifecycle when it is not. // Called twice — after winning the executing claim, and again immediately // before provider dispatch, because tool/snapshot resolution between the two // involves network calls and leaves a seconds-wide window for the issue to // close. async function assertIssueOpenForApprovedAction(input: { claimed: typeof toolActionRequests.$inferSelect; invocation: typeof toolInvocations.$inferSelect; }): Promise<{ projectId: string | null }> { const { claimed, invocation } = input; const [issue] = await db .select({ status: issues.status, projectId: issues.projectId }) .from(issues) .where( and( eq(issues.id, invocation.issueId!), eq(issues.companyId, invocation.companyId), ), ) .limit(1); if (issue && issue.status !== "done" && issue.status !== "cancelled") { return { projectId: issue.projectId }; } const expiredAt = new Date(); await writeToolReviewChange(db, claimed.companyId, tx => tx .update(toolActionRequests) .set({ status: "expired", resolvedAt: expiredAt, updatedAt: expiredAt }) .where(eq(toolActionRequests.id, claimed.id))); await reflectToolActionInteractionLifecycle({ actionRequestId: claimed.id, status: "expired", }); throw new ToolGatewayHttpError( 409, "The issue for this tool action is closed; the approval has expired", "action_issue_closed", { actionRequestId: claimed.id, invocationId: invocation.id }, ); } async function restoreApprovedActionIdentity( session: ToolGatewaySession, identityContextId: string | undefined, ) { if (session.gatewayTokenId && session.gatewayId) { const [token] = await db.select({ subjectType: toolMcpGatewayTokens.subjectType, issuer: toolMcpGatewayTokens.createdByAgentId, userId: toolMcpGatewayTokens.responsibleUserId }) .from(toolMcpGatewayTokens).where(and(eq(toolMcpGatewayTokens.id, session.gatewayTokenId), eq(toolMcpGatewayTokens.companyId, session.companyId), eq(toolMcpGatewayTokens.gatewayId, session.gatewayId))); // Durable delegated clients retain issuer authority across approval. // Board clients and independently run-bound heartbeat clients keep their identity. if (token?.subjectType === "gateway_client" && (token.issuer || token.userId)) { session.originatingAgentId = token.issuer ?? session.originatingAgentId ?? session.actorId; session.responsibleUserId = token.userId; } } if (!identityContextId) return; const [origin] = await db .select() .from(runIdentityContexts) .where( and( eq(runIdentityContexts.id, identityContextId), eq(runIdentityContexts.companyId, session.companyId), eq(runIdentityContexts.runId, session.runId!), eq(runIdentityContexts.status, "accepted"), ), ); if (!origin) throw new ToolGatewayHttpError( 409, "Approved action identity is unavailable", "identity_context_unavailable", ); session.identityContextId = origin.id; session.responsibleUserId = origin.cause === "company_default" ? null : origin.responsibleUserId; } async function executeApprovedAgentInvocation(input: { actionRequest: typeof toolActionRequests.$inferSelect; invocation: typeof toolInvocations.$inferSelect; }) { const { actionRequest, invocation } = input; if ( !invocation.agentId || !invocation.issueId || isTestOriginInvocation(invocation) ) { throw new ToolGatewayHttpError( 409, "Tool action request is not an agent-origin action", "action_origin_invalid", ); } const [claimed] = await writeToolReviewChange(db, actionRequest.companyId, tx => tx .update(toolActionRequests) .set({ status: "executing", updatedAt: new Date() }) .where( and( eq(toolActionRequests.id, actionRequest.id), eq(toolActionRequests.status, "approved"), ), ) .returning()); if (!claimed) { const settled = await waitForActionRequestExecution(actionRequest.id); const [settledInvocation] = await db .select() .from(toolInvocations) .where(eq(toolInvocations.id, invocation.id)) .limit(1); if (settled?.status === "executed" && settledInvocation) { return storedInvocationResult(settledInvocation); } if (settled?.status === "failed") { throw new ToolGatewayHttpError( 502, settledInvocation?.errorMessage ?? "Approved tool action failed", settledInvocation?.errorCode ?? "tool_execution_failed", { actionRequestId: actionRequest.id, invocationId: invocation.id }, ); } throw new ToolGatewayHttpError( 409, "Tool action request was already consumed", "action_already_consumed", ); } const claim: ToolApprovalClaim = { actionRequestId: claimed.id, invocationId: invocation.id, claimedAt: claimed.updatedAt, }; const agentId = invocation.agentId; let connectionRevision: string | null = null; async function prepareExecution() { // Terminal-issue expiry revokes pending/approved requests, but a claim that // committed just before the issue closed slips past that revocation. Recheck // the issue after winning the claim so a governed action never runs external // side effects for an issue that is already done or cancelled. const issue = await assertIssueOpenForApprovedAction({ claimed, invocation, }); const signedPayload = readSignedToolArgumentsPayload({ signedArguments: claimed.signedArguments, invocationId: invocation.id, toolName: invocation.toolName, signingSecret: options.toolActionSigningSecret, }); if (!signedPayload) { const error = new ToolGatewayHttpError( 409, "Approved tool action arguments signature is invalid", "signed_arguments_invalid", ); throw error; } if (signedPayload.executionOnApprove !== true) { const error = new ToolGatewayHttpError( 409, "This approval predates execute-on-approve and must remain inert", "legacy_approved_action_inert", ); throw error; } claim.enforceDeadline = asRecord(signedPayload.approvalSnapshot)?.approvalSnapshotVersion === 2; const session: ToolGatewaySession = { id: `approved-action:${claimed.id}`, token: "", companyId: invocation.companyId, agentId, runId: invocation.runId, issueId: invocation.issueId, projectId: issue?.projectId ?? null, gatewayId: invocation.gatewayId, gatewayPublicId: invocation.gatewayPublicId, gatewayTokenId: invocation.gatewayTokenId, actorType: invocation.actorType as ToolGatewaySession["actorType"], actorId: invocation.actorId, originatingAgentId: typeof invocation.policyExplanation?.delegatedGatewayIssuer === "string" ? invocation.policyExplanation.delegatedGatewayIssuer : invocation.actorType === "agent" && invocation.gatewayId && !invocation.runId && !invocation.gatewayTokenId ? invocation.actorId : null, createdAt: new Date(), expiresAt: new Date(Date.now() + DEFAULT_SESSION_TTL_MS), }; await restoreApprovedActionIdentity( session, signedPayload.identityContextId, ); session.approvedInvocationId = invocation.id; session.approvedSlackInvocationId = invocation.id; connectionRevision = await toolApprovalConnectionRevision(db, invocation.companyId, invocation.connectionId, signedPayload.approvalSnapshot); const tool = await findToolForSession(session, invocation.toolName); await prepareApprovedConnectionAuthorization(session, tool, signedPayload.approvalSnapshot); const liveApprovalSnapshot = await connectedRemoteApprovalSnapshot( session, tool, ); if ( !approvalSnapshotsMatch( signedPayload.approvalSnapshot, liveApprovalSnapshot, ) ) { const error = new ToolGatewayHttpError( 409, approvalTargetChangeMessage(signedPayload.approvalSnapshot, liveApprovalSnapshot), "approved_tool_target_changed", ); throw error; } const parameters = signedPayload.arguments; const canonicalArguments = canonicalToolArguments(parameters); if ( ![ toolRequestIdentityHash(parameters, options.toolActionSigningSecret), // Historical approvals used the redacted preview hash. Their signature // still binds the complete canonical arguments checked below. summarizeToolValue(parameters).sha256, ].includes(claimed.canonicalArgumentsHash) || !verifyToolArgumentsSignature({ signedArguments: claimed.signedArguments, invocationId: invocation.id, toolName: invocation.toolName, canonicalArguments, approvalSnapshot: signedPayload.approvalSnapshot, executionOnApprove: true, identityContextId: signedPayload.identityContextId, signingSecret: options.toolActionSigningSecret, }) ) { const error = new ToolGatewayHttpError( 409, "Approved tool action arguments do not match reviewed hash", "signed_arguments_mismatch", ); throw error; } const managedArgumentsRemainCurrent = await approvedManagedArgumentsRemainCurrent(session, tool, parameters); if (!managedArgumentsRemainCurrent) { throw await expireApprovedActionForManagedArgumentDrift({ companyId: claimed.companyId, actionRequestId: claimed.id, invocationId: invocation.id, toolName: invocation.toolName, ownsExecutingClaim: true, }); } const argumentsSummary = (await validateToolContent({ value: parameters, direction: "arguments", sensitiveMode: "redact", promptInjectionMode: "ignore", })).summary; // Validate the signed and managed payload before consuming admission. // Historical payload drift belongs to the expiry owner above. await bindVerifiedApprovalArguments(invocation, claim, signedPayload.arguments); const currentAccess = await policyService.admitInvocation( policyInputForTool({ session, tool, parameters: signedPayload.arguments, consumeRateLimit: false, }), invocation.id, claim, ); if ( !currentAccess.allowed && currentAccess.decision !== "require_approval" ) throw new ToolGatewayHttpError( 403, currentAccess.explanation, currentAccess.reasonCode, ); // Final recheck at the last DB write before dispatch: tool and snapshot // resolution above involve network calls, so re-verify the issue is still // open now that only the provider call remains. A close that commits after // this read has raced an execution that was approved, claimed, and verified // while the issue was open; that instant is irreducible for an external // side effect gated by DB state (holding a DB lock across a remote provider // call is not an option), and the accepted linearization is that the // execution wins — its result still lands on the expired card via // reflectToolActionInteractionLifecycle. await assertIssueOpenForApprovedAction({ claimed, invocation }); return { session, tool, parameters, argumentsSummary }; } let prepared: Awaited>; try { prepared = await prepareExecution(); } catch (error) { if (connectionRevision !== null && isToolApprovalConnectionError(error)) { if (await releaseToolApproval(db, claim, connectionRevision)) { await reflectToolActionInteractionLifecycle({ actionRequestId: claimed.id, status: "approved", errorCode: TOOL_APPROVAL_CONNECTION_REQUIRED, errorMessage: TOOL_APPROVAL_CONNECTION_MESSAGE }); } } else if (isApprovalPreparationRejection(error)) { await markApprovedActionFailed({ actionRequestId: claimed.id, invocationId: invocation.id, claimUpdatedAt: claimed.updatedAt, expectedInvocationStatus: "awaiting_approval", error, }); } else { await releaseToolApproval(db, claim); } throw error; } const { session, tool, parameters, argumentsSummary } = prepared; const startedAt = Date.now(); // Keep dispatch and outcome persistence outside the preparation retry // boundary. Only the still-current claim may record the provider start. if (!(await startToolInvocation(db, invocation.id, claim))) { throw new ToolGatewayHttpError(409, "Tool action execution claim is no longer current", "action_already_consumed"); } await reflectToolActionInteractionLifecycle({ actionRequestId: claimed.id, status: "executing", }); try { await assertCurrentGatewayIssuer(session, tool, parameters, invocation.id, true); const executionTimeoutMs = timeoutMs(APPROVED_EXECUTION_TIMEOUT_MS); const connectedMcpExecution = (tool.providerType === "mcp_remote_http" || tool.providerType === "provider_rest") ? await executeRemoteHttpTool( session, tool, parameters, executionTimeoutMs, invocation.id, ) : tool.providerType === "mcp_local_stdio" ? await executeLocalStdioTool( session, tool, parameters, executionTimeoutMs, false, invocation.id, ) : null; const result = connectedMcpExecution ? connectedMcpExecution.result : tool.providerType !== "paperclip_plugin" ? await runWithTimeout( executeBuiltinTool(session, tool, parameters, invocation.id), executionTimeoutMs, ) : (() => { throw new ToolGatewayHttpError( 409, "Plugin actions cannot execute outside their originating run", "approved_execution_unsupported", ); })(); const resultValidation = await validateToolContent({ value: result, direction: "result", sensitiveMode: "redact", promptInjectionMode: "block", classifier: resultClassifier(session, tool, invocation.id, { approvedAction: true }), }); const resultRecord = asRecord(resultValidation.value); if (resultRecord?.error) throw new ToolGatewayHttpError( resultRecord.errorCode === "github_access_denied" ? 403 : 502, toolResultErrorMessage(resultRecord, connectedMcpExecution?.failureInstructions), resultRecord.errorCode === "github_access_denied" ? "github_access_denied" : "tool_execution_failed", ); const now = new Date(); await db .update(toolInvocations) .set({ status: "succeeded", resultHash: resultValidation.summary.sha256 ?? null, resultSummary: resultValidation.summary, resultSizeBytes: resultValidation.summary.sizeBytes ?? null, completedAt: now, updatedAt: now, }) .where(eq(toolInvocations.id, invocation.id)); await markMcpTaskDelivered(invocation.companyId, invocation.id); void emitConnectionInvoked(db, invocation.id); await writeToolReviewChange(db, claimed.companyId, tx => tx .update(toolActionRequests) .set({ status: "executed", resolvedAt: now, updatedAt: now }) .where(eq(toolActionRequests.id, claimed.id))); await reflectToolActionInteractionLifecycle({ actionRequestId: claimed.id, status: "executed", resultSummary: resultValidation.summary.summary, }); await writeToolCallEvent({ invocationId: invocation.id, actionRequestId: claimed.id, session, eventType: "call_completed", outcome: "success", toolName: tool.name, policyDecision: "allow", reasonCode: "approved_action_executed", argumentsSummary, resultSummary: resultValidation.summary, detectorMetadata: resultValidation.detectorMetadata, metadata: { durationMs: Date.now() - startedAt, timeoutMs: executionTimeoutMs, }, tool, }); return resultValidation.value; } catch (error) { // The provider is still working on the approved action. Keep the // approval: the next execution attaches to the same task instead of // asking the person again or starting the work twice. if (error instanceof ToolGatewayHttpError && error.reasonCode === "provider_task_pending" && await resumeApprovedActionForPendingTask({ actionRequestId: claimed.id, invocationId: invocation.id, claimUpdatedAt: claimed.updatedAt, message: error.message })) { throw error; } // The app asked the person a question: keep the approval, so the // repeated call carries the answer instead of failing the action. if (error instanceof ToolGatewayHttpError && error.reasonCode === "elicitation_required" && await resumeApprovedActionForPendingTask({ actionRequestId: claimed.id, invocationId: invocation.id, claimUpdatedAt: claimed.updatedAt, message: error.message, errorCode: "elicitation_required" })) { throw error; } const { reasonCode } = await markApprovedActionFailed({ actionRequestId: claimed.id, invocationId: invocation.id, claimUpdatedAt: claimed.updatedAt, expectedInvocationStatus: "executing", error, }); await writeToolCallEvent({ invocationId: invocation.id, actionRequestId: claimed.id, session, eventType: "call_failed", outcome: "failure", toolName: tool.name, policyDecision: "deny", reasonCode, argumentsSummary, metadata: { durationMs: Date.now() - startedAt, ...(error instanceof ToolContentValidationError ? { promptInjection: error.detectorMetadata, findings: error.findings } : {}) }, tool, }); throw error; } } async function matchingAgentActionRequest(input: { session: ToolGatewaySession; toolName: string; argumentsHash: string; parameters: unknown; }) { if (!input.session.issueId || !input.session.agentId) return null; const [match] = await db .select({ actionRequest: toolActionRequests, invocation: toolInvocations, }) .from(toolActionRequests) .innerJoin( toolInvocations, eq(toolInvocations.id, toolActionRequests.invocationId), ) .where( and( eq(toolActionRequests.companyId, input.session.companyId), eq(toolActionRequests.issueId, input.session.issueId), inArray(toolActionRequests.canonicalArgumentsHash, [input.argumentsHash, summarizeToolValue(input.parameters).sha256]), eq(toolInvocations.agentId, input.session.agentId), eq(toolInvocations.toolName, input.toolName), inArray(toolActionRequests.status, [ "pending", "approved", "executing", "rejected", "executed", "failed", ]), ), ) .orderBy( desc(sql`${toolActionRequests.canonicalArgumentsHash} = ${input.argumentsHash}`), desc(toolActionRequests.createdAt), ) .limit(1); if (!match) return null; if (match.actionRequest.signedArguments) { const signed = readSignedToolArgumentsPayload({ signedArguments: match.actionRequest.signedArguments, invocationId: match.invocation.id, toolName: match.invocation.toolName, signingSecret: options.toolActionSigningSecret, }); // Redacted legacy hashes can collide across different secrets. Only // replay the exact authenticated arguments, including legacy approvals. if (!signed || canonicalToolArguments(signed.arguments) !== canonicalToolArguments(input.parameters)) return null; } else if (match.actionRequest.canonicalArgumentsHash !== input.argumentsHash) { return null; } // Rejection applies to that intent, not every later human request with the // same arguments. A new trusted request still passes the normal policy and // Ask first path below; it receives no execution or approval authority here. if (match.actionRequest.status === "rejected" && input.session.runId && input.session.responsibleUserId) { const [intent] = await db.select({ run: { id: heartbeatRuns.id, companyId: heartbeatRuns.companyId, agentId: heartbeatRuns.agentId, status: heartbeatRuns.status, responsibleUserId: heartbeatRuns.responsibleUserId, startedAt: heartbeatRuns.startedAt, issueId: heartbeatRuns.issueId, nativeIssueId: heartbeatRuns.nativeIssueId, contextSnapshot: sql>`jsonb_build_object( 'source', ${heartbeatRuns.contextSnapshot}->'source', 'issueId', ${heartbeatRuns.contextSnapshot}->'issueId', 'taskId', ${heartbeatRuns.contextSnapshot}->'taskId', 'commentId', ${heartbeatRuns.contextSnapshot}->'commentId')`, }, comment: issueComments, }).from(heartbeatRuns).innerJoin(issueComments, and( eq(issueComments.companyId, heartbeatRuns.companyId), eq(issueComments.issueId, input.session.issueId), eq(issueComments.id, sql`case when ${heartbeatRuns.contextSnapshot}->>'commentId' ~* '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$' then (${heartbeatRuns.contextSnapshot}->>'commentId')::uuid end`), )).where(and( eq(heartbeatRuns.id, input.session.runId), eq(heartbeatRuns.companyId, input.session.companyId), eq(heartbeatRuns.agentId, input.session.agentId), )).limit(1); if (intent && isNewHumanIntentAfterToolRejection({ session: input.session, rejection: match.actionRequest, invocation: match.invocation, ...intent })) return null; } if (match.actionRequest.status === "failed" && match.invocation.errorCode !== "provider_interaction_required") return null; // The gateway builds an ask-first request in two steps inside one call: it // inserts the row with a null signature and a null expiry, then signs the // row and sets the expiry. A concurrent matching call can observe the row in // this window. A null signature does not prove the create stopped, because a // parallel create can still be signing the same row right now. Only treat an // unsigned row as abandoned after the grace time from createdAt has passed; // before that, return the match so the retry replays approval_required and // does not create a duplicate request or expire a live row. After the grace // time an unsigned row stays pending forever and the review queue hides it, // so it can never be approved. Do not replay it as a live approval. Expire // the row and let the retry create a fresh, signable request. A null expiry // alone (without this guard) also makes the getTime() check below unsafe. const pendingRequest = match.actionRequest; const pendingUnsigned = pendingRequest.status === "pending" && pendingRequest.signedArguments === null && Date.now() - pendingRequest.createdAt.getTime() >= TOOL_ACTION_REQUEST_SIGNING_GRACE_MS; const pendingExpired = pendingRequest.status === "pending" && pendingRequest.expiresAt !== null && pendingRequest.expiresAt.getTime() <= Date.now(); if (pendingUnsigned || pendingExpired) { const now = new Date(); await writeToolReviewChange(db, pendingRequest.companyId, tx => tx .update(toolActionRequests) .set({ status: "expired", resolvedAt: now, updatedAt: now }) .where( and( eq(toolActionRequests.id, match.actionRequest.id), eq(toolActionRequests.status, "pending"), ), )); await db .update(toolInvocations) .set({ approvalState: "expired", idempotencyKey: null, updatedAt: now, }) .where(eq(toolInvocations.id, match.invocation.id)); await reflectToolActionInteractionLifecycle({ actionRequestId: match.actionRequest.id, status: "expired", }); return null; } return match; } async function replayMatchingAgentAction(input: { session: ToolGatewaySession; toolName: string; argumentsHash: string; parameters: unknown; }) { const match = await matchingAgentActionRequest(input); if (!match) return null; const { actionRequest, invocation } = match; if (actionRequest.status === "failed") { throw new ToolGatewayHttpError(409, "The provider is waiting for authorization or approval. Continue the existing execution; do not repeat the original call.", "provider_interaction_required", { invocationId: invocation.id, actionRequestId: actionRequest.id, upstreamPending: recoverUpstreamHandoff(invocation), }); } if (actionRequest.status === "pending") { await throwApprovalRequired({ invocationId: invocation.id, actionRequestId: actionRequest.id, interactionId: actionRequest.interactionId, issueId: input.session.issueId!, toolName: input.toolName, argumentsHash: input.argumentsHash, }); } if (actionRequest.status === "rejected") { throw new ToolGatewayHttpError( 409, "This tool action was declined; do not retry the same call", "action_declined", { invocationId: invocation.id, actionRequestId: actionRequest.id, instructions: "The action was declined. Do not retry the same call on your own; adjust your approach or report the decline on the task. If the person asks for the same action again in a new message, the call made for that message posts a fresh approval card.", }, ); } if (actionRequest.status === "executed") { return { matched: true as const, result: storedInvocationResult(invocation), invocationId: invocation.id, }; } if (actionRequest.status === "executing") { const settled = await waitForActionRequestExecution(actionRequest.id); const [settledInvocation] = await db .select() .from(toolInvocations) .where(eq(toolInvocations.id, invocation.id)) .limit(1); if (settled?.status === "executed" && settledInvocation) { return { matched: true as const, result: storedInvocationResult(settledInvocation), invocationId: invocation.id, }; } throw new ToolGatewayHttpError( 502, settledInvocation?.errorMessage ?? "Approved tool action failed", settledInvocation?.errorCode ?? "tool_execution_failed", ); } if (actionRequest.status === "approved" && actionRequest.decidedAt) { const result = await executeApprovedAgentInvocation({ actionRequest, invocation, }); return { matched: true as const, result, invocationId: invocation.id }; } return null; } /** * Project an ask-first test request + its invocation onto the lifecycle the * Test tab panel renders. Recovers the redacted parameter snapshot (the * "Where" row) and, once the call has run, the structured result or error. */ async function buildTestCallStatus( actionRequest: typeof toolActionRequests.$inferSelect, invocation: typeof toolInvocations.$inferSelect, ): Promise { const invocationDone = invocation.status === "succeeded" || invocation.status === "failed" || invocation.status === "timed_out" || invocation.status === "rate_limited" || invocation.status === "denied"; let phase: ToolConnectionTestCallStatusPhase; if (actionRequest.status === "rejected") { phase = "denied"; } else if (actionRequest.status === "cancelled") { phase = "cancelled"; } else if (actionRequest.status === "expired") { phase = "expired"; } else if ( actionRequest.status === "approved" || actionRequest.status === "executed" || actionRequest.status === "failed" ) { phase = invocationDone ? "done" : "running"; } else { phase = "waiting"; } // Recover a redacted, structured snapshot of the parameters for the // "Where" row — the test-call response never echoes them back. let parameters: Record | null = null; const signed = readSignedToolArgumentsPayload({ signedArguments: actionRequest.signedArguments, invocationId: invocation.id, toolName: invocation.toolName, signingSecret: options.toolActionSigningSecret, }); if ( signed && signed.arguments && typeof signed.arguments === "object" && !Array.isArray(signed.arguments) ) { const redacted = (await validateToolContent({ value: signed.arguments, direction: "arguments", sensitiveMode: "redact", promptInjectionMode: "ignore", })).value; if ( redacted && typeof redacted === "object" && !Array.isArray(redacted) ) { parameters = redacted as Record; } } let result: unknown; let error: ToolConnectionTestCallStatus["error"]; if (phase === "done") { if (invocation.status === "succeeded") { const summary = invocation.resultSummary?.summary; if (typeof summary === "string") { try { result = JSON.parse(summary); } catch { result = summary; } } else { result = null; } } else { error = { message: invocation.errorMessage ?? "The call didn't complete.", reasonCode: invocation.errorCode ?? null, }; } } const durationMs = invocation.startedAt && invocation.completedAt ? Math.max( 0, invocation.completedAt.getTime() - invocation.startedAt.getTime(), ) : null; return { actionRequestId: actionRequest.id, invocationId: invocation.id, phase, parameters, ...(result !== undefined ? { result } : {}), ...(error ? { error } : {}), ...(recoverUpstreamHandoff(invocation) ? { upstreamPending: recoverUpstreamHandoff(invocation) } : {}), durationMs, requestedAt: actionRequest.createdAt.toISOString(), resolvedAt: actionRequest.resolvedAt ? actionRequest.resolvedAt.toISOString() : null, }; } const reviewProjection = toolReviewProjectionService(db, reflectToolActionInteractionLifecycle); const reviewInterruption = toolReviewInterruptionService(db, async settled => { void emitConnectionInvoked(db, settled.invocationId); await reflectToolActionInteractionLifecycle(settled); }); const reviewExpiry = toolReviewExpiryService(db, async expired => { void emitConnectionInvoked(db, expired.invocationId); await reflectToolActionInteractionLifecycle(expired); }); return { async recordRuntimeMcpDeliveryDiagnostic(input: { companyId: string; agentId: string; runId: string; permittedNotInstalledConnections: Array<{ id: string; name: string }>; }) { if (input.permittedNotInstalledConnections.length === 0) return; const [run] = await db .select({ issueId: sql< string | null >`${heartbeatRuns.contextSnapshot} ->> 'issueId'`, }) .from(heartbeatRuns) .where( and( eq(heartbeatRuns.id, input.runId), eq(heartbeatRuns.companyId, input.companyId), eq(heartbeatRuns.agentId, input.agentId), ), ) .limit(1); await writeAudit({ companyId: input.companyId, agentId: input.agentId, runId: input.runId, issueId: run?.issueId ?? null, action: "tool_gateway.runtime_mcp_delivery", details: { decision: "diagnostic", reasonCode: "permitted_connections_not_installed", deliveredServerCount: 0, permittedNotInstalledCount: input.permittedNotInstalledConnections.length, permittedNotInstalledConnections: input.permittedNotInstalledConnections, }, }); }, async listNamedGateways( companyId: string, ): Promise { // Archived gateways are retired — they must not appear in the list UI. const gateways = await db .select() .from(toolMcpGateways) .where( and( eq(toolMcpGateways.companyId, companyId), ne(toolMcpGateways.status, "archived"), ), ) .orderBy(desc(toolMcpGateways.createdAt)); const rows = await Promise.all( gateways.map((gateway) => getGatewayWithTokens(companyId, gateway.id)), ); return rows; }, async createNamedGateway(input: { companyId: string; body: CreateToolMcpGateway; actor?: { agentId?: string | null; userId?: string | null }; managementContext?: ConnectionManagementContext; }): Promise { await input.managementContext?.reauthorize(); await assertGatewayContext({ companyId: input.companyId, profileId: input.body.profileId, agentId: input.body.agentId ?? null, projectId: input.body.projectId ?? null, issueId: input.body.issueId ?? null, }); const now = new Date(); const slug = input.body.displaySlug ?? input.body.slug ?? slugSegment(input.body.name, "gateway"); const gateway = await db.transaction(async tx => { await assertAgentToolAssignmentInteractions(tx as unknown as Db, input.managementContext?.actor.type === "agent" ? input.managementContext.actor.agentId : input.actor?.agentId, input.companyId, input.body.agentId ? [input.body.agentId] : []); const [gateway] = await tx .insert(toolMcpGateways) .values({ companyId: input.companyId, name: input.body.name, slug, displaySlug: slug, description: input.body.description ?? null, defaultProfileMode: input.body.defaultProfileMode ?? "gateway_only", contextScopeType: input.body.contextScopeType ?? "none", contextScopeId: input.body.contextScopeId ?? null, profileId: input.body.profileId, agentId: input.body.agentId ?? null, projectId: input.body.projectId ?? null, issueId: input.body.issueId ?? null, approvalIssueId: input.body.approvalIssueId ?? null, ...(input.body.authConfig !== undefined ? { authConfig: input.body.authConfig } : {}), ...(input.body.headerPolicy !== undefined ? { headerPolicy: input.body.headerPolicy } : {}), ...(input.body.metadataPolicy !== undefined ? { metadataPolicy: input.body.metadataPolicy } : {}), ...(input.body.onDemandToolsConfig !== undefined ? { onDemandToolsConfig: input.body.onDemandToolsConfig } : {}), metadata: input.body.metadata ?? {}, createdByAgentId: input.actor?.agentId ?? null, createdByUserId: input.actor?.userId ?? null, createdAt: now, updatedAt: now, }) .returning(); await tx .insert(toolProfileBindings) .values({ companyId: input.companyId, profileId: input.body.profileId, targetType: "gateway", targetId: gateway.id, priority: 10, metadata: { source: "named_mcp_gateway" }, createdByAgentId: input.actor?.agentId ?? null, createdByUserId: input.actor?.userId ?? null, }) .onConflictDoNothing(); return gateway; }); await writeAudit({ session: { id: `gateway:${gateway.id}`, token: "", companyId: gateway.companyId, agentId: gateway.agentId, runId: null, issueId: gateway.issueId, projectId: gateway.projectId, gatewayId: gateway.id, gatewayName: gateway.name, actorType: input.actor?.agentId ? "agent" : input.actor?.userId ? "user" : "system", actorId: input.actor?.agentId ?? input.actor?.userId ?? gateway.id, createdAt: now, expiresAt: now, }, companyId: input.companyId, agentId: input.actor?.agentId ?? gateway.agentId, runId: null, issueId: gateway.issueId, actorType: input.actor?.agentId ? "agent" : input.actor?.userId ? "user" : "system", actorId: input.actor?.agentId ?? input.actor?.userId ?? gateway.id, action: "tool_gateway.session_created", details: { decision: "allow", reasonCode: "named_gateway_created", gatewayId: gateway.id, gatewayName: gateway.name, profileId: gateway.profileId, }, }); if (input.managementContext) await logActivity(db, { companyId: input.companyId, ...input.managementContext.audit, action: "tool_gateway.created", entityType: "tool_mcp_gateway", entityId: gateway.id, details: { profileId: gateway.profileId } }); return getGatewayWithTokens(input.companyId, gateway.id); }, async updateNamedGateway(input: { companyId: string; gatewayId: string; body: UpdateToolMcpGateway; managementContext?: ConnectionManagementContext; }): Promise { await input.managementContext?.reauthorize(); const updated = await db.transaction(async tx => { const [existing] = await tx .select() .from(toolMcpGateways) .where( and( eq(toolMcpGateways.companyId, input.companyId), eq(toolMcpGateways.id, input.gatewayId), ), ) .limit(1).for("update"); if (!existing) throw new ToolGatewayHttpError( 404, "MCP gateway not found", "gateway_not_found", ); const targets = [...new Set([existing.agentId, input.body.agentId].filter((id): id is string => Boolean(id)))]; await assertAgentToolAssignmentInteractions(tx as unknown as Db, input.managementContext?.actor.type === "agent" ? input.managementContext.actor.agentId : null, input.companyId, targets); await assertGatewayContext({ companyId: input.companyId, profileId: input.body.profileId ?? existing.profileId, agentId: input.body.agentId === undefined ? existing.agentId : input.body.agentId, projectId: input.body.projectId === undefined ? existing.projectId : input.body.projectId, issueId: input.body.issueId === undefined ? existing.issueId : input.body.issueId, }); const [updated] = await tx .update(toolMcpGateways) .set({ ...(input.body.name !== undefined ? { name: input.body.name } : {}), ...(input.body.slug !== undefined || input.body.displaySlug !== undefined ? { slug: input.body.displaySlug ?? input.body.slug } : {}), ...(input.body.slug !== undefined || input.body.displaySlug !== undefined ? { displaySlug: input.body.displaySlug ?? input.body.slug } : {}), ...(input.body.description !== undefined ? { description: input.body.description ?? null } : {}), ...(input.body.status !== undefined ? { status: input.body.status } : {}), ...(input.body.profileId !== undefined ? { profileId: input.body.profileId } : {}), ...(input.body.defaultProfileMode !== undefined ? { defaultProfileMode: input.body.defaultProfileMode } : {}), ...(input.body.contextScopeType !== undefined ? { contextScopeType: input.body.contextScopeType } : {}), ...(input.body.contextScopeId !== undefined ? { contextScopeId: input.body.contextScopeId ?? null } : {}), ...(input.body.agentId !== undefined ? { agentId: input.body.agentId ?? null } : {}), ...(input.body.projectId !== undefined ? { projectId: input.body.projectId ?? null } : {}), ...(input.body.issueId !== undefined ? { issueId: input.body.issueId ?? null } : {}), ...(input.body.approvalIssueId !== undefined ? { approvalIssueId: input.body.approvalIssueId ?? null } : {}), ...(input.body.authConfig !== undefined ? { authConfig: input.body.authConfig } : {}), ...(input.body.headerPolicy !== undefined ? { headerPolicy: input.body.headerPolicy } : {}), ...(input.body.metadataPolicy !== undefined ? { metadataPolicy: input.body.metadataPolicy } : {}), ...(input.body.onDemandToolsConfig !== undefined ? { onDemandToolsConfig: input.body.onDemandToolsConfig } : {}), ...(input.body.metadata !== undefined ? { metadata: input.body.metadata ?? {} } : {}), updatedAt: new Date(), }) .where( and( eq(toolMcpGateways.companyId, input.companyId), eq(toolMcpGateways.id, input.gatewayId), ), ) .returning(); if (input.body.profileId && input.body.profileId !== existing.profileId) { await tx .insert(toolProfileBindings) .values({ companyId: input.companyId, profileId: input.body.profileId, targetType: "gateway", targetId: input.gatewayId, priority: 10, metadata: { source: "named_mcp_gateway" }, }) .onConflictDoNothing(); } return updated; }); if (input.managementContext) await logActivity(db, { companyId: input.companyId, ...input.managementContext.audit, action: "tool_gateway.updated", entityType: "tool_mcp_gateway", entityId: updated.id, details: { profileId: updated.profileId, status: updated.status } }); return getGatewayWithTokens(input.companyId, updated.id); }, async createNamedGatewayToken(input: NamedGatewayTokenInput): Promise { const { row, token } = await insertNamedGatewayToken(input, false); return { ...toGatewayToken(row), token }; }, /** * Saves an agent-created client token without a usable value. The value is * generated only when the responsible person reveals it, so the creating * agent never receives it in a tool result. */ async createPendingRevealGatewayToken(input: NamedGatewayTokenInput): Promise { return toGatewayToken((await insertNamedGatewayToken(input, true)).row); }, async revealNamedGatewayToken(input: { companyId: string; tokenId: string; userId: string; }): Promise { const [existing] = await db.select().from(toolMcpGatewayTokens).where(and( eq(toolMcpGatewayTokens.companyId, input.companyId), eq(toolMcpGatewayTokens.id, input.tokenId), )).limit(1); if (!existing) throw new ToolGatewayHttpError(404, "MCP gateway token not found", "gateway_token_not_found"); if (!existing.pendingReveal) throw new ToolGatewayHttpError(409, "This token's value was already shown once. Issue a new token to get a new value.", "gateway_token_already_revealed"); if (existing.revokedAt) throw new ToolGatewayHttpError(409, "This token was revoked before its value was revealed.", "gateway_token_revoked"); if (existing.expiresAt && existing.expiresAt.getTime() <= Date.now()) { throw new ToolGatewayHttpError(409, "This token expired before its value was revealed. Create a new token instead.", "gateway_token_expired"); } if (existing.responsibleUserId && existing.responsibleUserId !== input.userId) { throw new ToolGatewayHttpError(403, "Only the person this agent-created token acts for can reveal its value.", "gateway_token_reveal_requires_responsible_person"); } const token = generateNamedGatewayToken(existing.id); const now = new Date(); // Conditional on pendingReveal so concurrent reveals produce one value. // The value exists only in this response, so the reveal and its audit // entry commit together: a failed audit write leaves the token pending. const publications: ActivityPublication[] = []; const row = await db.transaction(async tx => { const [updated] = await tx.update(toolMcpGatewayTokens) .set({ tokenHash: hashGatewayToken(token), pendingReveal: false, updatedAt: now }) .where(and( eq(toolMcpGatewayTokens.companyId, input.companyId), eq(toolMcpGatewayTokens.id, input.tokenId), eq(toolMcpGatewayTokens.pendingReveal, true), isNull(toolMcpGatewayTokens.revokedAt), or(isNull(toolMcpGatewayTokens.expiresAt), gt(toolMcpGatewayTokens.expiresAt, now)), )) .returning(); if (!updated) throw new ToolGatewayHttpError(409, "This token's value was already shown once. Issue a new token to get a new value.", "gateway_token_already_revealed"); await logActivity(tx as unknown as Db, { companyId: input.companyId, actorType: "user", actorId: input.userId, action: "tool_gateway.token_revealed", entityType: "tool_mcp_gateway", entityId: updated.gatewayId, details: { tokenId: updated.id } }, publications); return updated; }); for (const publication of publications) publishActivity(publication); return { ...toGatewayToken(row), token }; }, async revokeNamedGatewayToken(input: { companyId: string; tokenId: string; revokedAt?: Date; managementContext?: ConnectionManagementContext; }): Promise { await input.managementContext?.reauthorize(); const now = input.revokedAt ?? new Date(); const [row] = await db .update(toolMcpGatewayTokens) .set({ revokedAt: now, updatedAt: now }) .where( and( eq(toolMcpGatewayTokens.companyId, input.companyId), eq(toolMcpGatewayTokens.id, input.tokenId), ), ) .returning(); if (!row) throw new ToolGatewayHttpError( 404, "MCP gateway token not found", "gateway_token_not_found", ); if (input.managementContext) await logActivity(db, { companyId: input.companyId, ...input.managementContext.audit, action: "tool_gateway.token_revoked", entityType: "tool_mcp_gateway", entityId: row.gatewayId, details: { tokenId: row.id } }); return toGatewayToken(row); }, async initializeNamedGatewayProtocol(input: { gatewayId?: string | null; gatewayPublicId?: string | null; bearerToken: string; callerHeaders?: Record; }): Promise { return namedGatewaySessionFromBearer({ gatewayId: input.gatewayId ?? null, gatewayPublicId: input.gatewayPublicId ?? null, bearerToken: input.bearerToken, protocolMethod: "initialize", callerHeaders: input.callerHeaders, }); }, async listToolsForNamedGateway(input: { gatewayId?: string | null; gatewayPublicId?: string | null; bearerToken: string; callerHeaders?: Record; signal?: AbortSignal; }): Promise { input.signal?.throwIfAborted(); const session = await namedGatewaySessionFromBearer({ gatewayId: input.gatewayId ?? null, gatewayPublicId: input.gatewayPublicId ?? null, bearerToken: input.bearerToken, protocolMethod: "tools/list", callerHeaders: input.callerHeaders, }); await assertGatewayTokenAction(session, "tools/list"); const tools = await listToolsForContext(session, input.signal); await writeAudit({ session, companyId: session.companyId, agentId: session.agentId, runId: session.runId, issueId: session.issueId, action: "tool_gateway.discovery", details: { decision: "allow", reasonCode: "named_gateway_discovery_filtered", visibleToolCount: tools.length, visibleToolsHash: createHash("sha256").update(JSON.stringify(tools.map((tool) => tool.name).sort())).digest("hex"), }, }); return tools; }, async executeContextForNamedGateway(input: { gatewayId?: string | null; gatewayPublicId?: string | null; bearerToken: string; method: "resources/list" | "resources/read" | "prompts/list" | "prompts/get"; params?: Record; callerHeaders?: Record; }): Promise> { return namedGatewayContextProtocol(input); }, async createSession(input: { companyId: string; agentId: string; runId: string; issueId?: string | null; projectId?: string | null; ttlMs?: number; actorType?: LogActivityInput["actorType"]; actorId?: string; }): Promise { await assertAgentInCompany(input.companyId, input.agentId); const { issueId, projectId } = await resolveRunContext(input); const now = new Date(); const sessionId = randomUUID(); const token = generateGatewayToken(sessionId); const session: ToolGatewaySession = { id: sessionId, token, companyId: input.companyId, agentId: input.agentId, runId: input.runId, issueId, projectId, createdAt: now, expiresAt: new Date(now.getTime() + sessionTtlMs(input.ttlMs)), }; await db.transaction(async tx => { await notifyDeliveryWork(tx, DELIVERY_QUEUES.gatewayCredentialExpiry); await tx.insert(toolGatewaySessions).values({ id: session.id, companyId: session.companyId, agentId: input.agentId, runId: input.runId, issueId: session.issueId, projectId: session.projectId, tokenHash: hashGatewayToken(token), expiresAt: session.expiresAt, createdAt: session.createdAt, updatedAt: session.createdAt, } as any); }); await writeAudit({ session, companyId: session.companyId, agentId: session.agentId, runId: session.runId, issueId: session.issueId, actorType: input.actorType, actorId: input.actorId, action: "tool_gateway.session_created", details: { decision: "allow", reasonCode: "session_created", expiresAt: session.expiresAt.toISOString(), }, }); return session; }, async listToolsForSession( sessionToken: string, options: { signal?: AbortSignal } = {}, ): Promise { options.signal?.throwIfAborted(); const session = await getActiveSession(sessionToken); const tools = await listToolsForContext(session, options.signal); await writeAudit({ session, companyId: session.companyId, agentId: session.agentId, runId: session.runId, issueId: session.issueId, action: "tool_gateway.discovery", details: { decision: "allow", reasonCode: "discovery_filtered", visibleToolCount: tools.length, visibleToolsHash: createHash("sha256").update(JSON.stringify(tools.map((tool) => tool.name).sort())).digest("hex"), }, }); return tools; }, async listPluginToolsForAgent(input: { companyId: string; agentId: string; }): Promise { await assertAgentInCompany(input.companyId, input.agentId); const decisions = await decideToolsForListing(pluginTools(), (tool) => policyInputForAgentTool({ companyId: input.companyId, agentId: input.agentId, tool, }), ); const visibleTools = decisions .filter( ({ decision }) => decision.allowed || decision.decision === "require_approval", ) .map(({ tool }) => tool); return deduplicateToolDescriptors(visibleTools) .map((tool) => { const { providerType: _providerType, risk: _risk, ...descriptor } = tool; return descriptor; }); }, async browserUseSessionAuthorized(binding: { companyId: string; agentId: string; runId: string; issueId: string; connectionId: string; grantId: string; invocationId: string }) { const [connection] = await db.select().from(toolConnections).where(and(eq(toolConnections.companyId, binding.companyId), eq(toolConnections.id, binding.connectionId))); const [invocation] = await db.select().from(toolInvocations).where(and(eq(toolInvocations.companyId, binding.companyId), eq(toolInvocations.id, binding.invocationId))); if (!connection || !invocation || !connection.enabled || connection.status !== "active") return false; const [issue] = await db.select({ projectId: issues.projectId }).from(issues).where(and(eq(issues.companyId, binding.companyId), eq(issues.id, binding.issueId))); const session: ToolGatewaySession = { ...binding, id: randomUUID(), token: "", projectId: issue?.projectId ?? null, createdAt: new Date(), expiresAt: new Date(Date.now() + 60000) }; try { const grant = await resolveConnectionGrant(session, connection, false); if (grant.id !== binding.grantId) return false; const tool = (await connectedMcpToolsForConnection(binding.companyId, binding.connectionId)).find(t => t.name === invocation.toolName); if (!tool) return false; const decision = await policyService.decide(policyInputForTool({ session, tool, consumeRateLimit: false })); return decision.allowed || decision.decision === "require_approval"; } catch { return false; } }, /** Standing instructions use exactly the same authorization as tool discovery. */ async resolveConnectionInstructionsForRun(binding: { companyId: string; agentId: string; runId: string }) { const candidates = await db.select().from(toolConnections).where(and( eq(toolConnections.companyId, binding.companyId), eq(toolConnections.enabled, true), eq(toolConnections.status, "active"), sql`${toolConnections.agentInstructions}->>'enabled' = 'true'`, )); if (!candidates.length) return null; const runContext = await resolveRunContext(binding); const session = await captureSessionIdentity({ ...binding, ...runContext, id: randomUUID(), token: "", createdAt: new Date(), expiresAt: new Date(Date.now() + 60_000), }); await assertAgentInCompany(binding.companyId, binding.agentId); const candidateIds = new Set(candidates.map((connection) => connection.id)); // Prompt assembly needs authorization, not a full discovery listing. Share // descriptors and policy decisions, but only authorize candidate sources; // discovery admission pressure must not remove guidance or reset sessions. const tools = (await connectionToolsForContext(session)) .filter((tool) => tool.connectionId && candidateIds.has(tool.connectionId)); const decisions = await decideToolsForListing(tools, (tool) => policyInputForTool({ session, tool })); const visible = new Set(decisions.flatMap(({ tool, decision }) => (decision.allowed || decision.decision === "require_approval") && tool.connectionId ? [tool.connectionId] : [], )); const sources: Parameters[0] = []; for (const connection of candidates) { if (!visible.has(connection.id)) continue; try { const grant = await resolveConnectionGrant(session, connection, false); sources.push({ connection, grantId: grant.id }); } catch (error) { // A missing/revoked identity makes this connection unavailable, without // opening an interaction or blocking unrelated work at prompt assembly. if (!(error instanceof ToolGatewayHttpError) && !(error instanceof HttpError)) throw error; if (error.status >= 500) throw error; } } return composeConnectionInstructions(sources); }, /** * MCP Skills: approved skills of the connections this agent can use, each * with its verified SKILL.md. A skill that cannot be loaded now is left out * with a reason; it never blocks the run. Runs in a company without an * approved MCP skill cost one indexed read. */ async resolveConnectionSkillsForRun(binding: { companyId: string; agentId: string; runId: string }, options: { budgetMs?: number } = {}) { const loaded: Array<{ skill: McpSkillRow; appName: string; markdown: string }> = []; const skipped: Array<{ skillName: string; appName: string; reason: string }> = []; if (!(await mcpSkills.hasApproved(binding.companyId))) return { loaded, skipped }; // The whole optional step shares one deadline: a slow database or app // must not hold the run back. Reads still in flight at the deadline // finish in the background and fill the cache for later runs. const budgetMs = options.budgetMs ?? MCP_SKILL_LOAD_BUDGET_MS; let timer: ReturnType | undefined; const deadline = new Promise<"late">((resolve) => { timer = setTimeout(() => resolve("late"), budgetMs); }); try { const prepare = (async () => { const candidates = await approvedMcpSkillConnections(binding.companyId); if (!candidates.length) return null; const session = await agentRunSession(binding); const usable = await usableConnectionsForAgent(session, candidates); const skills = await mcpSkills.approvedForConnections(binding.companyId, usable.map((connection) => connection.id)); return { session, skills, byId: new Map(usable.map((connection) => [connection.id, connection])) }; })(); prepare.catch(() => undefined); const prepared = await Promise.race([prepare, deadline]); if (prepared === "late") { skipped.push({ skillName: "", appName: "", reason: "Skills from connected apps took too long to prepare." }); return { loaded, skipped }; } if (!prepared) return { loaded, skipped }; const { session, skills, byId } = prepared; await Promise.all(skills.map(async (skill) => { const connection = byId.get(skill.connectionId)!; const read = readVerifiedMcpSkillFile(session, connection, skill, "SKILL.md"); read.catch(() => undefined); try { const bytes = await Promise.race([read, deadline]); if (bytes === "late") { skipped.push({ skillName: skill.name, appName: connection.name, reason: "The app took too long to answer." }); return; } loaded.push({ skill, appName: connection.name, markdown: bytes.toString("utf8") }); } catch (error) { skipped.push({ skillName: skill.name, appName: connection.name, reason: error instanceof ToolGatewayHttpError ? error.message : "The app could not be reached." }); } })); } finally { clearTimeout(timer); } loaded.sort((a, b) => a.skill.id.localeCompare(b.skill.id)); return { loaded, skipped }; }, /** * MCP Skills: one supporting file of an approved skill, for an agent in an * active run. The file must be listed in the approved manifest, and the * read goes only to the skill's own connection. */ async readConnectionSkillFile(input: { companyId: string; agentId: string; runId: string; skillId: string; path: string }) { const skill = await mcpSkills.get(input.companyId, input.skillId).catch(() => null); if (!skill || skill.status !== "approved" || skill.approvedManifestDigest !== skill.manifestDigest) { throw new ToolGatewayHttpError(404, "Skill not found", "mcp_skill_not_found"); } const [connection] = await approvedMcpSkillConnections(input.companyId, skill.connectionId); if (!connection) throw new ToolGatewayHttpError(404, "Skill not found", "mcp_skill_not_found"); const session = await agentRunSession(input); if (!(await usableConnectionsForAgent(session, [connection])).length) { throw new ToolGatewayHttpError(404, "Skill not found", "mcp_skill_not_found"); } return readVerifiedMcpSkillFile(session, connection, skill, input.path); }, /** * MCP Skills: the SKILL.md of any listed skill, for a board member to read * before deciding. It is read with the viewer's own access, verified like * any other read, and never counts as loading the skill. */ async readConnectionSkillForReview(input: { companyId: string; userId: string; skillId: string }) { const skill = await mcpSkills.get(input.companyId, input.skillId); if (!skill.manifest) throw new ToolGatewayHttpError(409, "This skill's content can't be checked, so it can't be shown.", "mcp_skill_not_verifiable"); const [connection] = await db.select().from(toolConnections) .where(and(eq(toolConnections.id, skill.connectionId), eq(toolConnections.companyId, input.companyId))).limit(1); if (!connection) throw new ToolGatewayHttpError(404, "Skill not found", "mcp_skill_not_found"); const session: ToolGatewaySession = { id: "mcp-skill-review", token: "mcp-skill-review", companyId: input.companyId, agentId: null, runId: null, issueId: null, projectId: null, actorType: "user", actorId: input.userId, responsibleUserId: input.userId, createdAt: new Date(), expiresAt: new Date(Date.now() + DEFAULT_SESSION_TTL_MS), }; try { await resolveConnectionGrant(session, connection, false); } catch { throw new ToolGatewayHttpError(404, "Skill not found", "mcp_skill_not_accessible"); } const bytes = await readVerifiedMcpSkillFile(session, connection, skill, "SKILL.md"); // The digest the content was verified against, so the board approves what it read. return { markdown: bytes.toString("utf8"), manifestDigest: skill.manifestDigest! }; }, async browserUseResources(binding: { companyId: string; agentId: string; runId?: string; issueId?: string }) { if (!binding.runId || !binding.issueId) return []; const connections = await measureRunPhase("connectors.browser_use.connection", () => db.select({ id: toolConnections.id }).from(toolConnections).where(and( eq(toolConnections.companyId, binding.companyId), eq(toolConnections.transport, "rest_api"), eq(toolConnections.enabled, true), eq(toolConnections.status, "active"), sql`${toolConnections.config}->>'sourceTemplateKey' = 'browser-use-cloud'`, )).orderBy(toolConnections.name, toolConnections.id)); if (!connections.length) return []; const session: ToolGatewaySession = { ...binding, runId: binding.runId, issueId: binding.issueId, id: randomUUID(), token: "", projectId: null, createdAt: new Date(), expiresAt: new Date(Date.now() + 60000) }; await assertAgentInCompany(binding.companyId, binding.agentId); if (await githubGuestBotConnectionForSession(db, session)) return []; const tools = await measureRunPhase("connectors.browser_use.catalog", async () => { const candidates = await connectedMcpToolsForCompany(binding.companyId, connections.map(connection => connection.id)); const decisions = await decideToolsForListing(candidates, tool => policyInputForTool({ session, tool })); return decisions.filter(({ decision }) => decision.allowed || decision.decision === "require_approval").map(({ tool }) => tool); }); const visible = new Set(tools.map(tool => tool.connectionId)); const resources: Array<{ id: string; label: string; connectionId: string }> = []; for (const candidate of connections) { if (!visible.has(candidate.id)) continue; const [connection] = await measureRunPhase("connectors.browser_use.connection", () => db.select().from(toolConnections).where(and( eq(toolConnections.companyId, binding.companyId), eq(toolConnections.id, candidate.id), eq(toolConnections.enabled, true), eq(toolConnections.status, "active"), ))); if (!connection || !isBrowserUseConnection(connection)) continue; try { await measureRunPhase("connectors.browser_use.grant", () => resolveConnectionGrant(session, connection, false)); resources.push({ id: connection.id, connectionId: connection.id, label: "Browser Use Cloud" }); } catch { /* Unavailable grants do not contribute a runtime skill. */ } } return resources; }, async summarizeConnectionAccessForAgent(input: { companyId: string; connectionId: string; agentId: string; heartbeatRunId?: string | null; issueId?: string | null; projectId?: string | null; }) { await assertAgentInCompany(input.companyId, input.agentId); const tools = await connectedMcpToolsForConnection( input.companyId, input.connectionId, ); const decisions = ( await decideToolsForListing(tools, (tool) => policyInputForAgentTool({ companyId: input.companyId, agentId: input.agentId, heartbeatRunId: input.heartbeatRunId, issueId: input.issueId, projectId: input.projectId, tool, }), ) ).map(({ tool, decision }) => { const testDecision = decision.decision === "require_approval" ? "ask_first" : decision.allowed ? "allowed" : "off"; return { toolName: tool.upstreamToolName ?? tool.name, gatewayToolName: tool.name, displayName: tool.displayName, risk: tool.risk, decision: testDecision, reasonCode: decision.reasonCode, matchedPolicyIds: decision.matchedPolicyIds, effectiveProfileIds: decision.effectiveProfileIds, }; }); const lastChange = await summarizeAccessLastChange({ companyId: input.companyId, connectionId: input.connectionId, agentId: input.agentId, policyIds: [ ...new Set( decisions.flatMap((decision) => decision.matchedPolicyIds), ), ], profileIds: [ ...new Set( decisions.flatMap((decision) => decision.effectiveProfileIds), ), ], }); return { connectionId: input.connectionId, toolCount: decisions.length, allowedCount: decisions.filter( (decision) => decision.decision === "allowed", ).length, askFirstCount: decisions.filter( (decision) => decision.decision === "ask_first", ).length, offCount: decisions.filter((decision) => decision.decision === "off") .length, lastChangedAt: lastChange.lastChangedAt, lastChangedByAgentId: lastChange.lastChangedByAgentId, lastChangedByName: lastChange.lastChangedByName, tools: decisions.map( ({ effectiveProfileIds: _effectiveProfileIds, ...tool }) => tool, ), }; }, async executeTestCall(input: ExecuteTestCallInput) { await input.managementContext?.reauthorize(); const actingAgentId = input.managementContext?.actor.type === "agent" ? input.managementContext.actor.agentId : null; await assertAgentInCompany(input.companyId, input.agentId); const session: ToolGatewaySession = { id: "test-call", token: "test-call", companyId: input.companyId, agentId: input.agentId, runId: input.managementContext?.workContext.runId ?? null, issueId: input.issueId ?? input.managementContext?.workContext.issueId ?? null, projectId: input.projectId ?? input.managementContext?.workContext.projectId ?? null, originatingAgentId: actingAgentId, actorType: actingAgentId ? "agent" : "user", actorId: actingAgentId ?? input.userId, responsibleUserId: input.userId, createdAt: new Date(), expiresAt: new Date(Date.now() + DEFAULT_SESSION_TTL_MS), }; const tool = ( await connectedMcpToolsForConnection( input.companyId, input.connectionId, ) ).find( (candidate) => candidate.name === input.toolName || candidate.upstreamToolName === input.toolName, ); if (!tool) { throw new ToolGatewayHttpError( 404, `Tool "${input.toolName}" not found`, "tool_not_found", { connectionId: input.connectionId, tool: input.toolName, }, ); } const requestedParameters = await governedToolArguments( session, tool, input.parameters ?? {}, ); const argumentValidation = await validateToolContent({ value: requestedParameters, direction: "arguments", sensitiveMode: "redact", promptInjectionMode: "ignore", }); const decisionInput = policyInputForTool({ session, tool, parameters: requestedParameters, idempotencyKey: `test-call:${randomUUID()}`, consumeRateLimit: true, }); await assertDelegatedTestCredentialAccess(session, tool); const callerSession = delegatedTestCallerSession(session); const callerDecisionInput = callerSession ? policyInputForTool({ session: callerSession, tool, parameters: requestedParameters, consumeRateLimit: true }) : null; const callerDecision = callerDecisionInput ? await policyService.decide(callerDecisionInput) : null; const targetDecision = await policyService.decide(decisionInput, { sharedRateDecision: callerDecision ?? undefined }); // Both principals' action controls apply. Either denial wins; either // Ask first decision creates the ordinary human approval request. const chosenDecision = callerDecision && !callerDecision.allowed && callerDecision.decision !== "require_approval" ? callerDecision : !targetDecision.allowed ? targetDecision : callerDecision?.decision === "require_approval" ? callerDecision : targetDecision; const accessDecision = { ...chosenDecision, policyExplanation: { ...chosenDecision.policyExplanation, consumedRateAdmissions: targetDecision.policyExplanation?.consumedRateAdmissions, delegatedCallerConsumedRateAdmissions: callerDecision?.policyExplanation?.consumedRateAdmissions, } }; if (callerDecisionInput && callerDecision) await policyService.writeAudit(callerDecisionInput, callerDecision); if (accessDecision.allowed || accessDecision.decision === "require_approval") await assertDelegatedTestCredentialAccess(session, tool); const recorded = await recordToolInvocation( decisionInput, accessDecision, ); await policyService.writeAudit(decisionInput, accessDecision); const invocationId = recorded.invocation.id; if (input.includeResultMeta) { // MCP Apps view call: its approval must run through the test path // (app-visible tools, viewer identity) with the view's task rules. await db.update(toolInvocations).set({ policyExplanation: { ...recorded.invocation.policyExplanation, mcpAppViewCall: { issueId: input.issueId ?? null, projectId: input.projectId ?? null }, } }).where(eq(toolInvocations.id, invocationId)); } if (actingAgentId && input.managementContext) { await db.update(toolInvocations).set({ policyExplanation: { ...recorded.invocation.policyExplanation, delegatedConnectionTest: { agentId: actingAgentId, responsibleUserId: input.managementContext.responsibleUserId, runId: input.managementContext.actor.runId ?? null, keyId: input.managementContext.actor.keyId ?? null, resource: input.managementContext.resource, }, } }).where(eq(toolInvocations.id, invocationId)); } if (accessDecision.decision === "require_approval") { if (!recorded.actionRequest) { throw new ToolGatewayHttpError( 500, "Approval request was not created", "approval_request_missing", { invocationId, tool: tool.name, }, ); } const pendingActionRequest = recorded.actionRequest; const canonicalArguments = canonicalToolArguments(requestedParameters); const canonicalArgumentsHash = toolRequestIdentityHash(requestedParameters, options.toolActionSigningSecret); const approvalSnapshot = await connectedRemoteApprovalSnapshot( session, tool, { requireResolvedCredentials: true, }, ); let signedArguments: ReturnType; try { signedArguments = signToolArguments({ invocationId, toolName: tool.name, canonicalArguments, approvalSnapshot: approvalSnapshot ?? undefined, executionOnApprove: true, signingSecret: options.toolActionSigningSecret, }); } catch (error) { await writeToolReviewChange(db, pendingActionRequest.companyId, tx => tx .update(toolActionRequests) .set({ status: "cancelled", resolvedAt: new Date(), updatedAt: new Date(), }) .where( and( eq(toolActionRequests.id, pendingActionRequest.id), eq(toolActionRequests.status, "pending"), ), )); if (error instanceof ToolActionSigningSecretMissingError) { await db .update(toolInvocations) .set({ status: "failed", errorCode: "signing_secret_unconfigured", errorMessage: error.message, completedAt: new Date(), updatedAt: new Date(), }) .where(eq(toolInvocations.id, invocationId)); void emitConnectionInvoked(db, invocationId); throw new ToolGatewayHttpError( 500, error.message, "signing_secret_unconfigured", { invocationId, tool: tool.name, }, ); } throw error; } const previewMarkdown = buildHumanizedActionPreview({ tool, argumentsSummary: argumentValidation.summary, }); await writeToolReviewChange(db, pendingActionRequest.companyId, tx => tx .update(toolActionRequests) .set({ canonicalArgumentsHash, canonicalArgumentsSummary: argumentValidation.summary, signedArguments, previewMarkdown, expiresAt: pendingActionRequest.expiresAt, updatedAt: new Date(), }) .where(eq(toolActionRequests.id, pendingActionRequest.id))); await writeToolCallEvent({ invocationId, actionRequestId: recorded.actionRequest.id, session, eventType: "approval_requested", outcome: "pending", toolName: tool.name, policyDecision: "require_approval", reasonCode: accessDecision.reasonCode, argumentsSummary: argumentValidation.summary, metadata: { source: "test", actionRequestId: recorded.actionRequest.id, }, tool, }); await writeAudit({ session, companyId: input.companyId, agentId: input.agentId, runId: session.runId, issueId: session.issueId, actorType: actingAgentId ? "agent" : "user", actorId: actingAgentId ?? input.userId, action: "tool_gateway.approval_requested", details: { source: "test", invocationId, actionRequestId: recorded.actionRequest.id, decision: "require_approval", reasonCode: accessDecision.reasonCode, matchedPolicyIds: accessDecision.matchedPolicyIds, tool: tool.name, ...toolAuditMetadata(tool), argumentsSummary: argumentValidation.summary, }, }); return { decision: "ask_first" as const, invocationId, actionRequestId: recorded.actionRequest.id, }; } if (!accessDecision.allowed) { // recordInvocation inserted this row already terminal (denied or // rate_limited), so this is its only completion boundary. void emitConnectionInvoked(db, invocationId); await writeAudit({ session, companyId: input.companyId, agentId: input.agentId, runId: session.runId, issueId: session.issueId, actorType: actingAgentId ? "agent" : "user", actorId: actingAgentId ?? input.userId, action: "tool_gateway.call_denied", details: { source: "test", invocationId, decision: accessDecision.decision, reasonCode: accessDecision.reasonCode, matchedPolicyIds: accessDecision.matchedPolicyIds, tool: tool.name, ...toolAuditMetadata(tool), argumentsSummary: argumentValidation.summary, rateLimitState: accessDecision.rateLimitState ?? null, }, }); return { decision: "off" as const, invocationId, error: { message: accessDecision.explanation, reasonCode: accessDecision.reasonCode, }, }; } await input.managementContext?.reauthorize(); const outcome = await runTestToolInvocation({ session, managementContext: input.managementContext, tool, parameters: requestedParameters, invocationId, companyId: input.companyId, agentId: input.agentId, userId: input.userId, argumentsSummary: argumentValidation.summary, reasonCode: accessDecision.reasonCode, matchedPolicyIds: accessDecision.matchedPolicyIds, timeoutMs: input.timeoutMs, signal: input.signal, }); if (!input.includeResultMeta && "resultMeta" in outcome) { const { resultMeta: _viewOnly, ...rest } = outcome; return rest; } return outcome; }, /** * MCP Apps: reads the `ui://` view document for a recorded call, through * the same connection and credential the agent's call used. */ async readMcpAppViewResource(input: { companyId: string; userId: string; view: { connectionId: string; agentId: string | null; runId: string | null; issueId: string | null; responsibleUserId: string | null; resourceUri: string }; }): Promise { const [connection] = await db.select().from(toolConnections) .where(and(eq(toolConnections.id, input.view.connectionId), eq(toolConnections.companyId, input.companyId))) .limit(1); if (!connection) throw new ToolGatewayHttpError(404, "MCP connection not found", "connection_not_found"); // The document is read with the viewer's own access to the connection // (the organization grant or the viewer's personal grant), never with the // run's credential: no run on the session, the viewer as responsible user. const session: ToolGatewaySession = { id: "mcp-app-view", token: "mcp-app-view", companyId: input.companyId, agentId: input.view.agentId, runId: null, issueId: input.view.issueId, projectId: null, actorType: "user", actorId: input.userId, responsibleUserId: input.userId, createdAt: new Date(), expiresAt: new Date(Date.now() + DEFAULT_SESSION_TTL_MS), }; try { await resolveConnectionGrant(session, connection, false); } catch { throw new ToolGatewayHttpError(404, "View not found", "mcp_app_view_not_accessible"); } const result = await callAssignedConnectionProtocol({ session, connection, method: "resources/read", params: { uri: input.view.resourceUri }, // JSON (or SSE) framing escapes the document, so allow headroom over the HTML limit. maxResponseBytes: MCP_APP_MAX_HTML_BYTES * 2, // A view document that fails to load says nothing about the connection's tools. markHealth: false, }); const resource = readMcpAppResource(result, input.view.resourceUri); if (!resource) { throw new ToolGatewayHttpError(502, "The app did not return a view for this tool", "mcp_app_resource_invalid"); } if (Buffer.byteLength(resource.html, "utf8") > MCP_APP_MAX_HTML_BYTES) { throw new ToolGatewayHttpError(502, "The app's view is too large to show", "mcp_app_resource_too_large"); } return resource; }, /** * MCP Apps: a view's `tools/call`. Only tools of the view's own connection * that are visible to apps can be called. The call runs with the viewer's * authority and the agent's connection access, through the same policy, * approval and audit path as a connection test call. */ async callMcpAppViewTool(input: { companyId: string; userId: string; view: { connectionId: string; agentId: string | null; issueId: string | null }; toolName: string; arguments: Record; signal?: AbortSignal; }): Promise { if (!input.view.agentId) { throw new ToolGatewayHttpError(409, "This view's agent no longer exists", "mcp_app_agent_missing"); } const tool = (await connectedMcpToolsForConnection(input.companyId, input.view.connectionId)) .find((candidate) => candidate.upstreamToolName === input.toolName); if (!tool || !mcpAppToolCallableFromApp((asRecord(tool.providerMetadata)?.ui ?? null) as McpAppToolUi | null)) { throw new ToolGatewayHttpError(404, `Tool "${input.toolName}" is not available to this app`, "mcp_app_tool_not_found"); } // Task- and project-scoped rules (block, Ask first) see the view's task. const [issue] = input.view.issueId ? await db.select({ id: issues.id, projectId: issues.projectId }).from(issues) .where(and(eq(issues.id, input.view.issueId), eq(issues.companyId, input.companyId))).limit(1) : []; const outcome = await this.executeTestCall({ companyId: input.companyId, issueId: issue?.id ?? null, projectId: issue?.projectId ?? null, connectionId: input.view.connectionId, agentId: input.view.agentId, userId: input.userId, toolName: tool.name, parameters: input.arguments, signal: input.signal, includeResultMeta: true, }); if (outcome.decision === "ask_first") { return { content: [{ type: "text", text: "This action needs approval first. It was sent for review." }], isError: true }; } if ("error" in outcome && outcome.error) { return { content: [{ type: "text", text: outcome.error.message }], isError: true }; } return mcpAppCallToolResult( "result" in outcome ? outcome.result : null, "resultMeta" in outcome ? outcome.resultMeta : undefined, ); }, /** * Live status of an ask-first test call, polled by the Test tab panel. * Scoped to the connection the panel is bound to and to test-origin * requests only, so it can't be used to read arbitrary action requests. */ async getTestCallStatus(input: { companyId: string; connectionId: string; actionRequestId: string; actor?: AuthorizationActor; }): Promise { const [actionRequest] = await db .select() .from(toolActionRequests) .where(eq(toolActionRequests.id, input.actionRequestId)) .limit(1); if (!actionRequest || actionRequest.companyId !== input.companyId) { throw new ToolGatewayHttpError( 404, "Tool action request not found", "action_request_not_found", ); } const [invocation] = await db .select() .from(toolInvocations) .where(eq(toolInvocations.id, actionRequest.invocationId)) .limit(1); if (!invocation || invocation.companyId !== input.companyId) { throw new ToolGatewayHttpError( 404, "Tool invocation not found", "invocation_not_found", ); } if ( invocation.connectionId !== input.connectionId || !isTestOriginInvocation(invocation) ) { throw new ToolGatewayHttpError( 404, "Tool action request not found", "action_request_not_found", ); } if (input.actor?.type === "agent" && invocation.actorId !== input.actor.agentId) { throw new ToolGatewayHttpError(403, "Test belongs to another principal", "test_principal_access_denied"); } if (invocation.issueId) { if (!input.actor) throw new ToolGatewayHttpError(403, "Task access is required", "test_task_access_denied"); const [issue] = await db.select().from(issues).where(and(eq(issues.companyId, input.companyId), eq(issues.id, invocation.issueId))); const decision = issue ? await authorizationService(db).decide({ actor: input.actor, action: "issue:read", resource: { type: "issue", companyId: input.companyId, issueId: issue.id, projectId: issue.projectId, parentIssueId: issue.parentId, assigneeAgentId: issue.assigneeAgentId, assigneeUserId: issue.assigneeUserId, } }) : null; if (!issue || !decision?.allowed || (input.actor.type === "agent" && ( !(await canActorReadIssuePrivacy(db, input.actor, issue)) || !input.actor.onBehalfOfUserId || !(await canActorReadIssuePrivacy(db, { type: "board", userId: input.actor.onBehalfOfUserId }, issue)) ))) { throw new ToolGatewayHttpError(403, "Task is unavailable to this principal", "test_task_access_denied"); } } return buildTestCallStatus(actionRequest, invocation); }, repairActionReviewProjections: reviewProjection.sweep, actionReviewProjectionCompanies: reviewProjection.companies, settleInterruptedActionReviews: reviewInterruption.sweep, nextActionReviewInterruptionAt: reviewInterruption.next, sweepExpiredActionReviews: reviewExpiry.sweep, nextActionReviewExpiryAt: reviewExpiry.next, actionReviewExpiryDeadlines: reviewExpiry.deadlines, sweepExpiredActionReviewsForCompany: reviewExpiry.sweepForCompany, approvedActionReviewCompanies: (companyId?: string) => approvedToolReviewCompanies(db, companyId), async recoverApprovedActionReviews(companyId?: string) { return recoverApprovedToolReviews(db, async row => { try { const prepared = await prepareApprovedToolReview(db, { actionRequestId: row.request.id, invocationId: row.invocation.id, signingSecret: options.toolActionSigningSecret }); if (prepared.kind === "skip") return false; if (prepared.kind === "settled") { await reflectToolActionInteractionLifecycle(prepared.projection); return false; } const { request, invocation, payload } = prepared; if (!isTestOriginInvocation(invocation) && payload.executionOnApprove !== true) return false; await this.approveActionRequest({ companyId: request.companyId, actionRequestId: request.id, actor: { userId: request.decidedByUserId ?? request.resolvedByUserId } }); const [remaining] = await db.select({ status: toolActionRequests.status, errorCode: toolInvocations.errorCode }) .from(toolActionRequests).innerJoin(toolInvocations, eq(toolInvocations.id, toolActionRequests.invocationId)) .where(eq(toolActionRequests.id, request.id)); return remaining?.status === "approved" && remaining.errorCode !== TOOL_APPROVAL_CONNECTION_REQUIRED; } catch (err) { logger.warn({ err, actionRequestId: row.request.id }, "Could not recover approved tool action"); return true; } }, companyId); }, async sweepActionReviews(input: { includeExpiry?: boolean; includeApproved?: boolean; includeInterrupted?: boolean } = {}) { await reviewProjection.sweep(); let scanned = input.includeExpiry === false ? 0 : (await reviewExpiry.sweep()).scanned; if (input.includeApproved !== false) scanned += (await this.recoverApprovedActionReviews()).scanned; if (input.includeInterrupted !== false) scanned += (await reviewInterruption.sweep()).scanned; return { scanned }; }, async approveActionRequest(input: { companyId: string; rememberAction?: boolean; issueId?: string; interactionId?: string; actionRequestId: string; actor: { agentId?: string | null; userId?: string | null }; }) { if (input.actor.agentId) throw new ToolGatewayHttpError( 403, "Only a human can resolve a tool review", "human_review_required", ); const [actionRequest] = await db .select() .from(toolActionRequests) .where(eq(toolActionRequests.id, input.actionRequestId)) .limit(1); if (!actionRequest || actionRequest.companyId !== input.companyId) { throw new ToolGatewayHttpError( 404, "Tool action request not found", "action_request_not_found", ); } const [invocation] = await db .select() .from(toolInvocations) .where(eq(toolInvocations.id, actionRequest.invocationId)) .limit(1); if (!invocation || invocation.companyId !== input.companyId) { throw new ToolGatewayHttpError( 404, "Tool invocation not found", "invocation_not_found", ); } if (input.issueId !== undefined || input.interactionId !== undefined) { if ( !input.issueId || !input.interactionId || actionRequest.issueId !== input.issueId || actionRequest.interactionId !== input.interactionId || invocation.issueId !== input.issueId ) { throw new ToolGatewayHttpError( 409, "Tool action request does not belong to this interaction", "action_context_mismatch", ); } const [originatingInteraction] = await db .select({ id: issueThreadInteractions.id }) .from(issueThreadInteractions) .where( and( eq(issueThreadInteractions.id, input.interactionId), eq(issueThreadInteractions.companyId, input.companyId), eq(issueThreadInteractions.issueId, input.issueId), ), ) .limit(1); if (!originatingInteraction) { throw new ToolGatewayHttpError( 409, "Tool action request does not belong to this interaction", "action_context_mismatch", ); } } if ( ["executing", "executed", "failed"].includes(actionRequest.status) && actionRequest.decidedAt ) { await options.onToolActionSettled?.(actionRequest.id); return actionRequestResolution(actionRequest); } if ( actionRequest.status !== "pending" && actionRequest.status !== "approved" ) { throw new ToolGatewayHttpError( 409, "Tool action request is no longer pending", "action_not_pending", ); } let signedPayload: ReturnType = null; try { signedPayload = readSignedToolArgumentsPayload({ signedArguments: actionRequest.signedArguments, invocationId: invocation.id, toolName: invocation.toolName, signingSecret: options.toolActionSigningSecret, }); } catch { signedPayload = null; } if (!signedPayload) { if (actionRequest.status === "pending") { await writeToolReviewChange(db, actionRequest.companyId, tx => tx .update(toolActionRequests) .set({ status: "cancelled", resolvedAt: new Date(), updatedAt: new Date(), }) .where( and( eq(toolActionRequests.id, actionRequest.id), eq(toolActionRequests.status, "pending"), ), )); } await reflectToolActionInteractionLifecycle({ actionRequestId: actionRequest.id, status: "cancelled", }); throw new ToolGatewayHttpError( 409, "Tool action request is no longer approvable; refresh the review queue", "action_request_invalidated", ); } if (actionRequest.approvalId) { const [formalApproval] = await db .select({ status: approvals.status }) .from(approvals) .where( and( eq(approvals.id, actionRequest.approvalId), eq(approvals.companyId, input.companyId), ), ) .limit(1); if (!formalApproval || formalApproval.status !== "approved") { throw new ToolGatewayHttpError( 409, "Tool action request requires formal board approval before execution", "formal_approval_required", { approvalId: actionRequest.approvalId }, ); } } if (actionRequest.status === "approved") { if (invocation.errorCode === TOOL_APPROVAL_CONNECTION_REQUIRED && !await toolApprovalConnectionCanResume(db, invocation.companyId, invocation.connectionId, signedPayload.approvalSnapshot, invocation.policyExplanation?.approvalConnectionWait)) return actionRequest; await reflectToolActionInteractionLifecycle({ actionRequestId: actionRequest.id, status: "approved", }); if (isTestOriginInvocation(invocation)) { await runApprovedTestInvocation(invocation, signedPayload, actionRequest.id); const [settled] = await db.select().from(toolActionRequests).where(eq(toolActionRequests.id, actionRequest.id)); return actionRequestResolution(settled ?? actionRequest); } if (signedPayload.executionOnApprove === true) { try { await executeApprovedAgentInvocation({ actionRequest, invocation }); } catch { // The execution outcome is persisted on the invocation/request and // reflected onto the accepted interaction for the continuation wake. } const [settled] = await db .select() .from(toolActionRequests) .where(eq(toolActionRequests.id, actionRequest.id)) .limit(1); return actionRequestResolution(settled ?? actionRequest); } return actionRequest; } if (actionRequest.expiresAt && actionRequest.expiresAt <= new Date()) throw new ToolGatewayHttpError( 409, "Tool review has expired", "action_expired", ); if ( !isTestOriginInvocation(invocation) && signedPayload.executionOnApprove === true ) { try { const [issue] = await db .select() .from(issues) .where( and( eq(issues.id, invocation.issueId!), eq(issues.companyId, input.companyId), ), ) .limit(1); if (!issue || issue.status === "done" || issue.status === "cancelled") throw new ToolGatewayHttpError( 409, "Task is closed", "action_task_closed", ); const session: ToolGatewaySession = { id: `review:${actionRequest.id}`, token: "", companyId: input.companyId, agentId: invocation.agentId, actorType: "agent", actorId: invocation.actorId, originatingAgentId: typeof invocation.policyExplanation?.delegatedGatewayIssuer === "string" ? invocation.policyExplanation.delegatedGatewayIssuer : invocation.actorType === "agent" && invocation.gatewayId && !invocation.runId && !invocation.gatewayTokenId ? invocation.actorId : null, gatewayId: invocation.gatewayId, gatewayPublicId: invocation.gatewayPublicId, gatewayTokenId: invocation.gatewayTokenId, runId: invocation.runId, issueId: issue.id, projectId: issue.projectId, createdAt: new Date(), expiresAt: new Date(Date.now() + DEFAULT_SESSION_TTL_MS), }; await restoreApprovedActionIdentity( session, signedPayload.identityContextId, ); session.approvedSlackInvocationId = invocation.id; const tool = await findToolForSession(session, invocation.toolName); const liveApprovalSnapshot = await connectedRemoteApprovalSnapshot(session, tool); if (!approvalSnapshotsMatch(signedPayload.approvalSnapshot, liveApprovalSnapshot)) throw new ToolGatewayHttpError( 409, approvalTargetChangeMessage(signedPayload.approvalSnapshot, liveApprovalSnapshot), "approved_tool_target_changed", ); const previewHash = summarizeToolValue(signedPayload.arguments).sha256; const access = await policyService.decide( policyInputForTool({ session, tool, parameters: signedPayload.arguments, consumeRateLimit: false, }), { admittedInvocationId: invocation.id, requiredGatewayAction: "tools/call", admittedPreviewHash: [previewHash, toolRequestIdentityHash(signedPayload.arguments, options.toolActionSigningSecret)] .includes(actionRequest.canonicalArgumentsHash) ? previewHash : undefined, }, ); if (!access.allowed && access.decision !== "require_approval") throw new ToolGatewayHttpError( 403, access.explanation, access.reasonCode, ); } catch (error) { // Save the human decision even if the existing authorization needs // repair. Dispatch revalidates the signed target after reconnection. if (!isToolApprovalConnectionError(error)) throw error; } } const updated = await commitToolActionReview(db, { ...input, decision: "approved", }); await reflectToolActionInteractionLifecycle({ actionRequestId: updated.id, status: "approved", }); // A test-tab ask-first request has no agent run to carry out the parked // call, so approving it is what runs it. Execute against the signed // arguments and record the result on the invocation for the live panel. if (isTestOriginInvocation(invocation)) { await runApprovedTestInvocation( { ...invocation, approvalState: "approved" }, signedPayload, updated.id, ); } else if (signedPayload.executionOnApprove === true) { try { await executeApprovedAgentInvocation({ actionRequest: updated, invocation, }); } catch { // Persisted failure is the approval result; accepting the card itself // remains successful and the agent wake receives the failure context. } } const [settled] = await db .select() .from(toolActionRequests) .where(eq(toolActionRequests.id, updated.id)) .limit(1); return actionRequestResolution(settled ?? updated); }, async declineActionRequest(input: { companyId: string; issueId?: string; interactionId?: string; actionRequestId: string; reason?: string; actor: { agentId?: string | null; userId?: string | null }; }) { const updated = await commitToolActionReview(db, { ...input, decision: "rejected", }); await options .onToolActionSettled?.(updated.id) .catch((error) => logger.warn( { err: error, actionRequestId: updated.id }, "Tool review continuation will be retried", ), ); return updated; }, async executeTool(input: ExecuteGatewayToolInput) { const session = await getActiveSession(input.sessionToken, { gatewayId: input.gatewayId ?? null, gatewayPublicId: input.gatewayPublicId ?? null, protocolMethod: "tools/call", callerHeaders: input.callerHeaders, }); await assertGatewayTokenAction(session, "tools/call"); let invocationId = String(randomUUID()); const startedAt = Date.now(); // A retry carries the signed originating operation, even if steering has // since accepted instructions from someone else in this same run. if (input.approvedActionRequestId) { const [request] = await db .select() .from(toolActionRequests) .where( and( eq(toolActionRequests.id, input.approvedActionRequestId), eq(toolActionRequests.companyId, session.companyId), ), ); const [invocation] = request ? await db .select() .from(toolInvocations) .where( and( eq(toolInvocations.id, request.invocationId), eq(toolInvocations.companyId, session.companyId), eq(toolInvocations.runId, session.runId!), eq(toolInvocations.agentId, session.agentId!), ), ) : []; const payload = request && invocation ? readSignedToolArgumentsPayload({ signedArguments: request.signedArguments, invocationId: invocation.id, toolName: invocation.toolName, signingSecret: options.toolActionSigningSecret, }) : null; if (payload?.identityContextId) { const [origin] = await db .select() .from(runIdentityContexts) .where( and( eq(runIdentityContexts.id, payload.identityContextId), eq(runIdentityContexts.companyId, session.companyId), eq(runIdentityContexts.runId, session.runId!), eq(runIdentityContexts.status, "accepted"), ), ); if (!origin) throw new ToolGatewayHttpError( 409, "Approved action identity is unavailable", "identity_context_unavailable", ); session.identityContextId = origin.id; session.responsibleUserId = origin.cause === "company_default" ? null : origin.responsibleUserId; } } let tool = await findToolForSession(session, input.tool); if (tool.providerType === "paperclip_slack_chat") { const definition = SLACK_TOOLS.find(t => t.name === tool.upstreamToolName); const args = definition?.schema.parse(input.parameters ?? {}) as Record | undefined; if (!args) throw new ToolGatewayHttpError(403, "Unknown Slack operation", "slack_task_required"); if (typeof args.idempotencyKey === "string") { const key = `slack:${tool.connectionId}:${session.issueId}:${session.responsibleUserId}:${args.idempotencyKey}`; const [prior] = await db.select().from(toolInvocations).where(and(eq(toolInvocations.companyId, session.companyId), eq(toolInvocations.idempotencyKey, key))); const currentHash = toolRequestIdentityHash(args, options.toolActionSigningSecret); if (prior && (prior.toolName !== tool.name || prior.argumentsHash !== currentHash)) throw new ToolGatewayHttpError(409, "Idempotency key belongs to a different Slack operation", "slack_idempotency_conflict"); input = { ...input, idempotencyKey: key }; } } let virtualToolName: string | null = null; let requestedParameters: unknown = input.parameters ?? {}; if ( tool.name === "search_tools" && tool.providerType === "paperclip_virtual" ) { const argumentValidation = await validateToolContent({ value: requestedParameters, direction: "arguments", sensitiveMode: "redact", promptInjectionMode: "ignore", }); const result = await executeVirtualSearchTools( session, requestedParameters, ); const resultValidation = await validateToolContent({ value: result, direction: "result", sensitiveMode: "redact", promptInjectionMode: "block", classifier: resultClassifier(session, tool, null, { signal: input.signal }), }).catch(async (error: unknown) => { if (error instanceof ToolContentValidationError) { await writeToolCallEvent({ session, eventType: "call_failed", outcome: "failure", toolName: tool.name, reasonCode: error.reasonCode, tool, detectorMetadata: error.detectorMetadata, metadata: { findings: error.findings } }); await writeAudit({ session, companyId: session.companyId, agentId: session.agentId, runId: session.runId, issueId: session.issueId, action: "tool_gateway.call_failed", details: { tool: tool.name, reasonCode: error.reasonCode, promptInjection: error.detectorMetadata } }); throw new ToolGatewayHttpError(422, error.message, error.reasonCode, { findings: error.findings }); } throw error; }); const [invocation] = await db .insert(toolInvocations) .values({ companyId: session.companyId, actorType: session.actorType ?? (session.agentId ? "agent" : "system"), actorId: session.actorId ?? session.agentId ?? session.gatewayTokenId ?? session.companyId, agentId: session.agentId, issueId: session.issueId, runId: session.runId, providerType: "paperclip_virtual", upstreamToolName: "search_tools", riskLevel: "read", toolName: "search_tools", argumentsHash: argumentValidation.summary.sha256 ?? null, argumentsSummary: argumentValidation.summary, policyDecision: "allow", matchedPolicyIds: [], approvalState: "not_required", status: "succeeded", resultHash: resultValidation.summary.sha256 ?? null, resultSummary: resultValidation.summary, resultSizeBytes: resultValidation.summary.sizeBytes ?? null, startedAt: new Date(), completedAt: new Date(), }) .returning(); if (resultValidation.detectorMetadata?.invocationId) await injectionPrevention.linkToolInvocation( session.companyId, resultValidation.detectorMetadata.invocationId, invocation.id); await writeToolCallEvent({ invocationId: invocation.id, session, eventType: "call_completed", outcome: "success", toolName: "search_tools", policyDecision: "allow", reasonCode: "virtual_tool_completed", argumentsSummary: argumentValidation.summary, resultSummary: resultValidation.summary, detectorMetadata: resultValidation.detectorMetadata, metadata: { virtualToolName: "search_tools" }, tool, }); await writeAudit({ session, companyId: session.companyId, agentId: session.agentId, runId: session.runId, issueId: session.issueId, action: "tool_gateway.call_completed", details: { invocationId: invocation.id, decision: "allow", reasonCode: "virtual_tool_completed", tool: "search_tools", virtualToolName: "search_tools", durationMs: Date.now() - startedAt, argumentsSummary: argumentValidation.summary, result: summarizeResult(resultValidation.value), resultSummary: resultValidation.summary, promptInjection: resultValidation.detectorMetadata, }, }); return { invocationId: invocation.id, status: "completed" as const, tool: "search_tools", result: resultValidation.value, }; } if ( tool.name === "run_tool" && tool.providerType === "paperclip_virtual" ) { const { targetToolName, targetParameters } = virtualRunToolInput(requestedParameters); const targetTool = await findToolForSession(session, targetToolName); if (!isOnDemandRemoteTool(targetTool)) { throw new ToolGatewayHttpError( 404, `Tool "${targetToolName}" not found`, "tool_not_found", { tool: targetToolName }, ); } virtualToolName = "run_tool"; tool = targetTool; requestedParameters = targetParameters; } // Managed provider arguments are part of the governed call, not a // transport decoration. Project them before hashing, policy evaluation, // approval signing, previews, and audit summaries. Approved retries // re-project only for a compatibility comparison and dispatch the // already-reviewed signed payload unchanged. if (!input.approvedActionRequestId) { requestedParameters = await governedToolArguments( session, tool, requestedParameters, ); } const argumentValidation = await validateToolContent({ value: requestedParameters, direction: "arguments", sensitiveMode: "redact", promptInjectionMode: "ignore", }); let recoveredGitHubPublication: { content: string; data: unknown } | undefined; /** A keyed retry collecting its provider task (MCP Tasks); it may only attach to that task. */ let retryingMcpTaskRecordId: string | null = null; let effectiveParameters: unknown = requestedParameters; let effectiveArgumentsSummary = argumentValidation.summary; if (session.runId && session.issueId && tool.connectionId && tool.risk !== "read" && // This owner has an exact publication receipt/reconciliation protocol. !(tool.providerType === "paperclip_github_chat" && ["comment", "update_comment", "submit_review"].includes(tool.upstreamToolName ?? ""))) { const unresolved = await unresolvedRecoveryToolInvocation(db, { companyId: session.companyId, issueId: session.issueId, runId: session.runId, connectionId: tool.connectionId, toolName: tool.name, risk: tool.risk, }); if (unresolved) throw new ToolGatewayHttpError(409, "A previous operation has an unconfirmed outcome. Reconcile it before repeating this operation; reads and independent work remain available.", "recovery_effect_outcome_unresolved", { invocationId: unresolved }); } if (!input.approvedActionRequestId) { const replay = await replayMatchingAgentAction({ session, toolName: tool.name, argumentsHash: toolRequestIdentityHash(requestedParameters, options.toolActionSigningSecret), parameters: requestedParameters, }); if (replay?.matched) { let replayResult: unknown = replay.result; if (tool.providerType === "paperclip_github_chat" && ["comment", "update_comment", "submit_review"].includes(tool.upstreamToolName ?? "")) { const access = await policyService.decide(policyInputForTool({ session, tool, parameters: effectiveParameters, consumeRateLimit: false })); if (!access.allowed && access.decision !== "require_approval") throw new ToolGatewayHttpError(policyErrorStatus(access), access.explanation, access.reasonCode); const receipt = await githubChatReviewService(db).readPublicationReceipt(session, tool.upstreamToolName ?? "", effectiveParameters, replay.invocationId); if (receipt) { // Revalidate the recovered receipt, without mutating the completed // invocation or executing its external write again. try { const validation = await validateToolContent({ value: { content: JSON.stringify(receipt), data: receipt }, direction: "result", sensitiveMode: "redact", promptInjectionMode: "block", classifier: resultClassifier(session, tool, replay.invocationId, { signal: input.signal }) }); replayResult = validation.value; await writeToolCallEvent({ invocationId: replay.invocationId, session, eventType: "call_completed", outcome: "success", toolName: tool.name, reasonCode: "receipt_revalidated", tool, detectorMetadata: validation.detectorMetadata, metadata: { replay: true } }); await writeAudit({ session, companyId: session.companyId, agentId: session.agentId, runId: session.runId, issueId: session.issueId, action: "tool_gateway.call_completed", details: { invocationId: replay.invocationId, replay: true, promptInjection: validation.detectorMetadata } }); } catch (error) { if (error instanceof ToolContentValidationError) { await writeToolCallEvent({ invocationId: replay.invocationId, session, eventType: "call_failed", outcome: "failure", toolName: tool.name, reasonCode: error.reasonCode, tool, detectorMetadata: error.detectorMetadata, metadata: { replay: true, findings: error.findings } }); await writeAudit({ session, companyId: session.companyId, agentId: session.agentId, runId: session.runId, issueId: session.issueId, action: "tool_gateway.call_failed", details: { invocationId: replay.invocationId, replay: true, reasonCode: error.reasonCode, promptInjection: error.detectorMetadata } }); throw new ToolGatewayHttpError(422, error.message, error.reasonCode, { findings: error.findings }); } throw error; } } } return { invocationId: replay.invocationId, status: "replayed" as const, tool: virtualToolName ?? tool.name, targetTool: virtualToolName ? tool.name : undefined, result: replayResult, }; } } if (input.approvedActionRequestId) { let [actionRequest] = await db .select() .from(toolActionRequests) .where(eq(toolActionRequests.id, input.approvedActionRequestId)) .limit(1); if (!actionRequest || actionRequest.companyId !== session.companyId) { throw new ToolGatewayHttpError( 404, "Tool action request not found", "action_request_not_found", ); } const [storedInvocation] = await db .select() .from(toolInvocations) .where(eq(toolInvocations.id, actionRequest.invocationId)) .limit(1); if ( !storedInvocation || storedInvocation.companyId !== session.companyId ) { throw new ToolGatewayHttpError( 404, "Tool invocation not found", "invocation_not_found", ); } const requestingActor = policyInputForTool({ session, tool }).actor; if ( actionRequest.issueId !== session.issueId || storedInvocation.issueId !== session.issueId || storedInvocation.agentId !== session.agentId || storedInvocation.runId !== session.runId || actionRequest.requestedByAgentId !== (requestingActor.actorType === "agent" ? requestingActor.actorId : null) ) { throw new ToolGatewayHttpError( 403, "Approved action request is not scoped to this gateway session", "action_scope_mismatch", ); } if (!actionRequest.issueId || !actionRequest.interactionId) { throw new ToolGatewayHttpError( 403, "Approved action request is missing issue scope", "action_scope_mismatch", ); } const actionIssueId: string = actionRequest.issueId; const [linkedInteraction] = await db .select({ id: issueThreadInteractions.id, issueId: issueThreadInteractions.issueId, companyId: issueThreadInteractions.companyId, }) .from(issueThreadInteractions) .where( and( eq(issueThreadInteractions.id, actionRequest.interactionId), eq(issueThreadInteractions.companyId, session.companyId), eq(issueThreadInteractions.issueId, actionIssueId), ), ) .limit(1); if (!linkedInteraction) { throw new ToolGatewayHttpError( 403, "Approved action request is not linked to its originating interaction", "action_scope_mismatch", ); } if (storedInvocation.toolName !== tool.name) { throw new ToolGatewayHttpError( 409, "Approved action request is for a different tool", "action_tool_mismatch", ); } if ( actionRequest.expiresAt && actionRequest.expiresAt.getTime() <= Date.now() ) { const expiredAt = new Date(); const [expired] = await writeToolReviewChange(db, actionRequest.companyId, tx => tx .update(toolActionRequests) .set({ status: "expired", resolvedAt: expiredAt, updatedAt: expiredAt, }) .where( and( eq(toolActionRequests.id, actionRequest.id), inArray(toolActionRequests.status, ["pending", "approved"]), ), ) .returning({ id: toolActionRequests.id })); if (expired) { await reflectToolActionInteractionLifecycle({ actionRequestId: expired.id, status: "expired", }); } throw new ToolGatewayHttpError( 409, "Tool action request approval has expired", "action_expired", ); } if (actionRequest.status === "pending" && actionRequest.interactionId) { const [interaction] = await db .select({ status: issueThreadInteractions.status, kind: issueThreadInteractions.kind, resolvedByAgentId: issueThreadInteractions.resolvedByAgentId, resolvedByUserId: issueThreadInteractions.resolvedByUserId, resolvedAt: issueThreadInteractions.resolvedAt, }) .from(issueThreadInteractions) .where( and( eq(issueThreadInteractions.id, actionRequest.interactionId), eq(issueThreadInteractions.companyId, session.companyId), eq(issueThreadInteractions.issueId, actionIssueId), ), ) .limit(1); if ( interaction?.kind === "request_confirmation" && interaction.status === "accepted" ) { const [approved] = await writeToolReviewChange(db, actionRequest.companyId, tx => tx .update(toolActionRequests) .set({ status: "approved", resolvedByAgentId: interaction.resolvedByAgentId ?? null, resolvedByUserId: interaction.resolvedByUserId ?? null, decidedByAgentId: interaction.resolvedByAgentId ?? null, decidedByUserId: interaction.resolvedByUserId ?? null, decidedAt: interaction.resolvedAt ?? new Date(), resolvedAt: interaction.resolvedAt ?? new Date(), updatedAt: new Date(), }) .where( and( eq(toolActionRequests.id, actionRequest.id), eq(toolActionRequests.status, "pending"), ), ) .returning()); if (!approved) { throw new ToolGatewayHttpError( 409, "Tool action request has already been resolved", "action_already_resolved", ); } actionRequest = approved; await reflectToolActionInteractionLifecycle({ actionRequestId: approved.id, status: "approved", }); await writeToolCallEvent({ invocationId: storedInvocation.id, actionRequestId: actionRequest.id, session, eventType: "approval_resolved", outcome: "success", toolName: tool.name, policyDecision: "require_approval", reasonCode: "interaction_accepted", metadata: { actionRequestId: actionRequest.id, interactionId: actionRequest.interactionId, }, tool, }); } } if (actionRequest.status !== "approved") { throw new ToolGatewayHttpError( 409, "Tool action request is not approved or was already consumed", "action_not_approved", ); } if (actionRequest.approvalId) { const [formalApproval] = await db .select({ status: approvals.status }) .from(approvals) .where( and( eq(approvals.id, actionRequest.approvalId), eq(approvals.companyId, session.companyId), ), ) .limit(1); if (!formalApproval || formalApproval.status !== "approved") { throw new ToolGatewayHttpError( 409, "Tool action request requires formal board approval before execution", "formal_approval_required", { approvalId: actionRequest.approvalId }, ); } } const signedPayload = readSignedToolArgumentsPayload({ signedArguments: actionRequest.signedArguments, invocationId: storedInvocation.id, toolName: storedInvocation.toolName, signingSecret: options.toolActionSigningSecret, }); if (!signedPayload) { throw new ToolGatewayHttpError( 409, "Approved tool action arguments signature is invalid", "signed_arguments_invalid", ); } if (signedPayload.executionOnApprove !== true) { const error = new ToolGatewayHttpError( 409, "This approval predates execute-on-approve and must remain inert", "legacy_approved_action_inert", ); await options.beforeLegacyApprovedActionClaim?.(); const claimedAt = new Date(); const [claimed] = await writeToolReviewChange(db, actionRequest.companyId, tx => tx .update(toolActionRequests) .set({ status: "executing", resolvedByAgentId: session.agentId, updatedAt: claimedAt, }) .where( and( eq(toolActionRequests.id, actionRequest.id), eq(toolActionRequests.status, "approved"), ), ) .returning()); if (!claimed) { throw new ToolGatewayHttpError( 409, "Tool action request was already consumed", "action_already_consumed", ); } await reflectToolActionInteractionLifecycle({ actionRequestId: claimed.id, status: "executing", }); await markApprovedActionFailed({ actionRequestId: claimed.id, invocationId: storedInvocation.id, claimUpdatedAt: claimed.updatedAt, expectedInvocationStatus: "awaiting_approval", error, }); throw error; } const liveApprovalSnapshot = await connectedRemoteApprovalSnapshot( session, tool, ); if ( !approvalSnapshotsMatch( signedPayload.approvalSnapshot, liveApprovalSnapshot, ) ) { throw new ToolGatewayHttpError( 409, approvalTargetChangeMessage(signedPayload.approvalSnapshot, liveApprovalSnapshot), "approved_tool_target_changed", { invocationId: storedInvocation.id, actionRequestId: actionRequest.id, tool: tool.name, }, ); } const storedParameters = signedPayload.arguments; const storedArgumentValidation = await validateToolContent({ value: storedParameters, direction: "arguments", sensitiveMode: "redact", promptInjectionMode: "ignore", }); const storedCanonical = canonicalToolArguments(storedParameters); if ( ![ toolRequestIdentityHash(storedParameters, options.toolActionSigningSecret), summarizeToolValue(storedParameters).sha256, ].includes(actionRequest.canonicalArgumentsHash) || !verifyToolArgumentsSignature({ signedArguments: actionRequest.signedArguments, invocationId: storedInvocation.id, toolName: storedInvocation.toolName, canonicalArguments: storedCanonical, approvalSnapshot: signedPayload.approvalSnapshot, executionOnApprove: signedPayload.executionOnApprove, identityContextId: signedPayload.identityContextId, signingSecret: options.toolActionSigningSecret, }) ) { throw new ToolGatewayHttpError( 409, "Approved tool action arguments do not match reviewed hash", "signed_arguments_mismatch", ); } if ( !(await approvedManagedArgumentsRemainCurrent( session, tool, storedParameters, )) ) { throw await expireApprovedActionForManagedArgumentDrift({ companyId: actionRequest.companyId, actionRequestId: actionRequest.id, invocationId: storedInvocation.id, toolName: storedInvocation.toolName, }); } const claimedAt = new Date(); const [claimed] = await writeToolReviewChange(db, actionRequest.companyId, tx => tx .update(toolActionRequests) .set({ status: "executing", resolvedByAgentId: session.agentId, updatedAt: claimedAt, }) .where( and( eq(toolActionRequests.id, actionRequest.id), eq(toolActionRequests.status, "approved"), ), ) .returning()); if (!claimed) { throw new ToolGatewayHttpError( 409, "Tool action request was already consumed", "action_already_consumed", ); } await reflectToolActionInteractionLifecycle({ actionRequestId: claimed.id, status: "executing", }); invocationId = storedInvocation.id as typeof invocationId; effectiveParameters = storedParameters; effectiveArgumentsSummary = storedArgumentValidation.summary; await db .update(toolInvocations) .set({ status: "executing", approvalState: "approved", startedAt: new Date(), updatedAt: new Date(), }) .where(eq(toolInvocations.id, invocationId)); } else { const decisionInput = policyInputForTool({ session, tool, parameters: effectiveParameters, idempotencyKey: input.idempotencyKey, consumeRateLimit: true, }); let accessDecision = await policyService.decide(decisionInput); if (accessDecision.allowed && tool.providerType === "paperclip_slack_chat" && SLACK_TOOLS.some(t => t.name === tool.upstreamToolName && t.risk === "approval")) { accessDecision = { ...accessDecision, allowed: false, decision: "require_approval", reasonCode: "requires_approval_policy", explanation: "Slack destructive actions, channel creation and invitations require approval." }; } const recorded = await recordToolInvocation( decisionInput, accessDecision, ); await policyService.writeAudit(decisionInput, accessDecision); invocationId = recorded.invocation.id; const retryingSlackRateLimit = recorded.replayed && accessDecision.allowed && tool.providerType === "paperclip_slack_chat" && session.agentId && session.runId && session.issueId ? await claimSlackRateLimitRetry(db, { companyId: session.companyId, agentId: session.agentId, runId: session.runId, issueId: session.issueId, endpointId: String(asRecord(tool.providerMetadata)?.endpointId ?? ""), identityContextId: session.identityContextId }, invocationId) : false; const gitHubPublicationReplay = recorded.replayed && tool.providerType === "paperclip_github_chat" && ["begin_review", "comment", "update_comment", "submit_review"].includes(tool.upstreamToolName ?? "") && recorded.invocation.approvalState === "not_required"; const gitHubReplayPolicyAllowed = accessDecision.allowed; const gitHubReplayBindingMatches = recorded.invocation.agentId === session.agentId && recorded.invocation.runId === session.runId && recorded.invocation.issueId === session.issueId && recorded.invocation.connectionId === tool.connectionId && recorded.invocation.toolName === tool.name && ["authorized", "executing", "succeeded", "failed", "timed_out"].includes(recorded.invocation.status); if (gitHubPublicationReplay && gitHubReplayPolicyAllowed && !gitHubReplayBindingMatches) throw new ToolGatewayHttpError(409, "Idempotency key belongs to a different GitHub publication", "github_idempotency_conflict"); const retryingGitHubPublication = gitHubPublicationReplay && accessDecision.allowed && recorded.invocation.approvalState === "not_required" && gitHubReplayBindingMatches; // A keyed retry of a call whose provider task is still undelivered // runs again so it attaches to the task; it never sends tools/call twice. retryingMcpTaskRecordId = recorded.replayed && accessDecision.allowed && !retryingSlackRateLimit && !retryingGitHubPublication && recorded.invocation.agentId === session.agentId && await mcpTasksEnabled() ? await mcpTaskForKeyedRetry(session.companyId, recorded.invocation, { connectionId: tool.connectionId ?? null, argumentsIdentity: mcpTaskArgumentsIdentity(effectiveParameters), callerHeaders: input.callerHeaders, }) : null; // The same call repeated after the app asked a person a question runs // again: it carries the answers back, or waits again without the app. // An explicit key may name a different request: only the same tool // and arguments as the saved question round run again. const retryingElicitation = recorded.replayed && accessDecision.allowed && !retryingSlackRateLimit && !retryingGitHubPublication && !retryingMcpTaskRecordId && recorded.invocation.agentId === session.agentId // Whatever the last attempt ended with (a failed send records its // own error), a matching unsent round means the answer still has // to reach the app. && await elicitationRetryMatches(session.companyId, recorded.invocation.id, tool.name, effectiveParameters); const retryingMcpTask = Boolean(retryingMcpTaskRecordId) || retryingElicitation; if (retryingGitHubPublication) { // Invocation hashes describe shortened audit previews. The durable // publication checks the complete saved request and current authority. let receipt; try { receipt = await githubChatReviewService(db).readPublicationReceipt( session, tool.upstreamToolName!, effectiveParameters, invocationId, ); } catch (error) { if (error instanceof HttpError && error.status === 409) throw new ToolGatewayHttpError(409, error.message, "github_idempotency_conflict"); throw error; } if (receipt) { recoveredGitHubPublication = { content: JSON.stringify(receipt), data: receipt }; } else { const canRepeatPreflight = tool.upstreamToolName === "begin_review" || (recorded.invocation.status !== "succeeded" && !recorded.invocation.resultHash); const exactRequest = recorded.invocation.argumentsHash === toolRequestIdentityHash(effectiveParameters, options.toolActionSigningSecret); if (!canRepeatPreflight || !exactRequest) throw new ToolGatewayHttpError(409, "The saved GitHub publication is not available yet", "github_publication_unavailable"); } } if (recorded.replayed && !retryingSlackRateLimit && !retryingGitHubPublication && !retryingMcpTask) { if (gitHubPublicationReplay && !gitHubReplayPolicyAllowed) throw new ToolGatewayHttpError(policyErrorStatus(accessDecision), accessDecision.explanation, accessDecision.reasonCode); await writeAudit({ session, companyId: session.companyId, agentId: session.agentId, runId: session.runId, issueId: session.issueId, action: "tool_gateway.call_completed", details: { invocationId, decision: "allow", reasonCode: "idempotent_replay", tool: tool.name, ...toolAuditMetadata(tool), replayed: true, }, }); return { invocationId, status: "replayed" as const, tool: tool.name, result: recorded.invocation.resultSummary ?? null, }; } if (accessDecision.decision === "require_approval") { await requestApprovalForRecordedToolCall({ invocation: recorded.invocation, actionRequest: recorded.actionRequest, session, tool, parameters: effectiveParameters, argumentsSummary: argumentValidation.summary, policyDecision: accessDecision, }); } if (!accessDecision.allowed) { // recordInvocation inserted this row already terminal (denied or // rate_limited), so this is its only completion boundary. void emitConnectionInvoked(db, invocationId); await writeAudit({ session, companyId: session.companyId, agentId: session.agentId, runId: session.runId, issueId: session.issueId, action: "tool_gateway.call_denied", details: { invocationId, decision: accessDecision.decision, reasonCode: accessDecision.reasonCode, matchedPolicyIds: accessDecision.matchedPolicyIds, tool: tool.name, virtualToolName, targetToolName: virtualToolName ? tool.name : undefined, ...toolAuditMetadata(tool), argumentsSummary: effectiveArgumentsSummary, rateLimitState: accessDecision.rateLimitState ?? null, }, }); throw new ToolGatewayHttpError( policyErrorStatus(accessDecision), accessDecision.explanation, accessDecision.reasonCode, { invocationId, tool: tool.name, decision: accessDecision.decision, matchedPolicyIds: accessDecision.matchedPolicyIds, rateLimitState: accessDecision.rateLimitState ?? null, }, ); } await db .update(toolInvocations) .set({ status: "executing", ...(retryingGitHubPublication || retryingMcpTask ? { errorCode: null, errorMessage: null, completedAt: null } : {}), startedAt: new Date(), updatedAt: new Date(), }) .where(eq(toolInvocations.id, invocationId)); } await writeAudit({ session, companyId: session.companyId, agentId: session.agentId, runId: session.runId, issueId: session.issueId, action: "tool_gateway.call_allowed", details: { invocationId, decision: input.approvedActionRequestId ? "approved" : "allow", reasonCode: input.approvedActionRequestId ? "approved_action_request" : "profile_allows_tool", tool: tool.name, virtualToolName, targetToolName: virtualToolName ? tool.name : undefined, ...toolAuditMetadata(tool), argumentsSummary: effectiveArgumentsSummary, }, }); try { await assertCurrentGatewayIssuer(session, tool, effectiveParameters, invocationId, !!input.approvedActionRequestId); const executionTimeoutMs = timeoutMs(input.timeoutMs, tool); if ( tool.providerType === "paperclip_plugin" && (!session.agentId || !session.runId) ) { throw new ToolGatewayHttpError( 403, "Plugin tools require an agent run context", "agent_context_required", ); } const connectedMcpExecution = (tool.providerType === "mcp_remote_http" || tool.providerType === "provider_rest") ? await executeRemoteHttpTool( session, tool, effectiveParameters, executionTimeoutMs, invocationId, input.callerHeaders, input.timeoutMs === undefined, { // Approved actions keep their run's attribution, not its lifetime. run: session.runId && !input.approvedActionRequestId ? adapterExecutionControls.get(session.runId)?.controller.signal : undefined, caller: input.signal, attachToTaskRecordId: retryingMcpTaskRecordId, }, ) : tool.providerType === "mcp_local_stdio" ? await executeLocalStdioTool( session, tool, effectiveParameters, executionTimeoutMs, input.timeoutMs === undefined, invocationId, ) : null; const result = recoveredGitHubPublication ?? (connectedMcpExecution ? connectedMcpExecution.result : tool.providerType === "paperclip_plugin" ? await runWithTimeout( pluginToolDispatcher!.executeTool( tool.name, effectiveParameters, { agentId: session.agentId!, runId: session.runId!, companyId: session.companyId, projectId: session.projectId ?? "", }, ), executionTimeoutMs, ) : await runWithTimeout( executeBuiltinTool(session, tool, effectiveParameters, invocationId), executionTimeoutMs, )); const resultValidation = await validateToolContent({ value: result, direction: "result", sensitiveMode: "redact", promptInjectionMode: "block", classifier: resultClassifier(session, tool, invocationId, { approvedAction: Boolean(input.approvedActionRequestId), signal: input.signal }), }); const completedAt = new Date(); const validatedMcpResult = connectedMcpExecution ? asRecord(resultValidation.value) : null; if (validatedMcpResult?.error) { throw new ToolGatewayHttpError( validatedMcpResult.errorCode === "github_access_denied" ? 403 : 502, toolResultErrorMessage(validatedMcpResult, connectedMcpExecution?.failureInstructions), validatedMcpResult.errorCode === "github_access_denied" ? "github_access_denied" : "tool_error", { execution: connectedMcpExecution?.execution }, ); } await db .update(toolInvocations) .set({ status: "succeeded", resultHash: resultValidation.summary.sha256 ?? null, resultSummary: resultValidation.summary, resultSizeBytes: resultValidation.summary.sizeBytes ?? null, completedAt, updatedAt: completedAt, }) .where(eq(toolInvocations.id, invocationId)); // A provider task's result is now recorded; only now is it delivered. await markMcpTaskDelivered(session.companyId, invocationId); if (input.approvedActionRequestId) { const actionRequestId = input.approvedActionRequestId; const [executedRequest] = await writeToolReviewChange(db, session.companyId, tx => tx .update(toolActionRequests) .set({ status: "executed", resolvedAt: completedAt, updatedAt: completedAt, }) .where( and( eq(toolActionRequests.id, actionRequestId), eq(toolActionRequests.status, "executing"), ), ) .returning({ id: toolActionRequests.id })); if (executedRequest) { await reflectToolActionInteractionLifecycle({ actionRequestId: executedRequest.id, status: "executed", }); } } await writeToolCallEvent({ invocationId, actionRequestId: input.approvedActionRequestId ?? null, session, eventType: "call_completed", outcome: "success", toolName: tool.name, policyDecision: input.approvedActionRequestId ? "allow" : "allow", reasonCode: "tool_completed", argumentsSummary: effectiveArgumentsSummary, resultSummary: resultValidation.summary, detectorMetadata: resultValidation.detectorMetadata, metadata: { ...(virtualToolName ? { virtualToolName, targetToolName: tool.name } : {}), ...(connectedMcpExecution?.headerSummary ? { headerSummary: connectedMcpExecution.headerSummary } : {}), ...(connectedMcpExecution ? { execution: connectedMcpExecution.execution } : {}), }, tool, }); await writeAudit({ session, companyId: session.companyId, agentId: session.agentId, runId: session.runId, issueId: session.issueId, action: "tool_gateway.call_completed", details: { invocationId, decision: "allow", reasonCode: "tool_completed", tool: tool.name, virtualToolName, targetToolName: virtualToolName ? tool.name : undefined, ...toolAuditMetadata(tool), durationMs: Date.now() - startedAt, argumentsSummary: effectiveArgumentsSummary, result: summarizeResult(resultValidation.value), resultSummary: resultValidation.summary, promptInjection: resultValidation.detectorMetadata, headerSummary: connectedMcpExecution?.headerSummary ?? undefined, execution: connectedMcpExecution?.execution ?? undefined, }, }); // After the bookkeeping above: a throw there is caught below, overwrites // the row to failed, and emits — an earlier success emit would make one // execution report both outcomes. void emitConnectionInvoked(db, invocationId); if (connectedMcpExecution) { await recordMcpAppView(db, { session, tool, invocationId, toolInput: argumentValidation.value, result: resultValidation.value, resultMeta: await redactedMcpResultMeta(connectedMcpExecution.result), }); } return { invocationId, status: "completed" as const, tool: virtualToolName ?? tool.name, targetTool: virtualToolName ? tool.name : undefined, result: resultValidation.value, }; } catch (err) { const normalizedError = err instanceof ToolRuntimeSupervisorError ? new ToolGatewayHttpError( err.status, err.message, err.reasonCode, err.details, ) : err; const status = normalizedError instanceof ToolGatewayHttpError ? normalizedError.status : 502; const reasonCode = normalizedError instanceof ToolContentValidationError ? normalizedError.reasonCode : normalizedError instanceof ToolGatewayHttpError ? normalizedError.reasonCode : "tool_execution_failed"; const isRuntimeDeferred = status === 429 && (reasonCode === "runtime_capacity_unavailable" || reasonCode === "runtime_restart_backoff" || reasonCode === "runtime_restart_suppressed"); const isDeferred = status === 504 || isRuntimeDeferred; const message = normalizedError instanceof Error ? normalizedError.message : String(normalizedError); if (reasonCode === "elicitation_required") { throw normalizedError; } const completedAt = new Date(); await db .update(toolInvocations) .set({ status: status === 504 ? "timed_out" : status === 429 ? "rate_limited" : "failed", errorCode: reasonCode, errorMessage: message, completedAt, updatedAt: completedAt, }) .where(eq(toolInvocations.id, invocationId)); void emitConnectionInvoked(db, invocationId); if (input.approvedActionRequestId) { const actionRequestId = input.approvedActionRequestId; const [failedRequest] = await writeToolReviewChange(db, session.companyId, tx => tx .update(toolActionRequests) .set({ status: "failed", resolvedAt: completedAt, updatedAt: completedAt, }) .where( and( eq(toolActionRequests.id, actionRequestId), eq(toolActionRequests.status, "executing"), ), ) .returning({ id: toolActionRequests.id })); if (failedRequest) { await reflectToolActionInteractionLifecycle({ actionRequestId: failedRequest.id, status: "failed", errorCode: reasonCode, errorMessage: message, }); } } await writeToolCallEvent({ invocationId, actionRequestId: input.approvedActionRequestId ?? null, session, eventType: status === 504 ? "call_failed" : "call_failed", outcome: status === 504 ? "timeout" : "failure", toolName: tool.name, policyDecision: isDeferred ? "defer_runtime" : "deny", reasonCode, argumentsSummary: effectiveArgumentsSummary, metadata: { ...(virtualToolName ? { virtualToolName, targetToolName: tool.name } : {}), ...(normalizedError instanceof ToolContentValidationError ? { findings: normalizedError.findings, promptInjection: normalizedError.detectorMetadata } : {}), ...(executionAuditFromError(normalizedError) ? { execution: executionAuditFromError(normalizedError) } : {}), }, tool, }); await writeAudit({ session, companyId: session.companyId, agentId: session.agentId, runId: session.runId, issueId: session.issueId, action: isDeferred ? "tool_gateway.call_deferred" : "tool_gateway.call_failed", details: { invocationId, decision: isDeferred ? "defer_runtime" : "deny", reasonCode, tool: tool.name, virtualToolName, targetToolName: virtualToolName ? tool.name : undefined, ...toolAuditMetadata(tool), argumentsSummary: effectiveArgumentsSummary, durationMs: Date.now() - startedAt, error: message, ...(normalizedError instanceof ToolContentValidationError ? { promptInjection: normalizedError.detectorMetadata } : {}), ...(executionAuditFromError(normalizedError) ? { execution: executionAuditFromError(normalizedError) } : {}), }, }); if (normalizedError instanceof ToolContentValidationError) { throw new ToolGatewayHttpError(422, message, reasonCode, { findings: normalizedError.findings, }); } throw normalizedError; } }, async executePluginTool(input: ExecutePluginToolInput) { if (!pluginToolDispatcher) { throw new ToolGatewayHttpError( 501, "Plugin tool dispatch is not enabled", "plugin_tools_disabled", ); } if (input.actor.type === "agent") { if (input.actor.companyId !== input.runContext.companyId) { throw new ToolGatewayHttpError( 403, "Agent key cannot access another company", "actor_company_mismatch", ); } if (input.actor.agentId !== input.runContext.agentId) { throw new ToolGatewayHttpError( 403, "Agent cannot execute tools as another agent", "actor_agent_mismatch", ); } if (input.actor.runId && input.actor.runId !== input.runContext.runId) { throw new ToolGatewayHttpError( 403, "Agent cannot execute tools for another run", "actor_run_mismatch", ); } } const context = await resolveRunContext({ companyId: input.runContext.companyId, agentId: input.runContext.agentId, runId: input.runContext.runId, projectId: input.runContext.projectId, }); let invocationId = String(randomUUID()); const sessionLike: ToolGatewaySession = { id: "plugin-route", token: "plugin-route", companyId: input.runContext.companyId, agentId: input.runContext.agentId, runId: input.runContext.runId, issueId: context.issueId, projectId: input.runContext.projectId ?? context.projectId, createdAt: new Date(), expiresAt: new Date(Date.now() + DEFAULT_SESSION_TTL_MS), }; const tool = findStaticTool(input.tool); if (tool.providerType !== "paperclip_plugin") { throw new ToolGatewayHttpError( 404, `Tool "${input.tool}" is not a plugin tool`, "tool_not_found", ); } const requestedParameters = input.parameters ?? {}; const argumentValidation = await validateToolContent({ value: requestedParameters, direction: "arguments", sensitiveMode: "redact", promptInjectionMode: "ignore", }); const decisionInput = policyInputForTool({ session: sessionLike, tool, parameters: requestedParameters, consumeRateLimit: true, }); const accessDecision = await policyService.decide(decisionInput); const recorded = await recordToolInvocation( decisionInput, accessDecision, ); await policyService.writeAudit(decisionInput, accessDecision); invocationId = recorded.invocation.id; if (recorded.replayed) { return recorded.invocation.resultSummary; } if (accessDecision.decision === "require_approval") { await requestApprovalForRecordedToolCall({ invocation: recorded.invocation, actionRequest: recorded.actionRequest, session: sessionLike, tool, parameters: requestedParameters, argumentsSummary: argumentValidation.summary, policyDecision: accessDecision, }); } if (!accessDecision.allowed) { // recordInvocation inserted this row already terminal (denied or // rate_limited), so this is its only completion boundary. void emitConnectionInvoked(db, invocationId); await writeAudit({ session: sessionLike, companyId: input.runContext.companyId, agentId: input.runContext.agentId, runId: input.runContext.runId, issueId: context.issueId, action: "tool_gateway.call_denied", details: { invocationId, decision: accessDecision.decision, reasonCode: accessDecision.reasonCode, matchedPolicyIds: accessDecision.matchedPolicyIds, tool: input.tool, ...toolAuditMetadata(tool), argumentsSummary: argumentValidation.summary, rateLimitState: accessDecision.rateLimitState ?? null, }, }); throw new ToolGatewayHttpError( policyErrorStatus(accessDecision), accessDecision.explanation, accessDecision.reasonCode, { invocationId, tool: input.tool, decision: accessDecision.decision, matchedPolicyIds: accessDecision.matchedPolicyIds, rateLimitState: accessDecision.rateLimitState ?? null, }, ); } await db .update(toolInvocations) .set({ status: "executing", startedAt: new Date(), updatedAt: new Date(), }) .where(eq(toolInvocations.id, invocationId)); await writeAudit({ session: sessionLike, companyId: input.runContext.companyId, agentId: input.runContext.agentId, runId: input.runContext.runId, issueId: context.issueId, action: "tool_gateway.call_allowed", details: { invocationId, decision: "allow", reasonCode: "profile_allows_tool", tool: input.tool, ...toolAuditMetadata(tool), argumentsSummary: argumentValidation.summary, }, }); const startedAt = Date.now(); try { const result = await pluginToolDispatcher.executeTool( input.tool, requestedParameters, input.runContext, ); const resultValidation = await validateToolContent({ value: result, direction: "result", sensitiveMode: "redact", promptInjectionMode: "block", classifier: resultClassifier(sessionLike, tool, invocationId, { signal: input.signal }), }); await db .update(toolInvocations) .set({ status: "succeeded", resultHash: resultValidation.summary.sha256 ?? null, resultSummary: resultValidation.summary, resultSizeBytes: resultValidation.summary.sizeBytes ?? null, completedAt: new Date(), updatedAt: new Date(), }) .where(eq(toolInvocations.id, invocationId)); await writeToolCallEvent({ invocationId, session: sessionLike, eventType: "call_completed", outcome: "success", toolName: tool.name, policyDecision: "allow", reasonCode: "tool_completed", argumentsSummary: argumentValidation.summary, resultSummary: resultValidation.summary, detectorMetadata: resultValidation.detectorMetadata, tool, }); await writeAudit({ session: sessionLike, companyId: input.runContext.companyId, agentId: input.runContext.agentId, runId: input.runContext.runId, issueId: context.issueId, action: "tool_gateway.call_completed", details: { invocationId, decision: "allow", reasonCode: "tool_completed", tool: input.tool, ...toolAuditMetadata(tool), durationMs: Date.now() - startedAt, result: summarizeResult( (resultValidation.value as typeof result).result, ), resultSummary: resultValidation.summary, promptInjection: resultValidation.detectorMetadata, }, }); // After the bookkeeping above: a throw there is caught below, overwrites // the row to failed, and emits — an earlier success emit would make one // execution report both outcomes. void emitConnectionInvoked(db, invocationId); return resultValidation.value as typeof result; } catch (err) { const status = err instanceof ToolGatewayHttpError ? err.status : 502; const reasonCode = err instanceof ToolContentValidationError ? err.reasonCode : err instanceof ToolGatewayHttpError ? err.reasonCode : "tool_execution_failed"; const message = err instanceof Error ? err.message : String(err); await db .update(toolInvocations) .set({ status: status === 504 ? "timed_out" : "failed", errorCode: reasonCode, errorMessage: message, completedAt: new Date(), updatedAt: new Date(), }) .where(eq(toolInvocations.id, invocationId)); void emitConnectionInvoked(db, invocationId); await writeToolCallEvent({ invocationId, session: sessionLike, eventType: "call_failed", outcome: status === 504 ? "timeout" : "failure", toolName: tool.name, policyDecision: status === 504 ? "defer_runtime" : "deny", reasonCode, argumentsSummary: argumentValidation.summary, metadata: err instanceof ToolContentValidationError ? { findings: err.findings, promptInjection: err.detectorMetadata } : null, tool, }); await writeAudit({ session: sessionLike, companyId: input.runContext.companyId, agentId: input.runContext.agentId, runId: input.runContext.runId, issueId: context.issueId, action: "tool_gateway.call_failed", details: { invocationId, decision: "deny", reasonCode, tool: input.tool, ...toolAuditMetadata(tool), argumentsSummary: argumentValidation.summary, durationMs: Date.now() - startedAt, error: message, ...(err instanceof ToolContentValidationError ? { promptInjection: err.detectorMetadata } : {}), }, }); if (err instanceof ToolContentValidationError) { throw new ToolGatewayHttpError(422, message, reasonCode, { findings: err.findings, }); } throw err; } }, async revokeSession(input: { companyId: string; sessionId: string; revokedAt?: Date; actor?: { actorType?: LogActivityInput["actorType"]; actorId?: string; agentId?: string | null; runId?: string | null; }; agentScope?: { agentId: string; runId?: string | null } | null; }) { const now = input.revokedAt ?? new Date(); const [existing] = await db .select() .from(toolGatewaySessions) .where( and( eq(toolGatewaySessions.companyId, input.companyId), eq(toolGatewaySessions.id, input.sessionId), ), ) .limit(1); if (!existing) { throw new ToolGatewayHttpError( 404, "Tool gateway session not found", "session_not_found", ); } if (input.agentScope) { const runMatches = input.agentScope.runId ? existing.runId === input.agentScope.runId : true; if (existing.agentId !== input.agentScope.agentId || !runMatches) { throw new ToolGatewayHttpError( 403, "Tool gateway session is outside the authenticated agent scope", "session_scope_mismatch", ); } } const [session] = await db .update(toolGatewaySessions) .set({ revokedAt: now, updatedAt: now }) .where( and( eq(toolGatewaySessions.companyId, input.companyId), eq(toolGatewaySessions.id, input.sessionId), ), ) .returning(); const sessionView = gatewaySessionFromRow(session!); await writeAudit({ session: sessionView, companyId: sessionView.companyId, agentId: sessionView.agentId, runId: sessionView.runId, issueId: sessionView.issueId, actorType: input.actor?.actorType, actorId: input.actor?.actorId, action: "tool_gateway.session_revoked", details: { decision: "revoke", reasonCode: "session_revoked", revokedAt: now.toISOString(), previousRevokedAt: existing.revokedAt?.toISOString() ?? null, }, }); return { ...sessionView, revokedAt: session!.revokedAt ?? now }; }, /** * Poll provider tasks that no live call is waiting on (MCP Tasks). Each * row is claimed with a short lease, so replicas never poll one twice. */ async pollDueMcpTasks(input: { signal?: AbortSignal; limit?: number; wake?: McpTaskWake } = {}) { if (!(await mcpTasksEnabled())) return { processed: 0 }; const now = new Date(); const due = await db.select().from(toolMcpTasks).where(and( lte(toolMcpTasks.nextPollAt, now), or(isNull(toolMcpTasks.leaseExpiresAt), lte(toolMcpTasks.leaseExpiresAt, now)), )).orderBy(asc(toolMcpTasks.nextPollAt)).limit(input.limit ?? 25); let processed = 0; for (const candidate of due) { if (input.signal?.aborted) break; const owner = `worker:${randomUUID()}`; const [claimed] = await db.update(toolMcpTasks).set({ leaseOwner: owner, leaseExpiresAt: new Date(Date.now() + MCP_TASK_WORKER_LEASE_MS), updatedAt: new Date() }) .where(and( eq(toolMcpTasks.id, candidate.id), eq(toolMcpTasks.companyId, candidate.companyId), eq(toolMcpTasks.nextPollAt, candidate.nextPollAt!), or(isNull(toolMcpTasks.leaseExpiresAt), lte(toolMcpTasks.leaseExpiresAt, now)), )).returning(); if (!claimed) continue; try { await pollStoredMcpTask(claimed, owner, input.wake, input.signal); } catch (error) { logger.warn({ err: error, companyId: claimed.companyId, taskRecordId: claimed.id }, "provider task poll failed"); await updateMcpTask(claimed, { leaseExpiresAt: null, leaseOwner: null, pollFailures: claimed.pollFailures + 1, nextPollAt: new Date(Date.now() + backgroundPollDelayMs({ pollIntervalMs: claimed.pollIntervalMs, status: claimed.status as McpTaskRecordStatus, failures: claimed.pollFailures + 1 })), }, { owner }).catch(() => undefined); } processed += 1; } return { processed }; }, /** The next time a stored provider task needs attention, or null when none does. */ async nextMcpTaskPollAt(): Promise { if (!(await mcpTasksEnabled())) return null; const [row] = await db.select({ at: sql`min(greatest(${toolMcpTasks.nextPollAt}, coalesce(${toolMcpTasks.leaseExpiresAt}, ${toolMcpTasks.nextPollAt})))`, }).from(toolMcpTasks).where(sql`${toolMcpTasks.nextPollAt} is not null`); return row?.at ? new Date(row.at).getTime() : null; }, async nextCredentialExpiryAt(): Promise { const [row] = await db.execute<{ at: string | Date | null }>(sql` select min(expires_at) as at from ( (select ${toolMcpGatewayTokens.expiresAt} as expires_at from ${toolMcpGatewayTokens} where ${toolMcpGatewayTokens.expiresAt} is not null order by ${toolMcpGatewayTokens.expiresAt} limit 1) union all (select ${toolGatewaySessions.expiresAt} as expires_at from ${toolGatewaySessions} order by ${toolGatewaySessions.expiresAt} limit 1) ) expiries `); return row?.at == null ? null : new Date(row.at).getTime(); }, async cleanupExpiredSessions(input: { now?: Date; singleBatch?: boolean } = {}) { const now = input.now ?? new Date(); let deletedCount = 0; while (true) { const expiredTokens = await db.select({ id: toolMcpGatewayTokens.id }) .from(toolMcpGatewayTokens) .where(lte(toolMcpGatewayTokens.expiresAt, now)) .orderBy(asc(toolMcpGatewayTokens.expiresAt), asc(toolMcpGatewayTokens.id)) .limit(500); if (expiredTokens.length > 0) { await db.delete(toolMcpGatewayTokens) .where(and(inArray(toolMcpGatewayTokens.id, expiredTokens.map((token) => token.id)), lte(toolMcpGatewayTokens.expiresAt, now))) .returning({ id: toolMcpGatewayTokens.id }); } const expiredSessions = await db.select({ id: toolGatewaySessions.id }) .from(toolGatewaySessions) .where(lte(toolGatewaySessions.expiresAt, now)) .orderBy(asc(toolGatewaySessions.expiresAt), asc(toolGatewaySessions.id)) .limit(500); if (expiredSessions.length > 0) { const rows = await db.delete(toolGatewaySessions) .where(and(inArray(toolGatewaySessions.id, expiredSessions.map((session) => session.id)), lte(toolGatewaySessions.expiresAt, now))) .returning({ id: toolGatewaySessions.id }); deletedCount += rows.length; } // The worker schedules the next page; one-shot startup/manual callers // must finish the backlog without relying on another scheduled pass. if (input.singleBatch || (expiredTokens.length < 500 && expiredSessions.length < 500)) break; } return { deletedCount }; }, async listRuntimeSlots(companyId?: string) { return runtimeSupervisor.listSlots(companyId); }, async stopRuntimeSlot(input: { companyId: string; slotId: string; actor?: { agentId?: string | null; runId?: string | null }; managementContext?: ConnectionManagementContext; }) { await input.managementContext?.reauthorize(); try { const result = await runtimeSupervisor.stopSlot({ companyId: input.companyId, slotId: input.slotId, agentId: input.actor?.agentId ?? null, runId: input.actor?.runId ?? null, }); if (input.managementContext) await logActivity(db, { companyId: input.companyId, ...input.managementContext.audit, action: "tool_runtime.stopped", entityType: "tool_runtime_slot", entityId: input.slotId }); return result; } catch (err) { if (err instanceof ToolRuntimeSupervisorError) { throw new ToolGatewayHttpError( err.status, err.message, err.reasonCode, err.details, ); } throw err; } }, async restartRuntimeSlot(input: { companyId: string; slotId: string; actor?: { agentId?: string | null; runId?: string | null }; managementContext?: ConnectionManagementContext; }) { await input.managementContext?.reauthorize(); try { const result = await runtimeSupervisor.restartSlot({ companyId: input.companyId, slotId: input.slotId, agentId: input.actor?.agentId ?? null, runId: input.actor?.runId ?? null, }); if (input.managementContext) await logActivity(db, { companyId: input.companyId, ...input.managementContext.audit, action: "tool_runtime.restarted", entityType: "tool_runtime_slot", entityId: input.slotId }); return result; } catch (err) { if (err instanceof ToolRuntimeSupervisorError) { throw new ToolGatewayHttpError( err.status, err.message, err.reasonCode, err.details, ); } throw err; } }, }; } export type ToolGatewayService = ReturnType;