@lelouchhe/webagent 0.9.0 → 0.10.0

package/lib/event-handler.js

@@ -4,44 +4,44 @@ import { isAutopilotMode } from "./mode-bucket.js";
 const ailog = log.scope("attachment-interceptor");
 const plog = log.scope("push");
 const clog = log.scope("cancel");
-function handleConnected(event, sessions, config) {
+function handleConnected(event, tasks, config) {
     event.cancelTimeout = config.cancelTimeout;
     event.recentPathsLimit = config.recentPathsLimit;
     // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- defensive check
     if (event.agent)
-        sessions.agentInfo = event.agent;
+        tasks.agentInfo = event.agent;
 }
-function handleConfigLikeEvent(event, sessions) {
-    sessions.recordConfigOptions(event.sessionId, event.configOptions);
+function handleConfigLikeEvent(event, tasks) {
+    tasks.recordConfigOptions(event.taskId, event.configOptions);
 }
-function handleMessageChunk(event, sessions) {
-    sessions.flushThinkingBuffer(event.sessionId);
-    sessions.appendAssistant(event.sessionId, event.text);
-    sessions.state.patch(event.sessionId, {
+function handleMessageChunk(event, tasks) {
+    tasks.flushThinkingBuffer(event.taskId);
+    tasks.appendAssistant(event.taskId, event.text);
+    tasks.state.patch(event.taskId, {
         runtime: { streaming: { assistant: true, thinking: false } },
     });
 }
-function handleThoughtChunk(event, sessions) {
-    sessions.flushAssistantBuffer(event.sessionId);
-    sessions.appendThinking(event.sessionId, event.text);
-    sessions.state.patch(event.sessionId, {
+function handleThoughtChunk(event, tasks) {
+    tasks.flushAssistantBuffer(event.taskId);
+    tasks.appendThinking(event.taskId, event.text);
+    tasks.state.patch(event.taskId, {
         runtime: { streaming: { assistant: false, thinking: true } },
     });
 }
-function handleToolCall(event, sessions, store) {
-    sessions.flushBuffers(event.sessionId);
-    sessions.state.patch(event.sessionId, {
+function handleToolCall(event, tasks, store) {
+    tasks.flushBuffers(event.taskId);
+    tasks.state.patch(event.taskId, {
         runtime: { streaming: { assistant: false, thinking: false } },
     });
-    store.saveEvent(event.sessionId, event.type, {
+    store.saveEvent(event.taskId, event.type, {
         id: event.id,
         title: event.title,
         kind: event.kind,
         rawInput: event.rawInput,
     }, { from_ref: "agent" });
 }
-function handleUsageUpdate(event, sessions) {
-    sessions.state.patch(event.sessionId, {
+function handleUsageUpdate(event, tasks) {
+    tasks.state.patch(event.taskId, {
         runtime: {
             contextUsage: {
                 used: event.used,
@@ -51,9 +51,9 @@ function handleUsageUpdate(event, sessions) {
         },
     });
 }
-function handlePlan(event, sessions, store) {
-    sessions.flushBuffers(event.sessionId);
-    sessions.state.patch(event.sessionId, {
+function handlePlan(event, tasks, store) {
+    tasks.flushBuffers(event.taskId);
+    tasks.state.patch(event.taskId, {
         runtime: {
             streaming: { assistant: false, thinking: false },
             plan: event.entries.length > 0 &&
@@ -62,14 +62,14 @@ function handlePlan(event, sessions, store) {
                 : null,
         },
     });
-    store.saveEvent(event.sessionId, event.type, { entries: event.entries }, { from_ref: "agent" });
+    store.saveEvent(event.taskId, event.type, { entries: event.entries }, { from_ref: "agent" });
 }
-function performAutoApprove(event, opt, sessions, store, bridge, sseManager, broadcastRequest) {
+function performAutoApprove(event, opt, tasks, store, bridge, sseManager, broadcastRequest) {
     bridge.resolvePermission(event.requestId, opt.optionId);
-    sessions.pendingPermissions.delete(event.requestId);
-    sessions.syncPendingPermissions(event.sessionId);
+    tasks.pendingPermissions.delete(event.requestId);
+    tasks.syncPendingPermissions(event.taskId);
     const optionName = opt.label ?? opt.optionId;
-    store.saveEvent(event.sessionId, "permission_response", {
+    store.saveEvent(event.taskId, "permission_response", {
         requestId: event.requestId,
         optionName,
         denied: false,
@@ -78,23 +78,23 @@ function performAutoApprove(event, opt, sessions, store, bridge, sseManager, bro
         sseManager.broadcast(event);
     sseManager.broadcast({
         type: "permission_response",
-        sessionId: event.sessionId,
+        taskId: event.taskId,
         requestId: event.requestId,
         optionName,
         denied: false,
     });
 }
-function maybeAutoApprovePermission(event, sessions, store, bridge, sseManager) {
-    const mode = store.getSession(event.sessionId)?.mode ?? "";
+function maybeAutoApprovePermission(event, tasks, store, bridge, sseManager) {
+    const mode = store.getTask(event.taskId)?.mode ?? "";
     if (!isAutopilotMode(mode))
         return false;
     const opt = event.options.find((o) => o.kind === "allow_once");
     if (!opt)
         return false;
-    performAutoApprove(event, opt, sessions, store, bridge, sseManager, true);
+    performAutoApprove(event, opt, tasks, store, bridge, sseManager, true);
     return true;
 }
-function maybeAutoApproveAttachmentRead(event, sessions, store, bridge, sseManager, config) {
+function maybeAutoApproveAttachmentRead(event, tasks, store, bridge, sseManager, config) {
     // Plan §1.4 — async attachment-read auto-approve runs *after* the
     // permission_request has already been broadcast (so the UI shows it
     // briefly), then if the request matches we follow up with a
@@ -106,7 +106,7 @@ function maybeAutoApproveAttachmentRead(event, sessions, store, bridge, sseManag
     if (!opt)
         return;
     void shouldAutoApproveAttachmentRead({
-        sessionId: event.sessionId,
+        taskId: event.taskId,
         toolKind: event.toolKind,
         toolName: event.toolName,
         locations: event.locations,
@@ -121,119 +121,172 @@ function maybeAutoApproveAttachmentRead(event, sessions, store, bridge, sseManag
             return;
         // Race guard: the user (or another client) may have already
         // resolved the permission while we were realpath-ing.
-        if (!sessions.pendingPermissions.has(event.requestId))
+        if (!tasks.pendingPermissions.has(event.requestId))
             return;
-        performAutoApprove(event, opt, sessions, store, bridge, sseManager, false);
+        performAutoApprove(event, opt, tasks, store, bridge, sseManager, false);
     }, (err) => {
         ailog.warn("unexpected error", { error: err.message });
     });
 }
-function handlePermissionRequest(event, sessions, store, bridge, sseManager, config) {
-    sessions.flushBuffers(event.sessionId);
-    sessions.state.patch(event.sessionId, {
+function handlePermissionRequest(event, tasks, store, bridge, sseManager, config) {
+    tasks.flushBuffers(event.taskId);
+    tasks.state.patch(event.taskId, {
         runtime: { streaming: { assistant: false, thinking: false } },
     });
-    store.saveEvent(event.sessionId, event.type, {
+    store.saveEvent(event.taskId, event.type, {
         requestId: event.requestId,
         title: event.title,
         options: event.options,
     }, { from_ref: "agent" });
-    sessions.pendingPermissions.set(event.requestId, {
+    tasks.pendingPermissions.set(event.requestId, {
         requestId: event.requestId,
-        sessionId: event.sessionId,
+        taskId: event.taskId,
         title: event.title,
         options: event.options.map((o) => ({
             optionId: o.optionId,
             label: o.label ?? o.name ?? o.optionId,
         })),
     });
-    sessions.syncPendingPermissions(event.sessionId);
-    const autopiloted = maybeAutoApprovePermission(event, sessions, store, bridge, sseManager);
+    tasks.syncPendingPermissions(event.taskId);
+    const autopiloted = maybeAutoApprovePermission(event, tasks, store, bridge, sseManager);
     if (autopiloted)
         return true;
     // Async attachment-read auto-approve runs after the request broadcasts.
-    maybeAutoApproveAttachmentRead(event, sessions, store, bridge, sseManager, config);
+    maybeAutoApproveAttachmentRead(event, tasks, store, bridge, sseManager, config);
     return false;
 }
-function handlePromptDone(event, sessions, store) {
-    const cancelStatus = sessions.state.getState(event.sessionId).runtime.busy?.cancelStatus ?? null;
+function handlePromptDone(event, tasks, store, bridge) {
+    const cancelStatus = tasks.state.getState(event.taskId).runtime.busy?.cancelStatus ?? null;
     if (cancelStatus !== null) {
         clog.info("agent completed after request", {
-            sessionId: event.sessionId.slice(0, 8),
+            taskId: event.taskId.slice(0, 8),
             requestedStatus: cancelStatus,
             stopReason: event.stopReason,
         });
     }
     // The tail this turn buffered must always land, even when the turn has
     // already been superseded — it is the only copy of that text.
-    const isCurrent = sessions.isCurrentPrompt(event.sessionId, event.promptId);
+    const isCurrent = tasks.isCurrentPrompt(event.taskId, event.promptId);
+    const taskBeforeIdle = isCurrent ? store.getTask(event.taskId) : null;
+    // Only Agent-created delegated Tasks owe a lifecycle handoff. User-created
+    // Tasks may receive the same collaboration content but remain interactive.
+    const needsHandoffReminder = isCurrent &&
+        taskBeforeIdle?.source === "agent" &&
+        event.stopReason !== "cancelled" &&
+        taskBeforeIdle.workflow_status === "running";
     if (isCurrent) {
-        sessions.activePrompts.delete(event.sessionId);
-        sessions.syncBusy(event.sessionId);
+        tasks.activePrompts.delete(event.taskId);
+        tasks.syncBusy(event.taskId);
     }
     else {
         clog.info("completion from a superseded turn", {
-            sessionId: event.sessionId.slice(0, 8),
+            taskId: event.taskId.slice(0, 8),
             promptId: event.promptId,
             stopReason: event.stopReason,
         });
     }
-    sessions.flushBuffers(event.sessionId);
-    sessions.state.patch(event.sessionId, {
+    tasks.flushBuffers(event.taskId);
+    tasks.state.patch(event.taskId, {
         runtime: { streaming: { assistant: false, thinking: false } },
     });
-    store.saveEvent(event.sessionId, event.type, {
+    store.saveEvent(event.taskId, event.type, {
         stopReason: event.stopReason,
         // Replay must be able to make the same judgement the live path does.
         ...(event.promptId ? { promptId: event.promptId } : {}),
     }, { from_ref: "agent" });
+    if (isCurrent) {
+        if (taskBeforeIdle?.workflow_status === "running") {
+            store.updateTaskWorkflowStatus(event.taskId, "idle");
+        }
+        // Defer past the synchronous prompt_done broadcast below: a busy patch
+        // minted by the drain must never race ahead of the finished turn's own
+        // terminator, or clients drop the terminator as a superseded turn and
+        // strand its pending tool/permission UI.
+        void Promise.resolve()
+            .then(async () => {
+            const drained = await tasks.drainCollaborationDeliveries(bridge, event.taskId);
+            if (!drained && needsHandoffReminder) {
+                await tasks.promptHandoffReminder(bridge, event.taskId);
+            }
+        })
+            .catch((error) => {
+            clog.warn("handoff recovery failed", {
+                taskId: event.taskId.slice(0, 8),
+                error,
+            });
+        });
+    }
 }
-function handleError(event, sessions, store) {
-    if (event.sessionId) {
+function handleError(event, tasks, store, bridge) {
+    if (event.taskId) {
+        const taskId = event.taskId;
         // Same attribution as a completion: a superseded turn failing late must
         // not end the turn that replaced it. The buffered tail still flushes.
-        if (sessions.isCurrentPrompt(event.sessionId, event.promptId)) {
-            sessions.activePrompts.delete(event.sessionId);
-            sessions.syncBusy(event.sessionId);
+        const isCurrent = tasks.isCurrentPrompt(event.taskId, event.promptId);
+        const taskBeforeIdle = isCurrent ? store.getTask(event.taskId) : null;
+        const needsHandoffReminder = isCurrent &&
+            taskBeforeIdle?.source === "agent" &&
+            taskBeforeIdle.workflow_status === "running";
+        if (isCurrent) {
+            tasks.activePrompts.delete(event.taskId);
+            tasks.syncBusy(event.taskId);
         }
         else {
             clog.info("failure from a superseded turn", {
-                sessionId: event.sessionId.slice(0, 8),
+                taskId: event.taskId.slice(0, 8),
                 promptId: event.promptId,
                 message: event.message,
             });
         }
-        sessions.flushBuffers(event.sessionId);
-        sessions.state.patch(event.sessionId, {
+        tasks.flushBuffers(event.taskId);
+        tasks.state.patch(event.taskId, {
             runtime: { streaming: { assistant: false, thinking: false } },
         });
-        store.saveEvent(event.sessionId, event.type, {
+        store.saveEvent(event.taskId, event.type, {
             message: event.message,
             ...(event.promptId ? { promptId: event.promptId } : {}),
         }, { from_ref: "agent" });
+        if (isCurrent) {
+            if (taskBeforeIdle?.workflow_status === "running") {
+                store.updateTaskWorkflowStatus(event.taskId, "idle");
+            }
+            void Promise.resolve()
+                .then(async () => {
+                const drained = await tasks.drainCollaborationDeliveries(bridge, taskId);
+                if (!drained && needsHandoffReminder) {
+                    await tasks.promptHandoffReminder(bridge, taskId);
+                }
+            })
+                .catch((recoveryError) => {
+                clog.warn("handoff recovery failed after agent error", {
+                    taskId: taskId.slice(0, 8),
+                    error: recoveryError,
+                });
+            });
+        }
     }
 }
-function dispatchAgentEvent(event, sessions, store, bridge, config, sseManager) {
+function dispatchAgentEvent(event, tasks, store, bridge, config, sseManager) {
     // eslint-disable-next-line @typescript-eslint/switch-exhaustiveness-check -- only handles events with side effects
     switch (event.type) {
         case "connected":
-            handleConnected(event, sessions, config);
+            handleConnected(event, tasks, config);
             return false;
-        case "session_created":
+        case "task_created":
         case "config_option_update":
-            handleConfigLikeEvent(event, sessions);
+            handleConfigLikeEvent(event, tasks);
             return false;
         case "message_chunk":
-            handleMessageChunk(event, sessions);
+            handleMessageChunk(event, tasks);
             return false;
         case "thought_chunk":
-            handleThoughtChunk(event, sessions);
+            handleThoughtChunk(event, tasks);
             return false;
         case "tool_call":
-            handleToolCall(event, sessions, store);
+            handleToolCall(event, tasks, store);
             return false;
         case "tool_call_update":
-            store.saveEvent(event.sessionId, event.type, {
+            store.saveEvent(event.taskId, event.type, {
                 id: event.id,
                 status: event.status,
                 content: event.content,
@@ -244,21 +297,21 @@ function dispatchAgentEvent(event, sessions, store, bridge, config, sseManager)
             }, { from_ref: "agent" });
             return false;
         case "plan":
-            handlePlan(event, sessions, store);
+            handlePlan(event, tasks, store);
             return false;
         case "permission_request":
-            return handlePermissionRequest(event, sessions, store, bridge, sseManager, config);
+            return handlePermissionRequest(event, tasks, store, bridge, sseManager, config);
         case "prompt_done":
-            handlePromptDone(event, sessions, store);
+            handlePromptDone(event, tasks, store, bridge);
             return false;
         case "error":
-            handleError(event, sessions, store);
+            handleError(event, tasks, store, bridge);
             return false;
     }
     return false;
 }
 function maybePushNotify(event, pushService) {
-    if (!("sessionId" in event) || !event.sessionId)
+    if (!("taskId" in event) || !event.taskId)
         return;
     const pushEvent = {
         type: event.type,
@@ -271,41 +324,41 @@ function maybePushNotify(event, pushService) {
         // bash_done has `code` not `exitCode`; command not stored in the event
         pushEvent.exitCode = event.code ?? undefined;
     }
-    pushService.sendForEvent(event.sessionId, pushEvent).catch((err) => {
+    pushService.sendForEvent(event.taskId, pushEvent).catch((err) => {
         plog.error("failed to send", { error: err });
     });
 }
-export function handleAgentEvent(event, sessions, store, bridge, config, sseManager, pushService, _clientRegistry) {
+export function handleAgentEvent(event, tasks, store, bridge, config, sseManager, pushService, _clientRegistry) {
     if (event.type === "usage_update") {
-        handleUsageUpdate(event, sessions);
+        handleUsageUpdate(event, tasks);
         return;
     }
     if (event.type === "available_commands_update") {
-        const snapshot = sessions.updateAgentCommands(event.sessionId, event.commands);
-        if (sessions.restoringSessions.has(event.sessionId))
+        const snapshot = tasks.updateAgentCommands(event.taskId, event.commands);
+        if (tasks.restoringTasks.has(event.taskId))
             return;
         sseManager.broadcast({ ...event, ...snapshot });
         return;
     }
     if (event.type === "agent_reloading" || event.type === "agent_disconnected") {
-        for (const sessionId of sessions.liveSessions) {
-            sessions.flushBuffers(sessionId);
+        for (const taskId of tasks.liveTasks) {
+            tasks.flushBuffers(taskId);
         }
-        sessions.state.clearStreaming();
-        sessions.state.clearPlans();
-        sessions.state.clearContextUsage();
-        for (const snapshot of sessions.clearAgentCommands()) {
+        tasks.state.clearStreaming();
+        tasks.state.clearPlans();
+        tasks.state.clearContextUsage();
+        for (const snapshot of tasks.clearAgentCommands()) {
             sseManager.broadcast({
                 type: "available_commands_update",
                 ...snapshot,
             });
         }
     }
-    if ("sessionId" in event &&
-        event.sessionId &&
-        sessions.restoringSessions.has(event.sessionId))
+    if ("taskId" in event &&
+        event.taskId &&
+        tasks.restoringTasks.has(event.taskId))
         return;
-    const suppress = dispatchAgentEvent(event, sessions, store, bridge, config, sseManager);
+    const suppress = dispatchAgentEvent(event, tasks, store, bridge, config, sseManager);
     if (suppress)
         return;
     sseManager.broadcast(event);

package/lib/files/routes.js

@@ -2,7 +2,7 @@
  * File viewer HTTP routes — read-only access to arbitrary local files.
  *
  * URL space claimed: `/api/v1/files/{info,list,content}`.
- * Sessionless by design (confirmed): the caller passes an absolute or
+ * Task-less by design (confirmed): the caller passes an absolute or
  * `~`-prefixed path; the server own `~` expansion + realpath canonicalization.
  * Relative paths are rejected. Bearer auth is enforced by the shared
  * `/api/**` gate in routes.ts — these paths are deliberately NOT in the

package/lib/mcp/capability.js

@@ -0,0 +1,74 @@
+import { randomBytes } from "node:crypto";
+const CAPABILITY_PREFIX = "mcp_";
+/**
+ * Per-task MCP capability store.
+ *
+ * Holds the mapping between opaque capability tokens handed to ACP
+ * `mcpServers` definitions and the WebAgent task they were minted for.
+ * Lifecycle (minting on task create, revocation on task delete) is
+ * driven exclusively by TaskManager — this class is deliberately free of
+ * any lifecycle logic so the two tables can never drift.
+ *
+ * Tokens never touch the persistent store: they exist only in this map and
+ * die with the process, so a restart invalidates every outstanding
+ * capability by construction.
+ */
+export class CapabilityStore {
+    byToken = new Map();
+    byTask = new Map();
+    mintToken(taskId) {
+        const token = `${CAPABILITY_PREFIX}${randomBytes(32).toString("base64url")}`;
+        this.byToken.set(token, taskId);
+        const tokens = this.byTask.get(taskId) ?? new Set();
+        tokens.add(token);
+        this.byTask.set(taskId, tokens);
+        return token;
+    }
+    /** Mint a fresh capability for one task, replacing any prior one. */
+    mint(taskId) {
+        this.revokeByTask(taskId);
+        return this.mintToken(taskId);
+    }
+    /** Mint a replacement while keeping the current execution capability valid. */
+    mintAdditional(taskId) {
+        return this.mintToken(taskId);
+    }
+    /** Revoke one capability token (no-op when it is unknown). */
+    revoke(token) {
+        const taskId = this.byToken.get(token);
+        if (!taskId)
+            return;
+        this.byToken.delete(token);
+        const tokens = this.byTask.get(taskId);
+        tokens?.delete(token);
+        if (tokens?.size === 0)
+            this.byTask.delete(taskId);
+    }
+    /** Revoke all capabilities except the one used by a replacement execution. */
+    revokeOtherTokens(taskId, keepToken) {
+        for (const token of this.byTask.get(taskId) ?? []) {
+            if (token !== keepToken)
+                this.revoke(token);
+        }
+    }
+    /** Revoke every capability minted for a task (no-op when none exists). */
+    revokeByTask(taskId) {
+        for (const token of this.byTask.get(taskId) ?? []) {
+            this.byToken.delete(token);
+        }
+        this.byTask.delete(taskId);
+    }
+    /**
+     * Resolve a capability token to its task, or null when unknown.
+     * Fail-closed: any token that was never minted, was revoked, or whose
+     * process died resolves to null.
+     */
+    resolve(token) {
+        return this.byToken.get(token) ?? null;
+    }
+    /** Drop every capability (server shutdown). */
+    clear() {
+        this.byToken.clear();
+        this.byTask.clear();
+    }
+}

package/lib/mcp/server.js

@@ -0,0 +1,148 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { registerMcpTools } from "./tools.js";
+import { HTTP_STATUS } from "../http-status.js";
+/**
+ * WebAgent MCP server endpoint.
+ *
+ * Serves the MCP control plane for ACP sessions over Streamable HTTP.
+ * Each request is authenticated by the capability token minted for its
+ * session (carried as `Authorization: Bearer <capability>`); the endpoint
+ * fails closed — an unknown, revoked, or out-of-scope capability never
+ * reaches the MCP protocol layer.
+ *
+ * The endpoint lives outside `/api/**`, so the shared Bearer auth gate does
+ * not apply to it (mirroring the share viewer's `/s/*` pattern): identity is
+ * the per-task capability, distinct from operator UI tokens.
+ */
+/** Uniquely-named WebAgent MCP server appended to an ACP session's mcpServers. */
+export const MCP_SERVER_NAME = "webagent";
+/**
+ * Short, transport-level usage guidance advertised through MCP initialize.
+ * Keep this generic and bounded: detailed workflow guidance belongs in tool
+ * descriptions, the Task Manual, or an on-demand skill.
+ */
+export const MCP_SERVER_INSTRUCTIONS = [
+    "Use task_create for a direct child, then immediately use task_send to give it its first instruction.",
+    "Use task_send for normal coordination and for continuing or resuming existing Tasks; task_send is not a lifecycle handoff. Use task_update(done|blocked) for typed lifecycle handoffs. A done Task remains available and is not deleted or permanently closed.",
+    "After dispatching work, end the current turn; do not poll with task_query.",
+    "Use task_query and task_get_record only for history recovery, diagnosis, or audit.",
+    "Omit task_id to inspect the current Task's persisted history.",
+].join("\n");
+const DEFAULT_PATH = "/mcp";
+/**
+ * Build the ACP `McpServer` definition for one session: an HTTP entry whose
+ * Authorization header carries the session's freshly minted capability.
+ * `authBaseUrl` is the WebAgent's own origin (e.g. `http://127.0.0.1:6800`);
+ * the endpoint path is appended here so callers pass the base only.
+ */
+export function buildMcpServerEntry(capability, authBaseUrl) {
+    const base = authBaseUrl.replace(/\/$/, "");
+    return {
+        type: "http",
+        name: MCP_SERVER_NAME,
+        url: `${base}${DEFAULT_PATH}`,
+        headers: [{ name: "Authorization", value: `Bearer ${capability}` }],
+        // ACP reserves _meta for extension metadata. pi-acp translates this
+        // generic direct-tools hint into the adapter's internal setting; agents
+        // that do not understand it can safely ignore the metadata.
+        _meta: { directTools: true },
+    };
+}
+function capabilityFromRequest(req) {
+    const raw = req.headers.authorization;
+    if (typeof raw !== "string")
+        return null;
+    const match = /^Bearer\s+(\S+)\s*$/i.exec(raw.trim());
+    return match ? match[1] : null;
+}
+/**
+ * Create an MCP request handler. Returns a function that handles requests
+ * for the endpoint path and returns `false` for everything else so the main
+ * router can continue dispatching.
+ */
+export function createMcpEndpoint(options) {
+    const path = options.path ?? DEFAULT_PATH;
+    const { capabilities, isTaskActive } = options;
+    return async (req, res) => {
+        const url = req.url ?? "/";
+        const pathname = url.split("?")[0] ?? url;
+        if (pathname !== path)
+            return false;
+        const method = req.method ?? "GET";
+        if (method !== "POST") {
+            // Stateless mode has no SSE stream and no session reuse, so the MCP
+            // client drives request/response over POST only — mirrors the SDK's
+            // stateless example, which rejects other methods with 405.
+            res.writeHead(HTTP_STATUS.METHOD_NOT_ALLOWED, {
+                Allow: "POST",
+                "Content-Type": "application/json",
+            });
+            res.end(JSON.stringify({
+                jsonrpc: "2.0",
+                error: { code: -32000, message: "Method not allowed." },
+                id: null,
+            }));
+            return true;
+        }
+        // --- Capability gate (fail closed) ---
+        const capability = capabilityFromRequest(req);
+        const taskId = capability ? capabilities.resolve(capability) : null;
+        if (!taskId || !isTaskActive(taskId)) {
+            res.writeHead(HTTP_STATUS.UNAUTHORIZED, {
+                "Content-Type": "application/json",
+                "WWW-Authenticate": "Bearer",
+            });
+            res.end(JSON.stringify({
+                jsonrpc: "2.0",
+                error: { code: -32000, message: "Unauthorized" },
+                id: null,
+            }));
+            return true;
+        }
+        // --- MCP protocol (stateless, one server+transport per request) ---
+        const server = new McpServer({ name: MCP_SERVER_NAME, version: "0.1.0" }, { instructions: MCP_SERVER_INSTRUCTIONS });
+        registerMcpTools(server, taskId, options.taskTools);
+        const transport = new StreamableHTTPServerTransport({
+            sessionIdGenerator: undefined,
+            // JSON responses for POST round trips (no SSE streaming needed for the
+            // agent-driven request/response shape; the SDK default SSE response is
+            // harder for clients without an event-stream consumer).
+            enableJsonResponse: true,
+        });
+        try {
+            await server.connect(transport);
+            await transport.handleRequest(req, res);
+            // Transport already owns response handling for protocol errors; a
+            // thrown error here means the response was not (or only partially)
+            // written. Emit a JSON-RPC internal error instead of leaking details.
+        }
+        catch {
+            try {
+                if (!res.headersSent) {
+                    res.writeHead(HTTP_STATUS.INTERNAL_SERVER_ERROR, {
+                        "Content-Type": "application/json",
+                    });
+                    res.end(JSON.stringify({
+                        jsonrpc: "2.0",
+                        error: { code: -32603, message: "Internal server error" },
+                        id: null,
+                    }));
+                }
+                else {
+                    res.end();
+                }
+            }
+            catch {
+                // Nothing more we can do; the connection is gone.
+            }
+        }
+        finally {
+            res.once("close", () => {
+                void transport.close().catch(() => { });
+                void server.close().catch(() => { });
+            });
+        }
+        return true;
+    };
+}