@kognai/tool-router 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kognai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,48 @@
-# Temporary Holding Version
+# @kognai/tool-router
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Kognai ToolRouter (KTR) turns a task written in plain words into a short, ranked list of tools an agent may use.
+
+It keeps a catalog of tools built from MCP registries, OpenAPI documents, x402 resource lists and pay-skills
+providers. It classifies the task and drops every tool the caller may not use (missing auth, risk class, payment
+rules, tools nobody has reviewed), then ranks what is left with lexical, vector and capability scores. Every candidate it returns exists in the
+catalog: it never makes a tool up.
+
+- No runtime dependencies: Node 18 or later.
+- No third-party code runs. It reads catalogs as data and never installs, launches or imports a tool.
+- Results are data. A shortlist never authorises a payment, a post or a write by itself.
+
+## Install
+
+```sh
+npm install @kognai/tool-router
+```
+
+## Use
+
+```ts
+import { MemoryCatalogStore, ingest, tagCapabilities, VERIFY_AUTHORITY, fromOpenApi, RouterIndex, route, readFlags, hashEmbeddingPort } from '@kognai/tool-router';
+
+const store = new MemoryCatalogStore();
+const provenance = { source: 'my-openapi', retrieved_at: new Date().toISOString(), licence: 'MIT', snapshot_sha256: '0'.repeat(64) };
+ingest([fromOpenApi(openApiDocument, provenance)], store, { now: new Date().toISOString(), tagger: tagCapabilities });
+
+// A tool from outside starts quarantined and is never offered until someone reviews it.
+for (const r of store.latest()) store.setTrust(r.id, r.version, 'reviewed', VERIFY_AUTHORITY, 'reviewed by me');
+
+const index = new RouterIndex(store, { vectorModel: hashEmbeddingPort.model });
+const result = await route(
+  { text: "What's the weather in Paris tomorrow?", context: { caller_id: 'my-agent', principal_id: 'me', kind: 'engine', business_tier: 'enterprise', connected: [], kognai_first: 'off' } },
+  { store, index, flags: readFlags({}), offline: true, embed: hashEmbeddingPort },
+);
+
+console.log(result.requirement, result.shortlists); // 'tool', with the forecast operation in the shortlist
+```
+
+`offline: true` runs the router without the `TOOL_ROUTER_ENABLED` switch. Online, the router answers only when that
+switch is on, and a stop flag always wins.
+
+The bundled hash embedding works without a model. To use your own embedding model, pass an `EmbeddingPort`.
+
+## Licence
+
+MIT

package/dist/adapters/awesome-list.d.ts

@@ -0,0 +1,10 @@
+/**
+ * awesome-mcp-servers (github punkpeye/awesome-mcp-servers, MIT list; each server under its own licence) Markdown
+ * lines to metadata only descriptors. Lifecycle "draft": never eligible, not even in discover mode; they exist in the
+ * catalog so the router can say that unverified community servers exist (exclusion counts) and so the benchmark has
+ * realistic volume. The emoji legend becomes tags.
+ */
+import type { ProvenanceIn, RawToolDescriptor } from './raw';
+export declare const ADAPTER = "awesome-list";
+export declare const ADAPTER_VERSION = "1.0.0";
+export declare function fromAwesomeMarkdown(md: string, p: ProvenanceIn): RawToolDescriptor[];

package/dist/adapters/awesome-list.js

