@musashishao/folderforge 1.2.0

package/dist/policy/risk.js

@@ -0,0 +1,112 @@
+export const RISK_ORDER = {
+    LOW: 0,
+    MEDIUM: 1,
+    HIGH: 2,
+    CRITICAL: 3,
+};
+export function maxRisk(a, b) {
+    return RISK_ORDER[a] >= RISK_ORDER[b] ? a : b;
+}
+/**
+ * Default risk classification per tool name (section 8 of the spec).
+ */
+export const TOOL_RISK = {
+    // LOW
+    file_read: 'LOW',
+    file_read_many: 'LOW',
+    search_files: 'LOW',
+    search_text: 'LOW',
+    search_ast: 'LOW',
+    git_status: 'LOW',
+    git_diff: 'LOW',
+    git_log: 'LOW',
+    git_show: 'LOW',
+    git_blame: 'LOW',
+    git_branch: 'LOW',
+    git_fetch: 'MEDIUM',
+    git_stash: 'MEDIUM',
+    list_directory: 'LOW',
+    run_test: 'LOW',
+    run_lint: 'LOW',
+    run_typecheck: 'LOW',
+    run_coverage: 'LOW',
+    pkg_list: 'LOW',
+    pkg_outdated: 'LOW',
+    pkg_audit: 'LOW',
+    format_check: 'LOW',
+    project_detect_commands: 'LOW',
+    workspace_status: 'LOW',
+    workspace_list: 'LOW',
+    workspace_health: 'LOW',
+    workspace_route: 'LOW',
+    policy_get: 'LOW',
+    policy_explain: 'LOW',
+    policy_ratelimits: 'LOW',
+    audit_recent: 'LOW',
+    memory_list: 'LOW',
+    memory_read: 'LOW',
+    code_symbols_overview: 'LOW',
+    code_find_symbol: 'LOW',
+    code_find_references: 'LOW',
+    code_find_definition: 'LOW',
+    code_find_implementations: 'LOW',
+    code_diagnostics: 'LOW',
+    browser_snapshot: 'LOW',
+    browser_console: 'LOW',
+    browser_network: 'LOW',
+    db_list_connections: 'LOW',
+    db_list_tables: 'LOW',
+    db_describe_table: 'LOW',
+    db_query_readonly: 'LOW',
+    db_explain: 'LOW',
+    secret_scan: 'LOW',
+    approval_status: 'LOW',
+    // MEDIUM
+    file_write: 'MEDIUM',
+    file_patch: 'MEDIUM',
+    file_edit_block: 'MEDIUM',
+    file_move: 'MEDIUM',
+    file_copy: 'MEDIUM',
+    git_pull: 'HIGH',
+    workspace_activate: 'MEDIUM',
+    workspace_switch: 'MEDIUM',
+    workspace_deactivate: 'MEDIUM',
+    workspace_onboard: 'MEDIUM',
+    git_add: 'MEDIUM',
+    git_checkout: 'MEDIUM',
+    run_build: 'MEDIUM',
+    pkg_run: 'MEDIUM',
+    format_apply: 'MEDIUM',
+    process_start: 'MEDIUM',
+    process_read: 'LOW',
+    process_tail: 'LOW',
+    process_write: 'MEDIUM',
+    process_stop: 'MEDIUM',
+    process_list: 'LOW',
+    memory_write: 'MEDIUM',
+    memory_update: 'MEDIUM',
+    code_replace_symbol_body: 'MEDIUM',
+    code_insert_before_symbol: 'MEDIUM',
+    code_insert_after_symbol: 'MEDIUM',
+    code_rename_symbol: 'MEDIUM',
+    browser_open: 'MEDIUM',
+    browser_click: 'MEDIUM',
+    browser_type: 'MEDIUM',
+    browser_screenshot: 'MEDIUM',
+    browser_close: 'MEDIUM',
+    policy_set_mode: 'MEDIUM',
+    db_connect: 'MEDIUM',
+    shell_exec: 'MEDIUM', // re-classified per command at runtime
+    // HIGH
+    file_delete: 'HIGH',
+    git_commit: 'HIGH',
+    process_kill: 'HIGH',
+    db_run_migration: 'HIGH',
+    db_write: 'HIGH',
+    pkg_add: 'HIGH',
+    pkg_remove: 'HIGH',
+    // CRITICAL
+    git_push: 'CRITICAL',
+    git_reset: 'CRITICAL',
+    browser_eval: 'HIGH',
+};

