glimind

A drop-in client for Glimind — a live reliability oracle for AI agent tools. Ask "is this tool working right now, and how do I call it correctly?" before you act, and (optionally) report the outcomes of your real calls so the data gets better for everyone.

npm i glimind

import { Glimind } from "glimind";

const glimind = new Glimind({
  endpoint: "https://glimind.com",
  reporterId: "my-agent-install-001", // optional, stored only as a salted hash
  region: "us",                        // optional, coarse only
});

// 1) Ask before acting
const h = await glimind.check("mcp-registry/acme/search");
if (h.verdict === "down") {
  // pick a fallback, or back off
}

// 2) Wrap a call — latency + success/failure are reported automatically
const results = await glimind.wrap(
  "mcp-registry/acme/search",
  () => acme.search(query),
  { input: { query, limit: 10 }, task: "web-search" }
);

// 3) When stuck on input shape, get a known-good pattern
const recipe = await glimind.recipe("mcp-registry/acme/search", "web-search");

Auto-routing — your agent routes around outages

Wrap your calls and your agent automatically routes around outages. Wrap a tool call once with autoRoute: true: Glimind checks the tool's health first and, when it's down, transparently fails over to a healthy alternative — your agent keeps working instead of erroring out.

// Wrap your tool call once. Glimind checks health first and transparently
// fails over to a healthy alternative when the tool is down — your agent keeps working.
const result = await glimind.wrap(
  "mcp-registry/acme/search",
  (toolId) => callMcpTool(toolId, { query, limit: 10 }),
  { input: { query, limit: 10 }, task: "web-search", autoRoute: true }
);

The executor receives the tool id it should actually call (the original, or a substitute). Telemetry is attributed to whatever was actually called, so the data stays accurate. Routing is best-effort and never breaks your call path: if the routing lookup itself fails, the executor runs against the original tool.

Want the decision without running anything? Call route() directly:

const decision = await glimind.route("mcp-registry/acme/search", { task: "web-search" });
// { toolId, original, viaAlternative, recommendation, reason, recipe }
if (decision.viaAlternative) {
  console.log(decision.reason); // e.g. routed to a healthy alternative
}

Health/prepare/route results are cached in-process for a short TTL (cacheTtlMs, default 15s; set 0 to disable) so an agent can call them on every action without latency cost. Telemetry is never cached. Use clearCache() to drop cached results.

Framework middleware — one line, zero hot-path latency

Don't wrap every call by hand. Instrument once at startup and every tool call is auto-reported (privacy-clean) — reporting is fire-and-forget/batched, so it adds no latency. All adapters are duck-typed (no extra peer deps required).

MCP (any client):

import { wrapMcpClient } from "glimind/mcp";
wrapMcpClient(client, glimind, { serverId: "acme" });   // every callTool now reported

MCP, zero code (config-only proxy): point your MCP client at a local proxy.

npx -p glimind glimind-proxy https://real-mcp-server.example/mcp
# then set your MCP server URL to  http://127.0.0.1:7077

Vercel AI SDK:

import { instrumentVercelTools } from "glimind/vercel";
const tools = instrumentVercelTools(myTools, glimind);   // pass to generateText/streamText

LangChain / LangGraph (JS):

import { glimindCallbackHandler } from "glimind/langchain";
await agent.invoke(input, { callbacks: [glimindCallbackHandler(glimind)] });

Python (LangChain, OpenAI Agents SDK) — see clients/python (pip install glimind-client).

Passive by default (observe + report). Opt into active mode ({ preflight: true } on the MCP wrapper) to health-check and route around outages before calling.

Privacy — the whole point

This SDK never sends your arguments, payloads, or tool outputs. Before anything leaves your process it is reduced to a value-free shape skeleton: every leaf value becomes a type tag.

deriveShape({ query: "secret terms", limit: 10, opts: { safe: true } })
// => { limit: "<number>", opts: { safe: "<boolean>" }, query: "<string>" }

What is transmitted per outcome:

| field | example | notes | |---|---|---| | toolId | mcp-registry/acme/search | tool identifier | | shape | { query: "<string>" } | value-free skeleton (server hashes it, salted) | | success | true | | | error | RateLimitError: 429 | scrubbed client-side and server-side | | latencyMs | 412 | | | region | us | coarse only, optional | | reporterId | my-agent-install-001 | stored only as a salted hash |

The server independently re-validates that the shape contains only type tags and hard-rejects anything resembling a raw payload. If you want query-only behavior with zero reporting, pass { report: false }.

API

• new Glimind(options) — endpoint, apiKey?, reporterId?, region?, report?, flushIntervalMs?, batchSize?, cacheTtlMs?
• discover(query, { category?, limit? }) → live tools that match a free-text capability ("find a tool that does X") when you don't yet have a tool id
• check(toolId) → live health verdict (healthy | degraded | down | unknown) + real-usage stats (cached)
• prepare(toolId, task?) → health + known-good shape + live alternatives in one round-trip (cached)
• route(toolId, { task? }) → RouteDecision: which tool to call now, failing over to a healthy alternative when needed (cached)
• recipe(toolId, task?) → currently-working input shapes
• breakages(limit?) → tools that just broke
• wrap(toolId, executor, { input?, task?, autoRoute? }) → runs executor(resolvedToolId), reports outcome, returns its result; with autoRoute it routes around outages first
• report(toolId, success, { input?, error?, latencyMs?, task? }) → manual report
• clearCache() → drop cached query results (telemetry is never cached)
• flush() / close() → flush batched outcomes (call close() on shutdown)

Outcomes are batched and flushed every few seconds; reporting is best-effort and will never throw into your call path or destabilize your app.

Why agents should adopt it

• Stop wasting calls on tools that are currently broken.
• Get a known-good input shape instead of guessing.
• React to ecosystem outages before status pages update.
• Basic health checks are free and fast.

MIT licensed.