@akira-tl/forgerelay 0.8.8 → 0.8.10

package/dist/mcp/server/transport/http-server.js

@@ -0,0 +1,301 @@
+import { randomUUID } from "node:crypto";
+import { createMcpExpressApp } from "@modelcontextprotocol/sdk/server/express.js";
+import { getOAuthProtectedResourceMetadataUrl } from "@modelcontextprotocol/sdk/server/auth/router.js";
+import { requireBearerAuth } from "@modelcontextprotocol/sdk/server/auth/middleware/bearerAuth.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
+import { checkResourceAllowed, resourceUrlFromServerUrl } from "@modelcontextprotocol/sdk/shared/auth-utils.js";
+import express from "express";
+import { ActivityAuditStore } from "../../../activity/history/audit-store.js";
+import { BashOutputStore } from "../../../activity/history/bash-output-store.js";
+import { HostTurnStore } from "../../../activity/history/host-turn-store.js";
+import { ActivityLifecycle } from "../../../activity/runtime/lifecycle.js";
+import { ActivityQueryService } from "../../../activity/history/query-service.js";
+import { CodeIntelligenceManager } from "../../../lsp/runtime/manager.js";
+import { createOpenAIIncomingArtifactAdapter } from "../../artifacts/incoming-artifacts.js";
+import { logEvent, requestPath, transportSessionIdPrefix } from "../../../runtime/logging/logger.js";
+import { SingleUserOAuthProvider } from "../../oauth/oauth-provider.js";
+import { createForgeRelayAuthRouter } from "../../oauth/router.js";
+import { publicEndpointUrl } from "../../oauth/public-url.js";
+import { McpTransportRegistry } from "./mcp-sessions.js";
+import { ProcessManager } from "../../process/process-sessions.js";
+import { createReviewCheckpointManager } from "../../../workspaces/review/review-checkpoints.js";
+import { RemoteWorkspaceRelay } from "../../../workspaces/relay/workspace-relay.js";
+import { CompositeWorkspaceRegistry } from "../../../workspaces/composite/composite-workspaces.js";
+import { createWorkspaceStore } from "../../../workspaces/state/workspace-store.js";
+import { WorkspaceTaskReminderTracker } from "../../../workspaces/tasks/workspace-task-reminders.js";
+import { WorkspaceTaskStore } from "../../../workspaces/tasks/workspace-tasks.js";
+import { WorkspaceRegistry } from "../../../workspaces.js";
+import { getSubagentProviderAvailabilitySnapshot } from "../../../subagents/providers/availability.js";
+import { activityPanelAssetDirectory, setActivityPanelAssetHeaders } from "../../panel/app.js";
+import { mcpRequestDebugFields, requestLogFields, sendJsonRpcError } from "./http-support.js";
+const MCP_TRANSPORT_IDLE_TIMEOUT_MS = 24 * 60 * 60 * 1_000;
+const MAX_MCP_TRANSPORT_SESSIONS = 64;
+const MCP_TRANSPORT_CLEANUP_INTERVAL_MS = 5 * 60 * 1_000;
+export function createHttpServer(config, options, createMcpServer) {
+    const incomingArtifactAdapters = options.incomingArtifactAdapters
+        ?? [createOpenAIIncomingArtifactAdapter()];
+    const allowedHosts = config.allowedHosts.includes("*")
+        ? undefined
+        : Array.from(new Set([config.host, ...config.allowedHosts]));
+    const app = createMcpExpressApp({
+        host: config.host,
+        ...(allowedHosts ? { allowedHosts } : {}),
+    });
+    const transports = new McpTransportRegistry({
+        maxTransports: MAX_MCP_TRANSPORT_SESSIONS,
+    });
+    const mcpUrl = publicEndpointUrl(config.publicBaseUrl, "mcp");
+    const resourceServerUrl = resourceUrlFromServerUrl(mcpUrl);
+    const oauthProvider = new SingleUserOAuthProvider(config.oauth, mcpUrl, config.stateDir);
+    const bearerAuth = requireBearerAuth({
+        verifier: oauthProvider,
+        requiredScopes: [config.oauth.scopes[0] ?? "forgerelay"],
+        resourceMetadataUrl: getOAuthProtectedResourceMetadataUrl(resourceServerUrl),
+    });
+    const workspaceStore = createWorkspaceStore(config.stateDir);
+    const workspaces = new WorkspaceRegistry(config, workspaceStore);
+    const sharedRemoteWorkspaces = new RemoteWorkspaceRelay(config.configDir, config.stateDir);
+    const sharedCompositeWorkspaces = new CompositeWorkspaceRegistry(config.stateDir);
+    const sharedWorkspaceTasks = new WorkspaceTaskStore(config.stateDir);
+    const sharedTaskReminders = new WorkspaceTaskReminderTracker(config.taskReminderInterval, sharedWorkspaceTasks);
+    const activityAuditStore = new ActivityAuditStore(config.stateDir);
+    const bashOutputStore = new BashOutputStore(config.stateDir);
+    const hostTurnStore = new HostTurnStore(config.stateDir);
+    const activityQueries = new ActivityQueryService(hostTurnStore, activityAuditStore, bashOutputStore);
+    const activityLifecycle = new ActivityLifecycle(activityAuditStore, {
+        turnIdForConversation: (conversationScopeId, workspaceId) => activityQueries.currentTurnId(conversationScopeId, workspaceId),
+    });
+    const reviewCheckpoints = createReviewCheckpointManager();
+    const processSessions = new ProcessManager({ outputAudit: bashOutputStore });
+    const codeIntelligence = new CodeIntelligenceManager(config);
+    const subagentProviders = config.subagents
+        ? getSubagentProviderAvailabilitySnapshot()
+        : [];
+    const logTransportCloseResults = (reason, results) => {
+        let closedCount = 0;
+        for (const result of results) {
+            if (result.error) {
+                logEvent(config.logging, "warn", "mcp_transport_session_close_failed", {
+                    reason,
+                    transportSessionIdPrefix: transportSessionIdPrefix(result.transportSessionId),
+                    error: result.error instanceof Error
+                        ? result.error.message
+                        : String(result.error),
+                });
+                continue;
+            }
+            closedCount += 1;
+            if (reason !== "server_shutdown") {
+                logEvent(config.logging, "debug", "mcp_transport_session_closed", {
+                    reason,
+                    transportSessionIdPrefix: transportSessionIdPrefix(result.transportSessionId),
+                });
+            }
+        }
+        if (reason === "server_shutdown" && closedCount > 0) {
+            logEvent(config.logging, "debug", "mcp_transport_sessions_closed", {
+                reason,
+                count: closedCount,
+            });
+        }
+    };
+    const logRuntimeResources = () => {
+        const memory = process.memoryUsage();
+        const processStats = processSessions.stats();
+        const codeStats = codeIntelligence.stats();
+        logEvent(config.logging, "debug", "runtime_resources", {
+            rssBytes: memory.rss,
+            heapUsedBytes: memory.heapUsed,
+            heapTotalBytes: memory.heapTotal,
+            externalBytes: memory.external,
+            arrayBuffersBytes: memory.arrayBuffers,
+            mcpTransports: transports.size,
+            processesTotal: processStats.total,
+            processesRunning: processStats.running,
+            processesCompleted: processStats.completed,
+            cachedWorkspaces: workspaces.cachedWorkspaceCount,
+            reviewStates: reviewCheckpoints.stateCount,
+            languageServices: codeStats.servicesTotal,
+            languageServicesActive: codeStats.servicesActive,
+            languageProcessesRunning: codeStats.processesRunning,
+            languageOperationsInFlight: codeStats.operationsInFlight,
+            languageRequestsActive: codeStats.semanticRequestsActive,
+            languageRequestsQueued: codeStats.semanticRequestsQueued,
+            languageOpenDocuments: codeStats.openDocuments,
+            languageDiagnosticSnapshots: codeStats.diagnosticSnapshots,
+            languageDiagnosticsRetained: codeStats.diagnosticsRetained,
+            languageStderrBytes: codeStats.stderrBytes,
+            languagePendingCreations: codeStats.pendingCreations,
+            languageCrashCooldowns: codeStats.crashCooldowns,
+            languageInvalidatedServices: codeStats.invalidatedServices,
+            languageRetiredWorkspaceRoots: codeStats.retiredWorkspaceRoots,
+        });
+    };
+    const transportCleanupTimer = setInterval(() => {
+        void transports
+            .closeIdle(MCP_TRANSPORT_IDLE_TIMEOUT_MS)
+            .then((results) => logTransportCloseResults("idle_timeout", results))
+            .finally(logRuntimeResources);
+    }, MCP_TRANSPORT_CLEANUP_INTERVAL_MS);
+    transportCleanupTimer.unref();
+    logRuntimeResources();
+    if (config.logging.trustProxy) {
+        app.set("trust proxy", 1);
+    }
+    app.use((req, res, next) => {
+        const requestId = randomUUID();
+        const startedAt = performance.now();
+        res.locals.requestId = requestId;
+        res.on("finish", () => {
+            const path = requestPath(req);
+            if (!config.logging.requests)
+                return;
+            if (!config.logging.assets && path.startsWith("/mcp-app-assets"))
+                return;
+            logEvent(config.logging, "info", "http_request", {
+                requestId,
+                method: req.method,
+                path,
+                status: res.statusCode,
+                durationMs: Math.round(performance.now() - startedAt),
+                ...requestLogFields(req),
+            });
+        });
+        next();
+    });
+    app.use(createForgeRelayAuthRouter({
+        provider: oauthProvider,
+        cliAuthenticationProvider: oauthProvider,
+        instanceId: config.instanceId,
+        issuerUrl: new URL(config.publicBaseUrl),
+        resourceServerUrl,
+        scopesSupported: config.oauth.scopes,
+        resourceName: "ForgeRelay",
+    }));
+    app.options("/mcp-app-assets/{*asset}", (_req, res) => {
+        setActivityPanelAssetHeaders(res);
+        res.sendStatus(204);
+    });
+    app.use("/mcp-app-assets", express.static(activityPanelAssetDirectory(), {
+        immutable: true,
+        maxAge: "1y",
+        fallthrough: false,
+        setHeaders: setActivityPanelAssetHeaders,
+    }));
+    app.get("/healthz", (_req, res) => {
+        res.json({ ok: true, name: "forgerelay" });
+    });
+    app.all("/mcp", async (req, res) => {
+        const requestId = res.locals.requestId;
+        const transportSessionId = req.header("mcp-session-id");
+        const initializeRequest = req.method === "POST" && isInitializeRequest(req.body);
+        await new Promise((resolve, reject) => {
+            bearerAuth(req, res, (error) => {
+                if (error)
+                    reject(error);
+                else
+                    resolve();
+            });
+        });
+        if (res.headersSent)
+            return;
+        if (!req.auth?.resource || !checkResourceAllowed({ requestedResource: req.auth.resource, configuredResource: resourceServerUrl })) {
+            logEvent(config.logging, "warn", "auth_denied", {
+                requestId,
+                method: req.method,
+                path: requestPath(req),
+                reason: "invalid_oauth_resource",
+                ...requestLogFields(req),
+            });
+            sendJsonRpcError(res, 401, -32001, "Unauthorized");
+            return;
+        }
+        logEvent(config.logging, "debug", "mcp_request", {
+            requestId,
+            httpMethod: req.method,
+            transportSessionIdPresent: Boolean(transportSessionId),
+            transportSessionIdPrefix: transportSessionIdPrefix(transportSessionId),
+            isInitialize: initializeRequest,
+            ...mcpRequestDebugFields(req.body),
+        });
+        try {
+            let transport;
+            if (transportSessionId) {
+                transport = transports.get(transportSessionId);
+                if (!transport) {
+                    sendJsonRpcError(res, 404, -32000, "Unknown MCP transport session");
+                    return;
+                }
+            }
+            else if (initializeRequest) {
+                transport = new StreamableHTTPServerTransport({
+                    sessionIdGenerator: () => randomUUID(),
+                    onsessioninitialized: (newTransportSessionId) => {
+                        if (transport) {
+                            void transports
+                                .register(newTransportSessionId, transport)
+                                .then((results) => logTransportCloseResults("capacity_limit", results));
+                        }
+                        logEvent(config.logging, "debug", "mcp_transport_session_created", {
+                            requestId,
+                            transportSessionIdPrefix: transportSessionIdPrefix(newTransportSessionId),
+                            ...requestLogFields(req),
+                        });
+                    },
+                });
+                transport.onclose = () => {
+                    const closedTransportSessionId = transport?.sessionId;
+                    if (closedTransportSessionId && transports.remove(closedTransportSessionId)) {
+                        logEvent(config.logging, "debug", "mcp_transport_session_closed", {
+                            reason: "transport_close",
+                            transportSessionIdPrefix: transportSessionIdPrefix(closedTransportSessionId),
+                        });
+                    }
+                };
+                const server = createMcpServer(config, workspaces, reviewCheckpoints, processSessions, subagentProviders, incomingArtifactAdapters, codeIntelligence, activityLifecycle, bashOutputStore, activityQueries, {
+                    taskReminders: sharedTaskReminders,
+                    remoteWorkspaces: sharedRemoteWorkspaces,
+                    compositeWorkspaces: sharedCompositeWorkspaces,
+                });
+                await server.connect(transport);
+            }
+            else {
+                sendJsonRpcError(res, 400, -32000, "No valid MCP transport session");
+                return;
+            }
+            await transport.handleRequest(req, res, req.body);
+        }
+        catch (error) {
+            logEvent(config.logging, "error", "mcp_request_error", {
+                requestId,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            if (!res.headersSent) {
+                sendJsonRpcError(res, 500, -32603, "Internal server error");
+            }
+        }
+    });
+    let closePromise;
+    return {
+        app,
+        config,
+        subagentProviders,
+        close: () => {
+            closePromise ??= (async () => {
+                clearInterval(transportCleanupTimer);
+                const results = await transports.closeAll();
+                logTransportCloseResults("server_shutdown", results);
+                await sharedRemoteWorkspaces.shutdown();
+                processSessions.shutdown();
+                await codeIntelligence.shutdown();
+                oauthProvider.close();
+                hostTurnStore.close();
+                bashOutputStore.close();
+                activityAuditStore.close();
+                workspaceStore.close?.();
+            })();
+            return closePromise;
+        },
+    };
+}

package/dist/mcp/server/transport/http-support.js

@@ -0,0 +1,43 @@
+import { requestIp } from "../../../runtime/logging/logger.js";
+export function sendJsonRpcError(res, status, code, message) {
+    res.status(status).json({
+        jsonrpc: "2.0",
+        error: { code, message },
+        id: null,
+    });
+}
+export function requestLogFields(req) {
+    return {
+        ip: requestIp(req),
+        host: req.header("host"),
+        userAgent: req.header("user-agent"),
+        origin: req.header("origin"),
+        referer: req.header("referer"),
+        contentLength: req.header("content-length"),
+    };
+}
+export function mcpRequestDebugFields(body) {
+    if (!body || typeof body !== "object" || Array.isArray(body))
+        return {};
+    const request = body;
+    const rpcMethod = typeof request.method === "string" ? request.method : undefined;
+    const params = request.params && typeof request.params === "object" && !Array.isArray(request.params)
+        ? request.params
+        : undefined;
+    const rpcMeta = params?._meta && typeof params._meta === "object" && !Array.isArray(params._meta)
+        ? params._meta
+        : undefined;
+    const rpcMetaKeys = rpcMeta ? Object.keys(rpcMeta).sort() : [];
+    let rpcTarget;
+    if (rpcMethod === "resources/read" && typeof params?.uri === "string") {
+        rpcTarget = params.uri;
+    }
+    else if (rpcMethod === "tools/call" && typeof params?.name === "string") {
+        rpcTarget = params.name;
+    }
+    return {
+        rpcMethod,
+        rpcTarget,
+        ...(rpcMetaKeys.length > 0 ? { rpcMetaKeys } : {}),
+    };
+}

package/dist/mcp/server/workspace/runtime/workspace-open-presentation.js

@@ -0,0 +1,242 @@
+import { buildCapabilityFingerprint } from "../../core/capabilities.js";
+import { isArtifactDownloadSupportedPlatform } from "../../../artifacts/artifact-tools.js";
+import { attachHookReports } from "../../../hooks/hooks.js";
+import { formatPathForPrompt } from "../../../../workspaces/resources/skills.js";
+import { compactWorkspacePresentation } from "../../../../workspaces/presentation/workspace-presentation.js";
+import { formatAgentsPath } from "../../../../workspaces.js";
+import { formatAvailableSubagentProfile, summarizeSubagentProfile } from "../../../../subagents/profiles.js";
+import { formatUnavailableSubagentProvider } from "../../../../subagents/providers/availability.js";
+import { capabilityContextFor } from "../../core/capability-support.js";
+import { redactSkillDiagnosticPaths } from "../../core/schemas.js";
+import { logToolCall, workspaceLogContext } from "../../core/tool-support.js";
+export const workspaceTaskUsageInstruction = "Use workspace.tasks proactively for work that spans multiple steps or sessions: create or update Tasks to preserve useful next steps and current state, and read its summary when resuming relevant unfinished work. Do not query it mechanically on every open_workspace call.";
+export async function presentLocalWorkspaceOpen(options, input, contextData) {
+    const { config, forgerelayVersion: FORGERELAY_VERSION, workspaces, workspaceTasks, reviewCheckpoints, capabilityRegistry, subagentProviders, hooks, rememberWorkspacePanelState, } = options;
+    const { path, workspaceId, mode, baseRef, newWorktree, newWorkspace, context } = input;
+    const { conversationScopeId, protectedWorkspaceIds, startedAt, sessionId } = contextData;
+    const { workspace, agentsFiles, availableAgentsFiles, hookReports, workspaceReused, bootstrapContextComponents, contextFingerprint, } = await workspaces.openWorkspace({ path, workspaceId, mode, baseRef, newWorktree, newWorkspace, context }, {
+        conversationScopeId,
+        protectedWorkspaceIds,
+    });
+    workspaceTasks.initializeWorkspace(workspace.id);
+    const requestedContext = context ?? "auto";
+    const resourceUpdate = workspaceReused && requestedContext === "auto"
+        ? workspaces.claimResourceUpdates(workspace.id, conversationScopeId)
+        : undefined;
+    if (requestedContext === "full" || (!workspaceReused && requestedContext !== "none")) {
+        workspaces.acknowledgeResourceUpdates(workspace.id, conversationScopeId);
+    }
+    const effectiveBootstrapContextComponents = resourceUpdate
+        ? bootstrapContextComponents.filter((component) => !resourceUpdate.coveredComponents.includes(component))
+        : bootstrapContextComponents;
+    const effectiveIncludeBootstrapContext = effectiveBootstrapContextComponents.length > 0 || Boolean(resourceUpdate);
+    const knownWorktrees = await workspaces.listKnownWorktrees(workspace);
+    const staleWorkspaces = await workspaces.listStaleWorkspaces(workspace);
+    const capabilityFingerprint = buildCapabilityFingerprint(config, FORGERELAY_VERSION, {
+        artifactDownloadSupported: isArtifactDownloadSupportedPlatform(),
+    });
+    if (config.widgets === "changes") {
+        await reviewCheckpoints.initializeWorkspace({
+            workspaceId: workspace.id,
+            root: workspace.root,
+        });
+    }
+    const cardSkills = workspace.skills
+        .filter((skill) => !skill.disableModelInvocation)
+        .map((skill) => ({
+        name: skill.name,
+        description: skill.description,
+    }));
+    const capabilityGuides = workspace.capabilityGuides.map((guide) => ({
+        name: guide.name,
+        description: guide.description,
+        whenToRead: guide.whenToRead,
+        path: formatPathForPrompt(guide.filePath),
+    }));
+    const capabilityCatalog = capabilityRegistry.catalog(capabilityContextFor(workspace));
+    const cardAgentProviders = config.subagents ? subagentProviders : [];
+    const cardAgents = workspace.agentProfiles.map((profile) => {
+        const summary = summarizeSubagentProfile(profile);
+        const availability = cardAgentProviders.find((provider) => provider.name === summary.provider);
+        return {
+            ...summary,
+            providerAvailable: availability?.available,
+            providerUnavailableReason: availability?.reason,
+        };
+    });
+    const cardAgentsFiles = agentsFiles.map((file) => ({
+        path: formatAgentsPath(file.path, workspace.root),
+        content: file.content,
+    }));
+    const cardAvailableAgentsFiles = availableAgentsFiles.map((file) => ({
+        path: formatAgentsPath(file.path, workspace.root),
+    }));
+    const bootstrapComponents = new Set(effectiveBootstrapContextComponents);
+    const visibleSkills = bootstrapComponents.has("skills") ? cardSkills : [];
+    const visibleSkillDiagnostics = bootstrapComponents.has("skillDiagnostics")
+        ? redactSkillDiagnosticPaths(workspace.skillDiagnostics)
+        : [];
+    const visibleCapabilityGuides = bootstrapComponents.has("capabilityGuides") ? capabilityGuides : [];
+    const visibleAgentProviders = bootstrapComponents.has("agentProfiles") ? cardAgentProviders : [];
+    const visibleAgents = bootstrapComponents.has("agentProfiles") ? cardAgents : [];
+    const loadedAgentsFiles = bootstrapComponents.has("agentsFiles") ? cardAgentsFiles : [];
+    const availableAgentsFileOutputs = bootstrapComponents.has("availableAgentsFiles")
+        ? cardAvailableAgentsFiles
+        : [];
+    const workspaceContextInstruction = "For later open_workspace calls, context=\"auto\" avoids repeating unchanged bootstrap context; use context=\"none\" when only the workspace handle/metadata is needed, or context=\"full\" to force a refresh.";
+    const workspaceManagementInstruction = [
+        "Use open_workspace(action=\"list\") for lightweight Workspace inventory. Use action=\"inspect\" with one known workspaceId for bounded read-only metadata without opening/resuming it. Explicitly open a Workspace before executing or mutating against it, and ask the user before close_workspace cleanup.",
+        capabilityCatalog.some((entry) => entry.name === "workspace.tasks")
+            ? workspaceTaskUsageInstruction
+            : undefined,
+    ].filter(Boolean).join(" ");
+    const cardInstruction = config.skillsEnabled
+        ? `Use this workspaceId in all subsequent tool calls for this project. Follow loaded agentsFiles instructions. Read an availableAgentsFiles path before working under it. When a task matches an available skill, load it with read(path=\"skills://<name>\") before proceeding. When a task matches a capability guide, read its advertised path before proceeding. ${workspaceContextInstruction} ${workspaceManagementInstruction}`
+        : `Use this workspaceId in all subsequent tool calls for this project. Follow loaded agentsFiles instructions. Read an availableAgentsFiles path before working under it. When a task matches a capability guide, read its advertised path before proceeding. ${workspaceContextInstruction} ${workspaceManagementInstruction}`;
+    const instruction = workspaceReused
+        ? effectiveIncludeBootstrapContext
+            ? [
+                `Workspace already exists as ${workspace.id} for this directory.`,
+                "Reuse this workspaceId for subsequent tool calls.",
+                effectiveBootstrapContextComponents.length > 0
+                    ? `Project bootstrap context components included in this response: ${effectiveBootstrapContextComponents.join(", ")}. Components not listed are unchanged and are not repeated.`
+                    : "Only Workspace context deltas are included in this response; unchanged bootstrap context is not repeated.",
+                workspaceContextInstruction,
+                workspaceManagementInstruction,
+            ].join("\n\n")
+            : [
+                `Workspace already open as ${workspace.id}.`,
+                "Reuse this workspaceId for subsequent tool calls. This is the same directory previously opened in this conversation.",
+                "Continue following the project instructions, nested instruction files, skills, capability guides, agent profiles, and diagnostics previously provided for this workspace. They remain active and are not repeated here.",
+                workspaceContextInstruction,
+                workspaceManagementInstruction,
+            ].join("\n\n")
+        : workspace.mode === "worktree"
+            ? `Use this workspaceId for subsequent tool calls. Follow the project instructions, nested instruction files, skills, agent profiles, and diagnostics returned for this isolated worktree. ${workspaceManagementInstruction}`
+            : cardInstruction;
+    const resultContent = [
+        {
+            type: "text",
+            text: [
+                workspaceReused
+                    ? `Workspace already open as ${workspace.id}.`
+                    : workspace.mode === "worktree"
+                        ? `Opened isolated worktree workspace ${workspace.id}.`
+                        : `Opened workspace ${workspace.id}.`,
+                `Root: ${workspace.root}`,
+                `Mode: ${workspace.mode}`,
+                loadedAgentsFiles.length > 0
+                    ? `Loaded project instructions: ${loadedAgentsFiles.map((file) => file.path).join(", ")}`
+                    : undefined,
+                availableAgentsFileOutputs.length > 0
+                    ? `Available nested instructions: ${availableAgentsFileOutputs.map((file) => file.path).join(", ")}`
+                    : undefined,
+                visibleSkills.length > 0
+                    ? `Available skills: ${visibleSkills.map((skill) => skill.name).join(", ")}`
+                    : undefined,
+                capabilityCatalog.length > 0
+                    ? `Optional capabilities: ${capabilityCatalog.map((entry) => entry.name).join(", ")}`
+                    : undefined,
+                visibleCapabilityGuides.length > 0
+                    ? `Capability guides: ${visibleCapabilityGuides.map((guide) => guide.name).join(", ")}`
+                    : undefined,
+                visibleAgentProviders.some((provider) => provider.available)
+                    ? `Available subagent providers: ${visibleAgentProviders.filter((provider) => provider.available).map((provider) => provider.name).join(", ")}`
+                    : undefined,
+                visibleAgentProviders.some((provider) => !provider.available)
+                    ? `Unavailable subagent providers: ${visibleAgentProviders.filter((provider) => !provider.available).map(formatUnavailableSubagentProvider).join(", ")}`
+                    : undefined,
+                visibleAgents.length > 0
+                    ? `Available subagent profiles: ${visibleAgents.map(formatAvailableSubagentProfile).join(", ")}`
+                    : undefined,
+                knownWorktrees.length > 0
+                    ? `Known worktrees: ${knownWorktrees.map((worktree) => `${worktree.path} [${worktree.workspaceId}]${worktree.branch ? ` branch=${worktree.branch}` : ""}${worktree.targetBranch ? ` target=${worktree.targetBranch}` : ""}${worktree.current ? " (current)" : ""}`).join(", ")}`
+                    : undefined,
+                staleWorkspaces.length > 0
+                    ? `This Workspace has been idle for more than 2 days: ${staleWorkspaces.map((stale) => `${stale.workspaceId} last-used=${stale.lastUsedAt}`).join(", ")}. It remains available to resume or explicitly close; do not clean it up automatically.`
+                    : undefined,
+                `ForgeRelay ${capabilityFingerprint.version} capabilities: ${capabilityFingerprint.capabilities.join(", ")}`,
+                instruction,
+                resourceUpdate?.text,
+            ].filter(Boolean).join("\n"),
+        },
+    ];
+    logToolCall(config, {
+        tool: "open_workspace",
+        ...workspaceLogContext(workspace, sessionId),
+        path: workspace.root,
+        success: true,
+        durationMs: Math.round(performance.now() - startedAt),
+    });
+    const workspaceCard = {
+        workspaceId: workspace.id,
+        kind: "workspace",
+        root: workspace.root,
+        path: workspace.root,
+        mode: workspace.mode,
+        workspaceReused,
+        includeBootstrapContext: effectiveIncludeBootstrapContext,
+        sourceRoot: workspace.sourceRoot,
+        worktree: workspace.worktree,
+        worktrees: knownWorktrees,
+        staleWorkspaces,
+        capabilityFingerprint,
+        contextFingerprint,
+        capabilityCatalog,
+        agentsFiles: cardAgentsFiles,
+        availableAgentsFiles: cardAvailableAgentsFiles,
+        skills: cardSkills,
+        agentProviders: cardAgentProviders,
+        agents: cardAgents,
+        instruction: cardInstruction,
+        summary: {
+            mode: workspace.mode,
+            agentsFiles: cardAgentsFiles.length,
+            availableAgentsFiles: cardAvailableAgentsFiles.length,
+            skills: cardSkills.length,
+            capabilities: capabilityCatalog.length,
+            agentProviders: cardAgentProviders.length,
+            agents: cardAgents.length,
+        },
+    };
+    const response = hooks.decorateResult(workspace.id, attachHookReports({
+        content: resultContent,
+        _meta: {
+            tool: "open_workspace",
+            card: effectiveIncludeBootstrapContext
+                ? workspaceCard
+                : compactWorkspacePresentation(workspaceCard),
+        },
+        structuredContent: {
+            action: "open",
+            workspaceId: workspace.id,
+            kind: "workspace",
+            root: workspace.root,
+            mode: workspace.mode,
+            sourceRoot: workspace.sourceRoot,
+            worktree: workspace.worktree,
+            worktrees: knownWorktrees,
+            staleWorkspaces,
+            capabilityFingerprint,
+            contextFingerprint,
+            capabilityCatalog,
+            ...(bootstrapComponents.has("capabilityGuides")
+                ? { capabilityGuides: visibleCapabilityGuides }
+                : {}),
+            ...(bootstrapComponents.has("agentsFiles") ? { agentsFiles: loadedAgentsFiles } : {}),
+            ...(bootstrapComponents.has("availableAgentsFiles")
+                ? { availableAgentsFiles: availableAgentsFileOutputs }
+                : {}),
+            ...(bootstrapComponents.has("skills") ? { skills: visibleSkills } : {}),
+            ...(bootstrapComponents.has("agentProfiles")
+                ? { agentProviders: visibleAgentProviders, agents: visibleAgents }
+                : {}),
+            ...(bootstrapComponents.has("skillDiagnostics")
+                ? { skillDiagnostics: visibleSkillDiagnostics }
+                : {}),
+            instruction,
+        },
+    }, hookReports));
+    rememberWorkspacePanelState(workspace.id, response);
+    return response;
+}