package/dist/policy/secret-policy.js

@@ -0,0 +1,132 @@
+/**
+ * Secret detection and redaction.
+ */
+const RULES = [
+    { name: 'OpenAI key', re: /\bsk-[A-Za-z0-9]{20,}\b/g },
+    { name: 'Anthropic key', re: /\bsk-ant-[A-Za-z0-9_-]{20,}\b/g },
+    { name: 'AWS access key id', re: /\bAKIA[0-9A-Z]{16}\b/g },
+    { name: 'GitHub token', re: /\bgh[pousr]_[A-Za-z0-9]{20,}\b/g },
+    { name: 'Google API key', re: /\bAIza[0-9A-Za-z_-]{35}\b/g },
+    { name: 'Slack token', re: /\bxox[baprs]-[A-Za-z0-9-]{10,}\b/g },
+    { name: 'Private key block', re: /-----BEGIN (?:RSA |EC |OPENSSH |DSA |PGP )?PRIVATE KEY-----/g },
+    { name: 'Generic assignment', re: /\b(?:password|passwd|secret|token|api[_-]?key|access[_-]?key)\s*[=:]\s*['"]?[^\s'"]{6,}/gi },
+    { name: 'Env secret', re: /\b(?:OPENAI_API_KEY|ANTHROPIC_API_KEY|AWS_SECRET_ACCESS_KEY|AWS_ACCESS_KEY_ID|GITHUB_TOKEN)\s*=\s*\S+/g },
+];
+const NAMED_ENV = [
+    'OPENAI_API_KEY',
+    'ANTHROPIC_API_KEY',
+    'AWS_ACCESS_KEY_ID',
+    'AWS_SECRET_ACCESS_KEY',
+    'GITHUB_TOKEN',
+    'GOOGLE_API_KEY',
+    'DATABASE_URL',
+];
+const DEFAULT_SCAN_CONFIG = {
+    entropyEnabled: true,
+    minEntropy: 4.0,
+    minLength: 20,
+};
+/**
+ * Shannon entropy in bits per character for a string. High values (> ~4.0)
+ * indicate random-looking content typical of keys and tokens.
+ */
+export function shannonEntropy(s) {
+    if (!s.length)
+        return 0;
+    const counts = new Map();
+    for (const ch of s)
+        counts.set(ch, (counts.get(ch) ?? 0) + 1);
+    let h = 0;
+    for (const c of counts.values()) {
+        const p = c / s.length;
+        h -= p * Math.log2(p);
+    }
+    return h;
+}
+// Candidate tokens for entropy scanning: long runs of base64/hex/key-ish chars.
+const TOKEN_RE = /[A-Za-z0-9+/_-]{16,}/g;
+// Tokens that are clearly not secrets (all one case word, pure numbers, hashes
+// of known kinds are still flagged - better safe). We skip obvious noise.
+const LOW_SIGNAL_RE = /^[0-9]+$/;
+export class SecretPolicy {
+    scanConfig;
+    constructor(scanConfig = DEFAULT_SCAN_CONFIG) {
+        this.scanConfig = scanConfig;
+    }
+    redact(text) {
+        let out = text;
+        for (const rule of RULES) {
+            out = out.replace(rule.re, (m) => {
+                if (rule.name === 'Generic assignment') {
+                    const eq = m.search(/[=:]/);
+                    return `${m.slice(0, eq + 1)} [REDACTED]`;
+                }
+                if (rule.name === 'Env secret') {
+                    const eq = m.indexOf('=');
+                    return `${m.slice(0, eq + 1)}[REDACTED]`;
+                }
+                return '[REDACTED]';
+            });
+        }
+        return out;
+    }
+    redactEnv(env) {
+        const out = {};
+        for (const [k, v] of Object.entries(env)) {
+            if (v === undefined)
+                continue;
+            if (NAMED_ENV.includes(k) || /key|secret|token|password|passwd/i.test(k)) {
+                out[k] = '[REDACTED]';
+            }
+            else {
+                out[k] = v;
+            }
+        }
+        return out;
+    }
+    scan(text) {
+        const findings = [];
+        const lines = text.split('\n');
+        lines.forEach((line, i) => {
+            for (const rule of RULES) {
+                rule.re.lastIndex = 0;
+                const m = rule.re.exec(line);
+                if (m) {
+                    findings.push({
+                        rule: rule.name,
+                        preview: m[0].slice(0, 12) + '...',
+                        line: i + 1,
+                    });
+                }
+            }
+            // Entropy pass: flag high-entropy tokens that no rule matched. This catches
+            // bespoke/unknown key formats. Tokens already covered by a regex finding on
+            // this line are skipped to avoid double-reporting.
+            if (this.scanConfig.entropyEnabled) {
+                const matchedOnLine = findings.filter((f) => f.line === i + 1 && f.rule !== 'high entropy');
+                TOKEN_RE.lastIndex = 0;
+                let tok;
+                while ((tok = TOKEN_RE.exec(line)) !== null) {
+                    const value = tok[0];
+                    if (value.length < this.scanConfig.minLength)
+                        continue;
+                    if (LOW_SIGNAL_RE.test(value))
+                        continue;
+                    const alreadyFlagged = matchedOnLine.some((f) => value.startsWith(f.preview.replace(/\.\.\.$/, '')));
+                    if (alreadyFlagged)
+                        continue;
+                    const entropy = shannonEntropy(value);
+                    if (entropy >= this.scanConfig.minEntropy) {
+                        findings.push({
+                            rule: 'high entropy',
+                            preview: value.slice(0, 12) + '...',
+                            line: i + 1,
+                            entropy: Math.round(entropy * 100) / 100,
+                        });
+                    }
+                }
+            }
+        });
+        return findings;
+    }
+}

package/dist/server/mcp-server.js

@@ -0,0 +1,144 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { logger } from '../core/logger.js';
+/**
+ * Build an MCP {@link Server} backed by the FolderForge {@link ToolRegistry}.
+ *
+ * The server exposes exactly two capabilities:
+ *  - `tools/list`  -> reads {@link ToolRegistry.listActive} (curated/active subset)
+ *  - `tools/call`  -> delegates to {@link ToolRegistry.call} (policy + audit pipeline)
+ *
+ * `tools/list` additionally advertises, when present:
+ *  - `outputSchema`  (MCP structured tool output, 2025-06-18)
+ *  - `annotations`   (readOnly/destructive/idempotent hints, derived from
+ *                     the frozen mutates/risk contract in defineTool)
+ *
+ * Transport binding (stdio / http) is handled separately in `server/transports/*`.
+ */
+export function createMcpServer(registry, info) {
+    const roots = info.roots ?? [];
+    // NOTE on `roots`: in MCP, `roots` is a *client* capability (the client tells
+    // the server which directories are in scope). A server cannot declare it.
+    // FolderForge instead surfaces its own filesystem scope to the client through
+    // the server `instructions` string below (and via the workspace_* tools), so
+    // the agent can discover the allowed directories without us mis-declaring a
+    // capability we don't own. This satisfies roadmap P5 truthfully.
+    const rootsLine = roots.length
+        ? `\n\nWorkspace roots (allowed directories): ${roots.join(', ')}.`
+        : '';
+    const server = new Server({ name: info.name, version: info.version }, {
+        capabilities: { tools: {} },
+        instructions: 'FolderForge: local development control plane. All tools run through a ' +
+            'policy + audit pipeline; tool annotations (readOnlyHint/destructiveHint) ' +
+            'are hints only.' +
+            rootsLine,
+    });
+    server.setRequestHandler(ListToolsRequestSchema, async () => {
+        const tools = registry.listActive().map((t) => {
+            const tool = {
+                name: t.name,
+                description: t.description,
+                inputSchema: toJsonSchema(t.inputSchema),
+            };
+            // Advertise structured output schema (MCP outputSchema) when a tool
+            // declares one. Clients use it to validate `structuredContent`.
+            if (t.outputSchema) {
+                tool.outputSchema = toJsonSchema(t.outputSchema);
+            }
+            // Advertise behaviour hints. Derived from mutates/risk in defineTool;
+            // hints only - never a security boundary.
+            if (t.annotations) {
+                tool.annotations = t.annotations;
+            }
+            return tool;
+        });
+        return { tools };
+    });
+    server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
+        const { name, arguments: args } = request.params;
+        // Wire MCP protocol features into the tool pipeline via a per-call control
+        // object (roadmap P4/P6/P8). All three are optional: a long-running handler
+        // may report progress, observe cancellation, or elicit input, while a
+        // simple handler ignores `control` entirely. None of this touches the
+        // frozen tool schema, so the schema-lock is unaffected.
+        const progressToken = request.params._meta?.progressToken;
+        // P8 - elicitation adapter: normalize the SDK's elicitInput result into the
+        // project's ElicitResult shape (narrowing `action` to our union). Present
+        // only when the client advertised the `elicitation` capability; otherwise
+        // omitted entirely so handlers fall back to non-interactive defaults.
+        const elicit = server.getClientCapabilities()
+            ?.elicitation
+            ? async (params) => {
+                const r = await server.elicitInput(params);
+                const action = r.action;
+                return r.content !== undefined ? { action, content: r.content } : { action };
+            }
+            : undefined;
+        // P4 - progress: only emit when the client opted in by sending a
+        // progressToken in the request _meta. Mirrors the SDK contract.
+        const reportProgress = progressToken === undefined
+            ? undefined
+            : async (progress, total, message) => {
+                await extra.sendNotification({
+                    method: 'notifications/progress',
+                    params: { progressToken, progress, total, message },
+                });
+            };
+        // Build the control object with conditional spreads: under
+        // exactOptionalPropertyTypes an optional field cannot be assigned
+        // `undefined` explicitly, so we omit absent capabilities entirely.
+        const control = {
+            // P6 - cancellation: the SDK aborts `extra.signal` on a notifications/
+            // cancelled for this request id. Handlers long-poll against it the same
+            // way ProcessManager.readUntil waits on its own waiters.
+            signal: extra.signal,
+            ...(reportProgress !== undefined ? { reportProgress } : {}),
+            ...(elicit !== undefined ? { elicitInput: elicit } : {}),
+        };
+        const result = await registry.call(name, (args ?? {}), control);
+        const tool = registry.get(name);
+        return toCallToolResult(result, Boolean(tool?.outputSchema));
+    });
+    server.onerror = (err) => {
+        logger.error({ err: err instanceof Error ? err.message : String(err) }, 'MCP server error');
+    };
+    return server;
+}
+/**
+ * Tool input schemas are stored as plain JSON-schema objects. The MCP SDK
+ * requires the top-level `type` to be `"object"`; normalize defensively.
+ */
+function toJsonSchema(schema) {
+    const base = schema && typeof schema === 'object' ? schema : {};
+    return { type: 'object', ...base };
+}
+/**
+ * Convert a FolderForge {@link ToolResult} into an MCP `tools/call` result.
+ *
+ * Exported for unit testing of the structuredContent mirroring contract.
+ */
+export function toCallToolResult(result, hasOutputSchema = false) {
+    if (!result.ok) {
+        const text = result.approvalId
+            ? `${result.error ?? 'Approval required'}\n(approvalId=${result.approvalId})`
+            : result.error ?? 'Tool call failed';
+        return { content: [{ type: 'text', text }], isError: true };
+    }
+    const payload = {};
+    if (result.data !== undefined)
+        payload.data = result.data;
+    if (result.diff !== undefined)
+        payload.diff = result.diff;
+    const text = result.diff && result.data === undefined
+        ? result.diff
+        : JSON.stringify(Object.keys(payload).length ? payload : { ok: true }, null, 2);
+    const out = { content: [{ type: 'text', text }] };
+    // When a tool declares an outputSchema, also return machine-readable
+    // structuredContent so spec-aware clients can consume typed output without
+    // re-parsing the text block (MCP 2025-06-18 structured tool output).
+    if (hasOutputSchema && result.data !== undefined && result.data !== null) {
+        out.structuredContent =
+            result.data;
+    }
+    return out;
+}