@@ -0,0 +1,68 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ADAPTER_VERSION = exports.ADAPTER = void 0;
+exports.fromAwesomeMarkdown = fromAwesomeMarkdown;
+const raw_1 = require("./raw");
+exports.ADAPTER = 'awesome-list';
+exports.ADAPTER_VERSION = '1.0.0';
+const LEGEND = [
+    ['🎖️', 'official'], ['🎖', 'official'], ['📇', 'typescript'], ['🐍', 'python'], ['🏎️', 'go'], ['🏎', 'go'], ['🦀', 'rust'],
+    ['#️⃣', 'csharp'], ['☕', 'java'], ['🌊', 'c-cpp'], ['💎', 'ruby'], ['☁️', 'cloud'], ['☁', 'cloud'], ['🏠', 'local'],
+    ['📟', 'embedded'], ['🍎', 'macos'], ['🪟', 'windows'], ['🐧', 'linux'],
+];
+const LINE = /^\s*[-*]\s+\[([^\]]+)\]\((https?:\/\/[^)\s]+)\)(.*)$/;
+const HEADING = /^###\s+(.*)$/;
+function fromAwesomeMarkdown(md, p) {
+    const out = [];
+    const used = new Set();
+    let category = 'uncategorised';
+    let inServers = false;
+    for (const line of md.split(/\r?\n/)) {
+        if (/^##\s/.test(line)) {
+            inServers = /^##\s+Server Implementations/i.test(line);
+            continue;
+        }
+        const h = HEADING.exec(line);
+        if (h) {
+            const anchor = /<a name="([^"]+)"/.exec(h[1]);
+            category = (anchor ? anchor[1] : h[1].replace(/<[^>]+>/g, '').replace(/[^\p{L}\p{N} &-]/gu, '').trim()).toLowerCase().replace(/\s+/g, '-') || 'uncategorised';
+            continue;
+        }
+        if (!inServers)
+            continue;
+        const m = LINE.exec(line);
+        if (!m)
+            continue;
+        const [, label, url, rest] = m;
+        const gh = /github\.com\/([^/\s]+)\/([^/\s#?]+)/i.exec(url);
+        let host = 'unknown';
+        let segs = [];
+        try {
+            const u = new URL(url);
+            host = u.hostname;
+            segs = u.pathname.split('/').filter(Boolean);
+        }
+        catch { /* keep unknown */ }
+        const ns = gh ? gh[1] : segs[0] || host;
+        const nm = (gh ? gh[2] : segs[1] || label.replace(/^@/, '').split('/').pop() || label).replace(/\.git$/, '');
+        const providerName = gh ? gh[1] : host;
+        let path = `${ns}/${nm}`;
+        for (let i = 2; used.has(path.toLowerCase()); i++)
+            path = `${ns}/${nm}-${i}`;
+        used.add(path.toLowerCase());
+        const noBadges = rest.replace(/\[!\[[^\]]*\]\([^)]*\)\]\([^)]*\)/g, ' ').replace(/!\[[^\]]*\]\([^)]*\)/g, ' ');
+        const dash = noBadges.search(/\s[-–—]\s/);
+        const legendPart = dash >= 0 ? noBadges.slice(0, dash) : noBadges;
+        const description = dash >= 0 ? noBadges.slice(dash).replace(/^\s*[-–—]\s*/, '').trim() : '';
+        const tags = [...new Set(LEGEND.filter(([e]) => legendPart.includes(e)).map(([, t]) => t))];
+        out.push({
+            source: 'awesome-mcp-servers', source_ref: url, origin: 'community', path,
+            name: label.slice(0, 120), description,
+            provider: { name: providerName, url, kognai_owned: false }, category, tags: ['community', 'metadata-only', category, ...tags],
+            operations: [{ op: 'server', summary: description || label, input_schema: null, output_schema: null, side_effects: null }],
+            auth: { kind: 'none' }, pricing: { model: 'unknown', source: 'unknown' }, licence: null,
+            implementation: 'metadata', lifecycle: 'draft', provenance: (0, raw_1.prov)(p, exports.ADAPTER, exports.ADAPTER_VERSION),
+        });
+    }
+    return out;
+}

package/dist/adapters/mcp-registry.d.ts

@@ -0,0 +1,12 @@
+/**
+ * MCP registry server.json entries (registry.modelcontextprotocol.io, `GET /v0/servers` pages) to raw descriptors.
+ * Metadata only: the registry does not list a server's tools, so each server becomes one tool with one unknown
+ * operation ("server"), unknown schema and unknown side effects (fail closed). Servers that ship only `packages` are
+ * marked implementation "package" and are never runnable by KTR; `remotes` make a server a candidate for a later
+ * CTO desk verification. Nothing here installs or launches anything.
+ */
+import type { ProvenanceIn, RawToolDescriptor } from './raw';
+export declare const ADAPTER = "mcp-registry";
+export declare const ADAPTER_VERSION = "1.0.0";
+/** Accepts a registry page ({servers: [...]}), an array of entries, or one server.json. */
+export declare function fromServerJson(input: unknown, p: ProvenanceIn): RawToolDescriptor[];

