@lelouchhe/webagent 0.8.0 → 0.10.0

package/lib/files/routes.js

@@ -0,0 +1,232 @@
+/**
+ * File viewer HTTP routes — read-only access to arbitrary local files.
+ *
+ * URL space claimed: `/api/v1/files/{info,list,content}`.
+ * 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
+ * public whitelist, with one exception: `content` IS whitelisted so
+ * `<img>` / `<a download>` can fetch without an Authorization header, and
+ * it instead requires an HMAC sig+exp signed URL (issued by `info`),
+ * mirroring the attachment scheme.
+ *
+ * Guards (see paths.ts + limits.ts): only regular files/dirs are served
+ * (no fifos/sockets/devices), directory scans and inline previews are bounded,
+ * downloads stream with backpressure, and responses carry nosniff + a
+ * restrictive CSP. The viewer renders text/markdown/image only — nothing here
+ * executes content.
+ */
+import { basename, dirname } from "node:path";
+import { pipeline } from "node:stream/promises";
+import { signAttachmentUrl, verifyAttachmentSig } from "../auth.js";
+import { buildContentDisposition, sniffMime } from "../attachments.js";
+import { HTTP_STATUS } from "../http-status.js";
+import { abbreviateHomePath } from "../home-path.js";
+import { log } from "../log.js";
+import { MAX_IMAGE_BYTES, MAX_TEXT_PREVIEW_BYTES } from "./limits.js";
+import { canonicalize, expandPath, FilePathError, listDirectory, openForStreaming, readHandleHead, readHead, statMeta, } from "./paths.js";
+const flog = log.scope("files");
+const CONTENT_TTL_SECONDS = 3600; // signed URLs live 1h, like attachments
+const SNIFF_BYTES = 4096;
+function fileSystemError(err) {
+    const code = err?.code;
+    if (code === "EACCES" || code === "EPERM") {
+        return new FilePathError(HTTP_STATUS.FORBIDDEN, "Permission denied");
+    }
+    if (code === "ENOENT" || code === "ENOTDIR") {
+        return new FilePathError(HTTP_STATUS.NOT_FOUND, "Path does not exist");
+    }
+    if (code === "ELOOP" ||
+        code === "EINVAL" ||
+        code === "ENAMETOOLONG" ||
+        code === "ERR_INVALID_ARG_VALUE") {
+        return new FilePathError(HTTP_STATUS.BAD_REQUEST, "Invalid path");
+    }
+    return null;
+}
+function json(res, status, body) {
+    res.writeHead(status, {
+        "Content-Type": "application/json",
+        "Cache-Control": "no-store",
+    });
+    res.end(JSON.stringify(body));
+}
+function previewLimitFor(mime) {
+    const m = mime.toLowerCase();
+    if (m.startsWith("image/"))
+        return MAX_IMAGE_BYTES;
+    if (m.startsWith("text/"))
+        return MAX_TEXT_PREVIEW_BYTES;
+    return null;
+}
+/** Expand + canonicalize a caller-supplied path; 400 on empty/relative. */
+async function resolvePath(raw) {
+    if (!raw)
+        throw new FilePathError(400, "Missing path");
+    return canonicalize(expandPath(raw));
+}
+function contentBasePath(pathRaw) {
+    return `/api/v1/files/content?path=${encodeURIComponent(pathRaw)}`;
+}
+async function streamHandle(res, handle, size) {
+    const stream = handle.createReadStream({
+        autoClose: false,
+        start: 0,
+        ...(size > 0 ? { end: size - 1 } : {}),
+    });
+    try {
+        await pipeline(stream, res);
+    }
+    catch (err) {
+        // Headers are already committed. A client disconnect or disk read error
+        // must terminate the stream, never fall through to a second JSON response.
+        if (!res.destroyed) {
+            res.destroy(err instanceof Error ? err : undefined);
+        }
+    }
+}
+export async function handleFileRoutes(req, res, deps) {
+    const url = req.url ?? "/";
+    if (!url.startsWith("/api/v1/files"))
+        return false;
+    const m = url.match(/^\/api\/v1\/files\/(info|list|content)(?:\?(.*))?$/);
+    if (!m)
+        return false;
+    const method = req.method ?? "GET";
+    if (method !== "GET") {
+        res.setHeader("Allow", "GET");
+        json(res, HTTP_STATUS.METHOD_NOT_ALLOWED, {
+            error: "Read-only: GET only",
+        });
+        return true;
+    }
+    try {
+        const params = new URLSearchParams(m[2]);
+        const pathRaw = params.get("path") ?? "";
+        switch (m[1]) {
+            case "info":
+                await handleInfo(res, deps, pathRaw);
+                return true;
+            case "list":
+                await handleList(res, pathRaw);
+                return true;
+            case "content":
+                await handleContent(res, deps, pathRaw, params);
+                return true;
+        }
+    }
+    catch (err) {
+        if (err instanceof FilePathError) {
+            json(res, err.status, { error: err.message });
+            return true;
+        }
+        const fsError = fileSystemError(err);
+        if (fsError) {
+            json(res, fsError.status, { error: fsError.message });
+            return true;
+        }
+        flog.error("file route failed", { url, error: String(err) });
+        json(res, HTTP_STATUS.INTERNAL_SERVER_ERROR, { error: "internal_error" });
+        return true;
+    }
+    return false;
+}
+async function handleInfo(res, deps, pathRaw) {
+    const canonical = await resolvePath(pathRaw);
+    const meta = await statMeta(canonical);
+    const out = {
+        path: meta.path,
+        pathDisplay: abbreviateHomePath(meta.path),
+        name: meta.name,
+        kind: meta.kind,
+        size: meta.size,
+        mtime: meta.mtime,
+    };
+    if (meta.kind === "file") {
+        const mime = await sniffMime(await readHead(canonical, SNIFF_BYTES));
+        const previewLimit = previewLimitFor(mime);
+        out.mime = mime;
+        if (previewLimit !== null)
+            out.maxBytes = previewLimit;
+        if (deps.secret) {
+            const basePath = contentBasePath(canonical);
+            out.contentUrl = `${basePath}&${signAttachmentUrl(basePath, deps.secret, CONTENT_TTL_SECONDS)}`;
+        }
+    }
+    json(res, HTTP_STATUS.OK, out);
+}
+async function handleList(res, pathRaw) {
+    const canonical = await resolvePath(pathRaw);
+    const meta = await statMeta(canonical);
+    if (meta.kind !== "dir") {
+        throw new FilePathError(HTTP_STATUS.BAD_REQUEST, "Not a directory");
+    }
+    const { entries, truncated } = await listDirectory(canonical);
+    const parent = dirname(canonical);
+    json(res, HTTP_STATUS.OK, {
+        path: canonical,
+        pathDisplay: abbreviateHomePath(canonical),
+        parent,
+        parentDisplay: abbreviateHomePath(parent),
+        truncated,
+        entries,
+    });
+}
+async function handleContent(res, deps, pathRaw, params) {
+    const basePath = contentBasePath(pathRaw);
+    const sig = params.get("sig") ?? "";
+    const exp = params.get("exp") ?? "";
+    // content is whitelisted in auth-middleware.ts (media tags / downloads
+    // cannot send Authorization headers), so it must verify its own URL.
+    // Unlike the older attachment route, this new security-sensitive route
+    // fails closed when no signing secret is wired.
+    if (!deps.secret) {
+        json(res, HTTP_STATUS.SERVICE_UNAVAILABLE, {
+            error: "file_content_signing_unavailable",
+        });
+        return;
+    }
+    if (!sig || !exp || !verifyAttachmentSig(basePath, exp, sig, deps.secret)) {
+        res.writeHead(HTTP_STATUS.UNAUTHORIZED, {
+            "Content-Type": "application/json",
+        });
+        res.end(JSON.stringify({ error: "Unauthorized" }));
+        return;
+    }
+    const canonical = await resolvePath(pathRaw);
+    // `info` signs the realpath-canonical string. If that path now resolves to
+    // another target (for example it was replaced by a symlink), the old
+    // capability must not silently acquire authority over the new target.
+    if (canonical !== pathRaw) {
+        json(res, HTTP_STATUS.UNAUTHORIZED, { error: "Unauthorized" });
+        return;
+    }
+    const handle = await openForStreaming(canonical);
+    try {
+        const stats = await handle.stat();
+        if (!stats.isFile()) {
+            throw new FilePathError(HTTP_STATUS.BAD_REQUEST, "Not a regular file");
+        }
+        const mime = await sniffMime(await readHandleHead(handle, stats.size, SNIFF_BYTES));
+        const previewLimit = previewLimitFor(mime);
+        const disposition = previewLimit !== null && stats.size <= previewLimit
+            ? "inline"
+            : "attachment";
+        res.writeHead(HTTP_STATUS.OK, {
+            "Content-Type": mime,
+            "X-Content-Type-Options": "nosniff",
+            // Ordinary project files change in place; never let reopening show a
+            // cached pre-edit body under the same path-bound signed URL.
+            "Cache-Control": "no-store",
+            // Belt-and-braces: even if a mime mis-sniff ever lets a browser
+            // interpret this body as HTML, it can't load any subresource.
+            "Content-Security-Policy": "default-src 'none'",
+            "Content-Disposition": buildContentDisposition(disposition, basename(canonical)),
+        });
+        await streamHandle(res, handle, stats.size);
+    }
+    finally {
+        await handle.close().catch(() => { });
+    }
+}