package/dist/server/transports/http.js

@@ -0,0 +1,133 @@
+import { createServer } from 'node:http';
+import { randomUUID, timingSafeEqual } from 'node:crypto';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { logger } from '../../core/logger.js';
+/** True when the bind host is loopback-only and therefore safe without a token. */
+export function isLoopbackHost(host) {
+    return host === '127.0.0.1' || host === '::1' || host === 'localhost';
+}
+/** Constant-time string comparison that tolerates length differences. */
+export function timingSafeEqualStr(a, b) {
+    const ab = Buffer.from(a);
+    const bb = Buffer.from(b);
+    if (ab.length !== bb.length) {
+        // Still compare against self to keep timing roughly constant.
+        timingSafeEqual(ab, ab);
+        return false;
+    }
+    return timingSafeEqual(ab, bb);
+}
+/** Extract a bearer token from the Authorization header. */
+export function extractBearer(req) {
+    const header = req.headers['authorization'];
+    if (typeof header === 'string' && header.startsWith('Bearer ')) {
+        return header.slice('Bearer '.length).trim();
+    }
+    return undefined;
+}
+/**
+ * Resolve the CORS origin header value for a request, or null to omit it.
+ * `['*']` echoes any origin (so credentials can still work); a concrete list
+ * echoes only matching origins.
+ */
+export function resolveCorsOrigin(requestOrigin, allowed) {
+    if (!allowed || allowed.length === 0)
+        return null;
+    if (allowed.includes('*'))
+        return requestOrigin ?? '*';
+    if (requestOrigin && allowed.includes(requestOrigin))
+        return requestOrigin;
+    return null;
+}
+/**
+ * Bind the MCP server to a hardened Streamable HTTP transport.
+ *
+ * Hardening over the bare transport:
+ *  - Bearer-token auth (constant-time) when a token is configured.
+ *  - CORS handling with an explicit allowlist + preflight support.
+ *  - Idle session expiry: the underlying transport is recreated after
+ *    `sessionTtlMs` of inactivity so stale sessions don't linger.
+ */
+export async function startHttpTransport(server, opts) {
+    const mcpPath = opts.path ?? '/mcp';
+    const ttl = opts.sessionTtlMs ?? 30 * 60 * 1000; // 30 min default
+    const requireAuth = Boolean(opts.token);
+    if (!isLoopbackHost(opts.host) && !opts.token) {
+        throw new Error('HTTP transport bound to a non-loopback host requires server.http.token');
+    }
+    let transport = new StreamableHTTPServerTransport({ sessionIdGenerator: () => randomUUID() });
+    await server.connect(transport);
+    let lastActivity = Date.now();
+    // Recreate the transport (and reconnect the server) when it has been idle past
+    // the TTL, expiring any stale session id.
+    const refreshIfIdle = async () => {
+        if (Date.now() - lastActivity > ttl) {
+            try {
+                await transport.close?.();
+            }
+            catch {
+                // ignore close errors
+            }
+            transport = new StreamableHTTPServerTransport({ sessionIdGenerator: () => randomUUID() });
+            await server.connect(transport);
+            logger.info({ ttlMs: ttl }, 'HTTP MCP session expired after idle TTL; rotated transport');
+        }
+        lastActivity = Date.now();
+    };
+    const applyCors = (req, res) => {
+        const origin = resolveCorsOrigin(req.headers.origin, opts.corsOrigins);
+        if (origin) {
+            res.setHeader('access-control-allow-origin', origin);
+            res.setHeader('vary', 'Origin');
+            res.setHeader('access-control-allow-methods', 'GET, POST, DELETE, OPTIONS');
+            res.setHeader('access-control-allow-headers', 'authorization, content-type, mcp-session-id');
+        }
+    };
+    const http = createServer((req, res) => {
+        const url = req.url ?? '/';
+        applyCors(req, res);
+        // CORS preflight.
+        if (req.method === 'OPTIONS') {
+            res.writeHead(204);
+            res.end();
+            return;
+        }
+        if (req.method === 'GET' && url === '/healthz') {
+            res.writeHead(200, { 'content-type': 'application/json' });
+            res.end(JSON.stringify({ ok: true }));
+            return;
+        }
+        if (url === mcpPath || url.startsWith(`${mcpPath}?`)) {
+            if (requireAuth) {
+                const provided = extractBearer(req);
+                if (!provided || !timingSafeEqualStr(provided, opts.token)) {
+                    res.writeHead(401, {
+                        'content-type': 'application/json',
+                        'www-authenticate': 'Bearer realm="folderforge-mcp"',
+                    });
+                    res.end(JSON.stringify({ error: 'unauthorized', message: 'Valid bearer token required.' }));
+                    return;
+                }
+            }
+            void refreshIfIdle()
+                .then(() => transport.handleRequest(req, res))
+                .catch((err) => {
+                logger.error({ err: String(err) }, 'HTTP MCP request failed');
+                if (!res.headersSent) {
+                    res.writeHead(500, { 'content-type': 'application/json' });
+                    res.end(JSON.stringify({ error: 'internal_error' }));
+                }
+            });
+            return;
+        }
+        res.writeHead(404, { 'content-type': 'text/plain; charset=utf-8' });
+        res.end('Not found');
+    });
+    await new Promise((resolveListen) => {
+        http.listen(opts.port, opts.host, () => {
+            logger.info({ host: opts.host, port: opts.port, path: mcpPath, authRequired: requireAuth, sessionTtlMs: ttl }, 'MCP HTTP transport listening');
+            resolveListen();
+        });
+    });
+    return http;
+}

