@anchrd/intel-contract 0.13.0 → 0.14.0

package/dist/contract/tool.js

@@ -0,0 +1,172 @@
+import { z } from "zod";
+function normalizedHostname(url) {
+    return url.hostname.toLowerCase().replace(/^\[|\]$/g, "");
+}
+function isPrivateIpv4(hostname) {
+    const parts = hostname.split(".").map(Number);
+    if (parts.length !== 4 ||
+        parts.some((part) => !Number.isInteger(part) || part < 0 || part > 255)) {
+        return false;
+    }
+    const [first = 0, second = 0] = parts;
+    return (first === 0 ||
+        first === 10 ||
+        first === 127 ||
+        (first === 100 && second >= 64 && second <= 127) ||
+        (first === 169 && second === 254) ||
+        (first === 172 && second >= 16 && second <= 31) ||
+        (first === 192 && second === 168) ||
+        (first === 198 && (second === 18 || second === 19)) ||
+        first >= 224);
+}
+function isPublicToolHost(url) {
+    const hostname = normalizedHostname(url);
+    if (hostname === "localhost" || hostname === "127.0.0.1" || hostname === "::1") {
+        return url.protocol === "http:";
+    }
+    if (!hostname.includes(".") ||
+        hostname.endsWith(".local") ||
+        hostname.endsWith(".localhost") ||
+        hostname.endsWith(".internal") ||
+        isPrivateIpv4(hostname) ||
+        hostname.includes(":")) {
+        return false;
+    }
+    return url.protocol === "https:";
+}
+/**
+ * One MCP server as the portal names it. The handle is what the portal puts in front of every tool
+ * that server offers (`notion_notion-search` belongs to `notion`), and it is the only identifier
+ * Intel can both store and recognise again in a live `tools/list`.
+ *
+ * ⚠️ A handle is never invented from a tool name. Which servers exist is the portal's answer
+ * (`portal_list_servers`), and the prefix is only used to attribute a tool to a server that answer
+ * already named — see `packages/api/src/tools/tool-servers` for why splitting on the underscore
+ * alone would be ambiguous.
+ */
+export const ToolServerHandle = z
+    .string()
+    .trim()
+    .min(1)
+    .max(120)
+    .regex(/^[A-Za-z0-9][A-Za-z0-9._-]*$/, "A server handle is the portal's own identifier");
+export const ToolSourceUrl = z.url().refine((value) => {
+    try {
+        const url = new URL(value);
+        return !url.username && !url.password && isPublicToolHost(url);
+    }
+    catch {
+        return false;
+    }
+}, "The portal must use an approved public HTTPS host without embedded credentials");
+// The portal namespaces every upstream tool, so the name alone identifies the target server. The
+// portal is still the one that resolves it and attaches the credentials — Intel never holds an
+// upstream credential. Since D30 Intel does read the namespace for one purpose: attributing a tool
+// to a server the portal's own `portal_list_servers` already named, so a delegation can be cut to
+// whole servers. That is attribution, not routing.
+export const ToolName = z.string().min(1).max(240);
+export const ToolAnnotations = z.strictObject({
+    title: z.string().max(240).optional(),
+    readOnlyHint: z.boolean().optional(),
+    destructiveHint: z.boolean().optional(),
+    idempotentHint: z.boolean().optional(),
+    openWorldHint: z.boolean().optional(),
+});
+export const ToolCapability = z.strictObject({
+    name: ToolName,
+    title: z.string().max(240).nullable(),
+    description: z.string().max(10_000).nullable(),
+    inputSchema: z.record(z.string(), z.unknown()),
+    outputSchema: z.record(z.string(), z.unknown()).nullable(),
+    annotations: ToolAnnotations,
+    fingerprint: z.string().regex(/^[a-f0-9]{64}$/),
+});
+// The catalog reflects one live tools/list for the requesting user. It is never stored as a
+// permission mirror, so there is no per-source state and no Intel-owned connection status.
+export const ToolCatalog = z.strictObject({
+    portalConnected: z.boolean(),
+    items: z.array(ToolCapability),
+    /**
+     * Which delegated servers actually contributed a tool to this catalog (#289).
+     *
+     * ⚠️ Present only where the attribution was actually made — a delegated caller whose catalog was
+     * read. It is absent for an ordinary user, and absent as well when the answer comes from one of
+     * the short paths that never reach the portal (nothing delegated, no portal sign-in, connection
+     * dropped). Absent therefore means "not stated", never "nothing arrived"; `[]` is the second one.
+     *
+     * That it is missing rather than empty on those paths is deliberate rather than half-finished:
+     * the attribution already happens for a delegation — `capabilities` has to make it to cut the
+     * list — so naming it costs nothing there, while computing the same thing for an ordinary user
+     * would mean a second portal request per call, for a question their screen does not ask.
+     *
+     * ⚠️ It is the answer to "what arrived", never to "what was granted". A server missing here has
+     * been switched off, revoked, or is failing right now; the delegation in the definition is
+     * unchanged. Reading it the other way round would turn an outage into a permission change.
+     */
+    reached: z.array(ToolServerHandle).optional(),
+});
+/**
+ * One MCP server the asking user reaches right now, as the portal itself names it (D30).
+ *
+ * ⚠️ `toolCount` is a fact about this moment and this user, not a size. It exists so a picker can
+ * say "9 tools" instead of showing a handle alone, and it must never be read as what an agent will
+ * get: the delegated run asks the portal again, with the delegator's token.
+ */
+export const ToolServer = z.strictObject({
+    handle: ToolServerHandle,
+    name: z.string().min(1).max(240),
+    toolCount: z.number().int().min(0),
+});
+// The same live-query rule as the tool catalog, one level up. `portalConnected: false` is the state
+// of somebody who has not signed into the portal yet, and it is not an error.
+export const ToolServerCatalog = z.strictObject({
+    portalConnected: z.boolean(),
+    items: z.array(ToolServer),
+});
+/**
+ * Which of the named servers a tool belongs to, or `null` for none of them.
+ *
+ * ⚠️ THE TRAP: a tool name does not say where its server name ends.
+ *
+ * The portal writes `<server>_<tool>`, and both halves may contain underscores — `intel_flow_get`
+ * reads equally well as server `intel` with tool `flow_get` and as a server called `intel_flow`
+ * with tool `get`. Splitting on the first underscore is therefore a guess that is wrong the day
+ * somebody adds a server whose name contains one, and on the API side being wrong means an agent
+ * delegated server A quietly reaching server B.
+ *
+ * So the prefix is never split. It is only ever MATCHED against handles the portal itself named,
+ * and the longest match wins: with `intel` and `intel_flow` both declared, `intel_flow_get` belongs
+ * to `intel_flow`, which is the only reading in which both declarations stay true.
+ *
+ * ⚠️ This lives in the contract because HOW A NAME IS READ is a property of the wire, and both
+ * surfaces read the same wire: `packages/api` cuts a delegation with it, `packages/ui` groups the
+ * tools screen with it (#212). A second implementation in the browser would be the third answer to
+ * one question — the underscore rule has already been answered differently in two places once
+ * (#106, #107), and the copies disagreed. What deliberately stays OUT of here is everything about
+ * reach: which handles are declared, which are enabled, which may be delegated and which one owns
+ * the portal's own management tools are decisions with consequences, and they belong to
+ * `packages/api/src/tools/tool-servers`. This function only reads a name.
+ */
+export function serverOf(toolName, handles) {
+    let best = null;
+    for (const handle of handles) {
+        if (!toolName.startsWith(`${handle}_`))
+            continue;
+        if (best === null || handle.length > best.length)
+            best = handle;
+    }
+    return best;
+}
+export const TestToolInput = z.strictObject({
+    name: ToolName.describe("The tool's full name as tool_list reported it, including the server handle it is prefixed with. The portal routes on that prefix, so a bare name reaches nothing."),
+    arguments: z
+        .record(z.string(), z.unknown())
+        .default({})
+        .describe("The arguments, shaped by that tool's own inputSchema from tool_list. Validated against it before anything is sent, so a wrong shape is refused here rather than by the far side."),
+});
+export const ExecuteToolInput = TestToolInput;
+export const ToolTestResult = z.strictObject({
+    isError: z.boolean(),
+    content: z.array(z.unknown()),
+    structuredContent: z.unknown().optional(),
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anchrd/intel-contract",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "type": "module",
   "license": "UNLICENSED",
   "repository": {
@@ -15,6 +15,34 @@
     ".": {
       "types": "./dist/contract/contract.d.ts",
       "default": "./dist/contract/contract.js"
+    },
+    "./bundle": {
+      "types": "./dist/contract/bundle.d.ts",
+      "default": "./dist/contract/bundle.js"
+    },
+    "./flow": {
+      "types": "./dist/contract/flow.d.ts",
+      "default": "./dist/contract/flow.js"
+    },
+    "./flow-run": {
+      "types": "./dist/contract/flow-run.d.ts",
+      "default": "./dist/contract/flow-run.js"
+    },
+    "./node": {
+      "types": "./dist/contract/node.d.ts",
+      "default": "./dist/contract/node.js"
+    },
+    "./share": {
+      "types": "./dist/contract/share.d.ts",
+      "default": "./dist/contract/share.js"
+    },
+    "./table": {
+      "types": "./dist/contract/table.d.ts",
+      "default": "./dist/contract/table.js"
+    },
+    "./tool": {
+      "types": "./dist/contract/tool.d.ts",
+      "default": "./dist/contract/tool.js"
     }
   },
   "files": [