@anchrd/intel-api 0.9.0 → 0.11.0

package/dist/adapters/json-schema/json-schema.js

@@ -1,31 +1,77 @@
-import Ajv, {} from "ajv";
-// Tool schemas come from remote catalogs and are therefore untrusted: allErrors lets a crafted
-// schema amplify validation work, and Ajv keeps every compiled schema for the life of the isolate.
-const MaxCompiledSchemas = 200;
+import { Validator } from "@cfworker/json-schema";
+import { reportUnexpectedError } from "../../shared/report-unexpected-error/report-unexpected-error.js";
+// ⚠️ This validator must not generate code, and Ajv must never come back. Ajv turns a schema into
+// JavaScript with `new Function`, and workerd answers that with `EvalError: Code generation from
+// strings disallowed for this context` — so `compile` threw for EVERY schema in production, the
+// catch called it a broken schema, and each tool call died with 400 "The cached tool schema is
+// invalid" while nothing was wrong with any schema (#229). Ajv is usable only with schemas
+// precompiled at build time; these arrive from a remote catalog and are unknown until the call.
+// `@cfworker/json-schema` interprets the schema instead, which is what it was written for.
+//
+// ⚠️ The `workerd` test pool does not prove this on its own: it replaces `globalThis.Function` with
+// a proxy onto an unsafe-eval binding, so Ajv compiled happily in every test while failing in every
+// deployment. `json-schema.int.ts` therefore takes that patch away for the length of the test — it
+// is the only thing that turns red when a code-generating validator returns.
+// Tool schemas come from remote catalogs and are therefore untrusted: `ShortCircuit` stops at the
+// first error so a crafted schema cannot amplify the work of one call, and the prepared validators
+// are bounded because each one holds its dereferenced schema for the life of the isolate.
+const MaxPreparedSchemas = 200;
+const ShortCircuit = true;
+const MaxDetailLength = 2_000;
+// A tool schema that names its draft gets that draft: draft-07 ignores keywords sitting beside a
+// `$ref` and the later drafts apply them, so guessing here would validate a foreign catalog against
+// rules its author never wrote. Unnamed means 2020-12, the draft the MCP generators emit when they
+// stay silent.
+const DefaultDraft = "2020-12";
+const DraftsByMetaSchema = [
+    ["draft-04", "4"],
+    ["draft-07", "7"],
+    ["2019-09", "2019-09"],
+    ["2020-12", "2020-12"],
+];
+function draftOf(schema) {
+    const declared = schema.$schema;
+    if (typeof declared !== "string")
+        return DefaultDraft;
+    return DraftsByMetaSchema.find(([marker]) => declared.includes(marker))?.[1] ?? DefaultDraft;
+}
 export function createJsonSchemaValidator() {
-    const ajv = new Ajv({ allErrors: false, strict: false });
-    const compiled = new Map();
+    const prepared = new Map();
     return (schema, value) => {
-        try {
-            const key = JSON.stringify(schema);
-            let validate = compiled.get(key);
-            if (!validate) {
-                if (compiled.size >= MaxCompiledSchemas) {
-                    compiled.clear();
-                    ajv.removeSchema();
-                }
-                validate = ajv.compile(schema);
-                compiled.set(key, validate);
+        const key = JSON.stringify(schema);
+        let validator = prepared.get(key);
+        if (!validator) {
+            try {
+                validator = new Validator(schema, draftOf(schema), ShortCircuit);
+            }
+            catch (error) {
+                // A schema this validator cannot even read is still refused by name — but the caller hears
+                // that it was the schema, not their arguments, and the reason itself goes to the log. The
+                // old wording claimed a broken schema for every failure, which is what hid #229 for weeks.
+                reportUnexpectedError(error);
+                return { valid: false, detail: "The tool schema could not be read; the reason was logged" };
             }
-            if (validate(value))
+            if (prepared.size >= MaxPreparedSchemas)
+                prepared.clear();
+            prepared.set(key, validator);
+        }
+        try {
+            const result = validator.validate(value);
+            if (result.valid)
                 return { valid: true };
-            return {
-                valid: false,
-                detail: ajv.errorsText(validate.errors, { separator: "; " }).slice(0, 2_000),
-            };
+            return { valid: false, detail: describe(result) };
         }
-        catch {
-            return { valid: false, detail: "The cached tool schema is invalid" };
+        catch (error) {
+            // An unresolvable `$ref` only shows up while walking the instance, so this is the same
+            // unreadable schema arriving one step later — and never a statement about the arguments.
+            reportUnexpectedError(error);
+            return { valid: false, detail: "The tool schema could not be read; the reason was logged" };
         }
     };
 }
+function describe(result) {
+    return result.errors
+        .map((unit) => `${unit.instanceLocation}: ${unit.error}`)
+        .join("; ")
+        .slice(0, MaxDetailLength);
+}

package/dist/build/build.js

@@ -1,3 +1,4 @@
+import { UI_LANGUAGES } from "@anchrd/intel-contract";
 import { z } from "zod";
 const UiConfig = z.strictObject({
     theme: z.string().min(1).optional(),
@@ -100,8 +101,12 @@ export function createBuild(deps) {
                     }
                     catalogs[language] = candidateParsed.data;
                 }
-                if (config.defaultLanguage !== "en" && !(config.defaultLanguage in catalogs)) {
-                    throw new Error(`ui.defaultLanguage ${JSON.stringify(config.defaultLanguage)} is not listed in ui.languages`);
+                // A built-in language needs no entry in ui.languages — its catalog is already in the UI.
+                // Without this exception, `ui.defaultLanguage: "de"` would force the customer to list a copy
+                // of de.json that rots at every UI update, and nobody maintains that copy.
+                const builtIn = UI_LANGUAGES;
+                if (!builtIn.includes(config.defaultLanguage) && !(config.defaultLanguage in catalogs)) {
+                    throw new Error(`ui.defaultLanguage ${JSON.stringify(config.defaultLanguage)} is neither built in (${UI_LANGUAGES.join(", ")}) nor listed in ui.languages`);
                 }
                 const theme = config.theme
                     ? `/* Generated by \`intel build\` from ${asComment(config.theme)}. */\n${await readRequired(config.theme, "ui.theme")}\n`

package/dist/tools/tool-servers/tool-servers.js

@@ -15,9 +15,10 @@ export const ServerDirectoryTool = "portal_list_servers";
  *
  * ⚠️ Only the shape is assumed, never the vocabulary. The portal is somebody else's product and its
  * payload is not part of any contract Intel owns, so every field is optional and the answer is
- * accepted from `structuredContent`, from `{ servers: [...] }` or from a JSON text block. What
- * makes a row usable is not that it parsed but that its identifier is confirmed against the live
- * tool list below.
+ * accepted from `structuredContent`, from `{ servers: [...] }`, from a JSON text block, or — the
+ * form the live portal actually uses — from the prose block `proseRows` reads. What makes a row
+ * usable is not that it parsed but that its identifier is confirmed against the live tool list
+ * below.
  */
 const DirectoryRow = z.looseObject({
     id: z.string().optional(),
@@ -26,10 +27,71 @@ const DirectoryRow = z.looseObject({
 });
 const DirectoryRows = z.array(DirectoryRow);
 const DirectoryEnvelope = z.looseObject({ servers: DirectoryRows });
+/** A line the portal meant as a directory entry: `- <display name> (<handle>): <state>`. */
+const ProseRow = /^\s*[-*•]\s+(.+?)\s*\(([^()\s]+)\)\s*:\s*(.*)$/;
+/** What claims to be an entry at all. Everything else in the block is a heading or a hint. */
+const ProseBullet = /^\s*[-*•]\s/;
+/**
+ * ⚠️ Never the ✓. A tick is decoration: a different locale, a plain-text client or a later version
+ * of the portal writes the same fact another way, and a reading that hangs on one code point would
+ * silently switch every server off. What is read is the word, and the word alone.
+ *
+ * It has to be the WHOLE state, not a word inside it, because "disabled" contains "enabled" and
+ * "not enabled" is built from it — a substring test would read both as switched on, and that is the
+ * one direction this must never get wrong. Anything else the portal might write ("aktiviert",
+ * "enabled (3 tools)") is therefore not offerable, and stays declared.
+ */
+function readsAsEnabled(state) {
+    const words = state.toLowerCase().match(/\p{L}+/gu);
+    return words !== null && words.length === 1 && words[0] === "enabled";
+}
+/**
+ * The portal's prose form: a heading, one bullet per server, a closing hint. It is what the live
+ * portal actually answers (#233), and it is read only after every JSON reading in `rows` has failed.
+ *
+ * ⚠️ This reading hangs on somebody else's wording and can break without warning. The portal owes
+ * Intel no format at all, so a reworded state, a translated page or a changed layout is a normal
+ * event here rather than a defect. Two things keep that from becoming a quiet widening:
+ *
+ * - **A bullet that does not read as a row refuses the whole answer.** Skipping it would hand back
+ *   a directory with one server missing, and a missing row is not a smaller list — it lets that
+ *   server's tools fall back onto the shorter handle that encloses them, which is exactly the
+ *   widening the split between `declared` and `servers` exists to prevent. The price is that a
+ *   portal which one day bullets its closing hint fails loudly with the same closed
+ *   `tool_servers_unavailable` that #233 found; that is the intended direction.
+ * - **Nothing read here can invent a server.** A handle no live tool confirms is never offered, so
+ *   a misread line costs an offer, never a delegation.
+ */
+function proseRows(answer) {
+    const parsed = [];
+    for (const block of answer.content) {
+        if (typeof block !== "object" || block === null || !("text" in block))
+            continue;
+        const text = block.text;
+        if (typeof text !== "string")
+            continue;
+        for (const line of text.split("\n")) {
+            if (!ProseBullet.test(line))
+                continue;
+            const [, name, handle, state] = ProseRow.exec(line) ?? [];
+            if (name === undefined || handle === undefined)
+                return null;
+            // `id` carries the handle and `name` the display name, but neither is believed on its own:
+            // both stay candidates in `toolServersFrom`, and the live tool list decides which one
+            // actually namespaces.
+            parsed.push({ id: handle, name, enabled: readsAsEnabled(state ?? "") });
+        }
+    }
+    return parsed.length > 0 ? parsed : null;
+}
 /**
  * Every place the portal could reasonably have put its list, tried in order. An MCP tool result is
  * either structured or text, and a server that answers with `{ servers: [...] }` is as likely as
  * one that answers with a bare array.
+ *
+ * ⚠️ The prose reading comes last and is ADDITIONAL, never replacing. The portal is somebody else's
+ * product: it answers in prose today and may answer structured tomorrow, and a structured answer
+ * must keep winning on the day it arrives beside a human sentence.
  */
 function rows(answer) {
     const candidates = [answer.structuredContent];
@@ -42,8 +104,9 @@ function rows(answer) {
                 candidates.push(JSON.parse(text));
             }
             catch {
-                // A text block that is not JSON is prose, not a directory. Skip it rather than fail: the
-                // portal may well add a human sentence beside the payload.
+                // A text block that is not JSON may still be the directory — see `proseRows` above. It is
+                // not fed to the JSON readings here, and it does not make them fail either: the portal may
+                // well add a human sentence beside the payload.
             }
         }
     }
@@ -55,7 +118,7 @@ function rows(answer) {
         if (wrapped.success)
             return wrapped.data.servers;
     }
-    return null;
+    return proseRows(answer);
 }
 /**
  * ⚠️ The rule itself — longest match against declared handles, never a cut at an underscore — is

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anchrd/intel-api",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "type": "module",
   "license": "UNLICENSED",
   "repository": {
@@ -43,9 +43,9 @@
   },
   "dependencies": {
     "@anchrd/gate-sdk": "^0.7.0",
-    "@anchrd/intel-contract": "^0.7.0",
+    "@anchrd/intel-contract": "^0.8.0",
+    "@cfworker/json-schema": "^4.1.1",
     "@modelcontextprotocol/sdk": "^1.30.0",
-    "ajv": "^8.20.0",
     "fflate": "^0.8.3",
     "hono": "^4.12.32",
     "openid-client": "^6.8.4",