@symbols-cli/cli 0.0.1

package/dist/mcp/tools.js

@@ -0,0 +1,646 @@
+// Copyright (c) 2025 Symbols LLC. All rights reserved.
+//
+// This source code is proprietary and confidential. Unauthorized copying,
+// distribution, modification, or use of this file, via any medium, is strictly prohibited.
+// The Symbols MCP tool surface — a TypeScript port of
+// `docker/odin-runtime/symbols-mcp/__main__.py` (751 lines, Python + `mcp` 2.x).
+//
+// ─────────────────────────────────────────────────────────────────────────────
+// WHAT CHANGED IN THE PORT, AND WHY
+// ─────────────────────────────────────────────────────────────────────────────
+//
+// 1. **Tools are DATA, not decorated functions.** The Python file spread eleven
+//    `@app.tool` decorators over one `_dispatch` chain, and needed a Python AST
+//    pass (`scripts/check_mcp_scopes.py`) to recover which paths it could reach.
+//    Here every tool is a row in `TOOLS` that DECLARES its route templates, and
+//    `buildPath` (mcp/scopes.ts) is the only path constructor in the module. The
+//    declaration is not a description of the request — it IS the request, so
+//    they cannot drift, and the checker reads one literal per route.
+//
+// 2. **The path is validated twice.** `templateOk` runs against the CONCRETE
+//    path for every tool, not just the dynamic `api_get` door. It costs nothing
+//    and it means a tool argument carrying `/` or `..` is refused here rather
+//    than reaching the wire. (The Python version interpolated `args['symbol']`
+//    unencoded.)
+//
+// 3. **THE v1 TOOL SURFACE IS READ-ONLY — the CREDENTIAL IS NOT.**
+//    ⚠ Do not read this as "the CLI cannot destroy anything". The device
+//    credential carries four DELETE scopes, including
+//    `DELETE /api/notebooks/{id}`, because `symbols project rm` needs them —
+//    and `symbols curl` honours `-X`. What is read-only is the list of TOOLS
+//    below. A P6 agent wrote the stronger claim into a skill, verified it, and
+//    found it false; `symbols whoami` now prints the destructive scopes
+//    separately so the distinction is visible rather than asserted.
+//    `place_order`, `cancel_order`, `deploy_regime` and
+//    `backtest_regime` are NOT ported. See `P5_SEAM` below.
+//
+// ⚠ Descriptions are the agent's ONLY instructions for these tools, and several
+// carry a safety rule. Carried across near-verbatim; where one described the
+// container it was rewritten rather than softened, because a description that
+// misdescribes a laptop is worse than one that is merely terse.
+import { request, ApiError, NotLoggedInError } from "../auth/client.js";
+import { SCOPED_PATHS, allowedFamilies, buildPath, splitRoute, templateOk } from "./scopes.js";
+// ─────────────────────────────────────────────────────────────────────────────
+// P5_SEAM — the write tools, deliberately absent
+// ─────────────────────────────────────────────────────────────────────────────
+//
+// The Python server ships four tools this file does not:
+//
+//     place_order       POST   /api/odin-code/brokerage/orders
+//     cancel_order      DELETE /api/odin-code/brokerage/orders/{client_order_id}
+//     deploy_regime     POST   /api/odin-code/regimes
+//     backtest_regime   POST   /api/odin-code/regimes/{regime_id}/backtest
+//
+// All four ride the SHORT-LIVED write credential, which the container re-mints
+// only while the WebSocket is open — i.e. while a human is watching the tile.
+// On a laptop `claude` sits in a detached tmux for days, so a timer-driven
+// refresher would be a PERMANENTLY-ARMED order credential: strictly worse than
+// the container, not equivalent to it.
+//
+// P5 adds `symbols arm`, the browser-consent window, the per-window cap and the
+// device+window audit rows, and only then these tools. Adding one here without
+// that window is not "getting ahead" — it is removing the control.
+//
+// `check_mcp_scopes.py` enforces the seam: a non-GET `route:` in this file while
+// `WRITE_PATHS` is empty fails the check.
+export const P5_SEAM = Object.freeze({
+    toolsDeferredToP5: ["place_order", "cancel_order", "deploy_regime", "backtest_regime"],
+    reason: "needs the armed window (symbols arm) — see plan §Money, P0 decision 2026-08-30",
+});
+// ─────────────────────────────────────────────────────────────────────────────
+// Enumerations derived from the generated scope list
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * The Unusual Whales endpoints, DERIVED from `SCOPED_PATHS`.
+ *
+ * The Python file hard-coded these twenty names beside a scope list that also
+ * held them — two places to add the twenty-first, and the flow family sat
+ * unreachable for exactly that kind of reason once already. Deriving means the
+ * tool's enum, the route it builds, and the server's allowlist are one fact.
+ */
+export const FLOW_ENDPOINTS = SCOPED_PATHS.filter((p) => p.startsWith("/api/flow/") && !p.includes("{"))
+    .map((p) => p.slice("/api/flow/".length))
+    .sort();
+/**
+ * Fundamentals: a caller-facing `kind` mapped to the route that serves it.
+ *
+ * The kind NAMES are a UX choice and stay hand-written; the TEMPLATES are
+ * checked against `SCOPED_PATHS` at module load, so a route rename fails loudly
+ * at startup instead of 404ing per call.
+ */
+export const FUNDAMENTALS = Object.freeze({
+    profile: "/api/company/profile/{symbol}",
+    earnings: "/api/earnings/{symbol}",
+    earnings_uw: "/api/earnings/{symbol}/uw",
+    ratios: "/api/ratios/{symbol}",
+    statements: "/api/financial-statements/{symbol}",
+});
+export const FUNDAMENTAL_KINDS = Object.keys(FUNDAMENTALS).sort();
+/** Startup invariant: every hand-written template above is really in scope. */
+export function assertDerivedTablesAreSound() {
+    if (FLOW_ENDPOINTS.length === 0) {
+        throw new Error("no /api/flow/* routes in SCOPED_PATHS — get_flow would advertise an empty " +
+            "enum. Regenerate scopes.ts (python3 scripts/check_mcp_scopes.py --write).");
+    }
+    const scoped = new Set(SCOPED_PATHS);
+    for (const [kind, template] of Object.entries(FUNDAMENTALS)) {
+        if (!scoped.has(template)) {
+            throw new Error(`get_fundamentals kind '${kind}' maps to '${template}', which is not a ` +
+                `CLI-token GET scope. Either the route was renamed or the scope was ` +
+                `dropped; both make the tool 403/404 silently.`);
+        }
+    }
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Argument validation
+// ─────────────────────────────────────────────────────────────────────────────
+//
+// The low-level MCP server does not validate `arguments` against a tool's
+// declared `inputSchema` — it hands them through as received. So the schema the
+// agent sees would be decorative unless something enforced it, and "decorative
+// schema" is how a symbol argument becomes a path segment.
+//
+// This is deliberately NOT a general JSON Schema engine. It covers exactly what
+// these twelve tools declare, and refuses anything it cannot check.
+export class ToolArgumentError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ToolArgumentError";
+    }
+}
+export function validateArgs(spec, raw) {
+    const schema = spec.inputSchema;
+    const out = {};
+    for (const key of Object.keys(raw)) {
+        if (!(key in schema.properties)) {
+            throw new ToolArgumentError(`${spec.name}: unknown argument '${key}'. Accepted: ` +
+                `${Object.keys(schema.properties).join(", ") || "(none)"}.`);
+        }
+    }
+    for (const [key, prop] of Object.entries(schema.properties)) {
+        // `null` reads as "omitted", matching the Python dispatcher, which stripped
+        // None values so a defaulted optional was indistinguishable from an unset
+        // one — otherwise an explicit null becomes an empty query param.
+        const value = raw[key];
+        if (value === undefined || value === null)
+            continue;
+        switch (prop.type) {
+            case "string": {
+                if (typeof value !== "string") {
+                    throw new ToolArgumentError(`${spec.name}: '${key}' must be a string`);
+                }
+                if (prop.enum && !prop.enum.includes(value)) {
+                    throw new ToolArgumentError(`${spec.name}: '${key}' must be one of: ${prop.enum.join(", ")} (got '${value}')`);
+                }
+                out[key] = value;
+                break;
+            }
+            case "integer":
+            case "number": {
+                const n = typeof value === "number" ? value : Number(value);
+                if (!Number.isFinite(n)) {
+                    throw new ToolArgumentError(`${spec.name}: '${key}' must be a number`);
+                }
+                if (prop.type === "integer" && !Number.isInteger(n)) {
+                    throw new ToolArgumentError(`${spec.name}: '${key}' must be a whole number`);
+                }
+                if (prop.minimum !== undefined && n < prop.minimum) {
+                    throw new ToolArgumentError(`${spec.name}: '${key}' must be >= ${prop.minimum}`);
+                }
+                if (prop.maximum !== undefined && n > prop.maximum) {
+                    throw new ToolArgumentError(`${spec.name}: '${key}' must be <= ${prop.maximum}`);
+                }
+                out[key] = n;
+                break;
+            }
+            case "boolean": {
+                if (typeof value !== "boolean") {
+                    throw new ToolArgumentError(`${spec.name}: '${key}' must be true or false`);
+                }
+                out[key] = value;
+                break;
+            }
+            case "object": {
+                if (typeof value !== "object" || Array.isArray(value)) {
+                    throw new ToolArgumentError(`${spec.name}: '${key}' must be an object of query params`);
+                }
+                out[key] = value;
+                break;
+            }
+            case "array": {
+                if (!Array.isArray(value)) {
+                    throw new ToolArgumentError(`${spec.name}: '${key}' must be an array`);
+                }
+                out[key] = value;
+                break;
+            }
+        }
+    }
+    for (const key of schema.required ?? []) {
+        if (out[key] === undefined) {
+            throw new ToolArgumentError(`${spec.name}: '${key}' is required`);
+        }
+    }
+    return out;
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Small helpers used by the specs
+// ─────────────────────────────────────────────────────────────────────────────
+function str(args, key) {
+    const v = args[key];
+    if (typeof v !== "string")
+        throw new ToolArgumentError(`'${key}' is required`);
+    return v;
+}
+function upper(args, key) {
+    return str(args, key).toUpperCase();
+}
+/** Copy only the keys the caller actually supplied, under their wire names. */
+function pick(args, mapping) {
+    const out = {};
+    for (const [argKey, wireKey] of Object.entries(mapping)) {
+        const v = args[argKey];
+        if (v === undefined || v === null)
+            continue;
+        if (typeof v === "string" || typeof v === "number" || typeof v === "boolean") {
+            out[wireKey] = v;
+        }
+    }
+    return out;
+}
+/** A free-form `params` object from the agent, flattened for a query string. */
+function queryFrom(value) {
+    if (value === undefined || value === null)
+        return {};
+    if (typeof value !== "object" || Array.isArray(value)) {
+        throw new ToolArgumentError("'params' must be an object, e.g. {\"ticker\": \"SPY\"}");
+    }
+    const out = {};
+    for (const [k, v] of Object.entries(value)) {
+        if (v === undefined || v === null)
+            continue;
+        if (typeof v === "string" || typeof v === "number" || typeof v === "boolean") {
+            out[k] = v;
+        }
+        else if (Array.isArray(v) && v.every((x) => ["string", "number", "boolean"].includes(typeof x))) {
+            out[k] = v;
+        }
+        else {
+            throw new ToolArgumentError(`params.${k} must be a string, number, boolean or a list of those`);
+        }
+    }
+    return out;
+}
+const SYMBOL = { type: "string", description: "Ticker, e.g. AAPL" };
+// ─────────────────────────────────────────────────────────────────────────────
+// The tools
+// ─────────────────────────────────────────────────────────────────────────────
+export const TOOLS = [
+    {
+        name: "get_quote",
+        description: "Get a real-time quote for a stock symbol (price, change, volume).",
+        inputSchema: {
+            type: "object",
+            properties: { symbol: SYMBOL },
+            required: ["symbol"],
+            additionalProperties: false,
+        },
+        routes: ["GET /api/quote/{symbol}"],
+        plan: (a) => ({ route: "GET /api/quote/{symbol}", params: { symbol: upper(a, "symbol") } }),
+    },
+    {
+        name: "get_bars",
+        description: "OHLCV bars for a ticker. Use `interval` for the bar size and either " +
+            "`range_code` (e.g. 1M, 6M, 1Y) or an explicit start_date/end_date pair " +
+            "(YYYY-MM-DD).",
+        inputSchema: {
+            type: "object",
+            properties: {
+                ticker: SYMBOL,
+                interval: { type: "string", description: "Bar size, e.g. 1Day, 1Hour, 1Min", default: "1Day" },
+                range_code: { type: "string", description: "Relative window, e.g. 1M, 6M, 1Y" },
+                start_date: { type: "string", description: "YYYY-MM-DD (sent as `from`)" },
+                end_date: { type: "string", description: "YYYY-MM-DD (sent as `to`)" },
+                limit: { type: "integer", description: "Max bars (1-50000)", minimum: 1, maximum: 50000 },
+            },
+            required: ["ticker"],
+            additionalProperties: false,
+        },
+        routes: ["GET /api/chart/pricing-data"],
+        // The API's parameters are `from` and `to`. The Python tool exposed
+        // start_date/end_date because `from` cannot be a Python parameter name; the
+        // names are kept here so the two servers present the same tool to the agent.
+        plan: (a) => ({
+            route: "GET /api/chart/pricing-data",
+            query: {
+                ticker: upper(a, "ticker"),
+                interval: typeof a["interval"] === "string" ? a["interval"] : "1Day",
+                ...pick(a, { range_code: "range_code", start_date: "from", end_date: "to", limit: "limit" }),
+            },
+        }),
+    },
+    {
+        name: "get_option_series",
+        description: "Price series for ONE option contract, by OCC symbol. " +
+            "NOTE: there is deliberately no full-chain tool - building a chain " +
+            "opens a live subscription per expiration, which is why " +
+            "/api/options/{symbol} is denied to this credential.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                occ_symbol: { type: "string", description: "OCC symbol, e.g. SPY241220C00500000" },
+                interval: { type: "string", default: "1Day" },
+                range_code: { type: "string" },
+            },
+            required: ["occ_symbol"],
+            additionalProperties: false,
+        },
+        routes: ["GET /api/options/chart-pricing"],
+        plan: (a) => ({
+            route: "GET /api/options/chart-pricing",
+            query: {
+                occ_symbol: upper(a, "occ_symbol"),
+                interval: typeof a["interval"] === "string" ? a["interval"] : "1Day",
+                ...pick(a, { range_code: "range_code" }),
+            },
+        }),
+    },
+    {
+        name: "get_flow",
+        description: "Unusual Whales options-flow and market-structure data. One of: " +
+            FLOW_ENDPOINTS.join(", ") +
+            '. `params` is a dict of query params, e.g. {"ticker": "SPY"}.',
+        inputSchema: {
+            type: "object",
+            properties: {
+                endpoint: { type: "string", enum: FLOW_ENDPOINTS },
+                params: { type: "object", description: 'Query params, e.g. {"ticker": "SPY"}' },
+            },
+            required: ["endpoint"],
+            additionalProperties: false,
+        },
+        // Twenty concrete routes, not one `/api/flow/{endpoint}` template. The Rust
+        // list enumerates them individually, so enumerating them here keeps the
+        // checker's comparison exact rather than shape-based.
+        routes: FLOW_ENDPOINTS.map((e) => `GET /api/flow/${e}`),
+        plan: (a) => ({
+            route: `GET /api/flow/${str(a, "endpoint")}`,
+            query: queryFrom(a["params"]),
+        }),
+    },
+    {
+        name: "get_fundamentals",
+        description: "Company fundamentals. `kind` is one of: " + FUNDAMENTAL_KINDS.join(", ") + ".",
+        inputSchema: {
+            type: "object",
+            properties: {
+                kind: { type: "string", enum: FUNDAMENTAL_KINDS },
+                symbol: SYMBOL,
+            },
+            required: ["kind", "symbol"],
+            additionalProperties: false,
+        },
+        routes: [
+            "GET /api/company/profile/{symbol}",
+            "GET /api/earnings/{symbol}",
+            "GET /api/earnings/{symbol}/uw",
+            "GET /api/ratios/{symbol}",
+            "GET /api/financial-statements/{symbol}",
+        ],
+        plan: (a) => {
+            const template = FUNDAMENTALS[str(a, "kind")];
+            if (!template) {
+                throw new ToolArgumentError(`unknown kind. One of: ${FUNDAMENTAL_KINDS.join(", ")}`);
+            }
+            return { route: `GET ${template}`, params: { symbol: upper(a, "symbol") } };
+        },
+    },
+    {
+        name: "search_research",
+        description: "Search the Symbols research corpus (papers, repos, resources).",
+        inputSchema: {
+            type: "object",
+            properties: {
+                q: { type: "string", description: "Free-text query" },
+                tags: { type: "string", description: "Comma-separated tag filter" },
+                limit: { type: "integer", minimum: 1, maximum: 100, default: 10 },
+            },
+            required: ["q"],
+            additionalProperties: false,
+        },
+        routes: ["GET /api/research/papers/search"],
+        plan: (a) => ({
+            route: "GET /api/research/papers/search",
+            query: {
+                q: str(a, "q"),
+                limit: typeof a["limit"] === "number" ? a["limit"] : 10,
+                ...pick(a, { tags: "tags" }),
+            },
+        }),
+    },
+    {
+        name: "list_regimes",
+        description: "List the current user's deployed trading regimes.",
+        inputSchema: { type: "object", properties: {}, additionalProperties: false },
+        routes: ["GET /api/regimes"],
+        plan: () => ({ route: "GET /api/regimes" }),
+    },
+    {
+        name: "get_regime",
+        description: "One regime with its executions, trades and stats.",
+        inputSchema: {
+            type: "object",
+            properties: { regime_id: { type: "string" } },
+            required: ["regime_id"],
+            additionalProperties: false,
+        },
+        routes: ["GET /api/regimes/{regime_id}/with-stats"],
+        plan: (a) => ({
+            route: "GET /api/regimes/{regime_id}/with-stats",
+            params: { regime_id: str(a, "regime_id") },
+        }),
+    },
+    {
+        name: "get_backtest_result",
+        description: "Fetch a backtest (or any execution) with its trades and status by " +
+            "execution id. A running backtest returns status='running' with no " +
+            "trades yet - poll until it is 'success' or 'error'. " +
+            "NOTE: this CLI can READ a run but cannot START one; deploy and backtest " +
+            "are done from the app.",
+        inputSchema: {
+            type: "object",
+            properties: { execution_id: { type: "string" } },
+            required: ["execution_id"],
+            additionalProperties: false,
+        },
+        routes: ["GET /api/regime-executions/{execution_id}/with-trades"],
+        plan: (a) => ({
+            route: "GET /api/regime-executions/{execution_id}/with-trades",
+            params: { execution_id: str(a, "execution_id") },
+        }),
+    },
+    {
+        name: "get_brokerage",
+        description: "The user's Alpaca account: buying power, equity, open positions, " +
+            "working orders - plus `policy`, which states the account's current " +
+            "agent-trading limits (the notional cap and the order budgets). " +
+            "Use it to SIZE and EXPLAIN a trade idea. " +
+            "⚠ This CLI cannot place or cancel orders - there is no such tool, by " +
+            "design. Orders are placed by the user in the Symbols app. " +
+            "Returns 403 if the user has not enabled brokerage access in " +
+            "Settings -> Connections.",
+        inputSchema: { type: "object", properties: {}, additionalProperties: false },
+        routes: ["GET /api/odin-code/brokerage/snapshot"],
+        plan: () => ({ route: "GET /api/odin-code/brokerage/snapshot" }),
+    },
+    {
+        name: "get_trade_history",
+        description: "How the user has actually been TRADING, as opposed to what they hold " +
+            "right now: individual fills, closed orders, and the account equity " +
+            "curve over the same window. This is the tool for questions like " +
+            "'how did I do on my last few trades'. " +
+            "`days` defaults to 30 (max 365); `limit` is rows per section. " +
+            "Note `portfolio_history` is account equity over time, so it also moves " +
+            "with deposits and withdrawals - derive realised P&L from `fills`.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                days: { type: "integer", minimum: 1, maximum: 365, default: 30 },
+                limit: { type: "integer", minimum: 1, maximum: 1000, default: 100 },
+            },
+            additionalProperties: false,
+        },
+        routes: ["GET /api/odin-code/brokerage/history"],
+        plan: (a) => ({
+            route: "GET /api/odin-code/brokerage/history",
+            query: {
+                days: typeof a["days"] === "number" ? a["days"] : 30,
+                limit: typeof a["limit"] === "number" ? a["limit"] : 100,
+            },
+        }),
+    },
+    {
+        name: "api_get",
+        description: "Generic READ of any allow-listed Symbols API path — levels, " +
+            "sparklines, batch quotes, scan catalog/presets/sectors, research " +
+            "tags/graph/stats/document, regime trades and executions, feed " +
+            "status, tracked tickers, and your notebook/project files. Pass a " +
+            "CONCRETE path (e.g. /api/levels/AAPL) and query params separately. " +
+            "GET only; paths off the allow-list are refused with the permitted " +
+            "families listed. Prefer the dedicated tools where one exists - they " +
+            "document their params; this door is for everything scoped but not " +
+            "wrapped.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                path: {
+                    type: "string",
+                    description: "Concrete API path, e.g. /api/levels/AAPL - no query string",
+                },
+                params: { type: "object", description: "Query params, passed separately" },
+            },
+            required: ["path"],
+            additionalProperties: false,
+        },
+        // No declared route: this is the ONE door where the caller chooses the path.
+        // It is not unchecked — `dispatch` runs `templateOk` against the whole of
+        // SCOPED_PATHS, which is the same list the checker proves equals the Rust
+        // allowlist. So a path that passes here is exactly as checked as a literal.
+        routes: [],
+        dynamic: true,
+        plan: (a) => ({ dynamicPath: str(a, "path"), query: queryFrom(a["params"]) }),
+    },
+];
+export const TOOL_COUNT = TOOLS.length;
+/**
+ * The count the server refuses to start without.
+ *
+ * ⚠ Not decoration. The Python server died AT IMPORT when `mcp` 2.0 removed the
+ * 1.x decorators; it kept answering the MCP handshake, registered nothing, and
+ * every Symbols tool silently vanished for the agent. A server that starts
+ * healthy and exposes zero tools is the worst failure mode this component has,
+ * because it is indistinguishable from "the user has no Symbols access".
+ *
+ * Bumping this number is how you add a tool. That is the point.
+ */
+export const EXPECTED_TOOL_COUNT = 12;
+export function toolByName(name) {
+    return TOOLS.find((t) => t.name === name);
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Dispatch
+// ─────────────────────────────────────────────────────────────────────────────
+/** How long a single tool call may wait on the API. Matches the Python client. */
+export const TOOL_TIMEOUT_MS = 15_000;
+/**
+ * Turn a validated argument set into the exact request this tool will make.
+ *
+ * Exported and pure, so a test can assert every tool's declared route against
+ * the bytes it produces without a network. That round-trip is what makes the
+ * `routes:` declarations a contract rather than a comment.
+ */
+export function resolveRequest(spec, args) {
+    const planned = spec.plan(args);
+    let method;
+    let path;
+    if ("dynamicPath" in planned) {
+        if (spec.dynamic !== true) {
+            // Unreachable through TOOLS as written; kept because the day someone adds
+            // a second dynamic planner without the flag, this is the difference
+            // between a refusal and an unchecked caller-controlled path.
+            throw new Error(`${spec.name} returned a dynamic path but is not the dynamic door`);
+        }
+        method = "GET";
+        path = planned.dynamicPath;
+    }
+    else {
+        if (!spec.routes.includes(planned.route)) {
+            throw new Error(`${spec.name} planned route '${planned.route}', which it does not declare. ` +
+                `Declared: ${spec.routes.join(", ") || "(none)"}. The declaration is what ` +
+                `check_mcp_scopes.py verifies, so an undeclared route is an unchecked one.`);
+        }
+        const { method: m, template } = splitRoute(planned.route);
+        method = m;
+        path = buildPath(template, planned.params ?? {});
+    }
+    if (method !== "GET") {
+        // v1 is read-only. See P5_SEAM.
+        throw new Error(`${spec.name} planned a ${method}, but this CLI ships read tools only in v1. ` +
+            `Write tools land in P5 behind the armed window.`);
+    }
+    if (!templateOk(path)) {
+        throw new ScopeRefusal(path);
+    }
+    const qs = toQueryString(planned.query ?? {});
+    return { method, path: qs ? `${path}?${qs}` : path };
+}
+export class ScopeRefusal extends Error {
+    attempted;
+    constructor(attempted) {
+        super(`Path '${attempted}' is not on the read allow-list.`);
+        this.attempted = attempted;
+        this.name = "ScopeRefusal";
+    }
+}
+function toQueryString(query) {
+    const sp = new URLSearchParams();
+    for (const [k, v] of Object.entries(query)) {
+        if (Array.isArray(v)) {
+            for (const item of v)
+                sp.append(k, String(item));
+        }
+        else {
+            sp.append(k, String(v));
+        }
+    }
+    return sp.toString();
+}
+/**
+ * Run one tool and return the value the agent sees.
+ *
+ * ⚠ A TOOL MUST ANSWER, NOT THROW. Carried from the Python server: an exception
+ * escaping here would surface to the agent as a transport failure, which reads
+ * as "this tool is broken" — the same indistinguishable-from-dead state the
+ * scope drift produced. Every refusal is returned as data with an explanation
+ * the agent can act on.
+ */
+export async function callTool(name, rawArgs) {
+    const spec = toolByName(name);
+    if (!spec)
+        return { error: `Unknown tool: ${name}` };
+    let resolved;
+    try {
+        resolved = resolveRequest(spec, validateArgs(spec, rawArgs));
+    }
+    catch (err) {
+        if (err instanceof ScopeRefusal) {
+            return {
+                error: err.message,
+                hint: "Concrete path, no query string — pass params separately.",
+                allowed_families: allowedFamilies(),
+            };
+        }
+        return { error: err instanceof Error ? err.message : String(err) };
+    }
+    try {
+        const res = await request(resolved.path, {
+            method: resolved.method,
+            signal: AbortSignal.timeout(TOOL_TIMEOUT_MS),
+        });
+        return res.body;
+    }
+    catch (err) {
+        if (err instanceof NotLoggedInError) {
+            return { error: "Not signed in. Run `symbols login` in a terminal, then retry." };
+        }
+        if (err instanceof ApiError) {
+            // A 403 on a brokerage read is a real answer — the user has not opted in —
+            // so say which door was closed rather than flattening it to a status code.
+            const extra = err.status === 403 && resolved.path.startsWith("/api/odin-code/brokerage/")
+                ? " (enable brokerage access in Settings -> Connections)"
+                : "";
+            return { error: `HTTP ${err.status}: ${err.message}${extra}` };
+        }
+        return { error: err instanceof Error ? err.message : String(err) };
+    }
+}