@profullstack/chat-plugins 0.0.0-stage → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/src/tools.js ADDED
@@ -0,0 +1,114 @@
1
+ // Tool naming and the OpenAI `tools` array.
2
+
3
+ /** Plugin slug: lowercase [a-z0-9-], 1-32 chars, never contains "__". @param {string} input */
4
+ export function slugify(input) {
5
+ const s = String(input || "")
6
+ .toLowerCase()
7
+ .normalize("NFKD")
8
+ .replace(/[^a-z0-9]+/g, "-")
9
+ .replace(/^-+|-+$/g, "")
10
+ .slice(0, 32)
11
+ .replace(/-+$/g, "");
12
+ return s || "plugin";
13
+ }
14
+
15
+ /** @param {string} s */
16
+ function fnv1a(s) {
17
+ let h = 0x811c9dc5;
18
+ for (let i = 0; i < s.length; i++) {
19
+ h ^= s.charCodeAt(i);
20
+ h = Math.imul(h, 0x01000193) >>> 0;
21
+ }
22
+ return h.toString(16).padStart(8, "0");
23
+ }
24
+
25
+ export const MAX_TOOL_NAME = 64;
26
+
27
+ /**
28
+ * Namespaced tool name `<slug>__<tool>`, [a-zA-Z0-9_-], at most 64 chars.
29
+ * Deterministic, so a name can be resolved again later.
30
+ * @param {string} slug
31
+ * @param {string} tool
32
+ */
33
+ export function toolName(slug, tool) {
34
+ const clean = `${slugify(slug)}__${String(tool).replace(/[^a-zA-Z0-9_-]/g, "_")}`;
35
+ if (clean.length <= MAX_TOOL_NAME) return clean;
36
+ const hash = fnv1a(`${slug}\u0000${tool}`);
37
+ return `${clean.slice(0, MAX_TOOL_NAME - 9)}_${hash}`;
38
+ }
39
+
40
+ /**
41
+ * @param {import("../index.js").Plugin[]} plugins
42
+ * @returns {Map<string, { plugin: import("../index.js").Plugin, tool: import("../index.js").McpTool, name: string }>}
43
+ */
44
+ export function buildToolIndex(plugins) {
45
+ const map = new Map();
46
+ for (const plugin of plugins || []) {
47
+ if (!plugin || plugin.enabled === false) continue;
48
+ for (const tool of plugin.tools || []) {
49
+ const name = toolName(plugin.slug, tool.name);
50
+ if (!map.has(name)) map.set(name, { plugin, tool, name });
51
+ }
52
+ }
53
+ return map;
54
+ }
55
+
56
+ /**
57
+ * Find a tool by the name a model used: the namespaced name, a bare tool name that
58
+ * is unique across plugins, or `slug.tool` / `slug/tool`; case-insensitive.
59
+ * @param {ReturnType<typeof buildToolIndex>} index
60
+ * @param {string} name
61
+ */
62
+ export function resolveTool(index, name) {
63
+ if (!name) return null;
64
+ const n = String(name).trim();
65
+ if (index.has(n)) return index.get(n) || null;
66
+ const lower = n.toLowerCase();
67
+ for (const [k, v] of index) if (k.toLowerCase() === lower) return v;
68
+ const alt = lower.replace(/[./:]/, "__");
69
+ for (const [k, v] of index) if (k.toLowerCase() === alt) return v;
70
+ const bare = [...index.values()].filter((v) => v.tool.name.toLowerCase() === lower);
71
+ return bare.length === 1 ? bare[0] : null;
72
+ }
73
+
74
+ /** JSON Schema for parameters, always an object schema. @param {any} schema */
75
+ function paramsSchema(schema) {
76
+ if (!schema || typeof schema !== "object" || schema.type !== "object") {
77
+ return { type: "object", properties: {} };
78
+ }
79
+ const { $schema, ...rest } = schema;
80
+ return { properties: {}, ...rest };
81
+ }
82
+
83
+ /**
84
+ * OpenAI chat-completions `tools` array for every enabled plugin's tools.
85
+ * @param {import("../index.js").Plugin[]} plugins
86
+ */
87
+ export function toOpenAITools(plugins) {
88
+ const out = [];
89
+ for (const { plugin, tool, name } of buildToolIndex(plugins).values()) {
90
+ const label = plugin.name || plugin.slug;
91
+ const desc = [tool.title && tool.title !== tool.name ? tool.title : "", tool.description || ""].filter(Boolean).join(": ");
92
+ out.push({
93
+ type: "function",
94
+ function: {
95
+ name,
96
+ description: `[${label}] ${desc}`.slice(0, 1024),
97
+ parameters: paramsSchema(tool.inputSchema),
98
+ },
99
+ });
100
+ }
101
+ return out;
102
+ }
103
+
104
+ /**
105
+ * Does calling this tool need the person's OK first?
106
+ * destructiveHint === true, or not read-only and open-world.
107
+ * @param {import("../index.js").McpTool} tool
108
+ */
109
+ export function needsApproval(tool) {
110
+ const a = tool?.annotations || {};
111
+ if (a.destructiveHint === true) return true;
112
+ if (a.readOnlyHint !== true && a.openWorldHint === true) return true;
113
+ return false;
114
+ }