package/lib/home-path.js

@@ -0,0 +1,35 @@
+import { homedir } from "node:os";
+import { isAbsolute, join, relative, sep } from "node:path";
+const NATIVE_PATH = { isAbsolute, join, relative, sep };
+function portableDisplayPath(input, path) {
+    return path.sep === "\\" ? input.replace(/\\/g, "/") : input;
+}
+/**
+ * Expand the current user's HOME shorthand with one authoritative grammar.
+ * Both `~/` and `~\` are accepted; named-user forms stay untouched.
+ */
+export function expandHomePath(input, home = homedir(), path = NATIVE_PATH) {
+    if (input === "~")
+        return home;
+    if (input.startsWith("~/") || input.startsWith("~\\")) {
+        const tail = input.slice(2).replace(/[\\/]/g, path.sep);
+        return path.join(home, tail);
+    }
+    return input;
+}
+/**
+ * Abbreviate HOME and normalize Windows display paths to portable `/`
+ * separators. Canonical filesystem paths remain native and are stored/signed
+ * separately; this function is exclusively for UI round-tripping.
+ */
+export function abbreviateHomePath(input, home = homedir(), path = NATIVE_PATH) {
+    const relativePath = path.relative(home, input);
+    if (relativePath === "")
+        return "~";
+    if (relativePath === ".." ||
+        relativePath.startsWith(`..${path.sep}`) ||
+        path.isAbsolute(relativePath)) {
+        return portableDisplayPath(input, path);
+    }
+    return `~/${portableDisplayPath(relativePath, path)}`;
+}

package/lib/http-status.js

@@ -7,6 +7,7 @@ export const HTTP_STATUS = Object.freeze({
     UNAUTHORIZED: 401,
     FORBIDDEN: 403,
     NOT_FOUND: 404,
+    METHOD_NOT_ALLOWED: 405,
     CONFLICT: 409,
     GONE: 410,
     PAYLOAD_TOO_LARGE: 413,

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;
+    };
+}