package/dist/adapters/mcp-registry.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ADAPTER_VERSION = exports.ADAPTER = void 0;
+exports.fromServerJson = fromServerJson;
+const raw_1 = require("./raw");
+exports.ADAPTER = 'mcp-registry';
+exports.ADAPTER_VERSION = '1.0.0';
+const NAME_RE = /^[a-zA-Z0-9.-]+\/[a-zA-Z0-9._-]+$/;
+/** Accepts a registry page ({servers: [...]}), an array of entries, or one server.json. */
+function fromServerJson(input, p) {
+    const list = Array.isArray(input) ? input
+        : (input && typeof input === 'object' && Array.isArray(input.servers)) ? input.servers
+            : [input];
+    const out = [];
+    for (const e of list) {
+        const s = (e && e.server) || e;
+        if (!s || typeof s !== 'object' || typeof s.name !== 'string' || !NAME_RE.test(s.name))
+            continue;
+        const official = e?._meta?.['io.modelcontextprotocol.registry/official'] || {};
+        // the registry lists every published version; only the latest one enters the catalog
+        if (official.isLatest === false)
+            continue;
+        const status = String(official.status || 'active');
+        const remotes = (s.remotes || []).filter((r) => typeof r?.url === 'string' && /^https:\/\//i.test(r.url));
+        const pkg = (s.packages || []).find((x) => x && (x.identifier || x.name));
+        const implementation = remotes.length ? 'remote' : pkg ? 'package' : 'metadata';
+        const [ns, nm] = s.name.split('/');
+        out.push({
+            source: 'mcp-registry',
+            source_ref: `${s.name}@${s.version || '?'}`,
+            origin: 'mcp',
+            path: `${ns}/${nm}`,
+            name: (s.title || nm).slice(0, 120),
+            description: String(s.description || ''),
+            provider: { name: ns, url: s.websiteUrl || s.repository?.url, kognai_owned: false },
+            category: 'mcp-server',
+            tags: ['mcp', implementation],
+            operations: [{ op: 'server', summary: String(s.description || s.title || nm), input_schema: null, output_schema: null, side_effects: null }],
+            auth: { kind: 'none' },
+            pricing: { model: 'unknown', source: 'unknown' },
+            licence: p.licence,
+            endpoint: remotes[0]?.url,
+            package: pkg ? { registry: String(pkg.registryType || pkg.registry_name || 'unknown'), identifier: String(pkg.identifier || pkg.name), version: pkg.version } : undefined,
+            implementation,
+            version: s.version,
+            lifecycle: status === 'deleted' ? 'retired' : status === 'deprecated' ? 'deprecated' : 'active',
+            provenance: (0, raw_1.prov)(p, exports.ADAPTER, exports.ADAPTER_VERSION),
+        });
+    }
+    return out;
+}

package/dist/adapters/mcp-tools.d.ts

@@ -0,0 +1,49 @@
+/**
+ * MCP tools/list results to raw descriptors, for APPROVED servers only (policy/tool-router.txt rule 2).
+ *
+ * fromMcpToolsList() reads a tools/list result that is already a file (a fixture in tests, a pinned snapshot
+ * otherwise). listToolsLive() is the only path that talks to a server, and it refuses unless all of these hold: the
+ * flag TOOL_ROUTER_MCP_LIST_LIVE is on, the server is in the approved list (workspace/ktr/mcp-approved.json, the CTO
+ * desk's file, decision D10), and the server has an https remote endpoint. A package-only server is refused always:
+ * KTR never installs or launches third party code, so there is no stdio transport here at all.
+ *
+ * Tool annotations (readOnlyHint, destructiveHint) come from the server and are untrusted: a destructive hint adds
+ * risk; a read only hint is believed only when the approval entry says the CTO desk checked it (trust_annotations).
+ */
+import type { KtrFlags } from '../flags';
+import type { ProvenanceIn, RawToolDescriptor } from './raw';
+export declare const ADAPTER = "mcp-tools";
+export declare const ADAPTER_VERSION = "1.0.0";
+export interface ApprovedServer {
+    name: string;
+    remote_url?: string;
+    approved_by: string;
+    approved_at: string;
+    schema_hash?: string;
+    trust_annotations?: boolean;
+}
+export interface McpTool {
+    name: string;
+    title?: string;
+    description?: string;
+    inputSchema?: Record<string, unknown>;
+    outputSchema?: Record<string, unknown>;
+    annotations?: {
+        readOnlyHint?: boolean;
+        destructiveHint?: boolean;
+        idempotentHint?: boolean;
+        openWorldHint?: boolean;
+    };
+}
+export declare class NotApproved extends Error {
+}
+export declare function approvedEntry(name: string, approved: ApprovedServer[]): ApprovedServer | null;
+export declare function fromMcpToolsList(serverName: string, result: unknown, approved: ApprovedServer[], p: ProvenanceIn): RawToolDescriptor;
+/** JSON-RPC over an https remote; injected so tests never touch the network. */
+export type McpHttpTransport = (url: string, body: {
+    jsonrpc: '2.0';
+    id: number;
+    method: 'tools/list';
+    params: Record<string, unknown>;
+}) => Promise<unknown>;
+export declare function listToolsLive(serverName: string, approved: ApprovedServer[], flags: Pick<KtrFlags, 'mcpListLive' | 'stopped'>, transport: McpHttpTransport): Promise<unknown>;

package/dist/adapters/mcp-tools.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NotApproved = exports.ADAPTER_VERSION = exports.ADAPTER = void 0;
+exports.approvedEntry = approvedEntry;
+exports.fromMcpToolsList = fromMcpToolsList;
+exports.listToolsLive = listToolsLive;
+const raw_1 = require("./raw");
+exports.ADAPTER = 'mcp-tools';
+exports.ADAPTER_VERSION = '1.0.0';
+class NotApproved extends Error {
+}
+exports.NotApproved = NotApproved;
+function approvedEntry(name, approved) {
+    return approved.find((a) => a.name === name && a.approved_by === 'cto-desk') || null;
+}
+function sideEffectsOf(t, a) {
+    if (t.annotations?.destructiveHint === true)
+        return ['delete'];
+    if (t.annotations?.readOnlyHint === true && a.trust_annotations === true)
+        return ['read'];
+    return null;
+}
+function fromMcpToolsList(serverName, result, approved, p) {
+    const a = approvedEntry(serverName, approved);
+    if (!a)
+        throw new NotApproved(`${serverName} is not in the approved MCP list (CTO desk, D10)`);
+    const tools = Array.isArray(result?.tools) ? result.tools : [];
+    if (tools.length > 200)
+        throw new Error(`${serverName} lists ${tools.length} tools, more than 200 (T14)`);
+    const ops = tools.filter((t) => t && typeof t.name === 'string').map((t) => ({
+        op: t.name,
+        summary: String(t.description || t.title || t.name),
+        input_schema: (t.inputSchema && typeof t.inputSchema === 'object') ? t.inputSchema : null,
+        output_schema: (t.outputSchema && typeof t.outputSchema === 'object') ? t.outputSchema : null,
+        side_effects: sideEffectsOf(t, a),
+        idempotent: t.annotations?.idempotentHint === true && a.trust_annotations === true ? true : null,
+    }));
+    const [ns, nm] = serverName.split('/');
+    return {
+        source: 'mcp-tools', source_ref: serverName, origin: 'mcp', path: `${ns}/${nm}`,
+        name: nm, description: ops.map((o) => o.summary).join(' ').slice(0, 2000),
+        provider: { name: ns, kognai_owned: false }, category: 'mcp-server', tags: ['mcp', 'remote', 'tools-listed'],
+        operations: ops, auth: { kind: 'none' }, pricing: { model: 'unknown', source: 'unknown' },
+        licence: p.licence, endpoint: a.remote_url, implementation: 'remote', lifecycle: 'active',
+        provenance: (0, raw_1.prov)(p, exports.ADAPTER, exports.ADAPTER_VERSION),
+    };
+}
+async function listToolsLive(serverName, approved, flags, transport) {
+    if (flags.stopped)
+        throw new Error('KTR is stopped (.swarm-state/ktr-stop)');
+    if (!flags.mcpListLive)
+        throw new Error('TOOL_ROUTER_MCP_LIST_LIVE is off');
+    const a = approvedEntry(serverName, approved);
+    if (!a)
+        throw new NotApproved(`${serverName} is not in the approved MCP list (CTO desk, D10)`);
+    if (!a.remote_url || !/^https:\/\//i.test(a.remote_url))
+        throw new Error(`${serverName} has no https remote: KTR never launches a package (policy/tool-router.txt rule 2)`);
+    const res = await transport(a.remote_url, { jsonrpc: '2.0', id: 1, method: 'tools/list', params: {} });
+    return res?.result ?? res;
+}

package/dist/adapters/openapi.d.ts

@@ -0,0 +1,25 @@
+/**
+ * OpenAPI 3.0 and 3.1 documents to one raw descriptor with one operation per path and method. The input schema is
+ * built from parameters plus the JSON request body; local $ref pointers are resolved (depth and size capped, cycles
+ * cut). Side effects come from the method and fail closed: GET and HEAD read, POST, PUT and PATCH write, DELETE
+ * deletes. A POST is read only when the caller's own reviewed list says so (`safePostOps`), never because the
+ * provider's text claims it.
+ */
+import type { SideEffect } from '../types/tool';
+import type { ProvenanceIn, RawToolDescriptor } from './raw';
+export declare const ADAPTER = "openapi";
+export declare const ADAPTER_VERSION = "1.0.0";
+export interface OpenApiOpts {
+    /** namespace/name for the tool id; defaults to the server host and the title. */
+    path?: string;
+    origin?: 'openapi' | 'x402';
+    provider?: {
+        name: string;
+        url?: string;
+    };
+    safePostOps?: string[];
+    category?: string;
+    tags?: string[];
+}
+export declare function sideEffectOf(method: string, op: string, safePostOps?: string[]): SideEffect[];
+export declare function fromOpenApi(doc: any, p: ProvenanceIn, opts?: OpenApiOpts): RawToolDescriptor;

package/dist/adapters/openapi.js

@@ -0,0 +1,107 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ADAPTER_VERSION = exports.ADAPTER = void 0;
+exports.sideEffectOf = sideEffectOf;
+exports.fromOpenApi = fromOpenApi;
+const raw_1 = require("./raw");
+exports.ADAPTER = 'openapi';
+exports.ADAPTER_VERSION = '1.0.0';
+const METHODS = ['get', 'head', 'post', 'put', 'patch', 'delete'];
+function resolver(doc) {
+    const lookup = (ref) => {
+        if (!ref.startsWith('#/'))
+            return null;
+        return ref.slice(2).split('/').reduce((o, k) => (o == null ? o : o[k.replace(/~1/g, '/').replace(/~0/g, '~')]), doc);
+    };
+    // `hops` counts $ref follows (cap 8), `level` counts nesting (cap 32); a ref already on the path is a cycle.
+    const resolve = (s, hops = 0, seen = new Set(), level = 0) => {
+        if (!s || typeof s !== 'object')
+            return s;
+        if (hops > 8 || level > 32)
+            return {};
+        if (typeof s.$ref === 'string') {
+            if (seen.has(s.$ref))
+                return { type: 'object', description: 'recursive' };
+            const t = lookup(s.$ref);
+            return t ? resolve(t, hops + 1, new Set([...seen, s.$ref]), level + 1) : {};
+        }
+        if (Array.isArray(s))
+            return s.map((x) => resolve(x, hops, seen, level + 1));
+        const out = {};
+        for (const [k, v] of Object.entries(s))
+            out[k] = typeof v === 'object' ? resolve(v, hops, seen, level + 1) : v;
+        return out;
+    };
+    return resolve;
+}
+const opName = (method, path, operationId) => (operationId || `${method}_${path}`).replace(/[^A-Za-z0-9_.-]+/g, '_').replace(/_+/g, '_').replace(/^_|_$/g, '').toLowerCase().slice(0, 64) || method;
+function sideEffectOf(method, op, safePostOps = []) {
+    switch (method) {
+        case 'get':
+        case 'head': return ['read'];
+        case 'delete': return ['delete'];
+        case 'post': return safePostOps.includes(op) ? ['read'] : ['write'];
+        default: return ['write'];
+    }
+}
+function fromOpenApi(doc, p, opts = {}) {
+    if (!doc || typeof doc !== 'object' || !/^3\./.test(String(doc.openapi || '')))
+        throw new Error('not an OpenAPI 3.x document');
+    const resolve = resolver(doc);
+    const server = String(doc.servers?.[0]?.url || '');
+    let host = 'unknown';
+    try {
+        host = new URL(server).hostname;
+    }
+    catch { /* relative server */ }
+    const title = String(doc.info?.title || host);
+    const ops = [];
+    for (const [path, item] of Object.entries(doc.paths || {})) {
+        const shared = Array.isArray(item?.parameters) ? item.parameters : [];
+        for (const method of METHODS) {
+            const o = item?.[method];
+            if (!o || typeof o !== 'object')
+                continue;
+            const op = opName(method, path, o.operationId);
+            const properties = {};
+            const required = [];
+            for (const prm of [...shared, ...(Array.isArray(o.parameters) ? o.parameters : [])].map((x) => resolve(x))) {
+                if (!prm || typeof prm.name !== 'string' || prm.in === 'header' || prm.in === 'cookie')
+                    continue;
+                properties[prm.name] = { ...(resolve(prm.schema) || { type: 'string' }), ...(prm.description ? { description: String(prm.description).slice(0, 200) } : {}) };
+                if (prm.required || prm.in === 'path')
+                    required.push(prm.name);
+            }
+            const body = resolve(o.requestBody);
+            const bodySchema = body?.content?.['application/json']?.schema;
+            if (bodySchema) {
+                properties.body = resolve(bodySchema);
+                if (body.required)
+                    required.push('body');
+            }
+            const ok = o.responses?.['200'] || o.responses?.['201'] || o.responses?.default;
+            const outSchema = resolve(ok)?.content?.['application/json']?.schema;
+            ops.push({
+                op, method: method.toUpperCase(), path,
+                summary: String(o.summary || o.description || `${method.toUpperCase()} ${path}`),
+                input_schema: { type: 'object', properties, ...(required.length ? { required: [...new Set(required)] } : {}) },
+                output_schema: outSchema ? resolve(outSchema) : null,
+                side_effects: sideEffectOf(method, op, opts.safePostOps),
+                idempotent: method === 'get' || method === 'head' || method === 'put' || method === 'delete',
+            });
+        }
+    }
+    return {
+        source: p.source, source_ref: `${title}@${doc.info?.version || '?'}`,
+        origin: opts.origin || 'openapi',
+        path: opts.path || `${host}/${title}`,
+        name: title.slice(0, 120),
+        description: String(doc.info?.description || title),
+        provider: { name: opts.provider?.name || host, url: opts.provider?.url || server || undefined, kognai_owned: false },
+        category: opts.category || 'api', tags: ['openapi', ...(opts.tags || [])],
+        operations: ops, auth: { kind: doc.components?.securitySchemes ? 'api_key' : 'none' },
+        pricing: { model: 'unknown', source: 'unknown' }, licence: p.licence,
+        endpoint: server || undefined, implementation: 'http', version: doc.info?.version ? String(doc.info.version) : undefined,
+        lifecycle: 'active', provenance: (0, raw_1.prov)(p, exports.ADAPTER, exports.ADAPTER_VERSION),
+    };
+}

package/dist/adapters/pay-skills.d.ts

@@ -0,0 +1,13 @@
+import type { ProvenanceIn, RawToolDescriptor } from './raw';
+export declare const ADAPTER = "pay-skills";
+export declare const ADAPTER_VERSION = "1.0.0";
+export interface PayMdFile {
+    path: string;
+    md: string;
+    openapi?: unknown;
+}
+/** The front matter subset pay-skills uses: top level scalars and one level of nested scalars. */
+export declare function frontMatter(md: string): Record<string, any> | null;
+/** '$0.01' or '0.01' to micro units; null when it is not a plain USD amount. */
+export declare function priceMicro(s: unknown): bigint | null;
+export declare function fromPaySkills(files: PayMdFile[], p: ProvenanceIn): RawToolDescriptor[];

package/dist/adapters/pay-skills.js

@@ -0,0 +1,119 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ADAPTER_VERSION = exports.ADAPTER = void 0;
+exports.frontMatter = frontMatter;
+exports.priceMicro = priceMicro;
+exports.fromPaySkills = fromPaySkills;
+const money_1 = require("../money");
+const openapi_1 = require("./openapi");
+const raw_1 = require("./raw");
+exports.ADAPTER = 'pay-skills';
+exports.ADAPTER_VERSION = '1.0.0';
+/** The front matter subset pay-skills uses: top level scalars and one level of nested scalars. */
+function frontMatter(md) {
+    const m = /^---\r?\n([\s\S]*?)\r?\n---/.exec(md);
+    if (!m)
+        return null;
+    const out = {};
+    let parent = null;
+    const unq = (v) => {
+        const t = v.trim();
+        if ((t.startsWith('"') && t.endsWith('"')) || (t.startsWith("'") && t.endsWith("'"))) {
+            try {
+                return t.startsWith('"') ? JSON.parse(t) : t.slice(1, -1);
+            }
+            catch {
+                return t.slice(1, -1);
+            }
+        }
+        return t;
+    };
+    for (const line of m[1].split(/\r?\n/)) {
+        const top = /^([A-Za-z_][\w-]*):\s*(.*)$/.exec(line);
+        const nested = /^\s{2,}([A-Za-z_][\w-]*):\s*(.*)$/.exec(line);
+        if (top) {
+            if (top[2] === '') {
+                out[top[1]] = {};
+                parent = top[1];
+            }
+            else {
+                out[top[1]] = unq(top[2]);
+                parent = null;
+            }
+        }
+        else if (nested && parent) {
+            out[parent][nested[1]] = unq(nested[2]);
+        }
+    }
+    return out;
+}
+/** '$0.01' or '0.01' to micro units; null when it is not a plain USD amount. */
+function priceMicro(s) {
+    const m = /^\s*\$?\s*(\d+(?:\.\d{1,6})?)\s*$/.exec(String(s ?? ''));
+    if (!m)
+        return null;
+    try {
+        return (0, money_1.toMicro)(m[1]);
+    }
+    catch {
+        return null;
+    }
+}
+function networksOf(text) {
+    const n = [];
+    if (/\bbase\b/i.test(text))
+        n.push('base');
+    if (/\bsolana\b/i.test(text))
+        n.push('solana');
+    return n;
+}
+function fromPaySkills(files, p) {
+    const out = [];
+    for (const f of files) {
+        const fm = frontMatter(f.md);
+        const parts = /(?:^|\/)providers\/(.+)\/PAY\.md$/.exec(f.path);
+        if (!fm || !parts || !fm.name)
+            continue;
+        const segs = parts[1].split('/');
+        if (segs.length < 2)
+            continue;
+        const operator = segs[0];
+        const name = segs.slice(1).join('-');
+        const body = f.md.replace(/^---[\s\S]*?---/, '');
+        const description = [fm.description, fm.use_case].filter(Boolean).join(' ');
+        let ops = [{ op: 'call', summary: String(fm.description || fm.title || name), input_schema: null, output_schema: null, side_effects: null }];
+        let pricing = { model: 'unknown', source: 'unknown' };
+        const networks = networksOf(body);
+        if (f.openapi) {
+            try {
+                const d = (0, openapi_1.fromOpenApi)(f.openapi, p, { origin: 'x402', path: `${operator}/${name}` });
+                if (d.operations.length)
+                    ops = d.operations;
+                const prices = [];
+                for (const [, item] of Object.entries(f.openapi.paths || {})) {
+                    for (const o of Object.values(item || {})) {
+                        const pm = priceMicro(o?.['x-payment-info']?.price);
+                        if (pm !== null)
+                            prices.push(pm);
+                    }
+                }
+                if (prices.length) {
+                    const min = prices.reduce((a, b) => (b < a ? b : a));
+                    pricing = { model: 'per_call', price: { amount_micro: min.toString(), currency: 'USDC', ...(networks[0] ? { network: networks[0] } : {}) }, unit: 'request', source: 'provider' };
+                }
+            }
+            catch { /* a broken openapi keeps the single unknown operation */ }
+        }
+        const priceLine = /\$\d+(?:\.\d+)?(?:\s*(?:per|\/)\s*\w+)?/.exec(body)?.[0];
+        out.push({
+            source: 'pay-skills', source_ref: f.path, origin: 'x402', path: `${operator}/${name}`,
+            name: String(fm.title || name).slice(0, 120), description,
+            provider: { name: operator, url: fm.service_url, kognai_owned: false },
+            category: String(fm.category || 'other'), tags: ['pay-skills', 'x402', String(fm.category || 'other')],
+            operations: ops, auth: { kind: 'x402' }, pricing, pricing_text: priceLine,
+            licence: p.licence, endpoint: fm.service_url, implementation: 'http', version: fm.version ? String(fm.version) : undefined,
+            networks, lifecycle: 'active', provenance: (0, raw_1.prov)(p, exports.ADAPTER, exports.ADAPTER_VERSION),
+        });
+    }
+    return out;
+}