@akira-tl/forgerelay 0.2.5 → 0.3.0

package/dist/server.js

@@ -14,17 +14,18 @@ import { registerAppResource, registerAppTool, RESOURCE_MIME_TYPE, } from "@mode
 import express from "express";
 import * as z from "zod/v4";
 import { applyPatch } from "./apply-patch.js";
+import { buildCapabilityFingerprint } from "./capabilities.js";
 import { deletePath, renamePath } from "./file-mutations.js";
 import { isArtifactDownloadSupportedPlatform, registerArtifactTools, } from "./artifact-tools.js";
 import { loadConfig } from "./config.js";
 import { attachHookReports, HookRunner, runToolWithHooks } from "./hooks.js";
 import { buildServerInstructions, buildShellMutationPolicy, buildToolDescriptions, toolNames, } from "./mcp/server-instructions.js";
 import { createOpenAIIncomingArtifactAdapter, } from "./incoming-artifacts.js";
-import { logEvent, requestIp, requestPath, commandPreview, sessionIdPrefix, workspaceLogLabel, } from "./logger.js";
+import { logEvent, requestIp, requestPath, commandPreview, transportSessionIdPrefix, workspaceLogLabel, } from "./logger.js";
 import { editFileTool, findFilesTool, grepFilesTool, listDirectoryTool, readFileTool, writeFileTool, } from "./pi-tools.js";
 import { SingleUserOAuthProvider } from "./oauth-provider.js";
-import { McpSessionRegistry, } from "./mcp-sessions.js";
-import { ProcessSessionManager, } from "./process-sessions.js";
+import { McpTransportRegistry, } from "./mcp-sessions.js";
+import { ProcessManager, resolveProcessId, } from "./process-sessions.js";
 import { createReviewCheckpointManager } from "./review-checkpoints.js";
 import { openAiConversationScopeId } from "./request-meta.js";
 import { readWorkspaceAppManifestEntry, resolveWorkspaceAppIdentity, WORKSPACE_APP_LEGACY_URI, WORKSPACE_APP_URI_TEMPLATE, } from "./mcp-app-template.js";
@@ -34,11 +35,12 @@ import { createWorkspaceStore } from "./workspace-store.js";
 import { formatAgentsPath, WorkspaceRegistry } from "./workspaces.js";
 import { summarizeLocalAgentProfile } from "./local-agent-profiles.js";
 import { formatLocalAgentProviderAvailabilitySummary, getLocalAgentProviderAvailabilitySnapshot, } from "./local-agent-availability.js";
-// MCP clients can reconnect without closing the previous transport. Bound stale
-// session retention so abandoned MCP servers do not accumulate for the life of the process.
-const MCP_SESSION_IDLE_TIMEOUT_MS = 24 * 60 * 60 * 1_000;
+// Legacy MCP Streamable HTTP clients can reconnect without closing the previous
+// transport. Bound stale transport-session retention so abandoned transports do
+// not accumulate for the life of the process.
+const MCP_TRANSPORT_IDLE_TIMEOUT_MS = 24 * 60 * 60 * 1_000;
 const FORGERELAY_VERSION = readForgeRelayVersion();
-const MCP_SESSION_CLEANUP_INTERVAL_MS = 5 * 60 * 1_000;
+const MCP_TRANSPORT_CLEANUP_INTERVAL_MS = 5 * 60 * 1_000;
 const WRITE_TOOL_ANNOTATIONS = {
     readOnlyHint: false,
     destructiveHint: true,
@@ -81,7 +83,7 @@ function toolWidgetDescriptorMeta(config, kind) {
         },
     };
 }
