@stigmer/server 3.14.0-dev.20260910084630

package/dist/domain/mcpserver/connect.js

@@ -0,0 +1,805 @@
+/**
+ * McpServer connect (blocking lane) + the shared connect machinery —
+ * ports pkg/domain/mcpserver/controller/connect.go: the Connect RPC,
+ * prepareConnect (OAuth refresh pre-flight, ephemeral ExecutionContext,
+ * decrypt-lane token minting), environment resolution, the workflow
+ * failure→gRPC mapping, and apply's best-effort auto-connect tail. The
+ * async lane lives in start-connect.ts; the connect_status persistence
+ * family in connect-status.ts.
+ *
+ * Discovery runs on the RUNNER: this module starts the runner's
+ * stigmer/mcp-server/connect workflow through the engine seam
+ * (engine.ts) and never registers a worker.
+ *
+ * Proven by mcpserver-connect.conformance.test.ts
+ * (CONFORMANCE_TARGET=local-execution) and __tests__/connect.test.ts.
+ */
+import { create } from "@bufbuild/protobuf";
+import { Code, ConnectError } from "@connectrpc/connect";
+import { randomUUID } from "node:crypto";
+import { EnvironmentValueSchema } from "@stigmer/protos/ai/stigmer/agentic/environment/v1/spec_pb";
+import { ExecutionContextSchema } from "@stigmer/protos/ai/stigmer/agentic/executioncontext/v1/api_pb";
+import { ExecutionValueSchema } from "@stigmer/protos/ai/stigmer/agentic/executioncontext/v1/spec_pb";
+import { McpServerSchema } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/api_pb";
+import { McpServerCommandController } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/command_pb";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import { TokenEndpointAuthMethod } from "@stigmer/protos/ai/stigmer/iam/oauthapp/v1/spec_pb";
+import { authorizeDirect } from "../../pipeline/steps/authorize.js";
+import { failedPreconditionError, internalError, notFoundError, invalidArgumentError, unavailableError, } from "../../pipeline/errors.js";
+import { TOKEN_TYPE_EXECUTION_SCOPED } from "../../runnerauth/runnerauth.js";
+import { ResourceNotFoundError } from "../../store/interface.js";
+import { resolveOAuthAppRef } from "../oauthapp/refresolution.js";
+import { persistConnectFailure, persistConnectResult, persistConnectStarting, } from "./connect-status.js";
+import { refreshTokenIfExpired } from "./oauth/refresh.js";
+import { TOKEN_AUTH_METHOD_BASIC, TOKEN_AUTH_METHOD_POST, } from "./oauth/token.js";
+/**
+ * The connect workflow's WorkflowRunTimeout — the total budget for
+ * discovery + tool-approval classification. Sized from the runner's own
+ * bounds (issue #243): the 270s stdio init allowance (STDIO_INIT_TIMEOUT_MS
+ * in activities/discover-mcp-server.ts — a first run may download and
+ * compile packages via npx/uvx/go run) + the 120s classification floor
+ * (classifyWithTimeout in workflows/connect-mcp-server.ts) + margin for
+ * tool listing and persistence. Anything smaller makes the runner's
+ * cold-start allowance — and its actionable timeout error — unreachable by
+ * construction, which is exactly how the pre-#243 45s value killed every
+ * heavy stdio connect.
+ *
+ * Deliberately NOT sized for classification retries (maximumAttempts: 2)
+ * or >~160-tool stdio servers, whose budgets scale past any flat ceiling —
+ * async/pollable discovery is the cure for those, not a longer wait.
+ *
+ * Trade-off, accepted: this is also the bound on "no runner ever picked up
+ * the task", so a connect against a dead runner now waits the full budget
+ * before DEADLINE_EXCEEDED. The local daemon supervises the runner
+ * (crash-restart), making that state pathological rather than designed; a
+ * CLI --timeout remains the caller's soft bound.
+ */
+export const CONNECT_TIMEOUT = {
+    ms: 420_000,
+    goLabel: "7m0s",
+};
+/**
+ * The WorkflowRunTimeout for connects started through the async lane
+ * (startConnect), where no client blocks on the result and the ceiling is
+ * a backstop rather than anyone's wait.
+ *
+ * Sized generously above the activity budgets that do the real
+ * budget-keeping (discovery hard-bounded at 600s; classification scales
+ * max(120, (n/40+1)*60)s with up to 2 attempts): one hour covers the
+ * discovery bound plus two classification attempts for servers up to
+ * ~800 tools — well past anything in the wild. Beyond that a flat
+ * backstop becomes the limiting factor again; if such a server ever
+ * exists, the ceiling should turn into a value derived from the
+ * discovered tool count, not a bigger constant.
+ *
+ * The dead-runner concern that shaped CONNECT_TIMEOUT does not apply
+ * here: the async lane surfaces "no worker is polling" as a start-time
+ * warning on ConnectStatus instead of making a client wait to find out.
+ */
+export const ASYNC_CONNECT_TIMEOUT = {
+    ms: 60 * 60 * 1000,
+    goLabel: "1h0m0s",
+};
+/**
+ * Added to a budget to bound a settle task's wait on the workflow result.
+ * The workflow's own WorkflowRunTimeout is the deadline that should fire
+ * first; this slightly longer bound is only a backstop so a settle task
+ * can never hang if Temporal becomes unreachable (Go
+ * bestEffortConnectGetBuffer).
+ */
+export const BEST_EFFORT_CONNECT_GET_BUFFER_MS = 15_000;
+/** The label selecting the user's personal environment (connect.go:74). */
+export const PERSONAL_ENV_LABEL = "stigmer.ai/personal";
+/**
+ * Connect — triggers server-side MCP discovery and tool approval
+ * classification via the runner's Temporal workflow, blocking until the
+ * operation settles (Go Connect, connect.go:165).
+ *
+ * Lifecycle: prepareConnect → start-or-attach → record CONNECTING (the
+ * same bookkeeping the async lane does, so observers see one consistent
+ * record regardless of which lane ran) → block on the result → persist
+ * capabilities + classifier output + terminal phase atomically → delete
+ * the ExecutionContext. Prefer startConnect for interactive clients: this
+ * RPC's response can outlive browser transport limits.
+ */
+export async function connect(deps, input, identity) {
+    const engineState = deps.engineState();
+    if (!engineState.connected) {
+        throw failedPreconditionError("connect is not available: Temporal not configured");
+    }
+    const mcpServerId = input.mcpServerId;
+    if (mcpServerId === "") {
+        throw invalidArgumentError("mcp_server_id is required");
+    }
+    if (input.org === "") {
+        throw invalidArgumentError("org is required for connect");
+    }
+    let mcpServer;
+    try {
+        mcpServer = await deps.store.getResource(ApiResourceKind.mcp_server, mcpServerId, McpServerSchema);
+    }
+    catch {
+        throw notFoundError("mcp_server", mcpServerId);
+    }
+    // The annotation's can_connect check AFTER the load — the Java
+    // McpServerConnectHandler order (load-before-authorize, stigmer#224).
+    // C2 Stage 4.
+    await authorizeDirect(McpServerCommandController.method.connect, deps.authorizer, identity, input);
+    const prepared = await prepareConnect(deps, mcpServer, input);
+    try {
+        let run;
+        try {
+            run = await engineState.engine.startOrAttachConnect(mcpServerId, prepared.workflowInput, CONNECT_TIMEOUT.ms);
+        }
+        catch (error) {
+            deps.logger.error("Failed to start MCP connect workflow", {
+                mcp_server_id: mcpServerId,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            throw internalError(error, "failed to start connect workflow");
+        }
+        // Record the operation on connect_status. Skipped when attached: the
+        // lane that started the run already recorded it, and overwriting
+        // would reset its started_at. Best-effort — the blocking caller
+        // learns the outcome from this RPC's response either way.
+        if (!run.attached) {
+            try {
+                await persistConnectStarting(deps.store, mcpServerId, run.workflowId, "");
+            }
+            catch (error) {
+                deps.logger.warn("Failed to record CONNECTING on connect_status (non-fatal)", {
+                    mcp_server_id: mcpServerId,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+        }
+        // Bounded even on the blocking lane: Go's wait rides the RPC context
+        // (unbounded when Temporal dies mid-await); here the budget+buffer
+        // race answers Internal instead of hanging the handler forever —
+        // unreachable while Temporal is alive, disclosed as a bounded-wait
+        // delta.
+        const outcome = await run.result(CONNECT_TIMEOUT.ms + BEST_EFFORT_CONNECT_GET_BUFFER_MS);
+        if (!outcome.ok) {
+            const failure = mapConnectFailure(deps.logger, mcpServer, run.workflowId, outcome.failure, CONNECT_TIMEOUT);
+            await persistConnectFailure(deps.store, deps.logger, mcpServerId, failure);
+            throw failure;
+        }
+        // Persist discovered capabilities + the connect-time classifier
+        // output (layer 1 of the approval policy chain) atomically. The
+        // freshly-read, updated resource is returned to the caller.
+        let persisted;
+        let toolApprovalCount;
+        try {
+            ({ persisted, toolApprovalCount } = await persistConnectResult(deps.store, mcpServerId, run.workflowId, outcome.output));
+        }
+        catch (error) {
+            throw internalError(error, "failed to save mcp server after connect");
+        }
+        deps.logger.info("MCP server connect completed and stored", {
+            mcp_server_id: mcpServerId,
+            tools: persisted.status?.discoveredCapabilities?.tools.length ?? 0,
+            resource_templates: persisted.status?.discoveredCapabilities?.resourceTemplates.length ?? 0,
+            tool_approvals: toolApprovalCount,
+        });
+        return persisted;
+    }
+    finally {
+        if (prepared.ecResourceId !== "") {
+            await deleteConnectExecutionContext(deps, prepared.ecResourceId, prepared.executionId);
+        }
+    }
+}
+/**
+ * The caller-context half of a connect: the OAuth refresh pre-flight,
+ * ephemeral ExecutionContext creation, and decrypt-lane token minting
+ * (Go prepareConnect).
+ *
+ * Both the blocking (connect) and async (startConnect) lanes run this
+ * synchronously inside the RPC handler, because everything here needs the
+ * caller's identity: OAuth refresh and personal-environment resolution
+ * read the caller's grant and secrets, which a background task has no
+ * request context to do (the same constraint that scopes
+ * startBestEffortConnect to env-less servers).
+ */
+export async function prepareConnect(deps, mcpServer, input) {
+    const mcpServerId = mcpServer.metadata?.id ?? "";
+    const callerOrg = input.org;
+    // Pre-flight: refresh expired OAuth tokens before env resolution. Only
+    // applies when runtime_env is empty and the MCP server has an auth
+    // block with an existing OAuthGrant. Tokens are refreshed in the
+    // grant's managed environment.
+    if (Object.keys(input.runtimeEnv).length === 0) {
+        await refreshOAuthTokenIfNeeded(deps, mcpServer, callerOrg);
+    }
+    const executionId = `connect-${mcpServerId}-${randomUUID().slice(0, 8)}`;
+    const ecResourceId = await createConnectExecutionContext(deps, mcpServer, executionId, callerOrg, input.runtimeEnv);
+    const workflowInput = {
+        mcp_server_id: mcpServerId,
+        ...(ecResourceId !== "" ? { execution_context_id: executionId } : {}),
+    };
+    // Mint the decrypt-lane token for the EC just created (oss#535) — see
+    // the engine.ts ConnectWorkflowInput doc for why this rides the
+    // payload. Minting failure degrades, not fails: discovery of a server
+    // with declared credentials will refuse the redacted read with an
+    // actionable error, and credential-less servers connect fine without
+    // the token.
+    if (ecResourceId !== "" &&
+        deps.runnerAuth.isEnabled(TOKEN_TYPE_EXECUTION_SCOPED)) {
+        try {
+            const minted = deps.runnerAuth.mint(TOKEN_TYPE_EXECUTION_SCOPED, executionId, 0);
+            return {
+                workflowInput: {
+                    ...workflowInput,
+                    execution_context_token: minted.token,
+                },
+                ecResourceId,
+                executionId,
+            };
+        }
+        catch (error) {
+            deps.logger.warn("Failed to mint connect EC token — discovery will read redacted credentials", {
+                execution_id: executionId,
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    return { workflowInput, ecResourceId, executionId };
+}
+/**
+ * Builds and persists an ephemeral ExecutionContext for the connect
+ * activity (Go createConnectExecutionContext).
+ *
+ * When runtime_env is provided, the values are used directly (one-time
+ * use). When runtime_env is empty, variables are resolved from two
+ * sources: OAuth-managed variables from the grant's managed environment,
+ * the remainder from the user's personal environment. Returns "" when the
+ * MCP server has no env declarations and no runtime_env.
+ */
+async function createConnectExecutionContext(deps, mcpServer, executionId, callerOrg, runtimeEnv) {
+    let ecData;
+    if (Object.keys(runtimeEnv).length > 0) {
+        ecData = runtimeEnv;
+        deps.logger.info("Using runtime_env for connect ExecutionContext (one-time use)", {
+            execution_id: executionId,
+            runtime_env_count: Object.keys(runtimeEnv).length,
+        });
+    }
+    else {
+        const envDecls = mcpServer.spec?.env ?? {};
+        if (Object.keys(envDecls).length === 0) {
+            deps.logger.debug("MCP server has no env declarations — skipping ExecutionContext creation", { execution_id: executionId });
+            return "";
+        }
+        const mcpServerId = mcpServer.metadata?.id ?? "";
+        // Split resolution: OAuth vars from managed env, rest from personal.
+        const { oauthVars, remainingDecls } = await resolveOAuthVarsFromManagedEnv(deps, mcpServerId, callerOrg, envDecls);
+        let personalVars = {};
+        if (Object.keys(remainingDecls).length > 0) {
+            personalVars = await resolveFromPersonalEnvironment(deps, callerOrg, remainingDecls);
+        }
+        ecData = { ...personalVars, ...oauthVars };
+        deps.logger.info("Resolved env vars for connect ExecutionContext", {
+            execution_id: executionId,
+            oauth_count: Object.keys(oauthVars).length,
+            personal_count: Object.keys(personalVars).length,
+        });
+    }
+    if (Object.keys(ecData).length === 0) {
+        return "";
+    }
+    let created;
+    try {
+        created = await deps.executionContext.create(create(ExecutionContextSchema, {
+            apiVersion: "agentic.stigmer.ai/v1",
+            kind: "ExecutionContext",
+            metadata: {
+                name: `exec-ctx-${executionId}`,
+                org: callerOrg,
+            },
+            spec: {
+                executionId,
+                data: ecData,
+            },
+        }));
+    }
+    catch (error) {
+        throw internalError(error, "failed to create connect ExecutionContext");
+    }
+    const resourceId = created.metadata?.id ?? "";
+    deps.logger.info("Created ephemeral ExecutionContext for MCP connect", {
+        execution_context_id: resourceId,
+        execution_id: executionId,
+        data_entries: Object.keys(ecData).length,
+    });
+    return resourceId;
+}
+/**
+ * Reads OAuth-managed variables from the grant's managed environment and
+ * returns them along with the remaining declarations that still need the
+ * personal environment (Go resolveOAuthVarsFromManagedEnv). If no grant
+ * exists or reads fail, all declarations are returned as "remaining" —
+ * the personal-env fallback Go takes on the same arms.
+ */
+async function resolveOAuthVarsFromManagedEnv(deps, mcpServerId, org, envDecls) {
+    let grant;
+    try {
+        grant = await deps.oauthGrants.find("", mcpServerId, org);
+    }
+    catch {
+        // A grant-store read failure falls through to the personal env,
+        // exactly Go's err-folded arm.
+        return { oauthVars: {}, remainingDecls: envDecls };
+    }
+    if (grant === undefined || grant.environmentId === "") {
+        return { oauthVars: {}, remainingDecls: envDecls };
+    }
+    const oauthKey = grant.accessTokenEnvVar;
+    if (!(oauthKey in envDecls)) {
+        return { oauthVars: {}, remainingDecls: envDecls };
+    }
+    let tokenValue = "";
+    try {
+        tokenValue = await deps.managedEnv.readSecretValue(grant.environmentId, oauthKey);
+    }
+    catch (error) {
+        deps.logger.warn("Failed to read OAuth token from managed environment — falling back to personal env", {
+            mcp_server_id: mcpServerId,
+            oauth_key: oauthKey,
+            managed_env_id: grant.environmentId,
+            error: error instanceof Error ? error.message : String(error),
+        });
+        return { oauthVars: {}, remainingDecls: envDecls };
+    }
+    if (tokenValue === "") {
+        deps.logger.warn("Failed to read OAuth token from managed environment — falling back to personal env", {
+            mcp_server_id: mcpServerId,
+            oauth_key: oauthKey,
+            managed_env_id: grant.environmentId,
+        });
+        return { oauthVars: {}, remainingDecls: envDecls };
+    }
+    const remainingDecls = {};
+    for (const [k, v] of Object.entries(envDecls)) {
+        if (k !== oauthKey) {
+            remainingDecls[k] = v;
+        }
+    }
+    deps.logger.debug("Resolved OAuth token from managed environment", {
+        mcp_server_id: mcpServerId,
+        oauth_key: oauthKey,
+        managed_env_id: grant.environmentId,
+    });
+    return {
+        oauthVars: {
+            [oauthKey]: create(ExecutionValueSchema, {
+                value: tokenValue,
+                isSecret: true,
+            }),
+        },
+        remainingDecls,
+    };
+}
+/**
+ * Reads environment variables from the user's personal environment
+ * (labeled stigmer.ai/personal=true; Go resolveFromPersonalEnvironment).
+ * Required variables (optional=false, the default) must be present;
+ * optional variables are included when available but silently skipped
+ * when missing.
+ */
+async function resolveFromPersonalEnvironment(deps, org, envDecls) {
+    const requiredKeys = [];
+    for (const [k, decl] of Object.entries(envDecls)) {
+        if (!decl.optional) {
+            requiredKeys.push(k);
+        }
+    }
+    let listResponse;
+    try {
+        listResponse = await deps.environmentReader.list({
+            org,
+            labels: { [PERSONAL_ENV_LABEL]: "true" },
+        });
+    }
+    catch (error) {
+        throw internalError(error, "failed to list personal environments");
+    }
+    if (listResponse.totalCount === 0 || listResponse.items.length === 0) {
+        if (requiredKeys.length === 0) {
+            return {};
+        }
+        // Go renders the key list with %v — bracketed, space-separated.
+        throw failedPreconditionError(`personal environment not found for org '${org}'; save required credentials first: [${requiredKeys.join(" ")}]`);
+    }
+    const personalEnv = listResponse.items[0];
+    const personalEnvId = personalEnv?.metadata?.id ?? "";
+    const storedKeys = new Set(Object.keys(personalEnv?.spec?.data ?? {}));
+    const result = {};
+    const missing = [];
+    for (const [key, decl] of Object.entries(envDecls)) {
+        if (!storedKeys.has(key)) {
+            if (decl.optional) {
+                deps.logger.debug("Optional env var not in personal environment — skipping", { key });
+                continue;
+            }
+            missing.push(key);
+            continue;
+        }
+        let secretValue;
+        try {
+            secretValue = await deps.environmentReader.getSecretValue({
+                environmentId: personalEnvId,
+                key,
+            });
+        }
+        catch (error) {
+            deps.logger.warn("Failed to get secret value from personal environment", {
+                key,
+                personal_env_id: personalEnvId,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            if (decl.optional) {
+                continue;
+            }
+            missing.push(key);
+            continue;
+        }
+        if (secretValue.value === "") {
+            if (decl.optional) {
+                continue;
+            }
+            missing.push(key);
+            continue;
+        }
+        result[key] = create(ExecutionValueSchema, {
+            value: secretValue.value,
+            isSecret: decl.isSecret,
+        });
+    }
+    if (missing.length > 0) {
+        throw failedPreconditionError(`missing required credentials in personal environment: [${missing.join(" ")}]`);
+    }
+    return result;
+}
+/**
+ * Removes the ephemeral ExecutionContext after the connect workflow
+ * completes (Go deleteConnectExecutionContext). Failures are logged but
+ * not propagated, since the result is already stored.
+ */
+export async function deleteConnectExecutionContext(deps, resourceId, executionId) {
+    try {
+        await deps.executionContext.delete({ resourceId });
+    }
+    catch (error) {
+        deps.logger.warn("Failed to delete connect ExecutionContext (non-fatal)", {
+            resource_id: resourceId,
+            execution_id: executionId,
+            error: error instanceof Error ? error.message : String(error),
+        });
+        return;
+    }
+    deps.logger.debug("Deleted ephemeral connect ExecutionContext", {
+        resource_id: resourceId,
+        execution_id: executionId,
+    });
+}
+/**
+ * Maps a classified connect-run failure to the gRPC status the connect
+ * contract promises (Go awaitConnectWorkflow's switch, connect.go:661-694).
+ * budget is the WorkflowRunTimeout the run was started with, named in the
+ * DEADLINE_EXCEEDED message so the error reports the ceiling that
+ * actually fired.
+ */
+export function mapConnectFailure(logger, mcpServer, workflowId, failure, budget) {
+    const mcpServerId = mcpServer.metadata?.id ?? "";
+    logger.error("MCP connect workflow failed", {
+        workflow_id: workflowId,
+        mcp_server_id: mcpServerId,
+        failure_kind: failure.kind,
+    });
+    switch (failure.kind) {
+        case "application":
+            // FAILED_PRECONDITION, not INTERNAL (issue #239): an application
+            // error from the connect workflow means the TARGET server (or its
+            // credentials/config) refused the connect — the runner's message
+            // is crafted for the user, and clients render FAILED_PRECONDITION
+            // messages verbatim while (correctly) hiding INTERNAL detail.
+            return failedPreconditionError(buildConnectFailureMessage(mcpServer, failure.message));
+        case "timeout":
+            // Name the budget that fired (issue #243): the runner's own bounds
+            // fail earlier with specific, actionable errors, so reaching this
+            // ceiling usually means the runner never served the task at all.
+            return new ConnectError(`connect did not complete within the ${budget.goLabel} budget for MCP server '${mcpServerId}' — ` +
+                "if this repeats, check that your runner is running and healthy", Code.DeadlineExceeded);
+        case "service-not-found":
+            return unavailableError(`connect service temporarily unavailable for MCP server '${mcpServerId}'`);
+        case "other": {
+            // Deliberate exception to the "internal causes stay off the wire"
+            // rule (stigmer/stigmer#478): the cause here is the runner's own
+            // CLASSIFIED, user-facing connect-failure text, not raw server
+            // internals — so the message rides the wire, NOT the sanitized
+            // internalError helper. Connect failures are user-debugged
+            // configuration problems; the classified cause is the product.
+            return new ConnectError(buildConnectFailureMessage(mcpServer, failure.message), Code.Internal);
+        }
+        default: {
+            const exhaustive = failure;
+            throw new Error(`unhandled connect failure ${String(exhaustive)}`);
+        }
+    }
+}
+/**
+ * Builds a user-facing, transport-aware connect failure message (Go
+ * buildConnectFailureMessage), replacing the raw ExceptionGroup/TaskGroup
+ * text that told users nothing.
+ *
+ * In the OSS/local edition the local runner spawns stdio servers on the
+ * user's own machine, so a stdio failure is usually a missing command or
+ * bad args/environment — and previewing discovery locally with --dry-run
+ * is the fastest way to diagnose it. HTTP servers fail on reachability or
+ * credentials.
+ */
+export function buildConnectFailureMessage(mcpServer, cause) {
+    const name = mcpServer.metadata?.name ?? "";
+    // The runner classifies a 401 OAuth challenge into a self-contained,
+    // user-facing message (see runner mcp-oauth-detect.ts). It already
+    // names the server and tells the user to sign in, so pass it through
+    // verbatim rather than wrapping it with a generic "check your
+    // credentials" suffix that would contradict it. The "requires OAuth"
+    // phrase is the stable marker.
+    if (cause.includes("requires OAuth")) {
+        return cause;
+    }
+    if (mcpServer.spec?.serverType.case === "stdio") {
+        const slug = mcpServer.metadata?.slug ?? "";
+        return (`connect failed for MCP server '${name}': ${cause}. This is a stdio server launched ` +
+            "by your local runner — verify the command is installed and its arguments " +
+            "and environment variables are correct. Preview discovery locally with: " +
+            `stigmer connect mcp-server ${slug} --dry-run`);
+    }
+    return (`connect failed for MCP server '${name}': ${cause}. Check that the server URL is ` +
+        "reachable and your credentials are valid.");
+}
+/**
+ * Checks whether the MCP server has an auth block with an existing
+ * OAuthGrant, and if the access token is expired, refreshes it using the
+ * refresh token from the grant's managed environment (Go
+ * refreshOAuthTokenIfNeeded) — the pre-flight that ensures the connect
+ * workflow (and agent execution) always sees a fresh token.
+ */
+export async function refreshOAuthTokenIfNeeded(deps, mcpServer, callerOrg) {
+    const auth = mcpServer.spec?.auth;
+    if (auth === undefined) {
+        return;
+    }
+    const mcpServerId = mcpServer.metadata?.id ?? "";
+    // OSS mode: single user, empty identity_account_id. Org comes from the
+    // caller's active org (matches how the grant was stored).
+    let grant;
+    try {
+        grant = await deps.oauthGrants.find("", mcpServerId, callerOrg);
+    }
+    catch (error) {
+        deps.logger.warn("Failed to load OAuth grant for pre-flight check (non-fatal)", {
+            mcp_server_id: mcpServerId,
+            error: error instanceof Error ? error.message : String(error),
+        });
+        return;
+    }
+    if (grant === undefined) {
+        return;
+    }
+    if (grant.environmentId === "") {
+        deps.logger.warn("OAuth grant has no managed environment ID — user must re-authenticate via OAuth Connect", { mcp_server_id: mcpServerId });
+        return;
+    }
+    let refreshTokenValue;
+    try {
+        refreshTokenValue = await deps.managedEnv.readSecretValue(grant.environmentId, grant.refreshTokenEnvVar);
+    }
+    catch (error) {
+        // Silent skip, ported as-is (oss#863's second half): a failed
+        // refresh-token read proceeds with the stale token instead of
+        // failing fast with the re-authenticate message — which is why
+        // refresh.ts's empty-token error is unreachable through this path.
+        deps.logger.debug("No refresh token found in managed environment (may not be OAuth-connected)", {
+            mcp_server_id: mcpServerId,
+            refresh_token_var: grant.refreshTokenEnvVar,
+            managed_env_id: grant.environmentId,
+            error: error instanceof Error ? error.message : String(error),
+        });
+        return;
+    }
+    // For vendor OAuth, the client_secret and its token-endpoint auth
+    // method come from the OAuthApp. For DCR, both are empty (public
+    // client).
+    let clientSecret = "";
+    let tokenAuthMethod = "";
+    if (grant.authMethod === "vendor_oauth") {
+        try {
+            ({ clientSecret, tokenAuthMethod } = await loadOAuthAppClientCredentials(deps, mcpServer));
+        }
+        catch (error) {
+            deps.logger.warn("Failed to load OAuthApp client secret for refresh", {
+                mcp_server_id: mcpServerId,
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    let result;
+    try {
+        result = await refreshTokenIfExpired(grant, refreshTokenValue, clientSecret, tokenAuthMethod, deps.logger);
+    }
+    catch (error) {
+        throw failedPreconditionError(error instanceof Error ? error.message : String(error));
+    }
+    if (!result.refreshed) {
+        return;
+    }
+    // Write refreshed tokens to the grant's managed environment.
+    const tokenVars = {
+        [grant.accessTokenEnvVar]: create(EnvironmentValueSchema, {
+            value: result.newAccessToken,
+            isSecret: true,
+        }),
+    };
+    if (result.newRefreshToken !== refreshTokenValue) {
+        tokenVars[grant.refreshTokenEnvVar] = create(EnvironmentValueSchema, {
+            value: result.newRefreshToken,
+            isSecret: true,
+        });
+    }
+    try {
+        await deps.managedEnv.updateSecrets(grant.environmentId, tokenVars);
+    }
+    catch (error) {
+        throw internalError(error, "failed to update refreshed tokens in managed environment");
+    }
+    try {
+        await deps.oauthGrants.upsert({
+            ...grant,
+            accessTokenExpiresAt: result.newExpiresAt,
+        });
+    }
+    catch (error) {
+        deps.logger.warn("Failed to update OAuth grant after refresh (non-fatal)", {
+            mcp_server_id: mcpServerId,
+            error: error instanceof Error ? error.message : String(error),
+        });
+    }
+}
+/**
+ * Loads the decrypted client_secret and the token-endpoint auth method
+ * from the referenced OAuthApp for vendor OAuth token refresh (Go
+ * loadOAuthAppClientCredentials). The method is read LIVE (not
+ * snapshotted on the grant) so an admin correcting a misconfigured
+ * OAuthApp fixes refreshes immediately.
+ *
+ * Resolution goes through refresolution — the same lookup the initiate
+ * path used when the grant was minted — so the refresh always runs
+ * against the credentials the user actually signed in with (the old
+ * slug-only scan could load a same-slug app from a different org,
+ * stigmer/stigmer#584).
+ */
+export async function loadOAuthAppClientCredentials(deps, mcpServer) {
+    const ref = mcpServer.spec?.auth?.oauthAppRef;
+    if (ref === undefined || ref.slug === "") {
+        return { clientSecret: "", tokenAuthMethod: "" };
+    }
+    let app;
+    try {
+        app = await resolveOAuthAppRef(deps.store, ref, deps.logger);
+    }
+    catch (error) {
+        throw new Error(`failed to list oauth apps: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (app === undefined) {
+        throw new Error(`OAuthApp '${ref.slug}' not found`);
+    }
+    const tokenAuthMethod = tokenAuthMethodFromSpec(app.spec?.tokenEndpointAuthMethod ?? TokenEndpointAuthMethod.UNSPECIFIED);
+    let secret = app.spec?.clientSecret ?? "";
+    if (deps.secretService.isEncrypted(secret)) {
+        secret = await deps.secretService.decrypt(secret);
+    }
+    return { clientSecret: secret, tokenAuthMethod };
+}
+/**
+ * Maps the OAuthAppSpec enum onto the oauth package's RFC 8414 strings
+ * (Go tokenAuthMethodFromSpec). UNSPECIFIED means Basic — every OAuthApp
+ * created before the field existed authenticated via HTTP Basic.
+ */
+export function tokenAuthMethodFromSpec(method) {
+    if (method === TokenEndpointAuthMethod.CLIENT_SECRET_POST) {
+        return TOKEN_AUTH_METHOD_POST;
+    }
+    return TOKEN_AUTH_METHOD_BASIC;
+}
+/**
+ * Runs the connect workflow for a freshly applied MCP server and persists
+ * its discovered capabilities + classifier tool-approvals (Go
+ * StartBestEffortConnect). Apply launches it fire-and-forget: every
+ * failure is logged, never propagated. Persistence is shared with the
+ * synchronous connect path via persistConnectResult, so auto-connect and
+ * manual connect store byte-identical results.
+ *
+ * A disconnected engine returns SILENTLY — byte parity with Go's
+ * nil-temporalClient no-op (connect.go:1048). Servers that declare env
+ * vars are skipped: creating an ExecutionContext requires the caller's
+ * request context (for personal environment resolution), which a
+ * background task does not have. If the server is deleted before the
+ * workflow completes, persistence is skipped — expected for best-effort.
+ */
+export async function startBestEffortConnect(deps, mcpServer) {
+    const engineState = deps.engineState();
+    if (!engineState.connected) {
+        return;
+    }
+    const envKeys = Object.keys(mcpServer.spec?.env ?? {}).length;
+    if (envKeys > 0) {
+        deps.logger.debug("Skipping best-effort auto-connect: MCP server has env declarations (requires manual connect)", {
+            mcp_server_id: mcpServer.metadata?.id ?? "",
+            env_keys: envKeys,
+        });
+        return;
+    }
+    const mcpServerId = mcpServer.metadata?.id ?? "";
+    let run;
+    try {
+        run = await engineState.engine.startOrAttachConnect(mcpServerId, { mcp_server_id: mcpServerId }, CONNECT_TIMEOUT.ms);
+    }
+    catch (error) {
+        deps.logger.warn("Failed to start best-effort connect workflow (non-fatal)", {
+            mcp_server_id: mcpServerId,
+            error: error instanceof Error ? error.message : String(error),
+        });
+        return;
+    }
+    // Record CONNECTING like the other lanes so an observer of a freshly
+    // applied server sees the auto-connect in progress rather than
+    // nothing. Skipped when attached (the starting lane's record stands);
+    // failures stay non-fatal like everything else on this path.
+    if (!run.attached) {
+        try {
+            await persistConnectStarting(deps.store, mcpServerId, run.workflowId, "");
+        }
+        catch (error) {
+            deps.logger.warn("Failed to record CONNECTING for best-effort connect (non-fatal)", {
+                mcp_server_id: mcpServerId,
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    const outcome = await run.result(CONNECT_TIMEOUT.ms + BEST_EFFORT_CONNECT_GET_BUFFER_MS);
+    if (!outcome.ok) {
+        deps.logger.warn("Best-effort connect workflow did not complete (non-fatal)", {
+            workflow_id: run.workflowId,
+            mcp_server_id: mcpServerId,
+            failure_kind: outcome.failure.kind,
+        });
+        await persistConnectFailure(deps.store, deps.logger, mcpServerId, internalError(new Error(`connect run failed: ${outcome.failure.kind}`), "best-effort connect did not complete"));
+        return;
+    }
+    let persisted;
+    let toolApprovalCount;
+    try {
+        ({ persisted, toolApprovalCount } = await persistConnectResult(deps.store, mcpServerId, run.workflowId, outcome.output));
+    }
+    catch (error) {
+        if (error instanceof ResourceNotFoundError) {
+            deps.logger.info("Skipping best-effort connect persistence: MCP server deleted before connect completed", { mcp_server_id: mcpServerId });
+            return;
+        }
+        deps.logger.warn("Failed to persist best-effort connect result (non-fatal)", {
+            mcp_server_id: mcpServerId,
+            error: error instanceof Error ? error.message : String(error),
+        });
+        return;
+    }
+    deps.logger.info("Best-effort auto-connect completed and stored", {
+        workflow_id: run.workflowId,
+        mcp_server_id: mcpServerId,
+        tools: persisted.status?.discoveredCapabilities?.tools.length ?? 0,
+        resource_templates: persisted.status?.discoveredCapabilities?.resourceTemplates.length ?? 0,
+        tool_approvals: toolApprovalCount,
+    });
+}
+//# sourceMappingURL=connect.js.map