@bevel-software/platform-core-backend 0.1.0

package/dist/modules/tool-manuals/tool-manuals.service.js

@@ -0,0 +1,710 @@
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import { parse as parseYaml } from 'yaml';
+import '@utcp/http'; // side effect: register the 'http' call-template type (http + inline sub-manuals)
+import '@utcp/mcp'; // side effect: register the 'mcp' call-template type (mcp `.tool` sources)
+import { UtcpManualSerializer, CallTemplateSerializer, DefaultVariableSubstitutor, } from '@utcp/sdk';
+import { DEFAULT_BRANCH, TOOLS_DIR } from '@bevel-software/platform-shared';
+import { workspaceIdForBranch } from '../workspace/workspace.service.js';
+import { assertSafeFetchUrl } from '../../shared/ssrf.js';
+import { extractFrontmatter, resolveDeclaredId, isValidId, dedupeById } from '../../shared/frontmatter-id.js';
+import { walkFiles } from '../../shared/fs-walk.js';
+import { TtlCache } from '../../shared/ttl-cache.js';
+import { utcpNamespacePrefix, utcpNamespacedKey, MCP_OAUTH_VAR, INTERNAL_MANUAL_NAME, } from '../../shared/utcp-namespace.js';
+import { EXTERNAL_KB_MANUAL_NAME, } from './tool-manuals.contract.js';
+const CACHE_TTL_MS = 60_000;
+/**
+ * UTCP namespaces a user `.tool` may NOT claim: they belong to built-in manuals
+ * whose loopback creds are pre-seeded on the agent's code-mode client (the
+ * internal `Bevel` manual carries the `source:'internal'` token + connector
+ * creds; the external KB manual carries the caller's bearer). A `.tool`
+ * reproducing one of these namespaces would resolve those seeded vars and could
+ * exfiltrate them, so the scanner refuses it. Compared case-insensitively —
+ * defensive, though the live collision is the mixed-case `Bevel` reachable via
+ * the `name` fallback (an explicit `id` must already be lowercase snake_case).
+ */
+const RESERVED_TOOL_NAMESPACES = [INTERNAL_MANUAL_NAME, EXTERNAL_KB_MANUAL_NAME].map((n) => n.toLowerCase());
+/**
+ * Variable names the platform seeds for its own (Bevel-hosted) manuals:
+ * `<ns>_API_URL` points a manual at the backend and `<ns>_CONNECTION_KEY`
+ * carries the platform bearer. No user `.tool` may REFERENCE them
+ * (`${API_URL}` / `$API_URL`), in any `.tool` type: the only seeded user
+ * namespace is an inline `.tool`'s (its discovery template is platform-served),
+ * and a reference inside author-written content would resolve platform creds
+ * into a request the author shaped. Refusing every `.tool` at the producing
+ * boundary makes "user tools never carry platform credentials" structural
+ * rather than dependent on which namespaces happen to be seeded.
+ */
+const RESERVED_VARIABLE_NAMES = ['API_URL', 'CONNECTION_KEY'];
+/** The SDK substitutor's reference grammar, exactly: `${VAR}` or `$VAR`. */
+const VARIABLE_REFERENCE_RE = /\$\{([a-zA-Z0-9_]+)\}|\$([a-zA-Z0-9_]+)/g;
+/**
+ * A REFERENCE is reserved by SUFFIX, not by exact name: the substitutor looks a
+ * variable up under the manual's UTCP namespace first, so `${<ns>_CONNECTION_KEY}`
+ * resolves the very same seeded value the bare `${CONNECTION_KEY}` does. Matching
+ * the bare name only would let a `.tool` reach the platform bearer just by
+ * spelling the namespace out. Suffix matching also refuses harmless-looking
+ * near-misses (`MY_API_URL`) — deliberately fail-closed: a `.tool` author who
+ * wants their own base URL has the whole namespace minus two suffixes.
+ */
+function isReservedVariableRef(varName) {
+    return RESERVED_VARIABLE_NAMES.some((reserved) => varName.endsWith(reserved));
+}
+/** Throw if any string in the `.tool` document references a reserved variable. */
+function assertNoReservedVariableRefs(doc, name) {
+    const text = JSON.stringify(doc) ?? '';
+    for (const match of text.matchAll(VARIABLE_REFERENCE_RE)) {
+        const varName = match[1] ?? match[2];
+        if (isReservedVariableRef(varName)) {
+            throw new Error(`\`.tool\` "${name}" references the reserved variable "${match[0]}" — ` +
+                'API_URL and CONNECTION_KEY (bare or namespaced, e.g. `<namespace>_CONNECTION_KEY`) ' +
+                'are seeded by the platform for its own manuals and may not appear anywhere in a `.tool`.');
+        }
+    }
+}
+const manualSerializer = new UtcpManualSerializer();
+const callTemplateSerializer = new CallTemplateSerializer();
+// `findRequiredVariables` is a pure walk — one shared instance is fine.
+const variableSubstitutor = new DefaultVariableSubstitutor();
+/**
+ * Reads `*.tool` manuals from the DEFAULT-branch workspace (never the caller's
+ * branch), so the catalog is one global, released set — same discipline as
+ * Skills. Results are cached briefly; drop via `invalidate()` after a merge to
+ * default. Any read failure degrades to an empty catalog: the MCP/UTCP endpoint
+ * must never break because a `.tool` can't be read.
+ */
+export class ToolManualService {
+    workspaceService;
+    accessControl;
+    kbDirName;
+    cache;
+    mcpAuthDiscovery;
+    constructor(workspaceService, accessControl, kbDirName, now = Date.now) {
+        this.workspaceService = workspaceService;
+        this.accessControl = accessControl;
+        this.kbDirName = kbDirName;
+        this.cache = new TtlCache(CACHE_TTL_MS, now);
+    }
+    /**
+     * Wire the MCP OAuth auto-discovery (setter injection: the discovery service
+     * depends on the vault, which is constructed after this service — the same
+     * reason the vault takes `scopeOfVariable` as a closure). Optional: without
+     * it, bare `type: mcp` tools simply aren't decorated.
+     */
+    setMcpAuthDiscovery(discovery) {
+        this.mcpAuthDiscovery = discovery;
+    }
+    invalidate() {
+        this.cache.invalidate();
+    }
+    async listAccessible(userEmail) {
+        const manuals = await this.accessibleManuals(userEmail);
+        return manuals.map((m) => ({
+            slug: m.slug,
+            name: m.name,
+            path: m.path,
+            type: m.type,
+            variables: m.variables,
+            remote: m.remote,
+            setup: m.setup,
+        }));
+    }
+    async listLocalOnly(userEmail) {
+        const manuals = await this.accessibleManuals(userEmail);
+        return manuals.filter((m) => m.remote === false).map((m) => ({ name: m.name, path: m.path }));
+    }
+    async userScopedKeysForManual(manualName) {
+        // The per-user (`user`-scoped) variables a manual declares, keyed the SAME
+        // way the vault stores them — the UTCP-namespaced key (underscores in the
+        // manual name doubled), so a readiness check reads the exact rows `resolve`
+        // would. `oauth` lets the pre-check treat a not-yet-authorized sign-in as
+        // still-missing.
+        const manual = (await this.scan()).find((m) => m.name === manualName);
+        return (manual?.variables ?? [])
+            .filter((v) => v.scope === 'user')
+            .map((v) => ({
+            key: utcpNamespacedKey(manualName, v.name),
+            name: v.name,
+            label: v.label ?? null,
+            oauth: v.oauth != null,
+            // The permissions the tool declares RIGHT NOW — the pre-check compares these
+            // against the caller's granted scopes to catch a token that predates a scope
+            // addition. Read live so a `.tool` edit self-heals on the next call.
+            oauthScopes: v.oauth?.scopes,
+        }));
+    }
+    async scopeOfVariable(effectiveKey) {
+        // UTCP looks up `<namespace-with-doubled-underscores>_<VAR>`. Find the manual
+        // whose namespace prefixes this key; the declared var is the remainder. Match
+        // the LONGEST prefix so a manual `a` can't shadow `a_b` when both exist. (A
+        // plain first-underscore split would mis-parse a snake_case manual name.)
+        let best = null;
+        for (const m of await this.scan()) {
+            const prefix = utcpNamespacePrefix(m.name);
+            if (effectiveKey.startsWith(prefix) && (!best || prefix.length > best.len)) {
+                best = { manual: m, varName: effectiveKey.slice(prefix.length), len: prefix.length };
+            }
+        }
+        if (!best)
+            return 'admin';
+        const declared = best.manual.variables?.find((v) => v.name === best.varName);
+        return declared?.scope ?? 'admin';
+    }
+    async toManualCallTemplates(userEmail, opts) {
+        const manuals = await this.accessibleManuals(userEmail);
+        const out = [];
+        for (const m of manuals) {
+            // Remote consumers (the hosted MCP proxy) don't get local-only manuals —
+            // they'd fail server-side. Discovery of them happens via `list_local_tools`.
+            if (opts?.remoteOnly && m.remote === false)
+                continue;
+            try {
+                out.push(callTemplateSerializer.validateDict(this.buildCallTemplateDict(m)));
+            }
+            catch (err) {
+                // A `.tool` that produces an invalid call-template is dropped here — at
+                // the producing boundary — so the served list is always valid.
+                console.warn(`[tool-manuals] skipping "${m.path}": ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        return out;
+    }
+    async resolveInlineManual(userEmail, slug) {
+        const found = (await this.scan()).find((m) => m.slug === slug);
+        if (!found || found.type !== 'inline')
+            return null;
+        const wsId = workspaceIdForBranch(DEFAULT_BRANCH);
+        if (!(await this.accessControl.canRead(wsId, userEmail, found.path)))
+            return null;
+        try {
+            return manualSerializer.validateDict({
+                utcp_version: '1.1.0',
+                manual_version: '1.0.0',
+                tools: found.tools ?? [],
+            });
+        }
+        catch {
+            return null;
+        }
+    }
+    async preview(content) {
+        let descriptor;
+        try {
+            descriptor = normalizeToolManual('draft', 'Tools/draft.tool', content);
+        }
+        catch (err) {
+            return { ok: false, errors: [err instanceof Error ? err.message : String(err)] };
+        }
+        if (descriptor.type === 'inline') {
+            try {
+                const manual = manualSerializer.validateDict({
+                    utcp_version: '1.1.0',
+                    manual_version: '1.0.0',
+                    tools: descriptor.tools ?? [],
+                });
+                const tools = (manual.tools ?? []).map((t) => ({
+                    name: String(t.name ?? ''),
+                    description: typeof t.description === 'string' ? t.description : undefined,
+                }));
+                return { ok: true, tools };
+            }
+            catch (err) {
+                return { ok: false, errors: [err instanceof Error ? err.message : String(err)] };
+            }
+        }
+        // http / mcp resolve their tools at runtime (a network round-trip we don't
+        // perform in preview), but still validate the call-template the same way
+        // `toManualCallTemplates` does, so a draft that discovery would reject is
+        // reported here instead of appearing valid.
+        try {
+            callTemplateSerializer.validateDict(this.buildCallTemplateDict(descriptor));
+        }
+        catch (err) {
+            return { ok: false, errors: [err instanceof Error ? err.message : String(err)] };
+        }
+        return { ok: true, tools: [] };
+    }
+    // --- internal --------------------------------------------------------------
+    /** Build the raw UTCP manual call-template dict for one descriptor (validated by the caller). */
+    buildCallTemplateDict(m) {
+        if (m.type === 'inline') {
+            return {
+                name: m.name,
+                call_template_type: 'http',
+                http_method: 'GET',
+                url: `\${API_URL}/api/tools/${m.slug}/manual`,
+                content_type: 'application/json',
+                headers: { Authorization: 'Bearer ${CONNECTION_KEY}' },
+            };
+        }
+        if (m.type === 'mcp') {
+            // Remote (HTTP/streamable) MCP server. Exact plugin field shape is
+            // finalized in Phase 4 (native `@utcp/mcp`); the proxy try/catches
+            // registration so an unsupported template never breaks the session.
+            return {
+                name: m.name,
+                call_template_type: 'mcp',
+                config: {
+                    mcpServers: {
+                        [m.name]: {
+                            transport: 'http',
+                            url: m.url,
+                            ...(m.headers ? { headers: m.headers } : {}),
+                        },
+                    },
+                },
+            };
+        }
+        // http: a URL returning a UTCP manual.
+        return {
+            name: m.name,
+            call_template_type: 'http',
+            http_method: m.httpMethod ?? 'GET',
+            url: m.url,
+            content_type: 'application/json',
+            ...(m.headers ? { headers: m.headers } : {}),
+        };
+    }
+    async accessibleManuals(userEmail) {
+        const manuals = await this.scan();
+        if (manuals.length === 0)
+            return [];
+        const wsId = workspaceIdForBranch(DEFAULT_BRANCH);
+        const allowed = await this.accessControl.canReadBatch(wsId, userEmail, manuals.map((m) => m.path));
+        // Fail closed: keep a manual only on an explicit `true` verdict (a missing
+        // entry is treated as denied, matching the KB's default-deny read model).
+        return manuals.filter((m) => allowed.get(m.path) === true);
+    }
+    async scan() {
+        const cached = this.cache.get();
+        if (cached)
+            return cached;
+        const manuals = await this.scanDisk();
+        await this.decorateMcpOAuth(manuals);
+        // AFTER the oauth decoration, so an injected `${MCP_OAUTH}` header ref is
+        // already declared and isn't re-surfaced as a bare admin key.
+        for (const m of manuals)
+            this.surfaceReferencedVariables(m);
+        this.cache.set(manuals);
+        return manuals;
+    }
+    /**
+     * Auto-surface every `${VAR}` a manual actually references, for ANY tool
+     * type — using UTCP's own required-variables walk, so the surfaced list
+     * can't drift from what substitution will demand at registration/call time.
+     * Referenced-but-undeclared vars become `scope: admin` entries (matching
+     * `scopeOfVariable`'s default for undeclared keys), which puts them in the
+     * secrets UI without the author having to write a `variables:` block. The
+     * block stays the way to add metadata: `scope: user`, labels, oauth.
+     */
+    surfaceReferencedVariables(m) {
+        let refs;
+        try {
+            refs = variableSubstitutor.findRequiredVariables(this.buildCallTemplateDict(m), m.name);
+            // An inline manual's credential refs live in its embedded tools'
+            // templates, not the (Bevel-hosted) discovery template.
+            if (m.type === 'inline' && m.tools) {
+                refs.push(...variableSubstitutor.findRequiredVariables(m.tools, m.name));
+            }
+        }
+        catch {
+            return; // a malformed template is reported elsewhere; never break the scan
+        }
+        const prefix = utcpNamespacePrefix(m.name);
+        const declared = new Set((m.variables ?? []).map((v) => v.name));
+        for (const ref of new Set(refs)) {
+            if (!ref.startsWith(prefix))
+                continue;
+            const name = ref.slice(prefix.length);
+            // Reserved names are seeded by the proxy per session — not credentials.
+            if (name === 'API_URL' || name === 'CONNECTION_KEY' || declared.has(name))
+                continue;
+            m.variables = [...(m.variables ?? []), { name, scope: 'admin' }];
+        }
+    }
+    /**
+     * Zero-config OAuth for bare `type: mcp` manuals: when discovery finds the
+     * remote server demands OAuth (and the file doesn't configure auth itself),
+     * decorate the descriptor with a synthetic user-scoped `MCP_OAUTH` variable
+     * and an `Authorization: Bearer ${MCP_OAUTH}` header. Decorating HERE — the
+     * one place descriptors are built — means every consumer inherits it:
+     * /connect lists the sign-in, `scopeOfVariable` resolves it per-user,
+     * `userScopedKeysForManual` gates unauthorized callers, and the call
+     * template carries the header for the variable loader to fill.
+     */
+    async decorateMcpOAuth(manuals) {
+        const discovery = this.mcpAuthDiscovery;
+        if (!discovery)
+            return;
+        const eligible = manuals.filter((m) => {
+            if (m.type !== 'mcp' || !m.url)
+                return false;
+            // Local-only servers aren't probeable from here; templated URLs aren't
+            // resolvable without a caller. Both keep their file-declared behavior.
+            if (m.remote === false || m.url.includes('${'))
+                return false;
+            // The file configures auth itself — explicit wins over discovery.
+            const hasAuthHeader = Object.keys(m.headers ?? {}).some((h) => h.toLowerCase() === 'authorization');
+            const hasOAuthVar = (m.variables ?? []).some((v) => v.oauth != null);
+            return !hasAuthHeader && !hasOAuthVar;
+        });
+        // Probe every eligible server CONCURRENTLY — a cold scan with several bare
+        // mcp tools shouldn't pay one network round-trip per tool in series. The
+        // mutation still happens per-manual after its own probe settles.
+        await Promise.all(eligible.map(async (m) => {
+            try {
+                const found = await discovery.statusFor(m.name, m.url);
+                // Record the setup requirement so the secrets UI can tell an admin
+                // whether anything needs configuring — especially the `unsupported`
+                // case, which otherwise only surfaced in server logs.
+                if (found.status === 'open') {
+                    m.setup = { kind: 'open' };
+                    return;
+                }
+                if (found.status === 'unsupported') {
+                    m.setup = { kind: 'oauth-manual', reason: found.reason };
+                    return;
+                }
+                m.setup = { kind: 'oauth-auto' };
+                m.headers = { ...(m.headers ?? {}), Authorization: `Bearer \${${MCP_OAUTH_VAR}}` };
+                m.variables = [
+                    ...(m.variables ?? []),
+                    {
+                        name: MCP_OAUTH_VAR,
+                        scope: 'user',
+                        label: `${m.name} sign-in`,
+                        // NO `scopes` here, deliberately. A variable's declared scopes are
+                        // REQUIRED back from the token (needsReauth + the call-time gate),
+                        // which is right for file-authored scopes but not for discovery's
+                        // machine-guessed ones (the PRM's `scopes_supported`): providers
+                        // don't reliably echo them (e.g. Granola's AS grants OIDC scopes
+                        // instead), which would permanently flag-and-block an authorized
+                        // sign-in. The shared provider row still carries them, so the
+                        // authorize request itself is unchanged; an under-scoped token
+                        // simply 401s at call time and re-enters auth there.
+                        oauth: {
+                            authorizationUrl: found.provider.authorizationUrl,
+                            tokenUrl: found.provider.tokenUrl,
+                            clientId: found.provider.clientId,
+                        },
+                    },
+                ];
+            }
+            catch (err) {
+                // Discovery must never break the catalog — the tool just stays bare.
+                console.warn(`[tool-manuals] mcp auth discovery failed for "${m.path}": ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }));
+    }
+    async scanDisk() {
+        let wsId;
+        try {
+            wsId = (await this.workspaceService.getOrCreateForBranch(DEFAULT_BRANCH)).id;
+        }
+        catch {
+            return [];
+        }
+        const root = path.join(await this.workspaceService.getWorkspacePath(wsId), this.kbDirName, TOOLS_DIR);
+        const files = (await walkFiles(root, (n) => n.toLowerCase().endsWith('.tool'))).map((rel) => ({
+            abs: path.join(root, rel),
+            rel: `${TOOLS_DIR}/${rel}`,
+        }));
+        const parsed = [];
+        for (const f of files) {
+            let content;
+            try {
+                content = await fs.readFile(f.abs, 'utf-8');
+            }
+            catch {
+                continue;
+            }
+            let descriptor;
+            try {
+                descriptor = normalizeToolManual(baseName(f.rel), f.rel, content);
+            }
+            catch {
+                // A malformed `.tool` is skipped rather than breaking the catalog.
+                continue;
+            }
+            // The route slug IS the id (unique after dedup below, snake_case → URL-safe),
+            // so the URL a user sees matches the tool's declared identity.
+            descriptor.slug = descriptor.name;
+            parsed.push(descriptor);
+        }
+        // The manual name (= its id) is the UTCP variable namespace secrets bind to, so
+        // it must be unique. A collision is REFUSED — not auto-suffixed, which would
+        // silently rebind a configured secret to a different file. The winner is
+        // deterministic (files scanned in sorted path order); the shared `dedupeById`
+        // is the one dedup rule across tools and skills.
+        return dedupeById(parsed, (m) => m.name, (m, id) => console.warn(`[tool-manuals] skipping "${m.path}": manual id "${id}" is already used by another ` +
+            '`.tool` — give it a unique `id` (the id is the secret-variable namespace and must be unique).'));
+    }
+}
+// --- helpers ------------------------------------------------------------------
+function baseName(rel) {
+    const base = rel.slice(rel.lastIndexOf('/') + 1);
+    return base.replace(/\.tool$/i, '');
+}
+/**
+ * Deterministically derive a `.tool`'s UTCP manual name — the variable namespace
+ * secrets bind to via `<manual>_<VAR>`. ALPHANUMERIC ONLY (no underscores) so the
+ * prefix splits cleanly on a single underscore, and a pure function of the file's
+ * own declared name: it never depends on what other `.tool`s exist, so a
+ * configured secret's namespace can't drift when the catalog changes. Collisions
+ * are refused by the scanner (see `scanDisk`), not silently suffixed. A name that
+ * strips to empty (or starts with a digit) is prefixed `tool`; because the KB
+ * manual name (`KNOWLEDGE_BASE`) contains an underscore, a user name can never
+ * collide with it after stripping.
+ */
+function manualName(raw) {
+    const name = raw.replace(/[^a-zA-Z0-9]/g, '');
+    if (!name || /^[0-9]/.test(name))
+        return `tool${name}`;
+    return name;
+}
+/**
+ * Parse + normalize a `.tool` file into a descriptor. THE TOOL IS THE
+ * FRONTMATTER: a fenced file's single `---` YAML block carries everything —
+ * `id`/`name`, access verbs (`read`/`write`/`owner`/`download`, read straight
+ * from the file by the access resolver, not here), and the config
+ * (`type`/`url`/`variables`/…). Text after the closing fence is free-form notes
+ * the parser ignores. A fence-less file is the legacy form (the whole file is
+ * the object — JSON can't carry fences). Throws on a structurally invalid
+ * object or a malformed explicit `id`. `slug` is provisional (the scanner
+ * dedups it); `name` is the FINAL UTCP manual namespace.
+ */
+export function normalizeToolManual(provisionalSlug, repoPath, content) {
+    // THE TOOL IS THE FRONTMATTER. A fenced `.tool` is one `---` YAML block
+    // carrying everything — identity (`id`/`name`), access verbs, and config —
+    // and anything after the closing fence is free-form notes the parser ignores
+    // (like a SKILL.md body). One object serves every reader: the access resolver
+    // finds its verbs inside the fence, the id index finds `id`/`name`, and the
+    // config keys live in the same object. A fence-less file is the legacy form
+    // (the whole file is the object) — JSON `.tool`s can't carry fences.
+    const fm = extractFrontmatter(content);
+    const source = fm ? fm.frontmatter : content;
+    const parsed = parseYaml(source);
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new Error('`.tool` file must be a YAML/JSON object (in the `---` block when fenced)');
+    }
+    const obj = parsed;
+    const type = normalizeType(obj.type);
+    // Identity: an explicit `id` is used VERBATIM as the UTCP manual namespace, so
+    // it must be lowercase snake_case (UTCP's namespace grammar). With no explicit
+    // id, fall back to `name` then the filename and sanitize (legacy behaviour —
+    // keeps existing tools' namespaces).
+    const explicitId = typeof obj.id === 'string' ? obj.id.trim() : '';
+    let name;
+    if (explicitId) {
+        if (!isValidId(explicitId)) {
+            throw new Error(`tool id "${explicitId}" must be lowercase snake_case (letters, digits, underscores)`);
+        }
+        name = explicitId;
+    }
+    else {
+        name = manualName(resolveDeclaredId(obj, provisionalSlug));
+    }
+    // A `.tool` may not reproduce a built-in manual's UTCP namespace — that would
+    // let it read the loopback creds seeded under that namespace on the agent's
+    // code-mode client (internal token, connector creds, KB bearer).
+    if (RESERVED_TOOL_NAMESPACES.includes(name.toLowerCase())) {
+        throw new Error(`tool namespace "${name}" is reserved for a built-in manual — choose a different \`id\`/\`name\` ` +
+            "(a `.tool` sharing a built-in namespace could read that manual's seeded credentials).");
+    }
+    // Any `.tool` content — url, headers, inline tool templates, notes — may not
+    // reference the platform-seeded variables.
+    assertNoReservedVariableRefs(obj, name);
+    const descriptor = {
+        slug: provisionalSlug,
+        name,
+        path: repoPath,
+        type,
+    };
+    const variables = normalizeVariables(obj.variables);
+    if (variables.length)
+        descriptor.variables = variables;
+    descriptor.remote = normalizeRemote(obj.remote);
+    if (type === 'inline') {
+        const tools = Array.isArray(obj.tools) ? obj.tools : undefined;
+        if (!tools)
+            throw new Error('inline `.tool` must have a `tools` array');
+        descriptor.tools = tools;
+    }
+    else {
+        const url = typeof obj.url === 'string' ? obj.url.trim() : '';
+        if (!url)
+            throw new Error(`${type} \`.tool\` must have a \`url\``);
+        descriptor.url = url;
+        // SSRF: a remote-capable `.tool` triggers a server-side discovery fetch to
+        // this URL (the MCP proxy AND now the in-process agent + headless routines),
+        // so a literal private/loopback/metadata host is refused at the producing
+        // boundary. Only a TEMPLATED HOSTNAME (resolved at call time) is
+        // uncheckable here — a `${...}` in the scheme, userinfo, port, path, or
+        // query still leaves a concrete network target (`${S}://169.254.169.254/x`
+        // and `http://${U}@169.254.169.254/x` target the metadata IP no matter what
+        // resolves), so the guard must still run against the literal host. The
+        // authority is therefore taken from `://` INDEPENDENT of the scheme being
+        // literal, and when the raw url can't parse (templated scheme or port) the
+        // check runs on a synthetic `<scheme-or-http>//host`. A BACKSLASH behaves as
+        // a slash for http(s) in WHATWG `new URL` — BOTH as the scheme separator
+        // (`${S}:\\169.254.169.254\\p` → the IP is the host) and inside the
+        // authority (`http://169.254.169.254\@${HOST}/x` fetches the IP, the `\@…`
+        // becoming path). So the authority separator is `:` + two `[\/]` (not just
+        // `://`), and `\` also terminates the authority alongside `/?#`; otherwise a
+        // literal internal host slips past as a templated scheme or userinfo.
+        // Local-only (`remote: false`) `.tool`s are never fetched server-side, so
+        // are exempt.
+        const literalScheme = /^([a-zA-Z][a-zA-Z0-9+.-]*:)[\\/]{2}/.exec(url)?.[1];
+        const sepMatch = /:[\\/]{2}/.exec(url);
+        const sepIdx = sepMatch ? sepMatch.index : -1;
+        const authority = sepIdx >= 0 ? url.slice(sepIdx + 3).split(/[/\\?#]/, 1)[0] : url;
+        const hostPort = authority.slice(authority.lastIndexOf('@') + 1);
+        const host = hostPort.startsWith('[') ? hostPort.slice(0, hostPort.indexOf(']') + 1) : hostPort.split(':')[0];
+        if (descriptor.remote !== false && !host.includes('${')) {
+            const checkUrl = literalScheme && !authority.includes('${')
+                ? url // fully literal scheme + authority → validate the URL as-is
+                : sepIdx >= 0
+                    ? `${literalScheme ?? 'http:'}//${host}` // templated scheme/userinfo/port, literal host
+                    : url; // no authority shape at all → parse raw (refuses malformed)
+            assertSafeFetchUrl(checkUrl, { label: `\`.tool\` "${name}" url` });
+        }
+        if (obj.headers && typeof obj.headers === 'object' && !Array.isArray(obj.headers)) {
+            descriptor.headers = obj.headers;
+        }
+        if (type === 'http') {
+            const m = typeof obj.httpMethod === 'string' ? obj.httpMethod.toUpperCase() : 'GET';
+            descriptor.httpMethod = m === 'POST' ? 'POST' : 'GET';
+        }
+    }
+    return descriptor;
+}
+/**
+ * Parse the optional `variables:` block of a `.tool` file. Each entry names a
+ * `${VAR}` and who provisions it (`admin` default | `user`). Throws on a
+ * malformed entry so the whole file is skipped (never silently mis-scoped) — a
+ * mis-scoped variable is a security-relevant mistake, not a soft warning.
+ */
+function normalizeVariables(raw) {
+    if (raw === undefined || raw === null)
+        return [];
+    if (!Array.isArray(raw))
+        throw new Error('`variables` must be an array');
+    const seen = new Set();
+    return raw.map((entry) => {
+        if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+            throw new Error('each `variables` entry must be an object');
+        }
+        const e = entry;
+        const name = typeof e.name === 'string' ? e.name.trim() : '';
+        if (!/^[A-Za-z0-9_]+$/.test(name)) {
+            throw new Error(`variable name "${name}" must match [A-Za-z0-9_]+`);
+        }
+        if (RESERVED_VARIABLE_NAMES.includes(name)) {
+            throw new Error(`variable name "${name}" is reserved for platform seeding and may not be declared by a \`.tool\``);
+        }
+        if (seen.has(name))
+            throw new Error(`duplicate variable "${name}"`);
+        seen.add(name);
+        const rawScope = typeof e.scope === 'string' ? e.scope.toLowerCase().trim() : '';
+        if (rawScope && rawScope !== 'admin' && rawScope !== 'user') {
+            throw new Error(`variable "${name}" has invalid scope "${e.scope}" (expected admin|user)`);
+        }
+        const scope = rawScope === 'user' ? 'user' : 'admin';
+        const label = typeof e.label === 'string' && e.label.trim() ? e.label.trim() : undefined;
+        const oauth = normalizeVariableOAuth(name, e.oauth);
+        // OAuth is inherently per-caller — each user signs in for their own token. An
+        // admin-shared OAuth token would leak one user's token to all callers.
+        if (oauth && scope !== 'user') {
+            throw new Error(`variable "${name}" with oauth must be scope:user`);
+        }
+        return {
+            name,
+            scope,
+            ...(label ? { label } : {}),
+            ...(oauth ? { oauth } : {}),
+        };
+    });
+}
+/**
+ * Parse a variable's optional OAuth provider config. Carries PUBLIC config only —
+ * never a client secret. Both URLs are validated with the SAME SSRF-safe check the
+ * vault uses for OAuth endpoints (`assertSafeFetchUrl` with https required), so a
+ * `.tool` author can't aim a sign-in/token exchange at an internal host.
+ */
+function normalizeVariableOAuth(name, raw) {
+    if (raw === undefined || raw === null)
+        return undefined;
+    if (typeof raw !== 'object' || Array.isArray(raw)) {
+        throw new Error(`variable "${name}" oauth must be an object`);
+    }
+    const o = raw;
+    // Confidential OAuth material is provisioned only through the protected
+    // client-secret route; reject it here so a plaintext `.tool` can't smuggle one in.
+    for (const forbidden of ['clientSecret', 'client_secret', 'secret']) {
+        if (o[forbidden] !== undefined) {
+            throw new Error(`variable "${name}" oauth.${forbidden} must be set through the protected client-secret route`);
+        }
+    }
+    const safeUrl = (v, field) => {
+        const s = typeof v === 'string' ? v.trim() : '';
+        try {
+            assertSafeFetchUrl(s, { requireHttps: true, label: `${name} oauth.${field}` });
+        }
+        catch (err) {
+            throw new Error(err instanceof Error ? err.message : `variable "${name}" oauth.${field} invalid`);
+        }
+        return s;
+    };
+    const authorizationUrl = safeUrl(o.authorizationUrl, 'authorizationUrl');
+    const tokenUrl = safeUrl(o.tokenUrl, 'tokenUrl');
+    const clientId = typeof o.clientId === 'string' && o.clientId.trim() ? o.clientId.trim() : '';
+    if (!clientId)
+        throw new Error(`variable "${name}" oauth.clientId is required`);
+    let scopes;
+    if (o.scopes !== undefined) {
+        if (!Array.isArray(o.scopes) || !o.scopes.every((s) => typeof s === 'string')) {
+            throw new Error(`variable "${name}" oauth.scopes must be string[]`);
+        }
+        scopes = o.scopes;
+    }
+    let authParams;
+    if (o.authParams !== undefined) {
+        if (typeof o.authParams !== 'object' || Array.isArray(o.authParams)) {
+            throw new Error(`variable "${name}" oauth.authParams must be an object of string values`);
+        }
+        const entries = Object.entries(o.authParams);
+        if (!entries.every(([, v]) => typeof v === 'string')) {
+            throw new Error(`variable "${name}" oauth.authParams values must be strings`);
+        }
+        authParams = Object.fromEntries(entries);
+    }
+    return {
+        authorizationUrl,
+        tokenUrl,
+        clientId,
+        ...(scopes ? { scopes } : {}),
+        ...(authParams ? { authParams } : {}),
+    };
+}
+/**
+ * Parse the optional `remote` flag. Absent ⇒ `true` (remote-capable, the default).
+ * A non-boolean throws so the file is skipped rather than silently mis-classified.
+ */
+function normalizeRemote(raw) {
+    if (raw === undefined || raw === null)
+        return true;
+    if (typeof raw !== 'boolean')
+        throw new Error('`remote` must be a boolean');
+    return raw;
+}
+function normalizeType(raw) {
+    const t = typeof raw === 'string' ? raw.toLowerCase().trim() : '';
+    if (t === 'http')
+        return 'http';
+    if (t === 'mcp')
+        return 'mcp';
+    if (t === 'inline' || t === 'text' || t === '')
+        return 'inline';
+    throw new Error(`unknown \`.tool\` type: ${raw}`);
+}
+//# sourceMappingURL=tool-manuals.service.js.map