TypeScript SDK reference.

npm install mesedi

Sets up the module-level client. Call once at process start. For local backend development, pass baseUrl; otherwise the SDK posts to the Mesedi production backend.

import { configure } from "mesedi";

configure({
  apiKey: process.env.MESEDI_API_KEY!,
  // baseUrl: "http://localhost:8080",   // for local dev
});

Decorate any async function as an agent execution. The SDK records start, completion (or crash), wall-clock duration, and a stable crash signature so identical errors cluster into a single failure group.

import { wrap } from "mesedi";

const runAgent = wrap(async (query: string) => {
  return "answer";
});

await runAgent("hello");

For each wrap()-decorated call:

• On entry: POST /executions with status="started", sdk_language="typescript".
• On normal return: PATCH /executions/{id} with status="completed", duration_ms.
• On thrown error: PATCH with status="crashed" and a stable crash_signature. The original error is re-thrown with its original stack.

All HTTP is async via a single in-process queue plus a setInterval drainer. Network failures during observation never throw back into the wrapped agent. The SDK is fail-open.

Wrap any async function as an observed tool call. Emits a tool_call event into the surrounding execution context, with sequence number, tool name, sanitized args, success or failure, and result summary (or exception fields).

import { tool, wrap } from "mesedi";

const searchWeb = tool(
  { name: "search_web" },
  async (q: string) => ["result1", "result2"],
);

const runAgent = wrap(async (query: string) => {
  const results = await searchWeb(query);
  return `found ${results.length} results`;
});

Blocks until the in-process queue drains. Call at end-of-script in short-lived processes (CLI tools, test suites, cron jobs) where the Node process would exit before the async shipper has shipped.

import { flush } from "mesedi";

await runAgent("hello");
await flush();

Optional. Cap a single execution by token spend, dollar cost, or wall-clock duration. When a budget is exceeded, the SDK throws MesediHalt.

import { wrap } from "mesedi";

const runAgent = wrap(
  {
    name: "support-triage",
    hardHalt: {
      maxUsd: 2.50,
      maxTokensIn: 200_000,
      maxTokensOut: 50_000,
      maxWallSeconds: 60,
    },
  },
  async (query: string) => { ... },
);

Hard-halt also subscribes to a Server-Sent Events channel for the running execution. When an operator clicks Halt on the dashboard, the running SDK sees the signal within a few seconds and throws MesediHalt.

If your agent uses Vercel's ai package (generateText, multi-step ReAct with tools and maxSteps), wrapGenerateText is a drop-in replacement that adds Mesedi telemetry as a side effect.

import { configure, wrap, flush } from "mesedi";
import { wrapGenerateText } from "mesedi/integrations/vercel_ai";
import { generateText } from "ai";
import { openai } from "@ai-sdk/openai";

configure({ apiKey: process.env.MESEDI_API_KEY! });

const generateTextM = wrapGenerateText(generateText);

export const runAgent = wrap(
  { name: "support-triage" },
  async (question: string) => {
    const result = await generateTextM({
      model: openai("gpt-4o"),
      prompt: question,
      tools: { lookup, search },
      maxSteps: 5,
    });
    return result.text;
  },
);

Per invocation, the wrapper emits one llm_callevent per step (Vercel's multi-step ReAct surfaces intermediate reasoning plus the final answer on result.steps) and one tool_call event per tool invocation in each step. It pairs result.toolCalls[i] with result.toolResults by toolCallId and detects failure mode (missing result or result.error field).

ai is declared as an optional peer dependency. Installing mesedidoesn't require it. If your project already has ai installed, the integration just works. streamText and generateObject ship in a later slice.

Python SDK reference covers the matching surface for Python and the LangChain / CrewAI adapters.

HTTP API reference covers what the SDK posts on the wire, so you can instrument from any language.

Failure classes and playbooks explains what each detector is looking for in the telemetry the SDK ships.