package/dist/server/transports/stdio.js

@@ -0,0 +1,14 @@
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { logger } from '../../core/logger.js';
+/**
+ * Bind the MCP server to the stdio transport.
+ *
+ * stdin/stdout carry the JSON-RPC channel, so logs must go to stderr only
+ * (see core/logger.ts). Returns once the transport is connected.
+ */
+export async function startStdioTransport(server) {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    logger.info('MCP stdio transport connected');
+    return transport;
+}

package/dist/tools/adapter-tools.js

@@ -0,0 +1,62 @@
+import { defineTool } from './registry.js';
+import { logger } from '../core/logger.js';
+/** Adapters we expose, in a stable order, with their namespace prefix. */
+const ADAPTER_NAMES = ['serena', 'playwright', 'desktopCommander'];
+/** Separator between an adapter namespace and the child tool name. */
+export const NS_SEP = '__';
+/**
+ * Build the namespaced tool name for a child tool, e.g. `serena__find_symbol`.
+ */
+export function namespacedName(adapter, childTool) {
+    return `${adapter}${NS_SEP}${childTool}`;
+}
+/**
+ * Discover the tools exposed by every enabled child MCP adapter and wrap each
+ * one as a native FolderForge {@link ToolDefinition}. The wrapper:
+ *  - prefixes the name with the adapter namespace (`serena__find_symbol`)
+ *  - lazily starts the child process on first call (via `adapters.ensure`)
+ *  - routes the call through the same policy + audit pipeline as native tools
+ *
+ * Child tools are treated as MEDIUM risk and `mutates: true` by default so that
+ * policy mode (readonly/safe) and the approval list still gate them. Discovery
+ * failures for one adapter never block the others.
+ */
+export async function buildAdapterTools(container) {
+    const tools = [];
+    for (const name of ADAPTER_NAMES) {
+        if (!container.adapters.isEnabled(name))
+            continue;
+        let childTools;
+        try {
+            const client = await container.adapters.ensure(name);
+            childTools = (await client.listTools());
+        }
+        catch (err) {
+            logger.warn({ adapter: name, err: String(err) }, 'Skipping adapter; tool discovery failed');
+            continue;
+        }
+        for (const child of childTools) {
+            const toolName = namespacedName(name, child.name);
+            tools.push(defineTool({
+                name: toolName,
+                description: child.description ?? `${name} tool: ${child.name}`,
+                inputSchema: child.inputSchema ?? { type: 'object' },
+                group: `adapter:${name}`,
+                mutates: true,
+                risk: 'MEDIUM',
+                handler: async (args) => {
+                    try {
+                        const client = await container.adapters.ensure(name);
+                        const raw = await client.callTool(child.name, args);
+                        return { ok: true, data: raw };
+                    }
+                    catch (err) {
+                        return { ok: false, error: `${toolName} failed: ${String(err)}` };
+                    }
+                },
+            }));
+        }
+        logger.info({ adapter: name, count: childTools.length }, 'Registered adapter tools');
+    }
+    return tools;
+}