-function workspaceLogContext(workspace, _sessionId) {
+function workspaceLogContext(workspace, _transportSessionId) {
     return {
         workspaceId: workspace.id,
         workspace: workspaceLogLabel(workspace.root, workspace.id),
@@ -111,6 +113,17 @@ const workspaceSkillOutputSchema = z.object({
     description: z.string(),
     path: z.string(),
 });
+const capabilityFingerprintOutputSchema = z.object({
+    version: z.string(),
+    toolMode: z.enum(["minimal", "full", "codex"]),
+    capabilities: z.array(z.string()),
+});
+const capabilityGuideOutputSchema = z.object({
+    name: z.string(),
+    description: z.string(),
+    whenToRead: z.string(),
+    path: z.string(),
+});
 const workspaceAgentsFileOutputSchema = z.object({
     path: z.string(),
     content: z.string(),
@@ -153,7 +166,7 @@ function sendJsonRpcError(res, status, code, message) {
 }
 function requestLogFields(req, config) {
     return {
-        ip: requestIp(req, config.logging.trustProxy),
+        ip: requestIp(req),
         host: req.header("host"),
         userAgent: req.header("user-agent"),
         origin: req.header("origin"),
@@ -357,7 +370,7 @@ async function readWorkspaceAppResource(config, requestedUri, transportSessionId
             requestedUri,
             currentUri,
             compatibility,
-            sessionIdPrefix: sessionIdPrefix(transportSessionId),
+            transportSessionIdPrefix: transportSessionIdPrefix(transportSessionId),
         });
         return result;
     }
@@ -367,14 +380,14 @@ async function readWorkspaceAppResource(config, requestedUri, transportSessionId
             currentUri,
             compatibility,
             error: error instanceof Error ? error.message : String(error),
-            sessionIdPrefix: sessionIdPrefix(transportSessionId),
+            transportSessionIdPrefix: transportSessionIdPrefix(transportSessionId),
         });
         throw error;
     }
 }
 function processResult(snapshot) {
     const status = snapshot.running
-        ? `Process running with session ID ${snapshot.sessionId}.`
+        ? `Process running with process ID ${snapshot.processId}.`
         : snapshot.signal
             ? `Process exited after signal ${snapshot.signal}.`
             : `Process exited with code ${snapshot.exitCode ?? "unknown"}.`;
@@ -382,8 +395,8 @@ function processResult(snapshot) {
 }
 function completedProcessResult(snapshot) {
     const status = snapshot.signal
-        ? `Background process ${snapshot.sessionId} exited after signal ${snapshot.signal}.`
-        : `Background process ${snapshot.sessionId} exited with code ${snapshot.exitCode ?? "unknown"}.`;
+        ? `Background process ${snapshot.processId} exited after signal ${snapshot.signal}.`
+        : `Background process ${snapshot.processId} exited with code ${snapshot.exitCode ?? "unknown"}.`;
     const command = `Command: ${snapshot.command}`;
     const output = snapshot.output ? `\n${snapshot.output.replace(/\n$/, "")}` : "";
     return `${status}\n${command}${output}`;
@@ -405,10 +418,14 @@ function attachCompletedProcessNotices(processSessions, workspaceId, result) {
     if (!Array.isArray(content))
         return result;
     const structured = result.structuredContent;
-    const currentSessionId = structured?.running === true && typeof structured.sessionId === "number"
-        ? structured.sessionId
+    const currentProcessId = structured?.running === true
+        ? typeof structured.processId === "number"
+            ? structured.processId
+            : typeof structured.sessionId === "number"
+                ? structured.sessionId
+                : undefined
         : undefined;
-    const completed = processSessions.takeCompleted(workspaceId, undefined, currentSessionId);
+    const completed = processSessions.takeCompleted(workspaceId, undefined, currentProcessId);
     if (completed.length === 0)
         return result;
     return {
@@ -421,7 +438,8 @@ function attachCompletedProcessNotices(processSessions, workspaceId, result) {
 }
 function processOutputSchema() {
     return resultOutputSchema({
-        sessionId: z.number().optional(),
+        processId: z.number().int().positive().optional().describe("Canonical process handle for write_stdin."),
+        sessionId: z.number().int().positive().optional().describe("Deprecated alias of processId for compatibility."),
         running: z.boolean(),
         exitCode: z.number().int().optional(),
         signal: z.string().optional(),
@@ -452,6 +470,7 @@ function processToolResponse(tool, workspaceId, snapshot, summary) {
         },
         structuredContent: {
             result,
+            processId: snapshot.processId,
             sessionId: snapshot.sessionId,
             running: snapshot.running,
             exitCode: snapshot.exitCode,
@@ -476,7 +495,7 @@ function registerProcessTools(server, config, workspaces, processSessions, hooks
     if (config.toolMode === "codex") {
         registerAppTool(server, "exec_command", {
             title: "Execute command",
-            description: `Run a command inside an open workspace. Returns its result when it exits during the yield window, otherwise returns a sessionId for write_stdin. Use this for file inspection, tests, builds, package scripts, generators, formatters, and long-running processes. ${buildShellMutationPolicy()} Call open_workspace first and pass workspaceId.`,
+            description: `Run a command inside an open workspace. Returns its result when it exits during the yield window, otherwise returns a processId for write_stdin. Use this for file inspection, tests, builds, package scripts, generators, formatters, and long-running processes. ${buildShellMutationPolicy()} Call open_workspace first and pass workspaceId.`,
             inputSchema: {
                 workspaceId: z.string().describe("Workspace identifier returned by open_workspace."),
                 cmd: z.string().min(1).describe("Shell command to execute."),
@@ -496,7 +515,7 @@ function registerProcessTools(server, config, workspaces, processSessions, hooks
                     .min(0)
                     .max(30_000)
                     .optional()
-                    .describe("Milliseconds to wait before returning a running session. Defaults to 10000."),
+                    .describe("Milliseconds to wait before returning a running process. Defaults to 10000."),
                 maxOutputTokens: z
                     .number()
                     .int()
@@ -537,7 +556,7 @@ function registerProcessTools(server, config, workspaces, processSessions, hooks
                         commandLength: cmd.length,
                         exitCode: snapshot.exitCode,
                         running: snapshot.running,
-                        processSessionId: snapshot.sessionId,
+                        processId: snapshot.processId,
                         success: snapshot.running || snapshot.exitCode === 0,
                         durationMs: Math.round(performance.now() - startedAt),
                     });
@@ -557,7 +576,8 @@ function registerProcessTools(server, config, workspaces, processSessions, hooks
         description: "Poll or write characters to a running process returned by bash or exec_command. Omit chars or pass an empty string to poll. Waiting never kills the process; pass \\u0003 to explicitly send Ctrl-C.",
         inputSchema: {
             workspaceId: z.string().describe("Workspace identifier used to start the process."),
-            sessionId: z.number().describe("Process session identifier returned by exec_command."),
+            processId: z.number().int().positive().optional().describe("Canonical process identifier returned by bash or exec_command."),
+            sessionId: z.number().int().positive().optional().describe("Deprecated alias for processId. Retained for compatibility."),
             chars: z.string().optional().describe("Characters to write. Omit or pass an empty string to poll."),
             columns: z.number().int().min(1).max(1_000).optional().describe("Resize a PTY to this width."),
             rows: z.number().int().min(1).max(1_000).optional().describe("Resize a PTY to this height."),
@@ -579,13 +599,14 @@ function registerProcessTools(server, config, workspaces, processSessions, hooks
         outputSchema: processOutputSchema(),
         ...toolWidgetDescriptorMeta(config, "shell"),
         annotations: SHELL_TOOL_ANNOTATIONS,
-    }, async ({ workspaceId, sessionId, chars, columns, rows, yieldTimeMs, maxOutputTokens }, extra) => {
+    }, async ({ workspaceId, processId, sessionId, chars, columns, rows, yieldTimeMs, maxOutputTokens }, extra) => {
         const workspace = workspaces.getWorkspace(workspaceId);
+        const resolvedProcessId = resolveProcessId(processId, sessionId);
         return runToolWithHooks(hooks, {
             tool: "write_stdin",
             invocation: workspaceHookInvocation(workspace),
             payload: {
-                sessionId,
+                processId: resolvedProcessId,
                 charactersWritten: chars?.length ?? 0,
                 columns,
                 rows,
@@ -594,7 +615,7 @@ function registerProcessTools(server, config, workspaces, processSessions, hooks
                 const startedAt = performance.now();
                 const snapshot = await processSessions.write({
                     workspaceId,
-                    sessionId,
+                    processId: resolvedProcessId,
                     chars,
                     columns,
                     rows,
@@ -606,12 +627,12 @@ function registerProcessTools(server, config, workspaces, processSessions, hooks
                     ...workspaceLogContext(workspace, extra.sessionId),
                     exitCode: snapshot.exitCode,
                     running: snapshot.running,
-                    processSessionId: snapshot.sessionId,
+                    processId: snapshot.processId,
                     success: snapshot.running || snapshot.exitCode === 0,
                     durationMs: Math.round(performance.now() - startedAt),
                 });
                 return processToolResponse("write_stdin", workspaceId, snapshot, {
-                    sessionId,
+                    processId: resolvedProcessId,
                     charactersWritten: chars?.length ?? 0,
                     running: snapshot.running,
                     exitCode: snapshot.exitCode,
@@ -630,9 +651,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
         version: FORGERELAY_VERSION,
         description: "Secure local coding workspace for MCP clients. Provides workspace-scoped file, search, edit, write, and shell tools.",
     }, {
-        instructions: buildServerInstructions(config, {
-            artifactDownloadSupported: isArtifactDownloadSupportedPlatform(),
-        }),
+        instructions: buildServerInstructions(config),
     });
     const currentWorkspaceAppUri = currentWorkspaceAppIdentity().uri;
     const workspaceAppResourceMetadata = {
@@ -651,7 +670,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
     }, async (uri, _variables, extra) => readWorkspaceAppResource(config, uri.toString(), extra.sessionId));
     registerAppTool(server, "open_workspace", {
         title: "Open workspace",
-        description: "Open or resume a local coding workspace. A conversation keeps a stable workspaceId for a project, while different conversations normally receive different logical workspaceIds that may point at the same physical checkout or worktree. Pass workspaceId to explicitly resume an existing logical workspace in this conversation. Default to checkout mode and only use mode=\"worktree\" when the user explicitly asks for isolated or parallel Git work. Workspaces idle for more than two days are reported for user-directed cleanup or resumption.",
+        description: "Open or resume a local coding workspace. Reuse the returned workspaceId for later calls. Default to checkout; use mode=\"worktree\" only when the user explicitly requests isolated or parallel Git work. Every call returns a capability fingerprint; bootstrap calls also expose project context, skills, and capability guides when needed.",
         inputSchema: {
             path: z
                 .string()
@@ -715,6 +734,8 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                 targetBranch: z.string().optional(),
                 managed: z.boolean(),
             })),
+            capabilityFingerprint: capabilityFingerprintOutputSchema,
+            capabilityGuides: z.array(capabilityGuideOutputSchema).optional(),
             agentsFiles: z.array(workspaceAgentsFileOutputSchema).optional(),
             availableAgentsFiles: z.array(workspaceAvailableAgentsFileOutputSchema).optional(),
             skills: z.array(workspaceSkillOutputSchema).optional(),
@@ -738,6 +759,9 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
         });
         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,
@@ -751,6 +775,12 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
             description: skill.description,
             path: formatPathForPrompt(skill.filePath),
         }));
+        const capabilityGuides = workspace.capabilityGuides.map((guide) => ({
+            name: guide.name,
+            description: guide.description,
+            whenToRead: guide.whenToRead,
+            path: formatPathForPrompt(guide.filePath),
+        }));
         const cardAgentProviders = config.subagents ? localAgentProviders : [];
         const cardAgents = workspace.agentProfiles.map((profile) => {
             const summary = summarizeLocalAgentProfile(profile);
@@ -769,13 +799,14 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
             path: formatAgentsPath(file.path, workspace.root),
         }));
         const visibleSkills = includeBootstrapContext ? cardSkills : [];
+        const visibleCapabilityGuides = includeBootstrapContext ? capabilityGuides : [];
         const visibleAgentProviders = includeBootstrapContext ? cardAgentProviders : [];
         const visibleAgents = includeBootstrapContext ? cardAgents : [];
         const loadedAgentsFiles = includeBootstrapContext ? cardAgentsFiles : [];
         const availableAgentsFileOutputs = includeBootstrapContext ? cardAvailableAgentsFiles : [];
         const cardInstruction = config.skillsEnabled
-            ? "Use this workspaceId in all subsequent tool calls for this project. Default to the user's checkout; only create a worktree when the user explicitly requests isolated or parallel work. Managed worktrees are branch-backed. When a managed worktree task is complete and verified, close it with close_worktree so ForgeRelay can commit, fast-forward the target branch when safe, and clean up the worktree. Follow loaded agentsFiles instructions. Before working under a path listed in availableAgentsFiles, read that instruction file. When a task matches an available skill in skills, read its path before proceeding."
-            : "Use this workspaceId in all subsequent tool calls for this project. Default to the user's checkout; only create a worktree when the user explicitly requests isolated or parallel work. Managed worktrees are branch-backed. When a managed worktree task is complete and verified, close it with close_worktree so ForgeRelay can commit, fast-forward the target branch when safe, and clean up the worktree. Follow loaded agentsFiles instructions. Before working under a path listed in availableAgentsFiles, read that instruction file.";
+            ? "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 or capability guide, read its advertised path before proceeding."
+            : "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.";
         const instruction = workspaceReused
             ? includeBootstrapContext
                 ? [
@@ -786,7 +817,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                 : [
                     `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, agent profiles, and diagnostics previously provided for this workspace. They remain active and are not repeated here.",
+                    "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.",
                 ].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."
@@ -811,6 +842,9 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                     visibleSkills.length > 0
                         ? `Available skills: ${visibleSkills.map((skill) => skill.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,
@@ -826,6 +860,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                     staleWorkspaces.length > 0
                         ? `Idle logical workspaces for this same physical workspace (>2 days): ${staleWorkspaces.map((stale) => `${stale.workspaceId} last-used=${stale.lastUsedAt}`).join(", ")}. Tell the user these are available to resume or explicitly close; do not clean them up automatically.`
                         : undefined,
+                    `ForgeRelay ${capabilityFingerprint.version} capabilities: ${capabilityFingerprint.capabilities.join(", ")}`,
                     instruction,
                 ].filter(Boolean).join("\n"),
             },
@@ -852,6 +887,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                     worktree: workspace.worktree,
                     worktrees: knownWorktrees,
                     staleWorkspaces,
+                    capabilityFingerprint,
                     agentsFiles: cardAgentsFiles,
                     availableAgentsFiles: cardAvailableAgentsFiles,
                     skills: cardSkills,
@@ -876,8 +912,10 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                 worktree: workspace.worktree,
                 worktrees: knownWorktrees,
                 staleWorkspaces,
+                capabilityFingerprint,
                 ...(includeBootstrapContext
                     ? {
+                        capabilityGuides: visibleCapabilityGuides,
                         agentsFiles: loadedAgentsFiles,
                         availableAgentsFiles: availableAgentsFileOutputs,
                         skills: visibleSkills,
@@ -892,7 +930,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
     });
     registerAppTool(server, toolNames.closeWorkspace, {
         title: "Close logical workspace",
-        description: "Release one logical ForgeRelay workspaceId after the user explicitly chooses to clean it up. This never deletes checkout files. A worktree handle can be released only when another logical handle still anchors the same physical worktree; use close_worktree to finalize and remove the last managed worktree. Running or unconsumed background processes prevent closure.",
+        description: "Release one logical workspaceId after the user chooses cleanup. This does not delete checkout files. Use close_worktree to finalize and remove a managed worktree. Running or unconsumed processes prevent closure.",
         inputSchema: {
             workspaceId: z.string().describe("Logical workspace ID to release."),
         },
@@ -920,7 +958,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
     });
     registerAppTool(server, toolNames.closeWorktree, {
         title: "Close worktree",
-        description: "Finish a managed ForgeRelay worktree after its task has been completed and verified. ForgeRelay commits any remaining worktree changes, fast-forwards the original target branch only when the source checkout is clean and the histories have not diverged, then removes the worktree and its forgerelay/* branch. If safe fast-forward is not possible, the source checkout is left out of a merge-conflict state and the worktree is preserved.",
+        description: "Finalize a managed worktree after its task is complete and verified. ForgeRelay may commit remaining changes, integrate the target branch when safe, and clean up the managed worktree. Read the managed-worktrees capability guide for advanced close, safety, and failure semantics.",
         inputSchema: {
             workspaceId: z
                 .string()
@@ -1001,8 +1039,8 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
             path: z
                 .string()
                 .describe(config.skillsEnabled
-                ? "File path to read, relative to the workspace root or absolute inside the OS temp directory. May also be an advertised skill path from open_workspace skills, including a ~/... home-relative path."
-                : "File path to read, relative to the workspace root or absolute inside the OS temp directory."),
+                ? "File path to read, relative to the workspace root or absolute inside the OS temp directory. May also be an advertised skill or capability-guide path from open_workspace, including a ~/... home-relative path."
+                : "File path to read, relative to the workspace root or absolute inside the OS temp directory. May also be an advertised capability-guide path from open_workspace."),
             offset: z
                 .number()
                 .int()
@@ -1747,7 +1785,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                         commandLength: command.length,
                         exitCode: snapshot.exitCode,
                         running: snapshot.running,
-                        processSessionId: snapshot.sessionId,
+                        processId: snapshot.processId,
                         success: snapshot.running || (snapshot.exitCode === 0 && !snapshot.signal),
                         durationMs: Math.round(performance.now() - startedAt),
                     });
@@ -1786,7 +1824,7 @@ export function createServer(config = loadConfig(), options = {}) {
         host: config.host,
         ...(allowedHosts ? { allowedHosts } : {}),
     });
-    const transports = new McpSessionRegistry();
+    const transports = new McpTransportRegistry();
     const mcpUrl = new URL("/mcp", config.publicBaseUrl);
     const resourceServerUrl = resourceUrlFromServerUrl(mcpUrl);
     const oauthProvider = new SingleUserOAuthProvider(config.oauth, mcpUrl, config.stateDir);
@@ -1798,17 +1836,17 @@ export function createServer(config = loadConfig(), options = {}) {
     const workspaceStore = createWorkspaceStore(config.stateDir);
     const workspaces = new WorkspaceRegistry(config, workspaceStore);
     const reviewCheckpoints = createReviewCheckpointManager();
-    const processSessions = new ProcessSessionManager();
+    const processSessions = new ProcessManager();
     const localAgentProviders = config.subagents
         ? getLocalAgentProviderAvailabilitySnapshot()
         : [];
-    const logSessionCloseResults = (reason, results) => {
+    const logTransportCloseResults = (reason, results) => {
         let closedCount = 0;
         for (const result of results) {
             if (result.error) {
-                logEvent(config.logging, "warn", "mcp_session_close_failed", {
+                logEvent(config.logging, "warn", "mcp_transport_session_close_failed", {
                     reason,
-                    sessionIdPrefix: sessionIdPrefix(result.sessionId),
+                    transportSessionIdPrefix: transportSessionIdPrefix(result.transportSessionId),
                     error: result.error instanceof Error
                         ? result.error.message
                         : String(result.error),
@@ -1817,27 +1855,27 @@ export function createServer(config = loadConfig(), options = {}) {
             }
             closedCount += 1;
             if (reason === "idle_timeout") {
-                logEvent(config.logging, "debug", "mcp_session_closed", {
+                logEvent(config.logging, "debug", "mcp_transport_session_closed", {
                     reason,
-                    sessionIdPrefix: sessionIdPrefix(result.sessionId),
+                    transportSessionIdPrefix: transportSessionIdPrefix(result.transportSessionId),
                 });
             }
         }
         if (reason === "server_shutdown" && closedCount > 0) {
-            logEvent(config.logging, "debug", "mcp_sessions_closed", {
+            logEvent(config.logging, "debug", "mcp_transport_sessions_closed", {
                 reason,
                 count: closedCount,
             });
         }
     };
-    const sessionCleanupTimer = setInterval(() => {
+    const transportCleanupTimer = setInterval(() => {
         void transports
-            .closeIdle(MCP_SESSION_IDLE_TIMEOUT_MS)
-            .then((results) => logSessionCloseResults("idle_timeout", results));
-    }, MCP_SESSION_CLEANUP_INTERVAL_MS);
-    sessionCleanupTimer.unref();
+            .closeIdle(MCP_TRANSPORT_IDLE_TIMEOUT_MS)
+            .then((results) => logTransportCloseResults("idle_timeout", results));
+    }, MCP_TRANSPORT_CLEANUP_INTERVAL_MS);
+    transportCleanupTimer.unref();
     if (config.logging.trustProxy) {
-        app.set("trust proxy", true);
+        app.set("trust proxy", 1);
     }
     app.use((req, res, next) => {
         const requestId = randomUUID();
@@ -1883,7 +1921,7 @@ export function createServer(config = loadConfig(), options = {}) {
     });
     app.all("/mcp", async (req, res) => {
         const requestId = res.locals.requestId;
-        const sessionId = req.header("mcp-session-id");
+        const transportSessionId = req.header("mcp-session-id");
         const initializeRequest = req.method === "POST" && isInitializeRequest(req.body);
         await new Promise((resolve, reject) => {
             bearerAuth(req, res, (error) => {
@@ -1909,39 +1947,39 @@ export function createServer(config = loadConfig(), options = {}) {
         logEvent(config.logging, "debug", "mcp_request", {
             requestId,
             httpMethod: req.method,
-            sessionIdPresent: Boolean(sessionId),
-            sessionIdPrefix: sessionIdPrefix(sessionId),
+            transportSessionIdPresent: Boolean(transportSessionId),
+            transportSessionIdPrefix: transportSessionIdPrefix(transportSessionId),
             isInitialize: initializeRequest,
             ...mcpRequestDebugFields(req.body),
         });
         try {
             let transport;
-            if (sessionId) {
-                transport = transports.get(sessionId);
+            if (transportSessionId) {
+                transport = transports.get(transportSessionId);
                 if (!transport) {
-                    sendJsonRpcError(res, 404, -32000, "Unknown MCP session");
+                    sendJsonRpcError(res, 404, -32000, "Unknown MCP transport session");
                     return;
                 }
             }
             else if (initializeRequest) {
                 transport = new StreamableHTTPServerTransport({
                     sessionIdGenerator: () => randomUUID(),
-                    onsessioninitialized: (newSessionId) => {
+                    onsessioninitialized: (newTransportSessionId) => {
                         if (transport)
-                            transports.register(newSessionId, transport);
-                        logEvent(config.logging, "debug", "mcp_session_created", {
+                            transports.register(newTransportSessionId, transport);
+                        logEvent(config.logging, "debug", "mcp_transport_session_created", {
                             requestId,
-                            sessionIdPrefix: sessionIdPrefix(newSessionId),
+                            transportSessionIdPrefix: transportSessionIdPrefix(newTransportSessionId),
                             ...requestLogFields(req, config),
                         });
                     },
                 });
                 transport.onclose = () => {
-                    const closedSessionId = transport?.sessionId;
-                    if (closedSessionId && transports.remove(closedSessionId)) {
-                        logEvent(config.logging, "debug", "mcp_session_closed", {
+                    const closedTransportSessionId = transport?.sessionId;
+                    if (closedTransportSessionId && transports.remove(closedTransportSessionId)) {
+                        logEvent(config.logging, "debug", "mcp_transport_session_closed", {
                             reason: "transport_close",
-                            sessionIdPrefix: sessionIdPrefix(closedSessionId),
+                            transportSessionIdPrefix: transportSessionIdPrefix(closedTransportSessionId),
                         });
                     }
                 };
@@ -1949,7 +1987,7 @@ export function createServer(config = loadConfig(), options = {}) {
                 await server.connect(transport);
             }
             else {
-                sendJsonRpcError(res, 400, -32000, "No valid MCP session");
+                sendJsonRpcError(res, 400, -32000, "No valid MCP transport session");
                 return;
             }
             await transport.handleRequest(req, res, req.body);
@@ -1971,9 +2009,9 @@ export function createServer(config = loadConfig(), options = {}) {
         localAgentProviders,
         close: () => {
             closePromise ??= (async () => {
-                clearInterval(sessionCleanupTimer);
+                clearInterval(transportCleanupTimer);
                 const results = await transports.closeAll();
-                logSessionCloseResults("server_shutdown", results);
+                logTransportCloseResults("server_shutdown", results);
                 processSessions.shutdown();
                 oauthProvider.close();
                 workspaceStore.close?.();

package/dist/skills.js

@@ -1,27 +1,16 @@
 import { existsSync } from "node:fs";
 import { homedir } from "node:os";
 import { join, resolve, sep } from "node:path";
-import { fileURLToPath } from "node:url";
+import { markAdvertisedFileSourceActivated, resolveAdvertisedFileReadPath, } from "./advertised-files.js";
 import { loadSkills, } from "@earendil-works/pi-coding-agent";
-import { expandHomePath, isPathInsideRoot } from "./roots.js";
+import { expandHomePath } from "./roots.js";
 const SUBAGENT_DELEGATION_NAME = "subagent-delegation";
-const SUBAGENT_DELEGATION_SKILL = join(SUBAGENT_DELEGATION_NAME, "SKILL.md");
-function bundledSkillsDir() {
-    return fileURLToPath(new URL("../skills", import.meta.url));
-}
-function hasSubagentDelegationSkill(skillDir) {
-    return existsSync(join(skillDir, SUBAGENT_DELEGATION_SKILL));
-}
 export function effectiveSkillPaths(config, cwd) {
-    const bundledSkills = bundledSkillsDir();
     const defaultPathCandidates = [
         join(homedir(), ".agents", "skills"),
         resolve(cwd, ".agents", "skills"),
         config.devspaceSkillsDir,
         join(config.agentDir, "skills"),
-        config.subagents && !hasSubagentDelegationSkill(config.devspaceSkillsDir)
-            ? bundledSkills
-            : undefined,
     ];
     const defaultPaths = defaultPathCandidates.filter((path) => path !== undefined && existsSync(path));
     const seen = new Set();
@@ -57,25 +46,17 @@ export function loadWorkspaceSkills(config, cwd) {
     };
 }
 export function resolveSkillReadPath(skills, activatedSkillDirs, inputPath) {
-    const absolutePath = resolve(expandHomePath(inputPath));
-    for (const skill of skills) {
-        const skillFilePath = resolve(skill.filePath);
-        if (absolutePath === skillFilePath) {
-            return { absolutePath, skill, isSkillFile: true };
-        }
-    }
-    for (const skill of skills) {
-        const baseDir = resolve(skill.baseDir);
-        if (!activatedSkillDirs.has(baseDir))
-            continue;
-        if (!isPathInsideRoot(absolutePath, baseDir))
-            continue;
-        return { absolutePath, skill, isSkillFile: false };
-    }
-    return undefined;
+    const resolution = resolveAdvertisedFileReadPath(skills, activatedSkillDirs, inputPath);
+    if (!resolution)
+        return undefined;
+    return {
+        absolutePath: resolution.absolutePath,
+        skill: resolution.source,
+        isSkillFile: resolution.isEntryFile,
+    };
 }
 export function markSkillActivated(activatedSkillDirs, skill) {
-    activatedSkillDirs.add(resolve(skill.baseDir));
+    markAdvertisedFileSourceActivated(activatedSkillDirs, skill);
 }
 export function formatPathForPrompt(path) {
     const home = resolve(homedir());

package/dist/workspaces.js

@@ -2,6 +2,7 @@ import { randomBytes } from "node:crypto";
 import { mkdir, opendir, readFile, realpath, stat } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { basename, dirname, join, relative, resolve, sep } from "node:path";
+import { loadCapabilityGuides, markCapabilityGuideActivated, resolveCapabilityGuideReadPath, } from "./capabilities.js";
 import { HookRunner } from "./hooks.js";
 import { closeManagedWorktree, createManagedWorktree, resolveManagedWorktreeBase, } from "./git-worktrees.js";
 import { AccessDeniedError, assertAllowedPath, isPathInsideRoot, resolveAllowedPath, } from "./roots.js";
@@ -548,8 +549,10 @@ export class WorkspaceRegistry {
                 }
                 : undefined,
             ...this.loadSkillsForWorkspace(root),
+            capabilityGuides: loadCapabilityGuides(this.config),
             agentProfiles: [],
             activatedSkillDirs: new Set(),
+            activatedCapabilityGuideDirs: new Set(),
         };
         if (touch)
             this.store?.touchSession(session.id);
@@ -582,6 +585,14 @@ export class WorkspaceRegistry {
                     skillRead,
                 };
             }
+            const capabilityGuideRead = resolveCapabilityGuideReadPath(workspace.capabilityGuides, workspace.activatedCapabilityGuideDirs, inputPath);
+            if (capabilityGuideRead) {
+                return {
+                    absolutePath: capabilityGuideRead.absolutePath,
+                    readRoots: [workspace.root, capabilityGuideRead.guide.baseDir],
+                    capabilityGuideRead,
+                };
+            }
             try {
                 return {
                     absolutePath: resolveAllowedPath(inputPath, workspace.root, [tmpdir()]),
@@ -597,6 +608,9 @@ export class WorkspaceRegistry {
         if (readPath.skillRead?.isSkillFile) {
             markSkillActivated(workspace.activatedSkillDirs, readPath.skillRead.skill);
         }
+        if (readPath.capabilityGuideRead?.isGuideFile) {
+            markCapabilityGuideActivated(workspace.activatedCapabilityGuideDirs, readPath.capabilityGuideRead.guide);
+        }
     }
     resolveWorkingDirectory(workspace, workingDirectory) {
         const directory = workingDirectory ? this.resolvePath(workspace, workingDirectory) : workspace.root;
@@ -631,8 +645,10 @@ export class WorkspaceRegistry {
             sourceRoot: input.sourceRoot,
             worktree: input.worktree,
             ...this.loadSkillsForWorkspace(input.root),
+            capabilityGuides: loadCapabilityGuides(this.config),
             agentProfiles: await loadLocalAgentProfiles(this.config, input.root),
             activatedSkillDirs: new Set(),
+            activatedCapabilityGuideDirs: new Set(),
         };
         this.store?.createSession({
             id: workspace.id,