package/dist/tools/browser-tools.js

@@ -0,0 +1,76 @@
+import { defineTool } from './registry.js';
+const PW_MAP = {
+    browser_open: 'browser_navigate',
+    browser_snapshot: 'browser_snapshot',
+    browser_click: 'browser_click',
+    browser_type: 'browser_type',
+    browser_console: 'browser_console_messages',
+    browser_network: 'browser_network_requests',
+    browser_screenshot: 'browser_take_screenshot',
+    browser_close: 'browser_close',
+    browser_eval: 'browser_evaluate',
+};
+function isLocalOrAllowed(url, ctx) {
+    try {
+        const u = new URL(url);
+        if (['localhost', '127.0.0.1', '0.0.0.0', '::1'].includes(u.hostname))
+            return true;
+        // Allow file:// for local fixtures.
+        if (u.protocol === 'file:')
+            return true;
+        return false;
+    }
+    catch {
+        return false;
+    }
+}
+async function routeToPlaywright(ctx, toolName, args) {
+    if (toolName === 'browser_open' && typeof args.url === 'string') {
+        if (!isLocalOrAllowed(args.url, ctx) && ctx.container.policy.getMode() !== 'danger') {
+            return { ok: false, error: `External URL blocked by policy: ${args.url}. Only localhost is allowed by default.` };
+        }
+    }
+    if (!ctx.container.adapters.isEnabled('playwright')) {
+        return { ok: false, error: 'Playwright adapter is disabled. Enable adapters.playwright in config.' };
+    }
+    try {
+        const client = await ctx.container.adapters.ensure('playwright');
+        const pwTool = PW_MAP[toolName] ?? toolName;
+        const result = await client.callTool(pwTool, args);
+        return { ok: true, data: result };
+    }
+    catch (err) {
+        return { ok: false, error: `Playwright call failed: ${String(err)}` };
+    }
+}
+function bTool(name, description, mutates, props) {
+    return defineTool({
+        name,
+        description,
+        group: 'browser',
+        mutates,
+        inputSchema: { type: 'object', properties: props },
+        handler: (args, ctx) => routeToPlaywright(ctx, name, args),
+    });
+}
+export function browserTools() {
+    return [
+        bTool('browser_open', 'Navigate the browser to a URL (localhost only by default).', true, {
+            url: { type: 'string' },
+        }),
+        bTool('browser_snapshot', 'Return the accessibility tree snapshot of the page.', false, {}),
+        bTool('browser_click', 'Click an element on the page.', true, { element: { type: 'string' }, ref: { type: 'string' } }),
+        bTool('browser_type', 'Type text into an input.', true, {
+            element: { type: 'string' },
+            ref: { type: 'string' },
+            text: { type: 'string' },
+        }),
+        bTool('browser_console', 'Read browser console messages.', false, {}),
+        bTool('browser_network', 'List network requests made by the page.', false, {}),
+        bTool('browser_screenshot', 'Capture a screenshot of the page.', true, {}),
+        bTool('browser_close', 'Close the browser session.', true, {}),
+        bTool('browser_eval', 'Evaluate a JavaScript expression in the page context. HIGH risk.', true, {
+            function: { type: 'string', description: 'A JavaScript function body to evaluate in the page.' },
+        }),
+    ];
+}